feat(postbox): add governed content protection profiles

This commit is contained in:
2026-08-20 03:42:58 +02:00
parent 15d93aaa25
commit 174ee97719
16 changed files with 3917 additions and 383 deletions
+79 -44
View File
@@ -12,14 +12,16 @@ needed a role, process, portal, campaign, or service responsibility. It may look
like an inbox for a message task or like a vault for content shared with the
current holders of that responsibility; neither form is owned by one account.
The strategic target is an encrypted administrative postbox. The current
implementation supports ordinary persisted messages and an optional
server-readable Encryption envelope for message bodies. The model also retains
external ciphertext, wrapped-key, signed-manifest, external-recipient-token,
and key-epoch metadata needed for later independently reviewed E2EE profiles.
The server-envelope profile is not E2EE, and subjects, routing, participants,
and attachment references remain visible. The
cross-module target architecture is recorded in
The strategic target is a policy-selectable administrative postbox. The current
implementation offers unencrypted content, an institution-managed Encryption
envelope, and a strict external E2EE boundary. E2EE messages contain only an
external ciphertext reference, signed-manifest reference, wrapped recipient
keys, and a verified plaintext digest; an approved producer or client owns the
actual cryptographic operation and private-key custody. GovOPlaN cannot decrypt
that profile. The institution-managed envelope remains server-readable by
authorized institutional key holders. Subjects, routing, participants, and
attachment references remain visible in every profile. The cross-module target
architecture is recorded in
`govoplan-core/docs/POSTBOX_E2EE_ARCHITECTURE.md`.
## Function-Organization-Bound Access
@@ -356,47 +358,80 @@ The WebUI should start as an administration and inbox surface:
Campaign, files, portal, and mail behavior should arrive as optional integrations after the core postbox model is stable.
### Current content-protection profile
### Configurable content-protection profiles
An exact Postbox or template revision may select `server_envelope_v1` and an
Encryption vault. New locally authored and delivered message bodies are then
stored in `body_ciphertext` with an owner-bound envelope reference; clear body
text is not persisted. Reads ask the optional `encryption.content_cipher`
capability to open the exact tenant, message, and envelope tuple. Missing
Encryption, a lost deployment key, a destroyed vault key, ciphertext tampering,
or a mismatched resource causes a fail-closed read.
An exact Postbox or template revision selects one profile. The administration
surface recommends the managed profile and requires its vault explicitly; the
API retains the legacy plaintext default when an older integration omits these
new fields so an upgrade cannot make an unavailable Encryption module block
existing automation.
Plaintext Postboxes continue to work without Encryption. A protected Postbox
cannot silently fall back to plaintext. Database recovery of protected messages
requires Postbox and Encryption tables from the same consistency point plus the
matching provider/deployment key. Hierarchy-routed copies retain the source
envelope reference rather than decrypting and re-encrypting during routing.
- `server_envelope_v1` is the recommended standard. New local message bodies
are encrypted through the optional `encryption.content_cipher` capability,
stored in `body_ciphertext`, and linked to an owner-bound envelope in the
institution's selected vault. Authorized reads ask that capability to open
the exact tenant, message, and envelope tuple. Missing Encryption, unavailable
or destroyed keys, tampering, and resource mismatch fail closed.
- `external_e2ee_v1` is a server-blind storage contract. Clear bodies are
rejected. A producer must provide a ciphertext reference, signed manifest,
wrapped recipient keys for the current key epoch, and `sha256` content digest.
The server retains and authorizes those artifacts but has no private key with
which to decrypt them.
- `plaintext_v1` stores the body without content encryption. It remains
available for deployments that explicitly choose transport and
infrastructure controls only.
## E2EE Readiness Checklist
No profile hides operational metadata. Subjects, senders, participants,
routing, timestamps, classifications, attachment references, receipts,
retention state, and access evidence remain server-visible. Native browser or
device enrollment, private-key custody, offline recovery, and independently
reviewed cryptographic clients are not bundled by Postbox; an institution that
selects E2EE must provide and govern that client/provider boundary.
Before the data model is considered stable, verify that it can represent:
### Protection and hand-over policy
- message or attachment ciphertext references
- signed manifest references
- recipient, role, or function key wrapping records
- key epoch and device-key references
- key-fetch/access audit events
- external recipient token state
- expiry and withdrawal state separate from deletion
- retention state that can operate without decrypting content
Each Postbox snapshots policy for the choices that cannot safely be inferred:
## E2EE decisions still to settle before implementation
- a new incumbent sees all retained history, content since assignment, or a
bounded look-back period;
- ordinary and compromise rotations select key rewrapping or full content
re-encryption;
- recovery, hand-over, emergency access, export, and destruction name the
required user-consent, institutional key-holder, or dual-control authority
and quorum;
- external retrieval requires strong identity, email plus a one-time code, or
may be disabled; and
- vacancy escalation is always metadata-only and never gives an unrelated
personal account content access.
The product direction above is selected, but the first trusted profile still
needs bounded decisions on:
The defaults are deliberately conservative: history since assignment,
ordinary rewrapping, re-encryption after compromise, two-person institutional
recovery, dual-control hand-over/emergency/export/destruction, strong external
identity, and metadata-only vacancy escalation. These are product defaults, not
hard-coded policy decisions; administrators can change them per template or
exact Postbox.
- whether a new incumbent receives all retained history, history from a
policy-defined date, or only content delivered during the assignment;
- organizational recovery/escrow and the authority required when every holder
loses all registered device keys;
- whether ordinary rotation only rewraps per-content keys or also re-encrypts
ciphertext, and which events require the stronger path;
- assurance and quorum requirements for delegation, hand-over, emergency
access, export, and destructive retention; and
- how attention/escalation works during a vacancy without granting plaintext
access to an unrelated personal account.
### Governed profile transitions
A profile change increments the Postbox key epoch and applies immediately to
new messages. The administrator chooses whether retained history stays under
its existing profile or is migrated. Every transition records an idempotency
key, source and target profiles/vaults, user-consent and/or institutional
authorization evidence, quorum, reason, immutable configuration snapshot,
message digests, and per-message outcome.
Plaintext-to-managed and managed-to-plaintext migrations can complete through
the configured Encryption capability. Managed decrypt, export, and
re-encryption operations are also written to the Encryption migration ledger;
old envelopes are not merely orphaned. A transition to or from E2EE pauses each
historical message until an approved external client supplies the ciphertext or
plaintext transform and evidence. Postbox checks the immutable SHA-256 digest
before committing the new representation. Leaving E2EE requires user-consent
evidence; changing institution-managed history requires institutional
key-holder evidence; dual control can require both. Previously viewed, copied,
printed, or exported cleartext cannot be recalled and must be acknowledged.
Database recovery of managed messages requires Postbox and Encryption tables
from the same consistency point plus the provider/deployment key. Recovery of
E2EE content additionally depends on the institution's external private-key
custody and client procedures.