Files
rea/src/artifacts/readStableArtifact.ts
T
YsopwnableGitHubKaoru0822github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2bf3663f65 feat(browser): inspect historical web network captures (#992)
* feat(browser): inspect retained HAR and mitmproxy capture evidence

Add independent offline format adapters, inline CLI/MCP evidence, bounded
owned decoder processes, and real producer verification.

Refs #882

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): preserve capture boundaries during cancellation and decoding

Honor cancellation during owned-command cleanup, retain opaque HAR
extension content, and clean verifier resources on every failure path.

Refs #882

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): exclude sensitive capture fields across representations

Normalize known native transport URLs for both bytes and strings, including backups. Exclude explicitly sensitive text fields with null so redaction markers cannot reintroduce declared literals. Cover both provider identities in catalog conformance.

Refs #882

Assisted-by: Yukari (gensokyo-skills:yukari-boundary-analysis)
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)

* fix(browser): exclude sensitive capture identities and bound diagnostics

* fix(browser): validate excluded HAR subtrees before projection

* fix(browser): distinguish capture input limits from decoder failures

* fix(browser): preserve decoder failure categories

* fix(browser): validate excluded native credential values

* test(browser): report capture verifier assertions directly

* fix(browser): classify native representation failures precisely

* fix(browser): exclude URL userinfo after header whitespace

* fix(browser): preserve capture evidence and failure boundaries

* fix(browser): exclude sensitive literals from capture limitations

* test(browser): check limitation values without JSON syntax

* fix(browser): preserve acquisition integrity and exclude selection diagnostics

* fix(browser): preserve capture acquisition and declaration boundaries

* fix(mcp): project sensitive capture argument validation

* fix: preserve capture bytes and prelaunch cancellation

* fix(browser): exclude sensitive HAR record ancestry

* fix(browser): preserve transport URL and parameter exclusions

* fix(browser): preserve numeric redaction and canonical capture provenance

* fix(browser): cover derived capture values and ownership preparation deadlines

* fix(browser): exclude explicitly sensitive artifact digests

* chore: regenerate generated metadata

* fix(browser): reject lossy HAR member normalization

* test(browser): assert the advertised unsupported-profile outcome

* fix(browser): preserve JSON visitor nesting failure locations

* fix(browser): exclude explicitly sensitive native source ranges

---------

Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-10-08 07:53:41 +08:00

123 lines
3.6 KiB
TypeScript

import { createHash } from "node:crypto";
import { constants, type BigIntStats } from "node:fs";
import { lstat, open, type FileHandle } from "node:fs/promises";
import { ArtifactReaderFailure } from "./ArtifactReader.js";
/** Filesystem boundary for stable reads, including deterministic replacement probes. */
export interface StableArtifactFileSystem {
lstat(path: string): Promise<BigIntStats>;
open(path: string, flags: number): Promise<FileHandle>;
}
const FILE_SYSTEM: StableArtifactFileSystem = {
lstat: (path) => lstat(path, { bigint: true }),
open,
};
const afterValidation = async <T>(
path: string,
stage: string,
read: () => Promise<T>,
): Promise<T> => {
try {
return await read();
} catch (cause) {
if (
cause instanceof Error &&
"code" in cause &&
["ENOENT", "ENOTDIR", "ELOOP"].includes(String(cause.code))
)
throw new ArtifactReaderFailure(
"integrity",
`Artifact changed ${stage}: ${path}`,
{ cause },
);
throw cause;
}
};
/** Read one bounded regular file and reject replacement or in-place changes. */
export const readStableArtifact = async (
path: string,
maximumBytes: number,
signal?: AbortSignal,
fileSystem: StableArtifactFileSystem = FILE_SYSTEM,
): Promise<{ readonly bytes: Buffer; readonly sha256: string }> => {
signal?.throwIfAborted();
const before = await fileSystem.lstat(path);
if (!before.isFile() || before.isSymbolicLink())
throw new ArtifactReaderFailure(
"path",
`Expected a regular file without a symlink: ${path}`,
);
if (before.size > BigInt(maximumBytes))
throw new ArtifactReaderFailure(
"limit",
`Selected artifact exceeds ${String(maximumBytes)} bytes: ${path}`,
);
const file = await afterValidation(path, "before open", () =>
fileSystem.open(
path,
constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
),
);
try {
const initial = await file.stat({ bigint: true });
if (
!initial.isFile() ||
initial.dev !== before.dev ||
initial.ino !== before.ino
)
throw new ArtifactReaderFailure(
"integrity",
`Artifact changed before open: ${path}`,
);
const chunks: Buffer[] = [];
let count = 0;
for await (const chunk of file.createReadStream({
autoClose: false,
highWaterMark: 65536,
})) {
signal?.throwIfAborted();
const value: unknown = chunk;
if (!Buffer.isBuffer(value))
throw new ArtifactReaderFailure(
"format",
`Artifact stream did not return bytes: ${path}`,
);
const bytes = value;
count += bytes.length;
if (count > maximumBytes)
throw new ArtifactReaderFailure(
"limit",
`Selected artifact grew beyond its byte limit: ${path}`,
);
chunks.push(bytes);
}
const after = await file.stat({ bigint: true });
const current = await afterValidation(path, "during read", () =>
fileSystem.lstat(path),
);
if (
[after, current].some(
(stat) =>
!stat.isFile() ||
stat.dev !== initial.dev ||
stat.ino !== initial.ino ||
stat.size !== initial.size ||
stat.mtimeNs !== initial.mtimeNs ||
stat.ctimeNs !== initial.ctimeNs,
) ||
BigInt(count) !== initial.size
)
throw new ArtifactReaderFailure(
"integrity",
`Artifact changed during read: ${path}`,
);
const bytes = Buffer.concat(chunks, count);
return { bytes, sha256: createHash("sha256").update(bytes).digest("hex") };
} finally {
await file.close();
}
};