failproofai 1.0.7-beta.1 → 1.0.7-beta.2

package/.next/standalone/sdk/typescript/src/redact.ts

@@ -0,0 +1,305 @@
+/**
+ * Deterministic credential scrubbing for SDK spool files.
+ *
+ * This mirrors the daemon's minimal redaction boundary — and, line for line,
+ * `failproofai_sdk/_redact.py`. The SDK applies it before bytes reach disk; the
+ * daemon applies it again before upload so batches written by older SDKs
+ * receive the same protection.
+ *
+ * The scan is index-based rather than regex-based on purpose: several of the
+ * rules (the JWT segment walk, the assignment's backwards name scan, the bearer
+ * token's byte budget) are not regular, and a half-regex/half-manual
+ * implementation is exactly how the two sides of a redactor drift apart.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+const PREFIX_RULES: ReadonlyArray<readonly [string, number, string]> = [
+  ["sk-ant-api", 16, "anthropic-key"],
+  ["sk-ant-", 16, "anthropic-key"],
+  ["sk-proj-", 16, "openai-key"],
+  ["sk-", 16, "api-key"],
+  ["ghp_", 20, "github-token"],
+  ["gho_", 20, "github-token"],
+  ["ghu_", 20, "github-token"],
+  ["ghs_", 20, "github-token"],
+  ["ghr_", 20, "github-token"],
+  ["github_pat_", 20, "github-token"],
+  ["sb_secret_", 16, "supabase-key"],
+  ["sbp_", 20, "supabase-key"],
+  ["xoxb-", 16, "slack-token"],
+  ["xoxp-", 16, "slack-token"],
+  ["AKIA", 16, "aws-access-key-id"],
+  ["ASIA", 16, "aws-access-key-id"],
+];
+
+const STRONG_SECRET_NAMES = ["secret", "password", "passwd", "credential"] as const;
+const WEAK_SECRET_NAMES = ["key", "token"] as const;
+const MIN_ASSIGNMENT_VALUE = 12;
+
+type Match = readonly [length: number, label: string];
+
+function isAsciiAlnum(code: number): boolean {
+  return (
+    (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122)
+  );
+}
+
+function isTokenChar(value: string, index: number): boolean {
+  const code = value.charCodeAt(index);
+  return isAsciiAlnum(code) || code === 0x5f /* _ */ || code === 0x2d /* - */;
+}
+
+/**
+ * UTF-8 byte length of the code unit at `index`.
+ *
+ * Summed across a string this is the exact UTF-8 byte count, including for
+ * astral characters: each half of a surrogate pair reports 2, and 2 + 2 is the
+ * 4 bytes such a code point actually occupies. That is what lets the byte
+ * budgets below scan by code unit without ever decoding the string.
+ */
+function utf8LenAt(value: string, index: number): number {
+  const code = value.charCodeAt(index);
+  if (code < 0x80) return 1;
+  if (code < 0x800) return 2;
+  return code >= 0xd800 && code <= 0xdfff ? 2 : 3;
+}
+
+export function utf8Length(value: string): number {
+  let total = 0;
+  for (let i = 0; i < value.length; i += 1) total += utf8LenAt(value, i);
+  return total;
+}
+
+// Python's `str.isspace()`: the ASCII whitespace set plus the file/group/record/
+// unit separators, plus Unicode separators. `\s` covers the Unicode half; the
+// C1 separators are spelled out because `\s` does not include them.
+function isSpaceChar(char: string): boolean {
+  return /\s/.test(char) || (char >= "\u001c" && char <= "\u001f");
+}
+
+function isUpperChar(char: string): boolean {
+  return char.toLowerCase() !== char && char.toUpperCase() === char;
+}
+
+function atBoundary(value: string, start: number): boolean {
+  return start === 0 || !isTokenChar(value, start - 1);
+}
+
+function matchPrefix(value: string, start: number): Match | null {
+  if (!atBoundary(value, start)) return null;
+  for (const [prefix, minimum, label] of PREFIX_RULES) {
+    if (!value.startsWith(prefix, start)) continue;
+    let end = start + prefix.length;
+    while (end < value.length && isTokenChar(value, end)) end += 1;
+    if (end - start - prefix.length >= minimum) return [end - start, label];
+  }
+  return null;
+}
+
+function matchJwt(value: string, start: number): Match | null {
+  if (!atBoundary(value, start) || !value.startsWith("eyJ", start)) return null;
+  let end = start;
+  let segments = 0;
+  while (segments < 3) {
+    const segmentStart = end;
+    while (end < value.length) {
+      const code = value.charCodeAt(end);
+      if (
+        !(
+          isAsciiAlnum(code) ||
+          code === 0x2d /* - */ ||
+          code === 0x5f /* _ */ ||
+          code === 0x3d /* = */
+        )
+      ) {
+        break;
+      }
+      end += 1;
+    }
+    if (end === segmentStart) break;
+    segments += 1;
+    if (segments < 3 && end < value.length && value[end] === ".") {
+      end += 1;
+    } else if (segments < 3) {
+      break;
+    }
+  }
+  const length = end - start;
+  return segments === 3 && length >= 40 ? [length, "jwt"] : null;
+}
+
+function matchBearer(value: string, start: number): Match | null {
+  if (value.slice(start, start + 7).toLowerCase() !== "bearer ") return null;
+  let end = start + 7;
+  let tokenBytes = 0;
+  while (end < value.length) {
+    const char = value[end]!;
+    if (isSpaceChar(char) || char === '"' || char === "'") break;
+    tokenBytes += utf8LenAt(value, end);
+    end += 1;
+  }
+  return tokenBytes >= 8 ? [end - start, "bearer-token"] : null;
+}
+
+function isSecretName(name: string): boolean {
+  const raw = name.replace(/^-+/, "").replace(/-+$/, "");
+  const lowered = raw.toLowerCase();
+  const compound =
+    raw.includes("_") ||
+    raw.includes("-") ||
+    Array.from(raw.slice(1)).some((char) => isUpperChar(char));
+  return (
+    STRONG_SECRET_NAMES.some((part) => lowered.endsWith(part)) ||
+    (compound && WEAK_SECRET_NAMES.some((part) => lowered.endsWith(part)))
+  );
+}
+
+const OPAQUE_VALUE_PREFIXES = ["{", "$", "<", "(", "`", "[redacted:"] as const;
+
+function isLiteralSecret(value: string): boolean {
+  return (
+    utf8Length(value) >= MIN_ASSIGNMENT_VALUE &&
+    !OPAQUE_VALUE_PREFIXES.some((prefix) => value.startsWith(prefix))
+  );
+}
+
+function matchAssignment(value: string, start: number): Match | null {
+  if (start === 0) return null;
+  if (value[start - 1] === "=" && (value[start] === '"' || value[start] === "'")) return null;
+
+  const previous = value[start - 1]!;
+  const quote = previous === '"' || previous === "'" ? previous : null;
+  const equals = quote ? start - 2 : start - 1;
+  if (equals < 0 || value[equals] !== "=") return null;
+
+  let nameStart = equals;
+  while (nameStart > 0) {
+    if (!isTokenChar(value, nameStart - 1)) break;
+    nameStart -= 1;
+  }
+  if (nameStart === equals) return null;
+  if (
+    !isSecretName(value.slice(nameStart, equals)) ||
+    ["{", "$", "<", "(", "`"].some((prefix) => value.startsWith(prefix, start))
+  ) {
+    return null;
+  }
+
+  let end = start;
+  let valueBytes = 0;
+  while (end < value.length) {
+    const char = value[end]!;
+    if (
+      (quote && char === quote) ||
+      (!quote && (isSpaceChar(char) || char === ";" || char === "&" || char === '"' || char === "'"))
+    ) {
+      break;
+    }
+    valueBytes += utf8LenAt(value, end);
+    end += 1;
+  }
+  return valueBytes >= MIN_ASSIGNMENT_VALUE ? [end - start, "secret-assignment"] : null;
+}
+
+/** The minimally redacted string and the replacement count. */
+export function scrubString(value: string): [string, number] {
+  const out: string[] = [];
+  let cursor = 0;
+  let copiedThrough = 0;
+  let hits = 0;
+  while (cursor < value.length) {
+    const match =
+      matchPrefix(value, cursor) ??
+      matchJwt(value, cursor) ??
+      matchBearer(value, cursor) ??
+      matchAssignment(value, cursor);
+    if (match === null) {
+      cursor += 1;
+      continue;
+    }
+    const [length, label] = match;
+    out.push(value.slice(copiedThrough, cursor));
+    out.push(`[redacted:${label}]`);
+    cursor += length;
+    copiedThrough = cursor;
+    hits += 1;
+  }
+  if (hits === 0) return [value, 0];
+  out.push(value.slice(copiedThrough));
+  return [out.join(""), hits];
+}
+
+/** Read the daemon's redaction switch, defaulting safely to minimal. */
+export function redactionEnabled(baseDir: string): boolean {
+  const configuredHome = process.env.FAILPROOFAI_HOME;
+  let configPath: string;
+  if (basename(baseDir) === "custom-agents") {
+    configPath = join(dirname(baseDir), "config.json");
+  } else if (configuredHome) {
+    configPath = join(configuredHome, "config.json");
+  } else {
+    configPath = join(homedir(), ".failproofai", "config.json");
+  }
+  try {
+    const config: unknown = JSON.parse(readFileSync(configPath, "utf-8"));
+    if (typeof config !== "object" || config === null || Array.isArray(config)) return true;
+    const collector = (config as Record<string, unknown>).collector;
+    if (typeof collector !== "object" || collector === null || Array.isArray(collector)) {
+      return true;
+    }
+    return (collector as Record<string, unknown>).redact !== "off";
+  } catch {
+    // A missing, unreadable or malformed config means we do not know the
+    // operator's intent — so redact. Failing open here would mean one typo in
+    // `config.json` silently ships credentials.
+    return true;
+  }
+}
+
+/** Redact credential-shaped keys and string values in a valid JSON event line. */
+export function redactJsonLine(encoded: string): string {
+  const event: unknown = JSON.parse(encoded);
+  let hits = 0;
+
+  const scrub = (value: unknown, fieldName?: string): unknown => {
+    if (typeof value === "string") {
+      const [scrubbed, count] = scrubString(value);
+      hits += count;
+      if (count === 0 && typeof fieldName === "string" && isSecretName(fieldName)) {
+        if (isLiteralSecret(scrubbed)) {
+          hits += 1;
+          return "[redacted:secret-assignment]";
+        }
+      }
+      return scrubbed;
+    }
+    if (Array.isArray(value)) {
+      // Elements are more values for the same field, so its name still applies.
+      return value.map((item) => scrub(item, fieldName));
+    }
+    if (typeof value === "object" && value !== null) {
+      const result: Record<string, unknown> = {};
+      for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+        const [redactedKey, count] = scrubString(key);
+        hits += count;
+        let uniqueKey = redactedKey;
+        let suffix = 2;
+        while (Object.prototype.hasOwnProperty.call(result, uniqueKey)) {
+          uniqueKey = `${redactedKey}#${suffix}`;
+          suffix += 1;
+        }
+        result[uniqueKey] = scrub(item, key);
+      }
+      return result;
+    }
+    return value;
+  };
+
+  const redacted = scrub(event);
+  return hits ? JSON.stringify(redacted) : encoded;
+}
+
+export { isSecretName, isLiteralSecret };

package/.next/standalone/sdk/typescript/src/resolver.ts

@@ -0,0 +1,120 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+
+import { shared } from "./shared.js";
+
+/**
+ * Where this SDK writes its event spool.
+ *
+ * Resolution order, most explicit first:
+ *
+ *   1. `setBaseDir()`                 — a caller said so outright
+ *   2. `~/.failproofai/custom-agents` — always
+ *
+ * There is no environment variable that redirects the spool off the umbrella,
+ * and that is the point. `FAILPROOFAI_HOME` (honoured by
+ * `failproofaiCustomAgentsDir()` below) MOVES the umbrella; it cannot take you
+ * outside it, because the `custom-agents` segment is appended unconditionally.
+ * Wherever the home is, the spool is inside it.
+ *
+ * ## Why `$AGENTEYE_HOME` does not resolve here
+ *
+ * In the Python SDK it used to sit at step 2 and win over the default, which
+ * made it possible to aim the SDK at `~/.agenteye` — or anywhere else — from
+ * the environment. That is a redirect with no confirmation and no error:
+ * batches land in a directory, something may or may not read it, and an unread
+ * spool is indistinguishable from an idle one. An operator who exports it for
+ * the OTHER component that reads it (the older `agenteye-collector`) moved the
+ * SDK's spool as a side effect they never asked for. This SDK never had it.
+ *
+ * ## Nothing is stranded by this
+ *
+ * `failproofaid`, the daemon this SDK ships beside, watches BOTH
+ * `~/.failproofai/custom-agents/events` AND `~/.agenteye/events`
+ * (`crates/fpai-collect/src/config.rs`, `spool_dirs`). Batches sitting under
+ * the legacy root still drain.
+ *
+ * ## The one case that needs a deliberate choice
+ *
+ * A host running the older `agenteye-collector` and nothing else. That
+ * collector never learned the umbrella, so it does not watch where this SDK
+ * writes. The supported bridges, in order of preference:
+ *
+ *   * run `failproofaid` instead — it watches both roots; or
+ *   * point the collector AT the SDK with
+ *     `AGENTEYE_HOME=~/.failproofai/custom-agents`; or
+ *   * `configure({ baseDir: "~/.agenteye" })` in the application, which is
+ *     explicit, visible at the call site, and cannot happen by inheriting
+ *     somebody else's environment.
+ *
+ * `test/spool-contract.test.ts` reads the Rust, the TypeScript in `src/hooks/`
+ * and the Python resolver and fails if any of them drifts from this.
+ */
+export function getBaseDir(): string {
+  const baseDir = shared().baseDir;
+  if (baseDir !== null) return baseDir;
+  return failproofaiCustomAgentsDir();
+}
+
+/**
+ * `~/.failproofai/custom-agents`, honouring `$FAILPROOFAI_HOME`.
+ *
+ * Mirrors `customAgentsDir()` in `src/hooks/fp-home.ts`,
+ * `custom_agents_events_dir()` in `crates/fpai-collect/src/config.rs` and
+ * `failproofai_custom_agents_dir()` in the Python SDK. All four must agree; a
+ * divergence would mean this SDK writes somewhere the daemon never reads, with
+ * NO error on either side.
+ *
+ * Returns a path unconditionally and never checks whether it exists. The caller
+ * creates it: `writer`'s file write already does a recursive `mkdir` on the
+ * directory it is about to write into. An existence check here is what made an
+ * earlier opt-in dead — a spool root that must pre-exist can never be the place
+ * a first batch is written.
+ */
+export function failproofaiCustomAgentsDir(): string {
+  const fpHome = process.env.FAILPROOFAI_HOME;
+  const base = fpHome ? expandUser(fpHome) : join(homedir(), ".failproofai");
+  return join(base, "custom-agents");
+}
+
+/**
+ * `~/.agenteye` — the root the SDK family wrote to before the default moved.
+ *
+ * Not part of resolution, and no environment variable can put it back — see
+ * `getBaseDir`. Kept as a named constant because the migration notes and the
+ * tests still refer to it, and because `failproofaid` goes on watching
+ * `~/.agenteye/events`. Spelling it in four places is how the sides drift apart.
+ */
+export function legacyAgenteyeDir(): string {
+  return join(homedir(), ".agenteye");
+}
+
+/**
+ * Expand a leading `~` against the current user's home.
+ *
+ * Load-bearing, not a nicety: the migration bridge this module itself
+ * prescribes — `configure({ baseDir: "~/.agenteye" })`, listed in `getBaseDir`'s
+ * docs and in the README as the explicit, visible-at-the-call-site option — is
+ * a RELATIVE path whose first segment is the literal character `~`. Without
+ * this, the writer's recursive `mkdir` cheerfully creates a `~` directory under
+ * the process's cwd and spools into it: nothing on the machine watches that
+ * path, so 100% of the telemetry is lost, which is the precise "an unread spool
+ * is indistinguishable from an idle one" failure the prose above is written to
+ * prevent.
+ */
+export function expandUser(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith(`~${sep}`) || path.startsWith("~/")) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+export function setBaseDir(path: string | null | undefined): void {
+  if (path === null || path === undefined) {
+    shared().baseDir = null;
+    return;
+  }
+  const expanded = expandUser(path);
+  shared().baseDir = isAbsolute(expanded) ? expanded : resolve(expanded);
+}

package/.next/standalone/sdk/typescript/src/runtime.ts

@@ -0,0 +1,29 @@
+/**
+ * The process-wide writer and event namespace.
+ *
+ * These live in a leaf module so that `scopes.ts` and the framework adapters
+ * can reach the namespace without importing the package index, which would be
+ * a circular import.
+ *
+ * Constructing `EventWriter` starts the flush interval and registers the
+ * module-level exit flush, and that happens at `import "@failproofai/sdk"`
+ * time — the index imports this module, so the timing matches the Python SDK's.
+ * The interval is `unref`'d, so importing this package never keeps a process
+ * alive on its own.
+ *
+ * Reach the namespace through the `runtime` object rather than a direct named
+ * import, so a test can swap in a recording namespace and the scopes and
+ * adapters pick it up. A `let` export would work under ESM live bindings and
+ * silently not under the CJS build, which is exactly the kind of difference
+ * that shows up only in somebody else's project.
+ */
+
+import { EventNamespace } from "./events.js";
+import { EventWriter } from "./writer.js";
+
+const writer = new EventWriter();
+
+export const runtime: { writer: EventWriter; event: EventNamespace } = {
+  writer,
+  event: new EventNamespace(writer),
+};