@soulbatical/tetra-dev-toolkit 1.1.0

package/lib/checks/security/service-key-exposure.js

@@ -0,0 +1,107 @@
+/**
+ * Check for Supabase service role key exposure in frontend code
+ */
+
+import { glob } from 'glob'
+import { readFileSync } from 'fs'
+
+export const meta = {
+  id: 'service-key-exposure',
+  name: 'Service Role Key Exposure',
+  category: 'security',
+  severity: 'critical',
+  description: 'Detects Supabase service role key usage in frontend code (RLS bypass risk)'
+}
+
+const DANGEROUS_PATTERNS = [
+  {
+    name: 'SERVICE_ROLE_KEY in frontend',
+    pattern: /SUPABASE_SERVICE_ROLE_KEY|SERVICE_ROLE_KEY/g,
+    severity: 'critical'
+  },
+  {
+    name: 'createClient with service key',
+    pattern: /createClient\s*\([^)]*service[_-]?role/gi,
+    severity: 'critical'
+  },
+  {
+    name: 'supabaseAdmin in frontend',
+    pattern: /supabaseAdmin/g,
+    severity: 'high'
+  },
+  {
+    name: 'VITE_ service key',
+    pattern: /VITE_.*SERVICE.*KEY/g,
+    severity: 'critical'
+  },
+  {
+    name: 'NEXT_PUBLIC_ service key',
+    pattern: /NEXT_PUBLIC_.*SERVICE.*KEY/g,
+    severity: 'critical'
+  }
+]
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // Only check frontend directories
+  const frontendPaths = config.paths?.frontend || ['frontend/src', 'src']
+  const frontendGlobs = frontendPaths.map(p => `${p}/**/*.{ts,tsx,js,jsx}`)
+
+  for (const pattern of frontendGlobs) {
+    const files = await glob(pattern, {
+      cwd: projectRoot,
+      ignore: [...config.ignore, '**/node_modules/**', '**/backend/**', '**/server/**']
+    })
+
+    for (const file of files) {
+      // Skip if file is clearly backend
+      if (file.includes('/api/') || file.includes('/server/') || file.includes('middleware')) {
+        continue
+      }
+
+      try {
+        const content = readFileSync(`${projectRoot}/${file}`, 'utf-8')
+        const lines = content.split('\n')
+
+        for (const { name, pattern: regex, severity } of DANGEROUS_PATTERNS) {
+          regex.lastIndex = 0
+
+          let match
+          while ((match = regex.exec(content)) !== null) {
+            // Find line number
+            let lineNumber = 1
+            let pos = 0
+            for (const line of lines) {
+              if (pos + line.length >= match.index) {
+                break
+              }
+              pos += line.length + 1
+              lineNumber++
+            }
+
+            results.passed = false
+            results.findings.push({
+              file,
+              line: lineNumber,
+              type: name,
+              severity,
+              message: `${name} - service role key should NEVER be in frontend code`,
+              snippet: lines[lineNumber - 1]?.trim().substring(0, 80)
+            })
+            results.summary[severity]++
+            results.summary.total++
+          }
+        }
+      } catch (e) {
+        // Skip unreadable files
+      }
+    }
+  }
+
+  return results
+}

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

@@ -0,0 +1,138 @@
+/**
+ * Check that all systemDB() calls use whitelisted contexts
+ *
+ * This prevents accidental RLS bypass by requiring explicit context strings
+ * that are defined in the systemDb.ts whitelist.
+ */
+
+import { glob } from 'glob'
+import { readFileSync, existsSync } from 'fs'
+
+export const meta = {
+  id: 'systemdb-whitelist',
+  name: 'systemDB Context Whitelist',
+  category: 'security',
+  severity: 'high',
+  description: 'Ensures all systemDB() calls use whitelisted context strings'
+}
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // Find systemDb.ts to extract whitelist
+  const systemDbPaths = [
+    `${projectRoot}/backend/src/core/systemDb.ts`,
+    `${projectRoot}/src/core/systemDb.ts`
+  ]
+
+  let systemDbPath = null
+  for (const path of systemDbPaths) {
+    if (existsSync(path)) {
+      systemDbPath = path
+      break
+    }
+  }
+
+  if (!systemDbPath) {
+    results.skipped = true
+    results.skipReason = 'No systemDb.ts found'
+    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)
+
+  if (!whitelistMatch) {
+    results.passed = false
+    results.findings.push({
+      file: systemDbPath,
+      line: 1,
+      type: 'missing-whitelist',
+      severity: 'critical',
+      message: 'systemDb.ts does not contain a whitelist Set'
+    })
+    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)
+  )
+
+  // Find all systemDB() calls in the codebase
+  const files = await glob('**/*.ts', {
+    cwd: projectRoot,
+    ignore: [
+      ...config.ignore,
+      '**/systemDb.ts', // Skip the definition file
+      '**/*.test.ts',
+      '**/*.spec.ts'
+    ]
+  })
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(`${projectRoot}/${file}`, 'utf-8')
+      const lines = content.split('\n')
+
+      // Find systemDB('context') calls
+      const pattern = /systemDB\s*\(\s*['"]([^'"]+)['"]\s*\)/g
+
+      let match
+      while ((match = pattern.exec(content)) !== null) {
+        const context = match[1]
+
+        // Find line number
+        let lineNumber = 1
+        let pos = 0
+        for (const line of lines) {
+          if (pos + line.length >= match.index) {
+            break
+          }
+          pos += line.length + 1
+          lineNumber++
+        }
+
+        if (!whitelist.has(context)) {
+          results.passed = false
+          results.findings.push({
+            file,
+            line: lineNumber,
+            type: 'unknown-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`
+          })
+          results.summary.high++
+          results.summary.total++
+        }
+      }
+    } catch (e) {
+      // Skip unreadable files
+    }
+  }
+
+  // Add info about whitelist
+  results.info = {
+    whitelistPath: systemDbPath,
+    whitelistCount: whitelist.size,
+    contexts: Array.from(whitelist)
+  }
+
+  return results
+}

package/lib/checks/stability/ci-pipeline.js

@@ -0,0 +1,143 @@
+/**
+ * Check for CI/CD pipeline configuration
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+
+export const meta = {
+  id: 'ci-pipeline',
+  name: 'CI/CD Pipeline',
+  category: 'stability',
+  severity: 'high',
+  description: 'Ensures CI/CD pipeline is configured with essential checks'
+}
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // Check for CI config files
+  const ciPaths = [
+    { path: '.github/workflows', name: 'GitHub Actions' },
+    { path: '.gitlab-ci.yml', name: 'GitLab CI' },
+    { path: '.circleci/config.yml', name: 'CircleCI' },
+    { path: 'Jenkinsfile', name: 'Jenkins' },
+    { path: 'azure-pipelines.yml', name: 'Azure DevOps' }
+  ]
+
+  let foundCi = null
+  let ciContent = ''
+
+  for (const { path, name } of ciPaths) {
+    const fullPath = join(projectRoot, path)
+    if (existsSync(fullPath)) {
+      foundCi = name
+
+      // Read content
+      if (path.endsWith('.yml') || path.endsWith('.yaml')) {
+        ciContent = readFileSync(fullPath, 'utf-8')
+      } else if (path === '.github/workflows') {
+        // Read all workflow files
+        const files = readdirSync(fullPath).filter(f => f.endsWith('.yml') || f.endsWith('.yaml'))
+        ciContent = files.map(f => readFileSync(join(fullPath, f), 'utf-8')).join('\n')
+      }
+      break
+    }
+  }
+
+  if (!foundCi) {
+    results.passed = false
+    results.findings.push({
+      type: 'ci-missing',
+      severity: 'high',
+      message: 'No CI/CD configuration found',
+      fix: 'Add .github/workflows/ with CI configuration'
+    })
+    results.summary.high++
+    results.summary.total++
+    return results
+  }
+
+  // Check for essential CI steps
+  const essentialChecks = [
+    {
+      name: 'install-dependencies',
+      patterns: ['npm ci', 'npm install', 'yarn install', 'pnpm install'],
+      severity: 'high'
+    },
+    {
+      name: 'lint',
+      patterns: ['npm run lint', 'eslint', 'npx lint'],
+      severity: 'medium'
+    },
+    {
+      name: 'type-check',
+      patterns: ['tsc', 'typecheck', 'type-check', '--noEmit'],
+      severity: 'medium'
+    },
+    {
+      name: 'test',
+      patterns: ['npm test', 'npm run test', 'jest', 'vitest'],
+      severity: 'high'
+    },
+    {
+      name: 'build',
+      patterns: ['npm run build', 'vite build', 'next build'],
+      severity: 'medium'
+    },
+    {
+      name: 'security-audit',
+      patterns: ['npm audit', 'vca-audit', 'security-check', 'snyk', 'CodeQL'],
+      severity: 'medium'
+    }
+  ]
+
+  const ciContentLower = ciContent.toLowerCase()
+
+  for (const { name, patterns, severity } of essentialChecks) {
+    const hasCheck = patterns.some(p => ciContentLower.includes(p.toLowerCase()))
+
+    if (!hasCheck) {
+      if (severity === 'high') {
+        results.passed = false
+      }
+      results.findings.push({
+        type: `ci-missing-${name}`,
+        severity,
+        message: `CI pipeline missing: ${name}`,
+        fix: `Add ${name} step to your CI workflow`
+      })
+      results.summary[severity]++
+      results.summary.total++
+    }
+  }
+
+  // Check for branch protection indicators
+  const hasBranchRestriction = ciContent.includes('branches:') ||
+                               ciContent.includes('on:\n  push:') ||
+                               ciContent.includes('pull_request:')
+
+  if (!hasBranchRestriction) {
+    results.findings.push({
+      type: 'ci-no-branch-filter',
+      severity: 'low',
+      message: 'CI runs on all branches - consider limiting to main/master and PRs',
+      fix: 'Add branch filters to CI configuration'
+    })
+    results.summary.low++
+    results.summary.total++
+  }
+
+  results.info = {
+    ciProvider: foundCi,
+    workflowCount: foundCi === 'GitHub Actions'
+      ? readdirSync(join(projectRoot, '.github/workflows')).filter(f => f.endsWith('.yml')).length
+      : 1
+  }
+
+  return results
+}

package/lib/checks/stability/husky-hooks.js

@@ -0,0 +1,117 @@
+/**
+ * Check for pre-commit hooks (Husky)
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+export const meta = {
+  id: 'husky-hooks',
+  name: 'Pre-commit Hooks (Husky)',
+  category: 'stability',
+  severity: 'high',
+  description: 'Ensures Husky pre-commit hooks are configured'
+}
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // Check 1: Husky installed
+  const huskyDir = join(projectRoot, '.husky')
+  if (!existsSync(huskyDir)) {
+    results.passed = false
+    results.findings.push({
+      type: 'husky-missing',
+      severity: 'high',
+      message: 'Husky is not installed - no pre-commit validation',
+      fix: 'Run: npm install --save-dev husky && npx husky init'
+    })
+    results.summary.high++
+    results.summary.total++
+    return results
+  }
+
+  // Check 2: pre-commit hook exists
+  const preCommitPath = join(huskyDir, 'pre-commit')
+  if (!existsSync(preCommitPath)) {
+    results.passed = false
+    results.findings.push({
+      type: 'pre-commit-missing',
+      severity: 'high',
+      message: 'No pre-commit hook configured',
+      fix: 'Create .husky/pre-commit with your checks'
+    })
+    results.summary.high++
+    results.summary.total++
+    return results
+  }
+
+  // Check 3: pre-commit content has useful checks
+  const preCommitContent = readFileSync(preCommitPath, 'utf-8')
+  const recommendedChecks = [
+    { name: 'lint', patterns: ['lint', 'eslint'] },
+    { name: 'type-check', patterns: ['tsc', 'typecheck', 'type-check'] },
+    { name: 'test', patterns: ['test', 'jest', 'vitest'] },
+    { name: 'security', patterns: ['security', 'audit', 'vca-'] }
+  ]
+
+  const missingChecks = []
+  for (const { name, patterns } of recommendedChecks) {
+    const hasCheck = patterns.some(p => preCommitContent.toLowerCase().includes(p))
+    if (!hasCheck) {
+      missingChecks.push(name)
+    }
+  }
+
+  if (missingChecks.length > 0) {
+    results.findings.push({
+      type: 'missing-recommended-checks',
+      severity: 'medium',
+      message: `Pre-commit hook missing recommended checks: ${missingChecks.join(', ')}`,
+      fix: 'Add these checks to .husky/pre-commit'
+    })
+    results.summary.medium++
+    results.summary.total++
+  }
+
+  // Check 4: lint-staged configured (optional but recommended)
+  const packagePath = join(projectRoot, 'package.json')
+  if (existsSync(packagePath)) {
+    const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'))
+    const hasLintStaged = pkg['lint-staged'] ||
+                          existsSync(join(projectRoot, '.lintstagedrc')) ||
+                          existsSync(join(projectRoot, 'lint-staged.config.js'))
+
+    if (!hasLintStaged && preCommitContent.includes('lint-staged')) {
+      results.findings.push({
+        type: 'lint-staged-missing',
+        severity: 'low',
+        message: 'lint-staged is referenced but not configured',
+        fix: 'Add lint-staged configuration to package.json or create .lintstagedrc'
+      })
+      results.summary.low++
+      results.summary.total++
+    }
+  }
+
+  // Check 5: prepare script in package.json
+  if (existsSync(packagePath)) {
+    const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'))
+    if (!pkg.scripts?.prepare?.includes('husky')) {
+      results.findings.push({
+        type: 'prepare-script-missing',
+        severity: 'low',
+        message: 'No "prepare": "husky" script - hooks may not install on npm install',
+        fix: 'Add "prepare": "husky" to package.json scripts'
+      })
+      results.summary.low++
+      results.summary.total++
+    }
+  }
+
+  return results
+}

package/lib/checks/stability/npm-audit.js

@@ -0,0 +1,140 @@
+/**
+ * Check for npm vulnerabilities
+ */
+
+import { execSync } from 'child_process'
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+export const meta = {
+  id: 'npm-audit',
+  name: 'NPM Vulnerability Audit',
+  category: 'stability',
+  severity: 'high',
+  description: 'Checks for known vulnerabilities in npm dependencies'
+}
+
+export async function run(config, projectRoot) {
+  const results = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  // Check for package-lock.json
+  const lockFile = join(projectRoot, 'package-lock.json')
+  if (!existsSync(lockFile)) {
+    results.findings.push({
+      type: 'no-lock-file',
+      severity: 'medium',
+      message: 'No package-lock.json found - cannot run npm audit',
+      fix: 'Run npm install to generate package-lock.json'
+    })
+    results.summary.medium++
+    results.summary.total++
+    return results
+  }
+
+  try {
+    // Run npm audit
+    const auditOutput = execSync('npm audit --json 2>/dev/null', {
+      cwd: projectRoot,
+      encoding: 'utf-8',
+      maxBuffer: 10 * 1024 * 1024 // 10MB buffer
+    })
+
+    const audit = JSON.parse(auditOutput)
+    const vulnerabilities = audit.metadata?.vulnerabilities || {}
+
+    // Get allowed thresholds from config
+    const allowed = config.stability?.allowedVulnerabilities || {
+      critical: 0,
+      high: 0,
+      moderate: 10
+    }
+
+    // Check critical
+    if (vulnerabilities.critical > allowed.critical) {
+      results.passed = false
+      results.findings.push({
+        type: 'critical-vulnerabilities',
+        severity: 'critical',
+        message: `${vulnerabilities.critical} critical vulnerabilities found (allowed: ${allowed.critical})`,
+        fix: 'Run: npm audit fix --force (or manually update packages)'
+      })
+      results.summary.critical += vulnerabilities.critical
+      results.summary.total += vulnerabilities.critical
+    }
+
+    // Check high
+    if (vulnerabilities.high > allowed.high) {
+      results.passed = false
+      results.findings.push({
+        type: 'high-vulnerabilities',
+        severity: 'high',
+        message: `${vulnerabilities.high} high severity vulnerabilities found (allowed: ${allowed.high})`,
+        fix: 'Run: npm audit fix'
+      })
+      results.summary.high += vulnerabilities.high
+      results.summary.total += vulnerabilities.high
+    }
+
+    // Check moderate (warning only)
+    if (vulnerabilities.moderate > allowed.moderate) {
+      results.findings.push({
+        type: 'moderate-vulnerabilities',
+        severity: 'medium',
+        message: `${vulnerabilities.moderate} moderate vulnerabilities found (allowed: ${allowed.moderate})`,
+        fix: 'Consider running: npm audit fix'
+      })
+      results.summary.medium += vulnerabilities.moderate
+      results.summary.total += vulnerabilities.moderate
+    }
+
+    // Info about total vulnerabilities
+    results.info = {
+      critical: vulnerabilities.critical || 0,
+      high: vulnerabilities.high || 0,
+      moderate: vulnerabilities.moderate || 0,
+      low: vulnerabilities.low || 0,
+      total: audit.metadata?.totalDependencies || 0
+    }
+
+  } catch (e) {
+    // npm audit returns non-zero exit code when vulnerabilities found
+    // Try to parse the JSON output anyway
+    if (e.stdout) {
+      try {
+        const audit = JSON.parse(e.stdout)
+        const vulnerabilities = audit.metadata?.vulnerabilities || {}
+
+        results.info = {
+          critical: vulnerabilities.critical || 0,
+          high: vulnerabilities.high || 0,
+          moderate: vulnerabilities.moderate || 0,
+          low: vulnerabilities.low || 0
+        }
+
+        if (vulnerabilities.critical > 0 || vulnerabilities.high > 0) {
+          results.passed = false
+          results.findings.push({
+            type: 'vulnerabilities-found',
+            severity: vulnerabilities.critical > 0 ? 'critical' : 'high',
+            message: `Found ${vulnerabilities.critical || 0} critical, ${vulnerabilities.high || 0} high vulnerabilities`,
+            fix: 'Run: npm audit fix'
+          })
+        }
+      } catch {
+        // Can't parse output
+        results.findings.push({
+          type: 'audit-error',
+          severity: 'medium',
+          message: 'Could not run npm audit',
+          fix: 'Ensure npm is installed and package-lock.json exists'
+        })
+      }
+    }
+  }
+
+  return results
+}