@soulbatical/tetra-dev-toolkit 1.13.1 → 1.15.0

package/bin/tetra-db-push.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra DB Push — Safe wrapper around `supabase db push`
+ *
+ * Runs tetra-migration-lint FIRST. If any CRITICAL or HIGH issues
+ * are found, the push is BLOCKED. No exceptions.
+ *
+ * Usage:
+ *   tetra-db-push                    # Lint + push
+ *   tetra-db-push --force            # Skip lint (DANGEROUS — requires explicit flag)
+ *   tetra-db-push --dry-run          # Lint only, don't push
+ *   tetra-db-push -- --linked        # Pass flags to supabase db push
+ *
+ * Replace in your workflow:
+ *   BEFORE: supabase db push
+ *   AFTER:  tetra-db-push
+ *
+ * Or add alias: alias supabase-push='tetra-db-push'
+ */
+
+import { execSync, spawnSync } from 'child_process'
+import chalk from 'chalk'
+import { resolve } from 'path'
+
+const args = process.argv.slice(2)
+const force = args.includes('--force')
+const dryRun = args.includes('--dry-run')
+const supabaseArgs = args.filter(a => a !== '--force' && a !== '--dry-run')
+
+const projectRoot = resolve(process.cwd())
+
+// ─── Step 1: Migration Lint ────────────────────────────────────────
+console.log('')
+console.log(chalk.bold('  🔒 Tetra DB Push — Security Gate'))
+console.log('')
+
+if (force) {
+  console.log(chalk.red.bold('  ⚠️  --force flag: SKIPPING security lint'))
+  console.log(chalk.red('  You are pushing migrations WITHOUT security validation.'))
+  console.log('')
+} else {
+  console.log(chalk.gray('  Step 1: Running migration lint...'))
+  console.log('')
+
+  const lintResult = spawnSync('node', [
+    resolve(import.meta.dirname, 'tetra-migration-lint.js'),
+    '--project', projectRoot
+  ], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    env: process.env
+  })
+
+  if (lintResult.status !== 0) {
+    console.log('')
+    console.log(chalk.red.bold('  ❌ Migration lint FAILED — push blocked'))
+    console.log(chalk.gray('  Fix the issues above, then run tetra-db-push again.'))
+    console.log('')
+    process.exit(1)
+  }
+
+  console.log(chalk.green('  ✅ Migration lint passed'))
+  console.log('')
+}
+
+// ─── Step 2: Supabase DB Push ──────────────────────────────────────
+if (dryRun) {
+  console.log(chalk.gray('  --dry-run: skipping actual push'))
+  console.log('')
+  process.exit(0)
+}
+
+console.log(chalk.gray('  Step 2: Running supabase db push...'))
+console.log('')
+
+const pushResult = spawnSync('npx', ['supabase', 'db', 'push', ...supabaseArgs], {
+  cwd: projectRoot,
+  stdio: 'inherit',
+  env: process.env
+})
+
+if (pushResult.status !== 0) {
+  console.log('')
+  console.log(chalk.red('  ❌ supabase db push failed'))
+  process.exit(pushResult.status || 1)
+}
+
+console.log('')
+console.log(chalk.green.bold('  ✅ Migrations pushed successfully (security validated)'))
+console.log('')

package/bin/tetra-migration-lint.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Migration Lint — HARD BLOCK before supabase db push
+ *
+ * Scans SQL migration files OFFLINE (no Supabase connection needed) for:
+ * 1. SECURITY DEFINER on data RPCs (must be INVOKER)
+ * 2. Tables without ENABLE ROW LEVEL SECURITY
+ * 3. DROP POLICY / DROP TABLE without explicit confirmation
+ * 4. GRANT to public/anon on sensitive tables
+ * 5. Missing WITH CHECK on INSERT/UPDATE policies
+ *
+ * Usage:
+ *   tetra-migration-lint                     # Lint all migrations
+ *   tetra-migration-lint --staged            # Only git-staged .sql files (for pre-commit)
+ *   tetra-migration-lint --file path.sql     # Lint a specific file
+ *   tetra-migration-lint --fix-suggestions   # Show fix SQL for each violation
+ *   tetra-migration-lint --json              # JSON output for CI
+ *
+ * Exit codes:
+ *   0 = all clean
+ *   1 = violations found (CRITICAL or HIGH)
+ *   2 = warnings only (MEDIUM/LOW) — does not block
+ *
+ * Hook usage (.husky/pre-commit):
+ *   tetra-migration-lint --staged || exit 1
+ *
+ * Wrapper usage (replace `supabase db push`):
+ *   tetra-migration-lint && supabase db push
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join, resolve, basename, relative } from 'path'
+import { globSync } from 'glob'
+import { execSync } from 'child_process'
+import chalk from 'chalk'
+import { program } from 'commander'
+
+// ─── Dangerous patterns ────────────────────────────────────────────
+const RULES = [
+  {
+    id: 'DEFINER_DATA_RPC',
+    severity: 'critical',
+    pattern: /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+(?:public\.)?(\w+)\s*\([^)]*\)[\s\S]*?SECURITY\s+DEFINER/gi,
+    test: (match, fullContent) => {
+      const funcName = match[1]
+      // Auth helpers are OK as DEFINER
+      const authWhitelist = [
+        'auth_org_id', 'auth_uid', 'auth_role', 'auth_user_role',
+        'auth_admin_organizations', 'auth_user_id', 'requesting_user_id',
+        'get_auth_org_id', 'get_current_user_id'
+      ]
+      return !authWhitelist.includes(funcName)
+    },
+    message: (match) => `SECURITY DEFINER on RPC "${match[1]}" — bypasses RLS completely. Use SECURITY INVOKER instead.`,
+    fix: (match) => `ALTER FUNCTION ${match[1]} SECURITY INVOKER;`
+  },
+  {
+    id: 'CREATE_TABLE_NO_RLS',
+    severity: 'critical',
+    // Match CREATE TABLE that is NOT followed by ENABLE ROW LEVEL SECURITY in the same migration
+    test: (match, fullContent) => {
+      const tableName = match[1]
+      const rlsPattern = new RegExp(`ALTER\\s+TABLE\\s+(?:public\\.)?${tableName}\\s+ENABLE\\s+ROW\\s+LEVEL\\s+SECURITY`, 'i')
+      return !rlsPattern.test(fullContent)
+    },
+    pattern: /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:public\.)?(\w+)\s*\(/gi,
+    message: (match) => `CREATE TABLE "${match[1]}" without ENABLE ROW LEVEL SECURITY in same migration.`,
+    fix: (match) => `ALTER TABLE ${match[1]} ENABLE ROW LEVEL SECURITY;`
+  },
+  {
+    id: 'DROP_POLICY',
+    severity: 'high',
+    pattern: /DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?["']?(\w+)["']?\s+ON\s+(?:public\.)?(\w+)/gi,
+    message: (match) => `DROP POLICY "${match[1]}" on "${match[2]}" — removes security. Ensure a replacement policy exists in the same migration.`,
+    test: (match, fullContent) => {
+      // OK if there's a CREATE POLICY in the same migration for the same table
+      const createPattern = new RegExp(`CREATE\\s+POLICY.*ON\\s+(?:public\\.)?${match[2]}`, 'i')
+      return !createPattern.test(fullContent)
+    },
+    fix: (match) => `-- Add replacement policy:\n-- CREATE POLICY "${match[1]}" ON ${match[2]} FOR ALL USING (organization_id = auth_org_id());`
+  },
+  {
+    id: 'GRANT_PUBLIC_ANON',
+    severity: 'critical',
+    pattern: /GRANT\s+(?:ALL|INSERT|UPDATE|DELETE)\s+ON\s+(?:TABLE\s+)?(?:public\.)?(\w+)\s+TO\s+(public|anon)/gi,
+    message: (match) => `GRANT ${match[0].match(/GRANT\s+(\w+)/)[1]} to ${match[2]} on "${match[1]}" — allows unauthenticated access.`,
+    fix: (match) => `-- Remove this GRANT or restrict to authenticated:\n-- GRANT SELECT ON ${match[1]} TO authenticated;`
+  },
+  {
+    id: 'DISABLE_RLS',
+    severity: 'critical',
+    pattern: /ALTER\s+TABLE\s+(?:public\.)?(\w+)\s+DISABLE\s+ROW\s+LEVEL\s+SECURITY/gi,
+    message: (match) => `DISABLE ROW LEVEL SECURITY on "${match[1]}" — removes ALL protection.`,
+    fix: (match) => `-- Do NOT disable RLS. If you need service-level access, use systemDB() in backend code.`
+  },
+  {
+    id: 'POLICY_NO_WITH_CHECK',
+    severity: 'medium',
+    pattern: /CREATE\s+POLICY\s+["']?(\w+)["']?\s+ON\s+(?:public\.)?(\w+)\s+FOR\s+(INSERT|UPDATE)\s+TO\s+\w+\s+USING\s*\([^)]+\)(?!\s*WITH\s+CHECK)/gi,
+    message: (match) => `Policy "${match[1]}" on "${match[2]}" for ${match[3]} has USING but no WITH CHECK — users could write data they can't read.`,
+    fix: (match) => `-- Add WITH CHECK clause matching the USING clause`
+  },
+  {
+    id: 'USING_TRUE_WRITE',
+    severity: 'critical',
+    pattern: /CREATE\s+POLICY\s+["']?(\w+)["']?\s+ON\s+(?:public\.)?(\w+)\s+FOR\s+(INSERT|UPDATE|DELETE|ALL)\s+(?:TO\s+\w+\s+)?USING\s*\(\s*true\s*\)/gi,
+    message: (match) => `Policy "${match[1]}" on "${match[2]}" allows ${match[3]} with USING(true) — anyone can write.`,
+    fix: (match) => `-- Replace USING(true) with proper org/user scoping:\n-- USING (organization_id = auth_org_id())`
+  },
+  {
+    id: 'RAW_SERVICE_KEY',
+    severity: 'critical',
+    pattern: /eyJ[A-Za-z0-9_-]{20,}\.eyJ[A-Za-z0-9_-]{20,}/g,
+    message: () => `Hardcoded JWT/service key found in migration file.`,
+    fix: () => `-- NEVER put keys in migrations. Use environment variables or Vault.`
+  }
+]
+
+// ─── Load whitelist from .tetra-quality.json ───────────────────────
+function loadWhitelist(projectRoot) {
+  const configPath = join(projectRoot, '.tetra-quality.json')
+  if (!existsSync(configPath)) return { securityDefinerWhitelist: [], tables: { noRls: [] } }
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+    return {
+      securityDefinerWhitelist: config?.supabase?.securityDefinerWhitelist || [],
+      tables: { noRls: config?.supabase?.backendOnlyTables || [] }
+    }
+  } catch { return { securityDefinerWhitelist: [], tables: { noRls: [] } } }
+}
+
+// ─── Find migration files ──────────────────────────────────────────
+function findMigrations(projectRoot, options) {
+  if (options.file) {
+    const filePath = resolve(options.file)
+    return existsSync(filePath) ? [filePath] : []
+  }
+
+  if (options.staged) {
+    try {
+      const staged = execSync('git diff --cached --name-only --diff-filter=ACM', {
+        cwd: projectRoot, encoding: 'utf-8'
+      })
+      return staged.split('\n')
+        .filter(f => f.endsWith('.sql'))
+        .map(f => join(projectRoot, f))
+        .filter(f => existsSync(f))
+    } catch { return [] }
+  }
+
+  // All migrations
+  const patterns = [
+    'supabase/migrations/**/*.sql',
+    'backend/supabase/migrations/**/*.sql',
+    'migrations/**/*.sql'
+  ]
+  const files = []
+  for (const pattern of patterns) {
+    files.push(...globSync(pattern, { cwd: projectRoot, absolute: true }))
+  }
+  return [...new Set(files)]
+}
+
+// ─── Lint a single file ────────────────────────────────────────────
+function lintFile(filePath, projectRoot, whitelist) {
+  const content = readFileSync(filePath, 'utf-8')
+  const relPath = relative(projectRoot, filePath)
+  const findings = []
+
+  for (const rule of RULES) {
+    // Reset regex lastIndex
+    rule.pattern.lastIndex = 0
+    let match
+    while ((match = rule.pattern.exec(content)) !== null) {
+      // Check whitelist for DEFINER rules
+      if (rule.id === 'DEFINER_DATA_RPC' && whitelist.securityDefinerWhitelist.includes(match[1])) {
+        continue
+      }
+      // Check backendOnlyTables for CREATE_TABLE_NO_RLS
+      if (rule.id === 'CREATE_TABLE_NO_RLS' && whitelist.tables.noRls.includes(match[1])) {
+        continue
+      }
+
+      // Run custom test if exists
+      if (rule.test && !rule.test(match, content)) {
+        continue
+      }
+
+      // Find line number
+      const lineNum = content.substring(0, match.index).split('\n').length
+
+      findings.push({
+        file: relPath,
+        line: lineNum,
+        rule: rule.id,
+        severity: rule.severity,
+        message: rule.message(match),
+        fix: rule.fix ? rule.fix(match) : null
+      })
+    }
+  }
+
+  return findings
+}
+
+// ─── Main ──────────────────────────────────────────────────────────
+program
+  .name('tetra-migration-lint')
+  .description('Lint SQL migrations for security issues before pushing to Supabase')
+  .option('--staged', 'Only lint git-staged .sql files (for pre-commit hook)')
+  .option('--file <path>', 'Lint a specific SQL file')
+  .option('--fix-suggestions', 'Show fix SQL for each violation')
+  .option('--json', 'JSON output for CI')
+  .option('--project <path>', 'Project root (default: cwd)')
+  .parse()
+
+const opts = program.opts()
+const projectRoot = resolve(opts.project || process.cwd())
+const whitelist = loadWhitelist(projectRoot)
+const files = findMigrations(projectRoot, opts)
+
+if (files.length === 0) {
+  if (!opts.json) console.log(chalk.gray('No migration files to lint.'))
+  process.exit(0)
+}
+
+const allFindings = []
+for (const file of files) {
+  allFindings.push(...lintFile(file, projectRoot, whitelist))
+}
+
+// ─── Output ────────────────────────────────────────────────────────
+if (opts.json) {
+  console.log(JSON.stringify({
+    files: files.length,
+    findings: allFindings,
+    critical: allFindings.filter(f => f.severity === 'critical').length,
+    high: allFindings.filter(f => f.severity === 'high').length,
+    medium: allFindings.filter(f => f.severity === 'medium').length,
+    passed: allFindings.filter(f => f.severity === 'critical' || f.severity === 'high').length === 0
+  }, null, 2))
+} else {
+  const critical = allFindings.filter(f => f.severity === 'critical')
+  const high = allFindings.filter(f => f.severity === 'high')
+  const medium = allFindings.filter(f => f.severity === 'medium')
+
+  console.log('')
+  console.log(chalk.bold('  Tetra Migration Lint'))
+  console.log(chalk.gray(`  ${files.length} migration files scanned`))
+  console.log('')
+
+  if (allFindings.length === 0) {
+    console.log(chalk.green('  ✅ All migrations pass security lint'))
+    console.log('')
+    process.exit(0)
+  }
+
+  // Group by file
+  const byFile = {}
+  for (const f of allFindings) {
+    if (!byFile[f.file]) byFile[f.file] = []
+    byFile[f.file].push(f)
+  }
+
+  for (const [file, findings] of Object.entries(byFile)) {
+    console.log(chalk.underline(`  ${file}`))
+    for (const f of findings) {
+      const icon = f.severity === 'critical' ? '🔴' : f.severity === 'high' ? '🟠' : '🟡'
+      const color = f.severity === 'critical' ? chalk.red : f.severity === 'high' ? chalk.yellow : chalk.gray
+      console.log(`    ${icon} ${color(`[${f.severity.toUpperCase()}]`)} Line ${f.line}: ${f.message}`)
+      if (opts.fixSuggestions && f.fix) {
+        console.log(chalk.cyan(`       Fix: ${f.fix}`))
+      }
+    }
+    console.log('')
+  }
+
+  console.log(chalk.bold('  Summary:'))
+  if (critical.length) console.log(chalk.red(`    ${critical.length} CRITICAL`))
+  if (high.length) console.log(chalk.yellow(`    ${high.length} HIGH`))
+  if (medium.length) console.log(chalk.gray(`    ${medium.length} MEDIUM`))
+  console.log('')
+
+  if (critical.length || high.length) {
+    console.log(chalk.red.bold('  ❌ BLOCKED — fix CRITICAL/HIGH issues before pushing migrations'))
+    console.log(chalk.gray('  Run with --fix-suggestions to see fix SQL'))
+    console.log('')
+    process.exit(1)
+  } else {
+    console.log(chalk.yellow('  ⚠️  Warnings found but not blocking'))
+    console.log('')
+    process.exit(0)
+  }
+}

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

@@ -32,11 +32,11 @@ export const meta = {
 }
 
 const DB_PATTERNS = {
-  systemDB:     { level: 'SYSTEM',     pattern: /systemDB\s*\(/g,     desc: 'System-level (cron, webhooks)' },
-  adminDB:      { level: 'ADMIN',      pattern: /adminDB\s*\(/g,      desc: 'Admin operations (org-scoped)' },
-  userDB:       { level: 'USER',       pattern: /userDB\s*\(/g,       desc: 'User-specific operations' },
-  publicDB:     { level: 'PUBLIC',     pattern: /publicDB\s*\(/g,     desc: 'Public/unauthenticated' },
-  superadminDB: { level: 'SUPERADMIN', pattern: /superadminDB\s*\(/g, desc: 'Cross-org superadmin' }
+  systemDB:     { level: 'SYSTEM',     pattern: /\bsystemDB\s*\(/g,     desc: 'System-level (cron, webhooks)' },
+  adminDB:      { level: 'ADMIN',      pattern: /(?<!\w)adminDB\s*\(/g,  desc: 'Admin operations (org-scoped)' },
+  userDB:       { level: 'USER',       pattern: /\buserDB\s*\(/g,       desc: 'User-specific operations' },
+  publicDB:     { level: 'PUBLIC',     pattern: /\bpublicDB\s*\(/g,     desc: 'Public/unauthenticated' },
+  superadminDB: { level: 'SUPERADMIN', pattern: /\bsuperadminDB\s*\(/g, desc: 'Cross-org superadmin' }
 }
 
 /**

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

@@ -0,0 +1,308 @@
+/**
+ * Route ↔ Config Alignment Check
+ *
+ * Verifies that route files match the feature config accessLevel:
+ *
+ * - accessLevel 'admin'   → route file must be adminRoutes.ts AND must have authenticateToken + requireOrganizationAdmin
+ * - accessLevel 'user'    → route file must be userRoutes.ts AND must have authenticateToken
+ * - accessLevel 'public'  → route can be publicRoutes.ts, NO auth middleware required
+ * - accessLevel 'system'  → should NOT have any route file (backend-only)
+ * - accessLevel 'creator' → route must have authenticateToken
+ *
+ * CRITICAL if an admin endpoint has no auth middleware.
+ * HIGH if route name doesn't match access level.
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join, basename, dirname } from 'path'
+import { globSync } from 'glob'
+
+export const meta = {
+  id: 'route-config-alignment',
+  name: 'Route ↔ Config Alignment',
+  category: 'security',
+  severity: 'critical',
+  description: 'Verifies route middleware matches feature config accessLevel'
+}
+
+/**
+ * Find files matching a glob pattern
+ */
+function findFiles(projectRoot, pattern) {
+  try {
+    return globSync(pattern, { cwd: projectRoot, absolute: true, ignore: ['**/node_modules/**'] })
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Parse all feature configs to extract tableName → accessLevel + feature directory
+ */
+function parseFeatureConfigs(projectRoot) {
+  const configs = [] // { tableName, accessLevel, configFile, featureDir }
+
+  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 }
+
+    const tableMatch = content.match(/tableName:\s*['"]([^'"]+)['"]/)
+    if (!tableMatch) continue
+
+    const tableName = tableMatch[1]
+
+    const accessMatch = content.match(/accessLevel:\s*['"]([^'"]+)['"]/)
+    const accessLevel = accessMatch ? accessMatch[1] : 'admin'
+
+    // Feature directory is two levels up from config file (features/X/config/file.ts → features/X)
+    const configDir = dirname(file)
+    const featureDir = dirname(configDir)
+
+    configs.push({
+      tableName,
+      accessLevel,
+      configFile: file.replace(projectRoot + '/', ''),
+      featureDir
+    })
+  }
+
+  return configs
+}
+
+/**
+ * Find route files in a feature directory
+ */
+function findRouteFiles(featureDir) {
+  const routesDir = join(featureDir, 'routes')
+  if (!existsSync(routesDir)) return []
+
+  try {
+    return globSync('*.ts', { cwd: routesDir, absolute: true, ignore: ['*.d.ts'] })
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Check if a route file contains authenticateToken middleware
+ */
+function hasAuthMiddleware(content) {
+  return /authenticateToken/.test(content)
+}
+
+/**
+ * Check if a route file contains requireOrganizationAdmin middleware
+ */
+function hasOrgAdminMiddleware(content) {
+  return /requireOrganizationAdmin/.test(content)
+}
+
+/**
+ * Expected route filename for a given accessLevel
+ */
+function expectedRouteFileName(accessLevel) {
+  switch (accessLevel) {
+    case 'admin': return 'adminRoutes.ts'
+    case 'user': return 'userRoutes.ts'
+    case 'public': return 'publicRoutes.ts'
+    default: return null
+  }
+}
+
+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: { routesChecked: 0, violations: 0 }
+  }
+
+  const featureConfigs = parseFeatureConfigs(projectRoot)
+
+  if (featureConfigs.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No feature config files found'
+    return results
+  }
+
+  for (const cfg of featureConfigs) {
+    const routeFiles = findRouteFiles(cfg.featureDir)
+
+    // --- system: should NOT have any route file ---
+    if (cfg.accessLevel === 'system') {
+      if (routeFiles.length > 0) {
+        const routeNames = routeFiles.map(f => basename(f)).join(', ')
+        results.findings.push({
+          file: cfg.configFile,
+          line: 1,
+          type: 'system-has-routes',
+          severity: 'high',
+          message: `Config declares accessLevel "system" for table "${cfg.tableName}" but feature has route files: ${routeNames}. System features should be backend-only with no HTTP routes.`,
+          fix: `Remove route files or change accessLevel in the config.`
+        })
+        results.summary.high++
+        results.summary.total++
+        results.passed = false
+        results.details.violations++
+      }
+      continue
+    }
+
+    // Skip features with no routes (may be intentional for some configs)
+    if (routeFiles.length === 0) continue
+
+    // Check each route file in this feature
+    for (const routeFile of routeFiles) {
+      results.details.routesChecked++
+
+      let content
+      try { content = readFileSync(routeFile, 'utf-8') } catch { continue }
+
+      const routeName = basename(routeFile)
+      const relRouteFile = routeFile.replace(projectRoot + '/', '')
+
+      // --- admin checks ---
+      if (cfg.accessLevel === 'admin') {
+        // Route name should be adminRoutes.ts
+        if (routeName === 'adminRoutes.ts') {
+          // CRITICAL: admin route MUST have authenticateToken
+          if (!hasAuthMiddleware(content)) {
+            results.findings.push({
+              file: relRouteFile,
+              line: 1,
+              type: 'admin-route-no-auth',
+              severity: 'critical',
+              message: `Admin route for table "${cfg.tableName}" is missing authenticateToken middleware. Endpoints are accessible without authentication.`,
+              fix: `Add authenticateToken middleware: router.use(authenticateToken, requireOrganizationAdmin)`
+            })
+            results.summary.critical++
+            results.summary.total++
+            results.passed = false
+            results.details.violations++
+          }
+
+          // CRITICAL: admin route MUST have requireOrganizationAdmin
+          if (!hasOrgAdminMiddleware(content)) {
+            results.findings.push({
+              file: relRouteFile,
+              line: 1,
+              type: 'admin-route-no-org-admin',
+              severity: 'critical',
+              message: `Admin route for table "${cfg.tableName}" is missing requireOrganizationAdmin middleware. Any authenticated user can access admin endpoints.`,
+              fix: `Add requireOrganizationAdmin middleware: router.use(authenticateToken, requireOrganizationAdmin)`
+            })
+            results.summary.critical++
+            results.summary.total++
+            results.passed = false
+            results.details.violations++
+          }
+        }
+      }
+
+      // --- user checks ---
+      if (cfg.accessLevel === 'user') {
+        if (routeName === 'userRoutes.ts') {
+          if (!hasAuthMiddleware(content)) {
+            results.findings.push({
+              file: relRouteFile,
+              line: 1,
+              type: 'user-route-no-auth',
+              severity: 'critical',
+              message: `User route for table "${cfg.tableName}" is missing authenticateToken middleware. Endpoints are accessible without authentication.`,
+              fix: `Add authenticateToken middleware: router.use(authenticateToken)`
+            })
+            results.summary.critical++
+            results.summary.total++
+            results.passed = false
+            results.details.violations++
+          }
+        }
+
+        // HIGH: user-level feature shouldn't primarily use adminRoutes
+        if (routeName === 'adminRoutes.ts') {
+          results.findings.push({
+            file: relRouteFile,
+            line: 1,
+            type: 'user-feature-admin-route',
+            severity: 'high',
+            message: `Config declares accessLevel "user" for table "${cfg.tableName}" but has adminRoutes.ts. Route file name does not match access level.`,
+            fix: `Rename to userRoutes.ts or update config accessLevel to "admin".`
+          })
+          results.summary.high++
+          results.summary.total++
+          results.passed = false
+          results.details.violations++
+        }
+      }
+
+      // --- creator checks ---
+      if (cfg.accessLevel === 'creator') {
+        // Creator routes must have authenticateToken
+        if (!hasAuthMiddleware(content) && routeName !== 'publicRoutes.ts') {
+          results.findings.push({
+            file: relRouteFile,
+            line: 1,
+            type: 'creator-route-no-auth',
+            severity: 'critical',
+            message: `Creator route "${routeName}" for table "${cfg.tableName}" is missing authenticateToken middleware. Endpoints are accessible without authentication.`,
+            fix: `Add authenticateToken middleware: router.use(authenticateToken)`
+          })
+          results.summary.critical++
+          results.summary.total++
+          results.passed = false
+          results.details.violations++
+        }
+      }
+
+      // --- public checks: no auth required, just verify naming ---
+      // public routes are fine without auth middleware, no action needed
+
+      // --- Cross-access-level route name mismatch ---
+      // Skip if route file has explicit @tetra-audit-ignore for this check
+      const hasIgnoreDirective = /@tetra-audit-ignore\s+route-config-alignment\b/.test(content)
+      if (cfg.accessLevel === 'admin' && routeName === 'publicRoutes.ts' && !hasAuthMiddleware(content) && !hasIgnoreDirective) {
+        results.findings.push({
+          file: relRouteFile,
+          line: 1,
+          type: 'admin-feature-public-route-no-auth',
+          severity: 'critical',
+          message: `Config declares accessLevel "admin" for table "${cfg.tableName}" but has a publicRoutes.ts without auth. Admin data may be exposed publicly.`,
+          fix: `Either add auth middleware to publicRoutes.ts, or add @tetra-audit-ignore route-config-alignment comment if the public route is intentional.`
+        })
+        results.summary.critical++
+        results.summary.total++
+        results.passed = false
+        results.details.violations++
+      }
+    }
+
+    // HIGH: Check if expected route file name exists for the access level
+    const expected = expectedRouteFileName(cfg.accessLevel)
+    if (expected && routeFiles.length > 0) {
+      const hasExpected = routeFiles.some(f => basename(f) === expected)
+      if (!hasExpected) {
+        const routeNames = routeFiles.map(f => basename(f)).join(', ')
+        results.findings.push({
+          file: cfg.configFile,
+          line: 1,
+          type: 'route-name-mismatch',
+          severity: 'high',
+          message: `Config declares accessLevel "${cfg.accessLevel}" for table "${cfg.tableName}" expecting ${expected} but found: ${routeNames}.`,
+          fix: `Rename the primary route file to ${expected} or update the config accessLevel.`
+        })
+        results.summary.high++
+        results.summary.total++
+        results.passed = false
+        results.details.violations++
+      }
+    }
+  }
+
+  return results
+}

package/lib/checks/security/rpc-security-mode.js

@@ -0,0 +1,175 @@
+/**
+ * RPC Security Mode Check — HARD BLOCK
+ *
+ * Scans ALL SQL migrations for RPC functions and verifies their security mode:
+ *
+ * SECURITY DEFINER = function runs as the DB owner, BYPASSES RLS completely.
+ * SECURITY INVOKER = function runs as the calling user, RLS is enforced.
+ *
+ * Rules:
+ * - Data query RPCs (get_*, list_*, search_*) → MUST be INVOKER
+ * - Auth helper functions (auth_org_id, auth_uid) → DEFINER is OK (they need to read auth.users)
+ * - Count/results RPCs linked to feature configs → MUST be INVOKER
+ * - Public RPCs (explicitly returning only public columns) → DEFINER is OK if whitelisted
+ *
+ * Whitelist: .tetra-quality.json → supabase.securityDefinerWhitelist: ['auth_org_id', ...]
+ *
+ * Reference: stella_howto_get slug="tetra-architecture-guide"
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import { globSync } from 'glob'
+
+export const meta = {
+  id: 'rpc-security-mode',
+  name: 'RPC Security Mode',
+  category: 'security',
+  severity: 'critical',
+  description: 'Verifies all RPC functions use SECURITY INVOKER (not DEFINER) unless explicitly whitelisted. DEFINER bypasses RLS completely.'
+}
+
+// Functions that legitimately need SECURITY DEFINER
+const BUILTIN_DEFINER_WHITELIST = [
+  // Auth helpers (need to read auth schema / organization_members)
+  'auth_org_id',
+  'auth_admin_organizations',
+  'auth_user_organizations',
+  'auth_creator_organizations',
+  'get_user_org_role',
+  'get_org_id',
+  'handle_new_user',
+  'moddatetime',
+  // Public RPCs (called by anon users, need DEFINER to bypass RLS and return only safe columns)
+  'search_public_ad_library',
+  // System/billing RPCs (called by systemDB, no user context)
+  'get_org_credit_limits',
+  // Supabase internal
+  'pgsodium_encrypt',
+  'pgsodium_decrypt'
+]
+
+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: { rpcsFound: 0, definerCount: 0, invokerCount: 0, defaultCount: 0, whitelistedCount: 0 }
+  }
+
+  const migrationDirs = [
+    join(projectRoot, 'supabase/migrations'),
+    join(projectRoot, 'backend/supabase/migrations')
+  ]
+
+  const sqlFiles = []
+  for (const dir of migrationDirs) {
+    if (!existsSync(dir)) continue
+    try {
+      const files = globSync('*.sql', { cwd: dir, absolute: true })
+      sqlFiles.push(...files)
+    } catch { /* skip */ }
+  }
+
+  if (sqlFiles.length === 0) {
+    results.skipped = true
+    results.skipReason = 'No SQL migration files found'
+    return results
+  }
+
+  // Build whitelist from config + builtins
+  const userWhitelist = (config.supabase?.securityDefinerWhitelist || [])
+  const whitelist = new Set([...BUILTIN_DEFINER_WHITELIST, ...userWhitelist])
+
+  // Track latest definition per function (migrations can override)
+  const functions = new Map() // funcName → { securityMode, file, line, isDataQuery }
+
+  for (const file of sqlFiles) {
+    let content
+    try { content = readFileSync(file, 'utf-8') } catch { continue }
+
+    const relFile = file.replace(projectRoot + '/', '')
+
+    // Find all CREATE [OR REPLACE] FUNCTION statements
+    const funcRegex = /CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+(?:public\.)?(\w+)\s*\(/gi
+    let match
+
+    while ((match = funcRegex.exec(content)) !== null) {
+      const funcName = match[1]
+      const startPos = match.index
+
+      // Extract the function body (up to next CREATE FUNCTION or end of file, max 5000 chars)
+      const bodyEnd = Math.min(startPos + 5000, content.length)
+      const funcBody = content.substring(startPos, bodyEnd)
+
+      // Determine security mode
+      let securityMode = 'DEFAULT' // PostgreSQL default is INVOKER
+      if (/SECURITY\s+DEFINER/i.test(funcBody.substring(0, 2000))) {
+        securityMode = 'DEFINER'
+      } else if (/SECURITY\s+INVOKER/i.test(funcBody.substring(0, 2000))) {
+        securityMode = 'INVOKER'
+      }
+
+      // Determine if this is a data query function
+      const isDataQuery = /^(get_|list_|search_|find_|fetch_|count_)/i.test(funcName) ||
+                          /_counts$|_results$|_detail$/i.test(funcName)
+
+      // Calculate line number
+      const beforeMatch = content.substring(0, startPos)
+      const line = (beforeMatch.match(/\n/g) || []).length + 1
+
+      // Store (later definitions override earlier ones)
+      functions.set(funcName, { securityMode, file: relFile, line, isDataQuery, funcBody: funcBody.substring(0, 500) })
+    }
+  }
+
+  results.details.rpcsFound = functions.size
+
+  for (const [funcName, info] of functions) {
+    if (info.securityMode === 'DEFINER') {
+      results.details.definerCount++
+
+      // Check whitelist
+      if (whitelist.has(funcName)) {
+        results.details.whitelistedCount++
+        continue
+      }
+
+      // Data query RPCs with DEFINER = CRITICAL
+      if (info.isDataQuery) {
+        results.passed = false
+        results.findings.push({
+          file: info.file,
+          line: info.line,
+          type: 'data-rpc-security-definer',
+          severity: 'critical',
+          message: `Data RPC "${funcName}" uses SECURITY DEFINER — bypasses ALL RLS policies. Any authenticated user can see ALL data from ALL organizations.`,
+          fix: `Change to SECURITY INVOKER or remove the SECURITY DEFINER clause. If this function legitimately needs DEFINER, add "${funcName}" to supabase.securityDefinerWhitelist in .tetra-quality.json.`
+        })
+        results.summary.critical++
+        results.summary.total++
+      } else {
+        // Non-data RPCs with DEFINER = HIGH (should still be investigated)
+        results.findings.push({
+          file: info.file,
+          line: info.line,
+          type: 'non-data-rpc-security-definer',
+          severity: 'high',
+          message: `RPC "${funcName}" uses SECURITY DEFINER but is not whitelisted. DEFINER functions bypass RLS — ensure this is intentional.`,
+          fix: `Change to SECURITY INVOKER, or add "${funcName}" to supabase.securityDefinerWhitelist in .tetra-quality.json if DEFINER is intentional.`
+        })
+        results.summary.high++
+        results.summary.total++
+        results.passed = false
+      }
+    } else if (info.securityMode === 'INVOKER') {
+      results.details.invokerCount++
+    } else {
+      results.details.defaultCount++
+      // DEFAULT = INVOKER in PostgreSQL, which is correct
+    }
+  }
+
+  return results
+}

package/lib/runner.js

@@ -15,6 +15,7 @@ import * as frontendSupabaseQueries from './checks/security/frontend-supabase-qu
 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 rpcSecurityMode from './checks/security/rpc-security-mode.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'
@@ -24,6 +25,7 @@ import * as fileSize from './checks/codeQuality/file-size.js'
 import * as namingConventions from './checks/codeQuality/naming-conventions.js'
 import * as routeSeparation from './checks/codeQuality/route-separation.js'
 import * as gitignoreValidation from './checks/security/gitignore-validation.js'
+import * as routeConfigAlignment from './checks/security/route-config-alignment.js'
 import * as rlsPolicyAudit from './checks/supabase/rls-policy-audit.js'
 import * as rpcParamMismatch from './checks/supabase/rpc-param-mismatch.js'
 import * as rpcGeneratorOrigin from './checks/supabase/rpc-generator-origin.js'
@@ -41,8 +43,10 @@ const ALL_CHECKS = {
     tetraCoreCompliance,
     mixedDbUsage,
     configRlsAlignment,
+    rpcSecurityMode,
     systemdbWhitelist,
-    gitignoreValidation
+    gitignoreValidation,
+    routeConfigAlignment
   ],
   stability: [
     huskyHooks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.13.1",
+  "version": "1.15.0",
   "publishConfig": {
     "access": "restricted"
   },
@@ -29,7 +29,9 @@
     "tetra-init": "./bin/tetra-init.js",
     "tetra-setup": "./bin/tetra-setup.js",
     "tetra-dev-token": "./bin/tetra-dev-token.js",
-    "tetra-check-rls": "./bin/tetra-check-rls.js"
+    "tetra-check-rls": "./bin/tetra-check-rls.js",
+    "tetra-migration-lint": "./bin/tetra-migration-lint.js",
+    "tetra-db-push": "./bin/tetra-db-push.js"
   },
   "files": [
     "bin/",