@dloizides/auth-client 3.0.0 → 3.3.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { T as TokenStorage, c as AuthTokens } from './AuthClient-D95OMajD.js';
-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-D95OMajD.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.
@@ -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 };

package/dist/index.js

@@ -944,7 +944,8 @@ function createFetchHttpClient(fetchImpl) {
     return {
       status: response.status,
       ok: response.ok,
-      data
+      data,
+      header: (name) => response.headers.get(name)
     };
   };
 }
@@ -1069,8 +1070,23 @@ var ENDPOINTS = {
   me: "/bff/me",
   register: "/bff/register",
   forgotPassword: "/bff/forgot-password",
-  resetPassword: "/bff/reset-password"
+  resetPassword: "/bff/reset-password",
+  otpRequest: "/bff/otp/request",
+  otpVerify: "/bff/otp/verify",
+  pinLogin: "/bff/pin/login",
+  config: "/bff/config",
+  pinEnroll: "/bff/pin/enroll",
+  pinUnlock: "/bff/pin/unlock",
+  pinDisable: "/bff/pin/disable"
 };
+var HTTP_OK = 200;
+var HTTP_MULTIPLE_CHOICES = 300;
+var HTTP_BAD_REQUEST = 400;
+var HTTP_UNAUTHORIZED = 401;
+var HTTP_FORBIDDEN = 403;
+var HTTP_TOO_MANY_REQUESTS = 429;
+var FALLBACK_METHODS = ["password"];
+var ALLOWED_PIN_DIGITS = [4, 6, 8];
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -1081,6 +1097,91 @@ function extractUser(data) {
   const envelope = data;
   return isRecord(envelope.user) ? envelope.user : null;
 }
+function toOtpRequestResult(data) {
+  if (!isRecord(data)) {
+    return { success: true, expiresIn: 0, code: null };
+  }
+  return {
+    success: typeof data.success === "boolean" ? data.success : true,
+    expiresIn: typeof data.expiresIn === "number" ? data.expiresIn : 0,
+    code: typeof data.code === "string" ? data.code : null
+  };
+}
+var FALLBACK_LOGIN_CONFIG = {
+  methods: [...FALLBACK_METHODS],
+  registrationEnabled: false,
+  deviceState: {
+    rememberedUsername: null,
+    hasPin: false,
+    pinDigits: null,
+    preferredMethod: null
+  }
+};
+function readOptionalString(record, key) {
+  const value = record[key];
+  if (typeof value !== "string" || value === "") {
+    return null;
+  }
+  return value;
+}
+function parseDeviceState(body) {
+  const rawDigits = body.pinDigits;
+  const hasValidDigits = typeof rawDigits === "number" && ALLOWED_PIN_DIGITS.includes(rawDigits);
+  return {
+    rememberedUsername: readOptionalString(body, "rememberedUsername"),
+    hasPin: body.hasPin === true,
+    pinDigits: hasValidDigits ? rawDigits : null,
+    preferredMethod: readOptionalString(body, "preferredMethod")
+  };
+}
+function parseMethods(body) {
+  const raw = body.methods;
+  if (!Array.isArray(raw)) {
+    return [...FALLBACK_METHODS];
+  }
+  const parsed = raw.filter((value) => typeof value === "string" && value !== "").map((value) => value.toLowerCase());
+  return parsed.length === 0 ? [...FALLBACK_METHODS] : Array.from(new Set(parsed));
+}
+function parseLoginConfig(data) {
+  if (!isRecord(data)) {
+    return FALLBACK_LOGIN_CONFIG;
+  }
+  return {
+    methods: parseMethods(data),
+    registrationEnabled: data.registrationEnabled === true,
+    deviceState: parseDeviceState(data)
+  };
+}
+function parseRetryAfter(response) {
+  const raw = response.header?.("Retry-After");
+  if (raw === null || raw === void 0) {
+    return null;
+  }
+  const seconds = Number.parseInt(raw, 10);
+  if (Number.isNaN(seconds) || seconds < 0) {
+    return null;
+  }
+  return seconds;
+}
+function classifyTooManyRequests(response) {
+  const retryAfterSeconds = parseRetryAfter(response);
+  if (isRecord(response.data)) {
+    return { status: "locked", retryAfterSeconds };
+  }
+  return { status: "rateLimited", retryAfterSeconds };
+}
+function classifyEnrollFailure(status) {
+  if (status === HTTP_UNAUTHORIZED) {
+    return { status: "unauthorized" };
+  }
+  if (status === HTTP_FORBIDDEN) {
+    return { status: "forbidden" };
+  }
+  if (status === HTTP_BAD_REQUEST) {
+    return { status: "invalidPin" };
+  }
+  return { status: "error" };
+}
 var BffAuthClient = class {
   constructor(options) {
     this.http = options.http;
@@ -1151,22 +1252,171 @@ var BffAuthClient = class {
     await this.postState(ENDPOINTS.resetPassword, request, "reset-password");
   }
   /**
-   * Shared POST for every state-changing `/bff/*` call: same-origin, cookie
-   * included, `X-BFF-Csrf` header attached. Throws a labelled error on non-2xx.
+   * `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.
    */
-  async postState(path, body, label) {
+  async requestOtp(request) {
+    const data = await this.postState(ENDPOINTS.otpRequest, request, "otp-request");
+    return toOtpRequestResult(data);
+  }
+  /**
+   * `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).
+   */
+  async verifyOtp(request) {
+    const data = await this.postState(ENDPOINTS.otpVerify, request, "otp-verify");
+    const user = extractUser(data);
+    if (user === null) {
+      throw new Error("otp-verify: BFF response missing user");
+    }
+    return user;
+  }
+  /**
+   * `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.
+   */
+  async pinLogin(request) {
+    const data = await this.postState(ENDPOINTS.pinLogin, request, "pin-login");
+    const user = extractUser(data);
+    if (user === null) {
+      throw new Error("pin-login: BFF response missing user");
+    }
+    return user;
+  }
+  /**
+   * `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.
+   */
+  async getLoginConfig() {
+    try {
+      const response = await this.http({
+        url: `${this.baseUrl}${ENDPOINTS.config}`,
+        method: "GET",
+        headers: { Accept: JSON_CONTENT_TYPE },
+        credentials: "include"
+      });
+      if (!response.ok) {
+        return FALLBACK_LOGIN_CONFIG;
+      }
+      return parseLoginConfig(response.data);
+    } catch {
+      return FALLBACK_LOGIN_CONFIG;
+    }
+  }
+  /**
+   * `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`.
+   */
+  async enrollDevicePin(request) {
+    try {
+      const response = await this.postRaw(ENDPOINTS.pinEnroll, request);
+      if (response.ok) {
+        return { status: "success" };
+      }
+      return classifyEnrollFailure(response.status);
+    } catch {
+      return { status: "error" };
+    }
+  }
+  /**
+   * `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`.
+   */
+  async unlockWithDevicePin(request) {
+    try {
+      const response = await this.postRaw(ENDPOINTS.pinUnlock, request);
+      const isSuccess = response.status >= HTTP_OK && response.status < HTTP_MULTIPLE_CHOICES;
+      if (isSuccess) {
+        const user = extractUser(response.data);
+        return user === null ? { status: "error" } : { status: "success", user };
+      }
+      if (response.status === HTTP_UNAUTHORIZED) {
+        return { status: "invalid" };
+      }
+      if (response.status === HTTP_TOO_MANY_REQUESTS) {
+        return classifyTooManyRequests(response);
+      }
+      return { status: "error" };
+    } catch {
+      return { status: "error" };
+    }
+  }
+  /**
+   * `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.
+   */
+  async disableDevicePin() {
+    try {
+      const response = await this.postRaw(ENDPOINTS.pinDisable, void 0);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * 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.
+   */
+  postRaw(path, body) {
     const headers = {
       "Content-Type": JSON_CONTENT_TYPE,
       Accept: JSON_CONTENT_TYPE,
       [CSRF_HEADER]: CSRF_HEADER_VALUE
     };
-    const response = await this.http({
+    return this.http({
       url: `${this.baseUrl}${path}`,
       method: "POST",
       headers,
       body: body === void 0 ? void 0 : JSON.stringify(body),
       credentials: "include"
     });
+  }
+  /**
+   * Shared POST for every state-changing `/bff/*` call: same-origin, cookie
+   * included, `X-BFF-Csrf` header attached. Throws a labelled error on non-2xx.
+   */
+  async postState(path, body, label) {
+    const response = await this.postRaw(path, body);
     if (!response.ok) {
       throw new Error(`${label} failed with status ${String(response.status)}`);
     }