@cboxdk/id-js 0.6.0 → 0.8.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,268 @@ 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
+    );
+  }
+  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 +440,7 @@ var VaultClient = class {
 };
 
 // src/webhook.ts
-function timingSafeEqual(a, b) {
+function timingSafeEqual2(a, b) {
   if (a.length !== b.length) {
     return false;
   }
@@ -225,7 +485,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
@@ -279,7 +539,15 @@ var CboxIdClient = class {
       params.set("max_age", String(options.maxAge));
     }
     const endpoint = await this.discovery.endpoint("authorization_endpoint");
-    return { url: `${endpoint}?${params.toString()}`, state, codeVerifier, nonce };
+    return {
+      url: `${endpoint}?${params.toString()}`,
+      state,
+      codeVerifier,
+      nonce,
+      // Carried through so authenticate() can hold the instance to it. Only present
+      // when requested (exactOptionalPropertyTypes).
+      ...typeof options.maxAge === "number" ? { maxAge: options.maxAge } : {}
+    };
   }
   /**
    * Complete login on your callback route: verify state, exchange the code with the
@@ -307,7 +575,11 @@ var CboxIdClient = class {
     }
     let claims = {};
     if (tokens.id_token) {
-      claims = await this.verifyIdToken(tokens.id_token, stored.nonce);
+      claims = await this.verifyIdToken(tokens.id_token, stored.nonce, stored.maxAge);
+    } else if (typeof stored.maxAge === "number") {
+      throw new AuthenticationError(
+        "A max_age was requested but no id_token was returned, so the authentication age could not be verified."
+      );
     }
     claims = { ...claims, ...await this.userinfo(tokens.access_token) };
     const sub = claims["sub"];
@@ -373,13 +645,30 @@ var CboxIdClient = class {
     const base = `${this.config.issuer.replace(/\/$/, "")}${this.accountPath()}`;
     return returnTo ? `${base}?${new URLSearchParams({ return_to: returnTo }).toString()}` : base;
   }
-  /** The RP-initiated logout URL, or null when the instance advertises none. */
-  async logoutUrl(returnTo) {
+  /**
+   * The RP-initiated logout URL, or null when the instance advertises none.
+   *
+   * `client_id` is always sent, even without a `returnTo`: the OP validates
+   * `post_logout_redirect_uri` against the registered allow-list of THAT client
+   * (OIDC RP-Initiated Logout 1.0 §2). With no way to name the RP the OP cannot
+   * check the list, so it silently drops the return URL and strands the user on a
+   * bare "you are signed out" page. `idTokenHint` — the user's `id_token`, if you
+   * still hold it — is the spec's other way to identify the RP, and additionally
+   * tells the OP which subject is logging out.
+   */
+  async logoutUrl(returnTo, idTokenHint) {
     const endpoint = await this.discovery.optionalEndpoint("end_session_endpoint");
     if (!endpoint) {
       return null;
     }
-    return returnTo ? `${endpoint}?${new URLSearchParams({ post_logout_redirect_uri: returnTo }).toString()}` : endpoint;
+    const params = new URLSearchParams({ client_id: this.config.clientId });
+    if (returnTo) {
+      params.set("post_logout_redirect_uri", returnTo);
+    }
+    if (idTokenHint) {
+      params.set("id_token_hint", idTokenHint);
+    }
+    return `${endpoint}?${params.toString()}`;
   }
   /**
    * A machine (client-credentials) access token for calling Cbox ID APIs as your
@@ -401,11 +690,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) {
@@ -438,6 +727,28 @@ var CboxIdClient = class {
     }
     return await response.json();
   }
+  /**
+   * RFC 7009 token revocation (confidential-client auth). Revokes an access or
+   * refresh token; revoking a refresh token also drops the whole token family, so
+   * this is what a real "sign out everywhere" does. Requires a secret.
+   *
+   * Per RFC 7009 the server answers 200 for an unknown or already-revoked token, so
+   * a successful call means "the token is not valid any more", not "it existed".
+   *
+   * @param tokenTypeHint which store to search first — only a hint, never required.
+   */
+  async revoke(token, tokenTypeHint) {
+    const endpoint = await this.discovery.endpoint("revocation_endpoint");
+    const basic = btoa(`${this.config.clientId}:${this.requireSecret()}`);
+    const body = new URLSearchParams({ token });
+    if (tokenTypeHint) {
+      body.set("token_type_hint", tokenTypeHint);
+    }
+    const response = await this.post(endpoint, body, { authorization: `Basic ${basic}` });
+    if (!response.ok) {
+      throw new AuthenticationError("Revocation request failed.");
+    }
+  }
   /** Verify a Cbox ID webhook / inline-action signature. See {@link verifyWebhook}. */
   verifyWebhook(options) {
     return verifyWebhook(options);
@@ -467,7 +778,7 @@ var CboxIdClient = class {
     }
     return await response.json();
   }
-  async verifyIdToken(idToken, nonce) {
+  async verifyIdToken(idToken, nonce, maxAge) {
     const jwksUri = await this.discovery.endpoint("jwks_uri");
     let resolver = this.jwksByUri.get(jwksUri);
     if (!resolver) {
@@ -478,7 +789,11 @@ var CboxIdClient = class {
     try {
       ({ payload } = await jose.jwtVerify(idToken, resolver, {
         issuer: this.config.issuer,
-        audience: this.config.clientId
+        audience: this.config.clientId,
+        // Pin the accepted signature algorithms explicitly. `jose` already refuses
+        // `alg: none` and key-type confusion, so this is belt-and-braces — but it
+        // states the contract in code rather than relying on a library default.
+        algorithms: ["RS256", "ES256"]
       }));
     } catch (error) {
       throw new AuthenticationError(`The id_token could not be verified: ${String(error)}`);
@@ -486,6 +801,21 @@ var CboxIdClient = class {
     if (nonce && payload["nonce"] !== nonce) {
       throw new AuthenticationError("The id_token nonce did not match \u2014 possible replay.");
     }
+    if (typeof maxAge === "number") {
+      const authTime = payload["auth_time"];
+      if (typeof authTime !== "number") {
+        throw new AuthenticationError(
+          "A max_age was requested but the id_token carried no auth_time, so the authentication age could not be verified."
+        );
+      }
+      const tolerance = this.config.authTimeToleranceSeconds ?? 60;
+      const age = Math.floor(Date.now() / 1e3) - authTime;
+      if (age > maxAge + tolerance) {
+        throw new AuthenticationError(
+          `The authentication is ${age}s old but max_age required ${maxAge}s \u2014 the user did not re-authenticate.`
+        );
+      }
+    }
     return payload;
   }
   scopes() {
@@ -494,7 +824,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) {
@@ -553,7 +883,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);
@@ -562,7 +895,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) {
@@ -588,8 +926,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(
@@ -606,13 +944,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();
@@ -671,11 +1009,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) {
@@ -699,15 +1037,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;