@canopy-io/node 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @canopy-io/node
 
+## 0.11.0
+
+### Minor Changes
+
+- 6cbddf8: `LocalAuthorizer` answers the list question, says why a check was denied, and hears every verdict.
+  
+  - `grantRoots(identityId, permission)`: the nodes the permission is granted at, in effect now, minus the ones another root already covers, with `envWide` when one is the Environment's root.
+  - `accessibleNodes(identityId, permission, { maxNodes })`: those roots expanded through their descendants into a `Set` for an `IN (...)` filter, from the same cached tree a check walks. Capped at `maxNodes` (10,000 by default, settable per authorizer or per call); past the cap `nodes` is null and `complete` false, and the roots filter a closure table or materialised path instead.
+  - `permissionsAt(identityId, nodeId)`: every permission the identity holds at the node, by grant or inheritance; `permissionsAtMany(identityId, nodeIds)` answers several nodes from one read.
+  - `evaluate` returns `{ allowed, reason }`. On a denial `reason` is `permission_not_held`, `outside_grants`, `expired`, `not_yet_effective` or `node_missing`. The grant roots are read with `include=windows`, so a grant that ends before the TTL is re-read at its boundary.
+  - `onDecision` and `onDenied` options, fired after every verdict and never awaited; a hook that throws is ignored.
+  - `canopy.identities.accessibleNodes(id, { permission, max_nodes })` wraps `GET /api/v1/identities/:id/accessible-nodes`, and `canopy.identities.permissions(id, { node_id })` takes the node.
+  
+  This version reads `GET /api/v1/identities/:id/grants?include=windows`, which Canopy serves from the same release that adds the accessible-nodes endpoint; against an older API the read is refused and every check fails, so upgrade after the API has it.
+  
+  `@canopy-io/nestjs` accepts `onDecision` and `onDenied` in `CanopyModuleOptions` and passes them to the authorizer; the guard's own behaviour is unchanged.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -270,6 +270,53 @@ up to five minutes (`300_000`); a longer value throws when the authorizer is
 created. Shortening it below the gap between a user's requests saves nothing:
 every request then finds the cache expired and refetches.
 
+Each answer carries a reason when it is no, from what the grant roots and the
+tree can say: `permission_not_held`, `outside_grants`, `expired`,
+`not_yet_effective`, or `node_missing` for a `node` check with no node. The
+grant roots are read with their windows, so a grant that ends sooner than the
+TTL is dropped at its boundary, not at the next expiry. `onDecision` and
+`onDenied` hooks hear every verdict after it is reached, never awaited and
+never able to change it, for audit trails and alerting without a fork of the
+guard.
+
+```ts
+const authorizer = new LocalAuthorizer(canopy.client, {
+  onDenied: ({ query, decision }) =>
+    audit.record("denied", { ...query, reason: decision.reason }),
+});
+```
+
+A list needs the other direction: which nodes may this identity see. The same
+cache answers it, in the shape your query wants. `grantRoots` names the nodes
+the permission is granted at, in effect now, minus the ones another root
+already covers, and says whether one is the Environment's root (`envWide`:
+every node qualifies, so no filter). `accessibleNodes` expands those roots
+through their descendants into a `Set` for an `IN (...)` filter, capped at
+`maxNodes` (10,000 by default, per authorizer or per call); past the cap it
+hands back the roots with `nodes: null` and `complete: false`, so an
+application with a closure table or a materialised path filters by "beneath a
+root" instead. `permissionsAt` lists what the identity holds at one node, for
+rendering a screen's controls, and `permissionsAtMany` answers several nodes
+from one read, for the rows of a list.
+
+```ts
+const access = await authorizer.accessibleNodes(identityId, "reports.view");
+
+if (access.envWide) {
+  return db.reports.findMany();
+}
+
+if (!access.complete) {
+  // Too large for an IN (...) list: filter beneath access.roots instead.
+}
+
+return db.reports.findMany({ where: { nodeId: { in: [...access.nodes] } } });
+```
+
+A list filtered this way is what to show; the write that follows still checks
+its node. Canopy answers the same question fresh, for a process without the
+authorizer, as `canopy.identities.accessibleNodes(id, { permission })`.
+
 `canopy.permissions.evaluate` remains for a decision with no staleness at all.
 
 `authorizer.invalidate(identityId)` drops one identity's cached grants, so

package/dist/index.cjs

@@ -604,10 +604,28 @@ var Identities = class {
    * question at the node that matters. This is for showing a person what
    * someone can do.
    */
-  permissions(id) {
+  permissions(id, query = {}) {
     return this.client.request(
       "GET",
-      `/api/v1/identities/${encodeURIComponent(id)}/permissions`
+      `/api/v1/identities/${encodeURIComponent(id)}/permissions`,
+      { query: { ...query } }
+    );
+  }
+  /**
+   * Where the identity may act with one permission, answered by Canopy for a
+   * list query: the minimal grant roots, and every node beneath them up to
+   * `max_nodes` (null past it, with `complete: false`), or `env_wide` when a
+   * root is the Environment's own root and no filter is needed.
+   *
+   * `LocalAuthorizer.accessibleNodes` answers the same question from its
+   * cache without a call; this is the fresh answer, and the one for a process
+   * that does not run the authorizer.
+   */
+  accessibleNodes(id, query) {
+    return this.client.request(
+      "GET",
+      `/api/v1/identities/${encodeURIComponent(id)}/accessible-nodes`,
+      { query: { ...query } }
     );
   }
   /**
@@ -1151,6 +1169,7 @@ var Canopy = class {
 // src/authorizer.ts
 var DEFAULT_TTL_MS = 6e4;
 var MAX_TTL_MS = 3e5;
+var DEFAULT_MAX_NODES = 1e4;
 var MAX_WALK_DEPTH = 256;
 var PAGE_SIZE = 100;
 var MAX_PAGES = 1e4;
@@ -1167,11 +1186,20 @@ function understood(page, path) {
 }
 var GRANTS_PATH = (identityId) => `/api/v1/identities/${encodeURIComponent(identityId)}/grants`;
 var PARENTS_PATH = "/api/v1/nodes/parents";
+function inEffect(window, now) {
+  return (window.from === null || window.from <= now) && (window.to === null || window.to > now);
+}
+function reasonAmong(windows, now) {
+  return windows.some((window) => window.to !== null && window.to <= now) ? "expired" : "not_yet_effective";
+}
 var LocalAuthorizer = class {
   client;
   ttlMs;
+  maxNodes;
   now;
   readOptions;
+  onDecision;
+  onDenied;
   grants = /* @__PURE__ */ new Map();
   tree;
   /**
@@ -1199,22 +1227,39 @@ var LocalAuthorizer = class {
         `ttlMs must be between 0 and ${MAX_TTL_MS} (five minutes); got ${String(this.ttlMs)}. It is how long a revoked user keeps access, so it is capped.`
       );
     }
+    this.maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+    if (!Number.isInteger(this.maxNodes) || this.maxNodes < 1) {
+      throw new RangeError(
+        `maxNodes must be a positive integer; got ${String(this.maxNodes)}.`
+      );
+    }
     this.now = options.now ?? (() => Date.now());
+    this.onDecision = options.onDecision;
+    this.onDenied = options.onDenied;
     this.readOptions = {
       ...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
       ...options.maxRetries === void 0 ? {} : { maxRetries: options.maxRetries, maxBackoffMs: options.timeoutMs }
     };
   }
   /**
-   * Whether the identity holds the permission.
+   * Whether the identity holds the permission, and why not when it does not.
    *
    * Shaped like the API's own evaluate so a caller can swap one for the other.
    * A `node` check with no node is a denial rather than an error: a request
    * whose subject cannot be established is exactly the one that must not pass.
    */
   async evaluate(query, options = {}) {
+    const started = this.now();
+    const decided = (decision) => {
+      this.announce({
+        query,
+        decision,
+        durationMs: Math.max(0, this.now() - started)
+      });
+      return decision;
+    };
     if (!options.signal) {
-      return this.decide(query);
+      return decided(await this.decide(query));
     }
     const signal = options.signal;
     let onAbort;
@@ -1231,25 +1276,157 @@ var LocalAuthorizer = class {
       onAbort = fail;
       signal.addEventListener("abort", fail, { once: true });
     });
-    return Promise.race([this.decide(query), aborted]).finally(() => {
+    return Promise.race([this.decide(query), aborted]).then(decided).finally(() => {
       if (onAbort) {
         signal.removeEventListener("abort", onAbort);
       }
     });
   }
+  /**
+   * The nodes the identity holds the permission at, in effect now, reduced to
+   * the ones no other such node already covers, and whether one of them is
+   * the Environment's root. The roots alone are enough for an application
+   * that keeps a closure table or a materialised path: it filters by "beneath
+   * one of these" without an expanded set.
+   *
+   * Reads the tree, since minimality and `envWide` are questions about it; a
+   * root the readable hierarchy does not contain raises
+   * `authorizer.hierarchy_incomplete`, as a check at such a node does.
+   */
+  async grantRoots(identityId, permission) {
+    const now = this.now();
+    const held = (await this.grantRootsFor(identityId)).get(permission) ?? [];
+    const granted = new Set(
+      held.filter((window) => inEffect(window, now)).map((w) => w.node)
+    );
+    if (granted.size === 0) {
+      return { roots: [], envWide: false };
+    }
+    const { parents } = await this.treeEntry();
+    const roots = [];
+    let envWide = false;
+    for (const node of granted) {
+      if (!parents.has(node)) {
+        throw this.hierarchyIncomplete(node);
+      }
+      if (parents.get(node) === null) {
+        envWide = true;
+      }
+      let covered = false;
+      let depth = 0;
+      for (let current = parents.get(node); current && depth < MAX_WALK_DEPTH; current = parents.get(current), depth += 1) {
+        if (granted.has(current)) {
+          covered = true;
+          break;
+        }
+      }
+      if (!covered) {
+        roots.push(node);
+      }
+    }
+    return { roots, envWide };
+  }
+  /**
+   * Where the identity may act with the permission, as the set a list query
+   * filters by: {@link grantRoots} expanded through their descendants, up to
+   * `maxNodes` (the authorizer's default unless given here).
+   *
+   * Past the cap `nodes` is null and `complete` false: the set is too large
+   * to be worth an `IN (...)` list, and the caller filters by `roots`
+   * instead. An `envWide` answer carries no set either, since every node
+   * qualifies and a filter would only slow the query down.
+   *
+   * Computed from the same cached grant roots and tree a check uses, so a
+   * list filtered by it and the check on a write cannot disagree, and it goes
+   * stale on the same `ttlMs`.
+   */
+  async accessibleNodes(identityId, permission, options = {}) {
+    const cap = options.maxNodes ?? this.maxNodes;
+    const { roots, envWide } = await this.grantRoots(identityId, permission);
+    if (envWide) {
+      return { roots, envWide: true, nodes: null, complete: true };
+    }
+    if (roots.length === 0) {
+      return { roots, envWide: false, nodes: /* @__PURE__ */ new Set(), complete: true };
+    }
+    const { children } = await this.treeEntry();
+    const nodes = /* @__PURE__ */ new Set();
+    const pending = [...roots];
+    while (pending.length > 0) {
+      const node = pending.pop();
+      if (nodes.has(node)) {
+        continue;
+      }
+      nodes.add(node);
+      if (nodes.size > cap) {
+        return { roots, envWide: false, nodes: null, complete: false };
+      }
+      for (const child of children.get(node) ?? []) {
+        pending.push(child);
+      }
+    }
+    return { roots, envWide: false, nodes, complete: true };
+  }
+  /**
+   * Every permission the identity holds at the node, by grant or by
+   * inheritance: the list a screen renders its controls from, answered from
+   * the same cached grant roots and tree a check uses.
+   */
+  async permissionsAt(identityId, nodeId) {
+    const answers = await this.permissionsAtMany(identityId, [nodeId]);
+    return answers.get(nodeId) ?? [];
+  }
+  /**
+   * {@link permissionsAt} for several nodes at once, as node → permissions:
+   * the rows of a list each with their own controls, answered from one read
+   * of the grant roots and one walk per node.
+   */
+  async permissionsAtMany(identityId, nodeIds) {
+    const now = this.now();
+    const roots = await this.grantRootsFor(identityId);
+    const answers = /* @__PURE__ */ new Map();
+    for (const nodeId of new Set(nodeIds)) {
+      const path = await this.lineageOf(nodeId);
+      const held = [];
+      for (const [permission, windows] of roots) {
+        if (windows.some(
+          (window) => path.has(window.node) && inEffect(window, now)
+        )) {
+          held.push(permission);
+        }
+      }
+      answers.set(nodeId, held.sort());
+    }
+    return answers;
+  }
   async decide(query) {
-    const roots = await this.grantRootsFor(query.identity_id);
-    const granted = roots.get(query.permission);
-    if (!granted || granted.size === 0) {
-      return { allowed: false };
+    const now = this.now();
+    const held = (await this.grantRootsFor(query.identity_id)).get(
+      query.permission
+    );
+    if (!held || held.length === 0) {
+      return { allowed: false, reason: "permission_not_held" };
     }
     if ((query.scope ?? "node") === "app_wide") {
-      return { allowed: true };
+      return held.some((window) => inEffect(window, now)) ? { allowed: true, reason: null } : { allowed: false, reason: reasonAmong(held, now) };
     }
     if (!query.node_id) {
-      return { allowed: false };
+      return { allowed: false, reason: "node_missing" };
+    }
+    if (held.some(
+      (window) => window.node === query.node_id && inEffect(window, now)
+    )) {
+      return { allowed: true, reason: null };
+    }
+    const path = await this.lineageOf(query.node_id);
+    const reachable = held.filter((window) => path.has(window.node));
+    if (reachable.some((window) => inEffect(window, now))) {
+      return { allowed: true, reason: null };
     }
-    return { allowed: await this.holdsAtNode(granted, query.node_id) };
+    if (reachable.length === 0) {
+      return { allowed: false, reason: "outside_grants" };
+    }
+    return { allowed: false, reason: reasonAmong(reachable, now) };
   }
   /** Counters for observability — how much traffic the cache is actually saving. */
   snapshot() {
@@ -1285,28 +1462,42 @@ var LocalAuthorizer = class {
     this.grants.clear();
     this.tree = void 0;
   }
-  /** Climb from `nodeId` and look for a grant root among its ancestors. */
-  async holdsAtNode(granted, nodeId) {
-    if (granted.has(nodeId)) {
-      return true;
+  /** Fire the decision hooks, after the verdict and without waiting on them. */
+  announce(event) {
+    for (const hook of [
+      this.onDecision,
+      event.decision.allowed ? void 0 : this.onDenied
+    ]) {
+      if (!hook) {
+        continue;
+      }
+      try {
+        hook(event);
+      } catch {
+      }
     }
-    const parents = await this.parents();
+  }
+  /** The node and its ancestors, from the tree this client can read. */
+  async lineageOf(nodeId) {
+    const { parents } = await this.treeEntry();
     if (!parents.has(nodeId)) {
-      throw new CanopyAuthorizerError(
-        "authorizer.hierarchy_incomplete",
-        `The hierarchy this client can read does not contain node "${nodeId}", so authorization at that node cannot be decided. A scoped API key needs the \`hierarchy.view\` scope to read the tree.`
-      );
+      throw this.hierarchyIncomplete(nodeId);
     }
+    const path = /* @__PURE__ */ new Set([nodeId]);
     let current = parents.get(nodeId);
     let depth = 0;
     while (current && depth < MAX_WALK_DEPTH) {
-      if (granted.has(current)) {
-        return true;
-      }
+      path.add(current);
       current = parents.get(current);
       depth += 1;
     }
-    return false;
+    return path;
+  }
+  hierarchyIncomplete(nodeId) {
+    return new CanopyAuthorizerError(
+      "authorizer.hierarchy_incomplete",
+      `The hierarchy this client can read does not contain node "${nodeId}", so authorization at that node cannot be decided. A scoped API key needs the \`hierarchy.view\` scope to read the tree.`
+    );
   }
   async grantRootsFor(identityId) {
     const cached = this.grants.get(identityId);
@@ -1324,12 +1515,19 @@ var LocalAuthorizer = class {
     return read;
   }
   /**
-   * Every page of the identity's grant roots, folded into permission → nodes.
+   * Every page of the identity's grant roots, with their windows, folded
+   * into permission → roots.
+   *
+   * Each row is one permission at one node for one assignment, 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.
    *
-   * 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.
+   * Rows outside their window are kept: they are what lets a denial say
+   * `expired` or `not_yet_effective`, and the entry expires at the nearest
+   * window boundary when that comes before the TTL, so a grant takes effect
+   * or ends on time rather than up to `ttlMs` late.
    */
   async fetchGrantRoots(identityId) {
     this.stats.grantFetches += 1;
@@ -1339,30 +1537,42 @@ var LocalAuthorizer = class {
         this.stats.grantPages += 1;
         return this.client.request("GET", path, {
           ...this.readOptions,
-          query
+          query: { ...query, include: "windows" }
         }).then((page) => understood(page, path));
       },
       { page: 1, take: PAGE_SIZE },
       { maxPages: MAX_PAGES }
     );
     const roots = /* @__PURE__ */ new Map();
+    const now = this.now();
+    let boundary = Number.POSITIVE_INFINITY;
     for await (const row of rows) {
-      const nodes = roots.get(row.permission);
-      if (nodes) {
-        nodes.add(row.node_id);
+      const window = {
+        node: row.node_id,
+        from: row.effective_from ? Date.parse(row.effective_from) : null,
+        to: row.effective_to ? Date.parse(row.effective_to) : null
+      };
+      for (const edge of [window.from, window.to]) {
+        if (edge !== null && edge > now && edge < boundary) {
+          boundary = edge;
+        }
+      }
+      const windows = roots.get(row.permission);
+      if (windows) {
+        windows.push(window);
       } else {
-        roots.set(row.permission, /* @__PURE__ */ new Set([row.node_id]));
+        roots.set(row.permission, [window]);
       }
     }
     this.grants.set(identityId, {
       roots,
-      expiresAt: this.now() + this.ttlMs
+      expiresAt: Math.min(now + this.ttlMs, boundary)
     });
     return roots;
   }
-  async parents() {
+  async treeEntry() {
     if (this.tree && this.tree.expiresAt > this.now()) {
-      return this.tree.parents;
+      return this.tree;
     }
     if (this.pendingTree) {
       return this.pendingTree;
@@ -1399,7 +1609,7 @@ var LocalAuthorizer = class {
       if (held) {
         this.stats.treeNotModified += 1;
         this.tree = { ...held, expiresAt: this.now() + this.ttlMs };
-        return held.parents;
+        return this.tree;
       }
       return this.keepTree([], null);
     }
@@ -1460,19 +1670,26 @@ var LocalAuthorizer = class {
       ids.set(edge.id, edge.id);
     }
     const parents = /* @__PURE__ */ new Map();
+    const children = /* @__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
-      );
+      const parent = edge.parent_node_id === null || edge.parent_node_id === void 0 ? null : ids.get(edge.parent_node_id) ?? edge.parent_node_id;
+      parents.set(edge.id, parent);
+      if (parent !== null) {
+        const siblings = children.get(parent);
+        if (siblings) {
+          siblings.push(edge.id);
+        } else {
+          children.set(parent, [edge.id]);
+        }
+      }
     }
     this.tree = {
       parents,
+      children,
       etag,
       expiresAt: this.now() + this.ttlMs
     };
-    return parents;
+    return this.tree;
   }
 };
 function spansPages(first) {
@@ -1915,6 +2132,7 @@ exports.CanopyClient = CanopyClient;
 exports.CanopyConnectionError = CanopyConnectionError;
 exports.CanopyError = CanopyError;
 exports.CanopyTokenError = CanopyTokenError;
+exports.DEFAULT_MAX_NODES = DEFAULT_MAX_NODES;
 exports.Identities = Identities;
 exports.LocalAuthorizer = LocalAuthorizer;
 exports.MAX_TTL_MS = MAX_TTL_MS;