From 088bc68b1cbddb11b7432e7541ba66f47409abf2 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sat, 21 Nov 2026 15:38:10 -0500 Subject: [PATCH] fix(capture): surface unsupported decoder requirements (#13203) --- docs/guides/web/web-network-captures.md | 3 + src/browser/history/CaptureFailures.test.ts | 27 +-- .../history/HistoricalCaptureBudgets.test.ts | 13 +- .../history/HistoricalCaptureDecoder.ts | 8 + .../history/HistoricalCaptureReply.test.ts | 211 ++++++++---------- .../browser/historicalCaptureDecoder.test.ts | 69 ++---- .../browser/historicalWebCapture.test.ts | 40 +++- tests/boundary/browser/sazWebCapture.test.ts | 7 +- 8 files changed, 174 insertions(+), 204 deletions(-) diff --git a/docs/guides/web/web-network-captures.md b/docs/guides/web/web-network-captures.md index e787711ed8..862389acd5 100644 --- a/docs/guides/web/web-network-captures.md +++ b/docs/guides/web/web-network-captures.md @@ -63,6 +63,9 @@ redaction, and its live status clears only after a confirmed retry. ## Formats and upstream profiles +Unsupported format and decoder errors identify the reported requirement and +include its source location when the decoder supplies one. + HAR uses `har-schema@2.0.0` draft-06 schemas, `ajv@8.20.0`, `ajv-formats@3.0.1`, `jsonc-parser@3.3.1` JSON visitor, and `lossless-json@4.3.1` numeric representations, pinned in the npm lockfile. diff --git a/src/browser/history/CaptureFailures.test.ts b/src/browser/history/CaptureFailures.test.ts index 437e2cb334..ff6b4a01f6 100644 --- a/src/browser/history/CaptureFailures.test.ts +++ b/src/browser/history/CaptureFailures.test.ts @@ -18,10 +18,7 @@ import { protobufCaptureFailure, recordedDecoderCpuSeconds, } from "./CaptureFailures.js"; -import { - CaptureFormatError, - captureLimitForReply, -} from "./CaptureFormatError.js"; +import { CaptureFormatError } from "./CaptureFormatError.js"; import { NODE_CAPTURE_PROCESS_MEMORY_LIMIT_BYTES } from "../../../tests/fixtures/captureDecoderLimits.js"; import { redactExplicitFailure } from "../../domain/explicitSensitiveFailure.js"; import { OwnedCommandFailure } from "../../process/OwnedCommand.js"; @@ -656,25 +653,3 @@ it.each([ expect(projected.remediation.action).toContain(String(limit.maximum)); }, ); - -it("derives each decoder-child wire reason from the limit table", () => { - expect( - new CaptureFormatError( - { name: "nesting-depth", maximum: 64 }, - "deep", - "/log", - ), - ).toMatchObject({ replyReason: "input-limit", pointer: "/log" }); - expect( - new CaptureFormatError({ name: "expanded-input", maximum: 1 }, "big") - .replyReason, - ).toBe("expanded-limit"); - expect(new CaptureFormatError("malformed", "bad").replyReason).toBe("format"); - expect(new CaptureFormatError("unsupported", "no").replyReason).toBe( - "unsupported", - ); - expect(captureLimitForReply("input-limit")).toBe("nesting-depth"); - expect(captureLimitForReply("expanded-limit")).toBe("expanded-input"); - // A reply-size refusal is not a decoder input limit. - expect(captureLimitForReply("limit")).toBeUndefined(); -}); diff --git a/src/browser/history/HistoricalCaptureBudgets.test.ts b/src/browser/history/HistoricalCaptureBudgets.test.ts index aca4e46ab1..18a59f94eb 100644 --- a/src/browser/history/HistoricalCaptureBudgets.test.ts +++ b/src/browser/history/HistoricalCaptureBudgets.test.ts @@ -1,3 +1,4 @@ +import { createHash } from "node:crypto"; import { createRequire } from "node:module"; import { writeFile } from "node:fs/promises"; import { fileURLToPath, pathToFileURL } from "node:url"; @@ -98,7 +99,11 @@ it.each(["max_input_bytes", "max_reply_bytes", "max_nesting_depth"] as const)( if (!recovered.ok) throw recovered.error; expect(recovered.value.parameters[control]).toBe(raised); expect(recovered.value.normalized_result).toMatchObject({ - artifact: { path, bytes: Buffer.byteLength(text) }, + artifact: { + path, + bytes: Buffer.byteLength(text), + sha256: createHash("sha256").update(text).digest("hex"), + }, total_records: 1, records: [ { @@ -108,12 +113,6 @@ it.each(["max_input_bytes", "max_reply_bytes", "max_nesting_depth"] as const)( ], }); expect(JSON.stringify(recovered.value)).not.toContain("exclude-me"); - // Admission changes cannot make malformed source valid. - await writeFile(path, '{"log":'); - const malformed = await capture.inspect({ ...request, [control]: raised }); - if (malformed.ok) - throw new Error("Malformed capture unexpectedly admitted"); - expect(malformed.error._tag).toBe("AnalysisInputError"); }, ); diff --git a/src/browser/history/HistoricalCaptureDecoder.ts b/src/browser/history/HistoricalCaptureDecoder.ts index 53975a9279..d4c718eeb0 100644 --- a/src/browser/history/HistoricalCaptureDecoder.ts +++ b/src/browser/history/HistoricalCaptureDecoder.ts @@ -310,6 +310,14 @@ export class HistoricalCaptureDecoder { input.format, OPERATION, reply.message, + { + userMessage: reply.message, + remediationAction: + "Meet the reported capture format or decoder requirement before retrying.", + ...(reply.pointer === "" + ? {} + : { diagnostics: { pointer: reply.pointer } }), + }, ); throw new AnalysisOutputError(OPERATION, reply.message, { userMessage: `The capture decoder refused a complete reply exceeding ${String(captureBudgets().outputBytes)} bytes: ${reply.message}`, diff --git a/src/browser/history/HistoricalCaptureReply.test.ts b/src/browser/history/HistoricalCaptureReply.test.ts index 635ccd63d7..909a430787 100644 --- a/src/browser/history/HistoricalCaptureReply.test.ts +++ b/src/browser/history/HistoricalCaptureReply.test.ts @@ -16,60 +16,37 @@ const replyFile = async (bytes: Uint8Array) => { return { path, resources }; }; -const replyText = (kind: "error" | "output", text: string) => { - if (kind === "error") - return JSON.stringify({ - ok: false, - reason: "format", - message: text, - pointer: "", - }); +it("preserves valid replacement-character text and rejects invalid bytes in the same capture reply", async () => { const capture = historicalHar(); - capture.log.entries[0]!.response.content.text = text; - return JSON.stringify({ + capture.log.entries[0]!.response.content.text = "valid � 雪"; + const reply = { ok: true, value: decodeHarCapture(JSON.stringify(capture), []), + }; + const bytes = Buffer.from(JSON.stringify(reply)); + const file = await replyFile(bytes); + const result = await readHistoricalCaptureReply( + file.path, + "/capture.har", + file.resources, + ); + expect(result.bytes).toBe(bytes.length); + expect(result.finalization).toBeUndefined(); + expect(result.value).toEqual(reply); + + const invalid = Buffer.from(bytes); + const offset = invalid.indexOf(Buffer.from("�")); + expect(offset).toBeGreaterThan(0); + invalid[offset] = 0xff; + await writeFile(file.path, invalid); + await expect( + readHistoricalCaptureReply(file.path, "/capture.har", file.resources), + ).rejects.toMatchObject({ + _tag: "AnalysisOutputError", + reason: expect.stringContaining("Reply is not valid UTF-8."), + cause: { code: "ERR_ENCODING_INVALID_ENCODED_DATA" }, }); -}; - -it.each(["error", "output"] as const)( - "rejects malformed bytes inside an otherwise schema-valid %s reply", - async (kind) => { - const text = replyText(kind, "WIRE_MARKER"); - const offset = text.indexOf("WIRE_MARKER"); - expect(offset).toBeGreaterThan(0); - const bytes = Buffer.concat([ - Buffer.from(text.slice(0, offset)), - Buffer.from([0xff]), - Buffer.from(text.slice(offset + "WIRE_MARKER".length)), - ]); - const file = await replyFile(bytes); - await expect( - readHistoricalCaptureReply(file.path, "/capture.har", file.resources), - ).rejects.toMatchObject({ - _tag: "AnalysisOutputError", - reason: expect.stringContaining("Reply is not valid UTF-8."), - cause: { code: "ERR_ENCODING_INVALID_ENCODED_DATA" }, - }); - }, -); - -it.each(["error", "output"] as const)( - "preserves valid replacement-character text and exact byte counts in %s replies", - async (kind) => { - const text = replyText(kind, "valid � 雪"); - const bytes = Buffer.from(text); - const file = await replyFile(bytes); - const result = await readHistoricalCaptureReply( - file.path, - "/capture.har", - file.resources, - ); - expect(result.bytes).toBe(bytes.length); - expect(result.finalization).toBeUndefined(); - expect(result.value).toEqual(JSON.parse(text)); - }, -); +}); it.each(["{broken", "\uFEFF{}"])( "retains malformed JSON handling for %j", @@ -85,99 +62,87 @@ it.each(["{broken", "\uFEFF{}"])( }, ); -// Python's wire spelling differs from the JavaScript number retained in Evidence. -const nativeNumericReply = (literal: string) => { +it("preserves native number sidecars until their plain or exponential spelling is marked sensitive", async () => { const payload = decodeHarCapture(JSON.stringify(historicalHar()), []); - payload.records[0]!.reported = { + const record = payload.records[0]!; + record.reported = { metadata: { - ["__proto__"]: { ["ratio/~"]: [Number(literal)] }, + ["__proto__"]: { ["ratio/~"]: [1e-7, 1e20] }, ordinary: 42, }, }; - payload.records[0]!.numeric_literals = [ - { - pointer: "/metadata/__proto__/ratio~1~0/0", - producer_type: "float", - literal, - }, - ]; - return JSON.stringify({ ok: true, value: payload }); -}; - -it.each([ - ["1e-07", "1e-7"], - ["1e+20", "000000"], -] as const)( - "excludes the public spelling of native number %s and its numeric sidecar", - async (literal, sensitive) => { - const bytes = Buffer.from(nativeNumericReply(literal)); - const file = await replyFile(bytes); - const result = await readHistoricalCaptureReply( - file.path, - "/capture.mitm", - file.resources, - undefined, - [sensitive], - ); - if (!result.value.ok) throw new Error("Expected a capture reply"); - const record = result.value.value.records[0]!; - expect(record.reported).toEqual({ - metadata: { ["__proto__"]: { ["ratio/~"]: [null] }, ordinary: 42 }, - }); - expect(record.numeric_literals).toEqual([]); - expect(record.redactions).toContainEqual({ - pointer: "/metadata/__proto__/ratio~1~0/0", - reason: "explicit-sensitive-value", - }); - expect(JSON.stringify(record)).not.toContain(sensitive); - expect(result.bytes).toBe(bytes.length); - expect(Reflect.get(Object.prototype, "ratio/~")).toBeUndefined(); - }, -); - -it("preserves unmarked native numbers and exact producer literals", async () => { - const text = nativeNumericReply("1e-07"); - const file = await replyFile(Buffer.from(text)); - const result = await readHistoricalCaptureReply( + record.numeric_literals = ["1e-07", "1e+20"].map((literal, index) => ({ + pointer: `/metadata/__proto__/ratio~1~0/${index}`, + producer_type: "float", + literal, + })); + const reply = { ok: true, value: payload }; + const bytes = Buffer.from(JSON.stringify(reply)); + const file = await replyFile(bytes); + const unmarked = await readHistoricalCaptureReply( file.path, "/capture.mitm", file.resources, undefined, ["unrelated"], ); - expect(result.value).toEqual(JSON.parse(text)); + expect(unmarked.value).toEqual(reply); + const result = await readHistoricalCaptureReply( + file.path, + "/capture.mitm", + file.resources, + undefined, + ["1e-7", "000000"], + ); + if (!result.value.ok) throw new Error("Expected a capture reply"); + const retained = result.value.value.records[0]!; + expect(retained.reported).toEqual({ + metadata: { ["__proto__"]: { ["ratio/~"]: [null, null] }, ordinary: 42 }, + }); + expect(retained.numeric_literals).toEqual([]); + expect(retained.redactions).toEqual([ + { + pointer: "/metadata/__proto__/ratio~1~0/0", + reason: "explicit-sensitive-value", + }, + { + pointer: "/metadata/__proto__/ratio~1~0/1", + reason: "explicit-sensitive-value", + }, + ]); + expect(JSON.stringify(retained)).not.toMatch(/1e-7|000000/u); + expect(result.bytes).toBe(bytes.length); + expect(Reflect.get(Object.prototype, "ratio/~")).toBeUndefined(); }); -it.each(["container", "record"] as const)( - "excludes a normalized number at the %s root", - async (kind) => { - const payload = decodeHarCapture(JSON.stringify(historicalHar()), []); - const projection = - kind === "container" ? payload.container : payload.records[0]!; +it("excludes normalized numbers and their sidecars at both projection roots", async () => { + const payload = decodeHarCapture(JSON.stringify(historicalHar()), []); + for (const projection of [payload.container, payload.records[0]!]) { projection.reported = 1e-7; projection.numeric_literals = [ { pointer: "", producer_type: "float", literal: "1e-07" }, ]; projection.redactions = []; - const file = await replyFile( - Buffer.from(JSON.stringify({ ok: true, value: payload })), - ); - const result = await readHistoricalCaptureReply( - file.path, - "/capture.mitm", - file.resources, - undefined, - ["1e-7"], - ); - if (!result.value.ok) throw new Error("Expected a capture reply"); - const retained = - kind === "container" - ? result.value.value.container - : result.value.value.records[0]!; + } + const file = await replyFile( + Buffer.from(JSON.stringify({ ok: true, value: payload })), + ); + const result = await readHistoricalCaptureReply( + file.path, + "/capture.mitm", + file.resources, + undefined, + ["1e-7"], + ); + if (!result.value.ok) throw new Error("Expected a capture reply"); + for (const retained of [ + result.value.value.container, + result.value.value.records[0]!, + ]) { expect(retained.reported).toBeNull(); expect(retained.numeric_literals).toEqual([]); expect(retained.redactions).toEqual([ { pointer: "", reason: "explicit-sensitive-value" }, ]); - }, -); + } +}); diff --git a/tests/boundary/browser/historicalCaptureDecoder.test.ts b/tests/boundary/browser/historicalCaptureDecoder.test.ts index e76b04646b..e5b2aa6696 100644 --- a/tests/boundary/browser/historicalCaptureDecoder.test.ts +++ b/tests/boundary/browser/historicalCaptureDecoder.test.ts @@ -600,24 +600,29 @@ it.each(["missing-capture", "missing-reply", "failed-command"])( const path = join(root, "explicit-private-value.har"); if (mode !== "missing-capture") await writeFile(path, JSON.stringify(historicalHar())); + let privatePath: string | undefined; const decoder = new HistoricalCaptureDecoder( [ { format: "har", identity: HAR_CAPTURE_PROVIDER_IDENTITY, - command: async () => ({ - command: process.execPath, - arguments: [ - "-e", - mode === "failed-command" - ? 'process.stderr.write("explicit-private-value ordinary diagnostic"); process.exit(2)' - : "process.exit(0)", - ], - }), + command: async (_, runtimePath) => { + privatePath = runtimePath; + return { + command: process.execPath, + arguments: [ + "-e", + mode === "failed-command" + ? 'process.stderr.write("explicit-private-value ordinary diagnostic"); process.exit(2)' + : "process.exit(0)", + ], + }; + }, }, ], process.env, ); + onTestFinished(() => decoder.close()); const result = await decoder.inspect( inspectWebNetworkCaptureInputSchema.parse({ capture_path: path, @@ -637,47 +642,21 @@ it.each(["missing-capture", "missing-reply", "failed-command"])( ? "AnalysisOutputError" : "ProviderAdapterError", ); - if (mode === "missing-capture") expect(serialized).toContain("ENOENT"); + if (mode === "missing-capture") { + expect(privatePath).toBeUndefined(); + expect(serialized).toContain("ENOENT"); + return; + } + if (privatePath === undefined) + throw new Error("Private root was not acquired"); + await expect(access(privatePath)).rejects.toMatchObject({ code: "ENOENT" }); + if (mode === "missing-reply") + expect(result.error.message).toContain("ENOENT"); if (mode === "failed-command") expect(serialized).toContain('"exit_code":2'); }, ); -it("reports an absent owned reply as output failure and removes its private snapshot root", async () => { - const root = await createTestTempDirectory("rea-historical-decoder-"); - const path = join(root, "input.har"); - await writeFile(path, JSON.stringify(historicalHar())); - let privatePath: string | undefined; - const decoder = new HistoricalCaptureDecoder( - [ - { - format: "har", - identity: HAR_CAPTURE_PROVIDER_IDENTITY, - command: async (_, runtimePath) => { - privatePath = runtimePath; - return { - command: process.execPath, - arguments: ["-e", "process.exit(0)"], - }; - }, - }, - ], - process.env, - ); - const result = await decoder.inspect( - inspectWebNetworkCaptureInputSchema.parse({ - capture_path: path, - format: "har", - }), - ); - if (result.ok) throw new Error("Owned reply is required"); - expect(result.error._tag).toBe("AnalysisOutputError"); - expect(result.error.message).toContain("ENOENT"); - if (privatePath === undefined) - throw new Error("Private root was not acquired"); - await expect(access(privatePath)).rejects.toMatchObject({ code: "ENOENT" }); -}); - it("cancels after snapshot acquisition before launch and removes private input declarations", async () => { const root = await createTestTempDirectory("rea-historical-cancel-"); const path = join(root, "input.har"); diff --git a/tests/boundary/browser/historicalWebCapture.test.ts b/tests/boundary/browser/historicalWebCapture.test.ts index 8f0a5fe952..fc4e6ce8ab 100644 --- a/tests/boundary/browser/historicalWebCapture.test.ts +++ b/tests/boundary/browser/historicalWebCapture.test.ts @@ -9,6 +9,7 @@ import { promisify } from "node:util"; import { parseEvidence } from "../../../src/domain/evidence.js"; import { webNetworkCaptureSchema } from "../../../src/domain/webNetworkCapture.js"; import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js"; +import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; const entrypoint = fileURLToPath( new URL("../../../scripts/rea.mjs", import.meta.url), @@ -312,7 +313,7 @@ it("reads actual upstream HAR packages in an owned process and retains selected }); }); -it("keeps malformed JSON separate from absent external mitmproxy capability", async () => { +it("keeps malformed JSON, unsupported HAR versions and missing external capability distinct", async () => { const root = await createTestTempDirectory("rea-history-errors-"); const path = join(root, "capture.har"); await writeFile(path, "{malformed-private-json"); @@ -322,6 +323,43 @@ it("keeps malformed JSON separate from absent external mitmproxy capability", as category: "invalid_input", }); expect(malformed.stdout).not.toContain("malformed-private-json"); + const fixture = historicalHar(); + fixture.log.version = "1.1"; + await writeFile(path, JSON.stringify(fixture)); + const unsupported = await cli(path, "har"); + expect(unsupported.ok, unsupported.stdout).toBe(false); + const refusal = { + code: "capability_unavailable", + category: "unsupported_provider", + message: expect.stringContaining("HAR 1.2"), + remediation: { action: expect.stringContaining("capture format") }, + details: { diagnostics: { pointer: "/log/version" } }, + }; + expect(JSON.parse(unsupported.stdout)).toMatchObject(refusal); + const { call } = await connectLocalToolsMcp(); + const request = { capture_path: path, format: "har" }; + const unsupportedMcp = await call("inspect_web_network_capture", request); + expect(parseMcpToolError(unsupportedMcp).error).toMatchObject(refusal); + const marked = await call("inspect_web_network_capture", { + ...request, + sensitive_values: ["HAR 1.2", "/log/version"], + }); + expect(parseMcpToolError(marked).error.code).toBe(refusal.code); + expect(JSON.stringify(marked)).not.toMatch(/HAR 1\.2|\/log\/version/u); + + const supportedPath = join(root, "supported.har"); + await writeFile(supportedPath, JSON.stringify(historicalHar())); + const recovered = await call("inspect_web_network_capture", { + ...request, + capture_path: supportedPath, + }); + expect(recovered.isError).not.toBe(true); + expect( + parseEvidence(recovered.structuredContent).normalized_result, + ).toMatchObject({ + artifact: { path: supportedPath }, + total_records: 1, + }); const missing = await cli(path, "mitmproxy"); expect(missing.ok).toBe(false); expect(JSON.parse(missing.stdout)).toMatchObject({ diff --git a/tests/boundary/browser/sazWebCapture.test.ts b/tests/boundary/browser/sazWebCapture.test.ts index 13ecc96df0..aa0881aed8 100644 --- a/tests/boundary/browser/sazWebCapture.test.ts +++ b/tests/boundary/browser/sazWebCapture.test.ts @@ -907,14 +907,17 @@ it.each([ const path = await fixture(bytes); const result = await cliResponse(path, ["--record", "0"]); expect(result.ok, result.stdout).toBe(false); - expect(JSON.parse(result.stdout).category).toBe( + const failure = JSON.parse(result.stdout); + expect(failure.category).toBe( ["encrypted", "unknown-member", "dtd"].includes(variant) ? "unsupported_provider" : "invalid_input", ); + if (variant === "encrypted") + expect(failure.message).toContain("export an unencrypted copy"); // Expanded size is a caller-correctable input bound, not a decoder failure. if (variant === "expanded-limit") { - const error = JSON.parse(result.stdout); + const error = failure; expect(error.code).toBe("invalid_request"); expect(error.details.issues).toEqual([ expect.objectContaining({