@dloizides/auth-client 3.0.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # 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
+login. Extends `BffAuthClient` with the browser-facing PIN call so the new
+`<PinForm>` in `@dloizides/auth-web` has a same-origin client. No breaking
+changes.
+
+### Added
+
+- `BffAuthClient.pinLogin({ pin, eventExternalId })` → `POST /bff/pin/login`.
+  The BFF runs the event-scoped PIN direct-grant against Keycloak server-side
+  (the `(event, pin)` pair resolves to the staff member's KC account + their
+  event-scoped role) and sets the httpOnly session cookie. Returns the
+  sanitised `BffUser`, exactly like `login` / `verifyOtp`. Throws on a non-2xx
+  (`401` for a bad / expired / locked-out PIN or an unknown event, `501` when
+  PIN login is not an enabled method). Carries the `X-BFF-Csrf` header like
+  every other state-changing call. No `username` / `password` ever leaves the
+  browser.
+- Type: `BffPinLoginRequest`.
+
+## 3.1.0 (2026-05-22)
+
+Additive release for Phase 2d of the unified-auth plan — email-OTP. Extends
+`BffAuthClient` with the two browser-facing OTP calls so the new `<OtpForm>` in
+`@dloizides/auth-web` has a same-origin client. No breaking changes.
+
+### Added
+
+- `BffAuthClient.requestOtp({ identifier })` → `POST /bff/otp/request`. The BFF
+  proxies to TenantService, which emails a short-TTL code. The endpoint is
+  anti-enumeration (a `200` is the normal path), so the method **returns** the
+  relayed `{ success, expiresIn, code }` body — the UI uses `expiresIn` for a
+  countdown. It still throws on a non-2xx (`501` OTP not enabled, `502` upstream
+  down). Carries the `X-BFF-Csrf` header like every other state-changing call.
+- `BffAuthClient.verifyOtp({ username, otp })` → `POST /bff/otp/verify`. The BFF
+  runs the OTP direct-grant against Keycloak server-side and sets the httpOnly
+  session cookie. Returns the sanitised `BffUser`, exactly like `login`. Throws
+  on a non-2xx (e.g. `401` for a bad / expired code).
+- Types: `BffOtpRequestRequest`, `BffOtpVerifyRequest`, `BffOtpRequestResult`.
+
 ## 3.0.0 (2026-05-19)
 
 Major release for Phase 2 of the identity-hardening initiative. Adds the

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-BGr8L03W.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.
@@ -457,4 +457,4 @@ declare class AuthClient {
     private resolveScope;
 }
 
-export { AuthApiClient as A, type DirectKcOptions as D, type ForgotPasswordRequest as F, type InactivityStore as I, type LoginOptions as L, type OtpLoginRequest as O, type PasswordLoginRequest as P, type ResetPasswordRequest as R, type TokenStorage as T, type AuthSessionInfo as a, AuthClient as b, type AuthTokens as c, type AuthApiClientOptions as d, type AuthClientCollaborators as e, type AuthClientConfig as f, type AuthClientFromIssuerInput as g, AuthEventEmitter as h, type AuthEventListener as i, type AuthEventName as j, type AuthEventUnsubscribe as k, InactivityTracker as l, type InactivityTrackerOptions as m, type LogoutOptions as n, type RawAuthLoginResponse as o, type RefreshFn as p, RefreshInterceptor as q, type RefreshInterceptorOptions as r };
+export { AuthApiClient as A, type DirectKcOptions as D, type ForgotPasswordRequest as F, type InactivityStore as I, type LoginOptions as L, type OtpLoginRequest as O, type PasswordLoginRequest as P, type RawAuthLoginResponse as R, type TokenStorage as T, type AuthApiClientOptions as a, AuthClient as b, type AuthClientCollaborators as c, type AuthClientConfig as d, type AuthClientFromIssuerInput as e, AuthEventEmitter as f, type AuthEventListener as g, type AuthEventName as h, type AuthEventUnsubscribe as i, type AuthSessionInfo as j, type AuthTokens as k, InactivityTracker as l, type InactivityTrackerOptions as m, type LogoutOptions as n, type RefreshFn as o, RefreshInterceptor as p, type RefreshInterceptorOptions as q, type ResetPasswordRequest as r };

package/dist/{AuthClient-D95OMajD.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.
@@ -457,4 +457,4 @@ declare class AuthClient {
     private resolveScope;
 }
 
-export { AuthApiClient as A, type DirectKcOptions as D, type ForgotPasswordRequest as F, type InactivityStore as I, type LoginOptions as L, type OtpLoginRequest as O, type PasswordLoginRequest as P, type ResetPasswordRequest as R, type TokenStorage as T, type AuthSessionInfo as a, AuthClient as b, type AuthTokens as c, type AuthApiClientOptions as d, type AuthClientCollaborators as e, type AuthClientConfig as f, type AuthClientFromIssuerInput as g, AuthEventEmitter as h, type AuthEventListener as i, type AuthEventName as j, type AuthEventUnsubscribe as k, InactivityTracker as l, type InactivityTrackerOptions as m, type LogoutOptions as n, type RawAuthLoginResponse as o, type RefreshFn as p, RefreshInterceptor as q, type RefreshInterceptorOptions as r };
+export { AuthApiClient as A, type DirectKcOptions as D, type ForgotPasswordRequest as F, type InactivityStore as I, type LoginOptions as L, type OtpLoginRequest as O, type PasswordLoginRequest as P, type RawAuthLoginResponse as R, type TokenStorage as T, type AuthApiClientOptions as a, AuthClient as b, type AuthClientCollaborators as c, type AuthClientConfig as d, type AuthClientFromIssuerInput as e, AuthEventEmitter as f, type AuthEventListener as g, type AuthEventName as h, type AuthEventUnsubscribe as i, type AuthSessionInfo as j, type AuthTokens as k, InactivityTracker as l, type InactivityTrackerOptions as m, type LogoutOptions as n, type RefreshFn as o, RefreshInterceptor as p, type RefreshInterceptorOptions as q, type ResetPasswordRequest as r };

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, c as AuthTokens } from './AuthClient-BGr8L03W.mjs';
-export { A as AuthApiClient, d as AuthApiClientOptions, b as AuthClient, e as AuthClientCollaborators, f as AuthClientConfig, g as AuthClientFromIssuerInput, h as AuthEventEmitter, i as AuthEventListener, j as AuthEventName, k as AuthEventUnsubscribe, a 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, o as RawAuthLoginResponse, p as RefreshFn, q as RefreshInterceptor, r as RefreshInterceptorOptions, R as ResetPasswordRequest } from './AuthClient-BGr8L03W.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.
@@ -342,6 +342,143 @@ interface BffResetPasswordRequest {
     token: string;
     newPassword: string;
 }
+/**
+ * Payload for `POST /bff/otp/request` — the BFF proxies it to TenantService,
+ * which generates a short-TTL code and emails it.
+ */
+interface BffOtpRequestRequest {
+    /** The email address (or username) the one-time code is sent to. */
+    identifier: string;
+}
+/** Payload for `POST /bff/otp/verify` — the BFF exchanges it for a session. */
+interface BffOtpVerifyRequest {
+    /** The email / username the code was requested for. */
+    username: string;
+    /** The one-time code the user entered. */
+    otp: string;
+}
+/**
+ * Payload for `POST /bff/pin/login` — the BFF exchanges an event-scoped PIN
+ * for a session.
+ *
+ * The `(event, pin)` pair alone identifies the staff member: no `username` /
+ * `password` ever leaves the browser. A PIN entered in an event's context
+ * grants that staff member their event-scoped role for that event only
+ * (the unified-auth plan §4.4 — event-scoped, per-individual PINs).
+ */
+interface BffPinLoginRequest {
+    /** The numeric PIN the staff member entered. */
+    pin: string;
+    /** 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.
+ *
+ * Anti-enumeration: the shape is identical whether or not the identifier is
+ * registered. `code` is non-null only outside production (a dev convenience);
+ * the UI must never depend on it being present.
+ */
+interface BffOtpRequestResult {
+    /** Always `true` on a relayed 200 — the request was accepted. */
+    success: boolean;
+    /** Seconds until the emitted code expires — drives a countdown in the UI. */
+    expiresIn: number;
+    /** The code itself, non-production only; `null` (or absent) in production. */
+    code: string | null;
+}
 /**
  * The user object returned by `GET /bff/me` and `POST /bff/login`. The BFF
  * returns the sanitised KC claims under a `user` envelope and **never** a
@@ -411,6 +548,86 @@ declare class BffAuthClient {
      * response (e.g. `400` for an invalid / expired token).
      */
     resetPassword(request: BffResetPasswordRequest): Promise<void>;
+    /**
+     * `POST /bff/otp/request` — the BFF proxies to TenantService, which generates
+     * a short-TTL code and emails it.
+     *
+     * The endpoint is anti-enumeration: a `200` is the normal path whether or not
+     * the identifier is registered. This method therefore **returns** the relayed
+     * `{ success, expiresIn, code }` body (so the UI can show the expiry) rather
+     * than treating a 200 as opaque. It still throws on a non-2xx — a `501`
+     * (OTP not enabled) or `502` (upstream down) is a real failure to surface.
+     */
+    requestOtp(request: BffOtpRequestRequest): Promise<BffOtpRequestResult>;
+    /**
+     * `POST /bff/otp/verify` — the BFF runs the OTP direct-grant against Keycloak
+     * server-side, stores the tokens in its Redis vault, and sets the httpOnly
+     * session cookie. Returns the sanitised user, exactly like `login`. Throws on
+     * a non-2xx (e.g. `401` for a bad / expired code).
+     */
+    verifyOtp(request: BffOtpVerifyRequest): Promise<BffUser>;
+    /**
+     * `POST /bff/pin/login` — the BFF runs the event-scoped PIN direct-grant
+     * against Keycloak server-side (the `(event, pin)` pair resolves to the
+     * staff member's KC account + event-scoped role), stores the tokens in its
+     * Redis vault, and sets the httpOnly session cookie. Returns the sanitised
+     * user, exactly like `login` / `verifyOtp`. Throws on a non-2xx — `401` for
+     * a bad / expired / locked-out PIN or an unknown event, `501` when PIN login
+     * 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.
@@ -591,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 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 };