@dloizides/auth-web 1.6.0 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # 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
+cross-dashboard nav. No breaking changes; every 1.6.x export is unchanged.
+
+### Added
+
+- **`resolveAccessibleRoutes(user, table)`** — the multi-role companion to
+  `resolvePostLoginRoute`. Returns the full, ordered list of `RoleRoute` entries
+  the user's role-set unlocks (not just the top one), reusing the same
+  `collectUserRoles` reader and `RoleRouteTable`. Table (priority) order is
+  preserved; the table `fallback` is never included; a role-less user gets `[]`.
+  Pure and app-agnostic — an app renders the result as a cross-dashboard nav.
+- **`RoleRoute.labelKey?`** — optional translation key carried per route so a
+  consuming app can render a localized label per accessible dashboard. Ignored
+  by `resolvePostLoginRoute`; the package stays i18n-agnostic (carries the key,
+  the app resolves it).
+
 ## 1.3.0 (2026-05-31)
 
 Additive release for the auth-UX reuse roll-out (feature-reuse-roadmap #1).

package/dist/index.d.mts

@@ -1022,16 +1022,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 +1053,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 {
@@ -1644,6 +1648,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 +1742,37 @@ 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;
+    /** 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).
  *
@@ -1815,6 +1888,14 @@ interface RoleRoute {
     role: string;
     /** The route/path to send a user holding that role to. */
     route: string;
+    /**
+     * Optional translation key for a human label of this route — consumed by the
+     * multi-role dashboard nav (`resolveAccessibleRoutes`) so an app can render a
+     * localized link per accessible dashboard. Ignored by `resolvePostLoginRoute`
+     * (landing only cares about the path). The package stays i18n-agnostic: it
+     * carries the key, the app resolves it.
+     */
+    labelKey?: string;
 }
 /** An app-supplied, ordered role-routing table. */
 interface RoleRouteTable {
@@ -1844,6 +1925,15 @@ declare function collectUserRoles(user: BffUser): string[];
  */
 declare function resolvePostLoginRoute(user: BffUser, table: RoleRouteTable): string | null;
 
+/**
+ * Resolve every route in `table` whose role the user holds, in table
+ * (priority) order.
+ *
+ * @returns the matching `RoleRoute` entries (each carrying its optional
+ *   `labelKey`), or an empty array when the user holds none of the roles.
+ */
+declare function resolveAccessibleRoutes(user: BffUser, table: RoleRouteTable): RoleRoute[];
+
 /**
  * The discrete ways a password can fail the shared client-side policy.
  *
@@ -1889,4 +1979,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, 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

@@ -1022,16 +1022,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 +1053,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 {
@@ -1644,6 +1648,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 +1742,37 @@ 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;
+    /** 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).
  *
@@ -1815,6 +1888,14 @@ interface RoleRoute {
     role: string;
     /** The route/path to send a user holding that role to. */
     route: string;
+    /**
+     * Optional translation key for a human label of this route — consumed by the
+     * multi-role dashboard nav (`resolveAccessibleRoutes`) so an app can render a
+     * localized link per accessible dashboard. Ignored by `resolvePostLoginRoute`
+     * (landing only cares about the path). The package stays i18n-agnostic: it
+     * carries the key, the app resolves it.
+     */
+    labelKey?: string;
 }
 /** An app-supplied, ordered role-routing table. */
 interface RoleRouteTable {
@@ -1844,6 +1925,15 @@ declare function collectUserRoles(user: BffUser): string[];
  */
 declare function resolvePostLoginRoute(user: BffUser, table: RoleRouteTable): string | null;
 
+/**
+ * Resolve every route in `table` whose role the user holds, in table
+ * (priority) order.
+ *
+ * @returns the matching `RoleRoute` entries (each carrying its optional
+ *   `labelKey`), or an empty array when the user holds none of the roles.
+ */
+declare function resolveAccessibleRoutes(user: BffUser, table: RoleRouteTable): RoleRoute[];
+
 /**
  * The discrete ways a password can fail the shared client-side policy.
  *
@@ -1889,4 +1979,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, 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 };