@cboxdk/id-js 0.15.1 → 0.18.0

package/dist/chunk-2E25IPBA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api-keys.ts"],"names":[],"mappings":"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","file":"chunk-2E25IPBA.js","sourcesContent":["import type { OrganizationRole } from './claims.js';\nimport { AuthenticationError, ConfigurationError, oauthError } from './errors.js';\nimport { assertSecureIssuer } from './issuer.js';\n\n/**\n * A customer API key Cbox ID vouches for: live, bound to YOUR app, and held by an active\n * member of `org`.\n *\n * The field names are the endpoint's own, so the claim helpers read it like a token —\n * `hasPermission(answer, 'invoices:create')`, `organization(answer)?.role`. (A type\n * alias rather than an interface for that reason: only an alias is assignable to the\n * helpers' record type.)\n */\nexport type ActiveApiKey = {\n  active: true;\n  /** The key's id — log this, never the key. */\n  key_id: string;\n  /** The person who holds the key (their subject id). */\n  sub: string;\n  /** The organization the key acts in. */\n  org: string;\n  /** The holder's membership tier in `org`; null for a tier this SDK does not know. */\n  org_role: OrganizationRole | null;\n  /**\n   * What the key may do, already re-capped by Cbox ID: the key's own list intersected\n   * with what the holder holds for your app right now. A demoted holder's key loses the\n   * permission on the next verification, not at the next reissue.\n   */\n  permissions: string[];\n  /** Your app's client id — always, or the answer is refused. */\n  client_id: string;\n  /** ISO 8601 UTC expiry, or null for a key that does not expire. */\n  expires_at: string | null;\n};\n\n/**\n * Every refusal: unknown, malformed, revoked, expired, another app's key, a holder who\n * left. Cbox ID never says which, so the endpoint cannot be used to probe keys — and\n * neither does this.\n */\nexport interface InactiveApiKey {\n  active: false;\n}\n\n/** What {@link ApiKeyVerifier.verifyApiKey} returns. Narrow on `active`. */\nexport type ApiKeyVerification = ActiveApiKey | InactiveApiKey;\n\n/** Configuration for an {@link ApiKeyVerifier}. */\nexport interface ApiKeyVerifierConfig {\n  /** Base URL (issuer) of the Cbox ID instance. */\n  issuer: string;\n  /** Your app's OAuth client id — the app the keys were issued for. */\n  clientId: string;\n  /** Your app's client secret. Verification is a confidential-client call. */\n  clientSecret: string;\n  /** Timeout (ms) for the verification request. Defaults to `10000`. */\n  timeoutMs?: number;\n  /**\n   * Cache an ACTIVE answer for this long (ms), so a burst of requests with one key costs\n   * one round-trip. Off (`0`) by default and at most {@link MAX_API_KEY_CACHE_TTL_MS}:\n   * while an answer is cached, a revoked key keeps working, and a demoted holder keeps\n   * the permissions they lost. Never cached past the key's `expires_at`. Refusals are\n   * never cached, so a key issued a moment ago works on its first request.\n   */\n  cacheTtlMs?: number;\n}\n\n/** The longest {@link ApiKeyVerifierConfig.cacheTtlMs} allowed: one minute. */\nexport const MAX_API_KEY_CACHE_TTL_MS = 60_000;\n\n/** Enough for a busy API's working set; oldest entries go first beyond it. */\nconst MAX_CACHE_ENTRIES = 1_000;\n\nconst ORGANIZATION_ROLES: ReadonlySet<string> = new Set<OrganizationRole>([\n  'owner',\n  'admin',\n  'developer',\n  'member',\n  'viewer',\n]);\n\n/**\n * Verifies customer API keys presented to your API: `POST {issuer}/oauth/api-keys/verify`,\n * authenticated with your app's own client credentials.\n *\n * SERVER-SIDE ONLY. It holds your client secret, so it lives in the\n * `@cboxdk/id-js/server` entry and the Next.js adapter, never in the main entry that a\n * browser bundle pulls in — and it refuses to be constructed in a browser at all.\n *\n * ```ts\n * import { ApiKeyVerifier } from '@cboxdk/id-js/server';\n * import { hasPermission } from '@cboxdk/id-js';\n *\n * const keys = new ApiKeyVerifier({ issuer, clientId, clientSecret, cacheTtlMs: 10_000 });\n *\n * const answer = await keys.verifyApiKey(request.headers.get('x-api-key') ?? '');\n * if (!answer.active) return unauthorized();\n * if (!hasPermission(answer, 'invoices:create')) return forbidden();\n * ```\n */\nexport class ApiKeyVerifier {\n  private readonly endpoint: string;\n  private readonly timeoutMs: number;\n  private readonly cacheTtlMs: number;\n  private readonly cache = new Map<string, { answer: ActiveApiKey; until: number }>();\n\n  constructor(private readonly config: ApiKeyVerifierConfig) {\n    // A heuristic, and enough of one: a page has a `document`, and no server runtime\n    // this SDK supports (Node, Deno, Bun, edge workers) defines one.\n    if (typeof (globalThis as { document?: unknown }).document !== 'undefined') {\n      throw new ConfigurationError(\n        'API key verification uses your client secret and must run on your server, never in a browser.',\n      );\n    }\n    if (!config.issuer || !config.clientId || !config.clientSecret) {\n      throw new ConfigurationError('Verifying API keys needs issuer, clientId and clientSecret.');\n    }\n    assertSecureIssuer(config.issuer);\n\n    const cacheTtlMs = config.cacheTtlMs ?? 0;\n    if (!Number.isFinite(cacheTtlMs) || cacheTtlMs < 0 || cacheTtlMs > MAX_API_KEY_CACHE_TTL_MS) {\n      throw new ConfigurationError(\n        `cacheTtlMs must be between 0 and ${MAX_API_KEY_CACHE_TTL_MS}: a cached answer keeps a revoked key working for that long.`,\n      );\n    }\n\n    this.endpoint = `${config.issuer.replace(/\\/$/, '')}/oauth/api-keys/verify`;\n    this.timeoutMs = config.timeoutMs ?? 10_000;\n    this.cacheTtlMs = cacheTtlMs;\n  }\n\n  /**\n   * Ask Cbox ID whether `key` is good for this app, and what it may do.\n   *\n   * Resolves `{ active: false }` for every kind of bad key, without a request for an empty\n   * one. Throws `AuthenticationError` when the call itself fails (wrong client\n   * credentials, an unreachable instance) or when the answer cannot be trusted — one that\n   * names another app's `client_id`, or does not have the promised shape. Both mean \"do\n   * not let this request in\"; the difference is that a throw is something to look at.\n   */\n  async verifyApiKey(key: string): Promise<ApiKeyVerification> {\n    if (typeof key !== 'string' || key.trim() === '') {\n      return { active: false };\n    }\n\n    const cacheKey = this.cacheTtlMs > 0 ? await digest(key) : null;\n    if (cacheKey !== null) {\n      const hit = this.cache.get(cacheKey);\n      if (hit && hit.until > Date.now()) {\n        return hit.answer;\n      }\n      this.cache.delete(cacheKey);\n    }\n\n    const answer = this.parse(await this.request(key));\n\n    if (cacheKey !== null && answer.active) {\n      this.remember(cacheKey, answer);\n    }\n\n    return answer;\n  }\n\n  private async request(key: string): Promise<unknown> {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeoutMs);\n\n    let response: Response;\n    try {\n      response = await fetch(this.endpoint, {\n        method: 'POST',\n        headers: {\n          authorization: `Basic ${btoa(`${this.config.clientId}:${this.config.clientSecret}`)}`,\n          accept: 'application/json',\n          'content-type': 'application/x-www-form-urlencoded',\n        },\n        body: new URLSearchParams({ key }),\n        signal: controller.signal,\n      });\n    } catch (error) {\n      throw new AuthenticationError(`API key verification request failed: ${String(error)}`);\n    } finally {\n      clearTimeout(timer);\n    }\n\n    if (!response.ok) {\n      throw await oauthError(response, 'API key verification failed');\n    }\n\n    return response.json().catch(() => null);\n  }\n\n  private parse(body: unknown): ApiKeyVerification {\n    if (typeof body !== 'object' || body === null) {\n      throw new AuthenticationError('API key verification returned a body that is not a JSON object.');\n    }\n\n    const record = body as Record<string, unknown>;\n\n    // Only a literal `true` lets anybody in.\n    if (record['active'] !== true) {\n      return { active: false };\n    }\n\n    const keyId = record['key_id'];\n    const sub = record['sub'];\n    const org = record['org'];\n    const clientId = record['client_id'];\n    const expiresAt = record['expires_at'];\n    const permissions = record['permissions'];\n\n    if (\n      !nonEmpty(keyId) ||\n      !nonEmpty(sub) ||\n      !nonEmpty(org) ||\n      !nonEmpty(clientId) ||\n      !Array.isArray(permissions) ||\n      (expiresAt !== null && expiresAt !== undefined && typeof expiresAt !== 'string')\n    ) {\n      throw new AuthenticationError('API key verification returned an active answer without the promised fields.');\n    }\n\n    // THE BINDING, CHECKED AGAIN HERE. Cbox ID only ever finds a key bound to the calling\n    // client, so this cannot fire against a correct instance — which is exactly when a\n    // check that it holds is worth having: a proxy, a misrouted base URL, or a shared\n    // secret between two apps would otherwise let one app's customers into another's API.\n    if (clientId !== this.config.clientId) {\n      throw new AuthenticationError(\n        `API key verification answered for client ${clientId}, not this app (${this.config.clientId}); refusing it.`,\n      );\n    }\n\n    // Past its expiry by our clock is expired, whatever the instance thought a moment ago.\n    if (typeof expiresAt === 'string') {\n      const expiry = Date.parse(expiresAt);\n      if (Number.isNaN(expiry) || expiry <= Date.now()) {\n        return { active: false };\n      }\n    }\n\n    const role = record['org_role'];\n\n    return {\n      active: true,\n      key_id: keyId,\n      sub,\n      org,\n      org_role: typeof role === 'string' && ORGANIZATION_ROLES.has(role) ? (role as OrganizationRole) : null,\n      permissions: permissions.filter((value): value is string => nonEmpty(value)),\n      client_id: clientId,\n      expires_at: typeof expiresAt === 'string' ? expiresAt : null,\n    };\n  }\n\n  private remember(cacheKey: string, answer: ActiveApiKey): void {\n    const expiry = answer.expires_at === null ? Number.POSITIVE_INFINITY : Date.parse(answer.expires_at);\n    const until = Math.min(Date.now() + this.cacheTtlMs, expiry);\n\n    if (this.cache.size >= MAX_CACHE_ENTRIES) {\n      const oldest = this.cache.keys().next();\n      if (!oldest.done) {\n        this.cache.delete(oldest.value);\n      }\n    }\n\n    this.cache.set(cacheKey, { answer, until });\n  }\n}\n\nfunction nonEmpty(value: unknown): value is string {\n  return typeof value === 'string' && value !== '';\n}\n\n/** The cache is keyed by a hash, so live keys are not sitting in memory as plaintext. */\nasync function digest(key: string): Promise<string> {\n  const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key));\n  return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, '0')).join('');\n}\n"]}

package/dist/{chunk-3V6OKRWF.js → chunk-CXGKOJRJ.js}

@@ -1,63 +1,7 @@
+import { assertSecureIssuer } from './chunk-QQW63PGU.js';
+import { AuthenticationError, ConfigurationError, InvalidStateError, oauthError } from './chunk-SEUD4TE4.js';
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 
-// src/errors.ts
-var CboxIdError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
-  }
-};
-var ConfigurationError = class extends CboxIdError {
-};
-var InvalidStateError = class extends CboxIdError {
-};
-var AuthenticationError = class extends CboxIdError {
-  constructor(message, error, errorDescription, status, retryAfter) {
-    super(message);
-    this.error = error;
-    this.errorDescription = errorDescription;
-    this.status = status;
-    this.retryAfter = retryAfter;
-  }
-  error;
-  errorDescription;
-  status;
-  retryAfter;
-  /** Whether waiting `retryAfter` seconds and repeating the same request is worth it. */
-  get isRateLimited() {
-    return this.status === 429;
-  }
-};
-async function oauthError(response, fallback) {
-  const body = await response.text().catch(() => "");
-  let code;
-  let description;
-  try {
-    const parsed = JSON.parse(body);
-    if (typeof parsed === "object" && parsed !== null) {
-      const { error, error_description: errorDescription } = parsed;
-      code = typeof error === "string" ? error : void 0;
-      description = typeof errorDescription === "string" ? errorDescription : void 0;
-    }
-  } catch {
-  }
-  const detail = code ?? `HTTP ${response.status}`;
-  const retryAfterHeader = response.headers.get("retry-after");
-  const retryAfter = retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader.trim()) ? Number(retryAfterHeader.trim()) : void 0;
-  return new AuthenticationError(`${fallback}: ${detail}`, code, description, response.status, retryAfter);
-}
-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/pkce.ts
 function base64url(bytes) {
   let binary = "";
@@ -77,6 +21,75 @@ async function challenge(verifier) {
   return base64url(new Uint8Array(digest));
 }
 
+// src/claims.ts
+var ORGANIZATION_ROLES = /* @__PURE__ */ new Set([
+  "owner",
+  "admin",
+  "developer",
+  "member",
+  "viewer"
+]);
+function organization(source) {
+  const claims = claimsOf(source);
+  const id = claims["org"];
+  if (typeof id !== "string" || id === "") {
+    return null;
+  }
+  const name = claims["org_name"];
+  const role = claims["org_role"];
+  return {
+    id,
+    name: typeof name === "string" && name !== "" ? name : null,
+    role: typeof role === "string" && ORGANIZATION_ROLES.has(role) ? role : null
+  };
+}
+function actor(source) {
+  return parseActor(claimsOf(source)["act"], 0);
+}
+function isSupportSession(source) {
+  return actor(source) !== null;
+}
+function sessionId(source) {
+  const sid = claimsOf(source)["sid"];
+  return typeof sid === "string" && sid !== "" ? sid : null;
+}
+function roles(source) {
+  return stringList(claimsOf(source)["roles"]);
+}
+function permissions(source) {
+  return stringList(claimsOf(source)["permissions"]);
+}
+function hasRole(source, role) {
+  return roles(source).includes(role);
+}
+function hasPermission(source, permission) {
+  return permissions(source).includes(permission);
+}
+var MAX_ACTOR_DEPTH = 8;
+function parseActor(claim, depth) {
+  if (claim === void 0 || claim === null) {
+    return null;
+  }
+  if (typeof claim !== "object" || Array.isArray(claim)) {
+    return { sub: null, actor: null };
+  }
+  const record = claim;
+  const sub = record["sub"];
+  return {
+    sub: typeof sub === "string" && sub !== "" ? sub : null,
+    actor: depth + 1 < MAX_ACTOR_DEPTH ? parseActor(record["act"], depth + 1) : null
+  };
+}
+function stringList(claim) {
+  return Array.isArray(claim) ? claim.filter((value) => typeof value === "string" && value !== "") : [];
+}
+function claimsOf(source) {
+  return isUser(source) ? source.claims : source;
+}
+function isUser(source) {
+  return typeof source["claims"] === "object" && source["claims"] !== null && typeof source["accessToken"] === "string";
+}
+
 // src/vault.ts
 var VaultClient = class {
   constructor(issuer, token, timeoutMs = 1e4) {
@@ -211,6 +224,58 @@ async function verifyWebhook(options) {
   );
   return timingSafeEqual(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 && timingSafeEqual(expected, signature)) {
+      valid = true;
+    }
+  }
+  return valid;
+}
 
 // src/discovery.ts
 var Discovery = class {
@@ -276,26 +341,6 @@ function trimSlash(value) {
   return value.replace(/\/+$/, "");
 }
 
-// src/issuer.ts
-function assertSecureIssuer(issuer) {
-  let url;
-  try {
-    url = new URL(issuer);
-  } catch {
-    throw new ConfigurationError("Cbox ID config `issuer` is not a valid URL.");
-  }
-  if (url.protocol === "https:") {
-    return;
-  }
-  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]" || url.hostname === "::1";
-  if (url.protocol === "http:" && loopback) {
-    return;
-  }
-  throw new ConfigurationError(
-    `Cbox ID config \`issuer\` must be https (got ${url.protocol}//${url.hostname}).`
-  );
-}
-
 // src/client.ts
 var CboxIdClient = class {
   constructor(config) {
@@ -306,9 +351,6 @@ var CboxIdClient = class {
     if (!config.clientId) {
       throw new ConfigurationError("Cbox ID config `clientId` is required.");
     }
-    if (!config.redirectUri) {
-      throw new ConfigurationError("Cbox ID config `redirectUri` is required.");
-    }
     assertSecureIssuer(config.issuer);
     this.discovery = new Discovery(
       config.issuer,
@@ -325,21 +367,29 @@ var CboxIdClient = class {
    * to {@link authenticate} on the callback.
    */
   async createAuthorizationRequest(options = {}) {
+    const prompt = promptValue(options.prompt);
+    assertOrganizationOptions(options, prompt);
     const codeVerifier = createVerifier();
     const state = options.state ?? randomToken(16);
     const nonce = randomToken(16);
+    const redirectUri = options.redirectUri ?? this.config.redirectUri;
+    if (redirectUri === void 0 || redirectUri === "") {
+      throw new ConfigurationError(
+        "A `redirectUri` is required to start the browser sign-in flow. Set it in the config, or pass it to createAuthorizationRequest."
+      );
+    }
     const params = new URLSearchParams({
       response_type: "code",
       client_id: this.config.clientId,
-      redirect_uri: options.redirectUri ?? this.config.redirectUri,
+      redirect_uri: redirectUri,
       scope: (options.scopes ?? this.scopes()).join(" "),
       state,
       nonce,
       code_challenge: await challenge(codeVerifier),
       code_challenge_method: "S256"
     });
-    if (options.prompt) {
-      params.set("prompt", options.prompt);
+    if (prompt.length > 0) {
+      params.set("prompt", prompt.join(" "));
     }
     if (options.loginHint) {
       params.set("login_hint", options.loginHint);
@@ -347,6 +397,12 @@ var CboxIdClient = class {
     if (typeof options.maxAge === "number") {
       params.set("max_age", String(options.maxAge));
     }
+    if (options.organization !== void 0) {
+      params.set("organization", options.organization);
+    }
+    if (options.organizationHint !== void 0) {
+      params.set("organization_hint", options.organizationHint);
+    }
     const endpoint = await this.discovery.endpoint("authorization_endpoint");
     return {
       url: `${endpoint}?${params.toString()}`,
@@ -355,9 +411,27 @@ var CboxIdClient = class {
       nonce,
       // Carried through so authenticate() can hold the instance to it. Only present
       // when requested (exactOptionalPropertyTypes).
-      ...typeof options.maxAge === "number" ? { maxAge: options.maxAge } : {}
+      ...typeof options.maxAge === "number" ? { maxAge: options.maxAge } : {},
+      ...options.organization !== void 0 ? { organization: options.organization } : {}
     };
   }
+  /**
+   * Switch the signed-in person to another organization: a new authorization bound to
+   * `organizationId`. Persist and redirect exactly as for
+   * {@link createAuthorizationRequest} — it is one, with `organization` set.
+   *
+   * Cbox ID already holds the person's session, so this is normally a redirect there and
+   * straight back with no sign-in form. The tokens that come back carry the new `org`,
+   * `org_role`, `roles` and `permissions`; replace your session with them rather than
+   * patching the old one, because every one of those can differ between organizations.
+   *
+   * A person who is not (or is no longer) an active member of that organization comes
+   * back with `error=access_denied`, which {@link authenticate} throws as an
+   * `AuthenticationError` with `error === 'access_denied'`.
+   */
+  switchOrganization(organizationId, options = {}) {
+    return this.createAuthorizationRequest({ ...options, organization: organizationId });
+  }
   /**
    * Complete login on your callback route: verify state, exchange the code with the
    * PKCE verifier, verify the id_token, and return the authenticated user.
@@ -372,7 +446,9 @@ var CboxIdClient = class {
     }
     if (params.error) {
       throw new AuthenticationError(
-        `Cbox ID returned an error: ${params.error}${params.error_description ? ` (${params.error_description})` : ""}`
+        `Cbox ID returned an error: ${params.error}${params.error_description ? ` (${params.error_description})` : ""}`,
+        params.error,
+        params.error_description ?? void 0
       );
     }
     if (!params.code) {
@@ -394,6 +470,24 @@ var CboxIdClient = class {
         "A max_age was requested but no id_token was returned, so the authentication age could not be verified."
       );
     }
+    const user = await this.identityFrom(tokens, verified);
+    if (stored.organization !== void 0 && user.organizationId !== stored.organization) {
+      throw new AuthenticationError(
+        `The sign-in was bound to organization ${stored.organization}, but the tokens are for ${user.organizationId ?? "no organization"}. The instance may not support organization selection.`
+      );
+    }
+    return user;
+  }
+  /**
+   * Turn a token response into the verified {@link CboxUser} every flow returns.
+   *
+   * Shared by the browser flow and the device flow rather than written twice: the checks
+   * in here — the UserInfo subject matching the id_token's, the merge that lets UserInfo
+   * enrich but never overwrite signed claims — are the ones that decide whether an
+   * identity is trustworthy. A second copy is a second place for one of them to be
+   * quietly missing, and the flow it was missing from would look exactly as correct.
+   */
+  async identityFrom(tokens, verified) {
     const profile = await this.userinfo(tokens.access_token);
     const verifiedSub = verified["sub"];
     const profileSub = profile["sub"];
@@ -411,6 +505,11 @@ var CboxIdClient = class {
       email: typeof claims["email"] === "string" ? claims["email"] : null,
       name: typeof claims["name"] === "string" ? claims["name"] : null,
       organizationId: typeof claims["org"] === "string" ? claims["org"] : null,
+      organization: organization(claims),
+      roles: roles(claims),
+      permissions: permissions(claims),
+      actor: actor(claims),
+      sessionId: sessionId(claims),
       // Only present when the instance emitted the claim (exactOptionalPropertyTypes).
       ...organizations ? { organizations } : {},
       claims,
@@ -420,6 +519,118 @@ var CboxIdClient = class {
       expiresIn: typeof tokens.expires_in === "number" ? tokens.expires_in : 0
     };
   }
+  /**
+   * Start the device authorization grant (RFC 8628) — the flow for a program with no
+   * browser of its own: a CLI, a CI job, a container, a TV.
+   *
+   * Print `userCode` and `verificationUri`, then call
+   * {@link CboxIdClient.pollDeviceToken}. If the machine has a desktop you may also open
+   * `verificationUriComplete`, which fills the code in — but print the code anyway: the
+   * machine running your program is often not the one the person is looking at.
+   *
+   * The scopes are bounded by what the app is REGISTERED for. A device request naming one
+   * outside that ceiling is refused with `invalid_scope` rather than quietly reduced,
+   * because no browser is in front of it to notice a smaller grant.
+   *
+   * @throws ConfigurationError when the instance advertises no device endpoint.
+   */
+  async requestDeviceAuthorization(scopes) {
+    const endpoint = await this.discovery.optionalEndpoint("device_authorization_endpoint");
+    if (endpoint === null) {
+      throw new ConfigurationError(
+        "This instance does not advertise a device_authorization_endpoint, so it does not support CLI sign-in."
+      );
+    }
+    const body = new URLSearchParams({
+      client_id: this.config.clientId,
+      scope: (scopes ?? this.scopes()).join(" ")
+    });
+    if (this.config.clientSecret) {
+      body.set("client_secret", this.config.clientSecret);
+    }
+    const response = await this.post(endpoint, body);
+    if (!response.ok) {
+      throw await oauthError(response, "Device authorization request failed");
+    }
+    const payload = await response.json();
+    const deviceCode = payload["device_code"];
+    const userCode = payload["user_code"];
+    const verificationUri = payload["verification_uri"];
+    if (typeof deviceCode !== "string" || typeof userCode !== "string" || typeof verificationUri !== "string") {
+      throw new AuthenticationError("The device authorization response was incomplete.");
+    }
+    return {
+      deviceCode,
+      userCode,
+      verificationUri,
+      verificationUriComplete: typeof payload["verification_uri_complete"] === "string" ? payload["verification_uri_complete"] : null,
+      expiresIn: typeof payload["expires_in"] === "number" ? payload["expires_in"] : 600,
+      // RFC 8628 §3.2: absent means 5 seconds. Polling faster than the server allows is
+      // answered with `slow_down`, so the default is the one the server assumes too.
+      interval: typeof payload["interval"] === "number" ? payload["interval"] : 5
+    };
+  }
+  /**
+   * Poll until the person approves, and return them.
+   *
+   * Blocks. It honours the server's `interval`, backs off permanently by five seconds on
+   * `slow_down` (RFC 8628 §3.5), and stops on the three answers that are final: they
+   * declined, the code expired, or tokens arrived. Pass an `AbortSignal` to give up
+   * early — a CLI should let Ctrl-C work.
+   *
+   * @throws AuthenticationError when the person declines or the code expires.
+   */
+  async pollDeviceToken(authorization, options = {}) {
+    const endpoint = await this.discovery.endpoint("token_endpoint");
+    const deadline = Date.now() + authorization.expiresIn * 1e3;
+    let intervalMs = authorization.interval * 1e3;
+    for (; ; ) {
+      if (options.signal?.aborted === true) {
+        throw new AuthenticationError("Device sign-in was cancelled.");
+      }
+      if (Date.now() > deadline) {
+        throw new AuthenticationError(
+          "The device code expired before it was approved. Start the sign-in again."
+        );
+      }
+      await sleep(intervalMs, options.signal);
+      const body = new URLSearchParams({
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code: authorization.deviceCode,
+        client_id: this.config.clientId
+      });
+      if (this.config.clientSecret) {
+        body.set("client_secret", this.config.clientSecret);
+      }
+      const response = await this.post(endpoint, body);
+      if (response.ok) {
+        const tokens = await response.json();
+        if (!tokens.access_token) {
+          throw new AuthenticationError("The device token response carried no access token.");
+        }
+        const verified = tokens.id_token ? await this.verifyIdToken(tokens.id_token, "") : {};
+        return await this.identityFrom(tokens, verified);
+      }
+      const payload = await response.json().catch(() => ({}));
+      const error = typeof payload["error"] === "string" ? payload["error"] : "invalid_request";
+      if (error === "authorization_pending") {
+        continue;
+      }
+      if (error === "slow_down") {
+        intervalMs += 5e3;
+        continue;
+      }
+      if (error === "access_denied") {
+        throw new AuthenticationError("Sign-in was declined.");
+      }
+      if (error === "expired_token") {
+        throw new AuthenticationError(
+          "The device code expired before it was approved. Start the sign-in again."
+        );
+      }
+      throw await oauthError(response, "Device sign-in failed");
+    }
+  }
   /**
    * Exchange a refresh token for a fresh access token (OAuth 2.0 `refresh_token`
    * grant). Cbox ID rotates refresh tokens and detects reuse, so ALWAYS persist the
@@ -467,6 +678,25 @@ var CboxIdClient = class {
     const base = `${this.config.issuer.replace(/\/$/, "")}${this.accountPath()}`;
     return returnTo ? `${base}?${new URLSearchParams({ return_to: returnTo }).toString()}` : base;
   }
+  /**
+   * The hosted page where a person creates and revokes API keys for your API — Cbox ID's
+   * `/account/api-keys`, preselected to this app (or `clientId`). Keys made there are
+   * checked with `ApiKeyVerifier` from `@cboxdk/id-js/server`.
+   *
+   * `returnTo` becomes a link back to your app, honoured only for an origin the app
+   * registered. `organization` picks which of the person's organizations the keys act in;
+   * omitted, the page uses the one they are in.
+   */
+  apiKeysUrl(options = {}) {
+    const params = new URLSearchParams({ client_id: options.clientId ?? this.config.clientId });
+    if (options.returnTo) {
+      params.set("return_to", options.returnTo);
+    }
+    if (options.organization) {
+      params.set("organization", options.organization);
+    }
+    return `${this.config.issuer.replace(/\/$/, "")}/account/api-keys?${params.toString()}`;
+  }
   /**
    * The RP-initiated logout URL, or null when the instance advertises none.
    *
@@ -606,10 +836,16 @@ var CboxIdClient = class {
     return new VaultClient(this.config.issuer, accessToken, this.config.timeoutMs ?? 1e4);
   }
   async exchange(code, verifier, redirectUri) {
+    const callback = redirectUri ?? this.config.redirectUri;
+    if (callback === void 0 || callback === "") {
+      throw new ConfigurationError(
+        "A `redirectUri` is required to exchange an authorization code. It must be the same one the authorization request used."
+      );
+    }
     const body = new URLSearchParams({
       grant_type: "authorization_code",
       code,
-      redirect_uri: redirectUri ?? this.config.redirectUri,
+      redirect_uri: callback,
       client_id: this.config.clientId,
       code_verifier: verifier
     });
@@ -693,6 +929,37 @@ var CboxIdClient = class {
     }
   }
 };
+function promptValue(prompt) {
+  if (prompt === void 0) {
+    return [];
+  }
+  const values = [...new Set(typeof prompt === "string" ? [prompt] : prompt)];
+  if (values.includes("none") && values.length > 1) {
+    throw new ConfigurationError("`prompt: 'none'` cannot be combined with another prompt value.");
+  }
+  return values;
+}
+function assertOrganizationOptions(options, prompt) {
+  if (options.organization === "") {
+    throw new ConfigurationError("`organization` is empty. Omit it to sign in without binding to an organization.");
+  }
+  if (options.organizationHint === "") {
+    throw new ConfigurationError("`organizationHint` is empty. Omit it when you have no organization to suggest.");
+  }
+  if (options.organization === void 0) {
+    return;
+  }
+  if (prompt.includes("select_organization")) {
+    throw new ConfigurationError(
+      "`organization` binds the sign-in to one organization, so `prompt: 'select_organization'` has nothing to choose. Use `organizationHint` to preselect an organization in the picker instead."
+    );
+  }
+  if (prompt.includes("create_organization")) {
+    throw new ConfigurationError(
+      "`organization` binds the sign-in to an existing organization and `prompt: 'create_organization'` creates a new one. Send one or the other."
+    );
+  }
+}
 function timingSafeEqualString(a, b) {
   if (a.length !== b.length) {
     return false;
@@ -721,7 +988,24 @@ function parseOrganizations(claim) {
   }
   return orgs;
 }
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted === true) {
+      reject(new AuthenticationError("Device sign-in was cancelled."));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new AuthenticationError("Device sign-in was cancelled."));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 
-export { AuthenticationError, CboxIdClient, CboxIdError, ConfigurationError, Discovery, FrontendApiError, InvalidStateError, VaultClient, assertSecureIssuer, challenge, createVerifier, randomToken, verifyWebhook };
-//# sourceMappingURL=chunk-3V6OKRWF.js.map
-//# sourceMappingURL=chunk-3V6OKRWF.js.map
+export { CboxIdClient, Discovery, VaultClient, actor, challenge, createVerifier, hasPermission, hasRole, isSupportSession, organization, permissions, randomToken, roles, sessionId, verifyStandardWebhook, verifyWebhook };
+//# sourceMappingURL=chunk-CXGKOJRJ.js.map
+//# sourceMappingURL=chunk-CXGKOJRJ.js.map