# Postbox End-To-End Encryption Architecture

This document records the strategic encryption target for GovOPlaN postboxes.
It does not require the first postbox implementation to ship full E2EE, but it
defines the architecture so early data models and APIs do not make the stronger
model impossible.

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.

## 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

## 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.

## 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.