@canopy-io/node 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -748,7 +748,7 @@ interface paths {
         };
         /**
          * Get identity's effective permissions
-         * @description Returns the identity's effective Application-wide permission keys for the current Environment as a flat `items` array of strings, resolved across all of its role assignments. Use this to answer "what can this identity do" without replaying individual assignments. Returns `404` when the identity has no membership in this Environment.
+         * @description Returns the identity's effective permission keys for the current Environment as a flat `items` array of strings. Without `node_id`, the Application-wide answer: every permission its role assignments grant anywhere. With `node_id`, the answer at that node: the permissions granted by assignments on the node's lineage, the list a screen renders its controls from. Returns `404` when the identity has no membership in this Environment, or when `node_id` names no node in it.
          */
         get: operations["ApiIdentitiesController_getIdentityPermissions"];
         put?: never;
@@ -759,6 +759,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/identities/{id}/accessible-nodes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get where an identity may act with one permission
+         * @description Returns where the identity may act with `permission`, for a list query: `roots`, the nodes it holds the permission at that no other such node already covers, and `nodes`, every node beneath those roots, the roots included, when there are at most `max_nodes` of them (default 10,000; at most 50,000). Past the cap `nodes` is null and `complete` false, and the caller filters by `roots` against its own closure table or materialised path. `env_wide` is true when a root is the Environment's own root, so every node qualifies and no filter is needed; `nodes` is null then too. The same rules as `evaluate` decide the roots, so a list filtered by this answer agrees with the check a write makes. Returns `404` when the identity has no membership in this Environment.
+         */
+        get: operations["ApiIdentitiesController_getIdentityAccessibleNodes"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/identities/{id}/grants": {
         parameters: {
             query?: never;
@@ -768,7 +788,7 @@ interface paths {
         };
         /**
          * Get where an identity holds each permission
-         * @description Returns, for the current Environment, one page of `(permission, node_id)` rows: every permission the identity holds, paired with each hierarchy node its grants were made at — the nodes themselves, **not** expanded through their descendants. Rows are ordered by permission, then node; a caller building the whole map walks every page. A grant already means "this node and everything beneath it", so a caller answers a node-scoped question by walking up from the node in question and looking for one of these roots, using a copy of the parent edges fetched once from `GET /api/v1/nodes/parents` and shared across identities. Answers both scopes without a further call: the permission appearing at all is the Application-wide answer, and the walk is the node-scoped one. Scheduled assignments outside their effective window are excluded. Returns `404` when the identity has no membership in this Environment.
+         * @description Returns, for the current Environment, one page of `(permission, node_id)` rows: every permission the identity holds, paired with each hierarchy node its grants were made at — the nodes themselves, **not** expanded through their descendants. Rows are ordered by permission, then node; a caller building the whole map walks every page. A grant already means "this node and everything beneath it", so a caller answers a node-scoped question by walking up from the node in question and looking for one of these roots, using a copy of the parent edges fetched once from `GET /api/v1/nodes/parents` and shared across identities. Answers both scopes without a further call: the permission appearing at all is the Application-wide answer, and the walk is the node-scoped one. By default, assignments outside their effective window are excluded. With `include=windows`, every assignment is a row carrying `effective_from` and `effective_to` (null for an unbounded side), in effect or not, so a caller applies the window itself: it can say why a check fails (the grant has ended, or has not begun) and drop a grant at its boundary without reading again. Returns `404` when the identity has no membership in this Environment.
          */
         get: operations["ApiIdentitiesController_getIdentityGrants"];
         put?: never;
@@ -2739,6 +2759,18 @@ interface components {
             /** Format: date-time */
             updated_at: string;
         };
+        IdentityAccessibleNodesResponseDto: {
+            /** @example reports.view */
+            permission: string;
+            /** @description True when a root is the Environment's own root, so every node qualifies and a list needs no filter. `nodes` is null then. */
+            env_wide: boolean;
+            /** @description The nodes the permission is granted at, in effect now, that no other such node already covers. Each reaches everything beneath it. */
+            roots: string[];
+            /** @description Every node beneath the roots, the roots included, for an `IN (...)` filter. Null when `env_wide`, or when there are more than `max_nodes` (then `complete` is false and the caller filters by `roots` instead). */
+            nodes: string[] | null;
+            /** @description False when the set beneath the roots was larger than `max_nodes` and was not sent. */
+            complete: boolean;
+        };
         IdentityGrantResponseDto: {
             /** @example reports.view */
             permission: string;
@@ -2747,6 +2779,16 @@ interface components {
              * @description The hierarchy node the permission was granted at. Not expanded through descendants.
              */
             node_id: string;
+            /**
+             * Format: date-time
+             * @description When the assignment behind this root begins, or null for no start. Present only with `include=windows`.
+             */
+            effective_from?: string | null;
+            /**
+             * Format: date-time
+             * @description When the assignment behind this root ends, or null for no end. Present only with `include=windows`.
+             */
+            effective_to?: string | null;
         };
         IdentityInviteResponseDto: {
             id: string;
@@ -8358,7 +8400,10 @@ interface operations {
     };
     ApiIdentitiesController_getIdentityPermissions: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Answer at this node: the permissions granted by assignments on its lineage. Omit for the Application-wide answer. */
+                node_id?: string;
+            };
             header?: never;
             path: {
                 id: string;
@@ -8464,6 +8509,119 @@ interface operations {
             };
         };
     };
+    ApiIdentitiesController_getIdentityAccessibleNodes: {
+        parameters: {
+            query: {
+                /** @description The permission to answer for, by key. */
+                permission: string;
+                /** @description The largest `nodes` set to return. Past it, `nodes` is null and `complete` false. */
+                max_nodes?: number;
+            };
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The minimal grant roots for the permission, and the nodes beneath them up to the cap */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["IdentityAccessibleNodesResponseDto"];
+                    };
+                };
+            };
+            /** @description The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 400,
+                     *         "code": null,
+                     *         "message": "The request failed validation: a body field, a query parameter or an id in the path is missing, malformed or out of range; or the request sent both an `X-API-Key` and an `Authorization` header",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/identities/{id}/accessible-nodes",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description Invalid or expired token */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 401,
+                     *         "code": null,
+                     *         "message": "Invalid or expired token",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/identities",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 403,
+                     *         "code": null,
+                     *         "message": "This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/identities",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description No identity with that id has a membership in this Environment */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 404,
+                     *         "code": null,
+                     *         "message": "No identity with that id has a membership in this Environment",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/identities/{id}/accessible-nodes",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+        };
+    };
     ApiIdentitiesController_getIdentityGrants: {
         parameters: {
             query?: {
@@ -8471,6 +8629,8 @@ interface operations {
                 page?: number;
                 /** @description Items per page (1-100, default 20) */
                 take?: number;
+                /** @description `windows` adds `effective_from` and `effective_to` to every row and includes assignments outside their window, so the caller applies the window itself. */
+                include?: "windows";
             };
             header?: never;
             path: {
@@ -21539,7 +21699,18 @@ declare class Identities {
      * question at the node that matters. This is for showing a person what
      * someone can do.
      */
-    permissions(id: string): Promise<ResponseBody<"ApiIdentitiesController_getIdentityPermissions">>;
+    permissions(id: string, query?: QueryParams<"ApiIdentitiesController_getIdentityPermissions">): Promise<ResponseBody<"ApiIdentitiesController_getIdentityPermissions">>;
+    /**
+     * 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: string, query: QueryParams<"ApiIdentitiesController_getIdentityAccessibleNodes">): Promise<ResponseBody<"ApiIdentitiesController_getIdentityAccessibleNodes">>;
     /**
      * Every session the identity holds that is neither revoked nor expired,
      * newest first: when and where it was signed in, when it expires, and the
@@ -21839,6 +22010,39 @@ declare class Canopy {
  * delay is short, so a longer value is refused rather than honoured.
  */
 declare const MAX_TTL_MS = 300000;
+/**
+ * The largest node set `accessibleNodes` builds unless told otherwise. Past
+ * it the answer carries the roots alone, and the caller filters against its
+ * own closure table or materialised path instead of an `IN (...)` list.
+ */
+declare const DEFAULT_MAX_NODES = 10000;
+/**
+ * Why a check was denied, as far as the grant roots and the tree can say.
+ *
+ * - `permission_not_held`: no assignment grants the permission anywhere, in
+ *   effect or not.
+ * - `outside_grants`: it is granted, but at no node on the lineage of the
+ *   node asked about.
+ * - `expired`: a grant that would answer has ended, and none is in effect.
+ * - `not_yet_effective`: a grant that would answer has not begun, and none
+ *   is in effect.
+ * - `node_missing`: a `node` check named no node, which is a denial rather
+ *   than an error, because a request whose subject cannot be established
+ *   must not pass.
+ */
+type LocalDenialReason = "permission_not_held" | "outside_grants" | "expired" | "not_yet_effective" | "node_missing";
+/** The answer to a check: the verdict, and why when it is no. */
+interface LocalDecision {
+    allowed: boolean;
+    reason: LocalDenialReason | null;
+}
+/** What a decision hook receives, after the verdict is in. */
+interface LocalDecisionEvent {
+    query: LocalAuthorizationQuery;
+    decision: LocalDecision;
+    /** How long the check took, reads included. */
+    durationMs: number;
+}
 interface LocalAuthorizerOptions {
     /**
      * How long grant roots and the hierarchy are reused, in milliseconds.
@@ -21871,6 +22075,19 @@ interface LocalAuthorizerOptions {
     timeoutMs?: number;
     /** Retries for those reads. */
     maxRetries?: number;
+    /**
+     * The largest node set {@link LocalAuthorizer.accessibleNodes} builds
+     * unless a call says otherwise. Defaults to {@link DEFAULT_MAX_NODES}.
+     */
+    maxNodes?: number;
+    /**
+     * Called after every decision, allowed or not, with the question and the
+     * answer. Never awaited and never allowed to fail the check: a hook that
+     * throws is ignored. For audit trails and metrics.
+     */
+    onDecision?: (event: LocalDecisionEvent) => void;
+    /** Called after every denial, the same way. For alerting on refusals. */
+    onDenied?: (event: LocalDecisionEvent) => void;
     /** Injectable clock, for tests. */
     now?: () => number;
 }
@@ -21881,6 +22098,26 @@ interface LocalAuthorizationQuery {
     scope?: "node" | "app_wide";
     node_id?: string;
 }
+/** Where an identity may act with one permission, shaped for a list query. */
+interface AccessibleNodes {
+    /**
+     * The nodes the permission is granted at, in effect now, that no other
+     * such node already covers. Each reaches everything beneath it.
+     */
+    roots: string[];
+    /**
+     * Every node beneath the roots, the roots included, for an `IN (...)`
+     * filter. Null when `envWide`, or when the set would exceed the cap.
+     */
+    nodes: Set<string> | null;
+    /** False when the set exceeded the cap and `nodes` was not built. */
+    complete: boolean;
+    /**
+     * True when a root is the Environment's own root: every node qualifies, so
+     * a list needs no filter at all.
+     */
+    envWide: boolean;
+}
 interface LocalAuthorizerStats {
     /** Reads of an identity's grant roots, one per refresh however many pages it took. */
     grantFetches: number;
@@ -21900,8 +22137,11 @@ interface LocalAuthorizerStats {
 declare class LocalAuthorizer {
     private readonly client;
     private readonly ttlMs;
+    private readonly maxNodes;
     private readonly now;
     private readonly readOptions;
+    private readonly onDecision;
+    private readonly onDenied;
     private readonly grants;
     private tree;
     /**
@@ -21917,7 +22157,7 @@ declare class LocalAuthorizer {
     private stats;
     constructor(client: CanopyClient, options?: LocalAuthorizerOptions);
     /**
-     * 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
@@ -21925,9 +22165,51 @@ declare class LocalAuthorizer {
      */
     evaluate(query: LocalAuthorizationQuery, options?: {
         signal?: AbortSignal;
-    }): Promise<{
-        allowed: boolean;
+    }): Promise<LocalDecision>;
+    /**
+     * 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.
+     */
+    grantRoots(identityId: string, permission: string): Promise<{
+        roots: string[];
+        envWide: boolean;
     }>;
+    /**
+     * 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`.
+     */
+    accessibleNodes(identityId: string, permission: string, options?: {
+        maxNodes?: number;
+    }): Promise<AccessibleNodes>;
+    /**
+     * 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.
+     */
+    permissionsAt(identityId: string, nodeId: string): Promise<string[]>;
+    /**
+     * {@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.
+     */
+    permissionsAtMany(identityId: string, nodeIds: readonly string[]): Promise<Map<string, string[]>>;
     private decide;
     /** Counters for observability — how much traffic the cache is actually saving. */
     snapshot(): LocalAuthorizerStats;
@@ -21954,19 +22236,29 @@ declare class LocalAuthorizer {
      * top of it — size the TTL to the revocation latency you can promise.
      */
     invalidate(identityId?: string): void;
-    /** Climb from `nodeId` and look for a grant root among its ancestors. */
-    private holdsAtNode;
+    /** Fire the decision hooks, after the verdict and without waiting on them. */
+    private announce;
+    /** The node and its ancestors, from the tree this client can read. */
+    private lineageOf;
+    private hierarchyIncomplete;
     private grantRootsFor;
     /**
-     * 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.
      */
     private fetchGrantRoots;
-    private parents;
+    private treeEntry;
     /**
      * 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
@@ -22432,4 +22724,4 @@ type WebhookEventData<Name extends WebhookEventName> = WebhookEvent<Name>["data"
  */
 declare function isWebhookEvent<Name extends WebhookEventName>(delivery: WebhookDelivery, name: Name): delivery is WebhookEvent<Name>;
 
-export { type AssignmentItem, Assignments, type CallOptions, Canopy, CanopyAuthorizerError, CanopyClient, type CanopyClientOptions, CanopyConnectionError, CanopyError, type CanopyErrorBody, type CanopyOrgContext, type CanopyTokenClaims, CanopyTokenError, type Collection, type ConcurrencyOptions, type ConditionalResult, type CursorPagination, type FailureStatus, Identities, type IdentityAssignmentItem, type IdentityItem, type IdentitySessionItem, type LocalAuthorizationQuery, LocalAuthorizer, type LocalAuthorizerOptions, type LocalAuthorizerStats, MAX_TTL_MS, type OffsetPagination, type OperationId, type OrganizationDirectoryGroupItem, type OrganizationInviteItem, type OrganizationItem, type OrganizationMemberItem, Organizations, type PageFetcher, type PageParams, type PaginateOptions, type Pagination, Paginator, type PartialSuccess, type PermissionItem, Permissions, type QueryParams, type RequestBody, type RequestOptions, type ResponseBody, type RoleItem, Roles, type Schema, TokenVerifier, type TokenVerifierOptions, type WebhookDelivery, type WebhookEvent, type WebhookEventData, type WebhookEventName, authorizationErrorStatus, type components, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, type operations, orgContext, paginate, type paths, tokenErrorStatus, withConcurrency };
+export { type AccessibleNodes, type AssignmentItem, Assignments, type CallOptions, Canopy, CanopyAuthorizerError, CanopyClient, type CanopyClientOptions, CanopyConnectionError, CanopyError, type CanopyErrorBody, type CanopyOrgContext, type CanopyTokenClaims, CanopyTokenError, type Collection, type ConcurrencyOptions, type ConditionalResult, type CursorPagination, DEFAULT_MAX_NODES, type FailureStatus, Identities, type IdentityAssignmentItem, type IdentityItem, type IdentitySessionItem, type LocalAuthorizationQuery, LocalAuthorizer, type LocalAuthorizerOptions, type LocalAuthorizerStats, type LocalDecision, type LocalDecisionEvent, type LocalDenialReason, MAX_TTL_MS, type OffsetPagination, type OperationId, type OrganizationDirectoryGroupItem, type OrganizationInviteItem, type OrganizationItem, type OrganizationMemberItem, Organizations, type PageFetcher, type PageParams, type PaginateOptions, type Pagination, Paginator, type PartialSuccess, type PermissionItem, Permissions, type QueryParams, type RequestBody, type RequestOptions, type ResponseBody, type RoleItem, Roles, type Schema, TokenVerifier, type TokenVerifierOptions, type WebhookDelivery, type WebhookEvent, type WebhookEventData, type WebhookEventName, authorizationErrorStatus, type components, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, type operations, orgContext, paginate, type paths, tokenErrorStatus, withConcurrency };