@dloizides/auth-client 3.0.0 → 3.3.0

package/dist/index.mjs

@@ -942,7 +942,8 @@ function createFetchHttpClient(fetchImpl) {
     return {
       status: response.status,
       ok: response.ok,
-      data
+      data,
+      header: (name) => response.headers.get(name)
     };
   };
 }
@@ -1067,8 +1068,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;
 }
@@ -1079,6 +1095,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;
@@ -1149,22 +1250,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)}`);
     }