From 687e872622aa9095bfc8be3445406ee6450f2f08 Mon Sep 17 00:00:00 2001 From: matthew-pilot Date: Thu, 18 Jun 2026 11:19:32 +0000 Subject: [PATCH] =?UTF-8?q?fix(docs):=20add=20outer=20frame=20encapsulatio?= =?UTF-8?q?n=20preamble=20to=20SPEC.md=20=C2=A73=20(PILOT-419)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a preamble to §3 (Packet Format) explaining that all wire-format frames are encapsulated in a tunnel envelope identified by 4-byte magic bytes. Documents the four frame types (PILT, PILS, PILK, PILA) with their magic byte values and clarifies that §3 describes the inner header for PILT frames while §4 covers the other frame type layouts. A first-time reader encountering §3 would not know the header is tunnel-encapsulated — this preamble addresses that gap. Closes PILOT-419 --- SPEC.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/SPEC.md b/SPEC.md index 8b9610f..e0d0cbe 100644 --- a/SPEC.md +++ b/SPEC.md @@ -70,6 +70,21 @@ Socket address includes a port: `1:0001.F291.0004:1000` ## 3. Packet Format +All Pilot Protocol wire-format frames are encapsulated in a tunnel envelope +identified by a 4-byte magic byte prefix. Four frame types are defined: + +| Magic | Frame Type | +|-------------------------|--------------------------------------| +| `PILT` (0x50494C54) | Unencrypted tunnel frame (plaintext) | +| `PILS` (0x50494C53) | AES-256-GCM encrypted tunnel frame | +| `PILK` (0x50494C4B) | X25519 key exchange frame | +| `PILA` (0x50494C41) | Ed25519 + X25519 authenticated key exchange | + +The frame types are detailed in §4 below. This section (§3) describes the +inner 34-byte header shared by PILT (plaintext) frames. Encrypted (PILS), +key-exchange (PILK), and authenticated (PILA) frames use different header +layouts documented in §4. + ### 3.1 Header Layout (34 bytes) ```