@canopy-io/node 0.7.2 → 0.8.0

package/dist/index.d.cts

@@ -21964,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";
@@ -21982,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?: {
@@ -22013,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
@@ -22070,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;
 }
@@ -22160,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);
@@ -22208,6 +22262,7 @@ declare class TokenVerifier {
     private shouldRefresh;
     private refreshKeys;
     private fetchKeys;
+    private readKeys;
 }
 
 /**
@@ -22254,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 };

package/dist/index.d.ts

@@ -21964,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";
@@ -21982,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?: {
@@ -22013,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
@@ -22070,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;
 }
@@ -22160,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);
@@ -22208,6 +22262,7 @@ declare class TokenVerifier {
     private shouldRefresh;
     private refreshKeys;
     private fetchKeys;
+    private readKeys;
 }
 
 /**
@@ -22254,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 };

package/dist/index.js

@@ -54,6 +54,8 @@ var CanopyTokenError = class 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`)
    */
   code;
   constructor(code, message, options) {
@@ -1344,6 +1346,56 @@ var LocalAuthorizer = class {
   }
 };
 
+// src/status.ts
+function tokenErrorStatus(error) {
+  if (!isCanopyTokenError(error)) {
+    return { status: 500, message: "Authentication could not be checked." };
+  }
+  if (error.code === "token.jwks_unavailable") {
+    return {
+      status: 503,
+      message: "Authentication is temporarily unavailable."
+    };
+  }
+  return { status: 401, message: "Invalid or expired access token." };
+}
+function authorizationErrorStatus(error) {
+  if (isCanopyAuthorizerError(error)) {
+    return {
+      status: 500,
+      message: `Authorization is misconfigured: ${error.message}`
+    };
+  }
+  if (!isCanopyError(error)) {
+    return {
+      status: 503,
+      message: "Authorization is temporarily unavailable."
+    };
+  }
+  if (error.isAuthFailure) {
+    return {
+      status: 500,
+      message: "Authorization is misconfigured. Check the Canopy API key and its scopes."
+    };
+  }
+  if (error.statusCode === 404 && error.code === null) {
+    return {
+      status: 500,
+      message: `Authorization is misconfigured: ${error.request.method} ${error.request.path} is not served by this Canopy. The SDK requires an API that exposes the identity grants endpoint.`
+    };
+  }
+  if (error.statusCode === 404) {
+    return { status: 403, message: "Could not evaluate the permission." };
+  }
+  if (error.isRateLimited || error.statusCode >= 500) {
+    return {
+      status: 503,
+      message: "Authorization is temporarily unavailable."
+    };
+  }
+  return { status: 500, message: "Authorization could not be evaluated." };
+}
+
 // src/verify.ts
 var HOSTED_ORIGIN = "https://auth.canopy-io.com";
 var DEFAULT_JWKS_CACHE_MAX_AGE_MS = 10 * 60 * 1e3;
@@ -1404,11 +1456,14 @@ var TokenVerifier = class {
   jwksTimeoutMs;
   clockToleranceSec;
   allowPreAuthTokens;
+  allowedTypes;
   fetchImpl;
   /** Imported keys by `kid`, so a repeat verification skips the import cost. */
   keys = /* @__PURE__ */ new Map();
   keysFetchedAt = 0;
   lastFetchAttemptAt = 0;
+  /** Whether the latest read of the key set failed, for an unknown `kid`. */
+  lastFetchFailed = false;
   /** In-flight fetch, so a burst of requests triggers one call, not N. */
   inFlight = null;
   constructor(options = {}) {
@@ -1420,6 +1475,7 @@ var TokenVerifier = class {
     this.jwksTimeoutMs = options.jwksTimeoutMs ?? DEFAULT_JWKS_TIMEOUT_MS;
     this.clockToleranceSec = options.clockToleranceSec ?? DEFAULT_CLOCK_TOLERANCE_SEC;
     this.allowPreAuthTokens = options.allowPreAuthTokens ?? false;
+    this.allowedTypes = new Set(options.allowedTypes ?? ["identity"]);
     const boundFetch = options.fetch ?? globalThis.fetch;
     if (typeof boundFetch !== "function") {
       throw new TypeError(
@@ -1497,6 +1553,14 @@ var TokenVerifier = class {
         `Token has an unrecognised \`type\` claim: ${JSON.stringify(claims.type)}.`
       );
     }
+    if (!this.allowedTypes.has(claims.type)) {
+      throw new CanopyTokenError(
+        "token.type_not_allowed",
+        `Token is for a "${claims.type}" principal; this verifier accepts ${[
+          ...this.allowedTypes
+        ].map((type) => `"${type}"`).join(", ")}. Set \`allowedTypes\` to accept another.`
+      );
+    }
     if (claims.iss !== this.issuer) {
       throw new CanopyTokenError(
         "token.issuer_mismatch",
@@ -1569,7 +1633,13 @@ var TokenVerifier = class {
     const stale = Date.now() - this.keysFetchedAt > this.jwksCacheMaxAgeMs;
     if (this.keys.size === 0 || stale) {
       if (this.shouldRefresh()) {
-        await this.refreshKeys();
+        try {
+          await this.refreshKeys();
+        } catch (error) {
+          if (this.keys.size === 0) {
+            throw error;
+          }
+        }
       } else if (this.keys.size === 0) {
         throw new CanopyTokenError(
           "token.jwks_unavailable",
@@ -1588,6 +1658,12 @@ var TokenVerifier = class {
     if (rotated) {
       return rotated;
     }
+    if (this.lastFetchFailed) {
+      throw new CanopyTokenError(
+        "token.jwks_unavailable",
+        `Signing keys at ${this.jwksUri} could not be read to look up kid "${kid}".`
+      );
+    }
     throw new CanopyTokenError(
       "token.key_not_found",
       `No signing key matches kid "${kid}".`
@@ -1618,6 +1694,15 @@ var TokenVerifier = class {
   }
   async fetchKeys() {
     this.lastFetchAttemptAt = Date.now();
+    try {
+      await this.readKeys();
+      this.lastFetchFailed = false;
+    } catch (error) {
+      this.lastFetchFailed = true;
+      throw error;
+    }
+  }
+  async readKeys() {
     let response;
     const controller = new AbortController();
     const timer = this.jwksTimeoutMs > 0 ? setTimeout(() => controller.abort(), this.jwksTimeoutMs) : void 0;
@@ -1690,6 +1775,6 @@ function isWebhookEvent(delivery, name) {
   return delivery.event === name;
 }
 
-export { Assignments, Canopy, CanopyAuthorizerError, CanopyClient, CanopyConnectionError, CanopyError, CanopyTokenError, Identities, LocalAuthorizer, MAX_TTL_MS, Organizations, Paginator, Permissions, Roles, TokenVerifier, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, orgContext, paginate, withConcurrency };
+export { Assignments, Canopy, CanopyAuthorizerError, CanopyClient, CanopyConnectionError, CanopyError, CanopyTokenError, Identities, LocalAuthorizer, MAX_TTL_MS, Organizations, Paginator, Permissions, Roles, TokenVerifier, authorizationErrorStatus, isCanopyAuthorizerError, isCanopyConnectionError, isCanopyError, isCanopyTokenError, isCursorPagination, isWebhookEvent, orgContext, paginate, tokenErrorStatus, withConcurrency };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map