# Device Key And Identity Trust Concept

`govoplan-identity-trust` should own the trust primitives that let GovOPlaN
separate authentication, authorization, and cryptographic access.

The initial driver is encrypted postbox support, but the same trust layer may
later support stronger assurance, signatures, recovery policy, and external
recipient trust.

## Responsibilities

The module owns:

- public key directory
- per-device encryption keys
- account or identity public signing-key references
- device registration and revocation
- key rotation and key epochs
- assurance metadata from OIDC, WebAuthn, SAML, or other providers
- bounded assurance evidence and recovery/lost-device policy hooks
- audited key-access and rewrap decisions

It should not own login sessions, tenant membership, groups, functions, roles,
or permission decisions. Those remain in `govoplan-access`.

## Postbox Contract

For encrypted role/function postboxes, identity trust should be able to:

- publish recipient/device public keys
- verify that a device belongs to the authenticated actor
- track key epochs when role membership changes
- rewrap or release encrypted content keys only after access approves the actor
- emit audit events for key fetch or rewrap operations

The module must never require an identity provider or directory service to see
message plaintext or private Postbox keys.

## Implemented Boundary

The SQL-backed module now provides:

- tenant-bound public JWK registration with replay safety and explicit
  revocation;
- effective key epochs for identities, accounts, functions, Postboxes, and
  external recipients, including an explicit retained-history policy;
- immutable allow/deny key-access decisions bound to the upstream Access
  decision, acting account, device, epoch, purpose, assignment/delegation, and
  resource;
- bounded assurance evidence with provider, level, device, verification,
  expiry, and maximum-age checks;
- migrations, uninstall guards, permissions, APIs, capability contracts, and
  manifest-driven user/admin documentation.
- bounded user and security-officer projections for public device keys,
  assurance provenance, subject epoch history, and immutable key-access
  decisions;
- user key revocation and security-officer epoch rotation surfaces with stale
  revision rejection and explicit non-retroactivity consequences;
- optional Access-backed account selection without making Access a hard module
  dependency.

Only public keys are accepted. JWK private parameters are rejected by the Core
contract. Key-access decisions state explicitly that no cryptographic material
was released. A concrete Encryption provider performs any later key rewrap.

## Epoch And History Semantics

A function or Postbox has one active epoch. Rotation supersedes, but does not
rewrite, the previous epoch. The grant records one explicit history policy,
with `all_retained` as the accepted baseline for a new incumbent. Other bounded
policies may be selected by Policy. Rotation does not itself grant resource
access and ownership transfer does not transfer a private key.

Revocation stops future server-mediated release or rewrap decisions. It cannot
erase plaintext, exports, printouts, or keys already obtained by an endpoint.
That limitation must remain visible to users and operators.

## Recovery

Database recovery restores public keys, epochs, assurance references, and
decision evidence. It cannot restore private device keys. Lost-device recovery
therefore registers a new device key, rotates affected epochs under a separate
authorized workflow, and leaves the old key revoked. Encryption key custody
and quorum recovery remain with `govoplan-encryption` and its selected provider.

## Current Limits

- There is no private-key custody or browser/device key generator.
- Attestation references are retained but no WebAuthn/OIDC attestation adapter
  is selected yet.
- Device key generation and registration remains provider/browser driven; the
  administration UI deliberately does not ask an operator to paste private or
  manually generated key material.
- The module decides trust eligibility; it does not perform encryption,
  decryption, signing, or rewrapping.