@treeseed/sdk 0.4.13 → 0.5.0

package/dist/operations/services/key-agent.js

@@ -0,0 +1,476 @@
+import { spawnSync } from "node:child_process";
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+const TRESEED_MACHINE_KEY_PASSPHRASE_ENV = "TREESEED_KEY_PASSPHRASE";
+const TRESEED_KEY_AGENT_IDLE_TIMEOUT_MS = 15 * 60 * 1e3;
+const TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS = TRESEED_KEY_AGENT_IDLE_TIMEOUT_MS;
+const TRESEED_WRAPPED_MACHINE_KEY_VERSION = 2;
+const TRESEED_WRAPPED_MACHINE_KEY_KIND = "treeseed-wrapped-machine-key";
+const TREESEED_MACHINE_KEY_PASSPHRASE_ENV = TRESEED_MACHINE_KEY_PASSPHRASE_ENV;
+const KEY_AGENT_SOCKET_RELATIVE_PATH = ".treeseed/run/key-agent.sock";
+const WRAPPED_KEY_KDF_PARAMS = {
+  N: 1 << 14,
+  r: 8,
+  p: 1,
+  keyLength: 32
+};
+class TreeseedKeyAgentError extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "TreeseedKeyAgentError";
+    this.code = code;
+    this.details = details;
+  }
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function ensureParent(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+function ensureFifo(filePath) {
+  ensureParent(filePath);
+  if (existsSync(filePath)) {
+    const stats = statSync(filePath);
+    if (stats.isFIFO()) {
+      return;
+    }
+    rmSync(filePath, { force: true });
+  }
+  const result = spawnSync("mkfifo", [filePath], { stdio: "pipe", encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.trim() || `Unable to create FIFO ${filePath}.`);
+  }
+}
+function pidFilePath(socketPath) {
+  return `${socketPath}.pid`;
+}
+function responseFifoPath(socketPath) {
+  return join(mkdtempSync(resolve(dirname(socketPath), "key-agent-response-")), "response.fifo");
+}
+function writePidFile(socketPath) {
+  writeFileSync(pidFilePath(socketPath), `${process.pid}
+`, { mode: 384 });
+}
+function clearPidFile(socketPath) {
+  rmSync(pidFilePath(socketPath), { force: true });
+}
+function readAgentPid(socketPath) {
+  const pidPath = pidFilePath(socketPath);
+  if (!existsSync(pidPath)) {
+    return null;
+  }
+  const raw = readFileSync(pidPath, "utf8").trim();
+  const pid = Number.parseInt(raw, 10);
+  return Number.isFinite(pid) ? pid : null;
+}
+function agentProcessAlive(socketPath) {
+  const pid = readAgentPid(socketPath);
+  if (!pid) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function createFingerprint(machineKey) {
+  return machineKey.subarray(0, 6).toString("base64");
+}
+function deriveWrappingKey(passphrase, salt, keyLength) {
+  return scryptSync(passphrase.normalize("NFKC"), salt, keyLength, {
+    N: WRAPPED_KEY_KDF_PARAMS.N,
+    r: WRAPPED_KEY_KDF_PARAMS.r,
+    p: WRAPPED_KEY_KDF_PARAMS.p
+  });
+}
+function wrapMachineKey(machineKey, passphrase) {
+  const salt = randomBytes(16);
+  const iv = randomBytes(12);
+  const wrappingKey = deriveWrappingKey(passphrase, salt, WRAPPED_KEY_KDF_PARAMS.keyLength);
+  const cipher = createCipheriv("aes-256-gcm", wrappingKey, iv);
+  const ciphertext = Buffer.concat([cipher.update(machineKey), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    version: TRESEED_WRAPPED_MACHINE_KEY_VERSION,
+    kind: TRESEED_WRAPPED_MACHINE_KEY_KIND,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+    kdf: {
+      algorithm: "scrypt",
+      salt: salt.toString("base64"),
+      N: WRAPPED_KEY_KDF_PARAMS.N,
+      r: WRAPPED_KEY_KDF_PARAMS.r,
+      p: WRAPPED_KEY_KDF_PARAMS.p,
+      keyLength: WRAPPED_KEY_KDF_PARAMS.keyLength
+    },
+    wrappedKey: {
+      algorithm: "aes-256-gcm",
+      iv: iv.toString("base64"),
+      tag: tag.toString("base64"),
+      ciphertext: ciphertext.toString("base64")
+    },
+    fingerprint: createFingerprint(machineKey)
+  };
+}
+function unwrapMachineKey(payload, passphrase) {
+  try {
+    const salt = Buffer.from(payload.kdf.salt, "base64");
+    const wrappingKey = deriveWrappingKey(passphrase, salt, payload.kdf.keyLength);
+    const decipher = createDecipheriv("aes-256-gcm", wrappingKey, Buffer.from(payload.wrappedKey.iv, "base64"));
+    decipher.setAuthTag(Buffer.from(payload.wrappedKey.tag, "base64"));
+    return Buffer.concat([
+      decipher.update(Buffer.from(payload.wrappedKey.ciphertext, "base64")),
+      decipher.final()
+    ]);
+  } catch (error) {
+    throw new TreeseedKeyAgentError(
+      "unlock_failed",
+      "Unable to unlock the Treeseed machine key. The passphrase is incorrect or the wrapped key file is corrupt.",
+      { cause: error instanceof Error ? error.message : String(error) }
+    );
+  }
+}
+function isWrappedMachineKeyPayload(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const record = value;
+  return record.kind === TRESEED_WRAPPED_MACHINE_KEY_KIND && record.version === TRESEED_WRAPPED_MACHINE_KEY_VERSION;
+}
+function readWrappedMachineKeyFile(keyPath) {
+  if (!existsSync(keyPath)) {
+    return {
+      exists: false,
+      wrapped: null,
+      plaintextLegacy: null,
+      migrationRequired: false
+    };
+  }
+  const raw = readFileSync(keyPath, "utf8").trim();
+  if (!raw) {
+    return {
+      exists: false,
+      wrapped: null,
+      plaintextLegacy: null,
+      migrationRequired: false
+    };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (isWrappedMachineKeyPayload(parsed)) {
+      return {
+        exists: true,
+        wrapped: parsed,
+        plaintextLegacy: null,
+        migrationRequired: false
+      };
+    }
+  } catch {
+  }
+  try {
+    return {
+      exists: true,
+      wrapped: null,
+      plaintextLegacy: Buffer.from(raw, "base64"),
+      migrationRequired: true
+    };
+  } catch {
+    throw new TreeseedKeyAgentError(
+      "corrupt_wrapped_key",
+      "Unable to parse the Treeseed machine key file.",
+      { keyPath }
+    );
+  }
+}
+function writeWrappedMachineKeyFile(keyPath, payload) {
+  ensureParent(keyPath);
+  writeFileSync(keyPath, `${JSON.stringify(payload, null, 2)}
+`, { mode: 384 });
+}
+function replaceWrappedMachineKey(keyPath, machineKey, passphrase) {
+  const payload = wrapMachineKey(machineKey, passphrase);
+  writeWrappedMachineKeyFile(keyPath, payload);
+  return payload;
+}
+function getTreeseedKeyAgentPaths() {
+  const homeRoot = process.env.HOME && process.env.HOME.trim().length > 0 ? process.env.HOME : homedir();
+  return {
+    homeRoot,
+    socketPath: resolve(homeRoot, KEY_AGENT_SOCKET_RELATIVE_PATH)
+  };
+}
+function createStatus(command, session) {
+  const wrapped = readWrappedMachineKeyFile(command.keyPath);
+  const idleRemainingMs = session.machineKey ? Math.max(0, session.idleTimeoutMs - (Date.now() - session.lastTouchedAt)) : 0;
+  return {
+    running: true,
+    unlocked: Boolean(session.machineKey) && idleRemainingMs > 0,
+    wrappedKeyPresent: wrapped.exists && Boolean(wrapped.wrapped),
+    migrationRequired: wrapped.migrationRequired,
+    keyPath: command.keyPath,
+    socketPath: command.socketPath,
+    idleTimeoutMs: session.idleTimeoutMs,
+    idleRemainingMs
+  };
+}
+function maybeExpireSession(session) {
+  if (!session.machineKey) {
+    return;
+  }
+  if (Date.now() - session.lastTouchedAt >= session.idleTimeoutMs) {
+    session.machineKey = null;
+  }
+}
+function readLegacyProjectMachineKey(legacyKeyPath) {
+  if (!existsSync(legacyKeyPath)) {
+    return null;
+  }
+  try {
+    return Buffer.from(readFileSync(legacyKeyPath, "utf8").trim(), "base64");
+  } catch {
+    return null;
+  }
+}
+function unwrapOrProvisionMachineKey(command) {
+  const wrapped = readWrappedMachineKeyFile(command.keyPath);
+  if (wrapped.wrapped) {
+    return unwrapMachineKey(wrapped.wrapped, command.passphrase);
+  }
+  if (wrapped.plaintextLegacy) {
+    if (!command.allowMigration) {
+      throw new TreeseedKeyAgentError(
+        "wrapped_key_migration_required",
+        "The Treeseed machine key is still stored in the legacy plaintext format. Run a migration or unlock interactively to wrap it first.",
+        { keyPath: command.keyPath }
+      );
+    }
+    replaceWrappedMachineKey(command.keyPath, wrapped.plaintextLegacy, command.passphrase);
+    return wrapped.plaintextLegacy;
+  }
+  if (!command.createIfMissing) {
+    throw new TreeseedKeyAgentError(
+      "wrapped_key_missing",
+      "No wrapped Treeseed machine key exists yet. Create one by unlocking interactively or with a startup passphrase.",
+      { keyPath: command.keyPath }
+    );
+  }
+  const machineKey = randomBytes(32);
+  replaceWrappedMachineKey(command.keyPath, machineKey, command.passphrase);
+  return machineKey;
+}
+function ok(response = {}) {
+  return { ok: true, ...response };
+}
+function fail(error, command) {
+  if (error instanceof TreeseedKeyAgentError) {
+    return {
+      ok: false,
+      code: error.code,
+      message: error.message,
+      status: {
+        running: true,
+        unlocked: false,
+        wrappedKeyPresent: readWrappedMachineKeyFile(command.keyPath).wrapped !== null,
+        migrationRequired: readWrappedMachineKeyFile(command.keyPath).migrationRequired,
+        keyPath: command.keyPath,
+        socketPath: command.socketPath,
+        idleTimeoutMs: command.idleTimeoutMs,
+        idleRemainingMs: 0
+      }
+    };
+  }
+  return {
+    ok: false,
+    code: "unlock_failed",
+    message: error instanceof Error ? error.message : String(error),
+    status: {
+      running: true,
+      unlocked: false,
+      wrappedKeyPresent: readWrappedMachineKeyFile(command.keyPath).wrapped !== null,
+      migrationRequired: readWrappedMachineKeyFile(command.keyPath).migrationRequired,
+      keyPath: command.keyPath,
+      socketPath: command.socketPath,
+      idleTimeoutMs: command.idleTimeoutMs,
+      idleRemainingMs: 0
+    }
+  };
+}
+function handleTreeseedKeyAgentCommand(command, session) {
+  maybeExpireSession(session);
+  if (command.command === "status") {
+    return ok({ status: createStatus(command, session) });
+  }
+  if (command.command === "lock") {
+    session.machineKey = null;
+    return ok({ status: createStatus(command, session) });
+  }
+  if (command.command === "touch") {
+    if (!session.machineKey) {
+      return fail(new TreeseedKeyAgentError("locked", "Treeseed secret session is locked."), command);
+    }
+    session.lastTouchedAt = Date.now();
+    return ok({ status: createStatus(command, session) });
+  }
+  if (command.command === "unlock") {
+    try {
+      session.machineKey = unwrapOrProvisionMachineKey(command);
+      session.lastTouchedAt = Date.now();
+      session.idleTimeoutMs = command.idleTimeoutMs;
+      return ok({ status: createStatus(command, session) });
+    } catch (error) {
+      return fail(error, command);
+    }
+  }
+  if (!session.machineKey) {
+    return fail(new TreeseedKeyAgentError("locked", "Treeseed secret session is locked."), command);
+  }
+  session.lastTouchedAt = Date.now();
+  return ok({
+    status: createStatus(command, session),
+    machineKey: session.machineKey.toString("base64")
+  });
+}
+async function requestTreeseedKeyAgent(command) {
+  if (!agentProcessAlive(command.socketPath) || !existsSync(command.socketPath)) {
+    throw new TreeseedKeyAgentError("daemon_unavailable", "Treeseed key-agent is not running.");
+  }
+  const responsePath = responseFifoPath(command.socketPath);
+  ensureFifo(responsePath);
+  try {
+    const responsePromise = Promise.resolve().then(() => readFileSync(responsePath, "utf8"));
+    writeFileSync(command.socketPath, `${JSON.stringify({ ...command, responsePath })}
+`, "utf8");
+    return JSON.parse((await responsePromise).trim() || "{}");
+  } finally {
+    rmSync(dirname(responsePath), { recursive: true, force: true });
+  }
+}
+async function socketAlreadyServed(socketPath) {
+  return agentProcessAlive(socketPath) && existsSync(socketPath);
+}
+async function removeStaleSocket(socketPath) {
+  if (!existsSync(socketPath)) {
+    return true;
+  }
+  try {
+    if (await socketAlreadyServed(socketPath)) {
+      return false;
+    }
+    rmSync(socketPath, { force: true });
+    clearPidFile(socketPath);
+    return true;
+  } catch {
+    rmSync(socketPath, { force: true });
+    clearPidFile(socketPath);
+    return true;
+  }
+}
+async function startTreeseedKeyAgentServer(options) {
+  const socketPath = options.socketPath ?? getTreeseedKeyAgentPaths().socketPath;
+  const canStart = await removeStaleSocket(socketPath);
+  if (!canStart) {
+    return;
+  }
+  ensureFifo(socketPath);
+  writePidFile(socketPath);
+  const session = {
+    machineKey: null,
+    lastTouchedAt: 0,
+    idleTimeoutMs: options.idleTimeoutMs ?? TRESEED_KEY_AGENT_IDLE_TIMEOUT_MS
+  };
+  process.on("exit", () => {
+    try {
+      rmSync(socketPath, { force: true });
+      clearPidFile(socketPath);
+    } catch {
+    }
+  });
+  for (; ; ) {
+    const line = readFileSync(socketPath, "utf8").trim();
+    if (!line) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(line);
+      const response = handleTreeseedKeyAgentCommand(parsed, session);
+      if (parsed.responsePath) {
+        writeFileSync(parsed.responsePath, `${JSON.stringify(response)}
+`, "utf8");
+      }
+    } catch (error) {
+      const fallback = fail(error, {
+        command: "status",
+        keyPath: options.keyPath,
+        socketPath,
+        idleTimeoutMs: options.idleTimeoutMs ?? TRESEED_KEY_AGENT_IDLE_TIMEOUT_MS
+      });
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed.responsePath) {
+          writeFileSync(parsed.responsePath, `${JSON.stringify(fallback)}
+`, "utf8");
+        }
+      } catch {
+      }
+    }
+  }
+}
+function assertTreeseedKeyAgentResponse(response, fallback = "Treeseed secret session request failed.") {
+  if (response.ok) {
+    return response;
+  }
+  throw new TreeseedKeyAgentError(
+    response.code ?? "unlock_failed",
+    response.message ?? fallback,
+    response.status ? { status: response.status } : void 0
+  );
+}
+function rotateWrappedMachineKeyPassphrase(keyPath, machineKey, passphrase) {
+  return replaceWrappedMachineKey(keyPath, machineKey, passphrase);
+}
+function migrateLegacyProjectMachineKeyToWrapped(keyPath, legacyKeyPath, passphrase) {
+  const legacyProjectKey = readLegacyProjectMachineKey(legacyKeyPath);
+  if (!legacyProjectKey) {
+    throw new TreeseedKeyAgentError(
+      "wrapped_key_migration_required",
+      "No legacy project machine key is available to migrate.",
+      { legacyKeyPath }
+    );
+  }
+  const wrapped = replaceWrappedMachineKey(keyPath, legacyProjectKey, passphrase);
+  if (legacyKeyPath !== keyPath) {
+    rmSync(legacyKeyPath, { force: true });
+  }
+  return wrapped;
+}
+function machineKeysEqual(left, right) {
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+export {
+  TREESEED_KEY_AGENT_IDLE_TIMEOUT_MS,
+  TREESEED_MACHINE_KEY_PASSPHRASE_ENV,
+  TRESEED_KEY_AGENT_IDLE_TIMEOUT_MS,
+  TRESEED_MACHINE_KEY_PASSPHRASE_ENV,
+  TRESEED_WRAPPED_MACHINE_KEY_KIND,
+  TRESEED_WRAPPED_MACHINE_KEY_VERSION,
+  TreeseedKeyAgentError,
+  assertTreeseedKeyAgentResponse,
+  getTreeseedKeyAgentPaths,
+  handleTreeseedKeyAgentCommand,
+  machineKeysEqual,
+  migrateLegacyProjectMachineKeyToWrapped,
+  readWrappedMachineKeyFile,
+  replaceWrappedMachineKey,
+  requestTreeseedKeyAgent,
+  rotateWrappedMachineKeyPassphrase,
+  startTreeseedKeyAgentServer,
+  unwrapMachineKey,
+  writeWrappedMachineKeyFile
+};

package/dist/operations/services/knowledge-coop-launch.d.ts

@@ -0,0 +1,90 @@
+import { checkTreeseedProviderConnections } from './config-runtime.ts';
+import { provisionCloudflareResources, verifyProvisionedCloudflareResources } from './deploy.ts';
+import { configuredRailwayServices, deployRailwayService, ensureRailwayScheduledJobs, verifyRailwayScheduledJobs } from './railway-deploy.ts';
+import { buildKnowledgeCoopKnowledgePackPackage, buildKnowledgeCoopTemplatePackage } from './knowledge-coop-packaging.ts';
+export type KnowledgeCoopLaunchFailurePhase = 'repo_provision_failed' | 'content_bootstrap_failed' | 'workflow_bootstrap_failed' | 'hosting_registration_failed' | 'runtime_connection_failed';
+export interface KnowledgeCoopManagedLaunchInput {
+    projectId: string;
+    teamId: string;
+    teamSlug?: string | null;
+    projectSlug: string;
+    projectName: string;
+    summary?: string | null;
+    sourceKind: 'blank' | 'template' | 'knowledge_pack';
+    sourceRef?: string | null;
+    hostingMode?: 'managed' | 'hybrid' | 'self_hosted';
+    publicSite?: boolean;
+    repoOwner?: string | null;
+    repoVisibility?: 'private' | 'public' | 'internal';
+    marketBaseUrl?: string | null;
+    projectApiBaseUrl?: string | null;
+    contactEmail?: string | null;
+    enableDefaultAgents?: boolean;
+    preserveWorkingTree?: boolean;
+}
+export interface KnowledgeCoopLaunchPhaseRecord {
+    phase: string;
+    status: 'running' | 'completed' | 'failed';
+    detail: string;
+    timestamp: string;
+}
+export interface KnowledgeCoopManagedLaunchResult {
+    workingRoot: string;
+    repository: {
+        slug: string;
+        owner: string;
+        name: string;
+        url: string;
+        defaultBranch: string;
+        stagingBranch: string | null;
+        visibility: 'private' | 'public' | 'internal';
+    };
+    workflows: {
+        repository: string | null;
+        workflows: Array<{
+            workflowPath: string;
+            changed: boolean;
+            workingDirectory?: string;
+            mode?: string;
+        }>;
+        secrets: {
+            existing: string[];
+            created: string[];
+        };
+        variables: {
+            existing: string[];
+            created: string[];
+        };
+    };
+    cloudflare: {
+        staging: ReturnType<typeof provisionCloudflareResources>;
+        prod: ReturnType<typeof provisionCloudflareResources>;
+        verification: ReturnType<typeof verifyProvisionedCloudflareResources>;
+    };
+    railway: {
+        services: ReturnType<typeof configuredRailwayServices>;
+        deployments: ReturnType<typeof deployRailwayService>[];
+        schedules: Awaited<ReturnType<typeof ensureRailwayScheduledJobs>>;
+        verification: Awaited<ReturnType<typeof verifyRailwayScheduledJobs>>;
+    };
+    projectApiBaseUrl: string;
+    projectSiteUrl: string;
+    projectMetadata: Record<string, unknown>;
+    defaultWorkstream: Record<string, unknown>;
+    phases: KnowledgeCoopLaunchPhaseRecord[];
+    templatePackage: ReturnType<typeof buildKnowledgeCoopTemplatePackage>;
+    knowledgePackPackage: ReturnType<typeof buildKnowledgeCoopKnowledgePackPackage>;
+}
+export interface KnowledgeCoopLaunchPreflightReport {
+    ok: boolean;
+    missingConfig: string[];
+    providerChecks: ReturnType<typeof checkTreeseedProviderConnections>;
+    commands: {
+        git: boolean;
+        gh: boolean;
+        wrangler: boolean;
+        railway: boolean;
+    };
+}
+export declare function validateKnowledgeCoopManagedLaunchPrerequisites(tenantRoot?: string): KnowledgeCoopLaunchPreflightReport;
+export declare function executeKnowledgeCoopManagedLaunch(input: KnowledgeCoopManagedLaunchInput): Promise<KnowledgeCoopManagedLaunchResult>;