@soulbatical/tetra-dev-toolkit 1.17.1 → 1.17.3

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

@@ -281,32 +281,98 @@ function isWideOpen(using) {
 }
 
 /**
- * Forbidden patterns in RLS policies — these bypass RLS and defeat the purpose.
- * Valid patterns (from sparkbuddy-live):
- *   - organization_id IN (SELECT auth_admin_organizations())
- *   - user_id = auth.uid()
- *   - USING(true) for public tables only
- *   - Subquery to parent table with org/user check
+ * Allowed RLS policy patterns — whitelist approach.
  *
- * Everything else that grants blanket access is a security hole.
+ * 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.
+ *
+ * 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 FORBIDDEN_RLS_PATTERNS = [
-  { pattern: /service_role/i, label: 'service_role bypass' },
-  { pattern: /current_setting\s*\(\s*'role'/i, label: 'PostgreSQL role check bypass' },
-  { pattern: /current_setting\s*\(\s*'request\.jwt\.claims'/i, label: 'JWT claims role bypass' },
-  { pattern: /session_user\s*=\s*'postgres'/i, label: 'session_user postgres bypass' },
-  { pattern: /current_user\s*=\s*'postgres'/i, label: 'current_user postgres bypass' },
-  { pattern: /auth\.role\s*\(\)\s*=\s*'service_role'/i, label: 'auth.role() service_role bypass' },
-  { pattern: /pg_has_role/i, label: 'pg_has_role bypass' },
+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' },
 ]
 
 /**
- * Check if a USING/WITH CHECK clause contains forbidden bypass patterns
- * Returns array of { label } for each forbidden pattern found
+ * 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.
  */
-function findForbiddenPatterns(clause) {
-  if (!clause) return []
-  return FORBIDDEN_RLS_PATTERNS.filter(({ pattern }) => pattern.test(clause)).map(({ label }) => label)
+const BANNED_RLS_PATTERNS = [
+  { pattern: /service_role/i, label: 'service_role bypass — service role already bypasses RLS at the Supabase layer' },
+  { 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: /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 string if banned/unrecognized.
+ */
+function validateRlsClause(clause) {
+  if (!clause || !clause.trim()) return null
+
+  // First: check for explicitly banned patterns (these are always wrong)
+  for (const { pattern, label } of BANNED_RLS_PATTERNS) {
+    if (pattern.test(clause)) return label
+  }
+
+  // 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
 }
 
 export async function run(config, projectRoot) {
@@ -475,24 +541,24 @@ export async function run(config, projectRoot) {
       }
     }
 
-    // CHECK 4b: No forbidden bypass patterns in any policy clause
+    // CHECK 4b: All policy clauses must match whitelisted patterns only
     for (const p of policies) {
-      const usingViolations = findForbiddenPatterns(p.using)
-      const checkViolations = findForbiddenPatterns(p.withCheck)
-      const allViolations = [...new Set([...usingViolations, ...checkViolations])]
-
-      if (allViolations.length > 0) {
-        results.passed = false
-        results.findings.push({
-          file: p.file,
-          line: 1,
-          type: 'rls-bypass-pattern',
-          severity: 'critical',
-          message: `Policy "${p.name}" on table "${tableName}" contains forbidden bypass pattern(s): ${allViolations.join(', ')}. RLS policies must ONLY use auth.uid(), auth_admin_organizations(), or parent-table subqueries. Service role bypasses RLS automatically — adding it to policies defeats the purpose.`,
-          fix: `Remove the bypass clause. Valid patterns: USING (organization_id IN (SELECT auth_admin_organizations())) or USING (user_id = auth.uid()).`
-        })
-        results.summary.critical++
-        results.summary.total++
+      for (const [clauseType, clause] of [['USING', p.using], ['WITH CHECK', p.withCheck]]) {
+        if (!clause) continue
+        const violation = validateRlsClause(clause)
+        if (violation) {
+          results.passed = false
+          results.findings.push({
+            file: p.file,
+            line: 1,
+            type: 'rls-invalid-clause',
+            severity: 'critical',
+            message: `Policy "${p.name}" on table "${tableName}" has invalid ${clauseType} clause: ${violation}`,
+            fix: `Only whitelisted patterns are allowed. Valid: auth_admin_organizations(), auth.uid(), org/user column checks, parent-table subqueries, boolean column filters. See ALLOWED_RLS_ATOMS in config-rls-alignment.js.`
+          })
+          results.summary.critical++
+          results.summary.total++
+        }
       }
     }
 

package/package.json

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