@dloizides/auth-web 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## 1.12.0 (2026-07-17)
+
+Completes the demo-credential feature for **BFF-fronted apps**, whose demo pair
+arrives ASYNChronously from `GET /bff/config` rather than a module-level const (a
+const would bake the credentials into a bundle handed to a customer to
+self-deploy). Two gaps closed:
+
+1. `prefillOnMount` was inert for async credentials (1.11.0 bug).
+2. `useBffLoginConfig().config` dropped the `demo` field the BFF now serves.
+
+Requires `@dloizides/auth-client` **>= 4.2.0** (which surfaces `demo` on
+`BffLoginConfig`) — the peer floor is raised accordingly. Additive for existing
+consumers: the new `LoginForm` prop is optional and the synchronous /
+module-const path is byte-identical.
+
+### Fixed
+
+- **`prefillOnMount` now honours credentials that arrive AFTER mount.** `useState`
+  reads its initial argument on the first render only, so a demo pair landing a
+  render later (every BFF app) was silently dropped and the form stayed empty
+  beside a populated hint. `useDemoCredentials` now seeds when the resolved pair
+  transitions to non-null (or to a genuinely different pair), gated by VALUE so a
+  react-query refetch handing back a fresh-but-equal object does not re-seed on a
+  loop.
+
+### Added
+
+- **`config.demo` carries through `useBffLoginConfig`.** `BffLoginConfig` gains
+  `demo?: DemoCredentials | null`, so the intended wiring works end-to-end:
+  ```tsx
+  const { config } = useBffLoginConfig(bffAuthClient);
+  const demo = useDemoCredentials({ credentials: config.demo ?? undefined, prefillOnMount: true });
+  ```
+- **`PrefillIntent`** enum + **`LoginForm` gains `prefillIntent`** — the "don't
+  fight the user" control. An `Opportunistic` re-seed (a late config fetch) is
+  DROPPED unless both fields are still empty, so it never overwrites what a real
+  account holder is typing while `/bff/config` is in flight; an `Explicit` re-seed
+  (the user tapped "use these credentials") always applies. `useDemoCredentials`
+  sets the right intent automatically — most apps never touch this prop.
+- **`DemoCredentials` is now re-exported from `@dloizides/auth-client`** (its
+  canonical owner) rather than defined locally, so there is exactly ONE shape
+  across the two packages. Structurally identical to 1.11.0 — no consumer change.
+
+### "Don't fight the user" — what the hook can and cannot know
+
+`useDemoCredentials` does not own the input fields (`<LoginForm>` does), so it
+cannot observe keystrokes. The interaction test it CAN make is on the field
+values: an opportunistic seed applies only when both fields are still empty
+(pristine). This is intentionally conservative — a user who typed and then
+cleared a field keeps control for the rest of the session (a dropped
+opportunistic bump is not retried). An explicit user request is never subject to
+this test.
+
+## 1.11.0 (2026-07-17)
+
+Additive release adding **public demo-credential support** for products with an
+open, published demo account (Zygos is the first). Purely additive — every 1.10.0
+export is unchanged, and an app that imports none of the new exports renders
+byte-identically: the three new `<LoginForm>` props are all optional and inert
+when omitted.
+
+It fills form fields and nothing else. **No auth bypass**: the demo login travels
+the ordinary path (same BFF, same Keycloak, same session cookie, same roles), and
+no credential ships inside this package — the host supplies the pair.
+
+### Added
+
+- **`<DemoCredentialsHint>`** — a themed panel for the login card showing a
+  published demo username + password with a one-tap "use these credentials"
+  action. Takes the usual `AuthTheme` / `labels` / `testIdPrefix` props. Values
+  render as selectable monospace chips (an `l`/`1` in a published password must
+  not be a guess). Omit `onUse` for a read-only panel.
+
+  **Fails closed**: no credentials — or a half-configured pair (blank username,
+  blank password, or a field that is `undefined` at runtime because an env var
+  was never set) — renders `null`. Zero DOM. A misconfigured demo can never
+  publish an empty credentials panel.
+
+- **`useDemoCredentials({ credentials?, prefillOnMount? })`** — the hint↔form
+  wiring, so no app hand-rolls it. Returns two prop bags to spread:
+  `hintProps` (`{ credentials, onUse }`) and `loginFormProps`
+  (`{ initialUsername, initialPassword, prefillNonce }`).
+
+  `prefillOnMount` (default `false`) makes the form arrive already filled, so
+  signing in as the demo user is a single tap on "Sign in".
+
+- **`resolveDemoCredentials(credentials?)`** — the exported fail-closed gate the
+  above share: returns a trimmed pair, or `null` when there is no usable demo.
+
+- **`DemoCredentials`** type and `DEFAULT_DEMO_CREDENTIALS_HINT_LABELS` /
+  `DemoCredentialsHintLabels` (all copy stays app-supplied, as everywhere else).
+
+- **`<LoginForm>` gains `initialUsername` / `initialPassword` / `prefillNonce`.**
+  The `initial*` props **seed** the fields; they do not own them — every value
+  stays editable and clearable, so a real account holder can always wipe the demo
+  values and sign in with their own. `prefillNonce` is the re-seed signal:
+  changing it re-applies the seed over fields the user has edited or cleared.
+
+  The nonce is not ceremony. `useState` ignores its initial argument on
+  re-render, so a fill button wired to `initialUsername` alone would render a
+  form that stays stubbornly empty — the nonce is what makes "click the hint →
+  form fills" work at all. `useDemoCredentials` manages it for you.
+
+### Internal
+
+- `useLoginPrefill` — extracts `<LoginForm>`'s credential field state (the only
+  part of that component with real logic), so the seed/re-seed contract is unit
+  tested directly rather than through the JSX.
+
 ## 1.10.0 (2026-07-17)
 
 Additive release adding the shared **logout sequencer**. Purely additive — every

package/README.md

@@ -185,6 +185,106 @@ export const katalogosAuthTheme: AuthTheme = {
 Because all three forms share one `useAuthStyles` token-to-style mapping,
 re-theming `<LoginForm>` automatically re-themes the others.
 
+## Public demo credentials — `<DemoCredentialsHint>`
+
+For a product with an OPEN demo account whose credentials are already published
+(typically on the marketing site). It shows the username + password on the login
+card and offers a one-tap fill, so a non-technical evaluator never copy-pastes a
+password between two tabs.
+
+It **fills fields, nothing more.** The login then travels the ordinary path —
+same BFF, same Keycloak, same session cookie, same roles. There is no auth
+bypass and no credential inside this package: the host supplies the pair, and the
+demo account's blast radius is whatever the IdP grants it.
+
+The demo pair comes from the BFF (`GET /bff/config` → `config.demo`), not a
+client const — the BFF is the only thing that knows whether a deployment has a
+demo configured, and a bundled const would ship credentials into every customer's
+self-hosted build. `useBffLoginConfig` already fetches that config, so it also
+carries `demo`. `useDemoCredentials` owns the hint↔form wiring:
+
+```tsx
+import {
+  AuthScreen, DemoCredentialsHint, LoginForm,
+  useBffLoginConfig, useDemoCredentials,
+} from '@dloizides/auth-web';
+
+function LoginScreen() {
+  const { config } = useBffLoginConfig(bffAuthClient);
+  // Credentials arrive ASYNC — prefillOnMount honours a late arrival (see below).
+  const demo = useDemoCredentials({ credentials: config.demo ?? undefined, prefillOnMount: true });
+
+  return (
+    <AuthScreen theme={authTheme}>
+      <DemoCredentialsHint
+        {...demo.hintProps}
+        labels={authLabels.demo}
+        testIdPrefix="zygos"
+        theme={authTheme}
+      />
+      <LoginForm
+        {...demo.loginFormProps}
+        chromeless
+        client={bffAuthClient}
+        labels={authLabels.login}
+        theme={authTheme}
+        onSuccess={handleSignedIn}
+      />
+    </AuthScreen>
+  );
+}
+```
+
+`hintProps` carries `{ credentials, onUse }`; `loginFormProps` carries
+`{ initialUsername, initialPassword, prefillNonce, prefillIntent }`. A module-const
+demo works too — just pass it as `credentials` instead of `config.demo`.
+
+> Requires `@dloizides/auth-client >= 4.2.0`, which surfaces `demo` on
+> `BffLoginConfig` (mapped from the wire's `publishedUsername` /
+> `publishedPassword`). `config.demo` is `DemoCredentials | null`.
+
+### Async credentials: `prefillOnMount` honours a late arrival
+
+Because the pair arrives a render or two after mount, `prefillOnMount` cannot lean
+on `useState`'s initial value (React reads it on the first render only). The hook
+seeds the form when `config.demo` resolves to a usable pair — but as an
+**opportunistic** seed: `<LoginForm>` applies it only while both fields are still
+empty, so a late `/bff/config` response never overwrites a username a real account
+holder was typing meanwhile. Tapping *Use these credentials* is an **explicit**
+seed and always applies. Seeding is gated by value, so a react-query refetch
+returning an equal-valued object does not re-seed. `useDemoCredentials` chooses
+the intent for you via the `prefillIntent` prop; you only touch `PrefillIntent`
+if you drive `<LoginForm>` without the hook.
+
+**`prefillOnMount`** (default `false`) chooses the trade:
+
+| | Fields on arrival | To sign in as the demo user | Cost |
+|---|---|---|---|
+| `false` | empty | tap *Use these credentials*, then *Sign in* | — |
+| `true` | filled | tap *Sign in* | a real account holder must clear two fields first |
+
+Use `true` only on a genuinely public demo surface. The panel renders either way,
+so a visitor can always see *why* the fields are populated.
+
+### It fails closed
+
+No credentials — or a half-configured pair (blank username, blank password, or a
+field that is `undefined` at runtime because an env var was never set) — renders
+**nothing at all**: zero DOM. A misconfigured demo can never publish an empty
+credentials panel. `resolveDemoCredentials` is exported if you need the same
+decision elsewhere.
+
+### The prefill is a seed, not a leash
+
+`initialUsername` / `initialPassword` choose the fields' *starting* value and
+then get out of the way: every field stays editable and clearable, so a real
+account holder can always wipe the demo values and sign in with their own. This
+is why `prefillNonce` exists — React ignores a `useState` initial argument on
+re-render, so changing `initial*` alone does nothing once mounted, and a "fill
+the form" button wired without the nonce would leave the form stubbornly empty.
+`useDemoCredentials` manages it for you; drive it yourself only if you are not
+using the hook.
+
 ## Internationalisation
 
 `@dloizides/auth-web` ships **no** i18n framework. Every user-facing string is
@@ -215,6 +315,8 @@ const route = resolvePostLoginRoute(user, roleRoutes);
 | Export | Kind |
 |--------|------|
 | `LoginForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `OtpForm`, `PinForm` | Components |
+| `AuthScreen`, `DemoCredentialsHint`, `PreferredMethodHint` | Composition + login-surface panels |
+| `useDemoCredentials`, `resolveDemoCredentials`, `DemoCredentials`, `PrefillIntent` | Public demo credentials |
 | `AuthThemeProvider`, `useAuthTheme`, `defaultAuthTheme`, `AuthTheme` | Theming |
 | `DEFAULT_LOGIN_LABELS`, `DEFAULT_FORGOT_PASSWORD_LABELS`, `DEFAULT_RESET_PASSWORD_LABELS`, `DEFAULT_OTP_LABELS`, `DEFAULT_PIN_LABELS` | Label bags |
 | `useBffAuth`, `useBffForgotPassword`, `useBffResetPassword`, `useResetPasswordForm`, `useOtpLogin`, `usePinLogin` | Headless hooks |

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { ReactNode, ReactElement } from 'react';
-import { BffAuthClient, BffUser, HttpClient, BffLoginRequest, BffForgotPasswordRequest, BffResetPasswordRequest, BffOtpRequestResult } 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 { BffAuthClient, BffUser, DemoCredentials, HttpClient, BffLoginRequest, BffForgotPasswordRequest, BffResetPasswordRequest, BffOtpRequestResult } from '@dloizides/auth-client';
+export { BffAuthClient, BffAuthClientOptions, BffForgotPasswordRequest, BffLoginRequest, BffOtpRequestRequest, BffOtpRequestResult, BffOtpVerifyRequest, BffPinLoginRequest, BffRegisterRequest, BffResetPasswordRequest, BffUser, DemoCredentials, HttpClient, HttpRequest, HttpResponse, createFetchHttpClient } from '@dloizides/auth-client';
 import { UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
 
 /**
@@ -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,8 +439,30 @@ 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;
 
+/**
+ * Who asked for a prefill — the difference between "the user requested this" and
+ * "the app offered it".
+ *
+ * A seed that the USER asked for (tapping "use these credentials") must always
+ * apply: they can see the fields, they know what is in them, and they asked
+ * anyway. A seed the APP offers (a demo pair arriving from `GET /bff/config`
+ * mid-typing) must not: it is an unrequested, racing write against a field the
+ * user may already be filling in.
+ *
+ * Collapsing the two into a bare nonce bump is what makes a late-arriving config
+ * fetch overwrite the username a real account holder is halfway through typing.
+ * `<LoginForm>` switches on this, never on a string literal.
+ */
+declare const enum PrefillIntent {
+    /** The user asked for it. Always applies, over whatever is in the fields. */
+    Explicit = "explicit",
+    /** The app offered it. Applies only to untouched, empty fields. */
+    Opportunistic = "opportunistic"
+}
+
 /**
  * `<LoginForm>` — the ready-made, themeable password-login form.
  *
@@ -467,9 +504,35 @@ 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 four, ready to spread.
+     */
+    prefillNonce?: number;
+    /**
+     * Whether the pending re-seed was requested by the user or offered by the app.
+     * An {@link PrefillIntent.Opportunistic} re-seed (e.g. a demo pair arriving
+     * from `GET /bff/config` after mount) is DROPPED unless both fields are still
+     * empty, so a late fetch never overwrites what someone is typing. Defaults to
+     * unconditional — omit it and every nonce bump applies.
+     */
+    prefillIntent?: PrefillIntent;
 }
 /** 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, prefillIntent, }: Readonly<LoginFormProps>): ReactElement;
 
 /**
  * `<ForgotPasswordForm>` — the ready-made, themeable "request a reset link"
@@ -768,6 +831,7 @@ declare const enum DevicePinErrorKey {
  * error) so the unlock / enrol UIs can route on each one rather than collapsing
  * them into a single opaque failure.
  */
+
 /**
  * The per-device half of `GET /bff/config` — what this device remembers about
  * the last user, all fields safe-defaulted by the parser when absent.
@@ -790,6 +854,14 @@ interface BffLoginConfig {
     registrationEnabled: boolean;
     /** The per-device remembered state. */
     deviceState: BffDeviceState;
+    /**
+     * The published demo credentials this deployment advertises, or `null` when
+     * none is configured. Feeds `useDemoCredentials` / `<DemoCredentialsHint>`:
+     * `useDemoCredentials({ credentials: config.demo ?? undefined })`. `auth-client`
+     * 4.2.0 populates it; older clients (and hand-rolled objects) simply omit it,
+     * which reads as `undefined` — treated the same as "no demo" by the hint.
+     */
+    demo?: DemoCredentials | null;
 }
 /**
  * Discriminated result of a device-PIN UNLOCK attempt. The client never rejects;
@@ -1211,6 +1283,50 @@ 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;
 
+/**
+ * `<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 +1432,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 +1938,78 @@ 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;
+    prefillIntent: PrefillIntent;
+}
+/** 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`.
  *
@@ -2061,4 +2253,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 BffLogoutClient, 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, 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 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, 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, 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, PrefillIntent, 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 };