04. Keys and custody

Draft 0.1. Reference implementation: shared/ed25519.js, shared/familySigning.js, shared/vaultEnvelope.js, frontend/src/services/webCrypto.js, frontend/src/services/vaultCloudSync.js, frontend/src/services/vaultEnvelopeClient.js, frontend/src/services/vaultKeyCustody.js, api/vault-key.js, frontend/src/utils/receiptSignature.js, api/verify-receipt.js (loadIssuerSignature), supabase/SIGNED_RECEIPTS_V1_PHASE_A.sql, supabase/V42_ZK_FAMILY_KEY_WRAPS.sql, docs/H1_STAGE2_ZERO_KNOWLEDGE_ADR.md. Vectors v09, v10, v11.

4.1 Two kinds of key, three signed artifacts, three contexts

Every context prefix is distinct and frozen (gate-tested). A signature MUST be verified with its context prepended; a signature over the bare message MUST NOT verify (vector v11). This is what stops a receipt signature from being replayed as a tree head, or a countersignature as a family signature.

All keys are Ed25519. Public keys are exchanged as JWK {kty: "OKP", crv: "Ed25519", x}. Signatures are 64 raw bytes rendered as 'z' + base58btc(bytes).

4.2 The organization key

• Public JWK x = Oo09J95ausJIDH4nnNNy6wfKgveRbGgDsX9V3Y0xyMQ, served in the DID document at /.well-known/did.json as verification method did:web:eformogi.com#key-1 (type JsonWebKey2020) and embedded in the reference verifier.
• Per the setup runbook (docs/ANCHORED_LEDGER_SETUP.md, step 1) and the source comment in shared/ed25519.js, the private half lives only in the deployment environment (VC_SIGNING_PRIVATE_KEY) and the founder's password manager, with the key ceremony recorded as performed on 2026-07-05. This draft reports that record; it has not been independently verified.
• Drift guard. Before every signing operation the implementation derives the public key from the private key and refuses to sign unless it equals the published x (loadPrivateKey). A rotated or wrong private key can never silently sign under the published identity.
• Rotation: planned. There is no second published key and no rotation statement format yet. The anchored ledger (chapter 05) means pre-rotation tree heads stay verifiable against the old key and a forked history is detectable from third-party git timestamps; the rotation procedure itself (new #key-2, signed rotation statement in the anchor repository) is unbuilt.

4.3 The family key

Minted on the family's first publish after family signing is enabled (EFG_SIGNED_RECEIPTS=1); flag off means no keys are read or written and receipts publish unsigned.

Signing (signPublishedReceipt): after a receipt row is inserted and its leaf appended to the log, the implementation signs 'eformogi-receipt-sig-v1:' + <leaf payload> (chapter 02, section 2.5) with the family key and stores issuer_sig, issuer_key_id, sig_alg: "Ed25519" on the receipt row. The signature binds the same bytes the log anchors, so signer and log can never disagree about what was signed. The signature columns are outside every hash domain.

Rules (MUST):

• No self-heal. If a stored key fails to unwrap (KEK drift, corruption), the implementation publishes unsigned and alerts; it MUST NOT mint a replacement over the old identity. A silently swapped signing key is an identity break, strictly worse than a missed signature. Recovery is a human decision.
• Best effort, never blocking. A signing failure MUST NOT fail, slow, or reshape a family's publish.
• Guest publishes are never signed (no account, no key).
• publish-attestation is deliberately not family-signed; the witness model is chapter 03.
• Rotation: planned (gap: no family signing-key rotation path; a new key would need a new kb_ and a signed link from the old key). Recovery: because the seed is escrowed the family cannot lose it; that is the trade escrow makes, stated in section 4.7.

4.4 The kb_ key binding

Minting a family key appends a public receipt establishing it. The payload is frozen (vector v09):

{"established_at":"2026-07-17T00:00:00.000Z","key_id":"did:key:z6MkiPpc1FZaVEji99SsAa5GyfGprgJVgfpQCVcoZQyBxv2X","public_jwk":{"crv":"Ed25519","kty":"OKP","x":"Oo09J95ausJIDH4nnNNy6wfKgveRbGgDsX9V3Y0xyMQ"}}

kb_ id = kb_ + first 12 hex of sha256(canonical payload); the vector above yields kb_b5ed898815ac. The row lives in key_binding_receipts (no PII by construction), resolves at /verify/kb_<id> with custody: "escrowed_by_eformogi", and is logged like any other receipt, so a swapped or backdated key would be publicly visible. kb_ receipts are never revoked.

4.5 What a receiver can check in the browser

The verify payload for a signed receipt carries (issuer_signature):

The receiver's browser, not the operator, does the math (receiptSignature.js): it fetches the exact leaf bytes from /api/receipt-proof (served even while the leaf is still pending a tree head), falls back to reconstructing the leaf locally for ws_/wn_/tr_ (whose payload issued_at is byte-exact with the leaf), imports public_jwk with WebCrypto, and verifies. Verdicts MUST be rendered honestly:

An unsigned receipt renders: "Not signed with a family key. This receipt verifies by integrity alone."

4.6 Vault custody: escrow versus family-held

The published receipts are public by design. The private vault behind them is a separate custody question with three layers, each with its own wire prefix:

The Stage-1 to Stage-2 move re-wraps the DEK; the vault ciphertext never changes (no second data migration). The per-family cutover (POST /api/vault-key, action cutover) MUST refuse unless all of: an explicit confirm string, a passkey wrap on file, a recovery wrap on file, and a verified readback of the recovery code. On cutover the server overwrites its own wrap with the tombstone zk-removed and sets server_wrap_removed_at; from then on GET /api/vault-key returns zk: true and blobs the server cannot open, and the cloud sync HOLDS writes (never plaintext) while the family's key is locked.

Rotation after cutover (rotate-wraps) replaces both wraps and is authorized only by a timing-safe match of the current recovery code's one-way verify tag; the tombstone is never touched. Recovery is the recovery code, unwrapped on device; the code never leaves the browser. A family that loses both its passkey and its recovery code has an unrecoverable vault, by anyone, including the operator, and the security page says so.

4.7 The honest claims, exactly

The verify page states the per-family vault fact only when the server proved it, keeps the escrow caveat next to it, and says "when key custody moves to families, this page will say so."

4.8 What this does not prove

A valid family signature proves that the escrowed key bound to this family's account signed these leaf bytes when the operator's infrastructure published them. Because custody is escrow, it does not prove the family personally authorized that exact signing operation; it proves the operator signed under the family's identity as part of a publish the family initiated. A kb_ proves when a key was publicly established, not who controls it. The organization key proves the operator's infrastructure signed, not that the operator vouches for any claim inside the receipt.