@canopy-io/node 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @canopy-io/node
 
+## 0.8.0
+
+### Minor Changes
+
+- 621b9a6: `TokenVerifier` accepts identity tokens only by default. Tokens Canopy signs for its own administrators (`user`), staff (`platform`) and API key flows (`api_key`) are refused with `token.type_not_allowed` unless named in the new `allowedTypes` option; `CanopyTokenGuard` takes it under `verify.allowedTypes`.
+  
+  When Canopy cannot be reached as cached signing keys come due for a refresh, the verifier keeps verifying with the keys it holds instead of failing every request until the issuer is back. A token signed by a key the verifier has never seen, during an outage, is reported as `token.jwks_unavailable` (503) rather than `token.key_not_found` (401).
+  
+  New exports `tokenErrorStatus` and `authorizationErrorStatus` turn a failed verification or authorization check into the HTTP status and message to answer with; the NestJS guards use them. The node README's verification example now names its Environment, and documents the 503 and the per-process reach of `LocalAuthorizer.invalidate()`.
+
+## 0.7.2
+
+### Patch Changes
+
+- 66415c2: The NestJS README's first `CanopyModule.forRoot` example now includes the required `verify` option, and `@canopy-io/node`'s types are regenerated from the published spec, adding the `branding.view` and `branding.manage` API key scopes. No behaviour changes.
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -37,7 +37,8 @@ import { Canopy, isCanopyError } from "@canopy-io/node";
 
 const canopy = new Canopy({ apiKey: process.env.CANOPY_API_KEY });
 
-// The call every integrator makes on every request.
+// A fresh decision from the API. On the request path, prefer LocalAuthorizer
+// (below), which answers in-process.
 const { allowed } = await canopy.permissions.evaluate({
   identity_id: identityId,
   permission: "documents.read",
@@ -81,30 +82,43 @@ access tokens RS256 and publishes the keys, so a token is checked locally —
 one JWKS fetch, then no network on any verification after it.
 
 ```ts
-import { TokenVerifier, isCanopyTokenError } from "@canopy-io/node";
+import { TokenVerifier, tokenErrorStatus } from "@canopy-io/node";
 
-const verifier = new TokenVerifier();
+const verifier = new TokenVerifier({
+  environmentId: process.env.CANOPY_ENVIRONMENT_ID,
+});
 
 try {
   const claims = await verifier.verify(bearerToken);
 
-  claims.sub; // the identity or user id
-  claims.type; // "identity" | "user" | "api_key" | "platform"
+  claims.sub; // the identity's id
+  claims.type; // "identity", the only type accepted by default
   claims.environment_id; // present on identity tokens
 } catch (error) {
-  if (isCanopyTokenError(error)) {
-    // Every code here means 401 to the caller who presented the token.
-    // `error.code` is for your logs: token.expired, token.signature_invalid,
-    // token.issuer_mismatch, and so on.
-  }
+  // 401 when the token is at fault, 503 when the signing keys could not be
+  // read and the token may be good. `error.code` is for your logs:
+  // token.expired, token.signature_invalid, token.jwks_unavailable, ...
+  const { status, message } = tokenErrorStatus(error);
 
-  throw error;
+  return response.status(status).json({ message });
 }
 ```
 
-Hosted Login tokens carry an audience, so name your client. Direct API tokens
-carry none and need no option — and a token that has an `aud` is refused
-rather than ignored when you have not said which client you are:
+A verifier accepts only identity tokens, the people who sign in to your
+application. Canopy signs tokens for its own administrators (`user`), its
+staff (`platform`) and some API key flows (`api_key`) with the same keys and
+issuer, so they are refused with `token.type_not_allowed` unless you name them:
+`new TokenVerifier({ ..., allowedTypes: ["identity", "user"] })`.
+
+If Canopy cannot be reached when the cached keys are due for a refresh, the
+verifier keeps verifying with the keys it holds; only a verifier that has never
+loaded a key set, or a token signed by a key it has never seen, answers
+`token.jwks_unavailable`.
+
+Hosted Login tokens carry an audience, your `client_id`, so name your client.
+Direct API tokens carry none and need no option. A token that has an `aud` is
+refused rather than ignored when you have not said which client you are, so a
+token minted for another client is never accepted by accident:
 
 ```ts
 new TokenVerifier({ audience: process.env.CANOPY_OAUTH_CLIENT_ID });
@@ -241,6 +255,34 @@ every request then finds the cache expired and refetches.
 
 `canopy.permissions.evaluate` remains for a decision with no staleness at all.
 
+`authorizer.invalidate(identityId)` drops one identity's cached grants, so
+the next check reads them fresh. It reaches only this process: with several
+instances behind a load balancer, each keeps its own cache until its TTL runs
+out or it is told to invalidate too.
+
+A failed check (Canopy unreachable, a credential that cannot read the
+hierarchy, an identity not in the Environment) throws rather than answering
+`false`. `authorizationErrorStatus` turns the error into the response to send:
+`503` when Canopy did not answer, `500` for a misconfiguration no retry fixes,
+`403` for an identity Canopy does not know. The NestJS guard uses the same
+mapping.
+
+```ts
+import { authorizationErrorStatus } from "@canopy-io/node";
+
+try {
+  const { allowed } = await authorizer.evaluate(query);
+
+  if (!allowed) {
+    return response.status(403).json({ message: "Forbidden" });
+  }
+} catch (error) {
+  const { status, message } = authorizationErrorStatus(error);
+
+  return response.status(status).json({ message });
+}
+```
+
 The credential needs to be able to read both halves. A `full_access` API key
 already can; a **scoped** one must list `identity.view` (the grant roots) and
 `hierarchy.view` (the tree). Without the latter the tree endpoint answers an

package/dist/index.cjs

@@ -56,6 +56,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) {
@@ -1346,6 +1348,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;
@@ -1406,11 +1458,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 = {}) {
@@ -1422,6 +1477,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(
@@ -1499,6 +1555,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",
@@ -1571,7 +1635,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",
@@ -1590,6 +1660,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}".`
@@ -1620,6 +1696,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;
@@ -1707,6 +1792,7 @@ exports.Paginator = Paginator;
 exports.Permissions = Permissions;
 exports.Roles = Roles;
 exports.TokenVerifier = TokenVerifier;
+exports.authorizationErrorStatus = authorizationErrorStatus;
 exports.isCanopyAuthorizerError = isCanopyAuthorizerError;
 exports.isCanopyConnectionError = isCanopyConnectionError;
 exports.isCanopyError = isCanopyError;
@@ -1715,6 +1801,7 @@ exports.isCursorPagination = isCursorPagination;
 exports.isWebhookEvent = isWebhookEvent;
 exports.orgContext = orgContext;
 exports.paginate = paginate;
+exports.tokenErrorStatus = tokenErrorStatus;
 exports.withConcurrency = withConcurrency;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map