ADR 0011: Passkey-based portable vault access

Keep authentication and encryption recovery separate while using WebAuthn PRF to protect a portable Ownfold device key.

Status

Accepted for implementation.

Decision

Ownfold passkey vault access is a recovery and device-enrollment mechanism. It is not an authentication provider and does not replace a normal browser device.

A dedicated Ownfold WebAuthn credential produces a local PRF result. HKDF-SHA-256 derives an AES-256-GCM key from that result. The derived key encrypts a portable X25519 private key, whose public key receives a normal Ownfold root-key envelope. A new browser opens both layers locally, then enrolls itself as an ordinary Ownfold device and discards access to the portable private key.

WorkOS or another host provider still decides which authenticated user owns the vault. A hosted authentication passkey does not expose its PRF result to Ownfold and therefore cannot recover the vault encryption key.

Better Auth implementation study

Better Auth 1.6.23 implements passkeys as a plugin over SimpleWebAuthn. The parts worth following are:

• registration and authentication options are generated on the server;
• a random token is stored in a signed, five-minute cookie while the challenge and ceremony type are stored in a verification row;
• verification atomically consumes that row before accepting the ceremony, preventing replay and concurrent double completion;
• registration persists credential ID, COSE public key, counter, device type, backup state, transports, creation time, and AAGUID;
• authentication looks up the exact credential, calls verifyAuthenticationResponse, updates the returned counter, and only then creates a session; and
• the browser client removes clientExtensionResults before sending the WebAuthn response to the server. It can return those results to the local caller when requested.

See Better Auth’s routes.ts, client.ts, and schema.ts.

The Better Auth plugin cannot be reused unchanged for vault access:

• it requests userVerification: "preferred" and verifies with requireUserVerification: false; Ownfold requires both to be strict;
• unless configured, it accepts the request Origin header as the expected origin; Ownfold uses an explicit allowlist and configured RP ID;
• its challenge is bound to the user and ceremony, but not an Ownfold vault, vault revision, or portable device;
• it has no PRF-input lifecycle, HKDF domain separation, portable-key encryption, root-key envelope, revocation, or root-rotation integration; and
• its stored counter update is not itself a substitute for Ownfold’s optimistic record revision.

Better Auth’s generic extension support is still useful. Registration and authentication options can request prf, and keeping clientExtensionResults out of the verification request is the right transport boundary. Ownfold must additionally validate prf.enabled, handle registration without an initial PRF result by performing a follow-up assertion, and ensure no PRF result is serialized by browser or framework helpers.

Required invariants

• The PRF result, portable private key, root key, Recovery Kit secret, and record keys never reach the server.
• Challenges are random, one-time, expiring, and bound to owner, vault, operation, revision, and credential when known.
• Registration and assertion require user verification, the configured RP ID, and an exact allowed origin.
• The portable private-key ciphertext authenticates its full versioned context, including owner, vault, credential, portable device, public key, root-key version, RP ID, PRF input, KDF parameters, and creation time.
• Active portable public keys receive replacement root-key envelopes during rotation without invoking a passkey.
• Revoking passkey access blocks future server-assisted recovery but does not revoke normal devices previously enrolled through it.
• Unsupported WebAuthn or PRF capability fails closed and leaves Recovery Kit restoration and existing-device pairing available.

Consequences

The passkey ceremony may add a second biometric prompt after hosted WorkOS passkey login on a new device. Synced passkeys improve portability but PRF capability remains a runtime requirement. The Recovery Kit stays the emergency recovery mechanism.