This is an internal proposal, filed by the same team that authored the specification. It does not move the count of proposals from outside this company, which remains zero on the governance page. It exists because the process should be demonstrated by its authors before anyone else is asked to use it.
Abstract
Abstract
The hu_ssh fixed header places three multi-byte integers at offsets that are not multiples of their width. A parser cannot therefore read them with an aligned load, which contradicts the specification’s stated goal of zero-copy, zero-allocation deserialisation. This proposal reorders the header and adds three bytes of explicit padding so that every scalar lands on a natural boundary, taking the fixed header from 53 to 56 bytes.
Motivation
Motivation
The specification claims the header is “sized so a reader can validate and dispatch without allocating.” That claim is only half true today.
Current layout — 53 bytes, 3 misaligned
| Offset | Field | Bytes | Align | |
|---|---|---|---|---|
| 0 | MAGIC | 2 | 1 | |
| 2 | VERSION | 1 | 1 | |
| 3 | FLAGS | 1 | 1 | |
| 4 | FRAME TYPE | 1 | 1 | |
| 5 | SEQUENCE NUMBER | 8 | 8 | ✕ 5 % 8 = 5 |
| 13 | PAYLOAD LENGTH | 4 | 4 | ✕ 13 % 4 = 1 |
| 17 | SIGNATURE LENGTH | 2 | 2 | ✕ 17 % 2 = 1 |
| 19 | RESERVED | 2 | 1 | |
| 21 | DEVICE ID | 32 | 1 |
SEQUENCE NUMBER is a u64 beginning at offset 5. PAYLOAD LENGTH is a u32 at 13. SIGNATURE LENGTH is a u16 at 17. None can be read by casting a pointer into the receive buffer. An implementation must either assemble each integer byte by byte, or perform an unaligned load — which is merely slow on x86-64 and aarch64, and a fault or a miscompile on stricter targets.
This was not found by reading the specification. It was found by drawing the header as a 32-bit packet grid, where the straddling is immediately visible and in prose it is not. That is the same mechanism that caught the header being declared 50 bytes when its fields summed to 53 — a projection that derives from the data rather than restating it.
Specification
Specification
Widen RESERVED from 2 bytes to 3 and move it ahead of SEQUENCE NUMBER; add a 2-byte PAD after SIGNATURE LENGTH. Both must be zero on send and ignored on receive.
Proposed layout — 56 bytes, all scalars aligned
| Offset | Field | Bytes | Align | |
|---|---|---|---|---|
| 0 | MAGIC | 2 | 1 | |
| 2 | VERSION | 1 | 1 | |
| 3 | FLAGS | 1 | 1 | |
| 4 | FRAME TYPE | 1 | 1 | |
| 5 | RESERVED | 3 | 1 | |
| 8 | SEQUENCE NUMBER | 8 | 8 | ✓ |
| 16 | PAYLOAD LENGTH | 4 | 4 | ✓ |
| 20 | SIGNATURE LENGTH | 2 | 2 | ✓ |
| 22 | PAD | 2 | 1 | |
| 24 | DEVICE ID | 32 | 1 |
Field widths, semantics, byte order and the magic value are unchanged. Only offsets move. The header grows by 3 bytes, or 5.7%, and becomes a multiple of eight — so a following payload also starts aligned.
Rationale
Rationale
Considered and rejected: leave it.The two architectures we target tolerate unaligned loads. But a wire format is supposed to outlive its first two targets, and “works on the hardware we happen to own” is how a portability bug becomes permanent.
Considered and rejected: drop the claim. Deleting the zero-copy sentence would make the specification honest at no cost in bytes. Rejected because the claim is worth keeping and cheap to earn — three bytes on a header that already carries a 32-byte fingerprint.
Considered and rejected: shrink instead. Moving SEQUENCE NUMBER to u32 would align it at 52 bytes. Rejected: the sequence number is replay protection, and a 32-bit counter on a long-lived link is a wrap we would have to handle rather than a size we get to save.
Backward compatibility
Backward compatibility
Breaking. Every offset after byte 4 moves. There is no deployed implementation to break — the specification states plainly that none conforms yet — which is precisely why this should land now rather than after one exists. If it is accepted after an implementation ships, it falls under the 365-day removal window and requires a version bump rather than a silent change.
Consent implications
Consent implications
None. This proposal moves bytes within a transport header. It does not add a field, does not change what a frame can carry, and does not alter what any counterparty can learn about a person. No scope, tier, purpose or receipt behaviour is affected.
That answer is short, and it is written down anyway, because the section is mandatory on every HEP including ones where the honest answer is “nothing.” The failure this guards against is not a proposal that lies about its consent impact — it is one where nobody thought to ask.
Security implications
Security implications
Marginally positive, for an unglamorous reason. Byte-by-byte assembly of length fields is where hand-written parsers get integer handling wrong; an aligned read is one fewer place to make that mistake. The widened RESERVED field must be validated as zero on receive, or it becomes a covert channel — that requirement is normative, not advisory.
No change to the threat model. The three limits named in the specification still hold: a compromised owner device signs valid frames, revocation cannot reach a frame already in flight, and nothing here prevents regretted consent.
Reference implementation
Reference implementation
Prototype written.The proposed layout is executable: a parser and encoder for the 56-byte aligned header live beside the published grammar’s reference parser in this repository (src/lib/hussh-wire/hep0001.ts), with tests that measure the alignment claims from the layout itself rather than asserting them, prove RESERVED and PAD are validated as zero on receive, and show a version-1 frame is refused rather than misread at the moved offsets. The published grammar is untouched; the prototype rides version 2, as this proposal’s backward-compatibility section requires. What remains before this HEP can leave draft: a sponsor, and a conformance scenario before final.
🤫