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 -8
View File
@@ -3,19 +3,17 @@ import {
serializeAnalysisSnapshot,
type AnalysisSnapshot,
} from "../domain/analysisSnapshot.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
import { err, ok, type Result } from "../domain/result.js";
import { readBoundedJson, writeBoundedText } from "./BoundedJsonFiles.js";
import { readJsonFile, writeTextFile } from "./JsonFiles.js";
type SnapshotFailure = EvidenceFileError | EvidenceIntegrityError;
/** Read and validate a bounded analysis snapshot inside an approved root. */
/** Read and validate an analysis snapshot from the caller's path. */
export const readAnalysisSnapshot = async (
path: string,
policy: EvidenceFilePolicy,
): Promise<Result<AnalysisSnapshot, SnapshotFailure>> => {
const loaded = await readBoundedJson(path, policy);
const loaded = await readJsonFile(path);
if (!loaded.ok) return loaded;
try {
return ok(parseAnalysisSnapshot(loaded.value));
@@ -26,12 +24,11 @@ export const readAnalysisSnapshot = async (
}
};
/** Atomically write a deterministic analysis snapshot inside an approved root. */
/** Atomically write a deterministic analysis snapshot to the caller's path. */
export const writeAnalysisSnapshot = async (
snapshot: AnalysisSnapshot,
path: string,
overwrite: boolean,
policy: EvidenceFilePolicy,
): Promise<
Result<{ readonly path: string; readonly bytes: number }, SnapshotFailure>
> => {
@@ -43,7 +40,7 @@ export const writeAnalysisSnapshot = async (
new EvidenceIntegrityError(snapshotValidationMessage(cause), { cause }),
);
}
return writeBoundedText(encoded, path, overwrite, policy);
return writeTextFile(encoded, path, overwrite);
};
const snapshotValidationMessage = (cause: unknown): string =>
+4 -46
View File
@@ -31,10 +31,6 @@ import { err, ok, type Result } from "../domain/result.js";
import type { AnalysisSnapshot } from "../domain/analysisSnapshot.js";
import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
import type { PermissionAuthority } from "./PermissionAuthority.js";
import {
authorizeFileReadWithDeferredWrite,
type DeferredFileWriteAuthorization,
} from "./DeferredFileAuthorization.js";
import {
REA_WORKFLOW_PROVIDER,
workflowAnalysisProfile,
@@ -155,31 +151,6 @@ const permissionAuthorityFor = (
? loadConfiguredPermissionAuthority(config)
: Promise.resolve(ok(supplied));
const authorizeSnapshotAccess = async (
authority: PermissionAuthority,
tool:
| NativeToolName
| ArtifactAnalysisOperation
| ManagedToolName
| DirectAnalysisTool,
snapshotPath: string | undefined,
): Promise<
Result<DeferredFileWriteAuthorization | undefined, AnalysisError>
> =>
snapshotPath === undefined
? ok(undefined)
: authorizeFileReadWithDeferredWrite(authority, {
path: snapshotPath,
readCapability: "snapshot_read",
writeCapability: "snapshot_write",
operation: tool,
});
const authorizeDeferredWrite = (
authorization: DeferredFileWriteAuthorization | undefined,
): Promise<Result<null, AnalysisError>> =>
authorization?.authorizeWrite() ?? Promise.resolve(ok(null));
const authorizeAnalysisRun = async (input: {
readonly config: AppConfig;
readonly suppliedAuthority: PermissionAuthority | undefined;
@@ -189,10 +160,7 @@ const authorizeAnalysisRun = async (input: {
| ManagedToolName
| DirectAnalysisTool;
readonly arguments: Readonly<Record<string, JsonValue>>;
readonly snapshotPath: string | undefined;
}): Promise<
Result<DeferredFileWriteAuthorization | undefined, AnalysisError>
> => {
}): Promise<Result<null, AnalysisError>> => {
const authority = await permissionAuthorityFor(
input.config,
input.suppliedAuthority,
@@ -204,11 +172,7 @@ const authorizeAnalysisRun = async (input: {
input.arguments,
);
if (!operation.ok) return operation;
return authorizeSnapshotAccess(
authority.value,
input.tool,
input.snapshotPath,
);
return ok(null);
};
const runAnalysis = async (
@@ -235,7 +199,6 @@ const runAnalysis = async (
suppliedAuthority: options.permissionAuthority,
tool,
arguments: arguments_,
snapshotPath,
});
if (!authorization.ok) return cliError(authorization.error);
const session = createBinarySession(config.value, logger);
@@ -243,7 +206,6 @@ const runAnalysis = async (
const prepared = await prepareSnapshot({
path,
snapshotPath,
policy: config.value.analysisSnapshotFilePolicy,
});
if (!prepared.ok) return cliError(prepared.error);
const { snapshot } = prepared.value;
@@ -272,8 +234,6 @@ const runAnalysis = async (
});
if (cached !== undefined) return cached;
}
const writable = await authorizeDeferredWrite(authorization.value);
if (!writable.ok) return cliError(writable.error);
const { output, evidence } = await executeAnalysisTool({
session,
openedTarget: opened.value,
@@ -290,7 +250,6 @@ const runAnalysis = async (
snapshot.value,
snapshotPath,
true,
config.value.analysisSnapshotFilePolicy,
);
if (!written.ok) return cliError(written.error);
}
@@ -386,14 +345,13 @@ const withProcessCancellation = async <Value>(
const prepareSnapshot = async (options: {
readonly path: string;
readonly snapshotPath: string | undefined;
readonly policy: Parameters<typeof readAnalysisSnapshot>[1];
}): Promise<
Result<{ readonly snapshot?: AnalysisSnapshot }, AnalysisError>
> => {
const { path, snapshotPath, policy } = options;
const { path, snapshotPath } = options;
if (snapshotPath === undefined || !(await fileExists(snapshotPath)))
return ok({});
const loaded = await readAnalysisSnapshot(snapshotPath, policy);
const loaded = await readAnalysisSnapshot(snapshotPath);
if (!loaded.ok) return loaded;
const target = await parseBinaryTarget(path);
if (!target.ok) return target;
+6 -12
View File
@@ -2,10 +2,7 @@ import {
EvidenceIntegrityError,
type AnalysisError,
} from "../domain/errors.js";
import type {
EvidenceFilePolicy,
EvidenceBundle,
} from "../domain/evidenceBundle.js";
import type { EvidenceBundle } from "../domain/evidenceBundle.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { err, ok, type Result } from "../domain/result.js";
@@ -19,9 +16,8 @@ import {
/** Validate and merge one bundle using the session Evidence ledger. */
export const importEvidenceBundleCommand = async (
path: string,
policy: EvidenceFilePolicy,
): Promise<Result<JsonValue, AnalysisError>> => {
const loaded = await readEvidenceBundle(path, policy);
const loaded = await readEvidenceBundle(path);
if (!loaded.ok) return loaded;
const ledger = createLedger();
const imported = ledger.import(loaded.value);
@@ -39,13 +35,12 @@ export const exportEvidenceBundleCommand = async (
sourcePath: string,
outputPath: string,
overwrite: boolean,
policy: EvidenceFilePolicy,
): Promise<Result<JsonValue, AnalysisError>> => {
const loaded = await readEvidenceBundle(sourcePath, policy);
const loaded = await readEvidenceBundle(sourcePath);
if (!loaded.ok) return loaded;
return projectWrite(
loaded.value,
await writeEvidenceBundle(loaded.value, outputPath, overwrite, policy),
await writeEvidenceBundle(loaded.value, outputPath, overwrite),
);
};
@@ -53,11 +48,10 @@ export const exportEvidenceBundleCommand = async (
export const compareEvidenceBundlesCommand = async (input: {
readonly leftPath: string;
readonly rightPath: string;
readonly policy: EvidenceFilePolicy;
}): Promise<Result<JsonValue, AnalysisError>> => {
const [left, right] = await Promise.all([
readEvidenceBundle(input.leftPath, input.policy),
readEvidenceBundle(input.rightPath, input.policy),
readEvidenceBundle(input.leftPath),
readEvidenceBundle(input.rightPath),
]);
if (!left.ok) return left;
if (!right.ok) return right;
+5 -12
View File
@@ -2,24 +2,20 @@ import {
parseEvidenceBundle,
serializeEvidenceBundle,
type EvidenceBundle,
type EvidenceFilePolicy,
} from "../domain/evidenceBundle.js";
import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
import { err, ok, type Result } from "../domain/result.js";
import { parseProcessCapture } from "../domain/processCapture.js";
import { readBoundedJson, writeBoundedText } from "./BoundedJsonFiles.js";
import { readJsonFile, writeTextFile } from "./JsonFiles.js";
type EvidenceReadFailure = EvidenceFileError | EvidenceIntegrityError;
type EvidenceWriteFailure = EvidenceFileError | EvidenceIntegrityError;
/** Read and validate a bounded evidence bundle inside an approved root. */
/** Read and validate an evidence bundle at the caller-supplied path. */
export const readEvidenceBundle = async (
path: string,
policy: EvidenceFilePolicy,
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> => {
if (policy.roots.length === 0)
return err(new EvidenceFileError("read", "disabled"));
const loaded = await readBoundedJson(path, policy);
const loaded = await readJsonFile(path);
if (!loaded.ok) return loaded;
try {
const bundle = parseEvidenceBundle(loaded.value);
@@ -37,20 +33,17 @@ export const readEvidenceBundle = async (
}
};
/** Atomically write deterministic evidence JSON inside an approved root. */
/** Atomically write deterministic evidence JSON at the caller-supplied path. */
export const writeEvidenceBundle = async (
bundle: EvidenceBundle,
path: string,
overwrite: boolean,
policy: EvidenceFilePolicy,
): Promise<
Result<
{ readonly path: string; readonly bytes: number },
EvidenceWriteFailure
>
> => {
if (policy.roots.length === 0)
return err(new EvidenceFileError("write", "disabled"));
let encoded: string;
try {
encoded = serializeEvidenceBundle(bundle);
@@ -61,5 +54,5 @@ export const writeEvidenceBundle = async (
}),
);
}
return writeBoundedText(encoded, path, overwrite, policy);
return writeTextFile(encoded, path, overwrite);
};
@@ -1,74 +1,45 @@
import { link, lstat, mkdtemp, open, realpath, rm } from "node:fs/promises";
import { link, lstat, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
import { basename, dirname, resolve } from "node:path";
import writeFileAtomic from "write-file-atomic";
import { isPathWithinRoot } from "../domain/localPath.js";
import type { EvidenceFilePolicy } from "../domain/evidenceBundle.js";
import { EvidenceFileError } from "../domain/errors.js";
import { isJsonWithinLimits } from "../domain/jsonLimits.js";
import { err, ok, type Result } from "../domain/result.js";
import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
/** Read bounded JSON data from a regular file beneath an approved root. */
export const readBoundedJson = async (
/** Read JSON data from a regular file at the caller-supplied path. */
export const readJsonFile = async (
path: string,
policy: EvidenceFilePolicy,
): Promise<Result<unknown, EvidenceFileError>> => {
if (policy.roots.length === 0)
return err(new EvidenceFileError("read", "disabled"));
try {
const canonicalPath = await realpath(resolve(path));
if (!(await isApproved(canonicalPath, policy.roots)))
return err(new EvidenceFileError("read", "outside-root"));
const stats = await lstat(canonicalPath);
if (!stats.isFile()) return err(new EvidenceFileError("read", "not-file"));
if (stats.size > policy.maxBytes)
return err(new EvidenceFileError("read", "too-large"));
const handle = await open(canonicalPath, "r");
let encoded: Buffer | undefined;
try {
encoded = await readBoundedFileBytes(handle, policy.maxBytes);
} finally {
await handle.close();
}
if (encoded === undefined)
return err(new EvidenceFileError("read", "too-large"));
const encoded = await readFile(canonicalPath);
let decoded: unknown;
try {
decoded = JSON.parse(encoded.toString("utf8"));
} catch (cause: unknown) {
return err(new EvidenceFileError("read", "invalid-json", { cause }));
}
return isJsonWithinLimits(decoded, policy)
? ok(decoded)
: err(new EvidenceFileError("read", "too-large"));
return ok(decoded);
} catch (cause: unknown) {
return err(new EvidenceFileError("read", "io", { cause }));
}
};
/** Atomically write bounded text to a regular file beneath an approved root. */
export const writeBoundedText = async (
/** Atomically write text to the caller-supplied path. */
export const writeTextFile = async (
encoded: string,
path: string,
overwrite: boolean,
policy: EvidenceFilePolicy,
): Promise<
Result<{ readonly path: string; readonly bytes: number }, EvidenceFileError>
> => {
if (policy.roots.length === 0)
return err(new EvidenceFileError("write", "disabled"));
const bytes = Buffer.byteLength(encoded, "utf8");
if (bytes > policy.maxBytes)
return err(new EvidenceFileError("write", "too-large"));
try {
const requestedPath = resolve(path);
const canonicalParent = await realpath(dirname(requestedPath));
const destination = resolve(canonicalParent, basename(requestedPath));
if (!(await isApproved(destination, policy.roots)))
return err(new EvidenceFileError("write", "outside-root"));
const existing = await lstat(destination).catch((cause: unknown) => {
if (fileErrorCode(cause) === "ENOENT") return undefined;
throw cause;
@@ -114,18 +85,6 @@ const publishNewFile = async (
}
};
const isApproved = async (
candidate: string,
roots: readonly string[],
): Promise<boolean> => {
for (const root of await canonicalizeConfiguredRoots(
roots.map((configuredRoot) => resolve(configuredRoot)),
)) {
if (isPathWithinRoot(root, candidate)) return true;
}
return false;
};
const fileErrorCode = (cause: unknown): unknown =>
typeof cause === "object" && cause !== null && "code" in cause
? cause.code
+7 -16
View File
@@ -137,18 +137,14 @@ const deriveInventoryState = (
return "complete";
};
const sortAndLimit = (
const sortExclusions = (
exclusions: HistoricalSourceGraphInput["exclusions"],
maxExclusions: number,
): HistoricalSourceGraphInput["exclusions"] => {
const sorted = [...exclusions].sort((left, right) => {
): HistoricalSourceGraphInput["exclusions"] =>
[...exclusions].sort((left, right) => {
const byPath = compareUnicodeCodePoints(left.path, right.path);
if (byPath !== 0) return byPath;
return compareUnicodeCodePoints(left.reason, right.reason);
});
if (sorted.length <= maxExclusions) return sorted;
return sorted.slice(0, maxExclusions);
};
/**
* Import a reference source directory into a committed historical source graph.
@@ -163,7 +159,7 @@ export const importReferenceSource = async (
if (isAborted(options.signal)) return err(cancelled());
const prepared = await prepareReferenceSourceImport(options);
if (!prepared.ok) return prepared;
const { ignored, limits, root, secrets } = prepared.value;
const { ignored, root, secrets } = prepared.value;
if (isAborted(options.signal)) return err(cancelled());
const exclusions: HistoricalSourceGraphInput["exclusions"] = [];
@@ -180,7 +176,7 @@ export const importReferenceSource = async (
};
const [readResult, vcs] = await Promise.all([
readReferenceSource(root, limits, {
readReferenceSource(root, {
...(options.signal === undefined ? {} : { signal: options.signal }),
shouldExclude,
}),
@@ -190,12 +186,7 @@ export const importReferenceSource = async (
if (!readResult.ok) {
const error = readResult.error;
if (error.code === "cancelled") return err(cancelled());
return err(
failure(
error.code === "invalid-limits" ? "invalid-limits" : "io",
error.message,
),
);
return err(failure("io", error.message));
}
if (isAborted(options.signal)) return err(cancelled());
@@ -218,7 +209,7 @@ export const importReferenceSource = async (
const sortedEntries = [...entries].sort((left, right) =>
compareUnicodeCodePoints(left.path, right.path),
);
const sortedExclusions = sortAndLimit(exclusions, limits.maxEntries);
const sortedExclusions = sortExclusions(exclusions);
const sortedLimitations = [...limitations].sort(compareUnicodeCodePoints);
const input: HistoricalSourceGraphInput = {
@@ -26,8 +26,6 @@ export const projectReferenceSourceEntryFailure = (
): string => {
if (entry.code === "cancelled")
return "This entry was not read because the import was cancelled. Start the import again when ready.";
if (entry.code === "limit")
return "This entry was not read because an import limit was reached. Import a smaller directory or raise the configured limits.";
if (entry.code === "unsupported")
return "This entry cannot be read safely on this system. Exclude it or import the directory on a supported system.";
if (entry.kind === "directory")
@@ -50,7 +48,7 @@ const failedEntry = (
path: entry.path,
kind: "directory",
classifications,
tree_state: entry.code === "limit" ? "partial" : "unreadable",
tree_state: "unreadable",
limitations: [limitation],
};
if (entry.kind === "symlink")
@@ -69,7 +67,7 @@ const failedEntry = (
size: entry.size ?? null,
language: null,
classifications: entry.kind === "file" ? classifications : ["unknown"],
content_state: entry.code === "limit" ? "too-large" : "unreadable",
content_state: "unreadable",
limitations: [limitation],
};
};
+5 -53
View File
@@ -4,20 +4,15 @@ import { join, resolve } from "node:path";
import ignore from "ignore";
import { err, ok, type Result } from "../domain/result.js";
import type { ReferenceSourceLimits } from "../reference/ReferenceSourceReader.js";
import { isPathWithinRoot } from "../domain/localPath.js";
import {
DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS,
DEFAULT_REFERENCE_SOURCE_LIMITS,
type ReferenceSourceImportError,
type ReferenceSourceImportOptions,
} from "./ReferenceSourceImportTypes.js";
import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
/** Validated, authorized inputs ready for filesystem traversal. */
/** Validated inputs ready for filesystem traversal. */
export interface PreparedReferenceSourceImport {
readonly root: string;
readonly limits: ReferenceSourceLimits;
readonly ignored: ReturnType<typeof ignore>;
readonly secrets: ReturnType<typeof ignore>;
}
@@ -31,52 +26,16 @@ const failure = (
message,
});
const validLimits = (limits: ReferenceSourceLimits): boolean =>
Object.values(limits).every(
(value) => Number.isSafeInteger(value) && value > 0,
);
const maximumLimits = (
options: ReferenceSourceImportOptions,
): ReferenceSourceLimits => ({
maxBytes: options.policy.maxBytes,
maxEntries: options.policy.maxEntries,
maxDepth: options.policy.maxDepth,
maxPathBytes: options.policy.maxPathBytes,
});
const clampLimits = (
requested: ReferenceSourceLimits,
maximum: ReferenceSourceLimits,
): ReferenceSourceLimits => ({
maxBytes: Math.min(requested.maxBytes, maximum.maxBytes),
maxEntries: Math.min(requested.maxEntries, maximum.maxEntries),
maxDepth: Math.min(requested.maxDepth, maximum.maxDepth),
maxPathBytes: Math.min(requested.maxPathBytes, maximum.maxPathBytes),
});
const authorizeRoot = async (
const resolveRoot = async (
requestedRoot: string,
approvedRoots: readonly string[],
): Promise<Result<string, ReferenceSourceImportError>> => {
if (approvedRoots.length === 0)
return err(failure("policy", "No approved reference source roots"));
try {
if (!(await stat(requestedRoot)).isDirectory())
return err(
failure("invalid-root", "Reference source root is not a directory"),
);
const canonicalRoot = await realpath(resolve(requestedRoot));
const canonicalApprovedRoots = await canonicalizeConfiguredRoots(
approvedRoots.map((approvedRoot) => resolve(approvedRoot)),
);
for (const canonicalApproved of canonicalApprovedRoots) {
if (isPathWithinRoot(canonicalApproved, canonicalRoot))
return ok(canonicalRoot);
}
return err(
failure("policy", "Reference source root is outside approved roots"),
);
return ok(canonicalRoot);
} catch {
return err(
failure("invalid-root", "Reference source root could not be resolved"),
@@ -102,23 +61,16 @@ const buildIgnored = async (
return ignored;
};
/** Validate limits, authorize root, and build non-executing path filters. */
/** Resolve the caller-selected directory and build path filters. */
export const prepareReferenceSourceImport = async (
options: ReferenceSourceImportOptions,
): Promise<
Result<PreparedReferenceSourceImport, ReferenceSourceImportError>
> => {
const requested = options.limits ?? DEFAULT_REFERENCE_SOURCE_LIMITS;
const maximum = maximumLimits(options);
if (!validLimits(requested) || !validLimits(maximum))
return err(
failure("invalid-limits", "Import limits must be positive integers"),
);
const root = await authorizeRoot(options.root, options.policy.roots);
const root = await resolveRoot(options.root);
if (!root.ok) return root;
return ok({
root: root.value,
limits: clampLimits(requested, maximum),
ignored: await buildIgnored(root.value, options.excludePaths ?? []),
secrets: ignore().add([...options.policy.secretPatterns]),
});
+2 -29
View File
@@ -1,16 +1,9 @@
import type { ReferenceSourcePolicy } from "../domain/referenceSourcePolicy.js";
import type { ReferenceSourceLimits } from "../reference/ReferenceSourceReader.js";
/** Typed expected failure returned by historical-source imports. */
export interface ReferenceSourceImportError {
readonly tag: "reference-source-import";
readonly code:
| "cancelled"
| "invalid-limits"
| "invalid-root"
| "io"
| "parse"
| "policy";
readonly code: "cancelled" | "invalid-root" | "io" | "parse";
readonly message: string;
}
@@ -24,24 +17,12 @@ export const projectReferenceSourceImportError = (
message:
"Reference source import was cancelled. Start it again when ready.",
};
if (error.code === "invalid-limits")
return {
category: "invalid_input",
message:
"Reference source limits are invalid. Use positive integer limits, then try again.",
};
if (error.code === "invalid-root")
return {
category: "invalid_input",
message:
"Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
};
if (error.code === "policy")
return {
category: "permission_required",
message:
"Reference source directory is not approved. Add its directory to `REA_REFERENCE_ROOTS_JSON`, restart REA, then try again.",
};
if (error.code === "io")
return {
category: "execution_failure",
@@ -55,10 +36,9 @@ export const projectReferenceSourceImportError = (
};
};
/** Bounded import request paired with mandatory operator policy. */
/** Import a caller-selected local source tree as historical reference. */
export interface ReferenceSourceImportOptions {
readonly root: string;
readonly limits?: ReferenceSourceLimits;
readonly signal?: AbortSignal;
readonly caller: string;
readonly policy: ReferenceSourcePolicy;
@@ -79,12 +59,5 @@ export const DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS = [
"*.log",
] as const;
export const DEFAULT_REFERENCE_SOURCE_LIMITS: ReferenceSourceLimits = {
maxBytes: 16 * 1024 * 1024,
maxEntries: 10_000,
maxDepth: 32,
maxPathBytes: 4_096,
};
export const PARSEABLE_REFERENCE_SOURCE_LANGUAGES: ReadonlySet<string> =
new Set(["JavaScript", "TypeScript", "JSX", "TSX"]);