# 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.*