@dloizides/auth-web 1.2.2 → 1.4.0

package/dist/index.d.mts

@@ -52,6 +52,17 @@ interface ForgotPasswordFormLabels {
     /** Shown when the entered value is not a valid email. */
     invalidEmail: string;
 }
+/**
+ * Strings rendered by `<ForgotPasswordFields>` — the embedded modal body. It is
+ * the forgot-password form plus the two modal affordances (`cancel` alongside
+ * submit, `close` on the success state) that a screen-shaped form has no need of.
+ */
+interface ForgotPasswordFieldsLabels extends ForgotPasswordFormLabels {
+    /** The "cancel" button shown alongside submit. */
+    cancel: string;
+    /** The "close" button shown on the success state. */
+    close: string;
+}
 /** Strings rendered by `<OtpForm>` — the two-step email-OTP login form. */
 interface OtpFormLabels {
     /** Title shown on the request-a-code step. */
@@ -104,6 +115,123 @@ interface PinFormLabels {
     /** Generic "that PIN was wrong / expired / locked out" message. */
     invalidPin: string;
 }
+/**
+ * Strings rendered by `<DevicePinUnlockScreen>` — the returning-device unlock
+ * gate. `{name}` / `{count}` placeholders are substituted by the component.
+ */
+interface DevicePinUnlockLabels {
+    /** Greeting with the remembered username; `{name}` is substituted. */
+    title: string;
+    /** Greeting when no username is remembered. */
+    titleNoName: string;
+    /** Copy above the PIN pad; `{count}` is substituted with the PIN length. */
+    description: string;
+    pinLabel: string;
+    pinPlaceholder: string;
+    /** The "unlock" submit button. */
+    submit: string;
+    /** Shown while the unlock is in flight. */
+    submitting: string;
+    /** The "sign in with password instead" escape link. */
+    usePasswordInstead: string;
+    /** Accessibility hint for the escape link. */
+    usePasswordHint: string;
+    /** Error: not enough digits entered; `{count}` is substituted. */
+    errorIncomplete: string;
+    /** Error: wrong PIN / unknown device (generic). */
+    errorInvalid: string;
+    /** Error: locked out, no retry hint. */
+    errorLockedOut: string;
+    /** Error: locked out with a retry hint; `{count}` is the seconds. */
+    errorLockedOutRetry: string;
+    /** Error: rate-limited, no retry hint. */
+    errorRateLimited: string;
+    /** Error: rate-limited with a retry hint; `{count}` is the seconds. */
+    errorRateLimitedRetry: string;
+    /** Error: anything else (network / unexpected). */
+    errorGeneric: string;
+    /** Accessibility label for a filled PIN dot. */
+    digitFilledHint: string;
+    /** Accessibility label for an empty PIN dot. */
+    digitEmptyHint: string;
+}
+/**
+ * Strings rendered by `<DevicePinEnrollForm>` (and the length picker it hosts)
+ * plus the `<DevicePinOffer>` wrapper. `{count}` placeholders are substituted.
+ */
+interface DevicePinEnrollLabels {
+    offerTitle: string;
+    offerDescription: string;
+    offerAccept: string;
+    offerAcceptHint: string;
+    offerSkip: string;
+    offerSkipHint: string;
+    formTitle: string;
+    /** Copy above the form; `{count}` is substituted with the chosen length. */
+    formDescription: string;
+    lengthLabel: string;
+    /** Accessibility hint for a length pill; `{count}` is substituted. */
+    lengthOptionHint: string;
+    pinLabel: string;
+    pinPlaceholder: string;
+    confirmLabel: string;
+    confirmPlaceholder: string;
+    submit: string;
+    submitting: string;
+    cancel: string;
+    cancelHint: string;
+    /** Error: PINs do not match / wrong length; `{count}` is substituted. */
+    errorMismatch: string;
+    /** Error: the current session is not authenticated. */
+    errorUnauthorized: string;
+    /** Error: the session already has a PIN / is forbidden. */
+    errorForbidden: string;
+    /** Error: the PIN failed server-side validation. */
+    errorInvalidPin: string;
+    /** Error: any other failure. */
+    errorFailed: string;
+}
+/** Strings rendered by `<DevicePinSettingsCard>` — the account toggle. */
+interface DevicePinSettingsLabels {
+    title: string;
+    description: string;
+    /** Status line when a device PIN is enabled. */
+    statusEnabled: string;
+    /** Status line when no device PIN is set. */
+    statusDisabled: string;
+    /** The "enable" button. */
+    enable: string;
+    enableHint: string;
+    /** The "disable" button. */
+    disable: string;
+    disableHint: string;
+    /** Shown while disabling is in flight. */
+    disabling: string;
+    /** Error shown when disabling fails. */
+    disableFailed: string;
+}
+/** Strings rendered by `<PasskeyLoginButton>` — the login-surface passkey CTA. */
+interface PasskeyLoginLabels {
+    /** The "sign in with a passkey" button. */
+    signInButton: string;
+    signInHint: string;
+    /** Error banner when the ceremony was cancelled. */
+    errorCancelled: string;
+    /** Error banner when the ceremony failed. */
+    errorFailed: string;
+}
+/** Strings rendered by `<PasskeySettingsCard>` — the account passkey card. */
+interface PasskeySettingsLabels {
+    title: string;
+    description: string;
+    /** Italic hint about the re-auth step. */
+    reauthHint: string;
+    /** The "add a passkey" button. */
+    addButton: string;
+    addHint: string;
+    /** Success line shown after returning from a registration. */
+    registeredSuccess: string;
+}
 /** Strings rendered by `<ResetPasswordForm>`. */
 interface ResetPasswordFormLabels {
     title: string;
@@ -127,8 +255,14 @@ interface ResetPasswordFormLabels {
 }
 declare const DEFAULT_LOGIN_LABELS: LoginFormLabels;
 declare const DEFAULT_FORGOT_PASSWORD_LABELS: ForgotPasswordFormLabels;
+declare const DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS: ForgotPasswordFieldsLabels;
 declare const DEFAULT_OTP_LABELS: OtpFormLabels;
 declare const DEFAULT_PIN_LABELS: PinFormLabels;
+declare const DEFAULT_DEVICE_PIN_UNLOCK_LABELS: DevicePinUnlockLabels;
+declare const DEFAULT_DEVICE_PIN_ENROLL_LABELS: DevicePinEnrollLabels;
+declare const DEFAULT_DEVICE_PIN_SETTINGS_LABELS: DevicePinSettingsLabels;
+declare const DEFAULT_PASSKEY_LOGIN_LABELS: PasskeyLoginLabels;
+declare const DEFAULT_PASSKEY_SETTINGS_LABELS: PasskeySettingsLabels;
 declare const DEFAULT_RESET_PASSWORD_LABELS: ResetPasswordFormLabels;
 
 /**
@@ -284,6 +418,56 @@ interface ForgotPasswordFormProps {
 /** Themeable "request a reset link" form built on `useBffForgotPassword`. */
 declare function ForgotPasswordForm({ client, theme: themeProp, labels: labelsProp, resetUrlTemplate, onSuccess, testIdPrefix, }: Readonly<ForgotPasswordFormProps>): ReactElement;
 
+/**
+ * `<ForgotPasswordFields>` — the embedded, themeable "request a reset link"
+ * body, sized to live INSIDE an app-owned modal shell (not a full screen).
+ *
+ * The product apps each show "Forgot password?" as a modal launched from their
+ * login route, wrapping their own modal chrome (title bar + close affordance)
+ * around an identical email field + submit/cancel body. This is that body,
+ * promoted into the package so the three apps stop hand-rolling it.
+ *
+ * Built on the react-query-free `useForgotPasswordSubmit` hook, so it renders +
+ * submits on a provider-less login route (where `useMutation` would crash). The
+ * backend is anti-enumeration, so a successful request swaps to a generic
+ * confirmation that never reveals whether the address is registered.
+ *
+ * Differs from the screen-shaped `<ForgotPasswordForm>`: no outer screen/card
+ * wrapper and no title (the host modal owns those), plus two modal affordances —
+ * a `Cancel` button beside submit and a `Close` button on the success state —
+ * each rendered only when its handler is supplied.
+ */
+
+interface ForgotPasswordFieldsProps {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<ForgotPasswordFieldsLabels>;
+    /**
+     * Full URL with a `{token}` placeholder, forwarded to the backend so it can
+     * build the reset-email link without hardcoding a frontend host.
+     */
+    resetUrlTemplate?: string;
+    /**
+     * The host modal's open state. When it flips to `false` the body clears
+     * itself, so reopening shows a fresh form regardless of which affordance
+     * closed it. Defaults to `true` for non-modal embedding.
+     */
+    visible?: boolean;
+    /** Called once the request succeeds (the generic-confirmation state). */
+    onSuccess?: () => void;
+    /** When supplied, renders a Cancel button beside submit. */
+    onCancel?: () => void;
+    /** When supplied, renders a Close button on the success state. */
+    onClose?: () => void;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+}
+/** Embedded "request a reset link" body for an app-owned modal. */
+declare function ForgotPasswordFields({ client, theme: themeProp, labels: labelsProp, resetUrlTemplate, visible, onSuccess, onCancel, onClose, testIdPrefix, }: Readonly<ForgotPasswordFieldsProps>): ReactElement;
+
 /**
  * `<ResetPasswordForm>` — the ready-made, themeable "choose a new password"
  * form.
@@ -385,6 +569,421 @@ interface PinFormProps {
 /** Themeable single-step event-PIN login form built on `usePinLogin`. */
 declare function PinForm({ client, eventExternalId, theme: themeProp, labels: labelsProp, onSuccess, testIdPrefix, }: Readonly<PinFormProps>): ReactElement;
 
+/**
+ * A masked numeric PIN input for the device-PIN unlock + enrol surfaces.
+ *
+ * A single hidden secure `TextInput` captures the digits (numeric keyboard,
+ * length-capped, digits-only); a row of dot cells visualises how many have been
+ * entered. Tapping anywhere on the row focuses the field. Purely presentational
+ * — all submit / error logic lives in the unlock / enrol hooks. Styled from the
+ * `AuthTheme` token bag (no hardcoded brand colours).
+ */
+
+interface DevicePinInputProps {
+    /** The current PIN value (digits only). */
+    value: string;
+    /** Number of dot cells to render — the enrolled / chosen PIN length. */
+    length: number;
+    /** Disable input while a request is in flight. */
+    disabled: boolean;
+    /** Base testID for the underlying field (a11y + E2E targeting). */
+    testID: string;
+    /** Optional prefix applied to the testID. */
+    testIdPrefix?: string;
+    /** Accessibility label for the field. */
+    accessibilityLabel: string;
+    /** Accessibility hint for the field. */
+    accessibilityHint: string;
+    /** Accessibility label for a filled dot. */
+    filledHint: string;
+    /** Accessibility label for an empty dot. */
+    emptyHint: string;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Emit the next digits-only value (already length-capped). */
+    onChange: (next: string) => void;
+}
+/** Themeable masked PIN pad — dots reflect entered digits; a hidden field captures them. */
+declare function DevicePinInput({ value, length, disabled, testID, testIdPrefix, accessibilityLabel, accessibilityHint, filledHint, emptyHint, theme: themeProp, onChange, }: Readonly<DevicePinInputProps>): ReactElement;
+
+/**
+ * The PIN-length (4/6/8) picker row for `<DevicePinEnrollForm>`.
+ *
+ * Presentational: renders one pill per allowed length and reports the chosen
+ * one. Styled from the `AuthTheme` token bag. Extracted from the enrol form to
+ * keep that component focused.
+ */
+
+interface DevicePinLengthPickerProps {
+    /** The currently-selected PIN length. */
+    selected: number;
+    /** Disable while a request is in flight. */
+    disabled: boolean;
+    /** Accessibility hint template for a pill; `{count}` is substituted. */
+    optionHint: string;
+    /** Optional prefix applied to each pill's testID. */
+    testIdPrefix?: string;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Report the newly-chosen length. */
+    onSelect: (digits: number) => void;
+}
+/** Themeable 4/6/8 length chooser. */
+declare function DevicePinLengthPicker({ selected, disabled, optionHint, testIdPrefix, theme: themeProp, onSelect, }: Readonly<DevicePinLengthPickerProps>): ReactElement;
+
+/**
+ * The localizable error states the device-PIN UNLOCK surface can show.
+ *
+ * Kept deliberately coarse so the UI never reveals whether a failed unlock was a
+ * wrong PIN or an unknown / revoked device (both map to `Invalid`). `LockedOut`
+ * and `RateLimited` carry no count — the human-readable "try again later" copy
+ * is built from the `retryAfterSeconds` hint at the call site, not encoded here.
+ */
+declare const enum DevicePinErrorKey {
+    /** The PIN entered was too short for the enrolled length. */
+    Incomplete = "incomplete",
+    /** Wrong PIN, or unknown / revoked device. Generic on purpose. */
+    Invalid = "invalid",
+    /** Locked out after too many wrong attempts. */
+    LockedOut = "locked_out",
+    /** Rate-limited by the BFF (too many requests). */
+    RateLimited = "rate_limited",
+    /** Anything else (network / unexpected). */
+    Generic = "generic"
+}
+
+/**
+ * Structural prop/result contracts for the device-PIN surfaces.
+ *
+ * `@dloizides/auth-web` deliberately does NOT take a hard dependency on the
+ * device-PIN methods that `@dloizides/auth-client` 3.3.0 adds. Instead the
+ * components depend on the **structural** shapes below — exactly what each one
+ * needs and no more. A real client (auth-client 3.3.0) satisfies
+ * {@link DevicePinCapableClient} by duck-typing; an app can equally pass a thin
+ * hand-rolled object. This keeps the two packages decoupled and lets a consumer
+ * upgrade either independently.
+ *
+ * The discriminated result shapes mirror the BFF's meaningfully-distinct
+ * outcomes (a wrong PIN, a lockout with a retry hint, a rate-limit, a generic
+ * error) so the unlock / enrol UIs can route on each one rather than collapsing
+ * them into a single opaque failure.
+ */
+/**
+ * The per-device half of `GET /bff/config` — what this device remembers about
+ * the last user, all fields safe-defaulted by the parser when absent.
+ */
+interface BffDeviceState {
+    /** Non-secret username this device remembers, or `null` when none. */
+    rememberedUsername: string | null;
+    /** `true` when this device has an enrolled device PIN. */
+    hasPin: boolean;
+    /** The enrolled PIN length (4/6/8), or `null` when unknown / no PIN. */
+    pinDigits: number | null;
+    /** The device-local preferred-method hint (e.g. `"pin"`), or `null`. */
+    preferredMethod: string | null;
+}
+/** The shape `GET /bff/config` resolves to (as the client parses it). */
+interface BffLoginConfig {
+    /** The enabled login methods, lower-cased (e.g. `["password", "otp"]`). */
+    methods: string[];
+    /** `true` when self-serve registration is enabled for this BFF. */
+    registrationEnabled: boolean;
+    /** The per-device remembered state. */
+    deviceState: BffDeviceState;
+}
+/**
+ * Discriminated result of a device-PIN UNLOCK attempt. The client never rejects;
+ * it resolves one of these so the UI can route on the distinct outcomes (a
+ * lockout / rate-limit carries an optional `retryAfterSeconds` hint).
+ */
+type DevicePinUnlockResult = {
+    status: 'success';
+    user: {
+        [claim: string]: unknown;
+    };
+} | {
+    status: 'invalid';
+} | {
+    status: 'locked';
+    retryAfterSeconds: number | null;
+} | {
+    status: 'rateLimited';
+    retryAfterSeconds: number | null;
+} | {
+    status: 'error';
+};
+/**
+ * Discriminated result of a device-PIN ENROL attempt. The client never rejects;
+ * it resolves one of these so the form can show the precise failure cause.
+ */
+type DevicePinEnrollResult = {
+    status: 'success';
+} | {
+    status: 'unauthorized';
+} | {
+    status: 'forbidden';
+} | {
+    status: 'invalidPin';
+} | {
+    status: 'error';
+};
+/**
+ * The client capability the device-PIN components depend on. `auth-client`
+ * 3.3.0 satisfies this structurally; a consuming app may also pass a thin
+ * hand-rolled object exposing exactly these four methods.
+ */
+interface DevicePinCapableClient {
+    /** Read `GET /bff/config` (methods + per-device state). */
+    getLoginConfig(): Promise<BffLoginConfig>;
+    /** Bind a device PIN of `digits` length to the current session. */
+    enrollDevicePin(request: {
+        pin: string;
+        digits: number;
+    }): Promise<DevicePinEnrollResult>;
+    /** Re-establish a session from a remembered device using `pin`. */
+    unlockWithDevicePin(request: {
+        pin: string;
+    }): Promise<DevicePinUnlockResult>;
+    /** Drop the device PIN for the current session. Resolves `true` on success. */
+    disableDevicePin(): Promise<boolean>;
+}
+/** The minimal slice {@link useBffLoginConfig} needs from a client. */
+interface LoginConfigCapableClient {
+    getLoginConfig(): Promise<BffLoginConfig>;
+}
+/** The minimal slice {@link useDevicePinUnlock} needs from a client. */
+interface DevicePinUnlockCapableClient {
+    unlockWithDevicePin(request: {
+        pin: string;
+    }): Promise<DevicePinUnlockResult>;
+}
+/** The minimal slice {@link useDevicePinEnroll} needs from a client. */
+interface DevicePinEnrollCapableClient {
+    enrollDevicePin(request: {
+        pin: string;
+        digits: number;
+    }): Promise<DevicePinEnrollResult>;
+}
+/** The minimal slice {@link DevicePinSettingsCard} needs to disable a PIN. */
+interface DevicePinDisableCapableClient {
+    disableDevicePin(): Promise<boolean>;
+}
+
+/** The signed-in user shape the success path hands back (claim bag). */
+type DevicePinUnlockedUser = {
+    [claim: string]: unknown;
+};
+interface UseDevicePinUnlockArgs {
+    /** The client exposing `unlockWithDevicePin`. */
+    client: DevicePinUnlockCapableClient;
+    /** Enrolled PIN length (4/6/8) — a shorter entry is rejected before any call. */
+    digits: number;
+    /** Called with the fresh user after a successful unlock. */
+    onSignedIn: (user: DevicePinUnlockedUser) => void;
+}
+interface UseDevicePinUnlockResult {
+    /** The PIN currently entered. */
+    pin: string;
+    /** `true` while an unlock call is in flight. */
+    submitting: boolean;
+    /** The current error key, or `null` when there is none. */
+    errorKey: DevicePinErrorKey | null;
+    /** Seconds until retry, set with a `LockedOut`/`RateLimited` error; else `null`. */
+    retryAfterSeconds: number | null;
+    /** Replace the entered PIN. Clears a stale error. */
+    setPin: (next: string) => void;
+    /** Run the unlock attempt for the current PIN. */
+    submit: () => void;
+}
+declare function useDevicePinUnlock({ client, digits, onSignedIn, }: UseDevicePinUnlockArgs): UseDevicePinUnlockResult;
+
+/**
+ * The device-PIN UNLOCK gate — shown on the login route for a returning,
+ * logged-OUT user whose device is remembered (`hasPin && rememberedUsername`).
+ *
+ * Renders a masked PIN pad of the enrolled length; on submit it calls
+ * `client.unlockWithDevicePin` (via {@link useDevicePinUnlock}) and, on success,
+ * routes through the SAME `onSignedIn` path as the password tab. A
+ * "Sign in with password instead" escape calls `onUsePassword` (the caller swaps
+ * this screen out). All five result statuses are handled, including the lockout /
+ * rate-limit retry countdown surfaced from `retryAfterSeconds`.
+ *
+ * react-query-FREE: all logic lives in `useDevicePinUnlock`, which uses plain
+ * `useState` + `.then()` over the client — never `useMutation`. Presentational
+ * only here. Distinct from the event-staff PIN (`PinForm`); this is `devicePin`.
+ */
+
+interface DevicePinUnlockScreenProps {
+    /** The client exposing `unlockWithDevicePin`. */
+    client: DevicePinUnlockCapableClient;
+    /** Enrolled PIN length (4/6/8). */
+    digits: number;
+    /** Remembered username, shown in the greeting (may be empty). */
+    rememberedUsername: string;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<DevicePinUnlockLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+    /** Called with the fresh user after a successful unlock. */
+    onSignedIn: (user: DevicePinUnlockedUser) => void;
+    /** Escape hatch → render the normal password/OTP/event-PIN tabs. */
+    onUsePassword: () => void;
+}
+/** Themeable device-PIN unlock gate built on `useDevicePinUnlock`. */
+declare function DevicePinUnlockScreen({ client, digits, rememberedUsername, theme: themeProp, labels: labelsProp, testIdPrefix, onSignedIn, onUsePassword, }: Readonly<DevicePinUnlockScreenProps>): ReactElement;
+
+/**
+ * The shared device-PIN ENROL form — reused by the post-login offer
+ * ({@link DevicePinOffer}) and the settings toggle ({@link DevicePinSettingsCard}).
+ *
+ * Lets the user pick a PIN length (4/6/8), enter + confirm a PIN, and submit via
+ * `client.enrollDevicePin` (through {@link useDevicePinEnroll}). On success it
+ * calls `onEnrolled`; `onCancel` dismisses without saving. Presentational only —
+ * all submit / mismatch / status logic lives in the hook (react-query-free).
+ * Styled from the `AuthTheme` token bag.
+ */
+
+interface DevicePinEnrollFormProps {
+    /** The client exposing `enrollDevicePin`. */
+    client: DevicePinEnrollCapableClient;
+    /** Initial PIN length (defaults to {@link DEVICE_PIN_DEFAULT_DIGITS}). */
+    initialDigits?: number;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<DevicePinEnrollLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+    /** Called after a successful enrol. */
+    onEnrolled: () => void;
+    /** Called when the user cancels without saving. */
+    onCancel: () => void;
+}
+/** Themeable device-PIN enrol form built on `useDevicePinEnroll`. */
+declare function DevicePinEnrollForm({ client, initialDigits, theme: themeProp, labels: labelsProp, testIdPrefix, onEnrolled, onCancel, }: Readonly<DevicePinEnrollFormProps>): ReactElement;
+
+/**
+ * The skippable post-login "Set a PIN for faster sign-in?" offer.
+ *
+ * Mount on the post-login landing for an authenticated user who does NOT already
+ * have a device PIN. It is dismissible and non-blocking: an initial prompt with
+ * "Set up a PIN" / "Not now"; tapping accept reveals the shared
+ * {@link DevicePinEnrollForm}; on success or skip it calls `onDismiss` so the
+ * host can hide it (and remember the dismissal). Self-contained, react-query-free.
+ */
+
+interface DevicePinOfferProps {
+    /** The client exposing `enrollDevicePin`. */
+    client: DevicePinEnrollCapableClient;
+    /** Initial PIN length offered in the enrol form. */
+    initialDigits?: number;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<DevicePinEnrollLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+    /** Called when the offer is finished — accepted+enrolled, or skipped. */
+    onDismiss: () => void;
+}
+/** Themeable, skippable post-login device-PIN setup offer. */
+declare function DevicePinOffer({ client, initialDigits, theme: themeProp, labels: labelsProp, testIdPrefix, onDismiss, }: Readonly<DevicePinOfferProps>): ReactElement;
+
+/**
+ * The authenticated "Quick PIN sign-in" settings control.
+ *
+ * Mount on an authenticated settings/account surface. Seeded with `initialHasPin`
+ * (from `GET /bff/config`); it tracks its own enabled/disabled state thereafter
+ * and offers either:
+ *  - Enable → reveals the shared {@link DevicePinEnrollForm} → `client.enrollDevicePin`;
+ *  - Disable → `client.disableDevicePin` (revokes the offline token + clears the
+ *    device record server-side).
+ *
+ * `onChanged(hasPin)` fires whenever the enabled state flips, so the host can
+ * persist / re-fetch. react-query-free: the disable logic lives in
+ * {@link useDevicePinDisable}; the enrol logic in the shared form's hook.
+ */
+
+interface DevicePinSettingsCardProps {
+    /** The client exposing both `enrollDevicePin` and `disableDevicePin`. */
+    client: DevicePinEnrollCapableClient & DevicePinDisableCapableClient;
+    /** Whether this device already has an enrolled PIN (seeded from config). */
+    initialHasPin: boolean;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Settings-card copy. Partial — unspecified keys fall back to English. */
+    labels?: Partial<DevicePinSettingsLabels>;
+    /** Enrol-form copy passed through to the embedded form. */
+    enrollLabels?: Partial<DevicePinEnrollLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+    /** Called whenever the enabled state flips (enabled / disabled). */
+    onChanged?: (hasPin: boolean) => void;
+}
+/** Themeable authenticated device-PIN enable/disable card. */
+declare function DevicePinSettingsCard({ client, initialHasPin, theme: themeProp, labels: labelsProp, enrollLabels, testIdPrefix, onChanged, }: Readonly<DevicePinSettingsCardProps>): ReactElement;
+
+/**
+ * The "Sign in with a passkey" button rendered on the unified login surface when
+ * the BFF advertises the `passkey` method.
+ *
+ * A passkey login is a full-page BROWSER NAVIGATION, not a fetch: tapping the
+ * button hands off to `/bff/passkey/login`, which drives the WebAuthn ceremony
+ * through Keycloak and returns the browser to `returnUrl` (default `'/'`, which
+ * routes an authenticated user to their dashboard) with a session cookie set. On
+ * a cancelled / failed ceremony the BFF bounces back to `?passkeyError=…`; we
+ * surface that as an inline error banner above the button.
+ *
+ * react-query-free: it is pure `window.location` navigation (see
+ * `passkeyNavigation`), so it is safe to mount inside the login route group which
+ * has no QueryClient provider.
+ */
+
+interface PasskeyLoginButtonProps {
+    /** Relative app path the BFF returns to on success. Defaults to `'/'`. */
+    returnUrl?: string;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<PasskeyLoginLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+}
+/** Themeable passkey login CTA + error banner. */
+declare function PasskeyLoginButton({ returnUrl, theme: themeProp, labels: labelsProp, testIdPrefix, }: Readonly<PasskeyLoginButtonProps>): ReactElement;
+
+/**
+ * The authenticated "Passkeys" settings card.
+ *
+ * Mount on an authenticated settings / account surface (alongside the device-PIN
+ * card). Adding a passkey is a full-page BROWSER NAVIGATION to
+ * `/bff/passkey/register`: Keycloak re-authenticates the user (password) then
+ * runs the WebAuthn credential-creation ceremony, returning the browser to the
+ * SAME settings page with `?passkey=registered` appended. On mount we read that
+ * param and, when present, show a success line.
+ *
+ * react-query-free: the add action is pure `window.location` navigation (see
+ * `passkeyNavigation`); there is no fetch here. Mirrors `DevicePinSettingsCard`.
+ */
+
+interface PasskeySettingsCardProps {
+    /**
+     * Relative app path the BFF returns to after registration. Defaults to the
+     * current `window.location.pathname` so the user lands back on this page.
+     */
+    returnUrl?: string;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<PasskeySettingsLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+}
+/** Themeable authenticated passkey add card. */
+declare function PasskeySettingsCard({ returnUrl, theme: themeProp, labels: labelsProp, testIdPrefix, }: Readonly<PasskeySettingsCardProps>): ReactElement;
+
 /**
  * React context for the `AuthTheme`.
  *
@@ -438,6 +1037,8 @@ declare const AuthTestIds: {
     readonly forgotPasswordForm: "auth-forgot-form";
     readonly forgotPasswordEmailInput: "auth-forgot-email";
     readonly forgotPasswordSubmitButton: "auth-forgot-submit";
+    readonly forgotPasswordCancelButton: "auth-forgot-cancel";
+    readonly forgotPasswordCloseButton: "auth-forgot-close";
     readonly forgotPasswordError: "auth-forgot-error";
     readonly forgotPasswordSuccess: "auth-forgot-success";
     readonly resetPasswordForm: "auth-reset-form";
@@ -457,6 +1058,32 @@ declare const AuthTestIds: {
     readonly pinInput: "auth-pin-input";
     readonly pinSubmitButton: "auth-pin-submit";
     readonly pinError: "auth-pin-error";
+    readonly devicePinUnlock: "auth-device-pin-unlock";
+    readonly devicePinUnlockInput: "auth-device-pin-unlock-input";
+    readonly devicePinUnlockSubmit: "auth-device-pin-unlock-submit";
+    readonly devicePinUnlockUsePassword: "auth-device-pin-unlock-use-password";
+    readonly devicePinUnlockError: "auth-device-pin-unlock-error";
+    readonly devicePinEnrollForm: "auth-device-pin-enroll-form";
+    readonly devicePinEnrollLength: "auth-device-pin-enroll-length";
+    readonly devicePinEnrollPin: "auth-device-pin-enroll-pin";
+    readonly devicePinEnrollConfirm: "auth-device-pin-enroll-confirm";
+    readonly devicePinEnrollSubmit: "auth-device-pin-enroll-submit";
+    readonly devicePinEnrollCancel: "auth-device-pin-enroll-cancel";
+    readonly devicePinEnrollError: "auth-device-pin-enroll-error";
+    readonly devicePinOffer: "auth-device-pin-offer";
+    readonly devicePinOfferAccept: "auth-device-pin-offer-accept";
+    readonly devicePinOfferSkip: "auth-device-pin-offer-skip";
+    readonly devicePinSettings: "auth-device-pin-settings";
+    readonly devicePinSettingsStatus: "auth-device-pin-settings-status";
+    readonly devicePinSettingsEnable: "auth-device-pin-settings-enable";
+    readonly devicePinSettingsDisable: "auth-device-pin-settings-disable";
+    readonly devicePinSettingsError: "auth-device-pin-settings-error";
+    readonly passkeyLogin: "auth-passkey-login";
+    readonly passkeyLoginButton: "auth-passkey-login-button";
+    readonly passkeyLoginError: "auth-passkey-login-error";
+    readonly passkeySettings: "auth-passkey-settings";
+    readonly passkeySettingsAdd: "auth-passkey-settings-add";
+    readonly passkeySettingsSuccess: "auth-passkey-settings-success";
 };
 /** Apply an optional prefix to a base test ID. */
 declare function withTestIdPrefix(baseId: string, prefix?: string): string;
@@ -590,6 +1217,38 @@ interface UseResetPasswordFormResult {
  */
 declare function useResetPasswordForm({ client, token, onSuccess, }: UseResetPasswordFormArgs): UseResetPasswordFormResult;
 
+/** `true` when `value` (after trimming) looks like an email address. */
+declare function isValidForgotPasswordEmail(value: string): boolean;
+interface UseForgotPasswordSubmitArgs {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /**
+     * Full URL with a `{token}` placeholder, forwarded to the backend so it can
+     * build the reset-email link without hardcoding a frontend host.
+     */
+    resetUrlTemplate?: string;
+    /** Invoked once the request succeeds (the generic-confirmation state). */
+    onSuccess?: () => void;
+}
+interface UseForgotPasswordSubmitResult {
+    email: string;
+    setEmail: (value: string) => void;
+    /** `true` once the request has succeeded (show the generic confirmation). */
+    submitted: boolean;
+    /** `true` while the request is in flight. */
+    isSubmitting: boolean;
+    /** `true` when the last submit hit a network / 5xx failure. */
+    hasNetworkError: boolean;
+    /** `true` when the email is valid and no request is in flight. */
+    canSubmit: boolean;
+    /** Validate, then fire the request (no-op when `canSubmit` is false). */
+    submit: () => void;
+    /** Clear all state — call when the modal closes. */
+    reset: () => void;
+}
+/** Headless, react-query-free "request a reset link" logic. */
+declare function useForgotPasswordSubmit({ client, resetUrlTemplate, onSuccess, }: UseForgotPasswordSubmitArgs): UseForgotPasswordSubmitResult;
+
 /**
  * The two discrete steps of the email-OTP login flow.
  *
@@ -679,6 +1338,148 @@ interface UsePinLoginResult {
  */
 declare function usePinLogin(options: UsePinLoginOptions): UsePinLoginResult;
 
+/** What {@link useBffLoginConfig} returns. */
+interface UseBffLoginConfigResult {
+    /** The parsed login config; the empty fallback until the fetch resolves. */
+    config: BffLoginConfig;
+    /** `true` until the initial `getLoginConfig` call settles. */
+    loading: boolean;
+}
+/**
+ * Fetch `getLoginConfig()` once on mount and expose `{ config, loading }`. The
+ * empty fallback config is used until the call resolves and on any failure. The
+ * effect guards against a `setState` after the consumer unmounts mid-request.
+ */
+declare function useBffLoginConfig(client: LoginConfigCapableClient): UseBffLoginConfigResult;
+
+/**
+ * The localizable failure states the device-PIN ENROL form can show — shared by
+ * the post-login offer and the settings toggle.
+ */
+declare const enum DevicePinEnrollErrorKey {
+    /** PIN length wrong or the confirmation didn't match (no network call). */
+    Mismatch = "mismatch",
+    /** The current session is not authenticated (401). */
+    Unauthorized = "unauthorized",
+    /** The session already has a PIN, or is otherwise forbidden (403). */
+    Forbidden = "forbidden",
+    /** The PIN failed server-side validation (400). */
+    InvalidPin = "invalid_pin",
+    /** Any other failure (grant / network / unexpected). */
+    Failed = "failed"
+}
+
+interface UseDevicePinEnrollArgs {
+    /** The client exposing `enrollDevicePin`. */
+    client: DevicePinEnrollCapableClient;
+    /** Chosen PIN length (4/6/8). */
+    digits: number;
+    /** Called after a successful enrol so the surface can dismiss / flip state. */
+    onEnrolled: () => void;
+}
+interface UseDevicePinEnrollResult {
+    pin: string;
+    confirmPin: string;
+    submitting: boolean;
+    errorKey: DevicePinEnrollErrorKey | null;
+    setPin: (next: string) => void;
+    setConfirmPin: (next: string) => void;
+    submit: () => void;
+}
+declare function useDevicePinEnroll({ client, digits, onEnrolled, }: UseDevicePinEnrollArgs): UseDevicePinEnrollResult;
+
+interface UseDevicePinDisableArgs {
+    /** The client exposing `disableDevicePin`. */
+    client: DevicePinDisableCapableClient;
+    /** Whether this device already has an enrolled PIN (seeded from config). */
+    initialHasPin: boolean;
+    /** Called whenever the enabled state changes (enabled / disabled). */
+    onChanged?: (hasPin: boolean) => void;
+}
+interface UseDevicePinDisableResult {
+    /** `true` when the device currently has an enrolled PIN. */
+    hasPin: boolean;
+    /** `true` while a disable call is in flight. */
+    disabling: boolean;
+    /** `true` when the last disable attempt failed. */
+    failed: boolean;
+    /** Run the disable call for the current session. */
+    disable: () => void;
+    /** Flip the card to enabled (called by the host after a successful enrol). */
+    markEnabled: () => void;
+}
+declare function useDevicePinDisable({ client, initialHasPin, onChanged, }: UseDevicePinDisableArgs): UseDevicePinDisableResult;
+
+/**
+ * Shared device-PIN constants for the unlock + enrol surfaces.
+ *
+ * The allowed PIN lengths (4 / 6 / 8) mirror the BFF's accepted `digits` values
+ * (`POST /bff/pin/enroll`). Centralised here so neither the enrol form nor the
+ * unlock screen carries magic numbers, and so the default length is defined once.
+ */
+/** The PIN lengths the BFF accepts on enrol (`digits` ∈ {4, 6, 8}). */
+declare const DEVICE_PIN_ALLOWED_DIGITS: readonly number[];
+/** Default PIN length offered when the BFF reports no stored `pinDigits`. */
+declare const DEVICE_PIN_DEFAULT_DIGITS = 4;
+/** Guard: is `value` one of the BFF-accepted PIN lengths? */
+declare function isAllowedPinDigits(value: number): boolean;
+
+/**
+ * Navigation helpers for the passkey (WebAuthn) BFF endpoints.
+ *
+ * Unlike the device-PIN client (which is plain `fetch`), the passkey login and
+ * registration ceremonies are NOT fetches — they are full-page BROWSER
+ * NAVIGATIONS. The BFF (`Bff.AspNetCore` 1.3.x) drives the WebAuthn ceremony
+ * through Keycloak's hosted pages, then redirects the browser back:
+ *  - login:        `/bff/passkey/login?returnUrl=<rel>` → on success the browser
+ *    lands on `returnUrl` with the session cookie already set;
+ *  - registration: `/bff/passkey/register?returnUrl=<rel>` → Keycloak re-auths
+ *    the user (password) then runs the credential-creation ceremony, returning
+ *    the browser to `returnUrl?passkey=registered`;
+ *  - failure / cancel: the BFF redirects to `<login>?passkeyError=cancelled` or
+ *    `<login>?passkeyError=failed`.
+ *
+ * react-query-FREE by construction: there is NO fetch here at all — every
+ * function is a pure `window.location` read or `window.location.assign`. The
+ * login route group has no QueryClient provider, so the passkey login button
+ * (which lives there) MUST avoid any react-query primitive; navigation satisfies
+ * that trivially.
+ *
+ * All reads are SSR-safe: when `window` is undefined (server render / native)
+ * they return a benign default rather than throwing.
+ */
+/** The recognised passkey error codes the BFF sends back via `?passkeyError=`. */
+type PasskeyErrorCode = 'cancelled' | 'failed';
+/**
+ * Start the passkey LOGIN ceremony by navigating the browser to the BFF's
+ * `/bff/passkey/login` endpoint. The BFF redirects through Keycloak's WebAuthn
+ * ceremony and, on success, returns the browser to `returnUrl` with a session
+ * cookie set. No-op off-web (no `window`). `returnUrl` should be a relative
+ * app path (e.g. `'/'`).
+ */
+declare function startPasskeyLogin(returnUrl: string): void;
+/**
+ * Start the passkey REGISTRATION ceremony by navigating the browser to the BFF's
+ * `/bff/passkey/register` endpoint. Requires an authenticated session; Keycloak
+ * re-authenticates the user (password) then runs the credential-creation
+ * ceremony, returning the browser to `returnUrl?passkey=registered`. No-op
+ * off-web. `returnUrl` should be a relative app path so the user lands back on
+ * the same settings surface.
+ */
+declare function startPasskeyRegistration(returnUrl: string): void;
+/**
+ * Read the `?passkeyError=` query param the BFF appends on a failed / cancelled
+ * ceremony. Returns `'cancelled'` or `'failed'` for the two known values, or
+ * `null` for an absent / unknown value. SSR-safe (returns `null` off-web).
+ */
+declare function readPasskeyError(): PasskeyErrorCode | null;
+/**
+ * `true` when the browser has just returned from a successful passkey
+ * registration, i.e. the `?passkey=registered` query param is present. SSR-safe
+ * (returns `false` off-web).
+ */
+declare function readPasskeyRegistered(): boolean;
+
 /**
  * `createBffAuthClient` — the one-line wiring of a same-origin `BffAuthClient`.
  *
@@ -814,4 +1615,4 @@ declare function validatePasswordPolicy(password: string): PasswordPolicyError[]
 /** `true` when the password satisfies every policy rule. */
 declare function isPasswordValid(password: string): boolean;
 
-export { AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type CreateBffAuthClientOptions, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PIN_LABELS, DEFAULT_RESET_PASSWORD_LABELS, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffResetPasswordOptions, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePinLoginOptions, type UsePinLoginResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, collectUserRoles, createBffAuthClient, defaultAuthTheme, isPasswordValid, resolvePostLoginRoute, useAuthTheme, useBffAuth, useBffForgotPassword, useBffResetPassword, useOtpLogin, usePinLogin, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };
+export { AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePinLoginOptions, type UsePinLoginResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, collectUserRoles, createBffAuthClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readPasskeyError, readPasskeyRegistered, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePinLogin, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };