@cboxdk/id-js 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -2,8 +2,6 @@
 
 var jose = require('jose');
 
-// src/client.ts
-
 // src/errors.ts
 var CboxIdError = class extends Error {
   constructor(message) {
@@ -17,6 +15,341 @@ var InvalidStateError = class extends CboxIdError {
 };
 var AuthenticationError = class extends CboxIdError {
 };
+var FrontendApiError = class extends CboxIdError {
+  constructor(message, code, status, retryAfter) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+  code;
+  status;
+  retryAfter;
+};
+
+// src/legacy.ts
+function createLegacyVerifier(options) {
+  if (!options.secret || options.secret.length < 32) {
+    throw new ConfigurationError(
+      "A legacy verifier secret must be at least 32 characters; it is the only thing proving a request came from Cbox ID."
+    );
+  }
+  const tolerance = options.toleranceSeconds ?? 300;
+  return async function handle(request) {
+    const raw = await request.text();
+    if (!await isSignedByCboxId(raw, request.headers.get("X-Cbox-Signature"), options.secret, tolerance)) {
+      return json({ error: "unauthorized" }, 401);
+    }
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      return json({ error: "invalid_request" }, 400);
+    }
+    const { email, password } = payload;
+    if (typeof email !== "string" || email === "") {
+      return json({ error: "invalid_request" }, 400);
+    }
+    if (typeof password !== "string") {
+      return json({ user: null }, 200);
+    }
+    let user;
+    try {
+      user = await options.verify(email, password);
+    } catch {
+      return json({ error: "unavailable" }, 503);
+    }
+    if (!user) {
+      return json({ user: null }, 200);
+    }
+    return json(
+      {
+        email: user.email,
+        name: user.name ?? null,
+        email_verified: user.emailVerified === true,
+        ...user.passwordHash ? { password_hash: user.passwordHash } : {}
+      },
+      200
+    );
+  };
+}
+async function isSignedByCboxId(body, header, secret, toleranceSeconds) {
+  if (!header) {
+    return false;
+  }
+  const parts = {};
+  for (const piece of header.split(",")) {
+    const [key2, value] = piece.split("=", 2);
+    if (key2 && value) {
+      parts[key2.trim()] = value.trim();
+    }
+  }
+  const timestamp = parts["t"] ?? "";
+  const signature = parts["v1"] ?? "";
+  if (!/^\d+$/.test(timestamp) || signature === "") {
+    return false;
+  }
+  if (Math.abs(Math.floor(Date.now() / 1e3) - Number(timestamp)) > toleranceSeconds) {
+    return false;
+  }
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${body}`));
+  const expected = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return timingSafeEqual(expected, signature);
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+function json(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+
+// src/frontend.ts
+var CboxIdFrontend = class {
+  issuer;
+  publishableKey;
+  timeoutMs;
+  retries;
+  fetchImpl;
+  /**
+   * The config document, and the in-flight promise for it.
+   *
+   * Deduplicated rather than merely cached: a page with a sign-in form, a user button and
+   * an organization switcher mounts three components in the same tick, and three parallel
+   * fetches of the same immutable document is a waste the SDK should absorb rather than
+   * ask every consumer to.
+   */
+  configPromise = null;
+  constructor(options) {
+    if (!options.issuer) {
+      throw new ConfigurationError("issuer is required.");
+    }
+    if (!options.publishableKey?.startsWith("pk_")) {
+      throw new ConfigurationError(
+        "publishableKey must be a pk_test_\u2026 or pk_live_\u2026 key. Client secrets and API keys must never be put in a browser."
+      );
+    }
+    this.issuer = options.issuer.replace(/\/$/, "");
+    this.publishableKey = options.publishableKey;
+    this.timeoutMs = options.timeoutMs ?? 1e4;
+    this.retries = Math.max(0, options.retries ?? 2);
+    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  /** Whether this key drives real sign-ins. Handy for a "test mode" badge in your own UI. */
+  get isLive() {
+    return this.publishableKey.startsWith("pk_live_");
+  }
+  /**
+   * The public sign-in configuration.
+   *
+   * Fetched once per client instance. The document is small and changes when somebody
+   * edits it in the console, so a long-lived page picks changes up on its next full load
+   * rather than mid-session — which is the right trade for something that decides layout.
+   */
+  async config() {
+    this.configPromise ??= this.get("/frontend/v1/config", {}, isFrontendConfig).catch((error) => {
+      this.configPromise = null;
+      throw error;
+    });
+    return this.configPromise;
+  }
+  /**
+   * Who is signed in, given an access token your app already holds.
+   *
+   * Returns `{ user: null }` rather than throwing when nobody is signed in. That is a
+   * state, not an error: a user button renders on pages nobody has signed in on, and
+   * making callers treat a rejection as a state is how flash-of-signed-out bugs happen.
+   *
+   * The publishable key grants nothing here — the token is the entire authority.
+   */
+  async session(accessToken) {
+    if (!accessToken) {
+      return { user: null };
+    }
+    return this.get(
+      "/frontend/v1/session",
+      { Authorization: `Bearer ${accessToken}` },
+      isFrontendSession
+    );
+  }
+  /**
+   * Sign in with a password, from a form your page drew.
+   *
+   * WHAT COMES BACK IS A TICKET, NEVER A TOKEN. Handing tokens to a page that proved a
+   * password is the implicit grant, which OAuth 2.1 removes: tokens in a URL, in history,
+   * in `Referer`, with no client authentication and no PKCE binding. Spend the ticket by
+   * sending the browser to `/oauth/authorize` with your own PKCE challenge and
+   * `login_ticket` in the query — the ordinary flow, which then issues an ordinary code.
+   *
+   * It expires in sixty seconds. It is for one redirect, not for storing.
+   *
+   * ```ts
+   * const result = await frontend.signIn(email, password)
+   *
+   * if (result.status === 'ok') {
+   *   window.location.href = `${config.endpoints.authorization}?${new URLSearchParams({
+   *     client_id, redirect_uri, response_type: 'code', code_challenge, code_challenge_method: 'S256',
+   *     login_ticket: result.loginTicket,
+   *   })}`
+   * }
+   * ```
+   *
+   * EVERY REFUSAL IS THE SAME REFUSAL. `invalid` covers a wrong password, an unknown
+   * address and a locked account, because distinguishing them is the enumeration oracle
+   * the server refuses to build — do not present them differently in your UI either.
+   */
+  async signIn(email, password) {
+    const response = await this.post("/frontend/v1/sign-in", { email, password });
+    if (response.status === 429) {
+      const retryAfter = Number(response.headers.get("Retry-After") ?? "");
+      return { status: "rate_limited", retryAfter: Number.isFinite(retryAfter) ? retryAfter : void 0 };
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new FrontendApiError("Cbox ID returned a body that is not JSON.", "malformed", response.status);
+    }
+    if (body.status === "ok" && typeof body.login_ticket === "string") {
+      return { status: "ok", loginTicket: body.login_ticket, expiresIn: body.expires_in ?? 60 };
+    }
+    switch (body.status) {
+      case "mfa_required":
+      case "otp_required":
+      case "sso_required":
+        return { status: body.status };
+      default:
+        return { status: "invalid" };
+    }
+  }
+  async post(path, payload) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await this.fetchImpl(`${this.issuer}${path}`, {
+        method: "POST",
+        headers: {
+          "X-Cbox-Publishable-Key": this.publishableKey,
+          "Content-Type": "application/json",
+          Accept: "application/json"
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+    } catch {
+      throw new FrontendApiError(
+        `Could not reach Cbox ID at ${this.issuer}. If this is a browser, check that this page's origin is on the key's allow-list \u2014 a refused request fails as a network error by design.`,
+        "unavailable"
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async get(path, extraHeaders = {}, validate) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      if (attempt > 0) {
+        await new Promise((resolve) => setTimeout(resolve, 150 * attempt));
+      }
+      try {
+        return await this.attempt(path, extraHeaders, validate);
+      } catch (error) {
+        lastError = error;
+        if (!(error instanceof FrontendApiError) || error.code !== "unavailable") {
+          throw error;
+        }
+      }
+    }
+    throw lastError;
+  }
+  async attempt(path, extraHeaders, validate) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.issuer}${path}`, {
+        headers: {
+          // A header, never a query string: a query string puts the key in server logs,
+          // in `Referer` on every outbound link, and in browser history.
+          "X-Cbox-Publishable-Key": this.publishableKey,
+          Accept: "application/json",
+          ...extraHeaders
+        },
+        signal: controller.signal
+      });
+    } catch (cause) {
+      throw new FrontendApiError(
+        `Could not reach Cbox ID at ${this.issuer}. If this is a browser, check that this page's origin is on the key's allow-list \u2014 a refused request fails as a network error by design.`,
+        "unavailable"
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status === 429) {
+      const retryAfter = Number(response.headers.get("Retry-After") ?? "");
+      throw new FrontendApiError(
+        "Cbox ID is rate limiting this key.",
+        "rate_limited",
+        429,
+        Number.isFinite(retryAfter) ? retryAfter : void 0
+      );
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new FrontendApiError(
+        `Cbox ID refused the request (${response.status}). Check that this page's origin is on the key's allow-list, and that the key is not revoked.`,
+        "origin_not_allowed",
+        response.status
+      );
+    }
+    if (!response.ok) {
+      throw new FrontendApiError(
+        `Cbox ID returned ${response.status}.`,
+        "unavailable",
+        response.status
+      );
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new FrontendApiError("Cbox ID returned a body that is not JSON.", "malformed", response.status);
+    }
+    if (validate && !validate(body)) {
+      throw new FrontendApiError(
+        "Cbox ID returned a body that is not the expected document.",
+        "malformed",
+        response.status
+      );
+    }
+    return body;
+  }
+};
+function isFrontendConfig(body) {
+  if (typeof body !== "object" || body === null) {
+    return false;
+  }
+  const doc = body;
+  return typeof doc.issuer === "string" && typeof doc.endpoints === "object" && doc.endpoints !== null;
+}
+function isFrontendSession(body) {
+  return typeof body === "object" && body !== null && "user" in body;
+}
 
 // src/discovery.ts
 var Discovery = class {
@@ -180,7 +513,7 @@ var VaultClient = class {
 };
 
 // src/webhook.ts
-function timingSafeEqual(a, b) {
+function timingSafeEqual2(a, b) {
   if (a.length !== b.length) {
     return false;
   }
@@ -225,7 +558,7 @@ async function verifyWebhook(options) {
   const expected = toHex(
     await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${payload}`))
   );
-  return timingSafeEqual(expected, signature);
+  return timingSafeEqual2(expected, signature);
 }
 
 // src/client.ts
@@ -430,11 +763,11 @@ var CboxIdClient = class {
     if (!response.ok) {
       throw new AuthenticationError(`Machine token request failed: ${await response.text()}`);
     }
-    const json = await response.json();
-    if (typeof json.access_token !== "string") {
+    const json2 = await response.json();
+    if (typeof json2.access_token !== "string") {
       throw new AuthenticationError("The token response had no access_token.");
     }
-    return json.access_token;
+    return json2.access_token;
   }
   /** The OIDC userinfo claims for an access token. */
   async userinfo(accessToken) {
@@ -564,7 +897,7 @@ var CboxIdClient = class {
   }
   accountPath() {
     const path = this.config.accountPath;
-    return path && path !== "" ? `/${path.replace(/^\//, "")}` : "/settings";
+    return path && path !== "" ? `/${path.replace(/^\//, "")}` : "/account";
   }
   requireSecret() {
     if (!this.config.clientSecret) {
@@ -623,7 +956,10 @@ function defineAuthz(declaration) {
   const permissions = declaration.permissions ?? [];
   const roles = declaration.roles ?? [];
   assertDeclaration(permissions, roles);
-  return { permissions, roles };
+  if (declaration.legacyLogin) {
+    assertLegacyLogin(declaration.legacyLogin);
+  }
+  return { ...declaration, permissions, roles };
 }
 async function buildManifest(declaration) {
   const permissions = (declaration.permissions ?? []).map(canonicalPermission);
@@ -632,7 +968,12 @@ async function buildManifest(declaration) {
   permissions.sort((a, b) => byteCompare(a.key, b.key));
   roles.sort((a, b) => byteCompare(a.key, b.key));
   const version = (await sha256Hex(canonicalManifestJson(permissions, roles))).slice(0, 16);
-  return { version, permissions, roles };
+  const manifest = { version, permissions, roles };
+  if (declaration.legacyLogin) {
+    assertLegacyLogin(declaration.legacyLogin);
+    manifest.legacy_login = declaration.legacyLogin;
+  }
+  return manifest;
 }
 async function publishManifest(config, declaration) {
   if (!config.issuer || !config.clientId || !config.clientSecret) {
@@ -658,8 +999,8 @@ async function publishManifest(config, declaration) {
   if (!response.ok) {
     throw new AuthenticationError(`Manifest push failed: HTTP ${response.status} ${await response.text()}`);
   }
-  const json = await response.json();
-  return json !== null && typeof json === "object" ? json : {};
+  const json2 = await response.json();
+  return json2 !== null && typeof json2 === "object" ? json2 : {};
 }
 async function mintToken(config, discovery, timeoutMs) {
   const response = await fetchWithTimeout(
@@ -676,13 +1017,13 @@ async function mintToken(config, discovery, timeoutMs) {
     },
     timeoutMs
   );
-  const json = await response.json().catch(() => ({}));
-  if (typeof json.access_token !== "string" || json.access_token === "") {
+  const json2 = await response.json().catch(() => ({}));
+  if (typeof json2.access_token !== "string" || json2.access_token === "") {
     throw new AuthenticationError(
       "Could not obtain an apps.manifest access token \u2014 check the client credentials and that the client holds the apps.manifest scope."
     );
   }
-  return json.access_token;
+  return json2.access_token;
 }
 function assertDeclaration(permissions, roles) {
   const permissionKeys = /* @__PURE__ */ new Set();
@@ -741,11 +1082,11 @@ function emptyToNull(value) {
 function byteCompare(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
 }
-function escapeLikePhp(json) {
+function escapeLikePhp(json2) {
   let out = "";
-  for (let i = 0; i < json.length; i++) {
-    const char = json.charAt(i);
-    const code = json.charCodeAt(i);
+  for (let i = 0; i < json2.length; i++) {
+    const char = json2.charAt(i);
+    const code = json2.charCodeAt(i);
     if (char === "/") {
       out += "\\/";
     } else if (code > 127) {
@@ -769,15 +1110,26 @@ async function fetchWithTimeout(url, init, timeoutMs) {
     clearTimeout(timer);
   }
 }
+function assertLegacyLogin(legacy) {
+  if (!legacy.url.startsWith("https://")) {
+    throw new ConfigurationError("legacyLogin.url must be https \u2014 a password must never cross the network in the clear.");
+  }
+  if (!legacy.secret || legacy.secret.length < 32) {
+    throw new ConfigurationError("legacyLogin.secret must be at least 32 characters; it is what proves a request came from Cbox ID.");
+  }
+}
 
 exports.AuthenticationError = AuthenticationError;
 exports.CboxIdClient = CboxIdClient;
 exports.CboxIdError = CboxIdError;
+exports.CboxIdFrontend = CboxIdFrontend;
 exports.ConfigurationError = ConfigurationError;
+exports.FrontendApiError = FrontendApiError;
 exports.InvalidStateError = InvalidStateError;
 exports.VaultClient = VaultClient;
 exports.buildManifest = buildManifest;
 exports.challenge = challenge;
+exports.createLegacyVerifier = createLegacyVerifier;
 exports.createVerifier = createVerifier;
 exports.defineAuthz = defineAuthz;
 exports.publishManifest = publishManifest;