@soulbatical/tetra-dev-toolkit 1.16.0 → 1.16.1

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

@@ -134,14 +134,52 @@ export async function run(config, projectRoot) {
     const whitelistMatch = systemDbContent.match(/new Set\s*(?:<[^>]+>)?\s*\(\s*\[([\s\S]*?)\]\s*\)/m)
 
     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)
+      const rawLines = whitelistMatch[1].split('\n')
+      let lastComment = null
+
+      for (let i = 0; i < rawLines.length; i++) {
+        const line = rawLines[i].trim()
+
+        // Track comments — group comments (// ...) or inline comments
+        const commentMatch = line.match(/^\s*\/\/\s*(.+)/)
+        if (commentMatch) {
+          lastComment = commentMatch[1].trim()
+          continue
+        }
+
+        const entryMatch = line.match(/['"]([^'"]+)['"]/)
+        if (!entryMatch) { continue }
+
+        const entry = entryMatch[1]
+        whitelist.add(entry)
+
+        // Check for inline comment: 'entry', // reason
+        const inlineCommentMatch = line.match(/['"][^'"]+['"]\s*,?\s*\/\/\s*(.+)/)
+        const reason = inlineCommentMatch ? inlineCommentMatch[1].trim() : lastComment
+
+        // Find line number in original file
+        const entryLineInFile = systemDbContent.substring(0, systemDbContent.indexOf(entry)).split('\n').length
+
+        if (!reason) {
+          results.findings.push({
+            file: systemDbPath.replace(projectRoot + '/', ''),
+            line: entryLineInFile,
+            type: 'whitelist-no-justification',
+            severity: 'high',
+            message: `systemDB whitelist entry '${entry}' has NO comment explaining WHY it needs service role key access. Every whitelist entry MUST have a comment above or inline.`,
+            fix: `Add a comment explaining why '${entry}' cannot use adminDB/userDB. Example:\n  // OAuth callback — browser redirect, no JWT in header\n  '${entry}',`
+          })
+          results.summary.high++
+          results.summary.total++
+          results.passed = false
+        }
+
+        // Reset lastComment after consuming it for a non-dynamic entry
+        // (don't reset for "// Dynamic:" comments which apply to patterns, not specific entries)
+        if (lastComment && !lastComment.toLowerCase().startsWith('dynamic')) {
+          lastComment = null
+        }
+      }
     }
 
     if (whitelist.size > MAX_WHITELIST_SIZE) {
@@ -159,6 +197,28 @@ export async function run(config, projectRoot) {
     }
   }
 
+  // Also check .tetra-quality.json for documented whitelist with justifications
+  const configWhitelist = config?.supabase?.systemDbWhitelist || {}
+  if (typeof configWhitelist === 'object' && !Array.isArray(configWhitelist)) {
+    // Format: { "context-name": "reason why systemDB is needed" }
+    for (const [context, reason] of Object.entries(configWhitelist)) {
+      whitelist.add(context)
+      if (!reason || typeof reason !== 'string' || reason.trim().length < 5) {
+        results.findings.push({
+          file: '.tetra-quality.json',
+          line: 1,
+          type: 'config-whitelist-no-justification',
+          severity: 'high',
+          message: `systemDbWhitelist entry '${context}' has empty or insufficient justification: "${reason || ''}". Explain WHY this context cannot use adminDB/userDB.`,
+          fix: `In .tetra-quality.json, set: "systemDbWhitelist": { "${context}": "Reason: e.g. OAuth callback — no JWT available, browser redirect flow" }`
+        })
+        results.summary.high++
+        results.summary.total++
+        results.passed = false
+      }
+    }
+  }
+
   // ─── Check 2: systemDB in forbidden locations ───────────────
 
   const files = await glob('**/*.ts', {

package/package.json

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