🤖 Golden vectors — the cross-language crypto contract

contra-v1.json is the reference for every derivation in PROTOCOL.md.

CONTRA implements the same crypto three times: Go on the instance, JavaScript in the console, Swift on the Mac. They must produce identical bytes. All three suites pass this one file, or the contract is not being kept — a second implementation that passes vectors of its own has proved nothing, and cross- platform KDF drift is the bug class behind the 1Password PRF mismatch that shaped our whole recovery design.

Changing a value in this file is changing the protocol.

What it pins

Argon2id at m=64MiB, t=3, p=1; all five contra/v1/* HKDF labels; the KCV construction; P-256 derivation from a seed, including a seed that forces the rejection branch; Crockford Base32 with the O→0 and I/L→1 mappings; the 20-bit checksum and a single-substitution repair; AES-256-GCM with its AAD binding. account_chain is the whole hierarchy end to end, so a new implementation can bisect where it diverges rather than staring at one wrong key.

The wire formats PROTOCOL.md leaves open — HKDF mode, the AAD layout, Crockford packing, the rejection loop — are pinned in discussion 19. Read that before implementing against this file.

Where the numbers come from

The generator is gen/gen.c, C against OpenSSL — deliberately not Go.

Generating vectors from an implementation and then testing that implementation against them proves only that the code agrees with itself. So the vectors come from an implementation nobody here wrote, and the Go package is only ever the thing under test. If you are ever tempted to regenerate this file to make a test pass, stop: that is the exact failure the arrangement exists to prevent. Fix the code, or argue on the record that the spec is wrong.

gen.c also re-computes published third-party vectors — the PHC Argon2id reference outputs, RFC 5869, RFC 4231, NIST CAVP AES-GCM — and aborts if any disagrees. Otherwise "independent" would only mean the two implementations are not the same, not that either is right.

Every input is generated from its own published label:

fixture(label, n) = SHA-256("contra/v1/vectors/" || label)[0..n]

so the file regenerates from the source alone, and nothing in it is, or may be reused as, a real secret (AGENTS.md decision 8).

Regenerating

cd gen && make vectors

REJECT_K in the Makefile is the seed witness that forces a P-256 rejection. It is pinned rather than searched each time because finding one costs a few billion HKDF evaluations — a rejection is a ~2^-32 event. If the contra/v1/ec-p256 label ever changes, the witness dies with it: run make search (minutes, all cores) and pin the new k.

Verifying the Go side

go test ./internal/contra/crypto/

The suite has been mutation-checked: lowering the Argon2 time cost, typoing an HKDF label, truncating the KCV, dropping the AAD length prefixes or its domain tag, skipping the rejected EC candidate, accepting non-zero Base32 pad bits, widening the checksum, and dropping the O/I/L mappings each turn it red. A vector nobody has watched fail is a vector nobody should trust.