Key Management
DarkAuth stores account key material as encrypted envelopes. The server persists metadata and ciphertext, while clients unwrap keys with material derived from OPAQUE login, passkey PRF output, trusted devices, or recovery keys.
Keybag
Section titled “Keybag”The keybag is the user’s encrypted account-key container. It contains an active account key and one or more envelopes that can unwrap that key. Envelopes can be created, rotated, revoked, and listed without returning plaintext key material.
Envelope types are:
passwordfor OPAQUE-derived login material.passkey_prffor WebAuthn PRF-capable authenticators.trusted_devicefor an approved device handoff.recoveryfor user-held recovery keys.
Use the keybag APIs for current integrations. Legacy wrapped-DRK endpoints can exist for older clients, but new work should use key envelopes and v2 client app key delivery.
Locked and unlocked sessions
Section titled “Locked and unlocked sessions”Authentication and key unlock are separate state. A password login can authenticate and unlock because OPAQUE export-key material is available in the browser. A federated login or authentication-only passkey can authenticate the user while leaving the session key locked.
Zero-knowledge authorization requests require an unlocked session before the frontend can derive and deliver a client app key. If the session is locked, the user UI should offer an unlock path rather than finalizing key delivery.
The available unlock paths come from the user’s effective unlock policy. The policy combines account state, SCIM policy, envelope availability, and client requirements so the UI can offer only valid choices. A user can be signed in by federation or an auth-only passkey and still need a separate password, recovery-key, PRF passkey, trusted-device approval, or setup flow before a ZK client can receive key material.
Passkeys
Section titled “Passkeys”Passkeys can be registered and used for sign-in. When a credential supports PRF, the client can create a passkey envelope so the account key can be recovered from the authenticator without exposing the passkey secret to the server.
Applications should treat PRF support as capability-dependent. Auth-only passkeys are still useful for sign-in, but they do not unlock the account key. Users may still need password, trusted-device, or recovery-key envelopes.
Trusted devices
Section titled “Trusted devices”Trusted devices let an already trusted browser approve a new device. The approving device creates an encrypted envelope for the requesting device, and the requester consumes that approval to unwrap the account key.
Approvals are short-lived and user scoped. Users should revoke devices they no longer control.
Trusted-device approval is an explicit unlock method. The new browser starts the approval request, the trusted browser approves the matching request, and the requester finalizes the handoff before DarkAuth marks that session key-unlocked.
Recovery keys
Section titled “Recovery keys”Recovery keys are user-held secrets. DarkAuth stores verifier hashes and encrypted recovery envelopes, not plaintext recovery keys. A recovery key can be marked used, revoked, and replaced.
Recovery keys should be generated, displayed, and stored through a deliberate user flow. Do not silently create recovery keys that users never save.
Federation and SCIM
Section titled “Federation and SCIM”Federation and SCIM manage identity lifecycle. They do not give the upstream identity provider access to plaintext DarkAuth key material.
For federated users, the external OIDC provider can satisfy authentication while DarkAuth still requires a local unlock method for zero-knowledge clients. For SCIM-managed users, admin policy decides which envelope types are allowed, whether only provisioned users can sign in, and whether trusted-device approval is available.
Security boundary
Section titled “Security boundary”The backend can store encrypted envelopes, metadata, hashes, and audit events. It must not receive OPAQUE export keys, passkey PRF outputs, recovery keys, plaintext account root keys, plaintext client app keys, or decrypted application data in the designed flow.
Frontend code that handles unlocked keys is inside the trust boundary. Keep key material in memory unless the product deliberately accepts persistent local custody, clear it on logout, and never log envelopes, plaintext keys, recovery secrets, or fragment JWE payloads.