@soulbatical/tetra-dev-toolkit 1.17.2 → 1.17.4

package/bin/tetra-check-peers.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+/**
+ * Tetra Check Peers — Validate peer dependency compatibility across consumer projects
+ *
+ * Scans all known consumer projects and checks if their installed versions
+ * are compatible with tetra packages' peerDependencies.
+ *
+ * Usage:
+ *   tetra-check-peers                  # Check all consumers
+ *   tetra-check-peers --fix            # Show npm commands to fix mismatches
+ *   tetra-check-peers --strict         # Fail on any mismatch (for CI/prepublish)
+ *   tetra-check-peers --json           # JSON output
+ *
+ * Add to prepublishOnly to catch breaking peer dep changes before publish.
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join, basename, dirname } from 'path'
+import { execSync } from 'child_process'
+
+// ─── Config ──────────────────────────────────────────────
+
+const PROJECTS_ROOT = join(process.env.HOME || '~', 'projecten')
+const TETRA_ROOT = join(PROJECTS_ROOT, 'tetra', 'packages')
+
+// Tetra packages that have peerDependencies
+const TETRA_PACKAGES = ['core', 'ui', 'dev-toolkit', 'schemas']
+
+// ─── Helpers ─────────────────────────────────────────────
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+function satisfiesRange(installed, range) {
+  // Simple semver range check without external deps
+  // Handles: exact "2.93.3", caret "^2.93.3", tilde "~2.93.3", star "*", >= ">= 8.0.0"
+  if (!installed || !range) return false
+  if (range === '*') return true
+
+  // Clean versions: remove leading ^ ~ >= <= > < =
+  const cleanVersion = (v) => v.replace(/^[\^~>=<\s]+/, '').trim()
+  const parseVersion = (v) => {
+    const cleaned = cleanVersion(v)
+    const parts = cleaned.split('.').map(Number)
+    return { major: parts[0] || 0, minor: parts[1] || 0, patch: parts[2] || 0 }
+  }
+
+  const inst = parseVersion(installed)
+  const req = parseVersion(range)
+
+  if (range.startsWith('>=')) {
+    // >= check
+    if (inst.major > req.major) return true
+    if (inst.major === req.major && inst.minor > req.minor) return true
+    if (inst.major === req.major && inst.minor === req.minor && inst.patch >= req.patch) return true
+    return false
+  }
+
+  if (range.startsWith('^') || range.includes('||')) {
+    // Caret: same major, >= minor.patch
+    // For ranges with || (e.g. "^18.0.0 || ^19.0.0"), check each part
+    const parts = range.split('||').map(p => p.trim())
+    return parts.some(part => {
+      const r = parseVersion(part)
+      if (inst.major !== r.major) return false
+      if (inst.minor > r.minor) return true
+      if (inst.minor === r.minor && inst.patch >= r.patch) return true
+      return false
+    })
+  }
+
+  if (range.startsWith('~')) {
+    // Tilde: same major.minor, >= patch
+    if (inst.major !== req.major || inst.minor !== req.minor) return false
+    return inst.patch >= req.patch
+  }
+
+  // Exact version match
+  return inst.major === req.major && inst.minor === req.minor && inst.patch === req.patch
+}
+
+// ─── Discovery ───────────────────────────────────────────
+
+function discoverTetraPeerDeps() {
+  const result = {}
+
+  for (const pkg of TETRA_PACKAGES) {
+    const pkgJson = readJson(join(TETRA_ROOT, pkg, 'package.json'))
+    if (!pkgJson?.peerDependencies) continue
+
+    result[pkgJson.name] = {
+      version: pkgJson.version,
+      peerDependencies: pkgJson.peerDependencies,
+      peerDependenciesMeta: pkgJson.peerDependenciesMeta || {}
+    }
+  }
+
+  return result
+}
+
+function discoverConsumers() {
+  const consumers = []
+
+  try {
+    const dirs = execSync(`ls -d ${PROJECTS_ROOT}/*/`, { encoding: 'utf-8' })
+      .trim().split('\n').filter(Boolean)
+
+    for (const dir of dirs) {
+      const projectName = basename(dir.replace(/\/$/, ''))
+      if (projectName === 'tetra' || projectName.startsWith('.') || projectName.startsWith('_')) continue
+
+      // Check root, backend/, frontend/ package.json
+      const locations = [
+        { path: join(dir, 'package.json'), label: projectName },
+        { path: join(dir, 'backend', 'package.json'), label: `${projectName}/backend` },
+        { path: join(dir, 'frontend', 'package.json'), label: `${projectName}/frontend` },
+      ]
+
+      for (const loc of locations) {
+        const pkg = readJson(loc.path)
+        if (!pkg) continue
+
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+
+        // Check if this package.json uses any tetra package
+        const usesTetra = Object.keys(allDeps).some(d => d.startsWith('@soulbatical/tetra-'))
+        if (!usesTetra) continue
+
+        consumers.push({
+          label: loc.label,
+          path: loc.path,
+          dependencies: allDeps,
+          tetraDeps: Object.fromEntries(
+            Object.entries(allDeps).filter(([k]) => k.startsWith('@soulbatical/tetra-'))
+          )
+        })
+      }
+    }
+  } catch {
+    // ignore discovery errors
+  }
+
+  return consumers
+}
+
+// ─── Check ───────────────────────────────────────────────
+
+function checkCompatibility(tetraPeers, consumers) {
+  const issues = []
+
+  for (const consumer of consumers) {
+    for (const [tetraPkg, tetraInfo] of Object.entries(tetraPeers)) {
+      // Does this consumer use this tetra package?
+      if (!consumer.tetraDeps[tetraPkg]) continue
+
+      // Check each peer dependency
+      for (const [peerDep, requiredRange] of Object.entries(tetraInfo.peerDependencies)) {
+        const isOptional = tetraInfo.peerDependenciesMeta[peerDep]?.optional
+        const installedVersion = consumer.dependencies[peerDep]
+
+        if (!installedVersion) {
+          if (!isOptional) {
+            issues.push({
+              consumer: consumer.label,
+              tetraPackage: tetraPkg,
+              dependency: peerDep,
+              required: requiredRange,
+              installed: 'MISSING',
+              severity: 'error',
+              fix: `npm install ${peerDep}@"${requiredRange}"`
+            })
+          }
+          continue
+        }
+
+        // Extract version from range (consumer might have "^2.93.3")
+        const cleanInstalled = installedVersion.replace(/^[\^~>=<\s]+/, '')
+
+        if (!satisfiesRange(cleanInstalled, requiredRange)) {
+          // Check if it's an exact pin vs range issue
+          const isExactPin = !requiredRange.startsWith('^') && !requiredRange.startsWith('~') && !requiredRange.startsWith('>')
+          const severity = isExactPin ? 'warning' : 'error'
+
+          issues.push({
+            consumer: consumer.label,
+            tetraPackage: tetraPkg,
+            dependency: peerDep,
+            required: requiredRange,
+            installed: installedVersion,
+            severity,
+            isExactPin,
+            fix: `npm install ${peerDep}@"${requiredRange}"`,
+            suggestion: isExactPin
+              ? `Consider using "^${requiredRange}" in ${tetraPkg} peerDependencies for flexibility`
+              : null
+          })
+        }
+      }
+    }
+  }
+
+  return issues
+}
+
+// ─── Output ──────────────────────────────────────────────
+
+function formatTerminal(issues, consumers, tetraPeers, options) {
+  const lines = []
+
+  lines.push('')
+  lines.push('═══════════════════════════════════════════════════════════════')
+  lines.push('  🔗 Tetra Check Peers — Peer Dependency Compatibility')
+  lines.push('═══════════════════════════════════════════════════════════════')
+  lines.push('')
+
+  // Summary
+  const tetraPackages = Object.entries(tetraPeers)
+    .map(([name, info]) => `${name}@${info.version}`)
+    .join(', ')
+  lines.push(`  Tetra packages: ${tetraPackages}`)
+  lines.push(`  Consumers found: ${consumers.length}`)
+  lines.push(`  Issues found: ${issues.length}`)
+  lines.push('')
+
+  if (issues.length === 0) {
+    lines.push('  ✅ All consumer projects are compatible with current peer dependencies')
+    lines.push('')
+    lines.push('═══════════════════════════════════════════════════════════════')
+    return lines.join('\n')
+  }
+
+  // Group by consumer
+  const byConsumer = {}
+  for (const issue of issues) {
+    if (!byConsumer[issue.consumer]) byConsumer[issue.consumer] = []
+    byConsumer[issue.consumer].push(issue)
+  }
+
+  for (const [consumer, consumerIssues] of Object.entries(byConsumer)) {
+    lines.push(`  📦 ${consumer}`)
+    for (const issue of consumerIssues) {
+      const icon = issue.severity === 'error' ? '❌' : '⚠️'
+      lines.push(`     ${icon} ${issue.dependency}: installed ${issue.installed}, needs ${issue.required}`)
+      if (issue.suggestion) {
+        lines.push(`        💡 ${issue.suggestion}`)
+      }
+      if (options.fix) {
+        lines.push(`        → ${issue.fix}`)
+      }
+    }
+    lines.push('')
+  }
+
+  // Exact pin warnings
+  const exactPins = issues.filter(i => i.isExactPin)
+  if (exactPins.length > 0) {
+    const uniquePins = [...new Set(exactPins.map(i => `${i.dependency} (${i.required} in ${i.tetraPackage})`))]
+    lines.push('  💡 EXACT VERSION PINS detected — these cause most compatibility issues:')
+    for (const pin of uniquePins) {
+      lines.push(`     → ${pin}`)
+    }
+    lines.push('     Consider using "^x.y.z" ranges instead of exact versions in peerDependencies')
+    lines.push('')
+  }
+
+  lines.push('═══════════════════════════════════════════════════════════════')
+  return lines.join('\n')
+}
+
+// ─── Main ────────────────────────────────────────────────
+
+const args = process.argv.slice(2)
+const options = {
+  fix: args.includes('--fix'),
+  strict: args.includes('--strict'),
+  json: args.includes('--json'),
+}
+
+const tetraPeers = discoverTetraPeerDeps()
+const consumers = discoverConsumers()
+const issues = checkCompatibility(tetraPeers, consumers)
+
+if (options.json) {
+  console.log(JSON.stringify({ tetraPeers, consumers: consumers.map(c => c.label), issues }, null, 2))
+} else {
+  console.log(formatTerminal(issues, consumers, tetraPeers, options))
+}
+
+// Exit code
+const errors = issues.filter(i => i.severity === 'error')
+if (options.strict && errors.length > 0) {
+  process.exit(1)
+}

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

@@ -194,15 +194,30 @@ function parseMigrations(projectRoot) {
           || content.match(/(?:TEXT\[\]|text\[\])\s*:=\s*ARRAY\s*\[\s*'([^[\]]+)'\s*\]/i)
         if (arrayMatch) {
           const loopTables = arrayMatch[1].split(/'\s*,\s*'/).map(t => t.trim())
-          const execLines = [...content.matchAll(/EXECUTE\s+format\s*\(\s*'(CREATE\s+POLICY\s+.*?)'\s*,/gi)]
+          // Match EXECUTE format('CREATE POLICY ...', ...) — multi-line, with escaped quotes ('')
+          // PL/pgSQL escapes single quotes as '' inside strings, so we must allow '' within the match
+          // The format string ends with a single ' (not '') followed by , or ;
+          const execLines = [...content.matchAll(/EXECUTE\s+format\s*\(\s*'(CREATE\s+POLICY(?:[^']|'')*?)'\s*,/gi)]
           for (const exec of execLines) {
-            const stmt = exec[1]
+            // Unescape PL/pgSQL doubled quotes back to single quotes for analysis
+            const stmt = exec[1].replace(/''/g, "'")
             const forOp = stmt.match(/FOR\s+(SELECT|INSERT|UPDATE|DELETE|ALL)/i)
             const operation = forOp ? forOp[1].toUpperCase() : 'ALL'
             const hasUsing = /\bUSING\b/i.test(stmt)
             const hasWithCheck = /WITH\s+CHECK/i.test(stmt)
-            const condMatch = stmt.match(/(?:USING|WITH\s+CHECK)\s*\(\s*(.*?)\s*\)/i)
-            const condition = condMatch ? condMatch[1] : ''
+
+            // Extract the full USING/WITH CHECK clause (may be multi-line with nested parens)
+            let usingCondition = ''
+            let withCheckCondition = ''
+            if (hasUsing) {
+              const uMatch = stmt.match(/USING\s*\(\s*([\s\S]*?)\s*\)\s*(?:WITH\s+CHECK|$)/i)
+                || stmt.match(/USING\s*\(\s*([\s\S]*?)\s*\)\s*$/i)
+              usingCondition = uMatch ? uMatch[1].trim() : ''
+            }
+            if (hasWithCheck) {
+              const wcMatch = stmt.match(/WITH\s+CHECK\s*\(\s*([\s\S]*?)\s*\)\s*$/i)
+              withCheckCondition = wcMatch ? wcMatch[1].trim() : ''
+            }
 
             for (const table of loopTables) {
               if (!tables.has(table)) tables.set(table, { rlsEnabled: false, policies: [], rpcFunctions: new Map() })
@@ -211,8 +226,8 @@ function parseMigrations(projectRoot) {
                 tables.get(table).policies.push({
                   name: policyName,
                   operation,
-                  using: hasUsing ? condition : '',
-                  withCheck: hasWithCheck ? condition : '',
+                  using: usingCondition,
+                  withCheck: withCheckCondition,
                   file: relFile
                 })
               }
@@ -281,117 +296,95 @@ function isWideOpen(using) {
 }
 
 /**
- * Whitelist-based RLS policy validation.
+ * Allowed RLS policy patterns — whitelist approach.
  *
- * ONLY these building blocks are allowed in USING/WITH CHECK clauses.
- * Derived from sparkbuddy-live (the reference implementation).
- * Everything that doesn't match is rejected as unrecognized.
+ * Derived from sparkbuddy-live production DB (562 policies analyzed).
+ * These are the ONLY structural patterns allowed in USING/WITH CHECK clauses.
+ * Everything else is rejected. To add a new pattern: add it here with justification.
  *
- * To add a new pattern: add it here AND document why it's safe.
+ * Categories:
+ * 1. Org isolation:  auth_admin_organizations(), auth_user_organizations(), auth_org_id()
+ * 2. User isolation: auth.uid(), auth_current_user_id()
+ * 3. Role gates:     auth.role() = 'authenticated' or 'anon' (NOT 'service_role')
+ * 4. Data filters:   column = literal, IS NULL, boolean checks
+ * 5. Parent checks:  IN (SELECT ...), EXISTS (SELECT ...)
+ * 6. Open access:    true, false
+ * 7. Legacy:         auth.jwt() -> 'app_metadata', current_setting('app.*')
  */
-const ALLOWED_RLS_ATOMS = [
-  // Org isolation via helper functions
-  /auth_admin_organizations\s*\(\)/i,
-  /auth_user_organizations\s*\(\)/i,
-  /auth_org_id\s*\(\)/i,
-  /auth_current_user_id\s*\(\)/i,
-  // User isolation
-  /auth\.uid\s*\(\)/i,
-  // Column comparisons (org_id, user_id, etc.)
-  /organization_id/i,
-  /organizationid/i,
-  /active_organization_id/i,
-  /user_id/i,
-  /userid/i,
-  /owner_id/i,
-  /created_by/i,
-  /creator_id/i,
-  /shared_by/i,
-  /sparkbuddy_user_id/i,
-  /user_public_id/i,
-  // Boolean/status column checks (for public/active filtering)
-  /is_active/i,
-  /is_public/i,
-  /is_template/i,
-  /is_published/i,
-  /anonymous_access/i,
-  /allow_cross_org_usage/i,
-  /visibility_level/i,
-  /published_status/i,
-  /post_type/i,
-  /status/i,
-  /active/i,
-  /invitation_token/i,
-  /original_testimonial_id/i,
-  /expires_at/i,
-  /session_id/i,
-  // Subqueries to parent tables
-  /\bIN\s*\(\s*SELECT\b/i,
-  /\bEXISTS\s*\(\s*SELECT\b/i,
-  // Literals and operators
-  /true/i,
-  /false/i,
-  /null/i,
-  /now\s*\(\)/i,
-  /\bAND\b/i,
-  /\bOR\b/i,
-  /\bNOT\b/i,
-  /\bIS\b/i,
-  /\bANY\b/i,
-  /\bARRAY\b/i,
-  // Legacy JWT pattern (sparkbuddy initial schema)
-  /auth\.jwt\s*\(\)/i,
-  /app_metadata/i,
-  // current_setting for app context (NOT role/jwt.claims bypass)
-  /current_setting\s*\(\s*'app\./i,
+const ALLOWED_RLS_PATTERNS = [
+  // 1. Org isolation helper functions
+  { pattern: /auth_admin_organizations\s*\(\)/i, label: 'org-admin isolation' },
+  { pattern: /auth_user_organizations\s*\(\)/i, label: 'org-user isolation' },
+  { pattern: /auth_org_id\s*\(\)/i, label: 'org isolation' },
+
+  // 2. User isolation
+  { pattern: /auth\.uid\s*\(\)/i, label: 'user isolation' },
+  { pattern: /auth_current_user_id\s*\(\)/i, label: 'user isolation' },
+
+  // 3. Role gates (ONLY authenticated and anon — never service_role)
+  { pattern: /auth\.role\s*\(\)\s*=\s*'authenticated'/i, label: 'authenticated role gate' },
+  { pattern: /auth\.role\s*\(\)\s*=\s*'anon'/i, label: 'anon role gate' },
+
+  // 4. Column comparisons and data filters (any column = any value is fine)
+  //    This is inherently safe — it filters data, doesn't bypass auth
+  { pattern: /\w+\s*=\s*/i, label: 'column comparison' },
+  { pattern: /\w+\s+IS\s+(NOT\s+)?NULL/i, label: 'null check' },
+  { pattern: /\w+\s+IN\s*\(/i, label: 'IN check' },
+  { pattern: /\w+\s*=\s*ANY\s*\(/i, label: 'ANY check' },
+
+  // 5. Parent table checks
+  { pattern: /EXISTS\s*\(\s*SELECT/i, label: 'exists subquery' },
+
+  // 6. Open access
+  { pattern: /^\s*true\s*$/i, label: 'public access' },
+  { pattern: /^\s*\(true\)\s*$/i, label: 'public access' },
+  { pattern: /^\s*false\s*$/i, label: 'deny all' },
+
+  // 7. Legacy JWT and app context
+  { pattern: /auth\.jwt\s*\(\)/i, label: 'legacy JWT' },
+  { pattern: /current_setting\s*\(\s*'app\./i, label: 'app context' },
+
+  // 8. Custom helper functions (e.g. is_org_member(), is_product_publicly_accessible())
+  //    These are project-specific SECURITY DEFINER helpers — safe as long as
+  //    the function itself is audited (which is done by the RPC Security Mode check)
+  { pattern: /\b\w+\s*\([^)]*\)/i, label: 'function call' },
 ]
 
 /**
- * Patterns that are NEVER allowed in RLS policies, regardless of context.
- * These bypass RLS and defeat the purpose of having policies at all.
+ * Patterns BANNED from RLS policies — these bypass tenant isolation.
+ * Service role already bypasses RLS at the Supabase layer automatically.
+ * Adding these to policies creates a false sense of security and opens
+ * cross-tenant data leakage vectors.
+ *
+ * Derived from sparkbuddy-live analysis: 2 policies with auth.role()='service_role'
+ * were identified as tech debt (redirects, translations) — not a pattern to follow.
  */
 const BANNED_RLS_PATTERNS = [
   { pattern: /service_role/i, label: 'service_role bypass — service role already bypasses RLS at the Supabase layer' },
-  { pattern: /current_setting\s*\(\s*'role'\s*(?:,\s*true\s*)?\)/i, label: 'PostgreSQL role check — bypasses tenant isolation' },
+  { pattern: /auth\.role\s*\(\)\s*=\s*'service_role'/i, label: 'auth.role() service_role bypass — service role already bypasses RLS automatically' },
+  { pattern: /current_setting\s*\(\s*'role'/i, label: 'PostgreSQL role check — bypasses tenant isolation' },
   { pattern: /current_setting\s*\(\s*'request\.jwt\.claims'/i, label: 'JWT claims role check — bypasses tenant isolation' },
   { pattern: /session_user/i, label: 'session_user check — bypasses tenant isolation' },
   { pattern: /current_user\s*=/i, label: 'current_user check — bypasses tenant isolation' },
-  { pattern: /auth\.role\s*\(\)/i, label: 'auth.role() check — bypasses tenant isolation' },
   { pattern: /pg_has_role/i, label: 'pg_has_role — bypasses tenant isolation' },
 ]
 
 /**
  * Validate an RLS clause against the whitelist.
- * Returns null if valid, or a description of what's wrong.
+ * Returns null if valid, or a description string if banned/unrecognized.
  */
 function validateRlsClause(clause) {
   if (!clause || !clause.trim()) return null
 
-  // First check for explicitly banned patterns
+  // First: check for explicitly banned patterns (these are always wrong)
   for (const { pattern, label } of BANNED_RLS_PATTERNS) {
     if (pattern.test(clause)) return label
   }
 
-  // Strip known-safe tokens and see if anything suspicious remains
-  let stripped = clause
-  // Remove string literals
-  stripped = stripped.replace(/'[^']*'/g, '')
-  // Remove numbers
-  stripped = stripped.replace(/\b\d+\b/g, '')
-  // Remove known-safe identifiers and functions
-  for (const atom of ALLOWED_RLS_ATOMS) {
-    stripped = stripped.replace(new RegExp(atom.source, 'gi'), '')
-  }
-  // Remove SQL syntax noise (parens, commas, operators, quotes, casts, aliases)
-  stripped = stripped.replace(/[(),"=<>!:.|{}\-\+\*\/\s]/g, '')
-  stripped = stripped.replace(/\b(AS|FROM|WHERE|SELECT|JOIN|ON|LIMIT|uuid|text|boolean|integer|jsonb|json|public|ARRAY|FOR)\b/gi, '')
-  // Remove table/column qualifiers that look like identifiers (lowercase + underscore)
-  stripped = stripped.replace(/\b[a-z_][a-z0-9_]*\b/gi, '')
-  stripped = stripped.trim()
-
-  // If anything substantial remains, it's an unrecognized pattern
-  if (stripped.length > 0) {
-    return `Unrecognized RLS clause content: "${clause.substring(0, 120)}". Only whitelisted patterns are allowed.`
+  // Second: verify clause contains at least one allowed pattern
+  const hasAllowedPattern = ALLOWED_RLS_PATTERNS.some(({ pattern }) => pattern.test(clause))
+  if (!hasAllowedPattern) {
+    return `Unrecognized RLS clause: "${clause.substring(0, 150)}". Only whitelisted patterns are allowed (org/user isolation, role gates, data filters, subqueries). See ALLOWED_RLS_PATTERNS in config-rls-alignment.js.`
   }
 
   return null

package/lib/checks/security/systemdb-whitelist.js

@@ -63,6 +63,9 @@ const ALLOWED_FILE_PATTERNS = [
   /BaseCronService/,
   // Internal service-to-service routes (API key auth, no user JWT)
   /internalRoutes/,
+  // Billing routers — hybrid files with both authenticated admin routes and unauthenticated webhook handlers
+  // systemDB is needed for Tetra BillingService config callbacks (getSystemDB, getWebhookDB)
+  /billingRouter/,
 ]
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.17.2",
+  "version": "1.17.4",
   "publishConfig": {
     "access": "restricted"
   },
@@ -31,7 +31,8 @@
     "tetra-dev-token": "./bin/tetra-dev-token.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"
+    "tetra-db-push": "./bin/tetra-db-push.js",
+    "tetra-check-peers": "./bin/tetra-check-peers.js"
   },
   "files": [
     "bin/",