@canopy-io/node 0.8.0 → 0.10.0

package/dist/index.js

@@ -613,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 }
     );
   }
   /**
@@ -913,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 }
     );
   }
   /**
@@ -979,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", {
@@ -1120,6 +1150,21 @@ 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 KNOWN_MODEL_VERSIONS = /* @__PURE__ */ new Set([1]);
+function understood(page, path) {
+  if (!KNOWN_MODEL_VERSIONS.has(page.model_version)) {
+    throw new CanopyAuthorizerError(
+      "authorizer.model_version_unknown",
+      `${path} describes authorization model version ${page.model_version}, which this version of @canopy-io/node does not understand. It knows ${[...KNOWN_MODEL_VERSIONS].join(", ")}. Upgrade @canopy-io/node; until then this authorizer cannot decide, rather than guess.`
+    );
+  }
+  return page;
+}
+var GRANTS_PATH = (identityId) => `/api/v1/identities/${encodeURIComponent(identityId)}/grants`;
+var PARENTS_PATH = "/api/v1/nodes/parents";
 var LocalAuthorizer = class {
   client;
   ttlMs;
@@ -1139,7 +1184,9 @@ var LocalAuthorizer = class {
   pendingTree;
   stats = {
     grantFetches: 0,
+    grantPages: 0,
     treeRequests: 0,
+    treePages: 0,
     treeNotModified: 0
   };
   constructor(client, options = {}) {
@@ -1274,16 +1321,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
+        }).then((page) => understood(page, path));
+      },
+      { 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,
@@ -1308,43 +1375,107 @@ 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(
-      "GET",
-      "/api/v1/nodes/parents",
-      held?.etag ?? void 0,
-      this.readOptions
-    );
-    if (!result.modified && held) {
-      this.stats.treeNotModified += 1;
-      this.tree = { ...held, expiresAt: this.now() + this.ttlMs };
-      return held.parents;
+    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);
     }
-    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 (let walk = 1; ; walk++) {
+      const edges = await this.parentsRemainingPages(first.data);
+      if (!spansPages(first.data) || first.etag === null) {
+        return this.keepTree(edges, first.etag);
       }
-      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 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", PARENTS_PATH, etag, {
+      ...this.readOptions,
+      query: { page: 1, take: PAGE_SIZE }
+    }).then((result) => {
+      if (result.modified) {
+        understood(result.data, PARENTS_PATH);
+      }
+      return result;
+    });
+  }
+  /** The first page's edges followed by every later page's. */
+  async parentsRemainingPages(first) {
+    const edges = [...first.items];
+    if (!spansPages(first)) {
+      return edges;
+    }
+    const rest = paginate(
+      (query) => {
+        this.stats.treePages += 1;
+        return this.client.request("GET", PARENTS_PATH, {
+          ...this.readOptions,
+          query
+        }).then((page) => understood(page, PARENTS_PATH));
+      },
+      { 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) {