@team-codeme/crud-forge 0.0.0-stage → 1.0.0

package/src/generator/auth-pack.js

@@ -0,0 +1,965 @@
+const fs = require('fs-extra');
+const path = require('path');
+const ejs = require('ejs');
+const { deriveAuthUrls, stripSecretsForGenerate, validateAuthConfig } = require('../config/auth-config');
+
+function isKeycloakAuthEnabled(config) {
+  return config.auth?.provider === 'keycloak';
+}
+
+/**
+ * Live login forms never inherit provisioning credentials from the CLI environment.
+ */
+function resolveSignInPrefill(auth = {}) {
+  const configured = auth.signInPrefill && typeof auth.signInPrefill === 'object' ? auth.signInPrefill : {};
+  if (auth.useMockAuth) {
+    return {
+      username: configured.username || 'demo@crudforge.com',
+      password: configured.password || 'admin',
+    };
+  }
+  return {
+    username: configured.username || '',
+    password: configured.password || '',
+  };
+}
+
+function resolveTokenUrl(auth = {}) {
+  const derived = deriveAuthUrls({ ...auth });
+  if (derived.tokenUrl) {
+    return derived.tokenUrl;
+  }
+  return '/auth/realms/crudforge/protocol/openid-connect/token';
+}
+
+function resolveBrowserTokenUrl(auth = {}) {
+  const realm = auth.realm || 'crudforge';
+  if (!auth.useMockAuth && auth.serverUrl) {
+    return `/realms/${realm}/protocol/openid-connect/token`;
+  }
+  return resolveTokenUrl(auth);
+}
+
+async function applyAuthPack({ outputDir, config, writeOrPreview, folderName, entities = [] }) {
+  if (!isKeycloakAuthEnabled(config) || !config.fuse?.enabled) {
+    return { generated: 0 };
+  }
+
+  const derived = deriveAuthUrls({ ...(config.auth || {}) });
+  const authForGenerate = {
+    ...derived,
+    provision: { ...(derived.provision || {}), enabled: false },
+  };
+  validateAuthConfig({ ...config, auth: authForGenerate }, { requireProvision: false });
+
+  const templatesDir = path.join(__dirname, '..', 'templates', 'angular');
+  const auth = {
+    ...stripSecretsForGenerate(derived),
+    provider: 'keycloak',
+    tokenUrl: resolveBrowserTokenUrl(derived),
+    signInPrefill: resolveSignInPrefill(derived),
+  };
+  const iam = { enabled: true, ...config.iam };
+  const locals = {
+    auth,
+    iam,
+    project: config.project || {},
+    config,
+  };
+
+  const authLayout = [
+    { template: 'current-user.ts', out: 'utils/current-user.ts' },
+    { template: 'auth.utils.ts', out: 'utils/auth.utils.ts' },
+    { template: 'permission-attribute.util.ts', out: 'utils/permission-attribute.util.ts' },
+    { template: 'auth.service.ts', out: 'services/auth.service.ts' },
+    { template: 'access-control.service.ts', out: 'services/access-control.service.ts' },
+    { template: 'keycloak-admin.service.ts', out: 'services/keycloak-admin.service.ts' },
+    { template: 'auth.interceptor.ts', out: 'interceptors/auth.interceptor.ts' },
+    { template: 'auth.guard.ts', out: 'guards/auth.guard.ts' },
+    { template: 'no-auth.guard.ts', out: 'guards/no-auth.guard.ts' },
+    { template: 'landing.guard.ts', out: 'guards/landing.guard.ts' },
+    { template: 'access-ctrl.pipe.ts', out: 'pipes/access-ctrl.pipe.ts' },
+    { template: 'has-permission.directive.ts', out: 'directives/has-permission.directive.ts' },
+    { template: 'index.ts', out: 'index.ts' },
+    {
+      template: 'disabled-account-overlay.component.ts',
+      out: 'components/disabled-account-overlay/disabled-account-overlay.component.ts',
+      html: 'disabled-account-overlay.component.html',
+      css: 'disabled-account-overlay.component.css',
+    },
+  ];
+
+  let generated = 0;
+  const authOutDir = path.join(outputDir, 'src/app/core/auth');
+  for (const entry of authLayout) {
+    const rendered = await renderTemplate(path.join(templatesDir, 'auth', `${entry.template}.ejs`), locals);
+    writeOrPreview(path.join(authOutDir, entry.out), rendered);
+    generated += 1;
+    if (entry.html) {
+      const html = await renderTemplate(path.join(templatesDir, 'auth', `${entry.html}.ejs`), locals);
+      writeOrPreview(path.join(authOutDir, path.dirname(entry.out), entry.html), html);
+      generated += 1;
+    }
+    if (entry.css) {
+      const css = await renderTemplate(path.join(templatesDir, 'auth', `${entry.css}.ejs`), locals);
+      writeOrPreview(path.join(authOutDir, path.dirname(entry.out), entry.css), css);
+      generated += 1;
+    }
+  }
+  writeOrPreview(path.join(authOutDir, 'AGENT_README.md'), renderAuthAgentReadme(locals));
+  generated += 1;
+  removeLegacyFlatAuthFiles(authOutDir);
+
+  const signInTs = await renderTemplate(path.join(templatesDir, 'auth', 'sign-in.ts.ejs'), locals);
+  writeOrPreview(path.join(outputDir, 'src/app/domains/auth/features/sign-in/sign-in.ts'), signInTs);
+  generated += 1;
+
+  patchAppConfig(outputDir, writeOrPreview);
+  patchAppRootOverlay(outputDir, writeOrPreview);
+  patchAdminRoutesGuard(outputDir, config, writeOrPreview);
+  patchLandingAndNoAccess(outputDir, config, writeOrPreview);
+  patchAuthRoutesGuard(outputDir, writeOrPreview);
+  patchSignInHtml(outputDir, writeOrPreview);
+  patchNavigationFilter(outputDir, writeOrPreview);
+  writeOrPreview(path.join(outputDir, 'src/app/domains/admin/layout/ui/user.ts'), await renderTemplate(path.join(templatesDir, 'auth', 'fuse-user.ts.ejs'), locals));
+
+  const accountFile = path.join(outputDir, 'src/app/domains/admin/modules/extras/settings/features/account.ts');
+  if (fs.existsSync(accountFile)) writeOrPreview(accountFile, await renderTemplate(path.join(templatesDir, 'auth', 'fuse-account.ts.ejs'), locals));
+
+  const noAccess = await renderTemplate(path.join(templatesDir, 'iam', 'no-access.component.ts.ejs'), locals);
+  writeOrPreview(
+    path.join(outputDir, 'src/app/domains/admin/modules/extras/no-access/no-access.component.ts'),
+    noAccess
+  );
+  generated += 1;
+
+  if (iam.enabled !== false && iam.users !== false) {
+    generated += await generateIamModule({
+      outputDir,
+      templatesDir,
+      locals,
+      writeOrPreview,
+      folderName,
+      config,
+      entities,
+    });
+  }
+
+  return { generated };
+}
+
+function removeLegacyFlatAuthFiles(authOutDir) {
+  // Older generates wrote auth files flat under core/auth/. Keep only the barrel + docs at root.
+  const keep = new Set(['index.ts', 'AGENT_README.md']);
+  if (!fs.existsSync(authOutDir)) {
+    return;
+  }
+  for (const entry of fs.readdirSync(authOutDir)) {
+    if (keep.has(entry)) continue;
+    const full = path.join(authOutDir, entry);
+    const stat = fs.statSync(full);
+    if (stat.isFile() && /\.(ts|js|map)$/.test(entry)) {
+      fs.removeSync(full);
+    }
+  }
+}
+
+function renderAuthAgentReadme(locals = {}) {
+  const auth = locals.auth || {};
+  const projectName = locals.project?.name || 'CRUDForge App';
+  return `# Auth (Keycloak) — agent guide
+
+> **Generated by \`@crudforge/cli\`** (\`crudforge generate\`) for **${projectName}**.
+> Location: \`src/app/core/auth/\` (alongside \`src/app/core/user-management/\`).
+
+## Purpose
+
+Browser-side Keycloak authentication, HTTP bearer attachment, route guards, and ACL helpers.
+Do **not** put admin passwords or client secrets here. Provisioning stays in the CRUDForge CLI (\`bootstrap\`).
+
+## Layout
+
+\`\`\`
+src/app/core/auth/
+  AGENT_README.md
+  index.ts                         ← public barrel (\`@/app/core/auth\`)
+  services/
+    auth.service.ts                ← sign-in / refresh / sign-out / token storage
+    access-control.service.ts      ← screen + component ACL from JWT + Keycloak attrs
+    keycloak-admin.service.ts      ← Admin REST (users/roles) via Fuse proxy
+  guards/
+    auth.guard.ts                  ← require authenticated session
+    no-auth.guard.ts               ← sign-in only when logged out
+    landing.guard.ts               ← post-login landing / no-access routing
+  interceptors/
+    auth.interceptor.ts            ← Authorization + X-Forwarded-Proto + refresh retry
+  pipes/
+    access-ctrl.pipe.ts            ← \`*ngIf="SCREEN | accessCtrl: 'edit'"\`
+  directives/
+    has-permission.directive.ts
+  utils/
+    auth.utils.ts                  ← JWT helpers
+    permission-attribute.util.ts   ← screen attribute normalize/merge
+  components/
+    disabled-account-overlay/      ← countdown lock UI (auth.disabledAccount.*)
+\`\`\`
+
+Sign-in UI lives under \`src/app/domains/auth/features/sign-in/\` (imports \`AuthService\` from this pack).
+
+## How it works
+
+1. **Sign-in** — password grant against \`environment.sso\` (proxied \`/realms/...\` when live).
+2. **Session** — access/refresh tokens in namespaced storage (\`cforge:{realm}:{clientId}\`). Default idle timeout is \`0\` (stay signed in until logout). Resilient refresh keeps the session on network/5xx; only terminal auth errors clear tokens. Optional focus refresh + cross-tab sync via \`auth.session.*\`.
+3. **HTTP** — \`authInterceptor\` attaches Bearer tokens; refreshes once on 401 when not mock; may start the disabled-account overlay instead of an immediate sign-out.
+4. **ACL** — \`AccessControlService\` combines realm/client roles with user/role screen attributes for nav + \`accessCtrl\` stamps.
+5. **Admin API** — \`KeycloakAdminService\` calls \`/admin/realms/{realm}\` (or mock data when \`useMockAuth\`).
+6. **Disabled account** — when \`auth.disabledAccount.enabled\`, explicit Keycloak “account disabled” grant errors freeze the shell (\`app.ts\` overlay) then sign out after the countdown.
+
+## Current snapshot (safe fields)
+
+- provider: \`${auth.provider || 'keycloak'}\`
+- realm: \`${auth.realm || ''}\`
+- clientId: \`${auth.clientId || ''}\`
+- useMockAuth: \`${auth.useMockAuth ? 'true' : 'false'}\`
+
+## Agent rules
+
+- Prefer importing from \`@/app/core/auth\` (barrel), not deep file paths, unless you need a non-exported helper.
+- Edit CRUDForge templates under \`src/templates/angular/auth/\`, then regenerate — do not treat the testing-area copy as source of truth.
+- Never emit \`clientSecret\` or provision passwords into Angular environments.
+- Keep User Management UI in \`src/app/core/user-management/\`; this pack is the shared auth/ACL substrate.
+
+## Related
+
+- \`src/app/core/user-management/AGENT_README.md\`
+- App \`AGENT_README.md\` / \`docs/ai/ARCHITECTURE.md\`
+- Generator \`QA/KEYCLOAK-BOOTSTRAP.md\`
+`;
+}
+
+function csvEscape(value) {
+  const text = String(value == null ? '' : value);
+  if (/[",\n\r]/.test(text)) {
+    return `"${text.replace(/"/g, '""')}"`;
+  }
+  return text;
+}
+
+function buildScreenAccessCatalog({ entities = [], folderName = 'micro-functions', iam = {} }) {
+  const rows = [];
+  const screens = [];
+  const pushRow = (screenName, screenId, componentName, componentId, componentType, description) => {
+    rows.push({ screenName, screenId, componentName, componentId, componentType, description });
+  };
+  const pushScreen = (screenName, screenId, buttons) => {
+    screens.push({ id: screenId, label: screenName });
+    pushRow(screenName, screenId, 'Screen Access', screenId, 'SCREEN', `${screenName} — screen access.`);
+    for (const button of buttons) {
+      pushRow(
+        screenName,
+        screenId,
+        button.name,
+        button.id,
+        'BUTTON',
+        button.description || `Allows the "${button.name}" action on the ${screenName} screen.`
+      );
+    }
+  };
+
+  // Semantic componentIds (aligned with access-control-tools/lib/id-rules.js).
+  const entityButtons = [
+    { id: 'view', name: 'View' },
+    { id: 'edit', name: 'Edit' },
+    { id: 'delete', name: 'Delete' },
+    { id: 'create', name: 'Create' },
+    { id: 'open-filter', name: 'Filter' },
+    { id: 'toggle-view', name: 'Toggle View' },
+    { id: 'open-columns', name: 'Columns' },
+  ];
+
+  for (const entity of entities) {
+    const kebab = String(entity.name || '')
+      .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+      .replace(/[\s_]+/g, '-')
+      .toLowerCase();
+    const entityFolder = entity.folderName || folderName;
+    const screenId = `${entityFolder}/${kebab}`;
+    const buttons = [...entityButtons];
+    if ((entity.fields || []).some((field) => field.fieldName === 'isActive')) {
+      buttons.push({ id: 'toggle-active', name: 'Toggle Active' });
+    }
+    pushScreen(entity.name, screenId, buttons);
+  }
+
+  if (iam.users !== false) {
+    pushScreen('User Management', 'user-management', [
+      { id: 'create', name: 'Create' },
+      { id: 'view', name: 'View' },
+      { id: 'edit', name: 'Edit' },
+      { id: 'delete', name: 'Delete' },
+      { id: 'change-password', name: 'Change Password' },
+      { id: 'access', name: 'Assign Role Matrix' },
+      { id: 'permissions', name: 'Assign User Matrix' },
+      { id: 'open-columns', name: 'Columns' },
+      { id: 'toggle-view', name: 'Toggle View' },
+      { id: 'copy-username', name: 'Copy Username' },
+      { id: 'copy-email', name: 'Copy Email' },
+      { id: 'toggle-enabled', name: 'Toggle Enabled' },
+      { id: 'roles', name: 'Roles' },
+    ]);
+  }
+  if (iam.roles !== false) {
+    pushScreen('Role Management', 'role-management', [
+      { id: 'toggle-create-form', name: 'Create Role' },
+      { id: 'toggle-create-form-2', name: 'Cancel Create' },
+      { id: 'submit', name: 'Submit Create' },
+      { id: 'sync-holders', name: 'Sync Holders' },
+      { id: 'role-permissions', name: 'Permission Matrix' },
+      { id: 'select-role', name: 'Select Role' },
+      { id: 'search-clear', name: 'Clear Role Search' },
+      { id: 'go-back-to-list', name: 'Back to Roles' },
+    ]);
+    pushScreen('User Select Dialog', 'user-select-dialog', [
+      { id: 'on-close', name: 'Close' },
+      { id: 'clear-search', name: 'Clear Search' },
+      { id: 'assign-user', name: 'Assign User' },
+    ]);
+  }
+  if (iam.rolePermissions !== false) {
+    pushScreen('Role Permissions', 'role-permissions', [{ id: 'toggle', name: 'Toggle Grant' }]);
+  }
+
+  for (const extra of iam.screens || []) {
+    if (!extra || screens.some((screen) => screen.id === extra)) continue;
+    pushScreen(String(extra).split('/').pop()?.replace(/-/g, ' ') || extra, String(extra), []);
+  }
+
+  const header = 'screenName,screenId,componentName,componentId,componentType,description';
+  const csv = [
+    header,
+    ...rows.map((row) =>
+      [row.screenName, row.screenId, row.componentName, row.componentId, row.componentType, row.description]
+        .map(csvEscape)
+        .join(',')
+    ),
+  ].join('\n');
+
+  return { csv: `${csv}\n`, screens, rows };
+}
+
+async function generateIamModule({ outputDir, templatesDir, locals, writeOrPreview, folderName, config, entities = [] }) {
+  const iamRoot = path.join(outputDir, 'src/app/core/user-management');
+  const catalog = buildScreenAccessCatalog({
+    entities,
+    folderName: folderName || 'micro-functions',
+    iam: locals.iam || {},
+  });
+  locals = { ...locals, managedScreens: catalog.screens };
+
+  // PMB-style ACL registry — matrices load this CSV at runtime.
+  writeOrPreview(path.join(outputDir, 'public/assets/screen-components.csv'), catalog.csv);
+
+  /** Flat template name → foldered output under src/app/core/user-management */
+  const iamLayout = [
+    { template: 'user-management.routes.ts', out: 'user-management.routes.ts' },
+    { template: 'screen-catalog.ts', out: 'shared/screen-catalog.ts' },
+    {
+      template: 'user-list.component.ts',
+      out: 'users/user-list/user-list.component.ts',
+      html: 'user-list.component.html',
+      scss: 'user-list.component.scss',
+    },
+    {
+      template: 'user-form.component.ts',
+      out: 'users/user-form/user-form.component.ts',
+      html: 'user-form.component.html',
+    },
+    {
+      template: 'user-detail.component.ts',
+      out: 'users/user-detail/user-detail.component.ts',
+      html: 'user-detail.component.html',
+    },
+    {
+      template: 'change-password.component.ts',
+      out: 'users/change-password/change-password.component.ts',
+      html: 'change-password.component.html',
+    },
+  ];
+  if (locals.iam.roles !== false) {
+    iamLayout.push({
+      template: 'role-list.component.ts',
+      out: 'roles/role-list/role-list.component.ts',
+      html: 'role-list.component.html',
+      scss: 'role-list.component.scss',
+    });
+  }
+  if (locals.iam.rolePermissions !== false) {
+    iamLayout.push({
+      template: 'role-permission-matrix.component.ts',
+      out: 'matrices/role-permission-matrix/role-permission-matrix.component.ts',
+      html: 'role-permission-matrix.component.html',
+      scss: 'role-permission-matrix.component.scss',
+    });
+  }
+  if (locals.iam.userAccess !== false) {
+    iamLayout.push({
+      template: 'user-access-matrix.component.ts',
+      out: 'matrices/user-access-matrix/user-access-matrix.component.ts',
+      html: 'user-access-matrix.component.html',
+      scss: 'user-access-matrix.component.scss',
+    });
+  }
+  if (locals.iam.userPermissions !== false) {
+    iamLayout.push({
+      template: 'user-permission-matrix.component.ts',
+      out: 'matrices/user-permission-matrix/user-permission-matrix.component.ts',
+      html: 'user-permission-matrix.component.html',
+      scss: 'user-permission-matrix.component.scss',
+    });
+  }
+
+  let generatedFiles = 0;
+
+  // Shared matrix helpers (PMB-aligned CSV clustering, sounds, highlight, skeleton).
+  for (const shared of [
+    'permission-matrix-sound.ts',
+    'screen-matrix.util.ts',
+    'role-display.util.ts',
+    'text-highlight.pipe.ts',
+    'role-permission-skeleton.component.ts',
+    'confirm-dialog.component.ts',
+    'screen-navigation-map.ts',
+    'screen-navigation.registry.ts',
+    'matrix-hierarchy.util.ts',
+  ]) {
+    const rendered = await renderTemplate(path.join(templatesDir, 'iam', 'shared', `${shared}.ejs`), locals);
+    writeOrPreview(path.join(iamRoot, 'shared', shared), rendered);
+    generatedFiles += 1;
+  }
+
+  // Empty hierarchy until access-control sync generates screen-navigation-map.json
+  {
+    const navAsset = path.join(outputDir, 'public/assets/screen-navigation-map.json');
+    const emptyNav =
+      JSON.stringify(
+        {
+          version: 1,
+          generatedAt: null,
+          pages: [],
+          unresolved: [],
+          stats: { pageCount: 0, embedEdgeCount: 0, unresolvedCount: 0 },
+        },
+        null,
+        2
+      ) + '\n';
+    writeOrPreview(navAsset, emptyNav);
+    generatedFiles += 1;
+  }
+
+  // Role Management subcomponents (PMB role-management layout).
+  if (locals.iam.roles !== false) {
+    const roleMgmtParts = [
+      {
+        base: 'role-header',
+        outDir: 'roles/role-list/components/role-header',
+        files: ['ts', 'html'],
+      },
+      {
+        base: 'role-users',
+        outDir: 'roles/role-list/components/role-users',
+        files: ['ts', 'html'],
+      },
+      {
+        base: 'role-inheritance',
+        outDir: 'roles/role-list/components/role-inheritance',
+        files: ['ts', 'html'],
+        when: () => locals.iam.inheritance !== false,
+      },
+      {
+        base: 'role-permissions-panel',
+        outDir: 'roles/role-list/components/role-permissions-panel',
+        files: ['ts', 'html', 'css'],
+        when: () => locals.iam.rolePermissions !== false,
+      },
+      {
+        base: 'user-select-dialog',
+        outDir: 'roles/role-list/components/user-select-dialog',
+        files: ['ts', 'html'],
+      },
+    ];
+    for (const part of roleMgmtParts) {
+      if (part.when && !part.when()) continue;
+      for (const ext of part.files) {
+        const templateName =
+          ext === 'ts'
+            ? `${part.base}.component.ts.ejs`
+            : ext === 'html'
+              ? `${part.base}.component.html.ejs`
+              : `${part.base}.component.css.ejs`;
+        const outName =
+          ext === 'ts'
+            ? `${part.base}.component.ts`
+            : ext === 'html'
+              ? `${part.base}.component.html`
+              : `${part.base}.component.css`;
+        const rendered = await renderTemplate(
+          path.join(templatesDir, 'iam', 'role-management', templateName),
+          locals
+        );
+        writeOrPreview(path.join(iamRoot, part.outDir, outName), rendered);
+        generatedFiles += 1;
+      }
+    }
+  }
+
+  // Ship PMB-style toggle sounds into public assets.
+  const soundSrcDir = path.join(__dirname, '..', 'templates', 'fuse-packs', 'iam-assets', 'sound');
+  const soundDestDir = path.join(outputDir, 'public', 'assets', 'sound');
+  if (fs.existsSync(soundSrcDir)) {
+    for (const file of fs.readdirSync(soundSrcDir)) {
+      const from = path.join(soundSrcDir, file);
+      if (!fs.statSync(from).isFile()) continue;
+      const to = path.join(soundDestDir, file);
+      if (config.dryRun) {
+        writeOrPreview(to, `[binary:${file}]`);
+      } else {
+        fs.ensureDirSync(soundDestDir);
+        fs.copyFileSync(from, to);
+      }
+    }
+  }
+
+  for (const entry of iamLayout) {
+    const rendered = await renderTemplate(path.join(templatesDir, 'iam', `${entry.template}.ejs`), locals);
+    writeOrPreview(path.join(iamRoot, entry.out), rendered);
+    generatedFiles += 1;
+    if (entry.html) {
+      const htmlRendered = await renderTemplate(path.join(templatesDir, 'iam', `${entry.html}.ejs`), locals);
+      const htmlOut = path.join(path.dirname(entry.out), entry.html);
+      writeOrPreview(path.join(iamRoot, htmlOut), htmlRendered);
+      generatedFiles += 1;
+    }
+    if (entry.scss) {
+      const scssRendered = await renderTemplate(path.join(templatesDir, 'iam', `${entry.scss}.ejs`), locals);
+      const scssOut = path.join(path.dirname(entry.out), entry.scss);
+      writeOrPreview(path.join(iamRoot, scssOut), scssRendered);
+      generatedFiles += 1;
+    }
+  }
+
+  writeOrPreview(path.join(iamRoot, 'AGENT_README.md'), renderUserManagementAgentReadme(locals));
+  generatedFiles += 2; // CSV + AGENT_README
+
+  registerIamRoutes(outputDir, config, folderName, writeOrPreview);
+  registerIamNavigation(outputDir, config, folderName, writeOrPreview);
+  return generatedFiles;
+}
+
+function renderUserManagementAgentReadme(locals = {}) {
+  const iam = locals.iam || {};
+  const auth = locals.auth || {};
+  const projectName = locals.project?.name || 'CRUDForge App';
+  const features = [
+    '- **Users** (`users/user-list`) — list / search / create / edit / view / delete Keycloak users; drawer + page modes',
+    '- **User form** (`users/user-form`) — create/edit identity fields via `KeycloakAdminService`',
+    '- **User detail** (`users/user-detail`) — read-only profile with links to role/screen matrices',
+    '- **Change password** (`users/change-password`) — dialog to set/reset password (temporary flag supported)',
+  ];
+  if (iam.roles !== false) {
+    features.push(
+      '- **Roles** (`roles/role-list`) — PMB Role Management: master-detail list, create, duplicate, assign users, sync holders, screen-permission summary'
+    );
+  }
+  if (iam.rolePermissions !== false) {
+    features.push(
+      '- **Role permissions** (`matrices/role-permission-matrix`) — map roles → screen IDs; UI locks until role write + holder sync; grant/revoke sounds'
+    );
+  }
+  if (iam.userAccess !== false) {
+    features.push(
+      '- **User access** (`matrices/user-access-matrix`) — assign realm roles to a user (lock + sounds while syncing)'
+    );
+  }
+  if (iam.userPermissions !== false) {
+    features.push(
+      '- **User permissions** (`matrices/user-permission-matrix`) — map a user → screen IDs (lock + sounds while saving)'
+    );
+  }
+
+  return `# User Management (IAM) — agent guide
+
+> **Generated by \`@crudforge/cli\`** (\`crudforge generate\`) for **${projectName}**.
+> Location: \`src/app/core/user-management/\` (not under \`domains/admin/modules/apps\`).
+
+## Purpose
+
+Angular overlay for Keycloak identity administration. It is **not** a JDL entity.
+Do not model User/Role in the domain JDL; keep IAM here and behind \`auth.provider: keycloak\` + \`iam.enabled\`.
+
+## Layout
+
+\`\`\`
+src/app/core/user-management/
+  AGENT_README.md
+  user-management.routes.ts
+  shared/screen-catalog.ts
+  users/{user-list,user-form,user-detail,change-password}/
+    *.component.ts + *.component.html   ← Angular-style split templates
+  roles/role-list/
+    role-list.component.{ts,html,scss}
+    components/{role-header,role-users,role-inheritance,role-permissions-panel,user-select-dialog}/
+  matrices/{role-permission-matrix,user-access-matrix,user-permission-matrix}/
+  shared/{permission-matrix-sound,screen-matrix.util,confirm-dialog,role-display,…}
+  public/assets/sound/{apple-play,remove}.mp3
+\`\`\`
+
+Each screen is a standalone Angular component (\`templateUrl\`, not inline \`template\`).
+
+Auth primitives stay next door in \`src/app/core/auth/\` (see that folder's \`AGENT_README.md\` — services, guards, interceptors, pipes).
+
+## Features enabled in this generate
+
+${features.join('\n')}
+
+## How it works
+
+1. **Routing** — Admin shell loads \`@/app/core/user-management/user-management.routes\` under path \`user-management\`. Public URLs remain \`/admin/user-management/**\`.
+2. **API** — UI calls \`KeycloakAdminService\`, which talks to Keycloak Admin REST through the Fuse proxy (\`/admin/realms\`, \`/realms\`). Browser never embeds admin passwords or client secrets.
+3. **ACL** — Buttons/screens use \`accessCtrl\` pipe + \`data-screen-id="user-management"\` (and related screen IDs). \`AccessControlService\` filters nav and enforces admin roles from \`environment.adminRoles\`.
+4. **Screen catalog** — \`shared/screen-catalog.ts\` merges nav IDs with IAM screens so permission matrices stay aligned with the sidebar.
+5. **Mock vs live** — \`environment.useMockAuth\` drives mock Keycloak data for Playwright; live mode uses \`auth.serverUrl\` / proxied Admin REST.
+
+## Current auth snapshot (safe fields only)
+
+- provider: \`${auth.provider || 'keycloak'}\`
+- realm: \`${auth.realm || ''}\`
+- clientId: \`${auth.clientId || ''}\`
+- useMockAuth: \`${auth.useMockAuth ? 'true' : 'false'}\`
+
+## Agent rules
+
+- Edit generator templates under CRUDForge \`src/templates/angular/iam/\`, then regenerate — do not treat a testing-area copy as source of truth.
+- Preserve \`// cforge-\` merge zones elsewhere; this pack is overwritten as a unit when IAM is regenerated.
+- Never write Keycloak admin credentials into these components or \`environment.ts\`.
+- Keep new/edit UX consistent with entity \`formMode\` patterns where drawers are used.
+- Nav label group is **User Management**; do not rename to Identity without updating screen IDs + ACL stamps together.
+
+## Related docs
+
+- App-level: \`AGENT_README.md\`, \`docs/ai/ARCHITECTURE.md\`, \`docs/ai/ROUTES.md\`
+- Generator QA: \`QA/KEYCLOAK-BOOTSTRAP.md\` in the CRUDForge repo
+`;
+}
+
+function registerIamRoutes(outputDir, config, folderName, writeOrPreview) {
+  const routesFilePath = path.join(outputDir, config.fuse.routesFile || 'src/app/domains/admin/routes.ts');
+  if (!fs.existsSync(routesFilePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(routesFilePath, 'utf8');
+  const iamRoute = `      {\n        path: 'user-management',\n        loadChildren: () => import('@/app/core/user-management/user-management.routes'),\n      },`;
+
+  // Migrate older apps/*/identity/user-management imports to core.
+  const legacyImport =
+    /loadChildren:\s*\(\)\s*=>\s*import\(['"]\.\/modules\/apps\/[^'"]+\/identity\/user-management\/user-management\.routes['"]\)/;
+  if (legacyImport.test(content)) {
+    content = content.replace(
+      legacyImport,
+      "loadChildren: () => import('@/app/core/user-management/user-management.routes')"
+    );
+    writeOrPreview(routesFilePath, content);
+    return;
+  }
+
+  if (content.includes("path: 'user-management'")) {
+    return;
+  }
+  if (content.includes('// cforge-routes-start')) {
+    content = content.replace('// cforge-routes-start', `// cforge-routes-start\n${iamRoute}`);
+  } else {
+    content = content.replace('children: [', `children: [\n${iamRoute}`);
+  }
+  writeOrPreview(routesFilePath, content);
+}
+
+function registerIamNavigation(outputDir, config, folderName, writeOrPreview) {
+  const navFilePath = path.join(outputDir, config.fuse.navigationFile || 'src/app/domains/admin/layout/data/navigation.ts');
+  if (!fs.existsSync(navFilePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(navFilePath, 'utf8');
+  const iam = config.iam || {};
+  const children = [`        {\n          id: 'user-management',\n          label: 'Users',\n          icon: 'users',\n          route: '/admin/user-management'\n        }`];
+  if (iam.roles !== false) {
+    children.push(`        {\n          id: 'role-management',\n          label: 'Roles',\n          icon: 'shield',\n          route: '/admin/user-management/roles'\n        }`);
+  }
+  if (iam.rolePermissions !== false) {
+    children.push(`        {\n          id: 'role-permissions',\n          label: 'Role permissions',\n          icon: 'lock',\n          route: '/admin/user-management/role-permissions'\n        }`);
+  }
+  const block = `    {\n      id: 'identity-group',\n      label: 'User Management',\n      icon: 'users',\n      children: [\n${children.join(',\n')}\n      ]\n    },`;
+
+  if (content.includes("id: 'identity-group'")) {
+    content = content.replace(
+      /id: 'identity-group',\n\s*label: '[^']*',(?:\n\s*description: '[^']*',)?\n\s*icon: '[^']*'/,
+      `id: 'identity-group',\n      label: 'User Management',\n      icon: 'users'`
+    );
+    writeOrPreview(navFilePath, content);
+    return;
+  }
+
+  if (content.includes('// cforge-navigation-start')) {
+    content = content.replace('// cforge-navigation-start', `// cforge-navigation-start\n${block}`);
+  } else if (content.includes('export const NAVIGATION: NavigationItem[] = [')) {
+    content = content.replace(
+      'export const NAVIGATION: NavigationItem[] = [',
+      `export const NAVIGATION: NavigationItem[] = [\n${block}`
+    );
+  }
+  writeOrPreview(navFilePath, content);
+}
+
+function patchAppConfig(outputDir, writeOrPreview) {
+  const filePath = path.join(outputDir, 'src/app/app.config.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  let content = fs.readFileSync(filePath, 'utf8');
+  if (!content.includes('authInterceptor')) {
+    content = content.replace(
+      "import { provideHttpClient, withFetch } from '@angular/common/http';",
+      "import { provideHttpClient, withFetch, withInterceptors } from '@angular/common/http';\nimport { authInterceptor } from '@/app/core/auth';"
+    );
+    content = content.replace(
+      'provideHttpClient(withFetch())',
+      'provideHttpClient(withFetch(), withInterceptors([authInterceptor]))'
+    );
+  }
+  writeOrPreview(filePath, content);
+}
+
+/**
+ * Wire AuthService + DisabledAccountOverlayComponent into Fuse root app.ts (PMB pattern).
+ * Overlay only appears when AuthService flips disabledAccountOverlayVisible (flag-gated in env).
+ */
+function patchAppRootOverlay(outputDir, writeOrPreview) {
+  const filePath = path.join(outputDir, 'src/app/app.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  let content = fs.readFileSync(filePath, 'utf8');
+  if (content.includes('DisabledAccountOverlayComponent')) {
+    return;
+  }
+
+  if (!content.includes("import { Component, inject } from '@angular/core';")) {
+    content = content.replace(
+      "import { Component } from '@angular/core';",
+      "import { Component, inject } from '@angular/core';"
+    );
+  }
+  if (!content.includes('from "@/app/core/auth"') && !content.includes("from '@/app/core/auth'")) {
+    content = content.replace(
+      "import { RouterOutlet } from '@angular/router';",
+      "import { RouterOutlet } from '@angular/router';\nimport { AuthService, DisabledAccountOverlayComponent } from '@/app/core/auth';\nimport { environment } from '@/environments/environment';"
+    );
+  }
+
+  content = content.replace(
+    /imports:\s*\[\s*RouterOutlet\s*\]/,
+    'imports: [RouterOutlet, DisabledAccountOverlayComponent]'
+  );
+
+  content = content.replace(
+    /template:\s*`\s*<router-outlet\s*\/>\s*`/,
+    `template: \`
+    <div
+      class="flex min-h-full w-full flex-auto flex-col"
+      [class.pointer-events-none]="authService.disabledAccountOverlayVisible()"
+      [class.select-none]="authService.disabledAccountOverlayVisible()"
+    >
+      <router-outlet />
+    </div>
+
+    @if (authService.disabledAccountOverlayVisible()) {
+      <cforge-disabled-account-overlay
+        [countdown]="authService.disabledAccountOverlayCountdown()"
+        [totalCountdownSeconds]="disabledCountdownSeconds"
+        [message]="disabledAccountMessage"
+      />
+    }
+  \``
+  );
+
+  content = content.replace(
+    /export class App \{\s*\}/,
+    `export class App {
+  readonly authService = inject(AuthService);
+  readonly disabledCountdownSeconds =
+    Number((environment as { disabledAccountCountdownSeconds?: number }).disabledAccountCountdownSeconds) || 20;
+  readonly disabledAccountMessage =
+    (environment as { disabledAccountMessage?: string }).disabledAccountMessage ||
+    'Your account has been disabled. Please contact your administrator.';
+}`
+  );
+
+  writeOrPreview(filePath, content);
+}
+
+function patchLandingAndNoAccess(outputDir, config, writeOrPreview) {
+  const filePath = path.join(outputDir, config.fuse.routesFile || 'src/app/domains/admin/routes.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8');
+  if (!content.includes('LandingGuard')) {
+    content = `import { LandingGuard } from '@/app/core/auth';\n${content}`;
+  }
+
+  content = content.replace(
+    "{ path: '', pathMatch: 'full', redirectTo: '/auth/sign-in' }",
+    "{ path: '', pathMatch: 'full', redirectTo: 'welcome' }"
+  );
+
+  if (!content.includes('canActivate: [LandingGuard]')) {
+    content = content.replace(
+      /path: 'welcome',\n(\s*)loadComponent: \(\) => import\('\.\/modules\/extras\/welcome\/welcome\.component'\)/,
+      "path: 'welcome',\n$1canActivate: [LandingGuard],\n$1loadComponent: () => import('./modules/extras/welcome/welcome.component')"
+    );
+  }
+
+  if (!content.includes("path: 'no-access'")) {
+    content = content.replace(
+      /path: 'welcome',[\s\S]*?welcome\.component'\)\n(\s*)\},/,
+      (match) =>
+        `${match}\n        {\n          path: 'no-access',\n          loadComponent: () => import('./modules/extras/no-access/no-access.component')\n        },`
+    );
+  }
+
+  writeOrPreview(filePath, content);
+}
+
+function patchAdminRoutesGuard(outputDir, config, writeOrPreview) {
+  const filePath = path.join(outputDir, config.fuse.routesFile || 'src/app/domains/admin/routes.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  let content = fs.readFileSync(filePath, 'utf8');
+  if (!content.includes('AuthGuard')) {
+    content = `import { AuthGuard } from '@/app/core/auth';\n${content}`;
+    content = content.replace(
+      'component: AdminLayout,',
+      'component: AdminLayout,\n    canActivate: [AuthGuard],\n    canActivateChild: [AuthGuard],'
+    );
+  }
+  writeOrPreview(filePath, content);
+}
+
+function patchAuthRoutesGuard(outputDir, writeOrPreview) {
+  const filePath = path.join(outputDir, 'src/app/domains/auth/routes.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  let content = fs.readFileSync(filePath, 'utf8');
+  if (!content.includes('NoAuthGuard')) {
+    content = `import { NoAuthGuard } from '@/app/core/auth';\n${content}`;
+    content = content.replace(
+      "path: 'sign-in',\n        loadComponent: () => import('./features/sign-in/sign-in'),",
+      "path: 'sign-in',\n        canActivate: [NoAuthGuard],\n        loadComponent: () => import('./features/sign-in/sign-in'),"
+    );
+  }
+  writeOrPreview(filePath, content);
+}
+
+function patchSignInHtml(outputDir, writeOrPreview) {
+  const filePath = path.join(outputDir, 'src/app/domains/auth/features/sign-in/sign-in.html');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  let html = fs.readFileSync(filePath, 'utf8');
+  html = html.replace('<mat-label>Email address</mat-label>', '<mat-label>Username or email</mat-label>');
+  if (!html.includes('signInError()')) {
+    html = html.replace(
+      '<!-- Submit button -->',
+      `@if (signInError()) {\n        <div class="text-sm text-red-600">{{ signInError() }}</div>\n        }\n\n        <!-- Submit button -->`
+    );
+  }
+  // Prefer button click over native form submit (avoids SPA reload with ?ng.form… query params).
+  if (html.includes('type="submit"') && !html.includes('(click)="signIn($event)"')) {
+    html = html.replace(
+      /type="submit"\s*\n(\s*)matButton="filled"\s*\n(\s*)class="mt-6 w-full"\s*\n(\s*)\[disabled\]="signInForm\(\)\.invalid\(\)"/,
+      'type="button"\n$1matButton="filled"\n$2class="mt-6 w-full"\n$3[disabled]="signInForm().invalid()"\n$3(click)="signIn($event)"'
+    );
+  }
+  writeOrPreview(filePath, html);
+}
+
+function patchNavigationFilter(outputDir, writeOrPreview) {
+  const filePath = path.join(outputDir, 'src/app/domains/admin/layout/ui/navigation.ts');
+  if (!fs.existsSync(filePath) || fs.readFileSync(filePath, 'utf8').includes('AccessControlService')) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8');
+  content = content.replace(
+    "import {\n  NAVIGATION,\n  NavigationItem,\n} from '@/app/domains/admin/layout/data/navigation';",
+    "import {\n  NAVIGATION,\n  NavigationItem,\n} from '@/app/domains/admin/layout/data/navigation';\nimport { AccessControlService } from '@/app/core/auth';"
+  );
+  content = content.replace(
+    'private router = inject(Router);',
+    'private router = inject(Router);\n  private accessControl = inject(AccessControlService);'
+  );
+  content = content.replace(
+    'protected navigation = signal<NavigationItem[]>(NAVIGATION);',
+    'protected navigation = signal<NavigationItem[]>([]);'
+  );
+  content = content.replace(
+    `constructor() {
+    // Expand active route on initial load
+    effect(() => {
+      const navigationEnd = this.navigationEnd();
+      if (!navigationEnd) {
+        return;
+      }
+
+      this.navigation.set(this.expandActiveRoute(this.navigation()));
+    });
+  }`,
+    `constructor() {
+    effect(() => {
+      const loaded = this.accessControl.isLoaded() || this.accessControl.isUserAdmin();
+      const items = loaded ? this.filterNavigation(NAVIGATION) : [];
+      const navigationEnd = this.navigationEnd();
+      this.navigation.set(navigationEnd ? this.expandActiveRoute(items) : items);
+    });
+  }
+
+  private filterNavigation(items: NavigationItem[]): NavigationItem[] {
+    const next: NavigationItem[] = [];
+    for (const item of items) {
+      const children = item.children?.length ? this.filterNavigation(item.children) : item.children;
+      if (item.route && item.id && !this.accessControl.hasScreenAccess(item.id)) {
+        continue;
+      }
+      if (children && children.length === 0 && !item.route) {
+        continue;
+      }
+      next.push({ ...item, children });
+    }
+    return next;
+  }`
+  );
+  writeOrPreview(filePath, content);
+}
+
+async function renderTemplate(templatePath, locals) {
+  const template = await fs.readFile(templatePath, 'utf8');
+  return ejs.render(template, locals, { filename: templatePath });
+}
+
+module.exports = {
+  applyAuthPack,
+  isKeycloakAuthEnabled,
+};