HPPR Repository Request Envelopes

Tags: repo, command-flow, auth

© R.A.Sol

Repository commands arrive in envelopes. The envelope carries the command name, arguments, identity material, and any flow binding needed to authorize the command.

A repository command envelope answers three questions:

• which command is requested
• which principal is making the request
• which connection or message-flow context validates the request

Session Request Envelope

After session HELLO, repository session commands are sent as Seal packets. API values starting with 🖧 are protocol commands.

🖧: S.<hash>.H3
Seal-By: <client-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: <group>
API: 🖧<COMMAND>
Key: <key-with-session>
TAI: <tai>
🖧: B.<hash>.H3
Data-Length: <len>

<args>

The Key format selects the authentication scheme:

Rules:

• API names the command.
• Key MUST carry the current session binding.
• Seal-By MUST verify the request signature.
• the session flow rejects envelopes whose session binding does not match the connection.
• Ring1 identity loading is defined in 051.
• Ring2 identity loading is defined in 052.

Ring1 Session Envelope

Ring1 request form:

🖧: S.<hash>.H3
Seal-By: <member-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: repo
API: 🖧<COMMAND>
Key: <repo-name>/<ring1-name>/<session-id>
TAI: <tai>
🖧: B.<hash>.H3
Data-Length: <len>

<args>

Rules:

• Group is repo.
• Key carries repo name, Ring1 name, and HELLO session.
• Seal-By must be a configured member verifier or derived member verifier.

Anyone Session Envelope

Anyone request form:

🖧: S.<hash>.H3
Seal-By: <client-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: repo
API: 🖧<COMMAND>
Key: <repo-name>/anyone/<session-id>
TAI: <tai>
🖧: B.<hash>.H3
Data-Length: <len>

<args>

Rules:

• Group is repo.
• Key carries repo name, the built-in Ring1 name anyone, and HELLO session.
• Seal-By must verify the request signature; membership is the built-in Ring1 anyone principal.

Ring2 Session Envelope

Ring2 request form:

🖧: S.<hash>.H3
Seal-By: <member-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: <target-group>
API: 🖧<COMMAND>
Key: <repo-name>/<session-id>
TAI: <tai>
🖧: B.<hash>.H3
Data-Length: <len>

<args>

Rules:

• Group is the target group, not repo.
• Key carries repo name and HELLO session.
• Seal-By must resolve to group membership, or the request follows the non-member runtime path where the repository service supports it.

Message Request Envelope

Repository message flow processes one complete request packet and returns one complete response packet. It does not create or use a connection-local session.

Non-HELLO message requests are Seal packets with the explicit public message envelope:

🖧: S.<hash>.H3
Seal-By: <ephemeral-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: repo
API: 🖧<COMMAND>
Key: message/anyone
TAI: <tai>
🖧: B.<hash>.H3
Data-Length: <len>

<args>

Rules:

• Group MUST be repo.
• Key MUST be exactly message/anyone.
• the client signs with ephemeral signing material.
• the server resolves read identity as Ring1 anyone and applies anyone policy.
• TAI tolerance applies to the outer request envelope.
• no repository session binding validation applies.
• session envelopes such as <repo>/<ring>/<session> are rejected on message flow.

Message requests are replayable by design. Use them for public reads and packet-authorized admission.

Trusted Local Null Envelope

The trusted Null command envelope is for local object-capability endpoints. It is not a public network envelope and is not accepted by ordinary repository service listeners.

Request packet form:

🖧: 0.H3
API: 🖧GET
Data-Length: <len>

<args>

Rules:

• possession of the endpoint object is the authorization capability.
• API is required exactly once and names the command.
• request data is the command payload defined by the corresponding repository command.
• Blob, Plex, and Seal request envelopes are rejected by this local endpoint convention.
• Null packets are command envelopes and response envelopes only.
• Null packets are never stored as repository content.
• one request packet produces one response packet.
• streaming commands are not part of this local endpoint convention.
• ordinary repository network listeners reject non-HELLO Null command packets.
• local endpoints accept non-HELLO Null command packets only when configured as trusted object-capability endpoints; this is endpoint behavior, not a client-supplied HELLO option.

Response shape:

• 🖧HELLO returns a Null HELLO packet.
• 🖧GET success returns raw Blob, Plex, or Seal packet bytes.
• non-GET success returns a Null packet whose data is the command response payload and whose Status header is ok.
• errors return Null packets whose Status header is error or fatal and whose data starts with ERROR or FATAL.
• clients may use Status when present; data-prefix parsing remains the generic error rule for Null error packets.

Trusted Null endpoint HELLO responses include:

🖧: 0.H3
Command-Flow: message
Seal-By: 0
Format: H3
Allow-Null-Command: 1
Storage-Backend: indexeddb
Schema-Version: 2
Message-Commands: 🖧HELLO 1 | 🖧GET 1 | 🖧STORE 1
Extension: store-top-level-blob
Status: ok
Data-Length: 0

Top-level Blob STORE is a local trusted-envelope extension for browser-local chunk storage and content-addressed caching. Repository service policy may still reject client-written top-level Blob packets on authenticated session flow.

Command Responses

Successful session-flow responses are Seal packets signed by the repo verifier.

🖧: S.<hash>.H3
Seal-By: <repo-verifier>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: repo
API: 🖧<COMMAND>
Key: <repo-name>/<session-id>
TAI: <response-tai>
🖧: B.<hash>.H3
Data-Length: <len>

<response-data>

Message-flow responses use the transport’s one-response mapping. Successful repository HTTP and UDP commands return raw packet bytes for 🖧GET and Null or command-defined response packets for other commands. Errors are Null packets as defined in 030.