@dloizides/auth-web 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # 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

package/README.md

@@ -197,16 +197,22 @@ 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.
 
-`useDemoCredentials` owns the wiring, so apps don't hand-roll 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, useDemoCredentials } from '@dloizides/auth-web';
-
-// Hoisted (or memoised): a new object each render re-creates the prop bags.
-const DEMO = { username: 'demo', password: 'ZygosDemo!2026.Try' };
+import {
+  AuthScreen, DemoCredentialsHint, LoginForm,
+  useBffLoginConfig, useDemoCredentials,
+} from '@dloizides/auth-web';
 
 function LoginScreen() {
-  const demo = useDemoCredentials({ credentials: DEMO, prefillOnMount: true });
+  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}>
@@ -219,7 +225,7 @@ function LoginScreen() {
       <LoginForm
         {...demo.loginFormProps}
         chromeless
-        client={client}
+        client={bffAuthClient}
         labels={authLabels.login}
         theme={authTheme}
         onSuccess={handleSignedIn}
@@ -230,7 +236,25 @@ function LoginScreen() {
 ```
 
 `hintProps` carries `{ credentials, onUse }`; `loginFormProps` carries
-`{ initialUsername, initialPassword, prefillNonce }`.
+`{ 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:
 
@@ -292,7 +316,7 @@ const route = resolvePostLoginRoute(user, roleRoutes);
 |--------|------|
 | `LoginForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `OtpForm`, `PinForm` | Components |
 | `AuthScreen`, `DemoCredentialsHint`, `PreferredMethodHint` | Composition + login-surface panels |
-| `useDemoCredentials`, `resolveDemoCredentials`, `DemoCredentials` | Public demo credentials |
+| `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';
 
 /**
@@ -442,6 +442,27 @@ 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.
  *
@@ -498,12 +519,20 @@ interface LoginFormProps {
      * 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.
+     * `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, initialUsername, initialPassword, prefillNonce, }: 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"
@@ -802,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.
@@ -824,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;
@@ -1245,23 +1283,6 @@ 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.
  *
@@ -1942,6 +1963,7 @@ interface DemoCredentialsLoginFormProps {
     initialUsername?: string;
     initialPassword?: string;
     prefillNonce: number;
+    prefillIntent: PrefillIntent;
 }
 /** The `<DemoCredentialsHint>` props that carry the credentials + fill action. */
 interface DemoCredentialsHintWiring {
@@ -2231,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_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 };
+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 };

package/dist/index.d.ts

@@ -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';
 
 /**
@@ -442,6 +442,27 @@ 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.
  *
@@ -498,12 +519,20 @@ interface LoginFormProps {
      * 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.
+     * `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, initialUsername, initialPassword, prefillNonce, }: 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"
@@ -802,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.
@@ -824,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;
@@ -1245,23 +1283,6 @@ 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.
  *
@@ -1942,6 +1963,7 @@ interface DemoCredentialsLoginFormProps {
     initialUsername?: string;
     initialPassword?: string;
     prefillNonce: number;
+    prefillIntent: PrefillIntent;
 }
 /** The `<DemoCredentialsHint>` props that carry the credentials + fill action. */
 interface DemoCredentialsHintWiring {
@@ -2231,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_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 };
+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 };

package/dist/index.js

@@ -494,18 +494,32 @@ function useAuthStyles(theme) {
     });
   }, [theme]);
 }
+
+// src/components/PrefillIntent.ts
+var PrefillIntent = /* @__PURE__ */ ((PrefillIntent2) => {
+  PrefillIntent2["Explicit"] = "explicit";
+  PrefillIntent2["Opportunistic"] = "opportunistic";
+  return PrefillIntent2;
+})(PrefillIntent || {});
+
+// src/components/useLoginPrefill.ts
 function useLoginPrefill({
   initialUsername,
   initialPassword,
-  prefillNonce
+  prefillNonce,
+  prefillIntent
 }) {
   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 ?? "");
+    const isPristine = username.length === 0 && password.length === 0;
+    const mayApply = prefillIntent !== "opportunistic" /* Opportunistic */ || isPristine;
+    if (mayApply) {
+      setUsername(initialUsername ?? "");
+      setPassword(initialPassword ?? "");
+    }
   }
   return { username, password, setUsername, setPassword };
 }
@@ -623,7 +637,8 @@ function LoginForm({
   chromeless = false,
   initialUsername,
   initialPassword,
-  prefillNonce
+  prefillNonce,
+  prefillIntent
 }) {
   const theme = useAuthTheme(themeProp);
   const styles3 = useAuthStyles(theme);
@@ -635,7 +650,8 @@ function LoginForm({
   const { username, password, setUsername, setPassword } = useLoginPrefill({
     initialUsername,
     initialPassword,
-    prefillNonce
+    prefillNonce,
+    prefillIntent
   });
   const [errorText, setErrorText] = react.useState(null);
   const runLogin = react.useCallback(async () => {
@@ -3324,7 +3340,8 @@ var EMPTY_CONFIG = {
     hasPin: false,
     pinDigits: null,
     preferredMethod: null
-  }
+  },
+  demo: null
 };
 function useBffLoginConfig(client) {
   const [config, setConfig] = react.useState(EMPTY_CONFIG);
@@ -3421,6 +3438,12 @@ async function syncPreferredMethodFromServer(client) {
     return null;
   }
 }
+function isSamePair(a, b) {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return a.username === b.username && a.password === b.password;
+}
 function useDemoCredentials({
   credentials,
   prefillOnMount = false
@@ -3430,23 +3453,38 @@ function useDemoCredentials({
     prefillOnMount ? resolved : null
   );
   const [prefillNonce, setPrefillNonce] = react.useState(0);
+  const [prefillIntent, setPrefillIntent] = react.useState(
+    "opportunistic" /* Opportunistic */
+  );
+  const [autoSeeded, setAutoSeeded] = react.useState(
+    prefillOnMount ? resolved : null
+  );
+  const shouldAutoSeed = prefillOnMount && resolved !== null && !isSamePair(resolved, autoSeeded);
+  if (shouldAutoSeed) {
+    setAutoSeeded(resolved);
+    setFilled(resolved);
+    setPrefillNonce((current) => current + 1);
+    setPrefillIntent("opportunistic" /* Opportunistic */);
+  }
   const handleUse = react.useCallback((next) => {
     setFilled(next);
     setPrefillNonce((current) => current + 1);
+    setPrefillIntent("explicit" /* Explicit */);
   }, []);
   return react.useMemo(
     () => ({
       loginFormProps: {
         initialUsername: filled?.username,
         initialPassword: filled?.password,
-        prefillNonce
+        prefillNonce,
+        prefillIntent
       },
       // `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]
+    [filled, prefillNonce, prefillIntent, credentials, handleUse]
   );
 }
 async function lazyFetchHttpClient(request) {
@@ -3588,6 +3626,7 @@ exports.PasswordPolicyError = PasswordPolicyError;
 exports.PinForm = PinForm;
 exports.PreferredMethodHint = PreferredMethodHint;
 exports.PreferredMethodSettingsCard = PreferredMethodSettingsCard;
+exports.PrefillIntent = PrefillIntent;
 exports.ResetPasswordError = ResetPasswordError;
 exports.ResetPasswordForm = ResetPasswordForm;
 exports.cachePreferredMethod = cachePreferredMethod;