# Capability Spec Delta: react-auth (complete-react-auth) **Package**: `@suaveplan/react-auth` **Status**: PROPOSED > Every requirement below carries a `**Verified by:**` line at authoring time naming planned test files. No exceptions. (See `openspec/AGENTS.md` §0c.) ## ADDED Requirements ### Requirement: AuthProvider establishes context, hydrates persisted session, and is SSR-safe The package SHALL export `` that accepts `AuthBackend`, optional `StorageLike`, optional `BroadcastChannel` factory, optional `IdleConfig`, optional `Clock`, optional `LoggerLike`, and optional `MessageResolver`. The provider SHALL render with a deterministic `{ status: "loading", user: null }` state on first paint (including SSR), then hydrate persisted session inside `useEffect` on the client. The provider SHALL never access `window`, `document`, `navigator`, `localStorage`, `sessionStorage`, or `BroadcastChannel` at module load or during server render. #### Scenario: server render contains zero DOM access - **WHEN** `` is rendered in a server-side environment (`typeof window === "undefined"`) - **THEN** no `window`/`document`/`navigator`/`localStorage`/`sessionStorage`/`BroadcastChannel` access occurs - **AND** the rendered children see `state.status === "loading"` #### Scenario: persisted session is loaded on client mount - **WHEN** the provider mounts on the client and the injected `StorageLike` contains a valid persisted session - **THEN** the provider hydrates `state` to `{ status: "authenticated", user, accessToken, expiresAt, refreshAt }` inside `useEffect` - **AND** consumers observe the hydrated state on the second render #### Scenario: useAuthContext throws CONTEXT_MISSING outside provider - **WHEN** `useAuthContext()` is called outside any `` - **THEN** a `SuaveplanError` with `code === "REACT_AUTH.CONTEXT_MISSING"` is thrown synchronously **Verified by:** `src/auth-provider/auth-provider.test.tsx::"renders deterministic loading state on SSR"` AND `src/auth-provider/auth-provider.test.tsx::"hydrates persisted session inside useEffect on client mount"` AND `src/auth-provider/use-auth-context.test.ts::"throws CONTEXT_MISSING when used outside provider"` --- ### Requirement: State read hooks expose context selectors The package SHALL export `useAuth`, `useUser`, `useIsAuthenticated`, and `useSession` hooks. Each SHALL read from `` context, return stable references across renders when the underlying slice is unchanged, and never trigger re-renders for unrelated state changes. #### Scenario: useUser returns null when unauthenticated - **WHEN** the provider state is `{ status: "unauthenticated" }` - **THEN** `useUser()` returns `null` - **AND** `useIsAuthenticated()` returns `false` #### Scenario: useSession returns the full state slice - **WHEN** the provider state is `{ status: "authenticated", user, accessToken, expiresAt, refreshAt }` - **THEN** `useSession()` returns the same shape - **AND** repeated calls with unchanged state return referentially-equal objects **Verified by:** `src/hooks/use-user/use-user.test.ts::"returns null when unauthenticated"` AND `src/hooks/use-is-authenticated/use-is-authenticated.test.ts::"returns false when unauthenticated"` AND `src/hooks/use-session/use-session.test.ts::"returns the full state slice with stable identity"` AND `src/hooks/use-auth/use-auth.test.ts::"exposes mutation methods"` --- ### Requirement: Sign-in / sign-up / sign-out / refresh hooks wrap the backend with typed mutation handles The package SHALL export `useSignIn`, `useSignUp`, `useSignOut`, and `useRefreshToken`. Each SHALL return a `MutationHandle` with `{ mutate, status, error, data, reset }` whose identity is stable across renders. Successful mutations SHALL update provider state and broadcast `signed-in` / `signed-out` / `session-refreshed` via the configured `BroadcastChannel`. Failures SHALL translate `AuthBackend` errors into `REACT_AUTH.SIGN_IN_FAILED` / `SIGN_UP_FAILED` / `SIGN_OUT_FAILED` / `REFRESH_FAILED` respectively, preserving the underlying error on `cause`. #### Scenario: successful sign-in updates context and broadcasts - **WHEN** `useSignIn().mutate({ email, password })` resolves - **THEN** provider state transitions to `{ status: "authenticated", user, accessToken, expiresAt, refreshAt }` - **AND** a `signed-in` envelope is posted on the broadcast channel #### Scenario: backend failure surfaces SIGN_IN_FAILED with cause preserved - **WHEN** `AuthBackend.passwordSignIn` rejects with an error - **THEN** `useSignIn().error` is a `SuaveplanError` with `code === "REACT_AUTH.SIGN_IN_FAILED"` - **AND** the original error is preserved on `error.cause` #### Scenario: sign-out broadcasts and clears storage - **WHEN** `useSignOut().mutate()` resolves - **THEN** provider state transitions to `{ status: "unauthenticated", user: null }` - **AND** the injected `StorageLike` no longer contains the persisted session - **AND** a `signed-out` envelope is posted on the broadcast channel #### Scenario: refresh failure transitions to unauthenticated - **WHEN** `useRefreshToken().mutate()` rejects - **THEN** the provider state transitions to `{ status: "unauthenticated", error: REACT_AUTH.REFRESH_FAILED }` **Verified by:** `src/hooks/use-sign-in/use-sign-in.test.ts::"updates context and broadcasts on success"` AND `src/hooks/use-sign-in/use-sign-in.test.ts::"translates backend failure to SIGN_IN_FAILED with cause"` AND `src/hooks/use-sign-up/use-sign-up.test.ts::"signs the user in on success"` AND `src/hooks/use-sign-out/use-sign-out.test.ts::"clears storage and broadcasts signed-out"` AND `src/hooks/use-refresh-token/use-refresh-token.test.ts::"transitions to unauthenticated on refresh failure"` --- ### Requirement: Password hooks cover change, request-reset, and confirm-reset flows The package SHALL export `useChangePassword` and `usePasswordReset`. `useChangePassword` SHALL return a `MutationHandle<{ currentPassword: string; newPassword: string }, void>`. `usePasswordReset` SHALL return `{ request, confirm }`, each a `MutationHandle`. New-password values SHALL be rejected synchronously with `REACT_AUTH.PASSWORD_TOO_WEAK` if `password-strength.estimate(...).score < minBits` (where `minBits` defaults to 50 bits-equivalent) and SHALL be rejected with `REACT_AUTH.PASSWORD_PWNED` if an injected `HibpClient` is supplied and the password appears in HIBP. #### Scenario: weak password is rejected before backend call - **WHEN** `useChangePassword().mutate({ currentPassword, newPassword: "abc" })` is invoked - **THEN** the mutation rejects with `REACT_AUTH.PASSWORD_TOO_WEAK` - **AND** `AuthBackend.changePassword` is not called #### Scenario: pwned password is rejected before backend call - **WHEN** `useChangePassword({ hibpClient }).mutate({ currentPassword, newPassword })` is invoked AND HIBP reports the password as pwned - **THEN** the mutation rejects with `REACT_AUTH.PASSWORD_PWNED` #### Scenario: request-reset and confirm-reset round-trip - **WHEN** `usePasswordReset().request.mutate({ email })` resolves and the user later calls `confirm.mutate({ token, newPassword })` - **THEN** the backend is called with the supplied token and a strength-validated password - **AND** provider state remains unchanged (reset flow does not authenticate) **Verified by:** `src/hooks/use-change-password/use-change-password.test.ts::"rejects weak passwords before calling backend"` AND `src/hooks/use-change-password/use-change-password.test.ts::"rejects HIBP-pwned passwords when hibpClient is supplied"` AND `src/hooks/use-password-reset/use-password-reset.test.ts::"request and confirm hit the backend in sequence"` --- ### Requirement: PasswordInput composes strength + HIBP slots with accessible markup The package SHALL export `` rendering an `` with optional show/hide toggle, optional `` slot, and optional `` slot. The component SHALL associate the input with its label via `htmlFor` / `id`, link help/error text via `aria-describedby`, set `aria-invalid` on error, and meet WCAG 2.1 AA contrast ratios in the bundled stories. #### Scenario: input is associated with label and described-by id - **WHEN** `` is rendered - **THEN** the rendered `` carries `for="pwd"` - **AND** the rendered `` carries `aria-describedby="pwd-help"` #### Scenario: show/hide toggle flips input type and announces state - **WHEN** the user clicks the show/hide toggle - **THEN** `` flips between `"password"` and `"text"` - **AND** the toggle button's `aria-pressed` state reflects the visibility #### Scenario: axe-core finds zero serious violations - **WHEN** `` is rendered in the canonical story - **THEN** `axe.run` reports zero `serious` or `critical` violations **Verified by:** `src/components/password-input/password-input.test.tsx::"associates label with input via htmlFor"` AND `src/components/password-input/password-input.test.tsx::"toggle flips type and aria-pressed"` AND `e2e/accessibility.spec.ts::"PasswordInput passes axe with zero serious violations"` --- ### Requirement: PasswordStrengthMeter wraps password-strength.assessReactive with cancellation The package SHALL export `` that wraps `@suaveplan/password-strength.assessReactive`. On every `password` prop change the component SHALL cancel any in-flight assessment via `AbortController`. On unmount the component SHALL abort the current assessment. #### Scenario: rapid prop changes do not leak assessments - **WHEN** the `password` prop changes 100 times within a single tick - **THEN** at most one `assessReactive` Promise is still pending after settle - **AND** no `unhandled rejection` is logged #### Scenario: unmount cancels the in-flight assessment - **WHEN** the component unmounts while an `assessReactive` Promise is pending - **THEN** the underlying `AbortController` aborts - **AND** the Promise rejects with `AbortError` (not surfaced to the consumer) **Verified by:** `src/components/password-strength-meter/password-strength-meter.test.tsx::"cancels stale assessments when password changes"` AND `src/components/password-strength-meter/password-strength-meter.test.tsx::"aborts on unmount"` --- ### Requirement: HibpPwnedIndicator debounces, SSR-no-ops, and surfaces pwned state The package SHALL export `` that wraps an injected `HibpClient` (per `@suaveplan/hibp`), debounces input changes by at least 500 ms, never performs a network request during SSR or when `password` is empty, and surfaces the pwned/clean result via accessible status text in an `aria-live="polite"` region. #### Scenario: SSR render performs no network access - **WHEN** the component is rendered server-side - **THEN** no method on the injected `HibpClient` is called #### Scenario: rapid keystrokes coalesce to a single request - **WHEN** the `password` prop changes 10 times in under 500 ms - **THEN** the `HibpClient.checkPassword` method is called at most once after debounce #### Scenario: pwned result is announced via aria-live region - **WHEN** the client reports the password as pwned - **THEN** an element with `aria-live="polite"` contains the localised pwned message **Verified by:** `src/components/hibp-pwned-indicator/hibp-pwned-indicator.test.tsx::"performs no HIBP call during SSR render"` AND `src/components/hibp-pwned-indicator/hibp-pwned-indicator.test.tsx::"debounces rapid keystrokes to a single request"` AND `src/components/hibp-pwned-indicator/hibp-pwned-indicator.test.tsx::"announces pwned result via aria-live region"` --- ### Requirement: PasswordGeneratorButton emits passphrase / chars / pin per `@suaveplan/password-generator` The package SHALL export `` that, on activation, opens a popover with a generated password from `@suaveplan/password-generator`. The mode SHALL be `"passphrase"` (default), `"chars"`, or `"pin"`. On accept the component SHALL invoke the consumer's `onPick(password)` callback. The popover SHALL be keyboard-accessible (Escape closes, focus traps inside). #### Scenario: default mode generates a passphrase - **WHEN** `` is opened and the user accepts the suggestion - **THEN** `onPick` is invoked once with a passphrase generated via `@suaveplan/password-generator` #### Scenario: Escape closes and returns focus to trigger - **WHEN** the popover is open and the user presses Escape - **THEN** the popover closes - **AND** focus returns to the trigger button **Verified by:** `src/components/password-generator-button/password-generator-button.test.tsx::"emits a passphrase on accept"` AND `src/components/password-generator-button/password-generator-button.test.tsx::"escape closes popover and restores focus"` --- ### Requirement: useRegisterPasskey wraps webauthn.register and persists the result The package SHALL export `useRegisterPasskey` returning a `MutationHandle<{ userId: string; friendlyName?: string }, RegisteredPasskey>`. The mutation SHALL call `AuthBackend.passkeyRegisterOptions`, invoke `webauthn.register` from `@suaveplan/webauthn`, then call `AuthBackend.passkeyRegisterFinish`. Failures SHALL be translated to `REACT_AUTH.PASSKEY_REGISTER_FAILED` with the underlying `WEBAUTHN.*` cause preserved. #### Scenario: full register handshake completes successfully - **WHEN** the mutation runs end-to-end - **THEN** `passkeyRegisterOptions`, `webauthn.register`, and `passkeyRegisterFinish` are called in order - **AND** the resolved value is the `RegisteredPasskey` from the backend #### Scenario: webauthn cancellation surfaces PASSKEY_REGISTER_FAILED - **WHEN** the user cancels the platform passkey UI (yielding `WEBAUTHN.ABORTED`) - **THEN** the mutation rejects with `REACT_AUTH.PASSKEY_REGISTER_FAILED` - **AND** `error.cause.code === "WEBAUTHN.ABORTED"` **Verified by:** `src/hooks/use-register-passkey/use-register-passkey.test.ts::"runs options → register → finish in order"` AND `src/hooks/use-register-passkey/use-register-passkey.test.ts::"translates WEBAUTHN.ABORTED to PASSKEY_REGISTER_FAILED with cause"` --- ### Requirement: useAuthenticateWithPasskey runs modal mediation and updates context The package SHALL export `useAuthenticateWithPasskey` returning a `MutationHandle<{ userHint?: string }, void>` that calls `AuthBackend.passkeyAuthenticateOptions({ mediation: "required" })`, invokes `webauthn.authenticate`, then `AuthBackend.passkeyAuthenticateFinish`. On success the provider state SHALL transition to `authenticated`. #### Scenario: successful modal passkey sign-in updates state - **WHEN** the mutation resolves - **THEN** provider state transitions to `{ status: "authenticated", user, accessToken, … }` #### Scenario: backend failure surfaces PASSKEY_AUTHENTICATE_FAILED - **WHEN** `passkeyAuthenticateFinish` rejects - **THEN** the mutation rejects with `REACT_AUTH.PASSKEY_AUTHENTICATE_FAILED` with cause preserved **Verified by:** `src/hooks/use-authenticate-with-passkey/use-authenticate-with-passkey.test.ts::"transitions to authenticated on success"` AND `src/hooks/use-authenticate-with-passkey/use-authenticate-with-passkey.test.ts::"translates backend failure to PASSKEY_AUTHENTICATE_FAILED"` --- ### Requirement: usePasskeyAutofill dispatches conditional WebAuthn with SSR-safe lifecycle The package SHALL export `usePasskeyAutofill(options)` that, on the first client mount, feature-detects `PublicKeyCredential.isConditionalMediationAvailable()` via `@suaveplan/webauthn` and dispatches `authenticate({ mediation: "conditional" })` with the caller-supplied `rpId`, `challenge`, `allowCredentials`, `userVerification`, `timeout`, `expectedOrigin`, and `expectedRpIdHash`. The hook SHALL own one `AbortController` per effect run composed with `options.signal`, abort on unmount / `options.signal` / returned `abort()`, perform zero work during SSR, return `{ ready: false, error: null, abort }` on the server, and validate options via Zod, throwing `REACT_AUTH.INVALID_OPTIONS` synchronously on mismatch. The returned `abort` reference SHALL be stable across re-renders. #### Scenario: conditional authenticate is invoked when supported - **WHEN** the hook mounts in a browser whose `isConditionalMediationAvailable()` resolves `true` - **THEN** `webauthn.authenticate` is called with `mediation: "conditional"` and the forwarded option fields - **AND** `ready` flips to `true` once the request is in-flight #### Scenario: SSR render performs no DOM access - **WHEN** the hook is rendered with `typeof window === "undefined"` - **THEN** no `navigator`/`document`/`PublicKeyCredential` access occurs - **AND** the return is `{ ready: false, error: null, abort }` #### Scenario: missing Conditional UI surfaces PASSKEY_AUTOFILL_UNAVAILABLE - **WHEN** `isConditionalMediationAvailable` is missing or resolves `false` - **THEN** `authenticate` is never called and `onError` (if supplied) receives `REACT_AUTH.PASSKEY_AUTOFILL_UNAVAILABLE` #### Scenario: unmount aborts the in-flight request - **WHEN** the component unmounts while the request is in-flight - **THEN** the request rejects with `AbortError` translated to `REACT_AUTH.PASSKEY_AUTOFILL_ABORTED` (cause preserved) #### Scenario: returned abort reference is stable across re-renders - **WHEN** the parent re-renders with unchanged options - **THEN** `Object.is(prevReturn.abort, nextReturn.abort) === true` #### Scenario: invalid options throw INVALID_OPTIONS synchronously - **WHEN** the caller passes `rpId: ""` or a non-`Uint8Array` challenge - **THEN** the hook throws `REACT_AUTH.INVALID_OPTIONS` during render - **AND** no `authenticate` call is dispatched **Verified by:** `src/hooks/use-passkey-autofill/use-passkey-autofill.test.tsx::"dispatches authenticate with mediation conditional when available"` AND `src/hooks/use-passkey-autofill/use-passkey-autofill.test.tsx::"performs no work during SSR render"` AND `src/hooks/use-passkey-autofill/use-passkey-autofill.test.tsx::"reports PASSKEY_AUTOFILL_UNAVAILABLE when conditional UI missing"` AND `src/hooks/use-passkey-autofill/use-passkey-autofill.test.tsx::"aborts the in-flight request on unmount"` AND `src/hooks/use-passkey-autofill/use-passkey-autofill.test.tsx::"returned abort reference is stable across re-renders"` AND `src/hooks/use-passkey-autofill/use-passkey-autofill.test.tsx::"throws INVALID_OPTIONS for empty rpId"` --- ### Requirement: PasskeyAutofillField renders the autocomplete input and blur-cancels The package SHALL export `` rendering an `` wired to `usePasskeyAutofill`. The component SHALL call the hook's `abort()` on the input's `blur` event when no credential has yet been delivered. After `onCredential` has fired, subsequent blur events SHALL NOT trigger `abort()`. Consumer-supplied `inputProps` SHALL be forwarded to the underlying `` (except `autocomplete`, which is fixed). #### Scenario: input has autocomplete="username webauthn" - **WHEN** `` is rendered - **THEN** the rendered `` has `autocomplete="username webauthn"` #### Scenario: blur cancels the in-flight request - **WHEN** the user blurs the input before any credential is delivered - **THEN** `abort()` is invoked and the in-flight request rejects with `REACT_AUTH.PASSKEY_AUTOFILL_ABORTED` #### Scenario: blur after credential delivery is a no-op - **WHEN** `onCredential` has already fired - **THEN** a subsequent blur does NOT invoke `abort()` **Verified by:** `src/components/passkey-autofill-field/passkey-autofill-field.test.tsx::"renders input with autocomplete username webauthn"` AND `src/components/passkey-autofill-field/passkey-autofill-field.test.tsx::"blur cancels in-flight request"` AND `src/components/passkey-autofill-field/passkey-autofill-field.test.tsx::"blur after credential delivery is a no-op"` --- ### Requirement: PasskeyList lists registered authenticators and revokes per row The package SHALL export `` that reads from `AuthBackend.listPasskeys()`, renders one row per credential with friendly name + last-used timestamp + revoke button, and on revoke confirmation calls `AuthBackend.revokePasskey({ credentialId })`. The revoke confirmation dialog SHALL trap focus and restore focus on close. #### Scenario: list renders one row per registered passkey - **WHEN** the backend returns three registered passkeys - **THEN** the component renders exactly three rows, each carrying the friendly name and a revoke button #### Scenario: revoke flow calls backend after confirmation - **WHEN** the user clicks revoke and confirms - **THEN** `AuthBackend.revokePasskey` is called with the row's `credentialId` - **AND** the row is removed from the list after success **Verified by:** `src/components/passkey-list/passkey-list.test.tsx::"renders one row per registered passkey"` AND `src/components/passkey-list/passkey-list.test.tsx::"revokes the credential after confirmation"` --- ### Requirement: useOAuthSignIn runs popup and redirect modes with PKCE The package SHALL export `useOAuthSignIn` returning a `MutationHandle<{ provider: string; mode: "popup" | "redirect"; scopes?: string[] }, void>`. The hook SHALL generate `state` and a PKCE pair via `@suaveplan/oauth-client.generatePkcePair`, persist `{ state, codeVerifier, provider }` to a return-state store (sessionStorage by default), and either open a centred popup (popup mode) or call `window.location.assign(authorizationUrl)` (redirect mode). On popup-mode receipt of `postMessage` from a same-origin source, the hook SHALL call `AuthBackend.oauthExchange`, persist the resulting session, broadcast `signed-in`, and close the popup. #### Scenario: popup-blocked surfaces OAUTH_POPUP_BLOCKED - **WHEN** `window.open` returns `null` - **THEN** the mutation rejects with `REACT_AUTH.OAUTH_POPUP_BLOCKED` #### Scenario: state mismatch surfaces OAUTH_STATE_MISMATCH - **WHEN** the callback `postMessage` carries a `state` that does not match the persisted PKCE state - **THEN** the mutation rejects with `REACT_AUTH.OAUTH_STATE_MISMATCH` - **AND** no `oauthExchange` call is made #### Scenario: cross-origin postMessage is ignored - **WHEN** the popup receives a `postMessage` from a different origin than the parent - **THEN** the message is ignored and the mutation remains pending #### Scenario: redirect mode persists return-state and navigates - **WHEN** `mutate({ provider, mode: "redirect" })` is called - **THEN** the PKCE state is persisted to the return-state store - **AND** `window.location.assign` is called with the authorization URL **Verified by:** `src/hooks/use-oauth-sign-in/use-oauth-sign-in.test.ts::"surfaces OAUTH_POPUP_BLOCKED when window.open returns null"` AND `src/hooks/use-oauth-sign-in/use-oauth-sign-in.test.ts::"surfaces OAUTH_STATE_MISMATCH on state mismatch"` AND `src/hooks/use-oauth-sign-in/use-oauth-sign-in.test.ts::"ignores cross-origin postMessage"` AND `src/hooks/use-oauth-sign-in/use-oauth-sign-in.test.ts::"redirect mode persists state and navigates"` --- ### Requirement: handleOAuthCallback parses, validates, exchanges, and is idempotent The package SHALL export `handleOAuthCallback()` that reads `code` and `state` from `window.location.search`, validates `state` against the persisted PKCE entry, calls `AuthBackend.oauthExchange`, and either `postMessage`s the result back to `window.opener` (popup mode) or persists the session + navigates to the originally-requested URL (redirect mode). The function SHALL be idempotent across remounts via a one-shot guard keyed by `state`. #### Scenario: missing PKCE state surfaces OAUTH_STATE_MISMATCH - **WHEN** the persisted return-state store has no entry for the URL `state` parameter - **THEN** the function rejects with `REACT_AUTH.OAUTH_STATE_MISMATCH` #### Scenario: idempotent across remounts - **WHEN** `handleOAuthCallback()` is called twice with the same `state` - **THEN** `AuthBackend.oauthExchange` is called at most once **Verified by:** `src/oauth/handle-callback.test.ts::"rejects with OAUTH_STATE_MISMATCH when state is unknown"` AND `src/oauth/handle-callback.test.ts::"is idempotent across remounts"` --- ### Requirement: OAuthProviderButton + OAuthProviderRegistry expose registered providers accessibly The package SHALL export `OAuthProviderRegistry` with `register`, `get`, `has`, `list`, and `unregister`. The package SHALL export `` that renders a button labelled via `react-auth.oauth..label` i18n key, with an icon slot, and on click invokes `useOAuthSignIn`. #### Scenario: button is keyboard-activatable - **WHEN** the button receives focus and the user presses Enter - **THEN** `useOAuthSignIn().mutate` is invoked #### Scenario: registry rejects duplicate registrations - **WHEN** `register` is called twice with the same provider name - **THEN** the second call throws a registry-error code defined in the registry module **Verified by:** `src/components/oauth-provider-button/oauth-provider-button.test.tsx::"invokes sign-in on Enter"` AND `src/oauth/provider-registry.test.ts::"rejects duplicate registrations"` --- ### Requirement: TOTP and recovery-code hooks cover full MFA lifecycle The package SHALL export `useEnrollTotp`, `useVerifyTotp`, `useEnrollWebauthnSecondFactor`, and `useRecoveryCodes`. `useEnrollTotp` SHALL provide `{ begin, finish }` mutation handles. `useRecoveryCodes` SHALL provide `{ generate, verify }` mutation handles. `useVerifyTotp` SHALL transition provider state from `mfa-required` to `authenticated` on success. Failures SHALL be translated to `TOTP_ENROLL_FAILED`, `MFA_VERIFY_FAILED`, or `RECOVERY_CODE_INVALID`. #### Scenario: TOTP enrollment returns secret + provisioning URI then recovery codes - **WHEN** `useEnrollTotp().begin.mutate()` resolves then `finish.mutate({ code })` resolves - **THEN** the consumer receives `{ secret, provisioningUri }` from `begin` and `{ recoveryCodes }` from `finish` #### Scenario: TOTP verification transitions out of mfa-required - **WHEN** provider state is `mfa-required` and `useVerifyTotp().mutate({ code })` resolves - **THEN** provider state transitions to `authenticated` #### Scenario: invalid recovery code rejects with RECOVERY_CODE_INVALID - **WHEN** `useRecoveryCodes().verify.mutate({ code: "bad" })` rejects from the backend - **THEN** the surfaced error is `REACT_AUTH.RECOVERY_CODE_INVALID` **Verified by:** `src/hooks/use-enroll-totp/use-enroll-totp.test.ts::"begin returns secret and uri, finish returns recovery codes"` AND `src/hooks/use-verify-totp/use-verify-totp.test.ts::"transitions out of mfa-required on success"` AND `src/hooks/use-recovery-codes/use-recovery-codes.test.ts::"rejects invalid recovery codes with RECOVERY_CODE_INVALID"` AND `src/hooks/use-enroll-webauthn-second-factor/use-enroll-webauthn-second-factor.test.ts::"forwards authenticatorSelection to webauthn.register"` --- ### Requirement: TotpEnrollmentPanel + RecoveryCodesPanel orchestrate accessible MFA UX The package SHALL export `` that wires `useEnrollTotp` end-to-end and renders a consumer-supplied QR slot. The component SHALL not display recovery codes until enrollment finalises. The package SHALL export `` that lists generated codes with copy-to-clipboard, download-as-text, and an "I have saved these" acknowledgement checkbox that must be checked before dismissal. #### Scenario: recovery codes are hidden until finalised - **WHEN** `` is in the `begin` state - **THEN** no recovery code is rendered in the DOM #### Scenario: dismiss requires acknowledgement - **WHEN** the user attempts to dismiss `` without checking the acknowledgement - **THEN** the dismiss is prevented and a `react-auth.recovery.must-acknowledge` warning is announced via `aria-live` #### Scenario: copy and download produce the same payload - **WHEN** the user clicks copy and then download - **THEN** the clipboard contents and the downloaded text match exactly **Verified by:** `src/components/totp-enrollment-panel/totp-enrollment-panel.test.tsx::"hides recovery codes until finalised"` AND `src/components/recovery-codes-panel/recovery-codes-panel.test.tsx::"prevents dismiss without acknowledgement"` AND `src/components/recovery-codes-panel/recovery-codes-panel.test.tsx::"copy and download contents match"` --- ### Requirement: Email and phone verification hooks + views The package SHALL export `useEmailVerification` and `usePhoneVerification`, each returning `{ request, confirm }` mutation handles wired to the corresponding `AuthBackend` methods. The package SHALL export `` with a resend cooldown timer and `` whose code input carries `inputMode="numeric"` and `autoComplete="one-time-code"`. #### Scenario: resend cooldown disables the button - **WHEN** the user clicks "resend" inside `` - **THEN** the resend button is disabled for at least `cooldownMs` (default 30000) - **AND** an `aria-live` region announces the remaining time #### Scenario: phone code input is optimised for mobile autofill - **WHEN** `` is rendered - **THEN** the code `` carries `inputMode="numeric"` and `autoComplete="one-time-code"` **Verified by:** `src/components/email-verification-view/email-verification-view.test.tsx::"resend is disabled during cooldown"` AND `src/components/phone-verification-view/phone-verification-view.test.tsx::"code input carries one-time-code autocomplete"` AND `src/hooks/use-email-verification/use-email-verification.test.ts::"request and confirm hit the backend"` AND `src/hooks/use-phone-verification/use-phone-verification.test.ts::"request and confirm hit the backend"` --- ### Requirement: Guards — AuthGuard, PermissionGate, useAuthGuard, usePermission, withAuth The package SHALL export ``, ``, `useAuthGuard`, `usePermission`, and `withAuth(Component)`. `` SHALL render `children` when authenticated and otherwise render the `fallback` prop; when no `fallback` is supplied the guard SHALL throw `REACT_AUTH.UNAUTHENTICATED` for the nearest error boundary. `` SHALL consult the injected `PermissionResolver`; absent permission SHALL render `fallback` or `null`. #### Scenario: AuthGuard renders fallback when unauthenticated - **WHEN** `}>` is mounted with provider state `unauthenticated` - **THEN** the `data-testid="x"` element renders and children do not #### Scenario: AuthGuard throws UNAUTHENTICATED when no fallback - **WHEN** `` is mounted with no `fallback` and provider state `unauthenticated` - **THEN** a `SuaveplanError` with `code === "REACT_AUTH.UNAUTHENTICATED"` is thrown during render #### Scenario: PermissionGate consults injected resolver - **WHEN** `` is mounted and `permissions.has("admin")` returns `false` - **THEN** children are not rendered **Verified by:** `src/components/auth-guard/auth-guard.test.tsx::"renders fallback when unauthenticated"` AND `src/components/auth-guard/auth-guard.test.tsx::"throws UNAUTHENTICATED when no fallback supplied"` AND `src/components/permission-gate/permission-gate.test.tsx::"hides children when permission is absent"` AND `src/hooks/use-auth-guard/use-auth-guard.test.ts::"exposes status and redirectTo"` AND `src/hooks/use-permission/use-permission.test.ts::"returns boolean from resolver"` --- ### Requirement: AuthErrorBoundary catches REACT_AUTH errors and renders i18n-keyed fallback The package SHALL export `` that catches any thrown `SuaveplanError` whose `code` starts with `"REACT_AUTH."` and renders a `fallback(error)` slot (default: an accessible alert resolving `react-auth.errors.` via the injected `MessageResolver`). Non-`REACT_AUTH` errors SHALL be re-thrown so other boundaries handle them. #### Scenario: REACT_AUTH error is caught and rendered - **WHEN** a child throws `REACT_AUTH.UNAUTHENTICATED` - **THEN** the boundary renders the resolved fallback message - **AND** the alert element carries `role="alert"` #### Scenario: non-REACT_AUTH error is re-thrown - **WHEN** a child throws an unrelated `Error` - **THEN** the boundary re-throws so a parent boundary can handle it **Verified by:** `src/components/auth-error-boundary/auth-error-boundary.test.tsx::"renders i18n fallback for REACT_AUTH errors"` AND `src/components/auth-error-boundary/auth-error-boundary.test.tsx::"re-throws non-REACT_AUTH errors"` --- ### Requirement: Multi-tab session sync via BroadcastChannel The provider SHALL open a `BroadcastChannel("@suaveplan/react-auth")` (via injected factory) on mount and SHALL post typed envelopes on every sign-in, sign-out, refresh, and forced-logout. Receivers SHALL hydrate state from `StorageLike` on `signed-in` / `session-refreshed` and SHALL clear state synchronously on `signed-out` / `forced-logout` without re-calling the backend. #### Scenario: sign-out in tab A clears state in tab B - **WHEN** tab A signs out and emits the `signed-out` envelope - **THEN** tab B's provider state transitions to `unauthenticated` - **AND** no `AuthBackend.sessionRevoke` call is made in tab B #### Scenario: forced-logout broadcasts to every tab - **WHEN** `forceLogout("policy-violation")` is invoked - **THEN** every subscribed tab transitions to `unauthenticated` - **AND** the reason is observable via the `forced-logout` envelope payload **Verified by:** `src/session/broadcast-channel.test.ts::"emits typed envelopes for lifecycle events"` AND `src/auth-provider/auth-provider.test.tsx::"receives signed-out from another tab and clears state without backend call"` AND `e2e/multi-tab-sync.spec.ts::"sign-out in one tab propagates to another"` --- ### Requirement: Auto-refresh fires before expiry via injected Clock The provider SHALL schedule a refresh at `expiresAt - refreshSkewMs` (default `60000`) using the injected `Clock`. The schedule SHALL be cancelled on every state update, every sign-out, and on unmount. On refresh success the provider SHALL broadcast `session-refreshed`. On refresh failure the provider SHALL transition to `unauthenticated` with `REACT_AUTH.REFRESH_FAILED`. #### Scenario: refresh fires at refreshAt - skew - **WHEN** the clock advances past `refreshAt` - **THEN** `AuthBackend.sessionRefresh` is called exactly once #### Scenario: refresh failure clears state - **WHEN** the scheduled `sessionRefresh` rejects - **THEN** provider state transitions to `unauthenticated` with `REACT_AUTH.REFRESH_FAILED` **Verified by:** `src/session/auto-refresh.test.ts::"fires sessionRefresh at refreshAt minus skew"` AND `src/session/auto-refresh.test.ts::"transitions to unauthenticated on refresh failure"` --- ### Requirement: Idle timeout triggers warning then forced sign-out When `IdleConfig` is supplied, the provider SHALL listen for `pointerdown`, `keydown`, and `visibilitychange` events on `document`, debounce to ≤ 1 reset / 250 ms, fire `onWarn` at `ttlMs - warnBeforeMs`, and fire `onTimeout` (default: `forceLogout("idle")`) at `ttlMs`. Listeners SHALL be removed on unmount. #### Scenario: pointer activity resets the idle counter - **WHEN** a `pointerdown` fires before the warning threshold - **THEN** the warning + timeout timers are reset #### Scenario: warning then timeout fire in order - **WHEN** the clock advances past `ttlMs - warnBeforeMs` then past `ttlMs` - **THEN** `onWarn` fires first, then `onTimeout` - **AND** provider state transitions to `unauthenticated` with `REACT_AUTH.IDLE_TIMEOUT` **Verified by:** `src/session/idle-timer.test.ts::"resets timers on pointerdown"` AND `src/session/idle-timer.test.ts::"fires onWarn then onTimeout and transitions to unauthenticated"` AND `e2e/idle-timeout.spec.ts::"forces sign-out after idle ttl"` --- ### Requirement: REACT_AUTH error registry is complete and every code reachable The package SHALL export a `defineCodes("REACT_AUTH", [...])` registry whose set equals exactly: `CONTEXT_MISSING`, `UNAUTHENTICATED`, `BACKEND_ERROR`, `SIGN_IN_FAILED`, `SIGN_UP_FAILED`, `SIGN_OUT_FAILED`, `REFRESH_FAILED`, `PASSWORD_TOO_WEAK`, `PASSWORD_PWNED`, `PASSWORD_RESET_FAILED`, `CHANGE_PASSWORD_FAILED`, `PASSKEY_REGISTER_FAILED`, `PASSKEY_AUTHENTICATE_FAILED`, `PASSKEY_AUTOFILL_UNAVAILABLE`, `PASSKEY_AUTOFILL_FAILED`, `PASSKEY_AUTOFILL_ABORTED`, `OAUTH_POPUP_BLOCKED`, `OAUTH_STATE_MISMATCH`, `OAUTH_CALLBACK_FAILED`, `MFA_REQUIRED`, `MFA_VERIFY_FAILED`, `TOTP_ENROLL_FAILED`, `RECOVERY_CODE_INVALID`, `EMAIL_VERIFY_FAILED`, `PHONE_VERIFY_FAILED`, `INVALID_OPTIONS`, `SSR_NO_OP`, `IDLE_TIMEOUT`, `FORCED_LOGOUT`. Every code SHALL be raised by at least one production path; every translation SHALL preserve the underlying cause. #### Scenario: every declared code is reachable - **WHEN** the test suite enumerates the registry - **THEN** for each code there exists a production code path that raises it (verified by call-graph or fixture) **Verified by:** `src/errors/errors.test.ts::"every REACT_AUTH code is reachable from a production path"` AND `src/errors/errors.test.ts::"every translation preserves cause"` --- ### Requirement: Zod schemas validate every hook option bag at boundary The package SHALL validate every public hook's option bag through a Zod schema exported from `src/schemas/schemas.ts`. Boundary mismatches SHALL throw `REACT_AUTH.INVALID_OPTIONS` synchronously so React's nearest error boundary catches the failure at mount time. #### Scenario: invalid sign-in option throws INVALID_OPTIONS - **WHEN** `useSignIn().mutate({ email: "", password: "" })` is called - **THEN** the mutation rejects with `REACT_AUTH.INVALID_OPTIONS` #### Scenario: invalid useOAuthSignIn provider throws INVALID_OPTIONS - **WHEN** `useOAuthSignIn().mutate({ provider: "", mode: "popup" })` is called - **THEN** the mutation rejects with `REACT_AUTH.INVALID_OPTIONS` **Verified by:** `src/schemas/schemas.test.ts::"rejects empty sign-in fields"` AND `src/schemas/schemas.test.ts::"rejects empty oauth provider"` --- ### Requirement: i18n catalogues for en-GB, cy-GB, zh-CN are parity-checked The package SHALL ship `react-auth.*` message catalogues at `src/i18n/{en-gb,cy-gb,zh-cn}/index.ts`. The catalogue key set SHALL be identical across the three locales. A parity test SHALL fail CI when any locale's key set differs from `en-GB`. #### Scenario: parity test fails on missing key - **WHEN** `cy-GB` omits a key that exists in `en-GB` - **THEN** the parity test fails with the missing key listed #### Scenario: parity test fails on extra key - **WHEN** `zh-CN` declares a key not present in `en-GB` - **THEN** the parity test fails with the orphan key listed **Verified by:** `src/i18n/parity.test.ts::"every locale has the same keys as en-GB"` AND `src/i18n/parity.test.ts::"no locale declares keys absent from en-GB"` --- ### Requirement: No hardcoded user-visible strings in components Every user-visible string in any `src/components/**/*.tsx` SHALL resolve via the `react-auth.*` i18n catalogue. A guard test SHALL scan component source for hardcoded English strings and fail on any match outside an allowlist of fixture/identifier strings. #### Scenario: a hardcoded button label is rejected - **WHEN** a component literal contains `>` `Sign in` `<` (or equivalent visible English text) in JSX - **THEN** the guard test fails citing the file and line **Verified by:** `src/i18n/no-hardcoded-strings.test.ts::"every component string resolves via i18n"` --- ### Requirement: Subpath exports cover every hook, component, oauth helper, session module, errors, and i18n locale The `package.json` `exports` map SHALL declare one tree-shakeable entry per feature module. At minimum the map SHALL include: `.`, `./auth-provider`, `./hooks/use-auth`, `./hooks/use-user`, `./hooks/use-is-authenticated`, `./hooks/use-session`, `./hooks/use-sign-in`, `./hooks/use-sign-up`, `./hooks/use-sign-out`, `./hooks/use-refresh-token`, `./hooks/use-change-password`, `./hooks/use-password-reset`, `./hooks/use-register-passkey`, `./hooks/use-authenticate-with-passkey`, `./hooks/use-passkey-autofill`, `./hooks/use-oauth-sign-in`, `./hooks/use-enroll-totp`, `./hooks/use-verify-totp`, `./hooks/use-enroll-webauthn-second-factor`, `./hooks/use-recovery-codes`, `./hooks/use-email-verification`, `./hooks/use-phone-verification`, `./hooks/use-permission`, `./hooks/use-auth-guard`, `./components/auth-guard`, `./components/permission-gate`, `./components/password-input`, `./components/password-strength-meter`, `./components/hibp-pwned-indicator`, `./components/password-generator-button`, `./components/passkey-autofill-field`, `./components/passkey-list`, `./components/oauth-provider-button`, `./components/totp-enrollment-panel`, `./components/recovery-codes-panel`, `./components/email-verification-view`, `./components/phone-verification-view`, `./components/auth-error-boundary`, `./oauth/handle-callback`, `./oauth/provider-registry`, `./session/storage`, `./session/broadcast-channel`, `./session/idle-timer`, `./errors`, `./i18n/en-gb`, `./i18n/cy-gb`, `./i18n/zh-cn`. #### Scenario: every documented subpath resolves to declared symbols - **WHEN** a consumer imports each documented subpath - **THEN** every import resolves to the symbols listed in `proposal.md`'s public API **Verified by:** `src/index.test.ts::"every documented subpath resolves"` --- ### Requirement: 100% Istanbul coverage with no carve-outs The package SHALL meet 100% statement, 100% branch, 100% function, and 100% line coverage under `@vitest/coverage-istanbul` for `src/`. The pre-publish gate (`bunx turbo test:coverage --filter=@suaveplan/react-auth`) SHALL hard-fail below 100%. #### Scenario: coverage gate hard-fails below 100% - **WHEN** `bunx turbo test:coverage --filter=@suaveplan/react-auth` reports any metric < 100% - **THEN** the command exits non-zero **Verified by:** `vitest.config.ts::"thresholds set to 100/100/100/100"` AND `package.json::"test:coverage script wired"` --- ### Requirement: Playwright E2E covers password, passkey, OAuth, MFA, verification, multi-tab, idle, error-boundary, RTL, and accessibility The package SHALL ship a Playwright E2E suite under `e2e/` containing at minimum: `password-sign-in.spec.ts`, `sign-up.spec.ts`, `password-reset.spec.ts`, `change-password.spec.ts`, `passkey-register.spec.ts`, `passkey-autofill.spec.ts`, `passkey-modal-authenticate.spec.ts`, `oauth-popup.spec.ts`, `oauth-redirect.spec.ts`, `totp-enroll-verify.spec.ts`, `recovery-codes.spec.ts`, `email-verification.spec.ts`, `phone-verification.spec.ts`, `multi-tab-sync.spec.ts`, `idle-timeout.spec.ts`, `error-boundary.spec.ts`, `rtl-locale.spec.ts`, `accessibility.spec.ts`. The accessibility spec SHALL fail on any `serious` or `critical` axe violation. #### Scenario: accessibility sweep finds zero serious or critical violations - **WHEN** `e2e/accessibility.spec.ts` runs against the canonical app - **THEN** `@axe-core/playwright` reports zero `serious` and zero `critical` violations #### Scenario: multi-tab sync propagates sign-out - **WHEN** tab A signs out - **THEN** within 2 s tab B's UI reflects the unauthenticated state **Verified by:** `e2e/accessibility.spec.ts::"every canonical page passes axe with zero serious or critical violations"` AND `e2e/multi-tab-sync.spec.ts::"sign-out in one tab propagates within 2 seconds"` AND `e2e/passkey-autofill.spec.ts::"conditional UI delivers credential through browser autofill"`