@soulbatical/tetra-dev-toolkit 1.16.0 → 1.16.2

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

@@ -134,14 +134,55 @@ 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 groupComment = null
+
+      for (let i = 0; i < rawLines.length; i++) {
+        const line = rawLines[i].trim()
+
+        // Track group comments — a comment line that is NOT inline with an entry
+        // Group comments apply to ALL entries below them until the next group comment
+        if (/^\s*\/\//.test(line) && !line.match(/['"][^'"]+['"]/)) {
+          const commentText = line.replace(/^\s*\/\/\s*/, '').trim()
+          if (commentText.length > 0) {
+            groupComment = commentText
+          }
+          continue
+        }
+
+        // Skip empty lines (don't reset group comment)
+        if (!line || line === ',') 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 inlineReason = inlineCommentMatch ? inlineCommentMatch[1].trim() : null
+
+        // Entry is justified if it has an inline comment OR falls under a group comment
+        const hasJustification = inlineReason || groupComment
+
+        if (!hasJustification) {
+          // Find line number in original file
+          const entryLineInFile = systemDbContent.substring(0, systemDbContent.indexOf(entry)).split('\n').length
+
+          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. Add a group comment above or an inline comment.`,
+            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
+        }
+      }
     }
 
     if (whitelist.size > MAX_WHITELIST_SIZE) {
@@ -159,6 +200,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.2",
   "publishConfig": {
     "access": "restricted"
   },