@canopy-io/node 0.7.1 → 0.8.0

package/dist/index.d.cts

@@ -550,7 +550,7 @@ interface paths {
         put?: never;
         /**
          * Set an identity's password (admin)
-         * @description Sets an identity's password directly (server-to-server admin), primarily for migrating users off a legacy store without the user present. Reuses the argon2id + HaveIBeenPwned path, so a breached password returns `400`; the prior hash is recorded to password history, any active failed-login lockout is cleared, and the identity's active sessions are revoked so a rotated credential can't keep a stale session alive. Returns `204 No Content`; returns `404` when the identity has no membership in this Environment.
+         * @description Sets an identity's password directly (server-to-server admin), primarily for migrating users off a legacy store without the user present. Reuses the argon2id + HaveIBeenPwned path, so a breached password returns `400`; any active failed-login lockout is cleared, and the identity's active sessions are revoked so a rotated credential can't keep a stale session alive. Returns `204 No Content`; returns `404` when the identity has no membership in this Environment.
          */
         post: operations["ApiIdentitiesController_setIdentityPassword"];
         delete?: never;
@@ -588,7 +588,7 @@ interface paths {
         };
         /**
          * List an identity's active sessions (admin)
-         * @description Lists an identity's active sessions (server-to-server admin): the rows a customer reads to confirm from its own side that a sign-out took, or to show a person where they are signed in. Each row is a session's current refresh token, so `id` changes on every refresh. Returns `404` when the identity has no membership in this Environment.
+         * @description Lists an identity's active sessions in the caller's Environment (server-to-server admin): the rows a customer reads to confirm from its own side that a sign-out took, or to show a person where they are signed in. Each row is a session's current refresh token, so `id` changes on every refresh. Sessions the identity holds in its other Environments are not listed. Returns `404` when the identity has no membership in this Environment.
          */
         get: operations["ApiIdentitiesController_listIdentitySessions"];
         put?: never;
@@ -611,7 +611,7 @@ interface paths {
         post?: never;
         /**
          * Revoke one of an identity's sessions (admin)
-         * @description Revokes one of an identity's sessions (server-to-server admin) by marking its refresh token revoked, so the next refresh from that device returns `401` while every other session carries on. Audited as `identity.session.revoked`, the same row the person's own per-session sign-out writes. Returns `204 No Content`; returns `404` when the identity has no membership in this Environment, or when the session is not the identity's or is already revoked.
+         * @description Revokes one of an identity's sessions in the caller's Environment (server-to-server admin) by marking its refresh token revoked, so the next refresh from that device returns `401` while every other session carries on. Audited as `identity.session.revoked`, the same row the person's own per-session sign-out writes. Returns `204 No Content`; returns `404` when the identity has no membership in this Environment, or when the session is not the identity's, belongs to another Environment, or is already revoked.
          */
         delete: operations["ApiIdentitiesController_revokeIdentitySession"];
         options?: never;
@@ -630,7 +630,7 @@ interface paths {
         put?: never;
         /**
          * Revoke all of an identity's sessions (admin)
-         * @description Revokes all of an identity's sessions (server-to-server admin) by marking every active refresh token revoked, so the next refresh on any device returns `401` and the user must sign in again. In-flight access tokens remain valid until their short TTL lapses. Idempotent — revoking when no tokens are active is a no-op. Audits twice: `identity.sessions.admin_revoked` for the identity's own security log, and `session.all_revoked`, the subscribable webhook event, so a revoke made here reaches subscribers exactly as one made from the Console does. Returns `204 No Content`; returns `404` when the identity has no membership in this Environment.
+         * @description Revokes all of an identity's sessions in the caller's Environment (server-to-server admin) by marking every active refresh token it holds there revoked, so the next refresh on any device returns `401` and the user must sign in again. Sessions in the identity's other Environments are left alone; the Console's account route is the one that signs a person out everywhere. In-flight access tokens remain valid until their short TTL lapses. Idempotent — revoking when no tokens are active is a no-op. Audits twice: `identity.sessions.admin_revoked` for the identity's own security log, and `session.all_revoked`, the subscribable webhook event, so a revoke made here reaches subscribers exactly as one made from the Console does. Returns `204 No Content`; returns `404` when the identity has no membership in this Environment.
          */
         post: operations["ApiIdentitiesController_revokeIdentitySessions"];
         delete?: never;
@@ -892,7 +892,7 @@ interface paths {
         };
         /**
          * List hierarchy (scoped tree)
-         * @description Returns the caller's accessible hierarchy as a nested tree for the current Environment, each node annotated with `access_state`, `can_access`, and `can_manage`. `user` principals (dashboard) see the full tree; API-key principals see only the subtree their `access_mode`/scopes grant — `full_access` unlocks everything, while scoped keys see nodes reachable via `hierarchy.view`. The response also includes a `scope` block listing `accessible_node_ids`, `scope_root_node_ids`, and `entry_node_ids`.
+         * @description Returns the caller's accessible hierarchy as a nested tree for the current Environment, each node annotated with `access_state`, `can_access`, and `can_manage`. `user` principals (dashboard), which need the Console capability covering `hierarchy.view`, see the full tree; API-key principals see only the subtree their `access_mode`/scopes grant — `full_access` unlocks everything, while scoped keys see nodes reachable via `hierarchy.view`. The response also includes a `scope` block listing `accessible_node_ids`, `scope_root_node_ids`, and `entry_node_ids`.
          */
         get: operations["ApiNodesController_listNodes"];
         put?: never;
@@ -2362,7 +2362,7 @@ interface paths {
         put?: never;
         /**
          * Create a new API key
-         * @description Issues a new API key in the active Application, scoped to the current Environment. The full `cnpy_`-prefixed secret is returned in the `key` field of the response and is not recoverable afterward, only a masked `key_preview` and metadata persist; the one exception is a retry carrying the same `Idempotency-Key` within 24 hours, which replays this response. `access_mode: "scoped"` requires a non-empty `scopes` array and enforces it on every authorization check; `access_mode: "full_access"` forbids `scopes` and bypasses RBAC entirely within the Application. Pass `expires_at` (ISO 8601) for an expiring key or omit it for none. Supports `Idempotency-Key` for safe retries, emits an `api_key.created` event, and is limited to 20 requests a minute per caller. A scope the platform does not offer is refused with `400`.
+         * @description Issues a new API key in the active Application, scoped to the current Environment. The full `cnpy_`-prefixed secret is returned in the `key` field of the response and is not recoverable afterward, only a masked `key_preview` and metadata persist; the one exception is a retry carrying the same `Idempotency-Key` within 24 hours, which replays this response. `access_mode: "scoped"` requires a non-empty `scopes` array and enforces it on every authorization check; `access_mode: "full_access"` forbids `scopes` and bypasses RBAC entirely within the Application. Pass `expires_at` (ISO 8601) for an expiring key or omit it for none. Supports `Idempotency-Key` for safe retries, emits an `api_key.created` event, and is limited to 20 requests a minute per caller. A scope the platform does not offer is refused with `400`. A scoped API key can create only scoped keys whose scopes it holds itself; asking for more is refused with `403`.
          */
         post: operations["ApiApiKeysController_create"];
         delete?: never;
@@ -3963,7 +3963,7 @@ interface components {
             /** Format: date-time */
             created_at: string;
             /**
-             * @description The issuer this client's tokens name, which a relying party configures: `https://<custom auth domain>` while the Environment has an active one, else the platform's. Its discovery document is at `<issuer>/.well-known/openid-configuration`.
+             * @description The issuer this client's tokens name, which a relying party configures: `https://<custom auth domain>` while the Environment has an active one, else the Environment's own, `<platform origin>/environments/<environment_id>`. Its discovery document is at `<issuer>/.well-known/openid-configuration`.
              * @example https://auth.yourapp.com
              */
             issuer: string;
@@ -4000,7 +4000,7 @@ interface components {
             /** Format: date-time */
             created_at: string;
             /**
-             * @description The issuer this client's tokens name, which a relying party configures: `https://<custom auth domain>` while the Environment has an active one, else the platform's. Its discovery document is at `<issuer>/.well-known/openid-configuration`.
+             * @description The issuer this client's tokens name, which a relying party configures: `https://<custom auth domain>` while the Environment has an active one, else the Environment's own, `<platform origin>/environments/<environment_id>`. Its discovery document is at `<issuer>/.well-known/openid-configuration`.
              * @example https://auth.yourapp.com
              */
             issuer: string;
@@ -4013,6 +4013,7 @@ interface components {
         };
         UpdateOAuthClientDto: {
             name?: string;
+            /** @description Replaces the registered redirect URIs. At least one is required, as at creation: a client with none could never complete a sign-in. */
             redirect_uris?: string[];
             /** @description Where this client may send someone after RP-initiated logout. Matched exactly. An empty array removes every destination, which leaves logout working with nowhere to return to. */
             post_logout_redirect_uris?: string[];
@@ -4053,12 +4054,12 @@ interface components {
             /** @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`.
+             * @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`. A scoped API key can create only scoped keys whose scopes it holds itself.
              * @enum {string}
              */
             access_mode: "scoped" | "full_access";
             /** @description Permission scopes this key is authorized for, each one the platform offers (`GET .../api-keys/scopes`). Required and must be non-empty when `access_mode` is `scoped`. Must be omitted when `access_mode` is `full_access`. */
-            scopes?: ("hierarchy.view" | "hierarchy.manage" | "rbac.view_roles" | "rbac.manage_roles" | "rbac.view_assignments" | "rbac.manage_assignments" | "permissions.evaluate" | "identity.view" | "identity.manage" | "api_key.view" | "api_key.manage" | "webhook.view" | "webhook.manage" | "oauth_client.view" | "oauth_client.manage")[];
+            scopes?: ("hierarchy.view" | "hierarchy.manage" | "rbac.view_roles" | "rbac.manage_roles" | "rbac.view_assignments" | "rbac.manage_assignments" | "permissions.evaluate" | "identity.view" | "identity.manage" | "api_key.view" | "api_key.manage" | "webhook.view" | "webhook.manage" | "oauth_client.view" | "oauth_client.manage" | "branding.view" | "branding.manage")[];
             /** @description Expiration date (ISO 8601). Omit for no expiration. */
             expires_at?: string;
         };
@@ -7682,7 +7683,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorResponseDto"];
                 };
             };
-            /** @description The identity is not found, or the session does not belong to it or is already revoked */
+            /** @description The identity is not found, or the session does not belong to it, belongs to another Environment, or is already revoked */
             404: {
                 headers: {
                     [name: string]: unknown;
@@ -7693,7 +7694,7 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 404,
                      *         "code": null,
-                     *         "message": "The identity is not found, or the session does not belong to it or is already revoked",
+                     *         "message": "The identity is not found, or the session does not belong to it, belongs to another Environment, or is already revoked",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/identities/{id}/sessions/{sessionId}",
                      *         "method": "DELETE"
@@ -13246,6 +13247,27 @@ interface operations {
                     "application/json": components["schemas"]["ErrorResponseDto"];
                 };
             };
+            /** @description The caller is an organization administrator and the member also belongs to another organization in the Environment; the second factor is held once per identity, so only the application's administrators may reset it (`organization.member_mfa_shared`) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": {
+                     *         "statusCode": 409,
+                     *         "code": null,
+                     *         "message": "The caller is an organization administrator and the member also belongs to another organization in the Environment; the second factor is held once per identity, so only the application's administrators may reset it (`organization.member_mfa_shared`)",
+                     *         "timestamp": "2026-04-20T12:00:00.000Z",
+                     *         "path": "/api/v1/organizations/{id}/members/{identityId}/mfa/reset",
+                     *         "method": "POST"
+                     *       }
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorResponseDto"];
+                };
+            };
         };
     };
     ApiOrganizationsController_listInvites: {
@@ -19166,7 +19188,7 @@ interface operations {
                     "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) */
+            /** @description The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment */
             403: {
                 headers: {
                     [name: string]: unknown;
@@ -19177,7 +19199,7 @@ interface operations {
                      *       "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)",
+                     *         "message": "The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/branding",
                      *         "method": "GET"
@@ -19255,7 +19277,7 @@ interface operations {
                     "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) */
+            /** @description The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment */
             403: {
                 headers: {
                     [name: string]: unknown;
@@ -19266,7 +19288,7 @@ interface operations {
                      *       "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)",
+                     *         "message": "The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/branding",
                      *         "method": "GET"
@@ -20882,7 +20904,7 @@ interface operations {
                     "application/json": components["schemas"]["ErrorResponseDto"];
                 };
             };
-            /** @description The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment */
+            /** @description The caller lacks `api_key.manage` (a scoped API key without that scope, or an admin without the Account capability that covers it), or is a scoped API key asking for more than it holds: `full_access`, or a scope outside its own (`api_key.access_exceeds_caller`) */
             403: {
                 headers: {
                     [name: string]: unknown;
@@ -20893,10 +20915,10 @@ interface operations {
                      *       "error": {
                      *         "statusCode": 403,
                      *         "code": null,
-                     *         "message": "The bearer token is not an admin or platform token, or the caller lacks the permission this operation checks: a scoped API key without that scope, an admin without the Account capability that covers it, or, for a node-scoped check, a node outside this Environment",
+                     *         "message": "The caller lacks `api_key.manage` (a scoped API key without that scope, or an admin without the Account capability that covers it), or is a scoped API key asking for more than it holds: `full_access`, or a scope outside its own (`api_key.access_exceeds_caller`)",
                      *         "timestamp": "2026-04-20T12:00:00.000Z",
                      *         "path": "/api/v1/api-keys",
-                     *         "method": "GET"
+                     *         "method": "POST"
                      *       }
                      *     }
                      */
@@ -21942,8 +21964,9 @@ declare class CanopyConnectionError extends Error {
  * whole point of verifying a signature rather than calling an endpoint.
  *
  * Branch on `code`; it follows the same dot-notation contract as the API's own
- * codes. Every one of them means the same thing to an HTTP caller — 401 — so
- * the code is for your logs and your tests, not usually for the response.
+ * codes. Every one but `token.jwks_unavailable` means the same thing to an
+ * HTTP caller, 401; that one means the keys could not be read, so the token may
+ * be good and the answer is 503. {@link tokenErrorStatus} maps them.
  */
 declare class CanopyTokenError extends Error {
     readonly name = "CanopyTokenError";
@@ -21960,6 +21983,8 @@ declare class CanopyTokenError extends Error {
      * - `token.audience_mismatch` — `aud` does not include the configured audience
      * - `token.audience_unverified` — token has an `aud` but none was configured
      * - `token.preauth_not_allowed` — a pre-auth token, which grants no access
+     * - `token.type_not_allowed` — a principal type the verifier does not accept
+     *   (see `allowedTypes`)
      */
     readonly code: string;
     constructor(code: string, message: string, options?: {
@@ -21991,6 +22016,44 @@ declare function isCanopyError(error: unknown): error is CanopyError;
 declare function isCanopyConnectionError(error: unknown): error is CanopyConnectionError;
 declare function isCanopyTokenError(error: unknown): error is CanopyTokenError;
 
+/**
+ * The HTTP answer a failure should become, for code that verifies tokens or
+ * authorizes requests outside the NestJS guards (Express, Fastify, a worker).
+ * The guards use the same mapping, so every integration answers alike.
+ */
+interface FailureStatus {
+    status: number;
+    /** A message safe to send to the caller; the detail stays on the error. */
+    message: string;
+}
+/**
+ * The answer for a failed {@link TokenVerifier.verify}: `401` when the token is
+ * at fault, `503` when the signing keys could not be read and the token may be
+ * perfectly good.
+ *
+ * The difference matters. A client reads `401` as "your token is stale",
+ * discards a valid one and asks for another, which aims a refresh storm at an
+ * issuer that is already down, and an outage that only emits 4xx is invisible
+ * to anything watching for 5xx.
+ *
+ * Anything that is not a token error is returned as `500`: it is a bug, not a
+ * verdict on the token.
+ */
+declare function tokenErrorStatus(error: unknown): FailureStatus;
+/**
+ * The answer for a failed authorization check ({@link LocalAuthorizer.evaluate}
+ * or a {@link Canopy} call that decides access). Every branch denies; they say
+ * different things so an incident is diagnosable:
+ *
+ * - `500` when the authorizer cannot see far enough to decide (a credential
+ *   that cannot read the hierarchy), when Canopy rejected our own credential,
+ *   when the endpoint is not served (an SDK newer than the API), or on a 4xx
+ *   nobody anticipated. No retry fixes these.
+ * - `503` when Canopy did not answer, or answered 429 or 5xx.
+ * - `403` when Canopy answered that the identity is not in this Environment.
+ */
+declare function authorizationErrorStatus(error: unknown): FailureStatus;
+
 interface TokenVerifierOptions {
     /**
      * The Environment whose tokens are accepted. Every Environment is its own
@@ -22048,6 +22111,16 @@ interface TokenVerifierOptions {
      * request path, so an unbounded read there is an unbounded request.
      */
     jwksTimeoutMs?: number;
+    /**
+     * The principal types accepted, matched against the `type` claim. Defaults to
+     * `["identity"]`: the people who sign in to your application.
+     *
+     * Canopy also signs tokens for its own administrators (`user`), its staff
+     * (`platform`) and, for some flows, API keys (`api_key`), all with the same
+     * keys and issuer. A backend that serves your end users should accept none
+     * of them, so they are refused unless you name them here.
+     */
+    allowedTypes?: ReadonlyArray<CanopyTokenClaims["type"]>;
     /** Injectable for tests and for runtimes with a non-global fetch. */
     fetch?: typeof globalThis.fetch;
 }
@@ -22138,11 +22211,14 @@ declare class TokenVerifier {
     private readonly jwksTimeoutMs;
     private readonly clockToleranceSec;
     private readonly allowPreAuthTokens;
+    private readonly allowedTypes;
     private readonly fetchImpl;
     /** Imported keys by `kid`, so a repeat verification skips the import cost. */
     private keys;
     private keysFetchedAt;
     private lastFetchAttemptAt;
+    /** Whether the latest read of the key set failed, for an unknown `kid`. */
+    private lastFetchFailed;
     /** In-flight fetch, so a burst of requests triggers one call, not N. */
     private inFlight;
     constructor(options?: TokenVerifierOptions);
@@ -22186,6 +22262,7 @@ declare class TokenVerifier {
     private shouldRefresh;
     private refreshKeys;
     private fetchKeys;
+    private readKeys;
 }
 
 /**
@@ -22232,4 +22309,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, Identities, type IdentityAssignmentItem, type IdentityItem, type IdentitySessionItem, type LocalAuthorizationQuery, LocalAuthorizer, type LocalAuthorizerOptions, type LocalAuthorizerStats, MAX_TTL_MS, type OffsetPagination, type OperationId, 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, type components, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, type operations, orgContext, paginate, type paths, withConcurrency };
+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 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 };