rea-agents 4.1.0 → 6.0.0

package/dist/browser/execution/CdpRuntimeSession.js

@@ -0,0 +1,163 @@
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisTimeoutError } from "../../domain/analysisErrorCore.js";
+import { BrowserObservationError } from "../../domain/browserObservationError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+import { WEB_RUNTIME_LIMITS, } from "../../domain/webRuntime.js";
+import { authorizeCdpTarget } from "../CdpAuthorizedTarget.js";
+import { authorizedMainFrame } from "../CdpAuthorizedMainFrame.js";
+import { discoverCdpEndpoint, } from "../CdpEndpoint.js";
+import { openCdpTargetSession, } from "../CdpTargetSession.js";
+import { runtimeFrameTreeSchema } from "./CdpRuntimeProtocol.js";
+/** Owned transport and instrumentation; the selected browser/page remain externally owned. */
+export class CdpRuntimeSession {
+    transport;
+    discovery;
+    target;
+    allowedOrigins;
+    operation;
+    options;
+    enabledDomains = [];
+    preciseCoverageMayBeActive = false;
+    #completion;
+    #completionTimer;
+    constructor(transport, discovery, target, allowedOrigins, operation, options) {
+        this.transport = transport;
+        this.discovery = discovery;
+        this.target = target;
+        this.allowedOrigins = allowedOrigins;
+        this.operation = operation;
+        this.options = options;
+    }
+    /** Acquire a validated target; failed setup releases its owned socket. */
+    static async open(input, operation, options) {
+        return runtimeDeadline(operation, options.signal, async (signal) => {
+            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, operation, signal);
+            const { target, allowedOrigins } = authorizeCdpTarget(discovery, input, operation);
+            const transport = await openCdpTargetSession(discovery, target, operation, signal, { maxPayloadBytes: WEB_RUNTIME_LIMITS.protocolBytes });
+            try {
+                const tree = runtimeFrameTreeSchema.parse(await authorizedMainFrame({
+                    ...transport,
+                    allowedOrigins,
+                    signal,
+                    operation,
+                }));
+                const frame = tree.frameTree.frame;
+                const url = sanitizeBrowserUrl(frame.url);
+                if (url.origin === null)
+                    throw new BrowserObservationError(operation, "target_not_allowed");
+                return new CdpRuntimeSession(transport, discovery, {
+                    target_id: target.id,
+                    initial_url: url.url,
+                    origin: url.origin,
+                    frame_id: frame.id,
+                    loader_id: frame.loaderId ?? null,
+                }, allowedOrigins, operation, options);
+            }
+            catch (cause) {
+                await transport.connection.close();
+                throw cause;
+            }
+        });
+    }
+    /** Bound each command separately from the caller-selected observation duration. */
+    async command(method, params = {}) {
+        const signals = [this.options.signal, this.#completion?.signal].filter((signal) => signal !== undefined);
+        try {
+            return await runtimeDeadline(this.operation, signals.length === 0 ? undefined : AbortSignal.any(signals), (signal) => this.transport.connection.send(method, params, this.transport.sessionId, signal));
+        }
+        catch (cause) {
+            if (this.#completion?.signal.aborted && !this.options.signal?.aborted)
+                throw new AnalysisTimeoutError(this.operation, WEB_RUNTIME_LIMITS.commandTimeoutMs);
+            throw cause;
+        }
+    }
+    /** Bound the complete inspection/source-join phase as well as each individual command. */
+    beginCompletion() {
+        if (this.#completion !== undefined)
+            return;
+        this.#completion = new AbortController();
+        this.#completionTimer = setTimeout(() => this.#completion?.abort(), WEB_RUNTIME_LIMITS.commandTimeoutMs);
+    }
+    /** Register cleanup before sending: cancellation can occur after producer acceptance. */
+    async enable(domain) {
+        this.enabledDomains.push(domain);
+        await this.command(`${domain}.enable`);
+    }
+    /** Check document identity before joining any live node or final coverage evidence. */
+    async assertDocument() {
+        const frame = runtimeFrameTreeSchema.parse(await this.command("Page.getFrameTree")).frameTree.frame;
+        const url = sanitizeBrowserUrl(frame.url);
+        if (frame.id !== this.target.frame_id ||
+            (frame.loaderId ?? null) !== this.target.loader_id ||
+            (this.target.loader_id === null && url.url !== this.target.initial_url))
+            throw new BrowserObservationError(this.operation, "target_changed", {
+                detail: `Selected target ${this.target.target_id} changed document during ${this.operation}.`,
+            });
+        if (url.origin === null || !this.allowedOrigins.has(url.origin))
+            throw new BrowserObservationError(this.operation, "target_not_allowed", {
+                detail: `Selected target ${this.target.target_id} moved to an unselected origin during ${this.operation}.`,
+            });
+    }
+    /** Cleanup uses its own deadline after caller cancellation, then closes REA's transport. */
+    async close(previousError, objectGroup) {
+        if (this.#completionTimer !== undefined)
+            clearTimeout(this.#completionTimer);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), WEB_RUNTIME_LIMITS.cleanupTimeoutMs);
+        const failures = [];
+        const send = async (method, params = {}) => {
+            try {
+                await this.transport.connection.send(method, params, this.transport.sessionId, controller.signal);
+            }
+            catch (cause) {
+                failures.push(`${method}: ${cause instanceof AnalysisError ? (cause.userMessage ?? cause.message) : cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        };
+        try {
+            if (this.preciseCoverageMayBeActive)
+                await send("Profiler.stopPreciseCoverage");
+            if (objectGroup !== undefined)
+                await send("Runtime.releaseObjectGroup", { objectGroup });
+            for (const domain of [...this.enabledDomains].reverse())
+                await send(`${domain}.disable`);
+            if (this.transport.sessionId !== undefined) {
+                try {
+                    await this.transport.connection.send("Target.detachFromTarget", { sessionId: this.transport.sessionId }, undefined, controller.signal);
+                }
+                catch (cause) {
+                    failures.push(`Target.detachFromTarget: ${cause instanceof AnalysisError ? (cause.userMessage ?? cause.message) : cause instanceof Error ? cause.message : String(cause)}`);
+                }
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            await this.transport.connection.close();
+        }
+        return failures.length === 0
+            ? undefined
+            : new ProviderCleanupError("rea-cdp-browser", [this.target.target_id, "runtime-instrumentation"], {
+                target_id: this.target.target_id,
+                cleanup_failures: failures,
+                previous_error: previousError?.userMessage ?? previousError?.message ?? null,
+            }, { operation: this.operation });
+    }
+}
+/** Apply a disposable command deadline without turning timeout into caller cancellation. */
+export const runtimeDeadline = async (operation, signal, run) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), WEB_RUNTIME_LIMITS.commandTimeoutMs);
+    try {
+        return await run(signal === undefined
+            ? controller.signal
+            : AbortSignal.any([signal, controller.signal]));
+    }
+    catch (cause) {
+        if (controller.signal.aborted && signal?.aborted !== true)
+            throw new AnalysisTimeoutError(operation, WEB_RUNTIME_LIMITS.commandTimeoutMs);
+        throw cause;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};

package/dist/browser/execution/CdpRuntimeSources.js

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { WEB_RUNTIME_LIMITS, } from "../../domain/webRuntime.js";
+import { runtimeContextSchema, runtimeScriptParsedSchema, } from "./CdpRuntimeProtocol.js";
+const scriptIdentitySchema = runtimeScriptParsedSchema.pick({ scriptId: true });
+const contextIdentitySchema = z.object({
+    context: runtimeContextSchema.shape.context.pick({ id: true }),
+});
+/** Source ownership is proven by execution context/frame metadata, independently of URL aliases. */
+export class CdpRuntimeSources {
+    session;
+    scripts = new Map();
+    #contexts = new Map();
+    #changed = new Set();
+    #changedContexts = new Set();
+    #sources = new Map();
+    #retainedBytes = 0;
+    #sourceBytes = 0;
+    #failure;
+    constructor(session) {
+        this.session = session;
+    }
+    /** Subscribe before enabling Debugger; existing uncollected scripts are replayed by the producer. */
+    ingest(event, retainNewMetadata = true) {
+        if (event.sessionId !== this.session.transport.sessionId ||
+            this.#failure !== undefined)
+            return;
+        try {
+            if (event.method === "Runtime.executionContextCreated") {
+                this.#retainedBytes += Buffer.byteLength(JSON.stringify(event.params));
+                if (this.#retainedBytes > WEB_RUNTIME_LIMITS.retainedEventBytes)
+                    throw new Error("Context/script metadata exceeds the complete 8 MiB event budget.");
+                const context = runtimeContextSchema.parse(event.params).context;
+                const previous = this.#contexts.get(context.id);
+                if (previous !== undefined &&
+                    JSON.stringify(previous) !== JSON.stringify(context)) {
+                    this.#changedContexts.add(context.id);
+                    for (const item of this.#sources.values())
+                        if (item.execution_context_id === context.id)
+                            this.revalidate(item);
+                }
+                if (retainNewMetadata)
+                    this.#contexts.set(context.id, context);
+            }
+            else if (event.method === "Debugger.scriptParsed") {
+                this.#retainedBytes += Buffer.byteLength(JSON.stringify(event.params));
+                if (this.#retainedBytes > WEB_RUNTIME_LIMITS.retainedEventBytes)
+                    throw new Error("Script metadata exceeds the complete 8 MiB event budget.");
+                const script = runtimeScriptParsedSchema.parse(event.params);
+                const previous = this.scripts.get(script.scriptId);
+                if (previous !== undefined &&
+                    JSON.stringify(previous) !== JSON.stringify(script)) {
+                    this.#changed.add(script.scriptId);
+                    const retained = this.#sources.get(script.scriptId);
+                    if (retained !== undefined)
+                        this.revalidate(retained);
+                }
+                if (retainNewMetadata)
+                    this.scripts.set(script.scriptId, script);
+            }
+        }
+        catch (cause) {
+            this.#failure = new AnalysisOutputError(this.session.operation, cause instanceof Error ? cause.message : String(cause));
+        }
+    }
+    /** Producer parse/resource failures are surfaced outside the transport event callback. */
+    check() {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+    }
+    /** Frozen inventories still monitor known identities through asynchronous source reads. */
+    verifyKnownIdentity(event) {
+        if (event.method === "Debugger.scriptParsed") {
+            const id = scriptIdentitySchema.safeParse(event.params);
+            if (id.success && this.scripts.has(id.data.scriptId))
+                this.ingest(event, false);
+        }
+        else if (event.method === "Runtime.executionContextCreated") {
+            const id = contextIdentitySchema.safeParse(event.params);
+            if (id.success && this.#contexts.has(id.data.context.id))
+                this.ingest(event, false);
+        }
+    }
+    /** Only proven default worlds of the selected main frame establish website source ownership. */
+    belongsToDocument(scriptId) {
+        const script = this.scripts.get(scriptId);
+        if (script === undefined ||
+            this.#changed.has(scriptId) ||
+            this.#changedContexts.has(script.executionContextId))
+            return false;
+        const scriptContext = script.executionContextAuxData;
+        const context = this.#contexts.get(script.executionContextId)?.auxData;
+        const worlds = [scriptContext, context];
+        if (worlds.some((world) => world?.isDefault === false ||
+            (world?.type !== undefined && world.type !== "default")) ||
+            !worlds.some((world) => world?.isDefault === true || world?.type === "default"))
+            return false;
+        const reported = scriptContext?.frameId;
+        const contextFrame = context?.frameId;
+        return ((reported === undefined ||
+            contextFrame === undefined ||
+            reported === contextFrame) &&
+            (reported ?? contextFrame) === this.session.target.frame_id);
+    }
+    /** Retain complete script text and compute a digest distinct from the producer hash. */
+    async read(scriptIds) {
+        this.check();
+        for (const scriptId of new Set(scriptIds)) {
+            if (this.#sources.has(scriptId))
+                continue;
+            const script = this.scripts.get(scriptId);
+            const owned = this.belongsToDocument(scriptId);
+            const context = script === undefined
+                ? undefined
+                : this.#contexts.get(script.executionContextId);
+            const item = {
+                script_id: scriptId,
+                url: this.sourceUrl(scriptId, script?.url ?? ""),
+                execution_context_id: script?.executionContextId ?? null,
+                reported_execution_context: context === undefined ? null : jsonObjectSchema.parse(context),
+                reported_script_context_aux_data: script?.executionContextAuxData === undefined
+                    ? null
+                    : jsonObjectSchema.parse(script.executionContextAuxData),
+                frame_id: owned ? this.session.target.frame_id : null,
+                producer_hash: script?.hash ?? null,
+                source_map_url: script?.sourceMapURL ?? null,
+                has_source_url: script?.hasSourceURL ?? null,
+                language: script?.scriptLanguage ?? null,
+                resource_start: script !== undefined
+                    ? {
+                        line_number: script.startLine,
+                        column_number: script.startColumn,
+                    }
+                    : null,
+                source: {
+                    state: "excluded",
+                    reason: this.#changed.has(scriptId)
+                        ? "The script changed identity during observation; source attribution is unknown."
+                        : "Selected main-document default-world ownership was not established.",
+                },
+            };
+            if (owned && script?.scriptLanguage !== "WebAssembly")
+                item.source = await this.capture(scriptId);
+            else if (owned)
+                item.source = {
+                    state: "excluded",
+                    reason: "WebAssembly bytecode is outside this JavaScript source operation.",
+                };
+            this.revalidate(item);
+            this.#sources.set(scriptId, item);
+        }
+        this.check();
+        return [...this.#sources.values()];
+    }
+    /** Resolve an exact producer script ID; URL equality is never an identity fallback. */
+    location(scriptId, url, line, column, functionName = null) {
+        return {
+            script_id: scriptId,
+            url: url === null ? null : this.sourceUrl(scriptId, url),
+            line_number: line,
+            column_number: column,
+            function_name: functionName,
+            source_association: this.belongsToDocument(scriptId)
+                ? "script_id"
+                : "unknown",
+        };
+    }
+    /** Declared script names are inert evidence; known resource URLs omit transport userinfo. */
+    sourceUrl(scriptId, url) {
+        return !this.#changed.has(scriptId) &&
+            this.scripts.get(scriptId)?.hasSourceURL === false
+            ? sanitizeBrowserUrl(url).url
+            : url;
+    }
+    revalidate(item) {
+        if (item.frame_id === null || this.belongsToDocument(item.script_id))
+            return;
+        const previous = item.source.state === "unavailable"
+            ? ` Previous source read failure: ${item.source.reason}`
+            : "";
+        item.frame_id = null;
+        item.source = {
+            state: "excluded",
+            reason: `The script or context changed identity during source collection; attribution is unknown.${previous}`,
+        };
+    }
+    async capture(scriptId) {
+        let raw;
+        try {
+            raw = await this.session.command("Debugger.getScriptSource", {
+                scriptId,
+            });
+        }
+        catch (cause) {
+            if (this.session.options.signal?.aborted ||
+                !(cause instanceof AnalysisError))
+                throw cause;
+            return {
+                state: "unavailable",
+                reason: cause.userMessage ?? cause.message,
+            };
+        }
+        const source = z.object({ scriptSource: z.string() }).safeParse(raw);
+        if (!source.success)
+            throw new AnalysisOutputError(this.session.operation, "Debugger.getScriptSource returned malformed source text.");
+        const text = source.data.scriptSource;
+        const bytes = Buffer.byteLength(text);
+        this.#sourceBytes += bytes;
+        if (this.#sourceBytes > WEB_RUNTIME_LIMITS.sourceBytes)
+            throw new AnalysisOutputError(this.session.operation, "Complete runtime source evidence exceeds its 32 MiB budget; no partial evidence is returned.");
+        return {
+            state: "captured",
+            text,
+            sha256: createHash("sha256").update(text).digest("hex"),
+            utf8_bytes: bytes,
+            utf16_units: text.length,
+        };
+    }
+}

package/dist/browser/execution/CdpWebRuntimeProvider.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { err, ok } from "../../domain/result.js";
+import { webExecutionSchema, } from "../../domain/webExecution.js";
+import { webEventListenersSchema, } from "../../domain/webEventListeners.js";
+import { CDP_BROWSER_PROVIDER_IDENTITY } from "../providerIdentities.js";
+import { CdpRuntimeSession } from "./CdpRuntimeSession.js";
+import { CdpRuntimeSources } from "./CdpRuntimeSources.js";
+import { captureWebExecution } from "./CdpExecutionCapture.js";
+import { captureWebEventListeners, eventListenerObjectGroup, } from "./CdpEventListeners.js";
+/** Native CDP integration with distinct inspection/instrumentation authority and confirmed cleanup. */
+export class CdpWebRuntimeProvider {
+    /** Identify this adapter independently of the captured browser version. */
+    identity() {
+        return CDP_BROWSER_PROVIDER_IDENTITY;
+    }
+    /** Observe one instrumented window while preserving the externally owned page. */
+    observeExecution(input, options = {}) {
+        return this.run(input, "observe_web_execution", options, webExecutionSchema, (sources) => captureWebExecution(input, sources));
+    }
+    /** Inspect one selected node's registered callback locations. */
+    inspectEventListeners(input, options = {}) {
+        const group = eventListenerObjectGroup();
+        return this.run(input, "inspect_web_event_listeners", options, webEventListenersSchema, (sources) => captureWebEventListeners(input, sources, group), group);
+    }
+    async run(input, operation, options, schema, capture, group) {
+        let session;
+        let result;
+        try {
+            session = await CdpRuntimeSession.open(input, operation, options);
+            result = ok(schema.parse(await capture(new CdpRuntimeSources(session))));
+        }
+        catch (cause) {
+            result = err(cause instanceof AnalysisError
+                ? cause
+                : cause instanceof z.ZodError
+                    ? new AnalysisOutputError(operation, cause.message)
+                    : new ProviderAdapterError(this.identity().id, operation, {
+                        cause,
+                    }));
+        }
+        if (session !== undefined) {
+            const failure = await session.close(result.ok ? undefined : result.error, group);
+            if (failure !== undefined)
+                return err(failure);
+        }
+        return result;
+    }
+}

package/dist/browser/history/CaptureFailures.js

@@ -0,0 +1,101 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { WEB_NETWORK_CAPTURE_LIMITS, } from "../../domain/webNetworkCapture.js";
+import { OwnedCommandFailure } from "../../process/OwnedCommand.js";
+const OPERATION = "inspect_web_network_capture";
+/** Preserve the origin and typed cause of a historical capture failure. */
+export const historicalCaptureFailure = (input, cause, phase, options) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (cause instanceof OwnedCommandFailure) {
+        if (cause.cleanupFailure !== null)
+            return new ProviderCleanupError(input.format, cause.resources, {
+                reason: cause.cleanupFailure,
+                previous_error: {
+                    failure_kind: cause.reason,
+                    message: cause.message,
+                    exit_code: cause.snapshot?.exitCode ?? null,
+                    signal: cause.snapshot?.signal ?? null,
+                    stdout: cause.snapshot?.stdout.text ?? null,
+                    stderr: cause.snapshot?.stderr.text ?? null,
+                    diagnostic_truncated: cause.snapshot?.diagnosticTruncated ?? null,
+                },
+            }, { operation: OPERATION, cause });
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError(OPERATION);
+        if (cause.reason === "timeout")
+            return new AnalysisTimeoutError(OPERATION, WEB_NETWORK_CAPTURE_LIMITS.timeoutMs);
+        if (cause.reason === "output-limit")
+            return new AnalysisOutputError(OPERATION, cause.message);
+    }
+    if (options?.signal?.aborted)
+        return new AnalysisCancelledError(OPERATION);
+    if (phase === "capture-read" &&
+        cause instanceof ArtifactReaderFailure &&
+        cause.reason === "integrity")
+        return new AnalysisArtifactChangedError(OPERATION, input.capture_path, cause.message, { cause });
+    if (phase === "capture-read" &&
+        cause instanceof ArtifactReaderFailure &&
+        cause.reason === "cancelled")
+        return new AnalysisCancelledError(OPERATION);
+    if (phase === "capture-read" &&
+        cause instanceof ArtifactReaderFailure &&
+        (cause.reason === "limit" ||
+            cause.reason === "format" ||
+            cause.reason === "path"))
+        return new AnalysisInputError(OPERATION, { cause }, [
+            {
+                path: ["capture_path"],
+                reason: cause.reason === "limit" ? "out_of_range" : "invalid_format",
+                message: cause.reason === "limit"
+                    ? `${cause.message}. Select a capture within the ${WEB_NETWORK_CAPTURE_LIMITS.inputBytes}-byte input budget.`
+                    : cause.message,
+                ...(cause.reason === "limit"
+                    ? {
+                        expected: {
+                            maximum_capture_bytes: WEB_NETWORK_CAPTURE_LIMITS.inputBytes,
+                        },
+                    }
+                    : {}),
+            },
+        ]);
+    if (phase === "capture-read" &&
+        cause instanceof Error &&
+        "code" in cause &&
+        (cause.code === "EACCES" || cause.code === "EPERM"))
+        return new AnalysisAccessDeniedError(OPERATION, input.capture_path, cause.code, { cause });
+    if (phase === "capture-read" &&
+        cause instanceof Error &&
+        "code" in cause &&
+        ["ENOENT", "ENOTDIR"].includes(String(cause.code)))
+        return new AnalysisInputError(OPERATION, { cause }, [
+            {
+                path: ["capture_path"],
+                reason: "invalid_value",
+                message: `Selected capture could not be read (${String(cause.code)}): ${input.capture_path}.`,
+            },
+        ]);
+    return new ProviderAdapterError(input.format, OPERATION, {
+        cause,
+        diagnostics: {
+            phase,
+            capture_path: input.capture_path,
+            reason: cause instanceof Error ? cause.message : String(cause),
+            ...(cause instanceof ArtifactReaderFailure
+                ? { failure_kind: cause.reason }
+                : {}),
+            ...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
+                ? {
+                    exit_code: cause.snapshot.exitCode ?? null,
+                    signal: cause.snapshot.signal ?? null,
+                    stdout: cause.snapshot.stdout.text,
+                    stderr: cause.snapshot.stderr.text,
+                    diagnostic_truncated: cause.snapshot.diagnosticTruncated ?? false,
+                }
+                : {}),
+        },
+    });
+};

package/dist/browser/history/CaptureFormatError.js

@@ -0,0 +1,10 @@
+/** Expected malformed, unsupported or oversized producer data at a historical decoder boundary. */
+export class CaptureFormatError extends Error {
+    reason;
+    pointer;
+    constructor(reason, message, pointer = "") {
+        super(message);
+        this.reason = reason;
+        this.pointer = pointer;
+    }
+}

package/dist/browser/history/CaptureRedaction.js

@@ -0,0 +1,65 @@
+const CREDENTIAL_HEADERS = new Set([
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+]);
+/** Literal redaction and structural authentication exclusions preserve unrelated local evidence. */
+export class CaptureRedaction {
+    sensitiveValues;
+    redactions = [];
+    #sensitiveByteValues;
+    constructor(sensitiveValues) {
+        this.sensitiveValues = sensitiveValues;
+        // An unpaired surrogate has no UTF-8 representation. Buffer.from would
+        // invent replacement-character bytes and incorrectly discard real evidence.
+        this.#sensitiveByteValues = sensitiveValues.flatMap((value) => {
+            const encoded = Buffer.from(value, "utf8");
+            return encoded.toString("utf8") === value ? [encoded] : [];
+        });
+    }
+    /** Preserve exact text unless explicitly sensitive or known transport URL userinfo. */
+    text(value, pointer, transportUrl = false) {
+        let result = value;
+        if (transportUrl) {
+            const match = /^([\x00-\x20]*(?:[a-z][a-z0-9+.-]*:)?\/\/)([^/?#]*@)/i.exec(result);
+            if (match !== null) {
+                result = `${match[1]}${result.slice(match[0].length)}`;
+                this.redactions.push({ pointer, reason: "transport-credential" });
+            }
+        }
+        if (this.sensitiveValues.some((literal) => value.includes(literal) || result.includes(literal))) {
+            this.redactions.push({ pointer, reason: "explicit-sensitive-value" });
+            return null;
+        }
+        return result;
+    }
+    /** Remove a credential field's value without retaining its digest or encoded form. */
+    credential(pointer) {
+        this.redactions.push({ pointer, reason: "transport-credential" });
+        return null;
+    }
+    /** Known HAR credential surfaces; unknown extensions are ordinary caller-selected evidence. */
+    harCredential(pointer, parent) {
+        return ((/^\/(request|response)\/headers\/\d+\/value$/.test(pointer) &&
+            typeof parent.name === "string" &&
+            CREDENTIAL_HEADERS.has(parent.name.toLowerCase())) ||
+            /^\/(request|response)\/cookies\/\d+\/value$/.test(pointer));
+    }
+    /** Only actual request/redirect fields and known transport header URLs declare URL semantics. */
+    harTransportUrl(pointer, parent) {
+        return (pointer === "/request/url" ||
+            pointer === "/response/redirectURL" ||
+            (/^\/(request|response)\/headers\/\d+\/value$/.test(pointer) &&
+                typeof parent?.name === "string" &&
+                ["location", "referer", "origin"].includes(parent.name.toLowerCase())));
+    }
+    /** Preserve bytes unless an explicitly declared UTF-8 literal occurs in them. */
+    sensitiveBytes(bytes) {
+        return this.#sensitiveByteValues.some((value) => bytes.includes(value));
+    }
+}
+/** Escape a producer property for an RFC 6901 location. */
+export const capturePointer = (parent, key) => `${parent}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+/** Structural record guard does not duck-type number/byte sidecar markers. */
+export const captureObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/browser/history/CaptureRelease.js

@@ -0,0 +1,12 @@
+/** Exact upstream package profile for unchanged offline HAR validation and numeric parsing. */
+export const HAR_CAPTURE_PROVIDER_IDENTITY = {
+    id: "har-schema/lossless-json",
+    name: "REA HAR capture adapter",
+    version: "har-schema@2.0.0;jsonc-parser@3.3.1;lossless-json@4.3.1",
+};
+/** Native executable profile verified with unchanged mitmproxy raw-state decoding. */
+export const MITMPROXY_CAPTURE_PROVIDER_IDENTITY = {
+    id: "mitmproxy-native-tnetstring",
+    name: "REA offline native mitmproxy adapter",
+    version: "12.2.3",
+};