HPPR Repository Session Flow
Tags: repo, command-flow, session
© R.A.Sol
The repository session flow is the authenticated command flow for long-lived repository connections.
It extends command messages with a connection-bound HELLO state, authenticated Seal request envelopes, repository identity metadata, and ACL enforcement.
Session Lifecycle
Repository session flow requires connection-bound greeting state before ordinary authenticated commands.
- on TCP, WebSocket, and Unix-socket transports, the client sends
generic
🖧HELLOfirst and receives a repository HELLO response - on QUIB, the encrypted handshake HELLO payload carries the same
repository greeting state, and later
🖧HELLOremains available as a refresh command - a different signing secret requires a new connection and new HELLO state
Repository HELLO Response
The repository service adds service-specific headers to the generic HELLO response. TCP, WebSocket, and Unix-socket session-flow HELLO responses are Null packets:
🖧: 0.H3
Command-Flow: session
Session-ID: <session-id>
Repo-Name: <repo-name>
Seal-By: <repo-verifier>
[PHC: $argon2id$v=19$m=<m>,t=<t>,p=<p>$]
Format: H3
[Transport: <via> [hints...]]*
Session-Commands: 🖧HELLO 1 | 🖧GET 1 | 🖧HEADERS 1 | 🖧LIST 1 | 🖧STORE 1 | 🖧ADD 1 | 🖧WATCH 1 | 🖧TIPS 1 | 🖧DETACH 1 | 🖧AUDIT 1 | 🖧MEMBERS 1 | 🖧INGEST 1 | 🖧EXCHANGE 1 | 🖧STREAM_PUB 1 | 🖧STREAM_SUB 1
Allow-Null-Command: 0
Limit: max-header-line 1024
Limit: max-extra-headers 512
Status: ok
Uptime: <seconds>
[Hpprd-Version: <version>]
Hpprd-Backend: <backend>
Data-Length: 0
QUIB carries a Null HELLO payload in the encrypted transport handshake instead of requiring a HELLO round trip. That handshake payload contains only the shared capability headers:
🖧: 0.H3
Command-Flow: session
Repo-Name: <repo-name>
Seal-By: <repo-verifier>
[PHC: $argon2id$v=19$m=<m>,t=<t>,p=<p>$]
Format: H3
[Transport: <via> [hints...]]*
Session-Commands: 🖧HELLO 1 | 🖧GET 1 | 🖧HEADERS 1 | 🖧LIST 1 | 🖧STORE 1 | 🖧ADD 1 | 🖧WATCH 1 | 🖧TIPS 1 | 🖧DETACH 1 | 🖧AUDIT 1 | 🖧MEMBERS 1 | 🖧INGEST 1 | 🖧EXCHANGE 1 | 🖧STREAM_PUB 1 | 🖧STREAM_SUB 1
Allow-Null-Command: 0
Data-Length: 0
Additional header meanings:
| Header | Status | Meaning |
|---|---|---|
Command-Flow |
required | session for repository session flow |
Session-ID |
required in session HELLO, absent from QUIB handshake payload | Connection-bound repository session token |
Repo-Name |
required | Repository identifier. Default is localhost |
Seal-By |
required | Repo verifier derived from the local operational ring0 signing
secret, or 0 before bootstrap |
PHC |
optional | Argon2id parameters for Ring1 token derivation; clients use defaults when absent |
Format |
required | Packet and envelope format identifier; value
H3 |
Session-Commands |
repeated | Session-flow command list from 032 |
Allow-Null-Command |
required | 0 for repository session flow; non-HELLO Null
commands are not accepted |
Transport |
repeated | Advertised transport via string plus endpoint hints |
Limit |
implementation extension | Repo limits as <name> <value> |
Status |
implementation extension | Daemon status; ok indicates readiness |
Uptime |
implementation extension | Daemon uptime in seconds |
Hpprd-Version |
optional implementation extension | Daemon build/version string |
Hpprd-Backend |
implementation extension | Storage backend name |
On QUIB, the repository service derives Session-ID
from transport keying material and formats it as
Q#<b64a>. The derived value is connection state,
not a header in the handshake payload. On TCP, WebSocket, and
Unix-socket transports, the repository service uses a
repository-generated TAI session id and sends it as
Session-ID.
Authenticated HELLO
After initial greeting, an authenticated 🖧HELLO
request returns the same session HELLO Null response shape and
refreshes endpoint status and capabilities. No ACL check is applied.
Any authenticated identity may send 🖧HELLO.
Repo Identity
The repository’s verifier is stored at:
//repo/admin/identity//root/|
It is a self-signed Seal. Repo-Name in that identity
is returned in HELLO.
Accepted Envelopes and Responses
Session flow accepts the Ring1, Ring2, and anyone session envelopes defined in 042. Non-HELLO Null command packets and public message envelopes are rejected on repository session listeners.
Successful session responses are Seal packets signed by the repo verifier, also defined in 042.
Command Authorization
Repository commands require authentication on session flow and are subject to ACL evaluation per 050. Command semantics and authorization mapping are defined in 041.
Repository Errors
In addition to the generic error types from 030, the repository service uses:
INVALID_IDENTITYUNAUTHORIZEDHELLO_REQUIRED