@soulbatical/tetra-dev-toolkit 1.14.0 → 1.15.1

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,310 @@
+#!/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',
+        'auth_user_organizations', 'auth_creator_organizations',
+        'auth_organization_id', 'auth_is_admin', 'auth_is_superadmin'
+      ]
+      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) => {
+      const table = match[2]
+      // 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\\.)?${table}`, 'i')
+      if (createPattern.test(fullContent)) return false
+      // OK if there's a DO $$ block that references the table (dynamic policy creation)
+      const doBlockPattern = new RegExp(`DO\\s+\\$\\$[\\s\\S]*?['"]${table}['"][\\s\\S]*?\\$\\$`, 'i')
+      if (doBlockPattern.test(fullContent)) return false
+      // OK if DROP POLICY IF EXISTS (safe — only drops if present)
+      const dropIfExists = new RegExp(`DROP\\s+POLICY\\s+IF\\s+EXISTS`, 'i')
+      const matchStr = match[0]
+      if (dropIfExists.test(matchStr)) {
+        // Check if ANY policy creation exists for this table (even dynamic)
+        const anyCreate = new RegExp(`(CREATE\\s+POLICY|EXECUTE\\s+format.*CREATE\\s+POLICY)`, 'i')
+        if (anyCreate.test(fullContent)) return false
+      }
+      return true
+    },
+    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

@@ -264,14 +264,16 @@ export async function run(config, projectRoot) {
       // public routes are fine without auth middleware, no action needed
 
       // --- Cross-access-level route name mismatch ---
-      if (cfg.accessLevel === 'admin' && routeName === 'publicRoutes.ts' && !hasAuthMiddleware(content)) {
+      // 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 ensure it only exposes non-sensitive endpoints.`
+          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++

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

@@ -29,15 +29,21 @@ export const meta = {
   description: 'Verifies all RPC functions use SECURITY INVOKER (not DEFINER) unless explicitly whitelisted. DEFINER bypasses RLS completely.'
 }
 
-// Auth helper functions that legitimately need SECURITY DEFINER
+// 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'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "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/",