@soulbatical/tetra-dev-toolkit 1.10.2 → 1.12.0

package/lib/checks/security/deprecated-supabase-admin.js

@@ -24,14 +24,23 @@ export async function run(config, projectRoot) {
     summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
   }
 
-  // Check if project uses the systemDB/userDB pattern
-  const hasSystemDb = existsSync(`${projectRoot}/backend/src/core/systemDb.ts`) ||
-                      existsSync(`${projectRoot}/src/core/systemDb.ts`)
+  // Check if project uses the systemDB/userDB pattern (local file OR tetra-core package)
+  const hasLocalSystemDb = existsSync(`${projectRoot}/backend/src/core/systemDb.ts`) ||
+                           existsSync(`${projectRoot}/src/core/systemDb.ts`)
 
-  if (!hasSystemDb) {
-    // Project doesn't use this pattern, skip check
+  let hasTetraCore = false
+  for (const pkgPath of [`${projectRoot}/package.json`, `${projectRoot}/backend/package.json`]) {
+    if (!existsSync(pkgPath)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+      if (deps['@soulbatical/tetra-core']) { hasTetraCore = true; break }
+    } catch { /* skip */ }
+  }
+
+  if (!hasLocalSystemDb && !hasTetraCore) {
     results.skipped = true
-    results.skipReason = 'Project does not use systemDB/userDB pattern'
+    results.skipReason = 'Project does not use systemDB/userDB pattern (no local systemDb.ts and no @soulbatical/tetra-core)'
     return results
   }
 

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/checks/security/systemdb-whitelist.js

@@ -106,39 +106,55 @@ export async function run(config, projectRoot) {
     }
   }
 
-  if (!systemDbPath) {
+  // Also check if project has tetra-core as npm package (no local systemDb.ts)
+  let hasTetraCore = false
+  for (const pkgPath of [`${projectRoot}/package.json`, `${projectRoot}/backend/package.json`]) {
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+        if (deps['@soulbatical/tetra-core']) { hasTetraCore = true; break }
+      } catch { /* skip */ }
+    }
+  }
+
+  if (!systemDbPath && !hasTetraCore) {
     results.skipped = true
-    results.skipReason = 'No systemDb.ts found'
+    results.skipReason = 'No systemDb.ts found and no @soulbatical/tetra-core dependency'
     return results
   }
 
-  const systemDbContent = readFileSync(systemDbPath, 'utf-8')
-  const whitelistMatch = systemDbContent.match(/new Set\s*(?:<[^>]+>)?\s*\(\s*\[([\s\S]*?)\]\s*\)/m)
-
   let whitelist = new Set()
-  if (whitelistMatch) {
-    const entries = whitelistMatch[1]
-      .split('\n')
-      .map(line => {
-        const m = line.match(/['"]([^'"]+)['"]/)
-        return m ? m[1] : null
-      })
-      .filter(Boolean)
-    whitelist = new Set(entries)
-  }
 
-  if (whitelist.size > MAX_WHITELIST_SIZE) {
-    results.passed = false
-    results.findings.push({
-      file: systemDbPath.replace(projectRoot + '/', ''),
-      line: 1,
-      type: 'whitelist-too-large',
-      severity: 'critical',
-      message: `systemDB whitelist has ${whitelist.size} entries (max: ${MAX_WHITELIST_SIZE}). This indicates systemDB is being used where SupabaseUserClient should be used instead. Refactor services to accept a supabase client parameter instead of calling systemDB() directly.`,
-      fix: `Refactor: services should receive a supabase client via dependency injection, not create their own via systemDB(). Only cron jobs, webhooks, and OAuth callbacks should use systemDB.`
-    })
-    results.summary.critical++
-    results.summary.total++
+  // Only check whitelist size if there's a local systemDb.ts
+  if (systemDbPath) {
+    const systemDbContent = readFileSync(systemDbPath, 'utf-8')
+    const whitelistMatch = systemDbContent.match(/new Set\s*(?:<[^>]+>)?\s*\(\s*\[([\s\S]*?)\]\s*\)/m)
+
+    if (whitelistMatch) {
+      const entries = whitelistMatch[1]
+        .split('\n')
+        .map(line => {
+          const m = line.match(/['"]([^'"]+)['"]/)
+          return m ? m[1] : null
+        })
+        .filter(Boolean)
+      whitelist = new Set(entries)
+    }
+
+    if (whitelist.size > MAX_WHITELIST_SIZE) {
+      results.passed = false
+      results.findings.push({
+        file: systemDbPath.replace(projectRoot + '/', ''),
+        line: 1,
+        type: 'whitelist-too-large',
+        severity: 'critical',
+        message: `systemDB whitelist has ${whitelist.size} entries (max: ${MAX_WHITELIST_SIZE}). This indicates systemDB is being used where adminDB/userDB should be used instead.`,
+        fix: `Refactor: services should receive a supabase client via dependency injection, not create their own via systemDB(). Only cron jobs, webhooks, and OAuth callbacks should use systemDB.`
+      })
+      results.summary.critical++
+      results.summary.total++
+    }
   }
 
   // ─── Check 2: systemDB in forbidden locations ───────────────
@@ -146,6 +162,10 @@ export async function run(config, projectRoot) {
   const files = await glob('**/*.ts', {
     cwd: projectRoot,
     ignore: [
+      '**/node_modules/**',
+      '**/.next/**',
+      '**/dist/**',
+      '**/build/**',
       ...config.ignore,
       '**/systemDb.ts',
       '**/superadminDb.ts',

package/lib/checks/security/tetra-core-compliance.js

@@ -0,0 +1,197 @@
+/**
+ * Tetra Core Compliance — HARD BLOCK
+ *
+ * If a project has @soulbatical/tetra-core as a dependency, it MUST use:
+ * 1. configureAuth() — sets up authentication middleware
+ * 2. authenticateToken — middleware on protected routes
+ * 3. adminDB/userDB/systemDB — db helpers (NOT raw createClient)
+ *
+ * If ANY of these are missing, the project is NOT secure.
+ * There is no "skip" — if you have tetra-core, you use it fully or not at all.
+ *
+ * This check also detects projects that SHOULD have tetra-core but don't:
+ * - Has a backend/ dir with Express + Supabase → MUST have tetra-core
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import { glob } from 'glob'
+
+export const meta = {
+  id: 'tetra-core-compliance',
+  name: 'Tetra Core Compliance',
+  category: 'security',
+  severity: 'critical',
+  description: 'Ensures projects using @soulbatical/tetra-core implement ALL required security patterns — auth, middleware, db helpers'
+}
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // ─── Step 1: Does this project have tetra-core? ────────────────
+
+  const packageJsonPaths = [
+    join(projectRoot, 'package.json'),
+    join(projectRoot, 'backend', 'package.json')
+  ]
+
+  let hasTetraCore = false
+  let tetraCoreLocation = null
+
+  for (const pkgPath of packageJsonPaths) {
+    if (!existsSync(pkgPath)) continue
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+      if (deps['@soulbatical/tetra-core']) {
+        hasTetraCore = true
+        tetraCoreLocation = pkgPath.replace(projectRoot + '/', '')
+        break
+      }
+    } catch { /* skip */ }
+  }
+
+  // ─── Step 2: Check if project SHOULD have tetra-core ───────────
+
+  if (!hasTetraCore) {
+    // Check if this is an Express + Supabase backend that should have it
+    const backendDirs = ['backend/src', 'src']
+    let hasExpress = false
+    let hasSupabase = false
+
+    for (const dir of backendDirs) {
+      const pkgPath = dir === 'src' ? join(projectRoot, 'package.json') : join(projectRoot, 'backend', 'package.json')
+      if (!existsSync(pkgPath)) continue
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+        if (deps['express']) hasExpress = true
+        if (deps['@supabase/supabase-js']) hasSupabase = true
+      } catch { /* skip */ }
+    }
+
+    if (hasExpress && hasSupabase) {
+      results.passed = false
+      results.findings.push({
+        type: 'missing-tetra-core',
+        severity: 'critical',
+        message: 'Project has Express + Supabase but does NOT have @soulbatical/tetra-core. This means NO standard auth middleware, NO db helpers, NO RLS enforcement. Install tetra-core and follow the architecture guide.',
+        fix: 'npm install @soulbatical/tetra-core && see stella_howto_get slug="tetra-architecture-guide"'
+      })
+      results.summary.critical++
+      results.summary.total++
+    } else {
+      // Not a backend project, skip
+      results.skipped = true
+      results.skipReason = 'Not a Tetra backend project (no Express + Supabase)'
+      return results
+    }
+
+    return results
+  }
+
+  // ─── Step 3: Has tetra-core → check FULL compliance ────────────
+
+  const backendSrc = existsSync(join(projectRoot, 'backend', 'src')) ? 'backend/src' : 'src'
+
+  // Check 3a: configureAuth() is called somewhere
+  const tsFiles = await glob(`${backendSrc}/**/*.ts`, {
+    cwd: projectRoot,
+    ignore: ['**/node_modules/**', '**/*.test.ts', '**/*.spec.ts', '**/*.d.ts']
+  })
+
+  let hasConfigureAuth = false
+  let hasAuthenticateToken = false
+  let hasDbHelpers = false
+  let dbHelperImports = { adminDB: false, userDB: false, systemDB: false, publicDB: false, superadminDB: false }
+  let hasRawCreateClient = false
+  let rawCreateClientFiles = []
+
+  for (const file of tsFiles) {
+    try {
+      const content = readFileSync(join(projectRoot, file), 'utf-8')
+
+      if (content.includes('configureAuth')) hasConfigureAuth = true
+      if (content.includes('authenticateToken')) hasAuthenticateToken = true
+
+      // Check for db helper usage
+      if (/(?:import|from).*(?:adminDB|userDB|systemDB|publicDB|superadminDB)/.test(content)) {
+        hasDbHelpers = true
+        if (content.includes('adminDB')) dbHelperImports.adminDB = true
+        if (content.includes('userDB')) dbHelperImports.userDB = true
+        if (content.includes('systemDB')) dbHelperImports.systemDB = true
+        if (content.includes('publicDB')) dbHelperImports.publicDB = true
+        if (content.includes('superadminDB')) dbHelperImports.superadminDB = true
+      }
+
+      // Check for raw createClient usage (should be caught by direct-supabase-client check too)
+      if (/import\s*\{[^}]*createClient[^}]*\}\s*from\s*['"]@supabase\/supabase-js['"]/.test(content)) {
+        if (!/import\s+type/.test(content)) {
+          // Not in core wrapper files
+          if (!/core\//.test(file) && !/SupabaseUserClient/.test(file) && !/scripts\//.test(file)) {
+            hasRawCreateClient = true
+            rawCreateClientFiles.push(file)
+          }
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  // ─── Report findings ──────────────────────────────────────────
+
+  if (!hasConfigureAuth) {
+    results.passed = false
+    results.findings.push({
+      type: 'missing-configureAuth',
+      severity: 'critical',
+      message: 'Project has @soulbatical/tetra-core but NEVER calls configureAuth(). This means the auth middleware is not initialized — all routes are potentially unprotected.',
+      fix: 'Create an auth-config.ts that calls configureAuth({ loadUserContext, roleHierarchy }). See sparkbuddy-live/backend/src/auth-config.ts for reference.'
+    })
+    results.summary.critical++
+    results.summary.total++
+  }
+
+  if (!hasAuthenticateToken) {
+    results.passed = false
+    results.findings.push({
+      type: 'missing-authenticateToken',
+      severity: 'critical',
+      message: 'Project has @soulbatical/tetra-core but NO route uses authenticateToken middleware. All API endpoints are unprotected.',
+      fix: 'Add authenticateToken middleware to all protected routes: router.use(authenticateToken, requireOrganizationAdmin)'
+    })
+    results.summary.critical++
+    results.summary.total++
+  }
+
+  if (!hasDbHelpers) {
+    results.passed = false
+    results.findings.push({
+      type: 'missing-db-helpers',
+      severity: 'critical',
+      message: 'Project has @soulbatical/tetra-core but does NOT use any db helpers (adminDB, userDB, systemDB, publicDB). Database access has no RLS enforcement.',
+      fix: 'Use adminDB(req) for admin routes, userDB(req) for user routes, systemDB(context) for system operations. See stella_howto_get slug="tetra-architecture-guide"'
+    })
+    results.summary.critical++
+    results.summary.total++
+  }
+
+  // Info: which helpers are used
+  const usedHelpers = Object.entries(dbHelperImports).filter(([_, used]) => used).map(([name]) => name)
+  const unusedHelpers = Object.entries(dbHelperImports).filter(([_, used]) => !used).map(([name]) => name)
+
+  results.info = {
+    tetraCoreLocation,
+    configureAuth: hasConfigureAuth,
+    authenticateToken: hasAuthenticateToken,
+    dbHelpers: {
+      used: usedHelpers,
+      unused: unusedHelpers
+    }
+  }
+
+  return results
+}

package/lib/runner.js

@@ -12,6 +12,8 @@ import * as serviceKeyExposure from './checks/security/service-key-exposure.js'
 import * as deprecatedSupabaseAdmin from './checks/security/deprecated-supabase-admin.js'
 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'
@@ -35,6 +37,8 @@ const ALL_CHECKS = {
     deprecatedSupabaseAdmin,
     directSupabaseClient,
     frontendSupabaseQueries,
+    tetraCoreCompliance,
+    mixedDbUsage,
     systemdbWhitelist,
     gitignoreValidation
   ],

package/package.json

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