# Encryption Boundary and Threat Model ## Status `govoplan-encryption` is the optional governance and lifecycle boundary for cryptographic protection. It persists opaque provider references, versioned content-protection envelopes, idempotent operation state, recovery decisions, and disable-preflight evidence. It ships a bounded `local_aesgcm` server-envelope provider. The provider uses AES-256-GCM, wraps generated vault keys under a key derived from deployment `MASTER_KEY_B64`, wraps one generated content key per envelope, and persists only wrapped keys, nonces, keyed commitments, ciphertext digests, and opaque references in shared SQL state. It does not ship a KMS/HSM driver or client E2EE protocol. Selecting the bundled profile is an authenticated encryption-at-rest claim for the covered payload, not an E2EE, endpoint-security, HSM/KMS, or legal certification claim. Stronger claims require a named protection profile whose provider, clients, algorithms, backup procedure, and failure tests have passed the profile's conformance and security review. ## Ownership Boundary Encryption owns: - vault and opaque provider-key reference metadata; - key-version and provider-operation lifecycle state; - versioned protection envelopes and migration evidence; - high-assurance, quorum-based recovery authorization; - disable and uninstall preflight. Feature modules still own domain content, access policy, retention, legal-hold meaning, and normal resource ownership. Identity Trust owns public device keys, key epochs, and recent-assurance evidence. Access decides whether an account may perform a resource action. A positive Access decision does not release a key; an ownership transfer does not transfer cryptographic custody. No capability in this module accepts or returns plaintext key material. ## Assets and Threat Actors Protected assets include content plaintext, data-encryption keys, wrapping keys, recipient/device private keys, authenticated context, recovery authority, and the integrity and provenance of lifecycle decisions. The threat model includes: - an unauthorized user or tenant attempting cross-tenant access; - a compromised account, API key, worker, or application node; - a malicious or mistaken tenant/platform administrator; - a compromised storage service, database backup, queue, log collector, or observability system; - a lost or revoked device and a former function holder; - a malicious or unavailable key provider; - replay, race, partial failure, rollback, and outcome-unknown provider calls; - ciphertext substitution, context confusion, algorithm downgrade, and mixed migration state; - backup restoration without matching provider keys, or key restoration without matching metadata. The initial model does not claim protection against endpoint compromise while a legitimate client has plaintext open, coercion of all configured recovery custodians, traffic analysis, or denial of service by a provider that controls required keys. ## Observable Metadata Unless an independently reviewed profile says otherwise, the server and its database can observe tenant, owner module, resource type and stable id, profile, vault and key version, algorithm suite, ciphertext location and digest, authenticated-context digest, wrapped-key references, timestamps, migration state, policy references, recovery scope, and actor/evidence references. Titles, recipient identities, content length, access patterns, and relationship graphs may also leak through the owning module or storage provider even when the payload is encrypted. Product UI and documentation must not imply that payload encryption hides this metadata. ## Deployment Profiles ### Bundled local AES-GCM reference provider `local_aesgcm` is a concrete server-side envelope provider intended for bounded deployments and integration verification. A per-deployment wrapping key is derived with HKDF-SHA-256 from `MASTER_KEY_B64`; the master key itself is never stored in the database. Vault keys and content keys are generated with the operating-system CSPRNG and wrapped with AES-256-GCM. Every content ciphertext authenticates a canonical tenant, owner, resource, profile, provider, vault, key-version, and algorithm context. The provider stores no unkeyed plaintext digest. Its internal plaintext commitment is keyed by deployment custody and bound to the authenticated resource context, preventing an offline database reader from enumerating low-entropy values such as ballot choices. The provider supports idempotent provision, rotation, revocation, destruction scheduling, content encryption/decryption, and same-provider key rewrap. A revoked vault key cannot protect new content but can open existing content until destruction. Due destruction clears wrapped vault material and causes reads to fail closed. Payload re-encryption is an explicit two-phase owner-coordinated workflow: Encryption decrypts and prepares an idempotent target ciphertext and exact envelope, while the owner must durably replace its payload before it records the migration as successful. This also permits cross-provider or algorithm migration without giving Encryption ownership of the payload store. ### Server-side envelope encryption The application or a deployment KMS/HSM can unwrap data keys after normal authorization. This protects backups and storage media but not plaintext from a compromised authorized application tier. Provider credentials and key policy are deployment secrets, not envelope metadata. Legal hold can preserve ciphertext and key availability under separately authorized policy. ### Tenant-held key provider The tenant controls an external KMS/HSM or equivalent provider. GovOPlaN holds only references and invokes the provider under tenant policy. The provider may allow server-side processing, but tenant revocation or provider outage can make content unavailable. Backup recovery requires both GovOPlaN state and the tenant's provider recovery procedure. ### End-to-end encryption Only authorized clients possess usable recipient/device private keys; ordinary servers cannot decrypt payloads. Search, preview, server-side Dataflow, virus/content inspection, reporting, legal-hold export, and recovery degrade or become impossible unless the selected profile deliberately adds an authorized recipient or escrow mechanism. Such a mechanism changes the threat model and must be displayed as part of the profile. The current code can label and track an `end_to_end` envelope, but it does not implement the client protocol. That label alone is never evidence of E2EE. ## Profile Consequences | Concern | Server envelope | Tenant-held | End-to-end | | --- | --- | --- | --- | | Normal server processing | Available after authorization | Provider-policy dependent | Unavailable unless a client performs it | | Provider outage | Decryption unavailable | Decryption unavailable | Existing enrolled clients may remain usable | | Platform admin can obtain plaintext | Possible under governed server policy | Tenant/provider dependent | Not from ordinary server custody | | Legal hold | Preserve ciphertext and governed keys | Requires tenant/provider cooperation | Ciphertext only unless the profile has a hold recipient | | Export | Governed plaintext or portable encrypted export | Provider cooperation required | Client-produced or recipient-key export | | Recovery | Provider recovery plus GovOPlaN quorum | Tenant provider recovery plus quorum | Device/recipient recovery defined by the client profile | | Ownership transfer | Separate reauthorization/rewrap | Separate reauthorization/rewrap | Explicit recipient change and re-encryption | | Revocation | Stops future provider use; cannot erase prior plaintext | Provider enforced | New key epoch; cannot erase prior client plaintext | ## Algorithms, Libraries, and Agility Concrete providers must declare a versioned suite id and pass conformance tests. The initial allowlist for reviewed profiles is: - AES-256-GCM through a deployment KMS/HSM or a maintained OpenSSL-backed cryptographic library; - XChaCha20-Poly1305 through a maintained libsodium implementation where the provider/profile requires extended nonces; - RFC 9180 HPKE suites for a future reviewed recipient-envelope protocol. Selection from this list is not automatic approval. A provider profile must also define nonce generation and uniqueness, associated-data construction, key separation, limits, error handling, and test vectors. Home-grown primitives, unauthenticated encryption, AES-ECB, bare AES-CBC, static/reused nonces, raw RSA encryption, SHA-1 integrity, provider-supplied secret values in logs, and silent algorithm fallback are prohibited. Every envelope fixes its profile, algorithm suite, vault, key version, ciphertext digest, and authenticated-context digest. Changing any of these is a new, evidence-backed migration. Readers never infer an algorithm from current defaults. Old readers fail closed on unknown suites or contract versions. ## Durable Operation Semantics Key-provider operations use a stable idempotency key. GovOPlaN records an operation as `prepared`, `succeeded`, or `outcome_unknown`. If a provider call raises or a process dies around the external side effect, absence of an error is never treated as success. Reconciliation repeats the exact idempotent provider request and records only bounded error class codes. An `outcome_unknown` content migration may subsequently be resolved to success or rejection; it is not an immutable terminal state. Content migrations are explicit records. Rewrap and re-encryption succeed only when an exact target envelope references the authorized source and migration. Re-encryption preparation leaves the source in `migrating` and does not register the active target envelope. Repeating it with the same migration and target reference returns identical authenticated ciphertext. Only the owner's evidence-backed outcome call activates the target and retires the source. Decrypt, export, and destruction require evidence references. Until an outcome is known, the source remains `migration_pending`; no implicit plaintext fallback is allowed. All runtime state is in the shared database or an external provider/object store reference. Application and worker nodes require no local encryption state, so multiple nodes can retry the same operation safely when the provider honors the idempotency contract. ## Recovery Ceremony Recovery requires current Identity Trust assurance at the `high` level, a policy-decision reference, expiry, distinct custodian accounts, and the vault's configured quorum. The requester cannot approve their own ceremony; one rejection rejects the current ceremony. Decisions are optimistic-concurrency protected and replay safe. An `approved` ceremony authorizes a later provider-specific recovery action. It does not return a key, change resource ownership, or prove that recovery has executed. A production provider must add separately auditable execution and post-recovery rotation/rewrap evidence. ## Disable and Uninstall Disabling or uninstalling never deletes keys or silently makes ciphertext look like ordinary unreadable content. Preflight inventories all envelopes. It blocks while any envelope is active, pending, migrating, unavailable, or otherwise unresolved. An envelope is locally terminal only after it is: - migrated to another registered protection envelope; - decrypted by an authorized workflow; - explicitly exported with documented custody; or - cryptographically destroyed with evidence. A migrated target remains an active protected envelope and therefore still blocks removal of the module/provider that owns it. Destructive table retirement is permitted only after this proof. ## Backup, Restore, and Key Loss A recoverable backup set consists of the shared database, ciphertext/object storage, provider configuration references, provider-side key backups or HSM replication, and audit evidence. These materials must be backed up separately according to their trust boundaries. Database restore without matching provider keys produces an explicit unavailable state; it must never create replacement keys under an old reference. Before production use, each concrete provider/profile needs automated restore, provider-loss, stale-backup, partial-migration, network-failure, and permanent key-loss exercises. Permanent key loss is data loss for the affected ciphertext and must be reported as such. ## Current Integration Contract Files, Postbox, Campaign, Calendar, and connector credentials may store an envelope id and ciphertext reference while retaining their own resource model. They resolve Encryption through optional capabilities and must fail closed when an encrypted record is encountered without the capability. Unencrypted module combinations continue to operate without Encryption. Focused fixtures validate Files and Postbox owner adapters: plaintext operation continues without Encryption, configured encrypted writes store ciphertext and an envelope link, encrypted reads fail closed when the capability is absent, and feature modules do not import Encryption models or providers. Files keeps plaintext semantic checksums separate from stored-ciphertext integrity and uses the protection profile in its deduplication identity. Postbox encrypts message bodies while subjects, routing, participant, and attachment-reference metadata remain observable.