shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/stories/databasev2/10-keypair-attach-auth.md
shoney.arickathil 566559cf70 docs: name the residency value keys, not index (review change) 
- `resident: all | keys` replaces `resident: all | index`. Two reasons beyond
  taste: it kills the collision with the `index:` argument
  (`@table(index: [customer], resident: index)` read badly), and it puts both
  values on ONE axis — each now answers "what row data stays resident",
  where `all`/`index` mixed a quantity with a structure name
- accurate as well as clearer: what stays resident is the id->offset map, the
  secondary indexes and the unique shadows — all key structures; row payloads
  are exactly what leaves. `resident: none` was rejected as overclaiming,
  since the indexes very much are resident
- checked for collisions: neither `all` nor `keys` is a keyword or a builtin
  (`key_at`/`val_at` exist, bare `keys` does not)
- the spec's wart note became a recorded decision; the rejected spelling is
  kept quoted so the rationale still reads
- fixes a bug I introduced in the 2026-08-26 track move: all six moved
  iterations carried a banner reading "Part of [Story — the database beyond
  RAM]" whose link pointed at the LANGUAGE arc — correct target, lying text,
  the exact failure mode the link audit warned about. Banners now point at
  the databasev2 story, and the original "Part of" line says plainly which
  track the iteration was authored in before the move
- linkcheck 0 broken / 0 anchors

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-26 22:47:24 +02:00

8 KiB
Raw Blame History

track iteration was_language_iteration status
databasev2 10 21 hold

databasev2 10 — keypair authentication for cross-program attach

Moved 2026-08-26 from the language track, where this was iteration 21. Part of Story — databasev2: the database beyond RAM. Content unchanged by the move; its dependencies are restated in that track index.

Format: product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary — the track this iteration was authored in before the 2026-08-26 move.

Inserted 2026-08-15. Promotes iteration 20's identity fork (Info, fork 3) to its own iteration: the name + unix-uid lean is the milestone bootstrap, and THIS is what replaces it — program identity is a keypair, and an attachment is granted to a public key, not to a process that happens to share a uid. It follows 20 (there is nothing to authenticate until attach exists) and stays same-machine; the same handshake is what a future remote channel would reuse, which is the point of doing it properly now.

No spec exists yet. The forks in Info are genuine decisions.

Goals

  • A program's identity is a keypair. Each writeonce program owns a private key (generated once, stored beside its data, never in the manifest) and a public key it can print/export. Identity stops being "whoever reached the socket first with the right uid".
  • Grants name public keys. A's [share] registers a client by its public key (fingerprint), with rights exactly as 20 defined them; B's [connect.a] pins A's public key beside the IPC string. Both sides authenticate: A proves it is A before B sends a byte of intent, B proves it is B before A executes a statement.
  • The handshake is mutual challenge–response, replay-proof: fresh nonces each attach, signatures over the nonce + channel binding, no secret ever crosses the channel. A failed handshake refuses the attachment with a catchable trap on the connecting side and one log line naming the offered fingerprint on the listening side.

Acceptance Criteria

  • What to achieve?
    • Given A's [share] registering B's public-key fingerprint with read+write, and B's [connect.a] pinning A's public key,
    • when B attaches,
    • then the mutual handshake completes, the attachment carries B's granted rights, and every 20 acceptance behavior (statements, traps, refusals) holds unchanged on top of it.
  • What to achieve?
    • Given a client presenting a keypair A never registered,
    • when it attempts the handshake,
    • then the attach is refused before any statement is read, the client sees the catchable authentication trap, and A logs the offered fingerprint (so granting it is a copy-paste, not an investigation).
  • What to achieve?
    • Given a same-uid process (the 20 bootstrap's whole trust basis) presenting no key or the wrong key,
    • when it attempts to attach,
    • then it is refused — proving the uid check has been superseded, not merely supplemented.
  • What to achieve?
    • Given an impostor listening on A's socket path (or a swapped socket file),
    • when B attaches and the impostor cannot sign A's challenge response with A's private key,
    • then B aborts before sending any statement or data, with a trap that names the fingerprint mismatch — the pinned-key check working in the B→A direction.
  • What to achieve?
    • Given a recorded handshake transcript from a legitimate attach,
    • when it is replayed against A,
    • then the attach is refused — the nonce is fresh per handshake and a signature over an old nonce proves nothing.
  • What to achieve?
    • Given A rotates B's registered key (manifest update + restart),
    • when B attaches with the old key and then with the new one,
    • then the old key is refused and the new one works — rotation is a config change, exactly like the grant itself.

Out Of Scope

  • Transport encryption. Same-machine unix sockets; the kernel is the wire. Session encryption (and the key exchange it needs) arrives with a remote channel, if one ever ships — this iteration's handshake is designed not to preclude it, nothing more.
  • Certificate hierarchies, expiry, revocation lists. A grant is a public key in a manifest; revocation is deleting the line and restarting. CA machinery has no workload here.
  • Key escrow / multi-key identities / agent forwarding. One program, one keypair.
  • Protecting the private key from a root attacker or from the program's own uid. File permissions (0600) are the boundary this iteration claims; anything stronger (TPM, keyring) is explicitly not promised.

Info

Forks the spec must settle:

1. Where does the crypto come from? The runtime is libc-only by doctrine, and hand-rolling signature crypto is the one wheel nobody gets to reinvent. The realistic options: vendor a compact, audited Ed25519 implementation (TweetNaCl-lineage, a few files, no allocation, no OS dependencies) into database/src/ or a new vendor/; or take libsodium as the first external dependency and break the doctrine openly. Leaning: vendored compact Ed25519, recorded as the single sanctioned vendored component with its provenance pinned in the tree — the doctrine's spirit is "no dependency sprawl", not "write your own constant-time field arithmetic".

2. Key generation and storage. Options: a woc keygen subcommand (keys are a toolchain concern), or first-boot generation by the runtime into the data directory (keys are a runtime concern, zero setup). Leaning: first-boot generation into WO_DATA (0600, alongside the WAL — a program with a persistent database already has the directory), plus a way to print the public fingerprint (program --identity or a stdlib call) so the operator can paste it into A's [share]. A program without WO_DATA has no identity and cannot attach anywhere — which is coherent: attach is a database feature.

3. What exactly gets signed. A bare nonce signature is vulnerable to cross-protocol reuse; the lean is signing a transcript hash: protocol tag, both fingerprints, both nonces, and the channel identity — so a signature from this handshake means nothing in any other context. The spec should write the exact byte layout down (the WAL encoding conventions apply: the format is normative, little-endian, versioned by the protocol tag).

4. Does the uid check survive at all? Options: keys only (one mechanism, one story), or keys AND peer-cred as defense in depth. Leaning: keys only — two mechanisms invite "it worked because of the other one" confusion in exactly the code that must never be confusing; SO_PEERCRED remains a log-line enrichment (who was that fingerprint), never an authorization input.

Proposed Solution

  • Brainstorm the spec settling the four forks, then fold the plan into 20's implementation plan as its authentication tasks — one plan, because 20 without 21 ships a placeholder identity and 21 without 20 has nothing to authenticate. The 20 milestone may still land first with the uid bootstrap, flagged loudly as pre-21.
  • Acceptance extends the 20 workload: the employee-A / employee-list-B pair (docs/examples/employee-list, pre-authored 2026-08-15) carries the key exchange in both manifests — A's [[share.clients]] names B's fingerprint, B's [connect.employee] pins A's; the acceptance script adds the wrong-key, no-key, same-uid-wrong-key, replay, impostor-socket, and rotation checks above, each asserting the exact trap/refusal.
  • Expected shape: handshake module beside the channel code (both ends), [share]/[connect] manifest keys for fingerprints, first-boot keygen in the runtime's data-directory setup, vendored signature primitive with its own unit suite (known-answer tests from the algorithm's reference vectors).