@authowl/react 0.24.4 → 0.25.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { AuthConfig, Locale, AuthOwlClient, PublicConfig, ConsentStatus, OrganizationInvitationDetails, OrganizationDetails, OrganizationMembership, HasParams, AuthUser, AuthClientError, InvitationRecipientHint, SessionState, Organization, AuthOwlErrorCode, LastUsedSignInMethod } from '@authowl/core';
+import { AuthConfig, Locale, AuthOwlClient, PublicConfig, ConsentStatus, OrganizationInvitationDetails, OrganizationDetails, OrganizationMembership, HasParams, AuthUser, AuthClientError, InvitationRecipientHint, SessionState, AuthActionResult, Organization, AuthOwlErrorCode, LastUsedSignInMethod } from '@authowl/core';
 export { AuthOwlError, AuthPasskey, ConsentStatus, HasParams, InvalidKeyError, Organization, OrganizationDetails, OrganizationInvitation, OrganizationMember, OrganizationMemberWithUser, OrganizationMembership, OrganizationRoleSummary, OrganizationTeam, OrganizationTeamMember, OrganizationUserInvitation, PublicConfig, RateLimitedError, createMembershipHas, membershipHas, membershipHasPermission, membershipHasTeam } from '@authowl/core';
 
 type Appearance = {
@@ -508,9 +508,14 @@ type BackupCodesManagerProps = {
 };
 /**
  * Backup-codes management (B.5d): regenerate the signed-in user's single-use
- * backup codes (password-confirmed; the previous set stops working) and show
- * the new set ONCE. Renders nothing for users without 2FA enrolled - mount it
- * unconditionally in an account/security page alongside <MFAEnrollment/>.
+ * backup codes and show the new set ONCE. Renders nothing for users without 2FA
+ * enrolled - mount it unconditionally in an account/security page alongside
+ * <MFAEnrollment/>.
+ *
+ * Reissuing codes retires the old set, so the server treats it as a weakening
+ * action and can demand a second-factor proof on top of the password. That
+ * arrives as a code prompt and the request finishes on its own - see
+ * {@link useStepUpAction}.
  */
 declare function BackupCodesManager({ title }: BackupCodesManagerProps): React.JSX.Element | null;
 
@@ -673,22 +678,179 @@ type MFAEnrollmentProps = {
  */
 declare function MFAEnrollment({ onEnrolled, title }: MFAEnrollmentProps): React.JSX.Element;
 
+/** Everything `run` needs besides the action itself. */
+type SubmitActionOptions<T> = {
+    /** Generic, already-localized copy shown when the action fails. */
+    failure: string;
+    onSuccess?: (res: AuthActionResult<T>) => void | Promise<void>;
+    /**
+     * Override the default code-based error message for an endpoint-specific
+     * status (e.g. SSO's bare 404 = "no connection for this domain", which is
+     * not a global server code). Return a message to use, or null to fall back
+     * to the standard `useServerError` mapping.
+     */
+    mapError?: (error: AuthClientError) => string | null;
+    /**
+     * Take over a failure entirely instead of rendering it. Return true when the
+     * caller has handled the error by swapping the UI (the second-factor step-up
+     * prompt is the case this exists for), and no message is surfaced. Runs
+     * before `mapError`, which only ever produces text.
+     */
+    intercept?: (error: AuthClientError) => boolean;
+    /**
+     * Keep `pending` true after a SUCCESSFUL action instead of resetting it -
+     * for redirect-out actions (SSO) where the browser navigates away, so the
+     * spinner persists through the navigation instead of flashing back to idle.
+     * Error and throw paths still reset. Only safe when success always navigates
+     * away; a success that stays on the page would leave a stuck spinner (which
+     * is why magic-link/OTP, whose success swaps a view in place, do NOT set it).
+     */
+    keepPendingOnSuccess?: boolean;
+};
+type UseSubmitActionResult = {
+    /** True while an action is in flight (drives disabled buttons / busy labels). */
+    pending: boolean;
+    /** The last surfaced error message, or null. */
+    error: string | null;
+    /** Set/clear the error directly (e.g. an initial load outside `run`). */
+    setError: (message: string | null) => void;
+    /**
+     * Run a client action and own the loading/error skeleton: clear the error, set
+     * pending, await the action, surface `res.error` (or the thrown message) as
+     * `failure`, and invoke `onSuccess` only on a clean result. Every sign-in
+     * surface differs only in its action and success branch, so this keeps that
+     * envelope in one place. Generic in the action's data type, so `onSuccess`
+     * receives a fully-typed `res` without a cast.
+     */
+    run: <T>(action: () => Promise<AuthActionResult<T> | null | undefined>, opts: SubmitActionOptions<T>) => Promise<void>;
+};
+
+/**
+ * The server code for "prove the second factor before weakening it".
+ *
+ * Raised by the endpoints that can weaken an enrolled account - today
+ * `/two-factor/disable` and `/two-factor/generate-backup-codes` - when the
+ * session has not proved a factor in the last five minutes. Knowing the
+ * password is deliberately not enough: social sign-in, inbound SSO and a
+ * trusted device all mint a fresh session without ever running the challenge,
+ * so password-only would have voided the promise the second factor exists to
+ * make.
+ *
+ * Signing in again is NOT the remedy and must never be offered as one. A
+ * trusted device skips the challenge, so a second sign-in mints another
+ * unstamped session and the next attempt fails identically - an infinite
+ * bounce. The only way through is a code.
+ */
+declare const SECOND_FACTOR_REQUIRED = "SECOND_FACTOR_REQUIRED";
+type UseStepUpActionResult = Omit<UseSubmitActionResult, 'run'> & {
+    /**
+     * Run an action the server may gate behind a fresh second-factor proof.
+     *
+     * On `SECOND_FACTOR_REQUIRED` the attempt is PARKED rather than surfaced as an
+     * error, and `stepUpRequired` flips so the caller can render the code prompt.
+     * Every other failure behaves exactly as `useSubmitAction`'s `run`.
+     *
+     * ONE ATTEMPT AT A TIME per hook instance. The returned promise settles when
+     * the attempt is parked, NOT when the action finishes - so do not await it to
+     * mean "this completed"; use `onSuccess`. A second action gated while one is
+     * already parked is refused as an ordinary error rather than silently taking
+     * the first one's place. Call the hook once per action if you drive two.
+     */
+    run: UseSubmitActionResult['run'];
+    /** True while the server is waiting for a code before it will run the action. */
+    stepUpRequired: boolean;
+    /**
+     * Replay the parked attempt. Call this once a code has been accepted; the
+     * original inputs (password, options) are replayed exactly as submitted, so
+     * the user never retypes anything.
+     */
+    resume: () => void;
+    /** Abandon the parked attempt and leave step-up. */
+    cancel: () => void;
+};
+/**
+ * The park-prompt-replay envelope for a second-factor step-up.
+ *
+ * Wrap any action the server may gate behind a fresh proof, render
+ * `<MFAChallenge variant="step-up" onVerified={resume} />` while
+ * `stepUpRequired`, and the original request finishes on its own.
+ *
+ * Both surfaces that can trip the gate need the identical three moves - catch
+ * the code, collect a factor, re-run the untouched attempt - so it lives here
+ * rather than twice. The gate is reactive by necessity: nothing on the client
+ * can see whether this session carries a fresh assertion, so the only honest
+ * design is to try, and prompt when the server says to. A user who just cleared
+ * a challenge at sign-in therefore never sees the prompt at all.
+ */
+declare function useStepUpAction(): UseStepUpActionResult;
+
+type PasskeyOfferGateProps = {
+    /** The signed-in application. Rendered untouched in every other state. */
+    children: React.ReactNode;
+    /** Optional heading override, matching the other gates. */
+    title?: string;
+};
+/**
+ * Offers a passkey once, just after a user starts a signed-in session having
+ * arrived by some other method. Wrap your signed-in app, next to
+ * <ConsentGate/> and <MFARequiredGate/>; it is free to wrap unconditionally.
+ *
+ * WHY A GATE AND NOT A STEP INSIDE <SignIn/>. The natural-looking design - show
+ * the offer between a successful sign-in and the handoff - cannot work in the
+ * documented embed. `<SignedOut>` unmounts `<SignIn/>` on the very store update
+ * that makes the session usable, so by the time an offer could be rendered the
+ * component that would render it is gone: the prompt never appears and the
+ * sign-in handoff never completes. There is no post-success moment inside a
+ * sign-in form. There is one here, on the side that survives.
+ *
+ * It also puts the checks where the answers exist. A sign-in form asks
+ * "is this user 2FA-enrolled?" before any user is loaded, and gets `undefined` -
+ * which reads as "no" and defeats the check entirely. On this side the user is
+ * real. {@link usePasskeyOffer} owns which checks those are and why.
+ *
+ * NEVER BLOCKS. Children render immediately and keep rendering while the checks
+ * run; the offer replaces them only on confirmed evidence. This is an optional
+ * convenience, so every uncertainty - config still loading, the passkey list
+ * unreadable, storage refusing - resolves to "show the app". Blocking would add
+ * another bootstrap blank-flash to a surface that already has one.
+ */
+declare function PasskeyOfferGate({ children, title }: PasskeyOfferGateProps): React.JSX.Element;
+
 type MFAChallengeProps = {
-    /** Called once the challenge clears and a session is issued. */
+    /** Called once the factor is accepted (a session is issued on `sign-in`). */
     onVerified?: () => void | Promise<void>;
     /**
      * Allow the "trust this device" option when the project's posture permits it.
-     * The server capability always wins over this presentation override.
+     * The server capability always wins over this presentation override. Ignored
+     * on `step-up`, where the server has no trust to grant.
      */
     allowTrustDevice?: boolean;
+    /**
+     * What this prompt is FOR, which decides its copy and whether device trust is
+     * on offer:
+     *
+     *  - `sign-in`   the session is withheld until the factor clears. The default.
+     *  - `step-up`   the user is ALREADY signed in and is re-proving the factor to
+     *                authorize a change that would weaken it. The server's
+     *                full-session branch returns the existing token and creates no
+     *                session, so nothing here may read as signing in - and it
+     *                cannot mint a trust cookie, so the checkbox is not offered.
+     */
+    variant?: 'sign-in' | 'step-up';
+    /** Abandon the prompt. Rendered as a Cancel control when provided. */
+    onCancel?: () => void;
 };
 /**
- * The sign-in second-factor prompt: a user with 2FA enrolled gets no session until
- * they clear this. Accepts a TOTP code or, as a fallback, a single-use backup code.
- * Rendered automatically by <SignIn/> when the server withholds the session behind
- * a 2FA challenge; also usable standalone.
+ * The second-factor prompt. Accepts a TOTP code or, as a fallback, a single-use
+ * backup code or an emailed code where the project's posture permits one.
+ *
+ * Serves two moments, which `variant` selects between. At `sign-in` a user with
+ * 2FA enrolled gets no session until they clear this, and <SignIn/> renders it
+ * automatically when the server withholds one. At `step-up` an already
+ * signed-in user re-proves the factor to authorize a change that would weaken
+ * it - the same three factors, different copy, and no device trust on offer.
  */
-declare function MFAChallenge({ onVerified, allowTrustDevice }: MFAChallengeProps): React.JSX.Element;
+declare function MFAChallenge({ onVerified, allowTrustDevice, variant, onCancel, }: MFAChallengeProps): React.JSX.Element;
 
 type AuthOwlBadgeProps = {
     /** Override the link target (defaults to the AuthOwl site). */
@@ -968,4 +1130,4 @@ declare function GoogleOneTap({ disabled, nonce, autoSelect, cancelOnTapOutside,
  */
 declare function useLastUsedSignInMethod(): LastUsedSignInMethod | null;
 
-export { type Appearance, AuthLoaded, type AuthLoadedProps, AuthLoading, type AuthLoadingProps, AuthOwlBadge, type AuthOwlBadgeProps, AuthOwlBranding, type AuthOwlBrandingProps, AuthOwlProvider, type AuthOwlProviderProps, type AutofillHost, BackupCodesManager, type BackupCodesManagerProps, Bidi, type ConfigState, ConsentDocLinks, type ConsentDocLinksProps, ConsentGate, type ConsentGateProps, CreateOrganization, type CreateOrganizationProps, DEFAULT_BRAND_COLOR, EmailOtpForm, type EmailOtpFormProps, ForgotPassword, type ForgotPasswordProps, GoogleOneTap, type GoogleOneTapDismissReason, type GoogleOneTapError, type GoogleOneTapErrorCode, type GoogleOneTapProps, type GoogleOneTapSkipReason, InvitationPrompt, type InvitationPromptStatus, KNOWN_METHODS, type KnownMethod, MFAChallenge, type MFAChallengeProps, MFAEnrollment, type MFAEnrollmentProps, MFARequiredGate, type MFARequiredGateProps, MagicLinkForm, type MagicLinkFormProps, OrganizationList, type OrganizationListProps, OrganizationProfile, type OrganizationProfileProps, type OrganizationProfileSection, OrganizationSwitcher, type OrganizationSwitcherProps, PasskeyButton, type PasskeyButtonProps, PasskeyManager, type PasskeyManagerProps, PhoneOTP, type PhoneOTPProps, PrivacyCenter, type PrivacyCenterProps, Protect, type ProtectProps, ResetPassword, type ResetPasswordProps, SignIn, type SignInPlan, type SignInProps, SignOutButton, type SignOutButtonProps, SignUp, type SignUpProps, SignedIn, type SignedInProps, SignedOut, type SignedOutProps, SocialButtons, type SocialButtonsProps, Spinner, type UseAccountResult, type UseAuthResult, type UseConsentResult, type UseEmailVerificationResult, type UseMFAResult, type UseOrganizationInvitationResult, type UseOrganizationResult, type UsePasskeysResult, type UsePasswordResetResult, type UsePrivacyResult, type UsePublicConfigResult, type UseSignInResult, type UseSignOutResult, type UseSignUpResult, type UseUserResult, type UseWaitlistResult, UserButton, UserProfile, type UserProfileProps, type UserProfileSection, VerificationPending, type VerificationPendingProps, VerifyEmail, type VerifyEmailProps, Waitlist, type WaitlistProps, emailAutocomplete, resolveSignInMethods, useAccount, useAuth, useAuthClient, useAuthOwlContext, useConsent, useEmailVerification, useInvitationRecipientHint, useLastUsedSignInMethod, useLocale, useMFA, useOrganization, useOrganizationInvitation, usePasskeys, usePasswordReset, usePrivacy, usePublicConfig, useSession, useSignIn, useSignOut, useSignUp, useUser, useWaitlist };
+export { type Appearance, AuthLoaded, type AuthLoadedProps, AuthLoading, type AuthLoadingProps, AuthOwlBadge, type AuthOwlBadgeProps, AuthOwlBranding, type AuthOwlBrandingProps, AuthOwlProvider, type AuthOwlProviderProps, type AutofillHost, BackupCodesManager, type BackupCodesManagerProps, Bidi, type ConfigState, ConsentDocLinks, type ConsentDocLinksProps, ConsentGate, type ConsentGateProps, CreateOrganization, type CreateOrganizationProps, DEFAULT_BRAND_COLOR, EmailOtpForm, type EmailOtpFormProps, ForgotPassword, type ForgotPasswordProps, GoogleOneTap, type GoogleOneTapDismissReason, type GoogleOneTapError, type GoogleOneTapErrorCode, type GoogleOneTapProps, type GoogleOneTapSkipReason, InvitationPrompt, type InvitationPromptStatus, KNOWN_METHODS, type KnownMethod, MFAChallenge, type MFAChallengeProps, MFAEnrollment, type MFAEnrollmentProps, MFARequiredGate, type MFARequiredGateProps, MagicLinkForm, type MagicLinkFormProps, OrganizationList, type OrganizationListProps, OrganizationProfile, type OrganizationProfileProps, type OrganizationProfileSection, OrganizationSwitcher, type OrganizationSwitcherProps, PasskeyButton, type PasskeyButtonProps, PasskeyManager, type PasskeyManagerProps, PasskeyOfferGate, type PasskeyOfferGateProps, PhoneOTP, type PhoneOTPProps, PrivacyCenter, type PrivacyCenterProps, Protect, type ProtectProps, ResetPassword, type ResetPasswordProps, SECOND_FACTOR_REQUIRED, SignIn, type SignInPlan, type SignInProps, SignOutButton, type SignOutButtonProps, SignUp, type SignUpProps, SignedIn, type SignedInProps, SignedOut, type SignedOutProps, SocialButtons, type SocialButtonsProps, Spinner, type UseAccountResult, type UseAuthResult, type UseConsentResult, type UseEmailVerificationResult, type UseMFAResult, type UseOrganizationInvitationResult, type UseOrganizationResult, type UsePasskeysResult, type UsePasswordResetResult, type UsePrivacyResult, type UsePublicConfigResult, type UseSignInResult, type UseSignOutResult, type UseSignUpResult, type UseStepUpActionResult, type UseUserResult, type UseWaitlistResult, UserButton, UserProfile, type UserProfileProps, type UserProfileSection, VerificationPending, type VerificationPendingProps, VerifyEmail, type VerifyEmailProps, Waitlist, type WaitlistProps, emailAutocomplete, resolveSignInMethods, useAccount, useAuth, useAuthClient, useAuthOwlContext, useConsent, useEmailVerification, useInvitationRecipientHint, useLastUsedSignInMethod, useLocale, useMFA, useOrganization, useOrganizationInvitation, usePasskeys, usePasswordReset, usePrivacy, usePublicConfig, useSession, useSignIn, useSignOut, useSignUp, useStepUpAction, useUser, useWaitlist };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { AuthConfig, Locale, AuthOwlClient, PublicConfig, ConsentStatus, OrganizationInvitationDetails, OrganizationDetails, OrganizationMembership, HasParams, AuthUser, AuthClientError, InvitationRecipientHint, SessionState, Organization, AuthOwlErrorCode, LastUsedSignInMethod } from '@authowl/core';
+import { AuthConfig, Locale, AuthOwlClient, PublicConfig, ConsentStatus, OrganizationInvitationDetails, OrganizationDetails, OrganizationMembership, HasParams, AuthUser, AuthClientError, InvitationRecipientHint, SessionState, AuthActionResult, Organization, AuthOwlErrorCode, LastUsedSignInMethod } from '@authowl/core';
 export { AuthOwlError, AuthPasskey, ConsentStatus, HasParams, InvalidKeyError, Organization, OrganizationDetails, OrganizationInvitation, OrganizationMember, OrganizationMemberWithUser, OrganizationMembership, OrganizationRoleSummary, OrganizationTeam, OrganizationTeamMember, OrganizationUserInvitation, PublicConfig, RateLimitedError, createMembershipHas, membershipHas, membershipHasPermission, membershipHasTeam } from '@authowl/core';
 
 type Appearance = {
@@ -508,9 +508,14 @@ type BackupCodesManagerProps = {
 };
 /**
  * Backup-codes management (B.5d): regenerate the signed-in user's single-use
- * backup codes (password-confirmed; the previous set stops working) and show
- * the new set ONCE. Renders nothing for users without 2FA enrolled - mount it
- * unconditionally in an account/security page alongside <MFAEnrollment/>.
+ * backup codes and show the new set ONCE. Renders nothing for users without 2FA
+ * enrolled - mount it unconditionally in an account/security page alongside
+ * <MFAEnrollment/>.
+ *
+ * Reissuing codes retires the old set, so the server treats it as a weakening
+ * action and can demand a second-factor proof on top of the password. That
+ * arrives as a code prompt and the request finishes on its own - see
+ * {@link useStepUpAction}.
  */
 declare function BackupCodesManager({ title }: BackupCodesManagerProps): React.JSX.Element | null;
 
@@ -673,22 +678,179 @@ type MFAEnrollmentProps = {
  */
 declare function MFAEnrollment({ onEnrolled, title }: MFAEnrollmentProps): React.JSX.Element;
 
+/** Everything `run` needs besides the action itself. */
+type SubmitActionOptions<T> = {
+    /** Generic, already-localized copy shown when the action fails. */
+    failure: string;
+    onSuccess?: (res: AuthActionResult<T>) => void | Promise<void>;
+    /**
+     * Override the default code-based error message for an endpoint-specific
+     * status (e.g. SSO's bare 404 = "no connection for this domain", which is
+     * not a global server code). Return a message to use, or null to fall back
+     * to the standard `useServerError` mapping.
+     */
+    mapError?: (error: AuthClientError) => string | null;
+    /**
+     * Take over a failure entirely instead of rendering it. Return true when the
+     * caller has handled the error by swapping the UI (the second-factor step-up
+     * prompt is the case this exists for), and no message is surfaced. Runs
+     * before `mapError`, which only ever produces text.
+     */
+    intercept?: (error: AuthClientError) => boolean;
+    /**
+     * Keep `pending` true after a SUCCESSFUL action instead of resetting it -
+     * for redirect-out actions (SSO) where the browser navigates away, so the
+     * spinner persists through the navigation instead of flashing back to idle.
+     * Error and throw paths still reset. Only safe when success always navigates
+     * away; a success that stays on the page would leave a stuck spinner (which
+     * is why magic-link/OTP, whose success swaps a view in place, do NOT set it).
+     */
+    keepPendingOnSuccess?: boolean;
+};
+type UseSubmitActionResult = {
+    /** True while an action is in flight (drives disabled buttons / busy labels). */
+    pending: boolean;
+    /** The last surfaced error message, or null. */
+    error: string | null;
+    /** Set/clear the error directly (e.g. an initial load outside `run`). */
+    setError: (message: string | null) => void;
+    /**
+     * Run a client action and own the loading/error skeleton: clear the error, set
+     * pending, await the action, surface `res.error` (or the thrown message) as
+     * `failure`, and invoke `onSuccess` only on a clean result. Every sign-in
+     * surface differs only in its action and success branch, so this keeps that
+     * envelope in one place. Generic in the action's data type, so `onSuccess`
+     * receives a fully-typed `res` without a cast.
+     */
+    run: <T>(action: () => Promise<AuthActionResult<T> | null | undefined>, opts: SubmitActionOptions<T>) => Promise<void>;
+};
+
+/**
+ * The server code for "prove the second factor before weakening it".
+ *
+ * Raised by the endpoints that can weaken an enrolled account - today
+ * `/two-factor/disable` and `/two-factor/generate-backup-codes` - when the
+ * session has not proved a factor in the last five minutes. Knowing the
+ * password is deliberately not enough: social sign-in, inbound SSO and a
+ * trusted device all mint a fresh session without ever running the challenge,
+ * so password-only would have voided the promise the second factor exists to
+ * make.
+ *
+ * Signing in again is NOT the remedy and must never be offered as one. A
+ * trusted device skips the challenge, so a second sign-in mints another
+ * unstamped session and the next attempt fails identically - an infinite
+ * bounce. The only way through is a code.
+ */
+declare const SECOND_FACTOR_REQUIRED = "SECOND_FACTOR_REQUIRED";
+type UseStepUpActionResult = Omit<UseSubmitActionResult, 'run'> & {
+    /**
+     * Run an action the server may gate behind a fresh second-factor proof.
+     *
+     * On `SECOND_FACTOR_REQUIRED` the attempt is PARKED rather than surfaced as an
+     * error, and `stepUpRequired` flips so the caller can render the code prompt.
+     * Every other failure behaves exactly as `useSubmitAction`'s `run`.
+     *
+     * ONE ATTEMPT AT A TIME per hook instance. The returned promise settles when
+     * the attempt is parked, NOT when the action finishes - so do not await it to
+     * mean "this completed"; use `onSuccess`. A second action gated while one is
+     * already parked is refused as an ordinary error rather than silently taking
+     * the first one's place. Call the hook once per action if you drive two.
+     */
+    run: UseSubmitActionResult['run'];
+    /** True while the server is waiting for a code before it will run the action. */
+    stepUpRequired: boolean;
+    /**
+     * Replay the parked attempt. Call this once a code has been accepted; the
+     * original inputs (password, options) are replayed exactly as submitted, so
+     * the user never retypes anything.
+     */
+    resume: () => void;
+    /** Abandon the parked attempt and leave step-up. */
+    cancel: () => void;
+};
+/**
+ * The park-prompt-replay envelope for a second-factor step-up.
+ *
+ * Wrap any action the server may gate behind a fresh proof, render
+ * `<MFAChallenge variant="step-up" onVerified={resume} />` while
+ * `stepUpRequired`, and the original request finishes on its own.
+ *
+ * Both surfaces that can trip the gate need the identical three moves - catch
+ * the code, collect a factor, re-run the untouched attempt - so it lives here
+ * rather than twice. The gate is reactive by necessity: nothing on the client
+ * can see whether this session carries a fresh assertion, so the only honest
+ * design is to try, and prompt when the server says to. A user who just cleared
+ * a challenge at sign-in therefore never sees the prompt at all.
+ */
+declare function useStepUpAction(): UseStepUpActionResult;
+
+type PasskeyOfferGateProps = {
+    /** The signed-in application. Rendered untouched in every other state. */
+    children: React.ReactNode;
+    /** Optional heading override, matching the other gates. */
+    title?: string;
+};
+/**
+ * Offers a passkey once, just after a user starts a signed-in session having
+ * arrived by some other method. Wrap your signed-in app, next to
+ * <ConsentGate/> and <MFARequiredGate/>; it is free to wrap unconditionally.
+ *
+ * WHY A GATE AND NOT A STEP INSIDE <SignIn/>. The natural-looking design - show
+ * the offer between a successful sign-in and the handoff - cannot work in the
+ * documented embed. `<SignedOut>` unmounts `<SignIn/>` on the very store update
+ * that makes the session usable, so by the time an offer could be rendered the
+ * component that would render it is gone: the prompt never appears and the
+ * sign-in handoff never completes. There is no post-success moment inside a
+ * sign-in form. There is one here, on the side that survives.
+ *
+ * It also puts the checks where the answers exist. A sign-in form asks
+ * "is this user 2FA-enrolled?" before any user is loaded, and gets `undefined` -
+ * which reads as "no" and defeats the check entirely. On this side the user is
+ * real. {@link usePasskeyOffer} owns which checks those are and why.
+ *
+ * NEVER BLOCKS. Children render immediately and keep rendering while the checks
+ * run; the offer replaces them only on confirmed evidence. This is an optional
+ * convenience, so every uncertainty - config still loading, the passkey list
+ * unreadable, storage refusing - resolves to "show the app". Blocking would add
+ * another bootstrap blank-flash to a surface that already has one.
+ */
+declare function PasskeyOfferGate({ children, title }: PasskeyOfferGateProps): React.JSX.Element;
+
 type MFAChallengeProps = {
-    /** Called once the challenge clears and a session is issued. */
+    /** Called once the factor is accepted (a session is issued on `sign-in`). */
     onVerified?: () => void | Promise<void>;
     /**
      * Allow the "trust this device" option when the project's posture permits it.
-     * The server capability always wins over this presentation override.
+     * The server capability always wins over this presentation override. Ignored
+     * on `step-up`, where the server has no trust to grant.
      */
     allowTrustDevice?: boolean;
+    /**
+     * What this prompt is FOR, which decides its copy and whether device trust is
+     * on offer:
+     *
+     *  - `sign-in`   the session is withheld until the factor clears. The default.
+     *  - `step-up`   the user is ALREADY signed in and is re-proving the factor to
+     *                authorize a change that would weaken it. The server's
+     *                full-session branch returns the existing token and creates no
+     *                session, so nothing here may read as signing in - and it
+     *                cannot mint a trust cookie, so the checkbox is not offered.
+     */
+    variant?: 'sign-in' | 'step-up';
+    /** Abandon the prompt. Rendered as a Cancel control when provided. */
+    onCancel?: () => void;
 };
 /**
- * The sign-in second-factor prompt: a user with 2FA enrolled gets no session until
- * they clear this. Accepts a TOTP code or, as a fallback, a single-use backup code.
- * Rendered automatically by <SignIn/> when the server withholds the session behind
- * a 2FA challenge; also usable standalone.
+ * The second-factor prompt. Accepts a TOTP code or, as a fallback, a single-use
+ * backup code or an emailed code where the project's posture permits one.
+ *
+ * Serves two moments, which `variant` selects between. At `sign-in` a user with
+ * 2FA enrolled gets no session until they clear this, and <SignIn/> renders it
+ * automatically when the server withholds one. At `step-up` an already
+ * signed-in user re-proves the factor to authorize a change that would weaken
+ * it - the same three factors, different copy, and no device trust on offer.
  */
-declare function MFAChallenge({ onVerified, allowTrustDevice }: MFAChallengeProps): React.JSX.Element;
+declare function MFAChallenge({ onVerified, allowTrustDevice, variant, onCancel, }: MFAChallengeProps): React.JSX.Element;
 
 type AuthOwlBadgeProps = {
     /** Override the link target (defaults to the AuthOwl site). */
@@ -968,4 +1130,4 @@ declare function GoogleOneTap({ disabled, nonce, autoSelect, cancelOnTapOutside,
  */
 declare function useLastUsedSignInMethod(): LastUsedSignInMethod | null;
 
-export { type Appearance, AuthLoaded, type AuthLoadedProps, AuthLoading, type AuthLoadingProps, AuthOwlBadge, type AuthOwlBadgeProps, AuthOwlBranding, type AuthOwlBrandingProps, AuthOwlProvider, type AuthOwlProviderProps, type AutofillHost, BackupCodesManager, type BackupCodesManagerProps, Bidi, type ConfigState, ConsentDocLinks, type ConsentDocLinksProps, ConsentGate, type ConsentGateProps, CreateOrganization, type CreateOrganizationProps, DEFAULT_BRAND_COLOR, EmailOtpForm, type EmailOtpFormProps, ForgotPassword, type ForgotPasswordProps, GoogleOneTap, type GoogleOneTapDismissReason, type GoogleOneTapError, type GoogleOneTapErrorCode, type GoogleOneTapProps, type GoogleOneTapSkipReason, InvitationPrompt, type InvitationPromptStatus, KNOWN_METHODS, type KnownMethod, MFAChallenge, type MFAChallengeProps, MFAEnrollment, type MFAEnrollmentProps, MFARequiredGate, type MFARequiredGateProps, MagicLinkForm, type MagicLinkFormProps, OrganizationList, type OrganizationListProps, OrganizationProfile, type OrganizationProfileProps, type OrganizationProfileSection, OrganizationSwitcher, type OrganizationSwitcherProps, PasskeyButton, type PasskeyButtonProps, PasskeyManager, type PasskeyManagerProps, PhoneOTP, type PhoneOTPProps, PrivacyCenter, type PrivacyCenterProps, Protect, type ProtectProps, ResetPassword, type ResetPasswordProps, SignIn, type SignInPlan, type SignInProps, SignOutButton, type SignOutButtonProps, SignUp, type SignUpProps, SignedIn, type SignedInProps, SignedOut, type SignedOutProps, SocialButtons, type SocialButtonsProps, Spinner, type UseAccountResult, type UseAuthResult, type UseConsentResult, type UseEmailVerificationResult, type UseMFAResult, type UseOrganizationInvitationResult, type UseOrganizationResult, type UsePasskeysResult, type UsePasswordResetResult, type UsePrivacyResult, type UsePublicConfigResult, type UseSignInResult, type UseSignOutResult, type UseSignUpResult, type UseUserResult, type UseWaitlistResult, UserButton, UserProfile, type UserProfileProps, type UserProfileSection, VerificationPending, type VerificationPendingProps, VerifyEmail, type VerifyEmailProps, Waitlist, type WaitlistProps, emailAutocomplete, resolveSignInMethods, useAccount, useAuth, useAuthClient, useAuthOwlContext, useConsent, useEmailVerification, useInvitationRecipientHint, useLastUsedSignInMethod, useLocale, useMFA, useOrganization, useOrganizationInvitation, usePasskeys, usePasswordReset, usePrivacy, usePublicConfig, useSession, useSignIn, useSignOut, useSignUp, useUser, useWaitlist };
+export { type Appearance, AuthLoaded, type AuthLoadedProps, AuthLoading, type AuthLoadingProps, AuthOwlBadge, type AuthOwlBadgeProps, AuthOwlBranding, type AuthOwlBrandingProps, AuthOwlProvider, type AuthOwlProviderProps, type AutofillHost, BackupCodesManager, type BackupCodesManagerProps, Bidi, type ConfigState, ConsentDocLinks, type ConsentDocLinksProps, ConsentGate, type ConsentGateProps, CreateOrganization, type CreateOrganizationProps, DEFAULT_BRAND_COLOR, EmailOtpForm, type EmailOtpFormProps, ForgotPassword, type ForgotPasswordProps, GoogleOneTap, type GoogleOneTapDismissReason, type GoogleOneTapError, type GoogleOneTapErrorCode, type GoogleOneTapProps, type GoogleOneTapSkipReason, InvitationPrompt, type InvitationPromptStatus, KNOWN_METHODS, type KnownMethod, MFAChallenge, type MFAChallengeProps, MFAEnrollment, type MFAEnrollmentProps, MFARequiredGate, type MFARequiredGateProps, MagicLinkForm, type MagicLinkFormProps, OrganizationList, type OrganizationListProps, OrganizationProfile, type OrganizationProfileProps, type OrganizationProfileSection, OrganizationSwitcher, type OrganizationSwitcherProps, PasskeyButton, type PasskeyButtonProps, PasskeyManager, type PasskeyManagerProps, PasskeyOfferGate, type PasskeyOfferGateProps, PhoneOTP, type PhoneOTPProps, PrivacyCenter, type PrivacyCenterProps, Protect, type ProtectProps, ResetPassword, type ResetPasswordProps, SECOND_FACTOR_REQUIRED, SignIn, type SignInPlan, type SignInProps, SignOutButton, type SignOutButtonProps, SignUp, type SignUpProps, SignedIn, type SignedInProps, SignedOut, type SignedOutProps, SocialButtons, type SocialButtonsProps, Spinner, type UseAccountResult, type UseAuthResult, type UseConsentResult, type UseEmailVerificationResult, type UseMFAResult, type UseOrganizationInvitationResult, type UseOrganizationResult, type UsePasskeysResult, type UsePasswordResetResult, type UsePrivacyResult, type UsePublicConfigResult, type UseSignInResult, type UseSignOutResult, type UseSignUpResult, type UseStepUpActionResult, type UseUserResult, type UseWaitlistResult, UserButton, UserProfile, type UserProfileProps, type UserProfileSection, VerificationPending, type VerificationPendingProps, VerifyEmail, type VerifyEmailProps, Waitlist, type WaitlistProps, emailAutocomplete, resolveSignInMethods, useAccount, useAuth, useAuthClient, useAuthOwlContext, useConsent, useEmailVerification, useInvitationRecipientHint, useLastUsedSignInMethod, useLocale, useMFA, useOrganization, useOrganizationInvitation, usePasskeys, usePasswordReset, usePrivacy, usePublicConfig, useSession, useSignIn, useSignOut, useSignUp, useStepUpAction, useUser, useWaitlist };