comber 0.1.0

package/dist/core/net.js

@@ -0,0 +1,39 @@
+import { checkNetworkEgress } from "./egress.js";
+/** Thrown when the egress guard blocks a target. The message names only the REASON,
+ *  never the URL, so a token-bearing URL can't leak through an error string/log. */
+export class EgressBlockedError extends Error {
+    constructor(reason) {
+        super(`network egress blocked: ${reason}`);
+        this.name = "EgressBlockedError";
+    }
+}
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_REDIRECTS = 5;
+/**
+ * `fetch` with the two baseline invariants applied. Follows redirects manually (bounded)
+ * when guarding so each hop is egress-checked; delegates to the platform's own redirect
+ * handling only in the `allowPrivate` escape hatch.
+ */
+export async function guardedFetch(url, init = {}, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (opts.allowPrivate) {
+        return await fetchImpl(url, { ...init, signal: init.signal ?? AbortSignal.timeout(timeoutMs) });
+    }
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        const decision = await checkNetworkEgress(current, opts.resolveHost);
+        if (!decision.allowed)
+            throw new EgressBlockedError(decision.reason ?? "blocked");
+        const res = await fetchImpl(current, {
+            ...init,
+            redirect: "manual",
+            signal: init.signal ?? AbortSignal.timeout(timeoutMs),
+        });
+        const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
+        if (!location)
+            return res;
+        current = new URL(location, current).toString();
+    }
+    throw new Error("too many redirects");
+}

package/dist/core/pipeline.js

@@ -0,0 +1,191 @@
+import { fallbackBlindSpots } from "./blind-spots.js";
+import { actionKey, elementSignature, surfaceFingerprint, traversalIntentOf } from "./safety.js";
+import { evaluateAction } from "./action-gate.js";
+/**
+ * THE merge point: exercise EVERY safe node in a surface exactly once via the driver's
+ * type-correct `exercise`, draining breakage and restoring baseline between each. The
+ * ElKind dispatch now lives behind `driver.exercise`; the core only partitions
+ * (discover / skip / navigate / exercise) and restores. `navigates` nodes (web: links)
+ * are counted and FOLLOWED by the frontier, never clicked. When an exercised node REPORTS
+ * it navigated somewhere new (`ExerciseResult.discovered` — native tap-only screens), those
+ * Addresses are handed to the frontier via `deps.enqueue` (inScope + dedup applied there).
+ */
+export async function exerciseState(snap, scope, deps) {
+    const { driver, cfg, triedSignatures, performedMutations, coverage, ledger } = deps;
+    coverage.blind(snap.blindSpots, snap.blindSpotDetails, snap.address.scope);
+    const blindSpotDetails = snap.blindSpotDetails ?? fallbackBlindSpots(snap.blindSpots, snap.address.scope, "surface could not be inspected");
+    for (const blindSpot of blindSpotDetails)
+        ledger?.recordBlindSpot(snap.address, blindSpot);
+    const baseAddr = snap.address;
+    const baselineFp = surfaceFingerprint(snap);
+    let acted = 0;
+    let regotoCount = 0;
+    for (const node of snap.nodes) {
+        if (deps.overBudget())
+            break;
+        const sig = elementSignature(node, scope);
+        if (triedSignatures.has(sig))
+            continue;
+        triedSignatures.add(sig);
+        coverage.discover(1);
+        const intent = traversalIntentOf(node);
+        // Partition (a partition, never a silent drop) — the effect-based action-floor. `deny`
+        // hard-skips (subsumes the old label-only denylist); `escalate`/`allow` fall through to
+        // exercise. In `advisory` mode `escalate` proceeds (coverage-preserving); in `strict`
+        // mode the floor already resolved it to `deny` (fail-closed). A future increment routes
+        // `escalate` to the LLM safety-judge before this fall-through.
+        const gate = evaluateAction(node, cfg);
+        if (gate.verdict === "deny") {
+            coverage.skipElement(gate.reason);
+            ledger?.recordNode(baseAddr, node, intent, "skipped", { reason: gate.reason });
+            continue;
+        }
+        // Escalation — an ambiguous mutation. Route to the out-of-band safety judge (Fable,
+        // fail-closed). No judge configured → advisory proceeds (permissive), strict fails closed.
+        // Symmetric with the `deny` path: a judge-denied node never reaches `driver.exercise`.
+        if (gate.verdict === "escalate") {
+            let allow;
+            let reason = gate.reason;
+            if (deps.safetyJudge) {
+                try {
+                    const d = await deps.safetyJudge(node);
+                    allow = d.allow;
+                    if (!allow)
+                        reason = d.reason;
+                }
+                catch {
+                    allow = false; // a judge that throws is treated as unsafe — fail closed, skip one node
+                    reason = "escalate-judge-threw";
+                }
+            }
+            else {
+                allow = cfg.actionGateMode !== "strict";
+                reason = "escalate-no-judge-fail-closed";
+            }
+            if (!allow) {
+                // A judge that is DEGRADED (infra error / refused-twice / threw) silently denies every
+                // ambiguous mutation while CI stays green — surface it as one deduped warn so a broken
+                // judge fails loudly. A genuine "unsafe" verdict is expected and stays quiet.
+                if (reason === "judge-error" || reason === "judge-refused" || reason === "escalate-judge-threw") {
+                    deps.onSignal({
+                        kind: "safety-judge-degraded",
+                        severity: "warn",
+                        message: "safety judge unavailable — ambiguous mutations are being denied (fail-closed); mutation coverage is degraded",
+                        url: baseAddr.label ?? baseAddr.id,
+                        signature: "safety-judge-degraded",
+                    });
+                }
+                coverage.skipElement(reason);
+                ledger?.recordNode(baseAddr, node, intent, "skipped", { reason });
+                continue;
+            }
+        }
+        // Known-disabled (the web driver also folds file-inputs in here — never drive a
+        // native file picker) → counted as a skip, not a gap.
+        if (node.disabled) {
+            coverage.skipElement("disabled");
+            ledger?.recordNode(baseAddr, node, intent, "skipped", { reason: "disabled" });
+            continue;
+        }
+        if (intent === "follow") {
+            coverage.bumpExtra("followTargetsDiscovered");
+            coverage.bumpExtra("linksDiscovered");
+            ledger?.recordNode(baseAddr, node, intent, "followed");
+            continue;
+        }
+        if (intent === "branch")
+            coverage.bumpExtra("branchesDiscovered");
+        if (cfg.dryRun) {
+            coverage.skipElement("dry-run");
+            ledger?.recordNode(baseAddr, node, intent, "skipped", { reason: "dry-run" });
+            continue;
+        }
+        // Idempotency — a mutating key fires once even across near-duplicate states.
+        const akey = actionKey(node, scope);
+        if (performedMutations.has(akey)) {
+            coverage.skipElement("idempotent-skip");
+            ledger?.recordNode(baseAddr, node, intent, "skipped", { reason: "idempotent-skip" });
+            continue;
+        }
+        if (acted >= cfg.maxActionsPerState) {
+            coverage.skipElement("per-state-cap");
+            coverage.cappedNotExhaustive = true;
+            ledger?.recordNode(baseAddr, node, intent, "blocked", { reason: "per-state-cap" });
+            continue;
+        }
+        try {
+            const res = await driver.exercise(node);
+            if (res && res.signals)
+                res.signals.forEach(deps.onSignal);
+            const childTargetsDiscovered = res?.discovered?.length ?? 0;
+            // Frontier expansion from ACTING: states the tap/click navigated to that aren't
+            // reachable by link-following (native tap-only screens). enqueue applies inScope +
+            // dedup; the global caps bound it at the loop head.
+            if (res && res.discovered) {
+                coverage.bumpExtra("branchTargetsDiscovered", res.discovered.length);
+                if (deps.enqueue)
+                    for (const a of res.discovered)
+                        deps.enqueue(a);
+            }
+            performedMutations.add(akey);
+            acted++;
+            coverage.exercise();
+            if (intent === "branch")
+                coverage.bumpExtra("branchesExercised");
+            ledger?.recordNode(baseAddr, node, intent, intent === "branch" ? "branched" : "exercised", {
+                childTargetsDiscovered,
+            });
+            deps.recordExercise?.(node.id);
+            driver.drainSignals().forEach(deps.onSignal);
+        }
+        catch (e) {
+            deps.onSignal({
+                kind: "interaction-threw",
+                severity: "warn",
+                message: `${node.kind} "${node.label}" threw: ${String(e).slice(0, 120)}`,
+                url: baseAddr.label ?? baseAddr.id,
+                signature: `threw-${node.id}`.slice(0, 80),
+            });
+            ledger?.recordNode(baseAddr, node, intent, "blocked", { reason: "interaction-threw" });
+        }
+        const r = await restoreBaseline(driver, { address: baseAddr, fingerprint: baselineFp }, cfg);
+        if (r.mode === "regoto" && ++regotoCount > cfg.maxRegotosPerState) {
+            coverage.cappedNotExhaustive = true;
+            break;
+        }
+        if (!r.ok) {
+            deps.onSignal({
+                kind: "irrecoverable-state",
+                severity: "warn",
+                message: `could not restore baseline after "${node.label}" (${node.kind})`,
+                url: baseAddr.label ?? baseAddr.id,
+                signature: `restore-fail-${scope}`,
+            });
+            break; // frontier re-goto will re-establish this scope cleanly
+        }
+    }
+    return acted;
+}
+/**
+ * Restore to the baseline state with escalating cost: probe (none) → soft reset (back) →
+ * goto (regoto backstop). Uses EXACT surfaceFingerprint equality so a partial restore
+ * still escalates to the deterministic regoto. The soft-reset tier (web: Escape) is an
+ * optional driver capability; without it the loop falls straight through to regoto.
+ */
+export async function restoreBaseline(driver, baseline, _cfg) {
+    if (driver.currentAddress().id !== baseline.address.id) {
+        await driver.goto(baseline.address);
+        return { ok: true, mode: "regoto" };
+    }
+    let snap = await driver.snapshot().catch(() => null);
+    if (snap && surfaceFingerprint(snap) === baseline.fingerprint)
+        return { ok: true, mode: "none" };
+    if (driver.softReset)
+        await driver.softReset();
+    snap = await driver.snapshot().catch(() => null);
+    if (snap && surfaceFingerprint(snap) === baseline.fingerprint)
+        return { ok: true, mode: "back" };
+    await driver.goto(baseline.address);
+    snap = await driver.snapshot().catch(() => null);
+    return { ok: snap ? surfaceFingerprint(snap) === baseline.fingerprint : false, mode: "regoto" };
+}

package/dist/core/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/core/plan.js

@@ -0,0 +1,121 @@
+// The deterministic replay PLAN — Comber's "discover once, replay cheaply" record.
+// A plan is a small, driver-AGNOSTIC trace of a normal crawl: for each visited state,
+// its `Address`, the ordered `SurfaceNode.id`s that were exercised, the outbound
+// Addresses that were followed, and the named probes that ran. It carries NO driver
+// handles (those are live, target-specific, and unserializable) — only ids + addresses —
+// so the SAME plan replays against the web AND api drivers. `core` owns this; the
+// dependency arrow still points one way (plan.ts imports nothing from a driver package).
+import { readFile } from "node:fs/promises";
+/** Bump when the on-disk shape changes incompatibly; `parsePlan` rejects other versions. */
+export const PLAN_VERSION = 1;
+/** Copy only the identity fields of an Address (no stray keys leak into the plan). */
+function leanAddress(a) {
+    return { id: a.id, scope: a.scope, ...(a.label !== undefined ? { label: a.label } : {}) };
+}
+/**
+ * Threaded through the orchestrator/pipeline during a NORMAL crawl. It is fed
+ * (begin-state → record probes/outbound/exercises) in execution order, then serialized
+ * to `plan.json`. Cheap and allocation-light: ids and addresses only.
+ */
+export class PlanRecorder {
+    meta;
+    states = [];
+    current;
+    constructor(meta) {
+        this.meta = meta;
+    }
+    /** Open a new state record; subsequent record* calls attach to it. */
+    beginState(address) {
+        this.current = { address: leanAddress(address), exercised: [], outbound: [], probes: [] };
+        this.states.push(this.current);
+    }
+    /** Note a named probe that fired at the current state (deduped, order-preserving). */
+    recordProbe(name) {
+        if (this.current && !this.current.probes.includes(name))
+            this.current.probes.push(name);
+    }
+    /** Note an outbound address followed from the current state. */
+    recordOutbound(addr) {
+        if (this.current)
+            this.current.outbound.push(leanAddress(addr));
+    }
+    /** Note (in order) a node that was actually exercised at the current state. */
+    recordExercise(nodeId) {
+        if (this.current)
+            this.current.exercised.push(nodeId);
+    }
+    toPlan() {
+        return {
+            version: PLAN_VERSION,
+            target: this.meta.target,
+            startUrl: this.meta.startUrl,
+            createdAt: new Date().toISOString(),
+            states: this.states,
+        };
+    }
+}
+// -- loading / validation (a malformed plan is a clear error, never a silent mis-replay) --
+function parseAddress(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    const o = value;
+    if (typeof o.id !== "string" || o.id === "")
+        throw new Error(`${label}.id must be a non-empty string`);
+    if (typeof o.scope !== "string")
+        throw new Error(`${label}.scope must be a string`);
+    if (o.label !== undefined && typeof o.label !== "string")
+        throw new Error(`${label}.label must be a string`);
+    return { id: o.id, scope: o.scope, ...(o.label !== undefined ? { label: o.label } : {}) };
+}
+function parseStringArray(value, label) {
+    if (!Array.isArray(value) || value.some((x) => typeof x !== "string")) {
+        throw new Error(`${label} must be an array of strings`);
+    }
+    return [...value];
+}
+function parseState(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    const o = value;
+    return {
+        address: parseAddress(o.address, `${label}.address`),
+        exercised: parseStringArray(o.exercised, `${label}.exercised`),
+        outbound: Array.isArray(o.outbound)
+            ? o.outbound.map((a, i) => parseAddress(a, `${label}.outbound[${i}]`))
+            : [],
+        probes: o.probes === undefined ? [] : parseStringArray(o.probes, `${label}.probes`),
+    };
+}
+/** Validate an untrusted value into a ReplayPlan (or throw a precise error). */
+export function parsePlan(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label}: plan must be a JSON object`);
+    }
+    const o = value;
+    if (o.version !== PLAN_VERSION) {
+        throw new Error(`${label}: unsupported plan version ${String(o.version)} (expected ${PLAN_VERSION})`);
+    }
+    if (!Array.isArray(o.states))
+        throw new Error(`${label}: plan.states must be an array`);
+    return {
+        version: PLAN_VERSION,
+        target: typeof o.target === "string" ? o.target : "web",
+        startUrl: typeof o.startUrl === "string" ? o.startUrl : "",
+        createdAt: typeof o.createdAt === "string" ? o.createdAt : "",
+        states: o.states.map((s, i) => parseState(s, `${label}.states[${i}]`)),
+    };
+}
+/** Read + parse a plan.json from disk. */
+export async function loadPlan(path) {
+    const raw = await readFile(path, "utf8");
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`replay plan is not valid JSON (${path}): ${String(e)}`);
+    }
+    return parsePlan(json, path);
+}

package/dist/core/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/core/plan.ts"],"names":[],"mappings":"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"}

package/dist/core/redact.js

@@ -0,0 +1,240 @@
+const URL_PATTERN = /\b(?:https?|wss?|data):[^\s"'<>]+/gi;
+const EMAIL_PATTERN = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+const BEARER_PATTERN = /\bBearer\s+[A-Za-z0-9._~+/=-]+/gi;
+const BASIC_AUTH_PATTERN = /\bBasic\s+[A-Za-z0-9+/=_-]{8,}/gi;
+// A JSON Web Token / Supabase service_role|anon key: three base64url segments.
+const JWT_PATTERN = /\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g;
+// Secret-shaped key=value / key: value / "key":"value" (cookies, sessions, JWTs,
+// CSRF, auth, api keys). The optional quote before the separator catches JSON form.
+const KEY_VALUE_PATTERN = /\b(token|secret|secrets|password|passwd|pwd|api[_-]?keys?|access[_-]?tokens?|refresh[_-]?tokens?|id[_-]?token|session[_-]?id|sessionid|sid|jwt|auth|authorization|csrf[_-]?token|csrf|xsrf|cookie|set-cookie|client[_-]?secret|private[_-]?key|signature|sig)"?\s*[:=]\s*"?([^&\s"';,]+)/gi;
+// Belt-and-suspenders: keyword-FREE, high-precision provider token shapes. These catch
+// a bare secret pasted into a finding message / log line with no `token=`/`Bearer`
+// context. Each is specific (prefix + charset + length) → near-zero false-positive.
+// Single source of truth; add new providers here.
+const PROVIDER_TOKEN_PATTERNS = [
+    /-----BEGIN (?:[A-Z]+ )*PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z]+ )*PRIVATE KEY-----/g, // PEM
+    /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, // AWS access key id
+    /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g, // GitHub PAT/OAuth/app/refresh
+    /\bgithub_pat_[0-9A-Za-z_]{22,}\b/g, // GitHub fine-grained PAT
+    /\bglpat-[0-9A-Za-z_-]{20,}\b/g, // GitLab PAT
+    /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/gi, // Slack
+    /\b[sprk]k_(?:live|test)_[A-Za-z0-9]{8,}\b/g, // Stripe sk/pk/rk live|test
+    /\bwhsec_[A-Za-z0-9]{16,}\b/g, // Stripe webhook secret
+    /\bsk-(?:ant-)?[A-Za-z0-9_-]{20,}\b/g, // OpenAI / Anthropic
+    /\bAIza[0-9A-Za-z_-]{35}\b/g, // Google API key
+    /\bya29\.[0-9A-Za-z_-]{20,}\b/g, // Google OAuth token
+    /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/g, // SendGrid
+    /\bshp(?:at|ss|ca|pa)_[A-Fa-f0-9]{32}\b/g, // Shopify
+    /\bnpm_[0-9A-Za-z]{36}\b/g, // npm
+    /\bhf_[A-Za-z0-9]{10,}\b/g, // HuggingFace
+    /\bappl_[A-Za-z0-9]{10,}\b/g, // RevenueCat
+    /\bkey-[0-9a-zA-Z]{32}\b/g, // Mailgun
+    /\bdop_v1_[a-f0-9]{64}\b/g, // DigitalOcean
+];
+function stripProviderTokens(text) {
+    let out = text;
+    for (const re of PROVIDER_TOKEN_PATTERNS)
+        out = out.replace(re, "[redacted]");
+    return out;
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// A bare opaque token candidate: a long base64url-ish run. Decided per-match by
+// `looksLikeBareSecret` so legit identifiers (UUIDs, git SHAs, decimal ids) survive.
+const BARE_TOKEN_CANDIDATE = /[A-Za-z0-9_\-+/=]{32,}/g;
+/** Shannon entropy in bits/char — random secrets are high; words/repeats are low. */
+function shannonBits(s) {
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    let h = 0;
+    for (const n of freq.values()) {
+        const p = n / s.length;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+/** True for a long, high-entropy, mixed-charset opaque string no keyword/provider
+ *  pattern named — a probable bare secret. EXCLUDES UUIDs, pure-hex (git SHAs/hashes),
+ *  and pure-decimal ids so legitimate identifiers are never masked. */
+function looksLikeBareSecret(s) {
+    if (s.length < 32)
+        return false;
+    if (UUID_RE.test(s))
+        return false;
+    if (/^[0-9a-f]+$/i.test(s))
+        return false; // hex: git SHAs, hashes, hex ids
+    if (/^[0-9]+$/.test(s))
+        return false; // long decimal id
+    if (!/[A-Za-z]/.test(s) || !/[0-9]/.test(s))
+        return false; // must be mixed alnum
+    return shannonBits(s) >= 3.5;
+}
+function stripBareSecrets(text) {
+    return text.replace(BARE_TOKEN_CANDIDATE, (m) => (looksLikeBareSecret(m) ? "[redacted]" : m));
+}
+/** Mask opaque high-entropy path segments (reset/magic-link tokens live in the path,
+ *  not just the query — which redactUrl already strips). Conservative: only a long,
+ *  contiguous alnum/token-charset segment carrying BOTH letters and digits, so human
+ *  slugs and UUID segments are left intact. */
+function maskPathSegment(seg) {
+    return seg.length >= 24 && /[0-9]/.test(seg) && /[A-Za-z]/.test(seg) && /^[A-Za-z0-9._~-]+$/.test(seg)
+        ? "[redacted]"
+        : seg;
+}
+export function redactUrl(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        if (url.protocol === "data:")
+            return "data:[redacted]";
+        if (!/^(?:https?|wss?):$/.test(url.protocol))
+            return `${url.protocol}[redacted]`;
+        // Drop userinfo + query + fragment entirely (the common secret carriers) and
+        // mask token-shaped path segments. Build the string manually so the [redacted]
+        // placeholder is not percent-encoded by the URL pathname setter.
+        const path = url.pathname.split("/").map(maskPathSegment).join("/");
+        return `${url.protocol}//${url.host}${path}`;
+    }
+    catch {
+        return stripProviderTokens(rawUrl
+            .replace(KEY_VALUE_PATTERN, "$1=[redacted]")
+            .replace(BEARER_PATTERN, "Bearer [redacted]")
+            .replace(EMAIL_PATTERN, "[email]"));
+    }
+}
+export function redactText(text) {
+    const structured = text
+        .replace(URL_PATTERN, (url) => redactUrl(url))
+        .replace(BASIC_AUTH_PATTERN, "Basic [redacted]")
+        .replace(BEARER_PATTERN, "Bearer [redacted]")
+        .replace(JWT_PATTERN, "[jwt]")
+        .replace(KEY_VALUE_PATTERN, "$1=[redacted]")
+        .replace(EMAIL_PATTERN, "[email]");
+    // Then the keyword-free catches: named provider shapes, then a conservative
+    // generic high-entropy sweep over whatever opaque tokens remain.
+    return stripBareSecrets(stripProviderTokens(structured));
+}
+function redactScope(scope) {
+    if (scope.startsWith("/")) {
+        const redacted = redactUrl(`https://comber.local${scope}`);
+        return redacted.replace("https://comber.local", "");
+    }
+    return redactText(redactUrl(scope));
+}
+export function redactFinding(finding) {
+    return {
+        ...finding,
+        url: redactUrl(finding.url),
+        message: redactText(finding.message),
+        verdict: finding.verdict
+            ? { real: finding.verdict.real, reason: redactText(finding.verdict.reason) }
+            : undefined,
+    };
+}
+function redactAuditRow(r) {
+    return {
+        ...r,
+        url: r.url ? redactUrl(r.url) : r.url,
+        foundOnUrl: r.foundOnUrl ? redactUrl(r.foundOnUrl) : r.foundOnUrl,
+        finalUrl: r.finalUrl ? redactUrl(r.finalUrl) : r.finalUrl,
+        reason: r.reason ? redactText(r.reason) : r.reason,
+        redirectChain: r.redirectChain ? r.redirectChain.map(redactUrl) : r.redirectChain,
+    };
+}
+function redactLedgerEntry(entry) {
+    return {
+        ...entry,
+        addressId: redactText(redactUrl(entry.addressId)),
+        addressScope: redactScope(entry.addressScope),
+        stateLabel: entry.stateLabel ? redactText(entry.stateLabel) : entry.stateLabel,
+        nodeLabel: entry.nodeLabel ? redactText(entry.nodeLabel) : entry.nodeLabel,
+        message: entry.message ? redactText(entry.message) : entry.message,
+    };
+}
+function redactCoverage(coverage) {
+    if (!coverage)
+        return coverage;
+    const blindSpots = Array.isArray(coverage.blindSpots) ? coverage.blindSpots : [];
+    return {
+        ...coverage,
+        blindSpots: blindSpots.map((blindSpot) => ({
+            ...blindSpot,
+            scope: redactScope(blindSpot.scope),
+            message: redactText(blindSpot.message),
+        })),
+    };
+}
+function redactEvidenceString(value) {
+    const pathMasked = value.includes("/") || value.includes("\\")
+        ? value
+            .split(/([/\\])/)
+            .map((segment) => (segment === "/" || segment === "\\" ? segment : maskPathSegment(segment)))
+            .join("")
+        : maskPathSegment(value);
+    return redactText(pathMasked);
+}
+function redactDeviceEvidence(value) {
+    if (typeof value === "string")
+        return redactEvidenceString(value);
+    if (Array.isArray(value))
+        return value.map((entry) => redactDeviceEvidence(entry));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            out[key] = redactDeviceEvidence(nested);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Deep-redact a driver's `extra` bag. `linkAudit` rows carry URLs, so they get URL-aware
+ * row redaction; EVERY OTHER key is deep-redacted at the string leaves by default. This is
+ * fail-closed: numeric audit bags (apiAudit/graphqlAudit counts) pass through untouched,
+ * while any string-bearing sub-bag — deviceEvidence, desktopEvidence, nativeReadiness,
+ * desktopReadiness, and anything a future driver adds — has its launch/verify commands and
+ * app paths scrubbed before it can reach the HTML report or the (possibly public) PR comment.
+ * (Previously only `linkAudit` + `deviceEvidence` were handled, so desktop/readiness bags
+ * leaked through unredacted.)
+ */
+function redactExtra(extra) {
+    if (!extra)
+        return extra;
+    const out = {};
+    for (const [key, value] of Object.entries(extra)) {
+        if (key === "linkAudit" && Array.isArray(value)) {
+            out[key] = value.map(redactAuditRow);
+        }
+        else {
+            out[key] = redactDeviceEvidence(value);
+        }
+    }
+    return out;
+}
+/**
+ * Return a deep-redacted copy of a crawl result, safe to persist (result.json),
+ * render (HTML report), or post to a (possibly public) PR comment. Every
+ * field that can carry crawled-app secrets — finding urls/messages, the start
+ * URL, visited URLs, link-audit URLs, and the baseline diff's findings — is
+ * scrubbed. `signature` is intentionally preserved so baseline diffing across
+ * runs (which keys on signature, not url/message) still works against a
+ * redacted baseline.
+ */
+export function redactResult(result) {
+    return {
+        ...result,
+        startUrl: redactUrl(result.startUrl),
+        visitedUrls: result.visitedUrls.map(redactUrl),
+        findings: result.findings.map(redactFinding),
+        coverage: redactCoverage(result.coverage),
+        exhaustivenessLedger: (result.exhaustivenessLedger ?? []).map(redactLedgerEntry),
+        extra: redactExtra(result.extra),
+        baseline: result.baseline
+            ? {
+                ...result.baseline,
+                newFindings: result.baseline.newFindings.map(redactFinding),
+                resolvedFindings: result.baseline.resolvedFindings.map(redactFinding),
+                unchangedFindings: result.baseline.unchangedFindings.map(redactFinding),
+            }
+            : result.baseline,
+    };
+}

package/dist/core/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/core/redact.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,GAAG,qCAAqC,CAAC;AAC1D,MAAM,aAAa,GAAG,6CAA6C,CAAC;AACpE,MAAM,cAAc,GAAG,kCAAkC,CAAC;AAC1D,MAAM,kBAAkB,GAAG,kCAAkC,CAAC;AAC9D,+EAA+E;AAC/E,MAAM,WAAW,GAAG,+DAA+D,CAAC;AACpF,iFAAiF;AACjF,oFAAoF;AACpF,MAAM,iBAAiB,GACrB,4RAA4R,CAAC;AAE/R,uFAAuF;AACvF,mFAAmF;AACnF,oFAAoF;AACpF,kDAAkD;AAClD,MAAM,uBAAuB,GAAsB;IACjD,uFAAuF,EAAE,MAAM;IAC/F,gCAAgC,EAAE,oBAAoB;IACtD,iCAAiC,EAAE,+BAA+B;IAClE,mCAAmC,EAAE,0BAA0B;IAC/D,+BAA+B,EAAE,aAAa;IAC9C,oCAAoC,EAAE,QAAQ;IAC9C,4CAA4C,EAAE,4BAA4B;IAC1E,6BAA6B,EAAE,wBAAwB;IACvD,qCAAqC,EAAE,qBAAqB;IAC5D,4BAA4B,EAAE,iBAAiB;IAC/C,+BAA+B,EAAE,qBAAqB;IACtD,iDAAiD,EAAE,WAAW;IAC9D,yCAAyC,EAAE,UAAU;IACrD,0BAA0B,EAAE,MAAM;IAClC,0BAA0B,EAAE,cAAc;IAC1C,4BAA4B,EAAE,aAAa;IAC3C,0BAA0B,EAAE,UAAU;IACtC,0BAA0B,EAAE,eAAe;CAC5C,CAAC;AAEF,SAAS,mBAAmB,CAAC,IAAY;IACvC,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,EAAE,IAAI,uBAAuB;QAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IAC9E,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAClF,gFAAgF;AAChF,qFAAqF;AACrF,MAAM,oBAAoB,GAAG,yBAAyB,CAAC;AAEvD,qFAAqF;AACrF,SAAS,WAAW,CAAC,CAAS;IAC5B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,KAAK,MAAM,EAAE,IAAI,CAAC;QAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;QACvB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;uEAEuE;AACvE,SAAS,mBAAmB,CAAC,CAAS;IACpC,IAAI,CAAC,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,iCAAiC;IAC3E,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,kBAAkB;IACxD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,sBAAsB;IACjF,OAAO,WAAW,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;AAC/B,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChG,CAAC;AAED;;;+CAG+C;AAC/C,SAAS,eAAe,CAAC,GAAW;IAClC,OAAO,GAAG,CAAC,MAAM,IAAI,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC;QACpG,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,GAAG,CAAC;AACV,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,iBAAiB,CAAC;QACvD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,GAAG,GAAG,CAAC,QAAQ,YAAY,CAAC;QACjF,6EAA6E;QAC7E,+EAA+E;QAC/E,iEAAiE;QACjE,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpE,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,mBAAmB,CACxB,MAAM;aACH,OAAO,CAAC,iBAAiB,EAAE,eAAe,CAAC;aAC3C,OAAO,CAAC,cAAc,EAAE,mBAAmB,CAAC;aAC5C,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC,CACrC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,UAAU,GAAG,IAAI;SACpB,OAAO,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;SAC7C,OAAO,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;SAC/C,OAAO,CAAC,cAAc,EAAE,mBAAmB,CAAC;SAC5C,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC;SAC7B,OAAO,CAAC,iBAAiB,EAAE,eAAe,CAAC;SAC3C,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACrC,4EAA4E;IAC5E,iEAAiE;IACjE,OAAO,gBAAgB,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,SAAS,CAAC,uBAAuB,KAAK,EAAE,CAAC,CAAC;QAC3D,OAAO,QAAQ,CAAC,OAAO,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO;QACL,GAAG,OAAO;QACV,GAAG,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC;QAC3B,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC;QACpC,OAAO,EAAE,OAAO,CAAC,OAAO;YACtB,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;YAC5E,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,CAAc;IACpC,OAAO;QACL,GAAG,CAAC;QACJ,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;QACrC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU;QACjE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ;QACzD,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM;QAClD,aAAa,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa;KAClF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAgC;IACzD,OAAO;QACL,GAAG,KAAK;QACR,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACjD,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,YAAY,CAAC;QAC7C,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU;QAC9E,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS;QAC1E,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO;KACnE,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,QAAqC;IAC3D,IAAI,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC/B,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IACjF,OAAO;QACL,GAAG,QAAQ;QACX,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YACzC,GAAG,SAAS;YACZ,KAAK,EAAE,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC;YACnC,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC;SACvC,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa;IACzC,MAAM,UAAU,GACd,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QACzC,CAAC,CAAC,KAAK;aACF,KAAK,CAAC,SAAS,CAAC;aAChB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;aAC5F,IAAI,CAAC,EAAE,CAAC;QACb,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,UAAU,CAAC,UAAU,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC;IACnF,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC7E,GAAG,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;sEACsE;AACtE,SAAS,WAAW,CAAC,KAA0C;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,GAAG,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAC;IAClD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,SAAS,GAAI,GAAG,CAAC,SAA2B,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,GAAG,CAAC,cAAc,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;QACvG,GAAG,CAAC,cAAc,GAAG,oBAAoB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,MAAmB;IAC9C,OAAO;QACL,GAAG,MAAM;QACT,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC;QACpC,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC;QAC9C,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC;QAC5C,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC;QACzC,oBAAoB,EAAE,CAAC,MAAM,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAChF,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC;QAChC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACvB,CAAC,CAAC;gBACE,GAAG,MAAM,CAAC,QAAQ;gBAClB,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC;gBAC3D,gBAAgB,EAAE,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,CAAC,aAAa,CAAC;gBACrE,iBAAiB,EAAE,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAC,GAAG,CAAC,aAAa,CAAC;aACxE;YACH,CAAC,CAAC,MAAM,CAAC,QAAQ;KACpB,CAAC;AACJ,CAAC"}