@cboxdk/id-js 0.15.1 → 0.17.0

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

@@ -1,63 +1,6 @@
+import { AuthenticationError, ConfigurationError, assertSecureIssuer, InvalidStateError, oauthError } from './chunk-ASOQN47M.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 +20,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) {
@@ -276,26 +288,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 +298,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 +314,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 +344,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 +358,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 +393,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 +417,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 +452,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 +466,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 +625,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 +783,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 +876,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 +935,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, verifyWebhook };
+//# sourceMappingURL=chunk-G3CD7X4U.js.map
+//# sourceMappingURL=chunk-G3CD7X4U.js.map