@soulbatical/tetra-dev-toolkit 1.20.0 → 2.0.0

package/lib/checks/security/route-config-alignment.js

@@ -1,342 +0,0 @@
-/**
- * Route ↔ Config Alignment Check
- *
- * Verifies that route files match the feature config accessLevel:
- *
- * - accessLevel 'admin'   → route file must be adminRoutes.ts AND must have authenticateToken + requireOrganizationAdmin
- * - accessLevel 'user'    → route file must be userRoutes.ts AND must have authenticateToken
- * - accessLevel 'public'  → route can be publicRoutes.ts, NO auth middleware required
- * - accessLevel 'system'  → should NOT have any route file (backend-only)
- * - accessLevel 'creator' → route must have authenticateToken
- *
- * CRITICAL if an admin endpoint has no auth middleware.
- * HIGH if route name doesn't match access level.
- */
-
-import { readFileSync, existsSync } from 'fs'
-import { join, basename, dirname } from 'path'
-import { globSync } from 'glob'
-
-export const meta = {
-  id: 'route-config-alignment',
-  name: 'Route ↔ Config Alignment',
-  category: 'security',
-  severity: 'critical',
-  description: 'Verifies route middleware matches feature config accessLevel'
-}
-
-/**
- * Find files matching a glob pattern
- */
-function findFiles(projectRoot, pattern) {
-  try {
-    return globSync(pattern, { cwd: projectRoot, absolute: true, ignore: ['**/node_modules/**'] })
-  } catch {
-    return []
-  }
-}
-
-/**
- * Parse all feature configs to extract tableName → accessLevel + feature directory
- */
-function parseFeatureConfigs(projectRoot) {
-  const configs = [] // { tableName, accessLevel, configFile, featureDir }
-
-  const configFiles = [
-    ...findFiles(projectRoot, 'backend/src/features/**/config/*.config.ts'),
-    ...findFiles(projectRoot, 'src/features/**/config/*.config.ts')
-  ]
-
-  for (const file of configFiles) {
-    let content
-    try { content = readFileSync(file, 'utf-8') } catch { continue }
-
-    const tableMatch = content.match(/tableName:\s*['"]([^'"]+)['"]/)
-    if (!tableMatch) continue
-
-    const tableName = tableMatch[1]
-
-    const accessMatch = content.match(/accessLevel:\s*['"]([^'"]+)['"]/)
-    const accessLevel = accessMatch ? accessMatch[1] : 'admin'
-
-    // Feature directory is two levels up from config file (features/X/config/file.ts → features/X)
-    const configDir = dirname(file)
-    const featureDir = dirname(configDir)
-
-    configs.push({
-      tableName,
-      accessLevel,
-      configFile: file.replace(projectRoot + '/', ''),
-      featureDir
-    })
-  }
-
-  return configs
-}
-
-/**
- * Find route files in a feature directory
- */
-function findRouteFiles(featureDir) {
-  const routesDir = join(featureDir, 'routes')
-  if (!existsSync(routesDir)) return []
-
-  try {
-    return globSync('*.ts', { cwd: routesDir, absolute: true, ignore: ['*.d.ts'] })
-  } catch {
-    return []
-  }
-}
-
-/**
- * Check if a route file contains authenticateToken middleware
- */
-function hasAuthMiddleware(content) {
-  return /authenticateToken/.test(content)
-}
-
-/**
- * Check if a route file contains requireOrganizationAdmin middleware
- */
-function hasOrgAdminMiddleware(content) {
-  return /requireOrganizationAdmin/.test(content)
-}
-
-/**
- * Check if admin routes are protected by a RouteManager group-level middleware.
- * Many projects apply auth middleware at the route group level (e.g., all /api/admin/* routes)
- * rather than in individual route files.
- */
-function hasRouteManagerGroupAuth(projectRoot) {
-  const candidates = [
-    join(projectRoot, 'backend/src/core/RouteManager.ts'),
-    join(projectRoot, 'src/core/RouteManager.ts'),
-    join(projectRoot, 'backend/src/routes/index.ts'),
-    join(projectRoot, 'src/routes/index.ts')
-  ]
-
-  for (const file of candidates) {
-    if (!existsSync(file)) continue
-    try {
-      const content = readFileSync(file, 'utf-8')
-      // Check for group middleware pattern: prefix '/api/admin' with authenticateToken
-      if (/\/api\/admin/.test(content) && /authenticateToken/.test(content)) {
-        return true
-      }
-    } catch { /* skip */ }
-  }
-  return false
-}
-
-/**
- * Expected route filename for a given accessLevel
- */
-function expectedRouteFileName(accessLevel) {
-  switch (accessLevel) {
-    case 'admin': return 'adminRoutes.ts'
-    case 'user': return 'userRoutes.ts'
-    case 'public': return 'publicRoutes.ts'
-    default: return null
-  }
-}
-
-export async function run(config, projectRoot) {
-  const results = {
-    passed: true,
-    skipped: false,
-    findings: [],
-    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
-    details: { routesChecked: 0, violations: 0 }
-  }
-
-  // Canonical: security.routeConfigIgnore
-  const routeIgnore = config?.security?.routeConfigIgnore || config?.routeConfigAlignmentIgnore || []
-
-  // Detect if RouteManager applies group-level auth middleware to /api/admin/*
-  const routeManagerHasGroupAuth = hasRouteManagerGroupAuth(projectRoot)
-
-  const featureConfigs = parseFeatureConfigs(projectRoot)
-
-  if (featureConfigs.length === 0) {
-    results.skipped = true
-    results.skipReason = 'No feature config files found'
-    return results
-  }
-
-  for (const cfg of featureConfigs) {
-    // Skip features explicitly ignored in config
-    if (routeIgnore.some(pattern => cfg.tableName === pattern || cfg.configFile.includes(pattern))) continue
-    const routeFiles = findRouteFiles(cfg.featureDir)
-
-    // --- system: should NOT have any route file ---
-    if (cfg.accessLevel === 'system') {
-      if (routeFiles.length > 0) {
-        const routeNames = routeFiles.map(f => basename(f)).join(', ')
-        results.findings.push({
-          file: cfg.configFile,
-          line: 1,
-          type: 'system-has-routes',
-          severity: 'high',
-          message: `Config declares accessLevel "system" for table "${cfg.tableName}" but feature has route files: ${routeNames}. System features should be backend-only with no HTTP routes.`,
-          fix: `Remove route files or change accessLevel in the config.`
-        })
-        results.summary.high++
-        results.summary.total++
-        results.passed = false
-        results.details.violations++
-      }
-      continue
-    }
-
-    // Skip features with no routes (may be intentional for some configs)
-    if (routeFiles.length === 0) continue
-
-    // Check each route file in this feature
-    for (const routeFile of routeFiles) {
-      results.details.routesChecked++
-
-      let content
-      try { content = readFileSync(routeFile, 'utf-8') } catch { continue }
-
-      const routeName = basename(routeFile)
-      const relRouteFile = routeFile.replace(projectRoot + '/', '')
-
-      // --- admin checks ---
-      if (cfg.accessLevel === 'admin') {
-        // Route name should be adminRoutes.ts
-        if (routeName === 'adminRoutes.ts') {
-          // CRITICAL: admin route MUST have authenticateToken (in file OR via RouteManager group)
-          if (!hasAuthMiddleware(content) && !routeManagerHasGroupAuth) {
-            results.findings.push({
-              file: relRouteFile,
-              line: 1,
-              type: 'admin-route-no-auth',
-              severity: 'critical',
-              message: `Admin route for table "${cfg.tableName}" is missing authenticateToken middleware. Endpoints are accessible without authentication.`,
-              fix: `Add authenticateToken middleware: router.use(authenticateToken, requireOrganizationAdmin)`
-            })
-            results.summary.critical++
-            results.summary.total++
-            results.passed = false
-            results.details.violations++
-          }
-
-          // CRITICAL: admin route MUST have requireOrganizationAdmin (in file OR via RouteManager group)
-          if (!hasOrgAdminMiddleware(content) && !routeManagerHasGroupAuth) {
-            results.findings.push({
-              file: relRouteFile,
-              line: 1,
-              type: 'admin-route-no-org-admin',
-              severity: 'critical',
-              message: `Admin route for table "${cfg.tableName}" is missing requireOrganizationAdmin middleware. Any authenticated user can access admin endpoints.`,
-              fix: `Add requireOrganizationAdmin middleware: router.use(authenticateToken, requireOrganizationAdmin)`
-            })
-            results.summary.critical++
-            results.summary.total++
-            results.passed = false
-            results.details.violations++
-          }
-        }
-      }
-
-      // --- user checks ---
-      if (cfg.accessLevel === 'user') {
-        if (routeName === 'userRoutes.ts') {
-          if (!hasAuthMiddleware(content)) {
-            results.findings.push({
-              file: relRouteFile,
-              line: 1,
-              type: 'user-route-no-auth',
-              severity: 'critical',
-              message: `User route for table "${cfg.tableName}" is missing authenticateToken middleware. Endpoints are accessible without authentication.`,
-              fix: `Add authenticateToken middleware: router.use(authenticateToken)`
-            })
-            results.summary.critical++
-            results.summary.total++
-            results.passed = false
-            results.details.violations++
-          }
-        }
-
-        // HIGH: user-level feature shouldn't primarily use adminRoutes
-        if (routeName === 'adminRoutes.ts') {
-          results.findings.push({
-            file: relRouteFile,
-            line: 1,
-            type: 'user-feature-admin-route',
-            severity: 'high',
-            message: `Config declares accessLevel "user" for table "${cfg.tableName}" but has adminRoutes.ts. Route file name does not match access level.`,
-            fix: `Rename to userRoutes.ts or update config accessLevel to "admin".`
-          })
-          results.summary.high++
-          results.summary.total++
-          results.passed = false
-          results.details.violations++
-        }
-      }
-
-      // --- creator checks ---
-      if (cfg.accessLevel === 'creator') {
-        // Creator routes must have authenticateToken
-        if (!hasAuthMiddleware(content) && routeName !== 'publicRoutes.ts') {
-          results.findings.push({
-            file: relRouteFile,
-            line: 1,
-            type: 'creator-route-no-auth',
-            severity: 'critical',
-            message: `Creator route "${routeName}" for table "${cfg.tableName}" is missing authenticateToken middleware. Endpoints are accessible without authentication.`,
-            fix: `Add authenticateToken middleware: router.use(authenticateToken)`
-          })
-          results.summary.critical++
-          results.summary.total++
-          results.passed = false
-          results.details.violations++
-        }
-      }
-
-      // --- public checks: no auth required, just verify naming ---
-      // public routes are fine without auth middleware, no action needed
-
-      // --- Cross-access-level route name mismatch ---
-      // Skip if route file has explicit @tetra-audit-ignore for this check
-      const hasIgnoreDirective = /@tetra-audit-ignore\s+route-config-alignment\b/.test(content)
-      if (cfg.accessLevel === 'admin' && routeName === 'publicRoutes.ts' && !hasAuthMiddleware(content) && !hasIgnoreDirective) {
-        results.findings.push({
-          file: relRouteFile,
-          line: 1,
-          type: 'admin-feature-public-route-no-auth',
-          severity: 'critical',
-          message: `Config declares accessLevel "admin" for table "${cfg.tableName}" but has a publicRoutes.ts without auth. Admin data may be exposed publicly.`,
-          fix: `Either add auth middleware to publicRoutes.ts, or add @tetra-audit-ignore route-config-alignment comment if the public route is intentional.`
-        })
-        results.summary.critical++
-        results.summary.total++
-        results.passed = false
-        results.details.violations++
-      }
-    }
-
-    // HIGH: Check if expected route file name exists for the access level
-    const expected = expectedRouteFileName(cfg.accessLevel)
-    if (expected && routeFiles.length > 0) {
-      const hasExpected = routeFiles.some(f => basename(f) === expected)
-      if (!hasExpected) {
-        const routeNames = routeFiles.map(f => basename(f)).join(', ')
-        results.findings.push({
-          file: cfg.configFile,
-          line: 1,
-          type: 'route-name-mismatch',
-          severity: 'high',
-          message: `Config declares accessLevel "${cfg.accessLevel}" for table "${cfg.tableName}" expecting ${expected} but found: ${routeNames}.`,
-          fix: `Rename the primary route file to ${expected} or update the config accessLevel.`
-        })
-        results.summary.high++
-        results.summary.total++
-        results.passed = false
-        results.details.violations++
-      }
-    }
-  }
-
-  return results
-}

package/lib/checks/security/rpc-security-mode.js

@@ -1,175 +0,0 @@
-/**
- * RPC Security Mode Check — HARD BLOCK
- *
- * Scans ALL SQL migrations for RPC functions and verifies their security mode:
- *
- * SECURITY DEFINER = function runs as the DB owner, BYPASSES RLS completely.
- * SECURITY INVOKER = function runs as the calling user, RLS is enforced.
- *
- * Rules:
- * - Data query RPCs (get_*, list_*, search_*) → MUST be INVOKER
- * - Auth helper functions (auth_org_id, auth_uid) → DEFINER is OK (they need to read auth.users)
- * - Count/results RPCs linked to feature configs → MUST be INVOKER
- * - Public RPCs (explicitly returning only public columns) → DEFINER is OK if whitelisted
- *
- * Whitelist: .tetra-quality.json → supabase.securityDefinerWhitelist: ['auth_org_id', ...]
- *
- * Reference: stella_howto_get slug="tetra-architecture-guide"
- */
-
-import { readFileSync, existsSync } from 'fs'
-import { join } from 'path'
-import { globSync } from 'glob'
-
-export const meta = {
-  id: 'rpc-security-mode',
-  name: 'RPC Security Mode',
-  category: 'security',
-  severity: 'critical',
-  description: 'Verifies all RPC functions use SECURITY INVOKER (not DEFINER) unless explicitly whitelisted. DEFINER bypasses RLS completely.'
-}
-
-// Functions that legitimately need SECURITY DEFINER
-const BUILTIN_DEFINER_WHITELIST = [
-  // Auth helpers (need to read auth schema / organization_members)
-  'auth_org_id',
-  'auth_admin_organizations',
-  'auth_user_organizations',
-  'auth_creator_organizations',
-  'get_user_org_role',
-  'get_org_id',
-  'handle_new_user',
-  'moddatetime',
-  // Public RPCs (called by anon users, need DEFINER to bypass RLS and return only safe columns)
-  'search_public_ad_library',
-  // System/billing RPCs (called by systemDB, no user context)
-  'get_org_credit_limits',
-  // Supabase internal
-  'pgsodium_encrypt',
-  'pgsodium_decrypt'
-]
-
-export async function run(config, projectRoot) {
-  const results = {
-    passed: true,
-    skipped: false,
-    findings: [],
-    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
-    details: { rpcsFound: 0, definerCount: 0, invokerCount: 0, defaultCount: 0, whitelistedCount: 0 }
-  }
-
-  const migrationDirs = [
-    join(projectRoot, 'supabase/migrations'),
-    join(projectRoot, 'backend/supabase/migrations')
-  ]
-
-  const sqlFiles = []
-  for (const dir of migrationDirs) {
-    if (!existsSync(dir)) continue
-    try {
-      const files = globSync('*.sql', { cwd: dir, absolute: true })
-      sqlFiles.push(...files)
-    } catch { /* skip */ }
-  }
-
-  if (sqlFiles.length === 0) {
-    results.skipped = true
-    results.skipReason = 'No SQL migration files found'
-    return results
-  }
-
-  // Build whitelist from config + builtins
-  const userWhitelist = (config.supabase?.securityDefinerWhitelist || [])
-  const whitelist = new Set([...BUILTIN_DEFINER_WHITELIST, ...userWhitelist])
-
-  // Track latest definition per function (migrations can override)
-  const functions = new Map() // funcName → { securityMode, file, line, isDataQuery }
-
-  for (const file of sqlFiles) {
-    let content
-    try { content = readFileSync(file, 'utf-8') } catch { continue }
-
-    const relFile = file.replace(projectRoot + '/', '')
-
-    // Find all CREATE [OR REPLACE] FUNCTION statements
-    const funcRegex = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+(?:public\.)?(\w+)\s*\(/gi
-    let match
-
-    while ((match = funcRegex.exec(content)) !== null) {
-      const funcName = match[1]
-      const startPos = match.index
-
-      // Extract the function body (up to next CREATE FUNCTION or end of file, max 5000 chars)
-      const bodyEnd = Math.min(startPos + 5000, content.length)
-      const funcBody = content.substring(startPos, bodyEnd)
-
-      // Determine security mode
-      let securityMode = 'DEFAULT' // PostgreSQL default is INVOKER
-      if (/SECURITY\s+DEFINER/i.test(funcBody.substring(0, 2000))) {
-        securityMode = 'DEFINER'
-      } else if (/SECURITY\s+INVOKER/i.test(funcBody.substring(0, 2000))) {
-        securityMode = 'INVOKER'
-      }
-
-      // Determine if this is a data query function
-      const isDataQuery = /^(get_|list_|search_|find_|fetch_|count_)/i.test(funcName) ||
-                          /_counts$|_results$|_detail$/i.test(funcName)
-
-      // Calculate line number
-      const beforeMatch = content.substring(0, startPos)
-      const line = (beforeMatch.match(/\n/g) || []).length + 1
-
-      // Store (later definitions override earlier ones)
-      functions.set(funcName, { securityMode, file: relFile, line, isDataQuery, funcBody: funcBody.substring(0, 500) })
-    }
-  }
-
-  results.details.rpcsFound = functions.size
-
-  for (const [funcName, info] of functions) {
-    if (info.securityMode === 'DEFINER') {
-      results.details.definerCount++
-
-      // Check whitelist
-      if (whitelist.has(funcName)) {
-        results.details.whitelistedCount++
-        continue
-      }
-
-      // Data query RPCs with DEFINER = CRITICAL
-      if (info.isDataQuery) {
-        results.passed = false
-        results.findings.push({
-          file: info.file,
-          line: info.line,
-          type: 'data-rpc-security-definer',
-          severity: 'critical',
-          message: `Data RPC "${funcName}" uses SECURITY DEFINER — bypasses ALL RLS policies. Any authenticated user can see ALL data from ALL organizations.`,
-          fix: `Change to SECURITY INVOKER or remove the SECURITY DEFINER clause. If this function legitimately needs DEFINER, add "${funcName}" to supabase.securityDefinerWhitelist in .tetra-quality.json.`
-        })
-        results.summary.critical++
-        results.summary.total++
-      } else {
-        // Non-data RPCs with DEFINER = HIGH (should still be investigated)
-        results.findings.push({
-          file: info.file,
-          line: info.line,
-          type: 'non-data-rpc-security-definer',
-          severity: 'high',
-          message: `RPC "${funcName}" uses SECURITY DEFINER but is not whitelisted. DEFINER functions bypass RLS — ensure this is intentional.`,
-          fix: `Change to SECURITY INVOKER, or add "${funcName}" to supabase.securityDefinerWhitelist in .tetra-quality.json if DEFINER is intentional.`
-        })
-        results.summary.high++
-        results.summary.total++
-        results.passed = false
-      }
-    } else if (info.securityMode === 'INVOKER') {
-      results.details.invokerCount++
-    } else {
-      results.details.defaultCount++
-      // DEFAULT = INVOKER in PostgreSQL, which is correct
-    }
-  }
-
-  return results
-}