chainlesschain 0.162.179 → 0.162.181

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();
+    });
+  }
+});

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

@@ -0,0 +1,378 @@
+/**
+ * Authenticated local transport for broker-issued credential references.
+ *
+ * A worker thread hosts the pipe so spawnSync children can resolve a reference
+ * while the broker's main JavaScript thread is blocked.
+ */
+
+import crypto from "node:crypto";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { Worker } from "node:worker_threads";
+
+const TRANSPORT_VERSION = "local-ipc-v1";
+const DEFAULT_TIMEOUT_MS = 5000;
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+
+function transportError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export function credentialTransportEndpoint(agentId, options = {}) {
+  const platform = options.platform || process.platform;
+  const safeId = crypto
+    .createHash("sha256")
+    .update(String(agentId))
+    .digest("hex")
+    .slice(0, 24);
+  if (platform === "win32") return `\\\\.\\pipe\\cc-cred-${safeId}`;
+  return path.join(options.tmpdir || os.tmpdir(), `cc-cred-${safeId}.sock`);
+}
+
+export class CredentialTransport {
+  constructor(options = {}) {
+    if (!options.agentId) {
+      throw transportError(
+        "CC_CREDENTIAL_INVALID_REQUEST",
+        "Credential transport requires an agent id",
+      );
+    }
+    this.agentId = String(options.agentId);
+    this.platform = options.platform || process.platform;
+    this.endpoint =
+      options.endpoint ||
+      credentialTransportEndpoint(this.agentId, {
+        platform: this.platform,
+        tmpdir: options.tmpdir,
+      });
+    this.version = TRANSPORT_VERSION;
+    this.ready = false;
+    this.closed = false;
+    this.error = null;
+    this._onAudit =
+      typeof options.onAudit === "function" ? options.onAudit : () => {};
+    this._onSettlement =
+      typeof options.onSettlement === "function"
+        ? options.onSettlement
+        : () => {};
+    this._workerFactory =
+      options.workerFactory ||
+      ((url, workerOptions) => new Worker(url, workerOptions));
+
+    this._readyPromise = new Promise((resolve, reject) => {
+      this._resolveReady = resolve;
+      this._rejectReady = reject;
+    });
+    this._readyPromise.catch(() => {});
+
+    try {
+      this._worker = this._workerFactory(
+        new URL("./credential-transport-worker.js", import.meta.url),
+        {
+          type: "module",
+          workerData: {
+            agentId: this.agentId,
+            endpoint: this.endpoint,
+            platform: this.platform,
+          },
+        },
+      );
+      this._worker.on("message", (message) =>
+        this._handleWorkerMessage(message),
+      );
+      this._worker.on("error", (error) => this._handleWorkerFailure(error));
+      this._worker.on("exit", (code) => {
+        if (!this.closed && code !== 0) {
+          this._handleWorkerFailure(
+            transportError(
+              "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+              `Credential transport worker exited with code ${code}`,
+            ),
+          );
+        }
+      });
+      this._worker.unref?.();
+    } catch (error) {
+      this._handleWorkerFailure(error);
+    }
+  }
+
+  _handleWorkerMessage(message) {
+    if (message?.type === "ready") {
+      this.ready = true;
+      this._resolveReady(this);
+      return;
+    }
+    if (message?.type === "audit" && message.entry) {
+      this._onAudit(message.entry);
+      return;
+    }
+    if (message?.type === "settlement") {
+      this._onSettlement(message);
+      return;
+    }
+    if (message?.type === "fatal") {
+      this._handleWorkerFailure(
+        transportError(
+          message.error?.code || "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+          message.error?.message || "Credential transport failed",
+        ),
+      );
+    }
+  }
+
+  _handleWorkerFailure(error) {
+    if (this.error) return;
+    this.error = transportError(
+      error?.code || "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+      error?.message || "Credential transport is unavailable",
+    );
+    this.ready = false;
+    this._rejectReady(this.error);
+  }
+
+  isAvailable() {
+    return Boolean(this._worker && !this.closed && !this.error);
+  }
+
+  waitUntilReady() {
+    return this._readyPromise;
+  }
+
+  createCapabilityToken() {
+    if (!this.isAvailable()) {
+      throw (
+        this.error ||
+        transportError(
+          "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+          "Credential transport is unavailable",
+        )
+      );
+    }
+    return crypto.randomBytes(32).toString("base64url");
+  }
+
+  registerCredential(record) {
+    if (!this.isAvailable()) {
+      throw (
+        this.error ||
+        transportError(
+          "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+          "Credential transport is unavailable",
+        )
+      );
+    }
+    this._worker.postMessage({ type: "register", record });
+  }
+
+  updateCredential(refId, state) {
+    if (!this.isAvailable()) return;
+    this._worker.postMessage({
+      type: "update",
+      refId,
+      useCount: state.useCount,
+      status: state.status,
+    });
+  }
+
+  revokeCredential(refId) {
+    if (!this.isAvailable()) return;
+    this._worker.postMessage({ type: "revoke", refId });
+  }
+
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    if (!this._worker) return;
+    const worker = this._worker;
+    await new Promise((resolve) => {
+      const timer = setTimeout(resolve, 1000);
+      const onMessage = (message) => {
+        if (message?.type !== "closed") return;
+        clearTimeout(timer);
+        worker.removeListener("message", onMessage);
+        resolve();
+      };
+      worker.on("message", onMessage);
+      worker.postMessage({ type: "close" });
+    });
+    await worker.terminate();
+    this.ready = false;
+  }
+
+  getInfo() {
+    return {
+      version: this.version,
+      endpoint: this.endpoint,
+      available: this.isAvailable(),
+      ready: this.ready,
+      error: this.error
+        ? {
+            code: this.error.code,
+            message: this.error.message,
+          }
+        : null,
+    };
+  }
+}
+
+function connectOnce(endpoint) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(endpoint);
+    const onError = (error) => {
+      socket.removeListener("connect", onConnect);
+      reject(error);
+    };
+    const onConnect = () => {
+      socket.removeListener("error", onError);
+      resolve(socket);
+    };
+    socket.once("error", onError);
+    socket.once("connect", onConnect);
+  });
+}
+
+async function connectWithRetry(endpoint, deadline) {
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      return await connectOnce(endpoint);
+    } catch (error) {
+      lastError = error;
+      const retryable = ["ENOENT", "ECONNREFUSED", "EPIPE"].includes(
+        error?.code,
+      );
+      if (!retryable) throw error;
+      await new Promise((resolve) => {
+        setTimeout(resolve, 25);
+      });
+    }
+  }
+  throw (
+    lastError ||
+    transportError(
+      "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+      "Credential transport connection timed out",
+    )
+  );
+}
+
+/**
+ * Resolve one reference using only the capability material inherited by the
+ * approved target process.
+ */
+export async function resolveCredentialRefOverTransport(refId, options = {}) {
+  const env = options.env || process.env;
+  const endpoint = options.endpoint || env.CC_CREDENTIAL_ENDPOINT;
+  const capabilityToken =
+    options.capabilityToken || env.CC_CREDENTIAL_AUTH_TOKEN;
+  const agentId = options.agentId || env.CC_CREDENTIAL_AGENT_ID;
+  const processTarget =
+    options.process ||
+    options.processTarget ||
+    env.CC_CREDENTIAL_TARGET_PROCESS;
+  const host =
+    options.host !== undefined
+      ? options.host
+      : env.CC_CREDENTIAL_TARGET_HOST || null;
+  const timeoutMs = Math.max(
+    1,
+    Number(options.timeoutMs || DEFAULT_TIMEOUT_MS),
+  );
+
+  if (!endpoint || !capabilityToken || !agentId || !processTarget || !refId) {
+    throw transportError(
+      "CC_CREDENTIAL_INVALID_REQUEST",
+      "Credential transport environment is incomplete",
+    );
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  const socket = await connectWithRetry(endpoint, deadline);
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    let carry = "";
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const timer = setTimeout(
+      () => {
+        finish(
+          transportError(
+            "CC_CREDENTIAL_TRANSPORT_TIMEOUT",
+            "Credential transport response timed out",
+          ),
+        );
+      },
+      Math.max(1, deadline - Date.now()),
+    );
+    timer.unref?.();
+    socket.on("data", (chunk) => {
+      carry += chunk.toString("utf8");
+      if (Buffer.byteLength(carry, "utf8") > MAX_RESPONSE_BYTES) {
+        finish(
+          transportError(
+            "CC_CREDENTIAL_INVALID_REQUEST",
+            "Credential transport response is too large",
+          ),
+        );
+        return;
+      }
+      const newline = carry.indexOf("\n");
+      if (newline === -1) return;
+      let response;
+      try {
+        response = JSON.parse(carry.slice(0, newline).replace(/\r$/, ""));
+      } catch {
+        finish(
+          transportError(
+            "CC_CREDENTIAL_INVALID_REQUEST",
+            "Credential transport returned invalid JSON",
+          ),
+        );
+        return;
+      }
+      if (!response.ok) {
+        finish(
+          transportError(
+            response.code || "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+            response.message || "Credential transport denied the request",
+          ),
+        );
+        return;
+      }
+      finish(null, response.value);
+    });
+    socket.once("error", (error) => finish(error));
+    socket.once("close", () => {
+      if (!settled) {
+        finish(
+          transportError(
+            "CC_CREDENTIAL_TRANSPORT_UNAVAILABLE",
+            "Credential transport closed without a response",
+          ),
+        );
+      }
+    });
+    socket.write(
+      `${JSON.stringify({
+        type: "resolve",
+        refId,
+        agentId,
+        capabilityToken,
+        process: processTarget,
+        host,
+      })}\n`,
+    );
+  });
+}
+
+export { TRANSPORT_VERSION };