@blimu/nestjs 1.1.0 → 1.1.3

package/dist/modules/blimu.module.cjs

@@ -0,0 +1,413 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+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 = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/modules/blimu.module.ts
+var blimu_module_exports = {};
+__export(blimu_module_exports, {
+  BlimuModule: () => BlimuModule
+});
+module.exports = __toCommonJS(blimu_module_exports);
+var import_common4 = require("@nestjs/common");
+
+// src/config/blimu.config.ts
+var BLIMU_CONFIG = /* @__PURE__ */ Symbol("BLIMU_CONFIG");
+
+// src/guards/entitlement.guard.ts
+var import_common2 = require("@nestjs/common");
+var import_reflect_metadata = require("reflect-metadata");
+
+// src/exceptions/blimu-forbidden.exception.ts
+var import_common = require("@nestjs/common");
+var BlimuForbiddenException = class _BlimuForbiddenException extends import_common.ForbiddenException {
+  /**
+   * The entitlement check result containing detailed failure information
+   */
+  entitlementResult;
+  /**
+   * The entitlement key that was checked
+   */
+  entitlementKey;
+  /**
+   * The resource ID that was checked
+   */
+  resourceId;
+  /**
+   * The user ID that was checked
+   */
+  userId;
+  constructor(entitlementResult, entitlementKey, resourceId, userId) {
+    const message = _BlimuForbiddenException.buildMessage(entitlementResult, entitlementKey);
+    super({
+      message,
+      entitlementResult,
+      entitlementKey,
+      resourceId,
+      userId
+    });
+    this.entitlementResult = entitlementResult;
+    this.entitlementKey = entitlementKey;
+    this.resourceId = resourceId;
+    this.userId = userId;
+  }
+  /**
+   * Builds a user-friendly error message from the entitlement check result
+   */
+  static buildMessage(result, entitlementKey) {
+    const reasons = [];
+    if (result.roles && !result.roles.allowed) {
+      reasons.push(
+        `Insufficient roles. Required: ${result.roles.allowedRoles?.join(", ") || "unknown"}. User has: ${result.roles.userRoles?.join(", ") || "none"}.`
+      );
+    }
+    if (result.plans && !result.plans.allowed) {
+      reasons.push(
+        `Plan restriction. Required plans: ${result.plans.allowedPlans?.join(", ") || "unknown"}. Current plan: ${result.plans.plan || "none"}.`
+      );
+    }
+    if (result.limit && !result.limit.allowed) {
+      reasons.push(`Usage limit exceeded. ${result.limit.reason || "Limit has been reached"}.`);
+    }
+    if (reasons.length === 0) {
+      return `Access denied for entitlement: ${entitlementKey}`;
+    }
+    return `Access denied for entitlement "${entitlementKey}": ${reasons.join(" ")}`;
+  }
+};
+
+// src/guards/entitlement.guard.ts
+var import_backend = require("@blimu/backend");
+var ENTITLEMENT_METADATA_KEY = /* @__PURE__ */ Symbol("entitlement");
+var EntitlementGuard = class {
+  constructor(config, runtime) {
+    this.config = config;
+    this.runtime = runtime;
+  }
+  async canActivate(context) {
+    const request = context.switchToHttp().getRequest();
+    const handler = context.getHandler();
+    const metadata = Reflect.getMetadata(ENTITLEMENT_METADATA_KEY, handler);
+    if (!metadata) {
+      return true;
+    }
+    let userId;
+    try {
+      userId = await this.config.getUserId(request);
+    } catch {
+      throw new import_common2.ForbiddenException("Failed to extract user ID from request");
+    }
+    if (!userId) {
+      throw new import_common2.ForbiddenException("User ID is required for entitlement check");
+    }
+    const entitlementInfo = await metadata.getEntitlementInfo(request);
+    if (!entitlementInfo?.resourceId) {
+      throw new import_common2.ForbiddenException("Resource ID is required for entitlement check");
+    }
+    try {
+      const result = await this.runtime.entitlements.checkEntitlement({
+        userId,
+        entitlement: metadata.entitlementKey,
+        resourceId: entitlementInfo.resourceId,
+        ...entitlementInfo.amount !== void 0 ? { amount: entitlementInfo.amount } : {}
+      });
+      if (!result.allowed) {
+        throw new BlimuForbiddenException(
+          result,
+          metadata.entitlementKey,
+          entitlementInfo.resourceId,
+          userId
+        );
+      }
+      return true;
+    } catch (error) {
+      if (error instanceof BlimuForbiddenException || error instanceof import_common2.ForbiddenException) {
+        throw error;
+      }
+      console.error("Entitlement check failed:", error);
+      throw new import_common2.ForbiddenException("Failed to verify entitlements");
+    }
+  }
+};
+EntitlementGuard = __decorateClass([
+  (0, import_common2.Injectable)(),
+  __decorateParam(0, (0, import_common2.Inject)(BLIMU_CONFIG)),
+  __decorateParam(1, (0, import_common2.Inject)(import_backend.Blimu))
+], EntitlementGuard);
+
+// src/services/jwk.service.ts
+var import_common3 = require("@nestjs/common");
+var import_backend2 = require("@blimu/backend");
+var JWKService = class {
+  constructor(config) {
+    this.config = config;
+    this.tokenVerifier = new import_backend2.TokenVerifier({
+      runtimeApiUrl: this.config.baseURL
+    });
+  }
+  logger = new import_common3.Logger(JWKService.name);
+  tokenVerifier;
+  /**
+   * Verify JWT token using JWKs from runtime-api
+   */
+  async verifyToken(token) {
+    try {
+      this.logger.debug(
+        `\u{1F50D} Verifying token. Runtime API URL: ${this.config.baseURL}, API Key prefix: ${this.config.apiKey?.substring(0, 10)}...`
+      );
+      const result = await this.tokenVerifier.verifyToken({
+        secretKey: this.config.apiKey,
+        token,
+        runtimeApiUrl: this.config.baseURL
+      });
+      this.logger.debug(`\u2705 Token verified successfully`);
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(`\u274C Token verification failed: ${errorMessage}`);
+      if (error instanceof Error && error.stack) {
+        this.logger.error(`Stack trace: ${error.stack}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Clear cache (useful for testing or key rotation)
+   */
+  clearCache() {
+    this.tokenVerifier.clearCache(this.config.apiKey);
+    this.logger.debug("JWK cache cleared");
+  }
+};
+JWKService = __decorateClass([
+  (0, import_common3.Injectable)(),
+  __decorateParam(0, (0, import_common3.Inject)(BLIMU_CONFIG))
+], JWKService);
+
+// src/modules/blimu.module.ts
+var import_backend3 = require("@blimu/backend");
+var DEFAULT_BASE_URL = "https://api.blimu.dev";
+var BlimuModule = class {
+  /**
+   * Configure the Blimu module with static configuration
+   *
+   * @param config - The Blimu configuration object
+   * @returns A configured dynamic module
+   *
+   * @example
+   * Basic usage with default Request type:
+   * ```typescript
+   * @Module({
+   *   imports: [
+   *     BlimuModule.forRoot({
+   *       apiKey: 'your-api-secret-key',
+   *       baseURL: 'https://api.blimu.dev', // optional
+   *       environmentId: 'your-environment-id', // optional
+   *       timeoutMs: 30000, // optional
+   *       getUserId: (req) => req.user?.id, // required
+   *     }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * ```
+   *
+   * @example
+   * Usage with custom request type:
+   * ```typescript
+   * interface AuthenticatedRequest {
+   *   user: { id: string; email: string };
+   * }
+   *
+   * @Module({
+   *   imports: [
+   *     BlimuModule.forRoot<AuthenticatedRequest>({
+   *       apiKey: 'your-api-secret-key',
+   *       getUserId: (req) => req.user.id, // req is typed as AuthenticatedRequest
+   *     }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forRoot(config) {
+    return {
+      ...config.global ? { global: true } : {},
+      module: BlimuModule,
+      providers: [
+        // Register factory providers first so dependencies are available
+        {
+          provide: BLIMU_CONFIG,
+          useValue: {
+            apiKey: config.apiKey,
+            baseURL: config.baseURL ?? DEFAULT_BASE_URL,
+            environmentId: config.environmentId,
+            timeoutMs: config.timeoutMs ?? 3e4,
+            getUserId: config.getUserId
+          }
+        },
+        {
+          provide: import_backend3.Blimu,
+          useFactory: (config2) => {
+            return new import_backend3.Blimu({
+              apiKey: config2.apiKey,
+              baseURL: config2.baseURL ?? DEFAULT_BASE_URL,
+              timeoutMs: config2.timeoutMs ?? 3e4
+            });
+          },
+          inject: [BLIMU_CONFIG]
+        },
+        // Register class providers after their dependencies are available
+        EntitlementGuard,
+        JWKService
+      ],
+      exports: [EntitlementGuard, import_backend3.Blimu, BLIMU_CONFIG, JWKService]
+    };
+  }
+  /**
+   * Configure the Blimu module with async configuration
+   *
+   * This is useful when you need to load configuration from environment variables,
+   * configuration services, or other async sources.
+   *
+   * @param options - Async configuration options
+   * @returns A configured dynamic module
+   *
+   * @example
+   * Using with ConfigService:
+   * ```typescript
+   * @Module({
+   *   imports: [
+   *     ConfigModule.forRoot(),
+   *     BlimuModule.forRootAsync({
+   *       useFactory: (configService: ConfigService) => ({
+   *         apiKey: configService.get('BLIMU_API_SECRET_KEY'),
+   *         baseURL: configService.get('BLIMU_BASE_URL'),
+   *         environmentId: configService.get('BLIMU_ENVIRONMENT_ID'),
+   *         timeoutMs: configService.get('BLIMU_TIMEOUT_MS'),
+   *         getUserId: (req) => req.user?.id,
+   *       }),
+   *       inject: [ConfigService],
+   *     }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * ```
+   *
+   * @example
+   * Using with custom request type:
+   * ```typescript
+   * interface AuthenticatedRequest {
+   *   user: { id: string; email: string };
+   * }
+   *
+   * @Module({
+   *   imports: [
+   *     BlimuModule.forRootAsync<AuthenticatedRequest>({
+   *       useFactory: (configService: ConfigService) => ({
+   *         apiKey: configService.get('BLIMU_API_SECRET_KEY'),
+   *         getUserId: (req) => req.user.id, // req is typed as AuthenticatedRequest
+   *       }),
+   *       inject: [ConfigService],
+   *     }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * ```
+   *
+   * @example
+   * Using with custom provider:
+   * ```typescript
+   * @Module({
+   *   imports: [
+   *     BlimuModule.forRootAsync({
+   *       imports: [MyConfigModule],
+   *       useFactory: async (myConfigService: MyConfigService) => {
+   *         const config = await myConfigService.getBlimuConfig();
+   *         return {
+   *           apiKey: config.apiKey,
+   *           baseURL: config.baseUrl,
+   *           environmentId: config.environmentId,
+   *           getUserId: (req) => req.user?.id,
+   *         };
+   *       },
+   *       inject: [MyConfigService],
+   *     }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forRootAsync(options) {
+    const additionalImports = options.imports ?? [];
+    const module2 = {
+      ...options.global ? { global: true } : {},
+      module: BlimuModule,
+      imports: [...additionalImports],
+      providers: [
+        // Register factory providers first so dependencies are available
+        {
+          provide: BLIMU_CONFIG,
+          useFactory: async (...args) => {
+            const configResult = options.useFactory(...args);
+            const config = configResult instanceof Promise ? await configResult : configResult;
+            return {
+              apiKey: config.apiKey,
+              baseURL: config.baseURL ?? DEFAULT_BASE_URL,
+              environmentId: config.environmentId,
+              timeoutMs: config.timeoutMs ?? 3e4,
+              getUserId: config.getUserId
+            };
+          },
+          ...options.inject ? { inject: options.inject } : {}
+        },
+        {
+          provide: import_backend3.Blimu,
+          useFactory: (config) => {
+            return new import_backend3.Blimu({
+              apiKey: config.apiKey,
+              baseURL: config.baseURL ?? DEFAULT_BASE_URL,
+              timeoutMs: config.timeoutMs ?? 3e4
+            });
+          },
+          inject: [BLIMU_CONFIG]
+        },
+        // Register class providers after their dependencies are available
+        EntitlementGuard,
+        JWKService
+      ],
+      exports: [EntitlementGuard, import_backend3.Blimu, BLIMU_CONFIG, JWKService]
+    };
+    return module2;
+  }
+};
+BlimuModule = __decorateClass([
+  (0, import_common4.Module)({})
+], BlimuModule);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BlimuModule
+});
+//# sourceMappingURL=blimu.module.cjs.map

package/dist/modules/blimu.module.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/modules/blimu.module.ts","../../src/config/blimu.config.ts","../../src/guards/entitlement.guard.ts","../../src/exceptions/blimu-forbidden.exception.ts","../../src/services/jwk.service.ts"],"sourcesContent":["import {\n  Module,\n  type DynamicModule,\n  type Type,\n  type ForwardReference,\n  type InjectionToken,\n  type OptionalFactoryDependency,\n} from '@nestjs/common';\n\nimport { BLIMU_CONFIG, type BlimuConfig } from '../config/blimu.config';\nimport { EntitlementGuard } from 'guards/entitlement.guard';\nimport { JWKService } from 'services/jwk.service';\nimport { Blimu } from '@blimu/backend';\n\nconst DEFAULT_BASE_URL = 'https://api.blimu.dev';\n\n/**\n * Blimu NestJS Module\n *\n * This module provides entitlement checking capabilities and Blimu Runtime SDK integration\n * for NestJS applications. It can be configured synchronously or asynchronously.\n */\n@Module({})\nexport class BlimuModule {\n  /**\n   * Configure the Blimu module with static configuration\n   *\n   * @param config - The Blimu configuration object\n   * @returns A configured dynamic module\n   *\n   * @example\n   * Basic usage with default Request type:\n   * ```typescript\n   * @Module({\n   *   imports: [\n   *     BlimuModule.forRoot({\n   *       apiKey: 'your-api-secret-key',\n   *       baseURL: 'https://api.blimu.dev', // optional\n   *       environmentId: 'your-environment-id', // optional\n   *       timeoutMs: 30000, // optional\n   *       getUserId: (req) => req.user?.id, // required\n   *     }),\n   *   ],\n   * })\n   * export class AppModule {}\n   * ```\n   *\n   * @example\n   * Usage with custom request type:\n   * ```typescript\n   * interface AuthenticatedRequest {\n   *   user: { id: string; email: string };\n   * }\n   *\n   * @Module({\n   *   imports: [\n   *     BlimuModule.forRoot<AuthenticatedRequest>({\n   *       apiKey: 'your-api-secret-key',\n   *       getUserId: (req) => req.user.id, // req is typed as AuthenticatedRequest\n   *     }),\n   *   ],\n   * })\n   * export class AppModule {}\n   * ```\n   */\n  static forRoot<TRequest = unknown>(config: BlimuConfig<TRequest>): DynamicModule {\n    return {\n      ...(config.global ? { global: true } : {}),\n      module: BlimuModule,\n      providers: [\n        // Register factory providers first so dependencies are available\n        {\n          provide: BLIMU_CONFIG,\n          useValue: {\n            apiKey: config.apiKey,\n            baseURL: config.baseURL ?? DEFAULT_BASE_URL,\n            environmentId: config.environmentId,\n            timeoutMs: config.timeoutMs ?? 30000,\n            getUserId: config.getUserId,\n          },\n        },\n        {\n          provide: Blimu,\n          useFactory: (config: BlimuConfig) => {\n            return new Blimu({\n              apiKey: config.apiKey,\n              baseURL: config.baseURL ?? DEFAULT_BASE_URL,\n              timeoutMs: config.timeoutMs ?? 30000,\n            });\n          },\n          inject: [BLIMU_CONFIG],\n        },\n        // Register class providers after their dependencies are available\n        EntitlementGuard,\n        JWKService,\n      ],\n      exports: [EntitlementGuard, Blimu, BLIMU_CONFIG, JWKService],\n    };\n  }\n\n  /**\n   * Configure the Blimu module with async configuration\n   *\n   * This is useful when you need to load configuration from environment variables,\n   * configuration services, or other async sources.\n   *\n   * @param options - Async configuration options\n   * @returns A configured dynamic module\n   *\n   * @example\n   * Using with ConfigService:\n   * ```typescript\n   * @Module({\n   *   imports: [\n   *     ConfigModule.forRoot(),\n   *     BlimuModule.forRootAsync({\n   *       useFactory: (configService: ConfigService) => ({\n   *         apiKey: configService.get('BLIMU_API_SECRET_KEY'),\n   *         baseURL: configService.get('BLIMU_BASE_URL'),\n   *         environmentId: configService.get('BLIMU_ENVIRONMENT_ID'),\n   *         timeoutMs: configService.get('BLIMU_TIMEOUT_MS'),\n   *         getUserId: (req) => req.user?.id,\n   *       }),\n   *       inject: [ConfigService],\n   *     }),\n   *   ],\n   * })\n   * export class AppModule {}\n   * ```\n   *\n   * @example\n   * Using with custom request type:\n   * ```typescript\n   * interface AuthenticatedRequest {\n   *   user: { id: string; email: string };\n   * }\n   *\n   * @Module({\n   *   imports: [\n   *     BlimuModule.forRootAsync<AuthenticatedRequest>({\n   *       useFactory: (configService: ConfigService) => ({\n   *         apiKey: configService.get('BLIMU_API_SECRET_KEY'),\n   *         getUserId: (req) => req.user.id, // req is typed as AuthenticatedRequest\n   *       }),\n   *       inject: [ConfigService],\n   *     }),\n   *   ],\n   * })\n   * export class AppModule {}\n   * ```\n   *\n   * @example\n   * Using with custom provider:\n   * ```typescript\n   * @Module({\n   *   imports: [\n   *     BlimuModule.forRootAsync({\n   *       imports: [MyConfigModule],\n   *       useFactory: async (myConfigService: MyConfigService) => {\n   *         const config = await myConfigService.getBlimuConfig();\n   *         return {\n   *           apiKey: config.apiKey,\n   *           baseURL: config.baseUrl,\n   *           environmentId: config.environmentId,\n   *           getUserId: (req) => req.user?.id,\n   *         };\n   *       },\n   *       inject: [MyConfigService],\n   *     }),\n   *   ],\n   * })\n   * export class AppModule {}\n   * ```\n   */\n  static forRootAsync<TRequest = unknown>(options: {\n    global?: boolean | undefined;\n    useFactory: (...args: unknown[]) => Promise<BlimuConfig<TRequest>> | BlimuConfig<TRequest>;\n    inject?: (InjectionToken | OptionalFactoryDependency)[];\n    imports?: (\n      | Type<unknown>\n      | DynamicModule\n      | Promise<DynamicModule>\n      | ForwardReference<() => Type<unknown>>\n    )[];\n  }): DynamicModule {\n    const additionalImports = options.imports ?? [];\n\n    const module = {\n      ...(options.global ? { global: true } : {}),\n      module: BlimuModule,\n      imports: [...additionalImports] as (\n        | Type<unknown>\n        | DynamicModule\n        | Promise<DynamicModule>\n        | ForwardReference\n      )[],\n      providers: [\n        // Register factory providers first so dependencies are available\n        {\n          provide: BLIMU_CONFIG,\n          useFactory: async (...args: unknown[]) => {\n            const configResult = options.useFactory(...args);\n            const config = configResult instanceof Promise ? await configResult : configResult;\n            return {\n              apiKey: config.apiKey,\n              baseURL: config.baseURL ?? DEFAULT_BASE_URL,\n              environmentId: config.environmentId,\n              timeoutMs: config.timeoutMs ?? 30000,\n              getUserId: config.getUserId,\n            };\n          },\n          ...(options.inject ? { inject: options.inject } : {}),\n        },\n        {\n          provide: Blimu,\n          useFactory: (config: BlimuConfig) => {\n            return new Blimu({\n              apiKey: config.apiKey,\n              baseURL: config.baseURL ?? DEFAULT_BASE_URL,\n              timeoutMs: config.timeoutMs ?? 30000,\n            });\n          },\n          inject: [BLIMU_CONFIG],\n        },\n        // Register class providers after their dependencies are available\n        EntitlementGuard,\n        JWKService,\n      ],\n      exports: [EntitlementGuard, Blimu, BLIMU_CONFIG, JWKService],\n    };\n    return module;\n  }\n}\n","/**\n * Configuration interface for Blimu NestJS integration\n */\nexport interface BlimuConfig<TRequest = unknown> {\n  global?: boolean | undefined;\n  /**\n   * The API secret key for authenticating with Blimu Runtime API\n   */\n  apiKey: string;\n\n  /**\n   * The base URL for the Blimu Runtime API\n   * @default 'https://api.blimu.dev'\n   */\n  baseURL?: string | undefined;\n\n  /**\n   * Environment ID for the Blimu environment\n   * This will be used in future versions for environment-specific configurations\n   */\n  environmentId?: string | undefined;\n\n  /**\n   * Request timeout in milliseconds\n   * @default 30000\n   */\n  timeoutMs?: number | undefined;\n\n  /**\n   * Function to extract user ID from the request\n   *\n   * This function is called by the EntitlementGuard to determine which user\n   * to check entitlements for. It should return the user ID as a string.\n   *\n   * @param request - The incoming HTTP request\n   * @returns The user ID as a string, or a Promise that resolves to the user ID\n   *\n   * @example\n   * ```typescript\n   * // Extract from JWT token in Authorization header\n   * getUserId: (req) => {\n   *   const token = req.headers.authorization?.replace('Bearer ', '');\n   *   const decoded = jwt.verify(token, secret);\n   *   return decoded.sub;\n   * }\n   *\n   * // Extract from request.user (common with Passport.js)\n   * getUserId: (req) => req.user?.id\n   *\n   * // Extract from custom header\n   * getUserId: (req) => req.headers['x-user-id']\n   * ```\n   */\n  getUserId: (request: TRequest) => string | Promise<string>;\n}\n\n/**\n * Injection token for Blimu configuration\n */\nexport const BLIMU_CONFIG = Symbol('BLIMU_CONFIG');\n","import {\n  type CanActivate,\n  type ExecutionContext,\n  ForbiddenException,\n  Injectable,\n  SetMetadata,\n  Inject,\n} from '@nestjs/common';\nimport 'reflect-metadata';\n\nimport type { EntitlementType } from '@blimu/types';\nimport { BlimuForbiddenException } from '../exceptions/blimu-forbidden.exception';\nimport { Blimu } from '@blimu/backend';\nimport { BLIMU_CONFIG, type BlimuConfig } from 'config/blimu.config';\n\nexport const ENTITLEMENT_KEY = 'entitlement';\nexport const ENTITLEMENT_METADATA_KEY = Symbol('entitlement');\n\n/**\n * Entitlement information returned by the getEntitlementInfo callback\n */\nexport interface EntitlementInfo {\n  resourceId: string;\n  amount?: number; // Amount to check against usage limit (for consumption)\n}\n\n/**\n * Metadata interface for entitlement checks\n */\nexport interface EntitlementMetadata<TRequest = unknown> {\n  entitlementKey: EntitlementType;\n  getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>;\n}\n\n/**\n * Sets entitlement metadata for a route handler\n * @internal This is used internally by the @Entitlement decorator\n */\nexport const SetEntitlementMetadata = <TRequest = unknown>(\n  entitlementKey: string,\n  getEntitlementInfo: (request: TRequest) => EntitlementInfo | Promise<EntitlementInfo>,\n): MethodDecorator =>\n  SetMetadata(ENTITLEMENT_METADATA_KEY, {\n    entitlementKey,\n    getEntitlementInfo,\n  } as EntitlementMetadata<TRequest>);\n\n/**\n * Guard that checks if the authenticated user has the required entitlement on a resource\n *\n * This guard automatically:\n * 1. Extracts the user from the request\n * 2. Extracts the resource ID using the provided extractor function\n * 3. Calls the Blimu Runtime API to check entitlements\n * 4. Allows or denies access based on the result\n */\n@Injectable()\nexport class EntitlementGuard<TRequest = unknown> implements CanActivate {\n  constructor(\n    @Inject(BLIMU_CONFIG)\n    private readonly config: BlimuConfig<TRequest>,\n    @Inject(Blimu)\n    private readonly runtime: Blimu,\n  ) {}\n\n  async canActivate(context: ExecutionContext): Promise<boolean> {\n    const request = context.switchToHttp().getRequest<TRequest>();\n    const handler = context.getHandler();\n    const metadata = Reflect.getMetadata(ENTITLEMENT_METADATA_KEY, handler) as\n      | EntitlementMetadata<TRequest>\n      | undefined;\n\n    if (!metadata) {\n      // No entitlement check required\n      return true;\n    }\n\n    // Extract user ID using the configured getUserId function\n    let userId: string;\n    try {\n      userId = await this.config.getUserId(request);\n    } catch {\n      throw new ForbiddenException('Failed to extract user ID from request');\n    }\n\n    if (!userId) {\n      throw new ForbiddenException('User ID is required for entitlement check');\n    }\n\n    // Extract entitlement info from request\n    const entitlementInfo = await metadata.getEntitlementInfo(request);\n\n    if (!entitlementInfo?.resourceId) {\n      throw new ForbiddenException('Resource ID is required for entitlement check');\n    }\n\n    try {\n      // Check entitlement\n      const result = await this.runtime.entitlements.checkEntitlement({\n        userId,\n        entitlement: metadata.entitlementKey,\n        resourceId: entitlementInfo.resourceId,\n        ...(entitlementInfo.amount !== undefined ? { amount: entitlementInfo.amount } : {}),\n      });\n\n      if (!result.allowed) {\n        throw new BlimuForbiddenException(\n          result,\n          metadata.entitlementKey,\n          entitlementInfo.resourceId,\n          userId,\n        );\n      }\n\n      return true;\n    } catch (error) {\n      if (error instanceof BlimuForbiddenException || error instanceof ForbiddenException) {\n        throw error;\n      }\n\n      // Log the error for debugging but don't expose internal details\n      console.error('Entitlement check failed:', error);\n      throw new ForbiddenException('Failed to verify entitlements');\n    }\n  }\n}\n","import { ForbiddenException } from '@nestjs/common';\nimport type { Schema } from '@blimu/backend';\nimport type { EntitlementType } from '@blimu/types';\n/**\n * Custom exception for Blimu entitlement check failures\n *\n * This exception extends NestJS's ForbiddenException and includes\n * the typed EntitlementCheckResult, providing detailed information\n * about why the entitlement check failed (roles, plans, limits, etc.)\n */\nexport class BlimuForbiddenException extends ForbiddenException {\n  /**\n   * The entitlement check result containing detailed failure information\n   */\n  public readonly entitlementResult: Schema.EntitlementCheckResult;\n\n  /**\n   * The entitlement key that was checked\n   */\n  public readonly entitlementKey: EntitlementType;\n\n  /**\n   * The resource ID that was checked\n   */\n  public readonly resourceId: string;\n\n  /**\n   * The user ID that was checked\n   */\n  public readonly userId: string;\n\n  constructor(\n    entitlementResult: Schema.EntitlementCheckResult,\n    entitlementKey: EntitlementType,\n    resourceId: string,\n    userId: string,\n  ) {\n    // Create a user-friendly message based on the failure reason\n    const message = BlimuForbiddenException.buildMessage(entitlementResult, entitlementKey);\n\n    super({\n      message,\n      entitlementResult,\n      entitlementKey,\n      resourceId,\n      userId,\n    });\n\n    this.entitlementResult = entitlementResult;\n    this.entitlementKey = entitlementKey;\n    this.resourceId = resourceId;\n    this.userId = userId;\n  }\n\n  /**\n   * Builds a user-friendly error message from the entitlement check result\n   */\n  private static buildMessage(\n    result: Schema.EntitlementCheckResult,\n    entitlementKey: EntitlementType,\n  ): string {\n    const reasons: string[] = [];\n\n    if (result.roles && !result.roles.allowed) {\n      reasons.push(\n        `Insufficient roles. Required: ${result.roles.allowedRoles?.join(', ') || 'unknown'}. User has: ${result.roles.userRoles?.join(', ') || 'none'}.`,\n      );\n    }\n\n    if (result.plans && !result.plans.allowed) {\n      reasons.push(\n        `Plan restriction. Required plans: ${result.plans.allowedPlans?.join(', ') || 'unknown'}. Current plan: ${result.plans.plan || 'none'}.`,\n      );\n    }\n\n    if (result.limit && !result.limit.allowed) {\n      reasons.push(`Usage limit exceeded. ${result.limit.reason || 'Limit has been reached'}.`);\n    }\n\n    if (reasons.length === 0) {\n      return `Access denied for entitlement: ${entitlementKey}`;\n    }\n\n    return `Access denied for entitlement \"${entitlementKey}\": ${reasons.join(' ')}`;\n  }\n}\n","import { Inject, Injectable, Logger } from '@nestjs/common';\nimport { TokenVerifier } from '@blimu/backend';\nimport { BLIMU_CONFIG, type BlimuConfig } from '../config/blimu.config';\n\n@Injectable()\nexport class JWKService {\n  private readonly logger = new Logger(JWKService.name);\n  private readonly tokenVerifier: TokenVerifier;\n\n  constructor(@Inject(BLIMU_CONFIG) private readonly config: BlimuConfig) {\n    this.tokenVerifier = new TokenVerifier({\n      runtimeApiUrl: this.config.baseURL,\n    });\n  }\n\n  /**\n   * Verify JWT token using JWKs from runtime-api\n   */\n  async verifyToken<T = unknown>(token: string): Promise<T> {\n    try {\n      this.logger.debug(\n        `🔍 Verifying token. Runtime API URL: ${this.config.baseURL}, API Key prefix: ${this.config.apiKey?.substring(0, 10)}...`,\n      );\n\n      const result = await this.tokenVerifier.verifyToken<T>({\n        secretKey: this.config.apiKey,\n        token,\n        runtimeApiUrl: this.config.baseURL,\n      });\n\n      this.logger.debug(`✅ Token verified successfully`);\n      return result;\n    } catch (error) {\n      const errorMessage = error instanceof Error ? error.message : String(error);\n      this.logger.error(`❌ Token verification failed: ${errorMessage}`);\n      if (error instanceof Error && error.stack) {\n        this.logger.error(`Stack trace: ${error.stack}`);\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Clear cache (useful for testing or key rotation)\n   */\n  clearCache(): void {\n    this.tokenVerifier.clearCache(this.config.apiKey);\n    this.logger.debug('JWK cache cleared');\n  }\n}\n"],"mappings":"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","names":["import_common","import_common","import_common","import_backend","import_backend","config","module"]}

package/dist/modules/blimu.module.d.cts

@@ -0,0 +1,14 @@
+import { DynamicModule, InjectionToken, OptionalFactoryDependency, Type, ForwardReference } from '@nestjs/common';
+import { BlimuConfig } from '../config/blimu.config.cjs';
+
+declare class BlimuModule {
+    static forRoot<TRequest = unknown>(config: BlimuConfig<TRequest>): DynamicModule;
+    static forRootAsync<TRequest = unknown>(options: {
+        global?: boolean | undefined;
+        useFactory: (...args: unknown[]) => Promise<BlimuConfig<TRequest>> | BlimuConfig<TRequest>;
+        inject?: (InjectionToken | OptionalFactoryDependency)[];
+        imports?: (Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference<() => Type<unknown>>)[];
+    }): DynamicModule;
+}
+
+export { BlimuModule };

package/dist/modules/blimu.module.d.ts

@@ -1,11 +1,14 @@
-import { DynamicModule, Type, ForwardReference, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
-import type { BlimuConfig } from '../config/blimu.config';
-export declare class BlimuModule {
-    static forRoot<TRequest = any>(config: BlimuConfig<TRequest>): DynamicModule;
-    static forRootAsync<TRequest = any>(options: {
+import { DynamicModule, InjectionToken, OptionalFactoryDependency, Type, ForwardReference } from '@nestjs/common';
+import { BlimuConfig } from '../config/blimu.config.js';
+
+declare class BlimuModule {
+    static forRoot<TRequest = unknown>(config: BlimuConfig<TRequest>): DynamicModule;
+    static forRootAsync<TRequest = unknown>(options: {
+        global?: boolean | undefined;
         useFactory: (...args: unknown[]) => Promise<BlimuConfig<TRequest>> | BlimuConfig<TRequest>;
-        inject?: Array<InjectionToken | OptionalFactoryDependency>;
-        imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference<() => Type<unknown>>>;
+        inject?: (InjectionToken | OptionalFactoryDependency)[];
+        imports?: (Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference<() => Type<unknown>>)[];
     }): DynamicModule;
 }
-//# sourceMappingURL=blimu.module.d.ts.map
+
+export { BlimuModule };