rea-agents 1.1.0 → 1.3.0

package/dist/application/AnalysisSnapshotCache.js

@@ -0,0 +1,131 @@
+import { EvidenceIntegrityError, NoBinaryOpenError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { analysisQueryId, createAnalysisSnapshotEntry, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
+import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+const STATEFUL_OPERATIONS = new Set([
+    "health",
+    "current_address",
+    "current_procedure",
+    "current_document",
+    "goto_address",
+    "list_documents",
+    "set_current_document",
+]);
+const CURSOR_DEFAULT_OPERATIONS = new Set([
+    "address_name",
+    "comment",
+    "inline_comment",
+    "next_address",
+    "prev_address",
+    "xrefs",
+]);
+const DOCUMENT_SCOPED_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name).filter((name) => name !== "current_document" &&
+    name !== "list_documents" &&
+    name !== "set_current_document"));
+/** Whether an operation is immutable and independent of provider UI state. */
+export const isSnapshotCacheable = (operation, descriptor, parameters) => !STATEFUL_OPERATIONS.has(operation) &&
+    (!DOCUMENT_SCOPED_OPERATIONS.has(operation) ||
+        typeof parameters.document === "string") &&
+    (!CURSOR_DEFAULT_OPERATIONS.has(operation) ||
+        typeof parameters.address === "string") &&
+    descriptor?.effects.mutatesArtifact === false &&
+    descriptor.effects.mayWriteFilesystem === false &&
+    descriptor.effects.changesPermissions === false;
+/** Bounded in-memory cache for one immutable binary identity. */
+export class AnalysisSnapshotCache {
+    #entries = new Map();
+    #target;
+    /** Whether staged entries belong to the supplied binary. */
+    matches(target) {
+        return (this.#target === undefined || snapshotMatchesTarget(this.#target, target));
+    }
+    /** Replace cache state when the active binary identity changes. */
+    select(target) {
+        if (!this.matches(target))
+            this.#entries.clear();
+        this.#target = snapshotTarget(target);
+    }
+    /** Merge already-validated entries and return the new-entry count. */
+    stage(snapshot) {
+        if (this.#target !== undefined &&
+            (this.#target.sha256 !== snapshot.target.sha256 ||
+                this.#target.format !== snapshot.target.format ||
+                this.#target.architecture !== snapshot.target.architecture))
+            this.#entries.clear();
+        this.#target = snapshot.target;
+        let imported = 0;
+        for (const entry of snapshot.entries) {
+            if (!this.#entries.has(entry.query_id))
+                imported += 1;
+            this.#entries.set(entry.query_id, entry);
+        }
+        return imported;
+    }
+    /** Build a complete snapshot for an active target. */
+    export(target, evidenceBundle) {
+        if (target === undefined)
+            return err(new NoBinaryOpenError());
+        return ok({
+            snapshot_version: 1,
+            target: snapshotTarget(target),
+            entries: this.entries(),
+            evidence_bundle: evidenceBundle,
+        });
+    }
+    /** Validate target identity, merge evidence atomically, then stage entries. */
+    import(snapshot, active, mergeEvidence) {
+        if (active !== undefined && !snapshotMatchesTarget(snapshot.target, active))
+            return err(new EvidenceIntegrityError("Analysis snapshot target does not match the active binary"));
+        const importedEvidence = mergeEvidence(snapshot.evidence_bundle);
+        return importedEvidence.ok ? ok(this.stage(snapshot)) : importedEvidence;
+    }
+    /** Return canonical entries for persistence. */
+    entries() {
+        return [...this.#entries.values()].sort((left, right) => left.query_id.localeCompare(right.query_id));
+    }
+    /** Replay an exact provider-specific query, marking its cached provenance. */
+    lookup(target, operation, parameters, provider) {
+        const queryId = analysisQueryId(snapshotTarget(target), operation, parameters, provider);
+        const cached = this.#entries.get(queryId);
+        if (cached === undefined)
+            return undefined;
+        const subject = cached.execution.subject;
+        return {
+            result: cached.execution.result,
+            rawResult: cached.execution.raw_result,
+            provider: cached.execution.provider,
+            limitations: [
+                ...cached.execution.limitations,
+                "Loaded from a local REA analysis snapshot; this call did not re-run the provider.",
+            ],
+            locations: cached.execution.locations,
+            subject: subject === null
+                ? null
+                : subject.architecture === null
+                    ? {
+                        path: subject.path,
+                        sha256: subject.sha256,
+                        format: subject.format,
+                    }
+                    : {
+                        path: subject.path,
+                        sha256: subject.sha256,
+                        format: subject.format,
+                        architecture: subject.architecture,
+                    },
+        };
+    }
+    /** Record one successful immutable call unless the cache is full. */
+    record(target, operation, parameters, execution) {
+        if (this.#entries.size >= 10_000)
+            return;
+        this.select(target);
+        const entry = createAnalysisSnapshotEntry(snapshotTarget(target), operation, parameters, execution);
+        this.#entries.set(entry.query_id, entry);
+    }
+    /** Forget all target-bound entries. */
+    clear() {
+        this.#entries.clear();
+        this.#target = undefined;
+    }
+}

package/dist/application/AnalysisSnapshotFiles.js

@@ -0,0 +1,31 @@
+import { parseAnalysisSnapshot, serializeAnalysisSnapshot, } from "../domain/analysisSnapshot.js";
+import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { readBoundedJson, writeBoundedText } from "./BoundedJsonFiles.js";
+/** Read and validate a bounded analysis snapshot inside an approved root. */
+export const readAnalysisSnapshot = async (path, policy) => {
+    const loaded = await readBoundedJson(path, policy);
+    if (!loaded.ok)
+        return loaded;
+    try {
+        return ok(parseAnalysisSnapshot(loaded.value));
+    }
+    catch (cause) {
+        return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
+            cause,
+        }));
+    }
+};
+/** Atomically write a deterministic analysis snapshot inside an approved root. */
+export const writeAnalysisSnapshot = async (snapshot, path, overwrite, policy) => {
+    let encoded;
+    try {
+        encoded = serializeAnalysisSnapshot(snapshot);
+    }
+    catch (cause) {
+        return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
+            cause,
+        }));
+    }
+    return writeBoundedText(encoded, path, overwrite, policy);
+};

package/dist/application/ArtifactInventory.js

@@ -7,24 +7,33 @@ import { ArtifactReaderFailure, } from "../artifacts/ArtifactReader.js";
 import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
 import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";
 import { MachOSliceArtifactReader } from "../artifacts/MachOSliceArtifactReader.js";
+import { NativeDmgArtifactReader } from "../artifacts/NativeDmgArtifactReader.js";
 import { streamChunkToBuffer } from "../artifacts/StreamBytes.js";
 import { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
 import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
+const NATIVE_MOUNT_DISABLED = {
+    nativeMountApproved: false,
+    nativeMountEnabled: false,
+};
 /** Inventory one local artifact without extracting or mounting it. */
-export const inventoryArtifact = async (inputPath, limits, page, signal) => {
-    const snapshot = await scanArtifactInventory(inputPath, limits, signal);
+export const inventoryArtifact = async (inputPath, limits, page, options = {}) => {
+    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED);
     return paginateArtifactInventory(snapshot, page);
 };
 /** Scan an artifact once and retain the complete immutable graph for projection. */
-export const scanArtifactInventory = async (inputPath, limits, signal) => {
+export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
     abortIfNeeded(signal);
     const path = await realpath(inputPath);
+    return scanCanonicalArtifactInventory(path, limits, signal, nativeMount);
+};
+/** Scan one already-canonical artifact path without resolving it again. */
+export const scanCanonicalArtifactInventory = async (path, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
     const metadata = await lstat(path);
     const rootFormat = await classifyRoot(path, metadata.isDirectory());
     const rootDigest = metadata.isDirectory()
         ? null
         : await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);
-    const reader = await createReader(path, rootFormat);
+    const reader = await createReader(path, rootFormat, nativeMount, signal);
     try {
         const { nodes, occurrences } = await scanReader(reader, limits, signal);
         materializeDirectoryNodes(occurrences, nodes);
@@ -104,7 +113,7 @@ const inventoryLimitations = (format, reader) => {
         return ["Universal Mach-O slices require the native macOS lipo adapter."];
     return ["Artifact has no child container entries."];
 };
-const createReader = async (path, format) => {
+const createReader = async (path, format, nativeMount, signal) => {
     switch (format) {
         case "directory":
             return new DirectoryArtifactReader(path);
@@ -118,57 +127,88 @@ const createReader = async (path, format) => {
             return process.platform === "darwin"
                 ? new MachOSliceArtifactReader(path)
                 : undefined;
+        case "dmg":
+            if (!nativeMount.nativeMountApproved)
+                return undefined;
+            if (!nativeMount.nativeMountEnabled)
+                throw new ArtifactReaderFailure("unavailable", "Native DMG mounting is disabled by operator policy");
+            return NativeDmgArtifactReader.create(path, signal);
         default:
             return undefined;
     }
 };
+const visitNestedAsar = async (adapterKey, logicalPath, visit) => {
+    const nested = new AsarArtifactReader(adapterKey);
+    try {
+        await visit(nested, logicalPath);
+    }
+    finally {
+        await nested.close();
+    }
+};
+const isExpandableAsar = (entry, logicalPath) => entry.kind === "file" &&
+    logicalPath.toLowerCase().endsWith(".asar") &&
+    entry.adapterKey.startsWith("/");
+const emptyScan = () => ({ nodes: new Map(), occurrences: [] });
 const scanReader = async (reader, limits, signal) => {
-    const nodes = new Map();
-    const occurrences = [];
+    const { nodes, occurrences } = emptyScan();
     if (reader === undefined)
         return { nodes, occurrences };
     const occurrenceByPath = new Map();
     const registry = new ArtifactPathRegistry();
     let totalBytes = 0;
-    for await (const entry of reader.entries(signal)) {
-        if (occurrences.length >= limits.maxEntries)
-            throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded");
-        const logicalPath = normalizeArtifactPath(entry.path, limits);
-        registry.add(logicalPath, entry.kind);
-        preflightEntry(entry, limits);
-        const parent = nearestParent(logicalPath, occurrenceByPath);
-        const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
-        if ((entry.kind === "file" || entry.kind === "slice") && !entry.encrypted) {
-            const remainingBytes = limits.maxTotalBytes - totalBytes;
-            if (remainingBytes <= 0)
-                throw new ArtifactReaderFailure("limit", "Artifact total byte limit exceeded");
-            if (entry.declaredSize !== null && entry.declaredSize > remainingBytes)
-                throw new ArtifactReaderFailure("limit", "Declared artifact bytes exceed remaining cumulative limit");
-            const digest = await hashReadable(await reader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
-            totalBytes += digest.bytes;
-            if (entry.declaredSha256 !== null &&
-                entry.declaredSha256 !== digest.sha256)
-                throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`);
-            if (totalBytes > limits.maxTotalBytes)
-                throw new ArtifactReaderFailure("limit", "Artifact total byte limit exceeded");
-            const classified = entry.kind === "slice"
-                ? { kind: "universal-slice", format: "mach-o" }
-                : classifyArtifactContent(logicalPath, digest.prefix);
-            const node = createArtifactNode({
-                sha256: digest.sha256,
-                size: digest.bytes,
-                kind: classified.kind,
-                format: classified.format,
-                executable: entry.executable,
-                contentState: "embedded",
+    const digestEntry = async (currentReader, entry, logicalPath) => {
+        if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
+            return undefined;
+        const remainingBytes = limits.maxTotalBytes - totalBytes;
+        if (remainingBytes <= 0)
+            throw new ArtifactReaderFailure("limit", "Artifact total byte limit exceeded");
+        if (entry.declaredSize !== null && entry.declaredSize > remainingBytes)
+            throw new ArtifactReaderFailure("limit", "Declared artifact bytes exceed remaining cumulative limit");
+        const digest = await hashReadable(await currentReader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
+        totalBytes += digest.bytes;
+        if (entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256)
+            throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
+                logicalPath,
+                declaredSha256: entry.declaredSha256,
+                calculatedSha256: digest.sha256,
+                unpacked: entry.unpacked,
             });
-            nodes.set(node.artifact_id, node);
-            occurrence.artifact_id = node.artifact_id;
-            occurrence.hash_status = "verified";
+        const classified = entry.kind === "slice"
+            ? { kind: "universal-slice", format: "mach-o" }
+            : classifyArtifactContent(logicalPath, digest.prefix);
+        return createArtifactNode({
+            sha256: digest.sha256,
+            size: digest.bytes,
+            kind: classified.kind,
+            format: classified.format,
+            executable: entry.executable,
+            contentState: "embedded",
+        });
+    };
+    const visit = async (currentReader, prefix) => {
+        for await (const entry of currentReader.entries(signal)) {
+            if (occurrences.length >= limits.maxEntries)
+                throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded");
+            const logicalPath = normalizeArtifactPath(prefix.length === 0 ? entry.path : `${prefix}/${entry.path}`, limits);
+            const expandableAsar = isExpandableAsar(entry, logicalPath);
+            registry.add(logicalPath, expandableAsar ? "directory" : entry.kind);
+            preflightEntry(entry, limits);
+            const parent = nearestParent(logicalPath, occurrenceByPath);
+            const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
+            const node = await digestEntry(currentReader, entry, logicalPath);
+            if (node !== undefined) {
+                nodes.set(node.artifact_id, node);
+                occurrence.artifact_id = node.artifact_id;
+                occurrence.hash_status = "verified";
+            }
+            occurrences.push(occurrence);
+            occurrenceByPath.set(logicalPath, occurrence);
+            if (expandableAsar)
+                await visitNestedAsar(entry.adapterKey, logicalPath, visit);
         }
-        occurrences.push(occurrence);
-        occurrenceByPath.set(logicalPath, occurrence);
-    }
+    };
+    await visit(reader, "");
     return { nodes, occurrences };
 };
 const classifyRoot = async (path, directory) => {

package/dist/application/AuthorizedArtifactInventory.js

@@ -0,0 +1,16 @@
+import { realpath } from "node:fs/promises";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
+import { scanCanonicalArtifactInventory, } from "./ArtifactInventory.js";
+/** Resolve, authorize, and scan one artifact without a second path resolution. */
+export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, signal) => {
+    if (roots.length === 0)
+        throw new ArtifactReaderFailure("path", "Artifact input roots are disabled");
+    const [path, approved] = await Promise.all([
+        realpath(inputPath),
+        Promise.all(roots.map(async (root) => realpath(root))),
+    ]);
+    if (!approved.some((root) => withinRoot(root, path)))
+        throw new ArtifactReaderFailure("path", "Artifact path is outside approved input roots");
+    return scanCanonicalArtifactInventory(path, limits, signal);
+};

package/dist/application/BinarySession.js

@@ -2,15 +2,14 @@ import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { AnalysisCapabilityUnavailableError, EvidenceIntegrityError, EvidenceLimitError, AnalysisCancelledError, NoBinaryOpenError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { createEvidence } from "../domain/evidence.js";
+import { evidenceBundleForTarget } from "../domain/evidenceBundle.js";
 import { EvidenceLedger } from "./EvidenceLedger.js";
 import { UnknownRegistryError } from "../domain/errors.js";
 import { enhancedToolNameSchema } from "../contracts/enhancedInputs.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
-const REGISTRY_PROVIDER = {
-    id: "rea-unknown-registry",
-    name: "REA residual unknown registry",
-    version: "1",
-};
+import { snapshotMatchesTarget } from "../domain/analysisSnapshot.js";
+import { AnalysisSnapshotCache, isSnapshotCacheable, } from "./AnalysisSnapshotCache.js";
+import { UNKNOWN_REGISTRY_PROVIDER, unknownEvidenceLinks, unknownMutationEvidence, } from "./UnknownEvidence.js";
 const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
@@ -32,8 +31,12 @@ export class BinarySession {
         maxRecords: 10_000,
         maxBytes: 64 * 1024 * 1024,
     });
-    constructor(provider) {
+    #snapshot = new AnalysisSnapshotCache();
+    #snapshotsEnabled;
+    #snapshotInvalidated = false;
+    constructor(provider, options = {}) {
         this.provider = provider;
+        this.#snapshotsEnabled = options.snapshotsEnabled ?? true;
         this.#createClient =
             typeof provider === "function"
                 ? provider
@@ -90,6 +93,23 @@ export class BinarySession {
     importEvidenceBundle(bundle) {
         return this.#evidence.import(bundle);
     }
+    /** Export immutable cached calls and session evidence for the active target. */
+    exportAnalysisSnapshot() {
+        if (!this.#snapshotsEnabled)
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable with custom Hopper loader arguments"));
+        if (this.#snapshotInvalidated)
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable after analysis metadata mutations"));
+        const target = this.#active?.target;
+        return this.#snapshot.export(target, target === undefined
+            ? this.#evidence.export()
+            : evidenceBundleForTarget(this.#evidence.export(), target.sha256));
+    }
+    /** Stage validated cached calls for an identical binary and merge its evidence. */
+    importAnalysisSnapshot(snapshot) {
+        if (!this.#snapshotsEnabled)
+            return err(new EvidenceIntegrityError("Analysis snapshots are unavailable with custom Hopper loader arguments"));
+        return this.#snapshot.import(snapshot, this.#active?.target, (bundle) => this.#evidence.import(bundle));
+    }
     /** Create an approved residual unknown and immutable mutation evidence. */
     recordUnknown(input) {
         const evidence = unknownMutationEvidence(this.#active?.target, input);
@@ -101,7 +121,7 @@ export class BinarySession {
     }
     /** Update one unknown using compare-and-swap revision semantics. */
     updateUnknown(input) {
-        const evidence = createEvidence(this.#active?.target, REGISTRY_PROVIDER, {
+        const evidence = createEvidence(this.#active?.target, UNKNOWN_REGISTRY_PROVIDER, {
             predicateType: "rea.residual-unknown-mutation/v1",
             operation: "update_unknown",
             parameters: {
@@ -137,10 +157,21 @@ export class BinarySession {
             const parsed = await parseBinaryTarget(path, process.cwd(), process.arch, options.targetKind);
             if (!parsed.ok)
                 return parsed;
+            if (options.snapshot !== undefined &&
+                !snapshotMatchesTarget(options.snapshot.target, parsed.value))
+                return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
+            if (this.#active === undefined && !this.#snapshot.matches(parsed.value))
+                return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
-            if (this.#active?.target.path === parsed.value.path)
+            if (this.#active?.target.path === parsed.value.path) {
+                if (options.snapshot !== undefined) {
+                    const imported = this.importAnalysisSnapshot(options.snapshot);
+                    if (!imported.ok)
+                        return imported;
+                }
                 return ok(parsed.value);
+            }
             await this.#drainCalls();
             const previous = this.#active;
             this.#active = undefined;
@@ -158,6 +189,17 @@ export class BinarySession {
                 return err(new AnalysisCancelledError("open_binary"));
             }
             this.#active = { target: parsed.value, client };
+            this.#snapshot.select(parsed.value);
+            if (options.snapshot !== undefined) {
+                const imported = this.importAnalysisSnapshot(options.snapshot);
+                if (!imported.ok) {
+                    this.#active = undefined;
+                    await client.close();
+                    await this.#restore(previous);
+                    return imported;
+                }
+            }
+            this.#snapshotInvalidated = false;
             return ok(parsed.value);
         });
     }
@@ -169,6 +211,8 @@ export class BinarySession {
             await this.#drainCalls();
             await previous?.client.close();
             this.#evidence.clear();
+            this.#snapshot.clear();
+            this.#snapshotInvalidated = false;
             return ok(null);
         });
     }
@@ -250,10 +294,23 @@ export class BinarySession {
         const active = this.#active;
         if (active === undefined)
             return err(new NoBinaryOpenError());
+        const cacheable = isSnapshotCacheable(name, capability, arguments_);
+        const cached = cacheable
+            ? this.#snapshot.lookup(active.target, name, arguments_, capability.provider)
+            : undefined;
+        if (cached !== undefined)
+            return ok(cached);
         const call = active.client.execute(name, arguments_, options);
         this.#calls.add(call);
         try {
-            return await call;
+            const result = await call;
+            if (result.ok && cacheable)
+                this.#snapshot.record(active.target, name, arguments_, result.value);
+            else if (result.ok && capability?.effects.mutatesArtifact === true) {
+                this.#snapshot.clear();
+                this.#snapshotInvalidated = true;
+            }
+            return result;
         }
         finally {
             this.#calls.delete(call);
@@ -303,31 +360,4 @@ export class BinarySession {
         });
     }
 }
-const unknownMutationEvidence = (target, input) => createEvidence(target, REGISTRY_PROVIDER, {
-    predicateType: "rea.residual-unknown-mutation/v1",
-    operation: "record_unknown",
-    parameters: {
-        domain: input.domain,
-        severity: input.severity,
-    },
-    result: {
-        action: "record",
-        question: input.question,
-        required_authority: input.required_authority,
-        required_confidence: input.required_confidence,
-    },
-    confidence: "derived",
-    authority: "analyst-inference",
-    evidenceLinks: unknownEvidenceLinks(input),
-    limitations: [
-        "Registry mutation evidence records analyst intent, not proof of the answer.",
-    ],
-});
-const unknownEvidenceLinks = (input) => [
-    ...input.supporting_evidence_ids,
-    ...input.contradicting_evidence_ids,
-    ...("resolution" in input && input.resolution !== null
-        ? input.resolution.evidence_ids
-        : []),
-].filter((id, index, values) => values.indexOf(id) === index);
 const isAborted = (signal) => signal?.aborted === true;

package/dist/application/BinarySessionPort.js

@@ -0,0 +1 @@
+export {};

package/dist/application/BoundedJsonFiles.js

@@ -0,0 +1,109 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { EvidenceFileError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Read bounded JSON data from a regular file beneath an approved root. */
+export const readBoundedJson = async (path, policy) => {
+    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 encoded = await readFile(canonicalPath);
+        if (encoded.byteLength > policy.maxBytes)
+            return err(new EvidenceFileError("read", "too-large"));
+        let decoded;
+        try {
+            decoded = JSON.parse(encoded.toString("utf8"));
+        }
+        catch (cause) {
+            return err(new EvidenceFileError("read", "invalid-json", { cause }));
+        }
+        const limits = validateJsonLimits(decoded, policy);
+        return limits.ok ? ok(decoded) : limits;
+    }
+    catch (cause) {
+        return err(new EvidenceFileError("read", "io", { cause }));
+    }
+};
+/** Atomically write bounded text to a regular file beneath an approved root. */
+export const writeBoundedText = async (encoded, path, overwrite, policy) => {
+    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) => {
+            if (isFileNotFound(cause))
+                return undefined;
+            throw cause;
+        });
+        if (existing !== undefined) {
+            if (!overwrite)
+                return err(new EvidenceFileError("write", "exists"));
+            if (!existing.isFile() || existing.isSymbolicLink())
+                return err(new EvidenceFileError("write", "not-file"));
+        }
+        await writeFileAtomic(destination, encoded, {
+            encoding: "utf8",
+            mode: 0o600,
+            fsync: true,
+        });
+        return ok({ path: requestedPath, bytes });
+    }
+    catch (cause) {
+        return err(new EvidenceFileError("write", "io", { cause }));
+    }
+};
+const isApproved = async (candidate, roots) => {
+    for (const configuredRoot of roots) {
+        const root = await realpath(resolve(configuredRoot));
+        const relation = relative(root, candidate);
+        if (relation === "" ||
+            (!relation.startsWith("..") && !isAbsolute(relation)))
+            return true;
+    }
+    return false;
+};
+const validateJsonLimits = (root, policy) => {
+    const pending = [
+        { value: root, depth: 0 },
+    ];
+    let nodes = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        nodes += 1;
+        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
+            return err(new EvidenceFileError("read", "too-large"));
+        if (typeof current.value === "string" &&
+            current.value.length > policy.maxStringLength)
+            return err(new EvidenceFileError("read", "too-large"));
+        if (typeof current.value !== "object" || current.value === null)
+            continue;
+        for (const [key, value] of Object.entries(current.value)) {
+            if (key.length > policy.maxStringLength)
+                return err(new EvidenceFileError("read", "too-large"));
+            pending.push({ value, depth: current.depth + 1 });
+        }
+    }
+    return ok(null);
+};
+const isFileNotFound = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";