@canopy-io/node 0.9.0 → 0.11.0

package/dist/index.js

@@ -602,10 +602,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`,
+      { 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)}/permissions`
+      `/api/v1/identities/${encodeURIComponent(id)}/accessible-nodes`,
+      { query: { ...query } }
     );
   }
   /**
@@ -1149,17 +1167,37 @@ 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;
 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";
+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;
   /**
@@ -1187,22 +1225,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;
@@ -1219,25 +1274,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" };
     }
-    return { allowed: await this.holdsAtNode(granted, query.node_id) };
+    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 };
+    }
+    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() {
@@ -1273,28 +1460,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);
@@ -1312,12 +1513,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, 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 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.
+   *
+   * 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;
@@ -1327,30 +1535,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;
@@ -1387,7 +1607,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);
     }
@@ -1408,12 +1628,15 @@ var LocalAuthorizer = class {
   }
   parentsFirstPage(etag) {
     this.stats.treePages += 1;
-    return this.client.requestConditional(
-      "GET",
-      PARENTS_PATH,
-      etag,
-      { ...this.readOptions, query: { page: 1, take: PAGE_SIZE } }
-    );
+    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) {
@@ -1427,7 +1650,7 @@ var LocalAuthorizer = class {
         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 }
@@ -1445,19 +1668,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) {
@@ -1893,6 +2123,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, authorizationErrorStatus, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, orgContext, paginate, tokenErrorStatus, withConcurrency };
+export { Assignments, Canopy, CanopyAuthorizerError, CanopyClient, CanopyConnectionError, CanopyError, CanopyTokenError, DEFAULT_MAX_NODES, 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