@soulbatical/tetra-dev-toolkit 1.8.9 → 1.9.1

package/README.md

@@ -18,7 +18,7 @@ npx tetra-setup
 
 This creates:
 - `.husky/pre-commit` — quick security checks before every commit
-- `.husky/pre-push` — hygiene check before every push (blocks clutter)
+- `.husky/pre-push` — hygiene + RLS security gate before every push
 - `.github/workflows/quality.yml` — full audit on PR/push to main
 - `.tetra-quality.json` — project config (override defaults)
 
@@ -32,6 +32,106 @@ npx tetra-setup config   # Config file only
 
 Re-running `tetra-setup hooks` on an existing project adds missing hooks without overwriting existing ones.
 
+---
+
+## 3-Layer Security Model
+
+Every Tetra project is protected by three layers. All three must pass before code reaches production. No fallbacks. No soft warnings. Hard errors only.
+
+```
+LAYER 1: PRE-COMMIT (tetra-audit quick)
+  Blocks: hardcoded secrets, service key exposure, direct createClient imports
+
+LAYER 2: PRE-PUSH (tetra-check-rls + tetra-audit hygiene)
+  Blocks: RLS violations on live DB, repo clutter, missing FORCE RLS
+
+LAYER 3: BUILD (Railway/deploy — tetra-check-rls --errors-only)
+  Blocks: anything that bypassed --no-verify. Last line of defense.
+```
+
+### Layer 1: Pre-commit
+
+Installed by `tetra-setup hooks`. Runs `tetra-audit quick` which executes critical security checks:
+
+| Check | What it catches |
+|-------|-----------------|
+| Hardcoded Secrets | API keys, tokens, JWTs in source code |
+| Service Key Exposure | Supabase service role keys in frontend code |
+| Direct Supabase Client | `createClient()` imports outside core db wrappers |
+
+If any check fails, the commit is **blocked**. No `--force`, no workaround.
+
+### Layer 2: Pre-push (RLS Security Gate)
+
+Installed by `tetra-setup hooks`. Runs before every `git push`. Two checks:
+
+1. **Repo hygiene** — `tetra-audit hygiene` blocks clutter
+2. **RLS Security Gate** — `tetra-check-rls --errors-only` against the live Supabase database
+
+The RLS gate auto-detects your Doppler project from `doppler.yaml` and runs 23 checks across 6 categories:
+
+| Category | Checks | What it catches |
+|----------|--------|-----------------|
+| Foundation | 3 | Tables without RLS, missing FORCE RLS, RLS without policies |
+| Policy Quality | 5 | Public role mutations, always-true policies, missing WITH CHECK |
+| Auth Functions | 4 | Missing auth functions, wrong SECURITY DEFINER, bad search_path |
+| Bypass Routes | 5 | SECURITY DEFINER data functions, anon grants, views bypassing RLS |
+| Data Exposure | 1 | Realtime enabled on sensitive tables |
+| Migration State | 4 | Non-Tetra auth patterns, missing org columns |
+
+If the RLS gate fails, the push is **blocked**. No `--no-verify` escape — Layer 3 catches that.
+
+### Layer 3: Build-time check
+
+Add to your Railway/deploy build command:
+
+```bash
+# Railway build command
+doppler run -- npx tetra-check-rls --errors-only && npm run build
+```
+
+This catches developers who bypass git hooks with `--no-verify`. If RLS is broken, the build fails, the deploy never happens.
+
+---
+
+## Supabase Client Architecture
+
+Every Tetra project MUST use the 5 db helpers. Direct `createClient` imports are **blocked** by the `direct-supabase-client` check.
+
+### The 5 DB Helpers
+
+| Helper | Key Used | RLS | When to Use |
+|--------|----------|-----|-------------|
+| `adminDB(req)` | Anon + user JWT | Enforced | Admin panel queries (org-scoped) |
+| `userDB(req)` | Anon + user JWT | Enforced | User's own data |
+| `publicDB()` | Anon key | Enforced | Public/anonymous access |
+| `superadminDB(req)` | Service Role | Bypassed | Cross-org operations (superadmin only, audit logged) |
+| `systemDB(context)` | Service Role | Bypassed | Webhooks, crons, system ops (whitelisted, audit logged) |
+
+### Why this matters
+
+```
+createClient(url, SERVICE_ROLE_KEY)  →  Bypasses ALL RLS. No audit trail. No access control.
+adminDB(req)                         →  Uses user's JWT. RLS enforces org boundaries. Audit logged.
+```
+
+A single `createClient` call with the service role key can leak data across all organizations. The db helpers enforce the security boundary at the application layer.
+
+### Allowed exceptions
+
+These files MAY import `createClient` directly because they ARE the wrappers:
+
+- `core/systemDb.ts`, `core/publicDb.ts`, `core/adminDb.ts`, `core/userDb.ts`, `core/superadminDb.ts`
+- `core/Application.ts` (bootstrap)
+- `features/database/services/SupabaseUserClient.ts`
+- `auth/controllers/AuthController.ts` (needs `auth.admin` API)
+- `backend-mcp/src/supabase-client.ts`, `org-scoped-client.ts`, `api-key-service.ts`, `http-server.ts`
+- `scripts/` (not production code)
+
+Everything else gets a **hard error** at commit time.
+
+---
+
 ## Usage
 
 ```bash
@@ -47,18 +147,43 @@ npx tetra-audit --json       # JSON output
 npx tetra-audit --verbose    # Detailed output with fix suggestions
 ```
 
-Exit codes: `0` = passed, `1` = failed, `2` = error.
+Exit codes: `0` = passed, `1` = failed, `2` = error. No middle ground.
+
+## RLS Security Gate (standalone)
+
+```bash
+npx tetra-check-rls                              # Auto-detect from doppler.yaml
+npx tetra-check-rls --url <url> --key <key>      # Explicit credentials
+npx tetra-check-rls --errors-only                # CI/build mode
+npx tetra-check-rls --json                       # JSON output for automation
+npx tetra-check-rls --fix                        # Generate hardening migration SQL
+npx tetra-check-rls --check-exec-sql             # Verify exec_sql function is secure
+```
+
+### Programmatic usage
+
+```typescript
+import { runRLSCheck } from '@soulbatical/tetra-core';
+
+const report = await runRLSCheck(supabaseServiceClient);
+if (!report.passed) {
+  throw new Error(report.summary); // Hard error. No soft fail.
+}
+```
+
+---
 
 ## Check Suites
 
-### Security (5 checks)
+### Security (6 checks)
 
 | Check | Severity | What it catches |
 |-------|----------|-----------------|
 | Hardcoded Secrets | critical | API keys, tokens, JWTs in source code |
 | Service Key Exposure | critical | Supabase service role keys in frontend |
-| Deprecated Supabase Admin | high | Legacy `createClient(serviceKey)` patterns |
-| SystemDB Whitelist | high | Unauthorized system database access |
+| Deprecated Supabase Admin | high | Legacy `supabaseAdmin` patterns |
+| Direct Supabase Client | critical | Direct `createClient` imports outside core wrappers |
+| SystemDB Whitelist | critical | Unauthorized service role key usage in authenticated routes |
 | Gitignore Validation | high | Missing .gitignore entries, tracked .env files |
 
 ### Stability (3 checks)
@@ -66,31 +191,38 @@ Exit codes: `0` = passed, `1` = failed, `2` = error.
 | Check | Severity | What it catches |
 |-------|----------|-----------------|
 | Husky Hooks | medium | Missing pre-commit/pre-push hooks |
-| CI Pipeline | medium | Missing or incomplete GitHub Actions config |
+| CI Pipeline | medium | Missing or incomplete CI config |
 | NPM Audit | high | Known vulnerabilities in dependencies |
 
-### Code Quality (1 check)
+### Code Quality (4 checks)
 
 | Check | Severity | What it catches |
 |-------|----------|-----------------|
-| API Response Format | medium | Non-standard `{ success, data }` response format |
+| API Response Format | medium | Non-standard response format |
+| File Size | medium | Files exceeding line limits |
+| Naming Conventions | medium | Inconsistent file/dir naming |
+| Route Separation | high | Business logic in route files |
 
-### Supabase (2 checks, auto-detected)
+### Supabase (3 checks, auto-detected)
 
 | Check | Severity | What it catches |
 |-------|----------|-----------------|
 | RLS Policy Audit | critical | Tables without Row Level Security |
 | RPC Param Mismatch | critical | TypeScript `.rpc()` calls with wrong parameter names vs SQL |
+| RPC Generator Origin | high | RPC functions not generated by Tetra SQL Generator |
 
-### Hygiene (1 check)
+### Hygiene (2 checks)
 
 | Check | Severity | What it catches |
 |-------|----------|-----------------|
-| File Organization | high | Stray .md, .sh, clutter in code dirs, root mess, nested docs/ |
+| File Organization | high | Stray .md, .sh, clutter in code dirs |
+| Stella Compliance | medium | Missing Stella integration |
+
+---
 
 ## Health Checks
 
-Separate from audit suites, health checks provide a scored assessment (0-N points) used by the Ralph Manager dashboard:
+Scored assessment (0-N points) used by the Ralph Manager dashboard:
 
 | Check | Max | What it measures |
 |-------|-----|------------------|
@@ -111,6 +243,8 @@ Separate from audit suites, health checks provide a scored assessment (0-N point
 | Plugins | 2pt | Claude Code plugin config |
 | VinciFox Widget | 1pt | Widget installation |
 
+---
+
 ## Auto-fix: Cleanup Script
 
 For hygiene issues, an auto-fix script is included:
@@ -123,13 +257,7 @@ bash node_modules/@soulbatical/tetra-dev-toolkit/bin/cleanup-repos.sh
 bash node_modules/@soulbatical/tetra-dev-toolkit/bin/cleanup-repos.sh --execute
 ```
 
-What it does:
-- `.md` files in code dirs -> `docs/_moved/`
-- `.sh` scripts in code dirs -> `scripts/_moved/`
-- Root clutter (`.txt`, `.png`, `.csv`) -> `docs/_cleanup/`
-- Code dir clutter -> `docs/_cleanup/{dir}/`
-- `.env` secrets in code dirs -> deleted
-- `tmp/`, `logs/`, `data/` dirs -> added to `.gitignore`
+---
 
 ## Configuration
 
@@ -158,20 +286,71 @@ Override defaults in `.tetra-quality.json` or `"tetra-quality"` key in `package.
 }
 ```
 
+---
+
 ## CLI Tools
 
 | Command | Description |
 |---------|-------------|
 | `tetra-audit` | Run quality/security/hygiene checks |
 | `tetra-setup` | Install hooks, CI, and config |
+| `tetra-check-rls` | RLS security gate against live Supabase |
+| `tetra-init` | Initialize project config files |
 | `tetra-dev-token` | Generate development tokens |
 
+---
+
+## New Project Checklist
+
+After `npm install` in a new Tetra project:
+
+```bash
+# 1. Install hooks (creates pre-commit + pre-push)
+npx tetra-setup hooks
+
+# 2. Verify hooks are active
+cat .husky/pre-commit   # Should contain tetra-audit quick
+cat .husky/pre-push     # Should contain tetra-check-rls
+
+# 3. Run full audit
+npx tetra-audit
+
+# 4. Run RLS gate manually once
+doppler run -- npx tetra-check-rls
+
+# 5. Add to Railway build command
+# doppler run -- npx tetra-check-rls --errors-only && npm run build
+```
+
+If any step fails, fix it before writing code. No exceptions.
+
+---
+
 ## Changelog
 
+### 1.9.0
+
+**New: Direct Supabase Client check (CRITICAL)**
+- Added `direct-supabase-client` check in security suite
+- Blocks any `createClient` import from `@supabase/supabase-js` outside core db wrappers
+- Hard error at commit time — no fallback, no override
+- Type-only imports (`import type { SupabaseClient }`) are allowed
+- Allowed files whitelist: core wrappers, auth controller, MCP server internals, scripts
+
+**New: 3-Layer Security Model documentation**
+- Layer 1: Pre-commit (tetra-audit quick)
+- Layer 2: Pre-push (tetra-check-rls + hygiene)
+- Layer 3: Build-time (tetra-check-rls --errors-only in Railway)
+- Complete Supabase Client Architecture docs with the 5 db helpers
+
+**Improved: prepublishOnly hooks**
+- tetra-core: `npm run build && npm run typecheck` before publish
+- tetra-dev-toolkit: `npm test` before publish
+
 ### 1.3.0 (2025-02-21)
 
 **New: Hygiene suite**
-- Added `tetra-audit hygiene` — detects stray docs, scripts, clutter in code dirs, root mess
+- Added `tetra-audit hygiene` — detects stray docs, scripts, clutter in code dirs
 - Added `cleanup-repos.sh` auto-fix script in `bin/`
 - `tetra-setup hooks` now creates pre-push hook with hygiene gate
 - Re-running `tetra-setup hooks` on existing repos adds hygiene check without overwriting
@@ -181,12 +360,6 @@ Override defaults in `.tetra-quality.json` or `"tetra-quality"` key in `package.
 - Statically compares `.rpc()` calls in TypeScript with SQL function parameter names
 - Catches PGRST202 errors before they hit production
 
-**Improved: File Organization health check**
-- Extended from 5pt to 6pt — added root clutter detection
-- Root clutter: `.txt`, `.png`, `.csv`, `.pdf`, `.py` files and `tmp/`, `logs/`, `data/` dirs
-- Gitignored dirs no longer counted as clutter
-- `CLAUDE.md` allowed anywhere (not just root)
-
 ### 1.2.0
 
 - Initial public version

package/bin/tetra-setup.js

@@ -122,35 +122,42 @@ async function setupHooks(options) {
     execSync('npx husky init', { stdio: 'inherit' })
   }
 
-  // Create pre-commit hook
+  // Create or extend pre-commit hook with tetra-audit quick
   const preCommitPath = join(huskyDir, 'pre-commit')
-  if (!existsSync(preCommitPath) || options.force) {
-    const preCommitContent = `#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-echo "🔍 Running Tetra quality checks..."
-
-# Run quick security checks (fast, blocks commit on critical issues)
+  const tetraAuditBlock = `
+# Tetra quick security checks (hardcoded secrets, direct createClient, service key exposure)
+echo "🔍 Running Tetra security checks..."
 npx tetra-audit quick
 if [ $? -ne 0 ]; then
   echo ""
   echo "❌ Security issues found! Fix before committing."
-  echo "   Run 'tetra-audit' for detailed report."
+  echo "   Run 'npx tetra-audit security --verbose' for details."
   exit 1
 fi
-
-# Run lint-staged if configured
-if [ -f "package.json" ] && grep -q "lint-staged" package.json; then
-  npx lint-staged
-fi
-
-echo "✅ Pre-commit checks passed"
 `
+
+  if (!existsSync(preCommitPath)) {
+    // No pre-commit hook — create one
+    const preCommitContent = `#!/bin/sh\n${tetraAuditBlock}\necho "✅ Pre-commit checks passed"\n`
+    writeFileSync(preCommitPath, preCommitContent)
+    execSync(`chmod +x ${preCommitPath}`)
+    console.log('   ✅ Created .husky/pre-commit with tetra-audit quick')
+  } else if (options.force) {
+    // Force overwrite
+    const preCommitContent = `#!/bin/sh\n${tetraAuditBlock}\necho "✅ Pre-commit checks passed"\n`
     writeFileSync(preCommitPath, preCommitContent)
     execSync(`chmod +x ${preCommitPath}`)
-    console.log('   ✅ Created .husky/pre-commit')
+    console.log('   ✅ Overwrote .husky/pre-commit with tetra-audit quick')
   } else {
-    console.log('   ⏭️  .husky/pre-commit already exists (use --force to overwrite)')
+    // Pre-commit exists — add tetra-audit quick if missing
+    const existing = readFileSync(preCommitPath, 'utf-8')
+    if (!existing.includes('tetra-audit')) {
+      const updated = existing.trimEnd() + '\n' + tetraAuditBlock
+      writeFileSync(preCommitPath, updated)
+      console.log('   ✅ Added tetra-audit quick to existing .husky/pre-commit')
+    } else {
+      console.log('   ⏭️  .husky/pre-commit already has tetra-audit')
+    }
   }
 
   // Create or extend pre-push hook with hygiene check + RLS security gate

package/lib/checks/hygiene/stella-compliance.js

@@ -0,0 +1,208 @@
+/**
+ * Hygiene Check: Stella Compliance
+ *
+ * Ensures MCP servers use shared Stella tools instead of duplicating code.
+ * Checks:
+ * - No local telegram tool implementations (must come from @soulbatical/stella)
+ * - No local detectWorkspaceRef copies (must use Stella's export)
+ * - No local gatewaySend for telegram (must use Stella's telegram module)
+ * - Stella version consistency across consumers
+ * - workspace_ref is always passed in telegram gateway calls
+ *
+ * Severity: high — duplicate code leads to bugs that only get fixed in one place
+ */
+
+import { readFile, access } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { glob } from 'glob'
+
+export const meta = {
+  id: 'stella-compliance',
+  name: 'Stella Compliance',
+  category: 'hygiene',
+  severity: 'high',
+  description: 'Checks that MCP servers use shared Stella tools and do not duplicate code'
+}
+
+// Patterns that indicate duplicate code — should only exist in Stella itself
+const DUPLICATE_PATTERNS = [
+  {
+    pattern: /const QUESTIONS_DIR\s*=\s*join\(tmpdir\(\)/,
+    label: 'Local QUESTIONS_DIR (telegram question store)',
+    allowedIn: ['stella/src/telegram.ts']
+  },
+  {
+    pattern: /function detectWorkspaceRef\(\)/,
+    label: 'Local detectWorkspaceRef implementation',
+    allowedIn: ['stella/src/permissions.ts']
+  },
+  {
+    pattern: /async function gatewaySend\(/,
+    label: 'Local gatewaySend helper',
+    allowedIn: ['stella/src/telegram.ts']
+  },
+  {
+    pattern: /\/api\/internal\/telegram\//,
+    label: 'Direct telegram gateway URL',
+    allowedIn: ['stella/src/telegram.ts', 'backend/src/', 'ralph-manager/backend/src/']
+  },
+  {
+    pattern: /function splitMessage\(text:\s*string/,
+    label: 'Local splitMessage helper (for telegram)',
+    allowedIn: ['stella/src/telegram.ts', 'tools/helpers.ts']
+  },
+  {
+    pattern: /function playMacAlert\(\)/,
+    label: 'Local playMacAlert helper',
+    allowedIn: ['stella/src/telegram.ts']
+  }
+]
+
+// Files that should be a thin re-export from Stella, not a full implementation
+const EXPECTED_REEXPORTS = [
+  {
+    glob: '**/backend-mcp/src/tools/telegram.ts',
+    mustContain: /@soulbatical\/stella/,
+    mustNotContain: /gatewaySend|QUESTIONS_DIR|QuestionState/,
+    label: 'telegram.ts should re-export from @soulbatical/stella'
+  }
+]
+
+// Stella version consistency check
+async function getInstalledStellaVersion(projectRoot) {
+  try {
+    const pkgPath = join(projectRoot, 'node_modules', '@soulbatical', 'stella', 'package.json')
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+    return pkg.version
+  } catch {
+    // Try in backend-mcp subdir
+    try {
+      const pkgPath = join(projectRoot, 'backend-mcp', 'node_modules', '@soulbatical', 'stella', 'package.json')
+      const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+      return pkg.version
+    } catch {
+      return null
+    }
+  }
+}
+
+async function getLatestStellaVersion() {
+  try {
+    const pkgPath = join(process.env.HOME, 'projecten', 'stella', 'package.json')
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+    return pkg.version
+  } catch {
+    return null
+  }
+}
+
+export async function run(config, projectRoot) {
+  const result = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {}
+  }
+
+  const projectName = relative(join(process.env.HOME, 'projecten'), projectRoot)
+
+  // Skip Stella itself
+  if (projectName === 'stella') {
+    result.details.skipped = 'Stella project — checks not applicable'
+    return result
+  }
+
+  // 1. Check for duplicate patterns in MCP tool files
+  const tsFiles = await glob('**/src/**/*.ts', {
+    cwd: projectRoot,
+    ignore: ['**/node_modules/**', '**/dist/**', '**/bot/**']
+  })
+
+  for (const file of tsFiles) {
+    let content
+    try {
+      content = await readFile(join(projectRoot, file), 'utf-8')
+    } catch {
+      continue
+    }
+
+    for (const { pattern, label, allowedIn } of DUPLICATE_PATTERNS) {
+      if (pattern.test(content)) {
+        const isAllowed = allowedIn.some(a => file.includes(a) || join(projectName, file).includes(a))
+        if (!isAllowed) {
+          result.findings.push({
+            type: 'Duplicate Stella code',
+            severity: 'high',
+            message: `${label} found in ${file} — should use @soulbatical/stella export instead`,
+            files: [file]
+          })
+          result.summary.high++
+          result.summary.total++
+        }
+      }
+    }
+  }
+
+  // 2. Check that telegram.ts files are thin re-exports
+  for (const { glob: pattern, mustContain, mustNotContain, label } of EXPECTED_REEXPORTS) {
+    const matches = await glob(pattern, {
+      cwd: projectRoot,
+      ignore: ['**/node_modules/**', '**/dist/**']
+    })
+
+    for (const file of matches) {
+      let content
+      try {
+        content = await readFile(join(projectRoot, file), 'utf-8')
+      } catch {
+        continue
+      }
+
+      if (!mustContain.test(content)) {
+        result.findings.push({
+          type: 'Missing Stella import',
+          severity: 'high',
+          message: `${file}: ${label}`,
+          files: [file]
+        })
+        result.summary.high++
+        result.summary.total++
+      }
+
+      if (mustNotContain.test(content)) {
+        result.findings.push({
+          type: 'Local implementation instead of Stella',
+          severity: 'high',
+          message: `${file} contains local implementation code — should be a thin re-export from @soulbatical/stella`,
+          files: [file]
+        })
+        result.summary.high++
+        result.summary.total++
+      }
+    }
+  }
+
+  // 3. Check Stella version consistency
+  const latestVersion = await getLatestStellaVersion()
+  const installedVersion = await getInstalledStellaVersion(projectRoot)
+
+  if (latestVersion && installedVersion) {
+    result.details.stellaVersion = { installed: installedVersion, latest: latestVersion }
+
+    if (installedVersion !== latestVersion) {
+      result.findings.push({
+        type: 'Outdated Stella version',
+        severity: 'medium',
+        message: `Installed @soulbatical/stella@${installedVersion}, latest is ${latestVersion} — run npm update @soulbatical/stella`,
+        files: ['package.json']
+      })
+      result.summary.medium++
+      result.summary.total++
+    }
+  }
+
+  // Fail if any high+ findings
+  result.passed = result.summary.critical === 0 && result.summary.high === 0
+
+  return result
+}

package/lib/checks/security/direct-supabase-client.js

@@ -0,0 +1,175 @@
+/**
+ * Direct Supabase Client Detection — HARD BLOCK
+ *
+ * Detects files that import createClient from @supabase/supabase-js directly.
+ * This bypasses ALL Tetra security layers (RLS enforcement, audit logging, access control).
+ *
+ * ALLOWED locations (these ARE the wrappers):
+ * - core/systemDb.ts
+ * - core/publicDb.ts
+ * - core/adminDb.ts
+ * - core/userDb.ts
+ * - core/superadminDb.ts
+ * - core/Application.ts (bootstrap only)
+ * - features/database/services/SupabaseUserClient.ts
+ * - auth/controllers/AuthController.ts (needs auth.admin API)
+ *
+ * EVERYTHING ELSE is a violation. No fallbacks. No exceptions.
+ *
+ * The correct pattern:
+ * - adminDB(req)       → org-scoped admin queries (RLS enforced)
+ * - userDB(req)        → user's own data (RLS enforced)
+ * - publicDB()         → anonymous/public data (RLS enforced)
+ * - superadminDB(req)  → cross-org operations (audit logged, superadmin only)
+ * - systemDB(context)  → webhooks/crons/system ops (audit logged, whitelisted)
+ */
+
+import { glob } from 'glob'
+import { readFileSync, existsSync } from 'fs'
+
+export const meta = {
+  id: 'direct-supabase-client',
+  name: 'Direct Supabase Client Import',
+  category: 'security',
+  severity: 'critical',
+  description: 'Blocks direct createClient imports from @supabase/supabase-js — all access must go through Tetra db helpers'
+}
+
+/**
+ * Files that ARE the Supabase wrappers — allowed to import createClient.
+ * Everything else is a hard error.
+ */
+const ALLOWED_FILES = [
+  // Core db wrappers
+  /core\/systemDb\.ts$/,
+  /core\/publicDb\.ts$/,
+  /core\/adminDb\.ts$/,
+  /core\/userDb\.ts$/,
+  /core\/superadminDb\.ts$/,
+  /core\/Application\.ts$/,
+
+  // The user client wrapper itself
+  /SupabaseUserClient\.ts$/,
+
+  // Auth controller needs auth.admin API (requires service role)
+  /auth\/controllers\/AuthController\.ts$/,
+
+  // MCP server has its own client management (org-scoped-client.ts, supabase-client.ts, api-key-service.ts)
+  /backend-mcp\/src\/supabase-client\.ts$/,
+  /backend-mcp\/src\/org-scoped-client\.ts$/,
+  /backend-mcp\/src\/auth\/api-key-service\.ts$/,
+  /backend-mcp\/src\/http-server\.ts$/,
+
+  // Domain middleware (sets RLS session vars — needs direct client)
+  /middleware\/domainOrganizationMiddleware\.ts$/,
+
+  // Scripts (not production code)
+  /scripts\//,
+]
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // Get all TypeScript files
+  const files = await glob('**/*.ts', {
+    cwd: projectRoot,
+    ignore: [
+      ...config.ignore,
+      '**/*.test.ts',
+      '**/*.spec.ts',
+      '**/*.d.ts',
+    ]
+  })
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(`${projectRoot}/${file}`, 'utf-8')
+      const lines = content.split('\n')
+
+      // Pattern 1: import { createClient } from '@supabase/supabase-js'
+      // Pattern 2: import { createClient as X } from '@supabase/supabase-js'
+      // We ALLOW: import { SupabaseClient } (type-only imports are fine)
+      // We ALLOW: import type { ... } from '@supabase/supabase-js'
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]
+
+        // Skip type-only imports
+        if (/import\s+type\s/.test(line)) continue
+
+        // Check for createClient import from supabase
+        if (/import\s*\{[^}]*createClient[^}]*\}\s*from\s*['"]@supabase\/supabase-js['"]/.test(line)) {
+          // Check if this file is in the allowed list
+          const isAllowed = ALLOWED_FILES.some(pattern => pattern.test(file))
+
+          if (!isAllowed) {
+            results.passed = false
+            results.findings.push({
+              file,
+              line: i + 1,
+              type: 'direct-createClient-import',
+              severity: 'critical',
+              message: `BLOCKED: Direct createClient import from @supabase/supabase-js. Use Tetra db helpers instead.`,
+              snippet: line.trim().substring(0, 120),
+              fix: getFixSuggestion(file, content)
+            })
+            results.summary.critical++
+            results.summary.total++
+          }
+        }
+
+        // Also catch: const supabase = createClient(url, key) without the import
+        // (in case someone imports it via re-export or variable)
+        if (/createClient\s*\(\s*(?:process\.env|supabase|SUPABASE)/.test(line)) {
+          const isAllowed = ALLOWED_FILES.some(pattern => pattern.test(file))
+          const isImportLine = /import/.test(line)
+
+          if (!isAllowed && !isImportLine) {
+            results.passed = false
+            results.findings.push({
+              file,
+              line: i + 1,
+              type: 'direct-createClient-call',
+              severity: 'critical',
+              message: `BLOCKED: Direct createClient() call with env vars. Use Tetra db helpers instead.`,
+              snippet: line.trim().substring(0, 120),
+              fix: getFixSuggestion(file, content)
+            })
+            results.summary.critical++
+            results.summary.total++
+          }
+        }
+      }
+    } catch (e) {
+      // Skip unreadable files
+    }
+  }
+
+  return results
+}
+
+/**
+ * Suggest the correct Tetra db helper based on the file's context.
+ */
+function getFixSuggestion(file, content) {
+  if (/Admin.*Controller/.test(file) || /adminRoutes/.test(file)) {
+    return `Use: import { adminDB } from '../../core/adminDb';\nconst supabase = await adminDB(req);`
+  }
+  if (/User.*Controller/.test(file) || /userRoutes/.test(file)) {
+    return `Use: import { userDB } from '../../core/userDb';\nconst supabase = await userDB(req);`
+  }
+  if (/Superadmin/.test(file)) {
+    return `Use: import { superadminDB } from '../../core/superadminDb';\nconst supabase = await superadminDB(req);`
+  }
+  if (/cron/i.test(file) || /webhook/i.test(file)) {
+    return `Use: import { systemDB } from '../../core/systemDb';\nconst supabase = systemDB('your-context');`
+  }
+  if (content.includes('AuthenticatedRequest') || content.includes('req.userToken')) {
+    return `User context available — use adminDB(req) or userDB(req) instead of createClient()`
+  }
+  return `Use one of: adminDB(req), userDB(req), publicDB(), superadminDB(req), or systemDB(context)`
+}

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

@@ -1,21 +1,89 @@
 /**
- * Check that all systemDB() calls use whitelisted contexts
+ * systemDB Usage Audit — Prevent unnecessary Service Role Key usage
  *
- * This prevents accidental RLS bypass by requiring explicit context strings
- * that are defined in the systemDb.ts whitelist.
+ * The Service Role Key bypasses ALL Row Level Security. This check ensures:
+ * 1. systemDB() is NEVER used in authenticated routes (Admin/User controllers & routes)
+ * 2. systemDB() is ONLY allowed in legitimate no-user-context scenarios
+ * 3. Whitelist size is capped — large whitelists indicate architectural problems
+ *
+ * ALLOWED locations (no user context available):
+ * - Cron services (files matching *Cron*.ts, *cron*.ts)
+ * - Webhook controllers (files matching System*Controller.ts, *webhook*.ts)
+ * - OAuth callback controllers (files matching *OAuth*Controller.ts)
+ * - Public routes (files in routes/publicRoutes.ts)
+ * - Core auth services (auth-guards, session services)
+ *
+ * FORBIDDEN locations (user context IS available via req.userToken):
+ * - Admin controllers (Admin*Controller.ts)
+ * - Admin routes (routes/adminRoutes.ts)
+ * - User controllers (User*Controller.ts)
+ * - Any file that imports AuthenticatedRequest
  */
 
 import { glob } from 'glob'
 import { readFileSync, existsSync } from 'fs'
+import { basename, dirname } from 'path'
 
 export const meta = {
   id: 'systemdb-whitelist',
-  name: 'systemDB Context Whitelist',
+  name: 'systemDB Service Role Key Audit',
   category: 'security',
-  severity: 'high',
-  description: 'Ensures all systemDB() calls use whitelisted context strings'
+  severity: 'critical',
+  description: 'Prevents unnecessary Service Role Key usage — systemDB() must not be used where user context is available'
 }
 
+/**
+ * Patterns for files where systemDB is ALLOWED (no user context)
+ */
+const ALLOWED_FILE_PATTERNS = [
+  // Cron jobs — no user context, runs on timer
+  /Cron/i,
+  // Webhook controllers from external systems — no auth header
+  /System.*Controller/,
+  // OAuth callback controllers — browser redirect, no JWT
+  /OAuth.*Controller/,
+  /OAuthController/,
+  // Public routes — unauthenticated endpoints
+  /publicRoutes/,
+  // Core infrastructure
+  /systemDb\.ts$/,
+  /superadminDb\.ts$/,
+  /webhookDb\.ts$/,
+  /adminDb\.ts$/,
+  /userDb\.ts$/,
+  // Auth infrastructure (needs SRK for auth.admin calls)
+  /auth-guards/,
+  /authService/,
+  /UserSessionService/,
+  // Platform services that run token refreshes in background
+  /TokenRefreshService/,
+  /PlatformSyncService/,
+  /BasePlatformService/,
+  // Base cron service
+  /BaseCronService/,
+  // Internal service-to-service routes (API key auth, no user JWT)
+  /internalRoutes/,
+]
+
+/**
+ * Patterns for files where systemDB is FORBIDDEN (user context available)
+ */
+const FORBIDDEN_FILE_PATTERNS = [
+  // Admin controllers — always have req.userToken from requireAuth middleware
+  { pattern: /Admin.*Controller\.ts$/, reason: 'Admin controllers have req.userToken — use SupabaseUserClient.createForUser() or adminDB(req) instead' },
+  // Admin routes — always behind requireAuth
+  { pattern: /adminRoutes\.ts$/, reason: 'Admin routes are behind requireAuth — use SupabaseUserClient.createForUser(req.userToken!) instead' },
+  // User controllers — always have user context
+  { pattern: /User.*Controller\.ts$/, reason: 'User controllers have req.userToken — use SupabaseUserClient.createForUser() instead' },
+  // User routes
+  { pattern: /userRoutes\.ts$/, reason: 'User routes are behind requireAuth — use SupabaseUserClient.createForUser(req.userToken!) instead' },
+]
+
+/**
+ * Maximum allowed whitelist size — anything above indicates architectural problems
+ */
+const MAX_WHITELIST_SIZE = 35
+
 export async function run(config, projectRoot) {
   const results = {
     passed: true,
@@ -23,7 +91,8 @@ export async function run(config, projectRoot) {
     summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
   }
 
-  // Find systemDb.ts to extract whitelist
+  // ─── Check 1: Whitelist size cap ─────────────────────────────
+
   const systemDbPaths = [
     `${projectRoot}/backend/src/core/systemDb.ts`,
     `${projectRoot}/src/core/systemDb.ts`
@@ -43,42 +112,44 @@ export async function run(config, projectRoot) {
     return results
   }
 
-  // Extract whitelist from systemDb.ts
   const systemDbContent = readFileSync(systemDbPath, 'utf-8')
-  const whitelistMatch = systemDbContent.match(/new Set\s*\(\s*\[([\s\S]*?)\]\s*\)/m)
+  const whitelistMatch = systemDbContent.match(/new Set\s*(?:<[^>]+>)?\s*\(\s*\[([\s\S]*?)\]\s*\)/m)
 
-  if (!whitelistMatch) {
+  let whitelist = new Set()
+  if (whitelistMatch) {
+    const entries = whitelistMatch[1]
+      .split('\n')
+      .map(line => {
+        const m = line.match(/['"]([^'"]+)['"]/)
+        return m ? m[1] : null
+      })
+      .filter(Boolean)
+    whitelist = new Set(entries)
+  }
+
+  if (whitelist.size > MAX_WHITELIST_SIZE) {
     results.passed = false
     results.findings.push({
-      file: systemDbPath,
+      file: systemDbPath.replace(projectRoot + '/', ''),
       line: 1,
-      type: 'missing-whitelist',
+      type: 'whitelist-too-large',
       severity: 'critical',
-      message: 'systemDb.ts does not contain a whitelist Set'
+      message: `systemDB whitelist has ${whitelist.size} entries (max: ${MAX_WHITELIST_SIZE}). This indicates systemDB is being used where SupabaseUserClient should be used instead. Refactor services to accept a supabase client parameter instead of calling systemDB() directly.`,
+      fix: `Refactor: services should receive a supabase client via dependency injection, not create their own via systemDB(). Only cron jobs, webhooks, and OAuth callbacks should use systemDB.`
     })
     results.summary.critical++
     results.summary.total++
-    return results
   }
 
-  // Parse whitelist entries
-  const whitelistStr = whitelistMatch[1]
-  const whitelist = new Set(
-    whitelistStr
-      .split('\n')
-      .map(line => {
-        const match = line.match(/['"]([^'"]+)['"]/)
-        return match ? match[1] : null
-      })
-      .filter(Boolean)
-  )
+  // ─── Check 2: systemDB in forbidden locations ───────────────
 
-  // Find all systemDB() calls in the codebase
   const files = await glob('**/*.ts', {
     cwd: projectRoot,
     ignore: [
       ...config.ignore,
-      '**/systemDb.ts', // Skip the definition file
+      '**/systemDb.ts',
+      '**/superadminDb.ts',
+      '**/webhookDb.ts',
       '**/*.test.ts',
       '**/*.spec.ts'
     ]
@@ -89,8 +160,9 @@ export async function run(config, projectRoot) {
       const content = readFileSync(`${projectRoot}/${file}`, 'utf-8')
       const lines = content.split('\n')
 
-      // Find systemDB('context') calls
-      const pattern = /systemDB\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+      // Find systemDB() calls
+      const pattern = /systemDB\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g
+      const fileName = basename(file)
 
       let match
       while ((match = pattern.exec(content)) !== null) {
@@ -100,26 +172,82 @@ export async function run(config, projectRoot) {
         let lineNumber = 1
         let pos = 0
         for (const line of lines) {
-          if (pos + line.length >= match.index) {
-            break
-          }
+          if (pos + line.length >= match.index) break
           pos += line.length + 1
           lineNumber++
         }
 
+        // Check if file is in a FORBIDDEN location
+        const forbidden = FORBIDDEN_FILE_PATTERNS.find(f => f.pattern.test(fileName))
+        if (forbidden) {
+          // Check if it's also in an allowed pattern (e.g., SystemActiveCampaignController is both System* and Controller)
+          const isAlsoAllowed = ALLOWED_FILE_PATTERNS.some(p => p.test(fileName))
+
+          if (!isAlsoAllowed) {
+            results.passed = false
+            results.findings.push({
+              file,
+              line: lineNumber,
+              type: 'systemdb-in-authenticated-route',
+              severity: 'critical',
+              message: `systemDB('${context}') used in ${fileName} — ${forbidden.reason}`,
+              snippet: lines[lineNumber - 1]?.trim().substring(0, 120),
+              fix: `Replace systemDB('${context}') with SupabaseUserClient.createForUser(req.userToken!) — RLS will handle authorization`
+            })
+            results.summary.critical++
+            results.summary.total++
+          }
+        }
+
+        // Check 3: Even in allowed files, flag calls that don't match whitelist
         if (!whitelist.has(context)) {
-          results.passed = false
+          // Dynamic contexts like platform-token-refresh-{name} are OK
+          const isDynamic = context.includes('${') ||
+            Array.from(whitelist).some(w => {
+              // Check if whitelist has a matching prefix pattern
+              const prefix = w.replace(/-[^-]+$/, '-')
+              return context.startsWith(prefix) && prefix.length > 5
+            })
+
+          if (!isDynamic) {
+            results.findings.push({
+              file,
+              line: lineNumber,
+              type: 'unknown-context',
+              severity: 'medium',
+              message: `systemDB context '${context}' is not in whitelist`,
+              snippet: lines[lineNumber - 1]?.trim().substring(0, 100),
+              fix: `If this is a legitimate system operation (cron/webhook/oauth callback), add '${context}' to the whitelist. Otherwise, refactor to use SupabaseUserClient.`
+            })
+            results.summary.medium++
+            results.summary.total++
+          }
+        }
+      }
+
+      // ─── Check 4: Files importing systemDB that shouldn't ────
+
+      if (content.includes("import") && content.includes("systemDB")) {
+        const hasAuthenticatedRequest = content.includes('AuthenticatedRequest') || content.includes('req.userToken') || content.includes('req.user!')
+        const isAllowed = ALLOWED_FILE_PATTERNS.some(p => p.test(file))
+        const isForbidden = FORBIDDEN_FILE_PATTERNS.some(f => f.pattern.test(fileName))
+
+        if (hasAuthenticatedRequest && !isAllowed) {
           results.findings.push({
             file,
-            line: lineNumber,
-            type: 'unknown-context',
+            line: lines.findIndex(l => l.includes('systemDB')) + 1,
+            type: 'systemdb-with-user-context',
             severity: 'high',
-            message: `systemDB context '${context}' is not in whitelist`,
-            snippet: lines[lineNumber - 1]?.trim().substring(0, 100),
-            fix: `Add '${context}' to ALLOWED_CONTEXTS in systemDb.ts`
+            message: `File imports systemDB but also uses AuthenticatedRequest/req.userToken — this means user context IS available. Use SupabaseUserClient instead.`,
+            fix: `Refactor: pass supabase client as parameter to services, created via SupabaseUserClient.createForUser(req.userToken!) in the route/controller`
           })
           results.summary.high++
           results.summary.total++
+
+          if (!isForbidden) {
+            // Don't double-fail if already caught by forbidden check
+            results.passed = false
+          }
         }
       }
     } catch (e) {
@@ -127,11 +255,13 @@ export async function run(config, projectRoot) {
     }
   }
 
-  // Add info about whitelist
+  // ─── Summary info ──────────────────────────────────────────
+
   results.info = {
-    whitelistPath: systemDbPath,
-    whitelistCount: whitelist.size,
-    contexts: Array.from(whitelist)
+    whitelistPath: systemDbPath?.replace(projectRoot + '/', ''),
+    whitelistSize: whitelist.size,
+    maxAllowed: MAX_WHITELIST_SIZE,
+    architecture: 'systemDB should ONLY be used in: cron jobs, external webhooks, OAuth callbacks. All authenticated routes must use SupabaseUserClient.createForUser(req.userToken!).'
   }
 
   return results

package/lib/runner.js

@@ -10,6 +10,7 @@ import { loadConfig, detectSupabase } from './config.js'
 import * as hardcodedSecrets from './checks/security/hardcoded-secrets.js'
 import * as serviceKeyExposure from './checks/security/service-key-exposure.js'
 import * as deprecatedSupabaseAdmin from './checks/security/deprecated-supabase-admin.js'
+import * as directSupabaseClient from './checks/security/direct-supabase-client.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'
@@ -23,6 +24,7 @@ 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'
 import * as fileOrganization from './checks/hygiene/file-organization.js'
+import * as stellaCompliance from './checks/hygiene/stella-compliance.js'
 
 // Register all checks
 const ALL_CHECKS = {
@@ -30,6 +32,7 @@ const ALL_CHECKS = {
     hardcodedSecrets,
     serviceKeyExposure,
     deprecatedSupabaseAdmin,
+    directSupabaseClient,
     systemdbWhitelist,
     gitignoreValidation
   ],
@@ -50,7 +53,8 @@ const ALL_CHECKS = {
     rpcGeneratorOrigin
   ],
   hygiene: [
-    fileOrganization
+    fileOrganization,
+    stellaCompliance
   ]
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulbatical/tetra-dev-toolkit",
-  "version": "1.8.9",
+  "version": "1.9.1",
   "publishConfig": {
     "access": "restricted"
   },
@@ -40,7 +40,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src/ lib/ bin/",
-    "build": "echo 'No build step needed'"
+    "build": "echo 'No build step needed'",
+    "prepublishOnly": "npm test"
   },
   "engines": {
     "node": ">=18.0.0"