Architecture
The browser encrypts, the backend orchestrates, and the database enforces. Plaintext and keys stay in the browser.
Browser app
Section titled “Browser app”An Astro site with one React island. It is served as static files, so there is no server rendering.
- Encryption: WebCrypto, but for one step: noble derives an Ed25519 public key from its seed, since some WebKit builds refuse keys WebCrypto makes. A password is stretched with PBKDF2-SHA-256, then split by HKDF into an authentication key, which the server stores hashed, and a wrapping key, which never leaves the page. Notes are sealed with AES-256-GCM. Shared notes wrap their keys to each member’s P-256 ECDH key pair, and the owner signs each key it hands out with Ed25519. Every primitive’s parameters are on Product Security.
- Editing: CodeMirror 6 over a Yjs document. A note is Markdown text, styled as it is typed. Each line records who wrote it, for shared notes. Every change is an encrypted Yjs update. The page keeps unsent updates in IndexedDB, so a closed tab or a lost connection loses nothing.
- Passkeys: WebAuthn sign-in unwraps the master key in the page. The server checks only the signature.
- Client: generated from the OpenAPI contract, so the page and the API cannot drift apart.
Backend
Section titled “Backend”A Rust service on axum and sqlx. It never sees plaintext content or passwords.
- Sync: each note is an ordered log of opaque updates. The backend orders, stores and pages them, and compacts them into snapshots the client seals.
- Live editing: single-use tickets admit WebSocket connections to a blind relay. The relay forwards ciphertext between the people editing a note, caps concurrent editors, and never decrypts.
- Errors: every refusal is RFC 9457 problem details. Its
typelinks to a problem page on this site. - Contract: the handlers’ annotations generate the OpenAPI 3.2 contract. Both the reference on this site and the browser client are built from it.
- Work after commit: email and Stripe cancellations go through outbox tables.
pg_notifyinside the writing transaction wakes the one listener at commit. - Hints to sockets: once a write commits, one notifier connection tells the open sockets, in batches, so writes never take turns at commit to announce themselves.
- Stopping: SIGTERM stops new work, drains open requests and sockets within one deadline, and then exits.
Database
Section titled “Database”PostgreSQL enforces ownership with row-level security. Each transaction carries its caller in a transaction-local setting, so one request’s identity never leaks to the next. Background jobs use a separate role. Erasing an account is one database function.
Operations
Section titled “Operations”- A small admin command-line tool reports the user base, grants Orbit, and erases an account after an operator confirms it at a terminal.
- Caddy serves the static sites and proxies
/apito two copies of the backend behind health checks, so a release replaces one while the other serves.