@agent-native/core 0.95.1 → 0.97.0

package/corpus/core/src/code-agents/transcript-normalizer.ts

@@ -61,6 +61,16 @@ export interface NormalizedCodeAgentToolEvent extends NormalizedCodeAgentTranscr
    * it.  Absent on old transcript events — UI must handle both cases.
    */
   structuredMeta?: Record<string, unknown>;
+  /**
+   * Stable approval id extracted from the synthetic "Approval required..."
+   * bash result (see `requestCodeAgentApproval` in `cli/code-agent-executor.ts`)
+   * when this exact approval has not yet been resolved elsewhere in the
+   * transcript (approved / denied / allowlisted / forbidden). Consumers attach
+   * this as `approval: { approvalKey }` on the rendered tool-call content part
+   * so the shared `ApprovalAffordance` can render inline. Absent once a later
+   * transcript event records a resolution for this approval id.
+   */
+  pendingApprovalKey?: string;
 }
 
 export interface NormalizedCodeAgentStatusEvent extends NormalizedCodeAgentTranscriptBase {
@@ -70,6 +80,7 @@ export interface NormalizedCodeAgentStatusEvent extends NormalizedCodeAgentTrans
   statusKind: CodeAgentTranscriptEvent["kind"];
   status?: string;
   phase?: string;
+  signal?: CodeAgentTranscriptEvent["signal"];
   metadata?: Record<string, unknown>;
 }
 
@@ -82,6 +93,35 @@ export interface NormalizedCodeAgentThinkingEvent extends NormalizedCodeAgentTra
   text: string;
 }
 
+/** Structured signal value stamped on the "no LLM provider key" status event. */
+export const CREDENTIAL_GAP_SIGNAL: NonNullable<
+  CodeAgentTranscriptEvent["signal"]
+> = "credential-gap";
+
+/**
+ * Shared "credential gap" detection for code-agent transcript events and the
+ * normalized status items built from them. Prefers the structured `signal`
+ * field the executor stamps on the event (see `code-agent-executor.ts`); only
+ * falls back to matching the legacy hint text for transcripts persisted
+ * before the structured signal existed. Accepts either a raw
+ * `CodeAgentTranscriptEvent` (`message`) or a `NormalizedCodeAgentStatusEvent`
+ * (`text`), and any of the other UI-facing transcript event shapes that carry
+ * the same field names, so every consumer can share one implementation
+ * instead of re-implementing the regex.
+ */
+export function isCredentialGapCodeAgentEvent(event: {
+  signal?: string;
+  text?: string;
+  message?: string;
+}): boolean {
+  if (event.signal === CREDENTIAL_GAP_SIGNAL) return true;
+  return isLegacyCredentialGapHintText(event.text ?? event.message ?? "");
+}
+
+function isLegacyCredentialGapHintText(value: string): boolean {
+  return /No LLM provider key was found|Missing credentials/i.test(value);
+}
+
 export function normalizeCodeAgentTranscript(
   events: readonly CodeAgentTranscriptEvent[],
 ): NormalizedCodeAgentTranscript {
@@ -148,6 +188,7 @@ export function normalizeCodeAgentTranscript(
   hiddenEvents.sort(
     (a, b) => (eventOrder.get(a.id) ?? 0) - (eventOrder.get(b.id) ?? 0),
   );
+  applyPendingCodeAgentApprovalKeys(dedupedItems, events);
 
   return {
     items: dedupedItems,
@@ -156,6 +197,40 @@ export function normalizeCodeAgentTranscript(
   };
 }
 
+/**
+ * Stamp `pendingApprovalKey` onto completed bash tool events whose synthetic
+ * result carries an "Approval id: {id}" marker (see `requestCodeAgentApproval`
+ * in `cli/code-agent-executor.ts`), unless a later raw event already recorded
+ * a resolution for that same id (approved / denied / allowlisted-and-run /
+ * forbidden — all stamp `metadata.approvalId`).
+ *
+ * Resolution lookup scans the *raw* event stream rather than the normalized
+ * items: resolution status events are intentionally low-signal (they read as
+ * "status: running") and get folded into `hiddenEvents` by
+ * `isLowSignalLifecycleEvent`, so they would not otherwise be visible here.
+ */
+function applyPendingCodeAgentApprovalKeys(
+  items: NormalizedCodeAgentTranscriptItem[],
+  events: readonly CodeAgentTranscriptEvent[],
+): void {
+  const resolvedApprovalIds = new Set<string>();
+  for (const event of events) {
+    const approvalId = stringMetadata(event.metadata, "approvalId");
+    if (approvalId) resolvedApprovalIds.add(approvalId);
+  }
+  for (const item of items) {
+    if (item.type !== "tool" || item.state !== "completed") continue;
+    if (typeof item.result !== "string") continue;
+    const match = CODE_AGENT_APPROVAL_ID_RESULT_PATTERN.exec(item.result);
+    const id = match?.[1];
+    if (id && !resolvedApprovalIds.has(id)) {
+      item.pendingApprovalKey = id;
+    }
+  }
+}
+
+const CODE_AGENT_APPROVAL_ID_RESULT_PATTERN = /Approval id:\s*(\S+)/;
+
 function createUserTurn(
   event: CodeAgentTranscriptEvent,
   turnIndex: number,
@@ -253,6 +328,7 @@ function createStatusEvent(
     statusKind: event.kind,
     status: stringMetadata(metadata, "status"),
     phase: stringMetadata(metadata, "phase"),
+    signal: event.signal,
     metadata,
     createdAt: event.createdAt,
     updatedAt: event.createdAt,

package/corpus/core/src/deploy/build.ts

@@ -32,7 +32,6 @@ import { normalizeAppBasePath } from "../server/app-base-path.js";
 import {
   DEFAULT_SSR_CDN_CACHE_CONTROL,
   DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL,
-  DEFAULT_SSR_NETLIFY_VARY,
   DEFAULT_SPECULATION_RULES_PATH,
   DEFAULT_SSR_CACHE_CONTROL,
 } from "../shared/cache-control.js";
@@ -909,7 +908,6 @@ function injectHeadScript(html, script) {
 const DEFAULT_SSR_CACHE_CONTROL = ${JSON.stringify(DEFAULT_SSR_CACHE_CONTROL)};
 const DEFAULT_SSR_CDN_CACHE_CONTROL = ${JSON.stringify(DEFAULT_SSR_CDN_CACHE_CONTROL)};
 const DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL = ${JSON.stringify(DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL)};
-const DEFAULT_SSR_NETLIFY_VARY = ${JSON.stringify(DEFAULT_SSR_NETLIFY_VARY)};
 const DEFAULT_SPECULATION_RULES_PATH = ${JSON.stringify(DEFAULT_SPECULATION_RULES_PATH)};
 const IMMUTABLE_ASSET_CACHE_CONTROL = ${JSON.stringify(IMMUTABLE_ASSET_CACHE_CONTROL)};
 const IMMUTABLE_ASSET_PATHS = new Set(${JSON.stringify(
@@ -986,17 +984,21 @@ function isSsrHtmlOrDataResponse(headers, status, pathname) {
 /**
  * Apply the SSR cache policy to the response headers.
  *
- * SSR IS A PUBLIC, HARD-CDN-CACHED SHELL — SERVED IDENTICALLY TO EVERYONE.
- * Every SSR HTML / React Router .data response gets the same public
- * stale-while-revalidate policy for ALL visitors, authenticated or not. The SSR
- * output is impersonal (the handler never reads the request's session/cookies),
- * so it is safe to hard-cache one shared copy at the edge. Do NOT reintroduce
- * per-user / cookie-based cache variation here (no private, no no-store, no
- * "authenticated then don't cache" branch) — that makes every logged-in
- * visitor's pages uncacheable. Per-user state is resolved client-side instead.
+ * Unannotated SSR HTML and React Router .data responses share a public
+ * stale-while-revalidate cache policy. Preserve an explicit route policy,
+ * though: token-gated and personalized routes can opt out with private or
+ * no-store policies.
  */
 function applyDefaultSsrCacheHeader(headers, status, pathname) {
   if (!isSsrHtmlOrDataResponse(headers, status, pathname)) return;
+  // React Router marks every .data response as no-cache, but those loader
+  // payloads are safe to cache at the shared edge. Preserve only explicit
+  // private/no-store policies, which token-gated and personalized routes use
+  // to opt out of shared caching.
+  const cacheControl = headers.get("cache-control")?.toLowerCase() ?? "";
+  if (cacheControl.includes("private") || cacheControl.includes("no-store")) {
+    return;
+  }
 
   headers.set("cache-control", DEFAULT_SSR_CACHE_CONTROL);
   headers.set("cdn-cache-control", DEFAULT_SSR_CDN_CACHE_CONTROL);
@@ -1005,7 +1007,6 @@ function applyDefaultSsrCacheHeader(headers, status, pathname) {
   // Netlify-specific header so SSR HTML/.data are served from the shared
   // durable CDN cache instead of stampeding origin — for every visitor.
   headers.set("netlify-cdn-cache-control", DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL);
-  headers.set("netlify-vary", DEFAULT_SSR_NETLIFY_VARY);
 }
 
 function applyDefaultSpeculationRulesHeader(headers, status, basePath) {

package/corpus/core/src/guards/db-tool-scoping.ts

@@ -0,0 +1,129 @@
+/**
+ * scanDbToolScoping — ported from `scripts/guard-db-tool-scoping.mjs`.
+ *
+ * The agent's raw DB tools (`db-query`, `db-exec`, `db-patch`) can only
+ * safely expose tables with an explicit tenant scope (`owner_email` and/or
+ * `org_id`) or a documented, reviewed exception. This guard keeps schema
+ * drift visible: any table without raw-DB scope must either add
+ * `owner_email`/`org_id`, or be added to the denylist with a
+ * reviewer-readable reason.
+ *
+ * Conditional guard — per report 005's V1 guard set table: the original
+ * walks every `templates/*\/server/db/schema.ts` and keys its denylist
+ * `"<template>:<table>"`. A generated app has exactly one
+ * `server/db/schema.ts` (confirmed convention), so this port scans that
+ * single file and uses bare `"<table>"` denylist keys. The denylist itself
+ * comes from `agent-native.json`'s `doctor.dbToolScopingDenylist` (see
+ * `../cli/doctor.ts`) — empty by default; app authors add entries with the
+ * same reviewer-readable-reason convention as the original constant.
+ *
+ * Not ported: the original also resolves `export * from
+ * "@agent-native/<pkg>/schema"` re-exports back to that package's
+ * `packages/<pkg>/src/schema/*.ts` monorepo source, so template schemas
+ * that re-export scheduling/dispatch tables get scanned too. In a
+ * generated app those packages are compiled `node_modules` output (no
+ * `.ts` source to brace-parse), and report 005's parameterization note
+ * doesn't cover that case, so re-export resolution is intentionally
+ * dropped for app mode: a re-exported table from an `@agent-native/*`
+ * package is not scanned here (false-negative, not false-positive) — see
+ * the plan's STOP-condition guidance ("report rather than invent new
+ * detection logic").
+ */
+
+import { readFileSafe, relPosix, walk } from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+export interface DbToolScopingOptions extends GuardScanOptions {
+  /** Table name -> reviewer-readable reason. Default `{}`. */
+  denylist?: Record<string, string>;
+}
+
+interface TableCall {
+  exportName: string;
+  sqlName: string;
+  body: string;
+}
+
+function extractTableCalls(contents: string): TableCall[] {
+  const out: TableCall[] = [];
+  const headerRegex =
+    /export\s+const\s+([a-zA-Z_$][\w$]*)\s*=\s*(?:[a-zA-Z_$][\w$]*Table|table)\s*\(\s*"([^"]+)"\s*,\s*\{/gm;
+  let match: RegExpExecArray | null;
+  while ((match = headerRegex.exec(contents)) !== null) {
+    const exportName = match[1];
+    const sqlName = match[2];
+    const start = headerRegex.lastIndex - 1;
+    let depth = 0;
+    let inStr: string | null = null;
+    let bodyEnd = -1;
+    for (let i = start; i < contents.length; i++) {
+      const c = contents[i];
+      const prev = contents[i - 1];
+      if (inStr) {
+        if (c === inStr && prev !== "\\") inStr = null;
+        continue;
+      }
+      if (c === '"' || c === "'" || c === "`") {
+        inStr = c;
+        continue;
+      }
+      if (c === "{") depth++;
+      else if (c === "}") {
+        depth--;
+        if (depth === 0) {
+          bodyEnd = i;
+          break;
+        }
+      }
+    }
+    if (bodyEnd === -1) continue;
+    out.push({ exportName, sqlName, body: contents.slice(start + 1, bodyEnd) });
+  }
+  return out;
+}
+
+function hasRawDbScope(tableBody: string): boolean {
+  return (
+    /\.\.\.ownableColumns\s*\(/.test(tableBody) ||
+    /\b[\w$]+\s*:\s*text\s*\(\s*["']owner_email["']/.test(tableBody) ||
+    /\b[\w$]+\s*:\s*text\s*\(\s*["']org_id["']/.test(tableBody)
+  );
+}
+
+export function scanDbToolScoping(options: DbToolScopingOptions): GuardResult {
+  const { root, denylist = {} } = options;
+  const findings: GuardFinding[] = [];
+  const seenAllowed = new Set<string>();
+
+  for (const file of walk(root)) {
+    if (!file.endsWith("/server/db/schema.ts")) continue;
+    const contents = readFileSafe(file);
+    if (contents === null) continue;
+    const rel = relPosix(root, file);
+    const tables = extractTableCalls(contents);
+    for (const table of tables) {
+      if (hasRawDbScope(table.body)) continue;
+      if (Object.hasOwn(denylist, table.sqlName)) {
+        seenAllowed.add(table.sqlName);
+        continue;
+      }
+      findings.push({
+        file: rel,
+        line: 1,
+        message: `Table "${table.sqlName}" (export ${table.exportName}) has no owner_email/org_id scope and is not on the doctor.dbToolScopingDenylist — add tenant scope, or add it to agent-native.json's "doctor.dbToolScopingDenylist" with a reason.`,
+      });
+    }
+  }
+
+  for (const key of Object.keys(denylist)) {
+    if (!seenAllowed.has(key)) {
+      findings.push({
+        file: "agent-native.json",
+        line: 1,
+        message: `Stale doctor.dbToolScopingDenylist entry "${key}" — no matching table found in server/db/schema.ts. Remove it.`,
+      });
+    }
+  }
+
+  return { name: "db-tool-scoping", findings };
+}

package/corpus/core/src/guards/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `agent-native doctor`'s guard functions — the source-code safety
+ * invariants ported from this monorepo's `scripts/guard-*.mjs` CI guards
+ * (see report `advisor-plans/reports/005-doctor-design.md` for the
+ * classification and per-guard parameterization). Each guard is a pure,
+ * synchronous function that scans an app root and returns a `GuardResult`.
+ *
+ * `../cli/doctor.ts` is the only in-package caller; this module is also
+ * published under the `./guards` export subpath for advanced/CI use
+ * outside the CLI.
+ */
+
+export { scanDbToolScoping } from "./db-tool-scoping.js";
+export type { DbToolScopingOptions } from "./db-tool-scoping.js";
+export { scanDrizzlePush } from "./no-drizzle-push.js";
+export { scanEnvCredentials } from "./no-env-credentials.js";
+export { scanEnvMutation } from "./no-env-mutation.js";
+export { scanLocalhostFallback } from "./no-localhost-fallback.js";
+export type { LocalhostFallbackOptions } from "./no-localhost-fallback.js";
+export { scanUnscopedCredentials } from "./no-unscoped-credentials.js";
+export { scanUnscopedQueries } from "./no-unscoped-queries.js";
+export type { UnscopedQueriesOptions } from "./no-unscoped-queries.js";
+export type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";

package/corpus/core/src/guards/no-drizzle-push.ts

@@ -0,0 +1,116 @@
+/**
+ * scanDrizzlePush — ported from `scripts/guard-no-drizzle-push.mjs`.
+ *
+ * Refuse to let `drizzle-kit push` (or `drizzle push`) get wired into any
+ * build/deploy path (`netlify.toml`, or a `package.json` build/deploy
+ * script). Generic guard — no monorepo-specific path assumption in the
+ * original, ported as-is.
+ *
+ * Standalone `db:push` / `db:push:*` npm scripts are intentionally NOT
+ * flagged — those are explicit, human-invoked commands, not build hooks.
+ */
+
+import {
+  lineColForOffset,
+  readFileSafe,
+  relPosix,
+  walk,
+} from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+const DANGEROUS_SCRIPT_HOOKS = new Set([
+  "build",
+  "prebuild",
+  "postbuild",
+  "install",
+  "preinstall",
+  "postinstall",
+  "deploy",
+  "predeploy",
+  "postdeploy",
+  "start",
+  "prestart",
+  "poststart",
+  "ci",
+  "release",
+  "prerelease",
+  "postrelease",
+]);
+
+const PATTERNS = [/\bdrizzle-kit\s+push\b/, /\bdrizzle\s+push\b/];
+
+function matchesForbidden(str: unknown): str is string {
+  if (!str || typeof str !== "string") return false;
+  return PATTERNS.some((p) => p.test(str));
+}
+
+interface PackageJsonLike {
+  scripts?: Record<string, unknown>;
+}
+
+export function scanDrizzlePush(options: GuardScanOptions): GuardResult {
+  const { root } = options;
+  const findings: GuardFinding[] = [];
+
+  for (const file of walk(root)) {
+    const base = file.split("/").pop() ?? file;
+    if (base === "netlify.toml") {
+      scanNetlifyToml(root, file, findings);
+    } else if (base === "package.json") {
+      scanPackageJson(root, file, findings);
+    }
+  }
+
+  return { name: "no-drizzle-push", findings };
+}
+
+function scanNetlifyToml(
+  root: string,
+  file: string,
+  findings: GuardFinding[],
+): void {
+  const contents = readFileSafe(file);
+  if (contents === null || !matchesForbidden(contents)) return;
+  const lines = contents.split("\n");
+  const rel = relPosix(root, file);
+  for (let i = 0; i < lines.length; i++) {
+    if (matchesForbidden(lines[i])) {
+      findings.push({
+        file: rel,
+        line: i + 1,
+        message: `forbidden \`drizzle-kit push\` in netlify.toml: ${lines[i].trim()}`,
+      });
+    }
+  }
+}
+
+function scanPackageJson(
+  root: string,
+  file: string,
+  findings: GuardFinding[],
+): void {
+  const contents = readFileSafe(file);
+  if (contents === null) return;
+  let json: PackageJsonLike;
+  try {
+    json = JSON.parse(contents) as PackageJsonLike;
+  } catch {
+    return;
+  }
+  const scripts = json.scripts;
+  if (!scripts || typeof scripts !== "object") return;
+  const rel = relPosix(root, file);
+  for (const [name, cmd] of Object.entries(scripts)) {
+    if (!DANGEROUS_SCRIPT_HOOKS.has(name)) continue;
+    if (matchesForbidden(cmd)) {
+      // Locate the line for a readable finding; fall back to line 1.
+      const idx = contents.indexOf(`"${name}"`);
+      const line = idx >= 0 ? lineColForOffset(contents, idx).line : 1;
+      findings.push({
+        file: rel,
+        line,
+        message: `forbidden \`drizzle-kit push\` in scripts.${name}: ${String(cmd)}`,
+      });
+    }
+  }
+}

package/corpus/core/src/guards/no-env-credentials.ts

@@ -0,0 +1,229 @@
+/**
+ * scanEnvCredentials — ported from `scripts/guard-no-env-credentials.mjs`.
+ *
+ * User credentials are per-user (or per-org) data. They MUST live in SQL,
+ * scoped by `userEmail` / `orgId`, never in `process.env` — a deployment's
+ * env vars are shared by every signed-in user. This guard flags any
+ * `process.env.<KEY>` / `process.env["KEY"]` read whose key is not on the
+ * deploy-level allowlist (`DATABASE_URL`, `BETTER_AUTH_SECRET`, etc.), plus
+ * any dynamic `process.env[key]` read (the key is only known at runtime, so
+ * it can never be allowlisted safely).
+ *
+ * Conditional guard — per report 005's V1 guard set table, this is "the big
+ * one": the original only scans a curated set of monorepo subtrees
+ * (`packages/core/src/{credentials,secrets,vault,agent}/`, template
+ * credential libs/routes) via `FORBIDDEN_PATH_PREDICATES` — none of which
+ * exist in a generated app, so nothing would ever be scanned. This port
+ * replaces that default-allow-outside-a-curated-subtree behavior with
+ * default-deny across the whole app source tree: every `process.env.<KEY>`
+ * read anywhere in app source must be on the deploy-var allowlist (kept
+ * verbatim) or carry the opt-out marker. `HIGH_RISK_ENV_KEY_ALLOWLIST`,
+ * `HIGH_RISK_PROCESS_ENV_ALLOWLIST`, and `HIGH_RISK_ENV_VARS_WRITE_ALLOWLIST`
+ * — the three monorepo-file-keyed exception maps for specific template
+ * platform-adapter files — are dropped entirely per the report; with
+ * default-deny scanning already covering every `process.env` read
+ * everywhere, the narrower `env-config.ts`/`core-routes.ts`-specific
+ * registration checks those maps supported become redundant (any
+ * high-risk key would already be caught by the general scan) and are
+ * dropped along with them. The per-line `// guard:allow-env-credential`
+ * marker remains the only escape hatch.
+ *
+ * Opt-out (same line, or the line immediately above):
+ *   process.env.SOMETHING // guard:allow-env-credential — short reason
+ */
+
+import {
+  lineColForOffset,
+  readFileSafe,
+  relPosix,
+  walk,
+} from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+const ALLOWLIST_EXACT = new Set([
+  "DATABASE_URL",
+  "DATABASE_AUTH_TOKEN",
+  "NODE_ENV",
+  "CI",
+  "DEBUG",
+  "NETLIFY",
+  "VERCEL",
+  "RENDER",
+  "FLY_APP_NAME",
+  "K_SERVICE",
+  "AWS_LAMBDA_FUNCTION_NAME",
+  "BETTER_AUTH_SECRET",
+  "BETTER_AUTH_URL",
+  "NOTION_CLIENT_ID",
+  "NOTION_CLIENT_SECRET",
+  "NOTION_STATE_SECRET",
+  "GOOGLE_SIGN_IN_CLIENT_ID",
+  "GOOGLE_SIGN_IN_CLIENT_SECRET",
+  "AUTH_SECRET",
+  "A2A_SECRET",
+  "ACCESS_TOKEN",
+  "PORT",
+  "HOST",
+  "SECRETS_ENCRYPTION_KEY",
+]);
+
+const ALLOWLIST_PREFIX = [
+  "npm_",
+  "AGENT_NATIVE_",
+  "AGENT_",
+  "NETLIFY_",
+  "VERCEL_",
+  "CF_",
+];
+
+/** Dev-only paths where ANTHROPIC_API_KEY etc. may legitimately be read
+ * from env (local dev tooling, scripts, tests). Portable subset of the
+ * original — the monorepo-only `packages/core/src/dev` predicate is
+ * dropped (see report 005's V1 guard set table). */
+const DEV_ONLY_PATH_PATTERNS = [
+  /\.spec\.[tj]sx?$/,
+  /\.test\.[tj]sx?$/,
+  /^scripts\//,
+];
+
+const DEV_ONLY_KEYS = new Set(["ANTHROPIC_API_KEY"]);
+
+const OPT_OUT_MARKER = /\/\/\s*guard:allow-env-credential\b[^\n]*/;
+const OPT_OUT_REQUIRES_REASON = /\/\/\s*guard:allow-env-credential\s*[—-]\s*\S/;
+
+const ENV_READ_REGEX =
+  /process\.env(?:\.([A-Z][A-Z0-9_]*)|\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\])/g;
+
+const ENV_DYNAMIC_READ_REGEX =
+  /process\.env(?:\?\.)?\s*\[\s*(?!["'])([^\]\n]+?)\s*\]/g;
+
+function isAllowlistedKey(key: string): boolean {
+  if (ALLOWLIST_EXACT.has(key)) return true;
+  return ALLOWLIST_PREFIX.some((prefix) => key.startsWith(prefix));
+}
+
+function isDevOnlyPath(rel: string): boolean {
+  return DEV_ONLY_PATH_PATTERNS.some((re) => re.test(rel));
+}
+
+function hasOptOutOnLine(lines: string[], lineIdx: number): boolean {
+  const cur = lines[lineIdx] ?? "";
+  if (OPT_OUT_MARKER.test(cur)) return true;
+  const prev = lines[lineIdx - 1] ?? "";
+  if (/^\s*\/\//.test(prev) && OPT_OUT_MARKER.test(prev)) return true;
+  return false;
+}
+
+function optOutOnLineIsValid(
+  lines: string[],
+  lineIdx: number,
+  key: string,
+  rel: string,
+): { ok: boolean; why?: string } {
+  const cur = lines[lineIdx] ?? "";
+  const prev = lines[lineIdx - 1] ?? "";
+  const candidate = OPT_OUT_REQUIRES_REASON.test(cur)
+    ? cur
+    : OPT_OUT_REQUIRES_REASON.test(prev)
+      ? prev
+      : null;
+  if (!candidate) return { ok: false, why: "missing or empty reason" };
+
+  if (/dev-only\b/i.test(candidate)) {
+    if (!DEV_ONLY_KEYS.has(key)) {
+      return {
+        ok: false,
+        why: `key "${key}" is not in the dev-only credential allowlist`,
+      };
+    }
+    if (!isDevOnlyPath(rel)) {
+      return {
+        ok: false,
+        why: "dev-only opt-out used outside dev / scripts / test paths",
+      };
+    }
+  }
+  return { ok: true };
+}
+
+export function scanEnvCredentials(options: GuardScanOptions): GuardResult {
+  const { root } = options;
+  const findings: GuardFinding[] = [];
+
+  for (const file of walk(root)) {
+    if (!/\.(ts|tsx|mts|cts|js|mjs|cjs)$/.test(file)) continue;
+    if (file.endsWith(".d.ts")) continue;
+    const rel = relPosix(root, file);
+
+    const contents = readFileSafe(file);
+    if (contents === null || !contents.includes("process.env")) continue;
+
+    const lines = contents.split("\n");
+
+    ENV_READ_REGEX.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = ENV_READ_REGEX.exec(contents)) !== null) {
+      const key = m[1] ?? m[2];
+      if (!key) continue;
+      const { line } = lineColForOffset(contents, m.index);
+      const lineIdx = line - 1;
+      const lineText = lines[lineIdx] ?? "";
+      const trimmed = lineText.trimStart();
+      if (
+        trimmed.startsWith("*") ||
+        trimmed.startsWith("//") ||
+        trimmed.startsWith("/*")
+      ) {
+        continue;
+      }
+      if (isAllowlistedKey(key)) continue;
+      if (hasOptOutOnLine(lines, lineIdx)) {
+        const verdict = optOutOnLineIsValid(lines, lineIdx, key, rel);
+        if (verdict.ok) continue;
+        findings.push({
+          file: rel,
+          line,
+          message: `process.env.${key} opt-out invalid: ${verdict.why}`,
+        });
+        continue;
+      }
+      findings.push({
+        file: rel,
+        line,
+        message: `process.env.${key} read — not a deploy-level allowlisted key. User credentials must be read via resolveCredential(key, { userEmail, orgId }), never process.env.`,
+      });
+    }
+
+    ENV_DYNAMIC_READ_REGEX.lastIndex = 0;
+    while ((m = ENV_DYNAMIC_READ_REGEX.exec(contents)) !== null) {
+      const { line } = lineColForOffset(contents, m.index);
+      const lineIdx = line - 1;
+      const lineText = lines[lineIdx] ?? "";
+      const trimmed = lineText.trimStart();
+      if (
+        trimmed.startsWith("*") ||
+        trimmed.startsWith("//") ||
+        trimmed.startsWith("/*")
+      ) {
+        continue;
+      }
+      if (hasOptOutOnLine(lines, lineIdx)) {
+        const verdict = optOutOnLineIsValid(lines, lineIdx, "<dynamic>", rel);
+        if (verdict.ok) continue;
+        findings.push({
+          file: rel,
+          line,
+          message: `process.env[<dynamic>] opt-out invalid: ${verdict.why}`,
+        });
+        continue;
+      }
+      findings.push({
+        file: rel,
+        line,
+        message: `process.env[<dynamic key>] read — dynamic keys can never be allowlisted safely.`,
+      });
+    }
+  }
+
+  return { name: "no-env-credentials", findings };
+}