@moondeck/station 0.0.1 → 1.0.0

package/lib/capture-flow.ts

@@ -0,0 +1,332 @@
+/**
+ * ADR-154 §3 on the sign-in box: write one capture as one immutable revision,
+ * exactly where the cloud's flow says, and never read it back.
+ *
+ * The cloud begins every capture (lib/credential-metadata.ts) and hands the
+ * box the revision's parameter names. The box checks them, builds the two
+ * parts from what the sign-in produced, and creates them, broker-only part
+ * first:
+ *
+ *  - lease-readable: what a task may receive: a static key as entered, or an
+ *    OAuth login's brokered copy (access token in, refresh token replaced);
+ *  - broker-only (OAuth logins only): the full material, which only the
+ *    broker reads and only the broker ever overwrites.
+ *
+ * Both are created, never overwritten (`putImmutable`), with tags naming the
+ * workspace and person the role policy checks. The answer carries names and
+ * versions, never material.
+ */
+import {
+  ENGINE_CREDENTIAL_FILES,
+  ENGINE_ENV_CREDENTIAL_KEYS,
+  MAX_CREDENTIAL_VALUE_BYTES,
+  parseCaptureFlowWire,
+  serializeLeasedValue,
+  type CaptureFlowWire,
+  type CaptureResultWire,
+  type CredentialLocation,
+} from "../src/cloud-credentials";
+import { parseCustomConnectionMaterial, type CustomConnectionMaterial } from "../src/custom-connections";
+import { ImmutableParameterAbortedError, storeFailureKind, type CredentialStore } from "./credential-store";
+import { laneFor } from "./token-lanes/registry";
+import {
+  emptyRefreshMeta,
+  refreshMetaFrom,
+  type CredentialFiles,
+  type RefreshMeta,
+} from "./token-lanes/types";
+
+/** What only the broker reads: the full material of an OAuth login. */
+export interface BrokerEngineValue {
+  v: 1;
+  part: "broker";
+  location: CredentialLocation;
+  class: "engine";
+  lane: string;
+  files: CredentialFiles;
+  refresh: RefreshMeta;
+}
+
+export type EngineCaptureMaterial =
+  | { authKind: "env"; env: Record<string, string> }
+  | { authKind: "config-dir"; files: CredentialFiles }
+  | { authKind: "custom-connection"; connection: CustomConnectionMaterial };
+
+export interface BuiltCapture {
+  lease: string;
+  broker: string | null;
+  expiresAt: number | null;
+  /** Metadata the lease part also carries (never material): an SSH key's
+   *  public half, so a retry can tell which key the revision holds. The
+   *  identity tags always win over these. */
+  leaseTags?: Record<string, string>;
+}
+
+export type ParsedCaptureFlow = CaptureFlowWire & { location: CredentialLocation };
+
+export function parseCaptureFlow(value: unknown): ParsedCaptureFlow | null {
+  return parseCaptureFlowWire(value);
+}
+
+function onlyKeys(record: Record<string, string>, allowed: readonly string[]): boolean {
+  const keys = Object.keys(record);
+  return keys.length > 0 && keys.every((key) => allowed.includes(key));
+}
+
+/**
+ * The two parts of an AI account's capture, or an error the sign-in shows.
+ * The flow's broker part must exist exactly when the material rotates: a
+ * rotating login without one would leave its refresh token nowhere the
+ * broker can reach (and a task holding it would refresh it itself), and a
+ * static key needs none.
+ */
+export function buildEngineCapture(
+  flow: ParsedCaptureFlow,
+  material: EngineCaptureMaterial,
+): BuiltCapture | { error: string } {
+  const { location } = flow;
+  if (location.class !== "engine") {
+    return { error: "This capture is not an AI account." };
+  }
+  const kind = location.engineKind!;
+  if (material.authKind === "custom-connection") {
+    const connection = parseCustomConnectionMaterial(material.connection);
+    if (!connection || connection.engine !== kind || flow.brokerParameter !== null) {
+      return { error: "unsupported" };
+    }
+    return {
+      lease: serializeLeasedValue({ v: 1, part: "lease", location, class: "engine", authKind: "custom-connection", connection }),
+      broker: null,
+      expiresAt: connection.expiresAt ?? null,
+    };
+  }
+  if (material.authKind === "env") {
+    if (!onlyKeys(material.env, ENGINE_ENV_CREDENTIAL_KEYS[kind] ?? [])) {
+      return { error: "This key is not one the engine reads." };
+    }
+    if (flow.brokerParameter !== null) {
+      return { error: "A pasted key does not rotate; it has no broker part." };
+    }
+    return {
+      lease: serializeLeasedValue({
+        v: 1,
+        part: "lease",
+        location,
+        class: "engine",
+        authKind: "env",
+        env: { ...material.env },
+      }),
+      broker: null,
+      expiresAt: null,
+    };
+  }
+  if (!onlyKeys(material.files, ENGINE_CREDENTIAL_FILES[kind] ?? [])) {
+    return { error: "The sign-in produced files the engine does not use." };
+  }
+  const lane = laneFor(
+    { kind, authKind: "config-dir", id: location.credentialId!, scope: location.scope },
+    material.files,
+  );
+  if (lane === null) {
+    if (flow.brokerParameter !== null) {
+      return { error: "This credential does not rotate; it has no broker part." };
+    }
+    return {
+      lease: serializeLeasedValue({
+        v: 1,
+        part: "lease",
+        location,
+        class: "engine",
+        authKind: "config-dir",
+        files: { ...material.files },
+        expiresAt: null,
+      }),
+      broker: null,
+      expiresAt: null,
+    };
+  }
+  if (flow.brokerParameter === null) {
+    return { error: "This sign-in rotates, and the cloud gave it nowhere to keep its refresh token." };
+  }
+  const expiresAt = lane.expiresAt(material.files);
+  const broker: BrokerEngineValue = {
+    v: 1,
+    part: "broker",
+    location,
+    class: "engine",
+    lane: lane.id,
+    files: { ...material.files },
+    refresh: { ...emptyRefreshMeta(lane.id), expiresAt },
+  };
+  return {
+    lease: serializeLeasedValue({
+      v: 1,
+      part: "lease",
+      location,
+      class: "engine",
+      authKind: "config-dir",
+      files: lane.brokeredCopy(material.files),
+      expiresAt,
+    }),
+    broker: JSON.stringify(broker),
+    expiresAt,
+  };
+}
+
+/** The tags every part carries: the identity a retry is checked against,
+ *  and the workspace and person the role policy compares. */
+export function captureTags(
+  flow: ParsedCaptureFlow,
+  part: "lease" | "broker",
+): Record<string, string> {
+  return {
+    ...(flow.orgId !== null ? { org: flow.orgId } : {}),
+    ...(flow.userId !== null ? { user: flow.userId } : {}),
+    uai_credential: flow.credentialId,
+    uai_revision: flow.revision,
+    uai_part: part,
+  };
+}
+
+/**
+ * Create both parts, broker-only first: a crash after it leaves a revision
+ * the cloud never promotes, which the sweep removes; a lease-readable part
+ * never exists without the refresh token it was brokered from. A retry after
+ * a lost answer finds its own create by its tags and carries on.
+ */
+export async function writeCapture(
+  store: CredentialStore,
+  flow: ParsedCaptureFlow,
+  built: BuiltCapture,
+  options: { signal?: AbortSignal } = {},
+): Promise<CaptureResultWire> {
+  if (!store.putImmutable) {
+    throw new Error("This credential store cannot create immutable parameters.");
+  }
+  // A caller's deadline covers the writes too: past it nothing more is sent,
+  // and a part already sent is the cloud's to sweep with the revision.
+  const { signal } = options;
+  if (built.broker !== null) {
+    if (flow.brokerParameter === null) throw new Error("no broker part to write");
+    if (signal?.aborted) throw new ImmutableParameterAbortedError();
+    await store.putImmutable(flow.brokerParameter, built.broker, captureTags(flow, "broker"), { signal });
+  }
+  if (signal?.aborted) throw new ImmutableParameterAbortedError();
+  await store.putImmutable(
+    flow.leaseParameter,
+    built.lease,
+    { ...built.leaseTags, ...captureTags(flow, "lease") },
+    { signal },
+  );
+  return {
+    credentialId: flow.credentialId,
+    revision: flow.revision,
+    // Created, never overwritten by the box: version 1. Only the broker
+    // writes later versions.
+    leaseVersion: 1,
+    expiresAt: built.expiresAt,
+  };
+}
+
+export interface CaptureOutcome {
+  ok: boolean;
+  message: string;
+  /** Present exactly when `ok`. */
+  capture?: CaptureResultWire;
+}
+
+/**
+ * The sign-in box's sink for an AI account's capture: check the flow, build
+ * both parts, create them. Every failure is a message the sign-in shows, and
+ * none of them carries material.
+ */
+export async function captureEngineAccount(
+  store: CredentialStore | null,
+  wire: CaptureFlowWire,
+  engine: string,
+  material: EngineCaptureMaterial,
+  engineLabel: string,
+): Promise<CaptureOutcome> {
+  const flow = parseCaptureFlow(wire);
+  if (!flow || flow.location.class !== "engine" || flow.location.engineKind !== engine) {
+    return { ok: false, message: "The sign-in's destination is invalid; nothing was kept." };
+  }
+  if (!store) {
+    return { ok: false, message: "This station has no credential store to hold the account." };
+  }
+  const built = buildEngineCapture(flow, material);
+  if ("error" in built) return { ok: false, message: built.error };
+  try {
+    const capture = await writeCapture(store, flow, built);
+    return { ok: true, message: `${engineLabel} signed in.`, capture };
+  } catch (err) {
+    // A category, never the error's words: a store failure can echo input.
+    console.warn(`[capture-flow] ${engine} ${flow.credentialId}/${flow.revision}: write failed (${storeFailureKind(err)})`);
+    return {
+      ok: false,
+      message: "The credential store refused the write; nothing was kept on this station.",
+    };
+  }
+}
+
+
+/**
+ * A stored broker-only part, exactly, for the revision at `expected`; null
+ * for anything else. Only the broker reads it (token-broker-revision.ts).
+ */
+export function parseBrokerEngineValue(
+  raw: string,
+  expected: CredentialLocation,
+): BrokerEngineValue | null {
+  if (typeof raw !== "string" || new TextEncoder().encode(raw).length > MAX_CREDENTIAL_VALUE_BYTES) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const o = parsed as Record<string, unknown>;
+  const location = o.location as Record<string, unknown> | null;
+  if (
+    o.v !== 1 ||
+    o.part !== "broker" ||
+    o.class !== "engine" ||
+    expected.class !== "engine" ||
+    typeof o.lane !== "string" ||
+    !location ||
+    typeof location !== "object" ||
+    location.class !== expected.class ||
+    location.scope !== expected.scope ||
+    location.ownerId !== expected.ownerId ||
+    location.engineKind !== expected.engineKind ||
+    location.credentialId !== expected.credentialId ||
+    location.revision !== expected.revision
+  ) {
+    return null;
+  }
+  const allowed = ENGINE_CREDENTIAL_FILES[expected.engineKind ?? ""] ?? [];
+  const files = o.files as Record<string, unknown> | null;
+  if (
+    !files ||
+    typeof files !== "object" ||
+    Array.isArray(files) ||
+    Object.keys(files).length === 0 ||
+    !Object.entries(files).every(([name, text]) => allowed.includes(name) && typeof text === "string")
+  ) {
+    return null;
+  }
+  const refresh = refreshMetaFrom(o.refresh);
+  if (!refresh || refresh.lane !== o.lane) return null;
+  return {
+    v: 1,
+    part: "broker",
+    location: expected,
+    class: "engine",
+    lane: o.lane,
+    files: files as CredentialFiles,
+    refresh,
+  };
+}

package/lib/cloud-credential-cleanup-adapter.ts

@@ -0,0 +1,123 @@
+/**
+ * Fail-closed boundary between the in-memory lease registry and the durable
+ * task credential cleanup procedure.
+ *
+ * The registry describes why its gate closed and whether the cleanup is
+ * selective or whole-task. The durable coordinator uses a smaller audit
+ * vocabulary and represents selectivity solely by the presence of
+ * `credentialIds`. Keep that lossy conversion here so a new registry reason
+ * cannot accidentally become a whole-task cleanup (or vice versa).
+ */
+import type {
+  CredentialCleanupReason as LeaseCredentialCleanupReason,
+  CredentialCleanupRequest as LeaseCredentialCleanupRequest,
+} from "./cloud-credential-leases";
+import type {
+  TaskCredentialCleanupCoordinator,
+  TaskCredentialCleanupReason,
+  TaskCredentialCleanupRequest,
+} from "./task-credential-cleanup";
+
+export type CredentialCleanupRunnerKind = "owned" | "task-machine";
+
+type LeaseCleanupMode = LeaseCredentialCleanupRequest["mode"];
+type CleanupReasonByMode = Readonly<
+  Record<LeaseCleanupMode, TaskCredentialCleanupReason | null>
+>;
+
+/**
+ * `null` marks a reason/mode pair the registry must never emit. The `satisfies`
+ * clause makes additions to either the reason union or the mode union a
+ * compile-time decision at this boundary.
+ */
+const CLEANUP_REASON_BY_MODE = {
+  starting: { selective: null, full: null },
+  recovery: { selective: null, full: "restart" },
+  superseded: { selective: null, full: "assignment" },
+  "minimum-revision": { selective: "removed", full: "removed" },
+  "manifest-narrowed": { selective: null, full: "removed" },
+  denied: { selective: null, full: "denied" },
+  expired: { selective: null, full: "expired" },
+  stopped: { selective: null, full: "stop" },
+  parked: { selective: null, full: "park" },
+  teardown: { selective: null, full: "teardown" },
+  // The registry emits this fail-closed fallback when its synchronous gate
+  // callback throws during assignment start/recovery.  The durable vocabulary
+  // has no internal-callback-failure reason; `restart` is the conservative
+  // whole-task recovery category and, critically, lets the coordinator write
+  // its pending witness before retrying the quarantine.
+  "cleanup-failed": { selective: null, full: "restart" },
+  // A launch slot that could not be retired in its runtime (ADR-154 §6):
+  // the whole run's cleanup, in the same conservative category.
+  "fence-failed": { selective: null, full: "restart" },
+  // Shutdown ends assignments without a cleanup: the next process's
+  // recovery sweep runs it.
+  shutdown: { selective: null, full: null },
+  "lease-replaced": { selective: "removed", full: null },
+} as const satisfies Readonly<
+  Record<LeaseCredentialCleanupReason, CleanupReasonByMode>
+>;
+
+function mappedReason(
+  reason: LeaseCredentialCleanupReason,
+  mode: LeaseCleanupMode,
+): TaskCredentialCleanupReason {
+  const mapped = CLEANUP_REASON_BY_MODE[reason][mode];
+  if (mapped === null) {
+    throw new Error(`invalid ${mode} lease credential cleanup reason: ${reason}`);
+  }
+  return mapped;
+}
+
+/** Convert one registry callback into the coordinator's durable request. */
+export function adaptLeaseCredentialCleanupRequest(
+  request: Readonly<LeaseCredentialCleanupRequest>,
+  runnerKind: CredentialCleanupRunnerKind,
+): TaskCredentialCleanupRequest {
+  const reason = mappedReason(request.reason, request.mode);
+
+  if (request.mode === "selective") {
+    if (request.removeFilesSession) {
+      throw new Error("selective credential cleanup cannot remove the files session");
+    }
+    if (request.removed.length === 0) {
+      throw new Error("selective credential cleanup requires a removed credential");
+    }
+    // Several revisions of one stable credential can retire before a floor
+    // grant lands. Inventory is keyed by the stable id, so collapse those
+    // qualified identities rather than widening or rejecting the cleanup.
+    const credentialIds = [
+      ...new Set(request.removed.map((identity) => identity.credentialId)),
+    ];
+    return {
+      taskId: request.assignment.taskId,
+      runEpoch: request.assignment.runEpoch,
+      reason,
+      credentialIds,
+    };
+  }
+
+  if (request.removed.length !== 0) {
+    throw new Error("full credential cleanup cannot carry selective identities");
+  }
+  const expectedFilesSession = runnerKind === "task-machine";
+  if (request.removeFilesSession !== expectedFilesSession) {
+    throw new Error(
+      `${runnerKind} full credential cleanup has the wrong files-session scope`,
+    );
+  }
+  return {
+    taskId: request.assignment.taskId,
+    runEpoch: request.assignment.runEpoch,
+    reason,
+  };
+}
+
+/** Callback with the exact shape consumed by TaskCredentialLeaseRegistry. */
+export function createLeaseCredentialCleanupAdapter(
+  coordinator: Pick<TaskCredentialCleanupCoordinator, "cleanup">,
+  runnerKind: CredentialCleanupRunnerKind,
+): (request: LeaseCredentialCleanupRequest) => Promise<void> {
+  return (request) =>
+    coordinator.cleanup(adaptLeaseCredentialCleanupRequest(request, runnerKind));
+}