@canopy-io/nestjs 0.1.0 → 0.1.1

package/dist/index.js

@@ -1,5 +1,5 @@
-import { Injectable, Inject, Module, Logger, ForbiddenException, ServiceUnavailableException, SetMetadata } from '@nestjs/common';
-import { Canopy } from '@canopy-io/node';
+import { Injectable, Inject, Module, Logger, ForbiddenException, InternalServerErrorException, ServiceUnavailableException, UnauthorizedException, SetMetadata } from '@nestjs/common';
+import { isCanopyAuthorizerError, isCanopyError, isCanopyTokenError, Canopy, TokenVerifier, LocalAuthorizer } from '@canopy-io/node';
 import { Reflector } from '@nestjs/core';
 
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -15,17 +15,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;
+}
 var CanopyGuard = class {
-  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 Logger(CanopyGuard.name);
   async canActivate(context) {
@@ -33,14 +48,20 @@ var CanopyGuard = class {
     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 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 ForbiddenException(
         `Identity does not hold ${requirement.permission}.`
@@ -55,19 +76,66 @@ var CanopyGuard = class {
    * 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 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 (isCanopyAuthorizerError(error)) {
+      return new InternalServerErrorException(
+        `Authorization is misconfigured: ${error.message}`
+      );
+    }
+    if (!isCanopyError(error)) {
+      return new ServiceUnavailableException(
+        "Authorization is temporarily unavailable."
+      );
+    }
+    if (error.isAuthFailure) {
+      return new InternalServerErrorException(
+        "Authorization is misconfigured. Check the Canopy API key and its scopes."
+      );
+    }
+    if (error.statusCode === 404 && error.code === null) {
+      return new 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 ForbiddenException("Could not evaluate the permission.");
+    }
+    if (error.isRateLimited || error.statusCode >= 500) {
+      return new ServiceUnavailableException(
         "Authorization is temporarily unavailable."
       );
     }
+    return new InternalServerErrorException(
+      "Authorization could not be evaluated."
+    );
   }
   buildQuery(requirement, identityId, request) {
     if (requirement.scope === "app_wide") {
@@ -77,7 +145,7 @@ var CanopyGuard = class {
         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 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.`
@@ -94,11 +162,102 @@ var CanopyGuard = class {
 CanopyGuard = __decorateClass([
   Injectable(),
   __decorateParam(0, Inject(Reflector)),
-  __decorateParam(1, Inject(CANOPY_CLIENT)),
+  __decorateParam(1, Inject(CANOPY_AUTHORIZER)),
   __decorateParam(2, Inject(CANOPY_OPTIONS))
 ], 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)
+  };
+}
+var CanopyTokenGuard = class {
+  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 UnauthorizedException(
+        "Missing bearer token in the Authorization header."
+      );
+    }
+    let claims;
+    try {
+      claims = await this.verifier.verify(token);
+    } catch (error) {
+      if (isCanopyTokenError(error) && error.code === "token.jwks_unavailable") {
+        throw new ServiceUnavailableException(
+          "Authentication is temporarily unavailable.",
+          { cause: error }
+        );
+      }
+      if (isCanopyTokenError(error)) {
+        throw new UnauthorizedException("Invalid or expired access token.", {
+          cause: error
+        });
+      }
+      throw error;
+    }
+    request[this.options.attachTokenAs ?? "canopyToken"] = claims;
+    return true;
+  }
+};
+CanopyTokenGuard = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(CANOPY_TOKEN_VERIFIER)),
+  __decorateParam(1, Inject(CANOPY_OPTIONS))
+], 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 LocalAuthorizer(client.client, {
+    ...options.authorizationTtlMs === void 0 ? {} : { ttlMs: options.authorizationTtlMs },
+    timeoutMs: options.evaluateTimeoutMs ?? DEFAULT_EVALUATE_TIMEOUT_MS,
+    maxRetries: options.evaluateMaxRetries ?? DEFAULT_EVALUATE_MAX_RETRIES
+  });
+}
 var CanopyModule = class {
   static forRoot(options) {
     const providers = [
@@ -107,13 +266,30 @@ var CanopyModule = class {
         provide: CANOPY_CLIENT,
         useFactory: () => new Canopy(options)
       },
-      CanopyGuard
+      {
+        provide: CANOPY_TOKEN_VERIFIER,
+        useFactory: () => new TokenVerifier(options.verify)
+      },
+      {
+        provide: CANOPY_AUTHORIZER,
+        useFactory: (client) => buildAuthorizer(client, options),
+        inject: [CANOPY_CLIENT]
+      },
+      CanopyGuard,
+      CanopyTokenGuard
     ];
     return {
       module: CanopyModule,
       global: options.isGlobal ?? false,
       providers,
-      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, CanopyGuard]
+      exports: [
+        CANOPY_CLIENT,
+        CANOPY_OPTIONS,
+        CANOPY_TOKEN_VERIFIER,
+        CANOPY_AUTHORIZER,
+        CanopyGuard,
+        CanopyTokenGuard
+      ]
     };
   }
   /**
@@ -132,7 +308,18 @@ var CanopyModule = class {
         useFactory: (resolved) => new Canopy(resolved),
         inject: [CANOPY_OPTIONS]
       },
-      CanopyGuard
+      {
+        provide: CANOPY_TOKEN_VERIFIER,
+        useFactory: (resolved) => new TokenVerifier(resolved.verify),
+        inject: [CANOPY_OPTIONS]
+      },
+      {
+        provide: CANOPY_AUTHORIZER,
+        useFactory: (client, resolved) => buildAuthorizer(client, resolved),
+        inject: [CANOPY_CLIENT, CANOPY_OPTIONS]
+      },
+      CanopyGuard,
+      CanopyTokenGuard
     ];
     return {
       module: CanopyModule,
@@ -141,7 +328,14 @@ var CanopyModule = class {
       // explicit `imports: undefined` is not the same as no `imports` at all.
       ...options.imports ? { imports: options.imports } : {},
       providers,
-      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, CanopyGuard]
+      exports: [
+        CANOPY_CLIENT,
+        CANOPY_OPTIONS,
+        CANOPY_TOKEN_VERIFIER,
+        CANOPY_AUTHORIZER,
+        CanopyGuard,
+        CanopyTokenGuard
+      ]
     };
   }
 };
@@ -154,6 +348,6 @@ var RequirePermission = (permission, options = {}) => SetMetadata(CANOPY_PERMISS
   scope: options.scope ?? "node"
 });
 
-export { CANOPY_CLIENT, CANOPY_OPTIONS, CANOPY_PERMISSION, CanopyGuard, CanopyModule, InjectCanopy, RequirePermission };
+export { CANOPY_AUTHORIZER, CANOPY_CLIENT, CANOPY_OPTIONS, CANOPY_PERMISSION, CANOPY_TOKEN_VERIFIER, CanopyGuard, CanopyModule, CanopyTokenGuard, InjectCanopy, RequirePermission };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tokens.ts","../src/canopy.guard.ts","../src/canopy.module.ts","../src/inject-canopy.decorator.ts","../src/require-permission.decorator.ts"],"names":["Inject"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Injection tokens.\n *\n * These are strings rather than classes because esbuild does not emit\n * `design:paramtypes`, so nothing here can be injected by constructor type\n * alone — every dependency is named with an explicit `@Inject`.\n */\n\n/** The resolved `CanopyModuleOptions`. */\nexport const CANOPY_OPTIONS = \"CANOPY_OPTIONS\";\n\n/** The configured `Canopy` client. */\nexport const CANOPY_CLIENT = \"CANOPY_CLIENT\";\n\n/** Metadata key holding what `@RequirePermission` recorded on a handler. */\nexport const CANOPY_PERMISSION = \"CANOPY_PERMISSION\";\n","import {\n  type CanActivate,\n  type ExecutionContext,\n  ForbiddenException,\n  Inject,\n  Injectable,\n  Logger,\n  ServiceUnavailableException,\n} from \"@nestjs/common\";\nimport { Reflector } from \"@nestjs/core\";\n\nimport type { Canopy, RequestBody, ResponseBody } from \"@canopy-io/node\";\n\n/** Read off the generated operation, so it follows the API rather than restating it. */\ntype EvaluateQuery = RequestBody<\"ApiPermissionsController_evaluate\">;\ntype EvaluateDecision = ResponseBody<\"ApiPermissionsController_evaluate\">;\n\nimport type { CanopyModuleOptions } from \"./options.js\";\nimport type { PermissionRequirement } from \"./require-permission.decorator.js\";\nimport { CANOPY_CLIENT, CANOPY_OPTIONS, CANOPY_PERMISSION } from \"./tokens.js\";\n\n/**\n * Enforces `@RequirePermission` by asking Canopy, once, per guarded request.\n *\n * The guard fails closed at every step. An unresolvable identity, a `node`\n * check with no node, a denial, or an unreachable API all end the request —\n * there is no path through this class that allows a request whose decision is\n * unknown. That is the property worth protecting when reading this code: an\n * `allow` must be something Canopy actually said.\n *\n * A route with no requirement is allowed through untouched, so the guard is\n * safe to apply globally and opt into per route.\n */\n@Injectable()\nexport class CanopyGuard implements CanActivate {\n  private readonly logger = new Logger(CanopyGuard.name);\n\n  constructor(\n    @Inject(Reflector) private readonly reflector: Reflector,\n    @Inject(CANOPY_CLIENT) private readonly canopy: Canopy,\n    @Inject(CANOPY_OPTIONS)\n    private readonly options: CanopyModuleOptions<unknown>,\n  ) {}\n\n  async canActivate(context: ExecutionContext): Promise<boolean> {\n    const requirement = this.reflector.getAllAndOverride<\n      PermissionRequirement | undefined\n    >(CANOPY_PERMISSION, [context.getHandler(), context.getClass()]);\n\n    if (!requirement) {\n      return true;\n    }\n\n    const request: unknown = context.switchToHttp().getRequest();\n    const identityId = this.options.resolveIdentity(request);\n\n    if (!identityId) {\n      throw new ForbiddenException(\n        \"No identity on the request. Canopy cannot evaluate a permission without one.\",\n      );\n    }\n\n    const decision = await this.evaluate(requirement, identityId, request);\n\n    if (!decision.allowed) {\n      throw new ForbiddenException(\n        `Identity does not hold ${requirement.permission}.`,\n      );\n    }\n\n    return true;\n  }\n\n  /**\n   * Asks Canopy the question the decorator recorded.\n   *\n   * Every failure is converted into a thrown exception rather than a `false`\n   * decision, so a caller cannot mistake \"we could not tell\" for \"denied by\n   * policy\" — and neither outcome lets the request proceed.\n   */\n  private async evaluate(\n    requirement: PermissionRequirement,\n    identityId: string,\n    request: unknown,\n  ): Promise<EvaluateDecision> {\n    const query = this.buildQuery(requirement, identityId, request);\n\n    try {\n      return await this.canopy.permissions.evaluate(query);\n    } catch (error) {\n      // Deliberately not re-thrown as-is: a transport failure must not reach\n      // the client as though Canopy had answered.\n      this.logger.error(\n        `Could not evaluate ${requirement.permission} for ${identityId}`,\n        error instanceof Error ? error.stack : String(error),\n      );\n\n      throw new ServiceUnavailableException(\n        \"Authorization is temporarily unavailable.\",\n      );\n    }\n  }\n\n  private buildQuery(\n    requirement: PermissionRequirement,\n    identityId: string,\n    request: unknown,\n  ): EvaluateQuery {\n    if (requirement.scope === \"app_wide\") {\n      return {\n        identity_id: identityId,\n        permission: requirement.permission,\n        scope: \"app_wide\",\n      };\n    }\n\n    const nodeId = this.options.resolveNode?.(request);\n\n    if (!nodeId) {\n      throw new ForbiddenException(\n        `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.`,\n      );\n    }\n\n    return {\n      identity_id: identityId,\n      permission: requirement.permission,\n      scope: \"node\",\n      node_id: nodeId,\n    };\n  }\n}\n","import { type DynamicModule, Module, type Provider } from \"@nestjs/common\";\n\nimport { Canopy } from \"@canopy-io/node\";\n\nimport { CanopyGuard } from \"./canopy.guard.js\";\nimport type {\n  CanopyModuleAsyncOptions,\n  CanopyModuleOptions,\n} from \"./options.js\";\nimport { CANOPY_CLIENT, CANOPY_OPTIONS } from \"./tokens.js\";\n\n/**\n * Wires one configured `Canopy` client and the guard that uses it into a Nest\n * application.\n *\n * ```ts\n * CanopyModule.forRoot<AuthedRequest>({\n *   apiKey: process.env.CANOPY_API_KEY,\n *   resolveIdentity: (request) => request.user.sub,\n *   resolveNode: (request) => request.params.orgId,\n * })\n * ```\n *\n * The client is a singleton because it holds no per-request state — it is a\n * `fetch` wrapper with credentials — so there is nothing to gain from building\n * one per request and a connection pool to lose.\n */\n@Module({})\nexport class CanopyModule {\n  static forRoot<TRequest = unknown>(\n    options: CanopyModuleOptions<TRequest>,\n  ): DynamicModule {\n    const providers: Provider[] = [\n      { provide: CANOPY_OPTIONS, useValue: options },\n      {\n        provide: CANOPY_CLIENT,\n        useFactory: () => new Canopy(options),\n      },\n      CanopyGuard,\n    ];\n\n    return {\n      module: CanopyModule,\n      global: options.isGlobal ?? false,\n      providers,\n      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, CanopyGuard],\n    };\n  }\n\n  /**\n   * The same wiring when the API key comes from something injectable, such as\n   * `ConfigService`, rather than being available at module-definition time.\n   */\n  static forRootAsync<TRequest = unknown>(\n    options: CanopyModuleAsyncOptions<TRequest>,\n  ): DynamicModule {\n    const providers: Provider[] = [\n      {\n        provide: CANOPY_OPTIONS,\n        useFactory: options.useFactory,\n        inject: options.inject ?? [],\n      },\n      {\n        provide: CANOPY_CLIENT,\n        useFactory: (resolved: CanopyModuleOptions<TRequest>) =>\n          new Canopy(resolved),\n        inject: [CANOPY_OPTIONS],\n      },\n      CanopyGuard,\n    ];\n\n    return {\n      module: CanopyModule,\n      global: options.isGlobal ?? false,\n      // Spread rather than assigned: under exactOptionalPropertyTypes an\n      // explicit `imports: undefined` is not the same as no `imports` at all.\n      ...(options.imports ? { imports: options.imports } : {}),\n      providers,\n      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, CanopyGuard],\n    };\n  }\n}\n","import { Inject } from \"@nestjs/common\";\n\nimport { CANOPY_CLIENT } from \"./tokens.js\";\n\n/**\n * Injects the configured client.\n *\n * ```ts\n * constructor(@InjectCanopy() private readonly canopy: Canopy) {}\n * ```\n *\n * Named rather than resolved by type because this package is bundled with\n * esbuild, which emits no `design:paramtypes` — so type-only injection would\n * fail at runtime with a confusing \"cannot resolve dependency\" rather than at\n * build time.\n */\nexport const InjectCanopy = (): ParameterDecorator => Inject(CANOPY_CLIENT);\n","import { SetMetadata } from \"@nestjs/common\";\n\nimport { CANOPY_PERMISSION } from \"./tokens.js\";\n\n/**\n * Which question the guard asks Canopy.\n *\n * `node` walks the node's lineage, so a role granted on an ancestor is\n * inherited at the node being touched. `app_wide` asks only whether the\n * identity holds the permission anywhere in the Environment.\n */\nexport type PermissionScope = \"node\" | \"app_wide\";\n\n/** What `@RequirePermission` records for the guard to read back. */\nexport interface PermissionRequirement {\n  readonly permission: string;\n  readonly scope: PermissionScope;\n}\n\nexport interface RequirePermissionOptions {\n  /**\n   * Defaults to `node`.\n   *\n   * `app_wide` is opt-in on purpose. It answers a coarser question and returns\n   * no effective node, which makes it right for deciding whether to render a\n   * menu item and wrong for guarding a resource that belongs to one — a\n   * distinction that is easy to get backwards if the looser check is the\n   * default.\n   */\n  readonly scope?: PermissionScope;\n}\n\n/**\n * Require a Canopy permission before a route runs.\n *\n * ```ts\n * @UseGuards(CanopyGuard)\n * @RequirePermission(\"orders.refund\")\n * @Post(\":orderId/refund\")\n * refund() {}\n * ```\n *\n * Applies to a single handler or to a whole controller; a handler's own\n * requirement wins over its controller's.\n */\nexport const RequirePermission = (\n  permission: string,\n  options: RequirePermissionOptions = {},\n): MethodDecorator & ClassDecorator =>\n  SetMetadata<string, PermissionRequirement>(CANOPY_PERMISSION, {\n    permission,\n    scope: options.scope ?? \"node\",\n  });\n"]}
+{"version":3,"sources":["../src/tokens.ts","../src/canopy.guard.ts","../src/canopy-token.guard.ts","../src/canopy.module.ts","../src/inject-canopy.decorator.ts","../src/require-permission.decorator.ts"],"names":["ServiceUnavailableException","Injectable","Inject","TokenVerifier"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Injection tokens.\n *\n * These are strings rather than classes because esbuild does not emit\n * `design:paramtypes`, so nothing here can be injected by constructor type\n * alone — every dependency is named with an explicit `@Inject`.\n */\n\n/** The resolved `CanopyModuleOptions`. */\nexport const CANOPY_OPTIONS = \"CANOPY_OPTIONS\";\n\n/** The configured `Canopy` client. */\nexport const CANOPY_CLIENT = \"CANOPY_CLIENT\";\n\n/**\n * The configured `LocalAuthorizer`.\n *\n * Shared deliberately: it holds one copy of the hierarchy for the whole\n * process, so a second instance would double both the memory and the traffic\n * it exists to avoid.\n */\nexport const CANOPY_AUTHORIZER = \"CANOPY_AUTHORIZER\";\n\n/** The configured `TokenVerifier`, shared so its key cache is shared too. */\nexport const CANOPY_TOKEN_VERIFIER = \"CANOPY_TOKEN_VERIFIER\";\n\n/** Metadata key holding what `@RequirePermission` recorded on a handler. */\nexport const CANOPY_PERMISSION = \"CANOPY_PERMISSION\";\n","import {\n  type CanActivate,\n  type ExecutionContext,\n  ForbiddenException,\n  Inject,\n  Injectable,\n  InternalServerErrorException,\n  Logger,\n  ServiceUnavailableException,\n} from \"@nestjs/common\";\nimport { Reflector } from \"@nestjs/core\";\n\nimport {\n  isCanopyAuthorizerError,\n  isCanopyError,\n  type LocalAuthorizer,\n  type RequestBody,\n} from \"@canopy-io/node\";\n\nimport type { CanopyModuleOptions } from \"./options.js\";\nimport type { PermissionRequirement } from \"./require-permission.decorator.js\";\nimport {\n  CANOPY_AUTHORIZER,\n  CANOPY_OPTIONS,\n  CANOPY_PERMISSION,\n} from \"./tokens.js\";\n\n/** Read off the generated operation, so it follows the API rather than restating it. */\ntype EvaluateQuery = RequestBody<\"ApiPermissionsController_evaluate\">;\n\n/**\n * Only the verdict, not the API's full explain payload.\n *\n * A decision reached in-process cannot report `granting_roles` or an effective\n * node — that reasoning lives on the server. The guard has never needed it, and\n * typing the narrow thing keeps that honest rather than implying a richer\n * answer than exists.\n */\ntype Verdict = { allowed: boolean };\n\ninterface Cancellation {\n  signal: AbortSignal;\n  dispose: () => void;\n}\n\n/** The Node stream underneath an Express or Fastify response. */\ninterface ClosableResponse {\n  once: (event: string, listener: () => void) => unknown;\n  removeListener: (event: string, listener: () => void) => unknown;\n  writableEnded?: boolean;\n  raw?: ClosableResponse;\n}\n\nfunction isClosable(value: unknown): value is ClosableResponse {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as ClosableResponse).once === \"function\" &&\n    typeof (value as ClosableResponse).removeListener === \"function\"\n  );\n}\n\n/**\n * Find the Node response stream behind whatever the adapter hands back.\n *\n * `.raw` is checked first and on its own merits, because the object Nest\n * returns is not always the stream. Express returns the `ServerResponse`\n * itself, which listens; Fastify returns a `Reply`, which is a plain object\n * with the real response on `.raw`. Testing the outer object first and\n * returning early on failure would skip `.raw` in exactly the case it exists\n * for.\n */\nfunction resolveStream(response: unknown): ClosableResponse | undefined {\n  const raw = (response as { raw?: unknown } | null | undefined)?.raw;\n\n  if (isClosable(raw)) {\n    return raw;\n  }\n\n  if (isClosable(response)) {\n    return response;\n  }\n\n  return undefined;\n}\n\n/**\n * Enforces `@RequirePermission` by asking Canopy, once, per guarded request.\n *\n * The guard fails closed at every step. An unresolvable identity, a `node`\n * check with no node, a denial, or an unreachable API all end the request —\n * there is no path through this class that allows a request whose decision is\n * unknown. That is the property worth protecting when reading this code: an\n * `allow` must be something Canopy actually said.\n *\n * A route with no requirement is allowed through untouched, so the guard can be\n * applied globally and opted into per route. Registered that way it runs before\n * controller- and route-scoped guards, so whatever authenticates the request has\n * to be registered globally ahead of it — otherwise `resolveIdentity` runs\n * before there is anything to resolve and every guarded route denies.\n */\n@Injectable()\nexport class CanopyGuard implements CanActivate {\n  private readonly logger = new Logger(CanopyGuard.name);\n\n  constructor(\n    @Inject(Reflector) private readonly reflector: Reflector,\n    @Inject(CANOPY_AUTHORIZER) private readonly authorizer: LocalAuthorizer,\n    @Inject(CANOPY_OPTIONS)\n    private readonly options: CanopyModuleOptions<unknown>,\n  ) {}\n\n  async canActivate(context: ExecutionContext): Promise<boolean> {\n    const requirement = this.reflector.getAllAndOverride<\n      PermissionRequirement | undefined\n    >(CANOPY_PERMISSION, [context.getHandler(), context.getClass()]);\n\n    if (!requirement) {\n      return true;\n    }\n\n    const http = context.switchToHttp();\n    const request: unknown = http.getRequest();\n    const identityId = resolveSafely(this.options.resolveIdentity, request);\n\n    if (!identityId) {\n      throw new ForbiddenException(\n        \"No identity on the request. Canopy cannot evaluate a permission without one.\",\n      );\n    }\n\n    const decision = await this.evaluate(\n      requirement,\n      identityId,\n      request,\n      watchDisconnect(http),\n    );\n\n    if (!decision.allowed) {\n      throw new ForbiddenException(\n        `Identity does not hold ${requirement.permission}.`,\n      );\n    }\n\n    return true;\n  }\n\n  /**\n   * Asks Canopy the question the decorator recorded.\n   *\n   * Every failure is converted into a thrown exception rather than a `false`\n   * decision, so a caller cannot mistake \"we could not tell\" for \"denied by\n   * policy\" — and neither outcome lets the request proceed.\n   */\n  private async evaluate(\n    requirement: PermissionRequirement,\n    identityId: string,\n    request: unknown,\n    cancellation: Cancellation | undefined,\n  ): Promise<Verdict> {\n    const query = this.buildQuery(requirement, identityId, request);\n\n    try {\n      // Answered in-process. The authorizer holds the identity's grant roots\n      // and a shared copy of the hierarchy, so the common case reaches no\n      // network at all; only a cold or expired entry does, and its deadline\n      // and retries are bounded by the same options as before.\n      return await this.authorizer.evaluate(\n        query,\n        cancellation ? { signal: cancellation.signal } : {},\n      );\n    } catch (error) {\n      // The caller hung up mid-check. There is no one left to answer, and this\n      // is not Canopy failing — so it must not be logged or reported as though\n      // it were. Rethrowing the abort ends the request without inventing a\n      // decision.\n      if (cancellation?.signal.aborted) {\n        throw error;\n      }\n\n      // Deliberately not re-thrown as-is: a failure here must not reach the\n      // client as though Canopy had answered.\n      this.logger.error(\n        `Could not evaluate ${requirement.permission} for ${identityId}`,\n        error instanceof Error ? error.stack : String(error),\n      );\n\n      throw this.toHttpException(error);\n    } finally {\n      cancellation?.dispose();\n    }\n  }\n\n  /**\n   * Turn a failed check into the status that describes it.\n   *\n   * Every branch denies — nothing here can let a request through — but they say\n   * different things, and the difference is what makes an incident diagnosable.\n   * Reporting a rejected API key as \"temporarily unavailable\" invites a retry\n   * that will never succeed and hides a misconfiguration behind an outage.\n   */\n  private toHttpException(error: unknown): Error {\n    // The authorizer could not see far enough to decide — a credential that\n    // cannot read the hierarchy, most likely. Not an outage: no retry fixes a\n    // missing scope, and reporting it as one would bury a misconfiguration\n    // under what looks like a blip.\n    if (isCanopyAuthorizerError(error)) {\n      return new InternalServerErrorException(\n        `Authorization is misconfigured: ${error.message}`,\n      );\n    }\n\n    if (!isCanopyError(error)) {\n      // Never answered: unreachable, reset, or past the deadline.\n      return new ServiceUnavailableException(\n        \"Authorization is temporarily unavailable.\",\n      );\n    }\n\n    // Canopy rejected our own credential. No retry fixes this.\n    if (error.isAuthFailure) {\n      return new InternalServerErrorException(\n        \"Authorization is misconfigured. Check the Canopy API key and its scopes.\",\n      );\n    }\n\n    // A 404 with no error code is Nest's own \"no such route\", which here means\n    // this Canopy does not serve the endpoint the authorizer reads — an SDK\n    // newer than the API it is pointed at. Denying would be catastrophic and\n    // silent: every guarded route in the application would answer 403 with\n    // nothing to suggest the cause is a version mismatch rather than policy.\n    if (error.statusCode === 404 && error.code === null) {\n      return new InternalServerErrorException(\n        `Authorization is misconfigured: ${error.request.method} ${error.request.path} is not served by this Canopy. ` +\n          \"The SDK requires an API that exposes the identity grants endpoint.\",\n      );\n    }\n\n    // A 404 that does carry a code is a real answer — the identity is not in\n    // this Environment. Deny rather than 500, the guard's whole thesis being\n    // that an undecidable request does not proceed, but say nothing about what\n    // was missing.\n    if (error.statusCode === 404) {\n      return new ForbiddenException(\"Could not evaluate the permission.\");\n    }\n\n    if (error.isRateLimited || error.statusCode >= 500) {\n      return new ServiceUnavailableException(\n        \"Authorization is temporarily unavailable.\",\n      );\n    }\n\n    // A 4xx we did not anticipate is a malformed question — our bug, not a\n    // transient condition.\n    return new InternalServerErrorException(\n      \"Authorization could not be evaluated.\",\n    );\n  }\n\n  private buildQuery(\n    requirement: PermissionRequirement,\n    identityId: string,\n    request: unknown,\n  ): EvaluateQuery {\n    if (requirement.scope === \"app_wide\") {\n      return {\n        identity_id: identityId,\n        permission: requirement.permission,\n        scope: \"app_wide\",\n      };\n    }\n\n    const nodeId = this.options.resolveNode\n      ? resolveSafely(this.options.resolveNode, request)\n      : undefined;\n\n    if (!nodeId) {\n      throw new ForbiddenException(\n        `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.`,\n      );\n    }\n\n    return {\n      identity_id: identityId,\n      permission: requirement.permission,\n      scope: \"node\",\n      node_id: nodeId,\n    };\n  }\n}\n\n/**\n * Run a resolver, treating a throw as \"could not resolve\".\n *\n * Resolvers reach into the request — `request.user.sub` is the shape the docs\n * suggest and the one most applications write. On an unauthenticated request\n * `request.user` is undefined and that expression throws, which without this\n * would surface as a 500. An identity that cannot be established is exactly the\n * request that must be denied, so it becomes the same 403 as returning nothing.\n */\nfunction resolveSafely(\n  resolve: (request: never) => string | null | undefined,\n  request: unknown,\n): string | null | undefined {\n  try {\n    return (resolve as (request: unknown) => string | null | undefined)(\n      request,\n    );\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Abort the permission check if the caller hangs up while it is in flight.\n *\n * Watches the *response*, not the request. A request stream emits `close` on\n * every normal request once its body has been read, so listening there would\n * abort perfectly healthy checks; a response emits `close` before\n * `writableEnded` only when nothing was ever sent — which is exactly the\n * disconnect case. The `writableEnded` re-check at fire time keeps that true\n * even if the ordering differs by adapter.\n *\n * Returns undefined for a transport with no such response — a GraphQL or\n * microservice context — where the check simply runs to its deadline.\n */\nfunction watchDisconnect(http: {\n  getResponse?: () => unknown;\n}): Cancellation | undefined {\n  const raw = resolveStream(http.getResponse?.());\n\n  if (!raw) {\n    return undefined;\n  }\n\n  const controller = new AbortController();\n\n  const onClose = () => {\n    if (raw.writableEnded === true) {\n      return;\n    }\n\n    controller.abort(\n      new DOMException(\"The client closed the request\", \"AbortError\"),\n    );\n  };\n\n  raw.once(\"close\", onClose);\n\n  return {\n    signal: controller.signal,\n    dispose: () => raw.removeListener(\"close\", onClose),\n  };\n}\n","import {\n  type CanActivate,\n  type ExecutionContext,\n  Inject,\n  Injectable,\n  ServiceUnavailableException,\n  UnauthorizedException,\n} from \"@nestjs/common\";\n\nimport {\n  type CanopyTokenClaims,\n  isCanopyTokenError,\n  TokenVerifier,\n} from \"@canopy-io/node\";\n\nimport type { CanopyModuleOptions } from \"./options.js\";\nimport { CANOPY_OPTIONS, CANOPY_TOKEN_VERIFIER } from \"./tokens.js\";\n\n/**\n * Verifies the bearer token and attaches its claims to the request.\n *\n * This is the authentication half, and it is opt-in on purpose. `CanopyGuard`\n * answers \"may this identity do this?\"; something has to have established\n * *which* identity first, and `resolveIdentity` says as much — \"usually a\n * claim off the verified access token your auth layer already attached\".\n *\n * Use this guard when Canopy issues your tokens and you have no auth layer\n * yet. Skip it entirely if you already run Passport or your own JWT\n * middleware — it is additive, and nothing else in the package depends on it.\n *\n * ```ts\n * @UseGuards(CanopyTokenGuard, CanopyGuard)\n * @RequirePermission(\"documents.read\")\n * findAll() {}\n * ```\n *\n * Order matters: this must run first, because `CanopyGuard` reads what it\n * attaches. Nest runs guards left to right, so listing them in that order is\n * the whole of the wiring.\n *\n * Claims land on `request.canopyToken` by default, which is why\n * `resolveIdentity` is usually `(req) => req.canopyToken?.sub`. The property\n * is configurable so it cannot collide with a `request.user` an existing\n * middleware already owns.\n */\n@Injectable()\nexport class CanopyTokenGuard implements CanActivate {\n  constructor(\n    @Inject(CANOPY_TOKEN_VERIFIER) private readonly verifier: TokenVerifier,\n    @Inject(CANOPY_OPTIONS)\n    private readonly options: CanopyModuleOptions<unknown>,\n  ) {}\n\n  async canActivate(context: ExecutionContext): Promise<boolean> {\n    const request = context.switchToHttp().getRequest<{\n      headers?: Record<string, string | string[] | undefined>;\n      [key: string]: unknown;\n    }>();\n\n    const token = readBearerToken(request.headers?.[\"authorization\"]);\n\n    if (token === null) {\n      throw new UnauthorizedException(\n        \"Missing bearer token in the Authorization header.\",\n      );\n    }\n\n    let claims: CanopyTokenClaims;\n\n    try {\n      claims = await this.verifier.verify(token);\n    } catch (error) {\n      // Not being able to verify is not the same as failing to verify. When\n      // the key set cannot be read the caller's token may be perfectly good —\n      // we simply cannot say — so this is ours to own, exactly as the\n      // permission guard answers 503 rather than denying on an undecidable\n      // check.\n      //\n      // Reporting it as 401 would be worse than merely inaccurate: a client\n      // reads 401 as \"your token is stale\", discards a valid one and asks for\n      // another, which aims a refresh storm at the issuer that is already\n      // down. And an outage that only ever emits 4xx is invisible to anything\n      // watching 5xx.\n      if (\n        isCanopyTokenError(error) &&\n        error.code === \"token.jwks_unavailable\"\n      ) {\n        throw new ServiceUnavailableException(\n          \"Authentication is temporarily unavailable.\",\n          { cause: error },\n        );\n      }\n\n      // Every other cause is the token itself, and a 401 whatever the detail:\n      // the caller cannot fix a bad signature by being granted something. The\n      // specific code stays on the error for logs rather than going to the\n      // caller, who has no use for the difference and should not be told which\n      // check failed.\n      if (isCanopyTokenError(error)) {\n        throw new UnauthorizedException(\"Invalid or expired access token.\", {\n          cause: error,\n        });\n      }\n\n      throw error;\n    }\n\n    request[this.options.attachTokenAs ?? \"canopyToken\"] = claims;\n\n    return true;\n  }\n}\n\n/**\n * The token out of an `Authorization: Bearer …` header.\n *\n * Returns null rather than throwing so the caller owns the message. The scheme\n * is matched case-insensitively because RFC 7235 says it is case-insensitive,\n * and clients do send `bearer`.\n */\nfunction readBearerToken(header: string | string[] | undefined): string | null {\n  const value = Array.isArray(header) ? header[0] : header;\n\n  if (typeof value !== \"string\") {\n    return null;\n  }\n\n  const match = /^bearer\\s+(.+)$/i.exec(value.trim());\n\n  if (!match?.[1]) {\n    return null;\n  }\n\n  const token = match[1].trim();\n\n  return token.length > 0 ? token : null;\n}\n","import { type DynamicModule, Module, type Provider } from \"@nestjs/common\";\n\nimport { Canopy, LocalAuthorizer, TokenVerifier } from \"@canopy-io/node\";\n\nimport { CanopyGuard } from \"./canopy.guard.js\";\nimport { CanopyTokenGuard } from \"./canopy-token.guard.js\";\nimport type {\n  CanopyModuleAsyncOptions,\n  CanopyModuleOptions,\n} from \"./options.js\";\nimport {\n  CANOPY_AUTHORIZER,\n  CANOPY_CLIENT,\n  CANOPY_OPTIONS,\n  CANOPY_TOKEN_VERIFIER,\n} from \"./tokens.js\";\n\n/**\n * Wires one configured `Canopy` client and the guard that uses it into a Nest\n * application.\n *\n * ```ts\n * CanopyModule.forRoot<AuthedRequest>({\n *   apiKey: process.env.CANOPY_API_KEY,\n *   resolveIdentity: (request) => request.user?.sub,\n *   resolveNode: (request) => request.params?.orgId,\n * })\n * ```\n *\n * The client is a singleton because it holds no per-request state — it is a\n * `fetch` wrapper with credentials — so there is nothing to gain from building\n * one per request and a connection pool to lose.\n */\n\n/**\n * Per-attempt deadline for a cache miss on the request path.\n *\n * Five seconds rather than the client's 30: this call sits on the request path,\n * so its deadline is time an inbound request spends waiting. An authorization\n * service that has not answered in five seconds is not going to save the\n * request.\n */\nconst DEFAULT_EVALUATE_TIMEOUT_MS = 5_000;\n\n/**\n * Retries for a cache miss on the request path.\n *\n * One, not the client's two. A deadline bounds an attempt; this bounds how many\n * of them an inbound request can wait through. One retry still absorbs a\n * transient blip, and caps the worst case at roughly two deadlines rather than\n * three.\n */\nconst DEFAULT_EVALUATE_MAX_RETRIES = 1;\n\n/**\n * The authorizer both registration paths build.\n *\n * The guard's `evaluateTimeoutMs` / `evaluateMaxRetries` still apply, but to\n * far fewer calls: they bound a cache miss rather than every request.\n */\nfunction buildAuthorizer<TRequest>(\n  client: Canopy,\n  options: CanopyModuleOptions<TRequest>,\n): LocalAuthorizer {\n  return new LocalAuthorizer(client.client, {\n    ...(options.authorizationTtlMs === undefined\n      ? {}\n      : { ttlMs: options.authorizationTtlMs }),\n    timeoutMs: options.evaluateTimeoutMs ?? DEFAULT_EVALUATE_TIMEOUT_MS,\n    maxRetries: options.evaluateMaxRetries ?? DEFAULT_EVALUATE_MAX_RETRIES,\n  });\n}\n\n@Module({})\nexport class CanopyModule {\n  static forRoot<TRequest = unknown>(\n    options: CanopyModuleOptions<TRequest>,\n  ): DynamicModule {\n    const providers: Provider[] = [\n      { provide: CANOPY_OPTIONS, useValue: options },\n      {\n        provide: CANOPY_CLIENT,\n        useFactory: () => new Canopy(options),\n      },\n      {\n        provide: CANOPY_TOKEN_VERIFIER,\n        useFactory: () => new TokenVerifier(options.verify),\n      },\n      {\n        provide: CANOPY_AUTHORIZER,\n        useFactory: (client: Canopy) => buildAuthorizer(client, options),\n        inject: [CANOPY_CLIENT],\n      },\n      CanopyGuard,\n      CanopyTokenGuard,\n    ];\n\n    return {\n      module: CanopyModule,\n      global: options.isGlobal ?? false,\n      providers,\n      exports: [\n        CANOPY_CLIENT,\n        CANOPY_OPTIONS,\n        CANOPY_TOKEN_VERIFIER,\n        CANOPY_AUTHORIZER,\n        CanopyGuard,\n        CanopyTokenGuard,\n      ],\n    };\n  }\n\n  /**\n   * The same wiring when the API key comes from something injectable, such as\n   * `ConfigService`, rather than being available at module-definition time.\n   */\n  static forRootAsync<TRequest = unknown>(\n    options: CanopyModuleAsyncOptions<TRequest>,\n  ): DynamicModule {\n    const providers: Provider[] = [\n      {\n        provide: CANOPY_OPTIONS,\n        useFactory: options.useFactory,\n        inject: options.inject ?? [],\n      },\n      {\n        provide: CANOPY_CLIENT,\n        useFactory: (resolved: CanopyModuleOptions<TRequest>) =>\n          new Canopy(resolved),\n        inject: [CANOPY_OPTIONS],\n      },\n      {\n        provide: CANOPY_TOKEN_VERIFIER,\n        useFactory: (resolved: CanopyModuleOptions<TRequest>) =>\n          new TokenVerifier(resolved.verify),\n        inject: [CANOPY_OPTIONS],\n      },\n      {\n        provide: CANOPY_AUTHORIZER,\n        useFactory: (client: Canopy, resolved: CanopyModuleOptions<TRequest>) =>\n          buildAuthorizer(client, resolved),\n        inject: [CANOPY_CLIENT, CANOPY_OPTIONS],\n      },\n      CanopyGuard,\n      CanopyTokenGuard,\n    ];\n\n    return {\n      module: CanopyModule,\n      global: options.isGlobal ?? false,\n      // Spread rather than assigned: under exactOptionalPropertyTypes an\n      // explicit `imports: undefined` is not the same as no `imports` at all.\n      ...(options.imports ? { imports: options.imports } : {}),\n      providers,\n      exports: [\n        CANOPY_CLIENT,\n        CANOPY_OPTIONS,\n        CANOPY_TOKEN_VERIFIER,\n        CANOPY_AUTHORIZER,\n        CanopyGuard,\n        CanopyTokenGuard,\n      ],\n    };\n  }\n}\n","import { Inject } from \"@nestjs/common\";\n\nimport { CANOPY_CLIENT } from \"./tokens.js\";\n\n/**\n * Injects the configured client.\n *\n * ```ts\n * constructor(@InjectCanopy() private readonly canopy: Canopy) {}\n * ```\n *\n * Named rather than resolved by type because this package is bundled with\n * esbuild, which emits no `design:paramtypes` — so type-only injection would\n * fail at runtime with a confusing \"cannot resolve dependency\" rather than at\n * build time.\n */\nexport const InjectCanopy = (): ParameterDecorator => Inject(CANOPY_CLIENT);\n","import { SetMetadata } from \"@nestjs/common\";\n\nimport { CANOPY_PERMISSION } from \"./tokens.js\";\n\n/**\n * Which question the guard asks Canopy.\n *\n * `node` walks the node's lineage, so a role granted on an ancestor is\n * inherited at the node being touched. `app_wide` asks only whether the\n * identity holds the permission anywhere in the Environment.\n */\nexport type PermissionScope = \"node\" | \"app_wide\";\n\n/** What `@RequirePermission` records for the guard to read back. */\nexport interface PermissionRequirement {\n  readonly permission: string;\n  readonly scope: PermissionScope;\n}\n\nexport interface RequirePermissionOptions {\n  /**\n   * Defaults to `node`.\n   *\n   * `app_wide` is opt-in on purpose. It answers a coarser question and returns\n   * no effective node, which makes it right for deciding whether to render a\n   * menu item and wrong for guarding a resource that belongs to one — a\n   * distinction that is easy to get backwards if the looser check is the\n   * default.\n   */\n  readonly scope?: PermissionScope;\n}\n\n/**\n * Require a Canopy permission before a route runs.\n *\n * ```ts\n * @UseGuards(CanopyGuard)\n * @RequirePermission(\"orders.refund\")\n * @Post(\":orderId/refund\")\n * refund() {}\n * ```\n *\n * Applies to a single handler or to a whole controller; a handler's own\n * requirement wins over its controller's.\n */\nexport const RequirePermission = (\n  permission: string,\n  options: RequirePermissionOptions = {},\n): MethodDecorator & ClassDecorator =>\n  SetMetadata<string, PermissionRequirement>(CANOPY_PERMISSION, {\n    permission,\n    scope: options.scope ?? \"node\",\n  });\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canopy-io/nestjs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official NestJS integration for Canopy — hierarchical identity and access management.",
   "license": "MIT",
   "author": "Canopy Identity Inc.",
@@ -51,7 +51,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@canopy-io/node": "^0.1.0"
+    "@canopy-io/node": "^0.1.1"
   },
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",
@@ -62,6 +62,7 @@
     "@nestjs/common": "^11.1.21",
     "@nestjs/core": "^11.1.21",
     "@nestjs/platform-express": "^11.1.28",
+    "@nestjs/platform-fastify": "^11.1.28",
     "@nestjs/testing": "^11.1.21",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1"