@soulbatical/tetra-dev-toolkit 1.12.1 → 1.13.1

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

@@ -0,0 +1,421 @@
+/**
+ * Config ↔ RLS Alignment Check — HARD BLOCK
+ *
+ * Verifies that feature config files and RLS policies are in 1:1 alignment:
+ *
+ * For each feature config:
+ * 1. tableName must have RLS enabled
+ * 2. accessLevel must match RLS policy patterns:
+ *    - 'admin'   → USING(organization_id = auth_org_id()) — org-scoped
+ *    - 'user'    → USING(user_id = auth.uid()) — user-scoped
+ *    - 'creator' → USING(user_id = auth.uid() OR visibility...) — sandboxed
+ *    - 'public'  → USING(true) or USING(is_published = true) — open read
+ *    - 'system'  → No frontend access, backend-only (must be in backendOnlyTables)
+ * 3. RPC functions must be SECURITY INVOKER (not DEFINER) unless whitelisted
+ * 4. Every config table must have SELECT, INSERT, UPDATE, DELETE policies
+ * 5. No USING(true) on non-public tables
+ *
+ * This is the "golden check" — if config says admin, RLS MUST enforce org isolation.
+ *
+ * Reference: stella_howto_get slug="tetra-architecture-guide"
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { globSync } from 'glob'
+
+export const meta = {
+  id: 'config-rls-alignment',
+  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.'
+}
+
+/**
+ * Parse all feature configs to extract table → accessLevel mapping
+ */
+function parseFeatureConfigs(projectRoot) {
+  const configs = new Map() // tableName → { accessLevel, configFile, organizationIdField, rpcFunctions }
+
+  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 }
+
+    // Extract tableName
+    const tableMatch = content.match(/tableName:\s*['"]([^'"]+)['"]/)
+    if (!tableMatch) continue
+
+    const tableName = tableMatch[1]
+
+    // Extract accessLevel (default: 'admin')
+    const accessMatch = content.match(/accessLevel:\s*['"]([^'"]+)['"]/)
+    const accessLevel = accessMatch ? accessMatch[1] : 'admin'
+
+    // Extract organizationIdField
+    const orgFieldMatch = content.match(/organizationIdField:\s*['"]([^'"]+)['"]/)
+    const organizationIdField = orgFieldMatch ? orgFieldMatch[1] : 'organization_id'
+
+    // Extract RPC function names
+    const rpcFunctions = []
+    const countsRpc = content.match(/countsRpcName:\s*['"]([^'"]+)['"]/)
+    const resultsRpc = content.match(/resultsRpcName:\s*['"]([^'"]+)['"]/)
+    const detailRpc = content.match(/detailRpcName:\s*['"]([^'"]+)['"]/)
+    if (countsRpc) rpcFunctions.push(countsRpc[1])
+    if (resultsRpc) rpcFunctions.push(resultsRpc[1])
+    if (detailRpc) rpcFunctions.push(detailRpc[1])
+
+    // Extract creatorVisibility
+    const creatorVis = content.match(/creatorVisibility:\s*\{/)
+    const hasCreatorVisibility = !!creatorVis
+
+    configs.set(tableName, {
+      accessLevel,
+      configFile: file.replace(projectRoot + '/', ''),
+      organizationIdField,
+      rpcFunctions,
+      hasCreatorVisibility
+    })
+  }
+
+  return configs
+}
+
+/**
+ * Parse all SQL migrations to extract RLS info per table
+ */
+function parseMigrations(projectRoot) {
+  const tables = new Map() // tableName → { rlsEnabled, policies: [], rpcFunctions: Map }
+
+  const migrationDirs = [
+    join(projectRoot, 'supabase/migrations'),
+    join(projectRoot, 'backend/supabase/migrations')
+  ]
+
+  for (const dir of migrationDirs) {
+    if (!existsSync(dir)) continue
+
+    let sqlFiles
+    try {
+      sqlFiles = findFiles(projectRoot, dir.replace(projectRoot + '/', '') + '/*.sql')
+    } catch { continue }
+
+    for (const file of sqlFiles) {
+      let content
+      try { content = readFileSync(file, 'utf-8') } catch { continue }
+
+      const relFile = file.replace(projectRoot + '/', '')
+
+      // Find RLS enables
+      const rlsMatches = content.matchAll(/ALTER\s+TABLE\s+(?:public\.)?(\w+)\s+ENABLE\s+ROW\s+LEVEL\s+SECURITY/gi)
+      for (const m of rlsMatches) {
+        const table = m[1]
+        if (!tables.has(table)) tables.set(table, { rlsEnabled: true, policies: [], rpcFunctions: new Map() })
+        else tables.get(table).rlsEnabled = true
+      }
+
+      // Find policies
+      const policyRegex = /CREATE\s+POLICY\s+"?([^"]+)"?\s+ON\s+(?:public\.)?(\w+)\s*([\s\S]*?)(?=CREATE\s+POLICY|CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION|ALTER\s+TABLE|CREATE\s+(?:UNIQUE\s+)?INDEX|GRANT|$)/gi
+      for (const m of content.matchAll(policyRegex)) {
+        const policyName = m[1]
+        const table = m[2]
+        const body = m[3] || ''
+
+        if (!tables.has(table)) tables.set(table, { rlsEnabled: false, policies: [], rpcFunctions: new Map() })
+
+        // Determine operation
+        let operation = 'ALL'
+        const forMatch = body.match(/FOR\s+(SELECT|INSERT|UPDATE|DELETE|ALL)/i)
+        if (forMatch) operation = forMatch[1].toUpperCase()
+
+        // Extract USING clause
+        const usingMatch = body.match(/USING\s*\(([\s\S]*?)(?:\)\s*(?:WITH|;|$)|\)$)/i)
+        const using = usingMatch ? usingMatch[1].trim() : ''
+
+        // Extract WITH CHECK
+        const withCheckMatch = body.match(/WITH\s+CHECK\s*\(([\s\S]*?)(?:\)\s*;|\)$)/i)
+        const withCheck = withCheckMatch ? withCheckMatch[1].trim() : ''
+
+        tables.get(table).policies.push({
+          name: policyName,
+          operation,
+          using,
+          withCheck,
+          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)) {
+        const funcName = m[1]
+        const funcBody = content.substring(m.index, m.index + 2000)
+
+        const isDefiner = /SECURITY\s+DEFINER/i.test(funcBody)
+        const isInvoker = /SECURITY\s+INVOKER/i.test(funcBody)
+
+        // Find which tables this function touches
+        for (const [table] of tables) {
+          if (funcBody.includes(table)) {
+            tables.get(table).rpcFunctions.set(funcName, {
+              securityMode: isDefiner ? 'DEFINER' : isInvoker ? 'INVOKER' : 'DEFAULT',
+              file: relFile
+            })
+          }
+        }
+      }
+    }
+  }
+
+  return tables
+}
+
+function findFiles(projectRoot, pattern) {
+  try {
+    return globSync(pattern, { cwd: projectRoot, absolute: true, ignore: ['**/node_modules/**'] })
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 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)
+}
+
+/**
+ * Check if a USING clause enforces user isolation
+ */
+function isUserIsolation(using) {
+  return /auth\.uid\(\)/i.test(using) &&
+         /user_id|created_by|owner_id/i.test(using)
+}
+
+/**
+ * Check if a USING clause is wide open
+ */
+function isWideOpen(using) {
+  return using.trim() === 'true' || using.trim() === '(true)'
+}
+
+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: { tablesChecked: 0, configsFound: 0, alignmentErrors: 0 }
+  }
+
+  const featureConfigs = parseFeatureConfigs(projectRoot)
+  const rlsData = parseMigrations(projectRoot)
+
+  results.details.configsFound = featureConfigs.size
+
+  if (featureConfigs.size === 0) {
+    results.skipped = true
+    results.skipReason = 'No feature config files found'
+    return results
+  }
+
+  // For each feature config, verify RLS alignment
+  for (const [tableName, cfg] of featureConfigs) {
+    results.details.tablesChecked++
+    const tableRls = rlsData.get(tableName)
+
+    // CHECK 1: Table must have RLS enabled
+    if (!tableRls || !tableRls.rlsEnabled) {
+      results.passed = false
+      results.findings.push({
+        file: cfg.configFile,
+        line: 1,
+        type: 'no-rls-on-config-table',
+        severity: 'critical',
+        message: `Config declares table "${tableName}" with accessLevel "${cfg.accessLevel}" but table has NO RLS enabled. Any authenticated user can access ALL data.`,
+        fix: `Add to migrations: ALTER TABLE ${tableName} ENABLE ROW LEVEL SECURITY; then add appropriate policies.`
+      })
+      results.summary.critical++
+      results.summary.total++
+      continue
+    }
+
+    const policies = tableRls.policies
+    const selectPolicies = policies.filter(p => p.operation === 'SELECT' || p.operation === 'ALL')
+    const insertPolicies = policies.filter(p => p.operation === 'INSERT' || p.operation === 'ALL')
+    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')
+    if (insertPolicies.length === 0) missingOps.push('INSERT')
+    if (updatePolicies.length === 0) missingOps.push('UPDATE')
+    if (deletePolicies.length === 0) missingOps.push('DELETE')
+
+    if (missingOps.length > 0 && cfg.accessLevel !== 'system') {
+      results.passed = false
+      results.findings.push({
+        file: cfg.configFile,
+        line: 1,
+        type: 'missing-operation-policies',
+        severity: 'high',
+        message: `Table "${tableName}" is missing RLS policies for: ${missingOps.join(', ')}. RLS is enabled but incomplete — these operations are blocked for everyone.`,
+        fix: `Add policies for ${missingOps.join(', ')} operations on table ${tableName}.`
+      })
+      results.summary.high++
+      results.summary.total++
+    }
+
+    // CHECK 3: accessLevel ↔ RLS policy alignment
+    if (cfg.accessLevel === 'admin') {
+      // Admin tables MUST have org_isolation on SELECT
+      const hasOrgIsolation = selectPolicies.some(p => isOrgIsolation(p.using))
+      if (!hasOrgIsolation && selectPolicies.length > 0) {
+        // Check if any policy enforces org scoping
+        const hasAnyOrgScope = selectPolicies.some(p =>
+          p.using.includes('organization_id') || p.using.includes('auth_org_id')
+        )
+        if (!hasAnyOrgScope) {
+          results.passed = false
+          results.findings.push({
+            file: cfg.configFile,
+            line: 1,
+            type: 'admin-without-org-isolation',
+            severity: 'critical',
+            message: `Config says accessLevel "admin" for table "${tableName}" but SELECT policy does NOT enforce organization isolation. Users from org A can see org B's data.`,
+            fix: `RLS SELECT policy must include: USING (${cfg.organizationIdField} = auth_org_id())`
+          })
+          results.summary.critical++
+          results.summary.total++
+        }
+      }
+
+      // Admin tables must NOT have USING(true) on SELECT
+      const hasWideOpen = selectPolicies.some(p => isWideOpen(p.using))
+      if (hasWideOpen) {
+        results.passed = false
+        results.findings.push({
+          file: cfg.configFile,
+          line: 1,
+          type: 'admin-with-using-true',
+          severity: 'critical',
+          message: `Config says accessLevel "admin" for table "${tableName}" but has a SELECT policy with USING(true). ALL data is visible to ALL authenticated users.`,
+          fix: `Replace USING(true) with USING (${cfg.organizationIdField} = auth_org_id())`
+        })
+        results.summary.critical++
+        results.summary.total++
+      }
+    }
+
+    if (cfg.accessLevel === 'user') {
+      // User tables MUST have user isolation
+      const hasUserIsolation = selectPolicies.some(p => isUserIsolation(p.using))
+      if (!hasUserIsolation && selectPolicies.length > 0) {
+        results.passed = false
+        results.findings.push({
+          file: cfg.configFile,
+          line: 1,
+          type: 'user-without-user-isolation',
+          severity: 'critical',
+          message: `Config says accessLevel "user" for table "${tableName}" but SELECT policy does NOT enforce user isolation. Users can see other users' data.`,
+          fix: `RLS SELECT policy must include: USING (user_id = auth.uid())`
+        })
+        results.summary.critical++
+        results.summary.total++
+      }
+    }
+
+    if (cfg.accessLevel === 'creator') {
+      // Creator tables MUST have both user isolation AND visibility rules
+      if (!cfg.hasCreatorVisibility) {
+        results.findings.push({
+          file: cfg.configFile,
+          line: 1,
+          type: 'creator-without-visibility-config',
+          severity: 'medium',
+          message: `Config says accessLevel "creator" for table "${tableName}" but no creatorVisibility config defined. Creators may see all org data instead of only their own + shared.`,
+          fix: `Add creatorVisibility: { column: 'visibility_level', publicValues: ['shared', 'public'] } to the config.`
+        })
+        results.summary.medium++
+        results.summary.total++
+      }
+    }
+
+    // CHECK 4: RPC functions must be SECURITY INVOKER
+    for (const rpcName of cfg.rpcFunctions) {
+      const rpcInfo = tableRls.rpcFunctions.get(rpcName)
+      if (rpcInfo && rpcInfo.securityMode === 'DEFINER') {
+        results.passed = false
+        results.findings.push({
+          file: rpcInfo.file,
+          line: 1,
+          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.`
+        })
+        results.summary.critical++
+        results.summary.total++
+      }
+    }
+
+    // CHECK 5: Write policies (INSERT/UPDATE) must have WITH CHECK for org isolation
+    if (cfg.accessLevel === 'admin' || cfg.accessLevel === 'user') {
+      const writePoilciesWithoutCheck = [
+        ...insertPolicies.filter(p => !p.withCheck && p.operation === 'INSERT'),
+        ...updatePolicies.filter(p => !p.withCheck && p.operation === 'UPDATE')
+      ]
+
+      for (const p of writePoilciesWithoutCheck) {
+        // INSERT policies without WITH CHECK allow inserting into any org
+        results.findings.push({
+          file: p.file,
+          line: 1,
+          type: 'write-without-check',
+          severity: 'high',
+          message: `${p.operation} policy "${p.name}" on table "${tableName}" has no WITH CHECK clause. Users can write data outside their ${cfg.accessLevel === 'admin' ? 'organization' : 'own records'}.`,
+          fix: `Add WITH CHECK (${cfg.organizationIdField} = auth_org_id()) to the ${p.operation} policy.`
+        })
+        results.summary.high++
+        results.summary.total++
+      }
+    }
+  }
+
+  // CHECK 6: Tables with RLS that are NOT in any config (orphan tables)
+  // These might be missing config files or intentionally backend-only
+  const backendOnlyTables = (config.supabase?.backendOnlyTables || [])
+  const configTables = new Set(featureConfigs.keys())
+
+  for (const [tableName, info] of rlsData) {
+    if (configTables.has(tableName)) continue
+    if (backendOnlyTables.includes(tableName)) continue
+    if (tableName.startsWith('_') || tableName.startsWith('pg_')) continue
+    // Skip common system tables
+    if (['organization_members', 'org_members', 'auth_tokens'].includes(tableName)) continue
+
+    if (info.policies.length === 0 && info.rlsEnabled) {
+      results.findings.push({
+        file: 'supabase/migrations',
+        line: 1,
+        type: 'orphan-table-no-policies',
+        severity: 'medium',
+        message: `Table "${tableName}" has RLS enabled but no policies AND no feature config. It's either dead or missing its config file.`,
+        fix: `Either add a feature config, add to backendOnlyTables in .tetra-quality.json, or add RLS policies.`
+      })
+      results.summary.medium++
+      results.summary.total++
+    }
+  }
+
+  results.details.alignmentErrors = results.findings.filter(f => f.severity === 'critical').length
+  return results
+}

package/lib/runner.js

@@ -14,6 +14,7 @@ import * as directSupabaseClient from './checks/security/direct-supabase-client.
 import * as frontendSupabaseQueries from './checks/security/frontend-supabase-queries.js'
 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 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'
@@ -39,6 +40,7 @@ const ALL_CHECKS = {
     frontendSupabaseQueries,
     tetraCoreCompliance,
     mixedDbUsage,
+    configRlsAlignment,
     systemdbWhitelist,
     gitignoreValidation
   ],

package/package.json

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