@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.50

package/dist/stream-evidence.js

@@ -0,0 +1,785 @@
+import { createHash } from "node:crypto";
+import { isSensitiveFixtureKey, isSensitiveFixtureValue, REDACTED_FIXTURE_VALUE, sanitizeDiagnosticText, sanitizeFixtureString, sanitizeUrlForLogs, } from "./fixture-sanitization.js";
+import { toJsonValue } from "./contract-json.js";
+import { readableBytes, readableLines, readableTextChunks } from "./stream.js";
+export const STREAM_PREVIEW_BYTES = 4096;
+export const STREAM_FINALIZE_TIMEOUT_MS = 30_000;
+const STREAM_EVIDENCE_HEADER_NAMES = [
+    "content-disposition",
+    "content-length",
+    "content-type",
+];
+const STREAM_EVIDENCE_HEADERS = new Set(STREAM_EVIDENCE_HEADER_NAMES);
+const STREAM_EVIDENCE_REDACTION_REASONS = [
+    "high-entropy-token",
+    "malformed-json",
+    "pem-private-key",
+    "sanitized-preview-too-large",
+    "sanitizer-output-invalid",
+    "sensitive-delimited-column",
+    "textual-xml",
+    "truncated-form",
+    "truncated-json",
+    "undecodable-text",
+];
+const STREAM_EVIDENCE_REDACTION_REASON_SET = new Set(STREAM_EVIDENCE_REDACTION_REASONS);
+export function parseStreamEvidenceRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Stream evidence must be an object.");
+    }
+    const record = value;
+    if (record.__apifuse_stream__ !== true) {
+        throw new Error('Stream evidence field "__apifuse_stream__" must be true.');
+    }
+    if (!Number.isInteger(record.status) ||
+        record.status < 100 ||
+        record.status > 599) {
+        throw new Error('Stream evidence field "status" must be an integer from 100 through 599.');
+    }
+    if (typeof record.ok !== "boolean") {
+        throw new Error('Stream evidence field "ok" must be a boolean.');
+    }
+    if (record.ok !== (record.status >= 200 && record.status < 300)) {
+        throw new Error('Stream evidence field "ok" is inconsistent with "status".');
+    }
+    if (!isStringRecord(record.headers)) {
+        throw new Error('Stream evidence field "headers" must contain only string values.');
+    }
+    for (const name of Object.keys(record.headers)) {
+        if (!STREAM_EVIDENCE_HEADERS.has(name)) {
+            throw new Error(`Stream evidence header "${sanitizeDiagnosticText(name)}" is not allowlisted.`);
+        }
+    }
+    if (typeof record.body_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(record.body_sha256)) {
+        throw new Error('Stream evidence field "body_sha256" must be a lowercase SHA-256 hex digest.');
+    }
+    if (!Number.isSafeInteger(record.body_bytes) || record.body_bytes < 0) {
+        throw new Error('Stream evidence field "body_bytes" must be a non-negative safe integer.');
+    }
+    if (typeof record.body_preview_base64 !== "string") {
+        throw new Error('Stream evidence field "body_preview_base64" must be a string.');
+    }
+    if (record.request !== undefined)
+        validateStreamEvidenceRequest(record.request);
+    if (record.preview_sanitized !== undefined && record.preview_sanitized !== true) {
+        throw new Error('Stream evidence field "preview_sanitized" must be true when present.');
+    }
+    if (record.preview_redaction_reason !== undefined &&
+        !isStreamEvidenceRedactionReason(record.preview_redaction_reason)) {
+        throw new Error('Stream evidence field "preview_redaction_reason" is invalid.');
+    }
+    if (record.preview_redaction_reason !== undefined && record.preview_sanitized !== true) {
+        throw new Error('Stream evidence field "preview_redaction_reason" requires "preview_sanitized".');
+    }
+    const preview = Buffer.from(record.body_preview_base64, "base64");
+    if (preview.toString("base64") !== record.body_preview_base64) {
+        throw new Error('Stream evidence field "body_preview_base64" must be canonical base64.');
+    }
+    const expectedPreviewBytes = Math.min(record.body_bytes, STREAM_PREVIEW_BYTES);
+    if (preview.byteLength !== expectedPreviewBytes) {
+        throw new Error(`Stream evidence preview must decode to ${expectedPreviewBytes} bytes for body_bytes=${String(record.body_bytes)}.`);
+    }
+    if (record.preview_sanitized !== true &&
+        record.body_bytes <= STREAM_PREVIEW_BYTES &&
+        createHash("sha256").update(preview).digest("hex") !== record.body_sha256) {
+        throw new Error('Stream evidence field "body_sha256" must match a complete unsanitized preview.');
+    }
+    const headers = streamEvidenceHeaders(record.headers);
+    return {
+        __apifuse_stream__: true,
+        status: record.status,
+        ok: record.ok,
+        headers,
+        body_sha256: record.body_sha256,
+        body_bytes: record.body_bytes,
+        body_preview_base64: record.body_preview_base64,
+        ...(record.request === undefined ? {} : { request: streamEvidenceRequest(record.request) }),
+        ...(record.preview_sanitized === true ? { preview_sanitized: true } : {}),
+        ...(record.preview_redaction_reason === undefined
+            ? {}
+            : { preview_redaction_reason: record.preview_redaction_reason }),
+    };
+}
+export function isStreamEvidenceRecord(value) {
+    try {
+        parseStreamEvidenceRecord(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function findStreamEvidenceRecord(value) {
+    return findStreamEvidenceRecords(value).at(-1);
+}
+/**
+ * Selects every stream captured by the latest recording invocation, in stream call order.
+ * Evidence without request ordinals uses the legacy latest-record-only behavior.
+ */
+export function findStreamEvidenceRecords(value) {
+    if (isStreamCaptureEnvelope(value)) {
+        return parseStreamCaptureEnvelope(value).items.flatMap((item) => item.kind === "stream" ? [item.evidence] : []);
+    }
+    if (Array.isArray(value) && isStreamCaptureEnvelope(value.at(-1))) {
+        return parseStreamCaptureEnvelope(value.at(-1)).items.flatMap((item) => (item.kind === "stream" ? [item.evidence] : []));
+    }
+    const group = findLatestStreamCaptureGroup(value);
+    if (!group)
+        return [];
+    return group
+        .filter(hasStreamEvidenceMarker)
+        .map((candidate) => parseStreamEvidenceRecord(candidate));
+}
+/** Returns a tagged latest mixed response group used by evidence-only snapshot replay. */
+export function findStreamCaptureGroup(value) {
+    if (isStreamCaptureEnvelope(value))
+        return parseStreamCaptureEnvelope(value);
+    if (Array.isArray(value)) {
+        const latest = value.at(-1);
+        if (isStreamCaptureEnvelope(latest))
+            return parseStreamCaptureEnvelope(latest);
+        if (Array.isArray(latest)) {
+            const nested = findStreamCaptureGroup(latest);
+            if (nested)
+                return nested;
+        }
+    }
+    const group = findLatestStreamCaptureGroup(value);
+    if (!group)
+        return undefined;
+    return {
+        items: group.map((item) => {
+            if (hasStreamEvidenceMarker(item)) {
+                return { kind: "stream", evidence: parseStreamEvidenceRecord(item) };
+            }
+            const json = toJsonValue(item);
+            if (json === undefined) {
+                throw new Error("Stream capture group contains a non-JSON response value.");
+            }
+            return { kind: "response", value: json };
+        }),
+    };
+}
+/** Creates a discriminated invocation envelope so ordinary arrays cannot mimic capture timelines. */
+export function createStreamCaptureEnvelope(items) {
+    if (!items.some((item) => item.kind === "stream")) {
+        throw new Error("A stream capture envelope must contain at least one stream item.");
+    }
+    return { __apifuse_capture__: true, items };
+}
+function isStreamCaptureEnvelope(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.__apifuse_capture__ === true);
+}
+function parseStreamCaptureEnvelope(value) {
+    if (!Array.isArray(value.items) || value.items.length === 0) {
+        throw new Error("Stream capture envelope items must be a non-empty array.");
+    }
+    const items = value.items.map((item) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error("Stream capture envelope item must be an object.");
+        }
+        if (item.kind === "stream") {
+            return { kind: "stream", evidence: parseStreamEvidenceRecord(item.evidence) };
+        }
+        if (item.kind === "response") {
+            const json = toJsonValue(item.value);
+            if (json === undefined) {
+                throw new Error("Stream capture response item must contain a JSON value.");
+            }
+            return { kind: "response", value: json };
+        }
+        throw new Error('Stream capture envelope item kind must be "stream" or "response".');
+    });
+    if (!items.some((item) => item.kind === "stream")) {
+        throw new Error("Stream capture envelope must contain at least one stream item.");
+    }
+    return { items };
+}
+export function isStreamEvidenceReplayResponse(response) {
+    const candidate = response;
+    return (candidate.evidence_only === true &&
+        typeof candidate.body_sha256 === "string" &&
+        Number.isSafeInteger(candidate.body_bytes));
+}
+export function captureStreamEvidence(response, options) {
+    const reader = response.body.getReader();
+    const hash = createHash("sha256");
+    const preview = new Uint8Array(STREAM_PREVIEW_BYTES);
+    let bodyBytes = 0;
+    let previewBytes = 0;
+    let evidence;
+    let terminalError;
+    let handlerPull;
+    let handlerCanceled = false;
+    let finalizing = false;
+    let evidencePromise;
+    function retainChunk(chunk) {
+        hash.update(chunk);
+        bodyBytes += chunk.byteLength;
+        if (previewBytes < STREAM_PREVIEW_BYTES) {
+            const retained = chunk.subarray(0, STREAM_PREVIEW_BYTES - previewBytes);
+            preview.set(retained, previewBytes);
+            previewBytes += retained.byteLength;
+        }
+    }
+    function finishCapture() {
+        evidence ??= createEvidenceRecord(response, hash.digest("hex"), bodyBytes, preview.subarray(0, previewBytes), options.sanitizeFixture, options.request);
+        return evidence;
+    }
+    function captureReadFailure(error) {
+        terminalError ??= streamCaptureError("read failed", options.requestUrl, response, bodyBytes, error);
+        return terminalError;
+    }
+    const body = new ReadableStream({
+        async pull(controller) {
+            if (finalizing)
+                return;
+            const currentPull = (async () => {
+                try {
+                    const result = await reader.read();
+                    if (terminalError)
+                        throw terminalError;
+                    if (result.done) {
+                        finishCapture();
+                        if (!handlerCanceled)
+                            controller.close();
+                        return;
+                    }
+                    retainChunk(result.value);
+                    if (!handlerCanceled)
+                        controller.enqueue(result.value);
+                }
+                catch (error) {
+                    controller.error(captureReadFailure(error));
+                }
+            })();
+            handlerPull = currentPull;
+            try {
+                await currentPull;
+            }
+            finally {
+                if (handlerPull === currentPull)
+                    handlerPull = undefined;
+            }
+        },
+        cancel() {
+            handlerCanceled = true;
+            // Keep the upstream reader alive so finalization can capture the complete body.
+        },
+    });
+    return {
+        response: streamResponseFromBody(response.status, response.ok, response.headers, body),
+        getEvidence() {
+            if (terminalError)
+                return Promise.reject(terminalError);
+            if (evidence)
+                return Promise.resolve(evidence);
+            if (evidencePromise)
+                return evidencePromise;
+            finalizing = true;
+            const drainPromise = (async () => {
+                await handlerPull;
+                if (terminalError)
+                    throw terminalError;
+                if (evidence)
+                    return evidence;
+                for (;;) {
+                    let result;
+                    try {
+                        result = await reader.read();
+                    }
+                    catch (error) {
+                        throw captureReadFailure(error);
+                    }
+                    if (terminalError)
+                        throw terminalError;
+                    if (result.done)
+                        return finishCapture();
+                    retainChunk(result.value);
+                }
+            })();
+            const timeoutMs = options.finalizeTimeoutMs ?? STREAM_FINALIZE_TIMEOUT_MS;
+            evidencePromise = withFinalizationTimeout(drainPromise, timeoutMs, () => {
+                const timeoutError = streamCaptureError(`finalization timed out after ${timeoutMs}ms`, options.requestUrl, response, bodyBytes);
+                terminalError ??= timeoutError;
+                void reader.cancel(timeoutError).catch((cancelError) => {
+                    timeoutError.cause = cancelError;
+                });
+                return timeoutError;
+            });
+            return evidencePromise;
+        },
+    };
+}
+export function replayStreamEvidence(evidence) {
+    const validEvidence = parseStreamEvidenceRecord(evidence);
+    const preview = new Uint8Array(Buffer.from(validEvidence.body_preview_base64, "base64"));
+    const replayHeaders = Object.fromEntries(Object.entries(validEvidence.headers).filter(([name]) => name !== "content-length"));
+    return {
+        ...streamResponseFromBytes(validEvidence.status, validEvidence.ok, replayHeaders, preview),
+        evidence_only: true,
+        body_sha256: validEvidence.body_sha256,
+        body_bytes: validEvidence.body_bytes,
+        ...(validEvidence.preview_sanitized ? { preview_sanitized: true } : {}),
+        ...(validEvidence.preview_redaction_reason
+            ? { preview_redaction_reason: validEvidence.preview_redaction_reason }
+            : {}),
+    };
+}
+function createEvidenceRecord(response, bodySha256, bodyBytes, preview, sanitizeFixture, request) {
+    const contentType = headerValue(response.headers, "content-type");
+    const sanitized = sanitizeFixture
+        ? sanitizePreview(preview, bodyBytes, contentType, sanitizeFixture)
+        : undefined;
+    const safePreview = sanitized?.preview ?? preview;
+    const previewChanged = !bytesEqual(safePreview, preview);
+    const previewSanitized = previewChanged || sanitized?.redactionReason !== undefined;
+    return {
+        __apifuse_stream__: true,
+        status: response.status,
+        ok: response.ok,
+        headers: evidenceHeaders(response.headers, sanitizeFixture !== undefined),
+        body_sha256: bodySha256,
+        body_bytes: bodyBytes,
+        body_preview_base64: Buffer.from(safePreview).toString("base64"),
+        ...(request ? { request } : {}),
+        ...(previewSanitized ? { preview_sanitized: true } : {}),
+        ...(sanitized?.redactionReason ? { preview_redaction_reason: sanitized.redactionReason } : {}),
+    };
+}
+function sanitizePreview(preview, bodyBytes, contentType, sanitizeFixture) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(preview);
+    }
+    catch {
+        return sanitizePartiallyDecodablePreview(preview);
+    }
+    const declaredTextual = isTextualContentType(contentType);
+    const sniffedTextual = looksLikeJson(text) || looksLikeXml(text) || looksLikeText(text);
+    const sanitizedPrimitive = sanitizeFixtureString(text);
+    const containsTextualSecret = sanitizedPrimitive !== text;
+    if (hasKnownBinaryMagic(preview) && !containsTextualSecret)
+        return undefined;
+    if (!declaredTextual && !sniffedTextual && !containsTextualSecret)
+        return undefined;
+    const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    if (looksLikePemPrivateKey(text)) {
+        return redactedSanitizedPreview(preview.byteLength, "pem-private-key");
+    }
+    if (mediaType.includes("xml") || looksLikeXml(text)) {
+        return redactedSanitizedPreview(preview.byteLength, "textual-xml");
+    }
+    let sanitizedText;
+    const jsonPreview = isJsonContentType(mediaType) || looksLikeJson(text);
+    if (jsonPreview) {
+        if (bodyBytes > preview.byteLength) {
+            return redactedSanitizedPreview(preview.byteLength, "truncated-json");
+        }
+        try {
+            sanitizedText = JSON.stringify(sanitizeFixture(JSON.parse(text)));
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError)) {
+                throw new Error("Stream JSON preview sanitizer failed.", { cause: error });
+            }
+            return redactedSanitizedPreview(preview.byteLength, "malformed-json", true);
+        }
+    }
+    else if (mediaType === "application/x-www-form-urlencoded") {
+        if (bodyBytes > preview.byteLength) {
+            return redactedSanitizedPreview(preview.byteLength, "truncated-form");
+        }
+        const form = new URLSearchParams(text);
+        let sanitized;
+        try {
+            sanitized = sanitizeFixture(Object.fromEntries(form.entries()));
+        }
+        catch (error) {
+            throw new Error("Stream form preview sanitizer failed.", { cause: error });
+        }
+        if (!isStringRecord(sanitized)) {
+            return redactedSanitizedPreview(preview.byteLength, "sanitizer-output-invalid");
+        }
+        sanitizedText = new URLSearchParams(sanitized).toString();
+    }
+    else {
+        if (hasSensitiveDelimitedHeader(text)) {
+            return redactedSanitizedPreview(preview.byteLength, "sensitive-delimited-column");
+        }
+        const tokenRedaction = redactHighEntropyTokens(text);
+        sanitizedText = sanitizeFixtureString(tokenRedaction.text);
+        const sanitizedBytes = new TextEncoder().encode(sanitizedText);
+        if (sanitizedBytes.byteLength > preview.byteLength) {
+            return redactedSanitizedPreview(preview.byteLength, "sanitized-preview-too-large");
+        }
+        return {
+            preview: fitSanitizedPreview(sanitizedBytes, preview.byteLength),
+            ...(tokenRedaction.redacted ? { redactionReason: "high-entropy-token" } : {}),
+        };
+    }
+    const sanitizedBytes = new TextEncoder().encode(sanitizedText);
+    if (sanitizedBytes.byteLength > preview.byteLength) {
+        return redactedSanitizedPreview(preview.byteLength, "sanitized-preview-too-large", jsonPreview);
+    }
+    return { preview: fitSanitizedPreview(sanitizedBytes, preview.byteLength) };
+}
+function sanitizePartiallyDecodablePreview(preview) {
+    const text = new TextDecoder("utf-8").decode(preview);
+    const containsTextualSecret = sanitizeFixtureString(text) !== text;
+    if (!containsTextualSecret) {
+        if (hasKnownBinaryMagic(preview))
+            return undefined;
+        // Undecodable non-binary data cannot be proven safe. Declared text in particular must fail closed.
+        return redactedSanitizedPreview(preview.byteLength, "undecodable-text");
+    }
+    let sanitized = sanitizeDecodableWindows(preview);
+    const retainedText = new TextDecoder("utf-8").decode(sanitized);
+    if (sanitizeFixtureString(retainedText) !== retainedText) {
+        sanitized = redactedPreview(preview.byteLength);
+    }
+    return {
+        preview: sanitized,
+        ...(looksLikePemPrivateKey(text)
+            ? { redactionReason: "pem-private-key" }
+            : redactHighEntropyTokens(text).redacted
+                ? { redactionReason: "high-entropy-token" }
+                : {}),
+    };
+}
+function sanitizeDecodableWindows(preview) {
+    const sanitized = preview.slice();
+    let start = 0;
+    for (let index = 0; index <= preview.byteLength; index += 1) {
+        const byte = preview[index];
+        if (index < preview.byteLength && byte !== undefined && byte < 0x80)
+            continue;
+        if (index > start) {
+            const window = preview.subarray(start, index);
+            const text = new TextDecoder("utf-8", { fatal: true }).decode(window);
+            const safeText = sanitizeFixtureString(text);
+            if (safeText !== text) {
+                sanitized.set(fitSanitizedPreview(new TextEncoder().encode(safeText), window.byteLength), start);
+            }
+        }
+        start = index + 1;
+    }
+    return sanitized;
+}
+function looksLikePemPrivateKey(text) {
+    return /-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/.test(text);
+}
+function redactHighEntropyTokens(text) {
+    let redacted = false;
+    const sanitized = text.replace(/[A-Za-z0-9_+/=.:~-]{24,}/g, (candidate) => {
+        if (!isSensitiveFixtureValue(candidate))
+            return candidate;
+        redacted = true;
+        return REDACTED_FIXTURE_VALUE;
+    });
+    return { text: sanitized, redacted };
+}
+function hasSensitiveDelimitedHeader(text) {
+    const lines = text.split(/\r?\n/);
+    const firstLine = lines[0]?.trim();
+    if (!firstLine)
+        return false;
+    if (lines.length > 1 && isSensitiveFixtureKey(firstLine))
+        return true;
+    for (const delimiter of [",", "\t", ";", "|"]) {
+        const columns = splitDelimitedRow(firstLine, delimiter);
+        if (columns.length > 1 && columns.some((column) => isSensitiveFixtureKey(column.trim()))) {
+            return true;
+        }
+    }
+    return false;
+}
+function splitDelimitedRow(row, delimiter) {
+    const values = [];
+    let value = "";
+    let quote = "";
+    for (let index = 0; index < row.length; index += 1) {
+        const character = row.charAt(index);
+        if (quote) {
+            if (character === quote && row[index + 1] === quote) {
+                value += quote;
+                index += 1;
+            }
+            else if (character === quote) {
+                quote = "";
+            }
+            else {
+                value += character;
+            }
+        }
+        else if ((character === '"' || character === "'") && value.length === 0) {
+            quote = character;
+        }
+        else if (character === delimiter) {
+            values.push(value);
+            value = "";
+        }
+        else {
+            value += character;
+        }
+    }
+    values.push(value);
+    return values;
+}
+function fitSanitizedPreview(sanitized, targetBytes) {
+    if (sanitized.byteLength > targetBytes)
+        return validRedactedPreview(targetBytes);
+    if (sanitized.byteLength === targetBytes)
+        return sanitized;
+    const fitted = new Uint8Array(targetBytes);
+    fitted.fill(0x20);
+    fitted.set(sanitized);
+    return fitted;
+}
+function redactedPreview(byteLength) {
+    const redacted = new Uint8Array(byteLength);
+    redacted.fill(0x20);
+    redacted.set(new TextEncoder().encode(REDACTED_FIXTURE_VALUE).subarray(0, byteLength));
+    return redacted;
+}
+function validRedactedPreview(byteLength) {
+    if (byteLength >= 2) {
+        const redacted = new Uint8Array(byteLength);
+        redacted.fill(0x20);
+        redacted.set(new TextEncoder().encode("{}"));
+        return redacted;
+    }
+    return redactedPreview(byteLength);
+}
+function redactedSanitizedPreview(byteLength, redactionReason, validJson = false) {
+    return {
+        preview: validJson ? validRedactedPreview(byteLength) : redactedPreview(byteLength),
+        redactionReason,
+    };
+}
+function isTextualContentType(contentType) {
+    const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+    return (mediaType.startsWith("text/") ||
+        isJsonContentType(mediaType) ||
+        mediaType === "application/xml" ||
+        mediaType.endsWith("+xml") ||
+        mediaType === "application/x-www-form-urlencoded");
+}
+function isJsonContentType(mediaType) {
+    return mediaType === "application/json" || mediaType.endsWith("+json");
+}
+function looksLikeJson(text) {
+    const trimmed = text.trimStart();
+    return trimmed.startsWith("{") || trimmed.startsWith("[");
+}
+function looksLikeXml(text) {
+    return /^\s*<\??[a-z_][\w:.-]*/i.test(text);
+}
+function looksLikeText(text) {
+    if (text.length === 0 || text.includes("\0"))
+        return false;
+    let readable = 0;
+    let suspicious = 0;
+    for (const character of text) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        if (character === "\uFFFD" || (codePoint < 0x20 && !"\t\n\r".includes(character))) {
+            suspicious += 1;
+        }
+        else {
+            readable += 1;
+        }
+    }
+    return readable > 0 && suspicious / (readable + suspicious) < 0.02;
+}
+function hasKnownBinaryMagic(bytes) {
+    const signatures = [
+        [0x89, 0x50, 0x4e, 0x47], // PNG
+        [0xff, 0xd8, 0xff], // JPEG
+        [0x47, 0x49, 0x46, 0x38], // GIF
+        [0x25, 0x50, 0x44, 0x46], // PDF
+        [0x50, 0x4b, 0x03, 0x04], // ZIP and ZIP-based formats
+        [0x1f, 0x8b], // gzip
+        [0x7f, 0x45, 0x4c, 0x46], // ELF
+        [0x52, 0x61, 0x72, 0x21], // RAR
+        [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c], // 7z
+    ];
+    return signatures.some((signature) => bytes.byteLength >= signature.length &&
+        signature.every((byte, index) => bytes[index] === byte));
+}
+function findLatestStreamCaptureGroup(value) {
+    if (hasStreamEvidenceMarker(value)) {
+        parseStreamEvidenceRecord(value);
+        return [value];
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    let rightmostDirectMarker = -1;
+    for (let index = value.length - 1; index >= 0; index -= 1) {
+        const candidate = value[index];
+        if (Array.isArray(candidate)) {
+            const nested = findLatestStreamCaptureGroup(candidate);
+            if (nested)
+                return nested;
+        }
+        if (hasStreamEvidenceMarker(candidate)) {
+            rightmostDirectMarker = index;
+            break;
+        }
+    }
+    if (rightmostDirectMarker < 0)
+        return undefined;
+    const directRecords = value
+        .map((candidate, index) => hasStreamEvidenceMarker(candidate)
+        ? { index, record: parseStreamEvidenceRecord(candidate) }
+        : undefined)
+        .filter((candidate) => candidate !== undefined);
+    if (directRecords.some(({ record }) => record.request === undefined)) {
+        return [value[rightmostDirectMarker]];
+    }
+    let startIndex = directRecords[0]?.index ?? 0;
+    let previous = directRecords[0];
+    if (!previous)
+        return undefined;
+    for (const current of directRecords.slice(1)) {
+        const previousRequest = previous.record.request;
+        const currentRequest = current.record.request;
+        if (!previousRequest || !currentRequest) {
+            throw new Error("Stream capture grouping invariant violated: request provenance is missing.");
+        }
+        if (currentRequest.ordinal <= previousRequest.ordinal) {
+            startIndex = current.index;
+        }
+        previous = current;
+    }
+    return value.slice(startIndex);
+}
+export function hasStreamEvidenceMarker(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (record.__apifuse_stream__ === true &&
+        ("body_sha256" in record ||
+            "body_bytes" in record ||
+            "body_preview_base64" in record ||
+            "headers" in record));
+}
+function isStringRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+function validateStreamEvidenceRequest(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error('Stream evidence field "request" must be an object.');
+    }
+    const request = value;
+    if (!Number.isSafeInteger(request.ordinal) || request.ordinal < 1) {
+        throw new Error('Stream evidence request field "ordinal" must be a positive safe integer.');
+    }
+    if (typeof request.method !== "string" || !/^[A-Z]+$/.test(request.method)) {
+        throw new Error('Stream evidence request field "method" must be an uppercase HTTP method.');
+    }
+    if (typeof request.path !== "string" ||
+        !request.path.startsWith("/") ||
+        request.path.includes("?") ||
+        request.path.includes("#")) {
+        throw new Error('Stream evidence request field "path" must be a query-free absolute path.');
+    }
+}
+function streamEvidenceRequest(value) {
+    validateStreamEvidenceRequest(value);
+    const request = value;
+    return {
+        ordinal: request.ordinal,
+        method: request.method,
+        path: request.path,
+    };
+}
+function isStreamEvidenceRedactionReason(value) {
+    return typeof value === "string" && STREAM_EVIDENCE_REDACTION_REASON_SET.has(value);
+}
+function streamEvidenceHeaders(headers) {
+    return selectEvidenceHeaders(Object.entries(headers));
+}
+function evidenceHeaders(headers, sanitize) {
+    return selectEvidenceHeaders(Object.entries(headers).map(([name, value]) => {
+        const normalizedName = name.toLowerCase();
+        return [
+            normalizedName,
+            sanitize ? sanitizeEvidenceHeaderValue(normalizedName, value) : value,
+        ];
+    }));
+}
+function sanitizeEvidenceHeaderValue(name, value) {
+    if (name === "content-disposition")
+        return sanitizeFixtureString(value);
+    if (name !== "content-type")
+        return value;
+    const [mediaType = "", ...parameters] = value.split(";");
+    if (parameters.length === 0)
+        return mediaType;
+    return [mediaType, ...parameters.map((parameter) => sanitizeFixtureString(parameter))].join(";");
+}
+function selectEvidenceHeaders(entries) {
+    const source = Object.fromEntries(entries);
+    return Object.fromEntries(STREAM_EVIDENCE_HEADER_NAMES.flatMap((name) => {
+        const value = source[name];
+        return value === undefined ? [] : [[name, value]];
+    }));
+}
+function bytesEqual(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    return left.every((byte, index) => byte === right[index]);
+}
+function withFinalizationTimeout(promise, timeoutMs, onTimeout) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(onTimeout());
+        }, timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timeout);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
+function headerValue(headers, targetName) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() === targetName)
+            return value;
+    }
+    return undefined;
+}
+function streamCaptureError(phase, requestUrl, response, bodyBytes, cause) {
+    return new Error(`Stream capture ${phase}: url=${sanitizeUrlForLogs(requestUrl)} status=${response.status} bytes_read=${bodyBytes}`, cause === undefined ? undefined : { cause });
+}
+function streamResponseFromBytes(status, ok, headers, bytes) {
+    const body = new ReadableStream({
+        start(controller) {
+            if (bytes.byteLength > 0)
+                controller.enqueue(bytes.slice());
+            controller.close();
+        },
+    });
+    return streamResponseFromBody(status, ok, headers, body);
+}
+function streamResponseFromBody(status, ok, headers, body) {
+    return {
+        status,
+        ok,
+        headers: { ...headers },
+        body,
+        bytes: () => readableBytes(body),
+        textChunks: () => readableTextChunks(body),
+        lines: () => readableLines(body),
+    };
+}