Skip to content

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

  1. Wrap navigator.credentials in 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) wraps create and get for publicKey requests 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.
  2. A private channel, one handover per document. An isolated-world bridge (passkey-bridge.content.ts, also at document start in every frame) creates a MessageChannel and 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 window message events, so a page's postMessage is never a request. The bridge derives the origin itself; the background takes it from the browser's sender record.
  3. 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.
  4. The daemon holds and uses the key. A passkey is an entry of type passkey (value type 11) with rp_id, credential_id, user_handle, user_name, display_name, private_key, alg (-7), counter and created. 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) refuses private_key, and export is the only way out. Attestation is none with the vaultfold AAGUID ae8f3184-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.
  5. 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) in passkey-list, passkey-create and passkey-get, and passkey-get also refuses an entry whose rp_id differs. Only the daemon's check knows the public suffix list.
  6. Anything the extension cannot serve falls through to the browser and logs the reason: cross-origin frames, prf and largeBlob, 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, and mediation: "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.
  7. 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 passkey entries, so a passkey made in Chrome signs in from Safari once those land. This change builds none of them.
  8. 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.credentials is 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, prf and largeBlob are version 1 limits, not designed in.