carlos / contra Public

🤖 Two more wire formats, pinned while building web/3 (#9). Same terms as the rest of this thread: cheap to reverse now, expensive once a second client exists.

7. What a client signs to prove possession

DESIGN.md says sign-in is a signed challenge and does not say over what. Signing the raw challenge bytes would leave the signature replayable into any other ceremony that ever uses ECDSA over the same key. Chosen:

signed = "contra/v1/login-challenge" || 0x00 || branch || 0x00 || challenge

ECDSA-SHA-256 over that, r || s raw (64 bytes), not the ASN.1 wrapper — WebCrypto emits raw, and asking the browser to re-encode would be inventing work for the one client that has the least room for it.

The branch is bound in, not merely checked alongside. A challenge issued for the recovery credential must not be spendable on the passphrase one, and a check beside the signature is one refactor away from being dropped while the signature still verifies.

The challenge itself is 32 random bytes, single-use, and spent whether or not the signature was good — a challenge that survives a failed attempt is a challenge an attacker can grind against.

8. The client mints the account id and every wrap id

Not a preference. It is forced, and it was forced by a bug.

The client seals each wrap under an AAD binding (account_id, object_type, wrap_id, version) — before the server has seen any of it. When the server minted those ids itself, every wrap it stored was bound to identifiers the client had never seen: a row that decrypts for nobody, ever, discovered only when somebody eventually tries to unlock.

So both ids come from the client, like every other id in this protocol. Collisions are refused by the primary key, and a client choosing an existing account's id gets a conflict rather than an overwrite.

This also retires a placeholder: signup had been sealing against sixteen zero bytes because the account id did not exist yet. That was a weaker binding recorded as a known gap, and it is now closed rather than deferred.

How it was found is the part worth keeping. The Go tests did not catch it, because they built the request struct by hand and so agreed with themselves. It surfaced the first time the real browser module talked to the real deployment. Neither implementation was wrong on its own; they disagreed about who owned an identifier, and only running one against the other could say so. That is an argument for driving the real client against the canary before calling any item done — a golden-vector suite cannot see this class of bug, because it is not a derivation, it is a contract.

9. Argon2id in the browser is written, not vendored

m=64MiB, t=3, p=1 is the one derivation WebCrypto cannot do. The choice was vendoring a .wasm or writing Argon2id out. Chosen: written, ~290 lines against RFC 9106, because a third-party binary blob in a password manager is unreadable in review and "no build step" is a stated constraint that vendoring quietly breaks.

Verified against OpenSSL 3.5 on nine parameter sets and against the published PHC reference vector. 64 MiB at t=3 takes ~1.7s in node and ~2.0s in the signup ceremony on the canary.

Rejected: p > 1, permanently. Argon2id's output depends on p, WASM without SharedArrayBuffer cannot parallelise, and any other value would break byte-identity with Go and Swift. Both the client floor and the Argon2id entry point refuse it.

🤖 One more, from web/4 (#10).

10. The kit carries the account id, not the blind index

DESIGN.md says both documents carry "the account's blind-index handle". They cannot, and the reason is a decision this thread already records rather than a gap: the blind index is an HMAC under a pepper the server holds and the browser deliberately never sees. The kit is generated in the browser and must never touch the server, so the value simply is not available where the document is made.

The server could send it — the blind index is not secret — but that is a round trip and a new endpoint to serve something that identifies the account no better than what the browser already has.

Chosen: the account id's first eight hex characters, formatted XXXX-XXXX. It is already a random UUID that identifies nothing by itself, it is on both documents, and it answers the only question the handle exists to answer: which account is this sheet for? — for somebody holding two kits from two accounts, years later.

If the blind index specifically is wanted on the paper, say so and it becomes a field on /auth/salt or /api/bootstrap. I did not add one for a cosmetic difference.

11. The printed documents are ASCII, and the writer enforces it

Not a style preference. The kit embeds no fonts — it uses the base-14 fonts every reader already has, which is what keeps the PDF writer small enough to read — and those have no glyph for a curly quote or an em dash in this encoding. A document that renders "don't" as "donOt" is not one to hand somebody at the worst moment of their year.

So pdf.js refuses a non-ASCII character rather than drawing the wrong one, and the kit copy uses - and '. Worth knowing before anybody edits that copy and wonders why it throws: the constraint is real, and the alternative is embedding a font subset, which is a much larger piece of code in the one place we are trying to keep readable.

🤖 One divergence from DESIGN.md, found by using the thing.

12. The kit is saved by two buttons, not one

DESIGN.md: "Signup generates both and offers a single print both action, so it stays one gesture, and does not let the user past until both are confirmed."

The single action does not work. Browsers refuse a second programmatic download from one user gesture — Safari refuses it silently — so the button downloaded the Account Key card, did not download the Recovery sheet, and reported success. Paul hit it on the first real run: "'Save both documents' only appears to have downloaded one file."

That is the worst possible failure for this particular screen. The recovery code is shown once and stored by nobody, so a save that silently half-works loses the only copy of the only thing that can open the vault, at the exact moment the interface says everything is fine.

Changed to one button per document, each marking itself saved once clicked. The "does not let the user past until both are confirmed" half is unchanged.

Why this is also the better shape

The single gesture existed to keep the ceremony feeling like one act. But the whole argument for two documents is that they belong in two different places — the card stays reachable, the sheet gets archived — and an interface that hands them over as one action quietly argues the opposite. Two buttons make the split visible at the moment it matters.

So the constraint and the design point the same way, which is lucky rather than clever: if browsers had allowed the double download I would have shipped the weaker interface.

Two smaller ones from the same run

The kit is its own screen. It was rendering into the passphrase form's status box, so the fields you had just typed sat above the recovery code you were meant to be reading. The passphrase step, a working screen, and the kit are now three screens with one visible at a time.

They cannot be three URLs, and the reason is the same reason the kit is fragile: it exists only in memory. A redirect between choosing a passphrase and seeing the kit would be a redirect that throws it away.

There is a working screen. Creating a vault is two seconds of deliberate Argon2id plus two round trips, and the only sign of life was a greyed-out button. It now names each task as it starts, driven by the crypto module's own progress messages rather than by a timer — a progress list that is really a timer is a lie with a spinner on it.