bitlogin/docs/passkey-login.md

# Passkey Sign-In — Zero Registration, Zero Servers

**Document version:** 0.1
**Status:** **Implemented** (2026-08-04). Supersedes the OAuth on-ramps of
[`centralized-onramps.md`](./centralized-onramps.md) (removed the same day;
that document stays on the record with the analysis of why every OAuth path
requires per-site provider registration — the requirement this design
exists to escape).
**Depends on:** `docs/spec.md` (standard registration §15 and login §16 are
reused unchanged), `docs/second-factor.md` §SF10 (import), WebAuthn PRF
extension.

---

# PK1. What it is

"Continue with a passkey": the browser's own credential sheet — for most
users backed by Google Password Manager or iCloud Keychain, so it *feels*
like signing in with the account they already have — unlocks a standard
BitLogin capsule account. The site ships the static widget and does nothing
else. No OAuth client ID, no provider console, no app review, no server, no
stored credential file anywhere: the credential is **derived, not fetched**.

Mechanically: the passkey's WebAuthn **PRF extension** evaluates a fixed,
domain-separated input (`bitlogin:passkey-credential:v1`) and returns 32
bytes only that passkey can produce. `passkey.ts` derives from it — via
HKDF, under a frozen v1 contract — a login name (`pk-<12 hex>`) and a
256-bit password, which feed the ordinary, audited password flows. The
derivation chain of the core spec is untouched; to the protocol this is
just a password that arrives from an authenticator instead of a keyboard.

**The derivation is a compatibility contract.** `passkey.test.ts` pins
known-answer vectors; a failure there is never "update the expected value"
— same standing rule as `knownAnswer.test.ts`.

# PK2. Why this beats OAuth on-ramps

Every OAuth provider requires a pre-registered per-application credential —
that gatekeeping *is* their product — and most additionally require a
client secret (a server). Passkeys are a web-platform API: no registration
with anyone, works on every site the moment the widget loads, and the
custody still lands where normies already keep their digital lives (their
Google or Apple account, via passkey sync). It is the only design that is
simultaneously zero-site-setup, zero-server, and zero-third-party.

# PK3. Custody, loss, and recourse

Stated the way §CO7 demands — who can access, what happens on loss, how to
leave:

- **Who holds what:** the passkey (and thus the account credential it
  derives) lives in the user's authenticator — typically synced by Google
  Password Manager or iCloud Keychain, optionally a hardware key or a
  third-party manager. The site holds nothing. BitLogin holds nothing.
- **Lost phone or laptop: usually fine.** Synced passkeys are exactly the
  failure mode passkeys were built for — sign into the platform account on
  a new device and the passkey is there. This is *better* than a
  remembered password, which dies with the memory, and better than the
  removed Drive rail, which died with a client ID.
- **Lost platform account (Google/Apple ban or lockout), or a device-bound
  key that's gone: the passkey is gone.** Recourse: the **12-word recovery
  phrase**, which every passkey account has, because the ceremony is
  **mandatory at registration** (owner decision 2026-08-04) — the session
  is not granted until the user has seen the phrase and answered the
  three-word quiz, exactly as password signup works. The deferred "secure
  your account later" card this replaced was inherited from the OAuth
  on-ramp design, where a service still held a copy of the credential;
  nothing holds a copy here, so deferring the only recovery path was
  strictly worse than the design it was borrowed from.
- **Lost site domain.** Worth stating because it surprises people: the
  passkey is bound to the site's WebAuthn RP id, so if a deployment changes
  domain, its users' passkeys no longer unlock anything there. The account
  is untouched on relays and the phrase (or password) still works — another
  reason the ceremony is not optional.
- **One passkey = one account.** PRF output is per-credential, so a second
  passkey derives a *different* account — there is no "add a backup
  passkey" for the same account. The backup for the account is the phrase
  (or a held password), not a second passkey. The sync fabric is the
  passkey's own redundancy.
- **Per-site scoping.** Passkeys are bound to the site's domain (rpId), so
  like every on-ramp this is per-site convenience; cross-site portability
  is the capsule account's job, via password or phrase.

# PK4. Graduation

Unchanged ladder, same npub throughout: save the npub; claim the phrase
(one tap from the dashboard card while it's still in session memory);
rotate to a self-held password — the rotate screen tells passkey users
plainly that this retires the passkey unlock ("you hold it, nobody else");
or full export. §SF10 import remains the same-identity escape hatch in the
other direction: an existing nsec can be wrapped into a passkey-unlocked
account at setup.

# PK5. UX flow

- Menu row (shown when WebAuthn exists): "Continue with a passkey" / "Kept
  in your phone or browser's password manager."
- The passkey screen offers "Use my passkey" (primary) and "Create a new
  passkey." Sign-in with a passkey that has no account on this site routes
  into first-time setup *with the credential it already derived* — fresh
  identity or import — rather than erroring.
- Setup runs the recovery ceremony before granting a session: phrase shown,
  three words verified, then the dashboard. The setup screen says so up
  front ("Next you'll save a 12-word recovery phrase… it isn't optional"),
  so it reads as part of the flow rather than an interruption. Net secret
  count is still lower than password signup — one phrase, versus a password
  *and* a phrase — and daily sign-in is a biometric tap.
- Re-creating setup against a passkey whose account already exists simply
  signs in (`AccountAlreadyExistsError` → login with the same derived
  credential); a passkey sign-in against no account offers setup
  (`AccountNotFoundError`). Both directions are idempotent by construction.

# PK6. Support boundaries

PRF requires a modern authenticator stack, and support is **genuinely
uneven across password managers today** — this is the method's real
limitation, not a rounding error. Support cannot be feature-detected
without running a ceremony (the widget asks for `prf` in the ceremony and
inspects the result), so an unsupported combination surfaces as an honest
in-flow message pointing at the other methods rather than a mystery
failure or a half-created account. The password path remains the universal
fallback — and the primary method, per the standing password-first
decision (§LM9.1).

Known provider status, as observed 2026-08-04. Treat as a snapshot: this
landscape moves, and only the ceremony is authoritative.

| Provider | PRF | Notes |
| --- | --- | --- |
| Chrome / Android + Google Password Manager | Yes | The mainstream path; passkeys sync with the platform account. |
| Safari / iOS + iCloud Keychain (recent versions) | Yes | Same shape on Apple platforms. |
| Bitwarden browser extension | Yes | Uses PRF itself for passkey vault unlock; open source, self-hostable via Vaultwarden — the practical choice on Linux desktops. |
| Hardware keys with hmac-secret (YubiKey 5, Nitrokey 3, SoloKeys v2) | Yes | PRF rides on CTAP2 hmac-secret. |
| KeePassXC 2.7.12 | **No** | Stores and manages passkeys (`credProps` present) but ships no `prf`/`hmac-secret` support — verified by binary inspection on 2.7.12, and PRF evaluation must happen inside the authenticator, so the browser extension cannot supply it. Users see the unsupported message. |
| de-Googled Android (/e/OS, GrapheneOS without Play Services) | Not reliably | Browser ceremonies typically route through Play Services' FIDO2 API; third-party credential-provider coverage is still patchy. Such users are well served by the NIP-46 remote-signer rail instead (§LM5), which needs no platform account at all. |

For a deployment, the practical reading: offer passkeys, expect a
meaningful minority to fall back, and never make the passkey the only
route to an account — which the graduation ladder (§PK4) already
guarantees.