@dloizides/auth-web 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 1.8.0 (2026-07-09)
+
+Additive release for the Move 2b passkey in-app rebuild — the passkey ceremony
+now runs **in-page** (`navigator.credentials.*` against the BFF's same-origin
+`/bff/passkey/*` fetch endpoints) instead of a full-page redirect to Keycloak.
+**Inert by default / no behaviour change until the BFF's WebAuthn RP is
+configured:** when the RP is off the options endpoint returns 501 and the hook
+transparently falls back to the legacy redirect. No breaking changes; every
+1.7.x export is unchanged and the legacy `startPasskeyLogin` /
+`startPasskeyRegistration` navigation helpers stay exported (they ARE the
+fallback).
+
+### Added
+
+- **`usePasskeyCeremony({ mode, returnUrl, onSuccess })`** — the react-query-free
+  in-page ceremony hook: options fetch → `navigator.credentials.create/get` →
+  verify fetch. Returns `{ status, error, isSupported, start, reset }`. Falls
+  back to the legacy Keycloak redirect on a 501 (RP not configured), any non-2xx
+  options response, or an unsupported browser — so nothing regresses until the
+  owner flips `Bff:Passkey`. A cancelled/timed-out ceremony (`NotAllowedError` /
+  `AbortError`) surfaces as `'cancelled'`, anything else as `'failed'`.
+- **`PasskeyCeremonyMode`** (`Login` / `Register`) and **`PasskeyCeremonyStatus`**
+  (`Idle` / `Running` / `Success` / `Error`) `const enum`s.
+
+### Changed
+
+- **`<PasskeyLoginButton>`** and **`<PasskeySettingsCard>`** now drive
+  `usePasskeyCeremony` instead of `window.location.assign`. Same exported props,
+  same testIDs — a drop-in bump for consumers; the in-page path only activates
+  once the BFF RP is configured, otherwise they behave exactly as before.
+
 ## 1.7.0 (2026-07-07)
 
 Additive release for the Kefi multi-role overhaul — the shared machinery for a

package/dist/index.d.mts

@@ -345,6 +345,13 @@ interface PasskeyLoginLabels {
     errorCancelled: string;
     /** Error banner when the ceremony failed. */
     errorFailed: string;
+    /**
+     * The "try another way" affordance shown after an in-page ceremony error — it
+     * hands off to the Keycloak-hosted passkey/password flow. This is the seam that
+     * rescues a user whose credential is only enrolled in Keycloak (not the in-page
+     * RP store): the in-page ceremony can't see it, so they fall back to KC.
+     */
+    tryAnotherWay: string;
 }
 /** Strings rendered by `<PasskeySettingsCard>` — the account passkey card. */
 interface PasskeySettingsLabels {
@@ -1022,16 +1029,18 @@ declare function DevicePinSettingsCard({ client, initialHasPin, theme: themeProp
  * 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.
+ * The passkey login runs IN-PAGE via `usePasskeyCeremony`
+ * (`navigator.credentials.get` against the same-origin `/bff/passkey/login/*`
+ * fetch endpoints), landing the authenticated user on `returnUrl` (default `'/'`)
+ * with a session cookie set. When the BFF's WebAuthn RP is not configured the
+ * options endpoint returns 501 and the hook transparently falls back to the
+ * legacy Keycloak redirect — so nothing regresses until the flag flips. A
+ * cancelled / failed in-page ceremony surfaces as an inline error banner; a prior
+ * redirect round-trip's `?passkeyError=…` is still honoured too.
  *
- * 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.
+ * react-query-free: the hook uses plain `fetch` + `useState` (see
+ * `usePasskeyCeremony`), so it is safe to mount inside the login route group
+ * which has no QueryClient provider.
  */
 
 interface PasskeyLoginButtonProps {
@@ -1051,14 +1060,16 @@ declare function PasskeyLoginButton({ returnUrl, theme: themeProp, labels: label
  * 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.
+ * card). Adding a passkey runs IN-PAGE via `usePasskeyCeremony`
+ * (`navigator.credentials.create` against the same-origin
+ * `/bff/passkey/register/*` fetch endpoints, session-cookie authenticated); on
+ * success we show an inline success line — no navigation. When the BFF's WebAuthn
+ * RP is not configured the options endpoint returns 501 and the hook falls back
+ * to the legacy Keycloak redirect, which returns here with `?passkey=registered`;
+ * that param is still honoured on mount, so nothing regresses until the flag flips.
  *
- * react-query-free: the add action is pure `window.location` navigation (see
- * `passkeyNavigation`); there is no fetch here. Mirrors `DevicePinSettingsCard`.
+ * react-query-free: the hook uses plain `fetch` + `useState` (see
+ * `usePasskeyCeremony`). Mirrors `DevicePinSettingsCard`.
  */
 
 interface PasskeySettingsCardProps {
@@ -1297,6 +1308,7 @@ declare const AuthTestIds: {
     readonly passkeyLogin: "auth-passkey-login";
     readonly passkeyLoginButton: "auth-passkey-login-button";
     readonly passkeyLoginError: "auth-passkey-login-error";
+    readonly passkeyLoginFallback: "auth-passkey-login-fallback";
     readonly passkeySettings: "auth-passkey-settings";
     readonly passkeySettingsAdd: "auth-passkey-settings-add";
     readonly passkeySettingsSuccess: "auth-passkey-settings-success";
@@ -1644,6 +1656,44 @@ declare const DEVICE_PIN_DEFAULT_DIGITS = 4;
 /** Guard: is `value` one of the BFF-accepted PIN lengths? */
 declare function isAllowedPinDigits(value: number): boolean;
 
+/**
+ * Which WebAuthn ceremony {@link usePasskeyCeremony} drives.
+ *
+ * `Login` runs a usernameless/discoverable assertion
+ * (`navigator.credentials.get`) from the login surface; `Register` runs an
+ * attestation (`navigator.credentials.create`) from an authenticated settings
+ * surface. The mode selects the `/bff/passkey/{login,register}/*` endpoint pair
+ * and the matching redirect fallback.
+ */
+declare const enum PasskeyCeremonyMode {
+    /** Assertion ceremony — sign in with an existing passkey. */
+    Login = "login",
+    /** Attestation ceremony — add a passkey to the signed-in account. */
+    Register = "register"
+}
+
+/**
+ * The lifecycle state of an in-page passkey ceremony.
+ *
+ * `Idle` before the user acts; `Running` while options are fetched, the
+ * authenticator prompts, and the assertion/attestation is verified; `Success`
+ * once the BFF confirms (a login has a session cookie set, a registration has a
+ * stored credential); `Error` on a genuine in-page failure (see
+ * {@link PasskeyErrorCode}). A redirect fallback (RP not configured / unsupported
+ * browser) navigates the page away, so the hook never lands in a terminal state
+ * for that path.
+ */
+declare const enum PasskeyCeremonyStatus {
+    /** No ceremony has started. */
+    Idle = "idle",
+    /** A ceremony is in flight (fetch → authenticator → verify). */
+    Running = "running",
+    /** The ceremony completed and the BFF confirmed it. */
+    Success = "success",
+    /** The ceremony failed in-page (cancelled or failed). */
+    Error = "error"
+}
+
 /**
  * Navigation helpers for the passkey (WebAuthn) BFF endpoints.
  *
@@ -1700,6 +1750,44 @@ declare function readPasskeyError(): PasskeyErrorCode | null;
  */
 declare function readPasskeyRegistered(): boolean;
 
+/** Options for {@link usePasskeyCeremony}. */
+interface UsePasskeyCeremonyOptions {
+    /** Which ceremony to run — login (assertion) or register (attestation). */
+    mode: PasskeyCeremonyMode;
+    /**
+     * Relative app path used two ways: the redirect fallback returns here, and (for
+     * login) a successful in-page ceremony navigates here unless `onSuccess` is set.
+     */
+    returnUrl: string;
+    /**
+     * Called on a successful in-page ceremony. For login it receives the signed-in
+     * `BffUser`; for register it receives `undefined`. When omitted, a login
+     * navigates to `returnUrl` and a register just resolves to `Success`.
+     */
+    onSuccess?: (user: BffUser | undefined) => void;
+}
+/** The state + controls {@link usePasskeyCeremony} returns. */
+interface UsePasskeyCeremonyResult {
+    /** Current lifecycle state. */
+    status: PasskeyCeremonyStatus;
+    /** The in-page error code, or `null`. */
+    error: PasskeyErrorCode | null;
+    /** `true` when the browser can run the in-page ceremony (else it redirects). */
+    isSupported: boolean;
+    /** Start the ceremony (or redirect-fallback when the RP is off / unsupported). */
+    start: () => void;
+    /**
+     * Hand off to the legacy Keycloak redirect explicitly. Wired to the "try
+     * another way" affordance a surface shows after an in-page error — the escape
+     * hatch for a credential enrolled only in Keycloak (invisible to the in-page
+     * RP store), which the in-page ceremony cannot use.
+     */
+    fallbackToRedirect: () => void;
+    /** Clear a terminal state so the affordance can be retried. */
+    reset: () => void;
+}
+declare function usePasskeyCeremony(optionsArg: UsePasskeyCeremonyOptions): UsePasskeyCeremonyResult;
+
 /**
  * Device-local cache of the user's preferred login method (unified-login D5).
  *
@@ -1906,4 +1994,4 @@ declare function validatePasswordPolicy(password: string): PasswordPolicyError[]
 /** `true` when the password satisfies every policy rule. */
 declare function isPasswordValid(password: string): boolean;
 
-export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, 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_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_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, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, 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 UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };
+export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, 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_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_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, PasskeyCeremonyMode, PasskeyCeremonyStatus, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, 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 UsePasskeyCeremonyOptions, type UsePasskeyCeremonyResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePasskeyCeremony, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };

package/dist/index.d.ts

@@ -345,6 +345,13 @@ interface PasskeyLoginLabels {
     errorCancelled: string;
     /** Error banner when the ceremony failed. */
     errorFailed: string;
+    /**
+     * The "try another way" affordance shown after an in-page ceremony error — it
+     * hands off to the Keycloak-hosted passkey/password flow. This is the seam that
+     * rescues a user whose credential is only enrolled in Keycloak (not the in-page
+     * RP store): the in-page ceremony can't see it, so they fall back to KC.
+     */
+    tryAnotherWay: string;
 }
 /** Strings rendered by `<PasskeySettingsCard>` — the account passkey card. */
 interface PasskeySettingsLabels {
@@ -1022,16 +1029,18 @@ declare function DevicePinSettingsCard({ client, initialHasPin, theme: themeProp
  * 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.
+ * The passkey login runs IN-PAGE via `usePasskeyCeremony`
+ * (`navigator.credentials.get` against the same-origin `/bff/passkey/login/*`
+ * fetch endpoints), landing the authenticated user on `returnUrl` (default `'/'`)
+ * with a session cookie set. When the BFF's WebAuthn RP is not configured the
+ * options endpoint returns 501 and the hook transparently falls back to the
+ * legacy Keycloak redirect — so nothing regresses until the flag flips. A
+ * cancelled / failed in-page ceremony surfaces as an inline error banner; a prior
+ * redirect round-trip's `?passkeyError=…` is still honoured too.
  *
- * 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.
+ * react-query-free: the hook uses plain `fetch` + `useState` (see
+ * `usePasskeyCeremony`), so it is safe to mount inside the login route group
+ * which has no QueryClient provider.
  */
 
 interface PasskeyLoginButtonProps {
@@ -1051,14 +1060,16 @@ declare function PasskeyLoginButton({ returnUrl, theme: themeProp, labels: label
  * 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.
+ * card). Adding a passkey runs IN-PAGE via `usePasskeyCeremony`
+ * (`navigator.credentials.create` against the same-origin
+ * `/bff/passkey/register/*` fetch endpoints, session-cookie authenticated); on
+ * success we show an inline success line — no navigation. When the BFF's WebAuthn
+ * RP is not configured the options endpoint returns 501 and the hook falls back
+ * to the legacy Keycloak redirect, which returns here with `?passkey=registered`;
+ * that param is still honoured on mount, so nothing regresses until the flag flips.
  *
- * react-query-free: the add action is pure `window.location` navigation (see
- * `passkeyNavigation`); there is no fetch here. Mirrors `DevicePinSettingsCard`.
+ * react-query-free: the hook uses plain `fetch` + `useState` (see
+ * `usePasskeyCeremony`). Mirrors `DevicePinSettingsCard`.
  */
 
 interface PasskeySettingsCardProps {
@@ -1297,6 +1308,7 @@ declare const AuthTestIds: {
     readonly passkeyLogin: "auth-passkey-login";
     readonly passkeyLoginButton: "auth-passkey-login-button";
     readonly passkeyLoginError: "auth-passkey-login-error";
+    readonly passkeyLoginFallback: "auth-passkey-login-fallback";
     readonly passkeySettings: "auth-passkey-settings";
     readonly passkeySettingsAdd: "auth-passkey-settings-add";
     readonly passkeySettingsSuccess: "auth-passkey-settings-success";
@@ -1644,6 +1656,44 @@ declare const DEVICE_PIN_DEFAULT_DIGITS = 4;
 /** Guard: is `value` one of the BFF-accepted PIN lengths? */
 declare function isAllowedPinDigits(value: number): boolean;
 
+/**
+ * Which WebAuthn ceremony {@link usePasskeyCeremony} drives.
+ *
+ * `Login` runs a usernameless/discoverable assertion
+ * (`navigator.credentials.get`) from the login surface; `Register` runs an
+ * attestation (`navigator.credentials.create`) from an authenticated settings
+ * surface. The mode selects the `/bff/passkey/{login,register}/*` endpoint pair
+ * and the matching redirect fallback.
+ */
+declare const enum PasskeyCeremonyMode {
+    /** Assertion ceremony — sign in with an existing passkey. */
+    Login = "login",
+    /** Attestation ceremony — add a passkey to the signed-in account. */
+    Register = "register"
+}
+
+/**
+ * The lifecycle state of an in-page passkey ceremony.
+ *
+ * `Idle` before the user acts; `Running` while options are fetched, the
+ * authenticator prompts, and the assertion/attestation is verified; `Success`
+ * once the BFF confirms (a login has a session cookie set, a registration has a
+ * stored credential); `Error` on a genuine in-page failure (see
+ * {@link PasskeyErrorCode}). A redirect fallback (RP not configured / unsupported
+ * browser) navigates the page away, so the hook never lands in a terminal state
+ * for that path.
+ */
+declare const enum PasskeyCeremonyStatus {
+    /** No ceremony has started. */
+    Idle = "idle",
+    /** A ceremony is in flight (fetch → authenticator → verify). */
+    Running = "running",
+    /** The ceremony completed and the BFF confirmed it. */
+    Success = "success",
+    /** The ceremony failed in-page (cancelled or failed). */
+    Error = "error"
+}
+
 /**
  * Navigation helpers for the passkey (WebAuthn) BFF endpoints.
  *
@@ -1700,6 +1750,44 @@ declare function readPasskeyError(): PasskeyErrorCode | null;
  */
 declare function readPasskeyRegistered(): boolean;
 
+/** Options for {@link usePasskeyCeremony}. */
+interface UsePasskeyCeremonyOptions {
+    /** Which ceremony to run — login (assertion) or register (attestation). */
+    mode: PasskeyCeremonyMode;
+    /**
+     * Relative app path used two ways: the redirect fallback returns here, and (for
+     * login) a successful in-page ceremony navigates here unless `onSuccess` is set.
+     */
+    returnUrl: string;
+    /**
+     * Called on a successful in-page ceremony. For login it receives the signed-in
+     * `BffUser`; for register it receives `undefined`. When omitted, a login
+     * navigates to `returnUrl` and a register just resolves to `Success`.
+     */
+    onSuccess?: (user: BffUser | undefined) => void;
+}
+/** The state + controls {@link usePasskeyCeremony} returns. */
+interface UsePasskeyCeremonyResult {
+    /** Current lifecycle state. */
+    status: PasskeyCeremonyStatus;
+    /** The in-page error code, or `null`. */
+    error: PasskeyErrorCode | null;
+    /** `true` when the browser can run the in-page ceremony (else it redirects). */
+    isSupported: boolean;
+    /** Start the ceremony (or redirect-fallback when the RP is off / unsupported). */
+    start: () => void;
+    /**
+     * Hand off to the legacy Keycloak redirect explicitly. Wired to the "try
+     * another way" affordance a surface shows after an in-page error — the escape
+     * hatch for a credential enrolled only in Keycloak (invisible to the in-page
+     * RP store), which the in-page ceremony cannot use.
+     */
+    fallbackToRedirect: () => void;
+    /** Clear a terminal state so the affordance can be retried. */
+    reset: () => void;
+}
+declare function usePasskeyCeremony(optionsArg: UsePasskeyCeremonyOptions): UsePasskeyCeremonyResult;
+
 /**
  * Device-local cache of the user's preferred login method (unified-login D5).
  *
@@ -1906,4 +1994,4 @@ declare function validatePasswordPolicy(password: string): PasswordPolicyError[]
 /** `true` when the password satisfies every policy rule. */
 declare function isPasswordValid(password: string): boolean;
 
-export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, 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_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_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, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, 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 UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };
+export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, 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_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_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, PasskeyCeremonyMode, PasskeyCeremonyStatus, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, 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 UsePasskeyCeremonyOptions, type UsePasskeyCeremonyResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePasskeyCeremony, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };