@foldspace_npm/harness 0.1.33 → 0.1.35

package/src/lint/safety.mjs

@@ -0,0 +1,785 @@
+// Safety rules: what a handler may do with the customer's backend and the user's
+// sign-in. Cards may draw any markup - that is the builder's to use. Each rule
+// here blocks the build (known-hosts-only only warns), so each
+// one only fires on what it can see for certain in the source - an address
+// written out, a token read with getAuthToken - and stays quiet on what it
+// cannot follow (an address handed in as a parameter). Each message says what
+// to do instead.
+//
+//   no-fixed-customer-address  one customer's address, on a product with a subdomain per customer
+//   token-stays-home           the user's token returned to the agent, logged, stored again or sent elsewhere
+//   no-secrets                 keys, JWTs, cookies, HAR captures in the project
+//   known-hosts-only           calls only to the product's own hosts, or hosts named in agent/constants.ts
+
+import fs from "node:fs";
+import path from "node:path";
+import { finding, forEachNamedFunction, forEachReturn, isFunctionLike, parseFile, resolveModulePath, stringText } from "./ast.mjs";
+import { ts } from "./ts.mjs";
+import { hostMatchesAny, siteOf } from "../observe-core.mjs";
+import { addressNamesLabel, customerLabel, suggestedApiBase } from "../customer-subdomain.mjs";
+
+// ---------------------------------------------------------------- project facts
+
+const PLACEHOLDER_HOST = "x-subdomain-x";
+
+/** The host of an absolute address, or null. `{subdomain}` reads as a wildcard: `*.api.example.com`. */
+export function absoluteHost(text) {
+  const value = String(text || "").trim();
+  if (!/^(?:(?:https?|wss?):)?\/\//i.test(value)) return null;
+  try {
+    const host = new URL(value.replace(/\{subdomain\}/g, PLACEHOLDER_HOST), "https://placeholder.invalid").hostname.toLowerCase();
+    if (!host || host === "placeholder.invalid") return null;
+    return host.startsWith(`${PLACEHOLDER_HOST}.`) ? `*.${host.slice(PLACEHOLDER_HOST.length + 1)}` : host;
+  } catch {
+    return null;
+  }
+}
+
+function moduleConsts(sourceFile) {
+  const map = new Map();
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isVariableStatement(stmt)) continue;
+    for (const decl of stmt.declarationList.declarations) {
+      if (ts.isIdentifier(decl.name) && decl.initializer) map.set(decl.name.text, decl);
+    }
+  }
+  return map;
+}
+
+/**
+ * What the project says about where it may call: the app's host, the hosts in
+ * foldspace.dev.json, and agent/constants.ts - API_BASE, PER_CUSTOMER_SUBDOMAIN
+ * and every address written there. Missing or unreadable files give fewer
+ * facts, never an error: the rules that need a fact stay quiet without it.
+ */
+export function readProjectFacts(projectDir) {
+  const facts = {
+    appHost: null,
+    devHosts: [],
+    constantsFile: null,
+    constantsSource: null,
+    apiBase: null,
+    apiBaseNode: null,
+    perCustomerSubdomain: undefined,
+    namedHosts: [],
+  };
+
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(projectDir, "foldspace.dev.json"), "utf8"));
+    const targets = config?.targets && typeof config.targets === "object" ? config.targets : {};
+    const order = [config?.defaultTarget, ...Object.keys(targets)].filter((name) => typeof name === "string" && targets[name]);
+    for (const name of order) {
+      const target = targets[name];
+      for (const host of Array.isArray(target.hosts) ? target.hosts : []) {
+        if (typeof host === "string" && host) facts.devHosts.push(host.toLowerCase());
+      }
+      const start = absoluteHost(target.startUrl);
+      if (start) {
+        facts.devHosts.push(start);
+        facts.appHost ??= start;
+      }
+    }
+  } catch {
+    /* no dev config: fewer facts */
+  }
+
+  const constantsPath = ["constants.ts", "constants.js"].map((name) => path.join(projectDir, "agent", name)).find((file) => fs.existsSync(file));
+  if (constantsPath) {
+    const sourceFile = parseFile(constantsPath);
+    facts.constantsFile = path.relative(projectDir, constantsPath);
+    facts.constantsSource = sourceFile;
+    const consts = moduleConsts(sourceFile);
+    const text = (name) => {
+      const decl = consts.get(name);
+      return decl ? stringText(decl.initializer) : null;
+    };
+    const appDomain = text("APP_DOMAIN");
+    if (appDomain && !appDomain.includes("{{")) facts.appHost = absoluteHost(`https://${appDomain}`) ?? facts.appHost;
+    const apiBaseDecl = consts.get("API_BASE");
+    if (apiBaseDecl && stringText(apiBaseDecl.initializer) !== null) {
+      facts.apiBase = stringText(apiBaseDecl.initializer);
+      facts.apiBaseNode = apiBaseDecl.initializer;
+    }
+    const flag = consts.get("PER_CUSTOMER_SUBDOMAIN")?.initializer;
+    if (flag?.kind === ts.SyntaxKind.TrueKeyword) facts.perCustomerSubdomain = true;
+    if (flag?.kind === ts.SyntaxKind.FalseKeyword) facts.perCustomerSubdomain = false;
+    walkStrings(sourceFile, (node, value) => {
+      const host = absoluteHost(value);
+      if (host) facts.namedHosts.push(host);
+    });
+  }
+  if (facts.appHost) facts.devHosts.push(facts.appHost);
+  facts.devHosts = [...new Set(facts.devHosts)];
+  facts.namedHosts = [...new Set(facts.namedHosts)];
+  return facts;
+}
+
+function hostMatches(host, patterns) {
+  return patterns.some((pattern) => {
+    if (pattern.startsWith("*.")) return hostMatchesAny(host, [pattern]);
+    return host === pattern;
+  });
+}
+
+/** The product's own hosts: those foldspace.dev.json names, API_BASE's, and any on the app's own domain. */
+function isProductHost(host, facts) {
+  if (!facts.appHost && !facts.devHosts.length) return true; // nothing to judge by
+  const apiHost = absoluteHost(facts.apiBase);
+  const bare = host.replace(/^\*\./, "");
+  return (
+    hostMatchesAny(bare, facts.devHosts) ||
+    (apiHost !== null && hostMatches(bare, [apiHost])) ||
+    facts.devHosts.some((pattern) => siteOf(pattern.replace(/^\*\./, "")) === siteOf(bare))
+  );
+}
+
+/** Foldspace's own hosts are trusted everywhere. */
+function isFoldspaceHost(host) {
+  const bare = host.replace(/^\*\./, "").toLowerCase();
+  return bare === "foldspace.ai" || bare.endsWith(".foldspace.ai");
+}
+
+/** Product hosts, Foldspace's own, plus every host written in agent/constants.ts - the one reviewed list of other hosts. */
+function isKnownHost(host, facts) {
+  return isFoldspaceHost(host) || isProductHost(host, facts) || hostMatches(host, facts.namedHosts);
+}
+
+// ---------------------------------------------------------------- scopes
+
+/**
+ * Which declaration a name refers to, by function scope. Blocks are not
+ * scopes here: two `let token` in one function read as one. That only ever
+ * makes a rule see a token where there is one in the same function.
+ */
+class Scopes {
+  constructor(sourceFile) {
+    this.sourceFile = sourceFile;
+    this.byScope = new Map();
+    const scopeOf = (node) => {
+      for (let up = node.parent; up; up = up.parent) {
+        if (isFunctionLike(up) || ts.isSourceFile(up)) return up;
+      }
+      return sourceFile;
+    };
+    const declare = (scope, name, decl) => {
+      if (!this.byScope.has(scope)) this.byScope.set(scope, new Map());
+      const names = this.byScope.get(scope);
+      if (!names.has(name)) names.set(name, decl);
+    };
+    const declareBinding = (scope, name, decl) => {
+      if (ts.isIdentifier(name)) declare(scope, name.text, decl);
+      else if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+        for (const element of name.elements) {
+          if (ts.isBindingElement(element)) declareBinding(scope, element.name, element);
+        }
+      }
+    };
+    const walk = (node) => {
+      if (ts.isVariableDeclaration(node)) declareBinding(scopeOf(node), node.name, node);
+      else if (ts.isParameter(node)) declareBinding(node.parent, node.name, node);
+      else if (ts.isFunctionDeclaration(node) && node.name) declare(scopeOf(node), node.name.text, node);
+      else if (ts.isImportSpecifier(node) || ts.isImportClause(node) || ts.isNamespaceImport(node)) {
+        if (node.name) declare(sourceFile, node.name.text, node);
+      }
+      ts.forEachChild(node, walk);
+    };
+    walk(sourceFile);
+  }
+
+  resolve(identifier) {
+    for (let up = identifier; up; up = up.parent) {
+      if (isFunctionLike(up) || ts.isSourceFile(up)) {
+        const found = this.byScope.get(up)?.get(identifier.text);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  /** The value a `const` name holds, when it is declared with one. */
+  constValue(identifier) {
+    const decl = this.resolve(identifier);
+    if (!decl || !ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name)) return null;
+    const list = decl.parent;
+    if (!list || !(list.flags & ts.NodeFlags.Const)) return null;
+    return decl.initializer ?? null;
+  }
+
+  /** The module an imported name comes from. */
+  importedFrom(identifier) {
+    const decl = this.resolve(identifier);
+    if (!decl) return null;
+    let up = decl;
+    while (up && !ts.isImportDeclaration(up)) up = up.parent;
+    return up && ts.isStringLiteral(up.moduleSpecifier) ? up.moduleSpecifier.text : null;
+  }
+}
+
+const unwrap = (node) => {
+  while (
+    node &&
+    (ts.isParenthesizedExpression(node) ||
+      ts.isAsExpression(node) ||
+      ts.isNonNullExpression(node) ||
+      ts.isTypeAssertionExpression(node) ||
+      ts.isSatisfiesExpression(node) ||
+      ts.isAwaitExpression(node))
+  ) {
+    node = node.expression;
+  }
+  return node;
+};
+
+const calleeName = (call) => {
+  const callee = unwrap(call.expression);
+  if (ts.isIdentifier(callee)) return callee.text;
+  if (ts.isPropertyAccessExpression(callee)) return callee.name.text;
+  return null;
+};
+
+const receiverText = (call, sourceFile) => {
+  const callee = unwrap(call.expression);
+  return ts.isPropertyAccessExpression(callee) ? callee.expression.getText(sourceFile).replace(/\s+/g, "") : "";
+};
+
+function walkStrings(node, visit) {
+  const walk = (current) => {
+    if (ts.isImportDeclaration(current) || ts.isExportDeclaration(current)) return;
+    if (ts.isStringLiteral(current) || ts.isNoSubstitutionTemplateLiteral(current)) visit(current, current.text);
+    else if (ts.isTemplateExpression(current)) visit(current, current.head.text);
+    ts.forEachChild(current, walk);
+  };
+  walk(node);
+}
+
+// ---------------------------------------------------------------- where a URL goes
+
+/**
+ * Where an address expression points, as far as the source shows:
+ * `{ kind: "backend" }` - API_BASE, apiBaseUrl(), the page's own origin or a
+ * path on it; `{ kind: "host", host }` - an address written out;
+ * `{ kind: "unknown" }` - anything the source does not show.
+ */
+function destination(node, scopes, depth = 0) {
+  node = unwrap(node);
+  if (!node || depth > 6) return { kind: "unknown" };
+  const fromText = (text, partial = false) => {
+    if (!text) return { kind: "unknown" };
+    if (!text.startsWith("//") && !/^[a-z][a-z0-9+.-]*:/i.test(text)) return { kind: "backend" }; // a path on the page's own host
+    // The start of a template names a host only when something follows it: `https://api.` + name does not.
+    if (partial && !/^(?:(?:https?|wss?):)?\/\/[^/?#:]+[/?#:]/i.test(text)) return { kind: "unknown" };
+    const host = absoluteHost(text);
+    return host ? { kind: "host", host } : { kind: "unknown" };
+  };
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return fromText(node.text);
+  if (ts.isTemplateExpression(node)) {
+    if (node.head.text) return fromText(node.head.text, true);
+    return destination(node.templateSpans[0].expression, scopes, depth + 1);
+  }
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const left = unwrap(node.left);
+    if (ts.isStringLiteral(left) || ts.isNoSubstitutionTemplateLiteral(left)) return fromText(left.text, true);
+    return destination(node.left, scopes, depth + 1);
+  }
+  if (ts.isIdentifier(node)) {
+    if (node.text === "API_BASE" || node.text === "apiBase") return { kind: "backend" };
+    const value = scopes.constValue(node);
+    return value ? destination(value, scopes, depth + 1) : { kind: "unknown" };
+  }
+  if (ts.isPropertyAccessExpression(node)) {
+    if (node.name.text === "apiBase") return { kind: "backend" };
+    if (node.name.text === "origin" && /(^|\.)location$/.test(node.expression.getText(scopes.sourceFile))) return { kind: "backend" };
+    return { kind: "unknown" };
+  }
+  if (ts.isCallExpression(node)) {
+    return calleeName(node) === "apiBaseUrl" ? { kind: "backend" } : { kind: "unknown" };
+  }
+  if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "URL" && node.arguments?.length) {
+    const first = destination(node.arguments[0], scopes, depth + 1);
+    if (first.kind === "host" || node.arguments.length < 2) return first;
+    return destination(node.arguments[1], scopes, depth + 1);
+  }
+  return { kind: "unknown" };
+}
+
+/** Calls that reach the network, and which argument holds the address. */
+function networkCall(node, sourceFile) {
+  if (ts.isCallExpression(node)) {
+    const name = calleeName(node);
+    const receiver = receiverText(node, sourceFile);
+    if (name === "fetch" && (!receiver || /^(window|globalThis|self)$/.test(receiver))) return { what: "fetch", url: node.arguments[0], payload: node.arguments.slice(0, 2) };
+    if (name === "sendBeacon") return { what: "sendBeacon", url: node.arguments[0], payload: node.arguments.slice(0, 2) };
+    if (name === "open" && node.arguments.length >= 2 && ts.isStringLiteralLike(node.arguments[0]) && /^[A-Z]+$/.test(node.arguments[0].text)) {
+      return { what: "XMLHttpRequest", url: node.arguments[1], payload: [node.arguments[1]] };
+    }
+    if (name === "publicFetch" && node.arguments[1]) return { what: "publicFetch", url: node.arguments[1], payload: [] };
+    if (node.expression.kind === ts.SyntaxKind.ImportKeyword) return { what: "import()", url: node.arguments[0], payload: [] };
+    if (name === "importScripts") return { what: "importScripts", url: node.arguments[0], payload: [] };
+  }
+  if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && ["WebSocket", "EventSource"].includes(node.expression.text)) {
+    return { what: node.expression.text, url: node.arguments?.[0], payload: node.arguments?.slice(0, 1) ?? [] };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------- the user's token
+
+const TOKENISH_KEY = /token|session|auth|jwt|bearer|\bsid\b|credential|access/i;
+// atob is not here: decoding a JWT's middle part gives its claims (who the
+// user is), the way parseJwt does - not the token.
+const PASS_THROUGH_CALLS = new Set(["String", "encodeURIComponent", "encodeURI", "decodeURIComponent", "btoa", "escape", "unescape"]);
+const NON_CARRYING_METHODS = new Set(["startsWith", "endsWith", "includes", "indexOf", "lastIndexOf", "localeCompare", "test", "charCodeAt", "search", "has"]);
+const PASS_THROUGH_CONSTRUCTORS = new Set(["Headers", "URLSearchParams", "Blob", "FormData", "Request", "URL"]);
+const AGENT_METHODS = new Set(["identify", "setContext", "addContext", "message", "sendMessage", "runTask"]);
+
+class TokenFlow {
+  constructor(sourceFile, scopes) {
+    this.sourceFile = sourceFile;
+    this.scopes = scopes;
+    this.tainted = new Set();
+    this.taintedFunctions = new Set();
+    this.solve();
+  }
+
+  storageKeyIsToken(arg) {
+    const node = unwrap(arg);
+    if (!node) return false;
+    let text = stringText(node);
+    if (text === null && ts.isIdentifier(node)) {
+      const value = this.scopes.constValue(node);
+      text = value ? stringText(value) : null;
+      if (text === null) return TOKENISH_KEY.test(node.text);
+    }
+    return text !== null && TOKENISH_KEY.test(text);
+  }
+
+  isSource(node) {
+    if (ts.isCallExpression(node)) {
+      const name = calleeName(node);
+      if (name === "getAuthToken") return true;
+      if (name === "getItem" && /(^|\.)(localStorage|sessionStorage)$/.test(receiverText(node, this.sourceFile))) {
+        return this.storageKeyIsToken(node.arguments[0]);
+      }
+      return false;
+    }
+    if (ts.isPropertyAccessExpression(node) && node.name.text === "cookie" && /(^|\.)document$/.test(node.expression.getText(this.sourceFile))) {
+      const parent = node.parent;
+      const assigned = parent && ts.isBinaryExpression(parent) && parent.left === node && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+      return !assigned;
+    }
+    return false;
+  }
+
+  functionOf(decl) {
+    if (!decl) return null;
+    if (ts.isFunctionDeclaration(decl)) return decl;
+    if (ts.isVariableDeclaration(decl) && isFunctionLike(unwrap(decl.initializer))) return unwrap(decl.initializer);
+    return null;
+  }
+
+  carries(node, depth = 0) {
+    if (!node || depth > 40) return false;
+    const next = (child) => this.carries(child, depth + 1);
+    if (
+      ts.isParenthesizedExpression(node) ||
+      ts.isAsExpression(node) ||
+      ts.isNonNullExpression(node) ||
+      ts.isTypeAssertionExpression(node) ||
+      ts.isSatisfiesExpression(node) ||
+      ts.isAwaitExpression(node) ||
+      ts.isSpreadElement(node) ||
+      ts.isSpreadAssignment(node)
+    ) {
+      return next(node.expression);
+    }
+    if (this.isSource(node)) return true;
+    if (ts.isIdentifier(node)) {
+      const decl = this.scopes.resolve(node);
+      return Boolean(decl && this.tainted.has(decl));
+    }
+    if (ts.isTemplateExpression(node)) return node.templateSpans.some((span) => next(span.expression));
+    if (ts.isBinaryExpression(node)) {
+      const op = node.operatorToken.kind;
+      if (op === ts.SyntaxKind.PlusToken || op === ts.SyntaxKind.QuestionQuestionToken || op === ts.SyntaxKind.BarBarToken) {
+        return next(node.left) || next(node.right);
+      }
+      if (op === ts.SyntaxKind.AmpersandAmpersandToken || op === ts.SyntaxKind.CommaToken || op === ts.SyntaxKind.EqualsToken) {
+        return next(node.right);
+      }
+      return false;
+    }
+    if (ts.isConditionalExpression(node)) return next(node.whenTrue) || next(node.whenFalse);
+    if (ts.isObjectLiteralExpression(node)) {
+      return node.properties.some((prop) => {
+        if (ts.isPropertyAssignment(prop)) return next(prop.initializer);
+        if (ts.isShorthandPropertyAssignment(prop)) return next(prop.name);
+        if (ts.isSpreadAssignment(prop)) return next(prop.expression);
+        return false;
+      });
+    }
+    if (ts.isArrayLiteralExpression(node)) return node.elements.some(next);
+    if (ts.isPropertyAccessExpression(node)) return node.name.text !== "length" && next(node.expression);
+    if (ts.isElementAccessExpression(node)) return next(node.expression);
+    if (ts.isCallExpression(node)) {
+      const callee = unwrap(node.expression);
+      if (ts.isIdentifier(callee)) {
+        if (PASS_THROUGH_CALLS.has(callee.text)) return node.arguments.some(next);
+        const fn = this.functionOf(this.scopes.resolve(callee));
+        return Boolean(fn && this.taintedFunctions.has(fn));
+      }
+      if (ts.isPropertyAccessExpression(callee)) {
+        const owner = callee.expression.getText(this.sourceFile);
+        if (owner === "JSON" || (owner === "Object" && ["assign", "entries", "values", "fromEntries"].includes(callee.name.text))) {
+          return node.arguments.some(next);
+        }
+        return !NON_CARRYING_METHODS.has(callee.name.text) && next(callee.expression);
+      }
+      return false;
+    }
+    if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && PASS_THROUGH_CONSTRUCTORS.has(node.expression.text)) {
+      return (node.arguments ?? []).some(next);
+    }
+    return false;
+  }
+
+  solve() {
+    const decls = [];
+    const functions = [];
+    const assignments = [];
+    const walk = (node) => {
+      if (ts.isVariableDeclaration(node) && node.initializer) decls.push(node);
+      if (isFunctionLike(node)) functions.push(node);
+      if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(node.left)) {
+        assignments.push(node);
+      }
+      ts.forEachChild(node, walk);
+    };
+    walk(this.sourceFile);
+
+    const bindingNodes = (decl) => {
+      if (ts.isIdentifier(decl.name)) return [decl];
+      const out = [];
+      const visit = (pattern) => {
+        for (const element of pattern.elements) {
+          if (!ts.isBindingElement(element)) continue;
+          if (ts.isIdentifier(element.name)) out.push(element);
+          else visit(element.name);
+        }
+      };
+      visit(decl.name);
+      return out;
+    };
+
+    for (let round = 0; round < 12; round += 1) {
+      let changed = false;
+      for (const decl of decls) {
+        const targets = bindingNodes(decl).filter((target) => !this.tainted.has(target));
+        if (targets.length && this.carries(decl.initializer)) {
+          for (const target of targets) this.tainted.add(target);
+          changed = true;
+        }
+      }
+      for (const assignment of assignments) {
+        const decl = this.scopes.resolve(assignment.left);
+        if (decl && !this.tainted.has(decl) && this.carries(assignment.right)) {
+          this.tainted.add(decl);
+          changed = true;
+        }
+      }
+      for (const fn of functions) {
+        if (this.taintedFunctions.has(fn)) continue;
+        let returns = false;
+        forEachReturn(fn, (expression) => {
+          if (!returns && this.carries(expression)) returns = true;
+        });
+        if (returns) {
+          this.taintedFunctions.add(fn);
+          changed = true;
+        }
+      }
+      if (!changed) break;
+    }
+  }
+}
+
+const TOKEN_FIXES = {
+  agent:
+    "Return only the facts the answer needs. The token stays in the page: apiFetch adds it to the product's own calls for you.",
+  log: "Leave the token out of the log, or log redact(token) - it shows only the length.",
+  stored:
+    "Read it where the app keeps it, each time, with getAuthToken. Never keep a second copy - in storage, a cookie or on window.",
+  sent:
+    "Send it only to the product's own backend - call apiFetch with a path, and it adds the token for you.",
+};
+
+export function ruleTokenStaysHome(sourceFile, relative, findings, facts, scopes = new Scopes(sourceFile)) {
+  const flow = new TokenFlow(sourceFile, scopes);
+  const report = (node, message, fix) =>
+    findings.push(finding({ rule: "token-stays-home", severity: "error", sourceFile, node, file: relative, message, fix }));
+
+  // Returned to the agent: what execute and a card's callback return, and what
+  // render hands to callback or readyState.
+  forEachNamedFunction(sourceFile, ["execute", "callback"], (fn, name) => {
+    forEachReturn(fn, (expression) => {
+      if (flow.carries(expression)) {
+        report(expression, `${name} returns the user's sign-in token. What ${name} returns reaches the agent and the model.`, TOKEN_FIXES.agent);
+      }
+    });
+  });
+  forEachNamedFunction(sourceFile, ["render"], (fn) => {
+    const params = fn.parameters.filter((param) => !(ts.isIdentifier(param.name) && param.name.text === "this"));
+    const names = [params[3], params[5]].filter((param) => param && ts.isIdentifier(param.name)).map((param) => param.name.text);
+    const walk = (node) => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(unwrap(node.expression)) && names.includes(unwrap(node.expression).text)) {
+        if (node.arguments.some((arg) => flow.carries(arg))) {
+          report(node, `The card hands the user's sign-in token to ${unwrap(node.expression).text}, which reaches the agent and the model.`, TOKEN_FIXES.agent);
+        }
+      }
+      ts.forEachChild(node, walk);
+    };
+    if (fn.body) walk(fn.body);
+  });
+
+  const walk = (node) => {
+    if (ts.isCallExpression(node)) {
+      const name = calleeName(node);
+      const receiver = receiverText(node, sourceFile);
+      const carried = () => node.arguments.some((arg) => flow.carries(arg));
+      if (/^console$/.test(receiver) && carried()) {
+        report(node, `console.${name} writes the user's sign-in token to the browser console, where anyone at the screen or any script on the page can read it.`, TOKEN_FIXES.log);
+      } else if (name === "setItem" && /(^|\.)(localStorage|sessionStorage)$/.test(receiver) && node.arguments[1] && flow.carries(node.arguments[1])) {
+        report(node, `The user's sign-in token is stored again (${receiver}.setItem).`, TOKEN_FIXES.stored);
+      } else if (name && AGENT_METHODS.has(name) && /foldspace|agent/i.test(receiver) && carried()) {
+        report(node, `The user's sign-in token is handed to Foldspace (${receiver}.${name}), which sends it to the agent.`, TOKEN_FIXES.agent);
+      } else if (ts.isIdentifier(unwrap(node.expression)) && name === "foldspace" && carried()) {
+        report(node, "The user's sign-in token is handed to Foldspace, which sends it to the agent.", TOKEN_FIXES.agent);
+      }
+    }
+    const call = networkCall(node, sourceFile);
+    if (call && call.payload.some((arg) => arg && flow.carries(arg))) {
+      const where = destination(call.url, scopes);
+      if (where.kind === "host" && !isProductHost(where.host, facts)) {
+        report(node, `The user's sign-in token is sent to ${where.host}, which is not the product's backend.`, TOKEN_FIXES.sent);
+      }
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && flow.carries(node.right)) {
+      const left = unwrap(node.left);
+      let root = left;
+      while (ts.isPropertyAccessExpression(root) || ts.isElementAccessExpression(root)) root = unwrap(root.expression);
+      const isCookie =
+        ts.isPropertyAccessExpression(left) && left.name.text === "cookie" && /(^|\.)document$/.test(unwrap(left.expression).getText(sourceFile));
+      if (isCookie) {
+        report(node, "The user's sign-in token is stored again, in a cookie.", TOKEN_FIXES.stored);
+      } else if (root !== left && ts.isIdentifier(root) && ["window", "globalThis", "self"].includes(root.text)) {
+        report(node, `The user's sign-in token is stored again, on ${root.text}, where every script on the page can read it.`, TOKEN_FIXES.stored);
+      }
+    }
+    ts.forEachChild(node, walk);
+  };
+  walk(sourceFile);
+}
+
+// ---------------------------------------------------------------- one customer's address
+
+export function ruleNoFixedCustomerAddress(sourceFile, relative, findings, facts, { isConstants = false } = {}) {
+  const label = customerLabel(facts.appHost, facts.perCustomerSubdomain);
+  if (!label) return;
+  const decided = facts.perCustomerSubdomain === true;
+  const sameProduct = (host) => isProductHost(host, facts);
+
+  if (isConstants && facts.apiBaseNode) {
+    const value = facts.apiBase;
+    const host = absoluteHost(value);
+    if (host && !host.startsWith("*.") && sameProduct(host) && addressNamesLabel(value, label)) {
+      const suggestion = suggestedApiBase(value, facts.appHost, label);
+      findings.push(
+        finding({
+          rule: "no-fixed-customer-address",
+          severity: "error",
+          sourceFile,
+          node: facts.apiBaseNode,
+          file: relative,
+          message: decided
+            ? `API_BASE is one customer's address (${value}). Each customer has their own subdomain, so every user's agent would call this customer's data.`
+            : `API_BASE (${value}) carries "${label}", which may be one customer's own subdomain. If each customer has their own, every user's agent would call this customer's data.`,
+          fix: decided
+            ? `Write it from the page's address: API_BASE = "${suggestion}". ${suggestion.startsWith("/") ? "Each user's page then calls its own host." : "The runtime fills in each user's own subdomain."}`
+            : `Ask the human, as a choice, whether each of their customers gets their own address like ${facts.appHost}. Yes: set PER_CUSTOMER_SUBDOMAIN = true and API_BASE = "${suggestion}". No: set PER_CUSTOMER_SUBDOMAIN = false.`,
+        }),
+      );
+    }
+  }
+
+  walkStrings(sourceFile, (node, text) => {
+    if (isConstants && node === facts.apiBaseNode) return;
+    const host = absoluteHost(text);
+    if (!host || host.startsWith("*.") || !sameProduct(host) || !addressNamesLabel(text, label)) return;
+    const shown = text.length > 80 ? `${text.slice(0, 77)}...` : text;
+    findings.push(
+      finding({
+        rule: "no-fixed-customer-address",
+        severity: "error",
+        sourceFile,
+        node,
+        file: relative,
+        message: decided
+          ? `'${shown}' is one customer's address, written into the code. On every other customer's page it would reach this customer.`
+          : `'${shown}' carries "${label}", which may be one customer's own subdomain, written into the code. If each customer has their own, every other customer's page would reach this one.`,
+        fix: `Use a path alone: apiFetch("/…") for a call (the address comes from API_BASE), or "/…" for a link on the page's own host.${decided ? "" : ` If ${label} is not a customer, set PER_CUSTOMER_SUBDOMAIN = false in agent/constants.ts - with the human's answer.`}`,
+      }),
+    );
+  });
+}
+
+// ---------------------------------------------------------------- known hosts
+
+export function ruleKnownHostsOnly(sourceFile, relative, findings, facts, scopes = new Scopes(sourceFile)) {
+  const walk = (node) => {
+    const call = networkCall(node, sourceFile);
+    if (call && call.url) {
+      const where = destination(call.url, scopes);
+      if (where.kind === "host" && !isKnownHost(where.host, facts)) {
+        findings.push(
+          finding({
+            rule: "known-hosts-only",
+            severity: "warning",
+            sourceFile,
+            node: call.url,
+            file: relative,
+            message: `${call.what} goes to ${where.host}, which is not the product's own backend or a host this project names. The user's signed-in page would send it there.`,
+            fix: `Call the product's own backend with apiFetch. If ${where.host} really is needed, ask the human, then name it as a constant in agent/constants.ts and call it through that constant.`,
+          }),
+        );
+      }
+    }
+    ts.forEachChild(node, walk);
+  };
+  walk(sourceFile);
+}
+
+// ---------------------------------------------------------------- secrets in the project
+
+const SECRET_PATTERNS = [
+  { what: "a JWT (a signed-in session token)", re: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g },
+  { what: "a private key", re: /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----/g },
+  { what: "an AWS access key", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+  { what: "a Stripe key", re: /\b(?:sk|rk)_(?:live|test)_[0-9A-Za-z]{16,}/g },
+  { what: "a GitHub token", re: /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{40,})/g },
+  { what: "a Slack token", re: /\bxox[abprs]-[A-Za-z0-9-]{10,}/g },
+  { what: "a Google API key", re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { what: "an API key", re: /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{32,}/g },
+  { what: "a bearer token", re: /\bBearer\s+(?!\$\{)[A-Za-z0-9._~+/-]{20,}=*/g },
+  { what: "a cookie value", re: /\b(?:Set-)?Cookie\b["']?\s*[:=]\s*["'`]?[A-Za-z0-9_.-]+=[^;\s"'`<>]{16,}/gi },
+  {
+    what: "a secret",
+    re: /\b(?:api[_-]?key|api[_-]?secret|secret[_-]?key|client[_-]?secret|password|passwd|private[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|session[_-]?token|id[_-]?token)["']?\s*[:=]\s*["'`]([^"'`\s]{16,})["'`]/gi,
+    value: 1,
+  },
+];
+
+const PLACEHOLDER = /example|xxxx|\.\.\.|<|>|your[_-]|placeholder|changeme|redacted|dummy|sample|__observe|\$\{|\{\{/i;
+
+function looksReal(value) {
+  return !PLACEHOLDER.test(value) && /[A-Za-z]/.test(value) && /\d/.test(value);
+}
+
+const CAPTURE_FILE = /(?:\.har|\.cookies?|^cookies?\.(?:json|txt)|^storage[-_.]?state\.json|^\.env(?:\.(?!example$|sample$|template$)[\w.-]+)?)$/i;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".foldspace-dev", "video", ".claude"]);
+const TEXT_FILE = /\.(?:[cm]?[jt]sx?|json|md|txt|html?|css|ya?ml|env|har)$/i;
+
+function projectFiles(projectDir) {
+  const out = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name) || depth > 8) continue;
+        // The harness's own runtime copy is the harness's, not the project's.
+        if (path.relative(projectDir, full).split(path.sep).join("/") === "agent/runtime") continue;
+        walk(full, depth + 1);
+      } else if (entry.isFile()) out.push(full);
+    }
+  };
+  walk(projectDir, 0);
+  return out;
+}
+
+export function ruleNoSecrets(projectDir, findings) {
+  for (const file of projectFiles(projectDir)) {
+    const relative = path.relative(projectDir, file);
+    const base = path.basename(file);
+    if (base === "package-lock.json") continue;
+    if (CAPTURE_FILE.test(base)) {
+      findings.push({
+        rule: "no-secrets",
+        severity: "error",
+        file: relative,
+        line: 1,
+        column: 1,
+        message: `${relative} is a capture of browser traffic or storage. It holds live sign-ins and the customer's data, and anything in this folder can be saved and shared.`,
+        fix: "Delete it. What the build needs from a capture - the path, the field names, where the token lives - goes in docs/app-profile.md, as names, never values.",
+      });
+      continue;
+    }
+    if (!TEXT_FILE.test(base)) continue;
+    let text;
+    try {
+      const stat = fs.statSync(file);
+      if (stat.size > 2_000_000) continue;
+      text = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const lineStarts = [0];
+    for (let i = 0; i < text.length; i += 1) if (text[i] === "\n") lineStarts.push(i + 1);
+    const position = (index) => {
+      let low = 0;
+      let high = lineStarts.length - 1;
+      while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (lineStarts[mid] <= index) low = mid;
+        else high = mid - 1;
+      }
+      return { line: low + 1, column: index - lineStarts[low] + 1 };
+    };
+    const seen = new Set();
+    for (const pattern of SECRET_PATTERNS) {
+      pattern.re.lastIndex = 0;
+      for (const match of text.matchAll(pattern.re)) {
+        const value = pattern.value ? match[pattern.value] : match[0];
+        if (!looksReal(value)) continue;
+        const at = position(match.index);
+        const key = `${at.line}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        findings.push({
+          rule: "no-secrets",
+          severity: "error",
+          file: relative,
+          ...at,
+          message: `This line holds what looks like ${pattern.what}. Anything in this folder can be saved, shared and shipped in the bundle.`,
+          fix: "Delete the value. The agent reads the user's sign-in from the page at run time (getAuthToken); nothing secret is ever written into the project. A sample stays a placeholder such as \"<token>\".",
+        });
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------- entry
+
+/** Every source rule here, for one file under agent/ (not agent/runtime/). */
+export function lintSafetyFile(filePath, relative, findings, facts) {
+  const sourceFile = parseFile(filePath);
+  const scopes = new Scopes(sourceFile);
+  const isConstants = facts.constantsFile !== null && relative === facts.constantsFile;
+  ruleNoFixedCustomerAddress(isConstants ? facts.constantsSource : sourceFile, relative, findings, facts, { isConstants });
+  ruleTokenStaysHome(sourceFile, relative, findings, facts, scopes);
+  ruleKnownHostsOnly(sourceFile, relative, findings, facts, scopes);
+}
+