@cboxdk/id-js 0.17.0 → 0.19.0

package/dist/index.cjs

@@ -106,12 +106,12 @@ function createLegacyVerifier(options) {
     );
   };
 }
-async function isSignedByCboxId(body, header, secret, toleranceSeconds) {
-  if (!header) {
+async function isSignedByCboxId(body, header2, secret, toleranceSeconds) {
+  if (!header2) {
     return false;
   }
   const parts = {};
-  for (const piece of header.split(",")) {
+  for (const piece of header2.split(",")) {
     const [key2, value] = piece.split("=", 2);
     if (key2 && value) {
       parts[key2.trim()] = value.trim();
@@ -174,6 +174,7 @@ function assertSecureIssuer(issuer) {
 }
 
 // src/frontend.ts
+var SECOND_FACTOR_KINDS = /* @__PURE__ */ new Set(["totp", "sms", "recovery_code"]);
 var CboxIdFrontend = class {
   issuer;
   publishableKey;
@@ -188,7 +189,7 @@ var CboxIdFrontend = class {
    * fetches of the same immutable document is a waste the SDK should absorb rather than
    * ask every consumer to.
    */
-  configPromise = null;
+  configPromises = /* @__PURE__ */ new Map();
   constructor(options) {
     if (!options.issuer) {
       throw new ConfigurationError("issuer is required.");
@@ -215,13 +216,20 @@ var CboxIdFrontend = class {
    * 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.
+   * Each `organization` is fetched and cached on its own.
    */
-  async config() {
-    this.configPromise ??= this.get("/frontend/v1/config", {}, isFrontendConfig).catch((error) => {
-      this.configPromise = null;
-      throw error;
-    });
-    return this.configPromise;
+  async config(options = {}) {
+    const organization2 = options.organization ?? "";
+    let pending = this.configPromises.get(organization2);
+    if (pending === void 0) {
+      const path = organization2 === "" ? "/frontend/v1/config" : `/frontend/v1/config?${new URLSearchParams({ organization: organization2 }).toString()}`;
+      pending = this.get(path, {}, isFrontendConfig).catch((error) => {
+        this.configPromises.delete(organization2);
+        throw error;
+      });
+      this.configPromises.set(organization2, pending);
+    }
+    return pending;
   }
   /**
    * Who is signed in, given an access token your app already holds.
@@ -283,8 +291,12 @@ var CboxIdFrontend = class {
     if (body.status === "ok" && typeof body.login_ticket === "string") {
       return { status: "ok", loginTicket: body.login_ticket, expiresIn: body.expires_in ?? 60 };
     }
-    if ((body.status === "mfa_required" || body.status === "otp_required") && typeof body.mfa_token === "string") {
-      return { status: body.status, mfaToken: body.mfa_token };
+    if (body.status === "mfa_required" && typeof body.mfa_token === "string") {
+      const factors = Array.isArray(body.factors) ? body.factors.filter((f) => typeof f === "string" && SECOND_FACTOR_KINDS.has(f)) : void 0;
+      return { status: "mfa_required", mfaToken: body.mfa_token, ...factors ? { factors } : {} };
+    }
+    if (body.status === "otp_required" && typeof body.mfa_token === "string") {
+      return { status: "otp_required", mfaToken: body.mfa_token };
     }
     if (body.status === "sso_required") {
       return { status: "sso_required" };
@@ -301,6 +313,11 @@ var CboxIdFrontend = class {
    *
    * A wrong code costs an attempt, not the sign-in: five are allowed before the token
    * dies and the person starts from the password again.
+   *
+   * `method` says which challenge the code answers: `'mfa'` for an authenticator or
+   * recovery code, `'otp'` for an emailed code (`otp_required`), `'sms'` for a code sent
+   * with {@link sendSmsCode}. A texted code is six digits like an authenticator's, so the
+   * server cannot tell them apart by shape — answering one as the other is refused.
    */
   async submitSecondFactor(mfaToken, code, method = "mfa") {
     const response = await this.post("/frontend/v1/sign-in/factor", { mfa_token: mfaToken, code, method });
@@ -312,6 +329,41 @@ var CboxIdFrontend = class {
     }
     return body.status === "ok" && typeof body.login_ticket === "string" ? { status: "ok", loginTicket: body.login_ticket, expiresIn: body.expires_in ?? 60 } : { status: "invalid" };
   }
+  /**
+   * Text the person a sign-in code, when `mfa_required` listed `'sms'` in `factors`.
+   * Then finish with `submitSecondFactor(mfaToken, code, 'sms')`.
+   *
+   * Only call it when the person asks ("Text me a code"), never on page load: each send
+   * spends one of the token's five attempts — that is what bounds how many texts one
+   * proved password can cause — and every text costs the customer money.
+   *
+   * ```ts
+   * if (result.status === 'mfa_required' && result.factors?.includes('sms')) {
+   *   const sent = await frontend.sendSmsCode(result.mfaToken)
+   *   if (sent.status === 'sent') showCodeField(`We texted ${sent.to}`)
+   * }
+   * ```
+   */
+  async sendSmsCode(mfaToken) {
+    const response = await this.post("/frontend/v1/sign-in/factor/sms", { mfa_token: mfaToken });
+    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 === "sent" && typeof body.to === "string") {
+      return { status: "sent", to: body.to, expiresIn: typeof body.expires_in === "number" ? body.expires_in : 300 };
+    }
+    if (body.status === "rate_limited" || response.status === 429) {
+      const retryAfter = typeof body.retry_after === "number" ? body.retry_after : Number(response.headers.get("Retry-After") ?? "");
+      return { status: "rate_limited", retryAfter: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0 };
+    }
+    if (body.status === "unavailable") {
+      return { status: "unavailable" };
+    }
+    return { status: "invalid" };
+  }
   /**
    * The WebAuthn options for a passkey sign-in, and the handle that carries the challenge.
    *
@@ -607,6 +659,14 @@ function hasRole(source, role) {
 function hasPermission(source, permission) {
   return permissions(source).includes(permission);
 }
+var FEATURE_FLAGS_SCOPE = "feature_flags";
+function featureFlags(source) {
+  const claim = claimsOf(source)["feature_flags"];
+  return Array.isArray(claim) ? stringList(claim) : null;
+}
+function hasFeature(source, key) {
+  return featureFlags(source)?.includes(key) ?? false;
+}
 var MAX_ACTOR_DEPTH = 8;
 function parseActor(claim, depth) {
   if (claim === void 0 || claim === null) {
@@ -633,6 +693,43 @@ function isUser(source) {
 }
 
 // src/vault.ts
+function withConnectReturn(connectUrl, options = {}) {
+  const url = new URL(connectUrl);
+  if (options.clientId) url.searchParams.set("client_id", options.clientId);
+  if (options.returnTo) url.searchParams.set("return_to", options.returnTo);
+  return url.toString();
+}
+function pipeConnectUrl(issuer, provider, options = {}) {
+  return withConnectReturn(
+    `${issuer.replace(/\/$/, "")}/account/connected-services/${encodeURIComponent(provider)}/connect`,
+    options
+  );
+}
+var PipeLeaseError = class extends CboxIdError {
+  constructor(message, error, status, connectUrl = null, retryAfter = null) {
+    super(message);
+    this.error = error;
+    this.status = status;
+    this.connectUrl = connectUrl;
+    this.retryAfter = retryAfter;
+  }
+  error;
+  status;
+  connectUrl;
+  retryAfter;
+  /** `connectUrl` with your `client_id` and `return_to` on it, or null when there is none. */
+  connectUrlWith(options) {
+    return this.connectUrl === null ? null : withConnectReturn(this.connectUrl, options);
+  }
+};
+var PipeNotConnectedError = class extends PipeLeaseError {
+};
+var PipeReauthorizationRequiredError = class extends PipeLeaseError {
+};
+var PipeTemporarilyUnavailableError = class extends PipeLeaseError {
+};
+var PipeLeaseDeniedError = class extends PipeLeaseError {
+};
 var VaultClient = class {
   constructor(issuer, token, timeoutMs = 1e4) {
     this.token = token;
@@ -688,11 +785,69 @@ var VaultClient = class {
       return { secretId: r.secret_id, provider: r.provider, secret: r.secret, expiresAt: r.expires_at };
     });
   }
+  /**
+   * Lease a fresh access token for a person's connected account at `provider` (Pipes,
+   * scope `vault.lease`). The token is refreshed first when it is about to expire, so
+   * you never handle a refresh token.
+   *
+   * With a client-credentials token, name the person in `userId`. With a token issued to
+   * your app FOR a person, leave it out — the lease is theirs.
+   *
+   * ```ts
+   * try {
+   *   const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' })
+   * } catch (e) {
+   *   if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+   *     return redirect(e.connectUrlWith({ clientId, returnTo }))
+   *   }
+   *   throw e
+   * }
+   * ```
+   */
+  async leasePipeToken(provider, options) {
+    const path = `/pipes/${encodeURIComponent(provider)}/token`;
+    const response = await this.send("POST", path, {
+      purpose: options.purpose,
+      ...options.userId !== void 0 ? { user_id: options.userId } : {}
+    });
+    let body = {};
+    try {
+      const parsed = await response.json();
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        body = parsed;
+      }
+    } catch {
+    }
+    if (!response.ok) {
+      throw pipeLeaseError(response, body);
+    }
+    if (typeof body.access_token !== "string") {
+      throw new PipeLeaseError("The pipe lease answered without an access token.", null, response.status);
+    }
+    return {
+      accessToken: body.access_token,
+      tokenType: "Bearer",
+      provider: String(body.provider ?? provider),
+      userId: String(body.user_id ?? ""),
+      connectionId: String(body.connection_id ?? ""),
+      scopes: Array.isArray(body.scopes) ? body.scopes.filter((s) => typeof s === "string") : [],
+      expiresAt: typeof body.expires_at === "string" ? body.expires_at : null,
+      leaseExpiresAt: String(body.lease_expires_at ?? ""),
+      metadata: isStringRecord(body.metadata) ? body.metadata : {}
+    };
+  }
   async json(method, path, body) {
     const response = await this.request(method, path, body);
     return await response.json();
   }
   async request(method, path, body) {
+    const response = await this.send(method, path, body);
+    if (!response.ok) {
+      throw new AuthenticationError(`Vault ${method} ${path} failed with status ${response.status}.`);
+    }
+    return response;
+  }
+  async send(method, path, body) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
@@ -707,16 +862,35 @@ var VaultClient = class {
       if (body) {
         init.body = JSON.stringify(body);
       }
-      const response = await fetch(`${this.base}${path}`, init);
-      if (!response.ok) {
-        throw new AuthenticationError(`Vault ${method} ${path} failed with status ${response.status}.`);
-      }
-      return response;
+      return await fetch(`${this.base}${path}`, init);
     } finally {
       clearTimeout(timer);
     }
   }
 };
+function pipeLeaseError(response, body) {
+  const error = typeof body.error === "string" ? body.error : null;
+  const message = typeof body.message === "string" && body.message !== "" ? body.message : `The pipe lease failed with status ${response.status}.`;
+  const connectUrl = typeof body.connect_url === "string" && body.connect_url !== "" ? body.connect_url : null;
+  const header2 = response.headers.get("retry-after")?.trim() ?? "";
+  const retryAfter = /^\d+$/.test(header2) ? Number(header2) : null;
+  if (response.status === 404 && connectUrl !== null) {
+    return new PipeNotConnectedError(message, error, 404, connectUrl, retryAfter);
+  }
+  if (response.status === 409 && connectUrl !== null) {
+    return new PipeReauthorizationRequiredError(message, error, 409, connectUrl, retryAfter);
+  }
+  if (response.status === 503) {
+    return new PipeTemporarilyUnavailableError(message, error, 503, connectUrl, retryAfter);
+  }
+  if (response.status === 403 && error !== "insufficient_scope") {
+    return new PipeLeaseDeniedError(message, error, 403, connectUrl, retryAfter);
+  }
+  return new PipeLeaseError(message, error, response.status, connectUrl, retryAfter);
+}
+function isStringRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((v) => typeof v === "string");
+}
 
 // src/webhook.ts
 function timingSafeEqual2(a, b) {
@@ -766,6 +940,58 @@ async function verifyWebhook(options) {
   );
   return timingSafeEqual2(expected, signature);
 }
+function header(headers, name) {
+  if (typeof Headers !== "undefined" && headers instanceof Headers) {
+    return headers.get(name) ?? void 0;
+  }
+  const record = headers;
+  const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+  const value = key === void 0 ? void 0 : record[key];
+  return Array.isArray(value) ? value.join(" ") : value;
+}
+function base64ToBytes(value) {
+  try {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  } catch {
+    return null;
+  }
+}
+function toBase64(bytes) {
+  let binary = "";
+  for (const byte of new Uint8Array(bytes)) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+async function verifyStandardWebhook(options) {
+  const { payload, headers, secret } = options;
+  const toleranceSeconds = options.toleranceSeconds ?? 300;
+  const now = options.now ?? Math.floor(Date.now() / 1e3);
+  const id = header(headers, "webhook-id");
+  const timestamp = header(headers, "webhook-timestamp");
+  const signatures = header(headers, "webhook-signature");
+  if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) {
+    return false;
+  }
+  if (Math.abs(now - Number(timestamp)) > toleranceSeconds) {
+    return false;
+  }
+  const keyBytes = secret.startsWith("whsec_") ? base64ToBytes(secret.slice("whsec_".length)) : new TextEncoder().encode(secret);
+  if (keyBytes === null || keyBytes.length === 0) {
+    return false;
+  }
+  const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const expected = toBase64(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${id}.${timestamp}.${payload}`)));
+  let valid = false;
+  for (const candidate of signatures.split(" ")) {
+    const [version, signature] = candidate.split(",", 2);
+    if (version === "v1" && signature !== void 0 && timingSafeEqual2(expected, signature)) {
+      valid = true;
+    }
+  }
+  return valid;
+}
 
 // src/client.ts
 var CboxIdClient = class {
@@ -934,6 +1160,7 @@ var CboxIdClient = class {
       organization: organization(claims),
       roles: roles(claims),
       permissions: permissions(claims),
+      featureFlags: featureFlags(claims),
       actor: actor(claims),
       sessionId: sessionId(claims),
       // Only present when the instance emitted the claim (exactOptionalPropertyTypes).
@@ -1113,6 +1340,18 @@ var CboxIdClient = class {
    * registered. `organization` picks which of the person's organizations the keys act in;
    * omitted, the page uses the one they are in.
    */
+  /**
+   * The hosted page where the signed-in person connects their account at `provider`
+   * (Pipes) — `/account/connected-services/{provider}/connect`, preselected to this app.
+   * They come back to `returnTo` with `?provider=…&status=connected|cancelled|failed`,
+   * honoured only on an origin the app registered.
+   */
+  pipeConnectUrl(provider, returnTo) {
+    return pipeConnectUrl(this.config.issuer, provider, {
+      clientId: this.config.clientId,
+      ...returnTo !== void 0 ? { returnTo } : {}
+    });
+  }
   apiKeysUrl(options = {}) {
     const params = new URLSearchParams({ client_id: options.clientId ?? this.config.clientId });
     if (options.returnTo) {
@@ -1641,8 +1880,14 @@ exports.CboxIdClient = CboxIdClient;
 exports.CboxIdError = CboxIdError;
 exports.CboxIdFrontend = CboxIdFrontend;
 exports.ConfigurationError = ConfigurationError;
+exports.FEATURE_FLAGS_SCOPE = FEATURE_FLAGS_SCOPE;
 exports.FrontendApiError = FrontendApiError;
 exports.InvalidStateError = InvalidStateError;
+exports.PipeLeaseDeniedError = PipeLeaseDeniedError;
+exports.PipeLeaseError = PipeLeaseError;
+exports.PipeNotConnectedError = PipeNotConnectedError;
+exports.PipeReauthorizationRequiredError = PipeReauthorizationRequiredError;
+exports.PipeTemporarilyUnavailableError = PipeTemporarilyUnavailableError;
 exports.VaultClient = VaultClient;
 exports.actor = actor;
 exports.buildManifest = buildManifest;
@@ -1650,15 +1895,20 @@ exports.challenge = challenge;
 exports.createLegacyVerifier = createLegacyVerifier;
 exports.createVerifier = createVerifier;
 exports.defineAuthz = defineAuthz;
+exports.featureFlags = featureFlags;
+exports.hasFeature = hasFeature;
 exports.hasPermission = hasPermission;
 exports.hasRole = hasRole;
 exports.isSupportSession = isSupportSession;
 exports.organization = organization;
 exports.permissions = permissions;
+exports.pipeConnectUrl = pipeConnectUrl;
 exports.publishManifest = publishManifest;
 exports.randomToken = randomToken;
 exports.roles = roles;
 exports.sessionId = sessionId;
+exports.verifyStandardWebhook = verifyStandardWebhook;
 exports.verifyWebhook = verifyWebhook;
+exports.withConnectReturn = withConnectReturn;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map