Test vectors

Every implementation of the protocol, the relay and the four SDKs included, tests against one file of known answers: spec/vectors.json in zerobyte-protocol.

Where it comes from

The file is produced by spec/vectors.py, an independent reference implementation that:

• uses only the Python standard library;
• writes out ChaCha20, Poly1305 and the AEAD construction from RFC 8439 and checks them against the RFC's own test vectors (§2.5.2 and §2.8.2) before writing anything;
• implements HKDF from RFC 5869 over hmac and hashlib;
• shares no code with any SDK or the relay.

python3 spec/vectors.py > spec/vectors.json

Implementations copy the file into their test resources. They never generate it from their own code: a vector produced by the implementation under test proves nothing. To change a vector, change vectors.py, review the diff of vectors.json, and copy the result into every SDK.

Structure

{
  "protocol": "zerobyte-relay-v1",
  "note": "...",
  "labels": { "mailbox": "...", "token": "...", "p2c": "...", "c2p": "..." },
  "credentials": [ ... ],
  "envelopes": [ ... ],
  "rejections": [ ... ],
  "wire": [ ... ],
  "wireRejections": [ ... ]
}

Byte strings are lowercase hex. Sequence numbers are decimal strings, because they can exceed the range JSON numbers represent exactly.

credentials (2 sets)

Test: derive from linkKey and linkId, compare every field.

envelopes (4 cases)

Test both ways: sealing with the given nonce must produce envelope byte for byte, and opening envelope must return plaintext and sequence.

rejections (10 cases)

Test: opening must fail with exactly error. The cases cover a flipped tag byte, a flipped ciphertext bit, a renumbered sequence, another link's keys, a direction byte changed to match the reader, an envelope read in the wrong direction, a replay, an unknown version, an envelope shorter than 38 bytes and an unknown direction byte.

envelopes coverage

The four envelopes cover both directions, an empty plaintext, a plaintext of 516 bytes, sequence 256 (a carry into the second byte) and the largest sequence, 2^64 - 1.

wire and wireRejections

wire pairs lists of envelopes with the expected fetch body; test both join and split. wireRejections lists bodies that split must refuse, each with a why.

Running the tests in each repository

Every SDK also has tests against a live relay. They run when two environment variables are set:

RELAY_BASE=http://127.0.0.1:8080/v1/ RELAY_APP=<registered app id> <test command>