From 0a5647b3e81c402dd68939971a3858ece0100df7 Mon Sep 17 00:00:00 2001 From: ecgang Date: Sat, 25 Jul 2026 14:47:50 -0700 Subject: [PATCH 1/7] Add golden test vectors for the courier wire format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The courier layer is only implementable from the Swift source today, and three of the ways a second client gets it wrong fail silently — it builds, connects, and delivers nothing, with no error at either end: - `expiry` is milliseconds. Seconds makes every envelope read as long expired, so it is dropped at deposit with nothing logged. - The signature does not cover the wire bytes. It covers a re-encoding with ttl zeroed, isRSR cleared and the signature omitted, which is then PKCS#7 padded — a spray receipt is 46 bytes unsigned and unpadded, but 256 bytes signed. Signing the 46 produces a signature that never verifies. - The signing key is Ed25519. CryptoKit spells it Curve25519.Signing, so reaching for a "Curve25519" primitive elsewhere yields X25519 key agreement. Prose cannot defend against that class of bug; a fixture can. These vectors pin the envelope TLV, the copies clamp, recipient-tag derivation, the ciphertext hash, and the padded signing pre-image, and they are asserted from the implementation so they cannot drift without a test failing. Signature bytes are deliberately not pinned: CryptoKit's Ed25519 signing is randomized rather than the deterministic RFC 8032 construction, so two signatures over identical input differ and both verify. A second implementation will not reproduce these bytes and does not need to — the pre-image is what must match. docs/courier-test-vectors.json carries the same values for implementers who are not running Swift. Co-Authored-By: Claude Opus 5 (1M context) --- docs/courier-test-vectors.json | 141 +++++++++++++++ .../CourierVectorTests.swift | 162 ++++++++++++++++++ 2 files changed, 303 insertions(+) create mode 100644 docs/courier-test-vectors.json create mode 100644 localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift diff --git a/docs/courier-test-vectors.json b/docs/courier-test-vectors.json new file mode 100644 index 00000000..8981bcbf --- /dev/null +++ b/docs/courier-test-vectors.json @@ -0,0 +1,141 @@ +{ + "_comment": [ + "Golden vectors for the bitchat courier wire format. Generated from the iOS", + "implementation and asserted by CourierVectorTests in the BitFoundation test", + "target, so these cannot drift from the code without a test failing.", + "All hex is lowercase. All multi-byte integers are big-endian.", + "", + "These exist because three courier encoding mistakes fail SILENTLY — the", + "client builds, connects, and delivers nothing, with no error at either end:", + " 1. treating `expiry` as seconds when it is milliseconds", + " 2. signing the wire bytes instead of the padded, ttl-zeroed pre-image", + " 3. reaching for X25519 key agreement because CryptoKit spells Ed25519", + " as `Curve25519.Signing`" + ], + + "inputs": { + "_comment": "Synthetic. Not derived from any real key.", + "recipientTag": "000102030405060708090a0b0c0d0e0f", + "noiseStaticKey": "a0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebf", + "ciphertextUTF8": "courier-vector-ciphertext-0001", + "ciphertext": "636f75726965722d766563746f722d636970686572746578742d30303031", + "expiryMillis": 1800000000000, + "epochDay": 20833, + "senderID": "1122334455667788", + "recipientID": "99aabbccddeeff00", + "timestampMillis": 1750000000000, + "signingSeed": "4242424242424242424242424242424242424242424242424242424242424242" + }, + + "envelopeTLV": { + "_comment": [ + "TLV records are type(1) length(2, big-endian) value(length).", + "0x01 recipientTag(16) 0x02 expiry(8) 0x03 ciphertext 0x04 copies(1) 0x05 prekeyID(4).", + "Lengths are checked exactly, not as minimums. Unknown types are skipped", + "using the length field.", + "NOTE the 0x02 value below is 000001a3185c5000 = 1800000000000 MILLISECONDS.", + "Emitting seconds yields a value ~1000x too small, so every envelope reads", + "as long expired and is dropped at deposit with nothing logged." + ], + "copies": 4, + "prekeyID": 287454020, + "encoded": "010010000102030405060708090a0b0c0d0e0f020008000001a3185c500003001e636f75726965722d766563746f722d636970686572746578742d303030310400010405000411223344", + "encodedLength": 74 + }, + + "copiesClamping": { + "_comment": [ + "`copies` is clamped into 1...maxCopies by the initializer, never rejected.", + "An implementation that rejects out-of-range values will drop envelopes", + "this one accepts." + ], + "maxCopies": 8, + "cases": [ + { "requested": 0, "stored": 1 }, + { "requested": 4, "stored": 4 }, + { "requested": 200, "stored": 8 } + ] + }, + + "recipientTagDerivation": { + "_comment": [ + "HMAC-SHA256(key = recipient noise static key,", + " message = \"bitchat-courier-tag-v1\" || BE32(epochDay))", + "truncated to the first 16 bytes. The label is ASCII with no terminator.", + "epochDay = floor(unixSeconds / 86400).", + "A matcher computes tags for the previous, current and next epoch day and", + "accepts any of the three, so mail crossing UTC midnight still resolves." + ], + "label": "bitchat-courier-tag-v1", + "epochDay": 20833, + "expected": "ad8514c90ca1fa6bf44e38c8a6252482" + }, + + "ciphertextHash": { + "_comment": "SHA-256 of the ciphertext, truncated to 16 bytes. This is the envelope identity a spray receipt carries.", + "expected": "bb85dcc4d8b17377c61817992df95826" + }, + + "packetSigning": { + "_comment": [ + "THE trap. The signature does NOT cover the bytes as they appear on the", + "wire. It covers a re-encoding in which ttl is set to 0, the isRSR flag is", + "cleared, the signature is omitted (so the hasSignature flag bit 0x02 is", + "CLEAR in the signed bytes although SET on the wire) — and the result is", + "then PKCS#7-padded.", + "", + "Padding target is the smallest of [256, 512, 1024, 2048] that fits", + "size + 16, applied only when the shortfall is 1...255, every pad byte", + "equal to the shortfall. Here: 46 + 16 = 62 <= 256, so target 256,", + "shortfall 210 = 0xd2.", + "", + "Signing the 46 unpadded bytes produces a signature that never verifies,", + "and nothing in any log points at the cause." + ], + "packet": { + "version": 1, + "type": "0x2a", + "ttlOnWire": 7, + "payload": "bb85dcc4d8b17377c61817992df95826" + }, + "unsignedUnpaddedLength": 46, + "unsignedUnpadded": "012a07000001977420dc00010010112233445566778899aabbccddeeff00bb85dcc4d8b17377c61817992df95826", + "signingPreimageLength": 256, + "signingPreimagePadByte": "0xd2", + "signingPreimagePadCount": 210, + "signingPreimage": "012a00000001977420dc00010010112233445566778899aabbccddeeff00bb85dcc4d8b17377c61817992df95826d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2", + "signedWireLength": 110, + "flags": { + "_comment": [ + "Flag bits: hasRecipient 0x01, hasSignature 0x02, isCompressed 0x04,", + "hasRoute 0x08, isRSR 0x10. Byte lives at offset 11.", + "The unsignedUnpadded and signingPreimage vectors above both carry 0x01", + "because the signature is absent from each. Only the finished 110-byte", + "wire packet sets 0x02 as well — which is exactly why re-signing a", + "received packet requires clearing that bit before re-encoding." + ], + "unsignedUnpadded": "0x01", + "signingPreimage": "0x01", + "signedWirePacket": "0x03" + } + }, + + "signature": { + "_comment": [ + "Ed25519. CryptoKit spells the type `Curve25519.Signing.PrivateKey`, which", + "IS Ed25519 — reaching for a primitive named 'Curve25519' in another", + "language gets you X25519 key agreement, the wrong algorithm.", + "", + "Signature BYTES are deliberately not pinned here. CryptoKit's Ed25519", + "signing is RANDOMIZED rather than the deterministic RFC 8032", + "construction, so two signatures over identical input differ and both", + "verify. A second implementation using a deterministic Ed25519 library", + "will not reproduce iOS's bytes and does not need to. Pin the pre-image;", + "verification is the contract." + ], + "publicKey": "2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12", + "signatureLength": 64, + "deterministic": false, + "verify": "Ed25519 verify(publicKey, signature, packetSigning.signingPreimage) must succeed" + } +} diff --git a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift new file mode 100644 index 00000000..ae4b2918 --- /dev/null +++ b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift @@ -0,0 +1,162 @@ +// +// CourierVectorTests.swift +// bitchatTests +// +// This is free and unencumbered software released into the public domain. +// For more information, see +// + +import Testing +import Foundation +import CryptoKit +@testable import BitFoundation + +/// Golden vectors for the courier wire format, mirrored in +/// `docs/courier-test-vectors.json` so a second implementation can check itself +/// without running this app. +/// +/// These cover the three ways a courier client fails *silently* — it builds, +/// connects, and delivers nothing, with no error at either end: +/// +/// 1. `expiry` is milliseconds. Seconds makes every envelope read as long +/// expired, so it is dropped at deposit with nothing logged. +/// 2. The signature does not cover the wire bytes. It covers a re-encoding with +/// `ttl = 0`, `isRSR` cleared and the signature omitted, which is then +/// PKCS#7-padded. Signing the unpadded bytes produces a signature that never +/// verifies. +/// 3. The signing key is Ed25519. CryptoKit spells it `Curve25519.Signing`; +/// reaching for a "Curve25519" primitive elsewhere yields X25519 key +/// agreement instead. +struct CourierVectorTests { + + // MARK: Fixed inputs (synthetic — not derived from any real key) + + static let recipientTag = Data((0..<16).map { UInt8($0) }) + static let noiseStaticKey = Data((0..<32).map { UInt8(0xA0 &+ $0) }) + static let ciphertext = Data("courier-vector-ciphertext-0001".utf8) + static let expiryMs: UInt64 = 1_800_000_000_000 + static let epochDay: UInt32 = 20_833 + static let senderID = Data([0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88]) + static let recipientID = Data([0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x00]) + static let timestampMs: UInt64 = 1_750_000_000_000 + static let signingSeed = Data(repeating: 0x42, count: 32) + + // MARK: Envelope + + /// `expiry` is milliseconds since epoch, big-endian, in an 8-byte TLV. + @Test func envelopeTLVEncoding() throws { + let envelope = CourierEnvelope(recipientTag: Self.recipientTag, + expiry: Self.expiryMs, + ciphertext: Self.ciphertext, + copies: 4, + prekeyID: 0x1122_3344) + let encoded = try #require(envelope.encode()) + #expect(encoded.hexEncodedString() == """ + 010010000102030405060708090a0b0c0d0e0f020008000001a3185c500003001e636f7\ + 5726965722d766563746f722d636970686572746578742d30303031040001040500041122\ + 3344 + """.replacingOccurrences(of: "\n", with: "")) + + // 0x02 carries 000001a3185c50 00 == 1_800_000_000_000 ms, not seconds. + let decoded = try #require(CourierEnvelope.decode(encoded)) + #expect(decoded.expiry == Self.expiryMs) + #expect(decoded.copies == 4) + #expect(decoded.prekeyID == 0x1122_3344) + } + + /// `copies` is clamped into 1...maxCopies, never rejected. An implementation + /// that rejects out-of-range values drops envelopes this one accepts. + @Test func copiesAreClampedNotRejected() { + func copies(_ requested: UInt8) -> UInt8 { + CourierEnvelope(recipientTag: Self.recipientTag, + expiry: Self.expiryMs, + ciphertext: Self.ciphertext, + copies: requested).copies + } + #expect(copies(0) == 1) + #expect(copies(200) == CourierEnvelope.maxCopies) + #expect(CourierEnvelope.maxCopies == 8) + } + + /// HMAC-SHA256(noiseStaticKey, "bitchat-courier-tag-v1" || BE32(epochDay)), + /// truncated to 16 bytes. + @Test func recipientTagDerivation() { + let tag = CourierEnvelope.recipientTag(noiseStaticKey: Self.noiseStaticKey, + epochDay: Self.epochDay) + #expect(tag.hexEncodedString() == "ad8514c90ca1fa6bf44e38c8a6252482") + #expect(tag.count == CourierEnvelope.tagLength) + } + + /// The 16-byte envelope identity a spray receipt carries. + @Test func ciphertextHashIsSHA256TruncatedTo16() { + let hash = Data(Self.ciphertext.sha256Hash().prefix(CourierEnvelope.tagLength)) + #expect(hash.hexEncodedString() == "bb85dcc4d8b17377c61817992df95826") + } + + // MARK: Packet canonicalization — the trap worth a vector + + /// The signed pre-image is **not** the wire bytes. It zeroes `ttl`, clears + /// the `hasSignature` flag, and is PKCS#7-padded to a block boundary. + @Test func signingPreimageIsTTLZeroedAndPadded() throws { + let payload = Data(Self.ciphertext.sha256Hash().prefix(CourierEnvelope.tagLength)) + let packet = BitchatPacket(type: 0x2A, + senderID: Self.senderID, + recipientID: Self.recipientID, + timestamp: Self.timestampMs, + payload: payload, + signature: nil, + ttl: 7) + + // Unsigned, unpadded: 14 header + 8 sender + 8 recipient + 16 payload. + let unpadded = try #require(BinaryProtocol.encode(packet, padding: false)) + #expect(unpadded.count == 46) + #expect(unpadded.hexEncodedString().hasPrefix("012a07")) // ttl = 7 here + + let preimage = try #require(packet.toBinaryDataForSigning()) + #expect(preimage.count == 256) // padded, not 46 + #expect(preimage.hexEncodedString().hasPrefix("012a00")) // ttl zeroed + #expect(preimage[BinaryProtocol.Offsets.flags] == BinaryProtocol.Flags.hasRecipient) + #expect(preimage.dropFirst(46).allSatisfy { $0 == 210 }) // 210 == 0xD2 == pad length + } + + /// Ed25519 — CryptoKit's `Curve25519.Signing`, not X25519 key agreement. + @Test func signatureOverPreimageVerifies() throws { + let payload = Data(Self.ciphertext.sha256Hash().prefix(CourierEnvelope.tagLength)) + let packet = BitchatPacket(type: 0x2A, + senderID: Self.senderID, + recipientID: Self.recipientID, + timestamp: Self.timestampMs, + payload: payload, + signature: nil, + ttl: 7) + let preimage = try #require(packet.toBinaryDataForSigning()) + + let key = try Curve25519.Signing.PrivateKey(rawRepresentation: Self.signingSeed) + #expect(key.publicKey.rawRepresentation.hexEncodedString() + == "2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12") + + // Signature BYTES are deliberately not pinned. CryptoKit's Ed25519 + // signing is randomized rather than the deterministic RFC 8032 + // construction, so two signatures over identical input differ and both + // verify. A second implementation using a deterministic Ed25519 library + // will therefore not reproduce iOS's bytes — and does not need to. + // What must match is the pre-image above; verification is the contract. + let a = try key.signature(for: preimage) + let b = try key.signature(for: preimage) + #expect(Data(a) != Data(b), "CryptoKit Ed25519 signing is randomized") + #expect(key.publicKey.isValidSignature(a, for: preimage)) + #expect(key.publicKey.isValidSignature(b, for: preimage)) + #expect(Data(a).count == BinaryProtocol.signatureSize) + + let signature = a + + // On the wire the packet is 110 bytes — the 46 above plus a 64-byte + // signature — and the flags byte now also carries hasSignature. + var signed = packet + signed.signature = Data(signature) + let wire = try #require(BinaryProtocol.encode(signed, padding: false)) + #expect(wire.count == 110) + #expect(wire[BinaryProtocol.Offsets.flags] + == BinaryProtocol.Flags.hasRecipient | BinaryProtocol.Flags.hasSignature) + } +} From 6a675ab4fc028faf38df97287bee1c4abc8bbd17 Mon Sep 17 00:00:00 2001 From: ecgang Date: Sat, 25 Jul 2026 15:29:52 -0700 Subject: [PATCH 2/7] Courier vectors: use a real deposit frame and pin every byte MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both changes address the Codex review on #1472. The signing vector used type 0x2a, which is not a MessageType on main — it is the spray-receipt opcode from a separate unmerged branch, so the frame decoded to nothing and was misleading as an end-to-end courier vector. It now encodes an actual courierEnvelope deposit: type 0x04 carrying the encoded envelope from the TLV vector as its payload. 14 header + 8 sender + 8 recipient + 74 envelope = 104 unsigned and unpadded, 256 signed, 168 on the wire. The envelope is under the 100-byte compression threshold, so the compressed path stays out of it. The pre-image assertions checked only length, the first three bytes, the flags byte and the padding suffix. A change to timestamp encoding, payload length or field layout could have left the test green while the JSON went stale — which made the claim that these cannot drift without a test failing untrue as written. Both the unpadded and padded sequences are now compared in full. Co-Authored-By: Claude Opus 5 (1M context) --- docs/courier-test-vectors.json | 17 +++-- .../CourierVectorTests.swift | 74 +++++++++++++------ 2 files changed, 59 insertions(+), 32 deletions(-) diff --git a/docs/courier-test-vectors.json b/docs/courier-test-vectors.json index 8981bcbf..dc29fdbd 100644 --- a/docs/courier-test-vectors.json +++ b/docs/courier-test-vectors.json @@ -93,18 +93,19 @@ "and nothing in any log points at the cause." ], "packet": { + "_comment": "A real courierEnvelope deposit frame: type 0x04 carrying the encoded envelope from envelopeTLV.encoded above as its payload.", "version": 1, - "type": "0x2a", + "type": "0x04", "ttlOnWire": 7, - "payload": "bb85dcc4d8b17377c61817992df95826" + "payloadIs": "envelopeTLV.encoded (74 bytes)" }, - "unsignedUnpaddedLength": 46, - "unsignedUnpadded": "012a07000001977420dc00010010112233445566778899aabbccddeeff00bb85dcc4d8b17377c61817992df95826", + "unsignedUnpaddedLength": 104, + "unsignedUnpadded": "010407000001977420dc0001004a112233445566778899aabbccddeeff00010010000102030405060708090a0b0c0d0e0f020008000001a3185c500003001e636f75726965722d766563746f722d636970686572746578742d303030310400010405000411223344", "signingPreimageLength": 256, - "signingPreimagePadByte": "0xd2", - "signingPreimagePadCount": 210, - "signingPreimage": "012a00000001977420dc00010010112233445566778899aabbccddeeff00bb85dcc4d8b17377c61817992df95826d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2", - "signedWireLength": 110, + "signingPreimagePadByte": "0x98", + "signingPreimagePadCount": 152, + "signingPreimage": "010400000001977420dc0001004a112233445566778899aabbccddeeff00010010000102030405060708090a0b0c0d0e0f020008000001a3185c500003001e636f75726965722d766563746f722d636970686572746578742d3030303104000104050004112233449898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898989898", + "signedWireLength": 168, "flags": { "_comment": [ "Flag bits: hasRecipient 0x01, hasSignature 0x02, isCompressed 0x04,", diff --git a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift index ae4b2918..113ea1ee 100644 --- a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift +++ b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift @@ -95,40 +95,66 @@ struct CourierVectorTests { // MARK: Packet canonicalization — the trap worth a vector + /// A real `courierEnvelope` frame: type 0x04 carrying an encoded envelope, + /// which is what a deposit actually puts on the wire. + static func envelopePacket() throws -> BitchatPacket { + let envelope = CourierEnvelope(recipientTag: recipientTag, + expiry: expiryMs, + ciphertext: ciphertext, + copies: 4, + prekeyID: 0x1122_3344) + return BitchatPacket(type: 0x04, + senderID: senderID, + recipientID: recipientID, + timestamp: timestampMs, + payload: try #require(envelope.encode()), + signature: nil, + ttl: 7) + } + + /// Every byte of the unsigned frame. 14 header + 8 sender + 8 recipient + + /// 74 envelope = 104. The envelope is under the 100-byte compression + /// threshold, so the compressed path never applies here. + static let unpaddedHex = """ + 010407000001977420dc0001004a112233445566778899aabbccddeeff000100100001020\ + 30405060708090a0b0c0d0e0f020008000001a3185c500003001e636f75726965722d76656\ + 3746f722d636970686572746578742d303030310400010405000411223344 + """.replacingOccurrences(of: "\n", with: "") + + /// Identical to `unpaddedHex` except `ttl` at offset 2 is zeroed. + static let preimageBodyHex = """ + 010400000001977420dc0001004a112233445566778899aabbccddeeff000100100001020\ + 30405060708090a0b0c0d0e0f020008000001a3185c500003001e636f75726965722d76656\ + 3746f722d636970686572746578742d303030310400010405000411223344 + """.replacingOccurrences(of: "\n", with: "") + /// The signed pre-image is **not** the wire bytes. It zeroes `ttl`, clears /// the `hasSignature` flag, and is PKCS#7-padded to a block boundary. + /// Both sequences are compared in full — a change to timestamp encoding, + /// payload length, or field layout has to fail here, otherwise the JSON + /// fixture could go stale while this stayed green. @Test func signingPreimageIsTTLZeroedAndPadded() throws { - let payload = Data(Self.ciphertext.sha256Hash().prefix(CourierEnvelope.tagLength)) - let packet = BitchatPacket(type: 0x2A, - senderID: Self.senderID, - recipientID: Self.recipientID, - timestamp: Self.timestampMs, - payload: payload, - signature: nil, - ttl: 7) + let packet = try Self.envelopePacket() - // Unsigned, unpadded: 14 header + 8 sender + 8 recipient + 16 payload. let unpadded = try #require(BinaryProtocol.encode(packet, padding: false)) - #expect(unpadded.count == 46) - #expect(unpadded.hexEncodedString().hasPrefix("012a07")) // ttl = 7 here + #expect(unpadded.count == 104) + #expect(unpadded.hexEncodedString() == Self.unpaddedHex) let preimage = try #require(packet.toBinaryDataForSigning()) - #expect(preimage.count == 256) // padded, not 46 - #expect(preimage.hexEncodedString().hasPrefix("012a00")) // ttl zeroed + #expect(preimage.count == 256) + #expect(preimage.hexEncodedString() + == Self.preimageBodyHex + String(repeating: "98", count: 152)) + + // 152 == 0x98 == the shortfall to the 256-byte block, and every pad + // byte equals it. + #expect(preimage.dropFirst(104).allSatisfy { $0 == 152 }) #expect(preimage[BinaryProtocol.Offsets.flags] == BinaryProtocol.Flags.hasRecipient) - #expect(preimage.dropFirst(46).allSatisfy { $0 == 210 }) // 210 == 0xD2 == pad length + #expect(unpadded[2] == 7 && preimage[2] == 0) // ttl on wire vs signed } /// Ed25519 — CryptoKit's `Curve25519.Signing`, not X25519 key agreement. @Test func signatureOverPreimageVerifies() throws { - let payload = Data(Self.ciphertext.sha256Hash().prefix(CourierEnvelope.tagLength)) - let packet = BitchatPacket(type: 0x2A, - senderID: Self.senderID, - recipientID: Self.recipientID, - timestamp: Self.timestampMs, - payload: payload, - signature: nil, - ttl: 7) + let packet = try Self.envelopePacket() let preimage = try #require(packet.toBinaryDataForSigning()) let key = try Curve25519.Signing.PrivateKey(rawRepresentation: Self.signingSeed) @@ -150,12 +176,12 @@ struct CourierVectorTests { let signature = a - // On the wire the packet is 110 bytes — the 46 above plus a 64-byte + // On the wire the packet is 168 bytes — the 104 above plus a 64-byte // signature — and the flags byte now also carries hasSignature. var signed = packet signed.signature = Data(signature) let wire = try #require(BinaryProtocol.encode(signed, padding: false)) - #expect(wire.count == 110) + #expect(wire.count == 168) #expect(wire[BinaryProtocol.Offsets.flags] == BinaryProtocol.Flags.hasRecipient | BinaryProtocol.Flags.hasSignature) } From 5ae772fdd8cb03314ca527cfa2fbe3933e74ca65 Mon Sep 17 00:00:00 2001 From: ecgang Date: Sat, 25 Jul 2026 15:47:19 -0700 Subject: [PATCH 3/7] Courier vectors: pin the pre-image in the signature test too MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The signature test signed whatever pre-image it was handed and verified it, which is self-consistent by construction — it would have passed over a wrong canonicalization. Mutating an input (timestamp +1ms) proved it: the comparison test failed and this one did not. It now pins the pre-image before signing, so both tests fail on any change to field layout, timestamp encoding or payload length. Co-Authored-By: Claude Opus 5 (1M context) --- .../Tests/BitFoundationTests/CourierVectorTests.swift | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift index 113ea1ee..63991f69 100644 --- a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift +++ b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift @@ -157,6 +157,13 @@ struct CourierVectorTests { let packet = try Self.envelopePacket() let preimage = try #require(packet.toBinaryDataForSigning()) + // Pin what is being signed. Without this the test is self-consistent by + // construction — it would sign whatever it was handed, verify it, and + // pass over a wrong canonicalization. Proven by mutating an input and + // watching this line, not the verification below, be the one that fails. + #expect(preimage.hexEncodedString() + == Self.preimageBodyHex + String(repeating: "98", count: 152)) + let key = try Curve25519.Signing.PrivateKey(rawRepresentation: Self.signingSeed) #expect(key.publicKey.rawRepresentation.hexEncodedString() == "2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12") From 9875c24f6ca43a4927ab563ec4f5950f6f12258a Mon Sep 17 00:00:00 2001 From: ecgang Date: Sun, 26 Jul 2026 11:22:47 -0700 Subject: [PATCH 4/7] Courier vectors: drive the tests from the published JSON MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses both asks in the #1472 review. The tests duplicated every vector as a Swift literal, so a format change that updated only the Swift side would have left docs/courier-test-vectors.json silently stale — the document was published as authoritative but nothing checked it. Each test now reads the file and asserts against what it says. The NoiseTestVectors.json precedent does not transfer directly: that fixture lives inside its test target and loads from the test bundle, whereas this one lives at repo-root docs/, outside the package, so SwiftPM cannot carry it as a resource. It resolves the path from #filePath instead, the way bitchatTests/LocalizationCoverageTests already reaches the repo root. CI runs this package with the full tree checked out, and the target is not in the xcodeproj, so there is no bundle-only run to break. Two things beyond a mechanical swap: - The published `label` for the tag HMAC is now load-bearing. The implementation's context string is private, so the test recomputes the tag from the label in the file and compares — otherwise the document could name the wrong label and nothing would notice. - A dedicated test fails loudly if the file is missing or has lost a key, rather than letting a rename skip every assertion while the suite reports green. Also fixes the stale prose. The review caught "the finished 110-byte wire packet"; the same deleted spray-receipt example had left three more wrong numbers in packetSigning._comment — the padding worked example read 46 + 16 = 62 with shortfall 210 = 0xd2, where the real frame is 104 + 16 = 120 with shortfall 152 = 0x98. Proven by mutation, not by green: flipping a byte in envelopeTLV.encoded, a byte in signingPreimage, and the HMAC label each fail the matching test, and removing the file fails all seven. Co-Authored-By: Claude Opus 5 (1M context) --- docs/courier-test-vectors.json | 8 +- .../CourierVectorTests.swift | 326 +++++++++++++----- 2 files changed, 235 insertions(+), 99 deletions(-) diff --git a/docs/courier-test-vectors.json b/docs/courier-test-vectors.json index dc29fdbd..abf05acc 100644 --- a/docs/courier-test-vectors.json +++ b/docs/courier-test-vectors.json @@ -86,10 +86,10 @@ "", "Padding target is the smallest of [256, 512, 1024, 2048] that fits", "size + 16, applied only when the shortfall is 1...255, every pad byte", - "equal to the shortfall. Here: 46 + 16 = 62 <= 256, so target 256,", - "shortfall 210 = 0xd2.", + "equal to the shortfall. Here: 104 + 16 = 120 <= 256, so target 256,", + "shortfall 152 = 0x98.", "", - "Signing the 46 unpadded bytes produces a signature that never verifies,", + "Signing the 104 unpadded bytes produces a signature that never verifies,", "and nothing in any log points at the cause." ], "packet": { @@ -111,7 +111,7 @@ "Flag bits: hasRecipient 0x01, hasSignature 0x02, isCompressed 0x04,", "hasRoute 0x08, isRSR 0x10. Byte lives at offset 11.", "The unsignedUnpadded and signingPreimage vectors above both carry 0x01", - "because the signature is absent from each. Only the finished 110-byte", + "because the signature is absent from each. Only the finished 168-byte", "wire packet sets 0x02 as well — which is exactly why re-signing a", "received packet requires clearing that bit before re-encoding." ], diff --git a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift index 63991f69..435a4a6d 100644 --- a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift +++ b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift @@ -11,10 +11,15 @@ import Foundation import CryptoKit @testable import BitFoundation -/// Golden vectors for the courier wire format, mirrored in +/// Golden vectors for the courier wire format, published as /// `docs/courier-test-vectors.json` so a second implementation can check itself /// without running this app. /// +/// Every value asserted below is **read from that file**, not duplicated here. +/// A format change that updates only the Swift side leaves the published JSON +/// stale, and a stale JSON fails these tests — which is the only thing that +/// makes the document trustworthy to someone who cannot run it. +/// /// These cover the three ways a courier client fails *silently* — it builds, /// connects, and delivers nothing, with no error at either end: /// @@ -29,144 +34,274 @@ import CryptoKit /// agreement instead. struct CourierVectorTests { - // MARK: Fixed inputs (synthetic — not derived from any real key) + // MARK: Loading the published vectors - static let recipientTag = Data((0..<16).map { UInt8($0) }) - static let noiseStaticKey = Data((0..<32).map { UInt8(0xA0 &+ $0) }) - static let ciphertext = Data("courier-vector-ciphertext-0001".utf8) - static let expiryMs: UInt64 = 1_800_000_000_000 - static let epochDay: UInt32 = 20_833 - static let senderID = Data([0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88]) - static let recipientID = Data([0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF, 0x00]) - static let timestampMs: UInt64 = 1_750_000_000_000 - static let signingSeed = Data(repeating: 0x42, count: 32) + /// The published file, located relative to this source file. It lives at + /// repo-root `docs/`, outside this package, so it cannot be a SwiftPM + /// resource the way `NoiseTestVectors.json` is — the repo already resolves + /// a repo-root path this way in `bitchatTests/LocalizationCoverageTests`. + static let vectorFileURL = URL(fileURLWithPath: #filePath) + .deletingLastPathComponent() // → BitFoundationTests + .deletingLastPathComponent() // → Tests + .deletingLastPathComponent() // → BitFoundation + .deletingLastPathComponent() // → localPackages + .deletingLastPathComponent() // → repo root + .appendingPathComponent("docs/courier-test-vectors.json") + + struct MissingVectorFile: Error, CustomStringConvertible { + let path: String + var description: String { + "docs/courier-test-vectors.json not found at \(path). These tests assert " + + "the published vectors; they must not silently pass without them." + } + } + + static func loadVectors() throws -> Vectors { + guard FileManager.default.fileExists(atPath: vectorFileURL.path) else { + throw MissingVectorFile(path: vectorFileURL.path) + } + return try JSONDecoder().decode(Vectors.self, + from: try Data(contentsOf: vectorFileURL)) + } + + /// Decoded shape of the published file. `_comment` keys are prose for human + /// readers and are deliberately not decoded; every other key is, so a field + /// cannot be renamed or dropped without failing here. + struct Vectors: Decodable { + struct Inputs: Decodable { + let recipientTag: String + let noiseStaticKey: String + let ciphertextUTF8: String + let ciphertext: String + let expiryMillis: UInt64 + let epochDay: UInt32 + let senderID: String + let recipientID: String + let timestampMillis: UInt64 + let signingSeed: String + } + struct EnvelopeTLV: Decodable { + let copies: UInt8 + let prekeyID: UInt32 + let encoded: String + let encodedLength: Int + } + struct CopiesClamping: Decodable { + struct Case: Decodable { + let requested: UInt8 + let stored: UInt8 + } + let maxCopies: UInt8 + let cases: [Case] + } + struct RecipientTagDerivation: Decodable { + let label: String + let epochDay: UInt32 + let expected: String + } + struct CiphertextHash: Decodable { + let expected: String + } + struct PacketSigning: Decodable { + struct Packet: Decodable { + let version: UInt8 + let type: String + let ttlOnWire: UInt8 + } + struct Flags: Decodable { + let unsignedUnpadded: String + let signingPreimage: String + let signedWirePacket: String + } + let packet: Packet + let unsignedUnpaddedLength: Int + let unsignedUnpadded: String + let signingPreimageLength: Int + let signingPreimagePadByte: String + let signingPreimagePadCount: Int + let signingPreimage: String + let signedWireLength: Int + let flags: Flags + } + struct Signature: Decodable { + let publicKey: String + let signatureLength: Int + let deterministic: Bool + } + + let inputs: Inputs + let envelopeTLV: EnvelopeTLV + let copiesClamping: CopiesClamping + let recipientTagDerivation: RecipientTagDerivation + let ciphertextHash: CiphertextHash + let packetSigning: PacketSigning + let signature: Signature + } + + /// Fails loudly if the published file is missing, renamed, or has lost a + /// key — otherwise a rename would skip every assertion below while the + /// suite still reported green. + @Test func publishedVectorFileLoads() throws { + let v = try Self.loadVectors() + #expect(v.inputs.ciphertextUTF8 == "courier-vector-ciphertext-0001") + #expect(v.copiesClamping.cases.isEmpty == false) + } + + // MARK: Decoded inputs + + private static func hex(_ string: String) throws -> Data { + try #require(Data(hexString: string), "not valid hex: \(string)") + } + + /// `"0x03"` → `3`. + private static func flagByte(_ string: String) throws -> UInt8 { + let digits = string.hasPrefix("0x") ? String(string.dropFirst(2)) : string + return try #require(UInt8(digits, radix: 16), "not a hex byte: \(string)") + } + + private static func envelope(from v: Vectors) throws -> CourierEnvelope { + CourierEnvelope(recipientTag: try hex(v.inputs.recipientTag), + expiry: v.inputs.expiryMillis, + ciphertext: try hex(v.inputs.ciphertext), + copies: v.envelopeTLV.copies, + prekeyID: v.envelopeTLV.prekeyID) + } // MARK: Envelope /// `expiry` is milliseconds since epoch, big-endian, in an 8-byte TLV. @Test func envelopeTLVEncoding() throws { - let envelope = CourierEnvelope(recipientTag: Self.recipientTag, - expiry: Self.expiryMs, - ciphertext: Self.ciphertext, - copies: 4, - prekeyID: 0x1122_3344) - let encoded = try #require(envelope.encode()) - #expect(encoded.hexEncodedString() == """ - 010010000102030405060708090a0b0c0d0e0f020008000001a3185c500003001e636f7\ - 5726965722d766563746f722d636970686572746578742d30303031040001040500041122\ - 3344 - """.replacingOccurrences(of: "\n", with: "")) + let v = try Self.loadVectors() - // 0x02 carries 000001a3185c50 00 == 1_800_000_000_000 ms, not seconds. + // The published ciphertext hex and its UTF-8 source must agree, or the + // document contradicts itself. + #expect(try Self.hex(v.inputs.ciphertext) == Data(v.inputs.ciphertextUTF8.utf8)) + + let encoded = try #require(try Self.envelope(from: v).encode()) + #expect(encoded.hexEncodedString() == v.envelopeTLV.encoded) + #expect(encoded.count == v.envelopeTLV.encodedLength) + + // 0x02 carries 000001a3185c5000 == 1_800_000_000_000 ms, not seconds. let decoded = try #require(CourierEnvelope.decode(encoded)) - #expect(decoded.expiry == Self.expiryMs) - #expect(decoded.copies == 4) - #expect(decoded.prekeyID == 0x1122_3344) + #expect(decoded.expiry == v.inputs.expiryMillis) + #expect(decoded.copies == v.envelopeTLV.copies) + #expect(decoded.prekeyID == v.envelopeTLV.prekeyID) } /// `copies` is clamped into 1...maxCopies, never rejected. An implementation /// that rejects out-of-range values drops envelopes this one accepts. - @Test func copiesAreClampedNotRejected() { - func copies(_ requested: UInt8) -> UInt8 { - CourierEnvelope(recipientTag: Self.recipientTag, - expiry: Self.expiryMs, - ciphertext: Self.ciphertext, - copies: requested).copies + @Test func copiesAreClampedNotRejected() throws { + let v = try Self.loadVectors() + #expect(CourierEnvelope.maxCopies == v.copiesClamping.maxCopies) + + for testCase in v.copiesClamping.cases { + let stored = CourierEnvelope(recipientTag: try Self.hex(v.inputs.recipientTag), + expiry: v.inputs.expiryMillis, + ciphertext: try Self.hex(v.inputs.ciphertext), + copies: testCase.requested).copies + #expect(stored == testCase.stored, + "copies(\(testCase.requested)) expected \(testCase.stored), got \(stored)") } - #expect(copies(0) == 1) - #expect(copies(200) == CourierEnvelope.maxCopies) - #expect(CourierEnvelope.maxCopies == 8) } /// HMAC-SHA256(noiseStaticKey, "bitchat-courier-tag-v1" || BE32(epochDay)), /// truncated to 16 bytes. - @Test func recipientTagDerivation() { - let tag = CourierEnvelope.recipientTag(noiseStaticKey: Self.noiseStaticKey, - epochDay: Self.epochDay) - #expect(tag.hexEncodedString() == "ad8514c90ca1fa6bf44e38c8a6252482") + @Test func recipientTagDerivation() throws { + let v = try Self.loadVectors() + let noiseStaticKey = try Self.hex(v.inputs.noiseStaticKey) + #expect(v.recipientTagDerivation.epochDay == v.inputs.epochDay) + + let tag = CourierEnvelope.recipientTag(noiseStaticKey: noiseStaticKey, + epochDay: v.recipientTagDerivation.epochDay) + #expect(tag.hexEncodedString() == v.recipientTagDerivation.expected) #expect(tag.count == CourierEnvelope.tagLength) + + // Recompute from the published `label` so that field is load-bearing + // too: the implementation's context string is private, so without this + // the document could name the wrong label and nothing would notice. + var message = Data(v.recipientTagDerivation.label.utf8) + withUnsafeBytes(of: v.recipientTagDerivation.epochDay.bigEndian) { message.append(contentsOf: $0) } + let recomputed = Data(HMAC.authenticationCode( + for: message, using: SymmetricKey(data: noiseStaticKey) + ).prefix(CourierEnvelope.tagLength)) + #expect(recomputed == tag) } /// The 16-byte envelope identity a spray receipt carries. - @Test func ciphertextHashIsSHA256TruncatedTo16() { - let hash = Data(Self.ciphertext.sha256Hash().prefix(CourierEnvelope.tagLength)) - #expect(hash.hexEncodedString() == "bb85dcc4d8b17377c61817992df95826") + @Test func ciphertextHashIsSHA256TruncatedTo16() throws { + let v = try Self.loadVectors() + let hash = Data(try Self.hex(v.inputs.ciphertext) + .sha256Hash() + .prefix(CourierEnvelope.tagLength)) + #expect(hash.hexEncodedString() == v.ciphertextHash.expected) } // MARK: Packet canonicalization — the trap worth a vector /// A real `courierEnvelope` frame: type 0x04 carrying an encoded envelope, /// which is what a deposit actually puts on the wire. - static func envelopePacket() throws -> BitchatPacket { - let envelope = CourierEnvelope(recipientTag: recipientTag, - expiry: expiryMs, - ciphertext: ciphertext, - copies: 4, - prekeyID: 0x1122_3344) - return BitchatPacket(type: 0x04, - senderID: senderID, - recipientID: recipientID, - timestamp: timestampMs, - payload: try #require(envelope.encode()), - signature: nil, - ttl: 7) + static func envelopePacket(from v: Vectors) throws -> BitchatPacket { + BitchatPacket(type: try flagByte(v.packetSigning.packet.type), + senderID: try hex(v.inputs.senderID), + recipientID: try hex(v.inputs.recipientID), + timestamp: v.inputs.timestampMillis, + payload: try #require(try envelope(from: v).encode()), + signature: nil, + ttl: v.packetSigning.packet.ttlOnWire) } - /// Every byte of the unsigned frame. 14 header + 8 sender + 8 recipient + - /// 74 envelope = 104. The envelope is under the 100-byte compression - /// threshold, so the compressed path never applies here. - static let unpaddedHex = """ - 010407000001977420dc0001004a112233445566778899aabbccddeeff000100100001020\ - 30405060708090a0b0c0d0e0f020008000001a3185c500003001e636f75726965722d76656\ - 3746f722d636970686572746578742d303030310400010405000411223344 - """.replacingOccurrences(of: "\n", with: "") - - /// Identical to `unpaddedHex` except `ttl` at offset 2 is zeroed. - static let preimageBodyHex = """ - 010400000001977420dc0001004a112233445566778899aabbccddeeff000100100001020\ - 30405060708090a0b0c0d0e0f020008000001a3185c500003001e636f75726965722d76656\ - 3746f722d636970686572746578742d303030310400010405000411223344 - """.replacingOccurrences(of: "\n", with: "") - /// The signed pre-image is **not** the wire bytes. It zeroes `ttl`, clears /// the `hasSignature` flag, and is PKCS#7-padded to a block boundary. /// Both sequences are compared in full — a change to timestamp encoding, /// payload length, or field layout has to fail here, otherwise the JSON /// fixture could go stale while this stayed green. @Test func signingPreimageIsTTLZeroedAndPadded() throws { - let packet = try Self.envelopePacket() + let v = try Self.loadVectors() + let signing = v.packetSigning + let packet = try Self.envelopePacket(from: v) let unpadded = try #require(BinaryProtocol.encode(packet, padding: false)) - #expect(unpadded.count == 104) - #expect(unpadded.hexEncodedString() == Self.unpaddedHex) + #expect(unpadded.count == signing.unsignedUnpaddedLength) + #expect(unpadded.hexEncodedString() == signing.unsignedUnpadded) let preimage = try #require(packet.toBinaryDataForSigning()) - #expect(preimage.count == 256) - #expect(preimage.hexEncodedString() - == Self.preimageBodyHex + String(repeating: "98", count: 152)) + #expect(preimage.count == signing.signingPreimageLength) + #expect(preimage.hexEncodedString() == signing.signingPreimage) - // 152 == 0x98 == the shortfall to the 256-byte block, and every pad - // byte equals it. - #expect(preimage.dropFirst(104).allSatisfy { $0 == 152 }) - #expect(preimage[BinaryProtocol.Offsets.flags] == BinaryProtocol.Flags.hasRecipient) - #expect(unpadded[2] == 7 && preimage[2] == 0) // ttl on wire vs signed + // The pad byte equals the shortfall to the block boundary, and every + // pad byte equals it. + let padByte = try Self.flagByte(signing.signingPreimagePadByte) + #expect(Int(padByte) == signing.signingPreimagePadCount) + #expect(signing.unsignedUnpaddedLength + signing.signingPreimagePadCount + == signing.signingPreimageLength) + #expect(preimage.dropFirst(signing.unsignedUnpaddedLength).count + == signing.signingPreimagePadCount) + #expect(preimage.dropFirst(signing.unsignedUnpaddedLength).allSatisfy { $0 == padByte }) + + #expect(preimage[BinaryProtocol.Offsets.flags] + == (try Self.flagByte(signing.flags.signingPreimage))) + #expect(unpadded[BinaryProtocol.Offsets.flags] + == (try Self.flagByte(signing.flags.unsignedUnpadded))) + #expect(unpadded[2] == signing.packet.ttlOnWire && preimage[2] == 0) + #expect(unpadded[0] == signing.packet.version) } /// Ed25519 — CryptoKit's `Curve25519.Signing`, not X25519 key agreement. @Test func signatureOverPreimageVerifies() throws { - let packet = try Self.envelopePacket() + let v = try Self.loadVectors() + let packet = try Self.envelopePacket(from: v) let preimage = try #require(packet.toBinaryDataForSigning()) // Pin what is being signed. Without this the test is self-consistent by // construction — it would sign whatever it was handed, verify it, and // pass over a wrong canonicalization. Proven by mutating an input and // watching this line, not the verification below, be the one that fails. - #expect(preimage.hexEncodedString() - == Self.preimageBodyHex + String(repeating: "98", count: 152)) + #expect(preimage.hexEncodedString() == v.packetSigning.signingPreimage) - let key = try Curve25519.Signing.PrivateKey(rawRepresentation: Self.signingSeed) - #expect(key.publicKey.rawRepresentation.hexEncodedString() - == "2152f8d19b791d24453242e15f2eab6cb7cffa7b6a5ed30097960e069881db12") + let key = try Curve25519.Signing.PrivateKey( + rawRepresentation: try Self.hex(v.inputs.signingSeed) + ) + #expect(key.publicKey.rawRepresentation.hexEncodedString() == v.signature.publicKey) // Signature BYTES are deliberately not pinned. CryptoKit's Ed25519 // signing is randomized rather than the deterministic RFC 8032 @@ -176,20 +311,21 @@ struct CourierVectorTests { // What must match is the pre-image above; verification is the contract. let a = try key.signature(for: preimage) let b = try key.signature(for: preimage) + #expect(v.signature.deterministic == false) #expect(Data(a) != Data(b), "CryptoKit Ed25519 signing is randomized") #expect(key.publicKey.isValidSignature(a, for: preimage)) #expect(key.publicKey.isValidSignature(b, for: preimage)) #expect(Data(a).count == BinaryProtocol.signatureSize) + #expect(Data(a).count == v.signature.signatureLength) - let signature = a - - // On the wire the packet is 168 bytes — the 104 above plus a 64-byte - // signature — and the flags byte now also carries hasSignature. + // On the wire the packet carries the 64-byte signature on top of the + // unsigned frame, and the flags byte now also carries hasSignature. var signed = packet - signed.signature = Data(signature) + signed.signature = Data(a) let wire = try #require(BinaryProtocol.encode(signed, padding: false)) - #expect(wire.count == 168) + #expect(wire.count == v.packetSigning.signedWireLength) + #expect(wire.count == v.packetSigning.unsignedUnpaddedLength + v.signature.signatureLength) #expect(wire[BinaryProtocol.Offsets.flags] - == BinaryProtocol.Flags.hasRecipient | BinaryProtocol.Flags.hasSignature) + == (try Self.flagByte(v.packetSigning.flags.signedWirePacket))) } } From 4ab3e1a0e206c3c7c7e4b6b0115428f9c333c4ed Mon Sep 17 00:00:00 2001 From: ecgang Date: Sun, 26 Jul 2026 11:46:29 -0700 Subject: [PATCH 5/7] Courier vectors: fail the length checks before indexing the bytes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-model review (agy) on the previous commit. The length assertions were #expect, so a frame of the wrong size reported the mismatch and then kept going into `unpadded[2]` and the flags-offset reads. Data subscripting past the end traps, so the process would die and take the rest of the run's results with it — the failure mode where you learn least at the moment you need to learn most. They are #require now. Also marks the ciphertextHash vector as the weak one it is. Its derivation has no consumer on main: the function that reads it arrives with the courier-spray work, so the truncation is spelled out in the test rather than called, and a future helper that truncates differently would not fail here. Said plainly in the test rather than left for the next reader to discover. Verified by mutation: declaring the wrong unsignedUnpaddedLength now fails both signing tests with a reported expectation instead of a crash. Co-Authored-By: Claude Opus 5 (1M context) --- .../BitFoundationTests/CourierVectorTests.swift | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift index 435a4a6d..eff7db94 100644 --- a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift +++ b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift @@ -228,6 +228,14 @@ struct CourierVectorTests { } /// The 16-byte envelope identity a spray receipt carries. + /// + /// Weaker than the other vectors, and deliberately so: this derivation has + /// no consumer on main yet — the function that reads it arrives with the + /// courier-spray work. What production surface exists is asserted (the + /// `sha256Hash()` implementation and the `tagLength` constant), but the + /// truncation is spelled out here rather than called, so a future + /// `ciphertextHash` helper that truncates differently would not fail this. + /// When that helper lands it should assert against this same vector. @Test func ciphertextHashIsSHA256TruncatedTo16() throws { let v = try Self.loadVectors() let hash = Data(try Self.hex(v.inputs.ciphertext) @@ -261,11 +269,14 @@ struct CourierVectorTests { let packet = try Self.envelopePacket(from: v) let unpadded = try #require(BinaryProtocol.encode(packet, padding: false)) - #expect(unpadded.count == signing.unsignedUnpaddedLength) + // #require, not #expect: every assertion below subscripts these bytes, + // and `Data` subscripting past the end traps. A short frame has to fail + // the test, not crash the process and take the rest of the run with it. + try #require(unpadded.count == signing.unsignedUnpaddedLength) #expect(unpadded.hexEncodedString() == signing.unsignedUnpadded) let preimage = try #require(packet.toBinaryDataForSigning()) - #expect(preimage.count == signing.signingPreimageLength) + try #require(preimage.count == signing.signingPreimageLength) #expect(preimage.hexEncodedString() == signing.signingPreimage) // The pad byte equals the shortfall to the block boundary, and every @@ -323,7 +334,7 @@ struct CourierVectorTests { var signed = packet signed.signature = Data(a) let wire = try #require(BinaryProtocol.encode(signed, padding: false)) - #expect(wire.count == v.packetSigning.signedWireLength) + try #require(wire.count == v.packetSigning.signedWireLength) #expect(wire.count == v.packetSigning.unsignedUnpaddedLength + v.signature.signatureLength) #expect(wire[BinaryProtocol.Offsets.flags] == (try Self.flagByte(v.packetSigning.flags.signedWirePacket))) From 29ebbcfb6240bc4ddb2d8b0289576ebba7f2d3a1 Mon Sep 17 00:00:00 2001 From: ecgang Date: Sun, 26 Jul 2026 11:50:38 -0700 Subject: [PATCH 6/7] Courier vectors: move the ciphertext-hash vector to where it can be checked MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The remaining piece of the spray-receipt example this PR already removed once. `ciphertextHash` documents the envelope identity a spray receipt carries, and nothing on main carries one — `CourierStore.ciphertextHash` arrives with the courier-spray branch. So the test could not call the function the vector describes; it re-spelled the truncation instead, which would have passed just as green against a helper that truncated differently. A vector nobody can check is worse than no vector, because it reads as verified. It moves to the spray PR, where the production function exists and the assertion can go through it. Everything left in the file is now asserted against code that runs on main. Co-Authored-By: Claude Opus 5 (1M context) --- docs/courier-test-vectors.json | 5 ----- .../CourierVectorTests.swift | 21 ------------------- 2 files changed, 26 deletions(-) diff --git a/docs/courier-test-vectors.json b/docs/courier-test-vectors.json index abf05acc..82d24bce 100644 --- a/docs/courier-test-vectors.json +++ b/docs/courier-test-vectors.json @@ -71,11 +71,6 @@ "expected": "ad8514c90ca1fa6bf44e38c8a6252482" }, - "ciphertextHash": { - "_comment": "SHA-256 of the ciphertext, truncated to 16 bytes. This is the envelope identity a spray receipt carries.", - "expected": "bb85dcc4d8b17377c61817992df95826" - }, - "packetSigning": { "_comment": [ "THE trap. The signature does NOT cover the bytes as they appear on the", diff --git a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift index eff7db94..adb2d189 100644 --- a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift +++ b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift @@ -99,9 +99,6 @@ struct CourierVectorTests { let epochDay: UInt32 let expected: String } - struct CiphertextHash: Decodable { - let expected: String - } struct PacketSigning: Decodable { struct Packet: Decodable { let version: UInt8 @@ -133,7 +130,6 @@ struct CourierVectorTests { let envelopeTLV: EnvelopeTLV let copiesClamping: CopiesClamping let recipientTagDerivation: RecipientTagDerivation - let ciphertextHash: CiphertextHash let packetSigning: PacketSigning let signature: Signature } @@ -227,23 +223,6 @@ struct CourierVectorTests { #expect(recomputed == tag) } - /// The 16-byte envelope identity a spray receipt carries. - /// - /// Weaker than the other vectors, and deliberately so: this derivation has - /// no consumer on main yet — the function that reads it arrives with the - /// courier-spray work. What production surface exists is asserted (the - /// `sha256Hash()` implementation and the `tagLength` constant), but the - /// truncation is spelled out here rather than called, so a future - /// `ciphertextHash` helper that truncates differently would not fail this. - /// When that helper lands it should assert against this same vector. - @Test func ciphertextHashIsSHA256TruncatedTo16() throws { - let v = try Self.loadVectors() - let hash = Data(try Self.hex(v.inputs.ciphertext) - .sha256Hash() - .prefix(CourierEnvelope.tagLength)) - #expect(hash.hexEncodedString() == v.ciphertextHash.expected) - } - // MARK: Packet canonicalization — the trap worth a vector /// A real `courierEnvelope` frame: type 0x04 carrying an encoded envelope, From 44f8456c70bef80882c3c46cb301e37b98f4ace3 Mon Sep 17 00:00:00 2001 From: ecgang Date: Sun, 26 Jul 2026 11:55:42 -0700 Subject: [PATCH 7/7] Courier vectors: decode the two keys nothing was reading MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-model review (codex) on the previous commits. `packet.payloadIs` and `signature.verify` were the only non-comment keys the Decodable shapes did not declare, so either could be renamed or deleted from the published file and every test stayed green — the exact staleness this PR exists to prevent, surviving in the two fields that tell a second implementer what to feed the verifier. Both are declared now, and `payloadIs` is checked rather than merely present: it states a byte count, and that count is asserted against the real encoded payload. Prose that states a number is a claim like any other. Verified by mutation: renaming either key fails decoding, and stating 73 bytes where the payload is 74 fails the length assertion alone. Codex also read the pre-fix diff and re-reported the unchecked Data indexing already fixed two commits ago, and claimed Ed25519 signing is deterministic so the non-determinism assertion should fail. The latter is wrong for CryptoKit specifically: `Curve25519.Signing` randomizes rather than following RFC 8032's deterministic construction, which the test asserts and the suite confirms on every run. No change. Co-Authored-By: Claude Opus 5 (1M context) --- .../BitFoundationTests/CourierVectorTests.swift | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift index adb2d189..86716ee4 100644 --- a/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift +++ b/localPackages/BitFoundation/Tests/BitFoundationTests/CourierVectorTests.swift @@ -104,6 +104,9 @@ struct CourierVectorTests { let version: UInt8 let type: String let ttlOnWire: UInt8 + /// Declared so it cannot be renamed or dropped unnoticed; the + /// byte count it names is asserted against the real payload. + let payloadIs: String } struct Flags: Decodable { let unsignedUnpadded: String @@ -124,6 +127,9 @@ struct CourierVectorTests { let publicKey: String let signatureLength: Int let deterministic: Bool + /// Declared for the same reason as `payloadIs`: an undeclared key + /// can vanish from the published file and every test stays green. + let verify: String } let inputs: Inputs @@ -177,6 +183,12 @@ struct CourierVectorTests { #expect(encoded.hexEncodedString() == v.envelopeTLV.encoded) #expect(encoded.count == v.envelopeTLV.encodedLength) + // The prose in `packet.payloadIs` states this byte count. Prose that + // states a number is a claim like any other, and this is the one place + // it can be checked rather than trusted. + #expect(v.packetSigning.packet.payloadIs.contains("\(encoded.count) bytes"), + "packet.payloadIs disagrees with the real payload length") + // 0x02 carries 000001a3185c5000 == 1_800_000_000_000 ms, not seconds. let decoded = try #require(CourierEnvelope.decode(encoded)) #expect(decoded.expiry == v.inputs.expiryMillis) @@ -302,6 +314,9 @@ struct CourierVectorTests { let a = try key.signature(for: preimage) let b = try key.signature(for: preimage) #expect(v.signature.deterministic == false) + // The published instruction must keep naming the field it points at, + // so renaming `signingPreimage` cannot leave it dangling. + #expect(v.signature.verify.contains("signingPreimage")) #expect(Data(a) != Data(b), "CryptoKit Ed25519 signing is randomized") #expect(key.publicKey.isValidSignature(a, for: preimage)) #expect(key.publicKey.isValidSignature(b, for: preimage))