Architecture Decision Records
- 0001: Assume ciphertext is public forever - accepted
- 0002: Native modern cryptography with pluggable identity backends, not GPG - accepted
- 0003: Envelope encryption with epoch KEKs and derived per-event DEKs - accepted
- 0004: Write-once, content-addressed repository layout - accepted
- 0005: Causal DAG ordering with hybrid logical clock tie-break - accepted
- 0006: Signed events and a signed policy chain: integrity, not prevention - accepted
- 0007: Membership changes are additive; revocation is a new epoch plus rotation - accepted
- 0008: Members are sets of device keys; Signal-style device linking - accepted
- 0009: Key protection tiers and recipient types - accepted
- 0010: Storage backends are dumb, immutable blob stores - accepted
- 0011: The agent daemon owns key material; transports and the relay - accepted
- 0012: AI agent sessions may run and inject, never read - accepted
- 0013: Go monorepo with a shared core and native shells - accepted
- 0014: Licensing and commercial model - amended (see "Amendment: license revocation list" below)
- 0015: Web origins and the hosted service - accepted
- 0016: Cloud is a product-agnostic relay - accepted
- 0017: Two-phase revocation fold - superseded by [0046](0046-linear-policy-chain.md)
- 0018: CLI framework: cobra - accepted
- 0019: The git backend shells out to git - accepted
- 0020: In-process unlock until the daemon - superseded by [0028](0028-agent-daemon-process-and-wire-protocol.md)
- 0021: Cloud wire protocol foundation and module configuration - accepted
- 0022: Interactive prompts with Huh on the controlling terminal - accepted
- 0023: Relay authentication, pairing and forwarding wire - proposed
- 0024: Local Windows verification via a UTM ARM64 VM over SSH - accepted
- 0025: Blob wire frames, the sync endpoint and the client module boundary - proposed
- 0026: Operations and self-hosting - accepted
- 0027: Primary domain: vaultfold.app - accepted
- 0028: The agent daemon process, local transport and wire protocol - accepted
- 0029: Agent daemon sessions, approvals and purpose-scoped policy - accepted
- 0030: Agent detection by independent, cited signals - accepted
- 0031: macOS: a Secure Enclave key for the OS keychain tier, a helper app for dialogs, cgo isolated - accepted
- 0032: Windows: Windows Hello through the Passport key storage provider, DPAPI without Hello - accepted (pending verification on Windows hardware); amended
- 0033: Linux: the freedesktop Secret Service for the OS keychain tier, logind for locking, zenity or kdialog for approvals - accepted
- 0034: Namespace takedown fails closed on the tombstone; a seat change re-signs the single license - accepted
- 0035: One agent daemon pipe per profile on Windows - accepted
- 0036: Windows semantics for POSIX-shaped contracts - accepted
- 0037: Cheaper git open, and a test-only Argon2id memo - accepted
- 0038: Daemon clients verify the endpoint they connect to - accepted
- 0039: Local-first release with GoReleaser, minisign, a cask and an npm shim - accepted
- 0040: Website stack, analytics, security headers and the launch gate - accepted (the maintainer confirmed the analytics decision on 2026-10-19)
- 0041: In-repo vaults sync on a dedicated branch - accepted
- 0042: Member rename record and client-side name uniqueness - accepted (member-roles-and-rename archived 2026-10-30)
- 0043: Role reductions bind policy records - superseded by [0046](0046-linear-policy-chain.md)
- 0044: Exposure audit after revocations - accepted
- 0045: A 512 byte cap on enc_name and a 252 byte bound on names - accepted (cap-enc-name-size archived 2026-10-30)
- 0046: Linear policy chain - accepted
- 0047: Native messaging and a thin signed host reach the daemon - accepted (add-browser-extension archived 2026-10-30)
- 0048: Passkeys by page-world interception, with OS providers as a separate path - accepted (add-browser-extension archived 2026-10-30)
- 0049: The daemon is the only origin-matching authority - accepted (add-browser-extension archived 2026-10-30)
- 0050: Early-access launch: a waitlist by email and roadmap claims - accepted (the maintainer decided on 2026-10-31; implemented by `launch-site-mvp`)
- 0051: The folded-paper visual identity and scripted product recordings - accepted (the maintainer chose the direction on 2026-11-01 and approved the preview on 2026-11-15, `restyle-site-folded-paper` task 5.3)
- 0052: Epoch wraps keyed by the calling link - accepted
- 0053: One owner per task group, with verification scaled by risk - accepted (the maintainer chose this on 2026-11-14)
- 0054: Scope of 1.0 and the milestones to it - accepted (the maintainer ruled on 2026-11-15)
- 0065: The waitlist form and its function - accepted (the maintainer asked for the form on 2026-11-16; the orchestrator's rulings of 2026-11-16 and the approved `waitlist-form` proposal)
Open decisions
These were decided unilaterally while the records above were drafted and are recorded here so a human can confirm or overturn them.
- BLAKE3-256 as the content hash (hash suite 1).
- HKDF-SHA-256 for all key derivation.
- Canonical CBOR per RFC 8949 section 4.2.1 as the signed and hashed encoding.
- ECIES over NIST P-256 for the
p256recipient type. - ECDSA P-256 with SHA-256 for signatures by
p256(hardware) device keys. - Decided (ADR 0029): the default approval TTL is 8 hours.
- Decided (ADR 0029): the default approval scope is the collection of the first request in a session.
- The recovery key is an ordinary device key whose private half is Shamir-split, rather than a separate recovery mechanism.
- S3 put-if-absent implemented with a conditional write (
If-None-Match). - Epoch wraps nested per collection, and (decided, ADR 0052) under the
link that calls for each wrap:
epochs/<collection-id>/<epoch>/<link>/<keyid>.wrap,<link>the first 16 hex characters of that link's id. - Entry ids are random 128-bit values and the path is a mutable attribute.
- Decided (ADR 0046): policy files are stored unsharded at their slot
path
policy/<seqno>.pol, the seqno as 20 zero-padded decimal digits. - Decided: the v1
fileentry type is capped at 64 KiB; chunked attachments are deferred to a later change. - Deferred: forward secrecy via one-time pre-keys (v2;
prekeyrecipient type 4 is reserved and refused by v1).
See also ../threat-model.md.