@cboxdk/id-js 0.15.1 → 0.17.0

package/dist/index.cjs

@@ -563,6 +563,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) {
@@ -708,9 +777,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,
@@ -727,21 +793,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);
@@ -749,6 +823,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()}`,
@@ -757,9 +837,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.
@@ -774,7 +872,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) {
@@ -796,6 +896,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"];
@@ -813,6 +931,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,
@@ -822,6 +945,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
@@ -869,6 +1104,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.
    *
@@ -1008,10 +1262,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
     });
@@ -1095,6 +1355,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;
@@ -1123,25 +1414,44 @@ 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 });
+  });
+}
 
 // src/authz.ts
 function defineAuthz(declaration) {
-  const permissions = declaration.permissions ?? [];
-  const roles = declaration.roles ?? [];
-  assertDeclaration(permissions, roles);
+  const permissions2 = declaration.permissions ?? [];
+  const roles2 = declaration.roles ?? [];
+  assertDeclaration(permissions2, roles2);
   if (declaration.legacyLogin) {
     assertLegacyLogin(declaration.legacyLogin);
   }
-  return { ...declaration, permissions, roles };
+  return { ...declaration, permissions: permissions2, roles: roles2 };
 }
 async function buildManifest(declaration) {
-  const permissions = (declaration.permissions ?? []).map(canonicalPermission);
-  const roles = (declaration.roles ?? []).map(canonicalRole);
-  assertDeclaration(permissions, roles);
-  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);
-  const manifest = { version, permissions, roles };
+  const permissions2 = declaration.permissions ?? [];
+  const roles2 = declaration.roles ?? [];
+  assertDeclaration(permissions2, roles2);
+  const version = (await sha256Hex(canonicalManifestJson(permissions2, roles2))).slice(0, 16);
+  const manifest = {
+    version,
+    permissions: [...permissions2].sort((a, b) => byteCompare(a.key, b.key)).map(wirePermission),
+    roles: [...roles2].sort((a, b) => byteCompare(a.key, b.key)).map(wireRole)
+  };
   if (declaration.legacyLogin) {
     assertLegacyLogin(declaration.legacyLogin);
     manifest.legacy_login = declaration.legacyLogin;
@@ -1198,28 +1508,33 @@ async function mintToken(config, discovery, timeoutMs) {
   }
   return json2.access_token;
 }
-function assertDeclaration(permissions, roles) {
+var KEY_PATTERN = /^[a-z][a-z0-9_-]*(?:[.:][a-z0-9_-]+)*$/;
+function assertDeclaration(permissions2, roles2) {
   const permissionKeys = /* @__PURE__ */ new Set();
-  for (const permission of permissions) {
+  for (const permission of permissions2) {
     if (!permission.key) {
       throw new ConfigurationError("Every permission needs a non-empty `key`.");
     }
+    assertKey(permission.key, "Permission");
     if (permissionKeys.has(permission.key)) {
       throw new ConfigurationError(`Permission "${permission.key}" is declared more than once.`);
     }
+    assertFlag(permission.tenantAssignable, `Permission "${permission.key}"`);
     permissionKeys.add(permission.key);
   }
   const roleKeys = /* @__PURE__ */ new Set();
-  for (const role of roles) {
+  for (const role of roles2) {
     if (!role.key) {
       throw new ConfigurationError("Every role needs a non-empty `key`.");
     }
+    assertKey(role.key, "Role");
     if (!role.name) {
       throw new ConfigurationError(`Role "${role.key}" needs a non-empty \`name\`.`);
     }
     if (roleKeys.has(role.key)) {
       throw new ConfigurationError(`Role "${role.key}" is declared more than once.`);
     }
+    assertFlag(role.tenantAssignable, `Role "${role.key}"`);
     roleKeys.add(role.key);
     for (const reference of role.permissions) {
       if (!permissionKeys.has(reference)) {
@@ -1230,25 +1545,54 @@ function assertDeclaration(permissions, roles) {
     }
   }
 }
-function canonicalPermission(permission) {
-  return permission.description === void 0 ? { key: permission.key } : { key: permission.key, description: permission.description };
+function assertKey(key, what) {
+  if (!KEY_PATTERN.test(key)) {
+    throw new ConfigurationError(
+      `${what} key "${key}" is not a lowercase \`feature:action\` slug (e.g. \`invoices:create\`).`
+    );
+  }
 }
-function canonicalRole(role) {
-  const permissions = [...role.permissions].sort(byteCompare);
-  return role.description === void 0 ? { key: role.key, name: role.name, permissions } : { key: role.key, name: role.name, description: role.description, permissions };
+function assertFlag(value, owner) {
+  if (value !== void 0 && typeof value !== "boolean") {
+    throw new ConfigurationError(`${owner} \`tenantAssignable\` must be true or false.`);
+  }
+}
+function wirePermission(permission) {
+  return {
+    key: permission.key,
+    ...permission.description === void 0 ? {} : { description: permission.description },
+    ...permission.tenantAssignable === true ? { tenant_assignable: true } : {}
+  };
 }
-function canonicalManifestJson(permissions, roles) {
+function wireRole(role) {
+  return {
+    key: role.key,
+    name: role.name,
+    ...role.description === void 0 ? {} : { description: role.description },
+    permissions: uniqueSorted(role.permissions),
+    ...role.tenantAssignable === false ? { tenant_assignable: false } : {}
+  };
+}
+function canonicalManifestJson(permissions2, roles2) {
   const canonical = {
-    permissions: [...permissions].sort((a, b) => byteCompare(a.key, b.key)).map((p) => ({ key: p.key, description: emptyToNull(p.description) })),
-    roles: [...roles].sort((a, b) => byteCompare(a.key, b.key)).map((r) => ({
+    permissions: [...permissions2].sort((a, b) => byteCompare(a.key, b.key)).map((p) => ({
+      key: p.key,
+      description: emptyToNull(p.description),
+      ...p.tenantAssignable === true ? { tenant_assignable: true } : {}
+    })),
+    roles: [...roles2].sort((a, b) => byteCompare(a.key, b.key)).map((r) => ({
       key: r.key,
       name: r.name,
       description: emptyToNull(r.description),
-      permissions: [...r.permissions].sort(byteCompare)
+      permissions: uniqueSorted(r.permissions),
+      ...r.tenantAssignable === false ? { tenant_assignable: false } : {}
     }))
   };
   return escapeLikePhp(JSON.stringify(canonical));
 }
+function uniqueSorted(values) {
+  return [...new Set(values)].sort(byteCompare);
+}
 function emptyToNull(value) {
   return value === void 0 || value === "" ? null : value;
 }
@@ -1300,13 +1644,21 @@ exports.ConfigurationError = ConfigurationError;
 exports.FrontendApiError = FrontendApiError;
 exports.InvalidStateError = InvalidStateError;
 exports.VaultClient = VaultClient;
+exports.actor = actor;
 exports.buildManifest = buildManifest;
 exports.challenge = challenge;
 exports.createLegacyVerifier = createLegacyVerifier;
 exports.createVerifier = createVerifier;
 exports.defineAuthz = defineAuthz;
+exports.hasPermission = hasPermission;
+exports.hasRole = hasRole;
+exports.isSupportSession = isSupportSession;
+exports.organization = organization;
+exports.permissions = permissions;
 exports.publishManifest = publishManifest;
 exports.randomToken = randomToken;
+exports.roles = roles;
+exports.sessionId = sessionId;
 exports.verifyWebhook = verifyWebhook;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map