DodoSSH/docs/adr/0001-e2ee-trust-model.md

ADR 0001 — End-to-end encrypted vault and its trust model

• Status: accepted
• Date: 2026-07-28

Context

DodoSSH stores SSH credentials — passwords, private keys, key passphrases — on a server so they can sync across a user's devices and be shared with teammates. Authentication is OIDC against a provider the operator chooses.

The product is self-hosted. Its buyers are teams who currently refuse to put infrastructure credentials into a SaaS vault. "Trust us with your production keys" is exactly the promise we cannot make.

Decision

The vault is end-to-end encrypted. The server stores ciphertext and never holds a key.

1. A vault passphrase separate from OIDC. OIDC authenticates but yields no secret we can derive a key from, and SSO compromise must not equal vault compromise. The passphrase goes through Argon2id (m=256 MiB, t=4, p=1) to a master key that never leaves RAM.

2. A per-user keypair, wrapped many ways. The master key wraps a ~200-byte UserSecretBundle (X25519 + Ed25519 private keys). The same bundle is stored under several independent wraps: passphrase, one per enrolled device, recovery code, and optionally escrow. A passphrase change therefore re-wraps 200 bytes and updates one row — no re-encryption of vault data and no coordination with other members.

3. Vault keys, then per-item data keys. A vault key is sealed to each member's X25519 key; each item has its own data key wrapped under the vault key. Rotating a vault key re-wraps N × 32-byte data keys and never touches content blobs.

4. AAD bound to row identity. Every ciphertext's AAD is recomputed from the row's plaintext columns rather than stored, over purpose, resourceType, resourceId, keyId, keyGeneration, itemVersion and schemaVersion.

   The normative byte encoding is docs/crypto.md §4. It is fixed-width binary rather than delimited string concatenation, so that no field value can forge a field boundary.

5. Layered public-key trust — see Consequences.

Consequences

What this buys

The AAD binding is the most valuable structural property here, and it is not something ACLs can provide. A malicious server cannot paste credential A's ciphertext onto host B, cannot roll a row back to an earlier key generation, and cannot replay a revoked grant: each of those changes the AAD and fails the authentication tag on the client.

A stolen database dump, a rogue administrator, a TLS-terminating proxy and the relay operator all see ciphertext only. OIDC account takeover alone yields nothing readable.

What it costs, stated plainly

• Revocation is not retroactive and cannot be. A removed member keeps whatever they already downloaded, along with the cached keys. Rotating the vault key protects only items written after the rotation. The only real remediation is rotating the SSH credentials themselves, so offboarding is built around a credential-rotation checklist rather than a "revoke access" button that implies more than it delivers.

• Connect cannot be a security boundary. SSH terminates on the client, so opening a session requires the credential's plaintext on that machine. "May connect but may not view the key" is unenforceable in this architecture. The flag exists as a UI hint and must never be documented as access control.

• Forgotten passphrase with no recovery code and no enrolled device means permanent loss of personal vault contents. Team vault contents survive, because a remaining member with Share can re-wrap. That asymmetry is a feature: it makes team vaults the right default even for a team of one plus a backup admin.

• Public-key distribution is the real security boundary. Every guarantee is downstream of "the key I wrapped to is really Alice's". Four layers, deployed together: an IdP-signed key binding (the enrollment statement's hash is the nonce in an ID token, verified against JWKS fetched directly from the IdP and not proxied through us); TOFU fingerprint pinning with blocking warnings; an append-only key log whose head is embedded in every signed grant, so a forked view must stay consistent forever to go unnoticed; and safety numbers for out-of-band verification.

  The residual is honest and must stay in the docs: this makes the IdP a key-distribution trust root, and in a self-hosted deployment the person running Keycloak is frequently the person running DodoSSH. It raises the bar from "one compromised service" to "one compromised service plus a detectable artefact in the key log" — not to zero.

• No server-side session recording is possible in relay mode, since the relay forwards only SSH ciphertext. See ADR 0004.

• Metadata leaks. The server sees item counts, sizes, timestamps, access patterns and the complete sharing graph regardless of settings. Host addresses are plaintext when relay is enabled for that host; see ADR 0004 for why that is a security requirement rather than a convenience.

• Supply chain becomes the largest practical hole. An operator who wants the secrets attacks the client, not the crypto. Release signing with a key not held by the server, and eventually reproducible builds, matter more here than in a conventional product.

Rejected

• Server-side envelope encryption (KMS-held master key). Far simpler and it would permit a recording bastion, but a server compromise or a rogue admin exposes every credential. That is the exact promise the product exists to avoid making.
• Admin escrow of user identity keys. Turns every operator into a silent global reader and destroys the property being sold. Non-negotiable. Team-scoped break-glass escrow with Shamir M-of-N is a separate, opt-in, clearly-labelled M5 feature.
• Storing an Argon2id(passphrase) verifier server-side so the server can pre-validate. It creates an offline-crackable verifier on the very server being defended against, for no gain: the AEAD tag on the bundle wrap already proves the passphrase.