@foldspace_npm/harness 0.1.15 → 0.1.17

package/src/observe-core.mjs

@@ -0,0 +1,627 @@
+// Pure logic behind `foldspace observe`. Nothing here touches CDP, the network
+// or the filesystem, so every rule that protects the customer (GET only, names
+// never values, navigation-only clicks, same-origin paths) is unit-testable.
+//
+// Functions marked "self-contained" are also injected into the page with
+// Function#toString, so they must not reference anything outside their body.
+
+// ------------------------------------------------------------------ hosts
+
+export function hostMatchesAny(hostname, hosts = []) {
+  const host = String(hostname || "").toLowerCase();
+  return hosts.some((pattern) => {
+    const bare = String(pattern).toLowerCase().replace(/^\*\./, "");
+    return Boolean(bare) && (host === bare || host.endsWith(`.${bare}`));
+  });
+}
+
+// Correct registrable domains need public-suffix data, which we do not ship.
+// This approximation is only used to decide which requests are worth REPORTING
+// on, never to decide where anything is sent.
+const SECOND_LEVEL_SUFFIXES = new Set(["co", "com", "org", "net", "gov", "ac", "edu"]);
+
+function siteOf(hostname) {
+  const host = String(hostname || "").toLowerCase();
+  if (!host.includes(".") || /^[\d.]+$/.test(host) || host.includes(":")) return host;
+  const labels = host.split(".");
+  const take = SECOND_LEVEL_SUFFIXES.has(labels[labels.length - 2]) ? 3 : 2;
+  return labels.slice(-take).join(".");
+}
+
+export function isSameSite(url, pageUrl, hosts = []) {
+  try {
+    const target = new URL(url);
+    const page = new URL(pageUrl);
+    if (!/^https?:$/.test(target.protocol)) return false;
+    return (
+      target.hostname === page.hostname ||
+      hostMatchesAny(target.hostname, hosts) ||
+      siteOf(target.hostname) === siteOf(page.hostname)
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ------------------------------------------------------------ navigation
+
+export const NAV_SCOPE_SELECTOR =
+  "nav, aside, header, [role=navigation], [role=menubar], [role=tablist]";
+export const NAV_ITEM_SELECTOR =
+  "a[href], button, [role=menuitem], [role=tab], [role=link]";
+
+/** `--goto` accepts a path on the page's own origin and nothing else. */
+export function sameOriginPath(input, pageUrl) {
+  const raw = String(input ?? "").trim();
+  if (!raw.startsWith("/") || raw.startsWith("//") || raw.includes("\\")) {
+    throw new Error(
+      `--goto takes a path on the app's own origin, starting with "/" (got "${raw}").`,
+    );
+  }
+  const origin = new URL(pageUrl).origin;
+  const resolved = new URL(raw, origin);
+  if (resolved.origin !== origin) {
+    throw new Error(`--goto must stay on ${origin}.`);
+  }
+  const refused = pathRefusal(resolved.pathname);
+  if (refused) throw new Error(`--goto: ${refused}`);
+  return { url: resolved.href, path: resolved.pathname + resolved.search + resolved.hash };
+}
+
+/**
+ * Exact label first, then case-insensitive, then contains. Self-contained.
+ * Returns the index into `items`, or -1.
+ */
+export function pickByLabel(items, want) {
+  const wanted = String(want || "").replace(/\s+/g, " ").trim();
+  if (!wanted) return -1;
+  const lower = wanted.toLowerCase();
+  let index = items.findIndex((item) => item.label === wanted);
+  if (index < 0) index = items.findIndex((item) => item.label.toLowerCase() === lower);
+  if (index < 0) index = items.findIndex((item) => item.label.toLowerCase().includes(lower));
+  return index;
+}
+
+/**
+ * Why a same-origin PATH must not be opened, or null when it may. A GET is not
+ * always harmless: `/logout` ends the session and some apps delete, approve or
+ * send from a link. Paths that only open a form (`/new`, `/edit`) are fine.
+ * Self-contained (injected into the page).
+ */
+export function pathRefusal(pathAndQuery) {
+  const pathOnly = String(pathAndQuery || "").split(/[?#]/)[0].toLowerCase();
+  const risky =
+    /(^|[\/._-])(log[-_]?out|sign[-_]?out|log[-_]?off|sign[-_]?off|delete|destroy|remove|purge|erase|revoke|regenerate|rotate|deactivate|disable|enable|activate|suspend|terminate|cancel|confirm|approve|reject|accept|decline|unsubscribe|subscribe|archive|restore|pay|charge|refund|run|execute|start|stop|pause|resume|send|resend|publish|unpublish|merge|transfer|sync|disconnect|connect|install|uninstall|impersonate|export|download)([\/._-]|$)/;
+  const hit = pathOnly.match(risky);
+  return hit
+    ? `"${pathOnly}" looks like it does something ("${hit[2]}"), not like a screen; observe only opens screens.`
+    : null;
+}
+
+/**
+ * Why observe will not click this item, or null when it may. An ALLOW-list:
+ * observe clicks only what is provably navigation -
+ *   - a link with a real same-origin path (a GET to a screen), its path screened;
+ *   - a tab;
+ *   - a control that only expands a menu (aria-expanded / aria-haspopup / aria-controls).
+ * A plain button can do anything, so it is refused whatever its label says -
+ * a deny-list of verbs let "+ New deal", "Bulk delete", "Run payroll" and
+ * "Regenerate API key" through. Self-contained (injected into the page).
+ */
+export function clickRefusal(item) {
+  const label = String(item?.label || "");
+  const text = label.replace(/^[^\p{L}\p{N}]+/u, "");
+  if (/\b(log|sign)[\s-]?(out|off)\b/i.test(text)) {
+    return `"${label}" ends the session; observe never clicks it.`;
+  }
+  if (item?.submitsForm) return `"${label}" submits a form; observe only opens screens.`;
+  if (item?.download) return `"${label}" downloads a file; observe only opens screens.`;
+
+  const changes =
+    /\b(delete|remove|destroy|erase|purge|empty|clear|reset|revoke|regenerate|rotate|deactivate|disable|enable|activate|suspend|terminate|cancel|confirm|approve|reject|decline|accept|submit|send|resend|save|create|add(?![- ]?ons)|new|invite|pay|buy|purchase|charge|refund|upgrade|downgrade|subscribe|unsubscribe|publish|unpublish|archive|restore|import|export|upload|run|execute|start|stop|pause|resume|merge|transfer|assign|mark|bulk|sync|connect|disconnect|install|uninstall)\b/i;
+
+  if (item?.kind === "link" && item?.path) {
+    // Same-origin link: following it is a GET. Screen where it goes.
+    const pathOnly = String(item.path).split(/[?#]/)[0].toLowerCase();
+    const risky =
+      /(^|[\/._-])(log[-_]?out|sign[-_]?out|log[-_]?off|sign[-_]?off|delete|destroy|remove|purge|erase|revoke|regenerate|rotate|deactivate|disable|enable|activate|suspend|terminate|cancel|confirm|approve|reject|accept|decline|unsubscribe|subscribe|archive|restore|pay|charge|refund|run|execute|start|stop|pause|resume|send|resend|publish|unpublish|merge|transfer|sync|disconnect|connect|install|uninstall|impersonate|export|download)([\/._-]|$)/;
+    const hit = pathOnly.match(risky);
+    return hit
+      ? `"${label}" goes to ${pathOnly}, which looks like it does something ("${hit[2]}"); observe only opens screens.`
+      : null;
+  }
+  if (item?.kind === "tab" || item?.expands) {
+    return changes.test(text)
+      ? `"${label}" reads like an action, not a screen; observe only opens screens.`
+      : null;
+  }
+  return `"${label}" is a ${item?.kind || "button"} with no link behind it, and a button can do anything. observe clicks links, tabs and menu openers only - find the screen's path with \`menu\` and use --goto.`;
+}
+
+// ------------------------------------------------------------ JSON shapes
+
+/**
+ * The shape of a JSON document: key NAMES, where the rows are, and the field
+ * NAMES and value TYPES of a row. No value ever leaves: there is no sample
+ * option, because a truncated row still prints real emails, ids and keys.
+ * Self-contained (injected into the page).
+ */
+export function summarizeJson(value, options = {}) {
+  const maxDepth = options.maxDepth ?? 3;
+  const isObject = (node) => node !== null && typeof node === "object" && !Array.isArray(node);
+  // A map keyed by email or id would leak data through its key names.
+  const safeKey = (key) =>
+    key.includes("@") || key.length > 40 || /^\d{4,}$/.test(key) || /^[0-9a-f-]{24,}$/i.test(key)
+      ? "(id-like key)"
+      : key;
+  const keyNames = (node) => [...new Set(Object.keys(node).slice(0, 40).map(safeKey))];
+
+  let best = null;
+  const better = (candidate) => {
+    if (!best) return true;
+    if (candidate.objects !== best.objects) return candidate.objects;
+    return candidate.count > best.count;
+  };
+  const visit = (node, trail) => {
+    if (Array.isArray(node)) {
+      const candidate = {
+        path: trail.length ? trail.join(".") : "(root)",
+        count: node.length,
+        objects: isObject(node[0]),
+        first: node[0],
+      };
+      if (better(candidate)) best = candidate;
+      return;
+    }
+    if (!isObject(node) || trail.length >= maxDepth) return;
+    for (const key of Object.keys(node).slice(0, 200)) visit(node[key], [...trail, safeKey(key)]);
+  };
+  visit(value, []);
+
+  // What KIND of value a field holds - never the value. Enough to write a
+  // handler (is it a date? cents or a string?) without a row leaving the page.
+  const typeOf = (node) => {
+    if (node === null) return "null";
+    if (Array.isArray(node)) return "array";
+    if (typeof node !== "string") return typeof node;
+    if (/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2})?/.test(node)) return "string:date";
+    if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(node)) return "string:email";
+    if (/^https?:\/\//i.test(node)) return "string:url";
+    if (/^\d+$/.test(node)) return "string:digits";
+    if (/^[0-9a-f-]{16,}$/i.test(node)) return "string:id";
+    return "string";
+  };
+  const fieldTypes = (node) => {
+    const out = {};
+    for (const key of Object.keys(node).slice(0, 40)) out[safeKey(key)] = typeOf(node[key]);
+    return out;
+  };
+
+  const summary = {
+    rootType: Array.isArray(value) ? "array" : isObject(value) ? "object" : typeof value,
+    topLevelKeys: isObject(value) ? keyNames(value) : [],
+    rows: best ? { path: best.path, count: best.count } : null,
+    fieldNames: best && best.objects ? keyNames(best.first) : [],
+    // No rows (a "me" or settings document): the document's own fields.
+    fieldTypes: best && best.objects ? fieldTypes(best.first) : isObject(value) ? fieldTypes(value) : {},
+  };
+  return summary;
+}
+
+// ---------------------------------------------------------------- screen
+
+const NOISE_URL =
+  /(analytics|telemetry|experiment|metrics|beacon|segment|sentry|datadog|amplitude|mixpanel|feature_?flags?|pixel|\/collect\b|intercom|hotjar|fullstory|launchdarkly|\/track(ing)?\b|\/logs?\b)/i;
+
+export function isNoiseUrl(url) {
+  return NOISE_URL.test(String(url || ""));
+}
+
+/** Only successful JSON answers to GET XHR/fetch requests can be a data source. */
+export function isCandidateRequest(request) {
+  return (
+    String(request?.method || "").toUpperCase() === "GET" &&
+    /^(xhr|fetch)$/i.test(request?.type || "") &&
+    request?.status >= 200 &&
+    request?.status < 300 &&
+    /json/i.test(request?.mimeType || "") &&
+    !isNoiseUrl(request?.url)
+  );
+}
+
+export function parseMatchWords(input) {
+  return String(input || "")
+    .toLowerCase()
+    .split(/[,\s]+/)
+    .map((word) => word.trim())
+    .filter(Boolean);
+}
+
+/**
+ * The tab's own URL, fit to print: after sign-in it can carry an OAuth code, a
+ * reset token or an email address. Route-like parts stay, because on a
+ * single-page app `?view=deals` or `#/deals` IS the screen.
+ */
+export function printableUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return String(url || "").split(/[?#]/)[0];
+  }
+  const secretName = /(code|token|key|secret|pass|auth|session|sig|state|nonce|email|ticket|otp|jwt|sso)/i;
+  for (const [name, value] of [...parsed.searchParams.entries()]) {
+    if (secretName.test(name) || value.length > 40 || value.includes("@")) {
+      parsed.searchParams.set(name, "(hidden)");
+    }
+  }
+  if (parsed.hash && !/^#!?\/[^=&]*$/.test(parsed.hash)) parsed.hash = "";
+  return parsed.href.replace(/%28hidden%29/g, "(hidden)");
+}
+
+/** Same-origin URLs read better as a path; the query is part of the request. */
+export function displayUrl(url, origin, { query = true } = {}) {
+  try {
+    // Same hiding as printableUrl: a request's query string can carry a token,
+    // an email or a search the customer typed.
+    const parsed = new URL(printableUrl(url));
+    const tail = parsed.pathname + (query ? parsed.search.replace(/%28hidden%29/g, "(hidden)") : "");
+    const shown = parsed.origin === origin ? tail : parsed.origin + tail;
+    return shown.length > 300 ? `${shown.slice(0, 300)}...` : shown;
+  } catch {
+    return String(url);
+  }
+}
+
+/** A word in the URL is worth more than the same word among the key names. */
+export function rankCandidates(candidates, words = [], max = 8) {
+  const scored = candidates.map((candidate, order) => {
+    const url = String(candidate.path || "").toLowerCase();
+    const names = [
+      ...(candidate.topLevelKeys || []),
+      candidate.rows?.path || "",
+      ...(candidate.fieldNames || []),
+    ]
+      .join(" ")
+      .toLowerCase();
+    const score = words.reduce(
+      (total, word) => total + (url.includes(word) ? 3 : 0) + (names.includes(word) ? 1 : 0),
+      0,
+    );
+    return { candidate, score, order };
+  });
+  scored.sort(
+    (a, b) =>
+      b.score - a.score ||
+      (b.candidate.rows?.count || 0) - (a.candidate.rows?.count || 0) ||
+      a.order - b.order,
+  );
+  return scored.slice(0, max).map(({ candidate, score }) => ({ ...candidate, score }));
+}
+
+// ------------------------------------------------------------------ read
+
+const WRITE_FLAGS = ["method", "data", "body", "header", "headers", "json", "post", "put", "delete"];
+
+/**
+ * `observe read` is GET only. There is deliberately no way to pick a method,
+ * add a header or send a body: anything else belongs in an action handler the
+ * customer has approved, not in a discovery tool.
+ */
+export function refuseWriteFlags(flags = {}) {
+  const asked = WRITE_FLAGS.filter((name) => name in flags);
+  if (asked.length) {
+    throw new Error(
+      `observe read is GET only and never sends a body (refused: ${asked
+        .map((name) => `--${name}`)
+        .join(", ")}).`,
+    );
+  }
+}
+
+/**
+ * Where `read` may send a request - with the customer's session attached.
+ * Only: the page's own origin, a host configured for this project, or an
+ * origin this page was SEEN calling (recorded by `screen` / `auth`). The
+ * "same site" approximation above is never enough on its own: on a shared
+ * suffix (herokuapp.com, vercel.app, github.io) it accepts a stranger's site.
+ */
+export function readDestinationAllowed(url, pageUrl, hosts = [], observedOrigins = []) {
+  try {
+    const target = new URL(url);
+    const page = new URL(pageUrl);
+    if (!/^https?:$/.test(target.protocol)) return false;
+    return (
+      target.origin === page.origin ||
+      hostMatchesAny(target.hostname, hosts) ||
+      observedOrigins.includes(target.origin)
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function planRead({ target, flags = {}, extra = [], pageUrl, hosts = [], observedOrigins = [] }) {
+  refuseWriteFlags(flags);
+  if (extra.length) throw new Error(`unexpected argument '${extra[0]}'`);
+  const raw = String(target ?? "").trim();
+  if (!raw) throw new Error("usage: foldspace observe read <path-or-url>");
+  if (raw.startsWith("//") || raw.includes("\\")) {
+    throw new Error(`"${raw}" is not a path or an http(s) URL.`);
+  }
+  let resolved;
+  try {
+    resolved = new URL(raw, pageUrl);
+  } catch {
+    throw new Error(`"${raw}" is not a path or an http(s) URL.`);
+  }
+  if (!/^https?:$/.test(resolved.protocol)) {
+    throw new Error(`"${raw}" is not a path or an http(s) URL.`);
+  }
+  if (!readDestinationAllowed(resolved.href, pageUrl, hosts, observedOrigins)) {
+    throw new Error(
+      `${resolved.origin} is not part of the app that is open (${new URL(pageUrl).origin}), and this page has not been seen calling it. ` +
+        "observe read only goes to the app's own origin, a host configured for this project, or an origin `observe screen` saw the page call.",
+    );
+  }
+  return { method: "GET", url: resolved.href };
+}
+
+export function readHint(status) {
+  return status === 401 || status === 403
+    ? "cookies alone were refused - run: foldspace observe auth"
+    : null;
+}
+
+// ------------------------------------------------------------------ auth
+
+const STANDARD_HEADER = [
+  /^:/, // HTTP/2 pseudo headers
+  /^accept($|-)/,
+  /^content-/,
+  /^sec-/,
+  /^if-/,
+  /^(host|origin|referer|user-agent|cookie|connection|cache-control|pragma|priority|dnt)$/,
+  /^(range|te|upgrade-insecure-requests|purpose|x-client-data)$/,
+];
+
+/** True for headers the browser adds by itself; x-requested-with is NOT one. */
+export function isStandardHeader(name) {
+  const lower = String(name || "").toLowerCase();
+  return STANDARD_HEADER.some((pattern) => pattern.test(lower));
+}
+
+const MIN_SECRET_LENGTH = 8; // "1", "true", "web" would match everywhere
+
+function splitScheme(value) {
+  const match = /^(Bearer|Token|Basic|JWT)\s+(.+)$/i.exec(String(value));
+  return match ? { scheme: match[1], secret: match[2] } : { scheme: null, secret: String(value) };
+}
+
+function matchKind(secret, candidate) {
+  if (typeof candidate !== "string" || !candidate) return null;
+  if (candidate === secret) return "exact";
+  let decoded = candidate;
+  try {
+    decoded = decodeURIComponent(candidate);
+  } catch {
+    // not URL-encoded
+  }
+  if (decoded === secret) return "exact";
+  if (candidate.includes(secret) || decoded.includes(secret)) return "contains";
+  if (candidate.length >= MIN_SECRET_LENGTH && secret.includes(candidate)) return "part";
+  return null;
+}
+
+// Walk string leaves; a leaf that is itself JSON (redux-persist and friends) is
+// walked too, so the reported path goes all the way to the token.
+function walkLeaves(node, trail, visit, depth = 0) {
+  if (depth > 8) return;
+  if (typeof node === "string") {
+    const text = node.trim();
+    if (depth < 8 && /^[[{]/.test(text)) {
+      try {
+        walkLeaves(JSON.parse(text), trail, visit, depth + 1);
+        return;
+      } catch {
+        // an ordinary string that happens to start with a bracket
+      }
+    }
+    visit(node, trail);
+    return;
+  }
+  if (typeof node === "number") {
+    visit(String(node), trail);
+    return;
+  }
+  if (Array.isArray(node)) {
+    node.slice(0, 50).forEach((entry, index) => walkLeaves(entry, [...trail, String(index)], visit, depth + 1));
+    return;
+  }
+  if (node && typeof node === "object") {
+    for (const key of Object.keys(node).slice(0, 200)) {
+      walkLeaves(node[key], [...trail, key], visit, depth + 1);
+    }
+  }
+}
+
+/**
+ * Where a header's value comes from. `sources` holds real values; the result
+ * holds names, key paths and lengths ONLY.
+ *
+ * sources = { cookies: [{name, value, httpOnly}], localStorage: {k: v},
+ *             sessionStorage: {k: v}, metas: [{name, content}],
+ *             responses: [{request: "GET /api/me", json}] }
+ */
+export function findValueSources(headerValue, sources = {}) {
+  // A storage key or a JSON path can itself be data (a map keyed by email).
+  const safeName = (name) => {
+    const key = String(name);
+    return key.includes("@") || key.length > 40 || /^\d{4,}$/.test(key) || /^[0-9a-f-]{24,}$/i.test(key)
+      ? "(id-like key)"
+      : key;
+  };
+  const safeTrail = (trail) => trail.map(safeName).join(".");
+  const { secret } = splitScheme(headerValue);
+  if (secret.length < MIN_SECRET_LENGTH) return [];
+  const found = [];
+  const seen = new Set();
+  const add = (entry) => {
+    const id = JSON.stringify([entry.kind, entry.name, entry.key, entry.request, entry.jsonPath]);
+    if (seen.has(id)) return;
+    seen.add(id);
+    found.push(entry);
+  };
+
+  for (const cookie of sources.cookies || []) {
+    const match = matchKind(secret, cookie.value);
+    if (match) {
+      add({ kind: "cookie", name: cookie.name, httpOnly: Boolean(cookie.httpOnly), match });
+    }
+  }
+  for (const kind of ["localStorage", "sessionStorage"]) {
+    for (const [key, stored] of Object.entries(sources[kind] || {})) {
+      walkLeaves(stored, [], (leaf, trail) => {
+        const match = matchKind(secret, leaf);
+        if (match) add({ kind, key: safeName(key), jsonPath: trail.length ? safeTrail(trail) : null, match });
+      });
+    }
+  }
+  for (const meta of sources.metas || []) {
+    const match = matchKind(secret, meta.content);
+    if (match) add({ kind: "meta", name: meta.name, match });
+  }
+  for (const response of sources.responses || []) {
+    walkLeaves(response.json, [], (leaf, trail) => {
+      const match = matchKind(secret, leaf);
+      if (match) {
+        add({ kind: "response", request: response.request, jsonPath: safeTrail(trail) || "(root)", match });
+      }
+    });
+  }
+  const rank = { exact: 0, contains: 1, part: 2 };
+  return found.sort((a, b) => rank[a.match] - rank[b.match]).slice(0, 6);
+}
+
+/**
+ * requests = [{ method, path, headers: {name: value} }] -> one entry per
+ * non-standard header, with NO values.
+ */
+export function analyzeAuthHeaders(requests, sources = {}) {
+  const byName = new Map();
+  for (const request of requests) {
+    for (const [name, value] of Object.entries(request.headers || {})) {
+      if (isStandardHeader(name)) continue;
+      const id = name.toLowerCase();
+      if (!byName.has(id)) {
+        byName.set(id, { name, values: new Set(), methods: new Set(), paths: new Set(), requests: 0 });
+      }
+      const entry = byName.get(id);
+      entry.values.add(String(value));
+      entry.methods.add(String(request.method || "GET").toUpperCase());
+      entry.paths.add(request.path);
+      entry.requests += 1;
+    }
+  }
+  return [...byName.values()].map((entry) => {
+    const first = [...entry.values][0];
+    const { scheme, secret } = splitScheme(first);
+    const sources_ = [];
+    for (const value of [...entry.values].slice(0, 3)) {
+      for (const source of findValueSources(value, sources)) {
+        if (!sources_.some((known) => JSON.stringify(known) === JSON.stringify(source))) {
+          sources_.push(source);
+        }
+      }
+    }
+    return {
+      name: entry.name,
+      scheme,
+      valueLength: secret.length,
+      sameOnEveryRequest: entry.values.size === 1,
+      seenOn: {
+        requests: entry.requests,
+        methods: [...entry.methods],
+        paths: [...entry.paths].slice(0, 3),
+      },
+      sources: sources_,
+    };
+  });
+}
+
+export function describeSource(source) {
+  if (!source) return "a value not found in cookies, storage, meta tags or responses (built in page memory)";
+  const trail = source.jsonPath ? ` -> ${source.jsonPath}` : "";
+  const part = source.match === "exact" ? "" : source.match === "contains" ? " (inside it)" : " (part of it)";
+  if (source.kind === "cookie") {
+    return `cookie "${source.name}"${source.httpOnly ? " (HttpOnly: page code cannot read it)" : ""}${part}`;
+  }
+  if (source.kind === "meta") return `<meta name="${source.name}">${part}`;
+  if (source.kind === "response") return `${source.request} response${trail}${part}`;
+  return `${source.kind}["${source.key}"]${trail}${part}`;
+}
+
+export function buildAuthSummary({ headers = [], cookieOnlyGet = null } = {}) {
+  const recipe = headers
+    .map((header) => {
+      const prefix = header.scheme ? `"${header.scheme} " + ` : "";
+      return `${header.name} = ${prefix}${describeSource(header.sources[0])}`;
+    })
+    .join("; ");
+  const probe = cookieOnlyGet ? `GET ${cookieOnlyGet.path} -> ${cookieOnlyGet.status}` : null;
+  if (!headers.length) {
+    return cookieOnlyGet?.ok
+      ? `The app sends no custom headers; reads work with cookies alone (${probe}).`
+      : `The app sent no custom headers in this window${probe ? `, yet cookies alone got ${probe}` : ""}. Open a screen that loads data and run auth again.`;
+  }
+  if (cookieOnlyGet?.ok) {
+    return `Reads work with cookies alone (${probe}). The app also sends ${recipe}; expect writes to need that.`;
+  }
+  if (cookieOnlyGet) {
+    return `Cookies alone were refused (${probe}). Requests need ${recipe}.`;
+  }
+  return `The app sends ${recipe}. No GET could be replayed to check whether cookies alone are enough.`;
+}
+
+// ----------------------------------------------------------------- login
+
+// Anchored to the start of a path segment so /authors or /design-sso-guide do
+// not read as a login page; `auth(?!or)` keeps /auth, /auth0, /authorize.
+const LOGIN_PATH = /(^|\/)(log[-_]?in|sign[-_]?in|sso|oauth|auth(?!or)|session\/new)/i;
+
+export function isLoginPath(pathAndHash) {
+  return LOGIN_PATH.test(String(pathAndHash || ""));
+}
+
+/** One poll of `wait-login`. The caller wants two in a row. */
+export function looksLoggedIn({ url, hasPasswordField = false, hosts = [] }) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (!/^https?:$/.test(parsed.protocol)) return false;
+  if (!hostMatchesAny(parsed.hostname, hosts)) return false;
+  if (hasPasswordField) return false;
+  return !isLoginPath(parsed.pathname + parsed.hash);
+}
+
+// ---------------------------------------------------------------- styles
+
+/** Computed colours come back as rgb()/rgba(); anything else passes through. */
+export function toHex(cssColor) {
+  const text = String(cssColor || "").trim();
+  const match = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/i.exec(text);
+  if (!match) return text || null;
+  const channel = (value) =>
+    Math.max(0, Math.min(255, Math.round(Number(value))))
+      .toString(16)
+      .padStart(2, "0");
+  let alpha = 1;
+  if (match[4] !== undefined) {
+    alpha = match[4].endsWith("%") ? Number(match[4].slice(0, -1)) / 100 : Number(match[4]);
+  }
+  const hex = `#${channel(match[1])}${channel(match[2])}${channel(match[3])}`;
+  return alpha >= 1 ? hex : `${hex}${channel(alpha * 255)}`;
+}

package/src/session-events.mjs

@@ -0,0 +1,42 @@
+// One line per thing the human experienced, so a run can be scored without
+// reconstructing it from a transcript. Local only; never page content.
+//
+//   .foldspace-dev/events.jsonl   {"t": 1789940272818, "event": "login_seen", ...}
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const SESSION_EVENTS = Object.freeze([
+  "chrome_opened",
+  "login_seen",
+  "agent_visible",
+  "observe",
+  "ask",
+  "run",
+]);
+
+export function eventsPath(projectDir) {
+  return path.join(projectDir, ".foldspace-dev", "events.jsonl");
+}
+
+export function recordEvent(projectDir, event, data = {}) {
+  try {
+    const file = eventsPath(projectDir);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify({ t: Date.now(), event, ...data })}\n`);
+  } catch {
+    // Scoring is a convenience. It must never fail a command.
+  }
+}
+
+export function readEvents(projectDir) {
+  try {
+    return fs
+      .readFileSync(eventsPath(projectDir), "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}

package/templates/agent-starter/README.md

@@ -54,8 +54,8 @@ npm run attach:daemon  # same, but return after inspect_registration
 ```
 
 Run `inject` before `attach`. Sign in to the product in the Chrome window that
-`inject` opens. Observe the real product workflow in that window **before**
-attach if you need customer API evidence; `attach` owns the debug port.
+`inject` opens. To see how the product loads its data, use `npx foldspace
+observe` - it reads that same window, read-only, and works while `attach` runs.
 `inject` does not generate an application extension; `attach` loads
 `dist/index.js` directly through CDP. An empty local registry is valid,
 so you can attach before implementing handlers. Coding agents should use