@soulbatical/tetra-dev-toolkit 1.11.0 → 1.12.0

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

@@ -0,0 +1,180 @@
+/**
+ * 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'
+
+const DB_PATTERNS = {
+  systemDB:     { level: 'SYSTEM',     pattern: /systemDB\s*\(/g,     desc: 'System-level (cron, webhooks)' },
+  adminDB:      { level: 'ADMIN',      pattern: /adminDB\s*\(/g,      desc: 'Admin operations (org-scoped)' },
+  userDB:       { level: 'USER',       pattern: /userDB\s*\(/g,       desc: 'User-specific operations' },
+  publicDB:     { level: 'PUBLIC',     pattern: /publicDB\s*\(/g,     desc: 'Public/unauthenticated' },
+  superadminDB: { level: 'SUPERADMIN', pattern: /superadminDB\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 check(projectRoot, config = {}) {
+  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 }
+  }
+
+  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)
+
+    // 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) {
+      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/runner.js

@@ -13,6 +13,7 @@ import * as deprecatedSupabaseAdmin from './checks/security/deprecated-supabase-
 import * as directSupabaseClient from './checks/security/direct-supabase-client.js'
 import * as frontendSupabaseQueries from './checks/security/frontend-supabase-queries.js'
 import * as tetraCoreCompliance from './checks/security/tetra-core-compliance.js'
+import * as mixedDbUsage from './checks/security/mixed-db-usage.js'
 import * as systemdbWhitelist from './checks/security/systemdb-whitelist.js'
 import * as huskyHooks from './checks/stability/husky-hooks.js'
 import * as ciPipeline from './checks/stability/ci-pipeline.js'
@@ -37,6 +38,7 @@ const ALL_CHECKS = {
     directSupabaseClient,
     frontendSupabaseQueries,
     tetraCoreCompliance,
+    mixedDbUsage,
     systemdbWhitelist,
     gitignoreValidation
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "publishConfig": {
     "access": "restricted"
   },