Conformance vectors
Test vectors an implementation can check itself against. Each file is JSON with a description and one
or more cases. The conformance runner in ../examples/conformance loads and
checks every file here with Node’s crypto.
index.json is a machine-readable index of these files: each entry gives the file, its
kind (deterministic / rfc-primitive / composition / data / scenario / negative), the spec section, and the published
anchors, so a harness can enumerate the vectors instead of hardcoding filenames.
AVP 0.5 construction vectors (generated)
These pin the 0.5 byte constructions. They are derived only from fixed seeds (listed in each file under
seeds) by generate.ts, which owns them.
bip39-english.txt, the BIP39 English wordlist, a byte copy of the upstreambitcoin/bipsbip-0039/english.txt(2048 words, LF, trailing newline, SHA-2562f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda, checked bygenerate.ts --check).bip39-owner.json, the owner identity of SPEC §3.1: entropy to the 24-word mnemonic, the PBKDF2 seed (empty passphrase), and the HKDF owner Ed25519 and X25519 keys. Itsanchorsare three 256-bit cases of the Trezor reference vectors (trezor/python-mnemonicvectors.json, passphraseTREZOR), which pin entropy, mnemonic, and seed against an external implementation.manifest.json, a four-state owner-signed chain (genesis, add members, remove a member with a two-id frontier, policy flip) for SPEC §4.1 and §4.2: the CE bytesS, the owner signature,manifestHash, and the seq 1repoId. The wire lists are stored in descending order so an encoder that does not sort fails.commit.json, three commits (root, single parent, three-parent merge) for SPEC §4.3: the header bytes,commitId, author signature, AAD v2 bytes, and the AES-256-GCM ciphertext. Each commit cites amanifest.jsonstate; the removal frontier inmanifest.jsonnames two of these commits.
The CE constructions have no published anchor, so the runner also re-derives every case by a second, hand-written assembly of the SPEC layout (raw byte concatenation, independent of the encoder under test).
federation.json, the out-of-band tokens and addressing of SPEC §11 and the challenge transcript of SPEC §3.3. Unlike the others it uses top-leveltokens,leaves,linkCodes,fingerprints,uris, andchallengesrather thancases. Each token case (InviteToken,RepoLocator,LinkRequest,LinkGrant) is a decode oracle: base64url-decodingbase64urlMUST yielddecoded.canonicalJsonis the compact encoding with the fields in the SPEC order and"v": 2, andbase64urlis its base64url-nopad form; a decoder MUST accept any field order and whitespace and MUST reject avother than 2. The invite token’s acceptance is signed by the joiner’s home host overacceptanceMessageHex; eachleavescase is a leave request body (JSON, not base64url) signed by its member oversignatureMessageHex. The runner verifies both withnode:cryptoover a hand-assembled message.linkCodesare SPEC §11.6 confirmation codes (one has a leading zero),fingerprintsare the member and owner fingerprints, and the link grant’scheckerholds the link private key (never on the wire) and the owner entropy it unwraps to. Eachavp://URI case pins parse and format ofavp://<hostLocator>/<repoId>. Eachchallengescase pins the SPEC §3.3 transcript:messageHexisCE(tag "avp/challenge/v1", bytes(hostKey), bytes(ed25519PublicKey), bytes(nonce))over the raw nonce bytes, andsignatureis the signer’s Ed25519 signature over it (alice-to-a, a 32-byte nonce, andowner-to-b, a 64-byte nonce, from themanifest.jsonseeds). The runner rebuilds the message by hand, verifies the signature withnode:crypto, reproduces it from the seed, and shows it does not verify for the other host key or over the raw nonce.
Merge vectors (hand-written)
merge.json, the payload v2 merge of SPEC §5 and §5.1. Each case givesinputsand theexpectedmerge, written by hand from the SPEC rule (greatest(at, n, by)stamp per field and per ban server id,bycompared by UTF-8 bytes; greatestdeleted), andexpectedDeleted, the deletion state of each account. Merging the inputs in every order MUST giveexpected, mergingexpectedwith any input or with itself MUST giveexpected, and merge MUST be associative. WhenstripRefreshis true, the merged result is stripped ofrefreshTokenandexpiresAt(with their stamps) before comparing.hlcpins the hybrid logical clock: start atstart, apply eachtickorobserve, and the state after each step MUST equalexpect.
Host acceptance scenarios (hand-written verdicts)
-
acceptance.json, the host rules of SPEC §6, §7, §8.3, and §8.4 as replayable scenarios. The Rust and Java rule engines run this file unchanged. Its expectations are written by hand from the SPEC rule each scenario’sdescriptioncites; the signed items are built from themanifest.jsonseeds, plus one extra data key for epoch 2 (32 bytes of0x44) that only thecontent-epoch-jump-2scenario uses.{ description, scenarios: [ { name, description, description cites the SPEC sections hostKey, base64 Ed25519 key of the host whose view this is (a.vault.example) headBound, 16 steps: [ { op, via, label, item, expect } ], finalHeads: [commitId], base64, sorted finalHeld: [commitId], base64, sorted finalTip: manifestHash | null, base64 manifestHash of the winning chain's tip finalLeaves?: [{ memberKey, at }] optional: the pending leave requests, sorted by memberKey } ] }Each step:
opis"manifest","commit", or"leave".itemformanifestis{ manifest: SignedManifest, commit?: Commit }, thepublishManifestbody. The commit, when present, is the genesis commit (thecreateRepobody), the rotation commit of an epoch-raising state, or a commit that cites the new state; the state and its commit are applied together or not at all (SPEC §8.2, §8.3).itemforcommitis aCommit; forleave, aLeaveRequest. All in the HTTP/JSON wire form (base64 binary).viais the path the item arrived on."push"is a client write (push,createRepo,publishManifest,leave) whose authenticated caller is the commit’s author (the owner for a manifest and the commit carried with it,memberKeyfor a leave): the caller check of SPEC §7.1 and the head bound of §7.4 apply."offer"is an item in a peer host’s replicationoffer(SPEC §9.1): no caller check and no head bound.expectis"ok"or one of the SPEC §10.4 codesbad_request,forbidden,not_hosted,too_many_heads,manifest_conflict,missing_parents. A held commit (SPEC §6.5) answersforbiddenon either path.labelnames the item for readers and failure messages only.
After the last step, the host’s heads (accepted commits with no accepted child) MUST equal
finalHeads, its held commitsfinalHeld, and its tipfinalTip, compared as sets for the lists. A stored commit whose removal cutoff cannot yet be decided (SPEC §7.3) is in neither list.Two answers are host level, not engine verdicts, and no scenario pins them:
createRepofor arepoIdthe host already holds is409 duplicate_repo(SPEC §8.2, §12.3), and any operation on a repository the host does not hold is404 not_found(SPEC §10.1). A host answers both before it consults its rules engine, so the engine’s verdict type has neither code.not_hostedis an engine verdict only forvia: "push": a client write of a state whosehostsdoes not list this host (SPEC §6.1 rule 6). Forvia: "offer"it is host level, like the two answers above: the host validates the offer (and any catch-up) on a trial copy, checks that the validated received tip (the tip of the winning chain it would hold afterwards, SPEC §9.2) lists it, and otherwise answers the offer with403 not_hosted: for a repository it did not hold it discards the trial copy and stores nothing, and for one it holds it keeps the trial copy (SPEC §8.6). The engine therefore does not reject an offered state because it does not list this host, so a newly listed host can take the earlier states of the chain (SPEC §8.1); the offered steps of a scenario are items whose received tip passed that check. The engine reports whether its current tip lists this host, which the host uses for that check and to refuse to serve a repository whose tip does not list it (SPEC §8.6, §10.1).Whether a held repository is not hosted (SPEC §8.6) is a function of the engine’s winning tip, not a separate marker: the host does not serve the repository, and refuses client writes for it, exactly while the tip does not list it. A host that holds a repository adopts a validated state that drops it, from a client publish (whose answer is still the engine’s
not_hosted, which the shared scenarios pin) or from an offer, so its tip can stop listing it; it is hosted again when the tie rule and later states give it a winning tip that lists it (SPEC §6.5). No scenario pins this host-level keeping: the engine itself does not adopt a pushed state it answersnot_hosted(somanifest-drops-this-hostends at genesis), and the host that already holds the repository keeps such a state by applying it to its engine again withvia: "offer", together with its rotation commit only (no commit when the epoch is unchanged), never with a carried non-rotation commit, since the offer path skips the client caller check and the head bound. AcreateRepogenesis answerednot_hostedstores nothing.
Cryptographic primitive vectors (RFC-anchored)
Each primitive AVP relies on is pinned to a published RFC test vector, so a conformant implementation reproduces a known-good output and cannot drift on the primitive itself:
hkdf.json, HKDF-SHA256 (RFC 5869). Casesrfc5869-tc1(RFC 5869 Appendix A.1) andrfc5869-tc3(Appendix A.3, the zero-length-salt case that exercises the empty-salt → 32 zero bytes rule). Each case givesikmHex/saltHex/infoHex/lengthand the expectedprkHex(extract step) andokmHex(expand step).x25519.json, X25519 ECDH (RFC 7748), raw 32-byte little-endian keys, unhashed shared secret. Casesrfc7748-vec1andrfc7748-vec2are the RFC 7748 §5.2 single-iteration vectors;rfc7748-dhis the RFC 7748 §6.1 Diffie-Hellman example. Note: RFC 7748 prints thevec2input u-coordinate with its most-significant bit set; RFC 7748 §5 requires masking that bit before decoding, and the committed value is already masked so every conformant decoder (whether or not it masks internally) agrees byte-for-byte. Therfc7748-dhkeypairs (Alice = recipient, Bob = ephemeral) are reused bykey-wrap.json, anchoring the wrap composition’s shared secret to a published vector.ed25519.json, Ed25519 sign/verify (RFC 8032), raw 32-byte keys. Casesrfc8032-test2andrfc8032-test3are the RFC 8032 §7.1 vectors. The runner derives the public key from the seed, reproduces the (deterministic) signature byte-for-byte, and verifies it.
Composition vectors (three-way cross-verified)
This exercises the default wrap scheme (SPEC §4.4). They embed fixed keys/IVs so they are reproducible, and their correctness is established by three independent sources agreeing byte-for-byte (see “Three-way verification” below):
key-wrap.json, the default wrap schemeX25519-HKDF-SHA256-AESGCM-v1:sharedSecret = X25519(ephemeralPriv, recipientPub);KEK = HKDF-SHA256(ikm=sharedSecret, salt=ephemeralPubRaw, info=UTF8("avp/rdk-wrap/v1"), L=32);wrappedCiphertext = AES-256-GCM(KEK, iv, aad=UTF8("avp/rdk-wrap/v1"), plaintext=dataKey)with the 16-byte tag appended. TheWrappedKeyon the wire is{schemeId, ephemeralPublicKey, iv, ciphertext}; the case additionally carriesrecipientPrivateKeyB64(not part of the wire format, only so a checker can unwrap) plus the intermediatesharedSecretHex/kekHexfor cross-reference. The recipient and ephemeral keypairs are the RFC 7748 §6.1 Alice and Bob keypairs, so the shared secret equals the published RFC 7748 §6.1 value. The runner recomputes the shared secret and KEK, re-wraps and asserts equality with the committed ciphertext, and unwraps and asserts data-key recovery.
Three-way verification
The composition vectors are public and must not contain mistakes, so each was confirmed by three independent sources agreeing byte-for-byte before being committed:
- Published RFC test vectors, every primitive carries at least one published anchor: HKDF-SHA256 from RFC 5869 (Test Cases 1 and 3), X25519 from RFC 7748 (§5.2 vectors and the §6.1 DH example), and Ed25519 from RFC 8032 (§7.1 TEST 2 and TEST 3). The composition vectors are anchored to RFC 7748 §6.1 via the wrap keypairs. The Node runner reproduces every published output exactly.
- The reference implementation (Java), the
lol.trq.altscrypto primitives independently agree with every vector: its HKDF and X25519 reproduce the primitive outputs, it verifies (and reproduces) the Ed25519 signatures, and itsX25519HkdfAesGcmKeyWrapunwraps the key-wrap vector and recovers the data key. This was verified with a throwaway harness against the library’s compiled primitives. - The Node conformance runner, reproduces every primitive output and round-trips every composition
vector (decrypt/unwrap and assert recovery) with Node’s
crypto; see the runner’sREADME.md.bun run testmust pass.
An implementation proves conformance by reproducing the deterministic and RFC-anchored vectors exactly, and by round-tripping the composition vectors (decrypting/unwrapping what a peer encrypted/wrapped, verifying what a peer signed).
The 0.5 construction vectors (bip39-owner.json, manifest.json, commit.json) are verified by the
Trezor BIP39 reference vectors and the RFC-anchored primitives, by the Node runner, and by the runner’s
second, hand-written assembly of every CE layout; the rebuilt Rust and Java references reproduce them
byte-for-byte as their third source.
Negative vectors
negative.json, a bank of MUST-reject cases. Each case starts from a valid construction and applies one mutation. From the seeds ofkey-wrap.jsonanded25519.json: a flipped GCM tag, a flipped body bit, truncation, a wrong recipient or ephemeral wrap key, a wrong message, or a wrong public key. From the 0.5 items ofmanifest.json,commit.json, andfederation.json: a manifest with a bad or foreign owner signature, a validly signed manifest with a wrong previous hash, a commit whose id no longer recomputes (tampered ciphertext or header), an author signature over another commit id, a payload decrypted under AAD v2 with a wrong parent set, epoch, author, or repoId, a link grant unwrapped with the data key wrap labelavp/rdk-wrap/v1, an acceptance verified under another host key or with a tamperedexpiresAt, and a leave request signed by another key. The last sixed25519-verifycases are the strict verification rejects of SPEC §2, which a cofactorless verifier (the JDK’s, or OpenSSL’s under Node) accepts: forgeries withR= identity andS= 0 under the identity key, under an order-8 key, and under the non-canonical identity encodingy = p + 1, an honest key’s signature whoseRis the identity, a valid signature withLadded toS, and a forgery under the same order-8 key with its sign bit set (..03fa), whoseRis an honest point[r]B(the public key of the seed0x08 00..00) andS = r, so only a blocklist that masks the sign bit rejects it. They carry nobase; the runner shows instead that a verifier without the strict checks accepts each. The fivechallenge/cases come after them, at the end of the bank, and pin domain separation (SPEC §3.3, §4.1): alice’s challenge signature toa.vault.examplepresented as thecommit.jsonsingle-parent author signature, once with the commit id as the nonce and once with the whole 54-byte commit-sig message as the nonce (commit-verify); that commit’s author signature presented as a challenge signature for a nonce equal to its id, a challenge signature made forb.vault.example’s host key, and a signature over the raw nonce, the old construction (challenge-verify, which verifies undered25519PublicKeyover the transcript built withhostKey). A conformant implementation MUST reject every case; the description lists what eachopmeans. Each 0.5 case also carriesbase, the fields that restore the valid construction, which MUST be accepted, so the one mutation is shown to be the cause. Passing the positive vectors is not enough; an implementation that accepts a tampered input is not conformant. Wire base64 strictness is implementation-specific and is intentionally not tested here.
gRPC encoding vectors (generated)
grpc.json, the gRPC client profile (SPEC §10.3): one case per request and reply message of theavp.Vaultservice. Each case hasmessage(the fully qualified proto name, for exampleavp.PushRequest),json(the full form: every scalar field present with defaults included, repeated fields as arrays, absent message fields omitted, in the camelCase names of the HTTP/JSON profile), andprotoHex, the proto3 binary bytes in the canonical encoding: fields in ascending field number, scalars at their proto3 default and empty repeated fields omitted, absent message fields omitted, no packed encoding (no packable fields exist). The bodies are the worked examples in../examplesand values frommanifest.json,commit.json, andfederation.json; nothing is random. A checker decodesjsoninto its message type, encodes it, and compares the bytes, then decodesprotoHexand compares the full form. Proto3 encoders differ on whether they write an explicitly set default (protobufjs does), so build the message from the minimal form (defaults and empty arrays dropped) when your encoder writes them. The Node runner (protobufjs) and the Rust reference host (prost) reproduce every case independently.
Regenerating the vectors
grpc.json is not owned by generate.ts. It is derived from the proto and the files above by
../examples/conformance/scripts/grpc-vectors.ts:
--write regenerates it and --check asserts the committed file is current. The conformance runner’s
grpc.test.ts asserts the same, so bun run test fails on drift.
generate.ts is the reproducible derivation of these files. It reuses the vector-tested
reference crypto so it cannot drift from the runner.
bun vectors/generate.ts --checkre-derives every committed positive vector’s value fields from its documented seeds and asserts the committed file matches, checks the wordlist hash and the Trezor anchors, then assertsnegative.jsonand the 0.5 files equal the generator’s output. This is the provenance and drift gate; CI runs it. It does not rewrite the RFC-anchored and cross-verified positive files (their reviewed prose and formatting are preserved).bun vectors/generate.ts --writeregenerates the files the generator owns:negative.json,bip39-owner.json,manifest.json,commit.json,federation.json,merge.json, andacceptance.json. The expected values ofmerge.jsonandacceptance.jsonare literal data in the generator, written from the SPEC; only their signed inputs are derived from seeds.