@soulbatical/tetra-dev-toolkit 1.18.1 → 1.20.0

package/lib/checks/health/types.js

@@ -5,7 +5,7 @@
  */
 
 /**
- * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'rpc-param-mismatch'|'typescript-strict'|'prettier'|'coverage-thresholds'|'eslint-security'|'dependency-cruiser'|'conventional-commits'|'knip'|'dependency-automation'|'license-audit'|'sast'|'bundle-size'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'|'file-organization'|'security-layers'} HealthCheckType
+ * @typedef {'plugins'|'mcps'|'git'|'tests'|'secrets'|'quality-toolkit'|'naming-conventions'|'rls-audit'|'rpc-param-mismatch'|'typescript-strict'|'prettier'|'coverage-thresholds'|'eslint-security'|'dependency-cruiser'|'conventional-commits'|'knip'|'dependency-automation'|'license-audit'|'sast'|'bundle-size'|'gitignore'|'repo-visibility'|'vincifox-widget'|'stella-integration'|'claude-md'|'doppler-compliance'|'infrastructure-yml'|'file-organization'|'security-layers'|'smoke-readiness'} HealthCheckType
  *
  * @typedef {'ok'|'warning'|'error'} HealthStatus
  *

package/lib/checks/hygiene/stella-compliance.js

@@ -29,7 +29,7 @@ const DUPLICATE_PATTERNS = [
   {
     pattern: /const QUESTIONS_DIR\s*=\s*join\(tmpdir\(\)/,
     label: 'Local QUESTIONS_DIR (telegram question store)',
-    allowedIn: ['stella/src/telegram.ts']
+    allowedIn: ['stella/src/telegram.ts', 'backend/src/features/telegram/']
   },
   {
     pattern: /function detectWorkspaceRef\(\)/,
@@ -49,7 +49,7 @@ const DUPLICATE_PATTERNS = [
   {
     pattern: /function splitMessage\(text:\s*string/,
     label: 'Local splitMessage helper (for telegram)',
-    allowedIn: ['stella/src/telegram.ts', 'tools/helpers.ts']
+    allowedIn: ['stella/src/telegram.ts', 'tools/helpers.ts', 'backend/src/features/telegram/']
   },
   {
     pattern: /function playMacAlert\(\)/,

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/direct-supabase-client.js

@@ -63,6 +63,15 @@ const ALLOWED_FILES = [
   // Domain middleware (sets RLS session vars — needs direct client)
   /middleware\/domainOrganizationMiddleware\.ts$/,
 
+  // Auth routes that only use Supabase Auth API (not DB queries)
+  /routes\/auth\.ts$/,
+
+  // WebSocket auth verification (only uses auth.getUser for token validation)
+  /services\/terminalWebSocket\.ts$/,
+
+  // Frontend Supabase client (Vite apps — client-side auth only, no Tetra backend)
+  /frontend\/src\/lib\/supabase\.ts$/,
+
   // Scripts (not production code)
   /scripts\//,
 ]

package/lib/checks/security/hardcoded-secrets.js

@@ -34,10 +34,13 @@ export async function run(config, projectRoot) {
     summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
   }
 
-  // Get all source files
+  // Get all source files (always exclude node_modules, even nested ones)
   const files = await glob('**/*.{ts,tsx,js,jsx,json}', {
     cwd: projectRoot,
-    ignore: config.ignore
+    ignore: [
+      '**/node_modules/**',
+      ...config.ignore
+    ]
   })
 
   for (const file of files) {

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

@@ -47,6 +47,7 @@ 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'
+import { check as checkSmokeReadiness } from './checks/health/smoke-readiness.js'
 
 /**
  * Adapt a health check (score-based) to the runner format (meta + run).
@@ -93,12 +94,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,
@@ -116,7 +117,8 @@ const ALL_CHECKS = {
     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)
+    adaptHealthCheck('security-layers', 'Security Layer Coverage', 'high', checkSecurityLayers),
+    adaptHealthCheck('smoke-readiness', 'Smoke Test Readiness', 'medium', checkSmokeReadiness)
   ],
   codeQuality: [
     apiResponseFormat,
@@ -162,6 +164,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 +180,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.20.0",
   "publishConfig": {
     "access": "restricted"
   },
@@ -32,7 +32,9 @@
     "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",
+    "tetra-smoke": "./bin/tetra-smoke.js"
   },
   "files": [
     "bin/",