@soulbatical/tetra-dev-toolkit 1.16.3 → 1.17.1

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

@@ -280,6 +280,35 @@ function isWideOpen(using) {
   return using.trim() === 'true' || using.trim() === '(true)'
 }
 
+/**
+ * Forbidden patterns in RLS policies — these bypass RLS and defeat the purpose.
+ * Valid patterns (from sparkbuddy-live):
+ *   - organization_id IN (SELECT auth_admin_organizations())
+ *   - user_id = auth.uid()
+ *   - USING(true) for public tables only
+ *   - Subquery to parent table with org/user check
+ *
+ * Everything else that grants blanket access is a security hole.
+ */
+const FORBIDDEN_RLS_PATTERNS = [
+  { pattern: /service_role/i, label: 'service_role bypass' },
+  { pattern: /current_setting\s*\(\s*'role'/i, label: 'PostgreSQL role check bypass' },
+  { pattern: /current_setting\s*\(\s*'request\.jwt\.claims'/i, label: 'JWT claims role bypass' },
+  { pattern: /session_user\s*=\s*'postgres'/i, label: 'session_user postgres bypass' },
+  { pattern: /current_user\s*=\s*'postgres'/i, label: 'current_user postgres bypass' },
+  { pattern: /auth\.role\s*\(\)\s*=\s*'service_role'/i, label: 'auth.role() service_role bypass' },
+  { pattern: /pg_has_role/i, label: 'pg_has_role bypass' },
+]
+
+/**
+ * Check if a USING/WITH CHECK clause contains forbidden bypass patterns
+ * Returns array of { label } for each forbidden pattern found
+ */
+function findForbiddenPatterns(clause) {
+  if (!clause) return []
+  return FORBIDDEN_RLS_PATTERNS.filter(({ pattern }) => pattern.test(clause)).map(({ label }) => label)
+}
+
 export async function run(config, projectRoot) {
   const results = {
     passed: true,
@@ -424,8 +453,12 @@ export async function run(config, projectRoot) {
       }
     }
 
-    // CHECK 4: RPC functions must be SECURITY INVOKER
+    // CHECK 4: RPC functions must be SECURITY INVOKER (unless whitelisted)
+    const definerWhitelist = config?.supabase?.securityDefinerWhitelist || []
     for (const rpcName of cfg.rpcFunctions) {
+      // Skip if explicitly whitelisted in config
+      if (definerWhitelist.includes(rpcName)) continue
+
       const rpcInfo = tableRls.rpcFunctions.get(rpcName)
       if (rpcInfo && rpcInfo.securityMode === 'DEFINER') {
         results.passed = false
@@ -435,7 +468,28 @@ export async function run(config, projectRoot) {
           type: 'rpc-security-definer',
           severity: 'critical',
           message: `RPC function "${rpcName}" for table "${tableName}" uses SECURITY DEFINER — this BYPASSES RLS completely. Any authenticated user can see ALL data.`,
-          fix: `Change to SECURITY INVOKER or remove the SECURITY DEFINER clause.`
+          fix: `Change to SECURITY INVOKER or add "${rpcName}" to supabase.securityDefinerWhitelist in .tetra-quality.json.`
+        })
+        results.summary.critical++
+        results.summary.total++
+      }
+    }
+
+    // CHECK 4b: No forbidden bypass patterns in any policy clause
+    for (const p of policies) {
+      const usingViolations = findForbiddenPatterns(p.using)
+      const checkViolations = findForbiddenPatterns(p.withCheck)
+      const allViolations = [...new Set([...usingViolations, ...checkViolations])]
+
+      if (allViolations.length > 0) {
+        results.passed = false
+        results.findings.push({
+          file: p.file,
+          line: 1,
+          type: 'rls-bypass-pattern',
+          severity: 'critical',
+          message: `Policy "${p.name}" on table "${tableName}" contains forbidden bypass pattern(s): ${allViolations.join(', ')}. RLS policies must ONLY use auth.uid(), auth_admin_organizations(), or parent-table subqueries. Service role bypasses RLS automatically — adding it to policies defeats the purpose.`,
+          fix: `Remove the bypass clause. Valid patterns: USING (organization_id IN (SELECT auth_admin_organizations())) or USING (user_id = auth.uid()).`
         })
         results.summary.critical++
         results.summary.total++

package/lib/checks/security/direct-supabase-client.js

@@ -74,8 +74,8 @@ export async function run(config, projectRoot) {
     summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
   }
 
-  // Build whitelist from hardcoded + config
-  const configWhitelist = config?.supabase?.directSupabaseClientWhitelist || config?.directSupabaseClientWhitelist || []
+  // Build whitelist from hardcoded + config (canonical: security.directSupabaseClientWhitelist)
+  const configWhitelist = config?.security?.directSupabaseClientWhitelist || config?.directSupabaseClientWhitelist || []
   const extraPatterns = configWhitelist.map(p => new RegExp(p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
   const allAllowed = [...ALLOWED_FILES, ...extraPatterns]
 

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

@@ -77,7 +77,8 @@ export async function run(config, projectRoot) {
   }
 
   // Config-based ignore for controllers that legitimately mix DB helpers
-  const mixedDbIgnore = config?.supabase?.mixedDbUsageIgnore || []
+  // Canonical: security.mixedDbWhitelist
+  const mixedDbIgnore = config?.security?.mixedDbWhitelist || config?.mixedDbWhitelist || []
 
   const files = await glob('**/*[Cc]ontroller*.ts', {
     cwd: projectRoot,
@@ -157,11 +158,12 @@ export async function run(config, projectRoot) {
 
     // HIGH: Multiple DB helper types in one controller
     if (usedLevels.length > 1) {
-      // Allow: Superadmin controllers may legitimately use SUPERADMIN + ADMIN
+      // 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('ADMIN') || usedLevels.includes('SYSTEM'))
 
       if (!isSuperadminMixingAdmin) {
         results.passed = false

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

@@ -102,6 +102,32 @@ 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
  */
@@ -123,8 +149,11 @@ export async function run(config, projectRoot) {
     details: { routesChecked: 0, violations: 0 }
   }
 
-  // Config-based ignore for specific features/routes
-  const routeIgnore = config?.supabase?.routeConfigAlignmentIgnore || []
+  // 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)
 
@@ -176,8 +205,8 @@ export async function run(config, projectRoot) {
       if (cfg.accessLevel === 'admin') {
         // Route name should be adminRoutes.ts
         if (routeName === 'adminRoutes.ts') {
-          // CRITICAL: admin route MUST have authenticateToken
-          if (!hasAuthMiddleware(content)) {
+          // CRITICAL: admin route MUST have authenticateToken (in file OR via RouteManager group)
+          if (!hasAuthMiddleware(content) && !routeManagerHasGroupAuth) {
             results.findings.push({
               file: relRouteFile,
               line: 1,
@@ -192,8 +221,8 @@ export async function run(config, projectRoot) {
             results.details.violations++
           }
 
-          // CRITICAL: admin route MUST have requireOrganizationAdmin
-          if (!hasOrgAdminMiddleware(content)) {
+          // CRITICAL: admin route MUST have requireOrganizationAdmin (in file OR via RouteManager group)
+          if (!hasOrgAdminMiddleware(content) && !routeManagerHasGroupAuth) {
             results.findings.push({
               file: relRouteFile,
               line: 1,

package/lib/checks/security/systemdb-whitelist.js

@@ -86,7 +86,8 @@ const FORBIDDEN_FILE_PATTERNS = [
 const DEFAULT_MAX_WHITELIST_SIZE = 35
 
 export async function run(config, projectRoot) {
-  const MAX_WHITELIST_SIZE = config?.supabase?.maxWhitelistEntries || DEFAULT_MAX_WHITELIST_SIZE
+  // Canonical: security.systemDbMaxEntries
+  const MAX_WHITELIST_SIZE = config?.security?.systemDbMaxEntries || config?.systemDB?.maxWhitelistEntries || DEFAULT_MAX_WHITELIST_SIZE
   const results = {
     passed: true,
     findings: [],

package/lib/config.js

@@ -42,7 +42,13 @@ export const DEFAULT_CONFIG = {
     // Code patterns
     checkSqlInjection: true,
     checkEvalUsage: true,
-    checkCommandInjection: true
+    checkCommandInjection: true,
+
+    // Whitelists — project-specific overrides in .tetra-quality.json
+    directSupabaseClientWhitelist: [],  // Files allowed to import createClient directly
+    mixedDbWhitelist: [],               // Controllers allowed to mix DB helper types
+    routeConfigIgnore: [],              // Tables to skip in route↔config alignment check
+    systemDbMaxEntries: 35              // Max systemDB whitelist entries before warning
   },
 
   // Stability checks

package/package.json

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