@agent-native/core 0.95.1 → 0.97.0

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

@@ -0,0 +1,114 @@
+/**
+ * scanEnvMutation — ported from `scripts/guard-no-env-mutation.mjs`.
+ *
+ * Refuse to let production code MUTATE `process.env` (e.g.
+ * `process.env.AGENT_USER_EMAIL = userEmail`). `process.env` is
+ * process-scoped, not request-scoped — on serverless, every warm container
+ * handles many concurrent requests in one Node process, so mutating
+ * `process.env` in a request handler leaks state across requests. Use
+ * `runWithRequestContext` instead.
+ *
+ * Conditional guard — per report 005's V1 guard set table: the original
+ * has 9 `ALLOWED_PATH_PREDICATES`; 4 are monorepo-only
+ * (`packages/core/src/dev`, `templates/*\/test(s)/`, `packages/cli/`,
+ * `packages/create-agent-native/`) and dropped here. The 5 portable ones
+ * (`scripts/**`, `*.spec.*`, `*.test.*`, `/cli/`, `/scaffold/`) are kept
+ * verbatim — they already work unmodified for a generated app.
+ *
+ * Opt-out (same line, or the line immediately above):
+ *   process.env.X = y // guard:allow-env-mutation — short reason
+ */
+
+import {
+  isCommentLine,
+  lineColForOffset,
+  readFileSafe,
+  relPosix,
+  walk,
+} from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+const ALLOWED_PATH_PREDICATES: Array<(rel: string) => boolean> = [
+  (rel) => /^scripts\//.test(rel),
+  (rel) => /\.spec\.[tj]sx?$/.test(rel),
+  (rel) => /\.test\.[tj]sx?$/.test(rel),
+  (rel) => /\/cli\//.test(rel),
+  (rel) => /\/scaffold\//.test(rel),
+];
+
+const OPT_OUT_MARKER = /\/\/\s*guard:allow-env-mutation\b[^\n]*/;
+const OPT_OUT_REQUIRES_REASON = /\/\/\s*guard:allow-env-mutation\s*[—-]\s*\S/;
+
+const ASSIGN_TAIL = String.raw`(?:\s*(?:=(?!=)|\+=|-=|\*=|/=|\?\?=|\|\|=|&&=))`;
+const MEMBER_FORM = new RegExp(
+  String.raw`process\.env\.[A-Z_][A-Z0-9_]*${ASSIGN_TAIL}`,
+  "g",
+);
+const BRACKET_FORM = new RegExp(
+  String.raw`process\.env\[\s*["'][A-Z_][A-Z0-9_]+["']\s*\]${ASSIGN_TAIL}`,
+  "g",
+);
+const DELETE_MEMBER_FORM = new RegExp(
+  String.raw`\bdelete\s+process\.env\.[A-Z_][A-Z0-9_]*\b`,
+  "g",
+);
+const DELETE_BRACKET_FORM = new RegExp(
+  String.raw`\bdelete\s+process\.env\[\s*["'][A-Z_][A-Z0-9_]+["']\s*\]`,
+  "g",
+);
+
+function isAllowedPath(rel: string): boolean {
+  return ALLOWED_PATH_PREDICATES.some((p) => p(rel));
+}
+
+function hasValidOptOut(lines: string[], lineIdx: number): boolean {
+  const cur = lines[lineIdx] ?? "";
+  if (OPT_OUT_MARKER.test(cur)) {
+    return OPT_OUT_REQUIRES_REASON.test(cur);
+  }
+  const prev = lines[lineIdx - 1] ?? "";
+  if (/^\s*\/\//.test(prev) && OPT_OUT_MARKER.test(prev)) {
+    return OPT_OUT_REQUIRES_REASON.test(prev);
+  }
+  return false;
+}
+
+export function scanEnvMutation(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);
+    if (isAllowedPath(rel)) continue;
+
+    const contents = readFileSafe(file);
+    if (contents === null || !contents.includes("process.env")) continue;
+
+    const lines = contents.split("\n");
+
+    for (const re of [
+      MEMBER_FORM,
+      BRACKET_FORM,
+      DELETE_MEMBER_FORM,
+      DELETE_BRACKET_FORM,
+    ]) {
+      re.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = re.exec(contents)) !== null) {
+        const { line } = lineColForOffset(contents, m.index);
+        const lineText = lines[line - 1] ?? "";
+        if (isCommentLine(lineText)) continue;
+        if (hasValidOptOut(lines, line - 1)) continue;
+        findings.push({
+          file: rel,
+          line,
+          message: `process.env mutated in production code: ${lineText.trim()}. process.env is process-scoped, not request-scoped — use runWithRequestContext instead.`,
+        });
+      }
+    }
+  }
+
+  return { name: "no-env-mutation", findings };
+}

package/corpus/core/src/guards/no-localhost-fallback.ts

@@ -0,0 +1,124 @@
+/**
+ * scanLocalhostFallback — ported from
+ * `scripts/guard-no-localhost-fallback.mjs`.
+ *
+ * Refuse to let production code use the literal `local@localhost` (or the
+ * `DEV_MODE_USER_EMAIL` symbolic alias) as a fallback identity when no
+ * session is present — that pools every unauthenticated request onto one
+ * shared tenant. The right behavior in production is to throw/401 when
+ * there's no session, not fall back to a sentinel identity.
+ *
+ * Conditional guard — per report 005's V1 guard set table: the original
+ * hardcodes framework-file exemptions (`packages/core/src/server/auth.ts`,
+ * `packages/core/src/org/context.ts`, etc. — files that either define or
+ * intentionally handle the dev-mode sentinel). Those live in `node_modules`
+ * for a generated app and are already excluded by `SKIP_DIRS`, so they're
+ * moved behind an optional `extraExemptPaths` param (default `[]`) instead
+ * of hardcoded. The generic allowlist predicates (`*.spec.*`, `*.test.*`,
+ * `scripts/**`, `**\/seed(s)/**`) are kept verbatim.
+ *
+ * Opt-out (same line, or the line immediately above):
+ *   const x = email ?? "local@localhost" // guard:allow-localhost-fallback — short reason
+ */
+
+import {
+  isCommentLine,
+  lineColForOffset,
+  readFileSafe,
+  relPosix,
+  walk,
+} from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+export interface LocalhostFallbackOptions extends GuardScanOptions {
+  /** Exact repo-relative paths to exempt in addition to the generic
+   * predicates (spec/test/scripts/seed). Default `[]`. */
+  extraExemptPaths?: string[];
+}
+
+const GENERIC_ALLOWED_PATH_PREDICATES: Array<(rel: string) => boolean> = [
+  (rel) => /\.spec\.[tj]sx?$/.test(rel),
+  (rel) => /\.test\.[tj]sx?$/.test(rel),
+  (rel) => /^scripts\//.test(rel),
+  (rel) => /\/seed\//.test(rel),
+  (rel) => /\/seeds\//.test(rel),
+];
+
+const OPT_OUT_MARKER = /\/\/\s*guard:allow-localhost-fallback\b[^\n]*/;
+const OPT_OUT_REQUIRES_REASON =
+  /\/\/\s*guard:allow-localhost-fallback\s*[—-]\s*\S/;
+
+const LITERAL_RE = /(?:"local@localhost"|'local@localhost'|`local@localhost`)/g;
+
+const SYMBOLIC_FALLBACK_RE = /(?:\?\?|\|\|)\s*DEV_MODE_USER_EMAIL\b/g;
+
+const SQL_DEFAULT_RE = /\bDEFAULT\s+['"`]local@localhost['"`]/i;
+const DRIZZLE_DEFAULT_RE = /\.default\s*\(\s*['"`]local@localhost['"`]\s*\)/;
+
+function isAllowedPath(rel: string, extraExemptPaths?: string[]): boolean {
+  if (extraExemptPaths?.includes(rel)) return true;
+  return GENERIC_ALLOWED_PATH_PREDICATES.some((p) => p(rel));
+}
+
+function hasValidOptOut(lines: string[], lineIdx: number): boolean {
+  const cur = lines[lineIdx] ?? "";
+  if (OPT_OUT_MARKER.test(cur)) {
+    return OPT_OUT_REQUIRES_REASON.test(cur);
+  }
+  const prev = lines[lineIdx - 1] ?? "";
+  if (/^\s*\/\//.test(prev) && OPT_OUT_MARKER.test(prev)) {
+    return OPT_OUT_REQUIRES_REASON.test(prev);
+  }
+  return false;
+}
+
+export function scanLocalhostFallback(
+  options: LocalhostFallbackOptions,
+): GuardResult {
+  const { root, extraExemptPaths } = 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);
+    if (isAllowedPath(rel, extraExemptPaths)) continue;
+
+    const contents = readFileSafe(file);
+    if (contents === null || !contents.includes("local@localhost")) continue;
+
+    const lines = contents.split("\n");
+
+    LITERAL_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = LITERAL_RE.exec(contents)) !== null) {
+      const { line } = lineColForOffset(contents, m.index);
+      const lineText = lines[line - 1] ?? "";
+      if (isCommentLine(lineText)) continue;
+      if (SQL_DEFAULT_RE.test(lineText)) continue;
+      if (DRIZZLE_DEFAULT_RE.test(lineText)) continue;
+      if (hasValidOptOut(lines, line - 1)) continue;
+      findings.push({
+        file: rel,
+        line,
+        message: `"local@localhost" used as a fallback identity: ${lineText.trim()}. Throw/401 on missing session instead — this pools every unauthenticated request onto one shared tenant.`,
+      });
+    }
+
+    SYMBOLIC_FALLBACK_RE.lastIndex = 0;
+    let s: RegExpExecArray | null;
+    while ((s = SYMBOLIC_FALLBACK_RE.exec(contents)) !== null) {
+      const { line } = lineColForOffset(contents, s.index);
+      const lineText = lines[line - 1] ?? "";
+      if (isCommentLine(lineText)) continue;
+      if (hasValidOptOut(lines, line - 1)) continue;
+      findings.push({
+        file: rel,
+        line,
+        message: `DEV_MODE_USER_EMAIL used as a fallback identity: ${lineText.trim()}. Throw/401 on missing session instead.`,
+      });
+    }
+  }
+
+  return { name: "no-localhost-fallback", findings };
+}

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

@@ -0,0 +1,227 @@
+/**
+ * scanUnscopedCredentials — ported from
+ * `scripts/guard-no-unscoped-credentials.mjs`.
+ *
+ * Refuse to let any caller invoke `resolveCredential` / `hasCredential` /
+ * `saveCredential` / `deleteCredential` with only one argument. The
+ * contract requires a second argument carrying the per-user / per-org
+ * context object — `(key, { userEmail, orgId })` — so the credential
+ * lookup is scoped to the requesting principal.
+ *
+ * Generic guard, shipped as-is: the detection regex, arg-balancing parser,
+ * and marker semantics are unchanged from the monorepo original. The one
+ * difference from the monorepo script is scan scope: the original restricts
+ * its walk to `packages/`, `templates/`, `app/` — a monorepo-specific
+ * optimization that also happens to exclude its own dotfile/doc trees. A
+ * generated app's source lives at `actions/`, `app/`, `server/` (no
+ * `packages/`/`templates/` wrapper — see report 005's "Path resolution"),
+ * so keeping that literal subtree filter would silently skip `actions/`
+ * and `server/`. This port scans the whole app root (still respecting
+ * `SKIP_DIRS`) instead, which is a superset of the original's coverage and
+ * has no false-negative risk for a single-app tree.
+ *
+ * Opt-out (same line only):
+ *   resolveCredential(key) // guard:allow-unscoped-credential — short reason
+ */
+
+import {
+  lineColForOffset,
+  readFileSafe,
+  relPosix,
+  walk,
+} from "./scan-utils.js";
+import type { GuardFinding, GuardResult, GuardScanOptions } from "./types.js";
+
+const FUNCTIONS = [
+  "resolveCredential",
+  "hasCredential",
+  "saveCredential",
+  "deleteCredential",
+];
+
+const FUNC_NAME_RE = new RegExp(
+  `(?<![\\w$.])(${FUNCTIONS.join("|")})\\s*\\(`,
+  "g",
+);
+
+const OPT_OUT_MARKER =
+  /\/\/\s*guard:allow-unscoped-credential\b[^\n]*[—-]\s*\S/;
+
+/** Files that legitimately use the one-arg form because they ARE the
+ * implementation under guard — the definition file itself. In an app this
+ * file only ever exists inside `node_modules`, already excluded by
+ * SKIP_DIRS, so this allowlist is effectively a no-op for app mode; kept
+ * for parity with the source guard. */
+const FILE_ALLOWLIST = new Set(["packages/core/src/credentials/index.ts"]);
+
+interface ArgAnalysis {
+  topLevelCommas: number;
+  endIdx: number;
+}
+
+/**
+ * Starting at openParenIdx (the index of the `(` after the function name),
+ * walk forward, balancing nested parens / braces / brackets / strings, and
+ * return the top-level comma count. Ported verbatim.
+ */
+function analyzeArgs(
+  contents: string,
+  openParenIdx: number,
+): ArgAnalysis | null {
+  let depth = 0;
+  let topLevelCommas = 0;
+  let i = openParenIdx;
+  let mode: "code" | '"' | "'" | "tmpl" = "code";
+  let templateDepth = 0;
+  while (i < contents.length) {
+    const ch = contents[i];
+    const next = contents[i + 1];
+    if (mode === "code") {
+      if (ch === "/" && next === "/") {
+        while (i < contents.length && contents[i] !== "\n") i++;
+        continue;
+      }
+      if (ch === "/" && next === "*") {
+        i += 2;
+        while (
+          i < contents.length - 1 &&
+          !(contents[i] === "*" && contents[i + 1] === "/")
+        )
+          i++;
+        i += 2;
+        continue;
+      }
+      if (ch === '"' || ch === "'") {
+        mode = ch;
+        i++;
+        continue;
+      }
+      if (ch === "`") {
+        mode = "tmpl";
+        i++;
+        continue;
+      }
+      if (ch === "(" || ch === "[" || ch === "{") {
+        depth++;
+        i++;
+        continue;
+      }
+      if (ch === ")" || ch === "]" || ch === "}") {
+        depth--;
+        if (depth === 0 && ch === ")") {
+          return { topLevelCommas, endIdx: i };
+        }
+        i++;
+        continue;
+      }
+      if (ch === "," && depth === 1) {
+        topLevelCommas++;
+        i++;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (mode === '"' || mode === "'") {
+      if (ch === "\\") {
+        i += 2;
+        continue;
+      }
+      if (ch === mode) {
+        mode = "code";
+        i++;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (mode === "tmpl") {
+      if (ch === "\\") {
+        i += 2;
+        continue;
+      }
+      if (ch === "`" && templateDepth === 0) {
+        mode = "code";
+        i++;
+        continue;
+      }
+      if (ch === "$" && next === "{") {
+        templateDepth++;
+        i += 2;
+        continue;
+      }
+      if (ch === "}" && templateDepth > 0) {
+        templateDepth--;
+        i++;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    i++;
+  }
+  return null;
+}
+
+export function scanUnscopedCredentials(
+  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);
+    if (FILE_ALLOWLIST.has(rel)) continue;
+
+    const contents = readFileSafe(file);
+    if (contents === null) continue;
+
+    let anyHit = false;
+    for (const fn of FUNCTIONS) {
+      if (contents.includes(fn + "(") || contents.includes(fn + " (")) {
+        anyHit = true;
+        break;
+      }
+    }
+    if (!anyHit) continue;
+
+    const lines = contents.split("\n");
+    FUNC_NAME_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = FUNC_NAME_RE.exec(contents)) !== null) {
+      const fnName = m[1];
+      const openParenIdx = m.index + m[0].length - 1;
+      const before = contents.slice(Math.max(0, m.index - 30), m.index);
+      if (
+        /\bfunction\s+$/.test(before) ||
+        /\bexport\s+(default\s+)?(async\s+)?function\s+$/.test(before) ||
+        /\b(const|let|var)\s+$/.test(before)
+      ) {
+        continue;
+      }
+      const { line } = lineColForOffset(contents, m.index);
+      const lineText = lines[line - 1] ?? "";
+      const trimmed = lineText.trimStart();
+      if (
+        trimmed.startsWith("*") ||
+        trimmed.startsWith("//") ||
+        trimmed.startsWith("/*")
+      ) {
+        continue;
+      }
+      const analysis = analyzeArgs(contents, openParenIdx);
+      if (!analysis) continue;
+      if (analysis.topLevelCommas >= 1) continue;
+      if (OPT_OUT_MARKER.test(lineText)) continue;
+      findings.push({
+        file: rel,
+        line,
+        message: `${fnName}(...) called with only one argument — must pass a context object: ${fnName}(key, { userEmail, orgId })`,
+      });
+    }
+  }
+
+  return { name: "no-unscoped-credentials", findings };
+}