HPPR Core Specification

HPPR Packet Format

© R.A.Sol

Every packet starts with a markline:

🖧: <hash>

<hash> is BLAKE3-256 in B64A. It identifies the canonical payload after the first LF.

HPPR packet types:

• Blob: raw bytes
• Plex: metadata + embedded Blob
• Seal: signature + embedded Plex

Shared Rules

• Canonical payload is everything after the markline LF.
• Hash text format is T.<b64a>.H3 where T is B, P, or S.¹
• Header syntax is <Name>: <value> with exactly one space after :.
• Header values are non-empty.
• Header names and values are UTF-8 NFC.
• Control bytes are forbidden in headers: 0x00..0x1F and 0x7F.
• Header line length limit is 1024 bytes, excluding trailing LF.
• Line endings are LF only. CR and CRLF are invalid.
• Whitespace is data. Never trim.

Blob

🖧: <hash>
Data-Length: <len>

<data exactly <len> bytes>

Rules:

• <hash> MUST start with B..
• Canonical payload is Data-Length, blank line, then <len> data bytes.
• Data-Length is base-10 with no leading zeros, except 0.
• Readers MUST consume exactly <len> bytes.
• Blob data is opaque.
• Blob Data-Length max is 32 MiB.

Plex

🖧: <hash>
Group: <group>
App: <app>
Location: <location>
TAI: <tai>
[Extra headers]*
🖧: <blob_hash>
Data-Length: <len>

<data>

Rules:

• <hash> MUST start with P..
• Required headers appear exactly once, in this order: Group, App, Location, TAI.
• Extra headers follow TAI.
• Canonical payload is all Plex headers plus the full embedded Blob packet, including Blob markline and data bytes.

TAI Format

TAI format:

<seconds>:<subseconds>

Rules:

• 10 digits, :, then 9 digits
• no spaces
• subseconds are nanoseconds

TAI is currently UTC +37 seconds (at time of writing, 2026).

Header Validation

General:

• Header names MUST NOT contain :.
• Header values MAY contain :.

Group and App:

• non-empty
• case-sensitive
• max 56 bytes
• MUST NOT contain /, {, }, |, #
• MUST NOT equal . or ..

Location:

• non-empty; at least one segment is required
• MUST NOT start with /
• MUST NOT end with /
• split by / into segments
• each segment is non-empty
• each segment max 128 bytes
• segment MUST NOT contain {, }, |
• segment MUST NOT equal . or ..
• total Location value max 1014 bytes

Extra Headers

Extra-header ordering is canonical:

• sort by header name using bytewise ascending order
• same-name headers MUST be consecutive
• same-name header order is user-defined and hash-significant

Reserved header names (MUST NOT appear as extra headers):

• Data-Length
• Group
• App
• Location
• TAI
• Seal-By
• Seal-Sig
• 🖧
• ⋯🖧

Limits:

• at most 512 extra headers
• each extra header line max 1024 bytes (excluding LF)

Seal

🖧: <hash>
Seal-By: <verification-key>
Seal-Sig: <signature>
🖧: <plex_hash>
Group: <group>
App: <app>
Location: <location>
TAI: <tai>
[Extra headers (sorted)]*
🖧: <blob_hash>
Data-Length: <len>

<data>

Rules:

• <hash> MUST start with S..
• Canonical payload is Seal-By, Seal-Sig, then full embedded Plex.
• Seal-By format is V.<b64a>.H3 (48 chars).
• Signing keys use &.<b64a>.H3.
• Seal-Sig is an 86-char B64A text signature.
• Signature algorithm is HSB3 over the Plex hash digest.

Limits

• Blob data: 32 MiB (Data-Length max)
• Extra headers per Plex: 512
• Header line length: 1024 bytes (excluding LF)
• Location value: 1014 bytes
• Location segment: 128 bytes
• Group and App value length: 56 bytes

Parsing

1. Read markline and verify the type prefix in the hash.
2. Blob:
   • read Data-Length
   • consume exact data bytes
   • verify Blob hash
3. Plex:
   • read required headers in required order
   • read extra headers with canonical ordering checks
   • parse embedded Blob
   • verify Plex hash
4. Seal:
   • read Seal-By, Seal-Sig
   • parse embedded Plex
   • verify Seal hash
   • verify signature

Reject on any of the following:

• invalid UTF-8 or non-NFC header text
• forbidden control bytes
• CR or CRLF line endings
• size or count limit violations
• required-header order violations
• extra-header ordering violations
• hash mismatch
• signature verification failure

Trailer-hash Format

Trailer-hash format supports streaming when the final hash is only known at the end.

Open marker:

⋯🖧: <type>[ <coordinate>]

Close marker:

⋯🖧: <hash>

Rules:

• <type> is one of B, P, S.
• Exactly one opening marker is allowed per packet.
• Double-open, triple-open, and nested-open sequences are invalid.
• Trailer-hash is a transport transformation only. Packet hashes are unchanged.

Seal trailer example:

⋯🖧: S //<group>/<app>/<location>/|/seal/<verification-key>
<escaped data>
⋯🖧: B.<blob-hash>.H3
Group: <group>
App: <app>
Location: <location>
TAI: <tai>
[Extra headers]*
⋯🖧: P.<plex-hash>.H3
Seal-By: <verification-key>
Seal-Sig: <signature>
⋯🖧: S.<seal-hash>.H3

Additional rules:

• Escape data by replacing each ⋯🖧: with ⋯⋯🖧: before sending.
• Unescape after data extraction by reversing that replacement.
• Data ends at the first \n⋯🖧: sequence.
• Validate all headers and hashes using the same canonical rules.
• To convert to standard packet form:
  • remove leading ⋯ markers
  • insert Blob Data-Length
  • restore standard nested packet layout
  • verify hashes and signature

Both sides buffer full packet bytes to compute and verify hashes.

Thin Format

Thin format stores only part of a packet.

• Thin Seal stores:
  • Seal markline
  • Seal-By
  • Seal-Sig
  • embedded Plex 🖧: hash line
• Thin Plex stores:
  • Plex markline
  • Plex headers
  • embedded Blob 🖧: hash line
• Blob is already minimal and is effectively thin by definition.

Thin packets omit embedded content bytes and rely on nested hashes for reconstruction.

Hash computation always requires full packet bytes. Implementations MUST resolve thin references before hash verification.

Thin format is for storage and transfer when inner packets are already present.

🖧: B.EXAMPLE_BLOB_HASH.H3
Data-Length: 34

# HPPR Quickstart
This is Blob data.

🖧: P.EXAMPLE_PLEX_HASH.H3
Group: a-group
App: some-app
Location: our-collection/item
TAI: 1640995200:000000000
+Link: source B.EXAMPLE_BLOB_HASH.H3
X-Custom: header value
🖧: B.EXAMPLE_BLOB_HASH.H3
Data-Length: 25

This is embedded blob data.

🖧: S.EXAMPLE_SEAL_HASH.H3
Seal-By: V.EXAMPLE_VKEY.H3
Seal-Sig: EXAMPLE_SIGNATURE_B64A
🖧: P.EXAMPLE_PLEX_HASH.H3
Group: a-group
App: some-app
Location: our-collection/item
TAI: 1640995200:000000000
🖧: B.EXAMPLE_BLOB_HASH.H3
Data-Length: 22

This is signed content.

#!/bin/bash -e

blob_msg="# HPPR Quickstart

HPPR packets are content-addressed using BLAKE3.
This Blob contains raw markdown data."

plex_msg="# Plex
This is a plex packet with metadata and links."

seal_msg="# Seal
This is a signed packet that wraps a plex packet."

# Deterministic test-only signatures.
export _UNSAFE_VULNERABLE_HPP_HSB3_DETERMINISTIC_AUX_SEED="examples"
export HPPR_SECRET_KEY="&.ydejWAbshBxyrcKILG3bXkD7fU5c72LtHvLJRfzGXal.H3"
tai="1640995200:000000000"

out="./spec/011-PACKETS-BASIC-EXAMPLE.md"

# Blob
echo -n "$blob_msg" | mkpac --blob > "$out"
blob_hash=$(head -n 1 "$out" | awk '{print $2}')

# Plex
echo -n "$plex_msg" | mkpac \
  -g a-group \
  -a some-app \
  -l our-collection/item \
  -t "$tai" \
  -H "+Link: source $blob_hash" \
  -H "X-Custom: header value" \
  -H "Multiple-Values: B" \
  -H "Multiple-Values: A" \
  >> "$out"

# Seal
echo -n "$seal_msg" | mkpac \
  -k "$HPPR_SECRET_KEY" \
  -g a-group \
  -a some-app \
  -l our-collection/item \
  -t "$tai" \
  >> "$out"

Unified Resource Coordinate

© R.A.Sol

HPPR supports two address forms:

• by hash: ////<hash>
• by coordinate: //<group>/<app>/<location>

Hash addresses are immutable. Coordinate addresses are time-dependent and may resolve to different packets as new packets are stored.

A versioned coordinate pins one exact packet.

Terms

• Location: the Location header value in Plex or Seal packets.
• Coordinate: a string prefixed with //: //<group>/<app>/<location>.

Version Selectors

Multiple packets can share one coordinate. Add /|/... to select a version.

• Top-coordinate: no |, resolves to the latest packet. Example: //g/a/loc
• Versioned-coordinate: includes type path, TAI, and hash. Example: //g/a/loc/|/plex/<tai>/<hash>

Example

Packet:

🖧: P.EXAMPLE~HASH~EXAMPLE~HASH~EXAMPLE~HASH~EX.H3
Group: a-group
App: some-app
Location: our-collection/item
TAI: 1640995200:123000000
...

Addresses:

• Direct hash: ////P.EXAMPLE~HASH~EXAMPLE~HASH~EXAMPLE~HASH~EX.H3
• Top-coordinate: //a-group/some-app/our-collection/item
• Versioned-coordinate: //a-group/some-app/our-collection/item/|/plex/1640995200:123000000/P.EXAMPLE~HASH~EXAMPLE~HASH~EXAMPLE~HASH~EX.H3

Get resolution

In the tables below, <loc> is the Location header value and does not end with /.

The tip is the latest packet at a path. Tie-break order is highest TAI, then highest hash.

List resolution

repo/
├── hash/<Type>/<hh>/<tail>.H3
├── ref/B/<hh>/<tail>/...
├── ref/P/<hh>/<tail>/...
├── index/<group>/<app>/...
├── detach/<hash>
└── .tmp/

HPPR Basic Commands

© R.A.Sol

Security Model

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

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

Non-stream commands use one request packet and one response packet per exchange. Streaming behavior is command-specific (for example 🖧WATCH, 🖧AUDIT in 050).

Null Packet

The sentinel hash 0.H3 is never computed or verified.

Use 0.H3 for:

• HELLO response
• error responses

Null packets are never stored in repository storage.

🖧: 0.H3
[Header: value]*
Data-Length: <len>

<data>

Header rules follow 010 (format, encoding, control bytes, line length). Differences from Plex:

• Any header name is allowed (no required headers, no ordering rules).
• Header count max is 512.
• Data-Length is the final header before the blank line.
• Data max is 34 MiB (32 MiB payload + 2 MiB envelope overhead).

Session Lifecycle

Each connection starts with HELLO.

The repo creates a session-id and binds it to the connection. Later requests must carry that session-id in Location.

HELLO Request

Client sends a Null packet with App: 🖧HELLO:

🖧: 0.H3
App: 🖧HELLO
Data-Length: 0

HELLO Response

Repo responds with session parameters and capabilities:

🖧: 0.H3
Session-ID: <session-id>
Repo-Name: <repo-name>
Seal-By: <repo-vkey>
[PHC: $argon2id$v=19$m=<m>,t=<t>,p=<p>$]
[Command: 🖧NAME VERSION]*
[Transport: <via>]*
Data-Length: 0

Header meanings:

Sealed HELLO

After session setup, an authenticated 🖧HELLO Seal request returns fresh status and capabilities. The response is a Seal signed by repo-vkey. Session-ID and PHC are omitted.

No ACL check. Any authenticated identity may send 🖧HELLO.

Repo Identity

Repo identity is stored at:

//repo/admin/identity/|

It is a self-signed Seal. Repo-Name in that identity is returned in HELLO.

Authenticated Requests

After HELLO, commands are sent as Seal packets. App values starting with 🖧 are protocol commands.

🖧: S.<hash>.H3
Seal-By: <client-vkey>
Seal-Sig: <signature>
🖧: P.<hash>.H3
Group: <group>
App: 🖧<COMMAND>
Location: <location-with-session>
TAI: <tai>
🖧: B.<hash>.H3
Data-Length: <len>

<args>

Location format depends on auth scheme:

A different signing key requires a new connection and HELLO.

Command Responses

Successful responses are Seal packets signed by the repo verification key.

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

<response-data>

Commands

🖧STORE

🖧STORE payload is a complete packet starting with markline.

It also accepts thin packets:

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

For authenticated App: 🖧STORE, request Data-Length may be up to 34 MiB. This allows 32 MiB packet payload plus up to 2 MiB envelope overhead.

Other authenticated Seal apps remain capped at 32 MiB.

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)
• storing a Blob returns 1 line

Errors

Errors are Null packets. Data starts with one status line:

• ERROR <TYPE> <detail> keeps the connection open
• FATAL <TYPE> <detail> closes the connection

Standard error types:

• NOT_FOUND
• FORBIDDEN
• TOO_LARGE
• INVALID
• INVALID_IDENTITY
• UNAUTHORIZED
• HELLO_REQUIRED
• INTERNAL

Example:

🖧: 0.H3
Data-Length: 21

ERROR NOT_FOUND ring1

scheme+host[:port]

host[:port]

scheme[:port]

unix+<absolute-path>

client_ephemeral_pubkey (33 bytes, SEC1 compressed secp256k1)
client_transport_parameters (variable)

server_ephemeral_pubkey (33 bytes, SEC1 compressed secp256k1)
encrypted_hello_length (2 bytes, big-endian u16)
encrypted_hello (variable, ChaCha20-Poly1305)
server_transport_parameters (variable)

shared_point = ECDH(client_ephemeral_secret, server_ephemeral_pubkey)
shared_bytes = shared_point.x (32 bytes, big-endian)

stream = BLAKE3.derive_key_xof("hppr-🖧/quib/keys", shared_bytes)

stream = BLAKE3.derive_key_xof("hppr-🖧/quib/update", current_packet_key)
next_packet_key = stream[0..32]
next_iv          = stream[32..44]

nonce = IV XOR (0x00000000 || BE64(packet_number))

counter = LE_u32(sample[0..4])
nonce   = sample[4..16]
mask    = ChaCha20(hp_key, counter, nonce, zeroes)[0..5]

stream = BLAKE3.derive_key_xof("hppr-🖧/quib/initial", dst_cid)

tag = BLAKE3.keyed_hash(RETRY_KEY, len(orig_dst_cid) || orig_dst_cid || retry_pseudo_packet)[..16]

8a 3f c1 7b 52 e6 d9 04  ab 1e 73 f0 28 95 dc 46
b3 67 0a 5d e4 89 f1 3c  7e b2 05 6f d8 a1 43 97

mac = BLAKE3.keyed_hash(key, data)

aead_key = BLAKE3.derive_key("hppr-🖧/quib/token-aead", master_key || random_bytes)

output = BLAKE3.derive_key(label, shared_bytes || context)

HPPR Access Control

© R.A.Sol

ACL rules are defined per repository identity.

Each rule targets a coordinate prefix and controls three operations:

• read
• write
• list

Rule evaluation uses longest-prefix match with per-operation inheritance.

Operations

• read: fetch packet data
  • commands: 🖧GET, 🖧HEADERS, 🖧MEMBERS (060)
• write: store or mutate repository state
  • commands: 🖧STORE, 🖧ADD, 🖧DETACH
• list: enumerate or subscribe to coordinate trees
  • commands: 🖧LIST, 🖧WATCH, 🖧TIPS

Rule Format

Rule syntax:

<ops> <coordinate-prefix>

<ops> is exactly three characters:

[r|d|.][w|d|.][l|d|.]

Meaning:

• r, w, l: explicit allow for that operation
• d: explicit deny for that operation
• .: inherit from the next-longest matching rule

Examples:

ACL-Rule: rwl //u/chess/
ACL-Rule: r.l //u/mail/
ACL-Rule: rdl //u/market/
ACL-Rule: .w. //u/market/nl/eindhoven/

Common patterns:

• rwl: full access
• r.l: read and list, inherit write
• ddd: deny all
• rwd: read and write, deny list

Rule Ordering

Rules MUST be stored in canonical sorted order.

Sort bytewise, with custom priority:

• | sorts before /
• / sorts before all other bytes

Equivalent compare mapping:

• | => 0x01
• / => 0x02

Resolution

Given a request coordinate:

1. Find the longest matching rule prefix.
2. For each operation, apply explicit allow or deny when present.
3. For . values, continue to the next-longest matching rule.
4. If no explicit decision is found, deny.

For read and write checks, evaluate against the packet versioned coordinate.

Prefix examples:

Identity Storage

Rules are stored as ACL-Rule Plex headers.

Location depends on identity scheme:

• Ring1 (050):
  • //repo/admin/ring1/<name>/setup/|
• Ring2 (060):
  • //<group>/admin/setup/|/seal/<repo-vkey>

HPPR Ring1 Authentication

© R.A.Sol

Ring1 is the standard repository-auth API. All Ring1 requests are Seals signed by a Ring1 member key.

The key can be derived from a password or set up explicitly.

Request Envelope

Ring1 request form:

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

<args>

Rules:

• Group is repo
• Location carries repo name, ring1 name, and HELLO session
• Seal-By must be a configured member key or derived member key

Keys

ring0 Key

The repo verification key is the oldest packet at:

//repo/admin/ring1/ring0/keys/|/seal

Oldest means lowest (TAI, hash).

Ring1 and Ring2 setup packets must be signed by this repo key.

Ring1 Keys Config

Path:

//repo/admin/ring1/<name>/keys/|/seal/<vkey>

Packet contains Secret-Key: &.<b64a>.H3. 🖧ADD can use these keys.

Setup Config

Path:

//repo/admin/ring1/<name>/setup/|

Signed by ring0.

Headers:

• Ring1-Name
• Ring1-Secret-Token (optional)
• Ring1-Expire (optional)
• Member (repeatable)
• ACL-Rule (repeatable)

Ring1-Name constraints:

• max 128 bytes
• must match path segment
• must not contain / { } |
• must not equal . or ..

Secret Token Derivation

Ring1-Secret-Token format:

<derived-token> <original-secret>

Split on first ASCII space.

• left side: V.<b64a>.H3
• right side: original secret, may contain spaces

Client derives <derived-token> using Argon2id with HELLO PHC. Repo does not recompute Argon2id. Repo uses <derived-token> directly.

Argon2id:

• password: UTF-8 original secret
• salt: first 16 bytes of BLAKE3.derive_key("hppr-🖧/phc-salt", "<ring1>/<repo-vkey>")
• output length: 32 bytes

Then HSB3 key derivation secret is:

<derived-token>/<ring1-name>/<repo-vkey>

Special Ring1 Names

• ring0: full repository access, ACL bypass
• anyone: unauthenticated fallback ACL identity
• guest: signed non-member identity used by Ring2 flow

Pre-ACL Defaults

These apply before ACL-Rule evaluation and are final.

• ddd //repo/admin/ring1/ring0/
• dwd //repo/admin/request/ring1/
• rd. //repo/admin/ring1/
• rd. //repo/admin/identity

Ring1 Commands

Ring1 includes all commands from 030 and adds:

• 🖧HELLO
• 🖧ADD
• 🖧DETACH
• 🖧TIPS
• 🖧WATCH
• 🖧AUDIT

🖧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
• App: index
• Location: root
• TAI: now

References:

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

🖧DETACH

Payload is one hash. Removes packet from coordinate index only. Stored packet remains in hash storage. ring0 only.

🖧TIPS

Returns LF-separated versioned coordinates for tip packets.

🖧WATCH

Returns a stream of + and - lines for matching coordinate prefix changes. Events are filtered by list permission.

🖧AUDIT

Streams audit log lines. ring0 only.

Errors

Common Ring1 failures:

• HELLO_REQUIRED
• UNAUTHORIZED invalid signature
• UNAUTHORIZED not a member
• NOT_FOUND ring1
• NOT_FOUND inner packet
• INVALID config
• INVALID session
• UNAUTHORIZED ring1

Security

Ring1 expects encrypted transport for confidentiality. Replay resistance uses HELLO-bound session IDs in request Location.

HPPR Ring2 Authentication

© R.A.Sol

Ring2 is group-based authentication. Signer authorization is based on membership in the target group.

Request Envelope

Ring2 request form:

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

<args>

Rules:

• Group is the target group, not repo
• Location is <repo>/<session-id>
• Seal-By must resolve to group membership
• non-members evaluate under Ring1 guest ACL fallback

Group Setup

Setup path:

//<group>/admin/setup/|/seal/<repo-vkey>

Setup packet is signed by repo-vkey.

Headers:

• Ring2-Name (must equal <group>)
• Ring2-Expire (optional)
• ACL-Rule (optional, repeatable)

Each ACL-Rule coordinate must start with //<group>/.

Pre-ACL Default

Before ACL rules, apply:

• r.. //<group>/admin/members/|

This grants read access to membership config.

Membership Config

Membership packets live at:

//<group>/admin/members/|/seal/<vkey>

Multiple packets may exist under different signers and versions.

Supported headers:

• Member: <vkey> [<tags>...]
• Member-Delegate: [<group>]|[<vkey>[/<tai>/<hash>]] [<mods>...]

Member

Adds one member key plus optional tags.

Member-Delegate

Delegates membership from another config source. Pipe separator | is required.

Defaults:

• omitted group means current group
• omitted vkey means signer of current packet

Pinned form:

• <vkey>/<tai>/<hash> pins to exact member packet version

Modifier:

• dynamic follows unpinned delegates

Tag modifiers:

• *: inherit all tags
• +tag: inherit tag if present
• tag: grant tag
• !tag: deny tag

Traversal is depth-first with max depth 8.

🖧MEMBERS

Returns expanded member list with tags.

Payload is a // URC.

Shorthand:

• //<group> expands to //<group>/admin/members/|/seal/<repo-vkey>

Response:

• LF-separated lines: <vkey> [<tags>...]
• sorted by vkey

Errors

Common Ring2 failures:

• HELLO_REQUIRED
• UNAUTHORIZED invalid signature
• UNAUTHORIZED not a member
• NOT_FOUND ring2 setup
• INVALID config
• INVALID session
• UNAUTHORIZED ring2

HPPR Conventions

© R.A.Sol

This spec defines bootstrap and onboarding conventions.

Bootstrap Requirements

A new repository needs four initial items.

1. ring0 keys
   • path: //repo/admin/ring1/ring0/keys/|/seal/<vkey>
   • self-signed Seal with Secret-Key
   • oldest key becomes repo-vkey
2. ring0 setup
   • path: //repo/admin/ring1/ring0/setup/|/seal/<repo-vkey>
3. anyone setup
   • path: //repo/admin/ring1/anyone/setup/|/seal/<repo-vkey>
4. guest setup
   • path: //repo/admin/ring1/guest/setup/|/seal/<repo-vkey>

ring0 Initial Token

Initial ring0 member derives from token init:

secret = "init/ring0/<repo-vkey>"

signing_key = derive_key_from_secret(secret)

Replace bootstrap setup immediately with a secure token.

Default anyone Setup

Ring1-Name: anyone
ACL-Rule: .w. //repo/admin/request/ring1/
ACL-Rule: r.l //repo/admin/route/
ACL-Rule: r.l //u/

Default guest Setup

Ring1-Name: guest

Joining a Repository

Standard Ring1 join flow:

1. user writes request to: //repo/admin/request/ring1/<name>/setup/|
2. user watches reply path: //repo/admin/request/ring1/<name>/reply/|
3. admin approves or denies in reply packet
4. if approved, admin creates ring1 setup packet
5. user derives key and reconnects

Provisional Access

An anyone request gets temporary read/list access to matching reply path:

//repo/admin/request/ring1/<name>/reply/|

<name> must match first segment from request Location.

Joining a Group

Ring2 join flow:

• request path: //<group>/admin/request/member/|/seal/<requester-key>
• reply path: //<group>/admin/request/member/<requester-key>/reply/|

Recommended guest ACLs:

ACL-Rule: .w. //<group>/admin/request/member/|/seal/
ACL-Rule: r.l //<group>/admin/request/member/

Request headers:

• Request-Tags (optional)

Reply headers:

• Request-Status: approved|denied|pending
• +Link: request <hash>

Group Deployment Pointer Convention

Canonical app content should live under:

//u/apps/<publisher>/<app>/...

Each group publishes its deployment pointer at:

//<group>/admin/deploy/<app>/|

Required headers:

• Deploy-App: <app>
• Deploy-Root: //<...>
• Deploy-Signer: V.<...>.H3

Runtime intent:

• clients resolve //<group>/<app>/... through the deploy pointer
• clients then read content from Deploy-Root

Group forks are supported by pointing Deploy-Root to a group-owned subtree instead of the canonical //u/apps/... tree.

+Link Header

Generic form:

+Link: <tag> <hash>

Common tags:

• request: this packet replies to that request
• supersedes: this packet replaces older version

Typed links are headers named [Type]+Link. Tools should scan header names containing +Link.

Hash links form a DAG. Cycles are impossible because packet hash includes all header bytes.

Chunked Content Convention

Large content can be split into chunk blobs with a manifest packet.

Manifest detection:

• has one or more Chunk+Link headers
• has Data-Length: 0

Syntax:

Chunk+Link: <start>..<end> <T>.<hash>.H3

• range is half-open: start inclusive, end exclusive
• T=B: raw blob chunk
• T=P: nested chunk manifest

Required header:

• Content-Total-Length: <n>

Optional headers:

• Content-Type
• Content-Hash-Full: B.<hash>.H3

Validation:

• chunk ranges contiguous
• no overlap
• total span exactly 0..<Content-Total-Length>

Nested manifests use 0-relative ranges in each sub-manifest. Depth limit is 8.

Default chunk size is 32 MiB. Smaller chunks improve random access and increase overhead.

Ring0-Proxy Convention

Ring1 may request a ring0-mediated action.

Request path:

//repo/admin/ring1/<ring1-name>/🖧<COMMAND>/|

Reply path:

//repo/admin/ring1/<ring1-name>/🖧<COMMAND>/reply/|

Supported commands:

• 🖧LIST
• 🖧HEADERS
• 🖧ADD

🖧GET is excluded. Use 🖧HEADERS to obtain hash, then fetch blob by hash.

HPPR Replication

© R.A.Sol

Repository replication uses command 🖧EXCHANGE. It synchronizes packets while preserving ACL decisions.

🖧EXCHANGE

🖧EXCHANGE has three phases:

1. announce
2. transfer
3. finalize

Phase 1: Announce

Requester sends up to 1024 LF-separated lines:

NEED <versioned-coord>
HAVE <versioned-coord>

Responder returns FIN or PENDING followed by status lines:

SEND <coord>
DENY <coord>
RECV <coord>
HAVE <coord>

Status meanings:

• SEND: responder will send this packet
• DENY: denied by ACL or policy
• RECV: responder wants this packet from requester
• HAVE: responder already has this packet

Phase 2: Transfer

Both peers stream raw packets concurrently in both directions.

Implementations MUST perform bidirectional I/O concurrently. Unidirectional blocking can deadlock the exchange.

Packet boundaries are parsed using Data-Length.

Phase 3: Finalize

Responder reports final per-coordinate results:

FIN
OK <coord>
FAIL <coord> <type> <msg>

ACL Rules in Phase 1

For NEED <coord>:

1. check read
2. if readable and exists: SEND
3. else: DENY

For HAVE <coord>:

1. check read
2. if denied: DENY
3. if allowed and exists: HAVE
4. if missing, check write
5. if writable: RECV
6. else: DENY

Blob-Addressed 🖧EXCHANGE

🖧EXCHANGE also accepts blob hash addressing:

NEED ////B.<hash>.H3
HAVE ////B.<hash>.H3

Rules:

• only B. hashes are valid
• P. and S. in blob-addressed mode are FATAL invalid requests
• no ACL checks in this mode
• any authenticated session may request blob hash sync

Decision rules:

• NEED: blob exists => SEND, else DENY
• HAVE: blob exists => HAVE, else RECV

Transfer still uses full raw blob packets.

🖧STREAM_IN

🖧STREAM_IN ingests live trailer-format Seal segments.

Request:

• App: 🖧STREAM_IN
• data: <coordinate-prefix>

Response:

• sealed OK

After OK, connection enters relay mode and accepts trailer segments.

Per segment:

1. relay bytes to matching 🖧STREAM_OUT subscribers
2. detect segment close marker
3. verify hash and signature
4. store packet
5. emit 🖧WATCH event

ACL: write checked per segment at store time.

Disconnect behavior:

• publisher disconnect ends stream
• no explicit end marker required
• partial in-flight segment is discarded
• subscriber sockets are closed

No FATAL is injected into relay stream. Subscribers detect truncation via trailer parsing.

Size rule:

• each segment must respect 32 MiB blob limit

Continuity recommendation:

• include Previous-Segment: <hash> after first segment

🖧STREAM_OUT

🖧STREAM_OUT subscribes to live trailer bytes by prefix.

Request:

• App: 🖧STREAM_OUT
• data: <coordinate-prefix>

Behavior:

• enters dedicated relay mode immediately
• no OK response packet
• when no active publisher exists for the prefix, subscriber waits for one
• wait uses a fixed server timeout
• on wait timeout, repo writes FATAL NOT_FOUND wait timeout and closes
• forwards bytes from matching active publishers

Late joiners receive bytes buffered from current in-flight segment and then continue live.

ACL: read checked at subscription time.

On publisher disconnect, repo closes subscriber sockets. Mid-segment disconnect yields partial trailer data followed by EOF.

Completed segments remain available via 🖧GET and 🖧EXCHANGE.

Relay Chaining

A downstream repo can relay a live stream by:

1. subscribing upstream with 🖧STREAM_OUT
2. publishing downstream with 🖧STREAM_IN