@canopy-io/node 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @canopy-io/node
 
+## 0.10.0
+
+### Minor Changes
+
+- f2ee649: `LocalAuthorizer` is held to Canopy's own authorization rules. Its suite replays the conformance vectors Canopy publishes at `/conformance/authorization.json`, the same cases Canopy's API suite replays end to end, and `npm run generate` keeps the copy in step with the published one.
+  
+  The grant roots (`GET /api/v1/identities/:id/grants`) and the hierarchy's parent edges (`GET /api/v1/nodes/parents`) now carry the `model_version` of the authorization model they describe. `LocalAuthorizer` refuses a version it does not know with `CanopyAuthorizerError` (`authorizer.model_version_unknown`), which `authorizationErrorStatus` and the NestJS guard answer as a `500` misconfiguration, rather than walking rows whose meaning has changed. It knows version 1. This release requires a Canopy that sends `model_version`; against one that does not, every check is refused, so upgrade after the API has it.
+  
+  `@canopy-io/nestjs` picks up the new authorizer; its own options and behaviour are unchanged.
+
+## 0.9.0
+
+### Minor Changes
+
+- 436d639: Follows Canopy's paged hierarchy, grant, session and directory group reads. These endpoints now answer `{ items, pagination }`, at most 100 to a page, where they used to answer the whole collection.
+  
+  `LocalAuthorizer`, and so `CanopyGuard`, reads every page of an identity's grant roots (now one row per permission and node) and every page of the hierarchy's parent edges, 100 at a time. Revalidation still costs one request: only the hierarchy's first page is sent with its `ETag`, and a `304` keeps the held copy. When the hierarchy has changed, every page is read again, and a rebuild over several pages is confirmed against the first page's `ETag` so a change made mid-read is not kept half-applied. `snapshot()` gains `grantPages` and `treePages`, the page requests behind `grantFetches` and `treeRequests`. Earlier versions deny every check against a Canopy that answers grants as one row per node, so upgrade before that API reaches you.
+  
+  Caller shapes that changed:
+  
+  - `identities.sessions(id, query?)` returns a `Paginator` instead of a promise of `{ items }`, and takes `page` and `take`. Use `for await`, `.all()` or `.first()`.
+  - `organizations.listDirectoryGroups(id, query?)` returns a `Paginator`, and takes `page`, `take`, `q` (display name or external id) and `sort_by` (`name`, the default, or `created`). The item type is exported as `OrganizationDirectoryGroupItem`.
+  - `permissions.evaluateBulk` takes between 1 and 100 checks; more is refused with a `400`.
+  - The generated types follow the API: `GET /api/v1/nodes` and `GET /api/v1/nodes/:id/tree` answer pages of flat nodes (`ScopedNodeResponseDto`, linked by `parent_node_id`) instead of a nested tree with its scope, `GET /api/v1/nodes/:id/children` is paged, and `IdentityGrantResponseDto` carries `node_id` instead of `nodes`. Several lists' `sort_by` is now typed to the columns each accepts.
+  
+  `@canopy-io/nestjs` picks up the new authorizer; its own options and behaviour are unchanged.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -46,11 +46,14 @@ const { allowed } = await canopy.permissions.evaluate({
   node_id: nodeId,
 });
 
-// Pagination is handled for you, whichever style the endpoint uses.
+// Pagination is handled for you, whichever style the endpoint uses. Every
+// list method returns a Paginator: `for await`, `.all()` or `.first()`.
 for await (const identity of canopy.identities.list({ take: 50 })) {
   console.log(identity.email);
 }
 
+const newest = await canopy.identities.sessions(identityId).first();
+
 // Errors carry a stable code, not just a message.
 try {
   await canopy.assignments.create({
@@ -67,6 +70,10 @@ try {
 }
 ```
 
+Lists answer 20 items a page by default and at most 100 (`take`).
+`permissions.evaluateBulk` takes 1 to 100 checks in one request; more is
+refused with a `400` and nothing is evaluated, so send a larger set in batches.
+
 Anything without a typed wrapper is reachable the same way, with the same envelope handling and retry policy:
 
 ```ts
@@ -243,10 +250,20 @@ const { allowed } = await authorizer.evaluate({
 
 It holds two things: the identity's grant roots, and one copy of your hierarchy
 — read as parent edges from `GET /api/v1/nodes/parents` rather than the full
-tree, which is 3.7x smaller — shared across every identity in the process. A check walks up from the node in
+node list, which is 3.7x smaller — shared across every identity in the process. A check walks up from the node in
 question looking for a grant root — a grant already means _this node and
 everything beneath it_, so the roots are never expanded into their descendants.
 
+Both reads are paged, and the authorizer reads every page, 100 rows at a time:
+`GET /api/v1/identities/:id/grants` answers one row per permission and node
+it was granted at, and the hierarchy arrives 100 parent edges to a page. Only
+the hierarchy's first page is revalidated: its `ETag` covers the whole
+hierarchy, so a `304` keeps the copy held without reading any other page. When
+the hierarchy has changed, every page is read again and the copy rebuilt; a
+rebuild over several pages is then confirmed against the first page's `ETag`,
+and read again if the hierarchy changed while its pages were being read. At
+50,000 nodes a rebuild is 501 requests, and a revalidation is one.
+
 Both are held for at most 60 seconds, which is the delay between an access
 change and it taking effect, including a moved node. Set `ttlMs` to change it,
 up to five minutes (`300_000`); a longer value throws when the authorizer is
@@ -261,8 +278,12 @@ instances behind a load balancer, each keeps its own cache until its TTL runs
 out or it is told to invalidate too.
 
 A failed check (Canopy unreachable, a credential that cannot read the
-hierarchy, an identity not in the Environment) throws rather than answering
-`false`. `authorizationErrorStatus` turns the error into the response to send:
+hierarchy, an identity not in the Environment, or a Canopy serving an
+authorization model this version does not know) throws rather than answering
+`false`. The grant roots and the hierarchy each carry the `model_version` of
+the rules they describe; an unknown one is refused with `CanopyAuthorizerError`
+(`authorizer.model_version_unknown`) instead of being walked as if the rules
+had not changed, and upgrading the package is the fix. `authorizationErrorStatus` turns the error into the response to send:
 `503` when Canopy did not answer, `500` for a misconfiguration no retry fixes,
 `403` for an identity Canopy does not know. The NestJS guard uses the same
 mapping.

package/dist/index.cjs

@@ -615,11 +615,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 }
     );
   }
   /**
@@ -915,11 +927,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 }
     );
   }
   /**
@@ -981,6 +1007,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", {
@@ -1122,6 +1152,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;
@@ -1141,7 +1186,9 @@ var LocalAuthorizer = class {
   pendingTree;
   stats = {
     grantFetches: 0,
+    grantPages: 0,
     treeRequests: 0,
+    treePages: 0,
     treeNotModified: 0
   };
   constructor(client, options = {}) {
@@ -1276,16 +1323,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,
@@ -1310,43 +1377,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) {