@canopy-io/node 0.7.2 → 0.9.0

package/dist/index.js

@@ -54,6 +54,8 @@ var CanopyTokenError = class extends Error {
    * - `token.audience_mismatch` — `aud` does not include the configured audience
    * - `token.audience_unverified` — token has an `aud` but none was configured
    * - `token.preauth_not_allowed` — a pre-auth token, which grants no access
+   * - `token.type_not_allowed` — a principal type the verifier does not accept
+   *   (see `allowedTypes`)
    */
   code;
   constructor(code, message, options) {
@@ -611,11 +613,23 @@ var Identities = class {
    * newest first: when and where it was signed in, when it expires, and the
    * organization it is acting in. Read it back after a revoke to confirm,
    * from your own side, that a sign-out took.
+   *
+   * Paginated (20 per page by default, `take` up to 100), so this returns a
+   * `Paginator`: iterate it for every session, or call `.first()` for the
+   * newest. The list takes `page` and `take` only; its order is fixed.
+   *
+   * ```ts
+   * for await (const session of canopy.identities.sessions(id)) { … }
+   * ```
    */
-  sessions(id) {
-    return this.client.request(
-      "GET",
-      `/api/v1/identities/${encodeURIComponent(id)}/sessions`
+  sessions(id, query = {}) {
+    return paginate(
+      (params) => this.client.request(
+        "GET",
+        `/api/v1/identities/${encodeURIComponent(id)}/sessions`,
+        { query: params }
+      ),
+      { ...query }
     );
   }
   /**
@@ -911,11 +925,25 @@ var Organizations = class {
       `/api/v1/organizations/${enc(id)}/directory/activity`
     );
   }
-  /** The groups the provider has pushed, each with its role mapping. */
-  listDirectoryGroups(id) {
-    return this.client.request(
-      "GET",
-      `/api/v1/organizations/${enc(id)}/directory/groups`
+  /**
+   * The groups the provider has pushed, each with its role mapping.
+   *
+   * Paginated (20 per page by default, `take` up to 100), so this returns a
+   * `Paginator`. Sorted by display name unless `sort_by: "created"`; `q`
+   * searches display names and external ids.
+   *
+   * ```ts
+   * for await (const group of canopy.organizations.listDirectoryGroups(id)) { … }
+   * ```
+   */
+  listDirectoryGroups(id, query = {}) {
+    return paginate(
+      (params) => this.client.request(
+        "GET",
+        `/api/v1/organizations/${enc(id)}/directory/groups`,
+        { query: params }
+      ),
+      { ...query }
     );
   }
   /**
@@ -977,6 +1005,10 @@ var Permissions = class {
    *
    * Prefer this to a loop over `evaluate` when rendering a screen: the checks
    * are answered together instead of paying request latency for each.
+   *
+   * One request carries between 1 and 100 checks. More is refused with a
+   * `400` (`CanopyError`, `statusCode` 400) and nothing is evaluated, so split
+   * a larger set into batches of 100.
    */
   evaluateBulk(input, options = {}) {
     return this.client.request("POST", "/api/v1/permissions/evaluate/bulk", {
@@ -1118,6 +1150,11 @@ var Canopy = class {
 var DEFAULT_TTL_MS = 6e4;
 var MAX_TTL_MS = 3e5;
 var MAX_WALK_DEPTH = 256;
+var PAGE_SIZE = 100;
+var MAX_PAGES = 1e4;
+var MAX_TREE_WALKS = 3;
+var GRANTS_PATH = (identityId) => `/api/v1/identities/${encodeURIComponent(identityId)}/grants`;
+var PARENTS_PATH = "/api/v1/nodes/parents";
 var LocalAuthorizer = class {
   client;
   ttlMs;
@@ -1137,7 +1174,9 @@ var LocalAuthorizer = class {
   pendingTree;
   stats = {
     grantFetches: 0,
+    grantPages: 0,
     treeRequests: 0,
+    treePages: 0,
     treeNotModified: 0
   };
   constructor(client, options = {}) {
@@ -1272,16 +1311,36 @@ var LocalAuthorizer = class {
     this.pendingGrants.set(identityId, read);
     return read;
   }
+  /**
+   * Every page of the identity's grant roots, folded into permission → nodes.
+   *
+   * Each row is one permission at one node, so a permission granted at three
+   * nodes arrives as three rows, possibly on different pages. Stopping after
+   * the first page would under-report what the identity holds: a false deny,
+   * the safe direction, but a wrong answer all the same.
+   */
   async fetchGrantRoots(identityId) {
     this.stats.grantFetches += 1;
-    const response = await this.client.request(
-      "GET",
-      `/api/v1/identities/${encodeURIComponent(identityId)}/grants`,
-      this.readOptions
+    const path = GRANTS_PATH(identityId);
+    const rows = paginate(
+      (query) => {
+        this.stats.grantPages += 1;
+        return this.client.request("GET", path, {
+          ...this.readOptions,
+          query
+        });
+      },
+      { page: 1, take: PAGE_SIZE },
+      { maxPages: MAX_PAGES }
     );
     const roots = /* @__PURE__ */ new Map();
-    for (const row of response.items ?? []) {
-      roots.set(row.permission, new Set(row.nodes));
+    for await (const row of rows) {
+      const nodes = roots.get(row.permission);
+      if (nodes) {
+        nodes.add(row.node_id);
+      } else {
+        roots.set(row.permission, /* @__PURE__ */ new Set([row.node_id]));
+      }
     }
     this.grants.set(identityId, {
       roots,
@@ -1306,43 +1365,154 @@ var LocalAuthorizer = class {
    * Revalidate rather than re-read. The hierarchy is the expensive half and
    * the one that changes least, so the common case is a `304` and no transfer
    * at all — the tree stays in memory and only its expiry moves.
+   *
+   * The edges come a page at a time, so only the first page is conditional:
+   * its validator covers the whole hierarchy, and a `304` to it means no page
+   * has changed. On a `200` the remaining pages are read plainly and the map
+   * is rebuilt from every page.
+   *
+   * A walk over several pages is not one snapshot. A node added or removed
+   * between two page reads shifts the rows under the offset, so a row can be
+   * skipped, which would leave a node out of the map until the next refresh.
+   * So the walk is confirmed by asking for the first page again with the
+   * validator it came with: a `304` proves nothing changed while the pages
+   * were read. A `200` is a fresh first page, and the walk starts again from
+   * it, up to {@link MAX_TREE_WALKS} times.
    */
   async fetchTree() {
     this.stats.treeRequests += 1;
     const held = this.tree;
-    const result = await this.client.requestConditional(
+    let first = await this.parentsFirstPage(held?.etag ?? void 0);
+    if (!first.modified) {
+      if (held) {
+        this.stats.treeNotModified += 1;
+        this.tree = { ...held, expiresAt: this.now() + this.ttlMs };
+        return held.parents;
+      }
+      return this.keepTree([], null);
+    }
+    for (let walk = 1; ; walk++) {
+      const edges = await this.parentsRemainingPages(first.data);
+      if (!spansPages(first.data) || first.etag === null) {
+        return this.keepTree(edges, first.etag);
+      }
+      const confirm = await this.parentsFirstPage(first.etag);
+      if (!confirm.modified) {
+        return this.keepTree(edges, first.etag);
+      }
+      if (walk >= MAX_TREE_WALKS) {
+        return this.keepTree(edges, null);
+      }
+      first = confirm;
+    }
+  }
+  parentsFirstPage(etag) {
+    this.stats.treePages += 1;
+    return this.client.requestConditional(
       "GET",
-      "/api/v1/nodes/parents",
-      held?.etag ?? void 0,
-      this.readOptions
+      PARENTS_PATH,
+      etag,
+      { ...this.readOptions, query: { page: 1, take: PAGE_SIZE } }
     );
-    if (!result.modified && held) {
-      this.stats.treeNotModified += 1;
-      this.tree = { ...held, expiresAt: this.now() + this.ttlMs };
-      return held.parents;
+  }
+  /** The first page's edges followed by every later page's. */
+  async parentsRemainingPages(first) {
+    const edges = [...first.items];
+    if (!spansPages(first)) {
+      return edges;
     }
-    const parents = /* @__PURE__ */ new Map();
-    if (result.modified) {
-      const ids = /* @__PURE__ */ new Map();
-      for (const edge of result.data.items) {
-        ids.set(edge.id, edge.id);
-      }
-      for (const edge of result.data.items) {
-        const parent = edge.parent_node_id ?? null;
-        parents.set(
-          edge.id,
-          parent === null ? null : ids.get(parent) ?? parent
-        );
+    const rest = paginate(
+      (query) => {
+        this.stats.treePages += 1;
+        return this.client.request("GET", PARENTS_PATH, {
+          ...this.readOptions,
+          query
+        });
+      },
+      { page: first.pagination.page + 1, take: PAGE_SIZE },
+      { maxPages: MAX_PAGES - 1 }
+    );
+    for await (const page of rest.pages()) {
+      for (const edge of page.items) {
+        edges.push(edge);
       }
     }
+    return edges;
+  }
+  keepTree(edges, etag) {
+    const ids = /* @__PURE__ */ new Map();
+    for (const edge of edges) {
+      ids.set(edge.id, edge.id);
+    }
+    const parents = /* @__PURE__ */ new Map();
+    for (const edge of edges) {
+      const parent = edge.parent_node_id ?? null;
+      parents.set(
+        edge.id,
+        parent === null ? null : ids.get(parent) ?? parent
+      );
+    }
     this.tree = {
       parents,
-      etag: result.modified ? result.etag : held?.etag ?? null,
+      etag,
       expiresAt: this.now() + this.ttlMs
     };
     return parents;
   }
 };
+function spansPages(first) {
+  return first.pagination.has_next_page && first.items.length > 0;
+}
+
+// src/status.ts
+function tokenErrorStatus(error) {
+  if (!isCanopyTokenError(error)) {
+    return { status: 500, message: "Authentication could not be checked." };
+  }
+  if (error.code === "token.jwks_unavailable") {
+    return {
+      status: 503,
+      message: "Authentication is temporarily unavailable."
+    };
+  }
+  return { status: 401, message: "Invalid or expired access token." };
+}
+function authorizationErrorStatus(error) {
+  if (isCanopyAuthorizerError(error)) {
+    return {
+      status: 500,
+      message: `Authorization is misconfigured: ${error.message}`
+    };
+  }
+  if (!isCanopyError(error)) {
+    return {
+      status: 503,
+      message: "Authorization is temporarily unavailable."
+    };
+  }
+  if (error.isAuthFailure) {
+    return {
+      status: 500,
+      message: "Authorization is misconfigured. Check the Canopy API key and its scopes."
+    };
+  }
+  if (error.statusCode === 404 && error.code === null) {
+    return {
+      status: 500,
+      message: `Authorization is misconfigured: ${error.request.method} ${error.request.path} is not served by this Canopy. The SDK requires an API that exposes the identity grants endpoint.`
+    };
+  }
+  if (error.statusCode === 404) {
+    return { status: 403, message: "Could not evaluate the permission." };
+  }
+  if (error.isRateLimited || error.statusCode >= 500) {
+    return {
+      status: 503,
+      message: "Authorization is temporarily unavailable."
+    };
+  }
+  return { status: 500, message: "Authorization could not be evaluated." };
+}
 
 // src/verify.ts
 var HOSTED_ORIGIN = "https://auth.canopy-io.com";
@@ -1404,11 +1574,14 @@ var TokenVerifier = class {
   jwksTimeoutMs;
   clockToleranceSec;
   allowPreAuthTokens;
+  allowedTypes;
   fetchImpl;
   /** Imported keys by `kid`, so a repeat verification skips the import cost. */
   keys = /* @__PURE__ */ new Map();
   keysFetchedAt = 0;
   lastFetchAttemptAt = 0;
+  /** Whether the latest read of the key set failed, for an unknown `kid`. */
+  lastFetchFailed = false;
   /** In-flight fetch, so a burst of requests triggers one call, not N. */
   inFlight = null;
   constructor(options = {}) {
@@ -1420,6 +1593,7 @@ var TokenVerifier = class {
     this.jwksTimeoutMs = options.jwksTimeoutMs ?? DEFAULT_JWKS_TIMEOUT_MS;
     this.clockToleranceSec = options.clockToleranceSec ?? DEFAULT_CLOCK_TOLERANCE_SEC;
     this.allowPreAuthTokens = options.allowPreAuthTokens ?? false;
+    this.allowedTypes = new Set(options.allowedTypes ?? ["identity"]);
     const boundFetch = options.fetch ?? globalThis.fetch;
     if (typeof boundFetch !== "function") {
       throw new TypeError(
@@ -1497,6 +1671,14 @@ var TokenVerifier = class {
         `Token has an unrecognised \`type\` claim: ${JSON.stringify(claims.type)}.`
       );
     }
+    if (!this.allowedTypes.has(claims.type)) {
+      throw new CanopyTokenError(
+        "token.type_not_allowed",
+        `Token is for a "${claims.type}" principal; this verifier accepts ${[
+          ...this.allowedTypes
+        ].map((type) => `"${type}"`).join(", ")}. Set \`allowedTypes\` to accept another.`
+      );
+    }
     if (claims.iss !== this.issuer) {
       throw new CanopyTokenError(
         "token.issuer_mismatch",
@@ -1569,7 +1751,13 @@ var TokenVerifier = class {
     const stale = Date.now() - this.keysFetchedAt > this.jwksCacheMaxAgeMs;
     if (this.keys.size === 0 || stale) {
       if (this.shouldRefresh()) {
-        await this.refreshKeys();
+        try {
+          await this.refreshKeys();
+        } catch (error) {
+          if (this.keys.size === 0) {
+            throw error;
+          }
+        }
       } else if (this.keys.size === 0) {
         throw new CanopyTokenError(
           "token.jwks_unavailable",
@@ -1588,6 +1776,12 @@ var TokenVerifier = class {
     if (rotated) {
       return rotated;
     }
+    if (this.lastFetchFailed) {
+      throw new CanopyTokenError(
+        "token.jwks_unavailable",
+        `Signing keys at ${this.jwksUri} could not be read to look up kid "${kid}".`
+      );
+    }
     throw new CanopyTokenError(
       "token.key_not_found",
       `No signing key matches kid "${kid}".`
@@ -1618,6 +1812,15 @@ var TokenVerifier = class {
   }
   async fetchKeys() {
     this.lastFetchAttemptAt = Date.now();
+    try {
+      await this.readKeys();
+      this.lastFetchFailed = false;
+    } catch (error) {
+      this.lastFetchFailed = true;
+      throw error;
+    }
+  }
+  async readKeys() {
     let response;
     const controller = new AbortController();
     const timer = this.jwksTimeoutMs > 0 ? setTimeout(() => controller.abort(), this.jwksTimeoutMs) : void 0;
@@ -1690,6 +1893,6 @@ function isWebhookEvent(delivery, name) {
   return delivery.event === name;
 }
 
-export { Assignments, Canopy, CanopyAuthorizerError, CanopyClient, CanopyConnectionError, CanopyError, CanopyTokenError, Identities, LocalAuthorizer, MAX_TTL_MS, Organizations, Paginator, Permissions, Roles, TokenVerifier, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, orgContext, paginate, withConcurrency };
+export { Assignments, Canopy, CanopyAuthorizerError, CanopyClient, CanopyConnectionError, CanopyError, CanopyTokenError, Identities, LocalAuthorizer, MAX_TTL_MS, Organizations, Paginator, Permissions, Roles, TokenVerifier, authorizationErrorStatus, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, orgContext, paginate, tokenErrorStatus, withConcurrency };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map