@fiscalmindset/blindfold 0.4.0

package/src/usage-log.ts

@@ -0,0 +1,149 @@
+/**
+ * Append-only usage log for the Blindfold proxy.
+ *
+ * SAFETY: this module records ONLY non-sensitive metadata. It never
+ * writes request bodies, response bodies, or any header values to disk.
+ * The dashboard and stats commands read from the same file and inherit
+ * this constraint by construction.
+ *
+ * Default path: ./.blindfold/usage.jsonl   (overridable via env BLINDFOLD_USAGE_LOG)
+ *
+ * Format: one JSON object per line (JSONL). Schema below.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { stateDir } from "./env.ts";
+
+export interface UsageEvent {
+  /** ISO-8601 timestamp */
+  t: string;
+  /** "real" if a T3 contract was called, "mock" if the local stub responded */
+  mode: "real" | "mock";
+  /** Provider derived from the URL, e.g. "openai", "anthropic" */
+  provider: string;
+  /** HTTP method the agent used */
+  method: string;
+  /** Path the agent hit on the proxy (e.g. /v1/chat/completions) */
+  path: string;
+  /** Upstream URL the contract was asked to call */
+  upstream: string;
+  /** Response status code */
+  status: number;
+  /** End-to-end latency through the proxy (ms) */
+  latency_ms: number;
+  /** True if the agent supplied any Authorization header at all (interesting telemetry: did it think it had a key?) */
+  agent_supplied_auth: boolean;
+  /** True iff the outbound request carries the Blindfold sentinel — proof the proxy did its job */
+  sentinel_in_outbound: boolean;
+  /** Auth scheme the enclave applied: "bearer" | "basic" | "sigv4". Optional for back-compat. */
+  auth_scheme?: string;
+  /** How the secret was used: "proxy" (HTTP proxy) | "release"/"use"/"export" (broker paths). Optional for back-compat. */
+  via?: string;
+  /** The sealed secret name involved (for the per-secret view). */
+  secret_key?: string;
+}
+
+export function defaultLogPath(): string {
+  return process.env.BLINDFOLD_USAGE_LOG ?? path.join(stateDir(), "usage.jsonl");
+}
+
+const USAGE_MAX_BYTES = Number(process.env.BLINDFOLD_USAGE_MAX_BYTES) || 10 * 1024 * 1024;
+
+/** Rotate usage.jsonl → .1 → .2 when it grows past the size cap. */
+function rotateIfNeeded(p: string): void {
+  try {
+    const size = fs.statSync(p).size;
+    if (size < USAGE_MAX_BYTES) return;
+    if (fs.existsSync(`${p}.1`)) fs.renameSync(`${p}.1`, `${p}.2`);
+    fs.renameSync(p, `${p}.1`);
+  } catch {
+    /* stat/rename failures must not break the request path */
+  }
+}
+
+// Hot-path telemetry must not block the event loop (S4): ensure the dir once,
+// throttle the rotation stat, and append asynchronously (fire-and-forget).
+const ensuredDirs = new Set<string>();
+const ROTATE_CHECK_EVERY = 500;
+let writesSinceRotateCheck = ROTATE_CHECK_EVERY; // check on the first write
+
+export function logUsage(event: UsageEvent): void {
+  const p = defaultLogPath();
+  try {
+    const dir = path.dirname(p);
+    if (!ensuredDirs.has(dir)) { fs.mkdirSync(dir, { recursive: true }); ensuredDirs.add(dir); }
+    if (++writesSinceRotateCheck >= ROTATE_CHECK_EVERY) { writesSinceRotateCheck = 0; rotateIfNeeded(p); }
+    fs.appendFile(p, JSON.stringify(event) + "\n", () => { /* never throw on the request path */ });
+  } catch {
+    // Logging is never allowed to throw and crash a request path.
+  }
+}
+
+export function readUsage(): UsageEvent[] {
+  const p = defaultLogPath();
+  if (!fs.existsSync(p)) return [];
+  return fs
+    .readFileSync(p, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line) as UsageEvent;
+      } catch {
+        return null;
+      }
+    })
+    .filter((e): e is UsageEvent => e !== null);
+}
+
+/**
+ * Read only the last `n` events (byte-tail read), so a polled server never
+ * loads a multi-hundred-MB log into memory. Falls back to whole-file only for
+ * small files.
+ */
+export function readUsageTail(n = 500): UsageEvent[] {
+  const p = defaultLogPath();
+  if (!fs.existsSync(p)) return [];
+  const fd = fs.openSync(p, "r");
+  try {
+    const size = fs.fstatSync(fd).size;
+    // Read at most ~2KB per requested event from the end of the file.
+    const readLen = Math.min(size, Math.max(64 * 1024, n * 2048));
+    const buf = Buffer.alloc(readLen);
+    fs.readSync(fd, buf, 0, readLen, size - readLen);
+    let text = buf.toString("utf8");
+    if (readLen < size) {
+      // Drop a possibly-partial first line.
+      const nl = text.indexOf("\n");
+      if (nl >= 0) text = text.slice(nl + 1);
+    }
+    const events = text
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => { try { return JSON.parse(line) as UsageEvent; } catch { return null; } })
+      .filter((e): e is UsageEvent => e !== null);
+    return events.slice(-n);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+export function clearUsage(): void {
+  const p = defaultLogPath();
+  if (fs.existsSync(p)) fs.unlinkSync(p);
+}
+
+export function providerForUpstream(upstream: string): string {
+  try {
+    const u = new URL(upstream);
+    const h = u.hostname;
+    if (h.endsWith("openai.com")) return "openai";
+    if (h.endsWith("anthropic.com")) return "anthropic";
+    if (h.endsWith("googleapis.com")) return "google";
+    if (h.endsWith("x.ai")) return "xai";
+    if (h.endsWith("groq.com")) return "groq";
+    return h;
+  } catch {
+    return "unknown";
+  }
+}

package/src/versions.ts

@@ -0,0 +1,64 @@
+/**
+ * Local index of secret versions for rollback.
+ *
+ * When you `rotate` a secret, the PREVIOUS value is snapshotted into the enclave
+ * under a reserved key (`__bfver__<name>__<ts>`) — the value never leaves the
+ * enclave; only this metadata index is local. `rollback` reads the snapshot back
+ * and re-seals it under the live name.
+ *
+ * SAFETY: metadata only (name, the enclave version-key, byte-length, a
+ * non-reversible fingerprint, timestamp). Never the value. The reserved version
+ * keys are NOT recorded in the sealed-keys ledger, so `status`/`audit` ignore them.
+ *
+ * Default path: ./.blindfold/versions.jsonl (override via BLINDFOLD_VERSIONS_LOG)
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { stateDir } from "./env.ts";
+
+export interface VersionEntry {
+  t: string;            // ISO timestamp the snapshot was taken
+  name: string;         // the live secret name this is a version of
+  versionKey: string;   // reserved KV key holding the snapshot in the enclave
+  length: number;       // byte-length of the snapshotted value
+  fingerprint: string;  // sha256 prefix of the snapshotted value
+}
+
+export function defaultVersionsPath(): string {
+  return process.env.BLINDFOLD_VERSIONS_LOG ?? path.join(stateDir(), "versions.jsonl");
+}
+
+/** Build the reserved enclave key for a new snapshot of `name`. */
+export function versionKeyFor(name: string, stampMs: number): string {
+  return `__bfver__${name}__${stampMs}`;
+}
+
+/**
+ * Guard against a tampered versions.jsonl pointing `rollback` at an arbitrary
+ * enclave key: a legitimate versionKey is always `__bfver__<name>__<digits>`.
+ * (rollback additionally verifies the released value's fingerprint.)
+ */
+export function isValidVersionKey(name: string, versionKey: string): boolean {
+  return new RegExp(`^__bfver__${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}__\\d+$`).test(versionKey);
+}
+
+export function recordVersion(entry: VersionEntry): void {
+  const p = defaultVersionsPath();
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + "\n");
+  } catch {
+    /* never let version bookkeeping crash a rotate */
+  }
+}
+
+/** All version entries (optionally for one name), oldest-first. */
+export function readVersions(name?: string): VersionEntry[] {
+  const p = defaultVersionsPath();
+  if (!fs.existsSync(p)) return [];
+  const all = fs.readFileSync(p, "utf8")
+    .split("\n").filter(Boolean)
+    .map(l => { try { return JSON.parse(l) as VersionEntry; } catch { return null; } })
+    .filter((e): e is VersionEntry => e !== null);
+  return name ? all.filter(e => e.name === name) : all;
+}

package/src/wrap.ts

@@ -0,0 +1,122 @@
+/**
+ * Optional in-process integration:
+ *
+ *   import OpenAI from "openai";
+ *   import { wrap } from "blindfold";
+ *   const openai = wrap(new OpenAI({ apiKey: "__blindfold__" }));
+ *
+ * `wrap` replaces the OpenAI SDK's `fetch` with one that points at the
+ * local Blindfold proxy. The "apiKey" passed to OpenAI is meaningless;
+ * the SDK requires *some* string, so we use the sentinel.
+ *
+ * The wrap layer never sees the real key. Substitution happens inside
+ * the T3 contract, downstream.
+ */
+import http from "node:http";
+import { DEFAULT_PORT, SENTINEL } from "./constants.ts";
+
+export interface WrapOpts {
+  /** Defaults to http://127.0.0.1:<DEFAULT_PORT>/v1 */
+  baseUrl?: string;
+  /**
+   * Per-session proxy auth token. When set, the wrapped client sends it on
+   * every request as the `x-blindfold-token` header, so the proxy accepts calls
+   * only from this wrapped client (not any co-resident local process). Falls
+   * back to the `BLINDFOLD_PROXY_TOKEN` env var.
+   */
+  token?: string;
+  /**
+   * Route requests over a unix-domain socket (see `blindfold proxy --socket`)
+   * instead of a TCP host:port. The request URL's host is ignored; only its
+   * path is used. Falls back to the `BLINDFOLD_PROXY_SOCKET` env var.
+   */
+  socket?: string;
+}
+
+const PROXY_TOKEN_HEADER = "x-blindfold-token";
+
+/**
+ * A `fetch`-compatible function that sends the request over a unix-domain
+ * socket via node:http (`socketPath`). Only the URL's path+query is used; the
+ * host is irrelevant when talking to a socket. Optionally injects the
+ * per-session token header.
+ */
+function socketFetch(socketPath: string, token?: string): typeof fetch {
+  return (async (input: Parameters<typeof fetch>[0], init: Parameters<typeof fetch>[1] = {}) => {
+    const reqObj = typeof Request !== "undefined" && input instanceof Request ? input : undefined;
+    const rawUrl = reqObj ? reqObj.url : String(input);
+    const url = new URL(rawUrl);
+    const method = init?.method ?? reqObj?.method ?? "GET";
+    const headers = new Headers(init?.headers ?? reqObj?.headers);
+    if (token) headers.set(PROXY_TOKEN_HEADER, token);
+
+    const outHeaders: Record<string, string> = {};
+    headers.forEach((v, k) => { outHeaders[k] = v; });
+
+    return await new Promise<Response>((resolve, reject) => {
+      const req = http.request(
+        { socketPath, path: url.pathname + url.search, method, headers: outHeaders },
+        (res) => {
+          const chunks: Buffer[] = [];
+          res.on("data", (c) => chunks.push(c as Buffer));
+          res.on("end", () => {
+            const respHeaders = new Headers();
+            for (const [k, v] of Object.entries(res.headers)) {
+              if (typeof v === "string") respHeaders.set(k, v);
+              else if (Array.isArray(v)) respHeaders.set(k, v.join(", "));
+            }
+            resolve(new Response(Buffer.concat(chunks), {
+              status: res.statusCode ?? 502,
+              statusText: res.statusMessage ?? "",
+              headers: respHeaders,
+            }));
+          });
+        },
+      );
+      req.on("error", reject);
+      const body = init?.body;
+      if (body != null) {
+        if (typeof body === "string" || body instanceof Buffer || body instanceof Uint8Array) req.write(body);
+        else if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) req.write(body.toString());
+        else if (ArrayBuffer.isView(body as ArrayBufferView)) { const v = body as ArrayBufferView; req.write(Buffer.from(v.buffer, v.byteOffset, v.byteLength)); }
+        else if (body instanceof ArrayBuffer) req.write(Buffer.from(body));
+        else { req.destroy(); reject(new Error("socketFetch: unsupported body type (use string/Buffer/typed-array/URLSearchParams)")); return; }
+      }
+      req.end();
+    });
+  }) as typeof fetch;
+}
+
+/**
+ * Loose structural type — we don't want a hard dep on the openai package.
+ * Anything with `baseURL` and `fetch` (or `apiKey`) fields can be wrapped.
+ */
+export interface OpenAIish {
+  baseURL?: string;
+  apiKey?: string;
+  fetch?: typeof fetch;
+}
+
+export function wrap<T extends OpenAIish>(client: T, opts: WrapOpts = {}): T {
+  const baseUrl = opts.baseUrl ?? `http://127.0.0.1:${DEFAULT_PORT}/v1`;
+  client.baseURL = baseUrl;
+  client.apiKey = SENTINEL;
+
+  const token = (opts.token ?? process.env.BLINDFOLD_PROXY_TOKEN ?? "").trim() || undefined;
+  const socket = (opts.socket ?? process.env.BLINDFOLD_PROXY_SOCKET ?? "").trim() || undefined;
+
+  if (socket) {
+    // Talk to the proxy over its unix-domain socket (adds the token too, if set).
+    client.fetch = socketFetch(socket, token);
+  } else if (token) {
+    // Inject the per-session token on every outbound request without a hard
+    // dep on the OpenAI SDK: wrap whatever fetch the client uses.
+    const base = client.fetch ?? fetch;
+    client.fetch = ((input: Parameters<typeof fetch>[0], init: Parameters<typeof fetch>[1] = {}) => {
+      const headers = new Headers(init?.headers);
+      headers.set(PROXY_TOKEN_HEADER, token);
+      return base(input, { ...init, headers });
+    }) as typeof fetch;
+  }
+  return client;
+}