@trustnext/ztam-analyzer 1.0.0

package/lib/report-generator.js

@@ -0,0 +1,542 @@
+'use strict';
+
+/**
+ * report-generator.js  (v2)
+ *
+ * Gap analysis, strategy selection, complexity scoring, and all output formats.
+ * Language: bridges, never rewrites. ZTAM *provides* req.user — the report
+ * recommends how to connect that to whatever pattern the client already uses.
+ *
+ * READ-ONLY. Pure function — no side effects.
+ */
+
+// ── Conflict / Gap Rules ──────────────────────────────────────────────────────
+// Each rule: { id, check(result), conflict{title, detail}, bridgeHint }
+
+const GAP_RULES = [
+  {
+    id: 'session_bridge',
+    check({ auth }) {
+      return auth.userObjectPattern === 'req.session.user';
+    },
+    conflict: {
+      title: 'Session bridge needed',
+      detail: 'App reads from req.session.user; ZTAM provides req.user after cookie verification.',
+    },
+    bridgeHint: 'Populate req.session.user from req.user in a bridge middleware (1 file).',
+  },
+  {
+    id: 'custom_context_bridge',
+    check({ auth }) {
+      return ['req.auth', 'req.currentUser'].includes(auth.userObjectPattern);
+    },
+    conflict: {
+      title: 'Custom context bridge needed',
+      detail: `App reads from ${'{auth.userObjectPattern}'}; ZTAM provides req.user after cookie verification.`,
+    },
+    bridgeHint: 'Map req.user to the custom context key in a bridge middleware (1 file).',
+  },
+  {
+    id: 'role_mapping',
+    check({ roles }) {
+      return roles.patterns.includes('Role string comparison');
+    },
+    conflict: {
+      title: 'Role mapping needed',
+      detail: 'App checks user.role (string scalar); ZTAM provides user.roles[] (array). Review how role information should be mapped.',
+    },
+    bridgeHint: 'Add: req.user.role = req.user.roles?.[0]  inside the bridge middleware.',
+  },
+  {
+    id: 'local_login',
+    check({ auth }) { return auth.hasLocalLogin; },
+    conflict: {
+      title: 'Local Authentication Review Required',
+      detail: 'The ZTAM Gateway handles login. The local /login handler should be reviewed and likely redirected to /ztam/login.',
+    },
+    bridgeHint: 'Review local /login handler — redirect to /ztam/login if appropriate.',
+  },
+  {
+    id: 'local_logout',
+    check({ auth }) { return auth.hasLocalLogout; },
+    conflict: {
+      title: 'Local logout route detected',
+      detail: 'The ZTAM Gateway terminates sessions. The local /logout handler should redirect to /ztam/logout.',
+    },
+    bridgeHint: 'Update /logout to res.redirect(\'/ztam/logout\').',
+  },
+  {
+    id: 'jwt_verify_redundant',
+    check({ auth, packageJson }) { 
+      if (packageJson && packageJson.name === '@trustnext/ztam-middleware') return false;
+      return auth.libraries.includes('JWT (jsonwebtoken)'); 
+    },
+    conflict: {
+      title: 'JWT verification detected',
+      detail: 'Review whether this overlaps with ZTAM authentication responsibilities.',
+    },
+    bridgeHint: 'Review manual jwt.verify() calls from application code.',
+  },
+  {
+    id: 'passport_local_conflict',
+    check({ auth }) { return auth.libraries.includes('Passport'); },
+    conflict: {
+      title: 'Passport local authentication detected',
+      detail: 'Review whether this overlaps with ZTAM authentication responsibilities.',
+    },
+    bridgeHint: 'Review whether Passport local strategy is still required once ZTAM handles identity.',
+  },
+  {
+    id: 'keycloak_adapter_conflict',
+    check({ auth }) { return auth.libraries.includes('Keycloak'); },
+    conflict: {
+      title: 'Existing Keycloak adapter conflicts',
+      detail: 'ZTAM manages Keycloak centrally. A local keycloak-connect adapter will conflict.',
+    },
+    bridgeHint: 'Remove keycloak-connect from the application — the ZTAM Gateway owns the Keycloak integration.',
+  },
+];
+
+// ── Strategy Selection ────────────────────────────────────────────────────────
+
+function selectStrategy(detectionResult, conflicts) {
+  const { auth, session } = detectionResult;
+  const conflictIds = new Set(conflicts.map(c => c.id));
+
+  if (auth.userObjectPattern === 'req.user' && !conflictIds.has('role_mapping')) {
+    return {
+      id: 'direct_integration',
+      title: 'Direct Integration',
+      reason: 'Application already uses req.user — ZTAM middleware populates it directly.',
+      considerations: [
+        'Directly mount @trustnext/ztam-middleware before protected routes.',
+        'No custom mapping layer is required.'
+      ]
+    };
+  }
+
+  if (auth.userObjectPattern === 'req.session.user' && session.approach === 'express-session') {
+    return {
+      id: 'session_bridge',
+      title: 'Session Bridge',
+      reason: `Application uses express-session with ${auth.userObjectPattern}. ZTAM provides req.user — a bridge populates the session without changing existing auth middleware.`,
+      considerations: [
+        'Review how authenticated user information should be exposed through the application\'s existing session model.',
+        conflictIds.has('role_mapping') ? 'Review how role information should be represented within the application\'s authorization model.' : null
+      ].filter(Boolean)
+    };
+  }
+
+  if (['req.auth', 'req.currentUser'].includes(auth.userObjectPattern)) {
+    const key = auth.userObjectPattern;
+    return {
+      id: 'custom_context_bridge',
+      title: 'Custom Context Bridge',
+      reason: `Application uses ${key}. ZTAM provides req.user — a bridge maps it to the expected key.`,
+      considerations: [
+        'Review how authenticated user information should be mapped to the expected custom context property.'
+      ]
+    };
+  }
+
+  return {
+    id: 'greenfield_integration',
+    title: 'Greenfield Integration',
+    reason: 'No existing authentication pattern detected. Add ZTAM middleware directly.',
+    considerations: [
+      'Mount @trustnext/ztam-middleware to establish the req.user context.',
+      'Protect sensitive routes using the provided protect() guards.'
+    ]
+  };
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+function generateReport(detectionResult) {
+  const { framework, allFrameworks, auth, session, roles, allAffectedFiles, referenceCounts, projectPath } = detectionResult;
+
+  // Resolve dynamic conflict detail (template strings with runtime values)
+  const conflicts = GAP_RULES
+    .filter(rule => rule.check(detectionResult))
+    .map(rule => ({
+      id:         rule.id,
+      title:      rule.conflict.title,
+      detail:     rule.conflict.detail.replace('{auth.userObjectPattern}', auth.userObjectPattern || ''),
+      bridgeHint: rule.bridgeHint,
+    }));
+
+  const strategy   = selectStrategy(detectionResult, conflicts);
+
+  // Action Plan items — derived from detected conflicts
+  const requiredChanges = [];
+  requiredChanges.push({ title: 'Install @trustnext/ztam-middleware', description: null });
+
+  const conflictIds = new Set(conflicts.map(c => c.id));
+
+  if (conflictIds.has('session_bridge')) {
+    requiredChanges.push({
+      title: 'Session Mapping',
+      description: `The application uses ${auth.userObjectPattern}.\nZTAM provides authenticated users through req.user.\nReview how authenticated user context should be mapped.`
+    });
+  }
+
+  if (conflictIds.has('custom_context_bridge')) {
+    requiredChanges.push({
+      title: 'User Context Mapping',
+      description: `The application uses ${auth.userObjectPattern}.\nZTAM provides authenticated users through req.user.\nReview how the authenticated user context should be exposed to the application.`
+    });
+  }
+
+  if (conflictIds.has('role_mapping')) {
+    requiredChanges.push({
+      title: 'Role Representation',
+      description: 'The application checks roles as a string scalar (user.role).\nZTAM provides roles as an array (user.roles[]).\nReview how role information should be represented within the application.'
+    });
+  }
+
+  if (conflictIds.has('local_login') || conflictIds.has('local_logout')) {
+    const loginDetail  = conflictIds.has('local_login')  ? '- Local login route detected — review for compatibility with gateway authentication.' : null;
+    const logoutDetail = conflictIds.has('local_logout') ? '- Local logout route detected — review for compatibility with gateway session termination.' : null;
+    requiredChanges.push({
+      title: 'Authentication Routes',
+      description: [loginDetail, logoutDetail].filter(Boolean).join('\n')
+    });
+  }
+
+  if (conflictIds.has('jwt_verify_redundant')) {
+    requiredChanges.push({
+      title: 'JWT Verification',
+      description: 'JWT verification logic detected in the application.\nZTAM middleware handles token verification at the gateway level.\nReview whether in-application jwt.verify() calls remain necessary.'
+    });
+  }
+
+  if (conflictIds.has('passport_local_conflict')) {
+    requiredChanges.push({
+      title: 'Passport Strategy Review',
+      description: 'Passport authentication is detected.\nZTAM handles identity through the gateway.\nReview whether the Passport local strategy remains necessary after integration.'
+    });
+  }
+
+  if (conflictIds.has('keycloak_adapter_conflict')) {
+    requiredChanges.push({
+      title: 'Keycloak Adapter Review',
+      description: 'A local Keycloak adapter is detected.\nZTAM manages Keycloak centrally at the gateway level.\nReview whether the local adapter would conflict with the ZTAM integration.'
+    });
+  }
+
+  if (roles.customGuards.length > 0) {
+    const middlewareList = roles.customGuards.map(g => `- ${g}`).join('\n');
+    requiredChanges.push({
+      title: 'Protected Route Middleware',
+      description: `The following middleware guards were detected:\n${middlewareList}\nReview whether these guards remain compatible after ZTAM is introduced.`
+    });
+  } else if (auth.libraries.length > 0 && !conflictIds.has('session_bridge') && !conflictIds.has('custom_context_bridge')) {
+    requiredChanges.push({
+      title: 'Authentication Middleware',
+      description: 'Review existing authentication middleware to confirm compatibility with ZTAM.'
+    });
+  }
+
+  if (auth.allUserPatterns && auth.allUserPatterns.length > 1) {
+    const secondaryPatterns = auth.allUserPatterns.filter(p => p !== 'req.user' && p !== auth.userObjectPattern);
+    if (secondaryPatterns.length > 0) {
+      requiredChanges.push({
+        title: 'Additional Context',
+        description: `The application also references ${secondaryPatterns.join(', ')}.\nReview whether authenticated user information should continue to be exposed through this property after integration.`
+      });
+    }
+  }
+
+  const suggestedExamples = [];
+  if (strategy.id === 'session_bridge') {
+    suggestedExamples.push({
+      title: 'Session Bridge',
+      currentPattern: auth.userObjectPattern,
+      ztamPattern: 'req.user',
+      description: 'Consider introducing a middleware layer that maps authenticated user information into the application\'s existing session structure.\n\nThis is only a suggested approach and is not automatically applied.'
+    });
+  } else if (strategy.id === 'custom_context_bridge') {
+    suggestedExamples.push({
+      title: 'Custom Context Bridge',
+      currentPattern: auth.userObjectPattern,
+      ztamPattern: 'req.user',
+      description: 'Consider introducing a middleware layer that maps authenticated user information into the custom context property.\n\nThis is only a suggested approach and is not automatically applied.'
+    });
+  }
+
+  const terminal = _renderTerminal({ projectPath, framework, allFrameworks, auth, session, roles, allAffectedFiles, referenceCounts, conflicts, strategy, requiredChanges, suggestedExamples });
+  const markdown = _renderMarkdown({ projectPath, framework, allFrameworks, auth, session, roles, allAffectedFiles, referenceCounts, conflicts, strategy, requiredChanges, suggestedExamples });
+  const json     = _renderJson({ projectPath, framework, auth, session, roles, conflicts, strategy, allAffectedFiles, referenceCounts, requiredChanges, suggestedExamples });
+
+  return { terminal, markdown, json, conflicts, strategy, requiredChanges, suggestedExamples };
+}
+
+// ── Terminal Renderer ─────────────────────────────────────────────────────────
+
+function _renderTerminal(r) {
+  const LINE = '═'.repeat(62);
+  const THIN = '─'.repeat(62);
+  const ICON = { low: '🟢', medium: '🟡', high: '🔴' };
+  const lines = [];
+
+  lines.push('');
+  lines.push(LINE);
+  lines.push('  ZTAM Integration Analyzer — Report');
+  lines.push(LINE);
+  lines.push('');
+  lines.push(`Project:           ${r.projectPath}`);
+  lines.push('');
+
+  const fwStr = r.allFrameworks.length > 0
+    ? r.allFrameworks.map(f => `${f.name} [${f.confidence}]`).join(', ')
+    : 'Unknown';
+  lines.push(`Framework:         ${fwStr}`);
+  lines.push(`Authentication:    ${r.auth.libraries.join(', ') || 'None detected'}`);
+  lines.push(`Session Storage:   ${r.session.approach}  —  Store: ${r.session.store}`);
+
+  const uop = r.auth.allUserPatterns.length > 0 ? r.auth.allUserPatterns.join(', ') : 'Not detected';
+  lines.push(`User Object:       ${uop}`);
+
+  const roleStr = [
+    ...r.roles.libraries,
+    ...(r.roles.customGuards.length > 0 ? [`Custom: ${r.roles.customGuards.join(', ')}`] : []),
+    ...r.roles.patterns,
+  ].join(', ') || 'None detected';
+  lines.push(`Authorization:     ${roleStr}`);
+  lines.push('');
+
+  if (r.allAffectedFiles.length > 0) {
+    lines.push(THIN);
+    lines.push('Potential Touch Points:');
+    r.allAffectedFiles.forEach(f => lines.push(`  - ${f}`));
+    lines.push('');
+  }
+
+  const refKeys = Object.keys(r.referenceCounts);
+  if (refKeys.length > 0) {
+    lines.push(THIN);
+    lines.push('Detected References:');
+    refKeys.forEach(k => lines.push(`  - ${k}: ${r.referenceCounts[k]} occurrences`));
+    lines.push('');
+  }
+
+  lines.push(THIN);
+  if (r.conflicts.length === 0) {
+    lines.push('Integration Findings:   ✓ None — clean integration possible');
+  } else {
+    lines.push(`Integration Findings:   ${r.conflicts.length}`);
+    lines.push('');
+    r.conflicts.forEach((c, i) => {
+      lines.push(`  [${i + 1}] ${c.title}`);
+      lines.push(`      ${c.detail}`);
+    });
+  }
+  lines.push('');
+
+  lines.push(THIN);
+  lines.push(`Recommended Integration Strategy:  ${r.strategy.title}`);
+  lines.push('');
+  lines.push(`  Reason:   ${r.strategy.reason}`);
+  if (r.strategy.considerations && r.strategy.considerations.length > 0) {
+    lines.push('');
+    lines.push('  Integration Considerations:');
+    r.strategy.considerations.forEach(c => lines.push(`    - ${c}`));
+  }
+  lines.push('');
+
+  // ── Integration Guidance ──────────────────────────────────────────────────
+  // Only show a gap when the PRIMARY user context differs from what ZTAM provides.
+  const primaryPattern = r.auth.userObjectPattern;
+  const hasContextGap  = primaryPattern && primaryPattern !== 'req.user';
+
+  if (hasContextGap) {
+    lines.push(THIN);
+    lines.push('Integration Guidance');
+    lines.push('');
+    lines.push(`  Application expects:    ${primaryPattern}`);
+    lines.push(`  ZTAM provides:          req.user`);
+    lines.push('');
+    lines.push('  Gap: The application and ZTAM use different user context properties.');
+    lines.push('       An integration layer between ZTAM middleware and application routes');
+    lines.push('       is the area to review.');
+    lines.push('');
+  }
+
+  // ── Action Plan ──────────────────────────────────────────────────────
+  lines.push(THIN);
+  lines.push('Action Plan');
+  lines.push('');
+  r.requiredChanges.forEach((rc, i) => {
+    lines.push(`  ${i + 1}. ${rc.title}`);
+    if (rc.description) {
+      rc.description.split('\n').forEach(l => lines.push(`     ${l}`));
+    }
+    lines.push('');
+  });
+
+  // ── Suggested Architecture Pattern ─────────────────────────────────────────────────
+  if (r.suggestedExamples.length > 0) {
+    lines.push(THIN);
+    lines.push('Suggested Architecture Pattern');
+    lines.push('');
+    r.suggestedExamples.forEach(se => {
+      lines.push(`  Strategy:  ${se.title}`);
+      lines.push('');
+      lines.push(`  Middleware execution order:`);
+      lines.push('    [ ZTAM Middleware ]');
+      lines.push('          ↓');
+      lines.push('    [ Application Integration Layer ]');
+      lines.push('          ↓');
+      lines.push('    [ Existing Protected Routes ]');
+      lines.push('');
+      se.description.split('\n').forEach(l => lines.push(`  ${l}`));
+      lines.push('');
+    });
+  }
+
+  lines.push(LINE);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ── Markdown Renderer ─────────────────────────────────────────────────────────
+
+function _renderMarkdown(r) {
+  const now   = new Date().toISOString().replace('T', ' ').substring(0, 19);
+  const ICON  = { low: '🟢', medium: '🟡', high: '🔴' };
+  const lines = [];
+
+  lines.push('# ZTAM Integration Report');
+  lines.push('');
+  lines.push(`> **Generated:** ${now}`);
+  lines.push(`> **Project:** \`${r.projectPath}\``);
+  lines.push('');
+
+  lines.push('## Detection Summary');
+  lines.push('');
+  lines.push('| Property | Value |');
+  lines.push('|---|---|');
+  const fw = r.allFrameworks.map(f => `${f.name} (${f.confidence})`).join(', ') || 'Unknown';
+  lines.push(`| Framework | ${fw} |`);
+  lines.push(`| Authentication | ${r.auth.libraries.join(', ') || 'None'} |`);
+  lines.push(`| Session | ${r.session.approach} — ${r.session.store} |`);
+  lines.push(`| User Object | ${r.auth.allUserPatterns.join(', ') || 'Not detected'} |`);
+  const roleStr = [...r.roles.libraries, ...r.roles.patterns, ...r.roles.customGuards].join(', ') || 'None';
+  lines.push(`| Authorization | ${roleStr} |`);
+  lines.push('');
+
+  if (r.allAffectedFiles.length > 0) {
+    lines.push('## Potential Touch Points');
+    r.allAffectedFiles.forEach(f => lines.push(`- \`${f}\``));
+    lines.push('');
+  }
+
+  const refKeys = Object.keys(r.referenceCounts);
+  if (refKeys.length > 0) {
+    lines.push('## Detected References');
+    refKeys.forEach(k => lines.push(`- \`${k}\`: ${r.referenceCounts[k]} occurrences`));
+    lines.push('');
+  }
+
+  lines.push('## Integration Findings');
+  if (r.conflicts.length === 0) {
+    lines.push('✅ No integration findings — clean integration possible.');
+  } else {
+    r.conflicts.forEach((c, i) => {
+      lines.push(`### ${i + 1}. ${c.title}`);
+      lines.push(`> ${c.detail}`);
+      lines.push('');
+      lines.push(`**Bridge:** ${c.bridgeHint}`);
+      lines.push('');
+    });
+  }
+
+  lines.push('## Recommended Integration Strategy');
+  lines.push('');
+  lines.push(`**Strategy:** ${r.strategy.title}`);
+  lines.push('');
+  lines.push(`**Reason:** ${r.strategy.reason}`);
+  if (r.strategy.considerations && r.strategy.considerations.length > 0) {
+    lines.push('');
+    lines.push('**Integration Considerations:**');
+    r.strategy.considerations.forEach(c => lines.push(`- ${c}`));
+  }
+  lines.push('');
+
+  lines.push('## Required Changes');
+  lines.push('');
+  r.requiredChanges.forEach((rc, i) => {
+    lines.push(`### ${i + 1}. ${rc.title}`);
+    if (rc.description) {
+      rc.description.split('\n').forEach(l => lines.push(`${l}`));
+    }
+    lines.push('');
+  });
+
+  if (r.suggestedExamples.length > 0) {
+    lines.push('## Suggested Example');
+    lines.push('');
+    r.suggestedExamples.forEach(se => {
+      lines.push(`### ${se.title}`);
+      lines.push('');
+      lines.push(`**Current pattern:** \`${se.currentPattern}\``);
+      lines.push('');
+      lines.push(`**ZTAM pattern:** \`${se.ztamPattern}\``);
+      lines.push('');
+      se.description.split('\n').forEach(l => lines.push(`${l}`));
+      lines.push('');
+    });
+  }
+
+  return lines.join('\n');
+}
+
+// ── JSON Renderer ─────────────────────────────────────────────────────────────
+
+function _renderJson(r) {
+  const { framework, auth, session, roles, conflicts, strategy, projectPath, allAffectedFiles, referenceCounts, requiredChanges, suggestedExamples } = r;
+
+  // Determine role type
+  let roleType = 'none';
+  if (roles.patterns.includes('Role array check'))        roleType = 'array';
+  else if (roles.patterns.includes('Role string comparison')) roleType = 'string';
+  else if (roles.patterns.includes('Permission check'))   roleType = 'permission';
+
+  return JSON.stringify({
+    schemaVersion: '2.0',
+    generatedAt: new Date().toISOString(),
+    projectPath,
+    framework: {
+      name: framework.name,
+      confidence: framework.confidence,
+    },
+    authentication: {
+      libraries: auth.libraries,
+      userObjectPattern: auth.userObjectPattern,
+      allUserPatterns: auth.allUserPatterns,
+      hasLocalLogin:  auth.hasLocalLogin,
+      hasLocalLogout: auth.hasLocalLogout,
+    },
+    session: {
+      approach: session.approach,
+      store: session.store,
+      cookieBased: session.cookieBased,
+      secureCookie: session.secureCookie,
+    },
+    authorization: {
+      libraries: roles.libraries,
+      patterns: roles.patterns,
+      customGuards: roles.customGuards,
+      roleType,
+    },
+    conflicts: conflicts.map(c => c.id),
+    recommendedStrategy: strategy.id,
+    integrationCandidates: allAffectedFiles,
+    referenceCounts,
+    requiredChanges,
+    suggestedExamples
+  }, null, 2);
+}
+
+module.exports = { generateReport };

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@trustnext/ztam-analyzer",
+  "version": "1.0.0",
+  "description": "Read-only ZTAM integration analyzer for Node.js applications",
+  "main": "index.js",
+  "bin": {
+    "ztam-analyzer": "./cli.js"
+  },
+  "scripts": {
+    "analyze": "node cli.js analyze"
+  },
+  "keywords": ["ztam", "security", "analyzer", "integration", "zero-trust"],
+  "author": "TrustNext",
+  "license": "MIT",
+  "dependencies": {}
+}

package/report.json

@@ -0,0 +1,84 @@
+{
+  "schemaVersion": "2.0",
+  "generatedAt": "2026-06-25T14:36:40.715Z",
+  "projectPath": "/home/heisenberg/Desktop/test app 1",
+  "framework": {
+    "name": "Express",
+    "confidence": "high"
+  },
+  "authentication": {
+    "libraries": [
+      "express-session"
+    ],
+    "userObjectPattern": "req.session.user",
+    "allUserPatterns": [
+      "req.session.user"
+    ],
+    "hasLocalLogin": false,
+    "hasLocalLogout": false
+  },
+  "session": {
+    "approach": "express-session",
+    "store": "MySQL",
+    "cookieBased": true,
+    "secureCookie": null
+  },
+  "authorization": {
+    "libraries": [],
+    "patterns": [
+      "Role string comparison"
+    ],
+    "customGuards": [
+      "requireRole()",
+      "requireAdmin()",
+      "requireAuth()"
+    ],
+    "roleType": "string"
+  },
+  "conflicts": [
+    "session_bridge",
+    "role_mapping"
+  ],
+  "recommendedStrategy": "session_bridge",
+  "integrationCandidates": [
+    "public/app.js",
+    "src/middleware/auth.js",
+    "src/routes/adminRoutes.js",
+    "src/routes/authRoutes.js",
+    "src/routes/managerRoutes.js",
+    "src/routes/taskRoutes.js"
+  ],
+  "referenceCounts": {
+    "req.session.user": 32,
+    "requireRole": 4,
+    "requireAdmin": 12,
+    "requireAuth": 8
+  },
+  "requiredChanges": [
+    {
+      "title": "Install @trustnext/ztam-middleware",
+      "description": null
+    },
+    {
+      "title": "Session Handling",
+      "description": "The application uses req.session.user.\nZTAM provides authenticated users through req.user.\nA bridge between these patterns will be needed."
+    },
+    {
+      "title": "Authorization",
+      "description": "The application uses custom roles or role mapping.\nZTAM provides roles as an array (roles[]).\nReview how roles should be mapped."
+    },
+    {
+      "title": "Protected Routes",
+      "description": "Review routes protected by requireAuth(), requireRole(), requireAdmin(), passport.authenticate(), or similar middleware."
+    }
+  ],
+  "suggestedExamples": [
+    {
+      "title": "Session Bridge",
+      "currentPattern": "req.session.user",
+      "ztamPattern": "req.user",
+      "description": "Consider introducing a middleware layer that maps authenticated user information into the application's existing session structure.\n\nThis is only a suggested approach and is not automatically applied."
+    }
+  ],
+  "complexity": "medium"
+}