Failure Modes and Recovery

Owns the failures Capsule must survive and the independent recovery paths that must stay workable.

Failure Mode Catalog

Failure	Detected / contained by	Recovery
Master key loss	—	Path 1 or 2
Device key loss	Device keys are disposable	Re-bootstrap (1/2); never recovered
AMK loss	—	Path 3 or 4
Write-tier key loss	—	Re-minted next epoch
Master key compromise	—	Rotate and re-key
Device compromise	—	Revocation certificate + MLS Remove; survivors rotate
AMK / write-tier compromise	—	Epoch bump; old epoch cannot read or sign future ones
Server compromise	Server never trusted	Authz from MLS history; E2E data
One half of a hybrid primitive broken	Hybrid construction	Other half holds
Ciphertext corruption / truncation / reorder	STREAM tags + manifest ciphertext_hash	Re-fetch a content-addressed copy (6)
Reader-signed / removed-writer / wrong-epoch / forged / replayed manifest	verify_asset	Quarantine + audit trail
AMK distribution lag	verify_asset pending	Retry; quarantine after timeout
MLS ratchet corruption	—	Paths 1, 3, 4; MLS Resilience
Backup missing an amk_version	AMK-completeness check	Re-export before reliance
Nonce reuse	Structural (Re-keying)	—
CBOR non-determinism	Canonical encoding	Byte-identical re-encode
Bug corrupting the library DB	DB is a rebuildable cache	Rebuild from sidecars (5)
Erroneous delete	Soft-delete default	Restore from trash (7)
Stale revival (old valid manifest)	prior_provenance_hash chain, client and server	Quarantine; chain advance refused
Suite downgrade	Signature covers crypto_suite_id, protocol_version	Quarantine
Derivative poisoning	DerivativeManifest chain	Unsigned overwrite rejected
Old client strips unknown sidecar fields	Signature covers all bytes; refuse writes above max sidecar_schema	Quarantine

Redundant Recovery Paths

Independent paths:

#	Path	Survives
1	Master-key escrow: passphrase/seed → master key → AMK escrow	Total device loss
2	Cross-device recovery (Device Enrollment)	Partial device loss; lost master-key backup if one device survives
3	OGK: any owner recovers every album’s AMKs	Lost membership, AMK distribution gaps
4	Offline backup artifact	Server loss, account compromise, escrow corruption
5	Filesystem rebuild: CBOR sidecars are canonical, DB is a cache (idempotent rebuild_index())	DB corruption, index bugs
6	Content-addressed copies on devices or federated peers (ciphertext, not keys)	Single-server data loss
7	Trash: signed soft delete with a retention window before purge	Erroneous deletes

Account types. Registered accounts have all seven. Delegated/sponsored accounts recover only through the sponsor’s master key (consequence). Non-registered share-link accounts have no collection to recover.

Bug-Resistance Invariants

• Backup and restore never touch MLS ratchet state; the master key is the single backed-up root.
• Device keys are hardware-bound, non-exportable, never backed up; the master identity cross-signs every device.
• Every construction is versioned (KDF info, in-blob Argon2id params, crypto_suite_id, sidecar_schema), so v2 never strands v1.
• verify_asset quarantines, never drops or silently accepts.
• Provenance is append-only and hybrid-signed per record (Provenance).
• Backup verification runs before the backup is relied on.

Transport Security

• TLS 1.3 required wherever both ends support it; TLS 1.2 is the absolute floor (legacy ingress only); nothing lower. Clients try 1.3 first.
• Deployments SHOULD enable hybrid X25519+ML-KEM key exchange on 1.3.
• Ingress (not the app server) terminates TLS: operator-configured, documented not enforced.
• Capsule’s own TLS (SDK, LAN peering mTLS, egress) is rustls (Dependencies), same policy.

Validation

• Every catalog row tests detection and recovery; CI fails a row without one.
• One scenario per path: reach the lost state, recover, assert every asset returns.
• Exported backup artifacts contain no ratchet state; device private keys are non-exportable per platform (Keys); v1↔v2 sidecar round-trip.
• System-level coverage: Module Map — E2E Test Surface.