npm - @authowl/react - Versions diffs - 0.14.0 - Mend

@authowl/react 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,825 @@
+import * as React from 'react';
+import { AuthConfig, Locale, AuthOwlClient, PublicConfig, ConsentStatus, OrganizationDetails, OrganizationMembership, HasParams, AuthUser, AuthClientError, SessionState, Organization, AuthOwlErrorCode } from '@authowl/core';
+export { AuthOwlError, AuthPasskey, ConsentStatus, HasParams, InvalidKeyError, Organization, OrganizationDetails, OrganizationInvitation, OrganizationMember, OrganizationMemberWithUser, OrganizationMembership, OrganizationRoleSummary, OrganizationTeam, OrganizationUserInvitation, PublicConfig, RateLimitedError, createMembershipHas, membershipHas, membershipHasPermission, membershipHasTeam } from '@authowl/core';
+type Appearance = {
+    theme?: 'light' | 'dark' | 'system';
+    /** Primary accent color (CSS color). Falls back to project branding. */
+    primaryColor?: string;
+};
+/** Loading state of the fetched public config. */
+type ConfigState = 'loading' | 'ready' | 'error';
+type Ctx = {
+    client: AuthOwlClient;
+    appearance: Appearance | undefined;
+    /** Project public config (methods, social providers, branding). */
+    config: PublicConfig | null;
+    configState: ConfigState;
+    /** Resolved component locale (drives every t() call and the dir attribute). */
+    locale: Locale;
+};
+type AuthOwlProviderProps = AuthConfig & {
+    appearance?: Appearance;
+    /**
+     * Component locale. `'en' | 'ar'` forces it; `'auto'` detects from the host
+     * page (`<html lang/dir>`, then `navigator.language`); omitted = the
+     * project's default from public-config ('en' until the config loads).
+     */
+    locale?: Locale | 'auto';
+    children: React.ReactNode;
+};
+declare function AuthOwlProvider({ publishableKey, apiUrl, fetch, appearance, locale: localeProp, children, }: AuthOwlProviderProps): React.JSX.Element;
+declare function useAuthOwlContext(): Ctx;
+/** The active component locale (resolved by <AuthOwlProvider>). */
+declare function useLocale(): "en" | "ar";
+/**
+ * Bidi-isolate an LTR value (email address, manual key, code) embedded in a
+ * possibly-RTL sentence, so punctuation and order render correctly.
+ */
+declare function Bidi({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * Brand accent derivation (audit P1-5).
+ *
+ * The operator picks ONE brand color in the AuthOwl dashboard. This module turns
+ * that single hex into the full set of accent tokens the drop-in forms and the
+ * hosted account portal need - a filled button that IS the brand color, a
+ * contrast-correct label on it, perceptually-darkened hover/active states that
+ * stay ON hue, and a readable link/ring variant - WITHOUT the old
+ * `color-mix(in srgb, primary 40%, black)` that collapsed chroma to mud
+ * (gold #F5B84C -> #624A1E).
+ *
+ * The math is OKLab/OKLCH (Bjorn Ottosson) so lightness moves are perceptual and
+ * hue+chroma are preserved; contrast is WCAG 2.x relative luminance. Everything
+ * here is pure, synchronous, dependency-free and SSR-safe - `deriveBrandRamp`
+ * runs during render on the server (the portal's ramp is in the SSR HTML, so the
+ * brand is correct at first paint with zero client listeners).
+ */
+/** The single default brand color for BOTH the SDK forms and the hosted portal
+ *  when an operator has not chosen one - the AuthOwl gold. Exported so the app
+ *  (hosted portal) can default to the exact same value; one source of truth. */
+declare const DEFAULT_BRAND_COLOR = "#F5B84C";
+declare function useAuthClient(): AuthOwlClient;
+type UseAccountResult = AuthOwlClient['account'];
+/** Signed-in account profile, credential, session, provider, and deletion actions. */
+declare function useAccount(): UseAccountResult;
+type UsePublicConfigResult = {
+    config: PublicConfig | null;
+    isLoading: boolean;
+    isError: boolean;
+};
+/** The project's fetched public config (enabled methods, social providers, branding). */
+declare function usePublicConfig(): UsePublicConfigResult;
+declare function useSession(): SessionState;
+type UseUserResult = {
+    /**
+     * Stays populated for a session held at required-MFA enrolment even though
+     * `isSignedIn` is false - <MFARequiredGate/>'s enrolment UI needs it.
+     * Gate app content on `isSignedIn`, not on `user`.
+     */
+    user: AuthUser | null;
+    isLoaded: boolean;
+    /** False for a session held at required-MFA enrolment (CONTRACTS §5). */
+    isSignedIn: boolean;
+    /** The signed-in-enough-to-enrol state: route to <MFARequiredGate/>. */
+    needsMfaEnrollment: boolean;
+    error: AuthClientError | null;
+};
+declare function useUser(): UseUserResult;
+type UseAuthResult = {
+    /** False while the session is still being fetched. */
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    /** The signed-in user's id, else null. Consumers key token freshness on it. */
+    userId: string | null;
+    /** Active organization id (when the organization plugin is in use), else null. */
+    orgId: string | null;
+    /**
+     * Clerk-compatible: mint a short-lived JWT for third-party backends
+     * (Convex/Supabase/Hasura). Requires the project's JWT issuer toggle.
+     * Resolves null when signed out. Named templates use
+     * `{ template: 'convex' }`; `forceRefresh` bypasses only the selected entry.
+     */
+    getToken: AuthOwlClient['getToken'];
+};
+/**
+ * Clerk-compatible auth snapshot + token minting. This is the hook
+ * `<ConvexProviderWithAuthOwl useAuth={useAuth}>` consumes - its shape mirrors
+ * what Clerk's `useAuth` provides to `ConvexProviderWithClerk`, so swapping
+ * providers is a one-line change.
+ */
+declare function useAuth(): UseAuthResult;
+type UseOrganizationResult = {
+    /** The active organization's full details (members + invitations), or null. */
+    organization: OrganizationDetails | null;
+    /** The active-org membership: canonical role + advisory permission claim, or null. */
+    membership: OrganizationMembership | null;
+    /**
+     * Team ids the member holds in the active organization, from the session claim.
+     * Empty when they hold none; empty also when the session predates teams, so treat
+     * it as "no proven teams" rather than proof of absence.
+     *
+     * Teams are pure grouping - membership grants nothing by itself.
+     */
+    teams: string[];
+    /** The member's active team within the active organization, or null. */
+    activeTeamId: string | null;
+    /**
+     * Clerk-style `has({ role?, permission?, teamId? })` bound to the active
+     * membership. PURE + advisory (reads the local session claim, never the server) -
+     * gate real authorization server-side over the verified token
+     * (`@authowl/next` `has()`).
+     */
+    has: (params: HasParams) => boolean;
+    /** `hasPermission({ permission })` bound to the active membership. Pure + advisory. */
+    hasPermission: (params: {
+        permission: string;
+    }) => boolean;
+    /** False until the session (and, when there is an active org, its details) has loaded. */
+    isLoaded: boolean;
+};
+/**
+ * Active organization, its membership, and a bound `has()` - the permission-aware
+ * companion to <Protect role|permission>. `membership`/`has` resolve
+ * synchronously from the session claim (no fetch); `organization` is loaded from
+ * the active org when one is set. Advisory, like the rest of the client surface.
+ */
+declare function useOrganization(): UseOrganizationResult;
+type UseSignInResult = {
+    /** Email + password sign-in. */
+    signIn: AuthOwlClient['signIn']['email'];
+    /** Username + password sign-in. */
+    signInUsername: AuthOwlClient['signIn']['username'];
+    /** Social provider sign-in (Google, GitHub, etc). */
+    signInSocial: AuthOwlClient['signIn']['social'];
+    /** Enterprise SSO (OIDC/SAML) sign-in - redirects to the tenant's IdP. */
+    signInSso: AuthOwlClient['signIn']['sso'];
+    /** Passwordless: email a one-time sign-in link. */
+    signInMagicLink: AuthOwlClient['signIn']['magicLink'];
+    /** Passwordless: sign in with a registered passkey (WebAuthn). */
+    signInPasskey: AuthOwlClient['signIn']['passkey'];
+    /** Passwordless: request an emailed one-time code. */
+    sendEmailOtp: AuthOwlClient['emailOtp']['sendVerificationOtp'];
+    /** Passwordless: complete sign-in with the emailed code. */
+    signInEmailOtp: AuthOwlClient['signIn']['emailOtp'];
+    /** Managed SMS: request a phone verification code. */
+    startPhoneOtp: AuthOwlClient['phoneOtp']['start'];
+    /** Managed SMS: verify the phone code and establish a session. */
+    verifyPhoneOtp: AuthOwlClient['phoneOtp']['verify'];
+};
+declare function useSignIn(): UseSignInResult;
+type UsePasskeysResult = {
+    /** List the signed-in user's registered passkeys. */
+    listPasskeys: AuthOwlClient['passkey']['listUserPasskeys'];
+    /** Register a new passkey for the signed-in user. */
+    addPasskey: AuthOwlClient['passkey']['addPasskey'];
+    /** Rename an existing passkey. */
+    updatePasskey: AuthOwlClient['passkey']['updatePasskey'];
+    /** Remove an existing passkey. */
+    deletePasskey: AuthOwlClient['passkey']['deletePasskey'];
+};
+/** Passkey management for the signed-in user (drives {@link PasskeyManager}). */
+declare function usePasskeys(): UsePasskeysResult;
+type UseMFAResult = {
+    /** Begin TOTP enrolment (password-gated): returns the TOTP URI + backup codes. */
+    enable: AuthOwlClient['twoFactor']['enable'];
+    /** Turn two-factor off for the signed-in user (password-gated). */
+    disable: AuthOwlClient['twoFactor']['disable'];
+    /** Verify a TOTP code: activates a pending factor, or clears a sign-in challenge. */
+    verifyTotp: AuthOwlClient['twoFactor']['verifyTotp'];
+    /** Clear a sign-in challenge with a single-use backup code. */
+    verifyBackupCode: AuthOwlClient['twoFactor']['verifyBackupCode'];
+    /** Email a fallback second-factor code for the pending challenge (lost authenticator). */
+    sendOtp: AuthOwlClient['twoFactor']['sendOtp'];
+    /** Clear a sign-in challenge with the emailed fallback code. */
+    verifyOtp: AuthOwlClient['twoFactor']['verifyOtp'];
+    /** Regenerate the backup codes (password-gated), invalidating the previous set. */
+    regenerateBackupCodes: AuthOwlClient['twoFactor']['generateBackupCodes'];
+};
+/** TOTP two-factor actions (drives <MFAEnrollment/> and <MFAChallenge/>). */
+declare function useMFA(): UseMFAResult;
+type UsePasswordResetResult = {
+    /** Email a reset link to the user. */
+    requestPasswordReset: AuthOwlClient['requestPasswordReset'];
+    /** Set a new password with the token from the reset link. */
+    resetPassword: AuthOwlClient['resetPassword'];
+};
+/** Password-reset actions (drives <ForgotPassword/> and <ResetPassword/>). */
+declare function usePasswordReset(): UsePasswordResetResult;
+type UseEmailVerificationResult = {
+    /** (Re)send the email-verification link. */
+    sendVerificationEmail: AuthOwlClient['sendVerificationEmail'];
+    /** Send an email ownership-verification code. */
+    sendVerificationCode: AuthOwlClient['emailOtp']['sendVerificationOtp'];
+    /** Verify an email ownership code. */
+    verifyEmailCode: AuthOwlClient['emailOtp']['verifyEmail'];
+};
+/** Email-verification actions for link and code ceremonies. */
+declare function useEmailVerification(): UseEmailVerificationResult;
+type UseConsentResult = {
+    /** Consent status is still being fetched. */
+    isLoading: boolean;
+    /** The signed-in user must (re-)accept the current terms version to continue. */
+    needsConsent: boolean;
+    /** Full status (version + doc URLs) once loaded. */
+    status: ConsentStatus | null;
+    /** Record acceptance of the current version, then refresh (clears needsConsent). */
+    accept: () => Promise<void>;
+    /** Re-fetch the status (e.g. after the user navigates back). */
+    refresh: () => Promise<void>;
+};
+/**
+ * Legal-consent status for the signed-in user, driving the re-consent gate: when
+ * the operator bumps the terms version, `needsConsent` flips true until the user
+ * accepts. Re-fetches when the signed-in identity changes (sign-in/out). Used by
+ * <ConsentGate/>; also usable standalone.
+ */
+declare function useConsent(): UseConsentResult;
+type UseSignUpResult = {
+    signUp: AuthOwlClient['signUp']['email'];
+};
+declare function useSignUp(): UseSignUpResult;
+type UseWaitlistResult = AuthOwlClient['waitlist'];
+declare function useWaitlist(): UseWaitlistResult;
+type UseSignOutResult = {
+    signOut: AuthOwlClient['signOut'];
+};
+declare function useSignOut(): UseSignOutResult;
+/**
+ * Pure, DOM-free resolution of which sign-in surfaces to render from a project's
+ * public config. Kept out of <SignIn/> so the branching is unit-testable without
+ * a renderer, and so the "which methods, and why nothing" decision lives in one
+ * place.
+ */
+/** Method slugs the SDK can render a UI for (server contract, canonical snake_case). */
+declare const KNOWN_METHODS: readonly ["password", "magic_link", "email_otp", "phone_otp", "passkey", "sso"];
+type KnownMethod = (typeof KNOWN_METHODS)[number];
+/**
+ * Which email input carries the `webauthn` autocomplete token for passkey
+ * conditional mediation. Exactly one input can host it, so this names the first
+ * email-bearing method in render-priority order (or null when passkey is off /
+ * there is no email input to attach to).
+ */
+type AutofillHost = 'password' | 'magic_link' | 'email_otp' | 'sso' | null;
+/**
+ * The primary sign-in action - the one bound to <SignIn/>'s form submit (Enter
+ * key), rendered as the single filled button. Password wins when enabled;
+ * otherwise the first passwordless email method in priority order. The other
+ * email methods render as secondary (outlined) buttons reusing the same email.
+ * `null` when no email method is enabled (social/passkey only). SSO is last in
+ * priority: it is the filled submit only when it is the sole email method.
+ */
+type SignInPrimary = 'password' | 'magic' | 'otp' | 'sso' | null;
+type SignInPlan = {
+    password: boolean;
+    username: boolean;
+    magicLink: boolean;
+    emailOtp: boolean;
+    phoneOtp: boolean;
+    passkey: boolean;
+    /** Inbound enterprise SSO - an email-domain-resolved redirect method. */
+    sso: boolean;
+    social: string[];
+    /** True when at least one surface can render. */
+    renderable: boolean;
+    /** The primary action (filled submit button); see {@link SignInPrimary}. */
+    primary: SignInPrimary;
+    /**
+     * Why nothing renders, when `renderable` is false:
+     *  - 'unsupported': the project enabled only methods this SDK build cannot show
+     *    (the consumer needs to upgrade the SDK);
+     *  - 'none': the project has no sign-in methods enabled at all.
+     */
+    emptyReason: 'unsupported' | 'none' | null;
+    /**
+     * The single email input that should arm passkey autofill. The priority order
+     * here MUST match the order <SignIn/> renders these methods, so the token lands
+     * on the first visible email field.
+     */
+    autofillHost: AutofillHost;
+};
+/**
+ * Autocomplete value for a sign-in email input. Appends the WebAuthn token when
+ * this input is the passkey conditional-mediation host so the browser surfaces
+ * passkeys inline. One place owns the token string.
+ */
+declare function emailAutocomplete(isPasskeyHost: boolean): string;
+/**
+ * Resolve the sign-in surfaces from a project's public config. On a config error
+ * (`config` null) fall back to password - the safe default that always renders -
+ * rather than showing nothing.
+ */
+declare function resolveSignInMethods(config: PublicConfig | null): SignInPlan;
+type SignInProps = {
+    redirectTo?: string;
+    /** Optional callback after successful sign-in. */
+    onSignedIn?: () => void;
+    /**
+     * URL of your reset page (where <ResetPassword/> is mounted). When set and
+     * password sign-in is enabled, a "Forgot password?" link appears that switches
+     * to an inline reset-request form. Omit it to hide the link.
+     */
+    resetPasswordUrl?: string;
+    /**
+     * Force the "Secured by AuthOwl" badge on even when the plan would hide it
+     * (paid/comped projects). Free projects always show it regardless.
+     */
+    showBadge?: boolean;
+};
+declare function SignIn({ redirectTo, onSignedIn, resetPasswordUrl, showBadge }?: SignInProps): React.JSX.Element;
+type PhoneOTPProps = {
+    redirectTo?: string;
+    onSignedIn?: () => void;
+    /** Optional navigation affordance when embedded in another sign-in surface. */
+    onBack?: () => void;
+};
+/** Egyptian phone sign-in with managed Turnstile, retry-safe send, and code verification. */
+declare function PhoneOTP({ redirectTo, onSignedIn, onBack }: PhoneOTPProps): React.JSX.Element;
+type SignUpProps = {
+    redirectTo?: string;
+    onSignedUp?: () => void;
+    /**
+     * URL of your verify page (where <VerifyEmail/> is mounted). When the project
+     * requires email verification, the emailed link redirects here after confirming.
+     * Passed as the sign-up callbackURL; its origin must be an allowed origin.
+     */
+    verifyEmailUrl?: string;
+    /**
+     * Force the "Secured by AuthOwl" badge on even when the plan would hide it
+     * (paid/comped projects). Free projects always show it regardless.
+     */
+    showBadge?: boolean;
+    /** Called after an enrollment request is accepted while waitlist mode is active. */
+    onWaitlisted?: () => void;
+};
+declare function SignUp({ redirectTo, onSignedUp, verifyEmailUrl, showBadge, onWaitlisted, }?: SignUpProps): React.JSX.Element;
+type WaitlistProps = {
+    onJoined?: () => void;
+    /**
+     * Force the "Secured by AuthOwl" badge on even when the plan would hide it.
+     * Free projects always show it regardless.
+     */
+    showBadge?: boolean;
+};
+declare function Waitlist({ onJoined, showBadge }?: WaitlistProps): React.JSX.Element;
+type ConsentGateProps = {
+    /** The protected app content shown once consent is satisfied. */
+    children: React.ReactNode;
+    /** Optional heading for the re-consent screen. */
+    title?: string;
+};
+/**
+ * Re-consent gate for signed-in users: when the operator bumps the project's
+ * legal terms version, this interposes an "accept the updated terms" screen
+ * until the user accepts, then renders {@link children}.
+ *
+ * Non-blocking by design — until the status resolves (and whenever consent isn't
+ * needed, the overwhelmingly common case) it renders children immediately, so it
+ * costs nothing to wrap your app with. It's a UX affordance; the authoritative
+ * enforcement and recording happen server-side. Signed-out users and projects
+ * without an active consent gate always pass through.
+ */
+declare function ConsentGate({ children, title }: ConsentGateProps): React.JSX.Element;
+type MFARequiredGateProps = {
+    /** The protected app content shown once the session is fully authenticated. */
+    children: React.ReactNode;
+    /** Optional heading for the enrolment screen. */
+    title?: string;
+};
+/**
+ * Required-MFA gate (B.5c): on projects with "Require MFA for everyone", a
+ * factor-less user's session is held at enrolment (CONTRACTS §5) - `useUser`
+ * reads it as signed OUT while `needsMfaEnrollment` is true. Wrap your app in
+ * this gate to interpose the enrolment screen until the user activates a
+ * factor; free to wrap unconditionally (it renders children untouched in
+ * every other state, same non-blocking design as <ConsentGate/>).
+ *
+ * PLACEMENT: the gate must wrap a layout that includes your SIGN-IN route.
+ * Server pages that `redirect('/sign-in')` on a null `auth()` bounce pending
+ * users there (a pending session reads as signed out server-side) - if the
+ * gate only wraps protected content, they re-sign-in into another pending
+ * session without ever seeing enrolment.
+ *
+ * Before showing enrolment it CONFIRMS with an uncached session read: the
+ * cookie-cached pending flag can be stale-true for up to 5 minutes after
+ * another device completed enrolment, and re-running enrolment would
+ * regenerate the user's TOTP secret.
+ */
+declare function MFARequiredGate({ children, title }: MFARequiredGateProps): React.JSX.Element | null;
+type BackupCodesManagerProps = {
+    /** Optional heading; pass null to hide it. */
+    title?: string | null;
+};
+/**
+ * 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/>.
+ */
+declare function BackupCodesManager({ title }: BackupCodesManagerProps): React.JSX.Element | null;
+type ConsentDocLinksProps = {
+    termsUrl?: string;
+    privacyUrl?: string;
+};
+/**
+ * Renders the "Terms of Service and Privacy Policy" links for whichever docs the
+ * project configured (one, the other, or both joined with "and"). Returns null
+ * when neither is set. Shared by <SignUp/>'s consent checkbox and <ConsentGate/>
+ * so the link copy lives in one place. The caller supplies the surrounding
+ * sentence ("I agree to the …", "We've updated our …").
+ */
+declare function ConsentDocLinks({ termsUrl, privacyUrl }: ConsentDocLinksProps): React.JSX.Element | null;
+type SocialButtonsProps = {
+    providers: string[];
+    /** Where to send the browser after the OAuth round-trip. */
+    callbackURL?: string;
+};
+/**
+ * Renders one "Continue with <provider>" button per configured social provider.
+ * A social sign-in also creates the account on first use, so this is shared by
+ * both <SignIn/> and <SignUp/>.
+ */
+declare function SocialButtons({ providers, callbackURL }: SocialButtonsProps): React.JSX.Element | null;
+type MagicLinkFormProps = {
+    /** Where to land after the emailed link is followed. */
+    callbackURL?: string;
+    /** Append the `webauthn` autofill token to the email input (passkey host). */
+    webauthnAutofill?: boolean;
+};
+/**
+ * Passwordless magic-link request: collects an email and asks the server to send
+ * a one-time sign-in link. No session is issued here - the session is created
+ * when the user follows the emailed link, so there is no redirect on submit.
+ */
+declare function MagicLinkForm({ callbackURL, webauthnAutofill }: MagicLinkFormProps): React.JSX.Element;
+type EmailOtpFormProps = {
+    redirectTo?: string;
+    /** Called after the code is verified and a session is issued. */
+    onSignedIn?: () => void;
+    /** Append the `webauthn` autofill token to the email input (passkey host). */
+    webauthnAutofill?: boolean;
+};
+/**
+ * Passwordless email one-time-code sign-in, in two stages: request a code for an
+ * email, then verify the emailed code to complete sign-in. A session is issued
+ * on successful verification (unlike magic-link, which round-trips via email).
+ */
+declare function EmailOtpForm({ redirectTo, onSignedIn, webauthnAutofill }: EmailOtpFormProps): React.JSX.Element;
+type PasskeyButtonProps = {
+    redirectTo?: string;
+    /** Called after a passkey ceremony issues a session. */
+    onSignedIn?: () => void;
+};
+/**
+ * Explicit passkey (WebAuthn) sign-in: opens the browser's passkey prompt on
+ * click. Complements the inline conditional-mediation autofill armed by
+ * <SignIn/> - the button always works even where autofill is unavailable.
+ */
+declare function PasskeyButton({ redirectTo, onSignedIn }: PasskeyButtonProps): React.JSX.Element;
+type ForgotPasswordProps = {
+    /**
+     * The URL of your reset page (where <ResetPassword/> is mounted). The emailed
+     * link validates the token then redirects here with `?token=`. Its origin must
+     * be one of the project's allowed origins.
+     */
+    resetPasswordUrl?: string;
+    /** Optional "back to sign in" affordance (shown when embedded in <SignIn/>). */
+    onBack?: () => void;
+};
+/**
+ * Request a password-reset email. Always shows the same neutral confirmation on
+ * success - the server returns success for unknown emails too (anti-enumeration),
+ * so the UI must not reveal whether an account exists.
+ */
+declare function ForgotPassword({ resetPasswordUrl, onBack }: ForgotPasswordProps): React.JSX.Element;
+type ResetPasswordProps = {
+    /** The reset token; if omitted, read from the `?token=` query param on mount. */
+    token?: string;
+    /** Where to send the user after a successful reset (e.g. your sign-in page). */
+    redirectTo?: string;
+    /** Called after the password is reset. */
+    onReset?: () => void;
+};
+/**
+ * Set a new password from a reset link. Mount this on the page your
+ * `resetPasswordUrl` points at: the link redirects here with `?token=`, which
+ * this reads (unless a `token` prop is passed). On success it redirects to
+ * `redirectTo` (same-origin/relative only).
+ */
+declare function ResetPassword({ token: tokenProp, redirectTo, onReset }: ResetPasswordProps): React.JSX.Element;
+type VerifyEmailProps = {
+    /** Where to send the user after a successful verification - your sign-in page. */
+    redirectTo?: string;
+    /** Called once when the page loads in the verified (no-error) state. */
+    onVerified?: () => void;
+    /** Where a resent link should land; defaults to this page's own URL. */
+    callbackURL?: string;
+};
+/**
+ * Landing page for the verification link. The server confirms the address (it
+ * does NOT sign the user in - verification is login-CSRF-safe), then redirects
+ * here, appending `?error=CODE` only on failure. So this reads the outcome from
+ * the URL: success shows a confirmation and can redirect to your sign-in page;
+ * failure offers a resend. Point `redirectTo` at your sign-in route.
+ */
+declare function VerifyEmail({ redirectTo, onVerified, callbackURL }: VerifyEmailProps): React.JSX.Element;
+type VerificationPendingProps = {
+    /** The address the verification link or code was sent to. */
+    email: string;
+    /** Where the link should land after confirming (your <VerifyEmail/> page). */
+    callbackURL?: string;
+    /** Ownership-verification ceremony selected by the AuthOwl project. */
+    method?: 'link' | 'code';
+};
+/**
+ * "Check your email" panel shown after a sign-up that requires verification. Lets
+ * the user resend the link. Rendered by <SignUp/>; also usable standalone.
+ */
+declare function VerificationPending({ email, callbackURL, method, }: VerificationPendingProps): React.JSX.Element;
+type PasskeyManagerProps = {
+    /** Heading text; pass `null` to render without a heading. */
+    title?: string | null;
+    /** Whether project policy permits registering a new passkey. */
+    allowAdd?: boolean;
+};
+/**
+ * Drop-in passkey management for the signed-in user: list, register, rename, and
+ * remove passkeys. Requires an authenticated session.
+ *
+ * The stateful body is keyed on the user id: on an account switch React remounts
+ * it, so any in-flight load or mutation from the previous user resolves against
+ * an unmounted instance (a no-op) and can never surface stale errors, pending
+ * state, or another account's passkeys on the new user's UI.
+ */
+declare function PasskeyManager({ title, allowAdd }?: PasskeyManagerProps): React.JSX.Element;
+type MFAEnrollmentProps = {
+    /** Called once the factor is verified and active. */
+    onEnrolled?: () => void;
+    /** Heading text; pass `null` when a parent section owns the heading. */
+    title?: string | null;
+};
+/**
+ * TOTP enrolment for the signed-in user: confirm the password, scan the QR (or
+ * enter the secret manually) into an authenticator app, save the one-time backup
+ * codes, then verify a live code to activate. The factor is NOT active until that
+ * final verification, so an abandoned setup never half-enrols the account.
+ */
+declare function MFAEnrollment({ onEnrolled, title }: MFAEnrollmentProps): React.JSX.Element;
+type MFAChallengeProps = {
+    /** Called once the challenge clears and a session is issued. */
+    onVerified?: () => void | Promise<void>;
+    /** Show the "trust this device for 30 days" option on the TOTP step (default true). */
+    allowTrustDevice?: boolean;
+};
+/**
+ * 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.
+ */
+declare function MFAChallenge({ onVerified, allowTrustDevice }: MFAChallengeProps): React.JSX.Element;
+type AuthOwlBadgeProps = {
+    /** Override the link target (defaults to the AuthOwl site). */
+    href?: string;
+    /**
+     * Render the badge even when the plan would hide it (paid/comped projects).
+     * Free projects always show it. Use this to keep the "Secured by AuthOwl"
+     * attribution visible on a paid project by choice.
+     */
+    force?: boolean;
+};
+/**
+ * "Secured by AuthOwl" attribution. Shown on free-plan projects and hidden on
+ * paid plans - the server sets `config.badge` from the workspace's entitled plan,
+ * so this renders when `badge` is true (or when `force` is set). Auto-rendered at
+ * the foot of <SignIn/> and <SignUp/>; also exported so headless consumers can
+ * place it themselves.
+ *
+ * It is a plain client element: a consumer can hide it with CSS. Removing it on
+ * the free plan is a terms-of-service matter, not a technical control - the same
+ * posture every embeddable auth widget takes.
+ */
+declare function AuthOwlBadge({ href, force }?: AuthOwlBadgeProps): React.JSX.Element | null;
+/**
+ * Conditional-render helpers gated on the client session. They render nothing
+ * until the session has loaded (avoids a signed-out flash), then show/hide.
+ *
+ * IMPORTANT: these are UX affordances, NOT a security boundary. The session they
+ * read lives in the browser and can be spoofed; never gate access to secret data
+ * or privileged actions on them. Enforce real authorization on the server (verify
+ * the session with @authowl/next's `auth()` in a route handler / server
+ * component). Same posture as Clerk's `<SignedIn>`/`<Protect>`.
+ */
+type SignedInProps = {
+    children: React.ReactNode;
+};
+/** Renders its children only when a user is signed in. */
+declare function SignedIn({ children }: SignedInProps): React.JSX.Element | null;
+type SignedOutProps = {
+    children: React.ReactNode;
+};
+/** Renders its children only when no user is signed in (once loaded). */
+declare function SignedOut({ children }: SignedOutProps): React.JSX.Element | null;
+type ProtectProps = {
+    children: React.ReactNode;
+    /** Shown instead of the children when the user is signed out or fails a gate. */
+    fallback?: React.ReactNode;
+    /**
+     * Require the active organization membership's role to match (built-in
+     * `owner`/`admin`/`member` or a project role key). Read from the client
+     * session claim.
+     */
+    role?: string;
+    /**
+     * Require the active organization membership to grant this permission -
+     * `org:sys_*` or a custom `org:<feature>:<action>` id. Evaluated against the
+     * LOCAL session claim (never a statement-only has-permission route).
+     */
+    permission?: string;
+    /**
+     * Require membership of this team within the active organization. Teams are pure
+     * grouping, so this gates on WHICH GROUP someone is in, not on authority. A
+     * session predating teams proves no team and fails the gate.
+     */
+    teamId?: string;
+    /** Extra gate on the signed-in user (e.g. a custom flag). Signed-in is always required. */
+    condition?: (user: AuthUser) => boolean;
+};
+/**
+ * Renders `children` when the user is signed in AND passes every provided gate
+ * (`role`, `permission`, `condition` - all must pass), otherwise `fallback`.
+ * Renders nothing until the session has loaded.
+ *
+ * ADVISORY ONLY. `role`/`permission` here are a UX affordance read from the
+ * browser session claim, which a client can spoof - gating custom-permission UI
+ * this way hides controls, it does NOT secure them. Enforce the real boundary
+ * server-side over a VERIFIED project token (`@authowl/next`'s server `has()`),
+ * which checks the token signature before trusting any membership claim (§5).
+ */
+declare function Protect({ children, fallback, role, permission, teamId, condition, }: ProtectProps): React.JSX.Element | null;
+type AuthLoadingProps = {
+    /**
+     * Shown while the session is still bootstrapping. Defaults to a centered
+     * spinner with an sr-only "Loading…" label, so the common case is a
+     * self-closing `<AuthLoading />`.
+     */
+    children?: React.ReactNode;
+};
+/**
+ * Renders while the client session is still loading (`!useUser().isLoaded`),
+ * then nothing. Pair it as a SIBLING of `<SignedIn>`/`<SignedOut>` to cover the
+ * blank window after a page load or SSO/redirect landing before the session
+ * resolves. This is the Clerk-style split (`<AuthLoading>`/`<AuthLoaded>`)
+ * rather than a `loading` prop on `<SignedIn>`/`<SignedOut>`: those render as
+ * siblings, so per-component fallbacks would paint two spinners at once. One
+ * `<AuthLoading>` owns the loading window.
+ */
+declare function AuthLoading({ children }: AuthLoadingProps): React.JSX.Element | null;
+type AuthLoadedProps = {
+    children: React.ReactNode;
+};
+/** Renders its children only once the session has finished loading. */
+declare function AuthLoaded({ children }: AuthLoadedProps): React.JSX.Element | null;
+/**
+ * Decorative loading spinner (`.ba-spinner`). It carries no text, so pair it
+ * with a visible label (as `<Busy>` does on action buttons) or an sr-only label
+ * (as `<AuthLoading>` does): on its own it is `aria-hidden` and invisible to
+ * assistive tech. RTL-safe and reduced-motion-aware via CSS in `styles.css`.
+ */
+declare function Spinner(): React.JSX.Element;
+type SignOutButtonProps = {
+    /** Button label (defaults to "Sign out"). */
+    children?: React.ReactNode;
+    /** Where to navigate after sign-out (same-origin/relative only). */
+    redirectTo?: string;
+    /** Called after the session is cleared. */
+    onSignedOut?: () => void;
+    className?: string;
+};
+/**
+ * Standalone sign-out button. Clears the session, then notifies and redirects
+ * (same-origin/relative targets only). For a menu with avatar + sign-out, use
+ * <UserButton/> instead.
+ */
+declare function SignOutButton({ children, redirectTo, onSignedOut, className }: SignOutButtonProps): React.JSX.Element;
+declare function UserButton(): React.JSX.Element | null;
+declare const USER_PROFILE_SECTIONS: readonly ["profile", "email", "password", "social", "sessions", "passkeys", "mfa", "recovery", "danger"];
+type UserProfileSection = (typeof USER_PROFILE_SECTIONS)[number];
+type UserProfileSharedProps = {
+    /** Controlled active section. */
+    section?: UserProfileSection;
+    /** Initial section when uncontrolled. Falls back to the AuthOwl URL hash. */
+    defaultSection?: UserProfileSection;
+    onSectionChange?: (section: UserProfileSection) => void;
+    /** Called after the signed-in account is permanently deleted. */
+    onDeleted?: () => void;
+};
+type UserProfileProps = UserProfileSharedProps & ({
+    /** Render the account settings inline. */
+    mode?: 'page';
+    onClose?: never;
+} | {
+    /** Render an accessible account-settings overlay. */
+    mode: 'modal';
+    /** Called by the close button, backdrop, or Escape key. */
+    onClose: () => void;
+});
+declare function UserProfile(props?: UserProfileProps): React.JSX.Element;
+type OrganizationSwitcherProps = {
+    showPersonalWorkspace?: boolean;
+    onOrganizationChange?: (organization: Organization | null) => void;
+};
+declare function OrganizationSwitcher({ showPersonalWorkspace, onOrganizationChange }?: OrganizationSwitcherProps): React.JSX.Element | null;
+type OrganizationListProps = {
+    onOrganizationChange?: (organization: Organization | null) => void;
+};
+declare function OrganizationList({ onOrganizationChange }?: OrganizationListProps): React.JSX.Element | null;
+type CreateOrganizationProps = {
+    onCreated?: (organization: Organization) => void;
+    /** Hide the component heading when a surrounding dialog already supplies it. */
+    title?: string | null;
+};
+declare function CreateOrganization({ onCreated, title }?: CreateOrganizationProps): React.JSX.Element | null;
+type OrganizationProfileSection = 'general' | 'members' | 'invitations' | 'danger';
+type OrganizationProfileProps = {
+    /** Organization to manage. Omitted means the active organization from the session. */
+    organizationId?: string;
+    defaultSection?: OrganizationProfileSection;
+    onDeleted?: (organization: OrganizationDetails) => void;
+    onLeft?: (organization: OrganizationDetails) => void;
+};
+declare function OrganizationProfile({ organizationId, defaultSection, onDeleted, onLeft }?: OrganizationProfileProps): React.JSX.Element | null;
+type GoogleOneTapRuntimeErrorCode = 'script_load_failed' | 'api_unavailable' | 'configuration_conflict' | 'duplicate_instance' | 'prompt_failed';
+type GoogleOneTapSkipReason = 'disabled' | 'existing_session' | 'provider_disabled' | 'prompt_skipped';
+type GoogleOneTapDismissReason = 'tap_outside' | 'cancel_called' | 'flow_restarted' | 'unknown';
+type GoogleOneTapErrorCode = GoogleOneTapRuntimeErrorCode | 'public_config_unavailable' | 'missing_client_id' | 'credential_missing' | 'credential_exchange_failed';
+type GoogleOneTapError = {
+    code: GoogleOneTapErrorCode;
+    status?: number;
+    authCode?: AuthOwlErrorCode | (string & {});
+};
+type GoogleOneTapProps = {
+    /** Disable prompting without unmounting the component. */
+    disabled?: boolean;
+    /** Bind Google's ID token to this browser attempt. Generate a fresh random value server-side. */
+    nonce?: string;
+    /** Let eligible returning Google users sign in automatically. Defaults to false. */
+    autoSelect?: boolean;
+    /** Let tapping outside dismiss the prompt. Defaults to true. */
+    cancelOnTapOutside?: boolean;
+    /** Wording Google uses in the prompt. */
+    context?: 'signin' | 'signup' | 'use';
+    /** Enable Google's upgraded experience on ITP browsers. Defaults to true. */
+    itpSupport?: boolean;
+    loginHint?: string;
+    hostedDomain?: string;
+    stateCookieDomain?: string;
+    /** CSP nonce applied only when AuthOwl inserts the Google Identity script. */
+    scriptNonce?: string;
+    onSignedIn?: (user: AuthUser) => void;
+    onSkipped?: (reason: GoogleOneTapSkipReason) => void;
+    onDismissed?: (reason: GoogleOneTapDismissReason) => void;
+    onError?: (error: GoogleOneTapError) => void;
+};
+/** Invisible, server-configured Google One Tap conversion helper. */
+declare function GoogleOneTap({ disabled, nonce, autoSelect, cancelOnTapOutside, context, itpSupport, loginHint, hostedDomain, stateCookieDomain, scriptNonce, onSignedIn, onSkipped, onDismissed, onError, }: GoogleOneTapProps): null;
+export { type Appearance, AuthLoaded, type AuthLoadedProps, AuthLoading, type AuthLoadingProps, AuthOwlBadge, type AuthOwlBadgeProps, 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, 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, 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 UseOrganizationResult, type UsePasskeysResult, type UsePasswordResetResult, 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, useLocale, useMFA, useOrganization, usePasskeys, usePasswordReset, usePublicConfig, useSession, useSignIn, useSignOut, useSignUp, useUser, useWaitlist };