@canopy-io/node 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -327,6 +327,26 @@ interface paths {
         patch: operations["ApiPermissionsController_updatePermission"];
         trace?: never;
     };
+    "/api/v1/permissions/{id}/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get where a permission is used
+         * @description Returns the roles that grant a permission, each with the number of distinct identities holding that role, plus `role_count` and the distinct `identity_count` the permission reaches overall. Because a permission is only ever held through a role, this is the full blast radius of deleting it — the listed roles are exactly the ones a delete would strip it from. Deactivated roles are included; `identity_count` is not the sum of the per-role counts, since one identity may hold several granting roles. Returns `404` when no permission with that id exists in the Environment. Requires the `rbac.view_roles` permission.
+         */
+        get: operations["ApiPermissionsController_getPermissionUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/permissions/evaluate": {
         parameters: {
             query?: never;
@@ -1598,6 +1618,24 @@ interface components {
             /** @description One or more permissions to register */
             permissions: components["schemas"]["PermissionItemDto"][];
         };
+        PermissionUsageRoleDto: {
+            id: string;
+            name: string;
+            description?: string | null;
+            is_system_role: boolean;
+            /** @description Deactivated roles still carry the grant, so they are listed too — deleting the permission strips it from them as well. */
+            is_active: boolean;
+            /** @description Number of distinct identities assigned this role, across all nodes. */
+            member_count: number;
+        };
+        PermissionUsageDto: {
+            permission_id: string;
+            /** @description Number of roles that grant this permission. */
+            role_count: number;
+            /** @description Distinct identities that hold this permission through any granting role. Lower than the sum of `member_count` when an identity holds more than one granting role. */
+            identity_count: number;
+            roles: components["schemas"]["PermissionUsageRoleDto"][];
+        };
         UpdatePermissionDto: {
             /** @description Updated name */
             name?: string;
@@ -1606,18 +1644,6 @@ interface components {
             /** @description Updated category */
             category?: string;
         };
-        EvaluatePermissionDto: {
-            /** @description Identity ID (from the `identities` table — the end user being evaluated, not an admin). */
-            identity_id: string;
-            permission: string;
-            /**
-             * @description Required. `node` asks 'does this identity have the permission *at* `node_id`?' (lineage walk). `app_wide` asks the coarse-grained 'does this identity have the permission *anywhere* in the org?' question — useful for UI gating, **never** for resource-scoped enforcement. `node` requires `node_id`; `app_wide` forbids it.
-             * @enum {string}
-             */
-            scope: "node" | "app_wide";
-            /** @description Required when `scope` is `node`; must be omitted when `scope` is `app_wide`. */
-            node_id?: string;
-        };
         EvaluateResponseDto: {
             allowed: boolean;
             permission: string;
@@ -1631,6 +1657,18 @@ interface components {
             granting_roles: string[];
             denial_reason?: string | null;
         };
+        EvaluatePermissionDto: {
+            /** @description Identity ID (from the `identities` table — the end user being evaluated, not an admin). */
+            identity_id: string;
+            permission: string;
+            /**
+             * @description Required. `node` asks 'does this identity have the permission *at* `node_id`?' (lineage walk). `app_wide` asks the coarse-grained 'does this identity have the permission *anywhere* in the org?' question — useful for UI gating, **never** for resource-scoped enforcement. `node` requires `node_id`; `app_wide` forbids it.
+             * @enum {string}
+             */
+            scope: "node" | "app_wide";
+            /** @description Required when `scope` is `node`; must be omitted when `scope` is `app_wide`. */
+            node_id?: string;
+        };
         EvaluateCheckDto: {
             /** @description Identity ID (from the `identities` table — the end user being evaluated, not an admin). */
             identity_id: string;
@@ -1646,13 +1684,6 @@ interface components {
         BulkEvaluatePermissionDto: {
             checks: components["schemas"]["EvaluateCheckDto"][];
         };
-        ExplainPermissionDto: {
-            /** @description Identity ID (from the `identities` table — the end user being explained, not an admin). */
-            identity_id: string;
-            permission: string;
-            /** @description The hierarchy node to explain the decision at. The lineage from the root to this node is walked and returned in the trace. */
-            node_id: string;
-        };
         PermissionTraceAssignmentDto: {
             assignment_id: string;
             role_id: string;
@@ -1688,6 +1719,13 @@ interface components {
             /** @description Root-first lineage of the target node, each with the identity's assignments observed at that node. */
             lineage: components["schemas"]["PermissionTraceNodeDto"][];
         };
+        ExplainPermissionDto: {
+            /** @description Identity ID (from the `identities` table — the end user being explained, not an admin). */
+            identity_id: string;
+            permission: string;
+            /** @description The hierarchy node to explain the decision at. The lineage from the root to this node is walked and returned in the trace. */
+            node_id: string;
+        };
         PageMetaDto: {
             /** @description Current page number (1-based) */
             page: number;
@@ -1720,6 +1758,10 @@ interface components {
             name: string;
             node_id: string;
             node_name: string;
+            /** @description When this assignment starts; null means it is already active */
+            effective_from: string | null;
+            /** @description When this assignment expires; null means it never does */
+            effective_to: string | null;
         };
         IdentityRowDto: {
             id: string;
@@ -1891,29 +1933,6 @@ interface components {
             expired_count: number;
             revoked_count: number;
         };
-        CreateIdentityInviteDto: {
-            /** @description OAuth client ID — determines which app the invite links to. If omitted, uses Canopy hosted fallback. */
-            client_id?: string;
-            /**
-             * @description Optional. `activate` (default) creates a net-new identity OR — if an identity with this email already exists in the Account but has no active membership in this App — auto-derives an `add_to_app` invite that adds them to this App without touching their existing password. `password_reset` is the explicit admin-driven credential-rotation flow for an existing identity; it cannot carry a role/node assignment. The legacy `onboard` value is accepted and treated as `activate`.
-             * @enum {string}
-             */
-            intent?: "activate" | "password_reset" | "onboard";
-            email: string;
-            /** @description Required for `activate`. Ignored for `add_to_app` (the existing identity's name wins) and for `password_reset`. */
-            first_name?: string;
-            /** @description Required for `activate`. Ignored for `add_to_app` and `password_reset`. */
-            last_name?: string;
-            /** @description Role ID — required if node_id is provided */
-            role_id?: string;
-            /** @description Node ID — required if role_id is provided */
-            node_id?: string;
-            /**
-             * @description Whether Canopy should send the invite email. Set false to suppress delivery and handle it yourself — the API response includes accept_url with the tokenized link. Defaults to true.
-             * @default true
-             */
-            send_email: boolean;
-        };
         ApiIdentityInviteResponseDto: {
             id: string;
             email: string;
@@ -1942,6 +1961,29 @@ interface components {
             /** @description Tokenized URL the invitee would land on. Returned so callers that pass send_email=false can deliver it themselves. */
             accept_url: string;
         };
+        CreateIdentityInviteDto: {
+            /** @description OAuth client ID — determines which app the invite links to. If omitted, uses Canopy hosted fallback. */
+            client_id?: string;
+            /**
+             * @description Optional. `activate` (default) creates a net-new identity OR — if an identity with this email already exists in the Account but has no active membership in this App — auto-derives an `add_to_app` invite that adds them to this App without touching their existing password. `password_reset` is the explicit admin-driven credential-rotation flow for an existing identity; it cannot carry a role/node assignment. The legacy `onboard` value is accepted and treated as `activate`.
+             * @enum {string}
+             */
+            intent?: "activate" | "password_reset" | "onboard";
+            email: string;
+            /** @description Required for `activate`. Ignored for `add_to_app` (the existing identity's name wins) and for `password_reset`. */
+            first_name?: string;
+            /** @description Required for `activate`. Ignored for `add_to_app` and `password_reset`. */
+            last_name?: string;
+            /** @description Role ID — required if node_id is provided */
+            role_id?: string;
+            /** @description Node ID — required if role_id is provided */
+            node_id?: string;
+            /**
+             * @description Whether Canopy should send the invite email. Set false to suppress delivery and handle it yourself — the API response includes accept_url with the tokenized link. Defaults to true.
+             * @default true
+             */
+            send_email: boolean;
+        };
         BulkCreateIdentityInvitesDto: {
             invites: components["schemas"]["CreateIdentityInviteDto"][];
         };
@@ -1950,20 +1992,6 @@ interface components {
             /** @description Tokenized URL for the regenerated invite. Resend rotates the token, which invalidates any accept_url returned from the original create call. Self-delivery callers must replace the stored URL with this one. */
             accept_url: string;
         };
-        CreateNodeDto: {
-            /** @description Parent node ID (null for root) */
-            parent_node_id?: string;
-            /** @description Node type (org-defined, e.g. 'department', 'team') */
-            node_type: string;
-            /** @description Display name for the node */
-            name: string;
-            /** @description Optional free-text description shown under the node name */
-            description?: string;
-            /** @description URL-friendly slug (auto-generated if omitted) */
-            slug?: string;
-            /** @description Arbitrary metadata */
-            metadata?: Record<string, unknown>;
-        };
         NodeResponseDto: {
             id: string;
             application_id: string;
@@ -1982,6 +2010,20 @@ interface components {
             /** @description Optimistic-lock version. Send back as the `If-Match` header when updating, moving, or deleting to detect concurrent edits. */
             version: number;
         };
+        CreateNodeDto: {
+            /** @description Parent node ID (null for root) */
+            parent_node_id?: string;
+            /** @description Node type (org-defined, e.g. 'department', 'team') */
+            node_type: string;
+            /** @description Display name for the node */
+            name: string;
+            /** @description Optional free-text description shown under the node name */
+            description?: string;
+            /** @description URL-friendly slug (auto-generated if omitted) */
+            slug?: string;
+            /** @description Arbitrary metadata */
+            metadata?: Record<string, unknown>;
+        };
         HierarchyTreeNodeDto: {
             id: string;
             name: string;
@@ -2221,6 +2263,44 @@ interface components {
             /** @description Whether this row should appear on a future end-user `My security activity` surface. Not consumed by current reads. */
             identity_visible: boolean;
         };
+        ExportJobDto: {
+            /** Format: uuid */
+            id: string;
+            /**
+             * @description `pending` (enqueued), `processing` (worker rendering), `completed` (file ready), or `failed` (see `error`).
+             * @enum {string}
+             */
+            status: "pending" | "processing" | "completed" | "failed";
+            /**
+             * @description The audit surface the export was taken from.
+             * @enum {string}
+             */
+            surface: "admin" | "identities";
+            /**
+             * @description Wire format of the rendered file.
+             * @enum {string}
+             */
+            format: "csv" | "ndjson";
+            /** Format: uuid */
+            application_id?: string | null;
+            /** Format: uuid */
+            environment_id?: string | null;
+            /** @description Rows written, set once the job completes. */
+            row_count?: number | null;
+            /** @description Failure detail, present only when `status` is `failed`. */
+            error?: string | null;
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            completed_at?: string | null;
+            /**
+             * Format: date-time
+             * @description When the stored file + this record become eligible for sweep.
+             */
+            expires_at?: string | null;
+            /** @description Short-lived signed download URL. Present only on the single-job read of a completed job; `null` otherwise. */
+            download_url?: string | null;
+        };
         AuditExportQueryDto: {
             /**
              * Format: date-time
@@ -2269,44 +2349,6 @@ interface components {
              */
             format: "csv" | "ndjson";
         };
-        ExportJobDto: {
-            /** Format: uuid */
-            id: string;
-            /**
-             * @description `pending` (enqueued), `processing` (worker rendering), `completed` (file ready), or `failed` (see `error`).
-             * @enum {string}
-             */
-            status: "pending" | "processing" | "completed" | "failed";
-            /**
-             * @description The audit surface the export was taken from.
-             * @enum {string}
-             */
-            surface: "admin" | "identities";
-            /**
-             * @description Wire format of the rendered file.
-             * @enum {string}
-             */
-            format: "csv" | "ndjson";
-            /** Format: uuid */
-            application_id?: string | null;
-            /** Format: uuid */
-            environment_id?: string | null;
-            /** @description Rows written, set once the job completes. */
-            row_count?: number | null;
-            /** @description Failure detail, present only when `status` is `failed`. */
-            error?: string | null;
-            /** Format: date-time */
-            created_at: string;
-            /** Format: date-time */
-            completed_at?: string | null;
-            /**
-             * Format: date-time
-             * @description When the stored file + this record become eligible for sweep.
-             */
-            expires_at?: string | null;
-            /** @description Short-lived signed download URL. Present only on the single-job read of a completed job; `null` otherwise. */
-            download_url?: string | null;
-        };
         AuditLogDetailResponseDto: {
             id: string;
             account_id?: string | null;
@@ -2399,11 +2441,6 @@ interface components {
             /** @description Node type used when the root node is auto-created. Must be one of `node_types`. */
             root_node_type: string;
         };
-        CreateWebhookDto: {
-            url: string;
-            event_types: string[];
-            description?: string;
-        };
         WebhookCreatedResponseDto: {
             id: string;
             /** @enum {string} */
@@ -2417,6 +2454,11 @@ interface components {
             /** @description HMAC secret — only shown once on creation */
             secret: string;
         };
+        CreateWebhookDto: {
+            url: string;
+            event_types: string[];
+            description?: string;
+        };
         WebhookResponseDto: {
             id: string;
             /** @enum {string} */
@@ -2452,21 +2494,6 @@ interface components {
             description?: string | null;
             is_active?: boolean;
         };
-        CreateApiKeyDto: {
-            /** @description API key name */
-            name: string;
-            /** @description API key description */
-            description?: string;
-            /**
-             * @description Required. `scoped` enforces the `scopes` array on every authorization check (deny if the requested permission isn't listed). `full_access` bypasses RBAC entirely within the key's Application — every permission is granted. Pick `scoped` whenever possible; `full_access` should be a deliberate choice (use cases: bootstrap automation, trusted backend services that legitimately need App-wide access). `scoped` requires a non-empty `scopes` array; `full_access` forbids `scopes`.
-             * @enum {string}
-             */
-            access_mode: "scoped" | "full_access";
-            /** @description Permission scopes this key is authorized for. Required and must be non-empty when `access_mode` is `scoped`. Must be omitted when `access_mode` is `full_access`. */
-            scopes?: string[];
-            /** @description Expiration date (ISO 8601). Omit for no expiration. */
-            expires_at?: string;
-        };
         ApiKeyCreatedResponseDto: {
             id: string;
             name: string;
@@ -2485,6 +2512,21 @@ interface components {
             /** Format: date-time */
             created_at: string;
         };
+        CreateApiKeyDto: {
+            /** @description API key name */
+            name: string;
+            /** @description API key description */
+            description?: string;
+            /**
+             * @description Required. `scoped` enforces the `scopes` array on every authorization check (deny if the requested permission isn't listed). `full_access` bypasses RBAC entirely within the key's Application — every permission is granted. Pick `scoped` whenever possible; `full_access` should be a deliberate choice (use cases: bootstrap automation, trusted backend services that legitimately need App-wide access). `scoped` requires a non-empty `scopes` array; `full_access` forbids `scopes`.
+             * @enum {string}
+             */
+            access_mode: "scoped" | "full_access";
+            /** @description Permission scopes this key is authorized for. Required and must be non-empty when `access_mode` is `scoped`. Must be omitted when `access_mode` is `full_access`. */
+            scopes?: string[];
+            /** @description Expiration date (ISO 8601). Omit for no expiration. */
+            expires_at?: string;
+        };
         ApiKeyResponseDto: {
             id: string;
             client_id: string;
@@ -2645,7 +2687,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PermissionResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["PermissionResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -2709,7 +2753,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PermissionResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["PermissionResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -2868,7 +2914,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PermissionResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["PermissionResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -2936,6 +2984,93 @@ interface operations {
             };
         };
     };
+    ApiPermissionsController_getPermissionUsage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Granting roles and identity reach returned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["PermissionUsageDto"];
+                    };
+                };
+            };
+            /** @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/permissions",
+                     *         "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/permissions",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+            /** @description No permission with that id exists in this Environment */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 404,
+                     *         "code": null,
+                     *         "message": "No permission with that id exists in this Environment",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/permissions/{id}/usage",
+                     *         "method": "GET"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
+        };
+    };
     ApiPermissionsController_evaluate: {
         parameters: {
             query?: never;
@@ -2955,7 +3090,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["EvaluateResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["EvaluateResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3089,7 +3226,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PermissionTraceDto"];
+                    "application/json": {
+                        data: components["schemas"]["PermissionTraceDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3252,7 +3391,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityResponseDto"];
+                    };
                 };
             };
             /** @description Password rejected — appeared in a known data breach (HaveIBeenPwned check) */
@@ -3436,7 +3577,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentitiesSummaryDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentitiesSummaryDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3624,7 +3767,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3796,7 +3941,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3881,7 +4028,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityDetailResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityDetailResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -3966,7 +4115,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["MessageResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["MessageResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -4051,7 +4202,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["MessageResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["MessageResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -4410,7 +4563,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AccountIdentityMfaResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["AccountIdentityMfaResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -4578,7 +4733,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityAuthStateResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityAuthStateResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -5080,7 +5237,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiIdentityInviteResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiIdentityInviteResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -5142,7 +5301,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["IdentityInvitesSummaryDto"];
+                    "application/json": {
+                        data: components["schemas"]["IdentityInvitesSummaryDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -5330,7 +5491,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiIdentityInviteResendResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiIdentityInviteResendResponseDto"];
+                    };
                 };
             };
             /** @description Invite is no longer pending */
@@ -5541,7 +5704,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ScopedHierarchyTreeResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ScopedHierarchyTreeResponseDto"];
+                    };
                 };
             };
             /** @description The hierarchy is unchanged since the supplied `ETag`. No body; keep using the cached tree. */
@@ -5614,7 +5779,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeResponseDto"];
+                    };
                 };
             };
             /** @description Invalid parent-child relationship */
@@ -5794,7 +5961,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeAccessResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeAccessResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -5995,7 +6164,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeResponseDto"];
+                    };
                 };
             };
             /** @description Invalid parent-child relationship */
@@ -6122,7 +6293,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["HierarchyTreeNodeDto"];
+                    "application/json": {
+                        data: components["schemas"]["HierarchyTreeNodeDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6326,7 +6499,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6539,7 +6714,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["NodeIdentitiesSummaryDto"];
+                    "application/json": {
+                        data: components["schemas"]["NodeIdentitiesSummaryDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6693,7 +6870,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["RoleResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["RoleResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6778,7 +6957,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["RoleResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["RoleResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -6979,7 +7160,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["RoleResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["RoleResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -7176,7 +7359,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["MessageResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["MessageResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -7341,7 +7526,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AssignmentsSummaryDto"];
+                    "application/json": {
+                        data: components["schemas"]["AssignmentsSummaryDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -7407,7 +7594,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AssignmentResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["AssignmentResponseDto"];
+                    };
                 };
             };
             /** @description System roles cannot be assigned to identities — they are reserved for platform administration */
@@ -7600,7 +7789,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AssignmentResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["AssignmentResponseDto"];
+                    };
                 };
             };
             /** @description System roles cannot be assigned to identities — they are reserved for platform administration */
@@ -7772,7 +7963,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["MessageResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["MessageResponseDto"];
+                    };
                 };
             };
             /** @description System roles cannot be assigned to identities — they are reserved for platform administration */
@@ -8160,7 +8353,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ExportJobDto"];
+                    "application/json": {
+                        data: components["schemas"]["ExportJobDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8224,7 +8419,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ExportJobDto"];
+                    "application/json": {
+                        data: components["schemas"]["ExportJobDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8392,7 +8589,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["AuditLogDetailResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["AuditLogDetailResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8569,7 +8768,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["HierarchySchemaResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["HierarchySchemaResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8639,7 +8840,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["HierarchySchemaResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["HierarchySchemaResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -8802,7 +9005,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["WebhookCreatedResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["WebhookCreatedResponseDto"];
+                    };
                 };
             };
             /** @description One or more event types are not supported */
@@ -9050,7 +9255,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["WebhookResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["WebhookResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -9222,7 +9429,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["WebhookResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["WebhookResponseDto"];
+                    };
                 };
             };
             /** @description One or more event types are not supported */
@@ -9406,7 +9615,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiKeyCreatedResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiKeyCreatedResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -9557,7 +9768,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiKeyResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiKeyResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -9642,7 +9855,9 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ApiKeyCreatedResponseDto"];
+                    "application/json": {
+                        data: components["schemas"]["ApiKeyCreatedResponseDto"];
+                    };
                 };
             };
             /** @description Invalid or expired token */
@@ -10075,10 +10290,26 @@ declare class LocalAuthorizer {
     /** Counters for observability — how much traffic the cache is actually saving. */
     snapshot(): LocalAuthorizerStats;
     /**
-     * Drop everything held. Not needed in normal operation, where entries expire
-     * on their own; useful in tests and after a known change.
+     * Drop what is held so the next evaluate refetches.
+     *
+     * With an `identityId`, only that identity's grants are dropped — the
+     * cached hierarchy and every other identity's entries stay warm. This is
+     * the shape an assignment webhook wants: the event names the identity
+     * whose authority moved, and nothing else needs to pay a refetch for it.
+     *
+     * With no argument, everything goes: grants and the hierarchy tree. Not
+     * needed in normal operation, where entries expire on their own; useful in
+     * tests and after a change whose reach you cannot name (a role's
+     * permissions edited, a node moved).
+     *
+     * Multi-instance honesty: an invalidation reaches THIS process only. A
+     * webhook lands on one instance behind a load balancer; the others serve
+     * their cached grants until their own TTL expires. Unless the app fans the
+     * event out over its own pub/sub, the fleet-wide revocation guarantee is
+     * the TTL, and webhook-driven invalidation is a latency optimization on
+     * top of it — size the TTL to the revocation latency you can promise.
      */
-    invalidate(): void;
+    invalidate(identityId?: string): void;
     /** Climb from `nodeId` and look for a grant root among its ancestors. */
     private holdsAtNode;
     private grantRootsFor;