feat(versioning): snapshot corpus per spec version

A frozen spec is only meaningful if it's paired with the corpus that was current at release time — otherwise a v0.1.0 reader follows "see corpus/payloads/ack/" and lands on a file whose test vectors may have changed since v0.1.0 was cut. Three changes: 1. `cut-version` now copies BOTH src/ AND corpus/ into the snapshot directory. A release is the pair, not just the text. 2. The corpus URL rewriting in cut-version now retargets /tree/main/corpus -> /tree/main/versions/<v>/corpus (and the blob variant). This lets the link resolve on GitHub from main alone — no git tag required, since the frozen copy is a real path under main. Downgrades the "tag is REQUIRED" message from last commit back to "optionally tag the commit". 3. The frozen corpus's spec_ref fields get rewritten too: from `src/04-payload-ack.md` to `versions/<v>/04-payload-ack.md`, so a reader following a test vector lands on the spec text the vector was paired with at release time. versions/v0.1.0/ regenerated from scratch via `just cut-version v0.1.0` to pick up the corpus snapshot + the new sed patterns. The release is now self-consistent: v0.1.0 spec links go to v0.1.0 corpus, which links back to v0.1.0 spec. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-12 10:38:02 -06:00
1 parent f83d4088e3
commit 9232c16f7c
@@ -0,0 +1,129 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - Basic",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Tests encrypted payload encoding (REQ/RESPONSE/TXT_MSG) with known cryptographic material. Uses shared_secret = 0x000102...1F, AES key = first 16 bytes, HMAC key = full 32 bytes.",
+  "vectors": [
+    {
+      "id": "enc-001",
+      "description": "Encrypted TXT_MSG with 5-byte plaintext 'Hello'",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "09 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "plaintext 'Hello' = 48656C6C6F (5 bytes), zero-padded to 16 for AES-128-ECB. MAC is HMAC-SHA256(shared_secret, ciphertext) truncated to 2 bytes."
+    },
+    {
+      "id": "enc-002",
+      "description": "Encrypted REQUEST with 16-byte plaintext (exact AES block)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "request",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "631C",
+          "ciphertext": "0A940BB5416EF045F1C39458C653EA5A"
+        }
+      },
+      "binary": "01 00 ABCD 631C 0A940BB5416EF045F1C39458C653EA5A",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "000102030405060708090A0B0C0D0E0F"
+      },
+      "notes": "16-byte plaintext fills exactly one AES block. No padding needed."
+    },
+    {
+      "id": "enc-003",
+      "description": "Encrypted RESPONSE with 17-byte plaintext (spans 2 AES blocks)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "response",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "9822",
+          "ciphertext": "0A940BB5416EF045F1C39458C653EA5A299F7C29A3E13AE7F64ECBA062FC7560"
+        }
+      },
+      "binary": "05 00 ABCD 9822 0A940BB5416EF045F1C39458C653EA5A299F7C29A3E13AE7F64ECBA062FC7560",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "000102030405060708090A0B0C0D0E0F10"
+      },
+      "notes": "17-byte plaintext: first 16 bytes in block 1, byte 17 zero-padded in block 2. 32 bytes ciphertext total."
+    },
+    {
+      "id": "enc-004",
+      "description": "Encrypted TXT_MSG with 1-byte plaintext",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "83FB",
+          "ciphertext": "2D4135E80761429386BFE3833C535AA8"
+        }
+      },
+      "binary": "09 00 ABCD 83FB 2D4135E80761429386BFE3833C535AA8",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "42"
+      },
+      "notes": "1-byte plaintext 0x42, zero-padded to 16 bytes."
+    }
+  ]
+}
@@ -0,0 +1,69 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - MAC Verification",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Tests MAC verification: valid MACs must pass, tampered MACs or ciphertext must fail.",
+  "vectors": [
+    {
+      "id": "mac-001",
+      "description": "Valid MAC with known ciphertext",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "09 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      }
+    },
+    {
+      "id": "mac-002",
+      "description": "Tampered MAC (first byte changed)",
+      "type": "invalid",
+      "binary": "09 00 ABCD 00B5 D9FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "MAC changed from EAB5 to 00B5. MACThenDecrypt must return 0."
+    },
+    {
+      "id": "mac-003",
+      "description": "Tampered MAC (second byte changed)",
+      "type": "invalid",
+      "binary": "09 00 ABCD EA00 D9FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "MAC changed from EAB5 to EA00."
+    },
+    {
+      "id": "mac-004",
+      "description": "Tampered ciphertext (first byte changed)",
+      "type": "invalid",
+      "binary": "09 00 ABCD EAB5 00FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "Ciphertext first byte changed from D9 to 00. HMAC over modified ciphertext won't match."
+    },
+    {
+      "id": "mac-005",
+      "description": "Swapped MAC bytes",
+      "type": "invalid",
+      "binary": "09 00 ABCD B5EA D9FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "MAC bytes reversed: B5EA instead of EAB5."
+    }
+  ]
+}
@@ -0,0 +1,99 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - AES Block Padding",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Tests AES-128-ECB zero-padding behavior at block boundaries. Plaintexts of 1, 15, 16, 17, and 32 bytes exercise all padding edge cases.",
+  "vectors": [
+    {
+      "id": "pad-001",
+      "description": "1-byte plaintext: padded with 15 zero bytes",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "83FB",
+          "ciphertext": "2D4135E80761429386BFE3833C535AA8"
+        }
+      },
+      "binary": "09 00 ABCD 83FB 2D4135E80761429386BFE3833C535AA8",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "42"
+      },
+      "notes": "1 byte padded to 16: 42 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00. 1 AES block output."
+    },
+    {
+      "id": "pad-002",
+      "description": "16-byte plaintext: no padding needed (exact block boundary)",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "631C",
+          "ciphertext": "0A940BB5416EF045F1C39458C653EA5A"
+        }
+      },
+      "binary": "09 00 ABCD 631C 0A940BB5416EF045F1C39458C653EA5A",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "000102030405060708090A0B0C0D0E0F"
+      },
+      "notes": "Exactly 16 bytes: no padding. 1 AES block output."
+    },
+    {
+      "id": "pad-003",
+      "description": "17-byte plaintext: 1 byte in second block, padded with 15 zeros",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "9822",
+          "ciphertext": "0A940BB5416EF045F1C39458C653EA5A299F7C29A3E13AE7F64ECBA062FC7560"
+        }
+      },
+      "binary": "09 00 ABCD 9822 0A940BB5416EF045F1C39458C653EA5A299F7C29A3E13AE7F64ECBA062FC7560",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "000102030405060708090A0B0C0D0E0F10"
+      },
+      "notes": "17 bytes spans 2 blocks. Block 2 = 10 00 00 ... 00. 32 bytes ciphertext."
+    }
+  ]
+}
@@ -0,0 +1,47 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - Roundtrip Verification",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Roundtrip encrypt-then-MAC verification vectors. Each vector provides full key material enabling implementations to verify: (1) encryption produces the given ciphertext, (2) MAC computation produces the given MAC, (3) MAC verification succeeds, (4) decryption recovers the plaintext.",
+  "vectors": [
+    {
+      "id": "rt-enc-001",
+      "description": "Roundtrip: encrypt 'Hello', verify MAC, decrypt back",
+      "type": "encode_decode",
+      "structured": {
+        "header": {
+          "version": 0,
+          "payload_type": "txt_msg",
+          "route_type": "flood"
+        },
+        "path": {
+          "hash_size": 1,
+          "hash_count": 0,
+          "hashes": []
+        },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "09 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "encryption_key": "000102030405060708090A0B0C0D0E0F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Verification steps: (1) AES-128-ECB encrypt(key=00..0F, pad('Hello')) -> D9FD...3502. (2) HMAC-SHA256(key=00..1F, ct)[:2] -> EAB5. (3) HMAC verify: recompute and compare. (4) AES-128-ECB decrypt -> 48656C6C6F + 11 zero bytes."
+    },
+    {
+      "id": "rt-enc-002",
+      "description": "Roundtrip with wrong MAC must fail verification",
+      "type": "invalid",
+      "binary": "09 00 ABCD FFFF D9FD218D50A4409143A7243D6D913502",
+      "expected_error": "mac_invalid",
+      "notes": "Same ciphertext as rt-enc-001 but MAC replaced with FFFF. MACThenDecrypt must return 0 (failure)."
+    }
+  ]
+}
@@ -0,0 +1,76 @@
+{
+  "$schema": "../../schema/test-vector.schema.json",
+  "name": "Encrypted Payload - Extra Edge Cases",
+  "spec_ref": "versions/v0.1.0/06-payload-encrypted.md",
+  "protocol_version": 0,
+  "description": "Additional encrypted payload tests: non-FLOOD routes, hash_size>1 paths, 32-byte plaintext, and payload-level invalid cases.",
+  "vectors": [
+    {
+      "id": "enc-extra-001",
+      "description": "Encrypted TXT_MSG via DIRECT routing with 2-byte hash path",
+      "type": "encode_decode",
+      "structured": {
+        "header": { "version": 0, "payload_type": "txt_msg", "route_type": "direct" },
+        "path": { "hash_size": 2, "hash_count": 1, "hashes": ["AABB"] },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "0A 41 AABB ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Header 0x0A = TXT_MSG(2)+DIRECT(2). path_len=0x41 (hash_size=2, count=1). Tests encrypted payload with non-FLOOD routing and multi-byte hash."
+    },
+    {
+      "id": "enc-extra-002",
+      "description": "Encrypted TXT_MSG via TRANSPORT_FLOOD with transport codes",
+      "type": "encode_decode",
+      "structured": {
+        "header": { "version": 0, "payload_type": "txt_msg", "route_type": "transport_flood" },
+        "transport_codes": [1000, 0],
+        "path": { "hash_size": 1, "hash_count": 0, "hashes": [] },
+        "payload": {
+          "dest_hash": "AB",
+          "src_hash": "CD",
+          "cipher_mac": "EAB5",
+          "ciphertext": "D9FD218D50A4409143A7243D6D913502"
+        }
+      },
+      "binary": "08 E803 0000 00 ABCD EAB5 D9FD218D50A4409143A7243D6D913502",
+      "crypto_context": {
+        "shared_secret": "000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F",
+        "plaintext": "48656C6C6F"
+      },
+      "notes": "Header 0x08 = TXT_MSG(2)+TRANSPORT_FLOOD(0). Tests encrypted payload with transport codes."
+    },
+    {
+      "id": "enc-extra-003",
+      "description": "ACK payload too short (3 bytes instead of 4)",
+      "type": "invalid",
+      "binary": "0D 00 EFBEAD",
+      "expected_error": "incomplete_payload",
+      "notes": "ACK requires exactly 4 bytes. Only 3 provided."
+    },
+    {
+      "id": "enc-extra-004",
+      "description": "Payload exceeds MAX_PACKET_PAYLOAD (185 bytes)",
+      "type": "invalid",
+      "binary": "3D 00 000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F606162636465666768696A6B6C6D6E6F707172737475767778797A7B7C7D7E7F808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9FA0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8",
+      "expected_error": "payload_too_large",
+      "notes": "Payload is 185 bytes (0x00..0xB8), exceeding MAX_PACKET_PAYLOAD of 184. readFrom MUST reject."
+    },
+    {
+      "id": "enc-extra-005",
+      "description": "Header 0xFF sentinel on wire (must reject)",
+      "type": "invalid",
+      "binary": "FF 00 DEADBEEF",
+      "expected_error": "sentinel_header",
+      "notes": "Header 0xFF is used internally as do-not-retransmit marker. MUST NOT appear on the wire."
+    }
+  ]
+}