@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/dist/security-runtime/src/checks/code/auth-helpers.mjs

@@ -0,0 +1,659 @@
+// Auth-helper discovery for the code check. The three *-write-no-auth rules accept a fixed set of auth function names; real products wrap
+// the session check in their own helper (requireApiContext -> getCurrentUserContext -> supabase.auth.getUser()). This module finds those wrappers by
+// reading the scanned repository's source as text (a regex scanner, never executing it). Findings are filtered only for resolved local/imported bindings.
+import fs from 'node:fs';
+import path from 'node:path';
+import { listFiles } from '../../core/detect.mjs';
+
+export const MAX_INDEX_FILES = 3000;
+export const MAX_INDEX_FILE_BYTES = 300_000;
+/** Hops from a function to a primitive: 1 = it calls the primitive itself, 2 = it calls a function that does (requireApiContext -> getCurrentUserContext -> getUser). */
+export const MAX_DEPTH = 2;
+/** The sentinel in the rule regexes that explicitly configured names replace at scan time. */
+export const SENTINEL = '__vsg_discovered__';
+
+const SOURCE = /\.[cm]?[jt]sx?$/;
+const TEST_FILE = /(?:^|\/)[^/]+\.(?:test|spec)\.[^/]+$|\.d\.ts$/;
+// Names that must never become "auth helpers" however they are written: entry points and framework hooks, not checks.
+const DENY = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'default', 'handler', 'middleware', 'proxy', 'main', 'if', 'for', 'while', 'switch', 'catch', 'return', 'function', 'typeof', 'await', 'async']);
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+
+/** What makes a function a session or credential check. Each primitive is matched on source text. */
+const PRIMITIVES = [
+  /\bauth\s*\.\s*(?:getUser|getClaims|getSession)\s*\(/, // supabase.auth.getUser() and friends
+  /(?<![\w$.])(?:auth|currentUser|getServerSession|jwtVerify|getClaims|getSession)\s*\(/, // Clerk auth(), currentUser(), NextAuth getServerSession(), jose jwtVerify
+];
+/**
+ * Names that preserve a cost-zero imported guard hop after the resolved definition is proven to reach an auth primitive. A name alone cannot
+ * create an automatic helper. The write-no-auth rules also accept these conventional guard names directly, plus looser names such as get*User*.
+ * This graph heuristic is deliberately stricter than the rule regex: get*User* is too common a name (getUserPreferences) to propagate to callers.
+ * test/auth-helpers.test.mjs checks that the shipped rules accept every name this accepts.
+ */
+export const AUTH_CALL_NAME = /^(?:auth|getAuth|getSession|getClaims|getServerSession|currentUser|getCurrentUser\w*|(?:require|assert|ensure)\w*(?:User|Auth|Session|Context|Admin|Member|Role|Permission|Owner|Access)\w*|validateRequest|jwtVerify)$/;
+
+// SQL functions that read the caller from the database session. A call to one of them through a user-scoped Supabase client (supabase.rpc("name"))
+// checks the caller in the database even though no auth.getUser() appears in the TypeScript.
+const SQL_FUNCTION = /create\s+(?:or\s+replace\s+)?function\s+(?:"?\w+"?\s*\.\s*)?"?(\w+)"?\s*\(/gi;
+const SQL_CALLER = /\bauth\s*\.\s*(?:uid|jwt)\s*\(|current_setting\s*\(\s*'request\.jwt\.claims?(?:\.sub)?'/i;
+const SQL_CALL = /\b([a-z_][a-z0-9_]*)\s*\(/gi;
+
+/** Strips SQL comments (-- and block comments); string literals are kept. */
+const stripSqlComments = (sql) => sql.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/--[^\n]*/g, '');
+
+/**
+ * Names of SQL functions, defined in the given migration texts, whose body reads the caller (auth.uid(), auth.jwt()) or calls another such function.
+ * Pass the texts in migration order: the newest definition of a name wins. Text only, nothing is executed. Returns a sorted array of lower-case names.
+ */
+export function sqlAuthFunctions(sqlTexts) {
+  const defs = new Map(); // name -> { direct, calls }
+  for (const raw of sqlTexts) {
+    const sql = stripSqlComments(raw);
+    const starts = [...sql.matchAll(SQL_FUNCTION)];
+    starts.forEach((m, i) => {
+      const slice = sql.slice(m.index + m[0].length, starts[i + 1]?.index ?? sql.length);
+      const quote = /\$(\w*)\$/.exec(slice);
+      let body = slice;
+      if (quote) {
+        const open = quote.index + quote[0].length;
+        const close = slice.indexOf(quote[0], open);
+        body = slice.slice(open, close < 0 ? slice.length : close);
+      }
+      defs.set(m[1].toLowerCase(), { direct: SQL_CALLER.test(body), calls: new Set([...body.matchAll(SQL_CALL)].map((c) => c[1].toLowerCase())) });
+    });
+  }
+  const auth = new Set([...defs].filter(([, d]) => d.direct).map(([n]) => n));
+  for (let pass = 0; pass < 3; pass++) {
+    let changed = false;
+    for (const [name, d] of defs) if (!auth.has(name) && [...d.calls].some((c) => c !== name && auth.has(c))) { auth.add(name); changed = true; }
+    if (!changed) break;
+  }
+  return [...auth].sort();
+}
+
+/** Reads the migration SQL (any .sql file under a migrations/ folder, in file-name order) and returns sqlAuthFunctions of it. */
+export function discoverAuthRpcs(repo, files = listFiles(repo)) {
+  const sql = files.filter((f) => /\.sql$/i.test(f) && /(?:^|\/)migrations\//i.test(f)).sort();
+  const texts = [];
+  for (const f of sql.slice(0, 2000)) {
+    try {
+      const full = path.join(repo, f);
+      if (fs.statSync(full).size > 2_000_000) continue;
+      texts.push(fs.readFileSync(full, 'utf8'));
+    } catch { /* unreadable: skipped */ }
+  }
+  return sqlAuthFunctions(texts);
+}
+
+/**
+ * A primitive for `<client>.rpc("name")` over the given SQL function names, or null when there are none. A service-role or admin client carries
+ * no caller (auth.uid() is null for it), so a receiver whose name contains "service" or "admin" never counts.
+ */
+export function rpcPrimitive(rpcNames) {
+  const names = [...new Set(rpcNames)].filter((n) => /^\w+$/.test(n));
+  if (!names.length) return null;
+  return new RegExp(`(?<![\\w$.])(?![\\w$.]*(?:service|admin))[\\w$.]+?\\s*\\.\\s*rpc\\s*\\(\\s*["'\`](?:${names.join('|')})["'\`]`, 'i');
+}
+
+// Shared-secret checks (timingSafeEqual, Authorization compared with "Bearer <secret>") are recognized in the rules themselves, not discovered here:
+// a function that merely uses timingSafeEqual (a captcha, a webhook of someone else's) is not evidence that it checks the caller.
+
+/** Removes comments and keeps strings, so commented-out calls do not count. Not a full tokenizer: regex literals are not recognised. */
+export function stripComments(text) {
+  let out = '';
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    const d = text[i + 1];
+    if (c === '/' && d === '/') { while (i < n && text[i] !== '\n') i++; continue; }
+    if (c === '/' && d === '*') { const end = text.indexOf('*/', i + 2); i = end < 0 ? n : end + 2; out += ' '; continue; }
+    if (c === '"' || c === "'" || c === '`') {
+      let j = i + 1;
+      while (j < n && text[j] !== c && !(c !== '`' && text[j] === '\n')) j += text[j] === '\\' ? 2 : 1;
+      out += text.slice(i, j + 1);
+      i = j + 1;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/**
+ * Replaces JavaScript string and template literals with whitespace while preserving line breaks.
+ * Auth discovery is deliberately lexical, but a literal containing `supabase.auth.getUser()` is
+ * data, not an authentication check. Keeping the quotes out of the result also prevents the call
+ * matcher from treating words in a literal as function calls.
+ */
+export function stripLiterals(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c !== '"' && c !== "'" && c !== '`') {
+      out += c;
+      i++;
+      continue;
+    }
+    const quote = c;
+    out += ' ';
+    i++;
+    while (i < text.length) {
+      const ch = text[i];
+      if (ch === '\n' || ch === '\r') {
+        out += ch;
+        i++;
+        continue;
+      }
+      out += ' ';
+      if (ch === '\\') {
+        i++;
+        if (i < text.length) {
+          out += text[i] === '\n' || text[i] === '\r' ? text[i] : ' ';
+          i++;
+        }
+        continue;
+      }
+      i++;
+      if (ch === quote) break;
+    }
+  }
+  return out;
+}
+
+/** Whether an offset points at executable source rather than a comment or quoted literal. */
+function isCodePosition(text, offset) {
+  let quote = null;
+  for (let i = 0; i < offset; i++) {
+    const c = text[i];
+    const d = text[i + 1];
+    if (quote) {
+      if (c === '\\') { i++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '/' && d === '/') {
+      const end = text.indexOf('\n', i + 2);
+      if (end < 0 || end >= offset) return false;
+      i = end;
+      continue;
+    }
+    if (c === '/' && d === '*') {
+      const end = text.indexOf('*/', i + 2);
+      if (end < 0 || end >= offset) return false;
+      i = end + 1;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') quote = c;
+  }
+  return !quote;
+}
+
+const executableMatch = (text, re) => {
+  const flags = re.flags.includes('g') ? re.flags : `${re.flags}g`;
+  const copy = new RegExp(re.source, flags);
+  for (const match of text.matchAll(copy)) if (isCodePosition(text, match.index)) return true;
+  return false;
+};
+
+function topLevelLines(body) {
+  const clean = stripLiterals(stripComments(body));
+  // Supported bodies start on their own next line. Same-line statements can hide a
+  // single-statement conditional around the first apparent top-level call.
+  if (!/\{\s*$/.test(clean.split(/\r?\n/, 1)[0])) return [];
+  let depth = 0;
+  return clean.split(/\r?\n/).map((code) => {
+    const atTop = depth === 1;
+    depth += (code.match(/{/g) ?? []).length - (code.match(/}/g) ?? []).length;
+    return { line: code, code, atTop };
+  });
+}
+
+function primitiveResultBindings(body) {
+  const bindings = [];
+  for (const [index, { line, atTop }] of topLevelLines(body).entries()) {
+    if (index === 0 || !atTop) continue;
+    const assignment = /^\s*const\s+(.+?)\s*=\s*await\s+(.+?)\s*;?\s*$/.exec(line);
+    if (!assignment) continue;
+    const [, lhs, rhs] = assignment;
+    const supabaseMethod = /^(?:[A-Za-z_$][\w$]*\.)+auth\s*\.\s*(?:getUser|getClaims|getSession)\s*\(\s*\)$/.test(rhs);
+    if (supabaseMethod) {
+      const data = /^\s*\{[^{}]*\bdata\s*:\s*\{([^{}]*)\}[^{}]*\}\s*$/.exec(lhs)?.[1];
+      if (!data) continue;
+      const names = new Set();
+      for (const part of data.split(',')) {
+        const property = /^\s*(user|session|claims)(?:\s*:\s*([A-Za-z_$][\w$]*))?\s*$/.exec(part);
+        if (property) names.add(property[2] ?? property[1]);
+      }
+      if (names.size) bindings.push({ index, names });
+      continue;
+    }
+    const directMethod = /^(?:currentUser|getServerSession)\s*\(\s*\)$/.exec(rhs)?.[0];
+    if (!directMethod) continue;
+    const name = /^\s*([A-Za-z_$][\w$]*)\s*$/.exec(lhs)?.[1];
+    if (name && IDENT.test(name)) bindings.push({ index, names: new Set([name]) });
+  }
+  return bindings;
+}
+
+function primitiveResultNames(body) {
+  return new Set(primitiveResultBindings(body).flatMap((binding) => [...binding.names]));
+}
+
+const CONTROL = /\b(?:if|else|switch|for|while|do|try|catch|return|throw|function)\b|=>/;
+const escapeName = (name) => name.replace(/\$/g, '\\$');
+
+// Only simple awaited assignments carry another helper's proven return semantics.
+function helperResultBindings(body, callee) {
+  const re = new RegExp(`^\\s*const\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*await\\s+${escapeName(callee)}\\s*\\([^()]*\\)\\s*;?\\s*$`);
+  return topLevelLines(body).flatMap(({ code, atTop }, index) => {
+    const match = index > 0 && atTop && re.exec(code);
+    return match ? [{ index, names: new Set([match[1]]) }] : [];
+  });
+}
+
+function resultAliases(body, callee) {
+  return helperResultBindings(body, callee).flatMap(({ names }) => [...names]);
+}
+
+function authBindings(body, authValues) {
+  const primitive = primitiveResultBindings(body);
+  const scalar = topLevelLines(body).flatMap(({ code, atTop }, index) => {
+    const match = index > 0 && atTop && /^\s*const\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+[A-Za-z_$][\w$]*\s*\([^()]*\)\s*;?\s*$/.exec(code);
+    return match && authValues.has(match[1]) ? [{ index, names: new Set([match[1]]) }] : [];
+  });
+  return [...primitive, ...scalar].filter(({ names }) => [...names].some((name) => authValues.has(name)));
+}
+
+function straightPrefix(lines, end) {
+  return !CONTROL.test(lines.slice(1, end).map(({ code }) => code).join('\n'));
+}
+
+function directReturnCall(body, callee) {
+  const lines = topLevelLines(body);
+  const returns = lines.filter(({ code }) => /\breturn\b/.test(code));
+  const re = new RegExp(`^\\s*return\\s+(?:await\\s+)?${escapeName(callee)}\\s*\\([^()]*\\)\\s*;?\\s*$`);
+  return returns.length === 1 && returns[0].atTop && re.test(returns[0].code) && straightPrefix(lines, lines.indexOf(returns[0]));
+}
+
+function directReturnName(body, name) {
+  const lines = topLevelLines(body);
+  const escaped = escapeName(name);
+  const binding = authBindings(body, new Set([name])).find(({ names }) => names.has(name));
+  if (!binding || !straightPrefix(lines, binding.index)) return false;
+  const tail = lines.slice(binding.index + 1).filter(({ code }) => code.trim() && !/^\s*}\)?\s*;?\s*$/.test(code));
+  // A nullable identity may be returned directly, or mapped to context only after a null exit.
+  if (tail.length === 1) return tail[0].atTop && (
+    new RegExp(`^\\s*return\\s+${escaped}\\s*;?\\s*$`).test(tail[0].code)
+    // A single identity projection preserves null on the missing-identity branch.
+    || new RegExp(`^\\s*return\\s+${escaped}\\s*\\?\\s*\\{\\s*[A-Za-z_$][\\w$]*\\s*:\\s*${escaped}\\.[A-Za-z_$][\\w$]*\\s*\\}\\s*:\\s*null\\s*;?\\s*$`).test(tail[0].code)
+  );
+  return tail.length === 2 && tail.every(({ atTop }) => atTop)
+    && new RegExp(`^\\s*if\\s*\\(\\s*!\\s*${escaped}\\s*\\)\\s*return\\s+null\\s*;?\\s*$`).test(tail[0].code)
+    && /^\s*return\s*\{[^;]*\}\s*;?\s*$/.test(tail[1].code);
+}
+
+// Read only plain top-level object properties; nested keys never describe the returned sentinel.
+function denialProperties(code) {
+  const object = /\breturn\s*\{([^;]*)\}\s*;?\s*$/.exec(code)?.[1];
+  if (!object || /\.\.\.|\b(?:get|set|return|function)\b|=>/.test(object)) return new Map();
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; object.length > i; i++) {
+    if ('({['.includes(object[i])) depth++;
+    if (')}]'.includes(object[i])) depth--;
+    if (depth < 0) return new Map();
+    if (object[i] === ',' && depth === 0) { parts.push(object.slice(start, i)); start = i + 1; }
+  }
+  if (depth !== 0) return new Map();
+  parts.push(object.slice(start));
+  const properties = new Map();
+  for (const part of parts) {
+    const property = /^\s*([A-Za-z_$][\w$]*)\s*:\s*(.+?)\s*$/.exec(part);
+    if (!property || properties.has(property[1])) return new Map();
+    properties.set(property[1], property[2]);
+  }
+  return properties;
+}
+
+function denialResultKeys(body, authValues) {
+  const keys = new Set();
+  const lines = topLevelLines(body);
+  const allCode = lines.map(({ code }) => code).join('\n');
+  const returns = lines.map(({ code, atTop }, index) => ({ code, atTop, index })).filter(({ code, atTop }) => atTop && /\breturn\b/.test(code));
+  if (returns.length !== 2) return keys;
+  if (/\b(?:function|try|catch|switch|for|while)\b|=>/.test(lines.slice(1).map(({ code }) => code).join('\n'))) return keys;
+  if ((allCode.match(/\bif\b/g) ?? []).length !== 1) return keys;
+  const first = returns[0];
+  const second = returns[1];
+  if (!/^\s*return\s*\{[^;]*\}\s*;?\s*$/.test(second.code)) return keys;
+  const properties = denialProperties(first.code);
+  for (const value of authValues) {
+    const escaped = value.replace(/\$/g, '\\$');
+    if (!new RegExp(`^\\s*if\\s*\\(\\s*!\\s*${escaped}\\s*\\)\\s*return\\s*\\{[^;]*\\}\\s*;?\\s*$`).test(first.code)) continue;
+    const binding = authBindings(body, authValues).find((entry) => entry.names.has(value))?.index ?? -1;
+    if (binding < 0 || binding >= first.index || lines.slice(binding + 1, first.index).some(({ code }) => new RegExp(`\\b${escaped}\\s*(?:=|\\+\\+|--|\\|=|&&=|\\?\\?=)`).test(code))) continue;
+    const prior = lines.slice(1, first.index).map(({ code }) => code).join('\n');
+    if (/\b(?:if|else|switch|for|while|try|catch|return|throw)\b|=>/.test(prior)) continue;
+    if (lines.slice(first.index + 1, second.index).some(({ code }) => /\b(?:if|else|switch|for|while|try|catch|throw)\b|=>/.test(code))) continue;
+    for (const [key, denial] of [
+      ['response', /^new\s+Response\s*\([^()]*\)$/],
+      ['error', /^new\s+Error\s*\([^()]*\)$/],
+      ['denied', /^true$/],
+      ['unauthorized', /^true$/],
+      ['allowed', /^false$/],
+    ]) if (denial.test(properties.get(key) ?? '')) keys.add(key);
+  }
+  return keys;
+}
+/** True only for a top-level, straight-line await/return of a fail-closed helper. */
+export function callsUnconditionally(body, callee) {
+  const lines = topLevelLines(body);
+  const escaped = callee.replace(/\$/g, '\\$');
+  const callLine = new RegExp(`^\\s*(?:(?:(?:await|return\\s+await)\\s+|return\\s+)|(?:const|let|var)\\s+(?:\\{[^}]+\\}|[A-Za-z_$][\\w$]*)(?:\\s*:[^=]+)?\\s*=\\s*await\\s+)${escaped}\\s*\\(\\s*\\)\\s*;?\\s*$`);
+  if (/=>|\bcatch\b/.test(stripLiterals(stripComments(body)))) return false;
+  for (let i = 1; i < lines.length; i++) {
+    const { code, atTop } = lines[i];
+    if (!new RegExp(`(?<![\\w$.])${escaped}\\s*\\(`).test(code)) continue;
+    if (!atTop || !callLine.test(code)) return false;
+    const prior = lines.slice(1, i).map((entry) => entry.code).join('\n');
+    return !CONTROL.test(prior);
+  }
+  return false;
+}
+// A primitive call is evidence that a function reads caller identity, not that it enforces it.
+// Only an explicit denial throw tied to a result assigned from that primitive is a guard.
+function throwsOnMissingAuth(body, authValues, denialCalls = new Set()) {
+  const lines = topLevelLines(body);
+  const code = lines.slice(1).map((entry) => entry.code).join('\n');
+  if (!authValues.size || /\bcatch\b|=>/.test(code)) return false;
+  for (const binding of authBindings(body, authValues)) {
+    if (!straightPrefix(lines, binding.index)) continue;
+    let next = binding.index + 1;
+    while (next < lines.length && !lines[next].code.trim()) next++;
+    if (next >= lines.length || !lines[next].atTop) continue;
+    for (const value of binding.names) {
+      const escaped = value.replace(/\$/g, '\\$');
+      const guard = new RegExp(`^\\s*if\\s*\\(\\s*!\\s*${escaped}\\s*\\)\\s*(?:\\{\\s*)?throw\\b`);
+      if (guard.test(lines[next].code)) return true;
+      for (const denial of denialCalls) {
+        // Framework termination is trusted only through an unshadowed import, with a
+        // complete denial statement (no conditional call or compound fallback).
+        const call = `${escapeName(denial)}\\s*\\([^()]*\\)\\s*;?`;
+        const redirect = new RegExp(`^\\s*if\\s*\\(\\s*!\\s*${escaped}\\s*\\)\\s*(?:${call}|\\{\\s*${call}\\s*\\})\\s*$`);
+        if (redirect.test(lines[next].code)) return true;
+      }
+    }
+  }
+  return false;
+}
+
+const FN_START = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\b\s*\*?\s*([A-Za-z_$][\w$]*)/;
+const CONST_START = /^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=/;
+const FUNCTION_VALUE = /^\s*(?:[\w$.]+\(\s*)?(?:async\b|function\b|\(|[\w$]+\s*=>)/;
+const TOP_LEVEL = /^(?:export|function|async|const|let|var|class|type|interface|enum|import|declare|module)\b/;
+const CALL = /([A-Za-z_$][\w$]*)\s*\(/g;
+// `const requireX = cache(requireFreshX);`: one wrapper call around one identifier.
+const ALIAS_VALUE = /^\s*[\w$.]+\(\s*([A-Za-z_$][\w$]*)\s*\)\s*;?\s*$/;
+
+/**
+ * Splits a module into top-level declarations by column-0 keywords (formatted code; no parsing) and records, per name, whether it is exported,
+ * which names its body calls, and whether the body itself contains an auth primitive. Overload signatures merge into the implementation.
+ * `const x = cache(y)` (one wrapper call around one named function) is an alias: x calls y. extraPrimitives are further regexes that count as a
+ * primitive (see rpcPrimitive).
+ */
+export function parseDeclarations(text, { extraPrimitives = [] } = {}) {
+  const lines = stripComments(text).split(/\r?\n/);
+  const imports = parseImports(text);
+  const declared = new Set(lines.flatMap((line) => (FN_START.exec(line) ?? CONST_START.exec(line))?.[1] ?? []));
+  const frameworkNames = (source, imported) => new Set([...imports].filter(([name, binding]) => binding.source === source && imported.includes(binding.imported) && !declared.has(name)).map(([name]) => name));
+  const redirects = frameworkNames('next/navigation', ['redirect']);
+  const caches = frameworkNames('react', ['cache']);
+  const decls = new Map();
+  const exportedNames = new Set();
+  let cur = null;
+  const flush = () => {
+    if (!cur) return;
+    const body = cur.lines.join('\n');
+    const d = decls.get(cur.name) ?? { name: cur.name, exported: false, exportedNames: new Set(), calls: new Set(), primitive: false, failsClosed: false, authValues: new Set(), returnsAuthValue: false, denialKeys: new Set() };
+    d.body = body;
+    d.exported ||= cur.exported;
+    if (cur.exported) {
+      d.exportedNames.add(cur.name);
+      if (/^export\s+default\b/.test(cur.lines[0])) d.exportedNames.add('default');
+    }
+    const code = stripLiterals(body);
+    d.denialCalls = new Set([...redirects].filter((name) => {
+      const escaped = escapeName(name);
+      // The sole reference must be the denial statement. Extra references include
+      // parameters and local bindings, including multiline destructuring shadows.
+      return [...code.matchAll(new RegExp(`(?<![\\w$])${escaped}(?![\\w$])`, 'g'))].length === 1;
+    }));
+    d.transparentAlias = cur.alias && cur.wrapper && caches.has(cur.wrapper)
+      && /^\s*(?:export\s+)?const\s+/.test(body)
+      && new RegExp(`^\\s*(?:export\\s+)?const\\s+${escapeName(cur.name)}\\s*=\\s*${escapeName(cur.wrapper)}\\s*\\(\\s*${escapeName(cur.alias)}\\s*\\)\\s*;?\\s*$`).test(code)
+      ? cur.alias : null;
+    for (const m of code.matchAll(CALL)) if (!DENY.has(m[1]) && m[1] !== cur.name) d.calls.add(m[1]);
+    if (cur.alias && !DENY.has(cur.alias) && cur.alias !== cur.name) d.calls.add(cur.alias);
+    // RPC primitives intentionally include a literal function name, so evaluate those against the
+    // original body while the built-in auth primitives use the literal-free code.
+    // A name that merely resembles a guard (for example requireAuth()) is not evidence by itself.
+    // The definition must reach a primitive, either locally or through the discovered call graph.
+    // The declaration itself is part of `body` for one-line functions. Mask its name before
+    // primitive matching so `function auth() { return true; }` does not authenticate itself.
+    const declarationCall = new RegExp(`(?<![\\w$.])${cur.name.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}\\s*\\(`);
+    const primitiveCode = code.replace(declarationCall, `${cur.name} `);
+    const reachesPrimitive = PRIMITIVES.some((re) => re.test(primitiveCode)) || extraPrimitives.some((re) => executableMatch(body, re));
+    d.primitive ||= reachesPrimitive;
+    if (reachesPrimitive) {
+      for (const name of primitiveResultNames(body)) d.authValues.add(name);
+      d.failsClosed ||= throwsOnMissingAuth(body, d.authValues, d.denialCalls);
+    }
+    d.returnsAuthValue ||= [...d.authValues].some((name) => directReturnName(body, name));
+    for (const key of denialResultKeys(body, d.authValues)) d.denialKeys.add(key);
+    decls.set(cur.name, d);
+    cur = null;
+  };
+  for (const line of lines) {
+    const named = FN_START.exec(line) ?? CONST_START.exec(line);
+    if (named) {
+      flush();
+      // A const counts as a function only when its value looks like one (arrow, function, or a wrapper call such as cache(async ...)); objects and values never become helpers.
+      const rest = line.slice(named[0].length);
+      const alias = FN_START.test(line) ? undefined : ALIAS_VALUE.exec(rest)?.[1];
+      const fn = FN_START.test(line) || FUNCTION_VALUE.test(rest) || Boolean(alias);
+      const wrapper = alias ? /^\s*([A-Za-z_$][\w$]*)\s*\(/.exec(rest)?.[1] : null;
+      cur = { name: named[1], exported: /^export\b/.test(line) && fn, lines: [line], alias, wrapper };
+      continue;
+    }
+    const list = /^export\s*\{([^}]*)\}/.exec(line);
+    if (list) for (const part of list[1].split(',')) {
+      const [original, alias] = part.trim().split(/\s+as\s+/);
+      if (original) exportedNames.add(`${original}\t${alias ?? original}`);
+    }
+    if (TOP_LEVEL.test(line)) { flush(); continue; }
+    if (cur) cur.lines.push(line);
+  }
+  flush();
+  for (const entry of exportedNames) {
+    const [name, alias] = entry.split('\t');
+    if (!decls.has(name)) continue;
+    decls.get(name).exported = true;
+    decls.get(name).exportedNames.add(alias);
+  }
+  for (let pass = 0; pass < decls.size + 1; pass++) {
+    let changed = false;
+    for (const d of decls.values()) {
+      for (const callee of d.calls) {
+        const target = decls.get(callee);
+        if (!target) continue;
+        if (target.failsClosed && d.transparentAlias === callee && !d.failsClosed) { d.failsClosed = true; changed = true; }
+        if (target.returnsAuthValue) for (const alias of resultAliases(d.body, callee)) {
+          if (!d.authValues.has(alias)) { d.authValues.add(alias); changed = true; }
+        }
+        if (directReturnCall(d.body, callee)) {
+          if (target.returnsAuthValue && !d.returnsAuthValue) { d.returnsAuthValue = true; changed = true; }
+          for (const key of target.denialKeys) if (!d.denialKeys.has(key)) { d.denialKeys.add(key); changed = true; }
+        }
+      }
+      if (throwsOnMissingAuth(d.body, d.authValues, d.denialCalls) && !d.failsClosed) { d.failsClosed = true; changed = true; }
+      if ([...d.authValues].some((name) => directReturnName(d.body, name)) && !d.returnsAuthValue) { d.returnsAuthValue = true; changed = true; }
+      for (const key of denialResultKeys(d.body, d.authValues)) if (!d.denialKeys.has(key)) { d.denialKeys.add(key); changed = true; }
+    }
+    if (!changed) break;
+  }
+  return decls;
+}
+
+/** Returns local bindings for named, default, and namespace imports in a module. */
+export function parseImports(text) {
+  const imports = new Map();
+  const re = /^\s*import\s+(.+?)\s+from\s+["']([^"']+)["']\s*;?\s*$/gm;
+  for (const match of text.matchAll(re)) {
+    const clause = match[1].trim();
+    const source = match[2];
+    if (!isCodePosition(text, match.index)) continue;
+    const add = (local, imported) => { if (IDENT.test(local)) imports.set(local, { local, imported, source }); };
+    const named = /\{([^}]*)\}/.exec(clause)?.[1];
+    if (named !== undefined) for (const part of named.split(',')) {
+      const [imported, local] = part.trim().split(/\s+as\s+/);
+      if (imported) add(local ?? imported, imported);
+    }
+    const namespace = /\*\s+as\s+([A-Za-z_$][\w$]*)/.exec(clause)?.[1];
+    if (namespace) add(namespace, '*');
+    const defaultName = clause.match(/^(?!\{|\*)[A-Za-z_$][\w$]*/)?.[0];
+    if (defaultName) add(defaultName, 'default');
+  }
+  return imports;
+}
+
+export const resolveModule = (repo, fromFile, source) => {
+  const repoRoot = fs.realpathSync(repo);
+  const roots = [];
+  if (source.startsWith('./') || source.startsWith('../')) roots.push(path.resolve(repo, path.dirname(fromFile), source));
+  else if (source.startsWith('@/') || source.startsWith('~/')) {
+    const relative = source.slice(2);
+    roots.push(path.resolve(repo, 'src', relative), path.resolve(repo, relative));
+  } else return null;
+  for (const root of roots) {
+    for (const suffix of ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']) {
+      const candidate = `${root}${suffix}`;
+      try {
+        if (!fs.statSync(candidate).isFile()) continue;
+        const real = fs.realpathSync(candidate);
+        if (real !== repoRoot && !real.startsWith(`${repoRoot}${path.sep}`)) continue;
+        return path.relative(repoRoot, real).replaceAll('\\', '/');
+      } catch { /* try the next form */ }
+    }
+    for (const suffix of ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']) {
+      const candidate = path.join(root, `index${suffix}`);
+      try {
+        if (!fs.statSync(candidate).isFile()) continue;
+        const real = fs.realpathSync(candidate);
+        if (real !== repoRoot && !real.startsWith(`${repoRoot}${path.sep}`)) continue;
+        return path.relative(repoRoot, real).replaceAll('\\', '/');
+      } catch { /* try the next form */ }
+    }
+  }
+  return null;
+};
+
+/**
+ * Finds exported functions in the repository whose bodies reach an auth primitive within MAX_DEPTH calls.
+ * A call to a non-exported function in the same file does not count as a hop (cache(async function getXCached ...) wrappers).
+ * An imported binding whose resolved definition reaches a recognized caller-check name (AUTH_CALL_NAME) may preserve a cost-zero guard hop;
+ * the name alone never creates a helper. A Supabase RPC whose migration SQL reads auth.uid() counts as a primitive.
+ * Returns { helpers: [{ name, file, depth }], indexedFiles, candidateFiles, capped, authRpcs }.
+ */
+export function discoverAuthHelpers(repo, { excludes = [], maxFiles = MAX_INDEX_FILES, maxBytes = MAX_INDEX_FILE_BYTES, maxDepth = MAX_DEPTH } = {}) {
+  const skip = new Set(excludes);
+  const candidates = listFiles(repo).filter((f) => SOURCE.test(f) && !TEST_FILE.test(f) && !f.split('/').slice(0, -1).some((seg) => skip.has(seg)));
+  const files = candidates.slice(0, maxFiles);
+  const authRpcs = discoverAuthRpcs(repo);
+  const rpcRe = rpcPrimitive(authRpcs);
+  const nodes = []; // { file, name, exported, calls, dist }
+  const byFile = new Map();
+  const importsByFile = new Map();
+  let indexed = 0;
+  for (const file of files) {
+    let text;
+    try {
+      const full = path.join(repo, file);
+      if (fs.statSync(full).size > maxBytes) continue;
+      text = fs.readFileSync(full, 'utf8');
+    } catch { continue; }
+    indexed++;
+    importsByFile.set(file, parseImports(text));
+    for (const d of parseDeclarations(text, { extraPrimitives: rpcRe ? [rpcRe] : [] }).values()) {
+      const node = { file, name: d.name, exports: [...(d.exportedNames ?? [])], exported: d.exported, calls: d.calls, dist: d.primitive ? 1 : Infinity, failsClosed: d.failsClosed, returnsAuthValue: d.returnsAuthValue, denialKeys: new Set(d.denialKeys), authValues: new Set(d.authValues), body: d.body, denialCalls: d.denialCalls, transparentAlias: d.transparentAlias };
+      nodes.push(node);
+      if (!byFile.has(file)) byFile.set(file, new Map());
+      byFile.get(file).set(d.name, node);
+    }
+  }
+  // Relax distances through actual lexical bindings. A same-name export in an unrelated module is
+  // never a target unless the caller imports that module's binding.
+  for (let pass = 0; pass < maxDepth + 3; pass++) {
+    let changed = false;
+    for (const node of nodes) {
+      for (const callee of node.calls) {
+        const local = byFile.get(node.file)?.get(callee);
+        let targets = local ? [[local, 0]] : [];
+        if (!local) {
+          const binding = importsByFile.get(node.file)?.get(callee);
+          const targetFile = binding ? resolveModule(repo, node.file, binding.source) : null;
+          const target = targetFile ? byFile.get(targetFile) : null;
+          if (target) {
+            const cost = AUTH_CALL_NAME.test(binding.imported) ? 0 : 1;
+            targets = [...target.values()].filter((t) => t.exported && (t.name === binding.imported || t.exports.includes(binding.imported) || (binding.imported === 'default' && t.exports.includes('default')))).map((t) => [t, cost]);
+          }
+        }
+        for (const [t, cost] of targets) {
+          if (t.dist + cost < node.dist) { node.dist = t.dist + cost; changed = true; }
+          // A wrapper may inherit a throwing guard only when it transparently awaits/returns it and
+          // does not catch the failure. Do not treat a returned auth value as a guard.
+          if (t.failsClosed && (callsUnconditionally(node.body, callee) || node.transparentAlias === callee)) {
+            if (!node.failsClosed) { node.failsClosed = true; changed = true; }
+          }
+          if (t.returnsAuthValue) for (const alias of resultAliases(node.body, callee)) {
+            if (!node.authValues.has(alias)) { node.authValues.add(alias); changed = true; }
+          }
+          if (directReturnCall(node.body, callee)) {
+            if (t.returnsAuthValue && !node.returnsAuthValue) { node.returnsAuthValue = true; changed = true; }
+            for (const key of t.denialKeys) if (!node.denialKeys.has(key)) { node.denialKeys.add(key); changed = true; }
+          }
+        }
+      }
+      if (throwsOnMissingAuth(node.body, node.authValues, node.denialCalls) && !node.failsClosed) { node.failsClosed = true; changed = true; }
+      for (const key of denialResultKeys(node.body, node.authValues)) if (!node.denialKeys.has(key)) { node.denialKeys.add(key); changed = true; }
+      if ([...node.authValues].some((name) => directReturnName(node.body, name)) && !node.returnsAuthValue) { node.returnsAuthValue = true; changed = true; }
+    }
+    if (!changed) break;
+  }
+  const helpers = nodes
+    .filter((node) => node.exported && node.dist <= maxDepth && !DENY.has(node.name) && IDENT.test(node.name) && !/^[A-Z]/.test(node.name))
+    .map((node) => ({ name: node.name, file: node.file, depth: node.dist, exports: node.exports, failsClosed: node.failsClosed, returnsAuthValue: node.returnsAuthValue, denialKeys: [...node.denialKeys] }));
+  return { helpers: helpers.sort((a, b) => a.name.localeCompare(b.name) || a.file.localeCompare(b.file)), indexedFiles: indexed, candidateFiles: candidates.length, capped: candidates.length > files.length, authRpcs };
+}
+
+/** Names that are safe to put in a regex alternation: identifiers only, `$` escaped. */
+export const regexNames = (names) => [...new Set(names)].filter((n) => IDENT.test(n) && !DENY.has(n)).sort().map((n) => n.replace(/\$/g, '\\$'));
+
+/**
+ * Copies the vsg rule files to outDir with the sentinel in the auth-name regexes replaced by the extra names (the originals are never edited).
+ * Only .yaml rule files are copied. Returns the number of rule files that were changed.
+ */
+export function writeRulesWithHelpers(srcDir, outDir, names) {
+  const alt = regexNames(names).join('|');
+  fs.mkdirSync(outDir, { recursive: true });
+  let changed = 0;
+  for (const f of fs.readdirSync(srcDir).filter((x) => /\.ya?ml$/.test(x))) {
+    const text = fs.readFileSync(path.join(srcDir, f), 'utf8');
+    const next = text.includes(SENTINEL) ? text.split(SENTINEL).join(alt ? `${alt}|${SENTINEL}` : SENTINEL) : text;
+    if (next !== text) changed++;
+    fs.writeFileSync(path.join(outDir, f), next);
+  }
+  return changed;
+}