@canopy-io/node 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @canopy-io/node
 
+## 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
+
+- 621b9a6: `TokenVerifier` accepts identity tokens only by default. Tokens Canopy signs for its own administrators (`user`), staff (`platform`) and API key flows (`api_key`) are refused with `token.type_not_allowed` unless named in the new `allowedTypes` option; `CanopyTokenGuard` takes it under `verify.allowedTypes`.
+  
+  When Canopy cannot be reached as cached signing keys come due for a refresh, the verifier keeps verifying with the keys it holds instead of failing every request until the issuer is back. A token signed by a key the verifier has never seen, during an outage, is reported as `token.jwks_unavailable` (503) rather than `token.key_not_found` (401).
+  
+  New exports `tokenErrorStatus` and `authorizationErrorStatus` turn a failed verification or authorization check into the HTTP status and message to answer with; the NestJS guards use them. The node README's verification example now names its Environment, and documents the 503 and the per-process reach of `LocalAuthorizer.invalidate()`.
+
 ## 0.7.2
 
 ### Patch 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
@@ -82,27 +89,39 @@ access tokens RS256 and publishes the keys, so a token is checked locally —
 one JWKS fetch, then no network on any verification after it.
 
 ```ts
-import { TokenVerifier, isCanopyTokenError } from "@canopy-io/node";
+import { TokenVerifier, tokenErrorStatus } from "@canopy-io/node";
 
-const verifier = new TokenVerifier();
+const verifier = new TokenVerifier({
+  environmentId: process.env.CANOPY_ENVIRONMENT_ID,
+});
 
 try {
   const claims = await verifier.verify(bearerToken);
 
-  claims.sub; // the identity or user id
-  claims.type; // "identity" | "user" | "api_key" | "platform"
+  claims.sub; // the identity's id
+  claims.type; // "identity", the only type accepted by default
   claims.environment_id; // present on identity tokens
 } catch (error) {
-  if (isCanopyTokenError(error)) {
-    // Every code here means 401 to the caller who presented the token.
-    // `error.code` is for your logs: token.expired, token.signature_invalid,
-    // token.issuer_mismatch, and so on.
-  }
+  // 401 when the token is at fault, 503 when the signing keys could not be
+  // read and the token may be good. `error.code` is for your logs:
+  // token.expired, token.signature_invalid, token.jwks_unavailable, ...
+  const { status, message } = tokenErrorStatus(error);
 
-  throw error;
+  return response.status(status).json({ message });
 }
 ```
 
+A verifier accepts only identity tokens, the people who sign in to your
+application. Canopy signs tokens for its own administrators (`user`), its
+staff (`platform`) and some API key flows (`api_key`) with the same keys and
+issuer, so they are refused with `token.type_not_allowed` unless you name them:
+`new TokenVerifier({ ..., allowedTypes: ["identity", "user"] })`.
+
+If Canopy cannot be reached when the cached keys are due for a refresh, the
+verifier keeps verifying with the keys it holds; only a verifier that has never
+loaded a key set, or a token signed by a key it has never seen, answers
+`token.jwks_unavailable`.
+
 Hosted Login tokens carry an audience, your `client_id`, so name your client.
 Direct API tokens carry none and need no option. A token that has an `aud` is
 refused rather than ignored when you have not said which client you are, so a
@@ -231,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
@@ -243,6 +272,34 @@ every request then finds the cache expired and refetches.
 
 `canopy.permissions.evaluate` remains for a decision with no staleness at all.
 
+`authorizer.invalidate(identityId)` drops one identity's cached grants, so
+the next check reads them fresh. It reaches only this process: with several
+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:
+`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.
+
+```ts
+import { authorizationErrorStatus } from "@canopy-io/node";
+
+try {
+  const { allowed } = await authorizer.evaluate(query);
+
+  if (!allowed) {
+    return response.status(403).json({ message: "Forbidden" });
+  }
+} catch (error) {
+  const { status, message } = authorizationErrorStatus(error);
+
+  return response.status(status).json({ message });
+}
+```
+
 The credential needs to be able to read both halves. A `full_access` API key
 already can; a **scoped** one must list `identity.view` (the grant roots) and
 `hierarchy.view` (the tree). Without the latter the tree endpoint answers an

package/dist/index.cjs

@@ -56,6 +56,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) {
@@ -613,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 }
     );
   }
   /**
@@ -913,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 }
     );
   }
   /**
@@ -979,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", {
@@ -1120,6 +1152,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;
@@ -1139,7 +1176,9 @@ var LocalAuthorizer = class {
   pendingTree;
   stats = {
     grantFetches: 0,
+    grantPages: 0,
     treeRequests: 0,
+    treePages: 0,
     treeNotModified: 0
   };
   constructor(client, options = {}) {
@@ -1274,16 +1313,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,
@@ -1308,43 +1367,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";
@@ -1406,11 +1576,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 = {}) {
@@ -1422,6 +1595,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(
@@ -1499,6 +1673,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",
@@ -1571,7 +1753,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",
@@ -1590,6 +1778,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}".`
@@ -1620,6 +1814,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;
@@ -1707,6 +1910,7 @@ exports.Paginator = Paginator;
 exports.Permissions = Permissions;
 exports.Roles = Roles;
 exports.TokenVerifier = TokenVerifier;
+exports.authorizationErrorStatus = authorizationErrorStatus;
 exports.isCanopyAuthorizerError = isCanopyAuthorizerError;
 exports.isCanopyConnectionError = isCanopyConnectionError;
 exports.isCanopyError = isCanopyError;
@@ -1715,6 +1919,7 @@ exports.isCursorPagination = isCursorPagination;
 exports.isWebhookEvent = isWebhookEvent;
 exports.orgContext = orgContext;
 exports.paginate = paginate;
+exports.tokenErrorStatus = tokenErrorStatus;
 exports.withConcurrency = withConcurrency;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map