# GovOPlaN Encryption

<!-- govoplan-repository-type:start -->
**Repository type:** module (platform).
<!-- govoplan-repository-type:end -->

`govoplan-encryption` is the optional provider-neutral boundary for governed key
vaults, versioned content-protection envelopes, key lifecycle operations,
recovery ceremonies, and disable/uninstall assurance.

## Implemented

- opaque provider capability contracts; raw key material never crosses them;
- tenant/scope-bound vault and key-version metadata;
- idempotent provision, rotation, revocation, destruction scheduling, and
  outcome-unknown reconciliation;
- versioned ciphertext envelopes with authenticated-context and migration
  provenance;
- resumable, evidence-backed rewrap, re-encryption, decrypt, export, and destroy
  state transitions;
- recent high-assurance, distinct-custodian quorum recovery authorization;
- bounded tenant administration for safe vault/envelope status, key lifecycle,
  two-phase migration coordination, recovery decisions, and disable preflight;
- typed APIs, audit-safe events, Alembic migration, and uninstall blocking;
- a bundled `local_aesgcm` server-envelope provider using AES-256-GCM and
  SQL-persisted wrapped vault/content keys;
- owner-facing content protect/open/rewrap and two-phase re-encryption
  operations that never export key material;
- Files and Postbox encrypted-content adapters and fail-closed fixtures.

## Provider Boundary

The bundled provider derives a deployment wrapping key from `MASTER_KEY_B64` and
keeps vault and per-content keys wrapped in shared SQL state. It provides real
authenticated encryption at rest, but the application server can decrypt and
therefore this is not E2EE, an HSM/KMS assurance claim, or independent
certification. Production backup and restore must preserve the database,
ciphertext storage, and exact deployment key as separate governed assets.

No client E2EE protocol, tenant KMS/HSM driver, provider credentials, or formal
certification profile is bundled. Those remain provider-specific work and must
pass conformance, backup/restore, key-loss, interoperability, and security review
before a stronger product claim is made.

Feature modules continue to own content, authorization, retention, and resource
ownership. Access approval, resource ownership, Identity Trust, and key custody
are separate decisions.

The administration surface intentionally omits provider key references, wrapped
key references, ciphertext locations, and cryptographic material. Lifecycle
commands require policy and assurance references; destructive actions explain
their irreversibility and do not imply that previously obtained plaintext can be
recalled.

See [docs/ENCRYPTION_BOUNDARY.md](docs/ENCRYPTION_BOUNDARY.md) for the threat
model, profile consequences, algorithms, recovery, and disable semantics.

## Verification

```bash
cd /mnt/DATA/git/govoplan-encryption
PYTHONPATH=src:/mnt/DATA/git/govoplan-core/src \
  /mnt/DATA/git/govoplan/.venv/bin/python -m unittest discover -s tests
```

## Git-source WebUI package

The repository root exposes `@govoplan/encryption-webui` for Git-tagged release
dependencies. It mirrors the owning `webui/package.json` version, public
TypeScript/CSS exports and peer requirements, with entry paths under
`webui/src`. Consumers provide the shared Core/React peers; the facade runs no
development or install scripts. The source archive contains `webui/src`, this
README and any repository license file. Run module development checks from `webui/`; Python
installation remains governed by `pyproject.toml`.

Das Repository stellt `@govoplan/encryption-webui` am Wurzelpfad für versionierte
Git-Abhängigkeiten bereit. Version, öffentliche TypeScript-/CSS-Exporte und
Peer-Anforderungen entsprechen `webui/package.json`; die Einstiegspfade liegen
unter `webui/src`. Gemeinsame Core-/React-Peers stellt die einbindende Anwendung
bereit. Die Fassade führt keine Entwicklungs- oder Installationsskripte aus.
Entwicklungsprüfungen bleiben in `webui/`, die Python-Installation weiterhin in
`pyproject.toml` definiert.