chainlesschain 0.162.180 → 0.162.182

package/src/lib/process-execution-broker/credential-agent.js

@@ -6,12 +6,14 @@
  * receives short-lived opaque references. Resolving a reference requires an
  * attested agent id and the exact process/host target recorded at issuance.
  *
- * This module deliberately does not claim to provide an OS IPC transport. A
- * future broker-owned IPC implementation can call resolveCredentialRef() after
- * it has authenticated the requesting process and destination host.
+ * The production singleton also mirrors issued references into a broker-owned
+ * authenticated local transport. Per-launch capability tokens bind resolution
+ * to the approved process and destination host without putting credential
+ * values in the child environment or argv.
  */
 
 import crypto from "node:crypto";
+import { CredentialTransport } from "./credential-transport.js";
 
 const REDACTED_VALUE = "***REDACTED***";
 const DEFAULT_TTL_MS = 60_000;
@@ -33,6 +35,7 @@ const CREDENTIAL_ERROR_CODES = Object.freeze({
   REVOKED: "CC_CREDENTIAL_REF_REVOKED",
   AGENT_MISMATCH: "CC_CREDENTIAL_AGENT_MISMATCH",
   TARGET_MISMATCH: "CC_CREDENTIAL_TARGET_MISMATCH",
+  TRANSPORT_UNAVAILABLE: "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
 });
 
 // Patterns for environment variables that contain secrets.
@@ -126,6 +129,10 @@ const RESERVED_AGENT_ENV_KEYS = new Set([
   "CC_CREDENTIAL_AGENT_ID",
   "CC_CREDENTIAL_PROXY",
   "CC_CREDENTIAL_TRANSPORT",
+  "CC_CREDENTIAL_ENDPOINT",
+  "CC_CREDENTIAL_AUTH_TOKEN",
+  "CC_CREDENTIAL_TARGET_PROCESS",
+  "CC_CREDENTIAL_TARGET_HOST",
 ]);
 
 function credentialError(code, message) {
@@ -251,9 +258,21 @@ class CredentialAgent {
       Number.MAX_SAFE_INTEGER,
     );
 
-    // "broker-api" is an in-process primitive, not a socket/pipe endpoint.
-    this._transport = "broker-api";
-    this._proxyReady = false;
+    this._transportMode = "broker-api";
+    this._credentialTransport = null;
+    if (options.transport) {
+      this._credentialTransport =
+        options.transport === true
+          ? new CredentialTransport({
+              agentId: this._agentId,
+              onAudit: (entry) => this._recordAudit(entry),
+              onSettlement: (settlement) =>
+                this._applyTransportSettlement(settlement),
+            })
+          : options.transport;
+      this._transportMode =
+        this._credentialTransport?.version || "local-ipc-v1";
+    }
     this._lastEnabledState = this._computeEnabled();
   }
 
@@ -270,10 +289,11 @@ class CredentialAgent {
 
     if (!enabled) {
       let revoked = 0;
-      for (const record of this._credentialStore.values()) {
+      for (const [refId, record] of this._credentialStore) {
         if (record.status === "active") {
           record.value = null;
           record.status = "disabled";
+          this._credentialTransport?.revokeCredential(refId);
           revoked += 1;
         }
       }
@@ -387,6 +407,19 @@ class CredentialAgent {
     }
   }
 
+  _applyTransportSettlement(settlement) {
+    const record = this._credentialStore.get(settlement?.refId);
+    if (!record || record.status !== "active") return;
+    const useCount = Number(settlement.useCount);
+    if (Number.isFinite(useCount) && useCount > record.useCount) {
+      record.useCount = useCount;
+    }
+    if (settlement.status && settlement.status !== "active") {
+      record.status = settlement.status;
+      record.value = null;
+    }
+  }
+
   _ensureStoreCapacity() {
     this._expireStaleCredentials();
     if (this._credentialStore.size < this._maxCredentials) return;
@@ -447,6 +480,9 @@ class CredentialAgent {
         "Credential maxUses",
       ),
       origin: String(request.origin ?? "unknown"),
+      capabilityToken: request.capabilityToken
+        ? String(request.capabilityToken)
+        : null,
     };
   }
 
@@ -556,6 +592,38 @@ class CredentialAgent {
       target: normalized.target,
       approvalFingerprint: this._fingerprint(normalized.approvalId),
     });
+    if (this._credentialTransport && normalized.capabilityToken) {
+      try {
+        this._credentialTransport.registerCredential({
+          refId,
+          key: normalized.key,
+          value: normalized.value,
+          target: normalized.target,
+          createdAt,
+          expiresAt: createdAt + normalized.ttlMs,
+          maxUses: normalized.maxUses,
+          useCount: 0,
+          status: "active",
+          capabilityToken: normalized.capabilityToken,
+        });
+      } catch (error) {
+        const record = this._credentialStore.get(refId);
+        record.value = null;
+        record.status = "revoked";
+        this._recordAudit({
+          event: "credential_ref_issue",
+          outcome: "denied",
+          reason: CREDENTIAL_ERROR_CODES.TRANSPORT_UNAVAILABLE,
+          key: normalized.key,
+          target: normalized.target,
+          refFingerprint: this._fingerprint(refId),
+        });
+        throw credentialError(
+          CREDENTIAL_ERROR_CODES.TRANSPORT_UNAVAILABLE,
+          error?.message || "Credential transport is unavailable",
+        );
+      }
+    }
     this._recordAudit({
       event: "credential_ref_issue",
       outcome: "allowed",
@@ -695,6 +763,7 @@ class CredentialAgent {
       record.value = null;
       record.status = "exhausted";
     }
+    this._credentialTransport?.updateCredential(refId, record);
     this._recordAudit({
       event: "credential_ref_resolve",
       outcome: "allowed",
@@ -717,6 +786,7 @@ class CredentialAgent {
     if (!record) return false;
     record.value = null;
     record.status = "revoked";
+    this._credentialTransport?.revokeCredential(refId);
     this._recordAudit({
       event: "credential_ref_revoke",
       outcome: "allowed",
@@ -786,9 +856,18 @@ class CredentialAgent {
     );
   }
 
-  _setReferenceMarkers(safeEnv) {
+  _setReferenceMarkers(safeEnv, context) {
     safeEnv.CC_CREDENTIAL_AGENT_ID = this._agentId;
-    safeEnv.CC_CREDENTIAL_TRANSPORT = this._transport;
+    safeEnv.CC_CREDENTIAL_TRANSPORT = this._transportMode;
+    if (this._credentialTransport && context?.capabilityToken) {
+      safeEnv.CC_CREDENTIAL_ENDPOINT = this._credentialTransport.endpoint;
+      safeEnv.CC_CREDENTIAL_AUTH_TOKEN = context.capabilityToken;
+      safeEnv.CC_CREDENTIAL_TARGET_PROCESS = normalizeProcessTarget(
+        context.target?.process ?? context.process,
+      );
+      const host = normalizeHostTarget(context.target?.host ?? context.host);
+      if (host) safeEnv.CC_CREDENTIAL_TARGET_HOST = host;
+    }
   }
 
   /**
@@ -830,7 +909,7 @@ class CredentialAgent {
       redacted.push(entry);
     }
 
-    if (refsIssued > 0) this._setReferenceMarkers(safeEnv);
+    if (refsIssued > 0) this._setReferenceMarkers(safeEnv, context);
     return {
       safeEnv,
       redacted,
@@ -984,7 +1063,17 @@ class CredentialAgent {
       );
     }
 
-    const context = this._contextForSpawn(spawnOptions);
+    let context = this._contextForSpawn(spawnOptions);
+    if (
+      this._credentialTransport &&
+      this.isEnabled() &&
+      this._canIssueForContext(context)
+    ) {
+      context = {
+        ...context,
+        capabilityToken: this._credentialTransport.createCapabilityToken(),
+      };
+    }
     const env = spawnOptions.env || process.env;
     const {
       safeEnv,
@@ -1019,7 +1108,7 @@ class CredentialAgent {
     }
 
     const refsIssued = envRefsIssued + argRefsIssued;
-    if (refsIssued > 0) this._setReferenceMarkers(safeEnv);
+    if (refsIssued > 0) this._setReferenceMarkers(safeEnv, context);
     spawnOptions.env = safeEnv;
     spawnOptions.args = sanitizedArgs;
 
@@ -1094,6 +1183,14 @@ class CredentialAgent {
     this._accessLog = [];
   }
 
+  waitForTransportReady() {
+    return this._credentialTransport?.waitUntilReady() ?? Promise.resolve(null);
+  }
+
+  closeTransport() {
+    return this._credentialTransport?.close() ?? Promise.resolve();
+  }
+
   /**
    * Get credential agent info for status reporting. No raw references or
    * credential values are included.
@@ -1111,9 +1208,10 @@ class CredentialAgent {
       mode: this._lastEnabledState
         ? "broker-reference"
         : "redact-only-disabled",
-      transport: this._transport,
-      proxyReady: this._proxyReady,
-      ipcAvailable: false,
+      transport: this._transportMode,
+      proxyReady: this._credentialTransport?.ready === true,
+      ipcAvailable: this._credentialTransport?.isAvailable() === true,
+      transportInfo: this._credentialTransport?.getInfo() || null,
       credentialsTracked: this._credentialStore.size,
       activeCredentials: statusCounts.active || 0,
       accessCount: this._accessLog.length,
@@ -1126,7 +1224,7 @@ class CredentialAgent {
   }
 }
 
-const credentialAgent = new CredentialAgent();
+const credentialAgent = new CredentialAgent({ transport: true });
 
 export {
   credentialAgent,

package/src/lib/process-execution-broker/credential-transport-worker.js

@@ -0,0 +1,312 @@
+/**
+ * Broker-owned credential transport worker.
+ *
+ * The worker owns the local named-pipe / Unix-domain-socket server so it can
+ * answer a child while the broker's main thread is blocked in spawnSync().
+ * Credential values never enter the spawned command's argv or environment.
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import { parentPort, workerData } from "node:worker_threads";
+
+const MAX_FRAME_BYTES = 1024 * 1024;
+const records = new Map();
+const endpoint = workerData.endpoint;
+const agentId = workerData.agentId;
+const platform = workerData.platform;
+
+function normalizeProcessTarget(value) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) return null;
+  return platform === "win32"
+    ? normalized.replaceAll("/", "\\").toLowerCase()
+    : normalized;
+}
+
+function normalizeHostTarget(value) {
+  const candidate = String(value ?? "").trim();
+  if (!candidate) return null;
+  try {
+    const parsed = candidate.includes("://")
+      ? new URL(candidate)
+      : new URL(`https://${candidate}`);
+    return parsed.hostname.toLowerCase().replace(/\.$/, "");
+  } catch {
+    return candidate.toLowerCase().replace(/\.$/, "");
+  }
+}
+
+function fingerprint(value) {
+  return crypto
+    .createHash("sha256")
+    .update(String(value ?? ""))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+function capabilityMatches(expected, supplied) {
+  const expectedBuffer = Buffer.from(String(expected ?? ""));
+  const suppliedBuffer = Buffer.from(String(supplied ?? ""));
+  return (
+    expectedBuffer.length > 0 &&
+    expectedBuffer.length === suppliedBuffer.length &&
+    crypto.timingSafeEqual(expectedBuffer, suppliedBuffer)
+  );
+}
+
+function send(socket, message) {
+  if (!socket.destroyed) {
+    socket.end(`${JSON.stringify(message)}\n`);
+  }
+}
+
+function deny(socket, code, message, record, refId) {
+  parentPort.postMessage({
+    type: "audit",
+    entry: {
+      event: "credential_transport_resolve",
+      outcome: "denied",
+      reason: code,
+      key: record?.key,
+      target: record?.target,
+      refFingerprint: fingerprint(refId),
+    },
+  });
+  send(socket, { ok: false, code, message });
+}
+
+function handleResolution(socket, request) {
+  const refId = typeof request.refId === "string" ? request.refId : "";
+  const record = records.get(refId);
+  if (!record) {
+    deny(
+      socket,
+      "CC_CREDENTIAL_REF_NOT_FOUND",
+      "Credential reference was not found",
+      null,
+      refId,
+    );
+    return;
+  }
+  if (
+    request.agentId !== agentId ||
+    !capabilityMatches(record.capabilityToken, request.capabilityToken)
+  ) {
+    deny(
+      socket,
+      "CC_CREDENTIAL_TRANSPORT_UNAUTHORIZED",
+      "Credential transport authentication failed",
+      record,
+      refId,
+    );
+    return;
+  }
+
+  const requestTarget = {
+    process: normalizeProcessTarget(request.process),
+    host: normalizeHostTarget(request.host),
+  };
+  if (
+    !requestTarget.process ||
+    requestTarget.process !== record.target.process ||
+    requestTarget.host !== record.target.host
+  ) {
+    deny(
+      socket,
+      "CC_CREDENTIAL_TARGET_MISMATCH",
+      "Credential resolution target does not match",
+      record,
+      refId,
+    );
+    return;
+  }
+
+  if (record.status !== "active") {
+    const code =
+      record.status === "expired"
+        ? "CC_CREDENTIAL_REF_EXPIRED"
+        : record.status === "exhausted"
+          ? "CC_CREDENTIAL_REF_EXHAUSTED"
+          : "CC_CREDENTIAL_REF_REVOKED";
+    deny(socket, code, "Credential reference is not active", record, refId);
+    return;
+  }
+  if (Date.now() >= record.expiresAt) {
+    record.status = "expired";
+    record.value = null;
+    deny(
+      socket,
+      "CC_CREDENTIAL_REF_EXPIRED",
+      "Credential reference has expired",
+      record,
+      refId,
+    );
+    return;
+  }
+  if (record.useCount >= record.maxUses) {
+    record.status = "exhausted";
+    record.value = null;
+    deny(
+      socket,
+      "CC_CREDENTIAL_REF_EXHAUSTED",
+      "Credential reference usage limit has been reached",
+      record,
+      refId,
+    );
+    return;
+  }
+
+  const value = record.value;
+  record.useCount += 1;
+  const remainingUses = record.maxUses - record.useCount;
+  if (remainingUses <= 0) {
+    record.status = "exhausted";
+    record.value = null;
+  }
+  parentPort.postMessage({
+    type: "audit",
+    entry: {
+      event: "credential_transport_resolve",
+      outcome: "allowed",
+      key: record.key,
+      target: record.target,
+      refFingerprint: fingerprint(refId),
+      useCount: record.useCount,
+      remainingUses: Math.max(remainingUses, 0),
+    },
+  });
+  parentPort.postMessage({
+    type: "settlement",
+    refId,
+    useCount: record.useCount,
+    status: record.status,
+  });
+  send(socket, { ok: true, value });
+}
+
+if (platform !== "win32") {
+  try {
+    fs.unlinkSync(endpoint);
+  } catch {
+    // A socket normally does not exist on first start.
+  }
+}
+
+const server = net.createServer((socket) => {
+  let carry = "";
+  let handled = false;
+  socket.setTimeout(5000, () => socket.destroy());
+  socket.on("data", (chunk) => {
+    if (handled) return;
+    carry += chunk.toString("utf8");
+    if (Buffer.byteLength(carry, "utf8") > MAX_FRAME_BYTES) {
+      handled = true;
+      deny(
+        socket,
+        "CC_CREDENTIAL_INVALID_REQUEST",
+        "Credential transport request is too large",
+        null,
+        "",
+      );
+      return;
+    }
+    const newline = carry.indexOf("\n");
+    if (newline === -1) return;
+    handled = true;
+    const line = carry.slice(0, newline).replace(/\r$/, "");
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      deny(
+        socket,
+        "CC_CREDENTIAL_INVALID_REQUEST",
+        "Credential transport request is not valid JSON",
+        null,
+        "",
+      );
+      return;
+    }
+    if (!request || request.type !== "resolve") {
+      deny(
+        socket,
+        "CC_CREDENTIAL_INVALID_REQUEST",
+        "Credential transport request type is invalid",
+        null,
+        request?.refId,
+      );
+      return;
+    }
+    handleResolution(socket, request);
+  });
+  socket.on("error", () => {
+    // Per-client failures must not take down the credential service.
+  });
+});
+
+server.on("error", (error) => {
+  parentPort.postMessage({
+    type: "fatal",
+    error: {
+      code: error.code || "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+      message: error.message,
+    },
+  });
+});
+
+server.listen(endpoint, () => {
+  if (platform !== "win32") {
+    try {
+      fs.chmodSync(endpoint, 0o600);
+    } catch {
+      // The random per-launch capability remains mandatory if chmod is absent.
+    }
+  }
+  parentPort.postMessage({ type: "ready", endpoint });
+});
+
+parentPort.on("message", (message) => {
+  if (!message || typeof message !== "object") return;
+  if (message.type === "register") {
+    records.set(message.record.refId, {
+      ...message.record,
+      target: {
+        process: normalizeProcessTarget(message.record.target?.process),
+        host: normalizeHostTarget(message.record.target?.host),
+      },
+    });
+    return;
+  }
+  if (message.type === "update") {
+    const record = records.get(message.refId);
+    if (!record) return;
+    record.useCount = message.useCount;
+    record.status = message.status;
+    if (record.status !== "active") record.value = null;
+    return;
+  }
+  if (message.type === "revoke") {
+    const record = records.get(message.refId);
+    if (!record) return;
+    record.status = "revoked";
+    record.value = null;
+    return;
+  }
+  if (message.type === "close") {
+    for (const record of records.values()) record.value = null;
+    records.clear();
+    server.close(() => {
+      if (platform !== "win32") {
+        try {
+          fs.unlinkSync(endpoint);
+        } catch {
+          // The socket may already have been removed.
+        }
+      }
+      parentPort.postMessage({ type: "closed" });
+      parentPort.close();
+    });
+  }
+});