@canopy-io/nestjs 0.1.0 → 0.1.1

package/README.md

@@ -12,6 +12,19 @@ npm install @canopy-io/nestjs
 
 Requires NestJS 10 or 11 and Node 18 or later. `@canopy-io/node` comes with it.
 
+## Features
+
+- **One registration.** `CanopyModule.forRoot` for a static key, `forRootAsync` when it comes from something injectable. Pass your own request type and the resolvers are typed against it.
+- **`@RequirePermission` on the route.** The check is a declaration on the handler rather than a call inside it. A route without it passes through untouched, so the guard can be registered globally and opted into.
+- **`CanopyGuard`** answers that declaration **in your own process**, at the node the request names — inheriting a role granted on a parent without you modelling the walk.
+- **No network call per request.** The guard holds the identity's grant roots and one shared copy of your hierarchy, refreshed at most once a minute, so a guarded route normally reaches no network at all.
+- **Two scopes.** `node` is the default and the strict question; `app_wide` asks only whether the identity holds the permission anywhere in the Environment.
+- **`CanopyTokenGuard`** verifies a Canopy-issued bearer token locally against the published signing keys and attaches the claims, for applications with no auth layer in front. Additive — skip it if you already run Passport or your own JWT middleware.
+- **`@InjectCanopy()`** hands you the full `@canopy-io/node` client for everything the guard does not cover.
+- **Fails closed, with the status telling you which failure it was.** `403` for a denial, `503` for an undecidable one, `500` for a broken integration.
+- **A bounded check.** Its own evaluation timeout and retry count, separate from the client-wide ones, with the wait between attempts capped.
+- **Aborts when the caller hangs up**, on both Express and Fastify, rather than finishing a decision no one will read.
+
 ## Register
 
 ```ts
@@ -21,8 +34,8 @@ import { CanopyModule } from "@canopy-io/nestjs";
   imports: [
     CanopyModule.forRoot<AuthedRequest>({
       apiKey: process.env.CANOPY_API_KEY,
-      resolveIdentity: (request) => request.user.sub,
-      resolveNode: (request) => request.params.orgId,
+      resolveIdentity: (request) => request.user?.sub,
+      resolveNode: (request) => request.params?.orgId,
     }),
   ],
 })
@@ -39,8 +52,8 @@ CanopyModule.forRootAsync({
   inject: [ConfigService],
   useFactory: (config: ConfigService) => ({
     apiKey: config.getOrThrow("CANOPY_API_KEY"),
-    resolveIdentity: (request) => request.user.sub,
-    resolveNode: (request) => request.params.orgId,
+    resolveIdentity: (request) => request.user?.sub,
+    resolveNode: (request) => request.params?.orgId,
   }),
 });
 ```
@@ -59,9 +72,26 @@ export class OrdersController {
 }
 ```
 
-That asks Canopy whether the identity holds `orders.refund` **at** `orgId`, walking the node's lineage — so a role granted on a parent is inherited without you modelling it.
+That answers whether the identity holds `orders.refund` **at** `orgId`, walking the node's lineage — so a role granted on a parent is inherited without you modelling it.
+
+The walk happens in your process, not over the network. See [How the decision is reached](#how-the-decision-is-reached).
+
+A route with no `@RequirePermission` passes through untouched, so the guard can be registered globally and opted into per route. A requirement on a handler wins over one on its controller.
+
+### If you register it globally
 
-A route with no `@RequirePermission` passes through untouched, so the guard is safe to register globally and opt into per route. A requirement on a handler wins over one on its controller.
+Nest runs global guards **before** controller- and route-scoped ones. So a globally-registered `CanopyGuard` runs before a route-level `AuthGuard` has put anything on the request, and `resolveIdentity` finds nothing — every guarded route answers `403`.
+
+Register your authentication guard globally too, ahead of this one:
+
+```ts
+providers: [
+  { provide: APP_GUARD, useClass: JwtAuthGuard }, // must come first
+  { provide: APP_GUARD, useClass: CanopyGuard },
+];
+```
+
+Global guards run in registration order. If your authentication is route-level, apply `CanopyGuard` at the route as well — `@UseGuards(JwtAuthGuard, CanopyGuard)` — where left-to-right order holds.
 
 ### Scope
 
@@ -73,6 +103,49 @@ The default is `node`, which is the strict question: does this identity hold the
 
 `app_wide` asks only whether the identity holds the permission anywhere in the Environment, and returns no effective node. It is right for deciding whether to show a menu item and wrong for guarding a resource that belongs to a node — which is why it is opt-in rather than the default.
 
+## If Canopy issues your tokens
+
+`resolveIdentity` assumes something upstream already verified the caller. If
+you have no auth layer yet, `CanopyTokenGuard` is that layer: it verifies the
+bearer token against Canopy's published signing keys and attaches the claims,
+so `resolveIdentity` has something trustworthy to read.
+
+```ts
+CanopyModule.forRoot<AuthedRequest>({
+  apiKey: process.env.CANOPY_API_KEY,
+  verify: { audience: process.env.CANOPY_OAUTH_CLIENT_ID }, // omit for Direct API
+  resolveIdentity: (request) => request.canopyToken?.sub,
+});
+```
+
+```ts
+@UseGuards(CanopyTokenGuard, CanopyGuard)
+@RequirePermission("documents.read")
+findAll() {}
+```
+
+**Order matters.** Nest runs guards left to right, and `CanopyGuard` reads what
+`CanopyTokenGuard` attaches. Reversed, every request is denied — the identity
+is resolved before anything has established one.
+
+Verification is local: one fetch of the key set, then a signature check per
+request with no network at all.
+
+A rejected token is a 401 whatever the detail, with the specific code left on
+`error.cause` for your logs rather than handed to the caller — who has no use
+for the difference and should not be told which check failed. The exception is
+`token.jwks_unavailable`, which answers **503**: not being able to verify is not
+the same as failing to verify, the caller's token may be perfectly good, and
+telling a client its token is stale during a key-server outage only aims a
+refresh storm at the thing that is already down.
+
+Claims land on `request.canopyToken`, not `request.user` — that one belongs to
+Passport, and quietly overwriting it would be somebody's difficult afternoon.
+Use `attachTokenAs` to put them elsewhere.
+
+Skip this guard entirely if you already run Passport or your own JWT
+middleware. It is additive; nothing else in the package depends on it.
+
 ## The client
 
 For anything the guard does not cover, inject the client:
@@ -100,12 +173,101 @@ It is the same [`@canopy-io/node`](../node) client, with its retry policy, pagin
 
 There is no path through `CanopyGuard` that allows a request whose decision is unknown. Each of these ends the request:
 
-- no identity resolves — `403`
+- no identity resolves, including when a resolver throws on an unauthenticated request — `403`
 - a `node` check with no node, or with no `resolveNode` configured — `403`
-- Canopy answers `allowed: false` — `403`
-- Canopy cannot be reached — `503`, deliberately not `403`, because "we could not decide" is not "you are not allowed"
+- the identity holds the permission nowhere, or nowhere on this node's lineage — `403`
+- Canopy has never heard of the identity (`404`) — `403`
+- a cache miss cannot be filled because Canopy is unreachable, rate-limiting, or answers `5xx` — `503`, deliberately not `403`, because "we could not decide" is not "you are not allowed"
+- Canopy rejects the API key (`401`/`403`), or refuses the read (other `4xx`) — `500`, because a misconfiguration is not a temporary condition and no retry will fix it
+- the hierarchy this credential can read does not contain the node — `500`, naming the cause. Undecidable, not denied: answering `403` would take out every node-scoped route while looking like ordinary policy
+- the caller hung up mid-check — the abort is propagated, not turned into a `503`, because nothing failed and no one is waiting for an answer
+
+A held answer is never served past its window to paper over an outage. Once it expires, an unfillable read is a `503` — extending it silently would extend the revocation window with it, without anyone choosing to.
+
+Everything except the caller hanging up is logged with its cause before the request is refused.
+
+The `500` cases are worth alerting on: they mean the integration is broken rather than the service being slow. Reporting them as `503` would bury a bad API key under what looks like an outage.
+
+## How the decision is reached
+
+The guard does not ask Canopy per request. It asks a different question, once, and answers every later check from the result.
+
+Rather than "may this identity act **here**", it reads "**where** may this identity act" — the nodes each permission was granted at. Those grant roots are not expanded through their descendants, because a grant already means _this node and everything beneath it_; expanding would restate your hierarchy once per identity, and would be largest for the near-root grants your administrators hold.
+
+So two things are held, split by what they depend on:
+
+- **grant roots, per identity** — small, a handful of assignments
+- **your hierarchy, once per process** — shared by every identity, since its shape does not depend on who is asking
+
+and a check is a walk up from the node in question looking for a grant root. An `app_wide` check is simpler still: the permission appearing at all is the answer, and no hierarchy is needed.
+
+**Both are held for at most 60 seconds**, which is therefore the delay between an access change and it taking effect. The hierarchy is revalidated rather than re-read — a conditional request that normally answers `304`, so nothing transfers.
+
+```ts
+CanopyModule.forRoot({
+  apiKey: process.env.CANOPY_API_KEY,
+  authorizationTtlMs: 30_000,
+  resolveIdentity: (request) => request.user?.sub,
+});
+```
+
+Shortening that window makes revocation take effect sooner and costs more calls. Below the gap between a user's requests it stops saving anything at all — every request finds the cache expired and refetches, which is the per-request traffic this exists to remove. Human-paced traffic has multi-second gaps, so a few seconds can cost full price for no benefit.
+
+### What the credential needs
+
+A `full_access` API key needs nothing further. A **scoped** key must carry both
+of the permissions the guard reads with, because a scoped key is granted
+exactly the permission keys listed on it:
+
+- **`identity.view`** — to read an identity's grant roots.
+- **`hierarchy.view`** — to read the hierarchy the walk runs against, taken as parent edges (`GET /api/v1/nodes/parents`) rather than the dashboard's tree.
+
+Miss the first and every guarded route answers `500` naming the failed read.
+Miss the second and the tree comes back **empty with a `200`** — the API is
+answering "here is everything you may see", which is nothing. The guard does
+not treat that as an absence of grants: an incomplete hierarchy makes a
+node-scoped check undecidable, so it raises rather than denying. Silently
+denying there would take out every node-scoped route while every response still
+looked healthy.
+
+`app_wide` checks need only `identity.view`; they never consult the hierarchy.
+
+### What a revoked user can still do
+
+For up to the window, a request that should now be denied is allowed. That is the cost of not asking every time, and it is worth stating to whoever owns your access-review process rather than leaving it to be discovered.
+
+The window covers **every** change that can alter an answer, including a moved node — reparenting changes what an inherited grant reaches even though no grant itself changed, which is why the hierarchy is revalidated on the same cadence and not a slower one.
+
+Two ways out, depending on how much you need.
+
+For a **single** high-value operation, ask the API directly through the injected client — the rest of your routes keep the cache:
+
+```ts
+const { allowed } = await this.canopy.permissions.evaluate({
+  identity_id: identityId,
+  permission: "payments.release",
+  scope: "node",
+  node_id: nodeId,
+});
+```
+
+For an application that cannot tolerate a stale allow **anywhere**, set the window to zero. Every guarded request then reads fresh, which reinstates a round trip per request — the cost this design exists to remove, so choose it knowingly:
+
+```ts
+CanopyModule.forRoot({
+  apiKey: process.env.CANOPY_API_KEY,
+  authorizationTtlMs: 0,
+  resolveIdentity: (request) => request.user?.sub,
+});
+```
+
+### Bounding a cache miss
+
+A hit costs nothing. A miss reads from Canopy on the request path and holds an inbound request open, so it is bounded: a 5s per-attempt deadline rather than the client-wide 30s, and 1 retry rather than 2, with each wait between attempts capped at one deadline so a `Retry-After` header cannot hold the request past it. Both are settable with `evaluateTimeoutMs` and `evaluateMaxRetries`, and both apply to these reads alone — everything else through the injected client keeps the client-wide values.
+
+**Hanging up when the caller does.** If the client disconnects while a miss is being filled, the guard ends that check rather than finishing a decision no one will read. It watches the response for a close that arrives before anything was written, on Express (where Nest returns the Node response) and on Fastify (where the real response is on `reply.raw`).
 
-The unreachable case is logged with its cause before the request is refused.
+The read itself is deliberately **not** cancelled: it may be shared with other requests that are still waiting on it, and it warms the cache either way.
 
 ## License
 

package/dist/index.cjs

@@ -17,17 +17,32 @@ var __decorateParam = (index, decorator) => (target, key) => decorator(target, k
 // src/tokens.ts
 var CANOPY_OPTIONS = "CANOPY_OPTIONS";
 var CANOPY_CLIENT = "CANOPY_CLIENT";
+var CANOPY_AUTHORIZER = "CANOPY_AUTHORIZER";
+var CANOPY_TOKEN_VERIFIER = "CANOPY_TOKEN_VERIFIER";
 var CANOPY_PERMISSION = "CANOPY_PERMISSION";
 
 // src/canopy.guard.ts
+function isClosable(value) {
+  return typeof value === "object" && value !== null && typeof value.once === "function" && typeof value.removeListener === "function";
+}
+function resolveStream(response) {
+  const raw = response?.raw;
+  if (isClosable(raw)) {
+    return raw;
+  }
+  if (isClosable(response)) {
+    return response;
+  }
+  return void 0;
+}
 exports.CanopyGuard = class CanopyGuard {
-  constructor(reflector, canopy, options) {
+  constructor(reflector, authorizer, options) {
     this.reflector = reflector;
-    this.canopy = canopy;
+    this.authorizer = authorizer;
     this.options = options;
   }
   reflector;
-  canopy;
+  authorizer;
   options;
   logger = new common.Logger(exports.CanopyGuard.name);
   async canActivate(context) {
@@ -35,14 +50,20 @@ exports.CanopyGuard = class CanopyGuard {
     if (!requirement) {
       return true;
     }
-    const request = context.switchToHttp().getRequest();
-    const identityId = this.options.resolveIdentity(request);
+    const http = context.switchToHttp();
+    const request = http.getRequest();
+    const identityId = resolveSafely(this.options.resolveIdentity, request);
     if (!identityId) {
       throw new common.ForbiddenException(
         "No identity on the request. Canopy cannot evaluate a permission without one."
       );
     }
-    const decision = await this.evaluate(requirement, identityId, request);
+    const decision = await this.evaluate(
+      requirement,
+      identityId,
+      request,
+      watchDisconnect(http)
+    );
     if (!decision.allowed) {
       throw new common.ForbiddenException(
         `Identity does not hold ${requirement.permission}.`
@@ -57,19 +78,66 @@ exports.CanopyGuard = class CanopyGuard {
    * decision, so a caller cannot mistake "we could not tell" for "denied by
    * policy" — and neither outcome lets the request proceed.
    */
-  async evaluate(requirement, identityId, request) {
+  async evaluate(requirement, identityId, request, cancellation) {
     const query = this.buildQuery(requirement, identityId, request);
     try {
-      return await this.canopy.permissions.evaluate(query);
+      return await this.authorizer.evaluate(
+        query,
+        cancellation ? { signal: cancellation.signal } : {}
+      );
     } catch (error) {
+      if (cancellation?.signal.aborted) {
+        throw error;
+      }
       this.logger.error(
         `Could not evaluate ${requirement.permission} for ${identityId}`,
         error instanceof Error ? error.stack : String(error)
       );
-      throw new common.ServiceUnavailableException(
+      throw this.toHttpException(error);
+    } finally {
+      cancellation?.dispose();
+    }
+  }
+  /**
+   * Turn a failed check into the status that describes it.
+   *
+   * Every branch denies — nothing here can let a request through — but they say
+   * different things, and the difference is what makes an incident diagnosable.
+   * Reporting a rejected API key as "temporarily unavailable" invites a retry
+   * that will never succeed and hides a misconfiguration behind an outage.
+   */
+  toHttpException(error) {
+    if (node.isCanopyAuthorizerError(error)) {
+      return new common.InternalServerErrorException(
+        `Authorization is misconfigured: ${error.message}`
+      );
+    }
+    if (!node.isCanopyError(error)) {
+      return new common.ServiceUnavailableException(
+        "Authorization is temporarily unavailable."
+      );
+    }
+    if (error.isAuthFailure) {
+      return new common.InternalServerErrorException(
+        "Authorization is misconfigured. Check the Canopy API key and its scopes."
+      );
+    }
+    if (error.statusCode === 404 && error.code === null) {
+      return new common.InternalServerErrorException(
+        `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 new common.ForbiddenException("Could not evaluate the permission.");
+    }
+    if (error.isRateLimited || error.statusCode >= 500) {
+      return new common.ServiceUnavailableException(
         "Authorization is temporarily unavailable."
       );
     }
+    return new common.InternalServerErrorException(
+      "Authorization could not be evaluated."
+    );
   }
   buildQuery(requirement, identityId, request) {
     if (requirement.scope === "app_wide") {
@@ -79,7 +147,7 @@ exports.CanopyGuard = class CanopyGuard {
         scope: "app_wide"
       };
     }
-    const nodeId = this.options.resolveNode?.(request);
+    const nodeId = this.options.resolveNode ? resolveSafely(this.options.resolveNode, request) : void 0;
     if (!nodeId) {
       throw new common.ForbiddenException(
         `No node on the request. ${requirement.permission} is checked at a node; configure resolveNode, or declare the route as app_wide if that is genuinely the question.`
@@ -96,11 +164,102 @@ exports.CanopyGuard = class CanopyGuard {
 exports.CanopyGuard = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Inject(core.Reflector)),
-  __decorateParam(1, common.Inject(CANOPY_CLIENT)),
+  __decorateParam(1, common.Inject(CANOPY_AUTHORIZER)),
   __decorateParam(2, common.Inject(CANOPY_OPTIONS))
 ], exports.CanopyGuard);
+function resolveSafely(resolve, request) {
+  try {
+    return resolve(
+      request
+    );
+  } catch {
+    return void 0;
+  }
+}
+function watchDisconnect(http) {
+  const raw = resolveStream(http.getResponse?.());
+  if (!raw) {
+    return void 0;
+  }
+  const controller = new AbortController();
+  const onClose = () => {
+    if (raw.writableEnded === true) {
+      return;
+    }
+    controller.abort(
+      new DOMException("The client closed the request", "AbortError")
+    );
+  };
+  raw.once("close", onClose);
+  return {
+    signal: controller.signal,
+    dispose: () => raw.removeListener("close", onClose)
+  };
+}
+exports.CanopyTokenGuard = class CanopyTokenGuard {
+  constructor(verifier, options) {
+    this.verifier = verifier;
+    this.options = options;
+  }
+  verifier;
+  options;
+  async canActivate(context) {
+    const request = context.switchToHttp().getRequest();
+    const token = readBearerToken(request.headers?.["authorization"]);
+    if (token === null) {
+      throw new common.UnauthorizedException(
+        "Missing bearer token in the Authorization header."
+      );
+    }
+    let claims;
+    try {
+      claims = await this.verifier.verify(token);
+    } catch (error) {
+      if (node.isCanopyTokenError(error) && error.code === "token.jwks_unavailable") {
+        throw new common.ServiceUnavailableException(
+          "Authentication is temporarily unavailable.",
+          { cause: error }
+        );
+      }
+      if (node.isCanopyTokenError(error)) {
+        throw new common.UnauthorizedException("Invalid or expired access token.", {
+          cause: error
+        });
+      }
+      throw error;
+    }
+    request[this.options.attachTokenAs ?? "canopyToken"] = claims;
+    return true;
+  }
+};
+exports.CanopyTokenGuard = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(CANOPY_TOKEN_VERIFIER)),
+  __decorateParam(1, common.Inject(CANOPY_OPTIONS))
+], exports.CanopyTokenGuard);
+function readBearerToken(header) {
+  const value = Array.isArray(header) ? header[0] : header;
+  if (typeof value !== "string") {
+    return null;
+  }
+  const match = /^bearer\s+(.+)$/i.exec(value.trim());
+  if (!match?.[1]) {
+    return null;
+  }
+  const token = match[1].trim();
+  return token.length > 0 ? token : null;
+}
 
 // src/canopy.module.ts
+var DEFAULT_EVALUATE_TIMEOUT_MS = 5e3;
+var DEFAULT_EVALUATE_MAX_RETRIES = 1;
+function buildAuthorizer(client, options) {
+  return new node.LocalAuthorizer(client.client, {
+    ...options.authorizationTtlMs === void 0 ? {} : { ttlMs: options.authorizationTtlMs },
+    timeoutMs: options.evaluateTimeoutMs ?? DEFAULT_EVALUATE_TIMEOUT_MS,
+    maxRetries: options.evaluateMaxRetries ?? DEFAULT_EVALUATE_MAX_RETRIES
+  });
+}
 exports.CanopyModule = class CanopyModule {
   static forRoot(options) {
     const providers = [
@@ -109,13 +268,30 @@ exports.CanopyModule = class CanopyModule {
         provide: CANOPY_CLIENT,
         useFactory: () => new node.Canopy(options)
       },
-      exports.CanopyGuard
+      {
+        provide: CANOPY_TOKEN_VERIFIER,
+        useFactory: () => new node.TokenVerifier(options.verify)
+      },
+      {
+        provide: CANOPY_AUTHORIZER,
+        useFactory: (client) => buildAuthorizer(client, options),
+        inject: [CANOPY_CLIENT]
+      },
+      exports.CanopyGuard,
+      exports.CanopyTokenGuard
     ];
     return {
       module: exports.CanopyModule,
       global: options.isGlobal ?? false,
       providers,
-      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, exports.CanopyGuard]
+      exports: [
+        CANOPY_CLIENT,
+        CANOPY_OPTIONS,
+        CANOPY_TOKEN_VERIFIER,
+        CANOPY_AUTHORIZER,
+        exports.CanopyGuard,
+        exports.CanopyTokenGuard
+      ]
     };
   }
   /**
@@ -134,7 +310,18 @@ exports.CanopyModule = class CanopyModule {
         useFactory: (resolved) => new node.Canopy(resolved),
         inject: [CANOPY_OPTIONS]
       },
-      exports.CanopyGuard
+      {
+        provide: CANOPY_TOKEN_VERIFIER,
+        useFactory: (resolved) => new node.TokenVerifier(resolved.verify),
+        inject: [CANOPY_OPTIONS]
+      },
+      {
+        provide: CANOPY_AUTHORIZER,
+        useFactory: (client, resolved) => buildAuthorizer(client, resolved),
+        inject: [CANOPY_CLIENT, CANOPY_OPTIONS]
+      },
+      exports.CanopyGuard,
+      exports.CanopyTokenGuard
     ];
     return {
       module: exports.CanopyModule,
@@ -143,7 +330,14 @@ exports.CanopyModule = class CanopyModule {
       // explicit `imports: undefined` is not the same as no `imports` at all.
       ...options.imports ? { imports: options.imports } : {},
       providers,
-      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, exports.CanopyGuard]
+      exports: [
+        CANOPY_CLIENT,
+        CANOPY_OPTIONS,
+        CANOPY_TOKEN_VERIFIER,
+        CANOPY_AUTHORIZER,
+        exports.CanopyGuard,
+        exports.CanopyTokenGuard
+      ]
     };
   }
 };
@@ -156,9 +350,11 @@ var RequirePermission = (permission, options = {}) => common.SetMetadata(CANOPY_
   scope: options.scope ?? "node"
 });
 
+exports.CANOPY_AUTHORIZER = CANOPY_AUTHORIZER;
 exports.CANOPY_CLIENT = CANOPY_CLIENT;
 exports.CANOPY_OPTIONS = CANOPY_OPTIONS;
 exports.CANOPY_PERMISSION = CANOPY_PERMISSION;
+exports.CANOPY_TOKEN_VERIFIER = CANOPY_TOKEN_VERIFIER;
 exports.InjectCanopy = InjectCanopy;
 exports.RequirePermission = RequirePermission;
 //# sourceMappingURL=index.cjs.map