@dloizides/auth-client 3.2.1 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 3.3.0 (2026-06-02)
+
+Additive release for unified-login Increment 3 — device-bound PIN unlock +
+`/bff/config`. Extracts kefi-web's proven device-PIN client (the "second use"),
+giving `@dloizides/auth-web` 1.4.0 a shared same-origin client with
+**discriminated** results. The published `login` / `pinLogin` throw an opaque
+error on any non-2xx, collapsing 401 (wrong PIN) and 429 (locked / rate-limited);
+the new device-PIN methods never throw and route on a discriminated `status`
+instead. No breaking changes.
+
+### Added
+
+- `BffAuthClient.getLoginConfig()` → `GET /bff/config`. Returns the advertised
+  login methods (lowercase, de-duplicated), `registrationEnabled`, and the
+  optional per-device state (`rememberedUsername`, `hasPin`, `pinDigits`,
+  `preferredMethod`). NEVER throws — on a non-2xx, a network error, or a
+  malformed body it returns a safe fallback (`['password']`, registration off,
+  empty device-state). Unauthenticated, no CSRF (GET).
+- `BffAuthClient.enrollDevicePin({ pin, digits })` → `POST /bff/pin/enroll`.
+  Discriminated `DevicePinEnrollResult`: `success` (200), `unauthorized` (401),
+  `forbidden` (403, PIN-established session), `invalidPin` (400), `error`
+  (anything else / network). Never throws.
+- `BffAuthClient.unlockWithDevicePin({ pin })` → `POST /bff/pin/unlock`.
+  Discriminated `DevicePinUnlockResult`: `success` + `user` (200), `invalid`
+  (401), `locked` (429 **with** a JSON body — device lockout), `rateLimited`
+  (429 with an **empty** body — per-IP limiter), `error` (anything else /
+  malformed 200 / network). Both 429 variants carry the parsed `Retry-After`
+  seconds (`null` when absent / unparseable). Never throws. Distinguishing
+  `locked` vs `rateLimited` lets UIs poll through rate limits but show lockout
+  copy.
+- `BffAuthClient.disableDevicePin()` → `POST /bff/pin/disable`. `true` on a 2xx,
+  `false` otherwise. Never throws.
+- Types: `BffLoginConfig`, `BffDeviceState`, `BffDevicePinEnrollRequest`,
+  `BffDevicePinUnlockRequest`, `DevicePinUnlockResult`, `DevicePinEnrollResult`.
+- `HttpResponse.header?(name)` — an optional, case-insensitive response-header
+  accessor (the bundled `createFetchHttpClient` always provides it). Needed to
+  read `Retry-After` off the unlock `429`. Backward-compatible (optional).
+
 ## 3.2.0 (2026-05-22)
 
 Additive release for Phase 3d of the unified-auth plan — event-scoped PIN

package/README.md

@@ -151,6 +151,43 @@ await bff.resetPassword({ token, newPassword });
 await bff.logout();
 ```
 
+### Device-bound PIN unlock (v3.3 — unified-login Increment 3)
+
+A returning, remembered-device, logged-OUT user can re-establish a session with a
+4/6/8-digit device PIN. Unlike `login` / `pinLogin` (which throw an opaque error on
+any non-2xx), the device-PIN methods **never throw** — they return discriminated
+results so the UI can route on `status`.
+
+```ts
+// Which methods does this BFF advertise + does this device remember a PIN?
+// NEVER throws — safe fallback (['password'], registration off) on any failure.
+const config = await bff.getLoginConfig();
+if (config.deviceState.hasPin) {
+  /* render the device-PIN unlock screen */
+}
+
+// Bind a PIN to the current strong session.
+const enroll = await bff.enrollDevicePin({ pin: '482913', digits: 6 });
+// status: 'success' | 'unauthorized' | 'forbidden' | 'invalidPin' | 'error'
+
+// Re-establish a session from a remembered device.
+const unlock = await bff.unlockWithDevicePin({ pin: '482913' });
+switch (unlock.status) {
+  case 'success':     /* unlock.user — a session cookie was set */ break;
+  case 'invalid':     /* wrong PIN / unknown-or-revoked device */ break;
+  case 'locked':      /* device lockout — unlock.retryAfterSeconds */ break;
+  case 'rateLimited': /* per-IP limiter — may poll through it */ break;
+  case 'error':       /* network / unexpected */ break;
+}
+
+await bff.disableDevicePin(); // true on success, never throws
+```
+
+The two `429` outcomes are distinct on purpose: the per-IP `BffAuth` limiter
+answers `429` with an **empty** body (`rateLimited` — a UI may poll through it),
+whereas the device-PIN lockout answers `429` with a JSON `{ error }` body + a
+`Retry-After` header (`locked` — show a "try again in N s" message).
+
 The direct-KC `AuthClient` / ROPC surface below is retained for consumers not
 yet on a BFF; it is deprecated and removed once every app has migrated.
 
@@ -191,7 +228,7 @@ auth.on('sessionExpired', () => {
 
 ### Core (`@dloizides/auth-client`)
 
-- `BffAuthClient` — same-origin client for a per-app Backend-For-Frontend. `login()`, `logout()`, `getCurrentUser()`, `register()`, `forgotPassword()`, `resetPassword()`. No token handling — the BFF owns tokens, the browser owns only an httpOnly cookie. **The recommended auth surface (v3).**
+- `BffAuthClient` — same-origin client for a per-app Backend-For-Frontend. `login()`, `logout()`, `getCurrentUser()`, `register()`, `forgotPassword()`, `resetPassword()`, `requestOtp()`, `verifyOtp()`, `pinLogin()`, plus the v3.3 device-PIN surface: `getLoginConfig()`, `enrollDevicePin()`, `unlockWithDevicePin()`, `disableDevicePin()` (discriminated, never-throwing results). No token handling — the BFF owns tokens, the browser owns only an httpOnly cookie. **The recommended auth surface (v3).**
 - `AuthClient` — realm-aware orchestrator. `init()`, `refresh()`, `loginWithOtp()`, `loginWithPassword()`, `logout({ everywhere })`, `requestPasswordReset()`, `confirmPasswordReset()`, plus the v1 surface (`getAccessToken`, `getTokens`, `setTokens`, `clearTokens`, `buildAuthorizationUrl`, etc.). Direct-KC ROPC; deprecated in favour of `BffAuthClient`.
 - `AuthApiClient` — typed wrapper for IdentityService auth endpoints.
 - `AuthEventEmitter` — `sessionExpired` event.

package/dist/{AuthClient-D8Ul-aGa.d.mts → AuthClient-3lu6Y1bY.d.mts}

@@ -1,4 +1,4 @@
-import { H as HttpClient, T as TokenResponse } from './TokenResponse-CY1CaU2l.mjs';
+import { H as HttpClient, T as TokenResponse } from './TokenResponse-BkIDjenX.mjs';
 
 /**
  * Tiny dependency-free event emitter for auth lifecycle events.

package/dist/{AuthClient-Cv7btBX0.d.ts → AuthClient-Bb7N2shJ.d.ts}

@@ -1,4 +1,4 @@
-import { H as HttpClient, T as TokenResponse } from './TokenResponse-CY1CaU2l.js';
+import { H as HttpClient, T as TokenResponse } from './TokenResponse-BkIDjenX.js';
 
 /**
  * Tiny dependency-free event emitter for auth lifecycle events.

package/dist/{TokenResponse-CY1CaU2l.d.mts → TokenResponse-BkIDjenX.d.mts}

@@ -20,6 +20,13 @@ interface HttpResponse {
     ok: boolean;
     /** Parsed body (already JSON-decoded). `undefined` for 204 / empty bodies. */
     data?: unknown;
+    /**
+     * Read a single response header by (case-insensitive) name, or `null` when
+     * absent. Optional so existing transports stay source-compatible; the bundled
+     * `createFetchHttpClient` always provides it. The device-PIN unlock flow needs
+     * it to read `Retry-After` off a `429`.
+     */
+    header?: (name: string) => string | null;
 }
 type HttpClient = (request: HttpRequest) => Promise<HttpResponse>;
 /**

package/dist/{TokenResponse-CY1CaU2l.d.ts → TokenResponse-BkIDjenX.d.ts}

@@ -20,6 +20,13 @@ interface HttpResponse {
     ok: boolean;
     /** Parsed body (already JSON-decoded). `undefined` for 204 / empty bodies. */
     data?: unknown;
+    /**
+     * Read a single response header by (case-insensitive) name, or `null` when
+     * absent. Optional so existing transports stay source-compatible; the bundled
+     * `createFetchHttpClient` always provides it. The device-PIN unlock flow needs
+     * it to read `Retry-After` off a `429`.
+     */
+    header?: (name: string) => string | null;
 }
 type HttpClient = (request: HttpRequest) => Promise<HttpResponse>;
 /**

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { T as TokenStorage, k as AuthTokens } from './AuthClient-D8Ul-aGa.mjs';
-export { A as AuthApiClient, a as AuthApiClientOptions, b as AuthClient, c as AuthClientCollaborators, d as AuthClientConfig, e as AuthClientFromIssuerInput, f as AuthEventEmitter, g as AuthEventListener, h as AuthEventName, i as AuthEventUnsubscribe, j as AuthSessionInfo, D as DirectKcOptions, F as ForgotPasswordRequest, I as InactivityStore, l as InactivityTracker, m as InactivityTrackerOptions, L as LoginOptions, n as LogoutOptions, O as OtpLoginRequest, P as PasswordLoginRequest, R as RawAuthLoginResponse, o as RefreshFn, p as RefreshInterceptor, q as RefreshInterceptorOptions, r as ResetPasswordRequest } from './AuthClient-D8Ul-aGa.mjs';
+import { T as TokenStorage, k as AuthTokens } from './AuthClient-3lu6Y1bY.mjs';
+export { A as AuthApiClient, a as AuthApiClientOptions, b as AuthClient, c as AuthClientCollaborators, d as AuthClientConfig, e as AuthClientFromIssuerInput, f as AuthEventEmitter, g as AuthEventListener, h as AuthEventName, i as AuthEventUnsubscribe, j as AuthSessionInfo, D as DirectKcOptions, F as ForgotPasswordRequest, I as InactivityStore, l as InactivityTracker, m as InactivityTrackerOptions, L as LoginOptions, n as LogoutOptions, O as OtpLoginRequest, P as PasswordLoginRequest, R as RawAuthLoginResponse, o as RefreshFn, p as RefreshInterceptor, q as RefreshInterceptorOptions, r as ResetPasswordRequest } from './AuthClient-3lu6Y1bY.mjs';
 export { ExchangeAuthorizationCodeInput, FetchDiscoveryDocumentInput, OidcDiscoveryDocument, PkcePair, RefreshAccessTokenInput, clearDiscoveryCache, deriveCodeChallenge, exchangeAuthorizationCode, fetchDiscoveryDocument, generateCodeVerifier, generatePkcePair, refreshAccessToken } from './oidc/index.mjs';
-import { H as HttpClient, R as RawTokenResponse, T as TokenResponse } from './TokenResponse-CY1CaU2l.mjs';
-export { a as HttpRequest, b as HttpResponse, c as createFetchHttpClient } from './TokenResponse-CY1CaU2l.mjs';
+import { H as HttpClient, R as RawTokenResponse, T as TokenResponse } from './TokenResponse-BkIDjenX.mjs';
+export { a as HttpRequest, b as HttpResponse, c as createFetchHttpClient } from './TokenResponse-BkIDjenX.mjs';
 
 /**
  * Roles emitted by Keycloak realms in the dloizides.com portfolio.
@@ -372,6 +372,98 @@ interface BffPinLoginRequest {
     /** External id of the event the PIN is scoped to (supplied by the page/route). */
     eventExternalId: string;
 }
+/** Payload for `POST /bff/pin/enroll` — bind a device PIN to the current session. */
+interface BffDevicePinEnrollRequest {
+    /** The numeric PIN the user chose. */
+    pin: string;
+    /** The chosen PIN length (must be one of 4 / 6 / 8). */
+    digits: number;
+}
+/** Payload for `POST /bff/pin/unlock` — re-establish a session from a remembered device. */
+interface BffDevicePinUnlockRequest {
+    /** The numeric device PIN the returning user entered. */
+    pin: string;
+}
+/**
+ * The optional per-device state half of `GET /bff/config`, all fields safe-defaulted.
+ *
+ * Read off the BFF's per-device record (keyed by the device cookie). Older BFFs /
+ * tests omit the fields entirely, in which case the PIN-unlock gate simply never
+ * triggers (`hasPin` defaults to `false`, `rememberedUsername` to `null`).
+ */
+interface BffDeviceState {
+    /** Non-secret username this device remembers, or `null` when none. */
+    rememberedUsername: string | null;
+    /** `true` when this device has an enrolled device PIN. */
+    hasPin: boolean;
+    /** The enrolled PIN length (4 / 6 / 8), or `null` when unknown / no PIN. */
+    pinDigits: number | null;
+    /** The device-local preferred-method hint (e.g. `"pin"`), or `null`. */
+    preferredMethod: string | null;
+}
+/**
+ * The parsed `GET /bff/config` response: which login methods this BFF advertises,
+ * whether self-serve registration is enabled, and the optional per-device state.
+ *
+ * `methods` are the lowercase strings the server-side `BffLoginMethod` enum
+ * serialises to (`"password"` | `"otp"` | `"pin"` | `"passkey"`), de-duplicated
+ * and order-preserving. On a network failure or malformed body the client returns
+ * a safe fallback (`["password"]`, registration off, empty device-state).
+ */
+interface BffLoginConfig {
+    /** The enabled login methods, lowercase, in the order the BFF advertised them. */
+    methods: string[];
+    /** `true` when this BFF exposes self-serve registration. */
+    registrationEnabled: boolean;
+    /** The optional per-device state (remembered username + device PIN), safe-defaulted. */
+    deviceState: BffDeviceState;
+}
+/**
+ * Discriminated result of `unlockWithDevicePin`. Never rejects — the unlock UI
+ * routes on `status` (the published `login`/`pinLogin` throw an opaque error on
+ * any non-2xx, collapsing 401 vs 429; this is why the device-PIN flow needs its
+ * own client surface).
+ *
+ * The two `429` outcomes are distinct and MUST stay distinct: the BFF's per-IP
+ * `BffAuth` sliding-window limiter answers `429` with an EMPTY body
+ * (`rateLimited` — the UI may poll through it), whereas the device-PIN lockout
+ * answers `429` with a JSON `{ error }` body + a `Retry-After` header (`locked` —
+ * the UI shows a "try again in N s" message).
+ */
+type DevicePinUnlockResult = {
+    status: 'success';
+    user: BffUser;
+} | {
+    status: 'invalid';
+} | {
+    status: 'locked';
+    retryAfterSeconds: number | null;
+} | {
+    status: 'rateLimited';
+    retryAfterSeconds: number | null;
+} | {
+    status: 'error';
+};
+/**
+ * Discriminated result of `enrollDevicePin`. Never rejects — the enrol form routes
+ * on `status`:
+ *  - `success`      — HTTP 200, the device PIN is bound to the current session;
+ *  - `unauthorized` — HTTP 401, no session to bind to;
+ *  - `forbidden`    — HTTP 403, a PIN-established session can't enrol a new PIN;
+ *  - `invalidPin`   — HTTP 400, the PIN format was rejected;
+ *  - `error`        — anything else (501 disabled / 502 grant failed / network).
+ */
+type DevicePinEnrollResult = {
+    status: 'success';
+} | {
+    status: 'unauthorized';
+} | {
+    status: 'forbidden';
+} | {
+    status: 'invalidPin';
+} | {
+    status: 'error';
+};
 /**
  * The body `POST /bff/otp/request` relays from TenantService.
  *
@@ -484,6 +576,58 @@ declare class BffAuthClient {
      * is not an enabled method for this BFF.
      */
     pinLogin(request: BffPinLoginRequest): Promise<BffUser>;
+    /**
+     * `GET /bff/config` — which login methods this BFF advertises, whether
+     * registration is enabled, and the optional per-device state (remembered
+     * username + device PIN). Unauthenticated, no CSRF (GET).
+     *
+     * NEVER throws: on a non-2xx, a network error, or a malformed body it returns
+     * a safe fallback (`{ methods: ['password'], registrationEnabled: false,
+     * deviceState: { rememberedUsername: null, hasPin: false, pinDigits: null,
+     * preferredMethod: null } }`) so the login surface stays usable even when the
+     * config endpoint is unreachable.
+     */
+    getLoginConfig(): Promise<BffLoginConfig>;
+    /**
+     * `POST /bff/pin/enroll` — bind a device PIN to the CURRENT strong session.
+     * Requires an authenticated session (the cookie travels via
+     * `credentials: 'include'`); the BFF requests an offline token, hashes the
+     * PIN, and sets the device cookie.
+     *
+     * NEVER throws — resolves a discriminated {@link DevicePinEnrollResult}:
+     *  - 200 → `success`;
+     *  - 401 → `unauthorized` (no session);
+     *  - 403 → `forbidden` (a PIN-established session can't enrol);
+     *  - 400 → `invalidPin` (bad format);
+     *  - anything else (501 disabled / 502 grant failed) / network → `error`.
+     */
+    enrollDevicePin(request: BffDevicePinEnrollRequest): Promise<DevicePinEnrollResult>;
+    /**
+     * `POST /bff/pin/unlock` — re-establish a session from a remembered device.
+     * No prior session; the device cookie travels via `credentials: 'include'`.
+     *
+     * NEVER throws — resolves a discriminated {@link DevicePinUnlockResult}:
+     *  - 200 + `{ user }` → `success` (a session cookie was set);
+     *  - 401             → `invalid` (wrong PIN / unknown-or-revoked device);
+     *  - 429 + JSON body → `locked` (device lockout; `Retry-After` parsed);
+     *  - 429 + empty body → `rateLimited` (per-IP limiter; `Retry-After` parsed);
+     *  - anything else / malformed 200 body / network → `error`.
+     */
+    unlockWithDevicePin(request: BffDevicePinUnlockRequest): Promise<DevicePinUnlockResult>;
+    /**
+     * `POST /bff/pin/disable` — drop the device PIN for the CURRENT session. The
+     * BFF revokes the offline token at Keycloak, deletes the device record, and
+     * clears the device cookie. Requires an authenticated session.
+     *
+     * NEVER throws — resolves `true` on a 2xx, `false` on anything else.
+     */
+    disableDevicePin(): Promise<boolean>;
+    /**
+     * Shared POST for the never-throw device-PIN calls: same-origin, cookie
+     * included, `X-BFF-Csrf` header attached. Returns the raw {@link HttpResponse}
+     * (status + body + headers) so the caller can route on it instead of throwing.
+     */
+    private postRaw;
     /**
      * Shared POST for every state-changing `/bff/*` call: same-origin, cookie
      * included, `X-BFF-Csrf` header attached. Throws a labelled error on non-2xx.
@@ -664,4 +808,4 @@ declare function normalizeTokenResponse(raw: RawTokenResponse): TokenResponse;
  */
 declare function tokenResponseToAuthTokens(response: TokenResponse, now?: number): AuthTokens;
 
-export { AuthTokens, type AuthorizationCodeBodyInput, type AuthorizationResponseLike, type AuthorizationUrlInput, BffAuthClient, type BffAuthClientOptions, type BffForgotPasswordRequest, type BffLoginRequest, type BffOtpRequestRequest, type BffOtpRequestResult, type BffOtpVerifyRequest, type BffPinLoginRequest, type BffRegisterRequest, type BffResetPasswordRequest, type BffUser, type BiometricFlagStore, BiometricGate, type BiometricGateLike, type BiometricGateOptions, BrowserStorageTokenStorage, type BrowserStorageTokenStorageOptions, CookieTokenStorage, HttpClient, InMemoryTokenStorage, KeycloakRoles, type KeycloakUserInfo, type LocalAuthLike, type NormalizedUser, RawTokenResponse, type RefreshTokenBodyInput, type SecureStoreLike, SecureStoreTokenStorage, type SecureStoreTokenStorageOptions, type StorageLike, TokenResponse, TokenStorage, buildAuthorizationCodeBody, buildAuthorizationEndpoint, buildAuthorizationUrl, buildIssuerUrl, buildLogoutEndpoint, buildRefreshTokenBody, buildTokenEndpoint, buildUserInfoEndpoint, computeExpiresAt, decodeJwt, extractAuthCode, isKeycloakRole, isTokenExpired, normalizeKeycloakUser, normalizeTokenResponse, parseBaseUrlFromIssuer, parseRealmFromIssuer, tokenResponseToAuthTokens };
+export { AuthTokens, type AuthorizationCodeBodyInput, type AuthorizationResponseLike, type AuthorizationUrlInput, BffAuthClient, type BffAuthClientOptions, type BffDevicePinEnrollRequest, type BffDevicePinUnlockRequest, type BffDeviceState, type BffForgotPasswordRequest, type BffLoginConfig, type BffLoginRequest, type BffOtpRequestRequest, type BffOtpRequestResult, type BffOtpVerifyRequest, type BffPinLoginRequest, type BffRegisterRequest, type BffResetPasswordRequest, type BffUser, type BiometricFlagStore, BiometricGate, type BiometricGateLike, type BiometricGateOptions, BrowserStorageTokenStorage, type BrowserStorageTokenStorageOptions, CookieTokenStorage, type DevicePinEnrollResult, type DevicePinUnlockResult, HttpClient, InMemoryTokenStorage, KeycloakRoles, type KeycloakUserInfo, type LocalAuthLike, type NormalizedUser, RawTokenResponse, type RefreshTokenBodyInput, type SecureStoreLike, SecureStoreTokenStorage, type SecureStoreTokenStorageOptions, type StorageLike, TokenResponse, TokenStorage, buildAuthorizationCodeBody, buildAuthorizationEndpoint, buildAuthorizationUrl, buildIssuerUrl, buildLogoutEndpoint, buildRefreshTokenBody, buildTokenEndpoint, buildUserInfoEndpoint, computeExpiresAt, decodeJwt, extractAuthCode, isKeycloakRole, isTokenExpired, normalizeKeycloakUser, normalizeTokenResponse, parseBaseUrlFromIssuer, parseRealmFromIssuer, tokenResponseToAuthTokens };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { T as TokenStorage, k as AuthTokens } from './AuthClient-Cv7btBX0.js';
-export { A as AuthApiClient, a as AuthApiClientOptions, b as AuthClient, c as AuthClientCollaborators, d as AuthClientConfig, e as AuthClientFromIssuerInput, f as AuthEventEmitter, g as AuthEventListener, h as AuthEventName, i as AuthEventUnsubscribe, j as AuthSessionInfo, D as DirectKcOptions, F as ForgotPasswordRequest, I as InactivityStore, l as InactivityTracker, m as InactivityTrackerOptions, L as LoginOptions, n as LogoutOptions, O as OtpLoginRequest, P as PasswordLoginRequest, R as RawAuthLoginResponse, o as RefreshFn, p as RefreshInterceptor, q as RefreshInterceptorOptions, r as ResetPasswordRequest } from './AuthClient-Cv7btBX0.js';
+import { T as TokenStorage, k as AuthTokens } from './AuthClient-Bb7N2shJ.js';
+export { A as AuthApiClient, a as AuthApiClientOptions, b as AuthClient, c as AuthClientCollaborators, d as AuthClientConfig, e as AuthClientFromIssuerInput, f as AuthEventEmitter, g as AuthEventListener, h as AuthEventName, i as AuthEventUnsubscribe, j as AuthSessionInfo, D as DirectKcOptions, F as ForgotPasswordRequest, I as InactivityStore, l as InactivityTracker, m as InactivityTrackerOptions, L as LoginOptions, n as LogoutOptions, O as OtpLoginRequest, P as PasswordLoginRequest, R as RawAuthLoginResponse, o as RefreshFn, p as RefreshInterceptor, q as RefreshInterceptorOptions, r as ResetPasswordRequest } from './AuthClient-Bb7N2shJ.js';
 export { ExchangeAuthorizationCodeInput, FetchDiscoveryDocumentInput, OidcDiscoveryDocument, PkcePair, RefreshAccessTokenInput, clearDiscoveryCache, deriveCodeChallenge, exchangeAuthorizationCode, fetchDiscoveryDocument, generateCodeVerifier, generatePkcePair, refreshAccessToken } from './oidc/index.js';
-import { H as HttpClient, R as RawTokenResponse, T as TokenResponse } from './TokenResponse-CY1CaU2l.js';
-export { a as HttpRequest, b as HttpResponse, c as createFetchHttpClient } from './TokenResponse-CY1CaU2l.js';
+import { H as HttpClient, R as RawTokenResponse, T as TokenResponse } from './TokenResponse-BkIDjenX.js';
+export { a as HttpRequest, b as HttpResponse, c as createFetchHttpClient } from './TokenResponse-BkIDjenX.js';
 
 /**
  * Roles emitted by Keycloak realms in the dloizides.com portfolio.
@@ -372,6 +372,98 @@ interface BffPinLoginRequest {
     /** External id of the event the PIN is scoped to (supplied by the page/route). */
     eventExternalId: string;
 }
+/** Payload for `POST /bff/pin/enroll` — bind a device PIN to the current session. */
+interface BffDevicePinEnrollRequest {
+    /** The numeric PIN the user chose. */
+    pin: string;
+    /** The chosen PIN length (must be one of 4 / 6 / 8). */
+    digits: number;
+}
+/** Payload for `POST /bff/pin/unlock` — re-establish a session from a remembered device. */
+interface BffDevicePinUnlockRequest {
+    /** The numeric device PIN the returning user entered. */
+    pin: string;
+}
+/**
+ * The optional per-device state half of `GET /bff/config`, all fields safe-defaulted.
+ *
+ * Read off the BFF's per-device record (keyed by the device cookie). Older BFFs /
+ * tests omit the fields entirely, in which case the PIN-unlock gate simply never
+ * triggers (`hasPin` defaults to `false`, `rememberedUsername` to `null`).
+ */
+interface BffDeviceState {
+    /** Non-secret username this device remembers, or `null` when none. */
+    rememberedUsername: string | null;
+    /** `true` when this device has an enrolled device PIN. */
+    hasPin: boolean;
+    /** The enrolled PIN length (4 / 6 / 8), or `null` when unknown / no PIN. */
+    pinDigits: number | null;
+    /** The device-local preferred-method hint (e.g. `"pin"`), or `null`. */
+    preferredMethod: string | null;
+}
+/**
+ * The parsed `GET /bff/config` response: which login methods this BFF advertises,
+ * whether self-serve registration is enabled, and the optional per-device state.
+ *
+ * `methods` are the lowercase strings the server-side `BffLoginMethod` enum
+ * serialises to (`"password"` | `"otp"` | `"pin"` | `"passkey"`), de-duplicated
+ * and order-preserving. On a network failure or malformed body the client returns
+ * a safe fallback (`["password"]`, registration off, empty device-state).
+ */
+interface BffLoginConfig {
+    /** The enabled login methods, lowercase, in the order the BFF advertised them. */
+    methods: string[];
+    /** `true` when this BFF exposes self-serve registration. */
+    registrationEnabled: boolean;
+    /** The optional per-device state (remembered username + device PIN), safe-defaulted. */
+    deviceState: BffDeviceState;
+}
+/**
+ * Discriminated result of `unlockWithDevicePin`. Never rejects — the unlock UI
+ * routes on `status` (the published `login`/`pinLogin` throw an opaque error on
+ * any non-2xx, collapsing 401 vs 429; this is why the device-PIN flow needs its
+ * own client surface).
+ *
+ * The two `429` outcomes are distinct and MUST stay distinct: the BFF's per-IP
+ * `BffAuth` sliding-window limiter answers `429` with an EMPTY body
+ * (`rateLimited` — the UI may poll through it), whereas the device-PIN lockout
+ * answers `429` with a JSON `{ error }` body + a `Retry-After` header (`locked` —
+ * the UI shows a "try again in N s" message).
+ */
+type DevicePinUnlockResult = {
+    status: 'success';
+    user: BffUser;
+} | {
+    status: 'invalid';
+} | {
+    status: 'locked';
+    retryAfterSeconds: number | null;
+} | {
+    status: 'rateLimited';
+    retryAfterSeconds: number | null;
+} | {
+    status: 'error';
+};
+/**
+ * Discriminated result of `enrollDevicePin`. Never rejects — the enrol form routes
+ * on `status`:
+ *  - `success`      — HTTP 200, the device PIN is bound to the current session;
+ *  - `unauthorized` — HTTP 401, no session to bind to;
+ *  - `forbidden`    — HTTP 403, a PIN-established session can't enrol a new PIN;
+ *  - `invalidPin`   — HTTP 400, the PIN format was rejected;
+ *  - `error`        — anything else (501 disabled / 502 grant failed / network).
+ */
+type DevicePinEnrollResult = {
+    status: 'success';
+} | {
+    status: 'unauthorized';
+} | {
+    status: 'forbidden';
+} | {
+    status: 'invalidPin';
+} | {
+    status: 'error';
+};
 /**
  * The body `POST /bff/otp/request` relays from TenantService.
  *
@@ -484,6 +576,58 @@ declare class BffAuthClient {
      * is not an enabled method for this BFF.
      */
     pinLogin(request: BffPinLoginRequest): Promise<BffUser>;
+    /**
+     * `GET /bff/config` — which login methods this BFF advertises, whether
+     * registration is enabled, and the optional per-device state (remembered
+     * username + device PIN). Unauthenticated, no CSRF (GET).
+     *
+     * NEVER throws: on a non-2xx, a network error, or a malformed body it returns
+     * a safe fallback (`{ methods: ['password'], registrationEnabled: false,
+     * deviceState: { rememberedUsername: null, hasPin: false, pinDigits: null,
+     * preferredMethod: null } }`) so the login surface stays usable even when the
+     * config endpoint is unreachable.
+     */
+    getLoginConfig(): Promise<BffLoginConfig>;
+    /**
+     * `POST /bff/pin/enroll` — bind a device PIN to the CURRENT strong session.
+     * Requires an authenticated session (the cookie travels via
+     * `credentials: 'include'`); the BFF requests an offline token, hashes the
+     * PIN, and sets the device cookie.
+     *
+     * NEVER throws — resolves a discriminated {@link DevicePinEnrollResult}:
+     *  - 200 → `success`;
+     *  - 401 → `unauthorized` (no session);
+     *  - 403 → `forbidden` (a PIN-established session can't enrol);
+     *  - 400 → `invalidPin` (bad format);
+     *  - anything else (501 disabled / 502 grant failed) / network → `error`.
+     */
+    enrollDevicePin(request: BffDevicePinEnrollRequest): Promise<DevicePinEnrollResult>;
+    /**
+     * `POST /bff/pin/unlock` — re-establish a session from a remembered device.
+     * No prior session; the device cookie travels via `credentials: 'include'`.
+     *
+     * NEVER throws — resolves a discriminated {@link DevicePinUnlockResult}:
+     *  - 200 + `{ user }` → `success` (a session cookie was set);
+     *  - 401             → `invalid` (wrong PIN / unknown-or-revoked device);
+     *  - 429 + JSON body → `locked` (device lockout; `Retry-After` parsed);
+     *  - 429 + empty body → `rateLimited` (per-IP limiter; `Retry-After` parsed);
+     *  - anything else / malformed 200 body / network → `error`.
+     */
+    unlockWithDevicePin(request: BffDevicePinUnlockRequest): Promise<DevicePinUnlockResult>;
+    /**
+     * `POST /bff/pin/disable` — drop the device PIN for the CURRENT session. The
+     * BFF revokes the offline token at Keycloak, deletes the device record, and
+     * clears the device cookie. Requires an authenticated session.
+     *
+     * NEVER throws — resolves `true` on a 2xx, `false` on anything else.
+     */
+    disableDevicePin(): Promise<boolean>;
+    /**
+     * Shared POST for the never-throw device-PIN calls: same-origin, cookie
+     * included, `X-BFF-Csrf` header attached. Returns the raw {@link HttpResponse}
+     * (status + body + headers) so the caller can route on it instead of throwing.
+     */
+    private postRaw;
     /**
      * Shared POST for every state-changing `/bff/*` call: same-origin, cookie
      * included, `X-BFF-Csrf` header attached. Throws a labelled error on non-2xx.
@@ -664,4 +808,4 @@ declare function normalizeTokenResponse(raw: RawTokenResponse): TokenResponse;
  */
 declare function tokenResponseToAuthTokens(response: TokenResponse, now?: number): AuthTokens;
 
-export { AuthTokens, type AuthorizationCodeBodyInput, type AuthorizationResponseLike, type AuthorizationUrlInput, BffAuthClient, type BffAuthClientOptions, type BffForgotPasswordRequest, type BffLoginRequest, type BffOtpRequestRequest, type BffOtpRequestResult, type BffOtpVerifyRequest, type BffPinLoginRequest, type BffRegisterRequest, type BffResetPasswordRequest, type BffUser, type BiometricFlagStore, BiometricGate, type BiometricGateLike, type BiometricGateOptions, BrowserStorageTokenStorage, type BrowserStorageTokenStorageOptions, CookieTokenStorage, HttpClient, InMemoryTokenStorage, KeycloakRoles, type KeycloakUserInfo, type LocalAuthLike, type NormalizedUser, RawTokenResponse, type RefreshTokenBodyInput, type SecureStoreLike, SecureStoreTokenStorage, type SecureStoreTokenStorageOptions, type StorageLike, TokenResponse, TokenStorage, buildAuthorizationCodeBody, buildAuthorizationEndpoint, buildAuthorizationUrl, buildIssuerUrl, buildLogoutEndpoint, buildRefreshTokenBody, buildTokenEndpoint, buildUserInfoEndpoint, computeExpiresAt, decodeJwt, extractAuthCode, isKeycloakRole, isTokenExpired, normalizeKeycloakUser, normalizeTokenResponse, parseBaseUrlFromIssuer, parseRealmFromIssuer, tokenResponseToAuthTokens };
+export { AuthTokens, type AuthorizationCodeBodyInput, type AuthorizationResponseLike, type AuthorizationUrlInput, BffAuthClient, type BffAuthClientOptions, type BffDevicePinEnrollRequest, type BffDevicePinUnlockRequest, type BffDeviceState, type BffForgotPasswordRequest, type BffLoginConfig, type BffLoginRequest, type BffOtpRequestRequest, type BffOtpRequestResult, type BffOtpVerifyRequest, type BffPinLoginRequest, type BffRegisterRequest, type BffResetPasswordRequest, type BffUser, type BiometricFlagStore, BiometricGate, type BiometricGateLike, type BiometricGateOptions, BrowserStorageTokenStorage, type BrowserStorageTokenStorageOptions, CookieTokenStorage, type DevicePinEnrollResult, type DevicePinUnlockResult, HttpClient, InMemoryTokenStorage, KeycloakRoles, type KeycloakUserInfo, type LocalAuthLike, type NormalizedUser, RawTokenResponse, type RefreshTokenBodyInput, type SecureStoreLike, SecureStoreTokenStorage, type SecureStoreTokenStorageOptions, type StorageLike, TokenResponse, TokenStorage, buildAuthorizationCodeBody, buildAuthorizationEndpoint, buildAuthorizationUrl, buildIssuerUrl, buildLogoutEndpoint, buildRefreshTokenBody, buildTokenEndpoint, buildUserInfoEndpoint, computeExpiresAt, decodeJwt, extractAuthCode, isKeycloakRole, isTokenExpired, normalizeKeycloakUser, normalizeTokenResponse, parseBaseUrlFromIssuer, parseRealmFromIssuer, tokenResponseToAuthTokens };