@soulbatical/tetra-dev-toolkit 1.18.1 → 1.19.0

package/bin/tetra-check-peers.js

@@ -21,7 +21,28 @@ import { execSync } from 'child_process'
 
 // ─── Config ──────────────────────────────────────────────
 
-const PROJECTS_ROOT = join(process.env.HOME || '~', 'projecten')
+// Resolve paths dynamically:
+// 1. TETRA_PROJECTS_ROOT env var (explicit override)
+// 2. Detect from tetra repo: this script lives in tetra/packages/dev-toolkit/bin/
+//    so tetra root = 4 levels up, and projects root = 5 levels up (sibling dirs)
+// 3. Fallback: ~/projecten
+function resolveProjectsRoot() {
+  if (process.env.TETRA_PROJECTS_ROOT) return process.env.TETRA_PROJECTS_ROOT
+
+  // This file: <projects>/<tetra>/packages/dev-toolkit/bin/tetra-check-peers.js
+  const scriptDir = dirname(new URL(import.meta.url).pathname)
+  const tetraRoot = join(scriptDir, '..', '..', '..')  // → tetra/
+  const possibleProjectsRoot = join(tetraRoot, '..')     // → projects/
+
+  // Verify: does this directory contain a 'tetra' subdirectory?
+  if (existsSync(join(possibleProjectsRoot, 'tetra', 'packages'))) {
+    return possibleProjectsRoot
+  }
+
+  return join(process.env.HOME || '~', 'projecten')
+}
+
+const PROJECTS_ROOT = resolveProjectsRoot()
 const TETRA_ROOT = join(PROJECTS_ROOT, 'tetra', 'packages')
 
 // Tetra packages that have peerDependencies

package/bin/tetra-security-gate.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Security Gate — AI-powered pre-push security review
+ *
+ * Detects security-sensitive file changes in the current git diff,
+ * submits them to ralph-manager's security gate agent for review,
+ * and blocks the push if the agent denies the changes.
+ *
+ * Usage:
+ *   tetra-security-gate                     # Auto-detect ralph-manager URL
+ *   tetra-security-gate --url <url>         # Explicit ralph-manager URL
+ *   tetra-security-gate --timeout 120       # Custom timeout (seconds)
+ *   tetra-security-gate --dry-run           # Show what would be sent, don't block
+ *
+ * Exit codes:
+ *   0 = approved (or no security files changed)
+ *   1 = denied (security violation found)
+ *   0 = ralph-manager offline (graceful fallback, doesn't block)
+ */
+
+import { program } from 'commander'
+import { execSync } from 'child_process'
+import chalk from 'chalk'
+
+// Security-sensitive file patterns
+const SECURITY_PATTERNS = [
+  /supabase\/migrations\/.*\.sql$/i,
+  /\.rls\./i,
+  /rls[-_]?policy/i,
+  /auth[-_]?config/i,
+  /middleware\/auth/i,
+  /middleware\/security/i,
+  /security\.ts$/i,
+  /security\.js$/i,
+  /\.env$/,
+  /\.env\.\w+$/,
+  /doppler\.yaml$/,
+  /auth-config/i,
+  /permissions/i,
+  /checks\/security\//i,
+]
+
+function isSecurityFile(file) {
+  return SECURITY_PATTERNS.some(p => p.test(file))
+}
+
+function getChangedFiles() {
+  try {
+    // Files changed between HEAD and upstream (what's being pushed)
+    const upstream = execSync('git rev-parse --abbrev-ref @{upstream} 2>/dev/null', { encoding: 'utf8' }).trim()
+    if (upstream) {
+      return execSync(`git diff --name-only ${upstream}...HEAD`, { encoding: 'utf8' }).trim().split('\n').filter(Boolean)
+    }
+  } catch {
+    // No upstream — compare against origin/main or origin/master
+  }
+
+  for (const base of ['origin/main', 'origin/master']) {
+    try {
+      return execSync(`git diff --name-only ${base}...HEAD`, { encoding: 'utf8' }).trim().split('\n').filter(Boolean)
+    } catch { /* try next */ }
+  }
+
+  // Fallback: last commit
+  try {
+    return execSync('git diff --name-only HEAD~1', { encoding: 'utf8' }).trim().split('\n').filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+function getDiff(files) {
+  try {
+    const upstream = execSync('git rev-parse --abbrev-ref @{upstream} 2>/dev/null', { encoding: 'utf8' }).trim()
+    if (upstream) {
+      return execSync(`git diff ${upstream}...HEAD -- ${files.join(' ')}`, { encoding: 'utf8', maxBuffer: 1024 * 1024 })
+    }
+  } catch { /* fallback */ }
+
+  for (const base of ['origin/main', 'origin/master']) {
+    try {
+      return execSync(`git diff ${base}...HEAD -- ${files.join(' ')}`, { encoding: 'utf8', maxBuffer: 1024 * 1024 })
+    } catch { /* try next */ }
+  }
+
+  try {
+    return execSync(`git diff HEAD~1 -- ${files.join(' ')}`, { encoding: 'utf8', maxBuffer: 1024 * 1024 })
+  } catch {
+    return ''
+  }
+}
+
+function getProjectName() {
+  try {
+    const remoteUrl = execSync('git remote get-url origin 2>/dev/null', { encoding: 'utf8' }).trim()
+    const match = remoteUrl.match(/\/([^/]+?)(?:\.git)?$/)
+    if (match) return match[1]
+  } catch { /* fallback */ }
+
+  try {
+    return execSync('basename "$(git rev-parse --show-toplevel)"', { encoding: 'utf8' }).trim()
+  } catch {
+    return 'unknown'
+  }
+}
+
+function getRalphManagerUrl() {
+  // Check .ralph/ports.json first
+  try {
+    const portsJson = execSync('cat .ralph/ports.json 2>/dev/null', { encoding: 'utf8' })
+    const ports = JSON.parse(portsJson)
+    if (ports.api_url) return ports.api_url
+  } catch { /* fallback */ }
+
+  // Check RALPH_MANAGER_API env
+  if (process.env.RALPH_MANAGER_API) return process.env.RALPH_MANAGER_API
+
+  // Default
+  return 'http://localhost:3005'
+}
+
+async function pollForVerdict(baseUrl, gateId, timeoutSeconds) {
+  const deadline = Date.now() + timeoutSeconds * 1000
+  const pollInterval = 3000 // 3 seconds
+
+  while (Date.now() < deadline) {
+    try {
+      const resp = await fetch(`${baseUrl}/api/internal/security-gate/${gateId}`)
+      if (!resp.ok) {
+        console.error(chalk.yellow(`  Poll failed: HTTP ${resp.status}`))
+        break
+      }
+
+      const { data } = await resp.json()
+
+      if (data.status === 'approved') {
+        return { status: 'approved', reason: data.reason, findings: data.findings }
+      }
+      if (data.status === 'denied') {
+        return { status: 'denied', reason: data.reason, findings: data.findings }
+      }
+      if (data.status === 'error') {
+        return { status: 'error', reason: data.reason }
+      }
+
+      // Still pending — wait and retry
+      await new Promise(r => setTimeout(r, pollInterval))
+    } catch {
+      // Network error — ralph-manager might be restarting
+      await new Promise(r => setTimeout(r, pollInterval))
+    }
+  }
+
+  return { status: 'timeout', reason: `No verdict within ${timeoutSeconds}s` }
+}
+
+program
+  .name('tetra-security-gate')
+  .description('AI-powered pre-push security gate — reviews RLS/auth/security changes')
+  .version('1.0.0')
+  .option('--url <url>', 'Ralph Manager URL (default: auto-detect)')
+  .option('--timeout <seconds>', 'Max wait time for agent verdict', '180')
+  .option('--dry-run', 'Show what would be submitted, do not block')
+  .action(async (options) => {
+    try {
+      console.log(chalk.blue.bold('\n  Tetra Security Gate\n'))
+
+      // Step 1: Detect changed files
+      const allFiles = getChangedFiles()
+      const securityFiles = allFiles.filter(isSecurityFile)
+
+      if (securityFiles.length === 0) {
+        console.log(chalk.green('  No security-sensitive files changed — skipping gate.'))
+        console.log(chalk.gray(`  (checked ${allFiles.length} files)\n`))
+        process.exit(0)
+      }
+
+      console.log(chalk.yellow(`  ${securityFiles.length} security-sensitive file(s) detected:`))
+      for (const f of securityFiles) {
+        console.log(chalk.gray(`    - ${f}`))
+      }
+      console.log()
+
+      // Step 2: Get the diff
+      const diff = getDiff(securityFiles)
+      if (!diff.trim()) {
+        console.log(chalk.green('  No actual diff content — skipping gate.\n'))
+        process.exit(0)
+      }
+
+      const project = getProjectName()
+
+      if (options.dryRun) {
+        console.log(chalk.cyan('  [DRY RUN] Would submit to security gate:'))
+        console.log(chalk.gray(`    Project: ${project}`))
+        console.log(chalk.gray(`    Files: ${securityFiles.length}`))
+        console.log(chalk.gray(`    Diff size: ${diff.length} chars`))
+        console.log()
+        process.exit(0)
+      }
+
+      // Step 3: Submit to ralph-manager
+      const baseUrl = options.url || getRalphManagerUrl()
+      const timeout = parseInt(options.timeout, 10)
+
+      console.log(chalk.gray(`  Submitting to ${baseUrl}...`))
+
+      let gateId
+      try {
+        const resp = await fetch(`${baseUrl}/api/internal/security-gate`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ project, files_changed: securityFiles, diff }),
+          signal: AbortSignal.timeout(10_000),
+        })
+
+        if (!resp.ok) {
+          const body = await resp.text()
+          console.error(chalk.yellow(`  Ralph Manager returned ${resp.status}: ${body}`))
+          console.log(chalk.yellow('  Falling back to PASS (ralph-manager error).\n'))
+          process.exit(0)
+        }
+
+        const { data } = await resp.json()
+        gateId = data.id
+
+        // If already resolved (e.g. fallback auto-approve)
+        if (data.status === 'approved') {
+          console.log(chalk.green(`  ${chalk.bold('APPROVED')} (immediate): ${data.reason || 'OK'}\n`))
+          process.exit(0)
+        }
+        if (data.status === 'denied') {
+          console.error(chalk.red.bold(`\n  PUSH BLOCKED — Security Gate DENIED\n`))
+          console.error(chalk.red(`  Reason: ${data.reason}\n`))
+          process.exit(1)
+        }
+      } catch (err) {
+        // Ralph-manager offline — don't block the push
+        console.log(chalk.yellow(`  Cannot reach ralph-manager at ${baseUrl}`))
+        console.log(chalk.yellow('  Falling back to PASS (offline fallback).\n'))
+        process.exit(0)
+      }
+
+      // Step 4: Poll for verdict
+      console.log(chalk.gray(`  Agent reviewing... (timeout: ${timeout}s)`))
+      const result = await pollForVerdict(baseUrl, gateId, timeout)
+
+      if (result.status === 'approved') {
+        console.log(chalk.green.bold(`\n  APPROVED: ${result.reason || 'No issues found'}`))
+        if (result.findings?.length) {
+          for (const f of result.findings) {
+            console.log(chalk.yellow(`    ⚠ ${f}`))
+          }
+        }
+        console.log()
+        process.exit(0)
+      }
+
+      if (result.status === 'denied') {
+        console.error(chalk.red.bold(`\n  ════════════════════════════════════════════════════════════`))
+        console.error(chalk.red.bold(`  PUSH BLOCKED — Security Gate DENIED`))
+        console.error(chalk.red.bold(`  ════════════════════════════════════════════════════════════`))
+        console.error(chalk.red(`\n  Reason: ${result.reason}`))
+        if (result.findings?.length) {
+          console.error(chalk.red(`\n  Findings:`))
+          for (const f of result.findings) {
+            console.error(chalk.red(`    - ${f}`))
+          }
+        }
+        console.error(chalk.yellow(`\n  Fix the issues and try again.\n`))
+        process.exit(1)
+      }
+
+      if (result.status === 'timeout') {
+        console.log(chalk.yellow(`  Agent did not respond within ${timeout}s.`))
+        console.log(chalk.yellow('  Falling back to PASS (timeout fallback).\n'))
+        process.exit(0)
+      }
+
+      // Unknown status — don't block
+      console.log(chalk.yellow(`  Unexpected verdict status: ${result.status}`))
+      console.log(chalk.yellow('  Falling back to PASS.\n'))
+      process.exit(0)
+
+    } catch (err) {
+      console.error(chalk.red(`\n  ERROR: ${err.message}\n`))
+      // Never block on internal errors
+      process.exit(0)
+    }
+  })
+
+program.parse()

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

@@ -29,7 +29,7 @@ export const meta = {
   name: 'Config ↔ RLS Alignment',
   category: 'security',
   severity: 'critical',
-  description: 'Verifies that feature config accessLevel matches actual RLS policies on each table. The golden 1:1 check.'
+  description: 'Verifies that feature config accessLevel matches actual RLS policies on each table. Uses live DB when available, falls back to migration parsing.'
 }
 
 /**
@@ -390,17 +390,23 @@ function validateRlsClause(clause) {
   return null
 }
 
-export async function run(config, projectRoot) {
+export async function run(config, projectRoot, options = {}) {
   const results = {
     passed: true,
     skipped: false,
     findings: [],
     summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
-    details: { tablesChecked: 0, configsFound: 0, alignmentErrors: 0 }
+    details: { tablesChecked: 0, configsFound: 0, alignmentErrors: 0, source: 'migrations' }
   }
 
   const featureConfigs = parseFeatureConfigs(projectRoot)
-  const rlsData = parseMigrations(projectRoot)
+
+  // Use live DB state if available (passed from rls-live-audit via runner),
+  // otherwise fall back to migration file parsing
+  const rlsData = options.liveState || parseMigrations(projectRoot)
+  if (options.liveState) {
+    results.details.source = 'live-db'
+  }
 
   results.details.configsFound = featureConfigs.size
 

package/lib/checks/security/rls-live-audit.js

@@ -1,21 +1,35 @@
 /**
  * RLS Live DB Audit — queries pg_policies from the LIVE database
  *
- * The source of truth for RLS policy validation. Migration file parsing can miss:
+ * The PRIMARY source of truth for RLS policy validation.
+ * When this check runs successfully, migration-based RLS checks
+ * (rls-policy-audit, config-rls-alignment) are skipped for current state
+ * and only validate unapplied migrations (delta).
+ *
+ * Migration file parsing can miss:
  * - Policies applied directly via SQL (not in migration files)
  * - PL/pgSQL dynamic policies (EXECUTE format)
  * - Policies overridden by later manual changes
  *
  * Requires SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY in environment.
- * Connects via @supabase/supabase-js and calls a lightweight RPC.
  *
  * Setup (one-time per project):
  *   CREATE OR REPLACE FUNCTION tetra_rls_audit()
- *   RETURNS TABLE(tablename text, policyname text, using_clause text, with_check_clause text)
+ *   RETURNS TABLE(tablename text, policyname text, cmd text, using_clause text, with_check_clause text)
  *   LANGUAGE sql SECURITY DEFINER AS $$
- *     SELECT tablename::text, policyname::text, qual::text, with_check::text
+ *     SELECT tablename::text, policyname::text, cmd::text, qual::text, with_check::text
  *     FROM pg_policies WHERE schemaname = 'public';
  *   $$;
+ *
+ *   -- Optional: also return RLS enabled status per table
+ *   CREATE OR REPLACE FUNCTION tetra_rls_tables()
+ *   RETURNS TABLE(table_name text, rls_enabled boolean, rls_forced boolean)
+ *   LANGUAGE sql SECURITY DEFINER AS $$
+ *     SELECT c.relname::text, c.relrowsecurity, c.relforcerowsecurity
+ *     FROM pg_class c
+ *     JOIN pg_namespace n ON n.oid = c.relnamespace
+ *     WHERE n.nspname = 'public' AND c.relkind = 'r';
+ *   $$;
  */
 
 export const meta = {
@@ -70,13 +84,83 @@ function validateRlsClause(clause) {
   return null
 }
 
+/**
+ * Fetch data from a Supabase RPC endpoint.
+ * Returns null if the RPC doesn't exist or fails.
+ */
+async function callRpc(supabaseUrl, supabaseKey, rpcName) {
+  try {
+    const response = await fetch(`${supabaseUrl}/rest/v1/rpc/${rpcName}`, {
+      method: 'POST',
+      headers: {
+        'apikey': supabaseKey,
+        'Authorization': `Bearer ${supabaseKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: '{}',
+    })
+    if (!response.ok) return null
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build a structured live DB state from raw policy + table data.
+ * This is the same format that config-rls-alignment uses from migration parsing,
+ * so it can transparently use either source.
+ *
+ * Returns: Map<tableName, { rlsEnabled, policies: [{ name, operation, using, withCheck }] }>
+ */
+export function buildLiveState(policies, tableStatus) {
+  const tables = new Map()
+
+  // Initialize from table status (if available)
+  if (Array.isArray(tableStatus)) {
+    for (const t of tableStatus) {
+      if (!t?.table_name) continue
+      tables.set(t.table_name, {
+        rlsEnabled: t.rls_enabled || false,
+        policies: [],
+        rpcFunctions: new Map(),
+        source: 'live-db'
+      })
+    }
+  }
+
+  // Add policies
+  for (const policy of policies) {
+    if (!policy) continue
+    const { tablename, policyname, cmd, using_clause, with_check_clause } = policy
+    if (!tablename) continue
+
+    if (!tables.has(tablename)) {
+      // Table exists in policies but not in table status — it has RLS (otherwise no policies)
+      tables.set(tablename, { rlsEnabled: true, policies: [], rpcFunctions: new Map(), source: 'live-db' })
+    }
+
+    tables.get(tablename).policies.push({
+      name: policyname,
+      operation: (cmd || 'ALL').toUpperCase(),
+      using: using_clause || '',
+      withCheck: with_check_clause || '',
+      file: 'LIVE DB'
+    })
+  }
+
+  return tables
+}
+
 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: { policiesChecked: 0, tablesChecked: 0, violations: 0 }
+    details: { policiesChecked: 0, tablesChecked: 0, violations: 0 },
+    // Expose live data so runner can pass it to other checks
+    _liveData: null
   }
 
   const supabaseUrl = process.env.SUPABASE_URL
@@ -105,7 +189,7 @@ export async function run(config, projectRoot) {
       const status = response.status
       if (status === 404) {
         results.skipped = true
-        results.skipReason = 'RPC tetra_rls_audit() not found. Create it once:\n\n  CREATE OR REPLACE FUNCTION tetra_rls_audit()\n  RETURNS TABLE(tablename text, policyname text, using_clause text, with_check_clause text)\n  LANGUAGE sql SECURITY DEFINER AS $$\n    SELECT tablename::text, policyname::text, qual::text, with_check::text\n    FROM pg_policies WHERE schemaname = \'public\';\n  $$;'
+        results.skipReason = 'RPC tetra_rls_audit() not found. Create it once:\n\n  CREATE OR REPLACE FUNCTION tetra_rls_audit()\n  RETURNS TABLE(tablename text, policyname text, cmd text, using_clause text, with_check_clause text)\n  LANGUAGE sql SECURITY DEFINER AS $$\n    SELECT tablename::text, policyname::text, cmd::text, qual::text, with_check::text\n    FROM pg_policies WHERE schemaname = \'public\';\n  $$;'
       } else {
         results.skipped = true
         results.skipReason = `RPC tetra_rls_audit() failed with status ${status}`
@@ -126,6 +210,13 @@ export async function run(config, projectRoot) {
     return results
   }
 
+  // Optionally fetch table-level RLS status
+  const tableStatus = await callRpc(supabaseUrl, supabaseKey, 'tetra_rls_tables')
+
+  // Build structured live state (shared with config-rls-alignment)
+  const liveState = buildLiveState(policies, tableStatus)
+  results._liveData = { policies, tableStatus, liveState }
+
   const backendOnlyTables = config.supabase?.backendOnlyTables || []
   const tablesChecked = new Set()
 

package/lib/runner.js

@@ -93,12 +93,12 @@ const ALL_CHECKS = {
     frontendSupabaseQueries,
     tetraCoreCompliance,
     mixedDbUsage,
-    configRlsAlignment,
     rpcSecurityMode,
     systemdbWhitelist,
     gitignoreValidation,
     routeConfigAlignment,
-    rlsLiveAudit
+    rlsLiveAudit,          // Must run BEFORE config-rls-alignment (provides live DB data)
+    configRlsAlignment,    // Uses live DB data from rls-live-audit when available
   ],
   stability: [
     huskyHooks,
@@ -162,6 +162,10 @@ export async function runAllChecks(options = {}) {
     }
   }
 
+  // Track rls-live-audit result across suites so migration-based RLS checks can be skipped.
+  // rls-live-audit runs in 'security' suite, rls-policy-audit runs in 'supabase' suite.
+  let rlsLiveData = null
+
   for (const suite of suites) {
     if (!config.suites[suite]) {
       continue
@@ -174,11 +178,43 @@ export async function runAllChecks(options = {}) {
     }
 
     for (const check of checks) {
-      const checkResult = {
-        id: check.meta.id,
-        name: check.meta.name,
-        severity: check.meta.severity,
-        ...await check.run(config, projectRoot)
+      let checkResult
+
+      // rls-policy-audit is pure migration parsing — skip when live DB is available
+      if (rlsLiveData && check.meta.id === 'rls-policy-audit') {
+        checkResult = {
+          id: check.meta.id,
+          name: `${check.meta.name} (skipped — live DB is source of truth)`,
+          severity: check.meta.severity,
+          passed: true,
+          skipped: true,
+          skipReason: 'Skipped: rls-live-audit succeeded — live DB is the source of truth for current RLS state.',
+          findings: [],
+          summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+        }
+      }
+      // config-rls-alignment: always runs, but uses live DB data when available
+      else if (rlsLiveData && check.meta.id === 'config-rls-alignment') {
+        checkResult = {
+          id: check.meta.id,
+          name: `${check.meta.name} (live DB)`,
+          severity: check.meta.severity,
+          ...await check.run(config, projectRoot, { liveState: rlsLiveData.liveState })
+        }
+      }
+      else {
+        checkResult = {
+          id: check.meta.id,
+          name: check.meta.name,
+          severity: check.meta.severity,
+          ...await check.run(config, projectRoot)
+        }
+      }
+
+      // Capture live data from rls-live-audit for downstream checks
+      if (check.meta.id === 'rls-live-audit' && !checkResult.skipped && checkResult._liveData) {
+        rlsLiveData = checkResult._liveData
+        delete checkResult._liveData // Don't leak internal data into output
       }
 
       results.suites[suite].checks.push(checkResult)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "publishConfig": {
     "access": "restricted"
   },
@@ -32,7 +32,8 @@
     "tetra-check-rls": "./bin/tetra-check-rls.js",
     "tetra-migration-lint": "./bin/tetra-migration-lint.js",
     "tetra-db-push": "./bin/tetra-db-push.js",
-    "tetra-check-peers": "./bin/tetra-check-peers.js"
+    "tetra-check-peers": "./bin/tetra-check-peers.js",
+    "tetra-security-gate": "./bin/tetra-security-gate.js"
   },
   "files": [
     "bin/",