Design — `usePasskeyAutofill` (`@suaveplan/react-auth`)

Non-normative. Architecture, lifecycle, and rationale. The normative contract lives in specs/react-auth/spec.md.

Package shape

@suaveplan/react-auth is created by this change. It is a lightweight browser-tier package at packages/auth/react-auth/. Tier is browser (React 19 peer dep, DOM types fine). It holds exactly this hook and the optional <PasskeyAutofillField> wrapper today; future auth-related React hooks land in follow-up changes under the same package.

The hook lives at src/use-passkey-autofill/use-passkey-autofill.ts; the component at src/passkey-autofill-field/passkey-autofill-field.tsx; errors at src/errors/errors.ts. Each has a sibling .md, a .test.ts (or .test.tsx), and stories per CLAUDE.md.

Conditional UI background

WebAuthn Level 3 §5.1.4 defines mediation: "conditional". Browsers that support it surface available platform credentials in the autocomplete sheet of any <input> with autocomplete="username webauthn". The feature is gated on PublicKeyCredential.isConditionalMediationAvailable() — a static method that does not exist on Safari < 17, Firefox < 119, or any SSR environment. Calling navigator.credentials.get({ publicKey, mediation: "conditional" }) without that check throws NotSupportedError on older browsers, which @suaveplan/webauthn maps to WEBAUTHN.NOT_SUPPORTED.

The hook MUST therefore feature-detect before dispatching. Because feature detection is async and DOM-only, it can only run inside a useEffect.

Hook signature

interface UsePasskeyAutofillOptions {
    rpId: string;
    challenge: Uint8Array;
    onCredential: (result: AuthenticateResult) => void;
    onError?: (error: SuaveplanError) => void;
    signal?: AbortSignal;
    allowCredentials?: PublicKeyCredentialDescriptor[];
    userVerification?: UserVerificationRequirement;
    timeout?: number;
    expectedOrigin?: string;
    expectedRpIdHash?: Uint8Array;
}

interface UsePasskeyAutofillReturn {
    ready: boolean;
    error: SuaveplanError | null;
    abort: () => void;
}

function usePasskeyAutofill(opts: UsePasskeyAutofillOptions): UsePasskeyAutofillReturn;

ready flips to true after isConditionalMediationAvailable() resolves true AND the conditional authenticate Promise is in-flight. error carries the most recent translated error (cleared when a new attempt starts). abort is a stable useCallback that fires the internal AbortController.

Lifecycle — AbortController ownership

The hook owns exactly one AbortController per "session" (one mount, one option-identity). The controller is composed with the caller's options.signal via a small composeSignals(...signals) helper (any aborts → composed aborts).

Event	Behavior
Mount (client)	Run feature detect → dispatch `authenticate({ mediation: "conditional", signal: composed })`.
Mount (server)	No-op. The `useEffect` never runs.
Unmount	Call `controller.abort()`. The underlying `navigator.credentials.get` rejects with `AbortError`, mapped to `WEBAUTHN.ABORTED` → `REACT_AUTH.ABORTED`.
Caller `signal` aborts	Composed controller aborts → same as unmount path.
Caller calls returned `abort()`	Same as above. State remains mounted; consumer may re-trigger by changing option identity.
`<input>` blur (via `<PasskeyAutofillField>`)	Consumer-controlled. The component calls `abort()` on `onBlur` IF no credential has been delivered yet. The hook alone does not subscribe to blur (it does not touch the DOM).
Option identity changes (e.g. fresh `challenge`)	Effect re-runs: old controller aborts, new controller created, new request dispatched.
`onCredential` fires	Controller is left intact (the request is already settled); `error` cleared.
`onError` fires	Controller aborted; `error` stored; consumer may remount or change challenge to retry.

The hook MUST NOT touch the DOM directly — it works alongside an <input autocomplete="username webauthn"> rendered by the consumer. The browser surfaces the autofill UI based on the autocomplete token; the hook just keeps the conditional authenticate request pending so the browser has something to deliver into.

SSR safety

typeof window === "undefined" short-circuits before any navigator access.
isConditionalMediationAvailable() is called inside useEffect (which never runs server-side under React 19 SSR).
The hook returns { ready: false, error: null, abort: noop } on the server render, then re-renders on hydration.

Error translation

WEBAUTHN.NOT_SUPPORTED        → REACT_AUTH.AUTOFILL_UNAVAILABLE
WEBAUTHN.ABORTED              → REACT_AUTH.ABORTED
all other WEBAUTHN.*          → REACT_AUTH.AUTOFILL_FAILED  (cause-chained)
Zod schema rejection at entry → REACT_AUTH.INVALID_OPTIONS  (thrown synchronously)
SSR / non-DOM environment     → REACT_AUTH.SSR_NO_OP        (surfaced via onError only)

Every translation preserves the original SuaveplanError via cause, so consumers can introspect error.cause?.code for the underlying WEBAUTHN.* code.

Testing approach

Real navigator.credentials.get stub at the jsdom layer — install a fake PublicKeyCredential with isConditionalMediationAvailable and a navigator.credentials.get that resolves a fixture AuthenticateResult or rejects with a chosen DOMException. Tests live in src/use-passkey-autofill/use-passkey-autofill.test.tsx using @suaveplan/testing-dom render utilities and @suaveplan/testing/runner for the runner-neutral imports (CLAUDE.md rule 11).
For environments lacking PublicKeyCredential entirely (deliberately stripped), assert REACT_AUTH.AUTOFILL_UNAVAILABLE is reported via onError and ready stays false.
Lifecycle is verified by mounting, asserting an in-flight request, unmounting, and asserting the request rejected with REACT_AUTH.ABORTED.
100% coverage per CLAUDE.md / openspec rule 7 — no carve-outs.

File layout

packages/auth/react-auth/
  README.md
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts                                          # explicit named re-exports (rule 6a)
    use-passkey-autofill/
      index.ts
      use-passkey-autofill.ts
      use-passkey-autofill.md
      use-passkey-autofill.test.tsx
      use-passkey-autofill.stories.tsx
      use-passkey-autofill.types.ts
      use-passkey-autofill.schemas.ts
    passkey-autofill-field/
      index.ts
      passkey-autofill-field.tsx
      passkey-autofill-field.md
      passkey-autofill-field.test.tsx
      passkey-autofill-field.stories.tsx
      passkey-autofill-field.types.ts
    errors/
      index.ts
      errors.ts
      errors.md
      errors.test.ts
    utils/
      compose-signals.ts
      compose-signals.md
      compose-signals.test.ts

Decisions

Hook-first, component-optional. The <PasskeyAutofillField> wrapper exists for the common case but is never a requirement; advanced consumers wire the hook to their own input.
No global state, no context provider. Multiple usePasskeyAutofill instances may coexist (e.g. a multi-tenant login page); each owns its own controller.
Errors are translated, not leaked. Consumers see REACT_AUTH.* codes. The underlying WEBAUTHN.* cause is preserved on error.cause for introspection.
onCredential is required, onError is optional. A consumer that does not pass onError accepts that errors silently no-op (with error still populated on the return value).
Stable abort reference. Returned via useCallback so consumers can put it in dependency arrays without thrashing.

7.6 KiB Raw Permalink Blame History

Design — usePasskeyAutofill (@suaveplan/react-auth)