blun-king-cli 9.1.486 → 9.1.489

package/agent-spine-plugin/src/lib/object-transport.js

@@ -0,0 +1,206 @@
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+import {
+  buildHttpsSnapshot, fetchHttpsSnapshot, resolveHttpsEndpoint, validateHttpsSnapshot
+} from "./https-transport.js";
+
+const CONFIRMATION = "local-share-confirmed";
+const MAX_TOKEN_BYTES = 8192;
+const MAX_RESPONSE_BYTES = 16 * 1024;
+const TOKEN_ENV_RE = /^[A-Z_][A-Z0-9_]{0,127}$/;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+
+function bearerToken(tokenEnv, environment) {
+  if (tokenEnv === null || tokenEnv === undefined) return null;
+  if (!TOKEN_ENV_RE.test(tokenEnv)) throw new Error("tokenEnv must be an uppercase environment variable name");
+  const value = environment[tokenEnv];
+  if (typeof value !== "string" || !value) {
+    throw new Error(`HTTPS object token environment variable is missing: ${tokenEnv}`);
+  }
+  if (Buffer.byteLength(value) > MAX_TOKEN_BYTES || /[\0-\x1f\x7f]/.test(value)) {
+    throw new Error("HTTPS object bearer token is invalid");
+  }
+  return value;
+}
+
+function timeout(value) {
+  if (!Number.isInteger(value) || value < 1000 || value > 30000) {
+    throw new Error("HTTPS object timeout must be between 1000 and 30000 milliseconds");
+  }
+  return value;
+}
+
+async function within(promise, milliseconds, message) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), milliseconds);
+      })
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function validateHttpsObjectBase(value) {
+  let endpoint;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw new Error("HTTPS object base URL is invalid");
+  }
+  if (endpoint.protocol !== "https:") throw new Error("HTTPS object publishing requires an https:// URL");
+  if (endpoint.username || endpoint.password) {
+    throw new Error("credentials must not be embedded in an HTTPS object base URL");
+  }
+  if (endpoint.search || endpoint.hash) {
+    throw new Error("HTTPS object base URLs cannot contain a query or fragment");
+  }
+  if (!endpoint.hostname || /%(?:2f|5c)/i.test(endpoint.pathname)) {
+    throw new Error("HTTPS object base URL contains an ambiguous path");
+  }
+  endpoint.pathname = endpoint.pathname.replace(/\/+$/, "");
+  return endpoint;
+}
+
+export function httpsObjectUrl(baseUrl, snapshotDigest) {
+  if (!DIGEST_RE.test(snapshotDigest || "")) throw new Error("snapshot digest is invalid");
+  const endpoint = validateHttpsObjectBase(baseUrl);
+  endpoint.pathname = `${endpoint.pathname}/objects/${snapshotDigest}.json`;
+  return endpoint.toString();
+}
+
+async function upload({
+  url, body, digest, token, timeoutMs, allowPrivateNetwork, lookup, request
+}) {
+  const resolved = await within(
+    resolveHttpsEndpoint(url, { allowPrivateNetwork, lookup }),
+    timeoutMs,
+    "HTTPS object DNS resolution timed out"
+  );
+  const selected = resolved.addresses[0];
+  const headers = {
+    accept: "application/json",
+    "accept-encoding": "identity",
+    "content-length": String(body.length),
+    "content-type": "application/vnd.agentspine.snapshot+json",
+    "if-none-match": "*",
+    "user-agent": "AgentSpine/0.1 HTTPS object transport",
+    "x-agentspine-digest": `sha256:${digest}`
+  };
+  if (token) headers.authorization = `Bearer ${token}`;
+  return new Promise((resolvePromise, rejectPromise) => {
+    let deadline;
+    let settled = false;
+    const reject = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      rejectPromise(error);
+    };
+    const resolve = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      resolvePromise(value);
+    };
+    const options = {
+      protocol: "https:", hostname: resolved.lookupHostname,
+      port: resolved.endpoint.port || 443,
+      path: resolved.endpoint.pathname, method: "PUT", headers,
+      agent: false, autoSelectFamily: false,
+      servername: isIP(resolved.lookupHostname) ? undefined : resolved.lookupHostname,
+      lookup: (_hostname, lookupOptions, callback) => {
+        const family = typeof lookupOptions === "object" && lookupOptions.family
+          ? Number(lookupOptions.family) : 0;
+        const usable = family
+          ? resolved.addresses.find((item) => item.family === family)
+          : selected;
+        if (!usable) return callback(new Error("no vetted DNS address matches the requested family"));
+        return callback(null, usable.address, usable.family);
+      }
+    };
+    const active = request(options, (response) => {
+      const status = Number(response.statusCode || 0);
+      if (status >= 300 && status < 400 && status !== 412) {
+        response.resume();
+        reject(new Error("HTTPS object redirects are not followed"));
+        return;
+      }
+      const chunks = [];
+      let bytes = 0;
+      response.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_RESPONSE_BYTES) {
+          active.destroy(new Error("HTTPS object response exceeds the 16 KiB limit"));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => {
+        if (![201, 204, 412].includes(status)) {
+          reject(new Error(`HTTPS object publish failed with status ${status}`));
+          return;
+        }
+        resolve({ status, responseBytes: bytes });
+      });
+      response.on("error", reject);
+    });
+    active.setTimeout(timeoutMs, () => active.destroy(new Error("HTTPS object publish timed out")));
+    deadline = setTimeout(() => active.destroy(new Error("HTTPS object publish timed out")), timeoutMs);
+    active.on("error", reject);
+    active.end(body);
+  });
+}
+
+export async function putHttpsSnapshot({
+  baseUrl, snapshot, tokenEnv = null, timeoutMs = 10000,
+  allowPrivateNetwork = false, confirmation = null,
+  environment = process.env, lookup = dnsLookup, request = httpsRequest
+}) {
+  if (confirmation !== CONFIRMATION) {
+    throw new Error("HTTPS object publishing requires explicit local owner confirmation");
+  }
+  timeout(timeoutMs);
+  const validated = validateHttpsSnapshot(structuredClone(snapshot));
+  const objectUrl = httpsObjectUrl(baseUrl, validated.digest);
+  const token = bearerToken(tokenEnv, environment);
+  const body = Buffer.from(JSON.stringify(validated));
+  const result = await upload({
+    url: objectUrl, body, digest: validated.digest, token, timeoutMs,
+    allowPrivateNetwork, lookup, request
+  });
+  const fetched = await fetchHttpsSnapshot({
+    url: objectUrl, tokenEnv, timeoutMs, allowPrivateNetwork,
+    confirmation, environment, lookup, request
+  });
+  if (fetched.snapshot.digest !== validated.digest) {
+    throw new Error("HTTPS object read-back does not match the published snapshot");
+  }
+  return {
+    created: result.status !== 412,
+    alreadyExisted: result.status === 412,
+    verified: true,
+    objectUrl,
+    snapshotId: validated.snapshotId,
+    snapshotDigest: validated.digest,
+    scopeId: validated.scopeId,
+    adapterId: validated.adapterId,
+    events: validated.events.length,
+    authenticatedWrite: Boolean(token),
+    authority: "context-only"
+  };
+}
+
+export async function publishHttpsSnapshot({
+  root = process.cwd(), directory, baseUrl, snapshotId, now = new Date(), ...options
+}) {
+  if (options.confirmation !== CONFIRMATION) {
+    throw new Error("HTTPS object publishing requires explicit local owner confirmation");
+  }
+  const snapshot = await buildHttpsSnapshot({ root, directory, snapshotId, now });
+  return putHttpsSnapshot({ baseUrl, snapshot, ...options });
+}

package/agent-spine-plugin/src/lib/paths.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+
+export async function canonicalPath(input = process.cwd()) {
+  return realpath(resolve(input));
+}
+
+export async function findProjectRoot(input = process.cwd()) {
+  if (process.env.AGENTSPINE_ROOT) return canonicalPath(process.env.AGENTSPINE_ROOT);
+  let cursor = await canonicalPath(input);
+  while (true) {
+    try {
+      await lstat(join(cursor, ".git"));
+      return cursor;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) return canonicalPath(input);
+    cursor = parent;
+  }
+}
+
+export function isInside(parent, child, pathApi = { relative, isAbsolute, sep }) {
+  const value = pathApi.relative(parent, child);
+  return value === "" || (!pathApi.isAbsolute(value) && !value.startsWith(`..${pathApi.sep}`) && value !== "..");
+}
+
+export function ancestorsBetween(root, cwd) {
+  const result = [];
+  let cursor = resolve(cwd);
+  while (isInside(root, cursor)) {
+    result.push(cursor);
+    if (cursor === root) break;
+    const next = dirname(cursor);
+    if (next === cursor) break;
+    cursor = next;
+  }
+  return result.reverse();
+}
+
+export function stateRoot(env = process.env) {
+  if (env.AGENTSPINE_STATE_DIR) return resolve(env.AGENTSPINE_STATE_DIR);
+  if (process.platform === "win32") {
+    return join(env.LOCALAPPDATA || env.APPDATA || homedir(), "AgentSpine");
+  }
+  return join(env.XDG_STATE_HOME || join(homedir(), ".local", "state"), "agentspine");
+}
+
+export function projectId(root) {
+  return createHash("sha256").update(root).digest("hex").slice(0, 20);
+}
+
+export async function projectStateDir(root) {
+  const target = join(stateRoot(), "projects", projectId(root));
+  await mkdir(target, { recursive: true, mode: 0o700 });
+  return target;
+}

package/agent-spine-plugin/src/lib/peer-transport.js

@@ -0,0 +1,283 @@
+import { randomBytes, randomUUID, createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import {
+  assertTrustedIdentity, loadTrust, signEnvelope, verifyEnvelope
+} from "./authentication.js";
+import {
+  buildHttpsSnapshot, importHttpsSnapshot, validateHttpsSnapshot
+} from "./https-transport.js";
+
+const REQUEST_SCHEMA = "agentspine.peer-request/v1";
+const RESPONSE_SCHEMA = "agentspine.peer-response/v1";
+const CONFIRMATION = "local-share-confirmed";
+const DEFAULT_MAX_BYTES = 22 * 1024 * 1024;
+const MIN_MAX_BYTES = 1024 * 1024;
+const MAX_MAX_BYTES = 22 * 1024 * 1024;
+const MAX_REQUEST_BYTES = 4096;
+const MAX_COMMAND_BYTES = 32768;
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const CHALLENGE_RE = /^[a-f0-9]{64}$/;
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function digest(value) {
+  return createHash("sha256").update(canonical(value)).digest("hex");
+}
+
+function exactKeys(value, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index]);
+}
+
+function validDate(value) {
+  return typeof value === "string" && Number.isFinite(new Date(value).getTime());
+}
+
+function isoDate(value, field = "date") {
+  const parsed = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(parsed.getTime())) throw new Error(`${field} must be a valid date`);
+  return parsed.toISOString();
+}
+
+function byteLimit(value) {
+  if (!Number.isInteger(value) || value < MIN_MAX_BYTES || value > MAX_MAX_BYTES) {
+    throw new Error("peer maxBytes must be an integer between 1 MiB and 22 MiB");
+  }
+  return value;
+}
+
+function timeout(value) {
+  if (!Number.isInteger(value) || value < 1000 || value > 30000) {
+    throw new Error("peer timeout must be between 1000 and 30000 milliseconds");
+  }
+  return value;
+}
+
+export function createPeerRequest({
+  requestId = `request:${randomUUID()}`, challenge = randomBytes(32).toString("hex"),
+  maxBytes = DEFAULT_MAX_BYTES
+} = {}) {
+  byteLimit(maxBytes);
+  if (!ID_RE.test(requestId || "")) throw new Error("peer requestId must be a stable, whitespace-free identifier");
+  if (!CHALLENGE_RE.test(challenge || "")) throw new Error("peer challenge must be 32 random bytes encoded as lowercase hex");
+  return {
+    schema: REQUEST_SCHEMA, requestId, challenge, maxBytes, authority: "context-only"
+  };
+}
+
+export function validatePeerRequest(request) {
+  if (!exactKeys(request, ["schema", "requestId", "challenge", "maxBytes", "authority"])
+    || request.schema !== REQUEST_SCHEMA || !ID_RE.test(request.requestId || "")
+    || !CHALLENGE_RE.test(request.challenge || "") || request.authority !== "context-only") {
+    throw new Error("peer request is invalid");
+  }
+  byteLimit(request.maxBytes);
+  if (Buffer.byteLength(JSON.stringify(request)) > MAX_REQUEST_BYTES) throw new Error("peer request exceeds 4 KiB");
+  return request;
+}
+
+export async function buildPeerResponse({
+  root = process.cwd(), directory, signerId, request, now = new Date(),
+  snapshotId = `snapshot:peer:${randomUUID()}`
+}) {
+  const validatedRequest = validatePeerRequest(structuredClone(request));
+  if (!ID_RE.test(signerId || "")) throw new Error("signerId is required for peer responses");
+  const snapshot = await buildHttpsSnapshot({ root, directory, snapshotId, now });
+  const body = {
+    schema: RESPONSE_SCHEMA,
+    requestId: validatedRequest.requestId,
+    challenge: validatedRequest.challenge,
+    snapshot,
+    createdAt: isoDate(now, "now"),
+    authority: "context-only"
+  };
+  const payload = { ...body, digest: digest(body) };
+  const envelope = await signEnvelope({ root, signerId, kind: "manifest", payload, now });
+  const manifest = verifyEnvelope(snapshot.manifest, "manifest");
+  if (manifest.publicIdentity.keyId !== envelope.signer.keyId) {
+    throw new Error("peer response signer must match the snapshot manifest signer");
+  }
+  if (Buffer.byteLength(JSON.stringify(envelope)) > validatedRequest.maxBytes) {
+    throw new Error("peer response exceeds the request byte limit");
+  }
+  return envelope;
+}
+
+export function validatePeerResponse(envelope, request) {
+  const validatedRequest = validatePeerRequest(structuredClone(request));
+  const verified = verifyEnvelope(envelope, "manifest");
+  const response = verified.payload;
+  if (!exactKeys(response, [
+    "schema", "requestId", "challenge", "snapshot", "createdAt", "authority", "digest"
+  ]) || response.schema !== RESPONSE_SCHEMA || response.requestId !== validatedRequest.requestId
+    || response.challenge !== validatedRequest.challenge || !validDate(response.createdAt)
+    || response.authority !== "context-only" || !DIGEST_RE.test(response.digest || "")) {
+    throw new Error("peer response does not match the live request");
+  }
+  const { digest: _digest, ...body } = response;
+  if (digest(body) !== response.digest) throw new Error("peer response failed its integrity check");
+  const snapshot = validateHttpsSnapshot(structuredClone(response.snapshot));
+  const manifest = verifyEnvelope(snapshot.manifest, "manifest");
+  if (manifest.publicIdentity.keyId !== verified.publicIdentity.keyId) {
+    throw new Error("peer response signer does not match the snapshot manifest signer");
+  }
+  if (Buffer.byteLength(JSON.stringify(envelope)) > validatedRequest.maxBytes) {
+    throw new Error("peer response exceeds the request byte limit");
+  }
+  return {
+    envelope, response, snapshot,
+    authentication: verified.authentication,
+    publicIdentity: verified.publicIdentity
+  };
+}
+
+async function readJsonLine(input, { maxBytes, timeoutMs, label }) {
+  let timer;
+  const chunks = [];
+  let bytes = 0;
+  let complete = false;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out`)), timeoutMs);
+  });
+  const reading = (async () => {
+    for await (const chunkValue of input) {
+      const chunk = Buffer.isBuffer(chunkValue) ? chunkValue : Buffer.from(chunkValue);
+      bytes += chunk.length;
+      if (bytes > maxBytes + 1) throw new Error(`${label} exceeds its byte limit`);
+      chunks.push(chunk);
+      if (chunk.includes(0x0a)) { complete = true; break; }
+    }
+    if (!complete) throw new Error(`${label} ended before one complete JSON line`);
+    const content = Buffer.concat(chunks);
+    const newline = content.indexOf(0x0a);
+    if (newline > maxBytes) throw new Error(`${label} exceeds its byte limit`);
+    if (content.subarray(newline + 1).toString("utf8").trim()) {
+      throw new Error(`${label} contains unexpected output after the JSON frame`);
+    }
+    try { return JSON.parse(content.subarray(0, newline).toString("utf8")); } catch {
+      throw new Error(`${label} is not valid JSON`);
+    }
+  })();
+  try { return await Promise.race([reading, deadline]); } finally { clearTimeout(timer); }
+}
+
+export async function servePeerOnce({
+  root = process.cwd(), directory, signerId, input = process.stdin, output = process.stdout,
+  confirmation = null, timeoutMs = 10000, now = new Date()
+}) {
+  if (confirmation !== CONFIRMATION) throw new Error("peer serving requires explicit local owner confirmation");
+  timeout(timeoutMs);
+  const request = validatePeerRequest(await readJsonLine(input, {
+    maxBytes: MAX_REQUEST_BYTES, timeoutMs, label: "peer request"
+  }));
+  const envelope = await buildPeerResponse({ root, directory, signerId, request, now });
+  const frame = `${JSON.stringify(envelope)}\n`;
+  if (Buffer.byteLength(frame) > request.maxBytes + 1) throw new Error("peer response exceeds the request byte limit");
+  await new Promise((resolvePromise, rejectPromise) => {
+    output.write(frame, (error) => error ? rejectPromise(error) : resolvePromise());
+  });
+  return {
+    served: true, requestId: request.requestId,
+    snapshotId: envelope.payload.snapshot.snapshotId,
+    snapshotDigest: envelope.payload.snapshot.digest,
+    bytes: Buffer.byteLength(frame) - 1,
+    authority: "context-only"
+  };
+}
+
+function parseCommand(commandJson) {
+  let command;
+  try { command = typeof commandJson === "string" ? JSON.parse(commandJson) : structuredClone(commandJson); } catch {
+    throw new Error("peer command must be a JSON array of an executable and arguments");
+  }
+  if (!Array.isArray(command) || command.length < 1 || command.length > 64
+    || command.some((item) => typeof item !== "string" || !item || item.length > 8192 || item.includes("\0"))
+    || Buffer.byteLength(JSON.stringify(command)) > MAX_COMMAND_BYTES) {
+    throw new Error("peer command must contain 1 to 64 bounded strings");
+  }
+  return command;
+}
+
+function processEnvironment(environment = process.env) {
+  const allowed = new Set([
+    "PATH", "Path", "HOME", "USERPROFILE", "SystemRoot", "SYSTEMROOT", "WINDIR",
+    "TMP", "TEMP", "TMPDIR", "LANG", "LC_ALL", "SSH_AUTH_SOCK", "SSH_AGENT_PID",
+    "AGENTSPINE_STATE_DIR", "XDG_STATE_HOME", "LOCALAPPDATA", "APPDATA"
+  ]);
+  return Object.fromEntries(Object.entries(environment).filter(([key]) => allowed.has(key)));
+}
+
+async function exchangeCommand({ command, request, timeoutMs, spawnProcess }) {
+  const [executable, ...args] = command;
+  const child = spawnProcess(executable, args, {
+    shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"],
+    env: processEnvironment()
+  });
+  const processError = new Promise((_resolve, reject) => {
+    child.once("error", () => reject(new Error("peer command could not be started")));
+  });
+  let stderrBytes = 0;
+  child.stderr?.on("data", (chunk) => {
+    stderrBytes += chunk.length;
+    if (stderrBytes > 64 * 1024) child.kill();
+  });
+  child.stdin.on("error", () => {});
+  child.stdin.end(`${JSON.stringify(request)}\n`);
+  try {
+    return await Promise.race([
+      readJsonLine(child.stdout, {
+        maxBytes: request.maxBytes, timeoutMs, label: "peer response"
+      }),
+      processError
+    ]);
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) child.kill();
+  }
+}
+
+export async function importPeerResponse({
+  root = process.cwd(), envelope, request, now = new Date()
+}) {
+  const validated = validatePeerResponse(structuredClone(envelope), request);
+  const { trust } = await loadTrust(root);
+  assertTrustedIdentity(validated.publicIdentity, trust);
+  const imported = await importHttpsSnapshot({ root, snapshot: validated.snapshot, now });
+  return {
+    ...imported,
+    transport: "peer-stdio",
+    requestId: validated.response.requestId,
+    snapshotId: validated.snapshot.snapshotId,
+    snapshotDigest: validated.snapshot.digest,
+    peerSignerId: validated.publicIdentity.signerId,
+    peerKeyId: validated.publicIdentity.keyId,
+    authority: "context-only"
+  };
+}
+
+export async function pullPeerCommand({
+  root = process.cwd(), commandJson, confirmation = null,
+  timeoutMs = 10000, maxBytes = DEFAULT_MAX_BYTES,
+  now = new Date(), spawnProcess = spawn
+}) {
+  if (confirmation !== CONFIRMATION) throw new Error("peer command execution requires explicit local owner confirmation");
+  timeout(timeoutMs);
+  const command = parseCommand(commandJson);
+  const request = createPeerRequest({ maxBytes });
+  const envelope = await exchangeCommand({ command, request, timeoutMs, spawnProcess });
+  const imported = await importPeerResponse({ root, envelope, request, now });
+  return {
+    ...imported,
+    executable: command[0],
+    commandArguments: command.length - 1,
+    authority: "context-only"
+  };
+}