# Postbox End-To-End Encryption Architecture This document records the encryption boundary for GovOPlaN postboxes. Postbox now implements the server-side contracts for three selectable profiles: unencrypted content, institution-managed server envelopes, and externally produced E2EE envelopes. The E2EE contract is operational—the server rejects plaintext and retains ciphertext, signed manifests, wrapped keys, and digest evidence—but a reviewed browser/device client and private-key custody provider remain separately deployed responsibilities. The core principle is that a postbox can become a trusted administrative communication channel without requiring the server to see plaintext content. The server may route, store, authorize, audit, retain, and expire messages while message bodies and attachments remain client-encrypted. ## Goals - asynchronous encrypted delivery for internal and portal-facing postboxes - personal, organizational, role-bound, and function-bound postboxes - attachments encrypted with the message - access based on current role/function membership when configured - honest retraction and expiry semantics - auditable key access, delivery, and fetch events - support for external recipients without platform accounts - replaceable identity and trust providers ## Envelope Model The target model is envelope encryption: - Generate one random data encryption key per message or attachment set. - Encrypt content with an authenticated encryption algorithm. - Wrap the data encryption key for each authorized recipient or role mailbox. - Store only ciphertext, wrapped keys, signed manifests, and governed metadata on the server. Algorithm choices should remain replaceable behind a crypto profile. The first profile should prefer standard, reviewed primitives such as HPKE for key wrapping and AEAD encryption for content. ## Product Profiles And Default The content-protection policy is configurable per exact Postbox or immutable template revision: - `server_envelope_v1` is the recommended default. An institution-selected Encryption vault controls server-readable envelopes and their migration evidence. It is not end-to-end encryption. - `external_e2ee_v1` is server-blind. An approved client or producer supplies the ciphertext reference, signed manifest, wrapped recipient keys, key epoch, and SHA-256 plaintext digest. GovOPlaN has no private key that can decrypt it. - `plaintext_v1` stores clear content for institutions that explicitly choose that boundary. Operational metadata—including subject, routing, participants, classifications, timestamps, attachment references, receipts, and retention state—remains visible under every profile. Administrators therefore choose a content-protection boundary, not a metadata-anonymity profile. The standard policy grants new incumbents history since assignment, uses key rewrapping for ordinary rotation and content re-encryption after compromise, requires two-person institutional recovery and dual-control hand-over, emergency, export, and destruction, requires strong external identity, and limits vacancy escalation to metadata. Deployments may select other policy values rather than inheriting a decision from GovOPlaN. ## Governed Profile Changes A profile transition applies to new messages immediately and increments the Postbox key epoch. Retained history can remain under the previous profile or be migrated. The transition ledger records source and target profiles/vaults, authority route, consent and key-holder evidence, quorum, reason, immutable configuration snapshot, per-message source and target digest, and outcome. Plaintext and managed-envelope migrations can use the server-side Encryption capability. Managed decrypt, export, and re-encryption operations also create Encryption migration records so old envelopes are disposed of through the governed provider contract. Any transition to or from E2EE pauses each retained message for an approved client transform. The client must return plaintext or ciphertext as appropriate, plus evidence and the original content digest; Postbox verifies digest continuity before changing the stored representation. Leaving E2EE requires user-consent evidence, while changing managed history requires institutional key-holder evidence. Dual control can require both. This transition mechanism cannot revoke plaintext already decrypted, copied, printed, or exported. Administrators must explicitly acknowledge that residual disclosure before a transition is accepted. ## Identity And Device Keys The platform should distinguish: - account identity - tenant membership - role/function assignment - device key - postbox binding Identity providers and directories can authenticate users and provide membership facts, but they must not see postbox private keys or message plaintext. The trust layer should provide: - public key directory - account or identity signing keys - per-device encryption keys - device registration and revocation - key rotation and epoch tracking - recovery policy hooks Recovery must be organizationally governed. A server-held universal plaintext key would defeat the E2EE claim; any escrow, threshold recovery, or emergency grant needs an explicit assurance profile, authority/quorum, audit trail, and user-visible consequence. ## Role And Function Postboxes Role-bound access needs special handling. A postbox can be bound to an organizational unit and a role or function. Current members can access current messages according to policy; former members should lose access to not-yet fetched material when revocation is still technically enforceable. The target design should support role encryption keys or an equivalent rewrapping service: - sender encrypts the content key for the role/function postbox - access service verifies current membership and required assurance - trust service rewraps the content key to the actor's current device key - audit records the key access decision and fetch event Key epochs are required when role membership changes. Older messages may remain readable according to policy, but new access must use the current epoch. The function-bound container exists independently of membership. It may remain vacant and continue to receive ciphertext without falling back to an unrelated personal mailbox. Zero, one, or several incumbents are valid states. Each incumbent receives an independently auditable, device-bound wrapped-key path; the postbox is never copied into their account ownership. A new assignment or hand-over rotates the function/postbox key epoch. Envelope encryption permits the normal rotation path to rewrap per-message data keys rather than rewrite large ciphertext objects; a security policy may require full content re-encryption for selected compromise or cryptographic-profile events. The history available to a new incumbent must be selected policy (all retained history, a bounded historical window, or assignment-time content) and recorded with the grant. Delegation is a time-bounded represented-function grant, not a copy or substitution of the postbox. Expiry or withdrawal stops future key release and actions. It cannot revoke plaintext already decrypted, printed, exported, or captured outside the platform. Multiple simultaneous incumbents and delegates remain distinguishable in key-fetch and action evidence. Postbox content and signed manifests are immutable. Correction or replacement creates a linked new object/version; it never silently substitutes ciphertext or evidence that another actor may already have inspected. ## External Recipients External recipients may need one-time or time-limited access without a full platform account. The target model should support capability links or invitation tokens that are: - scoped to specific message or attachment resources - time-limited - optionally one-time - protected by an out-of-band secret, passphrase, or stronger external identity proof - revocable before key fetch - fully audited ## Retraction Semantics GovOPlaN should be honest about retraction. Before a recipient fetches a key or decrypts content, the system can revoke tokens, remove wrapped-key access, expire links, and delete ciphertext according to retention policy. After a recipient has decrypted or copied plaintext, the system cannot make the recipient forget it. The platform can only record access, revoke future access, notify parties, and apply legal or organizational controls. The UI must explain this distinction whenever it offers expiry, retraction, or message withdrawal. ## Server Responsibilities The server remains important even when content is encrypted: - store ciphertext and signed manifests - store routing and policy metadata - enforce access before key release or rewrapping - provide public key directory access - emit notifications without plaintext content - record audit events - enforce retention and expiry where possible - expose diagnostics for delivery and key-access failures ## Module Ownership - `govoplan-postbox` owns postbox bindings, postbox messages, message metadata, and postbox UI. - `govoplan-identity-trust` owns device keys, public key directory, key epochs, and assurance integration. - `govoplan-access` owns current identity, membership, function, delegation, and permission decisions. - `govoplan-policy` owns retention, retraction, and security policy decisions. - `govoplan-audit` owns durable audit traces. - `govoplan-files` owns managed file storage when encrypted postbox attachments are backed by file objects. No module should import another module's internals to decrypt content. All interaction must use capabilities, DTOs, and audited service contracts.