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