pi-harness-runtime 0.10.13 → 0.10.15

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

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+/**
+ * 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) {
+    if (typeof text !== "string" || text.length === 0)
+        return [];
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    if (Array.isArray(data)) {
+        for (const item of data) {
+            if (item && typeof item === "object" && !Array.isArray(item)) {
+                records.push(item);
+            }
+        }
+    }
+    else if (data && typeof data === "object" && !Array.isArray(data)) {
+        records.push(data);
+    }
+    const cookies = [];
+    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) {
+    if (typeof v === "string" && v.length > 0)
+        return v;
+    return undefined;
+}
+function asBool(v) {
+    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, session) {
+    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.js

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * 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) {
+    if (typeof text !== "string" || text.length === 0)
+        return [];
+    const rows = [];
+    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) {
+    const out = ["# 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";
+}

package/packages/cookie-sanitizer/src/sync.js

@@ -0,0 +1,268 @@
+/**
+ * Sync orchestrator — the heart of the sanitizer.
+ *
+ * Pipeline (per run):
+ *   1. Enumerate files in the drop folder (one level + one sublevel).
+ *   2. Read each file. Detect format. Parse.
+ *   3. Concatenate cookies from all parsed files.
+ *   4. Infer provider from filename + cookies.
+ *   5. Normalize (dedupe, expire, domain-match).
+ *   6. Serialize to Netscape and write to the canonical cache (atomic).
+ *
+ * Returns a SyncResult. Never throws — returns structured errors in `result.errors`.
+ *
+ * Sec-001: Cookie VALUES never appear in any log line. Diagnostics
+ * use file basenames and 64-char previews with values redacted.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, } from "node:fs";
+import { join } from "node:path";
+import { buildDetectedFile, safePreview } from "./detect-format.js";
+import { parseNetscape, serializeNetscape } from "./parse-netscape.js";
+import { parseEditThisCookieJson } from "./parse-json.js";
+import { normalize } from "./normalize.js";
+import { inferProvider } from "./infer-provider.js";
+import { atomicWriteFileSync, defaultCachePathFor } from "./atomic-write.js";
+/** Max depth for the drop-folder walk (one-level + one subfolder). */
+const MAX_DEPTH = 2;
+/** Max size of a single input file we'll parse (5 MB). */
+const MAX_INPUT_BYTES = 5 * 1024 * 1024;
+/** Default drop-folder location. */
+export const DEFAULT_DROP_DIR = join(process.env.HOME ?? "/tmp", ".pi-harness-runtime", "cookies");
+/**
+ * Enumerate readable files inside `dir`, up to MAX_DEPTH.
+ * Returns absolute paths. Skips dotfiles, editor temp files.
+ *
+ * `excludePath` (optional) — absolute path of a file to skip, e.g.
+ * the canonical cache file (so we never recursively read it).
+ */
+export function enumerateDropFiles(dir, excludePath) {
+    if (!existsSync(dir))
+        return [];
+    let stat;
+    try {
+        stat = statSync(dir);
+    }
+    catch {
+        return [];
+    }
+    if (!stat.isDirectory())
+        return [];
+    const result = [];
+    function walk(current, depth) {
+        if (depth > MAX_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(current);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            // Skip dotfiles, editor temp/swap.
+            if (name.startsWith("."))
+                continue;
+            if (name.endsWith("~") || name.endsWith(".swp"))
+                continue;
+            const full = join(current, name);
+            if (excludePath && full === excludePath)
+                continue;
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isFile()) {
+                result.push(full);
+            }
+            else if (st.isDirectory() && depth < MAX_DEPTH) {
+                walk(full, depth + 1);
+            }
+        }
+    }
+    walk(dir, 0);
+    return result;
+}
+/**
+ * Read a single input file as text, capped at MAX_INPUT_BYTES.
+ * Returns null + a `reason` if the file can't be read.
+ */
+export function readInputFile(filePath) {
+    let stat;
+    try {
+        stat = statSync(filePath);
+    }
+    catch {
+        return { text: "", reason: "file not accessible" };
+    }
+    if (!stat.isFile())
+        return { text: "", reason: "not a regular file" };
+    if (stat.size > MAX_INPUT_BYTES) {
+        return { text: "", reason: `file too large (${stat.size} bytes)` };
+    }
+    try {
+        return { text: readFileSync(filePath, "utf8") };
+    }
+    catch (e) {
+        return {
+            text: "",
+            reason: `read failed: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+}
+/**
+ * Run the full sync pipeline.
+ *
+ * Options:
+ *   - dropDir      default: ~/.pi-harness-runtime/cookies/
+ *   - cachePath    default: ~/.config/<provider>-cookies.txt
+ *   - providerHint override inference (skips filename/domain checks)
+ *   - dryRun       skip the actual file write (still returns would-be result)
+ *
+ * Returns a SyncResult. Never throws.
+ */
+export function sync(opts = {}) {
+    const dropDir = opts.dropDir ?? DEFAULT_DROP_DIR;
+    // Ensure the drop directory exists so users don't need to mkdir manually
+    if (!existsSync(dropDir))
+        mkdirSync(dropDir, { recursive: true });
+    const tmpResult = {
+        provider: null,
+        processedFiles: [],
+        skippedFiles: [],
+        totalCookies: 0,
+        cachePath: "",
+        sourceDir: dropDir,
+        wrote: false,
+        errors: [],
+    };
+    const files = enumerateDropFiles(dropDir, opts.cachePath);
+    if (files.length === 0) {
+        // Nothing to do — no error, just nothing. Caller decides whether
+        // to surface this to the user.
+        return tmpResult;
+    }
+    const allCookies = [];
+    let firstBasename;
+    for (const filePath of files) {
+        const { text, reason } = readInputFile(filePath);
+        if (reason) {
+            const det = buildDetectedFile(filePath, "");
+            tmpResult.skippedFiles.push({ basename: det.basename, reason });
+            tmpResult.errors.push({ basename: det.basename, message: reason });
+            continue;
+        }
+        const det = buildDetectedFile(filePath, text);
+        if (det.format == null) {
+            const preview = safePreview(text);
+            tmpResult.skippedFiles.push({
+                basename: det.basename,
+                reason: `unrecognised format (preview: ${preview})`,
+            });
+            tmpResult.errors.push({
+                basename: det.basename,
+                message: "unrecognised format",
+            });
+            continue;
+        }
+        let cookies = [];
+        if (det.format === "netscape") {
+            cookies = parseNetscape(text);
+        }
+        else if (det.format === "edit-this-cookie-json") {
+            cookies = parseEditThisCookieJson(text);
+        }
+        if (cookies.length === 0) {
+            tmpResult.skippedFiles.push({
+                basename: det.basename,
+                reason: `${det.format} parsed but yielded 0 cookies`,
+            });
+            continue;
+        }
+        allCookies.push(...cookies);
+        tmpResult.processedFiles.push(det.basename);
+        if (!firstBasename)
+            firstBasename = det.basename;
+    }
+    if (allCookies.length === 0) {
+        return tmpResult;
+    }
+    const provider = inferProvider(firstBasename, allCookies, opts.providerHint);
+    if (!provider) {
+        tmpResult.errors.push({
+            basename: firstBasename ?? "<unknown>",
+            message: "could not infer provider (no filename/domain match)",
+        });
+        return tmpResult;
+    }
+    tmpResult.provider = provider;
+    const cachePath = opts.cachePath ?? defaultCachePathFor(provider);
+    tmpResult.cachePath = cachePath;
+    const normalized = normalize(allCookies, provider);
+    tmpResult.totalCookies = normalized.length;
+    if (normalized.length === 0) {
+        // All cookies were filtered (expired / wrong domain).
+        tmpResult.errors.push({
+            basename: firstBasename ?? "<unknown>",
+            message: "all cookies filtered (expired or wrong-provider domain)",
+        });
+        return tmpResult;
+    }
+    if (opts.dryRun) {
+        tmpResult.wrote = false;
+        return tmpResult;
+    }
+    const serialized = serializeNetscape(normalized);
+    try {
+        atomicWriteFileSync(cachePath, serialized);
+        tmpResult.wrote = true;
+    }
+    catch (e) {
+        tmpResult.errors.push({
+            basename: firstBasename ?? "<unknown>",
+            message: `atomic write failed: ${e instanceof Error ? e.message : String(e)}`,
+        });
+    }
+    return tmpResult;
+}
+/**
+ * Has-any-input check: true if the drop folder has anything readable.
+ * Cheap — does a single `readdirSync`; no parsing.
+ */
+export function hasAnyCookieSource(dropDir = DEFAULT_DROP_DIR) {
+    return enumerateDropFiles(dropDir).length > 0;
+}
+/**
+ * Convenience: cache path for the dominant provider in the drop folder,
+ * or null if nothing's there. Used by `footer-status.ts` to ask "should
+ * the footer hint point at this provider?"
+ */
+export function inferCachePath(dropDir = DEFAULT_DROP_DIR) {
+    const files = enumerateDropFiles(dropDir);
+    if (files.length === 0)
+        return null;
+    let firstBasename;
+    const cookies = [];
+    for (const fp of files) {
+        const { text } = readInputFile(fp);
+        if (!text)
+            continue;
+        const det = buildDetectedFile(fp, text);
+        if (!det.format)
+            continue;
+        if (det.format === "netscape")
+            cookies.push(...parseNetscape(text));
+        else if (det.format === "edit-this-cookie-json")
+            cookies.push(...parseEditThisCookieJson(text));
+        if (!firstBasename)
+            firstBasename = det.basename;
+    }
+    const provider = inferProvider(firstBasename, cookies);
+    if (!provider)
+        return null;
+    return defaultCachePathFor(provider);
+}
+export { inferProvider, inferProviderFromFilename, inferProviderFromCookies, } from "./infer-provider.js";
+export { defaultCachePathFor } from "./atomic-write.js";

package/packages/cookie-sanitizer/src/types.js

@@ -0,0 +1,12 @@
+/**
+ * Cookie sanitizer types.
+ *
+ * The data model is intentionally simple and explicit. Cookies flow in
+ * from one of two input formats (Netscape, EditThisCookie JSON), are
+ * normalised here into a canonical record, and written out as a single
+ * standard Netscape file by the writer.
+ *
+ * Cookie values are NEVER logged anywhere. They live in memory only
+ * for the duration of one parse → normalize → write cycle.
+ */
+export {};

package/packages/cookie-sanitizer/src/watcher.js

@@ -0,0 +1,147 @@
+/**
+ * Live cookie-folder watcher.
+ *
+ * Wraps chokidar v5 with the project-specific options:
+ *  - `atomic: 100`           — EditThisCookie / browser exporters use atomic write
+ *  - `awaitWriteFinish`      — wait for size to settle before triggering
+ *  - `ignoreInitial: true`   — startup is handled by sync.ts separately
+ *  - `depth: 2`              — one level + one subfolder
+ *  - editor temp ignored
+ *
+ * Sec-001: Cookie values are NEVER logged. Diagnostics use only
+ * basenames, file paths, and event kinds.
+ */
+import chokidar from "chokidar";
+import { join } from "node:path";
+import { sync } from "./sync.js";
+const DEFAULT_DEBOUNCE_MS = 250;
+/** Wraps a chokidar watcher for the drop folder. */
+export class CookieWatcher {
+    watcher = null;
+    debounceMs;
+    debounceTimer = null;
+    log;
+    cfg;
+    running = false;
+    constructor(config) {
+        this.cfg = config;
+        this.debounceMs = config.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        this.log = config.logger ?? ((m) => console.log(`[cookie-sanitizer] ${m}`));
+    }
+    /** Start watching. Idempotent — calling twice is a no-op. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.watcher = chokidar.watch(this.cfg.dropDir, {
+            ignored: (targetPath) => {
+                const base = targetPath.split("/").pop() ?? "";
+                if (base.startsWith("."))
+                    return true;
+                if (base.endsWith("~") || base.endsWith(".swp"))
+                    return true;
+                if (base.endsWith(".tmp"))
+                    return true;
+                // Exclude the canonical cache file (if specified) so the
+                // sanitizer's own write doesn't trigger a re-sync.
+                if (this.cfg.syncOptions?.cachePath &&
+                    targetPath === this.cfg.syncOptions.cachePath) {
+                    return true;
+                }
+                return false;
+            },
+            ignoreInitial: true,
+            persistent: true,
+            depth: 2,
+            atomic: 100,
+            awaitWriteFinish: {
+                stabilityThreshold: 200,
+                pollInterval: 50,
+            },
+        });
+        this.watcher.on("add", () => this.schedule());
+        this.watcher.on("change", () => this.schedule());
+        this.watcher.on("unlink", () => this.schedule());
+        this.watcher.on("error", (err) => {
+            this.log(`watcher error: ${err instanceof Error ? err.message : String(err)}`);
+            this.cfg.onEvent({
+                kind: "watcher-error",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        });
+        this.log(`watching ${this.cfg.dropDir}`);
+    }
+    /** Stop watching. Idempotent. */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+        this.log("stopped");
+    }
+    /** Trigger a sync immediately (bypass debounce). */
+    triggerNow() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.runSync();
+    }
+    schedule() {
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            this.runSync();
+        }, this.debounceMs);
+    }
+    runSync() {
+        try {
+            const result = sync(this.cfg.syncOptions ?? {});
+            if (result.errors.length > 0) {
+                for (const err of result.errors) {
+                    this.cfg.onEvent({
+                        kind: "sync-error",
+                        message: `${err.basename}: ${err.message}`,
+                    });
+                }
+            }
+            if (result.provider && result.wrote) {
+                this.cfg.onEvent({
+                    kind: "sync-ok",
+                    provider: result.provider,
+                    cachePath: result.cachePath,
+                    cookies: result.totalCookies,
+                });
+            }
+            else if (result.processedFiles.length === 0 &&
+                result.provider === null) {
+                this.cfg.onEvent({
+                    kind: "sync-skip",
+                    reason: "no usable cookies found",
+                });
+            }
+        }
+        catch (e) {
+            this.cfg.onEvent({
+                kind: "sync-error",
+                message: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+}
+/** Factory: a watcher that writes to a default no-op logger. */
+export function createWatcher(dropDir, syncOptions, onEvent) {
+    return new CookieWatcher({ dropDir, syncOptions, onEvent });
+}
+/** Compute a sensible dropDir for a given HOME override (test seam). */
+export function defaultDropDir(home = process.env.HOME ?? "/tmp") {
+    return join(home, ".pi-harness-runtime", "cookies");
+}