Architecture decision records
ADR-1 — One cryptographic suite on P-256. The Secure Enclave only supports P-256; choosing it everywhere gives hardware-bound device keys on Apple devices and non-extractable keys in browsers with a single protocol and a single set of vectors. HPKE (RFC 9180) is used instead of a home-made ECIES.
ADR-2 — No master password. Unlock is "device key + local user presence"; recovery is a 256-bit recovery key. This removes password guessing, Argon2 parameter calibration across platforms and an extra dependency. Trade-off: the recovery kit must be kept; there is nothing to "remember".
ADR-3 — Dependencies. TypeScript: @hpke/core (RFC 9180 over WebCrypto), @simplewebauthn/server and
/browser, fastify, postgres, zod, react, qrcode, tldts (Public Suffix List). Everything else is
WebCrypto / Node built-ins. Swift: CryptoKit, AuthenticationServices, LocalAuthentication, Security, SQLite3 —
no third-party package.
ADR-4 — Backend: TypeScript on Node 26, Fastify 5, PostgreSQL 17, encrypted attachment chunks on local disk.
Matches the cluster's conventions (mld, PM2, MacLustr Tunnel + Caddy TLS on BHS64). The server never links the
protocol's decryption code; it validates envelope shape only.
ADR-5 — One process, modular services. services/api hosts auth, sync, attachments, relay, audit and
notifications (SSE) as modules. services/managed-secrets is a separate process, separate database role and
separate key, bound to loopback; the API talks to it over a local socket. Splitting sync/notifications into
separate daemons would add operational surface without a security benefit at this scale.
ADR-6 — Monorepo, one git repository (sp-vault.git on spbgit). The deployed directory on the node is a
clone; Apple targets live in apple/ and are built on the laptop (cluster rule: Apple apps are the laptop exception).
ADR-7 — Native apps are native. SwiftUI + AppKit/UIKit where needed; the protocol is re-implemented in Swift on CryptoKit and locked to the TypeScript implementation by shared vectors and by cross-client integration tests against a real server. No WebView, no bundled JavaScript engine.
ADR-8 — Web unlock. The browser holds non-extractable device keys in IndexedDB. The ARK envelope is released by the server only after a fresh passkey assertion with user verification, then decapsulated locally. Locking drops ARK from memory. The web client is documented as lower assurance (THREAT_MODEL T2).
ADR-9 — Conflicts. Server-side optimistic concurrency per record; on conflict the client keeps both versions (server version current, local version stored as a conflict copy) and asks the user. No silent last-writer-wins.
ADR-10 — Registration is by invitation (CLI on the node issues a single-use, expiring token). The service is private; this removes public sign-up abuse. An invitation creates an account; it never enrols a device into an existing account.