HPPR Repository Service Commands

Tags: repo, command

The HPPR Repository Service stores packets, resolves URCs, enforces repository policy, and exposes repository commands over accepted wire endpoints.

Wire message shape, Null packets, HELLO, command flows, and errors are defined in 030, 031, and 032. Repository envelopes are defined in 042.

Security Model

HPPR validates packets at the packet layer, not the channel layer.

markline hash proves packet bytes are unchanged
Seal signature proves which verifier signed the packet

Repository authentication, authorization, session binding, and accepted request envelopes are service behavior.

Command Summary

Command	Payload	Response	Result mode
`🖧HELLO`	none	capability advertisement	single-response packet
`🖧GET`	`<urc>` (020)	full packet bytes	single-response packet
`🖧HEADERS`	`<urc>`	markline + headers to blank line	single-response packet
`🖧LIST`	`<urc-coordinate>`	LF-separated children, sorted	single-response packet
`🖧STORE`	complete packet bytes	LF-separated stored hashes	single-response packet
`🖧ADD`	headers, blank line, data	LF-separated stored hashes	single-response packet
`🖧WATCH`	`<urc-coordinate-prefix>`	stream of `+`/`-` change events	acknowledged stream
`🖧TIPS`	`<urc-coordinate-prefix>`	LF-separated tip coordinates	single-response packet
`🖧DETACH`	hash	success response	single-response packet
`🖧AUDIT`	implementation-defined filter	audit log stream	acknowledged stream
`🖧MEMBERS`	member URC	LF-separated expanded members	single-response packet
`🖧INGEST`	full top-level Seal packet	LF-separated stored hashes	single-response packet
`🖧EXCHANGE`	NEED/HAVE lines	negotiated packet transfer	negotiated raw packet exchange
`🖧STREAM_PUB`	`<coordinate-prefix>`	OK then relay input	relay mode after response
`🖧STREAM_SUB`	`<coordinate-prefix>`	relay output	relay mode without response

Flow Availability

Command	Session	HTTP message	UDP message	Trusted local Null
`🖧HELLO`	yes	yes	no	yes
`🖧GET`	yes	yes	yes	yes
`🖧HEADERS`	yes	yes	yes	yes, if exposed
`🖧LIST`	yes	yes, when advertised	no	yes, if exposed
`🖧STORE`	yes	no	no	yes, if exposed
`🖧ADD`	yes	no	no	no
`🖧WATCH`	yes	no	no	no
`🖧TIPS`	yes	no	no	no
`🖧DETACH`	yes	no	no	no
`🖧AUDIT`	yes	no	no	no
`🖧MEMBERS`	yes	no	no	no
`🖧INGEST`	yes	yes, when advertised	no	no
`🖧EXCHANGE`	yes	no	no	no
`🖧STREAM_PUB`	yes	no	no	no
`🖧STREAM_SUB`	yes	no	no	no

Endpoint HELLO command lists are authoritative for a concrete endpoint.

Envelope Summary

Envelope layouts are defined in 042. This table summarizes which envelope families can carry each command.

Command	Session envelope	Message envelope	Auth source	Response type
`🖧HELLO`	initial Null, then session Seal	HTTP Null or trusted local Null	endpoint/session	HELLO Null packet
`🖧GET`	Ring1, Ring2, or anyone Seal	public message Seal, UDP message, trusted local Null	request principal or local capability	raw packet bytes
`🖧HEADERS`	Ring1, Ring2, or anyone Seal	public message Seal, UDP message, trusted local Null when exposed	request principal or local capability	packet headers
`🖧LIST`	Ring1, Ring2, or anyone Seal	public message Seal when advertised, trusted local Null when exposed	request principal or local capability	Null/command response data
`🖧STORE`	Ring1, Ring2, or anyone Seal	trusted local Null when exposed	request principal or local capability	stored hash list
`🖧ADD`	Ring1, Ring2, or anyone Seal	none	request principal	stored hash list
`🖧WATCH`	Ring1, Ring2, or anyone Seal	none	request principal	acknowledged event stream
`🖧TIPS`	Ring1, Ring2, or anyone Seal	none	request principal	tip coordinate list
`🖧DETACH`	Ring1 ring0 Seal	none	Ring1 ring0	success response
`🖧AUDIT`	Ring1 ring0 Seal	none	Ring1 ring0	acknowledged audit stream
`🖧MEMBERS`	Ring1, Ring2, or anyone Seal	none	request principal	expanded member list
`🖧INGEST`	Ring1, Ring2, or anyone Seal	public message Seal when advertised	submitted packet signer	stored hash list
`🖧EXCHANGE`	Ring1, Ring2, or anyone Seal	none	request principal	negotiated raw packet exchange
`🖧STREAM_PUB`	Ring1, Ring2, or anyone Seal	none	request principal per segment	relay input after OK
`🖧STREAM_SUB`	Ring1, Ring2, or anyone Seal	none	request principal	relay output without OK

Authorization Mapping

Repository session flow applies ACL evaluation per 050:

Command	ACL check
`🖧GET`	`read`
`🖧HEADERS`	`read`
`🖧LIST`	`list`
`🖧STORE`	`write`
`🖧ADD`	`write`
`🖧INGEST`	packet-authorized Ring2 write
`🖧WATCH`	`list`
`🖧TIPS`	`list`
`🖧DETACH`	Ring1 `ring0`
`🖧AUDIT`	Ring1 `ring0`
`🖧MEMBERS`	`read`

Ring1 behavior is defined in 051. Ring2 behavior is defined in 052.

`🖧STORE`

🖧STORE payload is complete packet bytes starting with a markline.

Repository session flow applies these rules:

top-level Blob packets are rejected for client writes
blob data for client writes must be wrapped in Plex or Seal so write policy can target the packet versioned coordinate
write authorization applies to the authenticated requester and does not require that requester to match any Seal-By inside the stored packet
thin packets may reference existing nested packets by hash
request Data-Length may be up to 34 MiB

Thin packets may reference existing nested packets:

thin Plex may reference existing Blob with 🖧: B.<hash>\n
thin Seal may reference existing Plex with 🖧: P.<hash>\n

Response data lists stored hashes from outermost to innermost:

S.seal~hash.H3
P.plex~hash.H3
B.blob~hash.H3

storing a Seal returns 3 lines
storing a Plex returns 2 lines (Plex, Blob)

`🖧ADD`

Input is LF-separated headers, blank line, optional data.

Type selection:

Seal-By present: create Seal
else if any Plex header present: create Plex
else: create Blob

Defaults:

Group: u
API: index
Key: root
TAI: now

Seal-By selectors for packet create mode:

ring0 — use the repo’s local operational ring0 signing secret; requires ring0 auth
<verifier> <secret> — use an explicit inline signing pair

No other selector form is valid.

References:

🖧: B.<hash> references existing Blob
🖧: P.<hash> references existing Plex

`🖧WATCH`

Subscribes to index changes under a coordinate prefix.

After acknowledgment, the connection delivers a stream of LF-terminated lines:

+ <versioned-coordinate>
- <versioned-coordinate>

+ means the coordinate became visible in the subscribed tree
- means the coordinate was removed or unindexed

WATCH delivers future changes only. To avoid missing events between subscription and initial state read, subscribe first, then read current state.

Events are filtered by list permission per 050. ACL changes to auth, member, or policy packets take effect on active WATCH streams immediately. No reconnect is required for ACL changes.

`🖧DETACH`

Payload is one hash. Removes packet from the coordinate index only. Stored packet bytes remain in hash storage. Ring1 ring0 authorization is required.

`🖧TIPS`

Returns LF-separated versioned coordinates for tip packets. Events are filtered by list permission.

`🖧AUDIT`

Streams audit log lines. Ring1 ring0 authorization is required.

`🖧MEMBERS`

Returns expanded member list with tags. Ring2 details are defined in 052.

`🖧INGEST`

🖧INGEST admits a packet by the submitted packet’s authority, not by the outer request identity.

Rules:

payload is one complete full top-level Seal packet
top-level Blob, Plex, Null, and thin packets are rejected
the submitted Seal signature and hash must validate
the submitted Plex Group selects the Ring2 group
submitted Seal-By must be a current expanded Ring2 member for that group
Ring2 policy must grant write on the exact submitted Seal versioned coordinate
Ring2 non-member / anyone fallback does not authorize INGEST
request envelope Data-Length may be up to 34 MiB

Response data lists stored hashes like 🖧STORE.

Streaming Commands

🖧EXCHANGE, 🖧STREAM_PUB, and 🖧STREAM_SUB are defined in 080.

Errors

In addition to generic error types from 030, the repository service uses:

INVALID_IDENTITY
UNAUTHORIZED
HELLO_REQUIRED