@soulbatical/tetra-dev-toolkit 1.13.0 → 1.14.0

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

@@ -20,9 +20,9 @@
  * Reference: stella_howto_get slug="tetra-architecture-guide"
  */
 
-import { readFileSync, existsSync } from 'fs'
+import { readFileSync, existsSync, readdirSync } from 'fs'
 import { join } from 'path'
-import { glob } from 'glob'
+import { globSync } from 'glob'
 
 export const meta = {
   id: 'config-rls-alignment',
@@ -176,7 +176,6 @@ function parseMigrations(projectRoot) {
 }
 
 function findFiles(projectRoot, pattern) {
-  const { globSync } = require('glob')
   try {
     return globSync(pattern, { cwd: projectRoot, absolute: true, ignore: ['**/node_modules/**'] })
   } catch {

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

@@ -0,0 +1,306 @@
+/**
+ * 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)
+}
+
+/**
+ * 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 }
+  }
+
+  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) {
+    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
+          if (!hasAuthMiddleware(content)) {
+            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
+          if (!hasOrgAdminMiddleware(content)) {
+            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 ---
+      if (cfg.accessLevel === 'admin' && routeName === 'publicRoutes.ts' && !hasAuthMiddleware(content)) {
+        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 ensure it only exposes non-sensitive endpoints.`
+        })
+        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

@@ -0,0 +1,169 @@
+/**
+ * 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.'
+}
+
+// Auth helper functions that legitimately need SECURITY DEFINER
+const BUILTIN_DEFINER_WHITELIST = [
+  'auth_org_id',
+  'auth_admin_organizations',
+  'auth_user_organizations',
+  'get_user_org_role',
+  'get_org_id',
+  'handle_new_user',
+  'moddatetime',
+  // 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
+}

package/lib/runner.js

@@ -15,6 +15,7 @@ import * as frontendSupabaseQueries from './checks/security/frontend-supabase-qu
 import * as tetraCoreCompliance from './checks/security/tetra-core-compliance.js'
 import * as mixedDbUsage from './checks/security/mixed-db-usage.js'
 import * as configRlsAlignment from './checks/security/config-rls-alignment.js'
+import * as rpcSecurityMode from './checks/security/rpc-security-mode.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'
@@ -24,6 +25,7 @@ import * as fileSize from './checks/codeQuality/file-size.js'
 import * as namingConventions from './checks/codeQuality/naming-conventions.js'
 import * as routeSeparation from './checks/codeQuality/route-separation.js'
 import * as gitignoreValidation from './checks/security/gitignore-validation.js'
+import * as routeConfigAlignment from './checks/security/route-config-alignment.js'
 import * as rlsPolicyAudit from './checks/supabase/rls-policy-audit.js'
 import * as rpcParamMismatch from './checks/supabase/rpc-param-mismatch.js'
 import * as rpcGeneratorOrigin from './checks/supabase/rpc-generator-origin.js'
@@ -41,8 +43,10 @@ const ALL_CHECKS = {
     tetraCoreCompliance,
     mixedDbUsage,
     configRlsAlignment,
+    rpcSecurityMode,
     systemdbWhitelist,
-    gitignoreValidation
+    gitignoreValidation,
+    routeConfigAlignment
   ],
   stability: [
     huskyHooks,

package/package.json

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