fix(capture): surface unsupported decoder requirements (#13203)

This commit is contained in:
morluto authored and GitHub committed 2026-11-21 20:38:10 +00:00
1 parent 204434e087
commit 088bc68b1c
8 files changed
+174 -204

No files matched your search

+3
View File
@@ -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.
+1 -26
View File
@@ -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();
});
@@ -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");
},
);
@@ -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}`,
@@ -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" },
]);
},
);
}
});
@@ -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");
@@ -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({
+5 -2
View File
@@ -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({