refactor(files): use caller paths for local evidence files

This commit is contained in:
morluto
2026-09-29 14:53:20 +08:00
parent 3f547eafa4
commit c34efca4cd
51 changed files with 289 additions and 936 deletions
+5 -24
View File
@@ -2,7 +2,6 @@ import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
import { err, ok } from "../domain/result.js";
import { traverseDirectory } from "./ReferenceSourceReaderEntries.js";
import {
type ReferenceSourceLimits,
type ReferenceSourceReaderOptions,
type ReferenceSourceRead,
type ReferenceSourceResult,
@@ -16,24 +15,16 @@ import {
export type {
ReferenceSourceEntry,
ReferenceSourceLimits,
ReferenceSourceRead,
ReferenceSourceReaderOptions,
} from "./ReferenceSourceReaderTypes.js";
const DEFAULT_LIMITS: ReferenceSourceLimits = {
maxBytes: 16 * 1024 * 1024,
maxEntries: 10_000,
maxDepth: 32,
maxPathBytes: 4_096,
};
const PATH_RACE_LIMITATION =
"Path identity is revalidated around operations; Node lacks portable descriptor-relative openat traversal, so a syscall-boundary pathname race remains.";
/** Read a bounded source tree without intentionally following symbolic links. */
/** Read a source tree without intentionally following symbolic links. */
export const readReferenceSource = async (
root: string,
limits: ReferenceSourceLimits = DEFAULT_LIMITS,
options: ReferenceSourceReaderOptions = {},
): Promise<ReferenceSourceResult<ReferenceSourceRead>> => {
if (!noFollowOpenSupported())
@@ -42,23 +33,19 @@ export const readReferenceSource = async (
code: "unsupported",
message: "Safe no-follow file opens are unavailable",
});
const prepared = await prepareRoot(root, limits, options.signal);
const prepared = await prepareRoot(root, options.signal);
if (!prepared.ok) return prepared;
const { canonicalRoot, rootIdentity } = prepared.value;
const state: TraversalState = {
root: canonicalRoot,
rootIdentity,
limits,
...(options.signal === undefined ? {} : { signal: options.signal }),
...(options.shouldExclude === undefined
? {}
: { shouldExclude: options.shouldExclude }),
entries: [],
pending: [{ path: canonicalRoot, depth: 0 }],
pending: [{ path: canonicalRoot }],
bytesRead: 0,
filesSeen: 0,
truncated: false,
stopReason: undefined,
};
const traversal = await traverse(state);
if (!traversal.ok) return traversal;
@@ -69,20 +56,14 @@ export const readReferenceSource = async (
root: canonicalRoot,
entries: state.entries,
bytesRead: state.bytesRead,
truncated: state.truncated,
limitations: [
PATH_RACE_LIMITATION,
...(state.stopReason === "entry-limit"
? ["Traversal stopped because the entry limit was reached."]
: []),
],
limitations: [PATH_RACE_LIMITATION],
});
};
const traverse = async (
state: TraversalState,
): Promise<ReferenceSourceResult<undefined>> => {
while (state.pending.length > 0 && state.stopReason === undefined) {
while (state.pending.length > 0) {
if (isAborted(state.signal))
return err({
tag: "reference-source-reader",
+2 -45
View File
@@ -81,7 +81,6 @@ export const traverseDirectory = async (
for (const name of names.value) {
const result = await processEntry(state, current, name, directories);
if (!result.ok) return result;
if (state.stopReason !== undefined) break;
}
directories.reverse();
state.pending.push(...directories);
@@ -145,14 +144,6 @@ const processEntry = async (
},
};
if (excluded.value) return { ok: true, value: undefined };
if (!reserveEntry(state)) return { ok: true, value: undefined };
if (Buffer.byteLength(path) > state.limits.maxPathBytes) {
state.entries.push(
entryFailure(path, "unknown", "limit", "Path exceeds maxPathBytes"),
);
state.truncated = true;
return { ok: true, value: undefined };
}
const metadata = await readMetadata(absolute);
if (!metadata.ok) {
state.entries.push(entryFailure(path, "unknown", "io", metadata.message));
@@ -170,15 +161,8 @@ const processEntry = async (
if (metadata.value.isSymbolicLink())
state.entries.push(await describeSymlink(state.root, absolute, path));
else if (metadata.value.isDirectory()) {
if (current.depth < state.limits.maxDepth) {
state.entries.push({ status: "read", kind: "directory", path });
directories.push({ path: absolute, depth: current.depth + 1 });
} else {
state.entries.push(
entryFailure(path, "directory", "limit", "Directory exceeds maxDepth"),
);
state.truncated = true;
}
state.entries.push({ status: "read", kind: "directory", path });
directories.push({ path: absolute });
} else if (!metadata.value.isFile())
state.entries.push(
entryFailure(
@@ -199,33 +183,16 @@ const processFileEntry = async (
path: string,
metadata: BigStats,
): Promise<void> => {
const remaining = state.limits.maxBytes - state.bytesRead;
if (metadata.size > BigInt(remaining)) {
state.entries.push(
entryFailure(
path,
"file",
"limit",
"File exceeds remaining maxBytes",
safeSize(metadata.size),
),
);
state.truncated = true;
return;
}
const result = await readStableFile({
root: state.root,
rootIdentity: state.rootIdentity,
absolute,
path,
expected: metadata,
remaining,
...(state.signal === undefined ? {} : { signal: state.signal }),
});
if (result.status === "read" && result.kind === "file")
state.bytesRead += result.bytes.byteLength;
else if (result.status === "failed" && result.code === "limit")
state.truncated = true;
state.entries.push(result);
};
@@ -291,13 +258,3 @@ const applyExclusion = (
return { ok: false };
}
};
const reserveEntry = (state: TraversalState): boolean => {
if (state.filesSeen < state.limits.maxEntries) {
state.filesSeen += 1;
return true;
}
state.truncated = true;
state.stopReason = "entry-limit";
return false;
};
+4 -30
View File
@@ -75,10 +75,9 @@ const prepareFileRead = async (
const readFileContents = async (request: {
readonly handle: FileHandle;
readonly path: string;
readonly remaining: number;
readonly signal?: AbortSignal;
}): Promise<FileContentsRead> => {
const { handle, path, remaining, signal } = request;
const { handle, path, signal } = request;
const chunks: Buffer[] = [];
let total = 0;
for (;;) {
@@ -93,20 +92,8 @@ const readFileContents = async (request: {
total,
),
};
const capacity = Math.min(READ_CHUNK_BYTES, remaining + 1 - total);
if (capacity <= 0)
return {
status: "failed",
entry: entryFailure(
path,
"file",
"limit",
"File exceeds remaining maxBytes",
total,
),
};
const chunk = Buffer.allocUnsafe(capacity);
const read = await handle.read(chunk, 0, capacity, null);
const chunk = Buffer.allocUnsafe(READ_CHUNK_BYTES);
const read = await handle.read(chunk, 0, chunk.byteLength, null);
if (isAborted(signal))
return {
status: "failed",
@@ -120,17 +107,6 @@ const readFileContents = async (request: {
};
if (read.bytesRead === 0) break;
total += read.bytesRead;
if (total > remaining)
return {
status: "failed",
entry: entryFailure(
path,
"file",
"limit",
"File exceeds remaining maxBytes",
total,
),
};
chunks.push(chunk.subarray(0, read.bytesRead));
}
return { status: "ok", chunks, total };
@@ -184,8 +160,7 @@ const finalizeFileRead = async (
export const readStableFile = async (
request: StableFileRequest,
): Promise<ReferenceSourceEntry> => {
const { root, rootIdentity, absolute, path, expected, remaining, signal } =
request;
const { root, rootIdentity, absolute, path, expected, signal } = request;
let handle: FileHandle | undefined;
try {
const parentBefore = await validateDirectory(
@@ -207,7 +182,6 @@ export const readStableFile = async (
const contents = await readFileContents({
handle,
path,
remaining,
...(signal === undefined ? {} : { signal }),
});
if (contents.status === "failed") return contents.entry;
+1 -21
View File
@@ -2,13 +2,6 @@ import { type BigIntStats } from "node:fs";
import { type Result } from "../domain/result.js";
export interface ReferenceSourceLimits {
readonly maxBytes: number;
readonly maxEntries: number;
readonly maxDepth: number;
readonly maxPathBytes: number;
}
export interface ReferenceSourceReaderOptions {
readonly signal?: AbortSignal;
readonly shouldExclude?: (path: string) => boolean;
@@ -18,7 +11,6 @@ export type ReferenceSourceFailureCode =
| "cancelled"
| "changed"
| "io"
| "limit"
| "symlink"
| "unsupported";
@@ -55,19 +47,13 @@ export interface ReferenceSourceRead {
readonly root: string;
readonly entries: readonly ReferenceSourceEntry[];
readonly bytesRead: number;
readonly truncated: boolean;
/** Node exposes no portable openat traversal; pathname identity is checked around each operation. */
readonly limitations: readonly string[];
}
export interface ReferenceSourceReaderError {
readonly tag: "reference-source-reader";
readonly code:
| "cancelled"
| "invalid-limits"
| "invalid-root"
| "io"
| "unsupported";
readonly code: "cancelled" | "invalid-root" | "io" | "unsupported";
readonly message: string;
}
@@ -75,21 +61,16 @@ export type BigStats = BigIntStats;
export type PendingDirectory = {
readonly path: string;
readonly depth: number;
};
export type TraversalState = {
readonly root: string;
readonly rootIdentity: BigStats;
readonly limits: ReferenceSourceLimits;
readonly signal?: AbortSignal;
readonly shouldExclude?: (path: string) => boolean;
readonly entries: ReferenceSourceEntry[];
readonly pending: PendingDirectory[];
bytesRead: number;
filesSeen: number;
truncated: boolean;
stopReason: "entry-limit" | undefined;
};
export type StableFileRequest = {
@@ -98,7 +79,6 @@ export type StableFileRequest = {
readonly absolute: string;
readonly path: string;
readonly expected: BigStats;
readonly remaining: number;
readonly signal?: AbortSignal;
};
@@ -7,7 +7,6 @@ import { isPathWithinRoot } from "../domain/localPath.js";
import {
type BigStats,
type ReferenceSourceFailureCode,
type ReferenceSourceLimits,
type ReferenceSourceResult,
} from "./ReferenceSourceReaderTypes.js";
@@ -24,11 +23,6 @@ export const sameFile = (left: BigStats, right: BigStats): boolean =>
export const isAborted = (signal?: AbortSignal): boolean =>
signal?.aborted === true;
const validLimits = (limits: ReferenceSourceLimits): boolean =>
Object.values(limits).every(
(value) => Number.isSafeInteger(value) && value > 0,
);
export const noFollowOpenSupported = (): boolean =>
Number.isSafeInteger(constants.O_NOFOLLOW) && constants.O_NOFOLLOW !== 0;
@@ -80,7 +74,6 @@ export const validateDirectory = async (
export const prepareRoot = async (
root: string,
limits: ReferenceSourceLimits,
signal?: AbortSignal,
): Promise<
ReferenceSourceResult<{
@@ -88,10 +81,6 @@ export const prepareRoot = async (
readonly rootIdentity: BigStats;
}>
> => {
if (!validLimits(limits))
return err(
failure("invalid-limits", "Reader limits must be positive integers"),
);
if (isAborted(signal)) return err(cancelled());
try {
const metadata = await bigLstat(root);