HPPR Schemes

Tags: scheme, route, name, attest

This spec defines standard schemes that sit above the HPPR packet, wire, and repository service specs:

public group discovery under //u/route/group//... and //<group>/route/group//...
authority-local identity naming under //<authority-group>/name//...
public attestation state under //u/attest/...//...

These schemes are conventions. They use ordinary HPPR packets and ordinary repo commands.

Route discovery maps public or local route records to upstream repositories and content authorities. Authority-local names define stable identity names under a group. Attestations publish signed statements about verifiers or names.

Terms

Public root: the provisioned public route root under //u/route/group//
Authority group: a group that publishes route or name records
Exact name: <part>[.<part>...]@<authority-group>
Route-Authority-Key: stable public authority verifier for a group namespace
Name-Key: stable continuity verifier for one exact identity name
Current-Key: current operational verifier for one exact identity name

Common Conditional Headers

Packets defined in this spec MAY include repeated conditional headers after that packet family’s required semantic headers. A packet is valid only while all of its conditions hold.

Headers:

Condition-Route-Authority-Key: <group> <verifier>
Condition-Name-Key: <name> <verifier>
Condition-Current-Key: <name> <verifier>
Condition-State: <state> <exact-urc>

Rules:

Condition-Route-Authority-Key passes only while <group> still resolves to Route-Authority-Key: <verifier>
for <group> = u, this means <verifier> is still one of the currently provisioned trusted root route authority verifiers for the public root
Condition-Name-Key passes only while <name> still resolves to Name-Key: <verifier>
Condition-Current-Key passes only while <name> still lists Current-Key: <verifier>
Condition-State passes only while the packet at <exact-urc> currently has exactly one State header equal to <state>
<exact-urc> in Condition-State MUST contain /|
<exact-urc> MAY further pin signer or version under /|/...
if the referenced packet has its own Condition-* headers, they MUST also hold
dependency cycles MUST fail evaluation
missing, unreadable, malformed, unsupported, or non-matching targets fail the condition

Hierarchical Public Group Route Discovery

Public group routing starts at the unnamed public root under //u/route/group//.

The root delegates top-level labels. Each resolved authority group then delegates its own immediate child labels. API routing stays explicit at the final resolved group.

Canonical roots:

//u/route/group//...
//u/route/api//...
//<group>/route/group//...
//<group>/route/api//...

Examples:

//u/route/group//eu
//eu/route/group//lab
//lab.eu/route/group//research

Group-name Model

Public group names use dotted suffix hierarchy for discovery only.

Examples:

eu
lab.eu
research.lab.eu

Each delegation step uses one immediate child label only. Canonical records do not repeat or reverse the full suffix.

Full group-name reconstruction:

under parent u, child group is <child-label>
under any other parent <parent-group>, child group is <child-label>.<parent-group>

Child-label Rules

Each child label:

MUST be non-empty
MUST NOT contain ., /, {, }, |, or :
MUST NOT equal . or ..
SHOULD fit in one Key segment

Provisioning

A route-capable client is provisioned out of band with:

the public-root endpoint
one or more trusted root route authority verifiers
optional repo verifier pin for the public root

Child-group Records

Canonical coordinate for top-level eu:

//u/route/group//eu/|/seal/<u-route-verifier>

Canonical coordinate for lab.eu under eu:

//eu/route/group//lab/|/seal/<eu-route-verifier>

Canonical coordinate for research.lab.eu under lab.eu:

//lab.eu/route/group//research/|/seal/<lab.eu-route-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <parent-route-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: <parent-group>
API: route/group
Key: <child-label>
TAI: <tai>
Upstream: <via>
Route-Authority-Key: <child-route-verifier>
[Upstream-Verifier: <repo-verifier>]
[Home-API: <api>]
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
🖧: B.<hash>.H3
Data-Length: 0

Rules:

packet MUST be a Seal
Seal-By MUST equal a currently trusted route authority verifier for <parent-group>
API MUST be route/group
Key MUST be <child-label>
<child-label> MUST be one immediate child label under <parent-group>
Upstream MUST appear exactly once
Route-Authority-Key MUST appear exactly once
Upstream-Verifier MAY appear at most once
Home-API MAY appear at most once
Blob Data-Length MUST be 0

API Records

Canonical coordinate for API chat in group u:

//u/route/api//chat/|/seal/<u-route-verifier>

Canonical coordinate for API docs in group lab.eu:

//lab.eu/route/api//docs/|/seal/<lab.eu-route-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <group-route-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: <group>
API: route/api
Key: <api>
TAI: <tai>
[Upstream: <via>]
[Upstream-Verifier: <repo-verifier>]
[Content-Authority: <content-verifier>]
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
🖧: B.<hash>.H3
Data-Length: 0

Rules:

packet MUST be a Seal
for Group: u, Seal-By MUST equal a trusted root route authority verifier
for any other group, Seal-By MUST equal a currently trusted route authority verifier for that group
API MUST be route/api
Key MUST be <api>
Upstream MAY appear at most once
Upstream-Verifier MAY appear at most once
Content-Authority MAY appear at most once
Blob Data-Length MUST be 0

After route resolution selects an API record, API content resolution continues through the deploy-pointer convention in [100-CONTENT-ROUTES.md].

Group Landing API Convention

Groups commonly expose one public landing API.

Convention:

Home-API in the resolved child-group record selects that landing API
when Home-API is absent, clients MAY fall back to API name home

Resolution Rules

To resolve direct root API //u/chat//...:

connect to the public-root endpoint
fetch //u/route/api//chat
verify Seal with a trusted root route authority verifier
use the API record’s endpoint and optional pins
continue with the API deploy-pointer resolution defined in [100-CONTENT-ROUTES.md]

To resolve group landing page //lab.eu:

connect to the public-root endpoint
fetch //u/route/group//eu
verify Seal with a trusted root route authority verifier
connect to eu upstream
fetch //eu/route/group//lab
verify Seal with trusted eu Route-Authority-Key
read Home-API when present, else fall back to home
continue as //lab.eu/<home-api>//index.html

To resolve //lab.eu/docs//...:

connect to the public-root endpoint
fetch //u/route/group//eu
verify Seal with a trusted root route authority verifier
read Upstream, Route-Authority-Key, and optional repo pin for group eu
connect to eu upstream
fetch //eu/route/group//lab
verify Seal with trusted eu Route-Authority-Key
read Upstream, Route-Authority-Key, and optional repo pin for group lab.eu
connect to lab.eu upstream
fetch //lab.eu/route/api//docs
verify Seal with trusted lab.eu Route-Authority-Key
apply API-level Upstream or repo pin overrides when present
resolve the API deploy pointer at //lab.eu/admin/deploy//docs/| as defined in [100-CONTENT-ROUTES.md]
fetch content from the selected content root

Generic algorithm for a public group with labels:

split the group into labels on .
start with the rightmost label under //u/route/group//
then walk leftward one label at a time
at each step, fetch //<resolved-parent-group>/route/group//<next-child-label>
after the final group resolves, fetch //<resolved-group>/route/api//<api>

Local Route Plane

The route scheme also defines a local effective route plane in the home repo.

Canonical roots:

//repo/route/group//...
//repo/route/api//...
//repo/route/auth//...

All local route-plane packets use:

Group: repo
APIs under route/...

For this section, <local-route-authority-verifier> is the currently trusted verifier for the local route plane.

This spec does not require one canonical storage source for that verifier. Repository-service clients commonly use the Seal-By of //repo/admin/identity//root/|, but other clients or local implementations may provision it independently.

These packets are private client-side policy. They are not public namespace authority records.

Local exact-group records

Canonical coordinate:

//repo/route/group//<exact-group>/|/seal/<local-route-authority-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <local-route-authority-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: repo
API: route/group
Key: <exact-group>
TAI: <tai>
Upstream: <via>
Route-Authority-Key: <verifier>
[Upstream-Verifier: <repo-verifier>]
[Home-API: <api>]
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
🖧: B.<hash>.H3
Data-Length: 0

Rules:

packet MUST be a Seal
Seal-By MUST equal the current <local-route-authority-verifier>
API MUST be route/group
Key MUST be <exact-group>
<exact-group> MUST satisfy the HPPR Group value constraints from 010-PACKETS.md
Upstream MUST appear exactly once
Upstream MUST follow the via syntax from 033-VIA-SYNTAX.md
Route-Authority-Key MUST appear exactly once
Route-Authority-Key MUST be V.<b64a>.H3
Upstream-Verifier MAY appear at most once
Upstream-Verifier, when present, MUST be V.<b64a>.H3
Home-API MAY appear at most once
Home-API, when present, MUST satisfy the HPPR API value constraints from 010-PACKETS.md
Blob Data-Length MUST be 0

Meaning:

exact local effective anchor for one full group name
replaces the canonical public answer for that exact group in effective mode
provides the trusted route-authority state from which descendant public records are verified
for exact-group = u, acts only as the effective local root anchor

The local plane stores exact groups, not delegation edges.

Local exact-API records

Canonical coordinate:

//repo/route/api//<group>/<api>/|/seal/<local-route-authority-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <local-route-authority-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: repo
API: route/api
Key: <group>/<api>
TAI: <tai>
[Upstream: <via>]
[Upstream-Verifier: <repo-verifier>]
[Content-Authority: <content-verifier>]
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
🖧: B.<hash>.H3
Data-Length: 0

Rules:

packet MUST be a Seal
Seal-By MUST equal the current <local-route-authority-verifier>
API MUST be route/api
Key MUST be <group>/<api>
<group> MUST satisfy the HPPR Group value constraints from 010-PACKETS.md
<api> MUST satisfy the HPPR API value constraints from 010-PACKETS.md
at least one of Upstream, Upstream-Verifier, or Content-Authority MUST appear
Upstream MAY appear at most once
Upstream, when present, MUST follow the via syntax from 033-VIA-SYNTAX.md
Upstream-Verifier MAY appear at most once
Upstream-Verifier, when present, MUST be V.<b64a>.H3
Content-Authority MAY appear at most once
Content-Authority, when present, MUST be V.<b64a>.H3
Blob Data-Length MUST be 0

Meaning:

exact local override for one API in one group
may layer over a local or public group answer
may act as terminal bootstrap for one group/api even when no exact-group anchor exists

Local auth records

Local route auth attaches an identity choice to routed access. Public route records do not carry auth data.

Canonical coordinates:

group default: //repo/route/auth//<group>/|/seal/<local-route-authority-verifier>
exact API: //repo/route/auth//<group>/<api>/|/seal/<local-route-authority-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <local-route-authority-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: repo
API: route/auth
Key: <group>[/<api>]
TAI: <tai>
Auth: <identity-text>
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
🖧: B.<hash>.H3
Data-Length: 0

Rules:

packet MUST be a Seal
Seal-By MUST equal the current <local-route-authority-verifier>
API MUST be route/auth
Key MUST be exactly <group> for group-default auth or <group>/<api> for exact-API auth
<group> MUST satisfy the HPPR Group value constraints from 010-PACKETS.md
<api>, when present, MUST satisfy the HPPR API value constraints from 010-PACKETS.md
Auth MUST appear exactly once
Auth: anyone means unauthenticated access
any non-anyone Auth value MUST follow the local route implementation’s client identity-text convention
Blob Data-Length MUST be 0

Meaning:

exact-API auth overrides group auth
missing local auth defaults to anyone
local auth records are private client policy

Auth: anyone is valid and can explicitly override a non-anonymous group default for one API.

Any non-anyone Auth text is outside generic HPPR scheme semantics. Repository-service clients commonly use the identity-text forms defined in 045-IDENTITY-TEXT.md.

Effective Route Resolution

Effective resolution uses both the public route plane and the local route plane.

For target //<group>/<api>//..., effective resolution proceeds in this order.

Step 0: explicit endpoint override

If the input includes explicit via or CLI --via, that wins.

This bypasses stored endpoint selection. It does not erase separately stored local auth or content metadata that the caller may still apply.

Step 1: local exact-API candidate

Check:

//repo/route/api//<group>/<api>/|

If present, record it as a local exact-API candidate. Do not merge fields yet.

Step 2: determine the effective root anchor

If //repo/route/group//u/| exists, effective mode uses it as the root anchor. Otherwise effective mode starts from the provisioned public root.

Step 3: walk exact groups from root to target

Split the group into dotted labels and reconstruct exact groups from right to left.

Example for research.ops.lab.eu:

eu
lab.eu
ops.lab.eu
research.ops.lab.eu

For each exact group in order:

check local exact-group anchor:
- //repo/route/group//<exact-group>/|
if present:
- use it as the effective anchor for that exact group
- it shadows the canonical public answer for that exact group
- descendant public lookup continues from this local anchor’s Route-Authority-Key
otherwise:
- fetch the canonical public child-group record under the current parent namespace
- verify it using the current parent anchor’s Route-Authority-Key
- use that public record as the effective anchor for the exact group

Step 4: resolve the API record

After the final exact-group anchor is known:

read local exact-API candidate when present
attempt canonical public API record:
- //<group>/route/api//<api>
- verified with the final exact-group anchor Route-Authority-Key
for non-u groups, allow canonical Content-Authority fallback from:
- //u/route/api//<api>

Content-Authority fallback applies only to Content-Authority. It never applies to Upstream.

Step 5: allow terminal local exact-API bootstrap

If no effective exact-group chain exists for the target group, a local exact-API record may still be sufficient.

In that case:

missing canonical public group/API records is not a failure
the local API record alone provides the effective route answer for that exact API
descendant group delegation is not implied

Step 6: effective field merge

API-level values override group-level values. Local values override public values at the same level.

Effective endpoint:

local API Upstream
public API Upstream
local exact-group Upstream
public exact-group Upstream
failure if nothing resolves

Effective upstream repo verifier:

local API Upstream-Verifier
public API Upstream-Verifier
local exact-group Upstream-Verifier
public exact-group Upstream-Verifier

Effective content authority:

local API Content-Authority
public API Content-Authority
for non-u groups only, canonical fallback to //u/route/api//<api>

Effective home API:

local exact-group Home-API
public exact-group Home-API
implementation fallback home

Step 7: local auth attachment

After the effective route target is known, attach local auth in this order:

//repo/route/auth//<group>/<api>/|
//repo/route/auth//<group>/|
implicit default anyone

Step 8: route client construction

The effective route client uses:

the resolved endpoint
the attached local auth identity, or anyone if none exists
the resolved upstream repo pin when present

Canonical Route Resolution

Canonical resolution ignores all //repo/route/...//... packets.

For public names:

start from the provisioned public root
walk delegated public group edges only
resolve the public API record under the final exact group
apply canonical public Content-Authority fallback from //u/route/api//<api> for non-u groups only

For ~ groups:

canonical resolution has no public answer

Conditions and Canonical Truth

Condition-* evaluation uses canonical resolution, not effective local resolution.

For group u, canonical truth is the current provisioned public-root configuration:

the trusted root route authority verifiers
the optional pinned public-root repo verifier, when provisioned

A local //repo/route/group//u/| packet affects only effective local routing. It MUST NOT affect canonical Condition-* truth.

Reason:

local route overrides are private client policy
condition meaning must not vary per client home repo
canonical public truth is the only stable reference for conditional scheme semantics

Authority-Local Name Tree

Public or private identity naming lives under an authority group.

Canonical root:

//<authority-group>/name//...

Examples:

//lab.eu/name//...
//friends/name//...

The same mechanism supports public and private identities. Visibility is controlled by the authority group’s repository policy.

Exact-name Syntax

Text form:

<part>[.<part>...]@<authority-group>

Examples:

ops@lab.eu
ops.alice@lab.eu
ops.alice.phone@lab.eu

The local name parts stay in written order. They are not reversed in storage.

Name-part Rules

Each local name part:

MUST be non-empty
MUST NOT contain /, {, }, |, :, @, or .
MUST NOT equal . or ..
SHOULD fit in one Key segment

Core Model

The exact identity node is the continuity anchor. Each exact node has:

one stable Name-Key
zero or more Current-Key values

Top-level nodes are created by the authority group. Child nodes are created by the current holder of the parent node’s Name-Key.

Identity Node Records

Canonical coordinate for ops.alice.phone@lab.eu:

//lab.eu/name//ops/alice/phone/|

Packet form:

🖧: S.<hash>.H3
Seal-By: <authority-or-parent-node-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: <authority-group>
API: name
Key: <part>[/<part>...]
TAI: <tai>
State: active|withdrawn|compromised|rotated
Name-Key: <verifier>
[Current-Key: <verifier>]*
[Node-Type: role|person|device|team]
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
[+Link: supersedes <hash>]
🖧: B.<hash>.H3
Data-Length: <len>

<optional note>

Rules:

packet MUST be a Seal
State MUST appear exactly once
State MUST be active, withdrawn, compromised, or rotated
Name-Key MUST appear exactly once when State: active
Current-Key MAY appear zero or more times
the exact identity anchor is //<authority-group>/name//<part>[/<part>...]
the visible name is <part>[.<part>...]@<authority-group>

Authorization rules:

a top-level node <part> MUST be signed by a verifier authorized by the authority group
a child node <p1>/.../<pn> MUST be signed by the current holder of the parent node’s Name-Key

Continuity rules:

changing Current-Key is ordinary operational rotation
changing Name-Key is identity-significant

Resolution

To resolve ops.alice.phone@lab.eu:

resolve authority group lab.eu through the route scheme
fetch //lab.eu/name//ops/|
read Name-Key and Current-Key for ops@lab.eu
fetch //lab.eu/name//ops/alice/|
read Name-Key and Current-Key for ops.alice@lab.eu
fetch //lab.eu/name//ops/alice/phone/|
read Name-Key and Current-Key for ops.alice.phone@lab.eu

Exact-name resolution is exact. There is no implicit fallback from ops.alice.phone@lab.eu to ops.alice@lab.eu or ops@lab.eu.

Underspecified UX is handled by listing:

//lab.eu/name//
//lab.eu/name//ops/
//lab.eu/name//ops/alice/

Public Attestation Tree

All attestation packets use:

Group: u
API: attest

Packet families:

state — current attestation state packets
request — advisory requests asking another key to publish attestation state
meaning — issuer-local explanation of relation names

Scope IDs

<scope-id> lets one issuer publish more than one independent statement for the same target and relation.

Typical values:

global
event-2026
org-hr

`state/verifier`

state/verifier carries attestation state about one signer verifier.

Canonical coordinate:

//u/attest/state/verifier//<subject-verifier>/<scope-id>/<relation>/|/seal/<issuer-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <issuer-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: u
API: attest/state/verifier
Key: <subject-verifier>/<scope-id>/<relation>
TAI: <tai>
State: yes|no|withdrawn
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
[Scope: //<group>/<api>//...]
[Expires: <tai>]
[Meaning: <text-or-urc>]
[+Link: evidence <hash>]*
[+Link: request <hash>]
🖧: B.<hash>.H3
Data-Length: <len>

<free text note>

Rules:

packet MUST be a Seal
State MUST appear exactly once
State MUST be yes, no, or withdrawn
the subject is the verifier named in the path
evaluators SHOULD use the tip packet for one exact signer path
if Expires is present and already passed, the statement is invalid

`state/name`

state/name carries attestation state about one exact identity name. It does not define names. Names are defined by the name scheme in this spec.

Canonical coordinate:

//u/attest/state/name//<scope-id>/<relation>/<authority-group>/<part>[/<part>...]/|/seal/<issuer-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <issuer-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: u
API: attest/state/name
Key: <scope-id>/<relation>/<authority-group>/<part>[/<part>...]
TAI: <tai>
State: yes|no|withdrawn
Target-Name: <part>[.<part>...]@<authority-group>
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
[Scope: //<group>/<api>//...]
[Expires: <tai>]
[+Link: evidence <hash>]*
🖧: B.<hash>.H3
Data-Length: <len>

<free text note>

Rules:

packet MUST be a Seal
State MUST appear exactly once
State MUST be yes, no, or withdrawn
Target-Name MUST appear exactly once
Target-Name MUST exactly match the authority group and local parts in the path
the exact identity anchor is the target name itself, not the target’s current operational verifier
if Expires is present and already passed, the statement is invalid

Relation names are ordinary strings. Common examples:

trusted
is-human
known
official
member
speaks-for

`request`

request packets are advisory only. They ask another verifier to publish attestation state.

Canonical coordinate:

//u/attest/request//<target-verifier>/<scope-id>/<relation>/<requester-verifier>/|/seal/<requester-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <requester-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: u
API: attest/request
Key: <target-verifier>/<scope-id>/<relation>/<requester-verifier>
TAI: <tai>
[Request-Subject: <subject-verifier>]
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
[Scope: //<group>/<api>//...]
[+Link: comment <hash>]
[+Link: profile <hash>]
🖧: B.<hash>.H3
Data-Length: <len>

<short free text request>

Rules:

packet MUST be a Seal
Seal-By MUST equal <requester-verifier>
request packets are advisory only
hosts MUST NOT require request packets for attestation validity

`meaning`

meaning explains one relation name in issuer-local human terms.

Canonical coordinate:

//u/attest/meaning//<relation>/|/seal/<issuer-verifier>

Packet form:

🖧: S.<hash>.H3
Seal-By: <issuer-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: u
API: attest/meaning
Key: <relation>
TAI: <tai>
Label: <short label>
[Condition-Route-Authority-Key: <group> <verifier>]*
[Condition-Name-Key: <name> <verifier>]*
[Condition-Current-Key: <name> <verifier>]*
[Condition-State: <state> <exact-urc>]*
[Scope: //<group>/<api>//...]
🖧: B.<hash>.H3
Data-Length: <len>

<human-readable explanation>