@dloizides/auth-web 1.9.1 → 1.11.0

package/dist/index.d.ts

@@ -391,6 +391,21 @@ interface PreferredMethodHintLabels {
     /** Full sentence shown when the cached preference is passkey. */
     passkey: string;
 }
+/** Strings rendered by `<DemoCredentialsHint>` — the public-demo credentials panel. */
+interface DemoCredentialsHintLabels {
+    /** Panel heading (e.g. "Demo access"). */
+    title: string;
+    /** Copy under the heading explaining what the demo account is. */
+    description: string;
+    /** Row label for the demo username. */
+    usernameLabel: string;
+    /** Row label for the demo password. */
+    passwordLabel: string;
+    /** The "use these credentials" button that fills the login form. */
+    useCredentials: string;
+    /** Accessibility hint for that button. */
+    useCredentialsHint: string;
+}
 /** Strings rendered by `<ResetPasswordForm>`. */
 interface ResetPasswordFormLabels {
     title: string;
@@ -424,6 +439,7 @@ declare const DEFAULT_PASSKEY_LOGIN_LABELS: PasskeyLoginLabels;
 declare const DEFAULT_PASSKEY_SETTINGS_LABELS: PasskeySettingsLabels;
 declare const DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS: PreferredMethodSettingsLabels;
 declare const DEFAULT_PREFERRED_METHOD_HINT_LABELS: PreferredMethodHintLabels;
+declare const DEFAULT_DEMO_CREDENTIALS_HINT_LABELS: DemoCredentialsHintLabels;
 declare const DEFAULT_RESET_PASSWORD_LABELS: ResetPasswordFormLabels;
 
 /**
@@ -467,9 +483,27 @@ interface LoginFormProps {
      * is byte-identical to before.
      */
     chromeless?: boolean;
+    /**
+     * Seeds the username field's INITIAL value. The field stays fully editable and
+     * clearable afterwards — this is a starting value, not a controlled one, so a
+     * real account holder can always wipe it and type their own.
+     */
+    initialUsername?: string;
+    /** Seeds the password field's initial value. Editable + clearable, as above. */
+    initialPassword?: string;
+    /**
+     * Re-seed signal. Changing it re-applies `initialUsername` / `initialPassword`
+     * to the fields even after the user has edited them — needed because React
+     * ignores a `useState` initial value on re-render, so changing the `initial*`
+     * props alone does nothing once mounted.
+     *
+     * Most apps should not manage this by hand: `useDemoCredentials` returns a
+     * `loginFormProps` bag carrying all three, ready to spread.
+     */
+    prefillNonce?: number;
 }
 /** Themeable password-login form built on `useBffAuth`. */
-declare function LoginForm({ client, theme: themeProp, labels: labelsProp, onSuccess, onForgotPassword, onSignUp, testIdPrefix, chromeless, }: Readonly<LoginFormProps>): ReactElement;
+declare function LoginForm({ client, theme: themeProp, labels: labelsProp, onSuccess, onForgotPassword, onSignUp, testIdPrefix, chromeless, initialUsername, initialPassword, prefillNonce, }: Readonly<LoginFormProps>): ReactElement;
 
 /**
  * `<ForgotPasswordForm>` — the ready-made, themeable "request a reset link"
@@ -1211,6 +1245,67 @@ interface PreferredMethodHintProps {
 /** Themeable login-screen preferred-method hint. Renders `null` when there is nothing to say. */
 declare function PreferredMethodHint({ method, theme: themeProp, labels: labelsProp, testIdPrefix, }: Readonly<PreferredMethodHintProps>): ReactElement | null;
 
+/**
+ * Public demo-credential contracts.
+ *
+ * A "demo credential" is a REAL account that a product publishes openly so a
+ * prospective evaluator can sign in without a sign-up step. It is not a bypass:
+ * the credentials travel the ordinary login path (same BFF, same Keycloak, same
+ * session cookie, same roles). The package only makes them *discoverable* and
+ * *one-click fillable* — it never authenticates anything itself.
+ */
+/** A publishable demo username + password pair. */
+interface DemoCredentials {
+    /** The demo account's username. */
+    username: string;
+    /** The demo account's password. */
+    password: string;
+}
+
+/**
+ * `<DemoCredentialsHint>` — the public-demo credentials panel.
+ *
+ * Mount on the login surface of a product with an OPEN demo account whose
+ * credentials are already published (typically on the marketing site). It shows
+ * the username and password and offers a one-tap "use these credentials" action
+ * that fills the form, so a non-technical evaluator never has to copy-paste a
+ * password between two tabs to see the product.
+ *
+ * It authenticates nothing. It fills fields; `<LoginForm>` then submits them
+ * down the ordinary path — same BFF, same Keycloak, same session, same roles.
+ * There is no bypass here and no credential in this package: the host supplies
+ * the pair, and the demo account's blast radius is whatever the IdP grants it.
+ *
+ * Fails closed: no credentials (or a half-configured pair) renders `null` — zero
+ * DOM — so a misconfigured env var can never publish an empty demo panel.
+ *
+ * Compose it as a child of `<AuthScreen>`, above a `chromeless` `<LoginForm>`;
+ * `useDemoCredentials` wires the two together. Read-only mode (no `onUse`) drops
+ * the button and just displays the credentials.
+ */
+
+interface DemoCredentialsHintProps {
+    /**
+     * The demo credentials to advertise. `undefined` — or a pair with a blank
+     * username or password — renders nothing at all.
+     */
+    credentials?: DemoCredentials;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<DemoCredentialsHintLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+    /**
+     * Called with the resolved credentials when the user taps "use these
+     * credentials". Omit to render the panel read-only (no button) — the values
+     * are still selectable, so a visitor can copy them by hand.
+     */
+    onUse?: (credentials: DemoCredentials) => void;
+}
+/** Themeable public-demo credentials panel. Renders `null` when there is no demo. */
+declare function DemoCredentialsHint({ credentials, theme: themeProp, labels: labelsProp, testIdPrefix, onUse, }: Readonly<DemoCredentialsHintProps>): ReactElement | null;
+
 /**
  * React context for the `AuthTheme`.
  *
@@ -1316,6 +1411,10 @@ declare const AuthTestIds: {
     readonly preferredMethodSettingsOption: "auth-preferred-method-settings-option";
     readonly preferredMethodSettingsError: "auth-preferred-method-settings-error";
     readonly preferredMethodHint: "auth-preferred-method-hint";
+    readonly demoCredentialsHint: "auth-demo-credentials-hint";
+    readonly demoCredentialsUsername: "auth-demo-credentials-username";
+    readonly demoCredentialsPassword: "auth-demo-credentials-password";
+    readonly demoCredentialsUseButton: "auth-demo-credentials-use";
 };
 /** Apply an optional prefix to a base test ID. */
 declare function withTestIdPrefix(baseId: string, prefix?: string): string;
@@ -1818,6 +1917,77 @@ interface UsePreferredMethodSettingResult {
 }
 declare function usePreferredMethodSetting({ client, onChanged, }: UsePreferredMethodSettingArgs): UsePreferredMethodSettingResult;
 
+/** Options for {@link useDemoCredentials}. */
+interface UseDemoCredentialsOptions {
+    /**
+     * The demo credentials to advertise. Omit (or pass a half-configured pair) and
+     * the whole surface disappears: the hint renders nothing and the form is never
+     * seeded. See `resolveDemoCredentials`.
+     */
+    credentials?: DemoCredentials;
+    /**
+     * When `true` the form arrives ALREADY filled, so signing in as the demo user
+     * is a single tap on "Sign in" — the hint panel then explains why the fields
+     * are populated and re-fills them if the visitor clears them.
+     *
+     * Defaults to `false`: the fields start empty and the visitor opts in by
+     * tapping "Use these credentials". Prefer the default unless the page is a
+     * genuinely public demo — a login form that arrives pre-filled with someone
+     * else's credentials is confusing on a page real account holders also use.
+     */
+    prefillOnMount?: boolean;
+}
+/** The `<LoginForm>` props that carry the demo prefill. Spread onto the form. */
+interface DemoCredentialsLoginFormProps {
+    initialUsername?: string;
+    initialPassword?: string;
+    prefillNonce: number;
+}
+/** The `<DemoCredentialsHint>` props that carry the credentials + fill action. */
+interface DemoCredentialsHintWiring {
+    credentials?: DemoCredentials;
+    onUse: (credentials: DemoCredentials) => void;
+}
+/** What {@link useDemoCredentials} hands back. */
+interface UseDemoCredentialsResult {
+    /** Spread onto `<LoginForm>`. */
+    loginFormProps: DemoCredentialsLoginFormProps;
+    /** Spread onto `<DemoCredentialsHint>`. */
+    hintProps: DemoCredentialsHintWiring;
+}
+/** Wire a demo-credentials hint to a login form. Returns two prop bags to spread. */
+declare function useDemoCredentials({ credentials, prefillOnMount, }?: Readonly<UseDemoCredentialsOptions>): UseDemoCredentialsResult;
+
+/**
+ * `resolveDemoCredentials` — the single fail-closed gate for the demo surface.
+ *
+ * Every demo affordance in the package (the `<DemoCredentialsHint>` panel and
+ * the `useDemoCredentials` wiring hook) routes its input through this function,
+ * so "should we advertise a demo account at all?" is decided in exactly ONE
+ * place and always the same way.
+ *
+ * Fail closed, deliberately. The realistic source of these values is an env var
+ * (`process.env.EXPO_PUBLIC_DEMO_USERNAME`), which is `string | undefined` at
+ * runtime no matter what the type says — a consumer writing `username: env.X!`
+ * hands us `undefined` and TypeScript never notices. A half-configured demo must
+ * render NOTHING rather than an empty panel inviting a client to sign in with
+ * blank credentials, so anything that is not a genuinely non-empty string pair
+ * resolves to `null`.
+ */
+
+/**
+ * Narrow an unvalidated demo-credential pair to a usable one, or `null`.
+ *
+ * Returns `null` for: `undefined` / `null`, a non-string field (runtime junk
+ * from an unset env var), a blank/whitespace-only username, and an empty
+ * password. Otherwise returns a NEW pair with the username trimmed.
+ *
+ * The password is deliberately NOT trimmed: leading/trailing whitespace can be
+ * a legitimate part of a password, and silently altering it would turn a
+ * working credential into a mystery login failure.
+ */
+declare function resolveDemoCredentials(credentials?: DemoCredentials | null): DemoCredentials | null;
+
 /**
  * `createBffAuthClient` — the one-line wiring of a same-origin `BffAuthClient`.
  *
@@ -1925,6 +2095,97 @@ declare function resolvePostLoginRoute(user: BffUser, table: RoleRouteTable): st
  */
 declare function resolveAccessibleRoutes(user: BffUser, table: RoleRouteTable): RoleRoute[];
 
+/**
+ * `performBffLogout` — the shared logout sequencer.
+ *
+ * Every app hand-rolled its own logout ordering inside its `AuthProvider`, and
+ * the orderings disagreed. Two of them (zygos-web, agora-web) navigated FIRST
+ * and called the BFF second:
+ *
+ * ```ts
+ * redirectTo('/(auth)/login');   // window.location.replace() → document unload
+ * await bffAuthClient.logout();  // races the unload — may never be sent
+ * ```
+ *
+ * That is wrong twice over:
+ *
+ * 1. **The BFF call can be cancelled.** A document navigation kills in-flight
+ *    fetches, so `POST /bff/logout` may never reach the server: the SPA looks
+ *    logged out while the httpOnly session cookie stays ALIVE. The `catch`
+ *    logged it "non-fatal", so the defect was silent.
+ * 2. **The IdP session survives.** `BffAuthClient.logout()` ends the *identity
+ *    provider's* browser session by doing a top-level navigation to the IdP's
+ *    RP-initiated logout URL (only a real navigation carries the IdP's own
+ *    cookie — a back-channel POST cannot clear it). An app that navigates to
+ *    its own login route first pre-empts that navigation, so the IdP still
+ *    considers the user signed in and the next authorize round-trip silently
+ *    re-authenticates them. That is the "sign-out that signs you back in" bug
+ *    the client's own docs warn about.
+ *
+ * This helper owns the whole sequence so neither can be reintroduced per-app:
+ *
+ *   1. `onClearSession()` — drop local state immediately so the UI reflects the
+ *      sign-out right away (perceived performance; no spinner needed).
+ *   2. `await client.logout({ redirect: false })` — let the network call SETTLE,
+ *      and take the IdP logout URL rather than letting the client navigate mid-
+ *      sequence. Errors are captured, never rethrown.
+ *   3. Navigate LAST, exactly once, when nothing is in flight to cancel:
+ *      - an IdP logout URL → a top-level navigation to the IdP, which ends that
+ *        session and bounces the user back. `onRedirect` is deliberately NOT
+ *        called: two competing navigations would race, and the IdP round-trip
+ *        already returns the user to the app.
+ *      - otherwise (ROPC / OTP / device-PIN logins never had an IdP cookie, so
+ *        the URL is `null`) → `onRedirect()`, the app's own login route.
+ *
+ * Step 3 runs even when step 2 rejects: a BFF that is down must not trap the
+ * user on a page they asked to leave. The local session is already gone, so the
+ * client-side sign-out holds regardless.
+ *
+ * Headless and framework-free: it takes callbacks, so an app can pair it with
+ * Redux, a context, expo-router, or `window.location` without this package
+ * knowing about any of them.
+ */
+/**
+ * The only part of a `BffAuthClient` this helper needs. Structural, so it is
+ * trivially fakeable in tests and does not couple to the full client surface.
+ */
+interface BffLogoutClient {
+    /**
+     * `POST /bff/logout` — ends the server-side session. With `redirect: false`
+     * it returns the IdP's RP-initiated logout URL (or `null` when the session
+     * never involved an IdP browser cookie) instead of navigating there itself.
+     */
+    logout: (options?: {
+        redirect?: boolean;
+    }) => Promise<string | null>;
+}
+/** Callbacks + client for {@link performBffLogout}. */
+interface PerformBffLogoutOptions {
+    /** The BFF auth client whose `logout()` ends the server-side session. */
+    client: BffLogoutClient;
+    /** Drop local session state. Runs BEFORE the network call. Optional. */
+    onClearSession?: () => void;
+    /**
+     * Navigate to the app's logged-out route. Runs only AFTER the network call
+     * settles, and only when there is no IdP logout URL to honour. Optional.
+     */
+    onRedirect?: () => void;
+    /** Observe a failed logout step (e.g. to log it). Never rethrown. Optional. */
+    onError?: (error: Error) => void;
+    /**
+     * Test seam: perform the top-level navigation to the IdP logout URL. Defaults
+     * to `window.location.assign`. Must be a real navigation — a `fetch` here
+     * would not carry the IdP cookie and would silently fail to end the session.
+     */
+    navigateToIdp?: (url: string) => void;
+}
+/**
+ * End the session: clear locally, await the BFF, then navigate exactly once.
+ *
+ * Never rejects — callers may `void` it safely.
+ */
+declare function performBffLogout(options: Readonly<PerformBffLogoutOptions>): Promise<void>;
+
 /**
  * The discrete ways a password can fail the shared client-side policy.
  *
@@ -1970,4 +2231,4 @@ declare function validatePasswordPolicy(password: string): PasswordPolicyError[]
 /** `true` when the password satisfies every policy rule. */
 declare function isPasswordValid(password: string): boolean;
 
-export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, PasskeyCeremonyMode, PasskeyCeremonyStatus, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePasskeyCeremonyOptions, type UsePasskeyCeremonyResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePasskeyCeremony, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };
+export { AuthScreen, type AuthScreenProps, AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type BffLogoutClient, type CreateBffAuthClientOptions, DEFAULT_AUTH_CARD_MAX_WIDTH, DEFAULT_DEMO_CREDENTIALS_HINT_LABELS, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DemoCredentials, DemoCredentialsHint, type DemoCredentialsHintLabels, type DemoCredentialsHintProps, type DemoCredentialsHintWiring, type DemoCredentialsLoginFormProps, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, PasskeyCeremonyMode, PasskeyCeremonyStatus, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, type PerformBffLogoutOptions, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDemoCredentialsOptions, type UseDemoCredentialsResult, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePasskeyCeremonyOptions, type UsePasskeyCeremonyResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, performBffLogout, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolveAccessibleRoutes, resolveDemoCredentials, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDemoCredentials, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePasskeyCeremony, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };

package/dist/index.js

@@ -262,6 +262,14 @@ var DEFAULT_PREFERRED_METHOD_HINT_LABELS = {
   pin: "You usually sign in with your quick PIN on this account.",
   passkey: "You usually sign in with a passkey."
 };
+var DEFAULT_DEMO_CREDENTIALS_HINT_LABELS = {
+  title: "Demo access",
+  description: "Explore the full product with our shared demo account.",
+  usernameLabel: "Username",
+  passwordLabel: "Password",
+  useCredentials: "Use these credentials",
+  useCredentialsHint: "Fill the sign-in form with the demo username and password"
+};
 var DEFAULT_RESET_PASSWORD_LABELS = {
   title: "Reset password",
   description: "Choose a new password for your account.",
@@ -350,7 +358,12 @@ var AuthTestIds = {
   preferredMethodSettingsOption: "auth-preferred-method-settings-option",
   preferredMethodSettingsError: "auth-preferred-method-settings-error",
   // Preferred-method login-screen hint
-  preferredMethodHint: "auth-preferred-method-hint"
+  preferredMethodHint: "auth-preferred-method-hint",
+  // Public-demo credentials panel
+  demoCredentialsHint: "auth-demo-credentials-hint",
+  demoCredentialsUsername: "auth-demo-credentials-username",
+  demoCredentialsPassword: "auth-demo-credentials-password",
+  demoCredentialsUseButton: "auth-demo-credentials-use"
 };
 function withTestIdPrefix(baseId, prefix) {
   return prefix === void 0 || prefix === "" ? baseId : `${prefix}-${baseId}`;
@@ -481,6 +494,21 @@ function useAuthStyles(theme) {
     });
   }, [theme]);
 }
+function useLoginPrefill({
+  initialUsername,
+  initialPassword,
+  prefillNonce
+}) {
+  const [username, setUsername] = react.useState(initialUsername ?? "");
+  const [password, setPassword] = react.useState(initialPassword ?? "");
+  const [appliedNonce, setAppliedNonce] = react.useState(prefillNonce);
+  if (prefillNonce !== appliedNonce) {
+    setAppliedNonce(prefillNonce);
+    setUsername(initialUsername ?? "");
+    setPassword(initialPassword ?? "");
+  }
+  return { username, password, setUsername, setPassword };
+}
 var BffAuthStatus = /* @__PURE__ */ ((BffAuthStatus2) => {
   BffAuthStatus2["Loading"] = "loading";
   BffAuthStatus2["Authenticated"] = "authenticated";
@@ -592,7 +620,10 @@ function LoginForm({
   onForgotPassword,
   onSignUp,
   testIdPrefix,
-  chromeless = false
+  chromeless = false,
+  initialUsername,
+  initialPassword,
+  prefillNonce
 }) {
   const theme = useAuthTheme(themeProp);
   const styles3 = useAuthStyles(theme);
@@ -601,8 +632,11 @@ function LoginForm({
     [labelsProp]
   );
   const { login, isSubmitting } = useBffAuth({ client, probeOnMount: false });
-  const [username, setUsername] = react.useState("");
-  const [password, setPassword] = react.useState("");
+  const { username, password, setUsername, setPassword } = useLoginPrefill({
+    initialUsername,
+    initialPassword,
+    prefillNonce
+  });
   const [errorText, setErrorText] = react.useState(null);
   const runLogin = react.useCallback(async () => {
     setErrorText(null);
@@ -3132,6 +3166,156 @@ function PreferredMethodHint({
   }
   return /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { testID: withTestIdPrefix(AuthTestIds.preferredMethodHint, testIdPrefix), children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: styles3.helperText, children: text }) });
 }
+var PANEL_BORDER_WIDTH = 1;
+var ACCENT_RAIL_WIDTH = 3;
+var TITLE_LETTER_SPACING = 0.8;
+var DESCRIPTION_LINE_HEIGHT_RATIO = 1.45;
+var HALF = 2;
+var MONOSPACE_FONT = reactNative.Platform.select({
+  ios: "Menlo",
+  android: "monospace",
+  default: "monospace"
+});
+function useDemoCredentialsStyles(theme) {
+  return react.useMemo(() => {
+    const { colors, radii, spacing, typography } = theme;
+    return reactNative.StyleSheet.create({
+      panel: {
+        borderWidth: PANEL_BORDER_WIDTH,
+        borderLeftWidth: ACCENT_RAIL_WIDTH,
+        borderRadius: radii.card,
+        borderColor: colors.border,
+        borderLeftColor: colors.primary,
+        padding: spacing.md,
+        marginBottom: spacing.md,
+        backgroundColor: colors.background
+      },
+      title: {
+        fontSize: typography.caption,
+        fontWeight: "700",
+        letterSpacing: TITLE_LETTER_SPACING,
+        textTransform: "uppercase",
+        color: colors.primary
+      },
+      description: {
+        fontSize: typography.caption,
+        lineHeight: typography.caption * DESCRIPTION_LINE_HEIGHT_RATIO,
+        marginTop: spacing.xs / HALF,
+        marginBottom: spacing.sm,
+        color: colors.textSecondary
+      },
+      row: {
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-between",
+        marginTop: spacing.xs / HALF
+      },
+      rowLabel: {
+        fontSize: typography.caption,
+        color: colors.textSecondary
+      },
+      rowValue: {
+        fontFamily: MONOSPACE_FONT,
+        fontSize: typography.caption,
+        fontWeight: "600",
+        borderWidth: PANEL_BORDER_WIDTH,
+        borderRadius: radii.input,
+        borderColor: colors.border,
+        paddingVertical: spacing.xs / HALF,
+        paddingHorizontal: spacing.xs,
+        // Never let a long password squeeze the label off the row.
+        flexShrink: 1,
+        backgroundColor: colors.surface,
+        color: colors.text
+      }
+    });
+  }, [theme]);
+}
+
+// src/demo/resolveDemoCredentials.ts
+function resolveDemoCredentials(credentials) {
+  if (credentials === void 0 || credentials === null) {
+    return null;
+  }
+  const username = typeof credentials.username === "string" ? credentials.username.trim() : "";
+  const password = typeof credentials.password === "string" ? credentials.password : "";
+  const isUnusable = username.length === 0 || password.length === 0;
+  if (isUnusable) {
+    return null;
+  }
+  return { username, password };
+}
+function DemoCredentialsHint({
+  credentials,
+  theme: themeProp,
+  labels: labelsProp,
+  testIdPrefix,
+  onUse
+}) {
+  const theme = useAuthTheme(themeProp);
+  const authStyles = useAuthStyles(theme);
+  const styles3 = useDemoCredentialsStyles(theme);
+  const labels = react.useMemo(
+    () => ({ ...DEFAULT_DEMO_CREDENTIALS_HINT_LABELS, ...labelsProp }),
+    [labelsProp]
+  );
+  const resolved = react.useMemo(() => resolveDemoCredentials(credentials), [credentials]);
+  const handleUse = react.useCallback(() => {
+    if (resolved !== null && onUse !== void 0) {
+      onUse(resolved);
+    }
+  }, [resolved, onUse]);
+  if (resolved === null) {
+    return null;
+  }
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    reactNative.View,
+    {
+      style: styles3.panel,
+      testID: withTestIdPrefix(AuthTestIds.demoCredentialsHint, testIdPrefix),
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: styles3.title, children: labels.title }),
+        /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: styles3.description, children: labels.description }),
+        /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: styles3.row, children: [
+          /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: styles3.rowLabel, children: labels.usernameLabel }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            reactNative.Text,
+            {
+              selectable: true,
+              style: styles3.rowValue,
+              testID: withTestIdPrefix(AuthTestIds.demoCredentialsUsername, testIdPrefix),
+              children: resolved.username
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: styles3.row, children: [
+          /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: styles3.rowLabel, children: labels.passwordLabel }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            reactNative.Text,
+            {
+              selectable: true,
+              style: styles3.rowValue,
+              testID: withTestIdPrefix(AuthTestIds.demoCredentialsPassword, testIdPrefix),
+              children: resolved.password
+            }
+          )
+        ] }),
+        onUse !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx(
+          reactNative.TouchableOpacity,
+          {
+            accessibilityHint: labels.useCredentialsHint,
+            accessibilityLabel: labels.useCredentials,
+            accessibilityRole: "button",
+            style: authStyles.secondaryButton,
+            testID: withTestIdPrefix(AuthTestIds.demoCredentialsUseButton, testIdPrefix),
+            onPress: handleUse,
+            children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: authStyles.secondaryButtonText, children: labels.useCredentials })
+          }
+        ) : null
+      ]
+    }
+  );
+}
 var EMPTY_CONFIG = {
   methods: [],
   registrationEnabled: false,
@@ -3237,6 +3421,34 @@ async function syncPreferredMethodFromServer(client) {
     return null;
   }
 }
+function useDemoCredentials({
+  credentials,
+  prefillOnMount = false
+} = {}) {
+  const resolved = react.useMemo(() => resolveDemoCredentials(credentials), [credentials]);
+  const [filled, setFilled] = react.useState(
+    prefillOnMount ? resolved : null
+  );
+  const [prefillNonce, setPrefillNonce] = react.useState(0);
+  const handleUse = react.useCallback((next) => {
+    setFilled(next);
+    setPrefillNonce((current) => current + 1);
+  }, []);
+  return react.useMemo(
+    () => ({
+      loginFormProps: {
+        initialUsername: filled?.username,
+        initialPassword: filled?.password,
+        prefillNonce
+      },
+      // `credentials` is passed through unresolved on purpose: the hint applies
+      // `resolveDemoCredentials` itself, so it fails closed even when it is used
+      // standalone, without this hook.
+      hintProps: { credentials, onUse: handleUse }
+    }),
+    [filled, prefillNonce, credentials, handleUse]
+  );
+}
 async function lazyFetchHttpClient(request) {
   const fetchImpl = typeof fetch === "function" ? fetch.bind(globalThis) : void 0;
   if (fetchImpl === void 0) {
@@ -3286,6 +3498,43 @@ function resolveAccessibleRoutes(user, table) {
   return table.routes.filter((entry) => userRoles.has(entry.role));
 }
 
+// src/session/performBffLogout.ts
+function toError4(caught) {
+  return caught instanceof Error ? caught : new Error(String(caught));
+}
+function runGuarded(callback, onError) {
+  if (callback === void 0) {
+    return;
+  }
+  try {
+    callback();
+  } catch (caught) {
+    onError?.(toError4(caught));
+  }
+}
+function assignLocation(url) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  window.location.assign(url);
+}
+async function performBffLogout(options) {
+  const { client, onClearSession, onRedirect, onError, navigateToIdp = assignLocation } = options;
+  runGuarded(onClearSession, onError);
+  let idpLogoutUrl = null;
+  try {
+    idpLogoutUrl = await client.logout({ redirect: false });
+  } catch (caught) {
+    onError?.(toError4(caught));
+  }
+  if (idpLogoutUrl !== null) {
+    const url = idpLogoutUrl;
+    runGuarded(() => navigateToIdp(url), onError);
+    return;
+  }
+  runGuarded(onRedirect, onError);
+}
+
 Object.defineProperty(exports, "BffAuthClient", {
   enumerable: true,
   get: function () { return authClient.BffAuthClient; }
@@ -3299,6 +3548,7 @@ exports.AuthTestIds = AuthTestIds;
 exports.AuthThemeProvider = AuthThemeProvider;
 exports.BffAuthStatus = BffAuthStatus;
 exports.DEFAULT_AUTH_CARD_MAX_WIDTH = DEFAULT_AUTH_CARD_MAX_WIDTH;
+exports.DEFAULT_DEMO_CREDENTIALS_HINT_LABELS = DEFAULT_DEMO_CREDENTIALS_HINT_LABELS;
 exports.DEFAULT_DEVICE_PIN_ENROLL_LABELS = DEFAULT_DEVICE_PIN_ENROLL_LABELS;
 exports.DEFAULT_DEVICE_PIN_SETTINGS_LABELS = DEFAULT_DEVICE_PIN_SETTINGS_LABELS;
 exports.DEFAULT_DEVICE_PIN_UNLOCK_LABELS = DEFAULT_DEVICE_PIN_UNLOCK_LABELS;
@@ -3314,6 +3564,7 @@ exports.DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS = DEFAULT_PREFERRED_METHOD_SETT
 exports.DEFAULT_RESET_PASSWORD_LABELS = DEFAULT_RESET_PASSWORD_LABELS;
 exports.DEVICE_PIN_ALLOWED_DIGITS = DEVICE_PIN_ALLOWED_DIGITS;
 exports.DEVICE_PIN_DEFAULT_DIGITS = DEVICE_PIN_DEFAULT_DIGITS;
+exports.DemoCredentialsHint = DemoCredentialsHint;
 exports.DevicePinEnrollErrorKey = DevicePinEnrollErrorKey;
 exports.DevicePinEnrollForm = DevicePinEnrollForm;
 exports.DevicePinErrorKey = DevicePinErrorKey;
@@ -3348,10 +3599,12 @@ exports.defaultAuthTheme = defaultAuthTheme;
 exports.isAllowedPinDigits = isAllowedPinDigits;
 exports.isPasswordValid = isPasswordValid;
 exports.isValidForgotPasswordEmail = isValidForgotPasswordEmail;
+exports.performBffLogout = performBffLogout;
 exports.readCachedPreferredMethod = readCachedPreferredMethod;
 exports.readPasskeyError = readPasskeyError;
 exports.readPasskeyRegistered = readPasskeyRegistered;
 exports.resolveAccessibleRoutes = resolveAccessibleRoutes;
+exports.resolveDemoCredentials = resolveDemoCredentials;
 exports.resolvePostLoginRoute = resolvePostLoginRoute;
 exports.startPasskeyLogin = startPasskeyLogin;
 exports.startPasskeyRegistration = startPasskeyRegistration;
@@ -3361,6 +3614,7 @@ exports.useBffAuth = useBffAuth;
 exports.useBffForgotPassword = useBffForgotPassword;
 exports.useBffLoginConfig = useBffLoginConfig;
 exports.useBffResetPassword = useBffResetPassword;
+exports.useDemoCredentials = useDemoCredentials;
 exports.useDevicePinDisable = useDevicePinDisable;
 exports.useDevicePinEnroll = useDevicePinEnroll;
 exports.useDevicePinUnlock = useDevicePinUnlock;