shoney.arickathil
566559cf70
- `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>
158 lines
8 KiB
Markdown
158 lines
8 KiB
Markdown
---
|
||
track: databasev2
|
||
iteration: "10"
|
||
was_language_iteration: "21"
|
||
status: 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](00-story.md). 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](../language-runtime-database/00-story.md)
|
||
> — 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).
|