# Neighborhood Registry License Passport — Specification v1 (Draft) **Status of this document:** Draft v1, published by Neighborhood Registry. This document is a draft specification. It describes the Neighborhood Registry License Passport system as designed for implementation in v1. Implementers SHOULD expect editorial corrections and clarifications during the Draft period. Substantive changes to normative requirements will be recorded in the Changelog (Section 13) and, where they change wire formats, identifiers, or verification semantics, will be issued under a new specification version. **Publisher:** Neighborhood Registry LLC — `https://neighborhoodregistry.com` **Specification name:** `nr-passport` **Specification version:** `1` **Canonical JSON:** RFC 8785 (JSON Canonicalization Scheme, JCS) **Signatures:** Ed25519 (EdDSA) **Hash function:** SHA-256 --- ## 1. Conformance and Normative Language The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals, as shown here. A **verifier** is any software that checks a License Passport record, a manifest, a Merkle inclusion proof, or a verified-tier individual attestation against the rules in this specification. A **resolver client** is any software that retrieves License Passport records using the Resolution Protocol (Section 8). An implementation is **conformant** if it satisfies every MUST and MUST NOT in this specification that applies to its role (issuer, verifier, or resolver client). A verifier that skips signature verification or Merkle proof verification MUST NOT claim conformance. This specification is self-contained for verifier and resolver-client implementation. No other Neighborhood Registry document is required to implement those roles. --- ## 2. Overview ### 2.1 What a License Passport Is A **License Passport** is a permanent, signed, resolvable verification record for exactly one triple: ``` (licensing authority, credential kind, license number) ``` The kind is part of the identity because a bare license number is not unique within every authority (Section 3.3). One triple maps to exactly one Passport ID (Section 3). A Passport ID, once issued, **MUST NOT** be reassigned to a different triple and **MUST NOT** change when the record's tier, status, or supporting evidence changes. A License Passport answers a narrow question: > Did Neighborhood Registry record, at a stated time and by a stated method, > a license record (or an individual verification) for this authority and > this license number? It does **NOT**, by itself, answer whether a person is currently authorized to practice, whether a license is in good standing today, or whether a consumer should hire the holder. Consumers and relying parties **MUST** treat the timestamps and status fields in the record as part of the claim. ### 2.2 The Two Tiers Every record belongs to exactly one attestation tier. #### 2.2.1 `verified` Tier * `attestation_level = "verified"`. * The holder's license was **individually attested** by Neighborhood Registry against the licensing authority's records. * The record is backed by an **individual JWS** (Section 9) in addition to its inclusion in a signed batch manifest. * The record payload carries a `verification` object (Section 5.4) linking to the individual verification record and its ledger entry, with a `checked_at` timestamp. #### 2.2.2 `listed` Tier * `attestation_level = "listed"`. * The record is a **roster observation**: the license appeared in a roster or index obtained from, or derived from, the licensing authority, and Neighborhood Registry **committed** that observation in a signed batch manifest (Section 6). * The record is **NOT** an individual attestation. No individual JWS exists for a listed-tier record by virtue of its listed status. * The record payload carries a `listing` object (Section 5.3) identifying the observation date, source, and index generation time. ### 2.3 Tier Semantics (Normative) 1. A listed record **MUST NOT** be presented — in user interfaces, badges, embeds, summaries, exports, or derived data — as verified, individually verified, attested, confirmed, or any equivalent claim. 2. A listed record **MUST** be presented, where a tier label is shown, with a label that preserves the distinction, e.g. "listed" or "License Record". Only a verified record **MAY** be labeled "verified" or "License Verified". 3. User interfaces and APIs that collapse both tiers into a single boolean "verified" value **MUST NOT** do so for listed records. 4. Tier is a field of the signed/committed payload. A client **MUST** read `attestation_level` from the record payload itself and **MUST NOT** infer tier from the presence of a record, a profile page, or an inclusion proof. Inclusion in a manifest proves commitment of the payload as written — including its tier — and nothing more. 5. **Absence is not invalidity.** The absence of a License Passport record, a `404` from the resolver (Section 8.5), or the absence of a pair from a manifest is **NOT** proof that a license is invalid, does not exist, was revoked, or was never issued. A verifier or resolver client **MUST NOT** present a not-found result as evidence of invalidity. See Section 8.5. ### 2.4 Design Properties * **Permanent:** the Passport ID is a deterministic function of the triple (Section 3); it survives tier upgrades, status changes, and generations. * **Signed:** every manifest is Ed25519-signed (Section 6.3); every verified-tier record additionally has an individual JWS (Section 9). * **Resolvable:** any party can resolve a Passport ID or look up a triple for free, without authentication (Section 8). * **Privacy by construction:** record payloads contain **no contact data** (Section 5.5). * **Auditable over time:** manifest generations form a hash-linked chain and support as-of resolution (Sections 8.3 and 10). ### 2.5 Terminology | Term | Meaning | |---|---| | Authority | A licensing authority (board, commission, department, or agency) identified by an authority code (Section 3.2). | | Pair | The tuple `(authority_code, license_number)` a passport is issued for. | | Payload | The canonical record object defined in Section 5. | | Manifest | The signed batch header defined in Section 6 committing to a set of payloads via a Merkle root. | | Generation | One issued manifest and its record set. Generations are sequentially numbered (Section 10). | | Proof | A Merkle inclusion proof as defined in Section 7. | | JWKS | The issuer's public key set, published at the URL in Section 6.4. | | Resolver | The HTTP service defined in Section 8. | --- ## 3. Passport ID ### 3.1 Derivation (Normative) A Passport ID **MUST** be derived exactly as follows: ``` LICNORM = NormalizeLicense(license_number) DIGEST = SHA-256( UTF-8( "nr-passport-v1|" + AUTHCODE + "|" + KIND + "|" + LICNORM ) ) PASSPORT_ID = "nrp_" + LowerHex(DIGEST)[0..23] ``` That is: * the literal string `nr-passport-v1`, followed by `|`, followed by the authority code `AUTHCODE`, followed by `|`, followed by the credential kind `KIND` (Section 3.3), followed by `|`, followed by `LICNORM`; * encoded as UTF-8 with **no** trailing newline and **no** additional whitespace; * hashed with SHA-256; * rendered as lowercase hexadecimal; * truncated to the **first 24 hexadecimal characters**; * prefixed with the literal `nrp_`. The resulting ID matches the pattern: ``` ^nrp_[0-9a-f]{24}$ ``` A verifier **MUST** reject as malformed any Passport ID that does not match this pattern. A verifier **SHOULD** recompute the ID from the `authority_code`, `license.kind`, and `license.number` in a payload and **MUST** treat a mismatch between the recomputed ID and the claimed `passport_id` as a validation failure. ### 3.2 Authority Code (`AUTHCODE`) * `AUTHCODE` is the uppercase authority code assigned in the **authority registry** published at: ``` https://neighborhoodregistry.com/passport-authorities.json ``` * Implementers **MUST** use the code exactly as it appears in that registry: uppercase ASCII, no surrounding whitespace. * Authority codes are stable. A code, once assigned to an authority, **MUST NOT** be reassigned to a different authority. * If an authority or code is not in the registry, an implementer **MUST NOT** invent a code for passport derivation. Such a triple has no Passport ID under this version of the specification. ### 3.3 Credential Kind (`KIND`) `KIND` is the credential-kind token of the record: a lowercase ASCII token such as `insurance`, `electrician`, `realtor`, `plumber`, `inspector`, `hvac`, `loanpro`, or `service`. It appears in every payload as `license.kind`. KIND is part of the identity key because **a bare license number is not unique within an authority**: some authorities reuse the same number across credential kinds (in production data, the Texas Department of Licensing and Regulation number `29203` is simultaneously an HVAC licence and an electrical licence held by different businesses). A licence is identified by the triple (authority, kind, number); the Passport ID derivation mirrors that fact. KIND is stable for a given credential and does not change when a record's tier changes (Section 10). ### 3.4 License Normalization (`LICNORM`) `NormalizeLicense` **MUST** be applied exactly as follows, in order: 1. Uppercase the license number (Unicode uppercase, then restrict per step 2; in practice license numbers in scope are ASCII). 2. Remove **every** character that is **not** in the set `[A-Z0-9]`. No other normalization is permitted. In particular, implementers **MUST NOT** strip leading zeros, **MUST NOT** insert or remove separators beyond step 2, and **MUST NOT** apply authority-specific reformatting before hashing. Examples (illustrative, non-normative except §3.4): | Input license number | `LICNORM` | |---|---| | `SA00071521` | `SA00071521` | | `sa00071521` | `SA00071521` | | `SA-00071521` | `SA00071521` | | `SA 00071521` | `SA00071521` | Note that distinct printed forms that normalize to the same `LICNORM` under the **same** authority and the **same** kind intentionally derive the **same** Passport ID. ### 3.5 Worked Example (Normative) Authority: Arkansas Real Estate Commission Authority code: `AREC` Credential kind: `realtor` License number: `SA00071521` Normalization: ``` LICNORM = "SA00071521" ``` Hash input (UTF-8, no newline): ``` nr-passport-v1|AREC|realtor|SA00071521 ``` SHA-256 of the hash input: ``` 8deafe6cef601cf7e2151edd83bad36cc2ddc865af987b48bd1394814f5d53d1 ``` First 24 hexadecimal characters: ``` 8deafe6cef601cf7e2151edd ``` Passport ID: ``` nrp_8deafe6cef601cf7e2151edd ``` An implementation that does not produce `nrp_8deafe6cef601cf7e2151edd` for this input is non-conformant. (This is a live record: it resolves in production.) ### 3.6 Collisions and Length The ID carries 96 bits of the SHA-256 digest. Implementers **MUST NOT** lengthen, shorten, or re-encode the ID. If a genuine collision between two distinct (authority, kind, license) triples were ever demonstrated, it **MUST** be handled by a new specification version (Section 12), never by local ad-hoc disambiguation. --- ## 4. Canonicalization All signed and hashed JSON in this specification **MUST** be canonicalized with the JSON Canonicalization Scheme (JCS), **RFC 8785**. * The bytes that are hashed or signed are the UTF-8 bytes of the JCS output. * Implementers **MUST NOT** hash or verify signatures over pretty-printed, whitespace-variant, or key-reordered serializations. * Numbers, strings, and escaping **MUST** follow RFC 8785 exactly. * Where this specification says "JCS(payload)" or "JCS(header)", it means the byte sequence produced by applying RFC 8785 to that JSON value. --- ## 5. Record Format ### 5.1 Canonical Record Payload A License Passport record is a single JSON object — the **payload**. The payload is the exact value committed as a Merkle leaf (Section 7) and, for the resolver, returned in the `record` member of the response envelope (Section 8.4). Example (listed tier — a real production record, generation 1): ```json { "type": "nr-passport-record", "version": 1, "passport_id": "nrp_8c9d9d0487077e423854009e", "holder_name": "Aaron Dean", "license": { "number": "G389691", "authority_code": "INS-FL", "authority_name": "Florida Department of Financial Services", "profession": "Insurance Agent", "kind": "insurance" }, "profile_url": "https://neighborhoodregistry.com/experts/aaron-dean/", "city": "Naples", "state": "FL", "attestation_level": "listed", "status": "listed", "listing": { "record_date": "2026-10-28", "source": "authority-public-roster", "index_generated_at": "2026-11-14T00:17:58Z" } } ``` A verified-tier payload replaces the `listing` object with a `verification` object (Section 5.4); it **MUST NOT** carry both. ### 5.2 Field Table (Normative) | Field | Type | Required | Meaning | |---|---|---|---| | `type` | string | REQUIRED | MUST be exactly `"nr-passport-record"`. | | `version` | integer | REQUIRED | Payload format version. For this specification, `1`. | | `passport_id` | string | REQUIRED | Passport ID derived per Section 3. MUST match recomputation from `license.authority_code`, `license.kind`, and `license.number`. | | `attestation_level` | string | REQUIRED | Exactly one of `"listed"` or `"verified"` (Section 2.2). | | `status` | string | REQUIRED | Lifecycle status (Section 10.4): one of `"listed"`, `"active"`, `"status-changed"`, `"superseded"`. | | `holder_name` | string | REQUIRED | Name of the license holder as recorded. This is a public license-record field, not contact data. | | `license` | object | REQUIRED | License object, Section 5.2.1. | | `listing` | object | REQUIRED if `attestation_level="listed"`; MUST be absent if `"verified"` | Roster-observation block, Section 5.3. | | `verification` | object | REQUIRED if `attestation_level="verified"`; MUST be absent if `"listed"` | Individual-attestation block, Section 5.4. | | `profile_url` | string (URL) or null | REQUIRED | Neighborhood Registry profile URL for the holder, or `null` if no profile exists. | | `city` | string or null | REQUIRED | City associated with the license record, or `null` if not recorded. | | `state` | string or null | REQUIRED | State associated with the license record (e.g. USPS two-letter code where applicable), or `null` if not recorded. | Additional members **MUST NOT** be added to a v1 payload except under a new payload `version`. Verifiers **MUST** ignore unknown members for forward compatibility in display, but a payload with unknown members **MUST NOT** be re-canonicalized differently: the leaf hash (Section 7) is computed over the payload exactly as issued. #### 5.2.1 `license` Object | Field | Type | Required | Meaning | |---|---|---|---| | `license.number` | string | REQUIRED | License number as recorded by the authority. Normalization for ID derivation is defined in Section 3.4; this field preserves the recorded form. | | `license.authority_code` | string | REQUIRED | Authority code from the registry at `https://neighborhoodregistry.com/passport-authorities.json`. This is `AUTHCODE` in Section 3.1. | | `license.authority_name` | string | REQUIRED | Human-readable authority name as in the authority registry. | | `license.profession` | string | REQUIRED | Profession / trade for the license (e.g. `"Real Estate"`, `"Loan Officer"`). | | `license.kind` | string or null | REQUIRED | License kind/type within the profession (e.g. `"Salesperson"`, `"Broker"`), or `null` if not recorded. | ### 5.3 `listing` Object (Listed Tier) Present if and only if `attestation_level = "listed"`. | Field | Type | Required | Meaning | |---|---|---|---| | `listing.record_date` | string (date) | REQUIRED | Date (`YYYY-MM-DD`) the roster observation was recorded. | | `listing.source` | string | REQUIRED | Source of the observation (authority roster/index identifier as recorded by the issuer). | | `listing.index_generated_at` | string (RFC 3339 date-time) | REQUIRED | Timestamp at which the source index from which this observation derives was generated. | The presence of `listing` is the complete evidentiary claim of the listed tier. A client **MUST NOT** describe dates in `listing` as a verification check date; see Section 5.4 for the verified-tier equivalent (`checked_at`). ### 5.4 `verification` Object (Verified Tier) Present if and only if `attestation_level = "verified"`. | Field | Type | Required | Meaning | |---|---|---|---| | `verification.record_url` | string (URL) | REQUIRED | URL of the individual verification record (JWS), Section 9: `https://neighborhoodregistry.com/verify/{slug}.json`. | | `verification.ledger_url` | string (URL) | REQUIRED | URL of the ledger entry for the individual attestation. | | `verification.checked_at` | string (RFC 3339 date-time) | REQUIRED | Timestamp at which Neighborhood Registry individually checked the license against the authority's records. | A verifier evaluating a verified-tier claim **SHOULD** also verify the individual JWS at `record_url` (Section 9). Manifest inclusion (Section 7) commits to this payload; it is not a substitute for the individual attestation, and the individual attestation is not a substitute for manifest inclusion — a complete verifier checks both. ### 5.5 No Contact Data (Normative) Payloads contain **NO contact data by construction**. * A v1 payload **MUST NOT** contain an email address, telephone number, or any equivalent direct-contact field, for the holder or any other person, under any field name. * A conformant issuer **MUST NOT** add such a field in a v1 payload; a verifier that encounters a payload purporting to be v1 and containing a member named `email`, `phone`, `telephone`, `mobile`, or `contact` (at any nesting level introduced outside Sections 5.2–5.4) **SHOULD** flag the payload as non-conformant. * `holder_name`, `city`, and `state` are public license-record fields and are not contact data for the purposes of this section. This property is intentional and permanent for the passport payload: passports are safe to mirror, embed, and redistribute without exposing contact data. ### 5.6 Status and Tier Are Independent `attestation_level` (how the record was established) and `status` (where the record stands in its lifecycle, Section 10.4) are independent fields. A client **MUST NOT** derive one from the other, except that a record in a manifest with `attestation_level = "listed"` and `status = "listed"` is the ordinary initial state of a listed record. --- ## 6. Manifest Format A **manifest** commits one generation's entire record set under a single Merkle root and a single issuer signature. A resolver response references the manifest from which its proof derives (Section 8.4). ### 6.1 Header Object The manifest is a JSON object with the following members: | Field | Type | Required | Meaning | |---|---|---|---| | `type` | string | REQUIRED | MUST be exactly `"nr-passport-manifest"`. | | `version` | integer | REQUIRED | Manifest format version. For this specification, `1`. | | `issuer` | string | REQUIRED | MUST be exactly `"https://neighborhoodregistry.com"`. | | `kid` | string | REQUIRED | Key identifier of the signing key. MUST match a `kid` in the JWKS (Section 6.4). | | `generation` | integer | REQUIRED | Generation number (Section 10). Strictly increasing across issued manifests. | | `generated_at` | string (RFC 3339 date-time) | REQUIRED | Timestamp at which this manifest was generated. | | `source_index` | object | REQUIRED | `{ "generated_at": , "count": }` — generation time and record count of the source index this manifest was built from. | | `record_count` | integer | REQUIRED | Number of records (leaves) committed by this manifest. It MAY be less than `source_index.count` where the source contains duplicate (authority, kind, license) keys, which are committed once. For proof verification it MUST equal the applicable `leaf_count` (Section 7). | | `merkle_root` | string | REQUIRED | Lowercase hex SHA-256 Merkle root over the record set, computed per Section 7. | | `algorithm` | string | REQUIRED | MUST be exactly `"sha256-merkle-ct-v1"`. | | `prev_manifest_root` | string or null | REQUIRED | `merkle_root` of the previous generation, or `null` for the first generation. Forms the chain in Section 10.2. | | `transparency_anchor` | object | REQUIRED | `{ "head_hash": , "events": , "issued_at": }` — anchor into the issuer's transparency log at manifest issuance: current log head hash, number of events, and issuance time as recorded. | | `records_url` | string (URL) | REQUIRED | URL from which the full record set for this generation can be retrieved. | | `jwks_url` | string (URL) | REQUIRED | MUST be `https://neighborhoodregistry.com/.well-known/nr-verification-key.json` (Section 6.4). | | `signature` | string | REQUIRED | Ed25519 signature, encoded as base64url without padding, computed per Section 6.3. | A manifest MAY carry additional members beyond this table (the production manifest carries `verified_count`, `listed_count`, `manifest_url`, `spec_url`, and a human-readable `verify` note). The signature covers the object exactly as published (Section 6.3); verifiers MUST canonicalize the published object including any additional members, and MUST ignore additional members semantically. Example (abbreviated, non-normative values except `type`, `issuer`, `algorithm`, and `jwks_url`): ```json { "type": "nr-passport-manifest", "version": 1, "issuer": "https://neighborhoodregistry.com", "kid": "nr-verify-2026-01", "generation": 1, "generated_at": "2026-11-13T18:00:00Z", "source_index": { "generated_at": "2026-11-13T17:00:00Z", "count": 42405 }, "record_count": 42405, "merkle_root": "<64 lowercase hex characters>", "algorithm": "sha256-merkle-ct-v1", "prev_manifest_root": null, "transparency_anchor": { "head_hash": "", "events": 0, "issued_at": "2026-11-13T18:00:00Z" }, "records_url": "https://neighborhoodregistry.com/passport-records.jsonl.gz", "jwks_url": "https://neighborhoodregistry.com/.well-known/nr-verification-key.json", "signature": "" } ``` ### 6.2 Records Retrieval The record set for a generation is retrievable from the manifest's `records_url`. Each element is a payload exactly as defined in Section 5. Leaf ordering and hashing do **not** depend on the serialization order at `records_url`; they are defined solely by Section 7. ### 6.3 Signature (Normative) The manifest signature is computed as follows: 1. Take the manifest header object (Section 6.1). 2. Remove the `signature` member entirely. No placeholder value is inserted. 3. Canonicalize the resulting object with RFC 8785 JCS (Section 4). The resulting bytes are the signing input. 4. Sign the signing input with **Ed25519**, using the private key identified by `kid`. 5. Encode the 64-byte signature as **base64url without padding** and place it in the `signature` member. A verifier **MUST**: * select the verification key from the JWKS by exact `kid` match; * reject the manifest if no key with that `kid` exists; * reconstruct the signing input by the same remove-then-canonicalize procedure (never by re-serializing with local formatting choices); * verify the Ed25519 signature over those bytes; and * reject the manifest if verification fails. A verifier **MUST NOT** accept an unsigned manifest, a manifest signed with an algorithm other than Ed25519, or a manifest whose `issuer` is not exactly `"https://neighborhoodregistry.com"`. ### 6.4 Key Publication (JWKS) Signing keys are published as a JSON Web Key Set (JWKS) at: ``` https://neighborhoodregistry.com/.well-known/nr-verification-key.json ``` * Each key **MUST** carry a `kid` matching the `kid` used in manifests and in verified-tier JWS headers (Section 9). * Keys are Ed25519 keys (`kty: "OKP"`, `crv: "Ed25519"`). * Retired keys **SHOULD** remain published for as long as manifests or individual attestations signed under them are expected to be verified. Removing a key makes everything signed under it unverifiable, and clients **MUST** report that condition as "key not available", not as "invalid record". --- ## 7. Merkle Inclusion Proof Algorithm identifier: `sha256-merkle-ct-v1`. ### 7.1 Leaf Hash (Normative) For a record payload `P`: ``` LEAF = SHA-256( 0x00 || JCS(P) ) ``` where `JCS(P)` is the RFC 8785 canonical byte sequence of the payload exactly as issued (Section 5), `0x00` is the single byte `0x00` prepended as a domain separator, and `||` is byte concatenation. The leaf hash is a 32-byte value; where a hex rendering is needed it **MUST** be lowercase hex. ### 7.2 Tree Construction (Normative) 1. Compute the leaf hash (Section 7.1) for every payload in the generation. 2. Order the leaves by **`passport_id` ascending byte order** — i.e. bytewise lexicographic ordering of the ASCII `passport_id` string. This ordering defines `leaf_index` (0-based). 3. Build the tree level by level from the leaves toward the root. For each pair of adjacent nodes `(left, right)` at a level, the parent is: ``` PARENT = SHA-256( 0x01 || left || right ) ``` where `0x01` is the single byte `0x01` prepended as a domain separator and `left`/`right` are the raw 32-byte node values (not hex). 4. **Odd-node promotion:** if a level contains an odd number of nodes, the final unpaired node is **promoted unchanged** to the next level. It is **NOT** duplicated, **NOT** hashed with itself, and **NOT** hashed alone. 5. Repeat until a single node remains. That node is the `merkle_root`. 6. Edge case: a generation with exactly one record has that record's leaf hash as its `merkle_root`, and its proof has an empty `path`. Domain separation (`0x00` for leaves, `0x01` for internal nodes) is mandatory. An implementation that omits either prefix is non-conformant. ### 7.3 Proof Object An inclusion proof is a JSON object: | Field | Type | Required | Meaning | |---|---|---|---| | `leaf_index` | integer | REQUIRED | 0-based index of the leaf in the Section 7.2 ordering. | | `leaf_count` | integer | REQUIRED | Total number of leaves in the generation. MUST equal the manifest's `record_count`. | | `path` | array | REQUIRED | Audit path, ordered **leaf-to-root**. Each element is `{ "side": "left" \| "right", "hash": "" }`, where `side` states on which side of the running node the sibling sits at that fold step, and `hash` is the sibling node's hash. For a promoted (unpaired) level, **no** path element is emitted for that level. For a single-leaf tree, `path` is `[]`. | Example (abbreviated): ```json { "leaf_index": 123, "leaf_count": 42405, "path": [ { "side": "right", "hash": "<64 lowercase hex characters>" }, { "side": "left", "hash": "<64 lowercase hex characters>" } ] } ``` ### 7.4 Verification Algorithm (Normative) To verify that a payload `P` is included in a generation, a verifier **MUST** perform the following steps in order, and **MUST** fail verification if any step fails: 1. **Fetch the manifest** for the generation referenced by the resolver response (or otherwise obtained) and **fetch the JWKS** from the manifest's `jwks_url` (`https://neighborhoodregistry.com/.well-known/nr-verification-key.json`). 2. **Verify the manifest signature** per Section 6.3: select the key by `kid`, remove the `signature` member, canonicalize with RFC 8785 JCS, and verify the Ed25519 signature. If the signature is invalid, or the `kid` is unknown, stop: the proof **MUST NOT** be evaluated against an unauthenticated root. 3. **Check manifest identity:** confirm `type` is `"nr-passport-manifest"`, `issuer` is `"https://neighborhoodregistry.com"`, and `algorithm` is `"sha256-merkle-ct-v1"`. If any differs, fail. 4. **Validate the payload identity:** recompute the Passport ID from the payload's `license.authority_code` and `license.number` per Section 3 and confirm it equals the payload's `passport_id` and the ID being resolved. If not, fail. 5. **Recompute the leaf** from the payload per Section 7.1: `leaf = SHA-256(0x00 || JCS(P))`. 6. **Check index/count consistency:** * `proof.leaf_count` **MUST** equal the manifest's `record_count`; * `proof.leaf_index` **MUST** satisfy `0 <= leaf_index < leaf_count`; * the number of folds implied by `(leaf_index, leaf_count)` under the promotion rule (Section 7.2, step 4) **MUST** equal `path.length` (levels where the running node is promoted contribute no path element). If any check fails, fail verification. 7. **Fold the path** leaf-to-root: set `node = leaf`. For each path element in order: decode `hash` from lowercase hex to 32 bytes; if `side = "left"`, compute `node = SHA-256(0x01 || hash || node)`; if `side = "right"`, compute `node = SHA-256(0x01 || node || hash)`. Levels at which the running node was promoted are already reflected by the absence of a path element and require no computation. 8. **Compare to the root:** after the final fold, `node` **MUST** equal the manifest's `merkle_root` (compared as raw bytes / lowercase hex). If not, fail. 9. **Check payload semantics:** confirm `attestation_level` and, for the verified tier, the `verification` block fields are as required by Section 5. A proof establishes inclusion of the payload as written; tier claims beyond the payload's own `attestation_level` **MUST NOT** be inferred (Section 2.3). Only after all steps pass **MAY** a verifier report the record as "included in generation N under a validly signed manifest". --- ## 8. Resolution Protocol ### 8.1 Base and Principles The resolver is served over HTTPS from `neighborhoodregistry.com`. * Resolution is **FREE**. * Resolution is **unauthenticated**: a client **MUST NOT** be required to present credentials, an API key, or an account. * Resolution is **rate-limited fairly**: the issuer **MAY** apply reasonable, uniformly applied rate limits to protect the service. Clients **SHOULD** respect `Retry-After` and **SHOULD** cache per Section 8.6. * A client **MUST NOT** treat resolution failure, rate limiting, or a `404` as evidence about the validity of a license (Sections 2.3 and 8.5). ### 8.2 Endpoints #### 8.2.1 Resolve by Passport ID ``` GET https://neighborhoodregistry.com/wp-json/nr/v1/passport/{passport_id} ``` `{passport_id}` **MUST** match `^nrp_[0-9a-f]{24}$`. Returns the current record for that ID per Section 8.4. #### 8.2.2 Lookup by Authority and License ``` GET https://neighborhoodregistry.com/wp-json/nr/v1/passport/lookup?authority={code or name}&license={number} ``` * `authority`: an authority code from the registry at `https://neighborhoodregistry.com/passport-authorities.json` **or** the authority's name as it appears in that registry. Clients **SHOULD** send the code when known. * `license`: the license number. The server applies the Section 3 derivation (authority-code resolution + Section 3.4 normalization) to locate the record. * `kind` (OPTIONAL): the credential kind. Supplying it makes the match exact (one triple). Omitting it performs a lookup across all kinds for the (authority, license) pair: where an authority reuses a number across kinds, the response is a `matches` list containing every matching passport (each a distinct credential) instead of a single record. * On success the response shape is the same as Section 8.4 (or the matches list above). On no match the response is Section 8.5. #### 8.2.3 As-Of Resolution ``` GET https://neighborhoodregistry.com/wp-json/nr/v1/passport/{passport_id}/as-of?date={YYYY-MM-DD} ``` Returns the record as committed in the latest generation whose `generated_at` is on or before the end of the given date (UTC), with the proof and manifest reference **for that generation** — not the current generation. Semantics are defined in Section 10.3. If no generation existed on or before that date, the response is the Section 8.5 `404`. #### 8.2.4 Human-Readable Page ``` https://neighborhoodregistry.com/passport/{passport_id}/ ``` The human page renders the same record for people. It is a presentation of the resolver data, not a separate source of truth; in any conflict, the JSON record, proof, and manifest govern. ### 8.3 As-Of Requests on the Other Endpoints Only Section 8.2.3 defines as-of semantics in v1. Clients needing historical state for a pair without a known Passport ID **SHOULD** first derive the ID (Section 3) and then use Section 8.2.3. ### 8.4 Response Shape (Normative) A successful resolution returns HTTP `200` with a JSON envelope: | Field | Type | Required | Meaning | |---|---|---|---| | `passport_id` | string | REQUIRED | The resolved Passport ID. | | `passport_url` | string (URL) | REQUIRED | Human page URL (Section 8.2.4): `https://neighborhoodregistry.com/passport/{passport_id}/`. | | `attestation_level` | string | REQUIRED | Mirror of the payload's tier: `"listed"` or `"verified"`. MUST equal `record.attestation_level`. | | `status` | string | REQUIRED | Mirror of the payload's status. MUST equal `record.status`. | | `record` | object | REQUIRED | The canonical record payload exactly as defined in Section 5. This is the exact value whose JCS bytes form the Merkle leaf. | | `proof` | object | REQUIRED | Merkle inclusion proof per Section 7.3, against the manifest identified in `manifest`. | | `manifest` | object | REQUIRED | `{ "generation": , "merkle_root": , "generated_at": , "manifest_url": }` — identifies the generation and manifest that `proof` verifies against. `manifest_url` is the URL of the full manifest (Section 6.1). | | `verification` | object | REQUIRED if verified tier; MUST be absent if listed tier | Mirror of `record.verification` (Section 5.4): `{ "record_url": , "ledger_url": , "checked_at": }`, provided at envelope level for client convenience. In any conflict, `record.verification` governs. | Example (listed tier, abbreviated proof/manifest hashes): ```json { "passport_id": "nrp_b222180b2a27adc03f4abf97", "passport_url": "https://neighborhoodregistry.com/passport/nrp_b222180b2a27adc03f4abf97/", "attestation_level": "listed", "status": "listed", "record": { "...": "payload per Section 5" }, "proof": { "leaf_index": 123, "leaf_count": 42405, "path": [ { "side": "right", "hash": "" } ] }, "manifest": { "generation": 1, "merkle_root": "<64 lowercase hex characters>", "generated_at": "2026-11-13T18:00:00Z", "manifest_url": "https://neighborhoodregistry.com/passport-manifest.json" } } ``` For the verified tier, the envelope additionally carries the top-level `verification` object described above. A client **MUST NOT** treat the envelope mirrors (`attestation_level`, `status`, `verification`) as substitutes for verifying `record` via Section 7.4: the signed/committed value is the payload inside `record`. ### 8.5 Errors #### 8.5.1 Not Found When no record exists for the requested ID, pair, or as-of date, the resolver returns: ``` HTTP 404 Content-Type: application/json { "code": "passport_not_found" } ``` **Standing note (normative):** a `passport_not_found` result means only that Neighborhood Registry has no License Passport record for that request. It is **NOT** evidence that a license is invalid, does not exist, was revoked, or was never issued, and clients **MUST NOT** display or propagate it as such. Recommended consumer-facing wording is equivalent to: "No Neighborhood Registry record found for this license — this does not mean the license is invalid." #### 8.5.2 Other Errors Malformed IDs, malformed dates, and unknown authority codes in lookup are client errors (`4xx`) and carry a JSON body with a `code` member. Rate limiting, when applied, uses HTTP `429` and **SHOULD** include `Retry-After`. Error codes other than `passport_not_found` are informative; clients **MUST** handle unknown `code` values gracefully. ### 8.6 Caching * Every response corresponds to a specific manifest generation, identified in the response (`manifest.generation`, `manifest.generated_at`) and in the proof it carries. * Responses **MAY be cached until the next generation**: because a new generation is issued only when the Merkle root changes (Section 10.1), a cached response remains exactly correct until a new generation supersedes it. * Clients **SHOULD** cache resolver responses and manifests, and **SHOULD** revalidate by checking for a newer generation rather than by polling on a short timer. * As-of responses (Section 8.2.3) are historical and immutable once the referenced generation is superseded; they **MAY** be cached indefinitely. * A client that presents cached data **SHOULD** surface the generation timestamp so a reader can tell which generation the answer came from. --- ## 9. Verified-Tier Individual Records ### 9.1 Individual JWS Each verified-tier attestation additionally exists as an individually signed JSON Web Signature (JWS) at: ``` https://neighborhoodregistry.com/verify/{slug}.json ``` where `{slug}` is the verification record's slug. The payload's `verification.record_url` (Section 5.4) is the authoritative pointer to the applicable JWS; a client **MUST** follow that URL rather than constructing a slug itself. The JWS header is: ```json { "alg": "EdDSA", "kid": "", "typ": "nr-verification+jwt" } ``` * `alg` **MUST** be `EdDSA` (Ed25519). * `kid` **MUST** identify a key in the same JWKS as Section 6.4: `https://neighborhoodregistry.com/.well-known/nr-verification-key.json`. * `typ` **MUST** be `nr-verification+jwt`. ### 9.2 Verification Steps (Summary) To verify an individual verified-tier attestation, a verifier: 1. Fetches the JWS from `record.verification.record_url`. 2. Parses the JWS header and rejects any `alg` other than `EdDSA` or `typ` other than `nr-verification+jwt`. 3. Selects the key from the JWKS by the header's `kid` and verifies the Ed25519 signature over the JWS signing input per RFC 7515. 4. Checks the JWS claims against the passport payload: the authority, license number, holder, and check time in the individual record **MUST** be consistent with `license`, `holder_name`, and `verification.checked_at` in the payload; an inconsistency is a verification failure. 5. Follows `record.verification.ledger_url` for the ledger entry supporting the attestation, where ledger evidence is required by the relying party's policy. ### 9.3 Relationship to the Manifest The manifest payload for a verified record links the batch commitment to the individual attestation via `verification.record_url` and `verification.ledger_url`. Neither artifact replaces the other: * Manifest inclusion proves the payload — including those links and the `checked_at` time — was committed in a signed generation. * The individual JWS proves Neighborhood Registry individually signed that attestation. A complete verified-tier verification performs **both** Section 7.4 and Section 9.2. Listed-tier records have no individual JWS under this section, and a client **MUST NOT** imply one exists. --- ## 10. Lifecycle and Generations ### 10.1 Generation Cadence * Manifests are evaluated on an **hourly** cadence. * A **new generation is issued only when the Merkle root changes** — i.e. only when the record set (payloads, tiers, or statuses) actually changes. If the root is unchanged at an hourly evaluation, **no** new manifest is issued and the `generation` number does not advance. * Each issued generation increments `generation` by exactly 1 from the previous issued generation. ### 10.2 Generation Chain Each manifest's `prev_manifest_root` (Section 6.1) **MUST** equal the `merkle_root` of the immediately preceding generation, or `null` for the first generation. This forms a hash-linked chain of generations: a verifier auditing history can walk `manifest_url`s backward and confirm each link. A broken link — a `prev_manifest_root` that does not match the predecessor's actual root — invalidates the later manifest for audit purposes and **MUST** be reported as a chain failure, distinct from a signature failure. Manifests also carry a `transparency_anchor` (Section 6.1) binding each generation to the issuer's transparency-log state at issuance. ### 10.3 As-Of Semantics As-of resolution (Section 8.2.3) for date `D` returns the payload, proof, and manifest reference from the latest generation with `generated_at` on or before the end of `D` (UTC). * As-of answers are statements about what was committed **at that time**, not retroactively corrected history. If a record was listed on `D` and upgraded later, the as-of answer for `D` shows the listed payload. * If the passport had no record in any generation on or before `D`, the answer is `404` / `passport_not_found` (Section 8.5), with the same standing note: it is not evidence of invalidity at that time either. * A tier upgrade takes effect in the first generation issued after the upgrade event (Section 10.5); as-of answers before that generation retain the earlier tier. ### 10.4 Statuses `status` takes exactly one of the following values in v1: | Status | Meaning | |---|---| | `listed` | Initial status of a listed-tier record: a roster observation committed in a manifest, with no individual attestation. | | `active` | The record is current in its tier. For a verified-tier record, this is the ordinary standing after individual attestation. | | `status-changed` | The issuer has recorded a change in the underlying license/record status (e.g. a change observed at the authority or established by a re-check). The record remains resolvable; clients **SHOULD** surface that a change was recorded and direct readers to the current authority record for the present standing. This status is a statement that a change was recorded — clients **MUST NOT** expand it into a specific claim (suspension, revocation, expiry) that the payload does not state. | | `superseded` | This payload has been replaced by a newer payload for the same Passport ID (e.g. after a tier upgrade or a material correction). Superseded payloads remain available through as-of resolution for the generations in which they were current. | Status transitions are effected only by issuing a new generation containing the updated payload; a payload in an already-issued generation never changes. ### 10.5 Tier Upgrade When a listed pair receives an individual attestation (verified tier): * the Passport ID **does not change** (same Section 3 derivation); * the next issued generation contains a payload for the same `passport_id` with `attestation_level = "verified"`, a `verification` block in place of the `listing` block, and the corresponding status; * earlier generations remain intact and continue to serve the listed payload via as-of resolution. ### 10.6 Corrections A material error in a payload is corrected the same way: a new generation with a corrected payload for the same `passport_id`, with the prior payload reachable via as-of resolution. The issuer **MUST NOT** silently rewrite an already-issued generation. --- ## 11. Security and Privacy Considerations * **Trust root:** the JWKS at `https://neighborhoodregistry.com/.well-known/nr-verification-key.json`, fetched over HTTPS, is the trust root for both manifest signatures and individual JWS verification. A verifier that accepts keys from any other source for this system is non-conformant. * **What a proof does and does not prove:** a valid manifest signature plus a valid inclusion proof proves the payload was in the issuer's committed set for that generation. It does not prove the underlying license is currently valid (see Sections 2.1 and 10.4). * **Replay/staleness:** a proof from an old generation remains valid *for that generation*. Relying parties who need current state **MUST** resolve against the current generation and **SHOULD** check `manifest.generated_at`. * **No contact data:** see Section 5.5. Mirrors and embedders inherit this property from the payload format. * **Not-found handling:** see Sections 2.3 and 8.5. Presenting absence as invalidity is both a conformance violation and a foreseeable source of harm to license holders. --- ## 12. Versioning of This Specification * This document is **Specification v1**. The `version` fields in the payload (Section 5.2) and manifest (Section 6.1) are `1` for everything defined here. * **Editorial changes** (clarifications that change no normative requirement) MAY be published in place under the same version, with a Changelog entry. * **Breaking changes** — any change to Passport ID derivation, canonicalization, leaf/tree construction, signature construction, required fields, or resolution semantics — **MUST** be issued as a new specification version (v2, …) with its own document. V1 artifacts (IDs, manifests, proofs) remain verifiable under v1 rules permanently. * The `nr-passport-v1|` domain string in Section 3.1 is part of the v1 ID derivation and **MUST NOT** be reused with different semantics. * Payload or manifest extensions that are purely additive and optional, if ever introduced, require a new `version` value for the affected format and a Changelog entry stating how v1 verifiers treat them. --- ## 13. Changelog ### Draft v1 — initial publication * Initial draft of the License Passport specification: Passport ID derivation (Section 3, with worked example), record format (Section 5), manifest format and signature (Section 6), Merkle inclusion proofs (`sha256-merkle-ct-v1`, Section 7), resolution protocol (Section 8), verified-tier individual JWS (Section 9), and lifecycle/generations (Section 10). --- *End of Specification v1 (Draft). Published by Neighborhood Registry.*