diff --git a/docs/DEVICE_KEY_TRUST_CONCEPT.md b/docs/DEVICE_KEY_TRUST_CONCEPT.md new file mode 100644 index 0000000..72d9ef2 --- /dev/null +++ b/docs/DEVICE_KEY_TRUST_CONCEPT.md @@ -0,0 +1,37 @@ +# 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 should eventually own: + +- public key directory +- per-device encryption keys +- account or identity signing-key references +- device registration and revocation +- key rotation and key epochs +- assurance metadata from OIDC, WebAuthn, SAML, or other providers +- recovery and 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.