@moondeck/station 0.0.1 → 1.0.1

package/lib/engine-connect.ts

@@ -0,0 +1,321 @@
+/**
+ * ADR-117: one-shot engine connect over the bridge.
+ *
+ * Much simpler than engine-login: nothing is spawned in a container. With a
+ * `secret` this runs the SAME paste paths the local UI's connect uses
+ * (`connectEngine` with pastedToken/apiKey, or the ADR-116 labeled-account
+ * sink); without one it runs OpenCode's re-detect. The secret arrives in the
+ * start frame, goes straight into `connectEngine`/`addEngineAccount`, and is
+ * never logged or echoed into any event.
+ */
+
+import {
+  HOST_ACCOUNT_SCOPE,
+  isEngineAccountLabel,
+  isEngineAccountScope,
+  isHostOpId,
+  MAX_ENGINE_CONNECT_LINE_CHARS,
+  MAX_ENGINE_CONNECT_SECRET_CHARS,
+  type EngineConnectEventFrame,
+  type EngineConnectKind,
+} from "../src/protocol";
+import type { CaptureFlowWire, CaptureResultWire } from "../src/cloud-credentials";
+import type { CaptureOutcome, EngineCaptureMaterial } from "./capture-flow";
+import { addEngineAccount, pastedSecretMaterial } from "./engine-accounts";
+import { connectEngine, type EngineKind } from "./engines";
+
+const CONNECT_TIMEOUT_MS = 2 * 60_000;
+// Connects are one store write each; labeled (workspace) connects never touch
+// a shared slot, so they run side by side — a user is never told to wait for
+// someone else's connect (ADR-136 sign-in box). Bounded, not serialised.
+const MAX_CONCURRENT_CONNECTS = 16;
+
+export type EmitEngineConnectEvent = (frame: EngineConnectEventFrame) => void;
+
+export interface AddAccountOutcome {
+  ok: boolean;
+  message: string;
+  id?: string;
+}
+
+export interface EngineConnectManagerOptions {
+  /** Re-advertise capabilities after a successful mutation (main.ts). */
+  readvertise(): void;
+  /** Refresh running agents of a kind after a DEFAULT credential change. */
+  refreshEngineAccountAgents(kind: string): Promise<void>;
+  /** Best-effort post-connect image maintenance (optional engines bake in). */
+  ensureStandardImage(): Promise<unknown>;
+  /** ADR-136 sign-in box: only labeled, workspace-scoped connects are
+   *  admitted — nothing here may write the host's default slot. */
+  workspaceOnly?: boolean;
+  /** The labeled-account sink. Defaults to the local `addEngineAccount`; the
+   *  sign-in box supplies the store-first one and awaits its write. */
+  addLabeledAccount?: (
+    kind: EngineConnectKind,
+    label: string,
+    secret: string,
+    scope: string,
+  ) => AddAccountOutcome | Promise<AddAccountOutcome>;
+  /** ADR-154: the sign-in box's sink for a capture flow. Absent elsewhere:
+   *  only the box writes cloud credentials. */
+  captureAccount?: (
+    flow: CaptureFlowWire,
+    kind: EngineConnectKind,
+    material: EngineCaptureMaterial,
+  ) => Promise<CaptureOutcome>;
+  timers?: {
+    setTimeout(handler: () => void, ms: number): NodeJS.Timeout;
+    clearTimeout(timer: NodeJS.Timeout): void;
+  };
+}
+
+interface ConnectOperation {
+  opId: string;
+  engine: EngineConnectKind;
+  emit: EmitEngineConnectEvent;
+  done: boolean;
+  timer: NodeJS.Timeout | null;
+}
+
+export class EngineConnectManager {
+  private readonly operations = new Map<string, ConnectOperation>();
+  /** Each connect's work, which goes on writing (a key, an account) after
+   *  its operation is finished or stopped. */
+  private readonly runs = new Set<Promise<void>>();
+
+  constructor(private readonly options: EngineConnectManagerOptions) {}
+
+  start(
+    opId: string,
+    engine: EngineConnectKind,
+    secret: string | undefined,
+    label: string | undefined,
+    emit: EmitEngineConnectEvent,
+    scope: string | undefined = undefined,
+    flow: CaptureFlowWire | undefined = undefined,
+  ): boolean {
+    if (!isHostOpId(opId) || this.operations.has(opId)) return false;
+    if (scope !== undefined && !isEngineAccountScope(scope)) return false;
+    if (
+      secret !== undefined &&
+      (secret.length < 1 || secret.length > MAX_ENGINE_CONNECT_SECRET_CHARS)
+    ) {
+      return false;
+    }
+    if (label !== undefined && !isEngineAccountLabel(label)) return false;
+    if (this.operations.size >= MAX_CONCURRENT_CONNECTS) {
+      safeEmit(emit, {
+        kind: "engine.connect.event",
+        opId,
+        engine,
+        phase: "done",
+        ok: false,
+        message: "Too many engine connects are running on this station right now; try again in a minute.",
+      });
+      return true;
+    }
+    const operation: ConnectOperation = {
+      opId,
+      engine,
+      emit,
+      done: false,
+      timer: null,
+    };
+    this.operations.set(opId, operation);
+    const timers = this.options.timers ?? {
+      setTimeout: (handler: () => void, ms: number) => setTimeout(handler, ms),
+      clearTimeout: (timer: NodeJS.Timeout) => clearTimeout(timer),
+    };
+    operation.timer = timers.setTimeout(() => {
+      this.finish(operation, false, "Engine connect timed out.");
+    }, CONNECT_TIMEOUT_MS);
+    operation.timer.unref?.();
+    const running = this.run(operation, secret, label, scope, flow).catch((error: unknown) => {
+      this.finish(
+        operation,
+        false,
+        error instanceof Error ? error.message : "Engine connect failed.",
+      );
+    });
+    this.runs.add(running);
+    void running.finally(() => this.runs.delete(running));
+    return true;
+  }
+
+  /** Resolves once no connect's work is under way, a stopped one's included:
+   *  what it writes has been written (ADR-154 §13's leaving waits for it). */
+  async idle(): Promise<void> {
+    while (this.runs.size > 0) await Promise.allSettled([...this.runs]);
+  }
+
+  stop(opId: string): void {
+    const operation = this.operations.get(opId);
+    if (operation) this.finish(operation, false, "Cancelled.");
+  }
+
+  stopAll(): void {
+    for (const operation of [...this.operations.values()]) {
+      this.finish(operation, false, "The connection was replaced.");
+    }
+  }
+
+  private async run(
+    operation: ConnectOperation,
+    secret: string | undefined,
+    label: string | undefined,
+    scope: string | undefined,
+    flow: CaptureFlowWire | undefined,
+  ): Promise<void> {
+    const { engine } = operation;
+    // ADR-154: a capture flow writes one revision of a cloud credential, on
+    // the sign-in box only, from the pasted secret alone.
+    if (flow !== undefined) {
+      if (!this.options.workspaceOnly || !this.options.captureAccount) {
+        this.finish(operation, false, "Only the Moondeck Cloud sign-in box writes cloud credentials.");
+        return;
+      }
+      if (secret === undefined) {
+        this.finish(operation, false, "Paste a token or API key.");
+        return;
+      }
+      const pasted = pastedSecretMaterial(engine, secret);
+      if (!pasted.ok) {
+        this.finish(operation, false, pasted.message);
+        return;
+      }
+      const outcome = await this.options.captureAccount(flow, engine, pasted.material);
+      if (operation.done) return;
+      this.finish(operation, outcome.ok, outcome.message, undefined, outcome.capture);
+      return;
+    }
+    const emitLine = (line: string): void => {
+      const bounded = line.trim().slice(0, MAX_ENGINE_CONNECT_LINE_CHARS);
+      if (!bounded || operation.done) return;
+      safeEmit(operation.emit, {
+        kind: "engine.connect.event",
+        opId: operation.opId,
+        engine,
+        phase: "line",
+        line: bounded,
+      });
+    };
+
+    if (secret === undefined && engine !== "opencode") {
+      this.finish(
+        operation,
+        false,
+        "This engine needs a credential here, or its sign-in run on the host.",
+      );
+      return;
+    }
+    if (secret !== undefined && engine === "opencode") {
+      // saveApiKey has no opencode branch and would claim success without
+      // storing anything — OpenCode connects on the host, we only re-detect.
+      this.finish(
+        operation,
+        false,
+        "OpenCode signs in on the host (`opencode auth login`); use Check connection here.",
+      );
+      return;
+    }
+
+    // ADR-136 sign-in box: a workspace account or nothing.
+    if (
+      this.options.workspaceOnly &&
+      (label === undefined || scope === undefined || scope === HOST_ACCOUNT_SCOPE)
+    ) {
+      this.finish(
+        operation,
+        false,
+        "The Moondeck Cloud sign-in box connects workspace accounts only.",
+      );
+      return;
+    }
+    // ADR-116 labeled extra account — the sink validates kind support.
+    if (label !== undefined && secret !== undefined) {
+      const sink =
+        this.options.addLabeledAccount ??
+        ((kind, accountLabel, value, accountScope) =>
+          addEngineAccount(kind, accountLabel, { token: value }, {}, accountScope));
+      const added = await sink(engine, label, secret, scope ?? HOST_ACCOUNT_SCOPE);
+      if (operation.done) return;
+      if (added.ok) this.afterMutation(engine, false);
+      this.finish(operation, added.ok, added.message, added.id);
+      return;
+    }
+    // ADR-131 D3: everything below writes the host's DEFAULT slot or re-detects
+    // a host-side login — the owner's credential, never a workspace's. A
+    // tenant scope must not reach it.
+    if (scope !== undefined && scope !== HOST_ACCOUNT_SCOPE) {
+      this.finish(
+        operation,
+        false,
+        "Workspace accounts need a label and a pasted secret; the host's own sign-in is not available to workspaces.",
+      );
+      return;
+    }
+
+    const result = await connectEngine(
+      engine as EngineKind,
+      secret === undefined
+        ? {}
+        : engine === "claude"
+          ? { pastedToken: secret }
+          : { apiKey: secret },
+      emitLine,
+    );
+    if (result.ok) this.afterMutation(engine, true);
+    this.finish(operation, result.ok, result.message);
+  }
+
+  /** Mirror the local UI's post-connect behavior (ui/server.ts). */
+  private afterMutation(engine: EngineConnectKind, defaultSlot: boolean): void {
+    this.options.readvertise();
+    void this.options.ensureStandardImage().catch(() => {});
+    if (defaultSlot) {
+      void this.options.refreshEngineAccountAgents(engine).catch(() => {});
+    }
+  }
+
+  private finish(
+    operation: ConnectOperation,
+    ok: boolean,
+    message: string,
+    accountId?: string,
+    capture?: CaptureResultWire,
+  ): void {
+    if (operation.done) return;
+    operation.done = true;
+    if (operation.timer) {
+      (this.options.timers ?? { clearTimeout }).clearTimeout(operation.timer);
+    }
+    this.operations.delete(operation.opId);
+    safeEmit(operation.emit, {
+      kind: "engine.connect.event",
+      opId: operation.opId,
+      engine: operation.engine,
+      phase: "done",
+      ok,
+      message,
+      ...(ok && accountId !== undefined ? { accountId } : {}),
+      ...(ok && capture !== undefined ? { capture } : {}),
+    });
+  }
+}
+
+function safeEmit(
+  emit: EmitEngineConnectEvent,
+  frame: EngineConnectEventFrame,
+): void {
+  try {
+    emit(frame);
+  } catch {
+    // The bridge socket owns delivery failures.
+  }
+}
+
+export function createEngineConnectManager(
+  options: EngineConnectManagerOptions,
+): EngineConnectManager {
+  return new EngineConnectManager(options);
+}

package/lib/engine-credential-env.ts

@@ -0,0 +1,52 @@
+import { ENGINE_ENV_CREDENTIAL_KEYS } from "../src/cloud-credentials";
+
+/** Every env-token engine's credential names, of any account kind. */
+export const ENGINE_CREDENTIAL_ENV_NAMES: ReadonlySet<string> = new Set(
+  Object.values(ENGINE_ENV_CREDENTIAL_KEYS).flat(),
+);
+
+/**
+ * Whether an exec env entry carries an env-token engine's credential: a name
+ * some account kind may set (ENGINE_ENV_CREDENTIAL_KEYS is the one list).
+ * ADR-154 §6 never puts such a value on the runner's argv, which every local
+ * user can read with `ps`. The docker and Apple providers pass it by name,
+ * from the exec client's own environment (cliExecEnv in
+ * task-environment/docker.ts). The machine and self providers, whose
+ * request environment rides a command line (buildRemoteCommand in
+ * machine-exec.ts), carry a leased launch's values in its single-use
+ * admission instead (credential-consumers/engine-anchor.ts).
+ */
+export function isEngineCredentialEnvName(name: string): boolean {
+  return ENGINE_CREDENTIAL_ENV_NAMES.has(name);
+}
+
+/**
+ * An agent's task token (ADR-048: its own permissions on the task's API)
+ * and the Managed Engine's names for it (ADR-128: the gateway's bearer):
+ * bearer credentials as an engine's own are.
+ */
+export const TASK_SECRET_ENV_NAMES: ReadonlySet<string> = new Set([
+  "UAI_TASK_TOKEN",
+  "UAI_INFERENCE_TOKEN",
+  "OPENAI_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "UAI_CUSTOM_API_KEY",
+  "AWS_BEARER_TOKEN_BEDROCK",
+]);
+
+/** Every name whose value never rides a runner's command line. */
+export const LAUNCH_SECRET_ENV_NAMES: ReadonlySet<string> = new Set([
+  ...ENGINE_CREDENTIAL_ENV_NAMES,
+  ...TASK_SECRET_ENV_NAMES,
+]);
+
+/**
+ * Whether an exec env entry carries a launch's secret: an engine's
+ * credential, or an agent's task token under any of its names. Like an
+ * engine credential, such a value is passed by name on the docker and Apple
+ * providers, and carried in a leased launch's admission on the machine and
+ * self providers (ADR-154 §6).
+ */
+export function isLaunchSecretEnvName(name: string): boolean {
+  return LAUNCH_SECRET_ENV_NAMES.has(name);
+}