@trustnext/ztam-analyzer 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# @trustnext/ztam-analyzer
+
+A read-only static analyzer for Node.js applications. Inspects a project and generates a structured ZTAM integration report — without touching, modifying, or installing anything in the client project.
+
+## What it does
+
+- Detects **frameworks** (Express, NestJS, Fastify, Next.js, Koa, Hapi).
+- Detects **authentication libraries** and **user object patterns**.
+- Detects **session backends** and **authorization / RBAC** models.
+- Recommends the least-disruptive **integration strategy** (e.g., Session Bridge, Custom Context Bridge).
+- Generates reports in Terminal, Markdown, and machine-readable JSON.
+
+## Installation
+
+```bash
+npm install @trustnext/ztam-analyzer
+```
+
+## Usage
+
+```bash
+# Print report to terminal
+node cli.js analyze /path/to/app
+
+# Save as Markdown and JSON
+node cli.js analyze /path/to/app --output ztam-report.md --json report.json
+```
+
+## Programmatic API
+
+```javascript
+const { analyze } = require('@trustnext/ztam-analyzer');
+
+const report = analyze('/path/to/app');
+
+console.log(report.terminal);    // terminal-formatted string
+console.log(report.markdown);    // markdown-formatted string
+console.log(report.json);        // schema-validated JSON string
+console.log(report.strategy);    // recommended integration path
+```
+
+## Important
+
+- **Read-only**: Never writes, installs, or executes anything inside the client project.
+- **Generic**: Works for any Node.js application — not tied to any specific customer.
+- **Extensible**: Add new frameworks/libraries by dropping a descriptor into `detectors/`.

package/cli.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * cli.js (v2) — Command-line interface for @trustnext/ztam-analyzer
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { analyze } = require('./index');
+
+const USAGE = `
+Usage:
+  node cli.js analyze <path-to-app> [options]
+
+Options:
+  --output <file.md>   Save the report as a Markdown file
+  --json <file.json>   Save the report as a machine-readable JSON file
+
+Examples:
+  node cli.js analyze /home/user/my-app
+  node cli.js analyze ./my-app --output ztam-report.md --json report.json
+`;
+
+function run() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  const command = args[0];
+  if (command !== 'analyze') {
+    console.error(`Unknown command: "${command}"`);
+    console.log(USAGE);
+    process.exit(1);
+  }
+
+  const projectPath = args[1];
+  if (!projectPath || projectPath.startsWith('--')) {
+    console.error('Error: path to app is required as the first argument after "analyze".');
+    console.log(USAGE);
+    process.exit(1);
+  }
+
+  const absolutePath = path.resolve(projectPath);
+  if (!fs.existsSync(absolutePath)) {
+    console.error(`Error: path does not exist: ${absolutePath}`);
+    process.exit(1);
+  }
+
+  // Parse options
+  let outputFile = null;
+  const outputIdx = args.indexOf('--output');
+  if (outputIdx !== -1) {
+    outputFile = args[outputIdx + 1];
+    if (!outputFile || outputFile.startsWith('--')) {
+      console.error('Error: --output requires a filename argument.');
+      process.exit(1);
+    }
+  }
+
+  let jsonFile = null;
+  const jsonIdx = args.indexOf('--json');
+  if (jsonIdx !== -1) {
+    jsonFile = args[jsonIdx + 1];
+    if (!jsonFile || jsonFile.startsWith('--')) {
+      console.error('Error: --json requires a filename argument.');
+      process.exit(1);
+    }
+  }
+
+  // Run analysis
+  let report;
+  try {
+    report = analyze(absolutePath);
+  } catch (err) {
+    console.error(`Analysis failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Print to terminal (always)
+  process.stdout.write(report.terminal);
+
+  // Write Markdown file (if requested)
+  if (outputFile) {
+    const outputPath = path.resolve(outputFile);
+    try {
+      fs.writeFileSync(outputPath, report.markdown, 'utf8');
+      console.log(`\nMarkdown report saved to: ${outputPath}`);
+    } catch (err) {
+      console.error(`Failed to write markdown file: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Write JSON file (if requested)
+  if (jsonFile) {
+    const jsonPath = path.resolve(jsonFile);
+    try {
+      fs.writeFileSync(jsonPath, report.json, 'utf8');
+      console.log(`JSON report saved to: ${jsonPath}`);
+    } catch (err) {
+      console.error(`Failed to write json file: ${err.message}`);
+      process.exit(1);
+    }
+  }
+  
+  if (outputFile || jsonFile) console.log('');
+}
+
+run();

package/detectors/auth/auth0.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Auth0',
+  category: 'auth',
+  depSignals: ['auth0', '@auth0/nextjs-auth0', 'express-openid-connect'],
+  codeSignals: [/require\(['"]auth0['"]\)/, /withApiAuthRequired/, /auth0\./],
+};

package/detectors/auth/better-auth.js

@@ -0,0 +1,14 @@
+'use strict';
+module.exports = {
+  name: 'Better Auth',
+  category: 'auth',
+  depSignals: ['better-auth'],
+  codeSignals: [
+    /better-auth/,
+    /auth\.api\./,
+    /betterAuth\(/,
+    /fromNodeHeaders/,
+    /require\(['"]better-auth['"]\)/,
+    /from ['"]better-auth['"]/,
+  ],
+};

package/detectors/auth/clerk.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Clerk',
+  category: 'auth',
+  depSignals: ['@clerk/clerk-sdk-node', '@clerk/nextjs', '@clerk/express'],
+  codeSignals: [/clerkMiddleware/, /requireAuth\(\)/, /getAuth\(/, /@clerk\//],
+};

package/detectors/auth/express-session.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'express-session',
+  category: 'auth',
+  depSignals: ['express-session'],
+  codeSignals: [/require\(['"]express-session['"]\)/, /app\.use\(session\(/, /req\.session/],
+};

package/detectors/auth/firebase.js

@@ -0,0 +1,15 @@
+'use strict';
+module.exports = {
+  name: 'Firebase Auth',
+  category: 'auth',
+  depSignals: ['firebase', 'firebase-admin'],
+  codeSignals: [
+    /firebase\/auth/,
+    /firebase-admin\/auth/,
+    /getAuth\(\)/,
+    /admin\.auth\(\)/,
+    /verifyIdToken\(/,
+    /signInWithEmailAndPassword/,
+    /signOut\(\)/,
+  ],
+};

package/detectors/auth/jwt.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'JWT (jsonwebtoken)',
+  category: 'auth',
+  depSignals: ['jsonwebtoken'],
+  codeSignals: [/jwt\.verify\(/, /jwt\.sign\(/, /Bearer /, /jsonwebtoken/],
+};

package/detectors/auth/keycloak.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Keycloak',
+  category: 'auth',
+  depSignals: ['keycloak-connect', 'keycloak-js', '@keycloak/keycloak-admin-client'],
+  codeSignals: [/keycloak\.protect\(/, /new Keycloak\(/, /keycloak-connect/],
+};

package/detectors/auth/lucia.js

@@ -0,0 +1,14 @@
+'use strict';
+module.exports = {
+  name: 'Lucia',
+  category: 'auth',
+  depSignals: ['lucia'],
+  codeSignals: [
+    /new Lucia\(/,
+    /lucia\.validateSession/,
+    /lucia\.createSession/,
+    /lucia\.invalidateSession/,
+    /require\(['"]lucia['"]\)/,
+    /from ['"]lucia['"]/,
+  ],
+};

package/detectors/auth/nextauth.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'NextAuth',
+  category: 'auth',
+  depSignals: ['next-auth'],
+  codeSignals: [/getServerSession/, /getSession\(/, /NextAuth\(/, /next-auth/],
+};

package/detectors/auth/passport.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Passport',
+  category: 'auth',
+  depSignals: ['passport'],
+  codeSignals: [/require\(['"]passport['"]\)/, /passport\.use\(/, /passport\.authenticate\(/],
+};

package/detectors/auth/supabase.js

@@ -0,0 +1,15 @@
+'use strict';
+module.exports = {
+  name: 'Supabase Auth',
+  category: 'auth',
+  depSignals: ['@supabase/supabase-js', '@supabase/ssr', '@supabase/auth-helpers-nextjs'],
+  codeSignals: [
+    /supabase\.auth/,
+    /createServerClient/,
+    /createBrowserClient/,
+    /getUser\(\)/,
+    /getSession\(\)/,
+    /supabase\.auth\.signInWithPassword/,
+    /supabase\.auth\.signOut/,
+  ],
+};

package/detectors/framework/express.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Express',
+  category: 'framework',
+  depSignals: ['express'],
+  codeSignals: [/express\(\)/, /app\.use\(/, /app\.get\(/, /app\.post\(/, /Router\(\)/],
+};

package/detectors/framework/fastify.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Fastify',
+  category: 'framework',
+  depSignals: ['fastify'],
+  codeSignals: [/fastify\(\)/, /app\.register\(/, /fastify\.register\(/],
+};

package/detectors/framework/hapi.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Hapi',
+  category: 'framework',
+  depSignals: ['@hapi/hapi', 'hapi'],
+  codeSignals: [/Hapi\.server\(/, /server\.route\(/, /server\.register\(/],
+};

package/detectors/framework/koa.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Koa',
+  category: 'framework',
+  depSignals: ['koa'],
+  codeSignals: [/new Koa\(\)/, /ctx\.body/, /ctx\.state/, /ctx\.request/],
+};

package/detectors/framework/nestjs.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'NestJS',
+  category: 'framework',
+  depSignals: ['@nestjs/core'],
+  codeSignals: [/@Module\(/, /@Controller\(/, /@Injectable\(/, /NestFactory/],
+};

package/detectors/framework/nextjs.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'Next.js',
+  category: 'framework',
+  depSignals: ['next'],
+  codeSignals: [/getServerSideProps/, /getStaticProps/, /NextApiRequest/, /NextApiResponse/],
+};

package/detectors/index.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * detectors/index.js — Detector Registry
+ *
+ * Loads all detector descriptors, runs them against the shared FileMap,
+ * and returns a unified DetectionResult.
+ *
+ * To add a new framework/library: create one file in the appropriate
+ * detectors/<category>/ directory and require() it here. Nothing else changes.
+ */
+
+// ── Framework descriptors ─────────────────────────────────────────────────────
+const FRAMEWORK_DETECTORS = [
+  require('./framework/nestjs'),   // NestJS must be checked before Express
+  require('./framework/nextjs'),
+  require('./framework/fastify'),
+  require('./framework/koa'),
+  require('./framework/hapi'),
+  require('./framework/express'),  // Express last — most generic signals
+];
+
+// ── Auth descriptors ──────────────────────────────────────────────────────────
+const AUTH_DETECTORS = [
+  require('./auth/passport'),
+  require('./auth/jwt'),
+  require('./auth/auth0'),
+  require('./auth/clerk'),
+  require('./auth/nextauth'),
+  require('./auth/keycloak'),
+  require('./auth/express-session'),
+  require('./auth/supabase'),
+  require('./auth/firebase'),
+  require('./auth/lucia'),
+  require('./auth/better-auth'),
+];
+
+// ── Session descriptors ───────────────────────────────────────────────────────
+const SESSION_DETECTORS = [
+  require('./session/express-session'),
+  require('./session/cookie-session'),
+  require('./session/jwt-stateless'),
+];
+
+// ── Role descriptors ──────────────────────────────────────────────────────────
+const ROLE_DETECTORS = [
+  require('./roles/casl'),
+  require('./roles/nestjs-guards'),
+  require('./roles/accesscontrol'),
+  require('./roles/custom-guards'),   // must run last — has extended scan()
+];
+
+// ── User object patterns to scan for ─────────────────────────────────────────
+const USER_OBJECT_PATTERNS = [
+  { pattern: 'req.user',          regex: /req\.user\b/ },
+  { pattern: 'req.session.user',  regex: /req\.session\.user\b/ },
+  { pattern: 'req.auth',          regex: /req\.auth\b/ },
+  { pattern: 'req.currentUser',   regex: /req\.currentUser\b/ },
+  { pattern: 'ctx.state.user',    regex: /ctx\.state\.user\b/ },
+  { pattern: 'ctx.user',          regex: /ctx\.user\b/ },
+  { pattern: 'request.user',      regex: /request\.user\b/ },
+  { pattern: 'res.locals.user',   regex: /res\.locals\.user\b/ },
+];
+
+// ── Login/logout route detection ──────────────────────────────────────────────
+const LOGIN_PATTERNS = [
+  /router\.(post|get)\(['"]\/login['"]/,
+  /app\.(post|get)\(['"]\/login['"]/,
+  /\/api\/auth\/signin/,
+  /\/api\/auth\/login/,
+  /signInWithPassword/,
+  /signInWithEmailAndPassword/,
+  /lucia\.createSession/,
+  /auth\.api\.signIn/,
+];
+const LOGOUT_PATTERNS = [
+  /router\.(post|get)\(['"]\/logout['"]/,
+  /app\.(post|get)\(['"]\/logout['"]/,
+  /\/api\/auth\/signout/,
+  /\/api\/auth\/logout/,
+  /supabase\.auth\.signOut/,
+  /lucia\.invalidateSession/,
+  /auth\.api\.signOut/,
+  /signOut\(\)/,
+];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function allDeps(packageJson) {
+  if (!packageJson) return new Set();
+  return new Set([
+    ...Object.keys(packageJson.dependencies     || {}),
+    ...Object.keys(packageJson.devDependencies  || {}),
+    ...Object.keys(packageJson.peerDependencies || {}),
+  ]);
+}
+
+function matchesDescriptor(descriptor, deps, allCode, files) {
+  const depMatch  = descriptor.depSignals.some(d => deps.has(d));
+  const codeMatch = descriptor.codeSignals.some(re =>
+    typeof re === 'object' ? re.test(allCode) : allCode.includes(re)
+  );
+  return depMatch || codeMatch;
+}
+
+// ── Main export ───────────────────────────────────────────────────────────────
+
+/**
+ * @param {Object|null} packageJson
+ * @param {Object.<string,string>} files  FileMap from file-scanner
+ * @returns {Object} DetectionResult
+ */
+function runAll(packageJson, files) {
+  const deps    = allDeps(packageJson);
+  const allCode = Object.values(files).join('\n');
+
+  // ── Frameworks ──────────────────────────────────────────────────────────────
+  const frameworks = [];
+  for (const fd of FRAMEWORK_DETECTORS) {
+    const depHit  = fd.depSignals.some(d => deps.has(d));
+    const codeHit = fd.codeSignals.some(re => re.test(allCode));
+    if (depHit && codeHit) frameworks.push({ name: fd.name, confidence: 'high' });
+    else if (depHit)        frameworks.push({ name: fd.name, confidence: 'medium' });
+    else if (codeHit)       frameworks.push({ name: fd.name, confidence: 'low' });
+  }
+  const primaryFramework = frameworks[0] || { name: 'Unknown', confidence: 'low' };
+
+  // ── Auth libraries ───────────────────────────────────────────────────────────
+  const authLibraries = AUTH_DETECTORS
+    .filter(d => matchesDescriptor(d, deps, allCode, files))
+    .map(d => d.name);
+
+  if (authLibraries.length === 0) {
+    // Fallback: custom if there's session or manual token logic
+    if (/req\.session/.test(allCode) || /jwt\.verify/.test(allCode)) {
+      authLibraries.push('Custom authentication');
+    }
+  }
+
+  // ── User object patterns ──────────────────────────────────────────────────
+  const userPatternsFound = new Set();
+  const authAffectedFiles = new Set();
+  let hasLocalLogin  = false;
+  let hasLocalLogout = false;
+
+  for (const [relPath, content] of Object.entries(files)) {
+    let touched = false;
+    for (const up of USER_OBJECT_PATTERNS) {
+      if (up.regex.test(content)) { userPatternsFound.add(up.pattern); touched = true; }
+    }
+    if (LOGIN_PATTERNS.some(re => re.test(content)))  { hasLocalLogin  = true; touched = true; }
+    if (LOGOUT_PATTERNS.some(re => re.test(content))) { hasLocalLogout = true; touched = true; }
+    if (touched) authAffectedFiles.add(relPath);
+  }
+
+  // Primary user object = first matched (most specific wins due to pattern order)
+  const allUserPatterns = [...userPatternsFound];
+  const primaryUserObject = allUserPatterns[0] || null;
+
+  const referenceCounts = {};
+  for (const up of USER_OBJECT_PATTERNS) {
+    const globalRegex = new RegExp(up.regex, 'g');
+    const matches = allCode.match(globalRegex);
+    if (matches) {
+      referenceCounts[up.pattern] = matches.length;
+    }
+  }
+
+  // ── Session ───────────────────────────────────────────────────────────────
+  let sessionResult = { approach: 'None detected', store: 'N/A', cookieBased: false, secureCookie: null };
+  for (const sd of SESSION_DETECTORS) {
+    if (matchesDescriptor(sd, deps, allCode, files)) {
+      sessionResult = sd.scan(packageJson, files, deps, allCode);
+      break;
+    }
+  }
+
+  // ── Roles ─────────────────────────────────────────────────────────────────
+  const roleLibraries = ROLE_DETECTORS
+    .filter(d => d.name !== 'Custom Guards' && matchesDescriptor(d, deps, allCode, files))
+    .map(d => d.name);
+
+  const customGuardsDetector = require('./roles/custom-guards');
+  const { guards: customGuards, patterns: rolePatterns } = customGuardsDetector.scan(files);
+
+  const roleAffectedFiles = new Set();
+  for (const [relPath, content] of Object.entries(files)) {
+    const isRoleFile = customGuardsDetector.codeSignals.some(re => re.test(content));
+    if (isRoleFile) roleAffectedFiles.add(relPath);
+  }
+
+  for (const guard of customGuards) {
+    const fnName = guard.replace('()', '');
+    const globalRegex = new RegExp(`\\b${fnName}\\b`, 'g');
+    const matches = allCode.match(globalRegex);
+    if (matches) {
+      referenceCounts[fnName] = matches.length;
+    }
+  }
+
+  // ── Merge affected files ──────────────────────────────────────────────────
+  const allAffectedFiles = [...new Set([...authAffectedFiles, ...roleAffectedFiles])].sort();
+
+  return {
+    framework: primaryFramework,
+    allFrameworks: frameworks,
+    auth: {
+      libraries: authLibraries,
+      userObjectPattern: primaryUserObject,
+      allUserPatterns,
+      hasLocalLogin,
+      hasLocalLogout,
+      affectedFiles: [...authAffectedFiles].sort(),
+    },
+    session: sessionResult,
+    roles: {
+      libraries: roleLibraries,
+      patterns: [...new Set(rolePatterns)],
+      customGuards,
+      affectedFiles: [...roleAffectedFiles].sort(),
+    },
+    allAffectedFiles,
+    referenceCounts,
+    packageJson,
+  };
+}
+
+module.exports = { runAll };

package/detectors/roles/accesscontrol.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'accesscontrol',
+  category: 'roles',
+  depSignals: ['accesscontrol', 'role-acl'],
+  codeSignals: [/AccessControl/, /\.can\(.*\)\.createOwn\(/, /\.permission\(/],
+};

package/detectors/roles/casl.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'CASL',
+  category: 'roles',
+  depSignals: ['@casl/ability', '@casl/mongoose', '@casl/prisma'],
+  codeSignals: [/defineAbility/, /ability\.can\(/, /new AbilityBuilder\(/, /@casl\//],
+};

package/detectors/roles/custom-guards.js

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * custom-guards.js
+ *
+ * Detects hand-written authorization middleware functions and role patterns.
+ * This is the only "roles" detector that does per-file scanning rather than
+ * simple signal matching — because custom guards have no fixed library name.
+ */
+
+const GUARD_PATTERNS = [
+  /function\s+requireRole\b/,
+  /function\s+requireAdmin\b/,
+  /function\s+requireAuth\b/,
+  /function\s+isAuthorized\b/,
+  /function\s+isAuthenticated\b/,
+  /function\s+checkRole\b/,
+  /function\s+hasRole\b/,
+  /const\s+requireRole\s*=/,
+  /const\s+requireAdmin\s*=/,
+  /const\s+protect\s*=/,
+  /const\s+checkPermission\s*=/,
+];
+
+const ROLE_CHECK_PATTERNS = [
+  { name: 'Role string comparison', regex: /user\.role\s*===?\s*['"]/ },
+  { name: 'Role string comparison', regex: /req\.session\.user\.role\b/ },
+  { name: 'Role array check',       regex: /user\.roles\.includes\(/ },
+  { name: 'Role array check',       regex: /req\.user\.roles\b/ },
+  { name: 'Roles in JWT claims',    regex: /decoded\.roles\b|token\.roles\b|claims\.roles\b/ },
+  { name: 'Permission check',       regex: /user\.permissions\b|req\.user\.permissions\b/ },
+];
+
+module.exports = {
+  name: 'Custom Guards',
+  category: 'roles',
+  depSignals: [],
+  codeSignals: [...GUARD_PATTERNS, ...ROLE_CHECK_PATTERNS.map(p => p.regex)],
+
+  // Extended scan: returns names of detected guards and role pattern names
+  scan(files) {
+    const guards   = new Set();
+    const patterns = new Set();
+
+    for (const content of Object.values(files)) {
+      for (const re of GUARD_PATTERNS) {
+        const match = content.match(re);
+        if (match) {
+          const name = match[0]
+            .replace(/function\s+/, '')
+            .replace(/const\s+/, '')
+            .replace(/\s*=.*/, '')
+            .trim();
+          guards.add(name + '()');
+        }
+      }
+      for (const rp of ROLE_CHECK_PATTERNS) {
+        if (rp.regex.test(content)) patterns.add(rp.name);
+      }
+    }
+
+    return { guards: [...guards], patterns: [...patterns] };
+  },
+};

package/detectors/roles/nestjs-guards.js

@@ -0,0 +1,7 @@
+'use strict';
+module.exports = {
+  name: 'NestJS Guards',
+  category: 'roles',
+  depSignals: ['@nestjs/core'],
+  codeSignals: [/@UseGuards\(/, /CanActivate/, /RolesGuard/, /@Roles\(/],
+};

package/detectors/session/cookie-session.js

@@ -0,0 +1,10 @@
+'use strict';
+module.exports = {
+  name: 'cookie-session',
+  category: 'session',
+  depSignals: ['cookie-session'],
+  codeSignals: [/require\(['"]cookie-session['"]\)/],
+  scan() {
+    return { approach: 'cookie-session', store: 'Signed cookie (stateless)', cookieBased: true, secureCookie: null };
+  },
+};