HPPR Packet Format

Tags: packet, stored-format

© R.A.Sol

Every stored packet starts with a markline:

🖧: <hash-text>

<hash-text> is the packet type, BLAKE3-256 digest encoded in B64A, and .H3 format suffix. It identifies the canonical payload after the first LF.

HPPR stored 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.¹ In this spec, digest means the raw 32 BLAKE3 bytes and hash text means the textual T.<b64a>.H3 form.
• 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>
API: <api>
Key: <key>
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, API, Key, 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 seconds use International Atomic Time. Timestamp generation applies the TAI-UTC offset in force for the generation instant.

Header Validation

General:

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

Group:

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

API:

• non-empty; at least one segment is required
• case-sensitive
• 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 API value max 1014 bytes

Key:

• 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 Key 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
• API
• Key
• 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>
API: <api>
Key: <key>
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 secrets use &.<b64a>.H3.
• Seal-Sig is an 86-char B64A text signature.
• Signature algorithm is HSB3 over the Plex digest.

Packet-shaped Command Envelopes

Wire protocols may define packet-shaped command envelopes that are not stored packets. The generic Null command packet uses markline 🖧: 0.H3 and is defined in 030-COMMAND-MESSAGES.md. Null packets are command envelopes and response envelopes only. They are not Blob, Plex, or Seal packets and are never stored in repository storage.

Limits

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

Parsing

1. Read markline and verify the type prefix in the hash text.
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>/<api>//<key>/|/seal/<verification-key>
<escaped data>
⋯🖧: B.<blob-hash>.H3
Group: <group>
API: <api>
Key: <key>
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.

Digest 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.