@soulbatical/tetra-dev-toolkit 1.16.2 → 1.17.0

package/README.md

@@ -58,7 +58,7 @@ LAYER 8: DB HELPERS            adminDB/userDB/publicDB/systemDB enforce correct
 | `tetra-audit` | Run quality/security/hygiene checks |
 | `tetra-audit quick` | Quick critical checks (pre-commit) |
 | `tetra-audit security` | Full security suite (12 checks) |
-| `tetra-audit stability` | Stability suite (3 checks) |
+| `tetra-audit stability` | Stability suite (16 checks) |
 | `tetra-audit codeQuality` | Code quality suite (4 checks) |
 | `tetra-audit supabase` | Supabase suite (3 checks) |
 | `tetra-audit hygiene` | Repo hygiene suite (2 checks) |
@@ -119,13 +119,26 @@ Exit codes: `0` = passed, `1` = failed (CRITICAL/HIGH), `2` = error. No middle g
 | `rpc-param-mismatch` | critical | TypeScript `.rpc()` calls with wrong parameter names vs SQL |
 | `rpc-generator-origin` | high | RPC functions not generated by Tetra SQL Generator |
 
-### Stability (3 checks)
+### Stability (16 checks)
 
 | Check | Severity | What it catches |
 |-------|----------|-----------------|
 | `husky-hooks` | medium | Missing pre-commit/pre-push hooks |
 | `ci-pipeline` | medium | Missing or incomplete CI config |
 | `npm-audit` | high | Known vulnerabilities in dependencies |
+| `tests` | high | Missing test framework, test files, or test scripts |
+| `eslint-security` | high | Missing ESLint config, security plugin, or SonarJS plugin |
+| `typescript-strict` | medium | TypeScript strict mode not enabled |
+| `coverage-thresholds` | medium | No coverage thresholds configured |
+| `knip` | medium | Dead code: unused files, dependencies, exports |
+| `dependency-cruiser` | medium | Circular dependencies, architecture violations |
+| `dependency-automation` | medium | No Dependabot or Renovate configured |
+| `prettier` | low | No code formatter configured |
+| `conventional-commits` | low | No commit message convention enforced |
+| `bundle-size` | low | No bundle size monitoring |
+| `sast` | medium | No static application security testing |
+| `license-audit` | low | No license compliance checking |
+| `security-layers` | high | Missing security layers (auth, rate limiting, CORS, etc.) |
 
 ### Code Quality (4 checks)
 
@@ -220,6 +233,18 @@ If any step fails, fix it before writing code. No exceptions.
 
 ## Changelog
 
+### 1.16.0
+
+**New: Full Stability Suite (16 checks)**
+- Stability suite expanded from 3 → 16 checks via health check adapter
+- New checks: tests, eslint-security, typescript-strict, coverage-thresholds, knip, dependency-cruiser, dependency-automation, prettier, conventional-commits, bundle-size, sast, license-audit, security-layers
+- `tetra-audit stability` now catches missing test infrastructure, dead code, formatting, and security layer gaps
+- Health checks (score-based) automatically adapted to runner format (pass/fail)
+- RPC generator: SECURITY DEFINER → SECURITY INVOKER for all data RPCs
+- Migration lint: expanded whitelist for legitimate DEFINER functions
+- Mixed DB checker: fixed regex that matched `superadminDB` as `adminDB`
+- Route config checker: support `@tetra-audit-ignore` directive
+
 ### 1.15.0
 
 **New: Migration Lint + DB Push Guard**

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

@@ -184,6 +184,43 @@ function parseMigrations(projectRoot) {
         })
       }
 
+      // Find PL/pgSQL loop-based CREATE POLICY patterns (DO blocks with EXECUTE format)
+      // Handles two patterns:
+      //   Pattern A: FOR t IN SELECT unnest(ARRAY['table1','table2']) LOOP ... EXECUTE format('CREATE POLICY ...')
+      //   Pattern B: tables TEXT[] := ARRAY['table1','table2']; FOREACH tbl IN ARRAY tables LOOP ... EXECUTE format('CREATE POLICY ...')
+      if (/DO\s+\$/.test(content) && /EXECUTE\s+format\s*\(\s*'CREATE\s+POLICY/i.test(content)) {
+        // Try unnest pattern first, then FOREACH/variable pattern
+        const arrayMatch = content.match(/unnest\s*\(\s*ARRAY\s*\[\s*'([^[\]]+)'\s*\]/i)
+          || content.match(/(?:TEXT\[\]|text\[\])\s*:=\s*ARRAY\s*\[\s*'([^[\]]+)'\s*\]/i)
+        if (arrayMatch) {
+          const loopTables = arrayMatch[1].split(/'\s*,\s*'/).map(t => t.trim())
+          const execLines = [...content.matchAll(/EXECUTE\s+format\s*\(\s*'(CREATE\s+POLICY\s+.*?)'\s*,/gi)]
+          for (const exec of execLines) {
+            const stmt = exec[1]
+            const forOp = stmt.match(/FOR\s+(SELECT|INSERT|UPDATE|DELETE|ALL)/i)
+            const operation = forOp ? forOp[1].toUpperCase() : 'ALL'
+            const hasUsing = /\bUSING\b/i.test(stmt)
+            const hasWithCheck = /WITH\s+CHECK/i.test(stmt)
+            const condMatch = stmt.match(/(?:USING|WITH\s+CHECK)\s*\(\s*(.*?)\s*\)/i)
+            const condition = condMatch ? condMatch[1] : ''
+
+            for (const table of loopTables) {
+              if (!tables.has(table)) tables.set(table, { rlsEnabled: false, policies: [], rpcFunctions: new Map() })
+              const policyName = `${table}_${operation.toLowerCase()}_org`
+              if (!tables.get(table).policies.find(p => p.name === policyName)) {
+                tables.get(table).policies.push({
+                  name: policyName,
+                  operation,
+                  using: hasUsing ? condition : '',
+                  withCheck: hasWithCheck ? condition : '',
+                  file: relFile
+                })
+              }
+            }
+          }
+        }
+      }
+
       // Find RPC functions and their security mode
       const funcRegex = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+(?:public\.)?(\w+)\s*\(([\s\S]*?)\)\s*RETURNS\s+([\s\S]*?)(?:LANGUAGE|AS)/gi
       for (const m of content.matchAll(funcRegex)) {
@@ -204,6 +241,7 @@ function parseMigrations(projectRoot) {
         }
       }
     }
+
   }
 
   return tables
@@ -221,8 +259,10 @@ function findFiles(projectRoot, pattern) {
  * Check if a USING clause enforces org isolation
  */
 function isOrgIsolation(using) {
-  return /auth_org_id\(\)|auth_admin_organizations\(\)/i.test(using) &&
-         /organization_id/i.test(using)
+  const hasOrgFunction = /auth_org_id\(\)|auth_admin_organizations\(\)/i.test(using)
+  // Legacy pattern: auth.jwt() -> 'app_metadata' ->> 'organization_id'
+  const hasLegacyJwtOrg = /auth\.jwt\(\)\s*->\s*'app_metadata'\s*->>\s*'organization_id'/i.test(using)
+  return (hasOrgFunction || hasLegacyJwtOrg) && /organization_id/i.test(using)
 }
 
 /**
@@ -287,6 +327,7 @@ export async function run(config, projectRoot) {
     const updatePolicies = policies.filter(p => p.operation === 'UPDATE' || p.operation === 'ALL')
     const deletePolicies = policies.filter(p => p.operation === 'DELETE' || p.operation === 'ALL')
 
+
     // CHECK 2: Must have policies for all operations
     const missingOps = []
     if (selectPolicies.length === 0) missingOps.push('SELECT')
@@ -383,8 +424,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
@@ -394,7 +439,7 @@ 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++

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/lib/runner.js

@@ -32,6 +32,56 @@ import * as rpcGeneratorOrigin from './checks/supabase/rpc-generator-origin.js'
 import * as fileOrganization from './checks/hygiene/file-organization.js'
 import * as stellaCompliance from './checks/hygiene/stella-compliance.js'
 
+// Health checks (score-based) — wrapped as runner checks via adapter
+import { check as checkTests } from './checks/health/tests.js'
+import { check as checkEslintSecurity } from './checks/health/eslint-security.js'
+import { check as checkTypescriptStrict } from './checks/health/typescript-strict.js'
+import { check as checkCoverageThresholds } from './checks/health/coverage-thresholds.js'
+import { check as checkKnip } from './checks/health/knip.js'
+import { check as checkDependencyCruiser } from './checks/health/dependency-cruiser.js'
+import { check as checkDependencyAutomation } from './checks/health/dependency-automation.js'
+import { check as checkPrettier } from './checks/health/prettier.js'
+import { check as checkConventionalCommits } from './checks/health/conventional-commits.js'
+import { check as checkBundleSize } from './checks/health/bundle-size.js'
+import { check as checkSast } from './checks/health/sast.js'
+import { check as checkLicenseAudit } from './checks/health/license-audit.js'
+import { check as checkSecurityLayers } from './checks/health/security-layers.js'
+
+/**
+ * Adapt a health check (score-based) to the runner format (meta + run).
+ * A health check passes if it scores > 0 (has at least some infrastructure).
+ */
+function adaptHealthCheck(id, name, severity, healthCheckFn) {
+  return {
+    meta: { id, name, severity },
+    async run(config, projectRoot) {
+      const result = await healthCheckFn(projectRoot)
+      const passed = result.score > 0
+      const findings = []
+
+      if (!passed && result.details?.message) {
+        findings.push({
+          file: 'project',
+          line: 0,
+          severity,
+          message: result.details.message
+        })
+      }
+
+      return {
+        passed,
+        findings,
+        summary: {
+          total: 1,
+          [severity]: passed ? 0 : 1,
+          score: result.score,
+          maxScore: result.maxScore
+        }
+      }
+    }
+  }
+}
+
 // Register all checks
 const ALL_CHECKS = {
   security: [
@@ -51,7 +101,20 @@ const ALL_CHECKS = {
   stability: [
     huskyHooks,
     ciPipeline,
-    npmAudit
+    npmAudit,
+    adaptHealthCheck('tests', 'Test Infrastructure', 'high', checkTests),
+    adaptHealthCheck('eslint-security', 'ESLint Security Plugins', 'high', checkEslintSecurity),
+    adaptHealthCheck('typescript-strict', 'TypeScript Strictness', 'medium', checkTypescriptStrict),
+    adaptHealthCheck('coverage-thresholds', 'Test Coverage Thresholds', 'medium', checkCoverageThresholds),
+    adaptHealthCheck('knip', 'Dead Code Detection (Knip)', 'medium', checkKnip),
+    adaptHealthCheck('dependency-cruiser', 'Dependency Architecture', 'medium', checkDependencyCruiser),
+    adaptHealthCheck('dependency-automation', 'Dependency Updates (Dependabot/Renovate)', 'medium', checkDependencyAutomation),
+    adaptHealthCheck('prettier', 'Code Formatting (Prettier)', 'low', checkPrettier),
+    adaptHealthCheck('conventional-commits', 'Conventional Commits', 'low', checkConventionalCommits),
+    adaptHealthCheck('bundle-size', 'Bundle Size Monitoring', 'low', checkBundleSize),
+    adaptHealthCheck('sast', 'Static Application Security Testing', 'medium', checkSast),
+    adaptHealthCheck('license-audit', 'License Compliance', 'low', checkLicenseAudit),
+    adaptHealthCheck('security-layers', 'Security Layer Coverage', 'high', checkSecurityLayers)
   ],
   codeQuality: [
     apiResponseFormat,

package/package.json

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