@soulbatical/tetra-dev-toolkit 1.20.0 → 2.0.0

package/lib/checks/security/mixed-db-usage.js

@@ -1,204 +0,0 @@
-/**
- * Mixed Database Usage Detection — HARD BLOCK
- *
- * Controllers MUST use only ONE type of database helper.
- * The DB helper must match the controller naming convention:
- *
- *   AdminXxxController  → adminDB(req) only
- *   UserXxxController   → userDB(req) only
- *   PublicXxxController  → publicDB() only
- *   SystemXxxController  → systemDB(context) only
- *   SuperadminXxxController → superadminDB(req) only
- *   WebhookXxxController → systemDB(context) only (webhooks have no user session)
- *
- * Violations:
- * - CRITICAL: Controller uses systemDB when user context is available (should be adminDB/userDB)
- * - HIGH: Controller mixes multiple DB helper types
- * - MEDIUM: Controller DB helper doesn't match naming convention
- *
- * Reference: stella_howto_get slug="tetra-architecture-guide"
- */
-
-import { readFileSync, existsSync } from 'fs'
-import { join, basename, dirname } from 'path'
-import { glob } from 'glob'
-
-export const meta = {
-  id: 'mixed-db-usage',
-  name: 'Mixed DB Usage',
-  category: 'security',
-  severity: 'critical',
-  description: 'Controllers must use exactly ONE DB helper type matching their naming convention. Detects systemDB misuse when user context is available.'
-}
-
-const DB_PATTERNS = {
-  systemDB:     { level: 'SYSTEM',     pattern: /\bsystemDB\s*\(/g,     desc: 'System-level (cron, webhooks)' },
-  adminDB:      { level: 'ADMIN',      pattern: /(?<!\w)adminDB\s*\(/g,  desc: 'Admin operations (org-scoped)' },
-  userDB:       { level: 'USER',       pattern: /\buserDB\s*\(/g,       desc: 'User-specific operations' },
-  publicDB:     { level: 'PUBLIC',     pattern: /\bpublicDB\s*\(/g,     desc: 'Public/unauthenticated' },
-  superadminDB: { level: 'SUPERADMIN', pattern: /\bsuperadminDB\s*\(/g, desc: 'Cross-org superadmin' }
-}
-
-/**
- * Determine expected DB level from controller filename
- */
-function getExpectedLevel(fileName) {
-  const lower = fileName.toLowerCase()
-  // Order matters — check compound names first
-  if (lower.includes('system'))     return 'SYSTEM'
-  if (lower.includes('superadmin')) return 'SUPERADMIN'
-  if (lower.includes('webhook'))    return 'SYSTEM' // webhooks have no user session
-  if (lower.includes('cron'))       return 'SYSTEM'
-  if (lower.includes('admin'))      return 'ADMIN'
-  if (lower.includes('user'))       return 'USER'
-  if (lower.includes('public'))     return 'PUBLIC'
-  return null
-}
-
-/**
- * Check if file has user authentication context available
- */
-function hasUserContext(content) {
-  return content.includes('AuthenticatedRequest') ||
-         content.includes('req.userToken') ||
-         content.includes('req.user') ||
-         content.includes('authenticateToken')
-}
-
-export async function run(config, projectRoot) {
-  const results = {
-    name: 'Mixed DB Usage',
-    slug: 'mixed-db-usage',
-    passed: true,
-    skipped: false,
-    findings: [],
-    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
-    details: { controllersChecked: 0, violations: 0 }
-  }
-
-  // Config-based ignore for controllers that legitimately mix DB helpers
-  // Canonical: security.mixedDbWhitelist
-  const mixedDbIgnore = config?.security?.mixedDbWhitelist || config?.mixedDbWhitelist || []
-
-  const files = await glob('**/*[Cc]ontroller*.ts', {
-    cwd: projectRoot,
-    ignore: [
-      '**/node_modules/**',
-      '**/.next/**',
-      '**/dist/**',
-      '**/build/**',
-      ...(config.ignore || []),
-      '**/*.test.ts',
-      '**/*.spec.ts',
-      '**/*.d.ts'
-    ]
-  })
-
-  if (files.length === 0) {
-    results.skipped = true
-    results.skipReason = 'No controller files found'
-    return results
-  }
-
-  for (const file of files) {
-    const fullPath = join(projectRoot, file)
-    let content
-    try { content = readFileSync(fullPath, 'utf-8') } catch { continue }
-
-    results.details.controllersChecked++
-    const fileName = basename(file)
-
-    // Skip controllers explicitly ignored in config
-    if (mixedDbIgnore.some(pattern => file.includes(pattern) || fileName.includes(pattern))) continue
-
-    // Detect all DB usages in this file
-    const dbUsages = new Map() // level -> [{type, line, code}]
-    const lines = content.split('\n')
-
-    for (const [dbType, cfg] of Object.entries(DB_PATTERNS)) {
-      lines.forEach((line, idx) => {
-        // Reset regex lastIndex
-        cfg.pattern.lastIndex = 0
-        if (cfg.pattern.test(line)) {
-          const level = cfg.level
-          if (!dbUsages.has(level)) dbUsages.set(level, [])
-          dbUsages.get(level).push({
-            type: dbType,
-            line: idx + 1,
-            code: line.trim().substring(0, 120)
-          })
-        }
-      })
-    }
-
-    if (dbUsages.size === 0) continue
-
-    const expectedLevel = getExpectedLevel(fileName)
-    const usedLevels = [...dbUsages.keys()]
-    const userContextAvailable = hasUserContext(content)
-
-    // CRITICAL: systemDB used when user context is available and it's not a system controller
-    if (dbUsages.has('SYSTEM') && userContextAvailable && expectedLevel !== 'SYSTEM') {
-      results.passed = false
-      const locs = dbUsages.get('SYSTEM')
-      for (const loc of locs) {
-        results.findings.push({
-          file,
-          line: loc.line,
-          type: 'systemDB with user context',
-          severity: 'critical',
-          message: `${fileName} uses systemDB() but has user authentication context → MUST use ${expectedLevel === 'ADMIN' ? 'adminDB(req)' : expectedLevel === 'USER' ? 'userDB(req)' : 'adminDB(req) or userDB(req)'}`,
-          snippet: loc.code,
-          fix: `Replace systemDB('context') with ${expectedLevel === 'ADMIN' ? 'adminDB(req)' : 'userDB(req)'}. systemDB bypasses RLS — user operations MUST go through RLS. See: stella_howto_get slug="tetra-architecture-guide"`
-        })
-        results.summary.critical++
-        results.summary.total++
-      }
-    }
-
-    // HIGH: Multiple DB helper types in one controller
-    if (usedLevels.length > 1) {
-      // Allow: Superadmin controllers use superadminDB which internally calls systemDB
-      // So tetra sees SUPERADMIN + SYSTEM (or SUPERADMIN + ADMIN) — both are legitimate
-      const isSuperadminMixingAdmin = expectedLevel === 'SUPERADMIN' &&
-        usedLevels.length === 2 &&
-        usedLevels.includes('SUPERADMIN') &&
-        (usedLevels.includes('ADMIN') || usedLevels.includes('SYSTEM'))
-
-      if (!isSuperadminMixingAdmin) {
-        results.passed = false
-        results.findings.push({
-          file,
-          line: 1,
-          type: 'mixed db usage',
-          severity: 'high',
-          message: `${fileName} mixes ${usedLevels.join(' + ')} database helpers. Controllers MUST use exactly ONE DB helper type.`,
-          fix: `Split into separate controllers per DB level, or refactor services to accept injected supabase client. Admin + System mix → move system ops to a separate SystemXxxController.`
-        })
-        results.summary.high++
-        results.summary.total++
-      }
-    }
-
-    // MEDIUM: DB helper doesn't match naming convention
-    if (expectedLevel && usedLevels.length === 1 && !usedLevels.includes(expectedLevel)) {
-      const actualLevel = usedLevels[0]
-      // Don't double-report if already caught as critical
-      if (!(actualLevel === 'SYSTEM' && userContextAvailable)) {
-        results.findings.push({
-          file,
-          line: 1,
-          type: 'naming mismatch',
-          severity: 'medium',
-          message: `${fileName} implies ${expectedLevel} but uses ${actualLevel}. Either rename the controller or change the DB helper.`,
-          fix: `Rename to match DB level, or change DB helper to match controller naming convention.`
-        })
-        results.summary.medium++
-        results.summary.total++
-      }
-    }
-  }
-
-  results.details.violations = results.findings.length
-  return results
-}

package/lib/checks/security/rls-live-audit.js

@@ -1,255 +0,0 @@
-/**
- * RLS Live DB Audit — queries pg_policies from the LIVE database
- *
- * The PRIMARY source of truth for RLS policy validation.
- * When this check runs successfully, migration-based RLS checks
- * (rls-policy-audit, config-rls-alignment) are skipped for current state
- * and only validate unapplied migrations (delta).
- *
- * Migration file parsing can miss:
- * - Policies applied directly via SQL (not in migration files)
- * - PL/pgSQL dynamic policies (EXECUTE format)
- * - Policies overridden by later manual changes
- *
- * Requires SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY in environment.
- *
- * Setup (one-time per project):
- *   CREATE OR REPLACE FUNCTION tetra_rls_audit()
- *   RETURNS TABLE(tablename text, policyname text, cmd text, using_clause text, with_check_clause text)
- *   LANGUAGE sql SECURITY DEFINER AS $$
- *     SELECT tablename::text, policyname::text, cmd::text, qual::text, with_check::text
- *     FROM pg_policies WHERE schemaname = 'public';
- *   $$;
- *
- *   -- Optional: also return RLS enabled status per table
- *   CREATE OR REPLACE FUNCTION tetra_rls_tables()
- *   RETURNS TABLE(table_name text, rls_enabled boolean, rls_forced boolean)
- *   LANGUAGE sql SECURITY DEFINER AS $$
- *     SELECT c.relname::text, c.relrowsecurity, c.relforcerowsecurity
- *     FROM pg_class c
- *     JOIN pg_namespace n ON n.oid = c.relnamespace
- *     WHERE n.nspname = 'public' AND c.relkind = 'r';
- *   $$;
- */
-
-export const meta = {
-  id: 'rls-live-audit',
-  name: 'RLS Live DB Audit',
-  category: 'security',
-  severity: 'critical',
-  description: 'Queries pg_policies from the live database and validates all RLS clauses against whitelisted patterns. Catches bypasses that migration parsing misses.'
-}
-
-const BANNED_RLS_PATTERNS = [
-  { pattern: /service_role/i, label: 'service_role bypass — service role already bypasses RLS at the Supabase layer' },
-  { pattern: /auth\.role\s*\(\)\s*=\s*'service_role'/i, label: 'auth.role() service_role bypass' },
-  { pattern: /current_setting\s*\(\s*'role'/i, label: 'PostgreSQL role check — bypasses tenant isolation' },
-  { pattern: /current_setting\s*\(\s*'request\.jwt\.claims'/i, label: 'JWT claims role check — bypasses tenant isolation' },
-  { pattern: /session_user/i, label: 'session_user check — bypasses tenant isolation' },
-  { pattern: /current_user\s*=/i, label: 'current_user check — bypasses tenant isolation' },
-  { pattern: /pg_has_role/i, label: 'pg_has_role — bypasses tenant isolation' },
-]
-
-const ALLOWED_RLS_PATTERNS = [
-  { pattern: /auth_admin_organizations\s*\(\)/i },
-  { pattern: /auth_user_organizations\s*\(\)/i },
-  { pattern: /auth_org_id\s*\(\)/i },
-  { pattern: /auth\.uid\s*\(\)/i },
-  { pattern: /auth_current_user_id\s*\(\)/i },
-  { pattern: /auth\.role\s*\(\)\s*=\s*'authenticated'/i },
-  { pattern: /auth\.role\s*\(\)\s*=\s*'anon'/i },
-  { pattern: /\w+\s*=\s*/i },
-  { pattern: /\w+\s+IS\s+(NOT\s+)?NULL/i },
-  { pattern: /\w+\s+IN\s*\(/i },
-  { pattern: /\w+\s*=\s*ANY\s*\(/i },
-  { pattern: /EXISTS\s*\(\s*SELECT/i },
-  { pattern: /^\s*\(?true\)?\s*$/i },
-  { pattern: /^\s*\(?false\)?\s*$/i },
-  { pattern: /auth\.jwt\s*\(\)/i },
-  { pattern: /current_setting\s*\(\s*'app\./i },
-  { pattern: /\b\w+\s*\([^)]*\)/i },
-]
-
-function validateRlsClause(clause) {
-  if (!clause || !clause.trim()) return null
-
-  for (const { pattern, label } of BANNED_RLS_PATTERNS) {
-    if (pattern.test(clause)) return label
-  }
-
-  if (!ALLOWED_RLS_PATTERNS.some(({ pattern }) => pattern.test(clause))) {
-    return `Unrecognized RLS clause: "${clause.substring(0, 150)}". Only whitelisted patterns allowed.`
-  }
-
-  return null
-}
-
-/**
- * Fetch data from a Supabase RPC endpoint.
- * Returns null if the RPC doesn't exist or fails.
- */
-async function callRpc(supabaseUrl, supabaseKey, rpcName) {
-  try {
-    const response = await fetch(`${supabaseUrl}/rest/v1/rpc/${rpcName}`, {
-      method: 'POST',
-      headers: {
-        'apikey': supabaseKey,
-        'Authorization': `Bearer ${supabaseKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: '{}',
-    })
-    if (!response.ok) return null
-    return await response.json()
-  } catch {
-    return null
-  }
-}
-
-/**
- * Build a structured live DB state from raw policy + table data.
- * This is the same format that config-rls-alignment uses from migration parsing,
- * so it can transparently use either source.
- *
- * Returns: Map<tableName, { rlsEnabled, policies: [{ name, operation, using, withCheck }] }>
- */
-export function buildLiveState(policies, tableStatus) {
-  const tables = new Map()
-
-  // Initialize from table status (if available)
-  if (Array.isArray(tableStatus)) {
-    for (const t of tableStatus) {
-      if (!t?.table_name) continue
-      tables.set(t.table_name, {
-        rlsEnabled: t.rls_enabled || false,
-        policies: [],
-        rpcFunctions: new Map(),
-        source: 'live-db'
-      })
-    }
-  }
-
-  // Add policies
-  for (const policy of policies) {
-    if (!policy) continue
-    const { tablename, policyname, cmd, using_clause, with_check_clause } = policy
-    if (!tablename) continue
-
-    if (!tables.has(tablename)) {
-      // Table exists in policies but not in table status — it has RLS (otherwise no policies)
-      tables.set(tablename, { rlsEnabled: true, policies: [], rpcFunctions: new Map(), source: 'live-db' })
-    }
-
-    tables.get(tablename).policies.push({
-      name: policyname,
-      operation: (cmd || 'ALL').toUpperCase(),
-      using: using_clause || '',
-      withCheck: with_check_clause || '',
-      file: 'LIVE DB'
-    })
-  }
-
-  return tables
-}
-
-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: { policiesChecked: 0, tablesChecked: 0, violations: 0 },
-    // Expose live data so runner can pass it to other checks
-    _liveData: null
-  }
-
-  const supabaseUrl = process.env.SUPABASE_URL
-  const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY
-
-  if (!supabaseUrl || !supabaseKey) {
-    results.skipped = true
-    results.skipReason = 'No SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY in environment'
-    return results
-  }
-
-  // Try to call tetra_rls_audit() RPC
-  let policies
-  try {
-    const response = await fetch(`${supabaseUrl}/rest/v1/rpc/tetra_rls_audit`, {
-      method: 'POST',
-      headers: {
-        'apikey': supabaseKey,
-        'Authorization': `Bearer ${supabaseKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: '{}',
-    })
-
-    if (!response.ok) {
-      const status = response.status
-      if (status === 404) {
-        results.skipped = true
-        results.skipReason = 'RPC tetra_rls_audit() not found. Create it once:\n\n  CREATE OR REPLACE FUNCTION tetra_rls_audit()\n  RETURNS TABLE(tablename text, policyname text, cmd text, using_clause text, with_check_clause text)\n  LANGUAGE sql SECURITY DEFINER AS $$\n    SELECT tablename::text, policyname::text, cmd::text, qual::text, with_check::text\n    FROM pg_policies WHERE schemaname = \'public\';\n  $$;'
-      } else {
-        results.skipped = true
-        results.skipReason = `RPC tetra_rls_audit() failed with status ${status}`
-      }
-      return results
-    }
-
-    policies = await response.json()
-  } catch (err) {
-    results.skipped = true
-    results.skipReason = `Failed to query live DB: ${err.message}`
-    return results
-  }
-
-  if (!Array.isArray(policies) || policies.length === 0) {
-    results.skipped = true
-    results.skipReason = 'No policies returned from tetra_rls_audit()'
-    return results
-  }
-
-  // Optionally fetch table-level RLS status
-  const tableStatus = await callRpc(supabaseUrl, supabaseKey, 'tetra_rls_tables')
-
-  // Build structured live state (shared with config-rls-alignment)
-  const liveState = buildLiveState(policies, tableStatus)
-  results._liveData = { policies, tableStatus, liveState }
-
-  const backendOnlyTables = config.supabase?.backendOnlyTables || []
-  const tablesChecked = new Set()
-
-  for (const policy of policies) {
-    if (!policy) continue
-    const { tablename, policyname, using_clause, with_check_clause } = policy
-
-    if (backendOnlyTables.includes(tablename)) continue
-    if (tablename?.startsWith('_') || tablename?.startsWith('pg_')) continue
-
-    tablesChecked.add(tablename)
-    results.details.policiesChecked++
-
-    for (const [clauseType, clause] of [['USING', using_clause], ['WITH CHECK', with_check_clause]]) {
-      if (!clause) continue
-      const violation = validateRlsClause(clause)
-      if (violation) {
-        results.passed = false
-        results.details.violations++
-        results.findings.push({
-          file: `LIVE DB → ${tablename}`,
-          line: 1,
-          type: 'rls-live-bypass',
-          severity: 'critical',
-          message: `[LIVE] Policy "${policyname}" on "${tablename}": ${violation}`,
-          fix: 'Fix the policy in the database and add a corrective migration.'
-        })
-        results.summary.critical++
-        results.summary.total++
-      }
-    }
-  }
-
-  results.details.tablesChecked = tablesChecked.size
-  return results
-}