pi-harness-runtime 0.9.7 → 0.9.10

package/packages/cookie-sanitizer/src/atomic-write.ts

@@ -0,0 +1,79 @@
+/**
+ * Atomic file write — write to temp, fsync, then rename.
+ *
+ * POSIX `rename(2)` is atomic — on partial-write crash, the prior target
+ * file remains valid. We pair this with `fsync(tempfile)` so the temp
+ * file's data is durable on disk before the rename.
+ *
+ * Permissions: `0o600` (owner R/W only) to keep the canonical cache
+ * owner-readable.
+ *
+ * Sec-001: Cookie values go into the file content. The caller is
+ * responsible for value-handling hygiene; this module just writes
+ * bytes. We do not log the content.
+ */
+
+import {
+	mkdirSync,
+	openSync,
+	writeSync,
+	fsyncSync,
+	closeSync,
+	renameSync,
+	chmodSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import type { ProviderId } from "./types.js";
+
+/**
+ * Atomically write `content` to `finalPath`.
+ *
+ * Steps:
+ *   1. mkdir -p the parent directory
+ *   2. write to <finalPath>.tmp.<rand>  with mode 0o600
+ *   3. fsync the temp file
+ *   4. rename temp → final  (atomic on POSIX)
+ *   5. chmod final to 0o600  (in case rename preserved looser perms)
+ *
+ * Throws if any step fails. The original `finalPath` is unchanged
+ * until step 4 succeeds.
+ */
+export function atomicWriteFileSync(finalPath: string, content: string): void {
+	mkdirSync(dirname(finalPath), { recursive: true });
+
+	const rand = randomBytes(6).toString("hex");
+	const tempPath = `${finalPath}.tmp.${rand}`;
+
+	let fd: number | undefined;
+	try {
+		fd = openSync(tempPath, "w", 0o600);
+		writeSync(fd, Buffer.from(content, "utf8"));
+		fsyncSync(fd);
+	} finally {
+		if (fd !== undefined) closeSync(fd);
+	}
+
+	renameSync(tempPath, finalPath);
+
+	// Belt-and-braces in case rename preserved a looser mode from an
+	// existing file on some systems.
+	try {
+		chmodSync(finalPath, 0o600);
+	} catch {
+		// Filesystems that don't support chmod (e.g. FAT32) are not a
+		// target platform here — drop the error silently.
+	}
+}
+
+/**
+ * Compute the default cache path for a given provider, e.g.:
+ *   defaultCachePathFor("minimax") → "~/.config/minimax-cookies.txt"
+ *
+ * The home directory is read via `process.env.HOME` so tests can
+ * override it.
+ */
+export function defaultCachePathFor(provider: ProviderId): string {
+	const home = process.env.HOME ?? "/tmp";
+	return join(home, ".config", `${provider}-cookies.txt`);
+}

package/packages/cookie-sanitizer/src/detect-format.ts

@@ -0,0 +1,102 @@
+/**
+ * Format detection — does the input look like Netscape or EditThisCookie JSON?
+ *
+ * Detection rule:
+ *  - File extension `.json` AND first non-blank byte is `[` or `{`  →  JSON
+ *  - File content has `# Netscape HTTP Cookie File` header OR
+ *    ≥ 1 tab-separated 7-column row                              →  Netscape
+ *  - Otherwise                                                    →  unknown
+ *
+ * Cookie VALUES are never copied into return values that get logged.
+ * Only the basename and a 64-char prefix of the first non-blank line.
+ */
+
+import { basename } from "node:path";
+import type { CookieFileFormat, DetectedFile } from "./types.js";
+
+const HEADER_RE = /^# Netscape HTTP Cookie File/im;
+const MIN_TAB_COLS = 7;
+
+/**
+ * Returns the basename only, never a path that could leak directory
+ * structure. Safe to log.
+ */
+export function safeBasename(filePath: string): string {
+	return basename(filePath);
+}
+
+/**
+ * Safely truncated preview of a file's content (for diagnostics).
+ * Strips cookie values to avoid leaking secrets.
+ *
+ * Heuristic: any line that has a tab-separated name=value pair,
+ * replace the value column with `<redacted>`.
+ */
+export function safePreview(text: string, maxChars = 64): string {
+	const firstLine =
+		text
+			.split("\n")
+			.map((l) => l.trim())
+			.find((l) => l.length > 0) ?? "";
+	const redacted = firstLine
+		.split("\t")
+		.map((col, i) => (i >= 5 ? "<redacted>" : col))
+		.join("\t");
+	return redacted.length > maxChars
+		? `${redacted.slice(0, maxChars)}…`
+		: redacted;
+}
+
+/**
+ * Detect the format of cookie file text.
+ */
+export function detectFormat(text: string): CookieFileFormat | null {
+	if (typeof text !== "string" || text.length === 0) return null;
+
+	const trimmed = text.trimStart();
+	const firstByte = trimmed[0];
+
+	// JSON heuristic — array or object at the top.
+	if (firstByte === "[" || firstByte === "{") {
+		return "edit-this-cookie-json";
+	}
+
+	// Netscape heuristic — header OR a tab-separated 7-column row.
+	if (HEADER_RE.test(text)) {
+		return "netscape";
+	}
+
+	const lines = text.split(/\r?\n/);
+	for (const line of lines) {
+		if (!line || (line.startsWith("#") && !line.startsWith("#HttpOnly_"))) {
+			continue;
+		}
+		const trimmedLine = line.startsWith("#HttpOnly_")
+			? line.slice("#HttpOnly_".length)
+			: line;
+		const cols = trimmedLine.split("\t");
+		if (cols.length >= MIN_TAB_COLS) {
+			return "netscape";
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Build a DetectedFile from a path and its text contents.
+ * Used by sync.ts after reading the file from disk.
+ */
+export function buildDetectedFile(
+	filePath: string,
+	text: string,
+): DetectedFile {
+	const format = detectFormat(text);
+	return {
+		path: filePath,
+		basename: safeBasename(filePath),
+		format,
+		text,
+		// No error if format is null — unknown format is a normal case.
+	};
+}

package/packages/cookie-sanitizer/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Cookie Sanitizer — public API.
+ *
+ * Forgiving input → strict canonical cache for downstream consumers
+ * (e.g. MiniMaxQuotaScraper reads only `~/.config/minimax-cookies.txt`).
+ *
+ * The package is provider-agnostic but currently shipping with:
+ *   - filename hints: minimax, anthropic, openai, glm, openrouter
+ *   - domain hints : the matching provider domains
+ *
+ * Inputs accepted (auto-detected per file):
+ *   - Netscape HTTP Cookie File
+ *   - EditThisCookie / Chrome devtools JSON export
+ *
+ * @example
+ * ```typescript
+ * import { sync, hasAnyCookieSource, CookieWatcher } from "@pi-harness/cookie-sanitizer";
+ *
+ * // One-shot sync.
+ * const result = sync();
+ * console.log(result.provider, result.cachePath, result.totalCookies);
+ *
+ * // Live updates.
+ * const watcher = new CookieWatcher({
+ *   dropDir: "~/.pi-harness-runtime/cookies",
+ *   onEvent: (e) => console.log(e),
+ * });
+ * watcher.start();
+ * ```
+ */
+
+export {
+	sync,
+	hasAnyCookieSource,
+	inferCachePath,
+	enumerateDropFiles,
+	readInputFile,
+	DEFAULT_DROP_DIR,
+} from "./sync.js";
+
+export {
+	parseNetscape,
+	serializeNetscape,
+} from "./parse-netscape.js";
+
+export { parseEditThisCookieJson } from "./parse-json.js";
+
+export {
+	inferProvider,
+	inferProviderFromFilename,
+	inferProviderFromCookies,
+	knownProviders,
+} from "./infer-provider.js";
+
+export {
+	normalize,
+	domainMatchesProvider,
+	isExpired,
+} from "./normalize.js";
+
+export {
+	detectFormat,
+	buildDetectedFile,
+	safeBasename,
+	safePreview,
+} from "./detect-format.js";
+
+export {
+	atomicWriteFileSync,
+	defaultCachePathFor,
+} from "./atomic-write.js";
+
+export {
+	CookieWatcher,
+	createWatcher,
+	defaultDropDir,
+} from "./watcher.js";
+
+export type {
+	CanonicalCookie,
+	CookieFileFormat,
+	DetectedFile,
+	ProviderId,
+	SyncOptions,
+	SyncResult,
+	WatcherEvent,
+} from "./types.js";
+
+export type { CookieWatcherConfig } from "./watcher.js";

package/packages/cookie-sanitizer/src/infer-provider.ts

@@ -0,0 +1,103 @@
+/**
+ * Provider inference — figure out which provider a cookie dump belongs to
+ * without the user having to organize by subfolder.
+ *
+ * Three inference passes, first hit wins:
+ *   1. Filename hint    (e.g. `minimax-*.txt`, `*minimax.json` → "minimax")
+ *   2. Dominant domain  (≥ 80% of cookies on `*.minimax.io` → "minimax")
+ *   3. Nothing           → null (caller will surface a friendly error)
+ *
+ * Provider hint from SyncOptions overrides all of the above.
+ */
+
+import type { CanonicalCookie, ProviderId } from "./types.js";
+
+const FILENAME_HINTS: Array<{ pattern: RegExp; provider: ProviderId }> = [
+	{ pattern: /minimax/i, provider: "minimax" },
+	{ pattern: /anthropic|claude/i, provider: "anthropic" },
+	{ pattern: /openai|gpt|chatgpt/i, provider: "openai" },
+	{ pattern: /glm|z\.ai|zhipuai/i, provider: "glm" },
+	{ pattern: /openrouter/i, provider: "openrouter" },
+];
+
+const DOMAIN_HINTS: Array<{ pattern: RegExp; provider: ProviderId }> = [
+	{ pattern: /\.minimax\.io$|^minimax\.io$/i, provider: "minimax" },
+	{ pattern: /\.anthropic\.com$|^anthropic\.com$/i, provider: "anthropic" },
+	{
+		pattern: /\.openai\.com$|^openai\.com$|\.chatgpt\.com$|^chatgpt\.com$/i,
+		provider: "openai",
+	},
+	{
+		pattern: /\.z\.ai$|^z\.ai$|\.zhipuai\.cn$|^zhipuai\.cn$/i,
+		provider: "glm",
+	},
+	{ pattern: /\.openrouter\.ai$|^openrouter\.ai$/i, provider: "openrouter" },
+];
+
+/** Returns the first provider whose filename pattern matches, or null. */
+export function inferProviderFromFilename(filename: string): ProviderId | null {
+	if (!filename) return null;
+	for (const { pattern, provider } of FILENAME_HINTS) {
+		if (pattern.test(filename)) return provider;
+	}
+	return null;
+}
+
+/** Returns the provider whose domain is the dominant (≥ 80%) match. */
+export function inferProviderFromCookies(
+	cookies: CanonicalCookie[],
+): ProviderId | null {
+	if (!Array.isArray(cookies) || cookies.length === 0) return null;
+
+	const counts = new Map<ProviderId, number>();
+	let total = 0;
+	for (const c of cookies) {
+		if (!c.domain) continue;
+		total += 1;
+		for (const { pattern, provider } of DOMAIN_HINTS) {
+			if (pattern.test(c.domain.toLowerCase())) {
+				counts.set(provider, (counts.get(provider) ?? 0) + 1);
+				break;
+			}
+		}
+	}
+
+	if (total === 0) return null;
+	const threshold = Math.ceil(total * 0.8); // ≥ 80 %
+	let best: { provider: ProviderId; count: number } | null = null;
+	for (const [provider, count] of counts) {
+		if (count >= threshold && (!best || count > best.count)) {
+			best = { provider, count };
+		}
+	}
+	return best?.provider ?? null;
+}
+
+/**
+ * Combined inference: hint → filename → dominant domain → null.
+ *
+ * If `filename` is provided it takes priority over domain inference
+ * (filename hints are explicit). Domain inference is the fallback.
+ */
+export function inferProvider(
+	filename: string | undefined,
+	cookies: CanonicalCookie[],
+	hint?: ProviderId,
+): ProviderId | null {
+	if (hint) return hint;
+	if (filename) {
+		const fromName = inferProviderFromFilename(filename);
+		if (fromName) return fromName;
+	}
+	return inferProviderFromCookies(cookies);
+}
+
+/**
+ * Build a list of provider rules used by other parts of the package.
+ * Exposed for UI display (e.g. "which providers does this sanitizer know?").
+ */
+export function knownProviders(): ProviderId[] {
+	const set = new Set<ProviderId>();
+	for (const { provider } of FILENAME_HINTS) set.add(provider);
+	return Array.from(set);
+}

package/packages/cookie-sanitizer/src/normalize.ts

@@ -0,0 +1,92 @@
+/**
+ * Normalize step — dedupe, drop invalid/expired, set provider.
+ *
+ * Rules (applied in order):
+ *  1. Drop cookies with empty `name` or `value`.
+ *  2. Drop cookies whose domain doesn't match the inferred provider.
+ *  3. Drop expired cookies (expires in the past, not session).
+ *  4. Dedupe by `(domain, name)` — keep the LAST entry (most recent wins).
+ *  5. Mark each surviving cookie with the provider id.
+ *
+ * SEC-001: Cookie values are not touched here, but never logged.
+ */
+
+import type { CanonicalCookie, ProviderId } from "./types.js";
+
+/** Returns true if the cookie's domain matches the given provider's domain scope. */
+export function domainMatchesProvider(
+	domain: string,
+	provider: ProviderId,
+): boolean {
+	if (!domain) return false;
+	const d = domain.toLowerCase();
+	switch (provider) {
+		case "minimax":
+			return d === "minimax.io" || d.endsWith(".minimax.io");
+		case "anthropic":
+			return d === "anthropic.com" || d.endsWith(".anthropic.com");
+		case "openai":
+			return (
+				d === "openai.com" ||
+				d.endsWith(".openai.com") ||
+				d === "chatgpt.com" ||
+				d.endsWith(".chatgpt.com")
+			);
+		case "glm":
+			return (
+				d === "z.ai" ||
+				d.endsWith(".z.ai") ||
+				d === "zhipuai.cn" ||
+				d.endsWith(".zhipuai.cn")
+			);
+		case "openrouter":
+			return d === "openrouter.ai" || d.endsWith(".openrouter.ai");
+		default:
+			// Unknown provider — accept all and let downstream reject.
+			return true;
+	}
+}
+
+/** Returns true if the cookie is expired (in the past). Session cookies never expire. */
+export function isExpired(
+	cookie: CanonicalCookie,
+	nowSec: number = Math.floor(Date.now() / 1000),
+): boolean {
+	if (cookie.expires == null) return false; // session cookie
+	if (cookie.expires <= 0) return false; // 0 = session in Netscape
+	return cookie.expires < nowSec;
+}
+
+/**
+ * Normalize the union of all parsed cookies.
+ *
+ * @param cookies     Raw cookies from all parsed files
+ * @param provider    Inferred (or hinted) provider; used for domain filtering and tagging
+ * @param nowSec      Override for the current Unix seconds (test seam)
+ */
+export function normalize(
+	cookies: CanonicalCookie[],
+	provider: ProviderId,
+	nowSec: number = Math.floor(Date.now() / 1000),
+): CanonicalCookie[] {
+	if (!Array.isArray(cookies) || cookies.length === 0) return [];
+
+	const dedup = new Map<string, CanonicalCookie>();
+
+	for (const c of cookies) {
+		// Rule 1: empty fields.
+		if (!c.name || !c.value) continue;
+
+		// Rule 2: domain must match provider (skip for unknown provider).
+		if (provider && !domainMatchesProvider(c.domain, provider)) continue;
+
+		// Rule 3: expired.
+		if (isExpired(c, nowSec)) continue;
+
+		// Rule 4 + 5: dedupe by (domain, name); last wins. Tag with provider.
+		const key = `${c.domain}::${c.name}`;
+		dedup.set(key, { ...c, provider });
+	}
+
+	return Array.from(dedup.values());
+}

package/packages/cookie-sanitizer/src/parse-json.ts

@@ -0,0 +1,122 @@
+/**
+ * EditThisCookie / Chrome devtools JSON cookie export parser.
+ *
+ * Browser extension "EditThisCookie" and Chrome devtools both export
+ * cookies in this canonical shape (Chrome/Edge/Chromium cookie store):
+ *
+ * ```json
+ * [
+ *   {
+ *     "domain": ".minimax.io",
+ *     "expirationDate": 1760000000.123,
+ *     "hostOnly": false,
+ *     "httpOnly": true,
+ *     "name": "_token",
+ *     "path": "/",
+ *     "sameSite": "no_restriction",
+ *     "secure": true,
+ *     "session": false,
+ *     "storeId": "0",
+ *     "value": "...",
+ *     "id": 1
+ *   }
+ * ]
+ * ```
+ *
+ * Some tools may export a single object (not an array). Handle both.
+ *
+ * SEC-001: Cookie VALUES are returned as strings in-memory. Never logged.
+ */
+
+import type { CanonicalCookie } from "./types.js";
+
+interface EditThisCookieRecord {
+	domain?: unknown;
+	expirationDate?: unknown;
+	hostOnly?: unknown;
+	httpOnly?: unknown;
+	name?: unknown;
+	path?: unknown;
+	secure?: unknown;
+	session?: unknown;
+	value?: unknown;
+}
+
+/**
+ * Parse EditThisCookie / Chrome devtools JSON export.
+ *
+ * Accepts:
+ * - top-level array of records
+ * - top-level single object
+ *
+ * Skips:
+ * - non-object entries
+ * - records without non-empty name+value
+ *
+ * Never throws; returns empty array on parse failure.
+ */
+export function parseEditThisCookieJson(text: string): CanonicalCookie[] {
+	if (typeof text !== "string" || text.length === 0) return [];
+
+	let data: unknown;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		return [];
+	}
+
+	const records: EditThisCookieRecord[] = [];
+	if (Array.isArray(data)) {
+		for (const item of data) {
+			if (item && typeof item === "object" && !Array.isArray(item)) {
+				records.push(item as EditThisCookieRecord);
+			}
+		}
+	} else if (data && typeof data === "object" && !Array.isArray(data)) {
+		records.push(data as EditThisCookieRecord);
+	}
+
+	const cookies: CanonicalCookie[] = [];
+	for (const r of records) {
+		const name = asString(r.name);
+		const value = asString(r.value);
+		if (!name || !value) continue;
+
+		const expires = asExpires(r.expirationDate, r.session);
+
+		cookies.push({
+			name,
+			value,
+			domain: asString(r.domain) ?? "",
+			path: asString(r.path) ?? "/",
+			expires,
+			secure: asBool(r.secure) ?? false,
+			httpOnly: asBool(r.httpOnly) ?? false,
+		});
+	}
+
+	return cookies;
+}
+
+function asString(v: unknown): string | undefined {
+	if (typeof v === "string" && v.length > 0) return v;
+	return undefined;
+}
+
+function asBool(v: unknown): boolean | undefined {
+	if (typeof v === "boolean") return v;
+	if (v === 1 || v === "1" || v === "true" || v === "TRUE") return true;
+	if (v === 0 || v === "0" || v === "false" || v === "FALSE") return false;
+	return undefined;
+}
+
+function asExpires(v: unknown, session: unknown): number | undefined {
+	if (session === true || session === "true") return undefined;
+	if (typeof v === "number" && Number.isFinite(v)) {
+		// EditThisCookie uses unix-seconds (with millisecond decimals sometimes).
+		// If v > 1e12, it's milliseconds — convert.
+		const seconds = v > 1e12 ? Math.floor(v / 1000) : Math.floor(v);
+		return seconds > 0 ? seconds : undefined;
+	}
+	return undefined;
+}

package/packages/cookie-sanitizer/src/parse-netscape.ts

@@ -0,0 +1,118 @@
+/**
+ * Netscape-format cookie file parser.
+ *
+ * Format reference: https://curl.haxx.se/rfc/cookie_spec.html
+ *
+ * Each row is tab-separated, 7 columns:
+ *   domain  flag  path  secure  expires  name  value
+ *
+ * - Lines starting with `# ` are comments (skipped).
+ * - Lines starting with `#HttpOnly_` are HTTP-only cookies
+ *   (the leading `#HttpOnly_` is stripped, the rest is parsed normally).
+ * - Empty lines are skipped.
+ * - `expires` is Unix seconds; `0` or unparseable → session cookie.
+ * - Lines with fewer than 7 columns are skipped (malformed).
+ *
+ * SEC-001: Cookie values are returned as strings in-memory. They MUST
+ * never be logged. The scrubber in cookie-sanitizer applies value
+ * redaction before any path-touching log line.
+ */
+
+import type { CanonicalCookie } from "./types.js";
+
+/** Raw row as parsed from a Netscape file. */
+interface NetscapeRow {
+	domain: string;
+	path: string;
+	secure: boolean;
+	httpOnly: boolean;
+	expires: number; // 0 = session
+	name: string;
+	value: string;
+}
+
+/**
+ * Parse a Netscape-format cookie string into canonical records.
+ *
+ * Skips:
+ * - blank lines
+ * - comments (lines starting with `#` but not `#HttpOnly_`)
+ * - malformed rows (< 7 columns)
+ *
+ * Never throws; returns empty array if input is invalid.
+ */
+export function parseNetscape(text: string): CanonicalCookie[] {
+	if (typeof text !== "string" || text.length === 0) return [];
+
+	const rows: NetscapeRow[] = [];
+	const lines = text.split(/\r?\n/);
+
+	for (const raw of lines) {
+		if (!raw) continue;
+
+		let line = raw;
+		let httpOnly = false;
+		if (line.startsWith("#HttpOnly_")) {
+			httpOnly = true;
+			line = line.slice("#HttpOnly_".length);
+		} else if (line.startsWith("#")) {
+			// Plain comment line (Netscape / curl spec).
+			continue;
+		}
+
+		const cols = line.split("\t");
+		if (cols.length < 7) continue;
+
+		const [domain, _flag, cookiePath, secure, expires, name, value] = cols;
+		if (!name || !value) continue;
+
+		rows.push({
+			domain: (domain ?? "").trim(),
+			path: (cookiePath ?? "/").trim() || "/",
+			secure: (secure ?? "FALSE").toUpperCase() === "TRUE",
+			httpOnly,
+			expires: parseInt(expires ?? "0", 10) || 0,
+			name: name.trim(),
+			value, // intentional: keep as-is for in-memory pipeline; never log
+		});
+	}
+
+	// Map to CanonicalCookie shape.
+	return rows.map((r) => ({
+		name: r.name,
+		value: r.value,
+		domain: r.domain,
+		path: r.path,
+		expires: r.expires === 0 ? undefined : r.expires,
+		secure: r.secure,
+		httpOnly: r.httpOnly,
+	}));
+}
+
+/**
+ * Serialize a list of canonical cookies back to Netscape format.
+ * Used by atomic-write.ts to produce the canonical cache.
+ *
+ * Output uses the canonical column order:
+ *   domain  flag  path  secure  expires  name  value
+ *
+ * `flag` is FALSE per curl spec (HttpOnly is encoded as `#HttpOnly_`).
+ * Cookie values are NEVER logged during the round-trip.
+ */
+export function serializeNetscape(cookies: CanonicalCookie[]): string {
+	const out: string[] = ["# Netscape HTTP Cookie File", ""];
+
+	for (const c of cookies) {
+		if (!c.name || !c.value) continue;
+		const domain = c.domain ?? "";
+		const path = c.path ?? "/";
+		const secure = c.secure ? "TRUE" : "FALSE";
+		const expires = c.expires != null ? String(c.expires) : "0";
+		const line = [domain, "FALSE", path, secure, expires, c.name, c.value].join(
+			"\t",
+		);
+		out.push(c.httpOnly ? `#HttpOnly_${line}` : line);
+	}
+
+	return out.join("\n") + "\n";
+}