Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Phase 1 — Faithful Viewer: server work packages (drafts)

Status: Draft, refined at the Phase-0 gate after SRV-003 (threat model v1). Server work runs in parallel with the viewer because the zero-knowledge server does not depend on the layout engine. All in bayan-server; attach bayan-server and docs (bayan-core read-only where shared crates are involved).

SRV-003 added the “Security” item of each draft, from the recommendations of the threat model (§13.1). Every work package below shows evidence, for each endpoint it builds, of the requirements in the threat model’s §10, stores nothing that its metadata inventory (§9) does not list, and adds what it changes to both. Items that name ADR-0029 or ADR-0030 follow those ADRs, which the owner accepted on 2026-10-17.

SRV-101 — Identity: OIDC, passkeys, sessions, devices

  • Size: L · Depends on: SRV-001, SRV-003 · Decisions: ADR-0015, ADR-0016, ADR-0028, ADR-0029
  • Scope: generic OpenID Connect login (tested with Keycloak, Authentik and Microsoft Entra ID); passkey accounts (WebAuthn); session management with secure defaults; device registration (public keys only); admin bootstrap; rate limits; audit log of security events (no content); registration closed by default (OPS-09); each device records its declared client application, as groundwork for device approval and client policy (COL-13); outbound HTTPS to identity providers through rustls with aws-lc-rs and the operating system’s certificate store (ADR-0028).
  • Security (threat model F1, F2, F3, F17): OIDC with state, nonce and PKCE, the iss check of RFC 9207, exact redirect URIs, ID tokens checked against an allowlist of algorithms, and accounts found by issuer and subject, never by email address; passkeys with the server’s domain as RP ID, user verification required, attestation “none” and no stored authenticator model; the desktop app signs in through the system browser with a loopback redirect and PKCE (RFC 8252), never in an embedded view; sessions belong to devices, web sessions are __Host- cookies (Secure, HttpOnly, SameSite=Strict), while the short-lived pre-sign-in cookie that binds state to the browser is SameSite=Lax so that it comes back with the identity provider’s redirect, and security-relevant requests carry the device key’s signature on a fresh challenge (ADR-0029); devices register as pending and stay powerless until approved (groundwork for ADR-0029); invitations as hashed, single-use, expiring tokens carried in the link’s fragment and spent only by a POST request; re-authentication for sensitive account actions; the audit log’s events and 90-day retention of the threat model’s §9.1, kept apart from the operational log; no IP addresses or user agents stored by default; forwarded client addresses believed only from the configured proxy; the first administrator’s bootstrap token printed only to the operator’s terminal.

SRV-102 — Storage layer

  • Size: M · Depends on: SRV-001, SRV-003 · Decisions: ADR-0015, ADR-0028
  • Scope: metadata schema (users, devices, documents, groups, memberships, roles, quotas) with migrations for SQLite and PostgreSQL; blob store interface with filesystem and S3-compatible backends (dependency chosen by size and maintenance); quotas; encrypted-blob APIs (opaque bytes only); TLS to PostgreSQL and to S3-compatible storage with rustls and aws-lc-rs (ADR-0028): certificate and host-name verification on by default, a setting for a private certificate authority, guidance on PostgreSQL’s ssl_groups for post-quantum key exchange, the deny.toml changes ADR-0028 describes and the webpki-roots license exception (ADR-0017, amendment 2026-10-04), with the measured build-time and image-size increase recorded.
  • Security (threat model §9, F8): the schema holds only the fields of the metadata inventory (§9.1), each with its purpose in a comment, and runs its retention jobs; identifiers are random and at least 128 bits long; blobs record no uploader (usage counters instead) and no content hash, and are never deduplicated across groups; object keys in the blob store consist of random IDs only; quotas per account and per group; blob uploads only by owners and editors, downloads only by current member devices or valid links.

SRV-103 — MLS delivery and authentication services; WebSocket relay

  • Size: L · Depends on: SRV-002, SRV-003, SRV-101, SRV-102 · Decisions: ADR-0016, ADR-0029, ADR-0030
  • Scope: key-package store; per-group ordering and fan-out of handshake and application messages; public-state validation of commits and role enforcement on authenticated connections; WebSocket gateway with authentication, backpressure, reconnection and resumption; retention policy; a hostile-client test suite proving that authorization never depends on which client software connects (SEC-13).
  • Security (threat model F6, F12, §7, §10): the server side of two-phase acceptance with its state kept in the database: witness reports, a commit dropped at the first refusal, expiry after a time-out without quarantine, quarantine of the committer’s account, and stuck reports (ADR-0030), or, if the Phase-0 gate defers it to Phase 3, a documented hook for it; the rules for revoked devices (ADR-0030, amendment 2026-10-26; threat model §13.4): in catch-up, device lists taken before commits and anything signed by a device that a newer list revokes refused; a resync or recovery join that a device of the joining account refuses with reason credential dropped, blocking only the joining device; an owner’s resync or recovery join held up to 10 minutes for the account’s other devices in the group; and a group stopped, with its owners told, when owners’ devices upload conflicting chains; key packages checked on upload (signature, lifetime, suite, credential naming the uploading device) and claims limited per claimer and per target; group information kept for resyncs and recovery joins (ADR-0029); WebSocket connections authenticated by session and device-key signature, with Origin checked; size limits per message kind, rate limits per device and per group, bounded queues; the sender of an update checked and then forgotten, never stored, and ephemeral (presence) messages relayed but never stored; the log retention of §9.1; the failure modes of §7.3 in the hostile-client suite.

SRV-104 — Sync protocol specification v1 and reference client

  • Size: M · Depends on: SRV-103, CORE-004 · Decisions: ADR-0016, ADR-0030
  • Scope: write specs/protocols/sync-protocol.md (contract-first, Apache-2.0): message types, ordering, resumption, snapshots, compaction by clients, presence; create the Apache-2.0 protocol definitions crate bayan-core/crates/bayan-protocol (message types and schemas, no GPL or AGPL dependencies) used by both core and server, adding LICENSES/Apache-2.0.txt to bayan-core (reuse download Apache-2.0; REUSE.toml already declares the crate Apache-2.0) and a crate-level LICENSE; implement a Rust reference client used by tests and later by bayan-core’s bayan-sync.
  • Security (threat model F6, F7, F8, F12, F17): sequence numbers and catch-up; the pending, outcome, report and stuck messages of two-phase acceptance (ADR-0030); offline queues of CRDT updates rather than MLS ciphertext, encrypted when sent; version vectors so that newcomers find missing updates; leave requests, accepted from every role, viewers included (ADR-0030); catch-up after a server restore (threat model §7.5), in which members upload the device lists the server lacks before the commits they merged (ADR-0030, amendment 2026-10-26); the notices that a device was blocked and that a group stopped on conflicting owners’ chains; options for batching and padding updates; group and blob IDs carried in messages rather than in URL paths, where proxies would log them.

SRV-105 — Operations

  • Size: M · Depends on: SRV-001, SRV-003 · Decisions: ADR-0015, ADR-0028, ADR-0030
  • Scope: Prometheus and OpenTelemetry metrics; structured security audit log; backup and restore tooling with tests; compose profiles (SQLite single node; PostgreSQL plus S3-compatible storage) with a Caddy front end, and the deployment guide’s reverse-proxy requirements (ADR-0028); load-test harness and first PERF-07 measurements; machine-readable API descriptions and a first integration kit in the Apache-2.0 integrations/ directory (it already holds a README and the Apache-2.0 LICENSE), with specs/protocols/server-api.md; the “Source code” link setting (OPS-08).
  • Security (threat model F17, §9, §10): metrics without account, device, group, blob or link IDs as labels, on a listener that is not routed through the public proxy; export of the audit log; a restore procedure that ends every session, marks key packages and pending commits stale and lets clients catch the server up, device lists first, stopping groups whose owners’ devices upload conflicting chains until an owner moves them (threat model §7.5 and §13.4, ADR-0030 and its amendment of 2026-10-26), with a test; in the deployment guide, HSTS at the proxy, forwarded headers that the proxy overwrites and the server believes only from the proxy, the proxy reaching the server only over loopback or a network nobody else can reach, and the proxy’s access logs switched off or kept without paths and addresses; server-api.md written against the endpoint checklist of the threat model’s §10.