chainlesschain 0.162.181 → 0.162.182

package/src/lib/process-execution-broker/index.js

@@ -38,6 +38,7 @@ import {
   postSpawnSandbox as _postSpawnSandbox,
   SANDBOX_BOUNDARIES,
 } from "./platform-sandbox.js";
+import { consumeIssuedPluginSandboxExecutionContract } from "../plugin-runtime/bin.js";
 import { credentialAgent } from "./credential-agent.js";
 
 const SUPPORTED_SANDBOX_BOUNDARIES = new Set(Object.values(SANDBOX_BOUNDARIES));
@@ -197,6 +198,222 @@ class ProcessExecutionBroker extends EventEmitter {
     return safe;
   }
 
+  _normalizePluginExecutableIdentity(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const realPath =
+      typeof raw.realPath === "string" && raw.realPath ? raw.realPath : null;
+    const sha256 =
+      typeof raw.sha256 === "string" && /^[a-f0-9]{64}$/i.test(raw.sha256)
+        ? raw.sha256.toLowerCase()
+        : null;
+    if (!realPath || !sha256) return null;
+    return {
+      contractVersion: 1,
+      realPath,
+      sha256,
+      bytes:
+        Number.isSafeInteger(raw.bytes) && raw.bytes >= 0 ? raw.bytes : null,
+      fileId:
+        raw.dev !== undefined && raw.ino !== undefined
+          ? {
+              dev: String(raw.dev),
+              ino: String(raw.ino),
+            }
+          : null,
+      mtimeMs: Number.isFinite(raw.mtimeMs) ? raw.mtimeMs : null,
+      attestation: "realpath-file-id-sha256",
+    };
+  }
+
+  _freezeExecutableIdentity(identity) {
+    if (!identity) return null;
+    return Object.freeze({
+      ...identity,
+      fileId: identity.fileId ? Object.freeze({ ...identity.fileId }) : null,
+    });
+  }
+
+  _normalizePluginRootIdentity(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+    if (
+      typeof raw.realPath !== "string" ||
+      !raw.realPath ||
+      raw.dev === undefined ||
+      raw.ino === undefined
+    ) {
+      return null;
+    }
+    return Object.freeze({
+      realPath: raw.realPath,
+      fileId: Object.freeze({
+        dev: String(raw.dev),
+        ino: String(raw.ino),
+      }),
+      attestation: "realpath-directory-file-id",
+    });
+  }
+
+  /**
+   * Normalize the private execution contract produced by agent-core for one
+   * direct, already-attested strict Plugin Node or static-native bin. Plugin
+   * manifests cannot provide this top-level option; they can only add
+   * required boundaries.
+   */
+  _normalizeSandboxExecutionContract(raw, options, requiredBoundaries, launch) {
+    if (raw === undefined) return null;
+    const invalid = (message) => {
+      throw this._sandboxBoundaryError(
+        "invalid_sandbox_execution_contract",
+        message,
+        {
+          requiredBoundaries,
+          missingBoundaries: requiredBoundaries,
+        },
+      );
+    };
+    if (
+      !consumeIssuedPluginSandboxExecutionContract(raw, {
+        origin: options.origin,
+        command: launch?.command,
+        args: launch?.args,
+        cwd: options.cwd,
+        pluginId: options.pluginId,
+        pluginVersion: options.pluginVersion,
+        pluginSource: options.pluginSource,
+        pluginExecutableIdentity: options.pluginExecutableIdentity,
+        requiredBoundaries,
+        sync: launch?.sync === true,
+      })
+    ) {
+      return invalid(
+        "sandboxExecutionContract was not issued for this plugin launch provenance",
+      );
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      return invalid("sandboxExecutionContract must be an object");
+    }
+    const supportedKeys = new Set([
+      "contractVersion",
+      "kind",
+      "pluginRoot",
+      "workingDirectory",
+      "runtimePath",
+      "rootIdentity",
+      "entryIdentity",
+      "runtimeIdentity",
+    ]);
+    const unsupportedKey = Object.keys(raw).find(
+      (key) => !supportedKeys.has(key),
+    );
+    if (unsupportedKey) {
+      return invalid(
+        `sandboxExecutionContract contains unsupported field: ${unsupportedKey}`,
+      );
+    }
+    if (
+      raw.contractVersion !== 1 ||
+      ![
+        "strict-plugin-node-bin",
+        "strict-plugin-native-static-elf-bin",
+      ].includes(raw.kind)
+    ) {
+      return invalid("unsupported sandboxExecutionContract kind or version");
+    }
+    if (
+      options.origin !== "plugin:bin" ||
+      typeof options.pluginId !== "string" ||
+      !options.pluginId ||
+      options.shell !== false
+    ) {
+      return invalid(
+        "sandboxExecutionContract is restricted to direct plugin:bin shell:false launches",
+      );
+    }
+
+    for (const [label, value] of [
+      ["pluginRoot", raw.pluginRoot],
+      ["workingDirectory", raw.workingDirectory],
+      ["runtimePath", raw.runtimePath],
+    ]) {
+      if (
+        typeof value !== "string" ||
+        !value ||
+        value.includes("\0") ||
+        !path.isAbsolute(value)
+      ) {
+        return invalid(`sandboxExecutionContract.${label} must be absolute`);
+      }
+    }
+    const entryIdentity = this._normalizePluginExecutableIdentity(
+      raw.entryIdentity,
+    );
+    const runtimeIdentity = this._normalizePluginExecutableIdentity(
+      raw.runtimeIdentity,
+    );
+    const rootIdentity = this._normalizePluginRootIdentity(raw.rootIdentity);
+    if (!rootIdentity || !entryIdentity || !runtimeIdentity) {
+      return invalid(
+        "sandboxExecutionContract requires attested root, entry, and runtime identities",
+      );
+    }
+    if (
+      rootIdentity.realPath !== raw.pluginRoot ||
+      raw.runtimeIdentity?.requestedPath !== path.resolve(process.execPath) ||
+      raw.runtimePath !== runtimeIdentity.realPath ||
+      !path.isAbsolute(entryIdentity.realPath) ||
+      !path.isAbsolute(runtimeIdentity.realPath)
+    ) {
+      return invalid(
+        "sandboxExecutionContract identity paths do not match the launch contract",
+      );
+    }
+
+    const provenanceIdentity = this._normalizePluginExecutableIdentity(
+      options.pluginExecutableIdentity,
+    );
+    if (
+      !provenanceIdentity ||
+      provenanceIdentity.realPath !== entryIdentity.realPath ||
+      provenanceIdentity.sha256 !== entryIdentity.sha256
+    ) {
+      return invalid(
+        "sandboxExecutionContract entry identity does not match plugin provenance",
+      );
+    }
+    const entryRelative = path.relative(
+      path.resolve(raw.pluginRoot),
+      path.resolve(entryIdentity.realPath),
+    );
+    if (
+      entryRelative === "" ||
+      entryRelative === ".." ||
+      entryRelative.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(entryRelative)
+    ) {
+      return invalid(
+        "sandboxExecutionContract entry must be inside pluginRoot",
+      );
+    }
+
+    return Object.freeze({
+      contractVersion: 1,
+      kind: raw.kind,
+      pluginRoot: raw.pluginRoot,
+      workingDirectory: raw.workingDirectory,
+      runtimePath: raw.runtimePath,
+      rootIdentity,
+      entryIdentity: this._freezeExecutableIdentity(entryIdentity),
+      runtimeIdentity: this._freezeExecutableIdentity(runtimeIdentity),
+    });
+  }
+
+  _stripPluginControlOptions(options) {
+    delete options.pluginId;
+    delete options.pluginVersion;
+    delete options.pluginSource;
+    delete options.pluginExecutableIdentity;
+  }
+
   _sandboxStrictEnabled() {
     return process.env.CC_SANDBOX_STRICT === "1";
   }
@@ -213,7 +430,7 @@ class ProcessExecutionBroker extends EventEmitter {
    * @param {Object} options
    * @returns {{profile: "default"|"strict"|"network-only"|null, requiredBoundaries: string[]}}
    */
-  _normalizeSandboxPolicy(options = {}) {
+  _normalizeSandboxPolicy(options = {}, launch = {}) {
     const rawPolicy = options.sandboxPolicy;
     if (
       rawPolicy !== undefined &&
@@ -269,12 +486,19 @@ class ProcessExecutionBroker extends EventEmitter {
         { requiredBoundaries },
       );
     }
-    return { profile, requiredBoundaries };
+    const executionContract = this._normalizeSandboxExecutionContract(
+      options.sandboxExecutionContract,
+      options,
+      requiredBoundaries,
+      launch,
+    );
+    return { profile, requiredBoundaries, executionContract };
   }
 
   _stripSandboxControlOptions(options) {
     delete options.sandboxPolicy;
     delete options.requiredBoundaries;
+    delete options.sandboxExecutionContract;
   }
 
   _sandboxUnavailablePlan(command, args, options, reason, sandboxPolicy = {}) {
@@ -318,6 +542,7 @@ class ProcessExecutionBroker extends EventEmitter {
       typeof metadata.sandboxPolicyAttested === "boolean"
         ? metadata.sandboxPolicyAttested
         : null;
+    error.sandboxPolicyDigest = metadata.sandboxPolicyDigest || null;
     error.sandboxCandidateReason = metadata.sandboxCandidateReason || null;
     return error;
   }
@@ -400,6 +625,16 @@ class ProcessExecutionBroker extends EventEmitter {
         "Sandbox policy attestation must be boolean",
       );
     }
+    const policyDigest = plan.policyDigest ?? null;
+    if (
+      policyDigest !== null &&
+      (typeof policyDigest !== "string" || !/^[a-f0-9]{64}$/.test(policyDigest))
+    ) {
+      throw this._sandboxError(
+        "invalid_sandbox_plan",
+        "Sandbox policy digest must be a lowercase SHA-256 value",
+      );
+    }
     let runtimeProbe = null;
     if (plan.runtimeProbe !== null && plan.runtimeProbe !== undefined) {
       if (
@@ -416,11 +651,62 @@ class ProcessExecutionBroker extends EventEmitter {
           "Sandbox runtime probe must use the typed probe contract",
         );
       }
+      for (const field of [
+        "probeRuntime",
+        "targetRuntime",
+        "contentSnapshotScope",
+        "contentSnapshotMechanism",
+      ]) {
+        if (
+          plan.runtimeProbe[field] !== undefined &&
+          (typeof plan.runtimeProbe[field] !== "string" ||
+            !plan.runtimeProbe[field])
+        ) {
+          throw this._sandboxError(
+            "invalid_sandbox_plan",
+            `Sandbox runtime probe ${field} must be a non-empty string`,
+          );
+        }
+      }
+      for (const field of ["contentSnapshot", "handleAtomic"]) {
+        if (
+          plan.runtimeProbe[field] !== undefined &&
+          typeof plan.runtimeProbe[field] !== "boolean"
+        ) {
+          throw this._sandboxError(
+            "invalid_sandbox_plan",
+            `Sandbox runtime probe ${field} must be boolean`,
+          );
+        }
+      }
       runtimeProbe = {
         kind: plan.runtimeProbe.kind,
         attempted: plan.runtimeProbe.attempted,
         runnable: plan.runtimeProbe.runnable,
         reason: plan.runtimeProbe.reason,
+        ...(plan.runtimeProbe.probeRuntime !== undefined
+          ? { probeRuntime: plan.runtimeProbe.probeRuntime }
+          : {}),
+        ...(plan.runtimeProbe.targetRuntime !== undefined
+          ? { targetRuntime: plan.runtimeProbe.targetRuntime }
+          : {}),
+        ...(plan.runtimeProbe.contentSnapshot !== undefined
+          ? { contentSnapshot: plan.runtimeProbe.contentSnapshot }
+          : {}),
+        ...(plan.runtimeProbe.handleAtomic !== undefined
+          ? { handleAtomic: plan.runtimeProbe.handleAtomic }
+          : {}),
+        ...(plan.runtimeProbe.contentSnapshotScope !== undefined
+          ? {
+              contentSnapshotScope: plan.runtimeProbe.contentSnapshotScope,
+            }
+          : {}),
+        ...(plan.runtimeProbe.contentSnapshotMechanism !== undefined
+          ? {
+              contentSnapshotMechanism:
+                plan.runtimeProbe.contentSnapshotMechanism,
+            }
+          : {}),
       };
     }
     const postSpawn = plan.postSpawn || { required: false, mode: "none" };
@@ -442,6 +728,7 @@ class ProcessExecutionBroker extends EventEmitter {
       guarantees: [...new Set(guarantees)],
       candidateBackend,
       policyAttested,
+      policyDigest,
       runtimeProbe,
       postSpawn: { ...postSpawn },
     };
@@ -465,6 +752,7 @@ class ProcessExecutionBroker extends EventEmitter {
           sandboxCandidateBackend: plan.candidateBackend,
           sandboxRuntimeProbe: plan.runtimeProbe,
           sandboxPolicyAttested: plan.policyAttested,
+          sandboxPolicyDigest: plan.policyDigest,
           sandboxCandidateReason: plan.candidateBackend ? plan.reason : null,
         },
       );
@@ -517,55 +805,70 @@ class ProcessExecutionBroker extends EventEmitter {
     const adapterRequest = Object.freeze({
       profile,
       requiredBoundaries: Object.freeze([...requiredBoundaries]),
+      sync,
+      ...(sandboxPolicy.executionContract
+        ? { executionContract: sandboxPolicy.executionContract }
+        : {}),
     });
-    let plan = this._validateSandboxPlan(
-      // Keep the legacy string profile in argument four. The built-in adapter
-      // reserves argument five for runtime injection, so the typed request is
-      // additive in argument six and legacy injected adapters can ignore it.
-      this._sandboxAdapter.applySandbox(
-        command,
-        args || [],
-        options,
-        profile,
-        undefined,
-        adapterRequest,
-      ),
+    // Keep the legacy string profile in argument four. The built-in adapter
+    // reserves argument five for runtime injection, so the typed request is
+    // additive in argument six and legacy injected adapters can ignore it.
+    const rawPlan = this._sandboxAdapter.applySandbox(
+      command,
+      args || [],
+      options,
+      profile,
+      undefined,
+      adapterRequest,
     );
-    plan = this._assertRequiredSandboxBoundaries(plan, requiredBoundaries);
-
-    if (!plan.applied && strict) {
-      throw this._sandboxError(
-        plan.reason || "sandbox_unavailable",
-        `Sandbox is unavailable in strict mode: ${
-          plan.reason || "unknown reason"
-        }`,
-      );
-    }
+    let plan;
+    try {
+      plan = this._validateSandboxPlan(rawPlan);
+      plan = this._assertRequiredSandboxBoundaries(plan, requiredBoundaries);
 
-    if (plan.applied && plan.postSpawn.required) {
-      if (typeof this._sandboxAdapter.postSpawnSandbox !== "function") {
+      if (!plan.applied && strict) {
         throw this._sandboxError(
-          "post_spawn_adapter_unavailable",
-          "Required post-spawn sandbox adapter is unavailable",
+          plan.reason || "sandbox_unavailable",
+          `Sandbox is unavailable in strict mode: ${
+            plan.reason || "unknown reason"
+          }`,
         );
       }
-      if (sync) {
-        throw this._sandboxError(
-          "post_spawn_unavailable_for_sync",
-          "spawnSync cannot satisfy required post-spawn sandbox enforcement",
-        );
+
+      if (plan.applied && plan.postSpawn.required) {
+        if (typeof this._sandboxAdapter.postSpawnSandbox !== "function") {
+          throw this._sandboxError(
+            "post_spawn_adapter_unavailable",
+            "Required post-spawn sandbox adapter is unavailable",
+          );
+        }
+        if (sync) {
+          throw this._sandboxError(
+            "post_spawn_unavailable_for_sync",
+            "spawnSync cannot satisfy required post-spawn sandbox enforcement",
+          );
+        }
+        if (
+          (strict || requiredBoundaries.length > 0) &&
+          plan.postSpawn.mode !== "sync"
+        ) {
+          throw this._sandboxError(
+            "async_post_spawn_disallowed_in_strict_mode",
+            "Fail-closed sandbox enforcement requires synchronous post-spawn enforcement",
+          );
+        }
       }
-      if (
-        (strict || requiredBoundaries.length > 0) &&
-        plan.postSpawn.mode !== "sync"
-      ) {
-        throw this._sandboxError(
-          "async_post_spawn_disallowed_in_strict_mode",
-          "Fail-closed sandbox enforcement requires synchronous post-spawn enforcement",
-        );
+      return plan;
+    } catch (error) {
+      if (typeof rawPlan?.cleanup === "function") {
+        try {
+          rawPlan.cleanup();
+        } catch {
+          // Preserve the boundary/contract failure that prevented execution.
+        }
       }
+      throw error;
     }
-    return plan;
   }
 
   _applySandboxAudit(auditEntry, plan, applied) {
@@ -580,6 +883,7 @@ class ProcessExecutionBroker extends EventEmitter {
       : null;
     auditEntry.sandboxPolicyAttested =
       typeof plan?.policyAttested === "boolean" ? plan.policyAttested : null;
+    auditEntry.sandboxPolicyDigest = plan?.policyDigest || null;
     auditEntry.sandboxCandidateReason = plan?.candidateBackend
       ? plan?.reason || null
       : null;
@@ -616,6 +920,8 @@ class ProcessExecutionBroker extends EventEmitter {
       typeof error.sandboxPolicyAttested === "boolean"
         ? error.sandboxPolicyAttested
         : (auditEntry.sandboxPolicyAttested ?? null);
+    auditEntry.sandboxPolicyDigest =
+      error.sandboxPolicyDigest || auditEntry.sandboxPolicyDigest || null;
     auditEntry.sandboxCandidateReason =
       error.sandboxCandidateReason || auditEntry.sandboxCandidateReason || null;
     auditEntry.deniedReason = `sandbox-init-failed: ${error.message}`;
@@ -923,6 +1229,9 @@ class ProcessExecutionBroker extends EventEmitter {
       pluginId: options.pluginId || null,
       pluginVersion: options.pluginVersion || null,
       pluginSource: options.pluginSource || null,
+      pluginExecutableIdentity: this._normalizePluginExecutableIdentity(
+        options.pluginExecutableIdentity,
+      ),
       sandboxRequired: [],
       sandboxGuarantees: [],
       sandboxBackend: null,
@@ -930,7 +1239,11 @@ class ProcessExecutionBroker extends EventEmitter {
 
     let sandboxPolicy;
     try {
-      sandboxPolicy = this._normalizeSandboxPolicy(options);
+      sandboxPolicy = this._normalizeSandboxPolicy(options, {
+        command,
+        args,
+        sync: false,
+      });
       auditEntry.sandboxRequired = [...sandboxPolicy.requiredBoundaries];
     } catch (sandboxPolicyError) {
       this._recordSandboxDenial(auditEntry, sandboxPolicyError, startTime);
@@ -966,6 +1279,7 @@ class ProcessExecutionBroker extends EventEmitter {
     // 传播traceparent环境变量
     const spawnOpts = this._sanitizeOptions(options);
     this._stripSandboxControlOptions(spawnOpts);
+    this._stripPluginControlOptions(spawnOpts);
     if (traceCtx) {
       spawnOpts.env = { ...(spawnOpts.env || process.env) };
       spawnOpts.env.TRACEPARENT = traceCtx.traceparent;
@@ -1138,6 +1452,9 @@ class ProcessExecutionBroker extends EventEmitter {
       pluginId: options.pluginId || null,
       pluginVersion: options.pluginVersion || null,
       pluginSource: options.pluginSource || null,
+      pluginExecutableIdentity: this._normalizePluginExecutableIdentity(
+        options.pluginExecutableIdentity,
+      ),
       sandboxRequired: [],
       sandboxGuarantees: [],
       sandboxBackend: null,
@@ -1145,7 +1462,11 @@ class ProcessExecutionBroker extends EventEmitter {
 
     let sandboxPolicy;
     try {
-      sandboxPolicy = this._normalizeSandboxPolicy(options);
+      sandboxPolicy = this._normalizeSandboxPolicy(options, {
+        command,
+        args,
+        sync: true,
+      });
       auditEntry.sandboxRequired = [...sandboxPolicy.requiredBoundaries];
     } catch (sandboxPolicyError) {
       this._recordSandboxDenial(auditEntry, sandboxPolicyError, startTime);
@@ -1174,6 +1495,7 @@ class ProcessExecutionBroker extends EventEmitter {
 
     const spawnOpts = this._sanitizeOptions(options);
     this._stripSandboxControlOptions(spawnOpts);
+    this._stripPluginControlOptions(spawnOpts);
     if (traceCtx) {
       spawnOpts.env = { ...(spawnOpts.env || process.env) };
       spawnOpts.env.TRACEPARENT = traceCtx.traceparent;
@@ -1291,10 +1613,17 @@ class ProcessExecutionBroker extends EventEmitter {
       pluginId: options.pluginId || null,
       pluginVersion: options.pluginVersion || null,
       pluginSource: options.pluginSource || null,
+      pluginExecutableIdentity: this._normalizePluginExecutableIdentity(
+        options.pluginExecutableIdentity,
+      ),
     };
     let sandboxPolicy;
     try {
-      sandboxPolicy = this._normalizeSandboxPolicy(options);
+      sandboxPolicy = this._normalizeSandboxPolicy(options, {
+        command,
+        args,
+        sync: false,
+      });
       auditEntry.sandboxRequired = [...sandboxPolicy.requiredBoundaries];
     } catch (sandboxPolicyError) {
       this._recordSandboxDenial(auditEntry, sandboxPolicyError, startTime);
@@ -1331,12 +1660,10 @@ class ProcessExecutionBroker extends EventEmitter {
 
     const spawnOptions = { ...options, args: [...auditEntry.args] };
     this._stripSandboxControlOptions(spawnOptions);
+    this._stripPluginControlOptions(spawnOptions);
     delete spawnOptions.origin;
     delete spawnOptions.policy;
     delete spawnOptions.scope;
-    delete spawnOptions.pluginId;
-    delete spawnOptions.pluginVersion;
-    delete spawnOptions.pluginSource;
     try {
       if (this._credentialBoundaryEnabled()) {
         spawnOptions.credentialContext = this._createCredentialContext(