@mycadet/cli 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/node_modules/@mycadet/local-mode/src/guardian-token.ts

@@ -0,0 +1,400 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  isDnsIndependentLoopbackUrl,
+  isLoopbackPublicUrl,
+} from "@mycadet/service-contracts/remote-web-pairing";
+
+import { guardianTokenPath, resolveConfigDirPaths } from "./config";
+import type { CliInvocation } from "./util";
+
+const GUARDIAN_TOKEN_REFRESH_TIMEOUT_MS = 15_000;
+const guardianTokenRefreshes = new Map<string, Promise<TokenResult>>();
+
+export const PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR =
+  "Paired assistant credentials are available only through the paired gateway proxy";
+export const PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR =
+  "Paired assistant target does not match the stored pairing";
+
+/** The persisted shape of an assistant's guardian token file. */
+export interface GuardianTokenData {
+  guardianPrincipalId: string;
+  accessToken: string;
+  /** ISO date string or epoch-ms number as returned by the gateway. */
+  accessTokenExpiresAt: string | number;
+  refreshToken: string;
+  /** ISO date string or epoch-ms number as returned by the gateway. */
+  refreshTokenExpiresAt: string | number;
+  refreshAfter: string;
+  isNew: boolean;
+  deviceId: string;
+  leasedAt: string;
+  /** Remote gateway bound to a credential imported through the pairing flow. */
+  pairedGatewayUrl?: string;
+}
+
+/**
+ * Persist an assistant's guardian token where every host-seam reader resolves
+ * it (`guardianTokenPath`). The per-assistant directory is created 0700 and the
+ * file written 0600; chmod after the write covers a pre-existing file whose
+ * mode drifted.
+ */
+export function saveGuardianToken(
+  configDir: string,
+  assistantId: string,
+  data: GuardianTokenData,
+): void {
+  const tokenPath = guardianTokenPath(configDir, assistantId);
+  fs.mkdirSync(path.dirname(tokenPath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(tokenPath, JSON.stringify(data, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  fs.chmodSync(tokenPath, 0o600);
+}
+
+/**
+ * The guardian refresh token is long-lived and replayable, so it is only
+ * transmitted over a confidential channel: HTTPS, or a host that stays on this
+ * machine whatever DNS answers (local dev, or a same-host reverse proxy /
+ * tunnel agent). Refreshing against any other plaintext `http://` URL is
+ * refused; an on-path attacker could otherwise capture the refresh token and
+ * rotate it into fresh credentials.
+ *
+ * A user-chosen malicious `https://` destination is intentionally out of
+ * scope: HTTPS protects the channel, and the access token already goes
+ * wherever the configured URL points. This guard targets the
+ * plaintext-interception vector.
+ */
+export function isConfidentialRefreshUrl(gatewayUrl: string): boolean {
+  try {
+    return (
+      new URL(gatewayUrl).protocol === "https:" ||
+      // The narrow loopback set, not {@link isLoopbackUrl}: this grants a
+      // plaintext channel the trust of an encrypted one, and a reserved
+      // `*.localhost` name resolves to whatever DNS says on a resolver that
+      // does not implement RFC 6761, which would put the refresh token on the
+      // wire to an arbitrary address.
+      isDnsIndependentLoopbackUrl(gatewayUrl)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether a URL's host is loopback, judged wide; false for unparseable URLs.
+ * Delegates to the shared pairing predicate so this package's refusals and the
+ * address checks in `@mycadet/service-contracts` judge a host by the same
+ * rules. Callers refuse what this matches; a caller granting loopback a
+ * privilege reads `isDnsIndependentLoopbackUrl` instead.
+ */
+export function isLoopbackUrl(url: string): boolean {
+  return isLoopbackPublicUrl(url);
+}
+
+function isAccessTokenExpired(data: GuardianTokenData): boolean {
+  const expiresAt = new Date(data.accessTokenExpiresAt).getTime();
+  if (!Number.isFinite(expiresAt)) return true;
+  return Date.now() >= expiresAt - 60_000;
+}
+
+function isRefreshTokenExpired(data: GuardianTokenData): boolean {
+  const expiresAt = new Date(data.refreshTokenExpiresAt).getTime();
+  if (!Number.isFinite(expiresAt)) return true;
+  return Date.now() >= expiresAt;
+}
+
+export type TokenResult =
+  | { ok: true; accessToken: string }
+  | { ok: false; status: number; error: string };
+
+/**
+ * Prefix of the machine-readable line `cadet gateway token refresh` writes
+ * to stderr on failure so hosts can distinguish a spent credential (401)
+ * from an unreachable gateway (503) without scraping the human message.
+ */
+export const GUARDIAN_REFRESH_ERROR_PREFIX = "CADET_REFRESH_ERROR=";
+
+/** Encode a structured refresh failure for the CLI's stderr. */
+export function formatGuardianRefreshCliFailure(
+  status: number,
+  error: string,
+): string {
+  return `${GUARDIAN_REFRESH_ERROR_PREFIX}${JSON.stringify({ status, error })}`;
+}
+
+/**
+ * Read the structured status out of a failed `cadet gateway token refresh`.
+ * An unlabeled non-zero exit defaults to 503: this spawn only runs when the
+ * on-disk refresh token is still unexpired, so a bare CLI failure is an
+ * unreachable or still-starting gateway, not a spent credential.
+ */
+export function parseGuardianRefreshCliFailure(
+  stdout: string,
+  stderr: string,
+): TokenResult {
+  const blob = `${stderr}\n${stdout}`;
+  for (const line of blob.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith(GUARDIAN_REFRESH_ERROR_PREFIX)) {
+      continue;
+    }
+    try {
+      const parsed: unknown = JSON.parse(
+        trimmed.slice(GUARDIAN_REFRESH_ERROR_PREFIX.length),
+      );
+      if (
+        parsed === null ||
+        typeof parsed !== "object" ||
+        !("status" in parsed) ||
+        typeof (parsed as { status: unknown }).status !== "number"
+      ) {
+        continue;
+      }
+      const status = (parsed as { status: number }).status;
+      if (status < 400 || status > 599) {
+        continue;
+      }
+      const errorText =
+        "error" in parsed &&
+        typeof (parsed as { error: unknown }).error === "string" &&
+        (parsed as { error: string }).error.trim() !== ""
+          ? (parsed as { error: string }).error
+          : "Failed to refresh guardian token";
+      return { ok: false, status, error: errorText };
+    } catch {
+      // Keep scanning; a later well-formed line still wins.
+    }
+  }
+  return {
+    ok: false,
+    status: 503,
+    error: "Failed to refresh guardian token",
+  };
+}
+
+export interface GuardianTokenOptions {
+  /**
+   * True when the entry was imported from another machine via `cadet pair`.
+   * A paired entry has no local daemon, so expired-refresh guidance points at
+   * re-pairing instead of `cadet hatch`/`cadet wake`.
+   */
+  paired?: boolean;
+  /** Gateway URL resolved for the paired proxy request. */
+  pairedGatewayUrl?: string;
+}
+
+export function getGuardianAccessToken(
+  assistantId: string,
+  configDir: string,
+  invocation: CliInvocation,
+  isLoopback: boolean,
+  env?: Record<string, string>,
+  options?: GuardianTokenOptions,
+): Promise<TokenResult> {
+  if (!isLoopback) {
+    return Promise.resolve({ ok: false, status: 403, error: "Forbidden" });
+  }
+
+  let tokenPaths: string[];
+  try {
+    const configDirs = [
+      configDir,
+      ...resolveConfigDirPaths({ ...process.env, ...env }),
+    ];
+    tokenPaths = [...new Set(configDirs)].map((dir) =>
+      guardianTokenPath(dir, assistantId),
+    );
+  } catch {
+    return Promise.resolve({
+      ok: false,
+      status: 400,
+      error: "Invalid assistant ID",
+    });
+  }
+
+  let raw: string | undefined;
+  let resolvedTokenPath: string | undefined;
+  for (const tokenPath of tokenPaths) {
+    try {
+      raw = fs.readFileSync(tokenPath, "utf-8");
+      resolvedTokenPath = tokenPath;
+      break;
+    } catch {
+      // Try the next compatible location.
+    }
+  }
+  if (raw === undefined || resolvedTokenPath === undefined) {
+    return Promise.resolve({
+      ok: false,
+      status: 404,
+      error: "Guardian token not found",
+    });
+  }
+
+  let data: GuardianTokenData;
+  try {
+    data = JSON.parse(raw) as GuardianTokenData;
+  } catch {
+    return Promise.resolve({
+      ok: false,
+      status: 500,
+      error: "Malformed guardian token file",
+    });
+  }
+
+  if (data.pairedGatewayUrl) {
+    if (!options?.paired) {
+      return Promise.resolve({
+        ok: false,
+        status: 403,
+        error: PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR,
+      });
+    }
+    if (options.pairedGatewayUrl !== data.pairedGatewayUrl) {
+      return Promise.resolve({
+        ok: false,
+        status: 403,
+        error: PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR,
+      });
+    }
+  } else if (options?.paired) {
+    if (!options.pairedGatewayUrl) {
+      return Promise.resolve({
+        ok: false,
+        status: 403,
+        error: PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR,
+      });
+    }
+    data = { ...data, pairedGatewayUrl: options.pairedGatewayUrl };
+    try {
+      saveGuardianToken(configDir, assistantId, data);
+    } catch {
+      return Promise.resolve({
+        ok: false,
+        status: 500,
+        error: "Failed to bind paired assistant credential",
+      });
+    }
+  }
+
+  if (!isAccessTokenExpired(data)) {
+    return Promise.resolve({ ok: true, accessToken: data.accessToken });
+  }
+
+  if (isRefreshTokenExpired(data)) {
+    return Promise.resolve({
+      ok: false,
+      status: 401,
+      error: options?.paired
+        ? "Guardian token expired. Run `cadet pair` on the assistant's machine, then re-import it from the app's connect flow or with `cadet connect import`."
+        : "Guardian token expired. Re-run `cadet hatch` or `cadet wake`.",
+    });
+  }
+
+  const existingRefresh = guardianTokenRefreshes.get(resolvedTokenPath);
+  if (existingRefresh) {
+    return existingRefresh;
+  }
+  const refresh = refreshToken(assistantId, invocation, env).finally(() => {
+    if (guardianTokenRefreshes.get(resolvedTokenPath) === refresh) {
+      guardianTokenRefreshes.delete(resolvedTokenPath);
+    }
+  });
+  guardianTokenRefreshes.set(resolvedTokenPath, refresh);
+  return refresh;
+}
+
+/** Resolve a paired bearer only when the proxy target matches its binding. */
+export function getPairedGuardianAccessToken(
+  assistantId: string,
+  pairedGatewayUrl: string,
+  configDir: string,
+  invocation: CliInvocation,
+  isLoopback: boolean,
+  env?: Record<string, string>,
+): Promise<TokenResult> {
+  return getGuardianAccessToken(
+    assistantId,
+    configDir,
+    invocation,
+    isLoopback,
+    env,
+    { paired: true, pairedGatewayUrl },
+  );
+}
+
+function refreshToken(
+  assistantId: string,
+  invocation: CliInvocation,
+  env?: Record<string, string>,
+): Promise<TokenResult> {
+  return new Promise((resolve) => {
+    const child = spawn(
+      invocation.command,
+      [...invocation.baseArgs, "gateway", "token", "refresh", assistantId],
+      {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        env: { ...process.env, ...env },
+      },
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const finish = (result: TokenResult) => {
+      if (done) {
+        return;
+      }
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({
+        ok: false,
+        status: 500,
+        error: "Guardian token refresh timed out",
+      });
+    }, GUARDIAN_TOKEN_REFRESH_TIMEOUT_MS);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        const accessToken = stdout.trim();
+        if (accessToken) {
+          finish({ ok: true, accessToken });
+        } else {
+          finish({ ok: false, status: 500, error: "CLI returned empty token" });
+        }
+      } else {
+        // This spawn only runs when the on-disk refresh token is still
+        // unexpired. A non-zero CLI exit is therefore a transport or
+        // gateway-availability failure unless the CLI labels a spent
+        // credential (401) or a local confidentiality refusal (403).
+        finish(parseGuardianRefreshCliFailure(stdout, stderr));
+      }
+    });
+
+    child.on("error", (err) => {
+      finish({
+        ok: false,
+        status: 500,
+        error: `Failed to spawn CLI: ${err.message}`,
+      });
+    });
+  });
+}

package/node_modules/@mycadet/local-mode/src/hatch.ts

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+
+import {
+  DAEMON_READINESS_WINDOW_MS,
+  DAEMON_STOP_TIMEOUT_MS,
+  HOST_WRAPPER_LONG_HEADROOM_MS,
+} from "./lifecycle-budgets";
+import type { CliInvocation } from "./util";
+
+// A hatch whose daemon comes up but never becomes ready spends the readiness
+// window first, then rolls back through the full daemon stop, so the wrapper
+// has to cover both plus the gateway and CES cleanup that follows.
+const HATCH_TIMEOUT_MS =
+  DAEMON_READINESS_WINDOW_MS +
+  DAEMON_STOP_TIMEOUT_MS +
+  HOST_WRAPPER_LONG_HEADROOM_MS;
+// Docker hatches pull images and wait up to 5 min for container readiness.
+const DOCKER_HATCH_TIMEOUT_MS = 10 * 60 * 1000;
+
+export type HatchResult =
+  | { ok: true; assistantId: string }
+  | { ok: false; status: number; error: string };
+
+export interface RunHatchOptions {
+  remote?: string;
+}
+
+export function runHatch(
+  invocation: CliInvocation,
+  options?: RunHatchOptions,
+): Promise<HatchResult> {
+  return new Promise((resolve) => {
+    const args = [...invocation.baseArgs, "hatch"];
+    if (options?.remote) {
+      args.push("--remote", options.remote);
+    }
+
+    const child = spawn(invocation.command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+
+    const finish = (result: HatchResult) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+
+    const timeoutMs =
+      options?.remote === "docker" ? DOCKER_HATCH_TIMEOUT_MS : HATCH_TIMEOUT_MS;
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({
+        ok: false,
+        status: 500,
+        error: `Hatch timed out after ${timeoutMs / 1000} seconds`,
+      });
+    }, timeoutMs);
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code !== 0) {
+        const error =
+          stderr.trim() ||
+          stdout.trim() ||
+          `Hatch failed: the CLI exited with code ${code ?? "unknown"} and produced no output.`;
+        finish({ ok: false, status: 500, error });
+        return;
+      }
+      const assistantId = stdout
+        .match(/Hatching (?:local|Docker) assistant:\s+(.+)/)?.[1]
+        ?.trim();
+      if (!assistantId) {
+        finish({
+          ok: false,
+          status: 500,
+          error:
+            "Hatch reported success but no assistant id was found in the CLI output.",
+        });
+        return;
+      }
+      finish({ ok: true, assistantId });
+    });
+
+    child.on("error", (err) => {
+      finish({
+        ok: false,
+        status: 500,
+        error: `Failed to spawn CLI: ${err.message}`,
+      });
+    });
+  });
+}

package/node_modules/@mycadet/local-mode/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * @mycadet/local-mode — shared host library for serving the local-assistant
+ * surface (lockfile reads, guardian-token issuance, gateway proxying, and the
+ * hatch/retire/wake lifecycle ops) over a loopback HTTP boundary. Consumed by the
+ * CLI `client` server and the web app's dev-server middleware so the local
+ * endpoint behaviour is defined exactly once instead of one host reaching into
+ * another's source tree. `@mycadet/environments`,
+ * `@mycadet/service-contracts`, and the source-only
+ * `@mycadet/avatar-manifest` are its only workspace dependencies.
+ */
+export {
+  stripSensitiveFields,
+  isLoopbackAddr,
+  headerHostIsLoopback,
+  originIsAllowed,
+  hasSameOriginCredentialProof,
+  resolveDevCliInvocation,
+} from "./util";
+export type { CliInvocation } from "./util";
+export {
+  DAEMON_STOP_TIMEOUT_MS,
+  HOST_WRAPPER_HEADROOM_MS,
+  HOST_WRAPPER_LONG_HEADROOM_MS,
+} from "./lifecycle-budgets";
+export {
+  resolveLocalConfigFromEnv,
+  resolveLockfilePaths,
+  resolveConfigDir,
+  resolveConfigDirPaths,
+  resolveRuntimeDir,
+  resolveLogDir,
+  resolveAssistantsDir,
+  resolveInstanceDir,
+  guardianTokenPath,
+} from "./config";
+export type { LocalEndpointConfig } from "./config";
+export type { LocalPathOptions } from "./paths";
+export {
+  defaultEnvironmentFilePath,
+  defaultEnvironmentFilePaths,
+  readDefaultEnvironment,
+  resolveEnvironmentName,
+} from "./environment";
+export {
+  getLockfileData,
+  renameLockfileAssistantIfPresent,
+  stampLockfileAssistantOnboardedIfPresent,
+  upsertLockfileAssistant,
+  upsertRendererLockfileAssistant,
+  replacePlatformAssistants,
+  isActiveAssistant,
+  isPairedLockfileEntry,
+} from "./lockfile";
+export type { LockfileResult, WriteResult } from "./lockfile";
+export { withLockfileLock } from "./lockfile-lock";
+export type { LockfileLockResult } from "./lockfile-lock";
+export { parseLockfile } from "./lockfile-contract";
+export type {
+  Lockfile,
+  LockfileAssistant,
+  LocalAssistantResources,
+  LockfileWriteResult,
+} from "./lockfile-contract";
+export { runHatch } from "./hatch";
+export type { HatchResult } from "./hatch";
+export { runRetire } from "./retire";
+export type { RetireOptions, RetireResult } from "./retire";
+export { unpairAssistant } from "./unpair";
+export {
+  pairAssistant,
+  checkPairedAssistantName,
+  pairingStart,
+  pairingPoll,
+  pairingCancel,
+  connectImport,
+} from "./pair";
+export type {
+  PairedAssistantCredentials,
+  PairOptions,
+  PairResult,
+  PairRefusal,
+  PairingFailure,
+  PairingFailureReason,
+  PairingStarted,
+  PairingStartResult,
+  PairingPollOptions,
+  PairingPollResult,
+  ConnectImportOptions,
+  ConnectImportResult,
+} from "./pair";
+export { runSleep } from "./sleep";
+export type { SleepResult } from "./sleep";
+export { runWake } from "./wake";
+export type { WakeOptions, WakeResult } from "./wake";
+export { runDevicesList, runDevicesRevoke } from "./devices";
+export type {
+  DeviceRecord,
+  DevicesListResult,
+  DevicesRevokeResult,
+} from "./devices";
+export { runUpgrade, isValidReleaseVersion } from "./upgrade";
+export type { UpgradeOptions, UpgradeResult } from "./upgrade";
+export { getLocalAssistantStatus } from "./status";
+export { readLockfileAssistantAvatar } from "./avatar";
+export type {
+  LocalAssistantRuntimeState,
+  LocalAssistantStatusResult,
+} from "./status";
+export {
+  getGuardianAccessToken,
+  getPairedGuardianAccessToken,
+  isConfidentialRefreshUrl,
+  formatGuardianRefreshCliFailure,
+  parseGuardianRefreshCliFailure,
+  PAIRED_GUARDIAN_TOKEN_HOST_ONLY_ERROR,
+  PAIRED_GUARDIAN_TARGET_MISMATCH_ERROR,
+  GUARDIAN_REFRESH_ERROR_PREFIX,
+  saveGuardianToken,
+} from "./guardian-token";
+export type {
+  TokenResult,
+  GuardianTokenData,
+  GuardianTokenOptions,
+} from "./guardian-token";
+export {
+  authorizePairedForwardHeaders,
+  parseGatewayUrl,
+  readAllowedGatewayPorts,
+  resolveGatewayProxyTarget,
+  parsePairedGatewayUrl,
+  pairedGatewayTargetsFromLockfile,
+  readPairedGatewayTargets,
+  resolvePairedGatewayProxyTarget,
+  sanitizePairedForwardHeaders,
+} from "./gateway-proxy";
+export type {
+  GatewayTarget,
+  GatewayParseResult,
+  GatewayProxyDecision,
+  PairedForwardAuthorizationResult,
+  PairedGuardianTokenProvider,
+} from "./gateway-proxy";

package/node_modules/@mycadet/local-mode/src/lifecycle-budgets.ts

@@ -0,0 +1,47 @@
+/**
+ * Timeouts shared between the CLI's lifecycle commands and the host wrappers
+ * that spawn them.
+ *
+ * A host wrapper kills the CLI subprocess when its own timeout expires, so
+ * every wrapper timeout must sit above the budget of the command it runs.
+ * Otherwise a slow-but-succeeding command is killed partway and misreported as
+ * a failure, and the SIGKILL ceiling it was waiting on is never reached.
+ * Deriving the wrapper timeouts from the same constant keeps the two from
+ * drifting apart.
+ */
+
+/**
+ * SIGKILL ceiling for stopping the assistant daemon.
+ *
+ * Derived from the daemon's own budget rather than guessed. Its shutdown arms
+ * a 30s force-exit timer; when that fires it hands the SQLite WAL fold to a
+ * detached subprocess that outlives `process.exit` and then exits. So a daemon
+ * whose event loop still runs is gone within 30s with its WAL folded, and a
+ * daemon whose event loop is blocked never fires that timer at all, which no
+ * amount of extra waiting changes. Waiting past the daemon's own ceiling plus
+ * a margin therefore buys nothing and only delays the SIGKILL.
+ *
+ * A ceiling, not a delay. The CLI returns as soon as the process exits, so
+ * this only applies to a daemon that is genuinely wedged.
+ */
+export const DAEMON_STOP_TIMEOUT_MS = 45_000;
+
+/**
+ * Headroom a host wrapper allows on top of {@link DAEMON_STOP_TIMEOUT_MS} for
+ * the rest of a command: the gateway's drain window, the CES and Qdrant stops,
+ * and any archiving or bring-up the command does around them.
+ */
+export const HOST_WRAPPER_HEADROOM_MS = 30_000;
+
+/** Headroom for commands that also archive or provision after stopping. */
+export const HOST_WRAPPER_LONG_HEADROOM_MS = 60_000;
+
+/**
+ * How long the CLI polls a freshly started daemon for readiness before giving
+ * up on it.
+ *
+ * A command that starts a daemon spends this before it can even discover it
+ * needs to stop one, so its wrapper budget has to cover the wait and the stop
+ * that may follow it, not just the stop.
+ */
+export const DAEMON_READINESS_WINDOW_MS = 60_000;