create-forgeon 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Forgeon project generator CLI",
   "license": "MIT",
   "author": "Forgeon",

package/src/modules/executor.mjs

@@ -7,6 +7,7 @@ import { applyI18nModule } from './i18n.mjs';
 import { applyJwtAuthModule } from './jwt-auth.mjs';
 import { applyLoggerModule } from './logger.mjs';
 import { applyRateLimitModule } from './rate-limit.mjs';
+import { applyRbacModule } from './rbac.mjs';
 import { applySwaggerModule } from './swagger.mjs';
 
 function ensureForgeonLikeProject(targetRoot) {
@@ -31,6 +32,7 @@ const MODULE_APPLIERS = {
   'jwt-auth': applyJwtAuthModule,
   logger: applyLoggerModule,
   'rate-limit': applyRateLimitModule,
+  rbac: applyRbacModule,
   swagger: applySwaggerModule,
 };
 

package/src/modules/executor.test.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { addModule } from './executor.mjs';
-import { syncIntegrations } from './sync-integrations.mjs';
+import { scanIntegrations, syncIntegrations } from './sync-integrations.mjs';
 import { scaffoldProject } from '../core/scaffold.mjs';
 
 function mkTmp(prefix) {
@@ -81,6 +81,37 @@ function assertRateLimitWiring(projectRoot) {
   assert.match(readme, /## Rate Limit Module/);
 }
 
+function assertRbacWiring(projectRoot) {
+  const appModule = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'app.module.ts'), 'utf8');
+  assert.match(appModule, /ForgeonRbacModule/);
+
+  const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
+  assert.match(apiPackage, /@forgeon\/rbac/);
+  assert.match(apiPackage, /pnpm --filter @forgeon\/rbac build/);
+
+  const apiDockerfile = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'Dockerfile'), 'utf8');
+  assert.match(apiDockerfile, /COPY packages\/rbac\/package\.json packages\/rbac\/package\.json/);
+  assert.match(apiDockerfile, /COPY packages\/rbac packages\/rbac/);
+  assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/rbac build/);
+
+  const healthController = fs.readFileSync(
+    path.join(projectRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'),
+    'utf8',
+  );
+  assert.match(healthController, /UseGuards/);
+  assert.match(healthController, /ForgeonRbacGuard/);
+  assert.match(healthController, /@Get\('rbac'\)/);
+  assert.match(healthController, /@Permissions\('health\.rbac'\)/);
+
+  const appTsx = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'src', 'App.tsx'), 'utf8');
+  assert.match(appTsx, /Check RBAC access/);
+  assert.match(appTsx, /RBAC probe response/);
+  assert.match(appTsx, /x-forgeon-permissions/);
+
+  const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
+  assert.match(readme, /## RBAC \/ Permissions Module/);
+}
+
 function assertJwtAuthWiring(projectRoot, withPrismaStore) {
   const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
   assert.match(apiPackage, /@forgeon\/auth-api/);
@@ -603,6 +634,41 @@ describe('addModule', () => {
     }
   });
 
+  it('applies rbac module on top of scaffold without i18n', () => {
+    const targetRoot = mkTmp('forgeon-module-rbac-');
+    const projectRoot = path.join(targetRoot, 'demo-rbac');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-rbac',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      const result = addModule({
+        moduleId: 'rbac',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      assert.equal(result.applied, true);
+      assertRbacWiring(projectRoot);
+
+      const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
+      assert.match(moduleDoc, /## Idea \/ Why/);
+      assert.match(moduleDoc, /## How It Works/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
   it('applies swagger module on top of scaffold without i18n', () => {
     const targetRoot = mkTmp('forgeon-module-swagger-');
     const projectRoot = path.join(targetRoot, 'demo-swagger');
@@ -1079,6 +1145,80 @@ describe('addModule', () => {
     }
   });
 
+  it('detects and applies jwt-auth + rbac claims integration explicitly', () => {
+    const targetRoot = mkTmp('forgeon-module-jwt-rbac-');
+    const projectRoot = path.join(targetRoot, 'demo-jwt-rbac');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-jwt-rbac',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      addModule({
+        moduleId: 'rbac',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+      addModule({
+        moduleId: 'jwt-auth',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      const scan = scanIntegrations({
+        targetRoot: projectRoot,
+        relatedModuleId: 'jwt-auth',
+      });
+      assert.equal(scan.groups.some((group) => group.id === 'auth-rbac-claims'), true);
+
+      const syncResult = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-rbac-claims'],
+      });
+      const claimsPair = syncResult.summary.find((item) => item.id === 'auth-rbac-claims');
+      assert.ok(claimsPair);
+      assert.equal(claimsPair.result.applied, true);
+
+      const authContracts = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'auth-contracts', 'src', 'index.ts'),
+        'utf8',
+      );
+      assert.match(authContracts, /permissions\?: string\[\];/);
+
+      const authService = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'auth-api', 'src', 'auth.service.ts'),
+        'utf8',
+      );
+      assert.match(authService, /permissions: \['health\.rbac'\]/);
+      assert.match(authService, /permissions: user\.permissions,/);
+      assert.match(
+        authService,
+        /permissions: Array\.isArray\(payload\.permissions\) \? payload\.permissions : \[\],/,
+      );
+
+      const authController = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'auth-api', 'src', 'auth.controller.ts'),
+        'utf8',
+      );
+      assert.match(
+        authController,
+        /permissions: Array\.isArray\(payload\.permissions\) \? payload\.permissions : \[\],/,
+      );
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
   it('applies logger then jwt-auth on db/i18n-disabled scaffold without breaking health controller syntax', () => {
     const targetRoot = mkTmp('forgeon-module-jwt-nodb-noi18n-');
     const projectRoot = path.join(targetRoot, 'demo-jwt-nodb-noi18n');
@@ -1255,6 +1395,43 @@ describe('addModule', () => {
     }
   });
 
+  it('keeps rbac wiring valid after mixed module installation order', () => {
+    const targetRoot = mkTmp('forgeon-module-rbac-order-');
+    const projectRoot = path.join(targetRoot, 'demo-rbac-order');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-rbac-order',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      for (const moduleId of ['jwt-auth', 'logger', 'rate-limit', 'rbac', 'swagger', 'i18n', 'db-prisma']) {
+        addModule({ moduleId, targetRoot: projectRoot, packageRoot });
+      }
+
+      assertRbacWiring(projectRoot);
+
+      const healthController = fs.readFileSync(
+        path.join(projectRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'),
+        'utf8',
+      );
+      const classStart = healthController.indexOf('export class HealthController {');
+      const classEnd = healthController.lastIndexOf('\n}');
+      const rbacProbe = healthController.indexOf("@Get('rbac')");
+      assert.equal(rbacProbe > classStart && rbacProbe < classEnd, true);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
   it('keeps db-prisma wiring across module installation orders', () => {
     const sequences = [
       ['logger', 'swagger', 'i18n'],

package/src/modules/i18n.mjs

@@ -422,6 +422,7 @@ function restoreKnownWebProbes(targetRoot, previousAppContent) {
       return;
     }
     const anchors = [
+      '  const [rbacProbeResult, setRbacProbeResult] = useState<ProbeResult | null>(null);',
       '  const [rateLimitProbeResult, setRateLimitProbeResult] = useState<ProbeResult | null>(null);',
       '  const [authProbeResult, setAuthProbeResult] = useState<ProbeResult | null>(null);',
       '  const [dbProbeResult, setDbProbeResult] = useState<ProbeResult | null>(null);',
@@ -458,6 +459,7 @@ function restoreKnownWebProbes(targetRoot, previousAppContent) {
       return;
     }
     const anchors = [
+      "      {renderResult('RBAC probe response', rbacProbeResult)}",
       "      {renderResult('Rate limit probe response', rateLimitProbeResult)}",
       "      {renderResult('Auth probe response', authProbeResult)}",
       "      {renderResult('DB probe response', dbProbeResult)}",
@@ -498,6 +500,15 @@ function restoreKnownWebProbes(targetRoot, previousAppContent) {
     ensureProbeResult("      {renderResult('Rate limit probe response', rateLimitProbeResult)}");
   }
 
+  if (previousAppContent.includes('Check RBAC access')) {
+    ensureProbeState('  const [rbacProbeResult, setRbacProbeResult] = useState<ProbeResult | null>(null);');
+    ensureProbeButton(
+      'Check RBAC access',
+      "        <button\n          onClick={() =>\n            runProbe(setRbacProbeResult, '/health/rbac', {\n              headers: { 'x-forgeon-permissions': 'health.rbac' },\n            })\n          }\n        >\n          Check RBAC access\n        </button>",
+    );
+    ensureProbeResult("      {renderResult('RBAC probe response', rbacProbeResult)}");
+  }
+
   fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
 }
 

package/src/modules/rbac.mjs

@@ -0,0 +1,324 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyRecursive, writeJson } from '../utils/fs.mjs';
+import {
+  ensureBuildSteps,
+  ensureClassMember,
+  ensureDependency,
+  ensureImportLine,
+  ensureLineAfter,
+  ensureLineBefore,
+  ensureNestCommonImport,
+} from './shared/patch-utils.mjs';
+
+function copyFromPreset(packageRoot, targetRoot, relativePath) {
+  const source = path.join(packageRoot, 'templates', 'module-presets', 'rbac', relativePath);
+  if (!fs.existsSync(source)) {
+    throw new Error(`Missing rbac preset template: ${source}`);
+  }
+  const destination = path.join(targetRoot, relativePath);
+  copyRecursive(source, destination);
+}
+
+function patchApiPackage(targetRoot) {
+  const packagePath = path.join(targetRoot, 'apps', 'api', 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  ensureDependency(packageJson, '@forgeon/rbac', 'workspace:*');
+  ensureBuildSteps(packageJson, 'predev', ['pnpm --filter @forgeon/rbac build']);
+  writeJson(packagePath, packageJson);
+}
+
+function patchAppModule(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'api', 'src', 'app.module.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  if (!content.includes("from '@forgeon/rbac';")) {
+    if (content.includes("import { ForgeonI18nModule, i18nConfig, i18nEnvSchema } from '@forgeon/i18n';")) {
+      content = ensureLineAfter(
+        content,
+        "import { ForgeonI18nModule, i18nConfig, i18nEnvSchema } from '@forgeon/i18n';",
+        "import { ForgeonRbacModule } from '@forgeon/rbac';",
+      );
+    } else if (
+      content.includes("import { authConfig, authEnvSchema, ForgeonAuthModule } from '@forgeon/auth-api';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { authConfig, authEnvSchema, ForgeonAuthModule } from '@forgeon/auth-api';",
+        "import { ForgeonRbacModule } from '@forgeon/rbac';",
+      );
+    } else if (
+      content.includes("import { ForgeonRateLimitModule, rateLimitConfig, rateLimitEnvSchema } from '@forgeon/rate-limit';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { ForgeonRateLimitModule, rateLimitConfig, rateLimitEnvSchema } from '@forgeon/rate-limit';",
+        "import { ForgeonRbacModule } from '@forgeon/rbac';",
+      );
+    } else if (
+      content.includes("import { ForgeonLoggerModule, loggerConfig, loggerEnvSchema } from '@forgeon/logger';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { ForgeonLoggerModule, loggerConfig, loggerEnvSchema } from '@forgeon/logger';",
+        "import { ForgeonRbacModule } from '@forgeon/rbac';",
+      );
+    } else if (
+      content.includes("import { ForgeonSwaggerModule, swaggerConfig, swaggerEnvSchema } from '@forgeon/swagger';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { ForgeonSwaggerModule, swaggerConfig, swaggerEnvSchema } from '@forgeon/swagger';",
+        "import { ForgeonRbacModule } from '@forgeon/rbac';",
+      );
+    } else if (
+      content.includes("import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';",
+        "import { ForgeonRbacModule } from '@forgeon/rbac';",
+      );
+    } else {
+      content = ensureLineAfter(
+        content,
+        "import { ConfigModule } from '@nestjs/config';",
+        "import { ForgeonRbacModule } from '@forgeon/rbac';",
+      );
+    }
+  }
+
+  if (!content.includes('    ForgeonRbacModule,')) {
+    if (content.includes('    ForgeonI18nModule.register({')) {
+      content = ensureLineBefore(content, '    ForgeonI18nModule.register({', '    ForgeonRbacModule,');
+    } else if (content.includes('    ForgeonAuthModule.register({')) {
+      content = ensureLineBefore(content, '    ForgeonAuthModule.register({', '    ForgeonRbacModule,');
+    } else if (content.includes('    ForgeonAuthModule.register(),')) {
+      content = ensureLineBefore(content, '    ForgeonAuthModule.register(),', '    ForgeonRbacModule,');
+    } else if (content.includes('    ForgeonRateLimitModule,')) {
+      content = ensureLineAfter(content, '    ForgeonRateLimitModule,', '    ForgeonRbacModule,');
+    } else if (content.includes('    DbPrismaModule,')) {
+      content = ensureLineAfter(content, '    DbPrismaModule,', '    ForgeonRbacModule,');
+    } else if (content.includes('    ForgeonLoggerModule,')) {
+      content = ensureLineAfter(content, '    ForgeonLoggerModule,', '    ForgeonRbacModule,');
+    } else if (content.includes('    ForgeonSwaggerModule,')) {
+      content = ensureLineAfter(content, '    ForgeonSwaggerModule,', '    ForgeonRbacModule,');
+    } else {
+      content = ensureLineAfter(content, '    CoreErrorsModule,', '    ForgeonRbacModule,');
+    }
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchHealthController(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  content = ensureNestCommonImport(content, 'UseGuards');
+
+  if (!content.includes("from '@forgeon/rbac';")) {
+    content = ensureImportLine(
+      content,
+      "import { ForgeonRbacGuard, Permissions } from '@forgeon/rbac';",
+    );
+  }
+
+  if (!content.includes("@Get('rbac')")) {
+    const method = `
+  @Get('rbac')
+  @UseGuards(ForgeonRbacGuard)
+  @Permissions('health.rbac')
+  getRbacProbe() {
+    return {
+      status: 'ok',
+      feature: 'rbac',
+      granted: true,
+      requiredPermission: 'health.rbac',
+      hint: 'Send x-forgeon-permissions: health.rbac to pass this check manually.',
+    };
+  }
+`;
+    const beforeNeedle = content.includes("@Get('rate-limit')")
+      ? "@Get('rate-limit')"
+      : content.includes('private translate(')
+        ? 'private translate('
+        : '';
+    content = ensureClassMember(content, 'HealthController', method, { beforeNeedle });
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchWebApp(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'web', 'src', 'App.tsx');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  content = content
+    .replace(/^\s*\{\/\* forgeon:probes:actions:start \*\/\}\r?\n?/gm, '')
+    .replace(/^\s*\{\/\* forgeon:probes:actions:end \*\/\}\r?\n?/gm, '')
+    .replace(/^\s*\{\/\* forgeon:probes:results:start \*\/\}\r?\n?/gm, '')
+    .replace(/^\s*\{\/\* forgeon:probes:results:end \*\/\}\r?\n?/gm, '');
+
+  if (!content.includes('rbacProbeResult')) {
+    const stateAnchors = [
+      '  const [rateLimitProbeResult, setRateLimitProbeResult] = useState<ProbeResult | null>(null);',
+      '  const [dbProbeResult, setDbProbeResult] = useState<ProbeResult | null>(null);',
+      '  const [authProbeResult, setAuthProbeResult] = useState<ProbeResult | null>(null);',
+      '  const [validationProbeResult, setValidationProbeResult] = useState<ProbeResult | null>(null);',
+    ];
+    const stateAnchor = stateAnchors.find((line) => content.includes(line));
+    if (stateAnchor) {
+      content = ensureLineAfter(
+        content,
+        stateAnchor,
+        '  const [rbacProbeResult, setRbacProbeResult] = useState<ProbeResult | null>(null);',
+      );
+    }
+  }
+
+  if (!content.includes('Check RBAC access')) {
+    const useProxyPath = content.includes("runProbe(setHealthResult, '/health')");
+    const probePath = useProxyPath ? '/health/rbac' : '/api/health/rbac';
+    const button = `        <button\n          onClick={() =>\n            runProbe(setRbacProbeResult, '${probePath}', {\n              headers: { 'x-forgeon-permissions': 'health.rbac' },\n            })\n          }\n        >\n          Check RBAC access\n        </button>`;
+
+    const actionsStart = content.indexOf('<div className="actions">');
+    if (actionsStart >= 0) {
+      const actionsEnd = content.indexOf('\n      </div>', actionsStart);
+      if (actionsEnd >= 0) {
+        content = `${content.slice(0, actionsEnd)}\n${button}${content.slice(actionsEnd)}`;
+      }
+    }
+  }
+
+  if (!content.includes("{renderResult('RBAC probe response', rbacProbeResult)}")) {
+    const resultLine = "      {renderResult('RBAC probe response', rbacProbeResult)}";
+    const networkLine = '      {networkError ? <p className="error">{networkError}</p> : null}';
+    if (content.includes(networkLine)) {
+      content = content.replace(networkLine, `${resultLine}\n${networkLine}`);
+    } else {
+      const anchors = [
+        "      {renderResult('Rate limit probe response', rateLimitProbeResult)}",
+        "      {renderResult('Auth probe response', authProbeResult)}",
+        "      {renderResult('DB probe response', dbProbeResult)}",
+        "      {renderResult('Validation probe response', validationProbeResult)}",
+      ];
+      const anchor = anchors.find((line) => content.includes(line));
+      if (anchor) {
+        content = ensureLineAfter(content, anchor, resultLine);
+      }
+    }
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchApiDockerfile(targetRoot) {
+  const dockerfilePath = path.join(targetRoot, 'apps', 'api', 'Dockerfile');
+  if (!fs.existsSync(dockerfilePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(dockerfilePath, 'utf8').replace(/\r\n/g, '\n');
+  const packageAnchors = [
+    'COPY packages/auth-api/package.json packages/auth-api/package.json',
+    'COPY packages/rate-limit/package.json packages/rate-limit/package.json',
+    'COPY packages/logger/package.json packages/logger/package.json',
+    'COPY packages/swagger/package.json packages/swagger/package.json',
+    'COPY packages/i18n/package.json packages/i18n/package.json',
+    'COPY packages/db-prisma/package.json packages/db-prisma/package.json',
+    'COPY packages/core/package.json packages/core/package.json',
+  ];
+  const packageAnchor = packageAnchors.find((line) => content.includes(line)) ?? packageAnchors.at(-1);
+  content = ensureLineAfter(content, packageAnchor, 'COPY packages/rbac/package.json packages/rbac/package.json');
+
+  const sourceAnchors = [
+    'COPY packages/auth-api packages/auth-api',
+    'COPY packages/rate-limit packages/rate-limit',
+    'COPY packages/logger packages/logger',
+    'COPY packages/swagger packages/swagger',
+    'COPY packages/i18n packages/i18n',
+    'COPY packages/db-prisma packages/db-prisma',
+    'COPY packages/core packages/core',
+  ];
+  const sourceAnchor = sourceAnchors.find((line) => content.includes(line)) ?? sourceAnchors.at(-1);
+  content = ensureLineAfter(content, sourceAnchor, 'COPY packages/rbac packages/rbac');
+
+  content = content.replace(/^RUN pnpm --filter @forgeon\/rbac build\r?\n?/gm, '');
+  const buildAnchor = content.includes('RUN pnpm --filter @forgeon/api prisma:generate')
+    ? 'RUN pnpm --filter @forgeon/api prisma:generate'
+    : 'RUN pnpm --filter @forgeon/api build';
+  content = ensureLineBefore(content, buildAnchor, 'RUN pnpm --filter @forgeon/rbac build');
+
+  fs.writeFileSync(dockerfilePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchReadme(targetRoot) {
+  const readmePath = path.join(targetRoot, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    return;
+  }
+
+  const marker = '## RBAC / Permissions Module';
+  let content = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+  if (content.includes(marker)) {
+    return;
+  }
+
+  const section = `## RBAC / Permissions Module
+
+The rbac add-module provides a minimal authorization layer for role and permission checks.
+
+What it adds:
+- \`@Roles(...)\` and \`@Permissions(...)\` decorators
+- \`ForgeonRbacGuard\`
+- simple helper functions for role / permission checks
+- a protected probe route: \`GET /api/health/rbac\`
+
+How it works:
+- the guard reads metadata from decorators
+- it checks \`request.user\` first
+- if no user payload is present, it can also read test headers:
+  - \`x-forgeon-roles\`
+  - \`x-forgeon-permissions\`
+
+How to verify:
+- the generated frontend button sends \`x-forgeon-permissions: health.rbac\` and should return \`200\`
+- the same route without that header should return \`403\`
+
+Current scope:
+- no policy engine
+- no database-backed role store
+- no frontend route-guard layer in this module`;
+
+  if (content.includes('## Prisma In Docker Start')) {
+    content = content.replace('## Prisma In Docker Start', `${section}\n\n## Prisma In Docker Start`);
+  } else {
+    content = `${content.trimEnd()}\n\n${section}\n`;
+  }
+
+  fs.writeFileSync(readmePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+export function applyRbacModule({ packageRoot, targetRoot }) {
+  copyFromPreset(packageRoot, targetRoot, path.join('packages', 'rbac'));
+  patchApiPackage(targetRoot);
+  patchAppModule(targetRoot);
+  patchHealthController(targetRoot);
+  patchWebApp(targetRoot);
+  patchApiDockerfile(targetRoot);
+  patchReadme(targetRoot);
+}

package/src/modules/registry.mjs

@@ -57,6 +57,24 @@ const MODULE_PRESETS = {
       '90_status_implemented',
     ],
   },
+  rbac: {
+    id: 'rbac',
+    label: 'RBAC / Permissions',
+    category: 'auth-security',
+    implemented: true,
+    description: 'Role and permission decorators with a Nest guard and a protected probe endpoint.',
+    docFragments: [
+      '00_title',
+      '10_overview',
+      '20_idea',
+      '30_what_it_adds',
+      '40_how_it_works',
+      '50_how_to_use',
+      '60_configuration',
+      '70_operational_notes',
+      '90_status_implemented',
+    ],
+  },
   queue: {
     id: 'queue',
     label: 'Queue Worker',

package/src/modules/sync-integrations.mjs

@@ -68,6 +68,29 @@ function isAuthPersistencePending(rootDir) {
   return !(hasModuleWiring && hasSchema && hasStoreFile && hasMigration);
 }
 
+function isAuthRbacPending(rootDir) {
+  const authContractsPath = path.join(rootDir, 'packages', 'auth-contracts', 'src', 'index.ts');
+  const authServicePath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.service.ts');
+  const authControllerPath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.controller.ts');
+
+  if (!fs.existsSync(authContractsPath) || !fs.existsSync(authServicePath) || !fs.existsSync(authControllerPath)) {
+    return false;
+  }
+
+  const authContracts = fs.readFileSync(authContractsPath, 'utf8');
+  const authService = fs.readFileSync(authServicePath, 'utf8');
+  const authController = fs.readFileSync(authControllerPath, 'utf8');
+
+  const hasContracts = authContracts.includes('permissions?: string[];');
+  const hasDemoClaims = authService.includes("permissions: ['health.rbac']");
+  const hasPayloadClaims = authService.includes('permissions: user.permissions,');
+  const hasRefreshClaims = authService.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],');
+  const hasControllerClaims =
+    authController.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],');
+
+  return !(hasContracts && hasDemoClaims && hasPayloadClaims && hasRefreshClaims && hasControllerClaims);
+}
+
 const INTEGRATION_GROUPS = [
   {
     id: 'auth-persistence',
@@ -83,6 +106,20 @@ const INTEGRATION_GROUPS = [
     isPending: (rootDir) => isAuthPersistencePending(rootDir),
     apply: syncJwtDbPrisma,
   },
+  {
+    id: 'auth-rbac-claims',
+    title: 'Auth Claims Integration',
+    modules: ['jwt-auth', 'rbac'],
+    description: [
+      'Extend AuthUser with optional permissions in @forgeon/auth-contracts',
+      'Add demo RBAC claims to jwt-auth login and token payloads',
+      'Expose permissions in auth refresh and /me responses',
+      'Update JWT auth README note about RBAC demo claims',
+    ],
+    isAvailable: (detected) => detected.jwtAuth && detected.rbac,
+    isPending: (rootDir) => isAuthRbacPending(rootDir),
+    apply: syncJwtRbacClaims,
+  },
 ];
 
 function detectModules(rootDir) {
@@ -93,6 +130,9 @@ function detectModules(rootDir) {
     jwtAuth:
       fs.existsSync(path.join(rootDir, 'packages', 'auth-api', 'package.json')) ||
       appModuleText.includes("from '@forgeon/auth-api'"),
+    rbac:
+      fs.existsSync(path.join(rootDir, 'packages', 'rbac', 'package.json')) ||
+      appModuleText.includes("from '@forgeon/rbac'"),
     dbPrisma:
       fs.existsSync(path.join(rootDir, 'packages', 'db-prisma', 'package.json')) ||
       appModuleText.includes("from '@forgeon/db-prisma'"),
@@ -216,6 +256,109 @@ function syncJwtDbPrisma({ rootDir, packageRoot, changedFiles }) {
   return { applied: true };
 }
 
+function syncJwtRbacClaims({ rootDir, changedFiles }) {
+  const authContractsPath = path.join(rootDir, 'packages', 'auth-contracts', 'src', 'index.ts');
+  const authServicePath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.service.ts');
+  const authControllerPath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.controller.ts');
+  const readmePath = path.join(rootDir, 'README.md');
+
+  if (!fs.existsSync(authContractsPath) || !fs.existsSync(authServicePath) || !fs.existsSync(authControllerPath)) {
+    return { applied: false, reason: 'auth package files are missing' };
+  }
+
+  let touched = false;
+
+  let authContracts = fs.readFileSync(authContractsPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthContracts = authContracts;
+  if (!authContracts.includes('permissions?: string[];')) {
+    authContracts = authContracts.replace(
+      '  roles: string[];',
+      `  roles: string[];
+  permissions?: string[];`,
+    );
+  }
+  if (authContracts !== originalAuthContracts) {
+    fs.writeFileSync(authContractsPath, `${authContracts.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authContractsPath);
+    touched = true;
+  }
+
+  let authService = fs.readFileSync(authServicePath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthService = authService;
+  authService = authService.replace(
+    /roles: \['user'\],/g,
+    `roles: ['admin'],
+      permissions: ['health.rbac'],`,
+  );
+  if (!authService.includes('permissions: user.permissions,')) {
+    authService = authService.replace(
+      '      roles: user.roles,',
+      `      roles: user.roles,
+      permissions: user.permissions,`,
+    );
+  }
+  if (!authService.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],')) {
+    authService = authService.replace(
+      "      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],",
+      `      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
+      permissions: Array.isArray(payload.permissions) ? payload.permissions : [],`,
+    );
+  }
+  if (!authService.includes('demoPermissions: [')) {
+    authService = authService.replace(
+      "      demoEmail: this.configService.demoEmail,",
+      `      demoEmail: this.configService.demoEmail,
+      demoPermissions: ['health.rbac'],`,
+    );
+  }
+  if (authService !== originalAuthService) {
+    fs.writeFileSync(authServicePath, `${authService.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authServicePath);
+    touched = true;
+  }
+
+  let authController = fs.readFileSync(authControllerPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthController = authController;
+  if (!authController.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],')) {
+    authController = authController.replace(
+      "      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],",
+      `      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
+      permissions: Array.isArray(payload.permissions) ? payload.permissions : [],`,
+    );
+  }
+  if (authController !== originalAuthController) {
+    fs.writeFileSync(authControllerPath, `${authController.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authControllerPath);
+    touched = true;
+  }
+
+  if (fs.existsSync(readmePath)) {
+    let readme = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+    const originalReadme = readme;
+    if (!readme.includes('- RBAC integration: demo auth tokens include `health.rbac` permission')) {
+      const marker = 'Default demo credentials:';
+      if (readme.includes(marker)) {
+        readme = readme.replace(
+          marker,
+          `- RBAC integration: demo auth tokens include \`health.rbac\` permission
+
+Default demo credentials:`,
+        );
+      }
+    }
+    if (readme !== originalReadme) {
+      fs.writeFileSync(readmePath, `${readme.trimEnd()}\n`, 'utf8');
+      changedFiles.add(readmePath);
+      touched = true;
+    }
+  }
+
+  if (!touched) {
+    return { applied: false, reason: 'already synced' };
+  }
+  return { applied: true };
+}
+
 export function syncIntegrations({ targetRoot, packageRoot, groupIds = null }) {
   const rootDir = path.resolve(targetRoot);
   const changedFiles = new Set();

package/src/run-add-module.mjs

@@ -94,7 +94,7 @@ function ensureSyncTooling({ packageRoot, targetRoot }) {
   );
   const targetScript = path.join(targetRoot, 'scripts', 'forgeon-sync-integrations.mjs');
 
-  if (fs.existsSync(sourceScript) && !fs.existsSync(targetScript)) {
+  if (fs.existsSync(sourceScript)) {
     fs.mkdirSync(path.dirname(targetScript), { recursive: true });
     fs.copyFileSync(sourceScript, targetScript);
   }

package/templates/base/README.md

@@ -37,6 +37,7 @@ pnpm forgeon:sync-integrations
 ```
 
 Current sync coverage:
+- `jwt-auth + rbac`: extends demo auth tokens with the `health.rbac` permission.
 - `jwt-auth + db-prisma`: wires persistent refresh-token storage for auth.
 
 `create-forgeon add <module>` scans for relevant integration groups and can apply them immediately.

package/templates/base/docs/AI/MODULE_SPEC.md

@@ -4,11 +4,15 @@
 
 Define one repeatable fullstack pattern for Forgeon add-modules.
 
-Each feature module should be split into:
+Most feature modules should be split into:
 
-1. `@forgeon/<feature>-contracts`
-2. `@forgeon/<feature>-api`
-3. `@forgeon/<feature>-web`
+1. `@forgeon/<feature>-contracts`
+2. `@forgeon/<feature>-api`
+3. `@forgeon/<feature>-web`
+
+Exception:
+
+- backend-only infrastructure or security modules may use a single runtime package (`@forgeon/<feature>`) when shared contracts and a dedicated web package add no real value.
 
 ## 1) Contracts Package
 

package/templates/base/scripts/forgeon-sync-integrations.mjs

@@ -53,6 +53,9 @@ function detectModules(rootDir) {
     jwtAuth:
       fs.existsSync(path.join(rootDir, 'packages', 'auth-api', 'package.json')) ||
       appModuleText.includes("from '@forgeon/auth-api'"),
+    rbac:
+      fs.existsSync(path.join(rootDir, 'packages', 'rbac', 'package.json')) ||
+      appModuleText.includes("from '@forgeon/rbac'"),
     dbPrisma:
       fs.existsSync(path.join(rootDir, 'packages', 'db-prisma', 'package.json')) ||
       appModuleText.includes("from '@forgeon/db-prisma'"),
@@ -179,6 +182,109 @@ function syncJwtDbPrisma({ rootDir, changedFiles }) {
   return { applied: true };
 }
 
+function syncJwtRbacClaims({ rootDir, changedFiles }) {
+  const authContractsPath = path.join(rootDir, 'packages', 'auth-contracts', 'src', 'index.ts');
+  const authServicePath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.service.ts');
+  const authControllerPath = path.join(rootDir, 'packages', 'auth-api', 'src', 'auth.controller.ts');
+  const readmePath = path.join(rootDir, 'README.md');
+
+  if (!fs.existsSync(authContractsPath) || !fs.existsSync(authServicePath) || !fs.existsSync(authControllerPath)) {
+    return { applied: false, reason: 'auth package files are missing' };
+  }
+
+  let touched = false;
+
+  let authContracts = fs.readFileSync(authContractsPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthContracts = authContracts;
+  if (!authContracts.includes('permissions?: string[];')) {
+    authContracts = authContracts.replace(
+      '  roles: string[];',
+      `  roles: string[];
+  permissions?: string[];`,
+    );
+  }
+  if (authContracts !== originalAuthContracts) {
+    fs.writeFileSync(authContractsPath, `${authContracts.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authContractsPath);
+    touched = true;
+  }
+
+  let authService = fs.readFileSync(authServicePath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthService = authService;
+  authService = authService.replace(
+    /roles: \['user'\],/g,
+    `roles: ['admin'],
+      permissions: ['health.rbac'],`,
+  );
+  if (!authService.includes('permissions: user.permissions,')) {
+    authService = authService.replace(
+      '      roles: user.roles,',
+      `      roles: user.roles,
+      permissions: user.permissions,`,
+    );
+  }
+  if (!authService.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],')) {
+    authService = authService.replace(
+      "      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],",
+      `      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
+      permissions: Array.isArray(payload.permissions) ? payload.permissions : [],`,
+    );
+  }
+  if (!authService.includes('demoPermissions: [')) {
+    authService = authService.replace(
+      "      demoEmail: this.configService.demoEmail,",
+      `      demoEmail: this.configService.demoEmail,
+      demoPermissions: ['health.rbac'],`,
+    );
+  }
+  if (authService !== originalAuthService) {
+    fs.writeFileSync(authServicePath, `${authService.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authServicePath);
+    touched = true;
+  }
+
+  let authController = fs.readFileSync(authControllerPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAuthController = authController;
+  if (!authController.includes('permissions: Array.isArray(payload.permissions) ? payload.permissions : [],')) {
+    authController = authController.replace(
+      "      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],",
+      `      roles: Array.isArray(payload.roles) ? payload.roles : ['user'],
+      permissions: Array.isArray(payload.permissions) ? payload.permissions : [],`,
+    );
+  }
+  if (authController !== originalAuthController) {
+    fs.writeFileSync(authControllerPath, `${authController.trimEnd()}\n`, 'utf8');
+    changedFiles.add(authControllerPath);
+    touched = true;
+  }
+
+  if (fs.existsSync(readmePath)) {
+    let readme = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+    const originalReadme = readme;
+    if (!readme.includes('- RBAC integration: demo auth tokens include `health.rbac` permission')) {
+      const marker = 'Default demo credentials:';
+      if (readme.includes(marker)) {
+        readme = readme.replace(
+          marker,
+          `- RBAC integration: demo auth tokens include \`health.rbac\` permission
+
+Default demo credentials:`,
+        );
+      }
+    }
+    if (readme !== originalReadme) {
+      fs.writeFileSync(readmePath, `${readme.trimEnd()}\n`, 'utf8');
+      changedFiles.add(readmePath);
+      touched = true;
+    }
+  }
+
+  if (!touched) {
+    return { applied: false, reason: 'already synced' };
+  }
+  return { applied: true };
+}
+
 function run() {
   const rootDir = process.cwd();
   const changedFiles = new Set();
@@ -197,6 +303,18 @@ function run() {
     });
   }
 
+  if (detected.jwtAuth && detected.rbac) {
+    summary.push({
+      feature: 'jwt-auth + rbac',
+      result: syncJwtRbacClaims({ rootDir, changedFiles }),
+    });
+  } else {
+    summary.push({
+      feature: 'jwt-auth + rbac',
+      result: { applied: false, reason: 'required modules are not both installed' },
+    });
+  }
+
   console.log('[forgeon:sync-integrations] done');
   for (const item of summary) {
     if (item.result.applied) {

package/templates/module-fragments/rbac/00_title.md

@@ -0,0 +1 @@
+# {{MODULE_LABEL}}

package/templates/module-fragments/rbac/10_overview.md

@@ -0,0 +1,6 @@
+## Overview
+
+- Id: `{{MODULE_ID}}`
+- Category: `{{MODULE_CATEGORY}}`
+- Status: {{MODULE_STATUS}}
+- Description: {{MODULE_DESCRIPTION}}

package/templates/module-fragments/rbac/20_idea.md

@@ -0,0 +1,9 @@
+## Idea / Why
+
+This module adds a minimal authorization layer for backend routes.
+
+It exists to answer one simple question consistently:
+
+- does the current caller have the required role or permission for this endpoint?
+
+The module intentionally stays small. It does not try to become a general policy engine. It provides a stable baseline for backend access checks and leaves more advanced patterns to separate modules if they are ever needed.

package/templates/module-fragments/rbac/30_what_it_adds.md

@@ -0,0 +1,11 @@
+## What It Adds
+
+- `@forgeon/rbac` runtime package
+- `@Roles(...)` decorator
+- `@Permissions(...)` decorator
+- `ForgeonRbacGuard`
+- helper utilities for role and permission checks
+- a protected probe route: `GET /api/health/rbac`
+- a frontend probe button that sends a valid permission header
+
+This module is backend-first. It does not include frontend route guards. If frontend access-control helpers are needed later, they should live in a separate module.

package/templates/module-fragments/rbac/40_how_it_works.md

@@ -0,0 +1,20 @@
+## How It Works
+
+Implementation details:
+
+- decorators store required roles and permissions as Nest metadata
+- `ForgeonRbacGuard` reads that metadata with `Reflector`
+- the guard checks `request.user` first
+- if no user payload is available, it can also read test headers:
+  - `x-forgeon-roles`
+  - `x-forgeon-permissions`
+
+Decision rules in v1:
+
+- roles: any required role is enough
+- permissions: all required permissions must be present
+
+Failure path:
+
+- denied access throws `403`
+- the existing Forgeon error envelope wraps it as `FORBIDDEN`

package/templates/module-fragments/rbac/50_how_to_use.md

@@ -0,0 +1,19 @@
+## How To Use
+
+Install:
+
+```bash
+npx create-forgeon@latest add rbac
+pnpm install
+```
+
+Verify:
+
+1. start the project
+2. click `Check RBAC access` on the generated frontend
+3. the request should return `200`
+
+Manual forbidden-path check:
+
+1. call `GET /api/health/rbac` without the `x-forgeon-permissions` header
+2. the request should return `403`

package/templates/module-fragments/rbac/60_configuration.md

@@ -0,0 +1,9 @@
+## Configuration
+
+This module has no dedicated environment variables in v1.
+
+Behavior is controlled by:
+
+- route decorators (`@Roles`, `@Permissions`)
+- the active request payload (`request.user`)
+- optional testing headers (`x-forgeon-roles`, `x-forgeon-permissions`)

package/templates/module-fragments/rbac/70_operational_notes.md

@@ -0,0 +1,10 @@
+## Operational Notes
+
+Current scope:
+
+- no policy engine
+- no database-backed role or permission store
+- no admin UI
+- no frontend route-guard package in this module
+
+This is a stable baseline module, not a placeholder for a future “v2”. If access-control needs grow later, this module can be extended carefully or paired with a separate specialized module.

package/templates/module-fragments/rbac/90_status_implemented.md

@@ -0,0 +1,3 @@
+## Status
+
+Implemented in the current scaffold.

package/templates/module-presets/rbac/packages/rbac/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@forgeon/rbac",
+  "version": "0.1.0",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}

package/templates/module-presets/rbac/packages/rbac/src/forgeon-rbac.guard.ts

@@ -0,0 +1,91 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import {
+  RBAC_PERMISSIONS_HEADER,
+  RBAC_PERMISSIONS_KEY,
+  RBAC_ROLES_HEADER,
+  RBAC_ROLES_KEY,
+} from './rbac.constants';
+import { hasAllPermissions, hasAnyRole } from './rbac.helpers';
+import { Permission, RbacPrincipal, Role } from './rbac.types';
+
+type HeaderValue = string | string[] | undefined;
+
+type HttpRequestLike = {
+  user?: unknown;
+  headers?: Record<string, HeaderValue>;
+};
+
+@Injectable()
+export class ForgeonRbacGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles =
+      this.reflector.getAllAndOverride<Role[]>(RBAC_ROLES_KEY, [
+        context.getHandler(),
+        context.getClass(),
+      ]) ?? [];
+    const requiredPermissions =
+      this.reflector.getAllAndOverride<Permission[]>(RBAC_PERMISSIONS_KEY, [
+        context.getHandler(),
+        context.getClass(),
+      ]) ?? [];
+
+    if (requiredRoles.length === 0 && requiredPermissions.length === 0) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<HttpRequestLike>();
+    const principal = this.resolvePrincipal(request);
+
+    if (!hasAnyRole(principal, requiredRoles) || !hasAllPermissions(principal, requiredPermissions)) {
+      throw new ForbiddenException({
+        message: 'Access denied',
+        details: {
+          feature: 'rbac',
+          requiredRoles,
+          requiredPermissions,
+        },
+      });
+    }
+
+    return true;
+  }
+
+  private resolvePrincipal(request: HttpRequestLike | undefined): RbacPrincipal {
+    const user = request?.user;
+    if (user && typeof user === 'object') {
+      const principal = user as RbacPrincipal;
+      if (Array.isArray(principal.roles) || Array.isArray(principal.permissions)) {
+        return {
+          roles: Array.isArray(principal.roles) ? principal.roles : [],
+          permissions: Array.isArray(principal.permissions) ? principal.permissions : [],
+        };
+      }
+    }
+
+    const headers = request?.headers;
+    return {
+      roles: this.parseHeaderList(headers?.[RBAC_ROLES_HEADER]),
+      permissions: this.parseHeaderList(headers?.[RBAC_PERMISSIONS_HEADER]),
+    };
+  }
+
+  private parseHeaderList(value: HeaderValue): string[] {
+    const source = Array.isArray(value) ? value.join(',') : value;
+    if (typeof source !== 'string' || source.trim().length === 0) {
+      return [];
+    }
+
+    return source
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean);
+  }
+}

package/templates/module-presets/rbac/packages/rbac/src/forgeon-rbac.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { ForgeonRbacGuard } from './forgeon-rbac.guard';
+
+@Module({
+  providers: [ForgeonRbacGuard],
+  exports: [ForgeonRbacGuard],
+})
+export class ForgeonRbacModule {}

package/templates/module-presets/rbac/packages/rbac/src/index.ts

@@ -0,0 +1,6 @@
+export * from './forgeon-rbac.guard';
+export * from './forgeon-rbac.module';
+export * from './rbac.constants';
+export * from './rbac.decorators';
+export * from './rbac.helpers';
+export * from './rbac.types';

package/templates/module-presets/rbac/packages/rbac/src/rbac.constants.ts

@@ -0,0 +1,4 @@
+export const RBAC_ROLES_KEY = 'forgeon:rbac:roles';
+export const RBAC_PERMISSIONS_KEY = 'forgeon:rbac:permissions';
+export const RBAC_ROLES_HEADER = 'x-forgeon-roles';
+export const RBAC_PERMISSIONS_HEADER = 'x-forgeon-permissions';

package/templates/module-presets/rbac/packages/rbac/src/rbac.decorators.ts

@@ -0,0 +1,11 @@
+import { SetMetadata } from '@nestjs/common';
+import { RBAC_PERMISSIONS_KEY, RBAC_ROLES_KEY } from './rbac.constants';
+import { Permission, Role } from './rbac.types';
+
+export function Roles(...roles: Role[]) {
+  return SetMetadata(RBAC_ROLES_KEY, roles);
+}
+
+export function Permissions(...permissions: Permission[]) {
+  return SetMetadata(RBAC_PERMISSIONS_KEY, permissions);
+}

package/templates/module-presets/rbac/packages/rbac/src/rbac.helpers.ts

@@ -0,0 +1,31 @@
+import { Permission, RbacPrincipal, Role } from './rbac.types';
+
+export function hasRole(principal: RbacPrincipal | null | undefined, role: Role): boolean {
+  const roles = principal?.roles ?? [];
+  return roles.includes(role);
+}
+
+export function hasPermission(
+  principal: RbacPrincipal | null | undefined,
+  permission: Permission,
+): boolean {
+  const permissions = principal?.permissions ?? [];
+  return permissions.includes(permission);
+}
+
+export function hasAnyRole(principal: RbacPrincipal | null | undefined, roles: Role[]): boolean {
+  if (roles.length === 0) {
+    return true;
+  }
+  return roles.some((role) => hasRole(principal, role));
+}
+
+export function hasAllPermissions(
+  principal: RbacPrincipal | null | undefined,
+  permissions: Permission[],
+): boolean {
+  if (permissions.length === 0) {
+    return true;
+  }
+  return permissions.every((permission) => hasPermission(principal, permission));
+}

package/templates/module-presets/rbac/packages/rbac/src/rbac.types.ts

@@ -0,0 +1,7 @@
+export type Role = string;
+export type Permission = string;
+
+export interface RbacPrincipal {
+  roles?: Role[];
+  permissions?: Permission[];
+}

package/templates/module-presets/rbac/packages/rbac/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}