The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(runner): verify ACPX installations (#12393)
Dottad1abff25671b
diff --git a/packages/paperclip-runner/src/drivers/acpx/installation-integrity.test.ts b/packages/paperclip-runner/src/drivers/acpx/installation-integrity.test.tsnew file mode 100644index 0000000000..e887139139--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/installation-integrity.test.ts@@ -0,0 +1,1215 @@+import { createHash } from "node:crypto";+import type { ChildProcess } from "node:child_process";+import { once } from "node:events";+import {+ chmod,+ link,+ mkdir,+ mkdtemp,+ realpath,+ rename,+ rm,+ symlink,+ stat,+ writeFile,+} from "node:fs/promises";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";++import { afterEach, describe, expect, it, vi } from "vitest";++import { resolveQualifiedAcpxProfile } from "./qualified-profiles.js";+import {+ guardSnapshotModuleLookup,+ guardSnapshotModuleResolution,+ sanitizedNodeEnvironment,+ snapshotDescriptorAncestorIndex,+ snapshotDescriptorResolution,+ verifiedExecutableOpenFlags,+ verifyQualifiedAcpxInstallation,+} from "./installation-integrity.js";++const temporaryDirectories: string[] = [];+const descriptorCommandPath = "/proc/self/fd/4/server.js";++afterEach(async () => {+ await Promise.all(+ temporaryDirectories+ .splice(0)+ .map((directory) => rm(directory, { force: true, recursive: true })),+ );+});++describe("ACPX installation integrity", () => {+ it("does not delegate non-Linux snapshot filesystem lookups", () => {+ for (const platform of ["darwin", "freebsd", "win32"] as const) {+ const nextResolve = vi.fn(() => ({ url: "file:///attacker.js" }));+ const nextLoad = vi.fn(() => ({ source: "attacker" }));+ expect(() =>+ guardSnapshotModuleLookup(platform, true, nextResolve),+ ).toThrow("requires Linux descriptor-pinned paths");+ expect(() => guardSnapshotModuleLookup(platform, true, nextLoad)).toThrow(+ "requires Linux descriptor-pinned paths",+ );+ expect(nextResolve).not.toHaveBeenCalled();+ expect(nextLoad).not.toHaveBeenCalled();+ }++ const pinnedLookup = vi.fn(() => "verified");+ expect(guardSnapshotModuleLookup("linux", true, pinnedLookup)).toBe(+ "verified",+ );+ expect(pinnedLookup).toHaveBeenCalledOnce();++ const builtinLookup = vi.fn(() => "builtin");+ expect(guardSnapshotModuleLookup("darwin", false, builtinLookup)).toBe(+ "builtin",+ );+ expect(builtinLookup).toHaveBeenCalledOnce();+ });++ it("rejects host-ancestry file resolutions outside retained descriptors", () => {+ const commandDirectoryUrl = "file:///proc/self/fd/4/";+ const dependencyDirectoryUrls = [+ "file:///proc/self/fd/5/",+ "file:///proc/self/fd/6/",+ ];+ const hostShadowUrl =+ "file:///proc/self/fd/node_modules/host-shadow/index.js";+ const hostShadowIndex = snapshotDescriptorAncestorIndex(+ hostShadowUrl,+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ );+ expect(hostShadowIndex).toBe(-1);+ expect(() =>+ guardSnapshotModuleResolution(false, hostShadowUrl, hostShadowIndex >= 0),+ ).toThrow("escaped descriptor-pinned ancestry");+ expect(+ snapshotDescriptorResolution(+ hostShadowUrl,+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ "file:///snapshot/package/bin/",+ ["file:///snapshot/package/", "file:///"],+ ),+ ).toBeNull();++ const verifiedUrl = "file:///proc/self/fd/5/node_modules/verified/index.js";+ const verifiedIndex = snapshotDescriptorAncestorIndex(+ verifiedUrl,+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ );+ expect(verifiedIndex).toBe(0);+ expect(() =>+ guardSnapshotModuleResolution(false, verifiedUrl, verifiedIndex >= 0),+ ).not.toThrow();+ expect(() =>+ guardSnapshotModuleResolution(false, "data:text/javascript,0", false),+ ).not.toThrow();++ const canonicalCommandDirectoryUrl = "file:///snapshot/package/bin/";+ const canonicalDependencyDirectoryUrls = [+ "file:///snapshot/package/",+ "file:///snapshot/",+ ];+ expect(+ snapshotDescriptorResolution(+ "file:///snapshot/package/bin/value.js",+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ canonicalCommandDirectoryUrl,+ canonicalDependencyDirectoryUrls,+ ),+ ).toEqual({ url: "file:///proc/self/fd/4/value.js", ancestorIndex: 0 });+ expect(+ snapshotDescriptorResolution(+ "file:///snapshot/package/node_modules/near/index.js",+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ canonicalCommandDirectoryUrl,+ canonicalDependencyDirectoryUrls,+ ),+ ).toEqual({+ url: "file:///proc/self/fd/5/node_modules/near/index.js",+ ancestorIndex: 0,+ });+ expect(+ snapshotDescriptorResolution(+ "file:///snapshot/node_modules/higher/index.js",+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ canonicalCommandDirectoryUrl,+ canonicalDependencyDirectoryUrls,+ ),+ ).toEqual({+ url: "file:///proc/self/fd/6/node_modules/higher/index.js",+ ancestorIndex: 1,+ });+ expect(+ snapshotDescriptorResolution(+ "file:///proc/self/fd/6/node_modules/higher/index.js",+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ canonicalCommandDirectoryUrl,+ canonicalDependencyDirectoryUrls,+ ),+ ).toEqual({+ url: "file:///proc/self/fd/6/node_modules/higher/index.js",+ ancestorIndex: 1,+ });+ expect(+ snapshotDescriptorResolution(+ "file:///unrelated/node_modules/host/index.js",+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ canonicalCommandDirectoryUrl,+ canonicalDependencyDirectoryUrls,+ ),+ ).toBeNull();+ });++ it("removes every case variant of Node module-loader overrides", () => {+ expect(+ sanitizedNodeEnvironment({+ PATH: "/verified/bin",+ NODE_PATH: "/unverified/one",+ node_path: "/unverified/two",+ NoDe_OpTiOnS: "--require=/unverified/preload.cjs",+ LD_PRELOAD: "/unverified/preload.so",+ ld_library_path: "/unverified/lib",+ LD_AUDIT: "/unverified/audit.so",+ DyLd_InSeRt_LiBrArIeS: "/unverified/inject.dylib",+ GCONV_PATH: "/unverified/gconv",+ glibc_tunables: "glibc.malloc.check=3",+ OPENSSL_CONF: "/unverified/openssl.cnf",+ OPENSSL_ENGINES: "/unverified/engines",+ openssl_modules: "/unverified/providers",+ }),+ ).toEqual({ PATH: "/verified/bin" });+ });++ it("fails closed when the platform cannot atomically open without following symlinks", () => {+ expect(() => verifiedExecutableOpenFlags("win32", 0x20000)).toThrow(+ "requires atomic no-follow",+ );+ expect(() => verifiedExecutableOpenFlags("linux", undefined)).toThrow(+ "requires atomic no-follow",+ );+ expect(verifiedExecutableOpenFlags("linux", 0x20000)).not.toBe(0);+ });++ it("accepts the exact package, version, executable, and runtime", async () => {+ const fixture = await installationFixture();+ const installation = await verifyQualifiedAcpxInstallation(+ fixture.profile,+ fixture.resolve,+ );+ expect(installation).toMatchObject({+ commandDigest: fixture.profile.commandDigest,+ openCommand: expect.any(Function),+ agentServerPackageJsonPath: await realpath(fixture.serverPackageJsonPath),+ agentRuntimePackageJsonPath: await realpath(+ fixture.runtimePackageJsonPath,+ ),+ });+ });++ it("rejects package version and executable digest drift", async () => {+ const fixture = await installationFixture();+ await writeFile(+ fixture.serverPackageJsonPath,+ JSON.stringify({ version: "0.0.34", bin: "bin/server.js" }),+ );+ await expect(+ verifyQualifiedAcpxInstallation(fixture.profile, fixture.resolve),+ ).rejects.toThrow(/package version mismatch/);++ await writeFile(+ fixture.serverPackageJsonPath,+ JSON.stringify({ version: "0.0.33", bin: "bin/server.js" }),+ );+ await writeFile(fixture.commandPath, "changed executable");+ await expect(+ verifyQualifiedAcpxInstallation(fixture.profile, fixture.resolve),+ ).rejects.toThrow(/digest mismatch/);+ });++ it("rejects ambiguous and escaping executable metadata", async () => {+ const fixture = await installationFixture();+ await writeFile(+ fixture.serverPackageJsonPath,+ JSON.stringify({+ version: "0.0.33",+ bin: { first: "bin/server.js", second: "bin/other.js" },+ }),+ );+ await expect(+ verifyQualifiedAcpxInstallation(fixture.profile, fixture.resolve),+ ).rejects.toThrow(/one relative executable/);++ await writeFile(+ fixture.serverPackageJsonPath,+ JSON.stringify({ version: "0.0.33", bin: "../outside.js" }),+ );+ await expect(+ verifyQualifiedAcpxInstallation(fixture.profile, fixture.resolve),+ ).rejects.toThrow(/escapes its package/);+ });++ it("rejects runtime version drift", async () => {+ const fixture = await installationFixture();+ await writeFile(+ fixture.runtimePackageJsonPath,+ JSON.stringify({ version: "0.84.3" }),+ );+ await expect(+ verifyQualifiedAcpxInstallation(fixture.profile, fixture.resolve),+ ).rejects.toThrow(/runtime version mismatch/);+ });++ it("rejects an executable symlink even when its target has the expected digest", async () => {+ const fixture = await installationFixture();+ const target = join(fixture.root, "outside.js");+ await writeFile(target, fixture.command);+ await rm(fixture.commandPath);+ await symlink(target, fixture.commandPath);++ await expect(+ verifyQualifiedAcpxInstallation(fixture.profile, fixture.resolve),+ ).rejects.toThrow(/real regular file|no-follow regular file/);+ });++ it("detects pathname replacement before opening a launch lease", async () => {+ const fixture = await installationFixture();+ const installation = await verifyQualifiedAcpxInstallation(+ fixture.profile,+ fixture.resolve,+ );+ await writeFile(fixture.commandPath, "replacement");++ await expect(installation.openCommand()).rejects.toThrow(+ /digest mismatch|identity changed/,+ );+ });++ it("rejects a hard-linked executable through a replacement directory", async () => {+ const fixture = await installationFixture();+ const attackerDirectory = join(fixture.root, "attacker-bin");+ await mkdir(attackerDirectory);+ await link(fixture.commandPath, join(attackerDirectory, "server.js"));+ const installation = await verifyQualifiedAcpxInstallation(+ fixture.profile,+ fixture.resolve,+ );+ await rename(+ fixture.commandDirectory,+ `${fixture.commandDirectory}.verified`,+ );+ await symlink(attackerDirectory, fixture.commandDirectory);++ await expect(installation.openCommand()).rejects.toThrow(+ /executable directory (must be a real directory|identity changed)/,+ );+ });++ it("launches the verified bytes after its pathname is replaced", async () => {+ const fixture = await installationFixture();+ const installation = await verifyQualifiedAcpxInstallation(+ fixture.profile,+ fixture.resolve,+ );+ const lease = await installation.openCommand();+ const replacement = `${fixture.commandPath}.replacement`;+ await writeFile(+ replacement,+ '#!/usr/bin/env node\nprocess.stdout.write("replacement");\n',+ );+ await chmod(replacement, 0o755);+ await rename(replacement, fixture.commandPath);++ await expectPinnedOutput(lease.spawn(), "verified");+ });++ it("launches the lexical verified snapshot after symlink replacement", async () => {+ const fixture = await installationFixture();+ const installation = await verifyQualifiedAcpxInstallation(+ fixture.profile,+ fixture.resolve,+ );+ const lease = await installation.openCommand();+ const outside = join(fixture.root, "outside.js");+ await writeFile(+ outside,+ '#!/usr/bin/env node\nprocess.stdout.write("symlink-target");\n',+ );+ await rm(fixture.commandPath);+ await symlink(outside, fixture.commandPath);++ await expectPinnedOutput(lease.spawn(), "verified");+ });++ it("launches the verified bytes after the open inode is modified", async () => {+ const fixture = await installationFixture();+ const installation = await verifyQualifiedAcpxInstallation(+ fixture.profile,+ fixture.resolve,+ );+ const lease = await installation.openCommand();+ const before = await stat(fixture.commandPath, { bigint: true });+ await writeFile(+ fixture.commandPath,+ '#!/usr/bin/env node\nprocess.stdout.write("modified");\n',+ );+ const after = await stat(fixture.commandPath, { bigint: true });+ expect(after.ino).toBe(before.ino);++ await expectPinnedOutput(lease.spawn(), "verified");+ });++ it("drops inherited and caller-supplied Node preload options", async () => {+ const fixture = await installationFixture();+ const installation = await verifyQualifiedAcpxInstallation(+ fixture.profile,+ fixture.resolve,+ );+ const preload = join(fixture.root, "unverified-preload.cjs");+ await writeFile(preload, 'process.stdout.write("unverified-preload");\n');+ const previousNodeOptions = process.env.NODE_OPTIONS;+ let inheritedChild: ChildProcess;+ try {+ process.env.NODE_OPTIONS = `--require=${preload}`;+ inheritedChild = (await installation.openCommand()).spawn();+ } finally {+ if (previousNodeOptions === undefined) delete process.env.NODE_OPTIONS;+ else process.env.NODE_OPTIONS = previousNodeOptions;+ }+ await expectPinnedOutput(inheritedChild, "verified");++ await expectPinnedOutput(+ (await installation.openCommand()).spawn([], {+ env: { ...process.env, node_options: `--require=${preload}` },+ }),+ "verified",+ );+ });++ it("drops native loader injection variables before spawning", async () => {+ const fixture = await installationFixture();+ const variables = [+ "LD_PRELOAD",+ "ld_library_path",+ "DyLd_InSeRt_LiBrArIeS",+ "GCONV_PATH",+ "OPENSSL_CONF",+ "OPENSSL_ENGINES",+ "openssl_modules",+ ];+ const command = `process.stdout.write(JSON.stringify(${JSON.stringify(+ variables,+ )}.filter((key) => Object.hasOwn(process.env, key))));`;+ await writeFile(fixture.commandPath, command);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ await expectPinnedOutput(+ (await installation.openCommand()).spawn([], {+ env: Object.fromEntries(+ variables.map((variable) => [variable, "/unverified/injection"]),+ ),+ }),+ "[]",+ );+ });++ it("drops inherited and caller-supplied Node package search paths", async () => {+ const fixture = await installationFixture();+ const command = [+ 'const value = require("unverified-node-path-package");',+ "process.stdout.write(value);",+ ].join("\n");+ const unverifiedPackage = join(+ fixture.root,+ "unverified-node-path",+ "unverified-node-path-package",+ );+ await mkdir(unverifiedPackage, { recursive: true });+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ join(unverifiedPackage, "package.json"),+ JSON.stringify({+ name: "unverified-node-path-package",+ main: "index.js",+ }),+ ),+ writeFile(+ join(unverifiedPackage, "index.js"),+ 'module.exports = "unverified-node-path";',+ ),+ ]);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ const previousNodePath = process.env.NODE_PATH;+ let inheritedChild: ChildProcess;+ try {+ process.env.NODE_PATH = dirname(unverifiedPackage);+ inheritedChild = (await installation.openCommand()).spawn();+ } finally {+ if (previousNodePath === undefined) delete process.env.NODE_PATH;+ else process.env.NODE_PATH = previousNodePath;+ }+ const expectedFailure =+ process.platform === "linux"+ ? "unverified-node-path-package"+ : "requires Linux descriptor-pinned paths";+ await expectFailure(inheritedChild, expectedFailure);++ await expectFailure(+ (await installation.openCommand()).spawn([], {+ env: {+ ...process.env,+ NODE_PATH: dirname(unverifiedPackage),+ node_path: dirname(unverifiedPackage),+ },+ }),+ expectedFailure,+ );+ });++ it("loads a verified ESM snapshot with relative imports and arguments", async () => {+ const fixture = await installationFixture();+ const command = [+ 'import { fileURLToPath } from "node:url";',+ 'import value from "./value.js";',+ "process.stdout.write(JSON.stringify({ value, argument: process.argv[2], argv: process.argv[1], filename: fileURLToPath(import.meta.url) }));",+ ].join("\n");+ await Promise.all([+ writeFile(+ fixture.serverPackageJsonPath,+ JSON.stringify({+ version: "0.0.33",+ type: "module",+ bin: "bin/server.js",+ }),+ ),+ writeFile(fixture.commandPath, command),+ writeFile(+ join(fixture.commandDirectory, "value.js"),+ 'export default "relative";',+ ),+ ]);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ const child = (await installation.openCommand()).spawn(["argument"]);+ if (process.platform === "linux") {+ await expectOutput(+ child,+ JSON.stringify({+ value: "relative",+ argument: "argument",+ argv: descriptorCommandPath,+ filename: descriptorCommandPath,+ }),+ );+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });++ it("pins relative imports when the command directory is replaced", async () => {+ const fixture = await installationFixture();+ const command = [+ 'import { fileURLToPath } from "node:url";',+ 'import value from "./value.js";',+ "process.stdout.write(JSON.stringify({ value, argv: process.argv[1], filename: fileURLToPath(import.meta.url) }));",+ ].join("\n");+ const attackerDirectory = join(fixture.root, "attacker-bin");+ await mkdir(attackerDirectory);+ await Promise.all([+ writeFile(+ fixture.serverPackageJsonPath,+ JSON.stringify({+ version: "0.0.33",+ type: "module",+ bin: "bin/server.js",+ }),+ ),+ writeFile(fixture.commandPath, command),+ writeFile(+ join(fixture.commandDirectory, "value.js"),+ 'export default "verified-relative";',+ ),+ writeFile(+ join(attackerDirectory, "value.js"),+ 'export default "attacker-relative";',+ ),+ ]);+ await link(fixture.commandPath, join(attackerDirectory, "server.js"));+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );+ const lease = await installation.openCommand();+ const verifiedDirectory = `${fixture.commandDirectory}.verified`;+ await rename(fixture.commandDirectory, verifiedDirectory);+ await symlink(attackerDirectory, fixture.commandDirectory);+ const verifiedCommand = await stat(join(verifiedDirectory, "server.js"), {+ bigint: true,+ });+ const redirectedCommand = await stat(fixture.commandPath, { bigint: true });+ expect(redirectedCommand.dev).toBe(verifiedCommand.dev);+ expect(redirectedCommand.ino).toBe(verifiedCommand.ino);++ if (process.platform === "linux") {+ await expectOutput(+ lease.spawn(),+ JSON.stringify({+ value: "verified-relative",+ argv: descriptorCommandPath,+ filename: descriptorCommandPath,+ }),+ );+ } else {+ await expectFailure(+ lease.spawn(),+ "requires Linux descriptor-pinned paths",+ );+ }+ });++ it("keeps descriptor-pinned CommonJS identity across replacement", async () => {+ const fixture = await installationFixture();+ const command = [+ 'const value = require("./value");',+ "process.stdout.write(JSON.stringify({ value, argument: process.argv[2], argv: process.argv[1], filename: __filename, directory: __dirname }));",+ ].join("\n");+ const attackerDirectory = join(fixture.root, "attacker-bin");+ await mkdir(attackerDirectory);+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ join(fixture.commandDirectory, "value.js"),+ 'module.exports = "verified-relative";',+ ),+ writeFile(+ join(attackerDirectory, "value.js"),+ 'module.exports = "attacker-relative";',+ ),+ ]);+ await link(fixture.commandPath, join(attackerDirectory, "server.js"));+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );+ const lease = await installation.openCommand();+ await rename(+ fixture.commandDirectory,+ `${fixture.commandDirectory}.verified`,+ );+ await symlink(attackerDirectory, fixture.commandDirectory);++ const child = lease.spawn(["argument"]);+ if (process.platform === "linux") {+ await expectOutput(+ child,+ JSON.stringify({+ value: "verified-relative",+ argument: "argument",+ argv: descriptorCommandPath,+ filename: descriptorCommandPath,+ directory: dirname(descriptorCommandPath),+ }),+ );+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });++ it("pins direct sibling resource reads across directory replacement", async () => {+ const fixture = await installationFixture();+ const command = [+ 'const { readFileSync } = require("node:fs");',+ 'const { join } = require("node:path");',+ 'process.stdout.write(readFileSync(join(__dirname, "resource.txt"), "utf8"));',+ ].join("\n");+ const attackerDirectory = join(fixture.root, "attacker-bin");+ await mkdir(attackerDirectory);+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ join(fixture.commandDirectory, "resource.txt"),+ "verified-resource",+ ),+ writeFile(join(attackerDirectory, "resource.txt"), "attacker-resource"),+ ]);+ await link(fixture.commandPath, join(attackerDirectory, "server.js"));+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );+ const lease = await installation.openCommand();+ await rename(+ fixture.commandDirectory,+ `${fixture.commandDirectory}.verified`,+ );+ await symlink(attackerDirectory, fixture.commandDirectory);++ const child = lease.spawn();+ if (process.platform === "linux") {+ await expectOutput(child, "verified-resource");+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });++ it("pins a bare entry require when the command directory is replaced", async () => {+ const fixture = await installationFixture();+ const command = [+ 'const value = require("verified-dependency");',+ "process.stdout.write(value);",+ ].join("\n");+ const attackerDirectory = join(fixture.root, "attacker-bin");+ const verifiedDependency = join(+ fixture.commandDirectory,+ "node_modules",+ "verified-dependency",+ );+ const attackerDependency = join(+ attackerDirectory,+ "node_modules",+ "verified-dependency",+ );+ await Promise.all([+ mkdir(verifiedDependency, { recursive: true }),+ mkdir(attackerDependency, { recursive: true }),+ ]);+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ join(verifiedDependency, "package.json"),+ JSON.stringify({ name: "verified-dependency", main: "index.js" }),+ ),+ writeFile(+ join(verifiedDependency, "index.js"),+ 'module.exports = "verified-bare";',+ ),+ writeFile(+ join(attackerDependency, "package.json"),+ JSON.stringify({ name: "verified-dependency", main: "index.js" }),+ ),+ writeFile(+ join(attackerDependency, "index.js"),+ 'module.exports = "attacker-bare";',+ ),+ ]);+ await link(fixture.commandPath, join(attackerDirectory, "server.js"));+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );+ const lease = await installation.openCommand();+ await rename(+ fixture.commandDirectory,+ `${fixture.commandDirectory}.verified`,+ );+ await symlink(attackerDirectory, fixture.commandDirectory);++ const child = lease.spawn();+ if (process.platform === "linux") {+ await expectOutput(child, "verified-bare");+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });++ it("rejects dependencies that escape through a descendant symlink", async () => {+ const fixture = await installationFixture();+ const command = [+ 'const value = require("linked-dependency");',+ "process.stdout.write(value);",+ ].join("\n");+ const packageNodeModules = join(fixture.serverDirectory, "node_modules");+ const outsideDependency = join(fixture.root, "outside-dependency");+ await Promise.all([+ mkdir(packageNodeModules, { recursive: true }),+ mkdir(outsideDependency, { recursive: true }),+ ]);+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ join(outsideDependency, "package.json"),+ JSON.stringify({ name: "linked-dependency", main: "index.js" }),+ ),+ writeFile(+ join(outsideDependency, "index.js"),+ 'module.exports = "attacker-symlink";',+ ),+ ]);+ await symlink(+ outsideDependency,+ join(packageNodeModules, "linked-dependency"),+ );+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ const child = (await installation.openCommand()).spawn();+ if (process.platform === "linux") {+ await expectFailure(child, "escaped descriptor-pinned ancestry");+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });++ it("rejects a final-component module symlink", async () => {+ const fixture = await installationFixture();+ const command = [+ 'const value = require("./linked.js");',+ "process.stdout.write(value);",+ ].join("\n");+ const outsideModule = join(fixture.root, "outside-module.js");+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(outsideModule, 'module.exports = "attacker-symlink";'),+ ]);+ await symlink(outsideModule, join(fixture.commandDirectory, "linked.js"));+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ const child = (await installation.openCommand()).spawn();+ if (process.platform === "linux") {+ await expectFailure(child, "descriptor-pinned ancestry");+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });++ it("rejects bare entry dependencies outside the verified package", async () => {+ const fixture = await installationFixture();+ const command = [+ 'const value = require("ancestor-dependency");',+ "process.stdout.write(value);",+ ].join("\n");+ const dependency = join(+ fixture.root,+ "node_modules",+ "ancestor-dependency",+ );+ await mkdir(dependency, { recursive: true });+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ join(dependency, "package.json"),+ JSON.stringify({ name: "ancestor-dependency", main: "index.js" }),+ ),+ writeFile(+ join(dependency, "index.js"),+ 'module.exports = "verified-ancestor";',+ ),+ ]);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ const child = (await installation.openCommand()).spawn();+ if (process.platform === "linux") {+ await expectFailure(child, "ancestor-dependency");+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });++ it("loads a separately qualified runtime through a package symlink", async () => {+ const fixture = await installationFixture();+ const packageName = "@earendil-works/pi-coding-agent";+ const command = [+ `const value = require(${JSON.stringify(packageName)});`,+ "process.stdout.write(value);",+ ].join("\n");+ const packageScope = join(+ fixture.serverDirectory,+ "node_modules",+ "@earendil-works",+ );+ await mkdir(packageScope, { recursive: true });+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ fixture.runtimePackageJsonPath,+ JSON.stringify({+ name: packageName,+ version: "0.84.2",+ main: "index.js",+ }),+ ),+ writeFile(+ join(fixture.runtimeDirectory, "index.js"),+ 'const { readFileSync } = require("node:fs"); const { join } = require("node:path"); module.exports = readFileSync(join(__dirname, "resource.txt"), "utf8");',+ ),+ writeFile(+ join(fixture.runtimeDirectory, "resource.txt"),+ "verified-runtime",+ ),+ ]);+ const runtimeLink = join(packageScope, "pi-coding-agent");+ await symlink(fixture.runtimeDirectory, runtimeLink);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ await expectPinnedOutput(+ (await installation.openCommand()).spawn(),+ "verified-runtime",+ );++ const replacementLease = await installation.openCommand();+ const attackerRuntime = join(fixture.root, "attacker-runtime");+ await mkdir(attackerRuntime);+ await Promise.all([+ writeFile(+ join(attackerRuntime, "package.json"),+ JSON.stringify({ name: packageName, main: "index.js" }),+ ),+ writeFile(+ join(attackerRuntime, "index.js"),+ 'module.exports = "attacker-runtime";',+ ),+ ]);+ await rm(runtimeLink);+ await symlink(attackerRuntime, runtimeLink);+ if (process.platform === "linux") {+ await expectFailure(replacementLease.spawn(), "descriptor-pinned");+ } else {+ await expectFailure(+ replacementLease.spawn(),+ "requires Linux descriptor-pinned paths",+ );+ }+ });++ it("loads parent-relative modules inside the verified package", async () => {+ const fixture = await installationFixture();+ const nestedDirectory = join(fixture.commandDirectory, "nested");+ const nestedCommandPath = join(nestedDirectory, "server.js");+ const packageLibrary = join(fixture.commandDirectory, "lib");+ const command = [+ 'const value = require("./child.js");',+ "process.stdout.write(value);",+ ].join("\n");+ await Promise.all([+ mkdir(nestedDirectory, { recursive: true }),+ mkdir(packageLibrary, { recursive: true }),+ ]);+ await Promise.all([+ writeFile(+ fixture.serverPackageJsonPath,+ JSON.stringify({ version: "0.0.33", bin: "bin/nested/server.js" }),+ ),+ writeFile(nestedCommandPath, command),+ writeFile(+ join(nestedDirectory, "child.js"),+ 'module.exports = require("../lib/value.js");',+ ),+ writeFile(+ join(packageLibrary, "value.js"),+ 'module.exports = "verified-parent-relative";',+ ),+ ]);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ await expectPinnedOutput(+ (await installation.openCommand()).spawn(),+ "verified-parent-relative",+ );+ });++ it("supports an executable at the verified package root", async () => {+ const fixture = await installationFixture();+ const rootCommandPath = join(fixture.serverDirectory, "server.js");+ const command = 'process.stdout.write("verified-package-root");';+ await Promise.all([+ writeFile(+ fixture.serverPackageJsonPath,+ JSON.stringify({ version: "0.0.33", bin: "server.js" }),+ ),+ writeFile(rootCommandPath, command),+ ]);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ await expectPinnedOutput(+ (await installation.openCommand()).spawn(),+ "verified-package-root",+ );+ });++ it("pins package-ancestor dependencies across directory replacement", async () => {+ const fixture = await installationFixture();+ const command = [+ 'const value = require("package-dependency");',+ "process.stdout.write(value);",+ ].join("\n");+ const packageDependency = join(+ fixture.serverDirectory,+ "node_modules",+ "package-dependency",+ );+ const attackerServerDirectory = join(fixture.root, "attacker-server");+ const attackerDependency = join(+ attackerServerDirectory,+ "node_modules",+ "package-dependency",+ );+ await Promise.all([+ mkdir(packageDependency, { recursive: true }),+ mkdir(attackerDependency, { recursive: true }),+ ]);+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ join(packageDependency, "package.json"),+ JSON.stringify({ name: "package-dependency", main: "index.js" }),+ ),+ writeFile(+ join(packageDependency, "index.js"),+ 'module.exports = "verified-package";',+ ),+ writeFile(+ join(attackerDependency, "package.json"),+ JSON.stringify({ name: "package-dependency", main: "index.js" }),+ ),+ writeFile(+ join(attackerDependency, "index.js"),+ 'module.exports = "attacker-package";',+ ),+ ]);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );+ const lease = await installation.openCommand();+ await rename(+ fixture.serverDirectory,+ `${fixture.serverDirectory}.verified`,+ );+ await symlink(attackerServerDirectory, fixture.serverDirectory);++ const child = lease.spawn();+ if (process.platform === "linux") {+ await expectOutput(child, "verified-package");+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });++ it("does not admit a transitive package from host ancestry", async () => {+ const fixture = await installationFixture();+ const command = 'require("higher-ancestor-package");';+ const higherPackage = join(+ fixture.root,+ "node_modules",+ "higher-ancestor-package",+ );+ const lowerDependency = join(+ fixture.serverDirectory,+ "node_modules",+ "lower-only-dependency",+ );+ await Promise.all([+ mkdir(higherPackage, { recursive: true }),+ mkdir(lowerDependency, { recursive: true }),+ ]);+ await Promise.all([+ writeFile(fixture.commandPath, command),+ writeFile(+ join(higherPackage, "package.json"),+ JSON.stringify({ name: "higher-ancestor-package", main: "index.js" }),+ ),+ writeFile(+ join(higherPackage, "index.js"),+ 'module.exports = require("lower-only-dependency");',+ ),+ writeFile(+ join(lowerDependency, "package.json"),+ JSON.stringify({ name: "lower-only-dependency", main: "index.js" }),+ ),+ writeFile(+ join(lowerDependency, "index.js"),+ 'module.exports = "must-not-resolve";',+ ),+ ]);+ const installation = await verifyQualifiedAcpxInstallation(+ {+ ...fixture.profile,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ },+ fixture.resolve,+ );++ const child = (await installation.openCommand()).spawn();+ if (process.platform === "linux") {+ await expectFailure(child, "higher-ancestor-package");+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+ });+});++async function expectOutput(+ child: ChildProcess,+ expected: string,+): Promise<void> {+ let stdout = "";+ let stderr = "";+ child.stdout?.setEncoding("utf8");+ child.stdout?.on("data", (chunk) => {+ stdout += String(chunk);+ });+ child.stderr?.setEncoding("utf8");+ child.stderr?.on("data", (chunk) => {+ stderr += String(chunk);+ });+ const [exitCode] = await once(child, "exit");+ expect(exitCode, stderr).toBe(0);+ expect(stdout).toBe(expected);+}++async function expectPinnedOutput(+ child: ChildProcess,+ expected: string,+): Promise<void> {+ if (process.platform === "linux") {+ await expectOutput(child, expected);+ } else {+ await expectFailure(child, "requires Linux descriptor-pinned paths");+ }+}++async function expectFailure(+ child: ChildProcess,+ expected: string,+): Promise<void> {+ let stderr = "";+ child.stderr?.setEncoding("utf8");+ child.stderr?.on("data", (chunk) => {+ stderr += String(chunk);+ });+ const [exitCode] = await once(child, "exit");+ expect(exitCode).not.toBe(0);+ expect(stderr).toContain(expected);+}++async function installationFixture() {+ const root = await mkdtemp(join(tmpdir(), "paperclip-acpx-installation-"));+ temporaryDirectories.push(root);+ const serverDirectory = join(root, "pi-acp");+ const runtimeDirectory = join(root, "pi-runtime");+ const commandDirectory = join(serverDirectory, "bin");+ await Promise.all([+ mkdir(commandDirectory, { recursive: true }),+ mkdir(runtimeDirectory, { recursive: true }),+ ]);+ const serverPackageJsonPath = join(serverDirectory, "package.json");+ const runtimePackageJsonPath = join(runtimeDirectory, "package.json");+ const commandPath = join(commandDirectory, "server.js");+ const command = '#!/usr/bin/env node\nprocess.stdout.write("verified");\n';+ await Promise.all([+ writeFile(+ serverPackageJsonPath,+ JSON.stringify({ version: "0.0.33", bin: "bin/server.js" }),+ ),+ writeFile(runtimePackageJsonPath, JSON.stringify({ version: "0.84.2" })),+ writeFile(commandPath, command),+ ]);+ await chmod(commandPath, 0o755);+ const base = resolveQualifiedAcpxProfile(+ "pi",+ "openrouter/deepseek/deepseek-v4-flash-0731",+ );+ const profile = {+ ...base,+ commandDigest: `sha256:${createHash("sha256").update(command).digest("hex")}`,+ };+ const paths = new Map([+ ["pi-acp", serverPackageJsonPath],+ ["@earendil-works/pi-coding-agent", runtimePackageJsonPath],+ ]);+ return {+ root,+ serverDirectory,+ command,+ profile,+ commandPath,+ commandDirectory,+ runtimeDirectory,+ serverPackageJsonPath,+ runtimePackageJsonPath,+ resolve(packageName: string): string {+ const resolved = paths.get(packageName);+ if (!resolved) throw new Error(`unexpected package ${packageName}`);+ return resolved;+ },+ };+}diff --git a/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts b/packages/paperclip-runner/src/drivers/acpx/installation-integrity.tsnew file mode 100644index 0000000000..e49706e776--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts@@ -0,0 +1,969 @@+import { createHash } from "node:crypto";+import {+ spawn as spawnChildProcess,+ type ChildProcess,+ type SpawnOptionsWithoutStdio,+} from "node:child_process";+import { constants } from "node:fs";+import {+ lstat,+ open,+ readFile,+ realpath,+ stat,+ type FileHandle,+} from "node:fs/promises";+import { createRequire } from "node:module";+import {+ basename,+ dirname,+ extname,+ isAbsolute,+ relative,+ resolve,+} from "node:path";+import type { Writable } from "node:stream";++import type { QualifiedAcpxProfile } from "./qualified-profiles.js";++const MAX_PACKAGE_JSON_BYTES = 256 * 1024;+const MAX_AGENT_COMMAND_BYTES = 16 * 1024 * 1024;+const COMMAND_SOURCE_FD = 3;+const COMMAND_DIRECTORY_FD = 4;+const DEPENDENCY_ANCESTOR_FD_START = 5;+const MAX_DEPENDENCY_ANCESTORS = 64;++export type AcpxPackageJsonResolver = (packageName: string) => string;++export interface VerifiedAcpxInstallation {+ readonly commandDigest: string;+ readonly agentServerPackageJsonPath: string;+ readonly agentRuntimePackageJsonPath: string | null;+ openCommand(): Promise<VerifiedAcpxCommandLease>;+}++export interface VerifiedAcpxCommandLease {+ /**+ * Launch with a Linux descriptor-backed entry identity. Callers must not+ * admit a provider that requires its mutable installation pathname; that+ * compatibility belongs to the later provider-specific adapter gate.+ */+ spawn(+ args?: readonly string[],+ options?: SpawnOptionsWithoutStdio,+ ): ChildProcess;+ close(): Promise<void>;+}++interface VerifiedAcpxCommandIdentity {+ device: string;+ inode: string;+ size: string;+ modifiedNanoseconds: string;+ changedNanoseconds: string;+}++interface VerifiedAcpxDirectoryIdentity {+ device: string;+ inode: string;+}++interface VerifiedAcpxDependencyAncestor {+ path: string;+ identity: VerifiedAcpxDirectoryIdentity;+}++type AcpxCommandFormat = "commonjs" | "module";++const COMMONJS_SNAPSHOT_BOOTSTRAP = snapshotBootstrap("commonjs");+const MODULE_SNAPSHOT_BOOTSTRAP = snapshotBootstrap("module");++/** Resolve and verify every installed artifact bound by a qualified profile. */+export async function verifyQualifiedAcpxInstallation(+ profile: QualifiedAcpxProfile,+ resolvePackageJson: AcpxPackageJsonResolver = defaultPackageJsonResolver,+): Promise<VerifiedAcpxInstallation> {+ const serverPackageJsonPath = await realpath(+ resolvePackageJson(profile.agentServerPackage),+ );+ const serverPackage = await readPackageJson(+ serverPackageJsonPath,+ profile.agentServerPackage,+ );+ if (serverPackage.version !== profile.agentServerVersion) {+ throw new Error(+ `ACPX ${profile.agent} package version mismatch: expected ${profile.agentServerVersion}, received ${serverPackage.version ?? "unknown"}`,+ );+ }+ const relativeCommand = oneExecutable(serverPackage.bin, profile.agent);+ const commandFormat = executableFormat(+ relativeCommand,+ serverPackage.type,+ profile.agent,+ );+ const serverPackageFormat = packageModuleFormat(serverPackage.type);+ const packageDirectory = dirname(serverPackageJsonPath);+ const unresolvedCommandPath = resolve(packageDirectory, relativeCommand);+ if (!isInside(packageDirectory, unresolvedCommandPath)) {+ throw new Error(`ACPX ${profile.agent} executable escapes its package`);+ }+ const commandDirectory = await realpath(dirname(unresolvedCommandPath));+ if (!isInsideOrEqual(packageDirectory, commandDirectory)) {+ throw new Error(`ACPX ${profile.agent} executable escapes its package`);+ }+ const commandPath = resolve(+ commandDirectory,+ basename(unresolvedCommandPath),+ );+ const verifiedDirectory = await openVerifiedCommandDirectory(+ commandDirectory,+ profile.agent,+ );+ const commandDirectoryIdentity = verifiedDirectory.identity;+ await verifiedDirectory.handle.close();+ const command = await inspectCommand(+ commandPath,+ profile.commandDigest,+ profile.agent,+ );++ let runtimePackageJsonPath: string | null = null;+ let runtimePackageFormat: AcpxCommandFormat | null = null;+ if (profile.agentRuntimePackage !== null) {+ if (profile.agentRuntimeVersion === null) {+ throw new Error("Qualified ACPX runtime package omitted its version");+ }+ runtimePackageJsonPath = await realpath(+ resolvePackageJson(profile.agentRuntimePackage),+ );+ const runtimePackage = await readPackageJson(+ runtimePackageJsonPath,+ profile.agentRuntimePackage,+ );+ if (runtimePackage.version !== profile.agentRuntimeVersion) {+ throw new Error(+ `ACPX ${profile.agent} runtime version mismatch: expected ${profile.agentRuntimeVersion}, received ${runtimePackage.version ?? "unknown"}`,+ );+ }+ runtimePackageFormat = packageModuleFormat(runtimePackage.type);+ } else if (profile.agentRuntimeVersion !== null) {+ throw new Error("Qualified ACPX runtime version omitted its package");+ }++ const serverDependencyAncestors = await inspectDependencyAncestors(+ commandDirectory,+ packageDirectory,+ profile.agent,+ );+ const dependencyAncestors = [...serverDependencyAncestors];+ const dependencyAncestorFormats = serverDependencyAncestors.map(+ () => serverPackageFormat,+ );+ if (runtimePackageJsonPath !== null) {+ const runtimeDirectory = dirname(runtimePackageJsonPath);+ // A separately qualified runtime is an explicit trust root. We do not+ // retain arbitrary package-manager ancestors: hoisted dependencies must+ // be qualified by a provider-specific layer instead of becoming ambient+ // executable authority here.+ if (+ runtimeDirectory !== commandDirectory &&+ !dependencyAncestors.some(+ (ancestor) => ancestor.path === runtimeDirectory,+ )+ ) {+ dependencyAncestors.push(+ await inspectExplicitDependencyRoot(+ runtimeDirectory,+ `${profile.agent} runtime`,+ ),+ );+ dependencyAncestorFormats.push(runtimePackageFormat ?? "commonjs");+ }+ }+ if (dependencyAncestors.length > MAX_DEPENDENCY_ANCESTORS) {+ throw new Error("ACPX provider dependency ancestry exceeds its bound");+ }+ const serverDependencyAncestorCount = serverDependencyAncestors.length;++ const commandDigest = command.digest;+ const commandIdentity = command.identity;+ return Object.freeze({+ commandDigest,+ agentServerPackageJsonPath: serverPackageJsonPath,+ agentRuntimePackageJsonPath: runtimePackageJsonPath,+ async openCommand(): Promise<VerifiedAcpxCommandLease> {+ const currentDirectory = await openVerifiedCommandDirectory(+ commandDirectory,+ "provider",+ );+ if (+ !sameDirectoryIdentity(+ currentDirectory.identity,+ commandDirectoryIdentity,+ )+ ) {+ await currentDirectory.handle.close();+ throw new Error(+ "ACPX provider executable directory identity changed after verification",+ );+ }+ let currentDependencyAncestors: FileHandle[] = [];+ try {+ currentDependencyAncestors =+ await openDependencyAncestors(dependencyAncestors);+ const current = await inspectCommand(+ commandPath,+ commandDigest,+ "provider",+ );+ if (!sameIdentity(current.identity, commandIdentity)) {+ current.bytes.fill(0);+ throw new Error(+ "ACPX provider executable identity changed after verification",+ );+ }+ return commandLease(+ commandDirectory,+ basename(commandPath),+ commandFormat,+ current.bytes,+ currentDirectory.handle,+ currentDependencyAncestors,+ serverDependencyAncestorCount,+ serverPackageFormat,+ dependencyAncestorFormats,+ );+ } catch (error) {+ await Promise.all([+ currentDirectory.handle.close(),+ ...currentDependencyAncestors.map((handle) => handle.close()),+ ]);+ throw error;+ }+ },+ });+}++function defaultPackageJsonResolver(packageName: string): string {+ return createRequire(import.meta.url).resolve(`${packageName}/package.json`);+}++async function readPackageJson(+ packageJsonPath: string,+ packageName: string,+): Promise<{ version?: string; bin?: unknown; type?: unknown }> {+ const bytes = await readBoundedRegularFile(+ packageJsonPath,+ MAX_PACKAGE_JSON_BYTES,+ `${packageName} package.json`,+ );+ let value: unknown;+ try {+ value = JSON.parse(bytes.toString("utf8"));+ } catch {+ throw new Error(`ACPX package ${packageName} has malformed package.json`);+ }+ if (typeof value !== "object" || value === null || Array.isArray(value)) {+ throw new Error(`ACPX package ${packageName} has invalid package metadata`);+ }+ return value as { version?: string; bin?: unknown; type?: unknown };+}++async function readBoundedRegularFile(+ filePath: string,+ maxBytes: number,+ label: string,+): Promise<Buffer> {+ const metadata = await stat(filePath);+ if (!metadata.isFile() || metadata.size < 1 || metadata.size > maxBytes) {+ throw new Error(`${label} must be a bounded regular file`);+ }+ const bytes = await readFile(filePath);+ if (bytes.length < 1 || bytes.length > maxBytes) {+ throw new Error(`${label} changed outside its bounded size`);+ }+ return bytes;+}++async function inspectCommand(+ commandPath: string,+ expectedDigest: string,+ agent: string,+): Promise<{+ bytes: Buffer;+ digest: string;+ identity: VerifiedAcpxCommandIdentity;+}> {+ const lexicalBefore = await lstat(commandPath, { bigint: true }).catch(+ () => null,+ );+ if (+ lexicalBefore === null ||+ lexicalBefore.isSymbolicLink() ||+ !lexicalBefore.isFile()+ ) {+ throw new Error(`ACPX ${agent} executable must be a real regular file`);+ }+ let handle: Awaited<ReturnType<typeof open>>;+ try {+ handle = await open(+ commandPath,+ verifiedExecutableOpenFlags(process.platform, constants.O_NOFOLLOW),+ );+ } catch {+ throw new Error(+ `ACPX ${agent} executable could not be opened as a no-follow regular file`,+ );+ }+ try {+ const before = await handle.stat({ bigint: true });+ if (+ !before.isFile() ||+ before.size < 1n ||+ before.size > BigInt(MAX_AGENT_COMMAND_BYTES)+ ) {+ throw new Error(+ `ACPX ${agent} executable must be a bounded regular file`,+ );+ }+ const bytes = await readHandleAtStart(handle, Number(before.size));+ const after = await handle.stat({ bigint: true });+ const lexicalAfter = await lstat(commandPath, { bigint: true }).catch(+ () => null,+ );+ const beforeIdentity = fileIdentity(before);+ const afterIdentity = fileIdentity(after);+ if (+ bytes.length < 1 ||+ bytes.length > MAX_AGENT_COMMAND_BYTES ||+ lexicalAfter === null ||+ lexicalAfter.isSymbolicLink() ||+ !lexicalAfter.isFile() ||+ !sameIdentity(fileIdentity(lexicalBefore), fileIdentity(lexicalAfter)) ||+ !sameIdentity(fileIdentity(lexicalAfter), afterIdentity) ||+ !sameIdentity(beforeIdentity, afterIdentity) ||+ after.size !== BigInt(bytes.length)+ ) {+ throw new Error(`ACPX ${agent} executable changed while it was verified`);+ }+ const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;+ if (digest !== expectedDigest) {+ throw new Error(`ACPX ${agent} executable digest mismatch`);+ }+ return { bytes, digest, identity: afterIdentity };+ } catch (error) {+ throw error;+ } finally {+ await handle.close();+ }+}++/** Fail closed where Node cannot atomically refuse a final symlink component. */+export function verifiedExecutableOpenFlags(+ platform: NodeJS.Platform,+ noFollowFlag: number | undefined,+): number {+ if (+ platform === "win32" ||+ typeof noFollowFlag !== "number" ||+ noFollowFlag === 0+ ) {+ throw new Error(+ "ACPX verified executable launch requires atomic no-follow file opening",+ );+ }+ return constants.O_RDONLY | noFollowFlag;+}++async function openVerifiedCommandDirectory(+ commandDirectory: string,+ agent: string,+): Promise<{+ handle: FileHandle;+ identity: VerifiedAcpxDirectoryIdentity;+}> {+ const lexicalBefore = await lstat(commandDirectory, { bigint: true }).catch(+ () => null,+ );+ if (+ lexicalBefore === null ||+ lexicalBefore.isSymbolicLink() ||+ !lexicalBefore.isDirectory()+ ) {+ throw new Error(+ `ACPX ${agent} executable directory must be a real directory`,+ );+ }+ let handle: FileHandle;+ try {+ handle = await open(+ commandDirectory,+ verifiedDirectoryOpenFlags(+ process.platform,+ constants.O_NOFOLLOW,+ constants.O_DIRECTORY,+ ),+ );+ } catch {+ throw new Error(+ `ACPX ${agent} executable directory could not be opened as a no-follow directory`,+ );+ }+ try {+ const opened = await handle.stat({ bigint: true });+ const lexicalAfter = await lstat(commandDirectory, { bigint: true }).catch(+ () => null,+ );+ const beforeIdentity = directoryIdentity(lexicalBefore);+ const openedIdentity = directoryIdentity(opened);+ if (+ !opened.isDirectory() ||+ lexicalAfter === null ||+ lexicalAfter.isSymbolicLink() ||+ !lexicalAfter.isDirectory() ||+ !sameDirectoryIdentity(beforeIdentity, directoryIdentity(lexicalAfter)) ||+ !sameDirectoryIdentity(directoryIdentity(lexicalAfter), openedIdentity)+ ) {+ throw new Error(+ `ACPX ${agent} executable directory changed while it was verified`,+ );+ }+ return { handle, identity: openedIdentity };+ } catch (error) {+ await handle.close();+ throw error;+ }+}++async function inspectDependencyAncestors(+ commandDirectory: string,+ packageDirectory: string,+ agent: string,+): Promise<VerifiedAcpxDependencyAncestor[]> {+ const ancestors: VerifiedAcpxDependencyAncestor[] = [];+ if (commandDirectory === packageDirectory) return ancestors;+ let ancestor = dirname(commandDirectory);+ for (let count = 0; count < MAX_DEPENDENCY_ANCESTORS; count += 1) {+ if (!isInsideOrEqual(packageDirectory, ancestor)) {+ throw new Error("ACPX provider dependency ancestry escaped its package");+ }+ const verified = await openVerifiedCommandDirectory(ancestor, agent);+ ancestors.push({ path: ancestor, identity: verified.identity });+ await verified.handle.close();+ if (ancestor === packageDirectory) return ancestors;+ const parent = dirname(ancestor);+ if (parent === ancestor) break;+ ancestor = parent;+ }+ throw new Error("ACPX provider dependency ancestry exceeds its bound");+}++async function openDependencyAncestors(+ ancestors: readonly VerifiedAcpxDependencyAncestor[],+): Promise<FileHandle[]> {+ const handles: FileHandle[] = [];+ try {+ for (const expected of ancestors) {+ const current = await openVerifiedCommandDirectory(+ expected.path,+ "provider dependency ancestor",+ );+ if (!sameDirectoryIdentity(current.identity, expected.identity)) {+ await current.handle.close();+ throw new Error(+ "ACPX provider dependency ancestor identity changed after verification",+ );+ }+ handles.push(current.handle);+ }+ return handles;+ } catch (error) {+ await Promise.all(handles.map((handle) => handle.close()));+ throw error;+ }+}++async function inspectExplicitDependencyRoot(+ path: string,+ label: string,+): Promise<VerifiedAcpxDependencyAncestor> {+ const verified = await openVerifiedCommandDirectory(path, label);+ const ancestor = { path, identity: verified.identity };+ await verified.handle.close();+ return ancestor;+}++/** Fail closed where Node cannot atomically pin a real directory inode. */+function verifiedDirectoryOpenFlags(+ platform: NodeJS.Platform,+ noFollowFlag: number | undefined,+ directoryFlag: number | undefined,+): number {+ if (+ platform === "win32" ||+ typeof noFollowFlag !== "number" ||+ noFollowFlag === 0 ||+ typeof directoryFlag !== "number" ||+ directoryFlag === 0+ ) {+ throw new Error(+ "ACPX verified executable launch requires atomic no-follow directory opening",+ );+ }+ return constants.O_RDONLY | noFollowFlag | directoryFlag;+}++async function readHandleAtStart(+ handle: FileHandle,+ size: number,+): Promise<Buffer> {+ const bytes = Buffer.alloc(size);+ let offset = 0;+ while (offset < size) {+ const read = await handle.read(bytes, offset, size - offset, offset);+ if (read.bytesRead === 0) break;+ offset += read.bytesRead;+ }+ if (offset !== size) {+ throw new Error("ACPX provider executable ended during verification");+ }+ return bytes;+}++function commandLease(+ commandDirectoryPath: string,+ commandName: string,+ format: AcpxCommandFormat,+ verifiedBytes: Buffer,+ commandDirectory: FileHandle,+ dependencyAncestors: readonly FileHandle[],+ serverDependencyAncestorCount: number,+ serverPackageFormat: AcpxCommandFormat,+ dependencyAncestorFormats: readonly AcpxCommandFormat[],+): VerifiedAcpxCommandLease {+ let consumed = false;+ let directoriesReleased = false;+ const releaseDirectories = async (): Promise<void> => {+ if (directoriesReleased) return;+ directoriesReleased = true;+ await Promise.all([+ commandDirectory.close(),+ ...dependencyAncestors.map((handle) => handle.close()),+ ]);+ };+ const releaseDirectoriesBestEffort = (): void => {+ void releaseDirectories().catch(() => undefined);+ };+ const close = async (): Promise<void> => {+ if (consumed) return;+ consumed = true;+ verifiedBytes.fill(0);+ await releaseDirectories();+ };+ return {+ spawn(+ args: readonly string[] = [],+ options: SpawnOptionsWithoutStdio = {},+ ): ChildProcess {+ if (consumed) throw new Error("Verified ACPX command lease is closed");+ consumed = true;+ let child: ChildProcess;+ try {+ child = spawnChildProcess(+ process.execPath,+ [+ // Keep resolved module URLs on the retained descriptor paths so+ // the hook can distinguish them from ordinary host ancestry.+ "--preserve-symlinks",+ "--eval",+ format === "module"+ ? MODULE_SNAPSHOT_BOOTSTRAP+ : COMMONJS_SNAPSHOT_BOOTSTRAP,+ commandDirectoryPath,+ commandName,+ String(dependencyAncestors.length),+ String(serverDependencyAncestorCount),+ serverPackageFormat,+ JSON.stringify(dependencyAncestorFormats),+ ...args,+ ],+ {+ ...options,+ env: sanitizedNodeEnvironment(options.env),+ shell: false,+ stdio: [+ "pipe",+ "pipe",+ "pipe",+ "pipe",+ commandDirectory.fd,+ ...dependencyAncestors.map((handle) => handle.fd),+ ],+ },+ );+ } catch (error) {+ verifiedBytes.fill(0);+ releaseDirectoriesBestEffort();+ throw error;+ }+ releaseDirectoriesBestEffort();+ const sourceInput = child.stdio[COMMAND_SOURCE_FD] as Writable | null;+ if (sourceInput === null) {+ verifiedBytes.fill(0);+ child.kill();+ throw new Error("Verified ACPX command source pipe was not created");+ }+ const release = (): void => {+ verifiedBytes.fill(0);+ };+ sourceInput.once("error", release);+ sourceInput.end(verifiedBytes, release);+ return child;+ },+ close,+ };+}++export function sanitizedNodeEnvironment(+ environment: NodeJS.ProcessEnv | undefined,+): NodeJS.ProcessEnv {+ const sanitized = { ...(environment ?? process.env) };+ for (const key of Object.keys(sanitized)) {+ // Environment keys are case-insensitive on Windows. Dropping every case+ // variant also keeps a context portable instead of admitting a preload or+ // an unverified package-search root on one runner host but not another.+ const normalizedKey = key.toUpperCase();+ if (+ normalizedKey === "NODE_OPTIONS" ||+ normalizedKey === "NODE_PATH" ||+ normalizedKey === "GCONV_PATH" ||+ normalizedKey === "GLIBC_TUNABLES" ||+ normalizedKey === "OPENSSL_CONF" ||+ normalizedKey === "OPENSSL_ENGINES" ||+ normalizedKey === "OPENSSL_MODULES" ||+ normalizedKey.startsWith("LD_") ||+ normalizedKey.startsWith("DYLD_")+ ) {+ delete sanitized[key];+ }+ }+ return sanitized;+}++function snapshotBootstrap(format: AcpxCommandFormat): string {+ return [+ 'const fs = require("node:fs");',+ 'const { isBuiltin, registerHooks } = require("node:module");',+ 'const { dirname, extname, join, normalize, relative, resolve } = require("node:path");',+ 'const { fileURLToPath, pathToFileURL } = require("node:url");',+ "const commandDirectory = process.argv[1];",+ "const commandName = process.argv[2];",+ "const dependencyAncestorCount = Number.parseInt(process.argv[3], 10);",+ "const serverDependencyAncestorCount = Number.parseInt(process.argv[4], 10);",+ "const serverPackageFormat = process.argv[5];",+ "const dependencyAncestorFormats = JSON.parse(process.argv[6]);",+ 'if (process.platform !== "linux") throw new Error("ACPX provider relative module loading requires Linux descriptor-pinned paths");',+ `if (!Number.isSafeInteger(dependencyAncestorCount) || dependencyAncestorCount < 0 || dependencyAncestorCount > ${MAX_DEPENDENCY_ANCESTORS}) throw new Error("ACPX provider dependency ancestry is invalid");`,+ 'if (!Number.isSafeInteger(serverDependencyAncestorCount) || serverDependencyAncestorCount < 0 || serverDependencyAncestorCount > dependencyAncestorCount) throw new Error("ACPX provider package ancestry is invalid");',+ 'if ((serverPackageFormat !== "module" && serverPackageFormat !== "commonjs") || !Array.isArray(dependencyAncestorFormats) || dependencyAncestorFormats.length !== dependencyAncestorCount || dependencyAncestorFormats.some((value) => value !== "module" && value !== "commonjs")) throw new Error("ACPX provider package formats are invalid");',+ "const commandPath = resolve(commandDirectory, commandName);",+ `const guardSnapshotModuleLookup = ${guardSnapshotModuleLookup.toString()};`,+ `const directory = process.platform === "linux" ? "/proc/self/fd/${COMMAND_DIRECTORY_FD}" : commandDirectory;`,+ "const directoryUrl = pathToFileURL(`${directory}/`).href;",+ "const pinnedTarget = new URL(commandName, directoryUrl).href;",+ 'const target = process.platform === "linux" ? pinnedTarget : pathToFileURL(commandPath).href;',+ "process.argv.splice(1, 6, fileURLToPath(target));",+ `const dependencyDirectoryUrls = Array.from({ length: dependencyAncestorCount }, (_, index) => pathToFileURL("/proc/self/fd/" + (${DEPENDENCY_ANCESTOR_FD_START} + index) + "/").href);`,+ 'const canonicalRootUrl = (url) => pathToFileURL(fs.realpathSync(fileURLToPath(url))).href.replace(/\\/?$/, "/");',+ 'const canonicalDirectoryUrl = process.platform === "linux" ? canonicalRootUrl(directoryUrl) : directoryUrl;',+ 'const canonicalDependencyDirectoryUrls = process.platform === "linux" ? dependencyDirectoryUrls.map(canonicalRootUrl) : dependencyDirectoryUrls;',+ "const dependencyAncestorByUrl = new Map([[target, 0]]);",+ `const descriptorFormatByUrl = new Map([[target, ${JSON.stringify(format)}]]);`,+ `const snapshotDescriptorAncestorIndex = ${snapshotDescriptorAncestorIndex.toString()};`,+ `const snapshotDescriptorResolution = ${snapshotDescriptorResolution.toString()};`,+ "const dependencyAncestorIndex = (url) => { const recorded = dependencyAncestorByUrl.get(url); return recorded === undefined ? snapshotDescriptorAncestorIndex(url, directoryUrl, dependencyDirectoryUrls) : recorded; };",+ `const guardSnapshotModuleResolution = ${guardSnapshotModuleResolution.toString()};`,+ 'const canonicalizeDescriptorResolution = (url) => { if (typeof url !== "string" || !url.startsWith("file:") || snapshotDescriptorAncestorIndex(url, directoryUrl, dependencyDirectoryUrls) < 0) return url; try { return pathToFileURL(fs.realpathSync(fileURLToPath(url))).href; } catch { const error = new Error("ACPX provider module could not be canonicalized through its retained descriptor"); error.code = "ERR_ACPX_UNVERIFIED_MODULE"; throw error; } };',+ 'const rememberDependencyAncestor = (specifier, resolution) => { const canonicalUrl = canonicalizeDescriptorResolution(resolution?.url); const pinned = snapshotDescriptorResolution(canonicalUrl, directoryUrl, dependencyDirectoryUrls, canonicalDirectoryUrl, canonicalDependencyDirectoryUrls); guardSnapshotModuleResolution(isBuiltin(specifier), resolution?.url, pinned !== null); if (pinned !== null && typeof resolution?.url === "string") { for (const rememberedUrl of [resolution.url, canonicalUrl, pinned.url]) { if (typeof rememberedUrl !== "string") continue; dependencyAncestorByUrl.set(rememberedUrl, pinned.ancestorIndex); if (typeof resolution.format === "string") descriptorFormatByUrl.set(rememberedUrl, resolution.format); } } return pinned === null || pinned.url === resolution?.url ? resolution : { ...resolution, url: pinned.url }; };',+ `const source = fs.readFileSync(${COMMAND_SOURCE_FD});`,+ "let resolvingDescriptorBare = false;",+ "const resolveBareFromDescriptor = (specifier, dependencyDirectoryUrl) => { resolvingDescriptorBare = true; try { return require.resolve(specifier, { paths: [fileURLToPath(dependencyDirectoryUrl)] }); } finally { resolvingDescriptorBare = false; } };",+ "registerHooks({ resolve(specifier, context, nextResolve) {",+ "if (resolvingDescriptorBare) return nextResolve(specifier, context);",+ "if (specifier === target) return { url: target, shortCircuit: true };",+ "const entryImport = context.parentURL === target;",+ "const parentDependencyAncestorIndex = entryImport ? 0 : dependencyAncestorIndex(context.parentURL);",+ 'const relativeImport = (entryImport || parentDependencyAncestorIndex >= 0) && (specifier.startsWith("./") || specifier.startsWith("../"));',+ "const pinRelativeSpecifier = () => {",+ "const parentDescriptorIndex = context.parentURL.startsWith(directoryUrl) ? -1 : dependencyDirectoryUrls.findIndex((dependencyDirectoryUrl) => context.parentURL.startsWith(dependencyDirectoryUrl));",+ "if (parentDescriptorIndex < -1) return null;",+ "const parentRootUrl = parentDescriptorIndex === -1 ? directoryUrl : dependencyDirectoryUrls[parentDescriptorIndex];",+ "const parentDirectoryWithinRoot = relative(fileURLToPath(parentRootUrl), dirname(fileURLToPath(context.parentURL)));",+ "const relativePath = normalize(join(parentDirectoryWithinRoot, specifier));",+ 'if (relativePath === "" || (!relativePath.startsWith("../") && relativePath !== "..")) return new URL(relativePath || ".", parentRootUrl);',+ "if (parentDescriptorIndex >= serverDependencyAncestorCount) return null;",+ 'const segments = relativePath.split("/");',+ 'let ancestorLevels = 0; while (segments[ancestorLevels] === "..") ancestorLevels += 1;',+ "const targetAncestorIndex = parentDescriptorIndex + ancestorLevels;",+ "if (ancestorLevels < 1 || targetAncestorIndex < 0 || targetAncestorIndex >= serverDependencyAncestorCount) return null;",+ 'return new URL(segments.slice(ancestorLevels).join("/") || ".", dependencyDirectoryUrls[targetAncestorIndex]);',+ "};",+ "const pinnedSpecifier = relativeImport ? pinRelativeSpecifier() : null;",+ 'if (relativeImport && pinnedSpecifier === null) { const error = new Error("ACPX provider relative module escaped its verified package"); error.code = "ERR_ACPX_UNVERIFIED_MODULE"; throw error; }',+ 'const lookupSpecifier = pinnedSpecifier === null ? specifier : context.conditions?.includes("require") ? fileURLToPath(pinnedSpecifier) : pinnedSpecifier.href;',+ "const snapshotImport = entryImport || parentDependencyAncestorIndex >= 0;",+ 'const bareImport = snapshotImport && !isBuiltin(specifier) && !specifier.startsWith("./") && !specifier.startsWith("../") && !specifier.startsWith("/") && !specifier.includes(":");',+ "const filesystemLookup = snapshotImport && !isBuiltin(specifier);",+ "const lookupContext = entryImport && pinnedSpecifier === null && !isBuiltin(specifier) ? { ...context, parentURL: pinnedTarget } : context;",+ 'const isMissingModuleError = (error) => error?.code === "MODULE_NOT_FOUND" || error?.code === "ERR_MODULE_NOT_FOUND";',+ "return guardSnapshotModuleLookup(process.platform, filesystemLookup, () => {",+ "try { return rememberDependencyAncestor(specifier, nextResolve(lookupSpecifier, lookupContext)); } catch (error) {",+ "if (!bareImport || !isMissingModuleError(error)) throw error;",+ "let dependencyError = error;",+ "for (let dependencyIndex = Math.max(0, parentDependencyAncestorIndex); dependencyIndex < dependencyDirectoryUrls.length; dependencyIndex += 1) {",+ "const dependencyDirectoryUrl = dependencyDirectoryUrls[dependencyIndex];",+ 'try { const candidateResolution = context.conditions?.includes("require") ? nextResolve(resolveBareFromDescriptor(specifier, dependencyDirectoryUrl), context) : nextResolve(specifier, { ...context, parentURL: new URL("package.json", dependencyDirectoryUrl).href }); return rememberDependencyAncestor(specifier, candidateResolution); } catch (candidateError) {',+ "if (!isMissingModuleError(candidateError)) throw candidateError;",+ "dependencyError = candidateError;",+ "}",+ "}",+ "throw dependencyError;",+ "}",+ "});",+ "}, load(url, context, nextLoad) {",+ `if (url === target) return { format: ${JSON.stringify(format)}, source, shortCircuit: true };`,+ "const dependencyDescriptorIndex = dependencyDirectoryUrls.findIndex((dependencyDirectoryUrl) => url.startsWith(dependencyDirectoryUrl));",+ "const descriptorLookup = url.startsWith(directoryUrl) || dependencyDescriptorIndex >= 0;",+ "guardSnapshotModuleResolution(false, url, descriptorLookup);",+ "return guardSnapshotModuleLookup(process.platform, descriptorLookup, () => {",+ "if (!descriptorLookup) return nextLoad(url, context);",+ "const canonicalRootUrl = url.startsWith(directoryUrl) ? canonicalDirectoryUrl : canonicalDependencyDirectoryUrls[dependencyDescriptorIndex];",+ "let moduleFd;",+ 'try { moduleFd = fs.openSync(fileURLToPath(url), fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); } catch { const error = new Error("ACPX provider module could not be opened without following its final component"); error.code = "ERR_ACPX_UNVERIFIED_MODULE"; throw error; }',+ "try {",+ "const metadataBefore = fs.fstatSync(moduleFd, { bigint: true });",+ `if (!metadataBefore.isFile() || metadataBefore.size > BigInt(${MAX_AGENT_COMMAND_BYTES})) { const error = new Error("ACPX provider module is not a bounded regular file"); error.code = "ERR_ACPX_UNVERIFIED_MODULE"; throw error; }`,+ 'const openedUrl = pathToFileURL(fs.realpathSync("/proc/self/fd/" + moduleFd)).href;',+ 'if (typeof canonicalRootUrl !== "string" || !openedUrl.startsWith(canonicalRootUrl)) { const error = new Error("ACPX provider module escaped descriptor-pinned ancestry"); error.code = "ERR_ACPX_UNVERIFIED_MODULE"; throw error; }',+ "const packageFormat = url.startsWith(directoryUrl) ? serverPackageFormat : dependencyAncestorFormats[dependencyDescriptorIndex];",+ "const hintedFormat = descriptorFormatByUrl.get(url) || context.format;",+ "const extension = extname(fileURLToPath(url));",+ 'const moduleFormat = extension === ".mjs" ? "module" : extension === ".cjs" ? "commonjs" : extension === ".json" ? "json" : extension === ".node" ? "addon" : extension === ".js" ? (hintedFormat === "module" || hintedFormat === "commonjs" ? hintedFormat : packageFormat) : hintedFormat;',+ 'if (moduleFormat !== "module" && moduleFormat !== "commonjs" && moduleFormat !== "json") { const error = new Error("ACPX provider module format is not supported by descriptor-pinned loading"); error.code = "ERR_ACPX_UNVERIFIED_MODULE"; throw error; }',+ "const admittedModuleBytes = Number(metadataBefore.size);",+ "const moduleBuffer = Buffer.alloc(admittedModuleBytes + 1);",+ "let moduleBytesRead = 0;",+ "while (moduleBytesRead < moduleBuffer.length) { const bytesRead = fs.readSync(moduleFd, moduleBuffer, moduleBytesRead, moduleBuffer.length - moduleBytesRead, moduleBytesRead); if (bytesRead === 0) break; moduleBytesRead += bytesRead; }",+ "const moduleSource = moduleBuffer.subarray(0, moduleBytesRead);",+ "const metadataAfter = fs.fstatSync(moduleFd, { bigint: true });",+ `if (moduleSource.length > ${MAX_AGENT_COMMAND_BYTES} || moduleSource.length !== admittedModuleBytes || BigInt(moduleSource.length) !== metadataAfter.size || metadataBefore.dev !== metadataAfter.dev || metadataBefore.ino !== metadataAfter.ino || metadataBefore.size !== metadataAfter.size || metadataBefore.mtimeNs !== metadataAfter.mtimeNs || metadataBefore.ctimeNs !== metadataAfter.ctimeNs) { const error = new Error("ACPX provider module changed while it was read"); error.code = "ERR_ACPX_UNVERIFIED_MODULE"; throw error; }`,+ "return { format: moduleFormat, source: moduleSource, shortCircuit: true };",+ "} finally { fs.closeSync(moduleFd); }",+ "});",+ "} });",+ "import(target).catch((error) => { console.error(error); process.exitCode = 1; });",+ ].join("");+}++export function guardSnapshotModuleLookup<T>(+ platform: NodeJS.Platform,+ filesystemLookup: boolean,+ lookup: () => T,+): T {+ if (platform !== "linux" && filesystemLookup) {+ throw new Error(+ "ACPX provider relative module loading requires Linux descriptor-pinned paths",+ );+ }+ return lookup();+}++/** Refuse filesystem modules that are not reached through a retained directory. */+export function guardSnapshotModuleResolution(+ builtin: boolean,+ resolvedUrl: unknown,+ descriptorAuthorized: boolean,+): void {+ if (+ !builtin &&+ typeof resolvedUrl === "string" &&+ resolvedUrl.startsWith("file:") &&+ !descriptorAuthorized+ ) {+ const error = new Error(+ "ACPX provider module escaped descriptor-pinned ancestry",+ );+ Object.assign(error, { code: "ERR_ACPX_UNVERIFIED_MODULE" });+ throw error;+ }+}++/** Locate a module URL within the command directory or retained ancestry. */+export function snapshotDescriptorAncestorIndex(+ resolvedUrl: unknown,+ commandDirectoryUrl: string,+ dependencyDirectoryUrls: readonly string[],+): number {+ if (typeof resolvedUrl !== "string") return -1;+ if (resolvedUrl.startsWith(commandDirectoryUrl)) return 0;+ return dependencyDirectoryUrls.findIndex((dependencyDirectoryUrl) =>+ resolvedUrl.startsWith(dependencyDirectoryUrl),+ );+}++/** Classify a canonical resolution and repin it to its retained descriptor. */+export function snapshotDescriptorResolution(+ resolvedUrl: unknown,+ commandDirectoryUrl: string,+ dependencyDirectoryUrls: readonly string[],+ canonicalCommandDirectoryUrl: string,+ canonicalDependencyDirectoryUrls: readonly string[],+): { url: string; ancestorIndex: number } | null {+ if (typeof resolvedUrl !== "string") return null;+ const descriptorIndex = snapshotDescriptorAncestorIndex(+ resolvedUrl,+ commandDirectoryUrl,+ dependencyDirectoryUrls,+ );+ if (descriptorIndex >= 0) {+ return { url: resolvedUrl, ancestorIndex: descriptorIndex };+ }+ if (+ canonicalDependencyDirectoryUrls.length !==+ dependencyDirectoryUrls.length ||+ !canonicalCommandDirectoryUrl.startsWith("file:") ||+ canonicalDependencyDirectoryUrls.some(+ (canonicalUrl) =>+ typeof canonicalUrl !== "string" || !canonicalUrl.startsWith("file:"),+ ) ||+ resolvedUrl.startsWith(new URL("../", commandDirectoryUrl).href)+ ) {+ return null;+ }+ if (resolvedUrl.startsWith(canonicalCommandDirectoryUrl)) {+ return {+ url:+ commandDirectoryUrl ++ resolvedUrl.slice(canonicalCommandDirectoryUrl.length),+ ancestorIndex: 0,+ };+ }+ const ancestorIndex = canonicalDependencyDirectoryUrls.findIndex(+ (canonicalUrl) => resolvedUrl.startsWith(canonicalUrl),+ );+ if (ancestorIndex < 0) return null;+ return {+ url:+ dependencyDirectoryUrls[ancestorIndex]! ++ resolvedUrl.slice(+ canonicalDependencyDirectoryUrls[ancestorIndex]!.length,+ ),+ ancestorIndex,+ };+}++function executableFormat(+ relativeCommand: string,+ packageType: unknown,+ agent: string,+): AcpxCommandFormat {+ const extension = extname(relativeCommand);+ if (extension === ".mjs") return "module";+ if (extension === ".cjs") return "commonjs";+ if (extension === ".js") {+ if (packageType === undefined || packageType === "commonjs") {+ return "commonjs";+ }+ if (packageType === "module") return "module";+ }+ throw new Error(`ACPX ${agent} package exposes an unsupported executable`);+}++function packageModuleFormat(packageType: unknown): AcpxCommandFormat {+ return packageType === "module" ? "module" : "commonjs";+}++function fileIdentity(metadata: {+ dev: bigint;+ ino: bigint;+ size: bigint;+ mtimeNs: bigint;+ ctimeNs: bigint;+}): VerifiedAcpxCommandIdentity {+ return {+ device: metadata.dev.toString(),+ inode: metadata.ino.toString(),+ size: metadata.size.toString(),+ modifiedNanoseconds: metadata.mtimeNs.toString(),+ changedNanoseconds: metadata.ctimeNs.toString(),+ };+}++function directoryIdentity(metadata: {+ dev: bigint;+ ino: bigint;+}): VerifiedAcpxDirectoryIdentity {+ return {+ device: metadata.dev.toString(),+ inode: metadata.ino.toString(),+ };+}++function sameDirectoryIdentity(+ left: VerifiedAcpxDirectoryIdentity,+ right: VerifiedAcpxDirectoryIdentity,+): boolean {+ return left.device === right.device && left.inode === right.inode;+}++function sameIdentity(+ left: VerifiedAcpxCommandIdentity,+ right: VerifiedAcpxCommandIdentity,+): boolean {+ return (+ left.device === right.device &&+ left.inode === right.inode &&+ left.size === right.size &&+ left.modifiedNanoseconds === right.modifiedNanoseconds &&+ left.changedNanoseconds === right.changedNanoseconds+ );+}++function oneExecutable(value: unknown, agent: string): string {+ const candidates =+ typeof value === "string"+ ? [value]+ : typeof value === "object" && value !== null && !Array.isArray(value)+ ? Object.values(value).filter(+ (candidate): candidate is string => typeof candidate === "string",+ )+ : [];+ const unique = Array.from(new Set(candidates));+ if (+ unique.length !== 1 ||+ unique[0]!.length === 0 ||+ unique[0]!.includes("\0") ||+ isAbsolute(unique[0]!)+ ) {+ throw new Error(+ `ACPX ${agent} package must expose one relative executable`,+ );+ }+ return unique[0]!;+}++function isInside(parent: string, child: string): boolean {+ const relativePath = relative(resolve(parent), resolve(child));+ return (+ relativePath.length > 0 &&+ relativePath !== ".." &&+ !relativePath.startsWith(+ `..${process.platform === "win32" ? "\\" : "/"}`,+ ) &&+ !isAbsolute(relativePath)+ );+}++function isInsideOrEqual(parent: string, child: string): boolean {+ return resolve(parent) === resolve(child) || isInside(parent, child);+}