Threat Model — v1

• Status: v1, written by work package SRV-003 on 2026-10-14; the owner accepted the two ADRs it proposed, ADR-0029 and ADR-0030, on 2026-10-17. It replaces v0 (the planning session, 2026-10-03), keeps every threat number of v0, and is reviewed at every phase gate and whenever a work package changes a trust boundary (plan/07).
• Owner stream: SECURITY
• Method: data-flow diagrams analysed with STRIDE, per element (§4.5, §4.6) and per flow (§6). STRIDE names six kinds of threat: Spoofing (pretending to be someone else), Tampering (changing data), Repudiation (denying having done something), Information disclosure, Denial of service and Elevation of privilege (getting more power than allowed).
• Decisions it relies on: some of the designs analysed here are decided in ADR-0029 (identity keys, device approval and recovery) and ADR-0030 (commit acceptance, departures and group repair), which SRV-003 proposed and the owner accepted on 2026-10-17, ADR-0030 together with its three departures from the owner’s earlier direction (§7.2).
• Related: SEC-01…SEC-13, COL-01…COL-14, OPS-01…OPS-09, ADR-0006, ADR-0008, ADR-0012, ADR-0014, ADR-0015, ADR-0016, ADR-0017, ADR-0023, ADR-0026, ADR-0028, the engine protocol, and the report of the MLS spike SRV-002, spikes/mls/REPORT.md in bayan-server.

Summary for the owner

• What BayanDocs protects. The content of shared documents (text, comments, media, edit history, titles and folder structure) is readable only on the devices of the people a document is shared with. Whoever runs the server cannot read it, change it unnoticed, or give anyone a role, with the two exceptions in the next point but one (§3.2).

• What a hostile server can do anyway. It can refuse service, delay or withhold messages, split a group into parts that no longer see each other’s edits, and see the metadata listed field by field in §9: who works with whom, when, how much, and from where.

• The two exceptions, and the largest remaining risks. First, when you share with someone for the first time, your app has to ask the server who that person is. A hostile server could answer with a fake identity of its own (a “ghost user”, T23) and then read what you share with them. Comparing safety numbers prevents this; key transparency, a later addition, would make it detectable without effort. Second, the web app runs code that the server delivers, so a hostile server could deliver code that steals the keys of people using BayanDocs in a browser (T11). The desktop app does not have this weakness. But an account that is also used in a browser carries the risk into everything shared with that account, until its browser devices are revoked. The same weakness limits link sharing and passkey unlock in the browser.

• Signing in is not the same as having the keys. Someone who takes over your sign-in (through your company’s identity provider, a stolen passkey, or an administrator) gets no keys. They cannot read documents, and any device they add stays powerless until one of your own devices approves it after comparing a code. Passkey unlock is the exception: an opt-in convenience that lets one passkey both sign in and unlock the keys (F10).

• Four problems in the design, and their fixes. The analysis found four problems in ADR-0016 as it stands after its amendment of 2026-10-07:

  1. A user who loses every device can get their identity back with the recovery kit but cannot rejoin their documents. A document whose only owner loses every device can never change its members again.
  2. A user cannot leave a document unless an owner is online to remove them.
  3. Approving a new device must compare a code or scan a QR code in both directions, or the server could slip in its own device, or its own keys, at the same moment.
  4. Restoring the server from a backup would stall every document that changed since the backup.

  ADR-0029 and ADR-0030 fix them, and you accepted both on 2026-10-17. ADR-0030 also gives the details of the “two-phase acceptance” you chose on 2026-10-09 against members who stall a group (§7). It departs from that choice in three named points, which you accepted too: owners’ commits take effect at once; a commit that no other member checks within 72 hours is dropped without punishing its sender; and quarantine applies to the sender’s whole account.

• What you decided. On 2026-10-17 you accepted both ADRs, including ADR-0030’s three departures, and decided against an expert cryptography review of ADR-0029’s constructions before Phase 3 builds them; the external audit before collaboration leaves beta (SEC-08) still reviews them (§13.2). On 2026-10-26 you confirmed six small corrections to those ADRs that the AC-4 review found, and accepted the rules of §13.4 for revoked devices when the server’s device list is stale, recorded as an amendment of ADR-0030. The question ADR-0016 left to SRV-003, whether the server may learn which updates are comments, needed no new decision: §7.4 confirms what you decided on 2026-10-09.

1. Scope, method and assumptions

1.1 Scope

v1 analyses the collaboration system end to end: signing in, accounts, devices and identity keys, sharing and roles, link sharing, synchronization online and offline, snapshots for new members, recovery, lost devices, notifications, administration and backups, the delivery of the web app’s code, and the compliance escrow member planned for Phase 4. It covers bayan-server, the collaboration code of bayan-core (bayan-sync, bayan-mls, bayan-crdt), the shells’ transport and key storage, and the services around them: the reverse proxy, the organization’s identity provider, the database, object storage and email.

Parsing documents, rendering, automation, local AI and the release pipeline keep the threats of v0 (T1–T4 and T14–T20 in §11) until their own work packages extend them.

Most of what v1 analyses is built in Phase 1 (SRV-101…SRV-105: identity, storage and relay foundations) and Phase 3 (collaboration); each flow in §6 names its phase. The server endpoints that exist today are only those of SRV-001 (/healthz, /readyz, /version and static files).

1.2 Method

1. Diagrams. A context diagram of the whole system (§4.2), diagrams of the inside of the server (§4.3) and of a client (§4.4), and a sequence diagram for every flow (§6). In the sequence diagrams each box is a trust zone, so every arrow that leaves a box crosses a trust boundary (§4.1).
2. STRIDE per element. §4.5 lists every element with the STRIDE categories that apply to its type (external entities: S and R; processes: all six; data stores: T, R, I and D; data flows: T, I and D) and where each is analysed; §4.6 analyses the infrastructure elements that no flow covers in full.
3. STRIDE per flow. Every flow in §6 has a table with one row per threat: an ID such as F4.2, the category, the element attacked, the threat, its mitigations and what remains. Rows name the principal threat (T-number) they belong to.
4. Principal threats. §11 keeps the numbers T1–T22 of v0, which other documents cite, and adds T23–T39. Numbers are never reused or renumbered.
5. Status values. In place (built and tested), Planned (designed here or in an Accepted ADR, not built), Proposed (depends on a Proposed ADR), Residual (accepted in §12).

1.3 Assumptions

1.4 Terms

2. Assets

3. Adversaries and security goals

3.1 Adversaries

3.2 Security goals

4. System model

4.1 Trust boundaries

Boundaries 1–9 are those of v0; v1 adds 10–14.

4.2 Context diagram

Each box is a trust zone; the numbers on the arrows are the boundaries of §4.1.

flowchart LR
  subgraph clientzone["Devices of a user (boundaries 2, 3, 11)"]
    user([User])
    desk["Desktop app<br/>Qt shell + core:<br/>keys, MLS, CRDT"]
    web["Web app<br/>React shell + core<br/>in a Web Worker"]
    store[("Key store and<br/>encrypted cache")]
    authr["Authenticator<br/>(passkey)"]
  end
  subgraph proxyzone["Operator's edge"]
    proxy["Reverse proxy<br/>TLS 1.3, X25519MLKEM768"]
  end
  subgraph serverzone["Server process"]
    srv["bayan-server"]
  end
  subgraph datazone["Operator's storage"]
    db[("Metadata database<br/>SQLite or PostgreSQL")]
    disk[("Blob store on disk")]
  end
  s3[("S3-compatible storage<br/>(optional, may be a third party)")]
  idp["Identity provider<br/>(organization, OIDC)"]
  smtp["Email relay<br/>(optional)"]
  others(["Other members' devices"])
  admin([Administrator's browser])
  operator([Operator's shell on the host])
  linkr([Link recipient])
  user --> desk
  user --> web
  desk --- store
  web --- store
  web -.->|"WebAuthn (11)"| authr
  desk -->|"HTTPS and WebSocket (4)"| proxy
  web -->|"HTTPS and WebSocket (4)"| proxy
  others -->|"HTTPS and WebSocket (4)"| proxy
  linkr -->|"link ID only; the key stays in the fragment (4)"| proxy
  admin -->|"admin console (4, 14)"| proxy
  proxy -->|"HTTP on loopback (13)"| srv
  srv -->|"web app code (9)"| proxy
  operator -->|"command line, backups, metrics (14)"| srv
  srv -->|"(5)"| db
  srv -->|"(5)"| disk
  srv -.->|"TLS (5)"| s3
  srv -.->|"TLS (10)"| idp
  srv -.->|"TLS (12)"| smtp

4.3 Inside the server

The boxes are parts of the one bayan-server binary (ADR-0015); only the middleware and the three /healthz, /readyz and /version routes exist today (SRV-001). Requests cross boundary 13 when they enter the process and boundary 5 when they reach the stores.

flowchart TB
  proxy["Reverse proxy"]
  subgraph process["bayan-server process"]
    mw["Middleware (SRV-001): request ID, content-free log line,<br/>security headers, timeout, body size limit"]
    signin["Sign-in and sessions<br/>OIDC, passkeys, desktop sign-in"]
    apis["HTTP APIs<br/>accounts, devices, directory, recovery data,<br/>key packages, blobs, links, notifications"]
    adminapi["Admin console API"]
    ws["WebSocket gateway<br/>device authentication, backpressure"]
    seq["Sequencer<br/>per-group order, fan-out"]
    val["Validator<br/>public state, role policy,<br/>two-phase acceptance"]
    notif["Notifier"]
    metrics["Metrics on a private listener"]
  end
  subgraph stores["Storage (boundary 5)"]
    db[("Metadata database,<br/>message log, audit log")]
    blobs[("Blob store")]
  end
  oplog[("Operational log, stdout")]
  smtp["Email relay"]
  monitor([Operator's monitoring])
  proxy -->|"boundary 13"| mw
  mw --> signin
  mw --> apis
  mw --> adminapi
  mw --> ws
  ws --> seq
  seq --> val
  signin --> db
  apis --> db
  adminapi --> db
  val --> db
  seq --> db
  apis --> blobs
  apis --> notif
  seq --> notif
  notif -->|"boundary 12"| smtp
  mw --> oplog
  monitor -->|"boundary 14"| metrics

4.4 Inside a client

The engine never opens sockets or reads keychains itself (ADR-0012 Decision 5): it asks the shell through host services. On the web the engine, and with it every key, lives in the Web Worker; the page’s main thread never needs key material (F16).

flowchart LR
  subgraph shellzone["Shell (boundaries 2 and 3)"]
    ui["Interface"]
    net["Transport host service<br/>WebSocket and HTTPS"]
    ks["Key-store host service<br/>OS keychain or IndexedDB"]
  end
  subgraph enginezone["Engine: bayan-core, in a Web Worker on the web"]
    sync["bayan-sync<br/>log, offline queue, snapshots"]
    mls["bayan-mls<br/>groups, credentials, policy"]
    crdt["bayan-crdt<br/>isolated import with limits"]
  end
  cache[("Encrypted local cache<br/>and offline queue")]
  ui <-->|"engine protocol"| sync
  sync <--> mls
  sync <--> crdt
  sync <-->|"host.net.send and net.received:<br/>opaque frames"| net
  mls <-->|"wrapped keys only"| ks
  sync --- cache

4.5 Elements and the STRIDE categories that apply

4.6 Infrastructure elements

No flow covers these elements in full, so their threats are listed here.

5. Keys, credentials and sessions

The flows in §6 rely on the key design below. ADR-0016 Decisions 6 and 7 fix its principles; the details are decided in ADR-0029.

5.1 Keys

All of this uses primitives that OpenMLS’s provider already offers (Ed25519, HKDF, AEAD, HPKE including the hybrid KEM), so it adds no new primitive (ADR-0016 Decision 12); the constructions that combine them (certificates, the secret store, the key backup, passkey wrapping, the approval exchange, link signing and the device’s proof of possession) are reviewed by the external audit before collaboration leaves beta (SEC-08); the owner decided on 2026-10-17 against a separate expert review before Phase 3 builds them (ADR-0029). Nothing is protected by a password or passphrase: that would need a password-hashing function such as Argon2id, which MLS’s providers do not include, so the recovery kit is always a generated secret. The account’s root secrets (secret store, passkey wraps) and link keys use 256-bit AEAD keys, a margin for keys that guard everything else for years; document data, snapshots and backup entries use the AEAD of the group’s ciphersuite, as ADR-0016 decided (AES-128-GCM in the hybrid suite, which quantum computers do not meaningfully weaken).

After an exposure. Whoever obtains the recovery kit, or a passkey with passkey unlock, can open the secret store and, with the server’s stored data alone, the latest snapshot of every document, including later ones, until the user acts (T28). The response is: a new recovery kit, a new key-backup key (devices seal the current snapshot keys to it again), a new device-signing key with the remaining devices certified again, and, if a hostile party may have kept an older secret store, a new identity key, which contacts see as a change. Passkey unlock is switched off for an exposed passkey. A new kit and a new key-backup key after every recovery are good practice, because a recovery may run on a device or in a browser the user does not fully trust.

5.2 Credentials and the directory

• Credentials. Every MLS leaf carries a credential that names the account and the device and carries the chain that proves it: the device certificate (signed by a device-signing key), that device-signing key’s certificate (signed by the identity key) and the identity public key. A chain is valid when it leads to the account’s identity key and names a device that the account’s latest signed device list lists as current; a certificate made by an earlier device-signing key stays valid for a device that the latest list still lists, so a rotation does not break existing places in groups. Devices replace their credential in each group with their next self-update. The server’s validator and every client check the chain whenever a leaf appears: in key packages, commits, Welcomes, resyncs and recovery joins. The encoding, a private-use credential type or X.509, is left to the Phase-3 work package (ADR-0029). The spike’s basic credentials naming user/device (SRV-002) are replaced.
• Directory. For each account the server publishes the identity public key, the current device-signing certificate and the signed device list, which carries a version number, the current devices and the revoked ones, and records which device made each change. Clients pin a contact’s identity key the first time they see it (TOFU), refuse a device list older than one they have already seen, and stop with a warning before sending anything new to a contact whose identity key has changed. Users can compare safety numbers or scan each other’s QR codes and then see the contact as verified (ADR-0016 Decision 6).
• Watching one’s own devices. Every device of a user shows each change of the user’s device list, who made it and when. A device that finds a change attributed to itself that it did not make raises an alarm and starts the response of F11, because only a stolen device-signing key can produce one.
• Personal data in groups. A user’s document index (titles and folders) and settings (pins, verifications and device names) are end-to-end encrypted groups of the user’s own devices, like documents with one account. A new or recovered device therefore inherits the user’s pins and does not start trusting the directory afresh.
• What the directory can and cannot do. The server can withhold or delay a newer device list, and it can answer a lookup for someone a client has never seen with an identity of its own (T23). It cannot add a device to an identity a client has pinned or verified (G4).

5.3 Sessions and device authentication

• Every session belongs to one device. On the web the session is a cookie with the __Host- prefix, Secure, HttpOnly and SameSite=Strict. The desktop app signs in through the system browser and receives its token over a loopback redirect protected by PKCE (RFC 8252, RFC 7636), never through an embedded browser view.
• Proof of possession. Each WebSocket connection, and each security-relevant HTTP request (revoking, deleting, approving), carries a signature by the device key over a fresh challenge from the server, under a signing label of its own, as DPoP (RFC 9449) does for OAuth tokens. A stolen token without the device key cannot act as the device (T32).
• Unapproved devices are powerless. A device that has signed in but is not yet approved (F3) can only finish its own approval or a recovery (F9). It cannot read group data, claim key packages, publish anything, end other sessions or delete anything. This is what keeps a sign-in takeover from becoming more (T27).
• Re-authentication. Adding a sign-in method, changing the email address, deleting the account, recovery joins and every admin action need a sign-in from the last few minutes; the server checks this, because clients cannot.

6. Flows

Every flow has a sequence diagram and a STRIDE table. Paths such as /auth/oidc/start are illustrative; SRV-105 publishes the real API in specs/protocols/server-api.md.

6.1 F1: Signing in with OpenID Connect

Phase 1 (SRV-101); used by collaboration from Phase 3. Organizations sign in through their own identity provider. The server is an OpenID Connect relying party using the authorization code flow with PKCE. The web app follows the redirects in the browser. The desktop app opens the system browser and receives the result on a loopback address (RFC 8252); embedded browser views are not used. A sign-in proves who the user is to the server; it never unlocks keys (ADR-0015 Decision 4).

The state value must be bound to the browser that started the sign-in. The provider’s redirect back is a navigation from another site, on which browsers do not send SameSite=Strict cookies. The binding therefore uses a short-lived pre-sign-in cookie of its own (__Host- prefix, Secure, HttpOnly, SameSite=Lax, 10 minutes), and the provider returns the code in the query of a plain redirect (response_mode=query).

sequenceDiagram
  autonumber
  box Device of the user
    participant App as Desktop app
    participant Br as Browser
  end
  box Server host
    participant S as bayan-server
    participant DB as Metadata database
  end
  box Organization
    participant IdP as Identity provider
  end
  App->>Br: desktop only: open the server's sign-in page with a loopback address and a PKCE challenge
  Br->>S: GET /auth/oidc/start
  S->>DB: keep state, nonce and PKCE verifier (single use, 10 minutes)
  S-->>Br: pre-sign-in cookie (SameSite=Lax), redirect to the identity provider (exact redirect URI, state, nonce, code challenge)
  Br->>IdP: the user signs in with the provider's own factors
  IdP-->>Br: redirect back with code, state and iss in the query
  Br->>S: GET /auth/oidc/callback with the pre-sign-in cookie
  S->>S: check state against the cookie, and iss. Single use
  S->>IdP: exchange the code (TLS, client authentication, PKCE verifier)
  IdP-->>S: ID token
  S->>S: check signature, algorithm, issuer, audience, expiry, nonce
  S->>DB: find the account by issuer and subject, create a session for this device
  S-->>Br: web: session cookie. Desktop: redirect to 127.0.0.1 with a one-time code
  Br->>App: desktop only: one-time code on the loopback address
  App->>S: desktop only: code, PKCE verifier and the device's public key
  S-->>App: device session token

6.2 F2: Passkey registration and sign-in

Phase 1 (SRV-101). Accounts that do not use an organization’s provider sign in with passkeys (WebAuthn). New self-hosted servers keep registration closed: a new account starts from an invitation (OPS-09). The invitation link carries its token in the URL’s fragment, which browsers never send to servers, so it reaches neither the proxy’s logs nor email scanners that open links; the page reads it and spends it only in a POST request. On the desktop, passkeys are used through the system browser, because a platform’s passkey interface for apps may refuse a self-hosted server’s domain: on Apple’s platforms, an app can use passkeys only for domains associated with it (Apple’s “Supporting passkeys” documentation).

sequenceDiagram
  autonumber
  box Device of the user
    participant Br as Browser
    participant A as Authenticator
  end
  box Server host
    participant S as bayan-server
    participant DB as Metadata database
  end
  Note over Br,DB: Registration, only with an invitation (OPS-09)
  Br->>Br: read the invitation token from the link's fragment
  Br->>S: POST registration options with the token
  S->>DB: token hash known, unused, not expired. Keep a challenge
  S-->>Br: options: RP ID is the server's domain, challenge, user verification required, no attestation
  Br->>A: create a passkey (the user verifies with PIN or biometrics)
  A-->>Br: public key and credential ID
  Br->>S: registration result
  S->>S: check challenge, origin, RP ID hash, user-verified flag
  S->>DB: create the account, store the credential, mark the invitation used
  Note over Br,DB: Sign-in
  Br->>S: sign-in options
  S-->>Br: challenge (single use, 5 minutes)
  Br->>A: get an assertion (the user verifies)
  A-->>Br: signature over the challenge
  Br->>S: assertion
  S->>S: check signature, challenge, origin, RP ID, user-verified flag, counter
  S->>DB: session for this device
  S-->>Br: session cookie, or a loopback code for the desktop app (F1)

6.3 F3: Device enrollment, approval and cross-signing

Server groundwork in Phase 1 (SRV-101); cross-signing in Phase 3; ADR-0029. A new device makes its own device key and a one-time transfer key, signs in and registers as pending. One of the user’s approved native (desktop) devices then approves it, and the approval must be authenticated in both directions:

• The approving device must approve this device, not one the server slipped in at the same moment.
• The new device must accept its user’s identity key and key-backup key only from that approving device, not from the server.

So the two devices first run an out-of-band step. Either the user scans, with the approving device, a QR code that the new device shows, holding the fingerprint of the new device’s keys and a one-time secret. Or, where no camera helps, both devices show the same short code produced by a commit-then-reveal exchange between them. The approving device then certifies the new device key with the device-signing key and sends the approval: the certificate, the new device list, the identity key and the key-backup public key. It seals the approval to the transfer key with HPKE using the hybrid post-quantum KEM, and authenticates it with an AEAD key derived from a secret the server cannot know: in the QR path the one-time secret in the QR code; in the short-code path the secret that the HPKE encapsulation establishes, which the short code authenticates because both devices compute the code over the whole exchange (both devices’ public keys, the commitments and the encapsulation), so that a server in the middle produces different codes on the two devices. Such a server gets one guess per exchange: a six-digit code gives it one chance in a million, and the devices stop after a few failed comparisons. Only a native device receives the device-signing key in that sealed approval.

Browser devices never hold the device-signing key, so web code that a hostile server serves once (T11) cannot certify devices or sign device lists. A user without a native device approves new devices with the recovery kit instead (F9). Administrators can additionally require their own approval (COL-13); that is a gate on the server, not a certificate. Once approved, the new device joins the user’s groups: the user’s other devices add it with own-device adds, or it makes recovery joins itself (F9). The first device of an account creates the identity key, the device-signing key, the key-backup key and the recovery kit (F9).

sequenceDiagram
  autonumber
  box New device
    participant N as New device's engine
  end
  box Server host
    participant S as bayan-server
  end
  box Approved native device of the same user
    participant O as Approved device's engine
  end
  N->>N: create a device key and a one-time transfer key (hybrid HPKE)
  N->>S: sign in (F1 or F2), register as pending: public keys, declared client application
  S->>S: pending: no group data, no key packages, no deletions
  S-->>O: content-free notice: a device is waiting for approval
  Note over N,O: Out of band: O scans N's QR code (fingerprint of N's keys and a one-time secret), or both show the same short code, computed over the whole exchange
  O->>S: fetch the pending device's public keys
  O->>O: compare them with what was scanned or compared, refuse on any difference
  O->>O: certify N's device key, add N to a new version of the device list
  O->>S: approval sealed to N's transfer key and authenticated with the QR code's secret or the secret of the exchange the short code covers: certificate, device list, identity key, key-backup public key, and for a native N the device-signing key
  S->>S: check signatures against the user's identity key, apply the administrator approval policy (COL-13)
  S-->>N: the sealed approval
  N->>N: open it, check its authentication, then check the chain up to that identity key
  O->>S: own-device adds of N to the user's groups, or N makes recovery joins (F9)

6.4 F4: Sharing, role changes, removal and leaving

Phase 3. To share, an owner’s client looks the recipient up (by exact email address or account ID), checks the recipient’s identity against its pin, claims one key package per recipient device, and sends one commit that adds the devices and gives the recipient a role in the roster. The validator checks it (ADR-0016, amendment 2026-10-07, design detail 3) and relays it; the new devices receive a Welcome, fetch the ratchet tree from the server and join in one storage transaction. An editor’s client then sends them a snapshot (F8). A role change is an owner’s commit with a new roster; a removal is an owner’s commit that removes every device of the user and their roster entry. To leave, a user sends a leave request inside the group from one of their devices. Members authenticate it like any MLS message; its kind is visible to the server, which accepts it from every role, viewers included, stops delivering to all of the user’s devices at once and accepts nothing more from that user in that group. An owner’s client then commits the removal; the last owner must first make another member an owner (ADR-0030). Sharing with someone who has no account yet records a pending share inside the document and sends an invitation (F2).

sequenceDiagram
  autonumber
  box Owner's device
    participant O as Owner's engine
  end
  box Server host
    participant S as bayan-server
  end
  box Recipient's devices
    participant R as Recipient's engine
  end
  box Other members
    participant M as Members' engines
  end
  O->>S: look up the recipient by exact email address or account ID
  S-->>O: identity key, device-signing certificate, signed device list
  O->>O: check the chain, compare the identity with the pinned or verified key, warn at first contact or on a change
  O->>S: claim one key package per recipient device
  S-->>O: key packages
  O->>O: check that each key package's credential chains to the recipient's identity
  O->>S: commit adding the devices with the recipient's role in the roster, and a Welcome without the tree
  S->>S: validator: committer is an owner, roster rules, public framing, current epoch
  S-->>M: commit
  M->>M: check the commit against the policy, merge it
  S-->>R: Welcome
  R->>S: fetch the ratchet tree
  R->>R: check the tree hash, that an owner added it and the roster, then join in one transaction
  Note over O,M: Role change: an owner's commit with a new roster. Removal: an owner's commit removing every device of the user. Leaving: a leave request in the group, accepted from every role, then an owner's commit

6.5 F5: End-to-end encrypted link sharing

Phase 3; design detail for ADR-0016 Decision 8, decided in Phase 3. An owner’s client creates a random link key, a link signing key pair and a random link ID, and keeps the link key and the private signing key in that owner’s own encrypted settings (§5.2), not in the document’s group. It wraps the latest snapshot key for the link and signs the wrapped key, and stores both on the server under the link ID. The URL carries the link ID in its path; its fragment (after #), which browsers never send to servers, carries the link key and the public signing key. The owner’s devices wrap and sign each new snapshot for the link as they make snapshots. A recipient’s app reads the fragment, removes it from the address bar, fetches the wrapped key and the snapshot by link ID, checks the signature, and shows the document read-only.

Link readers are not MLS members, which is also how very large read-only audiences are served (ADR-0016, amendment 2026-10-07, design detail 5). Because only the creating owner’s devices hold the link’s keys, no other member, link reader or server can show link readers forged content. The cost is that the link’s view advances only when that owner’s devices make snapshots, and stops when that owner leaves the document. This document recommends that links stay read-only in Phase 3.

sequenceDiagram
  autonumber
  box Owner's device
    participant O as Owner's engine
  end
  box Server host
    participant S as bayan-server
  end
  box Recipient's device
    participant L as Link recipient's app
  end
  O->>O: new link key (256 bits), link signing key pair and link ID (128 bits), all random
  O->>O: keep the link key and private signing key in the owner's encrypted settings
  O->>O: wrap the latest snapshot key (AEAD bound to link ID and group ID), sign the wrapped key
  O->>S: create the link: link ID, signed wrapped key, blob ID, expiry. The server checks the owner role
  Note over O,L: The owner sends the URL over any channel: link ID in its path, link key and public signing key in its fragment
  L->>L: read the fragment and remove it from the address bar
  L->>S: fetch the link record by link ID (the fragment is never sent)
  S-->>L: signed wrapped snapshot key and the snapshot blob
  L->>L: check the signature, unwrap, check the blob hash, decrypt, import read-only with limits
  Note over O,S: Updating: the owner's devices add a signed wrapped key for each new snapshot. Revoking: the owner deletes the record

6.6 F6: Synchronizing while online

Phase 3 (SRV-103 relay, SRV-104 protocol). Each device keeps one WebSocket connection to the server. The connection is authenticated by the session and by the device key’s signature on a challenge (§5.3). Edits become CRDT updates, which the engine batches, encrypts as MLS application messages (private framing, so even the sender is hidden inside) and hands to the shell as opaque frames. The server checks what it can without keys and fans the message out; receivers decrypt and check the sender’s role themselves. Commits take the path of §7. Presence (cursors and selections, COL-02) travels as MLS messages marked ephemeral, which the server relays but never stores.

sequenceDiagram
  autonumber
  box Device A
    participant EA as Engine A
    participant HA as Shell A
  end
  box Server host
    participant G as WebSocket gateway
    participant V as Validator and sequencer
    participant LOG as Message log
  end
  box Device B
    participant HB as Shell B
    participant EB as Engine B
  end
  HA->>G: WebSocket upgrade with the session (Origin checked)
  G-->>HA: challenge
  HA->>EA: host service: sign the challenge
  EA-->>HA: signature by the device key
  HA->>G: signature, subscribe to groups from their last sequence numbers
  G->>G: device approved and not revoked, member of each group
  G-->>HA: messages and outcomes since those sequence numbers
  EA->>EA: batch edits into a CRDT update, MLS-encrypt it (private framing, padded)
  EA->>HA: host.net.send with an opaque frame
  HA->>G: application message for group and epoch
  G->>V: device is a member whose role may send updates, epoch E or E-1, size and rate
  V->>LOG: append: sequence number, epoch, size, time, ciphertext. The sender is not stored
  V-->>HB: fan-out to the group's online devices
  HB->>EB: net.received
  EB->>EB: decrypt, check the sender's role for the update's kind in both epochs, import with limits
  EB-->>G: acknowledge the sequence number

6.7 F7: Synchronizing after being offline

Phase 3 (SRV-104). While offline, a client keeps its edits as CRDT updates in an encrypted local queue. It does not keep MLS ciphertext, because members keep keys for at most one past epoch (ADR-0016, amendment 2026-10-07, requirement 3) and would not be able to read updates encrypted many epochs ago. When it reconnects, it fetches everything since its last sequence numbers, processes commits in order, and only then encrypts and sends its queued updates in the current epoch.

sequenceDiagram
  autonumber
  box Device
    participant E as Engine
    participant Q as Encrypted offline queue
  end
  box Server host
    participant S as bayan-server
  end
  E->>Q: while offline: keep CRDT updates, encrypted with a local key, not MLS ciphertext
  E->>S: reconnect (F6) and subscribe from the last sequence numbers
  S-->>E: commits with their outcomes, and messages since then
  E->>E: process the commits in order, decrypt each message in its own epoch
  alt the log no longer reaches back far enough
    E->>S: resync with its own device key (F9) and fetch the latest snapshot (F8)
  end
  E->>E: encrypt the queued updates in the current epoch
  E->>S: send them
  S->>S: check the device's role now
  alt the role no longer allows edits
    S-->>E: refused
    E->>E: keep the edits locally, tell the user, offer a copy of the document
  end

6.8 F8: Snapshots and new members

Phase 3; the construction is ADR-0016’s amendment of 2026-10-07, design detail 2, tested in SRV-002. MLS’s forward secrecy means a device that joins cannot read anything sent before. An editor’s client therefore encrypts a snapshot of the current document under a fresh key and uploads it as an opaque blob, then sends the key, the snapshot’s ID and the blob’s hash inside the group. Every member’s device that receives a snapshot key seals it to its own account’s key backup (F9), so that each user can recover their documents. A recovery restores only the latest snapshot, so editors’ clients also make snapshots at a regular cadence, not only for newcomers.

sequenceDiagram
  autonumber
  box Editor's device
    participant ED as Editor's engine
  end
  box Server host
    participant S as bayan-server
    participant BL as Blob store
  end
  box Newcomer's device
    participant N as Newcomer's engine
  end
  Note over ED,N: After the commit that added the newcomer (F4), or at the snapshot cadence
  ED->>ED: snapshot of the current state, without edit history unless the sharer chooses otherwise
  ED->>ED: encrypt under a fresh key with the group's AEAD. Associated data: label, group ID, snapshot ID
  ED->>S: upload the blob and the log position it covers. The server checks the owner or editor role and the quota
  S->>BL: store it under a random blob ID with group and size
  ED->>S: MLS application message: snapshot key, snapshot ID, blob hash
  ED->>S: key-backup entry: the snapshot key sealed to the editor's own account's backup key
  S-->>N: the key message, in an epoch the newcomer can read
  N->>N: check that the sender may edit, in both epochs
  N->>S: fetch the blob. The server checks that the device is a member
  S-->>N: blob
  N->>N: check the hash, decrypt, import with limits
  N->>S: key-backup entry: the snapshot key sealed to its own account's backup key
  N->>N: compare version vectors and ask for a newer snapshot if updates are missing

6.9 F9: Recovery with the recovery kit

Phase 3; ADR-0029. When an account is created, its first device makes the recovery secret, shows it as the recovery kit (words and a QR code to print or save), checks that the user saved it, seals the identity key, the device-signing key and the key-backup key into the secret store on the server, and erases the secret. After losing every device, the user signs in on a new device, enters the recovery kit, and gets their identity back.

The new device then rejoins each group where the user still has a role, without anyone’s help:

• Recovery join. An MLS external commit that adds the new device and removes no one. The new device then removes the user’s lost devices with ordinary own-device removals. OpenMLS 0.9.0 can build an external commit that removes only a leaf with the joiner’s own signature key, so a new device cannot remove another device in the same commit.
• Resync. A device that kept its own key, because it fell behind the log’s retention (F7) or could not follow a commit (§7.2), rejoins with an external commit that replaces its own old leaf, as RFC 9420 §12.4.3.2 describes and OpenMLS supports.

Without recovery joins, a user who lost every device could rejoin only if an owner re-added them, and a document whose only owner lost every device could never change its members again (T29). Because a recovery may run on a device or in a browser the user does not fully trust, it ends with a new recovery kit and a new key-backup key (§5.1).

sequenceDiagram
  autonumber
  box New device
    participant U as User
    participant N as New device's engine
  end
  box Server host
    participant S as bayan-server
  end
  box Members of a document
    participant M as Members' engines
  end
  N->>S: sign in (F1 or F2), register as a pending device
  S-->>N: the secret store and the key-backup entries (ciphertext)
  U->>N: enter the recovery kit
  N->>N: derive the secret-store key, open the secret store
  N->>N: new device-signing key, certify its own device key
  N->>S: new signed device list that revokes the lost devices, and certificates
  S->>S: check against the identity key, approve the device, end the lost devices' sessions
  S-->>N: the groups where the account has a role, with their group information
  loop each such group
    N->>S: recovery join: external commit adding N, removing no one
    S->>S: validator: chain to the user's identity, latest device list, role in the roster, recent sign-in
    S-->>M: the commit
    M->>M: the same checks except the sign-in, then show that the user rejoined after a recovery
    N->>S: own-device removals of the user's lost devices
    N->>N: open the latest snapshot key from the key backup, fetch and decrypt the snapshot
  end
  N->>N: make a new recovery kit and a new key-backup key, seal the current snapshot keys again

6.10 F10: Passkey unlock (PRF)

Phase 3, opt-in; ADR-0029 and ADR-0016 Decision 7. The WebAuthn PRF extension lets an authenticator compute a secret from a passkey and a fixed input. With passkey unlock switched on, the client uses that secret to wrap a copy of the recovery secret and stores the wrapped copy on the server. On a new device, signing in with the passkey then also unlocks the account, instead of typing the recovery kit. Switching it on needs the recovery kit once, because no device keeps the recovery secret.

sequenceDiagram
  autonumber
  box Device
    participant U as User
    participant C as Client
    participant A as Authenticator
  end
  box Server host
    participant S as bayan-server
  end
  Note over U,S: Switching it on: opt-in, with the recovery kit once
  U->>C: switch on passkey unlock, enter the recovery kit
  C->>A: assertion with the PRF extension and the fixed BayanDocs input
  A-->>C: PRF output, only after user verification
  C->>C: derive the unlock key (HKDF), wrap the recovery secret (AEAD bound to the credential ID and account)
  C->>S: store the wrapped secret for this passkey
  Note over U,S: Unlocking on a new device
  C->>A: sign-in assertion with the PRF extension
  A-->>C: signature and PRF output
  C->>S: sign in (F2), fetch the wrapped secret
  C->>C: unwrap the recovery secret and continue as in F9

6.11 F11: Losing a device, and revocation

Phase 3; ADR-0029. From any of their remaining devices, the user marks a device as lost. The server ends the lost device’s sessions at once; the user’s devices then remove it from every group with MLS commits, which is what takes its keys away for good. If the lost device was a native device, it held the device-signing key, so the user rotates that key with the recovery kit or passkey unlock, and the lost device can no longer certify devices. Existing places of the remaining devices in groups stay valid, because a chain is checked against the latest device list (§5.2).

sequenceDiagram
  autonumber
  box Remaining device of the user
    participant D2 as Remaining device's engine
  end
  box Server host
    participant S as bayan-server
  end
  box Lost device
    participant D1 as Lost device
  end
  box Members
    participant M as Members' engines
  end
  D2->>S: new signed device list revoking D1
  S->>S: check the signature, end D1's sessions, refuse its connections, delete its key packages
  S--x D1: connections closed
  loop each group D1 is in
    D2->>S: commit removing D1 (own-device removal, §7)
    S-->>M: the commit
    M->>M: check it and merge it, D1 has no keys for the new epoch
  end
  opt D1 was a native device that held the device-signing key
    D2->>D2: recovery kit or passkey unlock, new device-signing key certified by the identity key
    D2->>S: new device list signed with the new key, listing the remaining devices
  end
  Note over D2,M: Without any remaining device: recovery (F9), whose recovery joins and removals replace the lost devices

6.12 F12: Accepting a commit that only members can check

Phase 3 (SRV-103 and bayan-mls). Direction chosen by the owner (ADR-0016, amendment 2026-10-07, requirement 6); details in ADR-0030 and §7.2. The server’s validator cannot check the parts of a commit that are keyed with the epoch’s secrets: its membership and confirmation tags, and the path secrets it encrypts to the other members (SRV-002 report §5). Each member decrypts only the path secret meant for its own part of the group. A committer can therefore send a commit that the server accepts and that every other member refuses. It can also make a commit work for some members, for example the owners or whoever is online, and fail for the rest. With two-phase acceptance, a commit from a member who is not an owner takes effect only once a device of another account confirms that it can process it and no such device refuses it; nobody merges it before.

sequenceDiagram
  autonumber
  box Committer, not an owner
    participant C as Committer's engine
  end
  box Server host
    participant V as Validator
  end
  box Witnesses: devices of other accounts in the group
    participant W as Witness engines
  end
  box Owners
    participant O as Owners' engines
  end
  C->>V: commit for epoch E (a self-update, a change to the user's own devices, a resync or recovery join)
  V->>V: public checks: signature, sender, policy, framing, epoch
  V->>V: pending: keep the public state of epoch E and the staged state of E+1
  V-->>W: the commit, marked pending
  W->>W: process it without merging, using the secrets of epoch E, and check its group information
  W->>V: report: OK, or refused with a reason class
  alt at least one OK and no refusal by the end of the grace period
    V-->>C: confirmed
    V-->>W: confirmed, everyone merges
  else any refusal
    V-->>C: dropped, the committer's account quarantined in this group
    V-->>W: dropped, everyone discards it
    V-->>O: notice with the reports, for review
  else no report within 72 hours
    V-->>C: dropped without quarantine, retry later
  end
  Note over C,O: A device that later cannot process a confirmed commit reports it: the committer's account is quarantined and the device resyncs

6.13 F13: Moving a document to a new group

Phase 3; ADR-0016, amendment 2026-10-07, design detail 4. An owner moves a document to a new group to change its ciphersuite (until OpenMLS implements MLS’s re-initialization) or, as the last resort after a stall, to leave out the users who caused it (requirement 6). The owner announces the move in the old group with an update that only owners may send, and every member checks the new group against the announcement before switching.

sequenceDiagram
  autonumber
  box Owner's device
    participant O as Owner's engine
  end
  box Server host
    participant S as bayan-server
  end
  box Members
    participant M as Members' engines
  end
  O->>S: claim fresh key packages for every member device, for the new ciphersuite
  O->>S: register the new group (only the owner), then one commit adding everyone with the same roster
  O->>S: in the old group: a group-moved update (owners only) naming the new group, its suite, and any users left out
  S-->>M: the update, and a Welcome to the new group
  M->>M: check that an owner sent it, and that the new group has exactly the announced members, roles and suite
  M->>M: join the new group, send there the CRDT updates not yet acknowledged, stop using the old group

6.14 F14: Notifications without content (COL-10)

Phase 3. The server can tell a user that something happened (a document was shared with them, a device is waiting for approval, a security event) but never what a document says or what it is called: it does not know. Notices go to the user’s devices over the sync connection; email is optional, switched on by the operator and the user. Push services of browser and phone vendors are not used, because they are third-party network calls at runtime, which the project’s rules exclude (AGENTS.md §6).

sequenceDiagram
  autonumber
  box Server host
    participant S as bayan-server
    participant NT as Notifier
  end
  box Optional, run by the operator
    participant MAIL as Email relay
  end
  box Recipient's device
    participant C as Client
  end
  S->>NT: event: shared with you, a device waits for approval, a security notice
  NT->>NT: build a content-free notice: event type, opaque reference, time, and the actor's display name if enabled
  NT-->>C: notice over the sync connection
  opt email switched on by the operator and by the user
    NT->>MAIL: plain-text email over TLS, without titles, content or remote images, with one link to the server
  end
  C->>C: fetch the details through sync, decrypt, show the title on the device

6.15 F15: Compliance escrow member

Phase 4 (E4-ENTERPRISE); ADR-0016 Decision 10. The design and its abuse cases are in §8. An organization’s policy adds a passive escrow member, whose key the organization keeps offline, to the documents its accounts own. Every member sees it.

sequenceDiagram
  autonumber
  box Organization
    participant ADM as Organization administrator
    participant ESC as Escrow officers, key offline under a quorum
  end
  box Server host
    participant S as bayan-server
  end
  box Member devices
    participant O as Owner's engine, organization account
    participant M as Members' engines
  end
  ADM->>S: escrow policy: escrow identity, a stock of its key packages, scope
  O->>O: managed configuration pins the organization's escrow identity
  O->>S: new organization document: group, then a commit adding the escrow member as viewer, with its Welcome, and the server keeps the tree of that epoch too (§8.1)
  S->>S: refuse updates in organization groups without the escrow member, and commits removing it
  S-->>M: the commit shows the escrow member
  M->>M: show that the organization's compliance can read it, warn external users before they join
  Note over ESC,S: Lawful access: officers fetch the retained log and the escrow member's Welcome, process them offline, every access is logged

6.16 F16: Delivering and starting the web app

Phase 1 (WEB-101, WEB-103) and every phase after; ADR-0014 and its amendment of 2026-10-12. The web app is code the server sends to the browser every time it is loaded. Everything the app protects therefore depends on that code (T11). The app’s own checks cover what browsers allow (strict CSP, Trusted Types, Subresource Integrity enforced with Integrity-Policy, and a check of the engine’s files against hashes built into the app), with one gap that WEB-002 found: the browser does not bind the worker’s own requests to the bytes the app checked (bayan-web issue 8).

sequenceDiagram
  autonumber
  box Browser
    participant P as Page, main thread
    participant W as Engine worker
    participant IDB as IndexedDB
  end
  box Server host
    participant S as bayan-server, static files
  end
  P->>S: GET / through the proxy (HTTPS)
  S-->>P: index.html with CSP, Trusted Types, Integrity-Policy, cross-origin isolation
  P->>S: the scripts named in index.html
  S-->>P: scripts, checked by the browser against their integrity hashes
  P->>S: fetch the engine's three files
  P->>P: compare with SHA-384 hashes built into the app, start nothing if any differs
  P->>W: start the worker through the Trusted Types policy bayan-script-url
  W->>S: load the engine. The browser does not bind these bytes to the ones checked
  W->>IDB: open the key store, wrapped with a non-extractable key
  Note over P,S: A hostile or compromised server can serve different code at every step (T11)

6.17 F17: Administration, backups and restores

Phase 1 (SRV-101 admin bootstrap, SRV-105 operations) and Phase 3 (admin console, OPS-06). Administrators manage accounts, quotas and policies through the admin console; operators run the command line inside the container and make and restore backups. None of them can read documents or add devices or members: those need keys that only users’ devices hold.

sequenceDiagram
  autonumber
  box Operator's side
    participant AD as Administrator's browser
    participant OP as Operator's shell on the host
  end
  box Server host
    participant S as bayan-server
    participant DB as Metadata database
    participant BL as Blob store
  end
  box Backup storage
    participant BK as Backups
  end
  AD->>S: admin console through the proxy: passkey sign-in, recent re-authentication
  S->>DB: accounts, devices, quotas, policies: metadata only
  S->>DB: audit entry for every admin action
  OP->>S: bayan-server admin command inside the container
  OP->>BK: backup: a consistent copy of the database and the blob store
  OP->>S: restore from a backup
  S->>S: after a restore: end every session, mark key packages and pending states stale, enter catch-up for every group
  Note over S,BK: Members then upload the commits and signed device lists the backup lacks, under the catch-up rules of §7.5 (ADR-0030)

7. Role enforcement: design details and failure modes

Roles are enforced twice: by the server, so that what it refuses never reaches anyone, and by every client, so that a misbehaving server cannot give anyone more than their role (ADR-0016 Decision 5). §7.1 lists who checks what; §7.2 gives the details of two-phase acceptance; §7.3 lists what happens when the server and the clients disagree; §7.4 confirms that the server is not told whether an update is an edit or a comment; §7.5 says how groups catch up after a server restore.

7.1 Who enforces what

7.2 Two-phase acceptance

The owner chose this direction on 2026-10-09 (ADR-0016, amendment 2026-10-07, requirement 6): the server keeps the previous epoch’s public state until a device of another user confirms the new epoch, and otherwise drops the commit and quarantines its sender. The rules below are the details SRV-003 was asked for, decided in ADR-0030. They depart from the chosen direction in three points, which the owner accepted explicitly on 2026-10-17:

1. Owners’ commits take effect at once. The direction covers every commit; ADR-0030 applies two phases only to commits by members who are not owners. Owners can already remove anyone. Two phases for owners would let one lying member drop every owner’s commit except its own removal, which it cannot witness, stopping shares and role changes until an owner removed it; every share would wait until another member’s device comes online; and nobody could witness the first share of a document that only its owner belongs to.
2. A commit that nobody checks within 72 hours is dropped without quarantine. The direction says “otherwise drops the commit and quarantines its sender”; a time-out is not evidence of misbehavior, so ADR-0030 drops such a commit but does not punish its sender, who retries.
3. Quarantine covers the sender’s account in that group, not one device, so that a quarantined member cannot start again with a new device.

stateDiagram-v2
  [*] --> Pending: valid commit by a member who is not an owner
  Pending --> Confirmed: OK from a witness and no refusal within the grace period
  Pending --> Dropped: a refusal from any witness, sender's account quarantined
  Pending --> Expired: no report within 72 hours
  Pending --> Superseded: an owner commits for the same epoch
  Confirmed --> [*]
  Dropped --> [*]
  Expired --> [*]
  Superseded --> [*]

1. Which commits. A commit takes two phases when the committer’s account is not an owner in the epoch before it: self-updates, changes to the committer’s own devices, and resyncs and recovery joins by users who are not owners. Owners’ commits and group registrations take effect at once, as today.

2. Pending. The validator checks the commit exactly as the SRV-002 validator does. If it passes and no other commit is pending in the group, it becomes the group’s pending commit. The server keeps the commit staged next to the current state; OpenMLS’s public group cannot be copied (see the spike’s validator.rs), so the server keeps the pending commit in the database and stages it again after a restart. It relays the commit marked as pending and holds any Welcome it carries until the commit is confirmed. While a commit is pending, the server accepts updates for the current and the previous epoch as today, but none for the pending epoch. It refuses other commits by users who are not owners, asking them to retry. It accepts an owner’s commit for the current epoch, which drops the pending commit as superseded, without quarantine.

3. Witnesses and reports. A witness is a device of an account other than the committer’s that is a member both before and after the commit. For resyncs and recovery joins, the joining account’s own other devices, which know every revocation, may also refuse, but their OK does not count; they may refuse an owner’s resync or recovery join too, within a limit (§13.4). Every witness device that receives the pending commit processes it without merging it, checks the group information the committer published with it, and reports either OK or a refusal with a reason class:

   • tag: a membership or confirmation tag is wrong;
   • path: its path secret does not decrypt or does not fit;
   • group-info: the published group information does not match the epoch it derived;
   • policy: its own policy check refuses what the validator accepted;
   • credential: a chain or a revocation is wrong;
   • malformed.

   Reports travel over the device’s authenticated connection. The server keeps the first report of each device and counts accounts, not devices. Devices witness the pending commits of all their groups in the background when they connect, not only those of documents that are open.

4. Decision. The first report starts a grace period, 10 seconds by default. At its end, the commit is confirmed if at least one witness account reported OK and none refused. A single refusal drops it: a commit made honestly can be processed by every member, so a refusal means either a bad commit or a lying witness, and the second is the smaller harm. An owner’s report counts like anyone else’s, because a committer can make a commit work for the owners’ devices alone. If no witness reports at all within 72 hours, the commit expires: it is dropped without quarantine and its committer may retry.

5. Outcomes. Confirmed: the new epoch becomes current, the old one is kept as the previous epoch, held Welcomes are delivered, and every device merges the commit (the committer merges its pending commit). Dropped or expired: the server discards the new state and every device discards the commit (the committer clears its pending commit). After a drop, the committer’s account is quarantined in the group: the server refuses commits by any of its devices, including resyncs and recovery joins, but not its updates, until an owner lifts the quarantine or removes the account. The exception is a resync or recovery join that a device of the joining account refuses with reason credential: only the joining device is blocked in the group (§13.4). Owners are told about every drop, quarantine and stuck report, with the reasons, without content.

6. After confirmation. A witness device that cannot process a commit that was confirmed while it was offline reports it as stuck, with a reason class. A stuck report with reason tag, path or group-info quarantines the committer’s account, because the commit was bad for some members, and owners are told. The stuck device resyncs with its own device key, using group information that a member who processed the epoch published, or an owner’s client re-adds it.

7. The committer meanwhile. The committer keeps sending updates in the current epoch while its commit is pending: OpenMLS 0.9.0 lets a member create application messages while its own commit is pending, as long as the commit’s proposals are carried inline, as this design’s always are (checked in its source, MlsGroup::create_message).

What it costs. A commit by a user who is not an owner takes effect one round trip to another user’s online device plus the grace period later; owners’ commits are not delayed. Witnessing a commit costs a device what processing it costs: in the worst case measured by SRV-002, a first self-update after many members were added at once, about 42 ms natively and 100 ms in Chromium at 1,000 members with the hybrid suite.

What it does not solve. A server can still withhold or delay anything (availability). An owner’s commit, which takes one phase, that members cannot process stalls the group; that needs a compromised or broken owner device, and another owner’s move (F13) repairs it. A lying witness can drop honest commits of members who are not owners, or report them as stuck after confirmation, and so get their accounts quarantined until an owner acts (FM12); owners cannot tell from a single report whether the witness lied or the committer encrypted a bad secret to it, and can only go on patterns across reports. In a group that no other member visits, members who are not owners cannot change their keys or devices until someone does. A commit that works for every member who happens to be online, and fails for those who are offline, is confirmed; the members it fails for resync, and its sender is quarantined afterwards.

7.3 When the server and the clients disagree

7.4 The kind of an update stays encrypted

ADR-0016’s amendment of 2026-10-07 (design detail 3) records the owner’s decision of 2026-10-09 that the server is not told whether an update is an edit or a comment, and asked SRV-003 to confirm it. Confirmed; no change. MLS lets a sender attach authenticated data that the server can read; putting the kind there would let the server also refuse a commenter’s edits, but:

1. Security does not depend on it: every client refuses a commenter’s edits after decrypting them (SRV-002 clients_reject_updates_whose_sender_lacks_the_role), and the server already refuses viewers’ messages, leave requests aside.
2. It would tell the server which updates are comments, and with sizes and timing, how much each person comments and when (T9), contrary to ADR-0016 Decision 9.
3. It would let a hostile server suppress comments selectively, which it cannot do now without suppressing everything.
4. A commenter who floods the group with edits only costs others some decryption; the server’s per-device rate limits and quotas bound that (F6.4).

Two distinctions stay visible. The server must know what to store: whether a message is ephemeral (presence, relayed and never stored) or durable. And it must recognize a leave request, which it accepts from every role and which stops delivery to the leaving user (F4, ADR-0030); that tells it nothing the leaving device would not tell it anyway. Snapshot-key messages, group-moved notices and link notices are durable updates like any other and look the same to the server.

7.5 Catching up after a restore

A server restored from a backup is behind every group that changed since the backup (FM8). Members still hold those commits, so they bring the server up to date (ADR-0030):

1. After a restore the server ends every session, marks stored key packages and pending commits as stale, and puts every group in catch-up.
2. Member devices upload the commits they merged after the server’s restored epoch, oldest first. Each is checked against the public state and the policy as usual, with two differences: its signature, not the uploading connection, shows who made it, and it is not witnessed again, because its members already merged it.
3. A commit is accepted only if a device of another account uploads it, or an owner’s device does, or the group has only one account. A member therefore cannot slip in its own commit that was dropped before the restore.
4. If devices upload different commits for the same epoch, the server stops catching up that group and tells its owners; the chain an owner’s device uploads decides, and members on the other branch resync.
5. Devices also upload their newest signed device lists, which the server accepts when they are newer and correctly signed, and replace their key packages. Lost updates and snapshots are sent again from members’ CRDT state through the normal sync protocol (SRV-104).
6. Reports and quarantines recorded after the backup are lost. A quarantined account can then commit again; if it sends another bad commit, witnesses drop it and its account is quarantined again. Owners, who were told of the first quarantine, can remove the account.

Revoked devices and conflicting chains (ADR-0030, amendment 2026-10-26; §13.4). Devices upload their newest signed device lists before any commit, and the server checks every uploaded commit, resync and recovery join against the newest list it then holds, refusing anything signed by a revoked device. It then drops uploaded chains that contain commits from revoked devices. If owners’ devices still upload conflicting chains, for example after a fork that a hostile server caused before the restore (FM6), the server accepts neither, keeps the group stopped and tells its owners, who move it to a new group (F13). Until a device that knows a revocation has reconnected, the server still checks against the restored, older list (FM9).

8. Compliance escrow member

Phase 4 (E4-ENTERPRISE in plan/05); ADR-0016 Decision 10. This section is the design recommendation for the Phase-4 work package and the abuse cases it must handle. The flow is F15.

8.1 Design

1. A member, not a back door. The escrow member is an ordinary MLS member: one device of a dedicated escrow account of the organization, with the role viewer, certified like any device (§5.2). Everything about it is visible in the group: it can be added only by a commit and every member’s client shows it.
2. Passive, with an offline key. The escrow device never commits and never sends. Its private keys stay offline, in a hardware security module whose own quorum feature requires several officers (k of n) to approve each use; splitting the key in software instead would need secret sharing, which MLS’s providers do not include and which would need its own ADR (ADR-0016 Decision 12). The organization uploads a stock of the escrow member’s key packages, made offline in advance. A member must process every commit in order to read later epochs, so lawful access means fetching the group’s retained log and the escrow member’s Welcome and processing them offline, from the escrow member’s join onwards. The escrow member therefore needs the ratchet tree of the epoch it joined. Carrying the tree in its Welcome would depart from ADR-0016 design detail 1 (“Welcomes carry no ratchet tree”) and need an amendment of ADR-0016 in the Phase-4 work package; this section recommends instead that the server keep the tree of the join epoch, with the Welcome and the log, for the escrow retention period, which leaves design detail 1 as it is. No online service ever decrypts.
3. Scope. The policy covers only groups whose owners are accounts of the organization. Clients add the escrow member only when the organization’s managed configuration says so, and they pin the organization’s escrow identity from that configuration rather than from the server alone. The server enforces presence: it refuses updates in a group of the organization until the escrow member is in it, and refuses commits that remove it.
4. Visibility to outsiders. Before a user from outside the organization joins an escrowed document, their client tells them that the organization can read it, and they can refuse.
5. Retention. Escrow needs the log kept, which contradicts minimization (§9). Escrowed groups therefore have a retention period of their own, stated in the policy and shown to members.
6. Zero knowledge stays. The server never holds the escrow key (ADR-0015 Decision 6).
7. Alternative for Phase 4 to weigh. Editors could instead seal each snapshot key to an escrow public key, without an escrow member: the escrow then sees only snapshots and the log need not be kept, but neither the server nor members could check that a modified client really does it. The member design is checkable by everyone, which is why this section recommends it.

8.2 Abuse cases

9. Metadata inventory

This is the field-by-field list that v0 §6 item 2 asked for: what the server stores (§9.1), what it sees without storing (§9.2), and what that lets an operator learn (§9.3). Retention periods are proposed defaults that SRV-102 and SRV-105 make configurable; “operator” means whoever runs the server. SRV-102’s schema must contain nothing that is not listed here (§13.1).

9.1 What the server stores

Accounts (SRV-101, SRV-102)

Sign-in

Sessions

Devices

Directory and recovery data (Phase 3)

Key packages (SRV-103)

Groups and their public state (SRV-103)

A user’s document index and settings are groups like any other, with one account; the server sees only that (§5.2).

Message log and delivery (SRV-103, SRV-104)

Blobs (SRV-102)

Links (Phase 3)

Invitations, notifications, audit

Audit events: sign-ins and failures; sessions created and ended; passkeys added and removed; devices registered, approved and revoked; recoveries and passkey unlocks; administrator actions and policy changes; quarantines and stuck reports; restores. The audit log is stored data with a retention period, not part of the operational log, which must never contain account identifiers (AGENTS.md §6).

Operations

Outside the server, under the operator’s control: the reverse proxy’s access logs (client IP address, time, method, path, which may contain link IDs and blob IDs, status, size, user agent), the object store’s request logs, the email relay’s logs, and the organization’s identity provider’s logs. The deployment guide (SRV-105) should recommend switching the proxy’s access logs off or logging without paths and addresses (§4.6 IE3), and the API should carry group and blob IDs in request bodies or WebSocket frames rather than paths where it can.

9.2 What the server sees without storing it

• IP addresses and ports, through the proxy’s forwarded headers, and user agents: where and with what people connect.
• When each device is connected, and which groups it subscribes to.
• For every update: which device sent it, how large it is and when, which reveals who edits which document, when, how much, and the rhythm of typing.
• The rate of ephemeral (presence) messages: who is looking at a document right now.
• Snapshot and media sizes: each document’s size and growth and how many images it holds.
• Key-package claims: who is about to share with whom, before the commit.
• Link fetches: when a link is used and from which address.
• Look-ups: which email addresses someone looks up.

9.3 What this lets an operator learn

From §9.1 and §9.2 together, an operator can learn the social graph (who shares with whom, with which role, from the readable commits), activity (who works on which document when, and how much), the documents’ sizes and growth, each user’s devices and client applications, approximate locations from IP addresses, the organization’s structure, and typing rhythms that may identify a person. It cannot learn content, titles, folder structure, comments or who mentions whom. Mitigations already designed: titles and structure encrypted (ADR-0016 Decision 9); the sender of updates not stored; no IP addresses stored by default; coarse dates; the retention limits above. Options for later, each with a cost in bandwidth or latency: batching updates at fixed intervals and padding them (MLS supports padding), padding blobs to size classes, and decoy traffic. This is threat T9, accepted as residual in §12.

10. Security requirements per server endpoint

v0 §6 item 6 asked for a checklist per planned endpoint. §10.1 applies to every endpoint; §10.2 adds what each one needs. The paths are illustrative: SRV-105 publishes the real API in specs/protocols/server-api.md, and each Phase-1 server work package proves these requirements for the endpoints it builds (§13.1).

10.1 Requirements for every endpoint

10.2 Endpoints

11. Principal threats

The register keeps the numbers of v0. Rows T1–T22 are v0’s, with their status and mitigations brought up to date; T23–T39 are new in v1. “Where” points to the analysis.

12. Accepted residual risks (v1)

1. An operator can deny service, and can observe the metadata listed in §9 (T9).
2. People who use the web app trust the origin that serves its code (T11), and so, until that account’s browser devices are revoked, does everyone who shares with an account that uses the web app. The same holds for link recipients in a browser (T31) and for passkey unlock in a browser (T28). The desktop app removes this trust for accounts that do not use the web app; self-hosting removes third parties.
3. At first contact, a user who does not compare safety numbers trusts the server’s directory (T23), until key transparency is adopted.
4. A collaborator who can read can copy; a former member keeps what they already had, including snapshots they received.
5. Compromised endpoints are out of scope; revocation and post-compromise security limit what happens afterwards.
6. A user can run any client with their own account; it can do only what that user may do.
7. A hostile server can fork a group; members notice only indirectly unless they compare group codes (T26).
8. Whoever holds the recovery kit owns the account, and, with the server’s stored data alone, reads the latest snapshot of every document until the user makes a new kit and rotates the keys it protects; with passkey unlock, the passkey alone does the same (T28).
9. Losing every device and the recovery kit loses the identity and the documents nobody else holds; a document whose only owner is gone keeps working but cannot change its members (T29).
10. Links are bearer secrets, and a link’s view can be out of date.
11. A lying member can drop the commits of members who are not owners, or report them as stuck, and get their accounts quarantined until an owner acts, and an owner cannot tell a liar from selective encryption by a single report; a commit that works only for the members who are online is confirmed, and the others resync; a compromised owner device can stall a group until another owner moves it (§7.2).
12. Updates are signed: members can prove to one another, and to anyone who trusts their keys, who wrote what. There is no deniability.
13. In escrowed documents (Phase 4), the organization can read what its policy allows.
14. After a restore from backup, groups that changed since the backup wait until their members’ clients reconnect and catch the server up (§7.5).
15. A hostile server that withholds a newer device list (T30) and ignores the refusals it receives can let a revoked device rejoin for members who have not seen the newer list. After a restore, until a device that knows a revocation reconnects, and when the user’s other devices stay offline beyond the limit of §13.4, a revoked owner device can still rejoin.

13. Recommendations

13.1 Phase-1 server work packages

This change updates the drafts in workpackages/phase-1/server.md; the Phase-0 gate review refines them into Ready briefs.

13.2 Decisions

• ADR-0029 (accepted on 2026-10-17): identity keys, device approval and account recovery. It makes ADR-0016 Decisions 6 and 7 concrete (§5) and fixes three of the problems found: recovery joins and resyncs so that a user who lost every device can rejoin their documents (T29); a key backup so that documents only the user held survive (T29); and device approval authenticated in both directions, with no device-signing key on browser devices (T24, T11). It also states plainly what holds at first contact (T23) and what the recovery kit and passkey unlock expose (T28). It changes design detail 3 of ADR-0016’s amendment of 2026-10-07 in two points: groups accept resyncs and recovery joins, which are external commits; and the required credential type is the one ADR-0029 chooses instead of basic credentials.
• ADR-0030 (accepted on 2026-10-17): commit acceptance, departures and group repair. It gives the details of two-phase acceptance (§7.2), with three departures from the owner’s earlier direction, which the owner accepted. It also lets users leave without waiting for an owner’s goodwill (F4.11), adds a policy version, and defines how groups catch up after a server restore (§7.5, T33). It confirms the owner’s decision that the kind of an update stays encrypted (§7.4).
• Both needed the owner’s decision (ADR-0001 Decision 5: they change security design). The owner accepted both on 2026-10-17, and decided against the expert review of ADR-0029’s constructions before Phase 3 that the proposal made a condition. ADR-0029 combines signatures, key derivation and encryption into constructions of its own: device certificates and device lists, the secret store, the key backup, passkey wrapping, the authenticated approval exchange (QR code or short code), link signing and the device’s proof of possession. Their first review from outside the project is therefore the external audit before collaboration leaves beta (SEC-08), which must cover both ADRs (risks R-06 and R-11).

13.3 Later phases and other repositories

1. Core, Phase 3 (bayan-mls, bayan-sync). The client side of §7.2 (holding staged commits, reports, background witnessing, stuck reports); credential chains, device lists and pinned identities (§5.2); resyncs, recovery joins and the key backup (F9); an offline queue of CRDT updates (F7); version vectors (F8); a snapshot cadence (F8); batching and padding options (§9.3). OpenMLS 0.9.0 can remove, in an external commit, only a leaf with the joiner’s own signature key; asking upstream for an external commit that removes another leaf the application accepts would let a recovery join replace a lost device in one commit.
2. Engine boundary. OpenMLS 0.9.0 draws randomness from the platform (through getrandom, with its js feature in WebAssembly, as SRV-002 used it) and reads the platform clock (SystemTime::now(), from web_time in WebAssembly): to set and check key-package lifetimes (key_packages/lifetime.rs; checks can take the time from the caller through validate_with_time, but creating a key package still reads the clock) and to timestamp every epoch’s message secrets (group/mls_group/past_secrets.rs). ADR-0012 Decision 5 and the determinism rules forbid both in the engine, and ADR-0012’s amendment of 2026-10-08 excepts only Loro’s randomness and clock, so bayan-mls needs its own amendment of ADR-0012, or randomness and time supplied by the host, before it joins the engine.
3. Engine protocol. A key-store host service that only ever sees wrapped keys, next to the transport host service of §4.4; no key material in messages to the shell. Recordings: diag.record of a collaborative session must not capture MLS state, keys or the user’s identity (its initial_state holds the engine’s session state), and never uploads; replays of collaborative sessions replay decrypted CRDT updates on the developer’s own machine (T36).
4. Web. Close the gap in the integrity of the worker’s files (bayan-web issue 8) before collaboration runs in browsers; keys only in the worker, wrapped in IndexedDB with a non-extractable key; no device-signing key in the browser; remove a link’s fragment from the address bar as soon as it is read (F5, F16).
5. Desktop. Open BayanDocs links in the desktop app; keep tokens and wrapped keys in the OS keychain; hold the device-signing key; use the platform’s passkey interface for passkey unlock where the platform allows it for the server’s domain (F10).
6. Phase-3 gate. Decide on key transparency, whose IETF protocol (draft-ietf-keytrans-protocol) was still a draft in April 2026 (T23); on HTTPS in the server itself (ADR-0028 Decision 4); on padding; and confirm that no push service is used (F14).
7. Phase 4. Escrow as in §8; SCIM deprovisioning that blocks a user’s devices at once and asks owners’ clients to remove them from groups; managed configuration that pins an organization’s identities (EA5).
8. Risk register. The Phase-0 gate review adds T23 (ghost users), T26 (forks), T28 (recovery kit and passkey unlock) and T29 (unrecoverable access) to risks R-06 and R-21 of plan/08.
9. External audit (SEC-08). Its scope includes ADR-0029, ADR-0030, the snapshot construction (ADR-0016, amendment 2026-10-07), link sharing (F5) and this document.

13.4 Revoked devices when the server’s device list is stale

The AC-4 review of SRV-003 found three gaps that ADR-0029 and ADR-0030 left together, all when the server’s device list is stale, because a hostile server withholds the newer list (T30) or an honest server was restored from a backup older than the revocation (FM9):

1. Owners’ joins took effect before anyone could refuse them. An owner’s resync or recovery join takes one phase (ADR-0030 Decision 1), so a revoked owner device’s join took effect at once, and the user’s own devices, which know the revocation, could not block it.
2. The victim’s account was quarantined. For a user who is not an owner, a refusal by the user’s own device dropped the join, but ADR-0030 Decision 5 then quarantined the committer’s account, which is the victim’s own.
3. Catch-up had no answer for conflicting owners’ chains. §7.5 rule 4 lets the chain that an owner’s device uploads decide, but not between owners’ devices, and a revoked owner device that the restored list still names counted as an owner’s device.

The owner accepted these rules on 2026-10-26, recorded in ADR-0030’s amendment of 2026-10-26:

• Device lists first. During catch-up, every device uploads the newest signed device lists it holds before any commit, and the server checks every uploaded commit, resync and recovery join against the newest list it then holds, refusing anything signed by a device that a newer list revokes.
• Block the device, not the victim. A refusal with reason credential by a device of the joining account drops a resync or recovery join and blocks only the joining device in that group: the server accepts nothing more from it there, and the account is not quarantined. Owners and the user’s devices are told.
• The user’s own devices may stop an owner’s join. When the joining account has other devices in the group, an owner’s resync or recovery join waits like a two-phase commit, but only those devices’ refusals count. It takes effect when the grace period after their first report ends without a refusal, or after a limit, proposed at 10 minutes, if none of them reports; SRV-103 measures the limit and may change it. A recovery after losing every device has no other device in the group and takes effect at once.
• Conflicting owners’ chains stop the group. Once the lists are applied, the server drops uploaded chains that contain commits from revoked devices. If owners’ devices still upload conflicting chains, the server accepts neither, keeps the group stopped and tells its owners, who repair it with a move to a new group (F13), as for any fork (FM6).

What remains: a hostile server can still withhold a newer list from members who have not seen it (T30) and ignore the refusals it receives, so against a hostile server only members who know the newer list protect themselves, by refusing the join and falling behind. Against an honest server that was restored, the rules close the gap once one device that knows the revocation has reconnected; until then, and when the user’s other devices stay offline beyond the limit, a revoked owner device can still rejoin.

14. Traceability

14.1 The open items of v0

14.2 Requirements of SRV-003

15. Maintenance and review

• When it changes. At every phase gate, and in any work package that changes a trust boundary or adds an endpoint. Phase-1 server work packages record, for each endpoint they build, the evidence for §10’s requirements, and update §9 when they store a new field.
• Numbers. Threat numbers (T1–T39), flow numbers (F1–F17), infrastructure rows (IE1–IE11), failure-mode numbers (FM1–FM13) and escrow abuse cases (EA1–EA10) are never reused or renumbered; new ones are added at the end.
• Review. A separate reviewer session reviews each version (SRV-003 AC-4); the external audit before collaboration leaves beta reviews §5–§8 (SEC-08).
• History. v0, 2026-10-03, planning session. v1, 2026-10-14, SRV-003: system and flow diagrams, STRIDE per element and per flow, metadata inventory, role enforcement, escrow, endpoint requirements, T23–T39, ADR-0029 and ADR-0030 proposed, and accepted by the owner on 2026-10-17. 2026-10-26: the owner confirmed the AC-4 review’s corrections and accepted the rules of §13.4 (ADR-0030, amendment 2026-10-26).