@canopy-io/nestjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Canopy Identity Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# @canopy-io/nestjs
+
+Official NestJS integration for [Canopy](https://canopy-io.com) — hierarchical identity and access management for B2B SaaS.
+
+Turns a permission check into a decorator on the route instead of a call in every handler.
+
+## Install
+
+```bash
+npm install @canopy-io/nestjs
+```
+
+Requires NestJS 10 or 11 and Node 18 or later. `@canopy-io/node` comes with it.
+
+## Register
+
+```ts
+import { CanopyModule } from "@canopy-io/nestjs";
+
+@Module({
+  imports: [
+    CanopyModule.forRoot<AuthedRequest>({
+      apiKey: process.env.CANOPY_API_KEY,
+      resolveIdentity: (request) => request.user.sub,
+      resolveNode: (request) => request.params.orgId,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+The two resolvers are how the guard learns _who_ is asking and _where_. Where those live is your application's business — a claim on a verified token, a route parameter, a tenant on the session — so you supply them rather than the library guessing. Pass your own request type to `forRoot` and both resolvers are typed against it.
+
+When the key comes from something injectable, use `forRootAsync`:
+
+```ts
+CanopyModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    apiKey: config.getOrThrow("CANOPY_API_KEY"),
+    resolveIdentity: (request) => request.user.sub,
+    resolveNode: (request) => request.params.orgId,
+  }),
+});
+```
+
+## Guard a route
+
+```ts
+import { CanopyGuard, RequirePermission } from "@canopy-io/nestjs";
+
+@Controller("orgs/:orgId/orders")
+@UseGuards(CanopyGuard)
+export class OrdersController {
+  @Post(":orderId/refund")
+  @RequirePermission("orders.refund")
+  refund() {}
+}
+```
+
+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.
+
+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.
+
+### Scope
+
+The default is `node`, which is the strict question: does this identity hold the permission _at this node_.
+
+```ts
+@RequirePermission("reports.view", { scope: "app_wide" })
+```
+
+`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.
+
+## The client
+
+For anything the guard does not cover, inject the client:
+
+```ts
+import { InjectCanopy, type Canopy } from "@canopy-io/nestjs";
+
+@Injectable()
+export class OrdersService {
+  constructor(@InjectCanopy() private readonly canopy: Canopy) {}
+
+  async assign(identityId: string, nodeId: string, roleId: string) {
+    await this.canopy.assignments.create({
+      identity_id: identityId,
+      node_id: nodeId,
+      role_id: roleId,
+    });
+  }
+}
+```
+
+It is the same [`@canopy-io/node`](../node) client, with its retry policy, pagination and typed errors.
+
+## Failing closed
+
+There is no path through `CanopyGuard` that allows a request whose decision is unknown. Each of these ends the request:
+
+- no identity resolves — `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 unreachable case is logged with its cause before the request is refused.
+
+## License
+
+MIT © Canopy Identity Inc.

package/dist/index.cjs

@@ -0,0 +1,165 @@
+'use strict';
+
+var common = require('@nestjs/common');
+var node = require('@canopy-io/node');
+var core = require('@nestjs/core');
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/tokens.ts
+var CANOPY_OPTIONS = "CANOPY_OPTIONS";
+var CANOPY_CLIENT = "CANOPY_CLIENT";
+var CANOPY_PERMISSION = "CANOPY_PERMISSION";
+
+// src/canopy.guard.ts
+exports.CanopyGuard = class CanopyGuard {
+  constructor(reflector, canopy, options) {
+    this.reflector = reflector;
+    this.canopy = canopy;
+    this.options = options;
+  }
+  reflector;
+  canopy;
+  options;
+  logger = new common.Logger(exports.CanopyGuard.name);
+  async canActivate(context) {
+    const requirement = this.reflector.getAllAndOverride(CANOPY_PERMISSION, [context.getHandler(), context.getClass()]);
+    if (!requirement) {
+      return true;
+    }
+    const request = context.switchToHttp().getRequest();
+    const identityId = 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);
+    if (!decision.allowed) {
+      throw new common.ForbiddenException(
+        `Identity does not hold ${requirement.permission}.`
+      );
+    }
+    return true;
+  }
+  /**
+   * Asks Canopy the question the decorator recorded.
+   *
+   * Every failure is converted into a thrown exception rather than a `false`
+   * 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) {
+    const query = this.buildQuery(requirement, identityId, request);
+    try {
+      return await this.canopy.permissions.evaluate(query);
+    } catch (error) {
+      this.logger.error(
+        `Could not evaluate ${requirement.permission} for ${identityId}`,
+        error instanceof Error ? error.stack : String(error)
+      );
+      throw new common.ServiceUnavailableException(
+        "Authorization is temporarily unavailable."
+      );
+    }
+  }
+  buildQuery(requirement, identityId, request) {
+    if (requirement.scope === "app_wide") {
+      return {
+        identity_id: identityId,
+        permission: requirement.permission,
+        scope: "app_wide"
+      };
+    }
+    const nodeId = this.options.resolveNode?.(request);
+    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.`
+      );
+    }
+    return {
+      identity_id: identityId,
+      permission: requirement.permission,
+      scope: "node",
+      node_id: nodeId
+    };
+  }
+};
+exports.CanopyGuard = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(core.Reflector)),
+  __decorateParam(1, common.Inject(CANOPY_CLIENT)),
+  __decorateParam(2, common.Inject(CANOPY_OPTIONS))
+], exports.CanopyGuard);
+
+// src/canopy.module.ts
+exports.CanopyModule = class CanopyModule {
+  static forRoot(options) {
+    const providers = [
+      { provide: CANOPY_OPTIONS, useValue: options },
+      {
+        provide: CANOPY_CLIENT,
+        useFactory: () => new node.Canopy(options)
+      },
+      exports.CanopyGuard
+    ];
+    return {
+      module: exports.CanopyModule,
+      global: options.isGlobal ?? false,
+      providers,
+      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, exports.CanopyGuard]
+    };
+  }
+  /**
+   * The same wiring when the API key comes from something injectable, such as
+   * `ConfigService`, rather than being available at module-definition time.
+   */
+  static forRootAsync(options) {
+    const providers = [
+      {
+        provide: CANOPY_OPTIONS,
+        useFactory: options.useFactory,
+        inject: options.inject ?? []
+      },
+      {
+        provide: CANOPY_CLIENT,
+        useFactory: (resolved) => new node.Canopy(resolved),
+        inject: [CANOPY_OPTIONS]
+      },
+      exports.CanopyGuard
+    ];
+    return {
+      module: exports.CanopyModule,
+      global: options.isGlobal ?? false,
+      // Spread rather than assigned: under exactOptionalPropertyTypes an
+      // 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.CanopyModule = __decorateClass([
+  common.Module({})
+], exports.CanopyModule);
+var InjectCanopy = () => common.Inject(CANOPY_CLIENT);
+var RequirePermission = (permission, options = {}) => common.SetMetadata(CANOPY_PERMISSION, {
+  permission,
+  scope: options.scope ?? "node"
+});
+
+exports.CANOPY_CLIENT = CANOPY_CLIENT;
+exports.CANOPY_OPTIONS = CANOPY_OPTIONS;
+exports.CANOPY_PERMISSION = CANOPY_PERMISSION;
+exports.InjectCanopy = InjectCanopy;
+exports.RequirePermission = RequirePermission;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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":["CanopyGuard","Logger","ForbiddenException","ServiceUnavailableException","Injectable","Reflector","CanopyModule","Canopy","Module","Inject","SetMetadata"],"mappings":"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","file":"index.cjs","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"]}

package/dist/index.d.cts

@@ -0,0 +1,180 @@
+import { ModuleMetadata, InjectionToken, DynamicModule, CanActivate, ExecutionContext } from '@nestjs/common';
+import { CanopyClientOptions, Canopy } from '@canopy-io/node';
+export { Canopy } from '@canopy-io/node';
+import { Reflector } from '@nestjs/core';
+
+/**
+ * Pulls a value out of the incoming request.
+ *
+ * Returning nothing is a denial, not an error — see `CanopyGuard`. That is
+ * deliberate: a request whose identity cannot be established is exactly the
+ * request that must not be allowed through.
+ *
+ * `TRequest` is a parameter rather than a fixed type because Nest runs on
+ * Express and Fastify, and because the interesting fields — `request.user`,
+ * a tenant on the session — are put there by the application's own middleware.
+ * Pass your request type to `CanopyModule.forRoot<AuthedRequest>(...)` and
+ * these resolvers are typed against it.
+ */
+type RequestResolver<TRequest> = (request: TRequest) => string | null | undefined;
+/**
+ * How the guard turns a request into an authorization question.
+ *
+ * Everything `CanopyClientOptions` accepts is accepted here too, so the client
+ * is configured in the same place as the guard rather than in two.
+ */
+interface CanopyModuleOptions<TRequest = unknown> extends CanopyClientOptions {
+    /**
+     * Which identity the request is acting as — usually a claim off the verified
+     * access token your auth layer already attached.
+     */
+    resolveIdentity: RequestResolver<TRequest>;
+    /**
+     * Which hierarchy node the request is touching, for the default `node`
+     * scope. Omit it only if every guarded route uses `scope: "app_wide"`;
+     * a `node` check with no node resolves to a denial.
+     */
+    resolveNode?: RequestResolver<TRequest>;
+    /**
+     * Register the module globally so feature modules need not import it.
+     * Defaults to false, matching `@nestjs/config`.
+     */
+    isGlobal?: boolean;
+}
+/**
+ * The same options, produced by a factory — for when the API key lives behind
+ * something injectable such as `ConfigService`.
+ *
+ * Extends `Pick<ModuleMetadata, "imports">` rather than restating the type,
+ * which is how Nest's own `*AsyncOptions` are declared.
+ */
+interface CanopyModuleAsyncOptions<TRequest = unknown> extends Pick<ModuleMetadata, "imports"> {
+    inject?: InjectionToken[];
+    useFactory: (...args: never[]) => Promise<CanopyModuleOptions<TRequest>> | CanopyModuleOptions<TRequest>;
+    isGlobal?: boolean;
+}
+
+/**
+ * Wires one configured `Canopy` client and the guard that uses it into a Nest
+ * application.
+ *
+ * ```ts
+ * CanopyModule.forRoot<AuthedRequest>({
+ *   apiKey: process.env.CANOPY_API_KEY,
+ *   resolveIdentity: (request) => request.user.sub,
+ *   resolveNode: (request) => request.params.orgId,
+ * })
+ * ```
+ *
+ * The client is a singleton because it holds no per-request state — it is a
+ * `fetch` wrapper with credentials — so there is nothing to gain from building
+ * one per request and a connection pool to lose.
+ */
+declare class CanopyModule {
+    static forRoot<TRequest = unknown>(options: CanopyModuleOptions<TRequest>): DynamicModule;
+    /**
+     * The same wiring when the API key comes from something injectable, such as
+     * `ConfigService`, rather than being available at module-definition time.
+     */
+    static forRootAsync<TRequest = unknown>(options: CanopyModuleAsyncOptions<TRequest>): DynamicModule;
+}
+
+/**
+ * Enforces `@RequirePermission` by asking Canopy, once, per guarded request.
+ *
+ * The guard fails closed at every step. An unresolvable identity, a `node`
+ * check with no node, a denial, or an unreachable API all end the request —
+ * there is no path through this class that allows a request whose decision is
+ * unknown. That is the property worth protecting when reading this code: an
+ * `allow` must be something Canopy actually said.
+ *
+ * A route with no requirement is allowed through untouched, so the guard is
+ * safe to apply globally and opt into per route.
+ */
+declare class CanopyGuard implements CanActivate {
+    private readonly reflector;
+    private readonly canopy;
+    private readonly options;
+    private readonly logger;
+    constructor(reflector: Reflector, canopy: Canopy, options: CanopyModuleOptions<unknown>);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Asks Canopy the question the decorator recorded.
+     *
+     * Every failure is converted into a thrown exception rather than a `false`
+     * decision, so a caller cannot mistake "we could not tell" for "denied by
+     * policy" — and neither outcome lets the request proceed.
+     */
+    private evaluate;
+    private buildQuery;
+}
+
+/**
+ * Injects the configured client.
+ *
+ * ```ts
+ * constructor(@InjectCanopy() private readonly canopy: Canopy) {}
+ * ```
+ *
+ * Named rather than resolved by type because this package is bundled with
+ * esbuild, which emits no `design:paramtypes` — so type-only injection would
+ * fail at runtime with a confusing "cannot resolve dependency" rather than at
+ * build time.
+ */
+declare const InjectCanopy: () => ParameterDecorator;
+
+/**
+ * Which question the guard asks Canopy.
+ *
+ * `node` walks the node's lineage, so a role granted on an ancestor is
+ * inherited at the node being touched. `app_wide` asks only whether the
+ * identity holds the permission anywhere in the Environment.
+ */
+type PermissionScope = "node" | "app_wide";
+/** What `@RequirePermission` records for the guard to read back. */
+interface PermissionRequirement {
+    readonly permission: string;
+    readonly scope: PermissionScope;
+}
+interface RequirePermissionOptions {
+    /**
+     * Defaults to `node`.
+     *
+     * `app_wide` is opt-in on purpose. It answers a coarser question and returns
+     * no effective node, which makes it right for deciding whether to render a
+     * menu item and wrong for guarding a resource that belongs to one — a
+     * distinction that is easy to get backwards if the looser check is the
+     * default.
+     */
+    readonly scope?: PermissionScope;
+}
+/**
+ * Require a Canopy permission before a route runs.
+ *
+ * ```ts
+ * @UseGuards(CanopyGuard)
+ * @RequirePermission("orders.refund")
+ * @Post(":orderId/refund")
+ * refund() {}
+ * ```
+ *
+ * Applies to a single handler or to a whole controller; a handler's own
+ * requirement wins over its controller's.
+ */
+declare const RequirePermission: (permission: string, options?: RequirePermissionOptions) => MethodDecorator & ClassDecorator;
+
+/**
+ * Injection tokens.
+ *
+ * These are strings rather than classes because esbuild does not emit
+ * `design:paramtypes`, so nothing here can be injected by constructor type
+ * alone — every dependency is named with an explicit `@Inject`.
+ */
+/** The resolved `CanopyModuleOptions`. */
+declare const CANOPY_OPTIONS = "CANOPY_OPTIONS";
+/** The configured `Canopy` client. */
+declare const CANOPY_CLIENT = "CANOPY_CLIENT";
+/** Metadata key holding what `@RequirePermission` recorded on a handler. */
+declare const CANOPY_PERMISSION = "CANOPY_PERMISSION";
+
+export { CANOPY_CLIENT, CANOPY_OPTIONS, CANOPY_PERMISSION, CanopyGuard, CanopyModule, type CanopyModuleAsyncOptions, type CanopyModuleOptions, InjectCanopy, type PermissionRequirement, type PermissionScope, type RequestResolver, RequirePermission, type RequirePermissionOptions };

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+import { ModuleMetadata, InjectionToken, DynamicModule, CanActivate, ExecutionContext } from '@nestjs/common';
+import { CanopyClientOptions, Canopy } from '@canopy-io/node';
+export { Canopy } from '@canopy-io/node';
+import { Reflector } from '@nestjs/core';
+
+/**
+ * Pulls a value out of the incoming request.
+ *
+ * Returning nothing is a denial, not an error — see `CanopyGuard`. That is
+ * deliberate: a request whose identity cannot be established is exactly the
+ * request that must not be allowed through.
+ *
+ * `TRequest` is a parameter rather than a fixed type because Nest runs on
+ * Express and Fastify, and because the interesting fields — `request.user`,
+ * a tenant on the session — are put there by the application's own middleware.
+ * Pass your request type to `CanopyModule.forRoot<AuthedRequest>(...)` and
+ * these resolvers are typed against it.
+ */
+type RequestResolver<TRequest> = (request: TRequest) => string | null | undefined;
+/**
+ * How the guard turns a request into an authorization question.
+ *
+ * Everything `CanopyClientOptions` accepts is accepted here too, so the client
+ * is configured in the same place as the guard rather than in two.
+ */
+interface CanopyModuleOptions<TRequest = unknown> extends CanopyClientOptions {
+    /**
+     * Which identity the request is acting as — usually a claim off the verified
+     * access token your auth layer already attached.
+     */
+    resolveIdentity: RequestResolver<TRequest>;
+    /**
+     * Which hierarchy node the request is touching, for the default `node`
+     * scope. Omit it only if every guarded route uses `scope: "app_wide"`;
+     * a `node` check with no node resolves to a denial.
+     */
+    resolveNode?: RequestResolver<TRequest>;
+    /**
+     * Register the module globally so feature modules need not import it.
+     * Defaults to false, matching `@nestjs/config`.
+     */
+    isGlobal?: boolean;
+}
+/**
+ * The same options, produced by a factory — for when the API key lives behind
+ * something injectable such as `ConfigService`.
+ *
+ * Extends `Pick<ModuleMetadata, "imports">` rather than restating the type,
+ * which is how Nest's own `*AsyncOptions` are declared.
+ */
+interface CanopyModuleAsyncOptions<TRequest = unknown> extends Pick<ModuleMetadata, "imports"> {
+    inject?: InjectionToken[];
+    useFactory: (...args: never[]) => Promise<CanopyModuleOptions<TRequest>> | CanopyModuleOptions<TRequest>;
+    isGlobal?: boolean;
+}
+
+/**
+ * Wires one configured `Canopy` client and the guard that uses it into a Nest
+ * application.
+ *
+ * ```ts
+ * CanopyModule.forRoot<AuthedRequest>({
+ *   apiKey: process.env.CANOPY_API_KEY,
+ *   resolveIdentity: (request) => request.user.sub,
+ *   resolveNode: (request) => request.params.orgId,
+ * })
+ * ```
+ *
+ * The client is a singleton because it holds no per-request state — it is a
+ * `fetch` wrapper with credentials — so there is nothing to gain from building
+ * one per request and a connection pool to lose.
+ */
+declare class CanopyModule {
+    static forRoot<TRequest = unknown>(options: CanopyModuleOptions<TRequest>): DynamicModule;
+    /**
+     * The same wiring when the API key comes from something injectable, such as
+     * `ConfigService`, rather than being available at module-definition time.
+     */
+    static forRootAsync<TRequest = unknown>(options: CanopyModuleAsyncOptions<TRequest>): DynamicModule;
+}
+
+/**
+ * Enforces `@RequirePermission` by asking Canopy, once, per guarded request.
+ *
+ * The guard fails closed at every step. An unresolvable identity, a `node`
+ * check with no node, a denial, or an unreachable API all end the request —
+ * there is no path through this class that allows a request whose decision is
+ * unknown. That is the property worth protecting when reading this code: an
+ * `allow` must be something Canopy actually said.
+ *
+ * A route with no requirement is allowed through untouched, so the guard is
+ * safe to apply globally and opt into per route.
+ */
+declare class CanopyGuard implements CanActivate {
+    private readonly reflector;
+    private readonly canopy;
+    private readonly options;
+    private readonly logger;
+    constructor(reflector: Reflector, canopy: Canopy, options: CanopyModuleOptions<unknown>);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Asks Canopy the question the decorator recorded.
+     *
+     * Every failure is converted into a thrown exception rather than a `false`
+     * decision, so a caller cannot mistake "we could not tell" for "denied by
+     * policy" — and neither outcome lets the request proceed.
+     */
+    private evaluate;
+    private buildQuery;
+}
+
+/**
+ * Injects the configured client.
+ *
+ * ```ts
+ * constructor(@InjectCanopy() private readonly canopy: Canopy) {}
+ * ```
+ *
+ * Named rather than resolved by type because this package is bundled with
+ * esbuild, which emits no `design:paramtypes` — so type-only injection would
+ * fail at runtime with a confusing "cannot resolve dependency" rather than at
+ * build time.
+ */
+declare const InjectCanopy: () => ParameterDecorator;
+
+/**
+ * Which question the guard asks Canopy.
+ *
+ * `node` walks the node's lineage, so a role granted on an ancestor is
+ * inherited at the node being touched. `app_wide` asks only whether the
+ * identity holds the permission anywhere in the Environment.
+ */
+type PermissionScope = "node" | "app_wide";
+/** What `@RequirePermission` records for the guard to read back. */
+interface PermissionRequirement {
+    readonly permission: string;
+    readonly scope: PermissionScope;
+}
+interface RequirePermissionOptions {
+    /**
+     * Defaults to `node`.
+     *
+     * `app_wide` is opt-in on purpose. It answers a coarser question and returns
+     * no effective node, which makes it right for deciding whether to render a
+     * menu item and wrong for guarding a resource that belongs to one — a
+     * distinction that is easy to get backwards if the looser check is the
+     * default.
+     */
+    readonly scope?: PermissionScope;
+}
+/**
+ * Require a Canopy permission before a route runs.
+ *
+ * ```ts
+ * @UseGuards(CanopyGuard)
+ * @RequirePermission("orders.refund")
+ * @Post(":orderId/refund")
+ * refund() {}
+ * ```
+ *
+ * Applies to a single handler or to a whole controller; a handler's own
+ * requirement wins over its controller's.
+ */
+declare const RequirePermission: (permission: string, options?: RequirePermissionOptions) => MethodDecorator & ClassDecorator;
+
+/**
+ * Injection tokens.
+ *
+ * These are strings rather than classes because esbuild does not emit
+ * `design:paramtypes`, so nothing here can be injected by constructor type
+ * alone — every dependency is named with an explicit `@Inject`.
+ */
+/** The resolved `CanopyModuleOptions`. */
+declare const CANOPY_OPTIONS = "CANOPY_OPTIONS";
+/** The configured `Canopy` client. */
+declare const CANOPY_CLIENT = "CANOPY_CLIENT";
+/** Metadata key holding what `@RequirePermission` recorded on a handler. */
+declare const CANOPY_PERMISSION = "CANOPY_PERMISSION";
+
+export { CANOPY_CLIENT, CANOPY_OPTIONS, CANOPY_PERMISSION, CanopyGuard, CanopyModule, type CanopyModuleAsyncOptions, type CanopyModuleOptions, InjectCanopy, type PermissionRequirement, type PermissionScope, type RequestResolver, RequirePermission, type RequirePermissionOptions };

package/dist/index.js

@@ -0,0 +1,159 @@
+import { Injectable, Inject, Module, Logger, ForbiddenException, ServiceUnavailableException, SetMetadata } from '@nestjs/common';
+import { Canopy } from '@canopy-io/node';
+import { Reflector } from '@nestjs/core';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/tokens.ts
+var CANOPY_OPTIONS = "CANOPY_OPTIONS";
+var CANOPY_CLIENT = "CANOPY_CLIENT";
+var CANOPY_PERMISSION = "CANOPY_PERMISSION";
+
+// src/canopy.guard.ts
+var CanopyGuard = class {
+  constructor(reflector, canopy, options) {
+    this.reflector = reflector;
+    this.canopy = canopy;
+    this.options = options;
+  }
+  reflector;
+  canopy;
+  options;
+  logger = new Logger(CanopyGuard.name);
+  async canActivate(context) {
+    const requirement = this.reflector.getAllAndOverride(CANOPY_PERMISSION, [context.getHandler(), context.getClass()]);
+    if (!requirement) {
+      return true;
+    }
+    const request = context.switchToHttp().getRequest();
+    const identityId = 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);
+    if (!decision.allowed) {
+      throw new ForbiddenException(
+        `Identity does not hold ${requirement.permission}.`
+      );
+    }
+    return true;
+  }
+  /**
+   * Asks Canopy the question the decorator recorded.
+   *
+   * Every failure is converted into a thrown exception rather than a `false`
+   * 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) {
+    const query = this.buildQuery(requirement, identityId, request);
+    try {
+      return await this.canopy.permissions.evaluate(query);
+    } catch (error) {
+      this.logger.error(
+        `Could not evaluate ${requirement.permission} for ${identityId}`,
+        error instanceof Error ? error.stack : String(error)
+      );
+      throw new ServiceUnavailableException(
+        "Authorization is temporarily unavailable."
+      );
+    }
+  }
+  buildQuery(requirement, identityId, request) {
+    if (requirement.scope === "app_wide") {
+      return {
+        identity_id: identityId,
+        permission: requirement.permission,
+        scope: "app_wide"
+      };
+    }
+    const nodeId = this.options.resolveNode?.(request);
+    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.`
+      );
+    }
+    return {
+      identity_id: identityId,
+      permission: requirement.permission,
+      scope: "node",
+      node_id: nodeId
+    };
+  }
+};
+CanopyGuard = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(Reflector)),
+  __decorateParam(1, Inject(CANOPY_CLIENT)),
+  __decorateParam(2, Inject(CANOPY_OPTIONS))
+], CanopyGuard);
+
+// src/canopy.module.ts
+var CanopyModule = class {
+  static forRoot(options) {
+    const providers = [
+      { provide: CANOPY_OPTIONS, useValue: options },
+      {
+        provide: CANOPY_CLIENT,
+        useFactory: () => new Canopy(options)
+      },
+      CanopyGuard
+    ];
+    return {
+      module: CanopyModule,
+      global: options.isGlobal ?? false,
+      providers,
+      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, CanopyGuard]
+    };
+  }
+  /**
+   * The same wiring when the API key comes from something injectable, such as
+   * `ConfigService`, rather than being available at module-definition time.
+   */
+  static forRootAsync(options) {
+    const providers = [
+      {
+        provide: CANOPY_OPTIONS,
+        useFactory: options.useFactory,
+        inject: options.inject ?? []
+      },
+      {
+        provide: CANOPY_CLIENT,
+        useFactory: (resolved) => new Canopy(resolved),
+        inject: [CANOPY_OPTIONS]
+      },
+      CanopyGuard
+    ];
+    return {
+      module: CanopyModule,
+      global: options.isGlobal ?? false,
+      // Spread rather than assigned: under exactOptionalPropertyTypes an
+      // explicit `imports: undefined` is not the same as no `imports` at all.
+      ...options.imports ? { imports: options.imports } : {},
+      providers,
+      exports: [CANOPY_CLIENT, CANOPY_OPTIONS, CanopyGuard]
+    };
+  }
+};
+CanopyModule = __decorateClass([
+  Module({})
+], CanopyModule);
+var InjectCanopy = () => Inject(CANOPY_CLIENT);
+var RequirePermission = (permission, options = {}) => SetMetadata(CANOPY_PERMISSION, {
+  permission,
+  scope: options.scope ?? "node"
+});
+
+export { CANOPY_CLIENT, CANOPY_OPTIONS, CANOPY_PERMISSION, CanopyGuard, CanopyModule, InjectCanopy, RequirePermission };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@canopy-io/nestjs",
+  "version": "0.1.0",
+  "description": "Official NestJS integration for Canopy — hierarchical identity and access management.",
+  "license": "MIT",
+  "author": "Canopy Identity Inc.",
+  "homepage": "https://github.com/canopy-identity/canopy-javascript#readme",
+  "bugs": "https://github.com/canopy-identity/canopy-javascript/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/canopy-identity/canopy-javascript.git",
+    "directory": "packages/nestjs"
+  },
+  "keywords": [
+    "canopy",
+    "nestjs",
+    "authorization",
+    "rbac",
+    "iam",
+    "permissions",
+    "guard"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@canopy-io/node": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.21",
+    "@nestjs/core": "^11.1.21",
+    "@nestjs/platform-express": "^11.1.28",
+    "@nestjs/testing": "^11.1.21",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1"
+  }
+}