@dloizides/auth-web 1.2.0

package/dist/index.d.mts

@@ -0,0 +1,806 @@
+import { ReactElement, ReactNode } from 'react';
+import { BffAuthClient, BffUser, BffLoginRequest, BffForgotPasswordRequest, BffResetPasswordRequest, BffOtpRequestResult, HttpClient } from '@dloizides/auth-client';
+export { BffAuthClient, BffAuthClientOptions, BffForgotPasswordRequest, BffLoginRequest, BffOtpRequestRequest, BffOtpRequestResult, BffOtpVerifyRequest, BffPinLoginRequest, BffRegisterRequest, BffResetPasswordRequest, BffUser, HttpClient, HttpRequest, HttpResponse, createFetchHttpClient } from '@dloizides/auth-client';
+import { UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+
+/**
+ * Label bags for the auth components.
+ *
+ * `@dloizides/auth-web` ships **no** translation framework — it is i18n-agnostic
+ * by design (each app already owns its own i18n). Every user-facing string a
+ * component renders is supplied by the consuming app through a typed `labels`
+ * prop. The app passes strings it has already localised with `FM()` / `t()`.
+ *
+ * Each bag has a `DEFAULT_*` constant (English) so a component renders sensibly
+ * with no `labels` prop and a consuming app can spread-override only the keys
+ * it wants to change.
+ */
+/** Strings rendered by `<LoginForm>`. */
+interface LoginFormLabels {
+    title: string;
+    subtitle: string;
+    usernameLabel: string;
+    usernamePlaceholder: string;
+    passwordLabel: string;
+    passwordPlaceholder: string;
+    submit: string;
+    /** Shown while the login request is in flight. */
+    submitting: string;
+    /** The "Forgot password?" link text. */
+    forgotPassword: string;
+    /** Generic credentials-rejected message. */
+    invalidCredentials: string;
+    /** Shown when one or both fields are empty on submit. */
+    missingFields: string;
+}
+/** Strings rendered by `<ForgotPasswordForm>`. */
+interface ForgotPasswordFormLabels {
+    title: string;
+    /** Copy above the email field. */
+    description: string;
+    emailLabel: string;
+    emailPlaceholder: string;
+    submit: string;
+    submitting: string;
+    /** Generic confirmation, shown regardless of whether the email is registered. */
+    successMessage: string;
+    /** Shown on a network / 5xx failure. */
+    networkError: string;
+    /** Shown when the entered value is not a valid email. */
+    invalidEmail: string;
+}
+/** Strings rendered by `<OtpForm>` — the two-step email-OTP login form. */
+interface OtpFormLabels {
+    /** Title shown on the request-a-code step. */
+    requestTitle: string;
+    /** Copy above the email field. */
+    requestDescription: string;
+    emailLabel: string;
+    emailPlaceholder: string;
+    /** The "send code" button. */
+    requestSubmit: string;
+    /** Shown while the request is in flight. */
+    requesting: string;
+    /** Shown when the entered value is not a valid email. */
+    invalidEmail: string;
+    /** Title shown on the enter-the-code step. */
+    verifyTitle: string;
+    /** Copy above the code field; `{identifier}` is replaced with the email. */
+    verifyDescription: string;
+    codeLabel: string;
+    codePlaceholder: string;
+    /** The "verify" button. */
+    verifySubmit: string;
+    /** Shown while verification is in flight. */
+    verifying: string;
+    /** Shown when the code field is empty on submit. */
+    missingCode: string;
+    /** Generic "that code was wrong / expired" message. */
+    invalidCode: string;
+    /** The "resend code" link text. */
+    resend: string;
+    /** Shown while a resend is in flight. */
+    resending: string;
+    /** The "use a different email" link text — returns to step 1. */
+    changeEmail: string;
+}
+/** Strings rendered by `<PinForm>` — the single-step event-PIN login form. */
+interface PinFormLabels {
+    /** Title shown above the PIN field. */
+    title: string;
+    /** Copy above the PIN field. */
+    description: string;
+    pinLabel: string;
+    pinPlaceholder: string;
+    /** The "sign in" button. */
+    submit: string;
+    /** Shown while the PIN exchange is in flight. */
+    submitting: string;
+    /** Shown when the PIN field is empty on submit. */
+    missingPin: string;
+    /** Generic "that PIN was wrong / expired / locked out" message. */
+    invalidPin: string;
+}
+/** Strings rendered by `<ResetPasswordForm>`. */
+interface ResetPasswordFormLabels {
+    title: string;
+    description: string;
+    newPasswordLabel: string;
+    newPasswordPlaceholder: string;
+    confirmPasswordLabel: string;
+    confirmPasswordPlaceholder: string;
+    submit: string;
+    submitting: string;
+    /** Error: one or both fields empty. */
+    errorEmpty: string;
+    /** Error: the new password fails the policy. */
+    errorWeakPassword: string;
+    /** Error: confirm does not match. */
+    errorMismatch: string;
+    /** Error: the reset token is missing / expired / consumed. */
+    errorTokenInvalid: string;
+    /** Error: a network / 5xx failure. */
+    errorNetwork: string;
+}
+declare const DEFAULT_LOGIN_LABELS: LoginFormLabels;
+declare const DEFAULT_FORGOT_PASSWORD_LABELS: ForgotPasswordFormLabels;
+declare const DEFAULT_OTP_LABELS: OtpFormLabels;
+declare const DEFAULT_PIN_LABELS: PinFormLabels;
+declare const DEFAULT_RESET_PASSWORD_LABELS: ResetPasswordFormLabels;
+
+/**
+ * `AuthTheme` — the design-token contract every `@dloizides/auth-web` component
+ * is styled against.
+ *
+ * The package owns **no** brand. Katalogos, Erevna and Kefi each look different;
+ * each one maps its own theme system onto this flat token bag and passes it in
+ * (via the `theme` prop or `<AuthThemeProvider>`). The component code only ever
+ * reads these tokens — never an app-specific theme object — so the same
+ * `<LoginForm>` renders on-brand in three visually distinct apps.
+ *
+ * Keep this shape minimal and stable: it is a public API surface.
+ */
+/** Colour tokens — the only colours the auth components reference. */
+interface AuthThemeColors {
+    /** Page / screen background behind the form card. */
+    background: string;
+    /** The form card surface colour. */
+    surface: string;
+    /** Primary text (titles, labels, input text). */
+    text: string;
+    /** Muted / secondary text (subtitles, helper copy). */
+    textSecondary: string;
+    /** Input + card border colour; also the disabled-button fill. */
+    border: string;
+    /** Brand primary — the submit button fill and link colour. */
+    primary: string;
+    /** Text drawn on top of `primary` (e.g. the submit button label). */
+    onPrimary: string;
+    /** Error text and error-state borders. */
+    danger: string;
+    /** Success text (e.g. the forgot-password confirmation). */
+    success: string;
+}
+/** Corner-radius tokens. */
+interface AuthThemeRadii {
+    /** Inputs and buttons. */
+    input: number;
+    /** The form card. */
+    card: number;
+}
+/** Spacing scale (in density-independent pixels). */
+interface AuthThemeSpacing {
+    /** Tight gap — e.g. label-to-input. */
+    xs: number;
+    /** Small gap. */
+    sm: number;
+    /** Default gap — between stacked fields. */
+    md: number;
+    /** Large gap — section separation. */
+    lg: number;
+    /** Card inner padding. */
+    xl: number;
+}
+/** Font-size tokens. */
+interface AuthThemeTypography {
+    /** Form title. */
+    title: number;
+    /** Form subtitle. */
+    subtitle: number;
+    /** Field labels. */
+    label: number;
+    /** Input text and button text. */
+    body: number;
+    /** Helper / error / footer copy. */
+    caption: number;
+}
+/** The full token bag a consuming app supplies. */
+interface AuthTheme {
+    colors: AuthThemeColors;
+    radii: AuthThemeRadii;
+    spacing: AuthThemeSpacing;
+    typography: AuthThemeTypography;
+}
+/**
+ * A neutral, accessible light-mode theme. Apps are expected to override this —
+ * it exists so a component renders sensibly with zero configuration and so
+ * `<AuthThemeProvider>` has a default value.
+ */
+declare const defaultAuthTheme: AuthTheme;
+
+/**
+ * `<LoginForm>` — the ready-made, themeable password-login form.
+ *
+ * The "themeable component" half of the package design: drop it in, pass a
+ * `client`, a `theme` (or wrap in `<AuthThemeProvider>`) and a localised
+ * `labels` bag, and you have a branded login surface. It is built on the
+ * headless `useBffAuth` hook, so the ready-made and custom-layout paths share
+ * one code path.
+ *
+ * The package ships no router and no i18n. `onSuccess` hands the signed-in
+ * `BffUser` back to the app, which decides where to navigate (typically via
+ * `resolvePostLoginRoute`). All copy comes from `labels`.
+ */
+
+interface LoginFormProps {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. Falls back to the default theme. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<LoginFormLabels>;
+    /** Called with the signed-in user after a successful login. */
+    onSuccess: (user: BffUser) => void;
+    /** Called when the user taps the "Forgot password?" link. Omit to hide the link. */
+    onForgotPassword?: () => void;
+    /** Prefix applied to every `testID` so multiple forms can share a screen. */
+    testIdPrefix?: string;
+}
+/** Themeable password-login form built on `useBffAuth`. */
+declare function LoginForm({ client, theme: themeProp, labels: labelsProp, onSuccess, onForgotPassword, testIdPrefix, }: Readonly<LoginFormProps>): ReactElement;
+
+/**
+ * `<ForgotPasswordForm>` — the ready-made, themeable "request a reset link"
+ * form.
+ *
+ * Captures an email and POSTs to `/bff/forgot-password` via the headless
+ * `useBffForgotPassword` hook. The backend answers 200 unconditionally (no
+ * email enumeration), so on success the form swaps to a generic confirmation
+ * message — it never reveals whether the address is registered.
+ *
+ * Extracted + generalised from `apps/katalogos-web/src/components/Auth/
+ * ForgotPasswordModal.tsx` — minus the modal shell (apps own the surface) and
+ * the app-specific `FM()` calls (copy now comes from `labels`).
+ */
+
+interface ForgotPasswordFormProps {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<ForgotPasswordFormLabels>;
+    /**
+     * Full URL with a `{token}` placeholder; forwarded to the backend so it can
+     * build the reset-email link without hardcoding any frontend host. Optional —
+     * apps that configure the template server-side can omit it.
+     */
+    resetUrlTemplate?: string;
+    /** Called once the request succeeds (the generic-confirmation state). */
+    onSuccess?: () => void;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+}
+/** Themeable "request a reset link" form built on `useBffForgotPassword`. */
+declare function ForgotPasswordForm({ client, theme: themeProp, labels: labelsProp, resetUrlTemplate, onSuccess, testIdPrefix, }: Readonly<ForgotPasswordFormProps>): ReactElement;
+
+/**
+ * `<ResetPasswordForm>` — the ready-made, themeable "choose a new password"
+ * form.
+ *
+ * Built on the headless `useResetPasswordForm` hook, which owns all the logic
+ * (shared password policy, confirm-match, backend-error mapping). The component
+ * is a thin render layer: two fields, one button, one error line.
+ *
+ * Extracted + generalised from `apps/katalogos-web/src/auth/useResetPasswordForm.ts`
+ * + the katalogos reset-password route — minus the app-specific `FM()` and
+ * router calls (copy is in `labels`, navigation is the app's `onSuccess`).
+ */
+
+interface ResetPasswordFormProps {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /** The reset token, typically read from the deep-link URL by the app. */
+    token: string;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<ResetPasswordFormLabels>;
+    /** Called once the password has been reset successfully. */
+    onSuccess: () => void;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+}
+/** Themeable "choose a new password" form built on `useResetPasswordForm`. */
+declare function ResetPasswordForm({ client, token, theme: themeProp, labels: labelsProp, onSuccess, testIdPrefix, }: Readonly<ResetPasswordFormProps>): ReactElement;
+
+/**
+ * `<OtpForm>` — the ready-made, themeable two-step email-OTP login form.
+ *
+ * The "themeable component" half of the OTP design: drop it in, pass a
+ * `client`, a `theme` (or wrap in `<AuthThemeProvider>`) and a localised
+ * `labels` bag, and you have a branded email-OTP surface. It is built on the
+ * headless `useOtpLogin` hook, so the ready-made and custom-layout paths share
+ * one code path — the same pattern as `<LoginForm>`.
+ *
+ * Two steps, switched on `OtpLoginStep`:
+ *   1. `RequestCode` — `<OtpRequestStep>`: an email field + a "send code" button.
+ *   2. `EnterCode`   — `<OtpVerifyStep>`: a code field + a "verify" button, plus
+ *      "resend code" and "use a different email" affordances.
+ *
+ * The package ships no router and no i18n. `onSuccess` hands the signed-in
+ * `BffUser` back to the app; all copy comes from `labels`.
+ */
+
+interface OtpFormProps {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. Falls back to the default theme. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<OtpFormLabels>;
+    /** Called with the signed-in user after a successful code verification. */
+    onSuccess: (user: BffUser) => void;
+    /** Prefix applied to every `testID` so multiple forms can share a screen. */
+    testIdPrefix?: string;
+}
+/** Themeable two-step email-OTP login form built on `useOtpLogin`. */
+declare function OtpForm({ client, theme: themeProp, labels: labelsProp, onSuccess, testIdPrefix, }: Readonly<OtpFormProps>): ReactElement;
+
+/**
+ * `<PinForm>` — the ready-made, themeable single-step event-PIN login form.
+ *
+ * The "themeable component" half of the PIN design: drop it in, pass a
+ * `client`, the `eventExternalId` of the event the staff member is signing in
+ * to, a `theme` (or wrap in `<AuthThemeProvider>`) and a localised `labels`
+ * bag, and you have a branded event-PIN surface. It is built on the headless
+ * `usePinLogin` hook, so the ready-made and custom-layout paths share one code
+ * path — the same pattern as `<OtpForm>` / `<LoginForm>`.
+ *
+ * Unlike `<OtpForm>` the PIN flow is a single step: a PIN field + a "sign in"
+ * button. The `eventExternalId` is a prop, never typed by the user — the event
+ * context comes from the route/page the form is rendered on.
+ *
+ * The package ships no router and no i18n. `onSuccess` hands the signed-in
+ * `BffUser` back to the app; all copy comes from `labels`.
+ */
+
+interface PinFormProps {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /**
+     * External id of the event the PIN is scoped to. Supplied by the route/page
+     * — the event context is never typed by the user.
+     */
+    eventExternalId: string;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. Falls back to the default theme. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<PinFormLabels>;
+    /** Called with the signed-in user after a successful PIN exchange. */
+    onSuccess: (user: BffUser) => void;
+    /** Prefix applied to every `testID` so multiple forms can share a screen. */
+    testIdPrefix?: string;
+}
+/** Themeable single-step event-PIN login form built on `usePinLogin`. */
+declare function PinForm({ client, eventExternalId, theme: themeProp, labels: labelsProp, onSuccess, testIdPrefix, }: Readonly<PinFormProps>): ReactElement;
+
+/**
+ * React context for the `AuthTheme`.
+ *
+ * Two ways to theme `@dloizides/auth-web` components:
+ *
+ *  1. Wrap the auth screens in `<AuthThemeProvider theme={appAuthTheme}>` —
+ *     every component below reads the theme from context.
+ *  2. Pass `theme` directly as a prop to an individual component — the prop
+ *     always wins over context.
+ *
+ * With neither, components fall back to `defaultAuthTheme`. `useAuthTheme()`
+ * implements that precedence (prop → context → default) so each component does
+ * not re-derive it.
+ */
+
+interface AuthThemeProviderProps {
+    /** The token bag every descendant auth component is styled against. */
+    theme: AuthTheme;
+    children: ReactNode;
+}
+/** Provides an `AuthTheme` to every `@dloizides/auth-web` component below it. */
+declare function AuthThemeProvider({ theme, children, }: Readonly<AuthThemeProviderProps>): ReactElement;
+/**
+ * Resolve the effective theme for a component.
+ *
+ * Precedence: an explicit `themeProp` (if given) wins over the context value,
+ * which itself defaults to `defaultAuthTheme` when no provider is mounted.
+ */
+declare function useAuthTheme(themeProp?: AuthTheme): AuthTheme;
+
+/**
+ * Stable `testID` values for every interactive element the auth components
+ * render. Exported so E2E suites and unit tests reference one source of truth
+ * rather than hard-coding string literals.
+ *
+ * Each component also accepts a `testIdPrefix` prop; when set, these base IDs
+ * are prefixed so two forms can coexist on one screen without ID collisions.
+ *
+ * `sonarjs/no-hardcoded-passwords` is disabled for this file: it flags keys
+ * such as `loginPasswordInput`, but every value here is a UI test ID, not a
+ * credential. There are no secrets in this module.
+ */
+declare const AuthTestIds: {
+    readonly loginForm: "auth-login-form";
+    readonly loginUsernameInput: "auth-login-username";
+    readonly loginPasswordInput: "auth-login-password";
+    readonly loginSubmitButton: "auth-login-submit";
+    readonly loginForgotLink: "auth-login-forgot-link";
+    readonly loginError: "auth-login-error";
+    readonly forgotPasswordForm: "auth-forgot-form";
+    readonly forgotPasswordEmailInput: "auth-forgot-email";
+    readonly forgotPasswordSubmitButton: "auth-forgot-submit";
+    readonly forgotPasswordError: "auth-forgot-error";
+    readonly forgotPasswordSuccess: "auth-forgot-success";
+    readonly resetPasswordForm: "auth-reset-form";
+    readonly resetPasswordNewInput: "auth-reset-new";
+    readonly resetPasswordConfirmInput: "auth-reset-confirm";
+    readonly resetPasswordSubmitButton: "auth-reset-submit";
+    readonly resetPasswordError: "auth-reset-error";
+    readonly otpForm: "auth-otp-form";
+    readonly otpEmailInput: "auth-otp-email";
+    readonly otpRequestButton: "auth-otp-request";
+    readonly otpCodeInput: "auth-otp-code";
+    readonly otpVerifyButton: "auth-otp-verify";
+    readonly otpResendButton: "auth-otp-resend";
+    readonly otpChangeEmailButton: "auth-otp-change-email";
+    readonly otpError: "auth-otp-error";
+    readonly pinForm: "auth-pin-form";
+    readonly pinInput: "auth-pin-input";
+    readonly pinSubmitButton: "auth-pin-submit";
+    readonly pinError: "auth-pin-error";
+};
+/** Apply an optional prefix to a base test ID. */
+declare function withTestIdPrefix(baseId: string, prefix?: string): string;
+
+/** Lifecycle status of the auth session. */
+declare const enum BffAuthStatus {
+    /** The initial `/bff/me` probe has not finished yet. */
+    Loading = "loading",
+    /** A live session exists; `user` is populated. */
+    Authenticated = "authenticated",
+    /** No session; `user` is `null`. */
+    Unauthenticated = "unauthenticated"
+}
+interface UseBffAuthOptions {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /**
+     * When `true` (default), the hook probes `GET /bff/me` on mount to bootstrap
+     * `status`/`user`. Set `false` to skip the probe (e.g. on a public page).
+     */
+    probeOnMount?: boolean;
+}
+interface UseBffAuthResult {
+    /** The signed-in user, or `null` when there is no session. */
+    user: BffUser | null;
+    /** Session lifecycle status. */
+    status: BffAuthStatus;
+    /** `true` while a `login` or `logout` call is in flight. */
+    isSubmitting: boolean;
+    /** The last `login`/`logout`/`refresh` error, cleared on the next attempt. */
+    error: Error | null;
+    /** ROPC password login via `POST /bff/login`. Resolves to the user; rejects on failure. */
+    login: (request: BffLoginRequest) => Promise<BffUser>;
+    /** End the session via `POST /bff/logout`. Always resolves; never throws to the caller. */
+    logout: () => Promise<void>;
+    /** Re-read `GET /bff/me` and resync `user`/`status`. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Headless BFF auth. Returns the current user, the session status, and
+ * `login` / `logout` / `refresh` callbacks. No rendering — the consumer (or
+ * `<LoginForm>`) wires it to UI.
+ */
+declare function useBffAuth(options: UseBffAuthOptions): UseBffAuthResult;
+
+/**
+ * React Query mutation hooks for the BFF password-reset flow.
+ *
+ * Headless counterparts to `<ForgotPasswordForm>` / `<ResetPasswordForm>` —
+ * apps with a custom layout use these directly. They POST to the same-origin
+ * `/bff/forgot-password` and `/bff/reset-password`, which the BFF proxies to
+ * TenantService.
+ *
+ * Extracted + generalised from `apps/katalogos-web/src/auth/bffPasswordHooks.ts`.
+ * Difference: the katalogos version closed over a module-level singleton
+ * `bffAuthClient`; the package version takes the `client` in the options so it
+ * carries no global state.
+ *
+ * The mutation result type is `undefined` (not `void`): the BFF endpoints
+ * return no body, and `undefined` is a valid generic argument where the lint
+ * config rejects `void`.
+ */
+
+type UseBffForgotPasswordOptions = Omit<UseMutationOptions<undefined, Error, BffForgotPasswordRequest>, 'mutationFn'> & {
+    /** The same-origin BFF client. */
+    client: BffAuthClient;
+};
+/**
+ * Mutation that POSTs to `/bff/forgot-password`.
+ *
+ * The backend returns 200 unconditionally (no email enumeration); the UI
+ * should show the same "if that email exists, we sent a link" message whether
+ * `onSuccess` or `onError` fires.
+ */
+declare function useBffForgotPassword(options: UseBffForgotPasswordOptions): UseMutationResult<undefined, Error, BffForgotPasswordRequest>;
+type UseBffResetPasswordOptions = Omit<UseMutationOptions<undefined, Error, BffResetPasswordRequest>, 'mutationFn'> & {
+    /** The same-origin BFF client. */
+    client: BffAuthClient;
+};
+/**
+ * Mutation that POSTs to `/bff/reset-password`. A `400` (invalid / expired
+ * token) surfaces as a rejected mutation with the status in the error message.
+ */
+declare function useBffResetPassword(options: UseBffResetPasswordOptions): UseMutationResult<undefined, Error, BffResetPasswordRequest>;
+
+/**
+ * The discrete failure states the reset-password flow can surface.
+ *
+ * Each member is the stable key a consuming app maps onto a localised message.
+ * `useResetPasswordForm` reports exactly one of these at a time, preferring the
+ * earliest-fixable issue so the user resolves one thing at a time.
+ */
+declare const enum ResetPasswordError {
+    /** One or both password fields are empty. */
+    Empty = "empty",
+    /** The new password fails the shared password policy. */
+    WeakPassword = "weakPassword",
+    /** The confirm field does not match the new password. */
+    Mismatch = "mismatch",
+    /** The reset token is missing, expired, or already consumed. */
+    TokenInvalid = "tokenInvalid",
+    /** A network or 5xx failure prevented the reset from completing. */
+    Network = "network"
+}
+
+interface UseResetPasswordFormArgs {
+    /** The same-origin BFF client. */
+    client: BffAuthClient;
+    /** The reset token, typically read from the deep-link URL. */
+    token: string;
+    /** Invoked once the password has been reset successfully. */
+    onSuccess: () => void;
+}
+interface UseResetPasswordFormResult {
+    newPassword: string;
+    confirmPassword: string;
+    setNewPassword: (value: string) => void;
+    setConfirmPassword: (value: string) => void;
+    /** `true` while the reset request is in flight. */
+    isSubmitting: boolean;
+    /** The single active error, or `null` when the form is clean. */
+    errorKey: ResetPasswordError | null;
+    /** `true` once a token-related failure is detected (drives a "request a new link" UI). */
+    hasInvalidToken: boolean;
+    /** Validate, then submit. */
+    submit: () => void;
+}
+/**
+ * Headless reset-password form logic. Returns the field values, setters, the
+ * single active error, and a `submit` callback.
+ */
+declare function useResetPasswordForm({ client, token, onSuccess, }: UseResetPasswordFormArgs): UseResetPasswordFormResult;
+
+/**
+ * The two discrete steps of the email-OTP login flow.
+ *
+ * `useOtpLogin` is at exactly one of these at a time, and `<OtpForm>` renders a
+ * different surface per step. The flow is strictly forward: a request moves
+ * `RequestCode` → `EnterCode`; a resend stays on `EnterCode`. Each member is a
+ * stable key — `<OtpForm>` switches on it, never on a string literal.
+ */
+declare const enum OtpLoginStep {
+    /** Step 1: collect the email and ask the BFF to send a code. */
+    RequestCode = "requestCode",
+    /** Step 2: the code is on its way — collect and verify it. */
+    EnterCode = "enterCode"
+}
+
+interface UseOtpLoginOptions {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+}
+interface UseOtpLoginResult {
+    /** Which of the two steps the flow is currently on. */
+    step: OtpLoginStep;
+    /** The identifier (email) the code was last requested for; `''` before step 1. */
+    identifier: string;
+    /**
+     * The latest `POST /bff/otp/request` result, or `null` before any request.
+     * Carries `expiresIn` for a countdown — never depend on `code` being present.
+     */
+    lastRequest: BffOtpRequestResult | null;
+    /** `true` while a `requestCode` / `verifyCode` / `resend` call is in flight. */
+    isSubmitting: boolean;
+    /** The last error, cleared at the start of the next attempt. */
+    error: Error | null;
+    /**
+     * Step 1 — ask the BFF to email a code to `identifier`. On success the flow
+     * advances to `EnterCode`. Rejects (and stays on `RequestCode`) on failure.
+     */
+    requestCode: (identifier: string) => Promise<BffOtpRequestResult>;
+    /**
+     * Step 2 — verify the entered `otp` for the stored identifier. Resolves to the
+     * signed-in `BffUser`; rejects on a bad / expired code (the flow stays on
+     * `EnterCode` so the user can retry or resend).
+     */
+    verifyCode: (otp: string) => Promise<BffUser>;
+    /**
+     * Re-send a code to the stored identifier without leaving `EnterCode`. A
+     * convenience wrapper over `requestOtp` for the step-2 "resend" affordance.
+     */
+    resend: () => Promise<BffOtpRequestResult>;
+    /** Return to step 1 (e.g. the user mistyped their email). Clears the error. */
+    reset: () => void;
+}
+/**
+ * Headless email-OTP login. Returns the current step, the in-flight status, and
+ * `requestCode` / `verifyCode` / `resend` / `reset` callbacks. No rendering —
+ * the consumer (or `<OtpForm>`) wires it to UI.
+ */
+declare function useOtpLogin(options: UseOtpLoginOptions): UseOtpLoginResult;
+
+interface UsePinLoginOptions {
+    /** The same-origin BFF client (build it with `createBffAuthClient`). */
+    client: BffAuthClient;
+    /**
+     * External id of the event the PIN is scoped to. Supplied by the page/route
+     * — the event context is never typed by the user.
+     */
+    eventExternalId: string;
+}
+interface UsePinLoginResult {
+    /** `true` while a `submit` call is in flight. */
+    isSubmitting: boolean;
+    /** The last error, cleared at the start of the next attempt. */
+    error: Error | null;
+    /**
+     * Exchange the entered `pin` (for the hook's `eventExternalId`) for a
+     * session. Resolves to the signed-in `BffUser`; rejects on a bad / expired /
+     * locked-out PIN (the consumer can let the user retry).
+     */
+    submit: (pin: string) => Promise<BffUser>;
+    /** Clear the current error so the form can be retried cleanly. */
+    reset: () => void;
+}
+/**
+ * Headless event-scoped PIN login. Returns the in-flight status, the last
+ * error, and `submit` / `reset` callbacks. No rendering — the consumer (or
+ * `<PinForm>`) wires it to UI.
+ */
+declare function usePinLogin(options: UsePinLoginOptions): UsePinLoginResult;
+
+/**
+ * `createBffAuthClient` — the one-line wiring of a same-origin `BffAuthClient`.
+ *
+ * `BffAuthClient` (from `@dloizides/auth-client`) needs an `HttpClient`. Every
+ * app wired it the same way — `createFetchHttpClient(fetch)` — and every app
+ * hit the same trap: binding `fetch` at module load throws in a non-browser
+ * runtime (the Jest/jsdom test environment has no `fetch` global). The lesson
+ * of Phase 1 was "copy-pasted auth adapters ship the same bug N times", so the
+ * correct wiring lives here once.
+ *
+ * `fetch` is resolved **lazily, per request** — module load stays
+ * side-effect-free. `baseUrl` is omitted by default → same-origin: every
+ * `/bff/*` call goes to the SPA's own host, which is fronted by the per-app
+ * BFF (`bff-katalogos`, `bff-erevna`, ...).
+ *
+ * Extracted + generalised from `apps/katalogos-web/src/auth/bffAuthClient.ts`.
+ */
+
+interface CreateBffAuthClientOptions {
+    /**
+     * BFF origin. Omit (the production default) for same-origin — the SPA's own
+     * host is the BFF. An explicit origin is only useful for a non-same-origin
+     * BFF or for tests.
+     */
+    baseUrl?: string;
+    /**
+     * Override the HTTP transport. Defaults to a lazily-resolved native `fetch`.
+     * Tests pass a fake `HttpClient` here; production never needs to.
+     */
+    http?: HttpClient;
+}
+/**
+ * Build a same-origin `BffAuthClient`. With no arguments this is the exact
+ * production wiring: same-origin, lazy `fetch`, no token handling.
+ */
+declare function createBffAuthClient(options?: CreateBffAuthClientOptions): BffAuthClient;
+
+/**
+ * `resolvePostLoginRoute` — the role-based post-login router helper.
+ *
+ * The unified-auth plan's secondary goal is to kill the "too many login links"
+ * problem (KUCY V2 has seven, one per role). One login surface; after a
+ * successful login the app reads the user's role from the token claims and
+ * routes to the right dashboard.
+ *
+ * This helper is intentionally pure and app-agnostic. The package does NOT
+ * know any app's routes — the consuming app supplies a `RoleRouteTable`
+ * mapping role → path. The helper picks the highest-priority matching role.
+ *
+ * Role priority: a user can hold several roles (`superUser` + `admin` + ...).
+ * The table is consulted in the order its entries are listed — the FIRST
+ * entry whose role the user holds wins. So an app lists the most privileged
+ * role first. A `fallback` covers a user whose roles match no entry.
+ */
+
+/** One role → route mapping. */
+interface RoleRoute {
+    /** The Keycloak role name to match against the user's claims. */
+    role: string;
+    /** The route/path to send a user holding that role to. */
+    route: string;
+}
+/** An app-supplied, ordered role-routing table. */
+interface RoleRouteTable {
+    /**
+     * Ordered list of role → route entries. Order is priority: the first entry
+     * whose `role` the user holds is chosen. List the most privileged role first.
+     */
+    routes: RoleRoute[];
+    /**
+     * Route used when the user holds none of the listed roles. When omitted and
+     * nothing matches, `resolvePostLoginRoute` returns `null` and the caller
+     * decides what to do (e.g. show an "no access" screen).
+     */
+    fallback?: string;
+}
+/**
+ * Collect every role on a `BffUser` — both the flat `roles` array and the
+ * nested `realm_access.roles` — into a de-duplicated set. The BFF may surface
+ * roles in either shape; this normalises both.
+ */
+declare function collectUserRoles(user: BffUser): string[];
+/**
+ * Resolve the post-login route for a user against an app-supplied table.
+ *
+ * Returns the route of the first table entry whose role the user holds; if no
+ * entry matches, returns the table's `fallback`, or `null` when there is none.
+ */
+declare function resolvePostLoginRoute(user: BffUser, table: RoleRouteTable): string | null;
+
+/**
+ * The discrete ways a password can fail the shared client-side policy.
+ *
+ * Each member is the stable key a consuming app maps onto a localised message —
+ * the package never ships translated copy.
+ */
+declare const enum PasswordPolicyError {
+    /** Shorter than `PASSWORD_MIN_LENGTH`. */
+    TooShort = "tooShort",
+    /** Longer than `PASSWORD_MAX_LENGTH`. */
+    TooLong = "tooLong",
+    /** Contains no `A-Z` character. */
+    MissingUppercase = "missingUppercase",
+    /** Contains no `a-z` character. */
+    MissingLowercase = "missingLowercase",
+    /** Contains no `0-9` character. */
+    MissingDigit = "missingDigit"
+}
+
+/**
+ * Client-side password policy that mirrors the backend
+ * (TenantService `ResetPasswordRequestValidator`):
+ *
+ * - 8 ≤ length ≤ 128
+ * - at least one uppercase letter
+ * - at least one lowercase letter
+ * - at least one digit
+ *
+ * Shared so every app's `<ResetPasswordForm>` (and any future password input)
+ * rejects ~99% of bad passwords before a network round-trip. Extracted from
+ * `apps/katalogos-web/src/auth/passwordPolicy.ts`.
+ */
+
+/** Minimum acceptable password length. */
+declare const PASSWORD_MIN_LENGTH = 8;
+/** Maximum acceptable password length. */
+declare const PASSWORD_MAX_LENGTH = 128;
+/**
+ * Return every policy rule the given password violates. An empty array means
+ * the password is acceptable.
+ */
+declare function validatePasswordPolicy(password: string): PasswordPolicyError[];
+/** `true` when the password satisfies every policy rule. */
+declare function isPasswordValid(password: string): boolean;
+
+export { AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type CreateBffAuthClientOptions, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PIN_LABELS, DEFAULT_RESET_PASSWORD_LABELS, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffResetPasswordOptions, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePinLoginOptions, type UsePinLoginResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, collectUserRoles, createBffAuthClient, defaultAuthTheme, isPasswordValid, resolvePostLoginRoute, useAuthTheme, useBffAuth, useBffForgotPassword, useBffResetPassword, useOtpLogin, usePinLogin, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };