0048: Passkeys by page-world interception, with OS providers as a separate path
- Status: accepted (add-browser-extension archived 2026-10-30)
- Date: 2026-10-27
- Change:
add-browser-extension(design.md "Decisions" and "Group 9 decisions")
Context
A synced password manager has to hold passkeys to replace the one it
displaces. Browsers expose no API for an extension to be a WebAuthn
authenticator: Chrome's webAuthenticationProxy is meant for remote
desktop and serves one extension only. Other extension-based managers wrap
navigator.credentials in the page's world. Safari and native apps cannot
be served that way, and need the OS credential provider APIs (macOS 14 and
iOS 17 ASCredentialProviderExtension, Windows 11 plugin authenticators,
Android 14 Credential Manager), which belong to the desktop and mobile
changes.
Decision
- Wrap
navigator.credentialsin the page world. On Chromium-family browsers and Firefox, a script registered for the main world at document start in every http(s) frame (passkey.content.ts) wrapscreateandgetforpublicKeyrequests and reports conditional mediation and user-verifying platform authenticators as available. It has no extension API and holds no secret or entry data. Safari registers neither passkey script. - A private channel, one handover per document. An isolated-world
bridge (
passkey-bridge.content.ts, also at document start in every frame) creates aMessageChanneland hands one port to the wrapper by a synchronous DOM event pair; each side accepts one handover, and the bridge drops its hello listener once the wrapper answers ready. The bridge never reads windowmessageevents, so a page'spostMessageis never a request. The bridge derives the origin itself; the background takes it from the browser's sender record. - The user confirms every ceremony in extension-owned UI. Create and get show the origin, rp id and account in the inline menu frame under the same activation gate as fills. The user can choose "Use another passkey or security key", which calls the saved original with the page's own arguments.
- The daemon holds and uses the key. A passkey is an entry of type
passkey(value type 11) withrp_id,credential_id,user_handle,user_name,display_name,private_key,alg(-7),counterandcreated. The daemon generates the P-256 key (core/webauthn), builds the authenticator data (user present always; backup eligible and backed up always; user verified only after the daemon's own verification) and signs ES256. The extension receives the public key, credential id and signature, never the private key: every value path (resolve,get,read,copy,edit,run,inject) refusesprivate_key, andexportis the only way out. Attestation isnonewith the vaultfold AAGUIDae8f3184-7890-474b-9bb6-a70cfec6a895. The counter is 0 for passkeys vaultfold creates (WebAuthn permits it for synced credentials) and the largest stored candidate, incremented, for imported ones. - The rp id is checked three times. The bridge falls a request through
when the rp id is not the frame's host or a parent domain of it; the
background refuses with
SecurityError, before any prompt or daemon request, an rp id that is not lowercase or not the origin's host or a parent domain; the daemon repeats the check from the origin the extension supplies (webauthn.ValidRPID: secure origin, not an IP, host or parent domain, and not a public suffix) inpasskey-list,passkey-createandpasskey-get, andpasskey-getalso refuses an entry whoserp_iddiffers. Only the daemon's check knows the public suffix list. - Anything the extension cannot serve falls through to the browser and
logs the reason: cross-origin frames,
prfandlargeBlob, a hybrid hint, enterprise attestation or platform attachment with real attestation, no ES256 parameter, a related-origin rp id, no vaultfold passkey for the rp id (with no UI shown), a daemon that cannot be reached, andmediation: "conditional". Listing vaultfold passkeys under conditional mediation is a follow-up (ticket 01M5HW4AKV). On-click mode registers no passkey script, so the browser's own implementation runs. - OS providers are a separate path that shares the entry type. Safari
and native apps get passkeys from the desktop and mobile apps' credential
provider integrations, built in their own change. They read and write the
same
passkeyentries, so a passkey made in Chrome signs in from Safari once those land. This change builds none of them. - Unknown value types fold opaque. A client that does not know a type
keeps it, shows
type(N)and prints no field unless asked, so older clients sharing a vault with this one lose nothing.
Consequences
- A site can detect that
navigator.credentialsis wrapped and can replace or call the wrapper. It cannot widen what it gets: the origin comes from the browser, the user confirms each ceremony, and the key stays in the daemon. A site can refuse to work with a wrapped API or fingerprint vaultfold users; every extension-based provider has this property. - Relying parties that require a platform authenticator with real attestation, or an AAGUID allowlist, will refuse vaultfold or not ask; the extension falls through where it can see the request is one of those.
- Passkeys in Safari and native apps do not work until the OS provider integrations exist.
- Related origin requests, hybrid flows,
prfandlargeBlobare version 1 limits, not designed in.