@moondeck/station 0.0.1 → 1.0.0

package/lib/credential-cleanup-inventory.ts

@@ -0,0 +1,490 @@
+/**
+ * ADR-154's durable, non-secret inventory of task-local credential paths.
+ *
+ * Writers remember a path before placing credential material there. Cleanup
+ * later removes the row only after it has independently verified the path is
+ * absent. This module records the witness; it deliberately does not perform
+ * cleanup or inspect credential contents.
+ */
+import { and, asc, eq, lte, sql } from "drizzle-orm";
+
+import { idPathSegment } from "../src/cloud-credentials";
+import type {
+  HostCredentialCleanupPath,
+  HostCredentialCleanupPending,
+  HostCredentialCleanupRestop,
+  HostLeasedEngineRuntime,
+} from "../db/schema";
+import { getDb, schema, type Db } from "./db";
+import { assertSafeHostTaskId } from "./task-identity";
+import {
+  LEASE_AWS_CONFIG_FILE,
+  LEASE_CREDENTIALS_FILE,
+} from "./lease";
+import {
+  serializeTaskEnvironmentLocator,
+  type TaskEnvironmentLocator,
+} from "./task-environment/types";
+
+type InventoryExecutor = Pick<Db, "select" | "insert" | "delete">;
+
+export interface CredentialCleanupPathKey {
+  taskId: string;
+  runEpoch: number;
+  runtime: TaskEnvironmentLocator;
+  lane: CredentialCleanupLane;
+  path: string;
+}
+
+export type CredentialCleanupLane =
+  | "engine-auth"
+  | "github"
+  | "ssh"
+  | "files-session";
+
+export type CredentialCleanupPendingReason =
+  | "removed"
+  | "denied"
+  | "expired"
+  | "assignment"
+  | "restart"
+  | "stop"
+  | "park"
+  | "teardown";
+
+const CLEANUP_PENDING_REASONS = new Set<CredentialCleanupPendingReason>([
+  "removed",
+  "denied",
+  "expired",
+  "assignment",
+  "restart",
+  "stop",
+  "park",
+  "teardown",
+]);
+
+export interface CredentialCleanupPendingInput {
+  taskId: string;
+  runEpoch: number;
+  reason: CredentialCleanupPendingReason;
+}
+
+export interface CredentialCleanupPathInput extends CredentialCleanupPathKey {
+  credentialId: string;
+}
+
+function positiveRunEpoch(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error("credential cleanup run epoch must be a positive safe integer");
+  }
+}
+
+function normalizedPending(input: CredentialCleanupPendingInput): void {
+  assertSafeHostTaskId(input.taskId);
+  positiveRunEpoch(input.runEpoch);
+  if (!CLEANUP_PENDING_REASONS.has(input.reason)) {
+    throw new Error("credential cleanup reason is invalid");
+  }
+}
+
+/**
+ * Durable fail-closed witness written before cleanup closes any gate or starts
+ * any asynchronous work.  A newer assignment can only raise the recorded
+ * epoch; a delayed older cleanup must never move the boot-recovery floor back.
+ */
+export function rememberCredentialCleanupPending(
+  input: CredentialCleanupPendingInput,
+  db: InventoryExecutor = getDb(),
+  now = Date.now(),
+): void {
+  normalizedPending(input);
+  db.insert(schema.hostCredentialCleanupPending)
+    .values({
+      taskId: input.taskId,
+      runEpoch: input.runEpoch,
+      reason: input.reason,
+      createdAt: now,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: schema.hostCredentialCleanupPending.taskId,
+      set: {
+        runEpoch: sql`max(${schema.hostCredentialCleanupPending.runEpoch}, excluded.run_epoch)`,
+        reason: sql`CASE WHEN excluded.run_epoch >= ${schema.hostCredentialCleanupPending.runEpoch} THEN excluded.reason ELSE ${schema.hostCredentialCleanupPending.reason} END`,
+        updatedAt: now,
+      },
+    })
+    .run();
+}
+
+export function listCredentialCleanupPending(
+  db: InventoryExecutor = getDb(),
+): HostCredentialCleanupPending[] {
+  return db
+    .select()
+    .from(schema.hostCredentialCleanupPending)
+    .orderBy(asc(schema.hostCredentialCleanupPending.taskId))
+    .all();
+}
+
+/** Clear only a marker no newer than the cleanup that just succeeded. */
+export function forgetCredentialCleanupPending(
+  taskId: string,
+  throughRunEpoch: number,
+  db: InventoryExecutor = getDb(),
+): void {
+  assertSafeHostTaskId(taskId);
+  positiveRunEpoch(throughRunEpoch);
+  db.delete(schema.hostCredentialCleanupPending)
+    .where(
+      and(
+        eq(schema.hostCredentialCleanupPending.taskId, taskId),
+        lte(schema.hostCredentialCleanupPending.runEpoch, throughRunEpoch),
+      ),
+    )
+    .run();
+}
+
+/** An engine account's file, or the intermediate its writer stages
+ * (`.uai-tmp`) before renaming it into place. */
+const CONNECTION_AUTH_PATH = /^\/home\/node\/\.uai-connection\/[a-f0-9]{64}(?:\/(?:auth\.json|config\.toml|aws-config|aws-credentials))?$/;
+const ENGINE_AUTH_PATH = /^\/home\/node\/(?:\.codex(?:-acct-[A-Za-z0-9_-]+)?(?:-agent-[A-Za-z0-9_-]+)?|\.grok(?:-acct-[A-Za-z0-9_-]+)?|\.local\/share\/opencode(?:-acct-[A-Za-z0-9_-]+)?)\/auth\.json(?:\.uai-tmp)?$/;
+/** A file a writer stages (`.uai-tmp`) before renaming it into place. */
+function andStaged(...paths: string[]): string[] {
+  return paths.flatMap((path) => [path, `${path}.uai-tmp`]);
+}
+const GITHUB_PATHS = new Set(
+  andStaged("/home/node/.config/gh/hosts.yml", "/home/node/.config/gh/uai.gitconfig"),
+);
+const SSH_PATHS = new Set(
+  andStaged(
+    "/home/node/.ssh/id_ed25519",
+    "/home/node/.ssh/id_ed25519.pub",
+    "/home/node/.ssh/allowed_signers",
+    "/home/node/.ssh/uai-signing.gitconfig",
+    "/home/node/.ssh/uai-transport.gitconfig",
+  ),
+);
+const FILES_SESSION_PATHS = new Set([
+  LEASE_CREDENTIALS_FILE,
+  `${LEASE_CREDENTIALS_FILE}.uai-tmp`,
+  LEASE_AWS_CONFIG_FILE,
+  `${LEASE_AWS_CONFIG_FILE}.uai-tmp`,
+]);
+
+/** Destructive cleanup accepts only lane-owned files. The executor repeats
+ * this check after reconstructing the runtime and resolves every parent
+ * symlink-safely before deletion; persistence never turns an arbitrary task
+ * path into cleanup authority. */
+export function assertCredentialCleanupPath(
+  lane: CredentialCleanupLane,
+  value: string,
+): void {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > 4096 ||
+    value.includes("\0") ||
+    value.split("/").some((part) => part === "." || part === "..")
+  ) {
+    throw new Error("credential cleanup path is invalid");
+  }
+  const allowed =
+    (lane === "engine-auth" && (ENGINE_AUTH_PATH.test(value) || CONNECTION_AUTH_PATH.test(value))) ||
+    (lane === "github" && GITHUB_PATHS.has(value)) ||
+    (lane === "ssh" && SSH_PATHS.has(value)) ||
+    (lane === "files-session" && FILES_SESSION_PATHS.has(value));
+  if (!allowed) {
+    throw new Error("credential cleanup path is outside its managed lane");
+  }
+}
+
+function normalizedKey(input: CredentialCleanupPathKey): {
+  taskId: string;
+  runEpoch: number;
+  runtimeLocator: string;
+  lane: CredentialCleanupLane;
+  path: string;
+} {
+  assertSafeHostTaskId(input.taskId);
+  positiveRunEpoch(input.runEpoch);
+  assertCredentialCleanupPath(input.lane, input.path);
+  return {
+    taskId: input.taskId,
+    runEpoch: input.runEpoch,
+    runtimeLocator: serializeTaskEnvironmentLocator(input.runtime),
+    lane: input.lane,
+    path: input.path,
+  };
+}
+
+/** Record before writing the credential path. Re-recording the same exact
+ * runtime path is idempotent and preserves its first-seen timestamp. */
+export function rememberCredentialCleanupPath(
+  input: CredentialCleanupPathInput,
+  db: InventoryExecutor = getDb(),
+  now = Date.now(),
+): void {
+  // The shared path encoder has the contract's exact bounded id grammar.
+  idPathSegment(input.credentialId);
+  const key = normalizedKey(input);
+  db.insert(schema.hostCredentialCleanupPaths)
+    .values({
+      ...key,
+      credentialId: input.credentialId,
+      createdAt: now,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [
+        schema.hostCredentialCleanupPaths.taskId,
+        schema.hostCredentialCleanupPaths.runEpoch,
+        schema.hostCredentialCleanupPaths.runtimeLocator,
+        schema.hostCredentialCleanupPaths.path,
+      ],
+      set: { credentialId: input.credentialId, updatedAt: now },
+    })
+    .run();
+}
+
+/** All outstanding cleanup work for a task, oldest assignment first. */
+export function listCredentialCleanupPaths(
+  taskId: string,
+  db: InventoryExecutor = getDb(),
+): HostCredentialCleanupPath[] {
+  assertSafeHostTaskId(taskId);
+  return db
+    .select()
+    .from(schema.hostCredentialCleanupPaths)
+    .where(eq(schema.hostCredentialCleanupPaths.taskId, taskId))
+    .orderBy(
+      asc(schema.hostCredentialCleanupPaths.runEpoch),
+      asc(schema.hostCredentialCleanupPaths.runtimeLocator),
+      asc(schema.hostCredentialCleanupPaths.path),
+    )
+    .all();
+}
+
+/** Boot recovery must not depend on a current manifest or even a surviving
+ * host-task row. Return the entire non-secret worklist in deterministic order. */
+export function listAllCredentialCleanupPaths(
+  db: InventoryExecutor = getDb(),
+): HostCredentialCleanupPath[] {
+  return db
+    .select()
+    .from(schema.hostCredentialCleanupPaths)
+    .orderBy(
+      asc(schema.hostCredentialCleanupPaths.taskId),
+      asc(schema.hostCredentialCleanupPaths.runEpoch),
+      asc(schema.hostCredentialCleanupPaths.runtimeLocator),
+      asc(schema.hostCredentialCleanupPaths.path),
+    )
+    .all();
+}
+
+/**
+ * Value-free boot worklist. A marker keeps a task recoverable even when a
+ * crash happened before its first path was inventoried, or after every path
+ * was deleted but before in-memory material was dropped.
+ */
+export function listCredentialCleanupRecoveryTasks(
+  db: InventoryExecutor = getDb(),
+): Array<{ taskId: string; runEpoch: number }> {
+  const tasks = new Map<string, number>();
+  for (const pending of listCredentialCleanupPending(db)) {
+    tasks.set(pending.taskId, pending.runEpoch);
+  }
+  for (const row of listAllCredentialCleanupPaths(db)) {
+    tasks.set(row.taskId, Math.max(tasks.get(row.taskId) ?? 0, row.runEpoch));
+  }
+  // A leased engine on an env-token account leaves no path: the record of
+  // where it ran is the evidence its task needs a cleanup after a crash.
+  for (const row of listAllLeasedEngineRuntimes(db)) {
+    tasks.set(row.taskId, Math.max(tasks.get(row.taskId) ?? 0, row.runEpoch));
+  }
+  // A container the boot sweep started and has not yet proven stopped again
+  // is owed its stop, whatever paths remain.
+  for (const row of listAllCredentialCleanupRestops(db)) {
+    tasks.set(row.taskId, Math.max(tasks.get(row.taskId) ?? 0, row.runEpoch));
+  }
+  return [...tasks]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([taskId, runEpoch]) => ({ taskId, runEpoch }));
+}
+
+/** Persistence primitive for the later cleanup executor. The executor is
+ * responsible for proving absence before it calls this. */
+export function forgetCredentialCleanupPath(
+  input: CredentialCleanupPathKey,
+  db: InventoryExecutor = getDb(),
+): void {
+  const key = normalizedKey(input);
+  db.delete(schema.hostCredentialCleanupPaths)
+    .where(
+      and(
+        eq(schema.hostCredentialCleanupPaths.taskId, key.taskId),
+        eq(schema.hostCredentialCleanupPaths.runEpoch, key.runEpoch),
+        eq(
+          schema.hostCredentialCleanupPaths.runtimeLocator,
+          key.runtimeLocator,
+        ),
+        eq(schema.hostCredentialCleanupPaths.lane, key.lane),
+        eq(schema.hostCredentialCleanupPaths.path, key.path),
+      ),
+    )
+    .run();
+}
+
+/**
+ * ADR-154 §6: record, before a leased engine starts in it, the runtime it
+ * starts in for this run, so the cleanup proves its engines stopped there
+ * even when they left no file to inventory. Idempotent.
+ */
+export function rememberLeasedEngineRuntime(
+  input: { taskId: string; runEpoch: number; runtime: TaskEnvironmentLocator },
+  db: InventoryExecutor = getDb(),
+  now = Date.now(),
+): void {
+  assertSafeHostTaskId(input.taskId);
+  positiveRunEpoch(input.runEpoch);
+  db.insert(schema.hostLeasedEngineRuntimes)
+    .values({
+      taskId: input.taskId,
+      runEpoch: input.runEpoch,
+      runtimeLocator: serializeTaskEnvironmentLocator(input.runtime),
+      createdAt: now,
+    })
+    .onConflictDoNothing()
+    .run();
+}
+
+/** Every runtime a leased engine of the task was started in, oldest run first. */
+export function listLeasedEngineRuntimes(
+  taskId: string,
+  db: InventoryExecutor = getDb(),
+): HostLeasedEngineRuntime[] {
+  assertSafeHostTaskId(taskId);
+  return db
+    .select()
+    .from(schema.hostLeasedEngineRuntimes)
+    .where(eq(schema.hostLeasedEngineRuntimes.taskId, taskId))
+    .orderBy(
+      asc(schema.hostLeasedEngineRuntimes.runEpoch),
+      asc(schema.hostLeasedEngineRuntimes.runtimeLocator),
+    )
+    .all();
+}
+
+/** Every runtime a leased engine of any task was started in. */
+export function listAllLeasedEngineRuntimes(
+  db: InventoryExecutor = getDb(),
+): HostLeasedEngineRuntime[] {
+  return db
+    .select()
+    .from(schema.hostLeasedEngineRuntimes)
+    .orderBy(
+      asc(schema.hostLeasedEngineRuntimes.taskId),
+      asc(schema.hostLeasedEngineRuntimes.runEpoch),
+      asc(schema.hostLeasedEngineRuntimes.runtimeLocator),
+    )
+    .all();
+}
+
+/** After a whole-task cleanup proved every engine of these runs stopped in
+ *  these runtimes: forget them, never a newer run's. */
+export function forgetLeasedEngineRuntimes(
+  taskId: string,
+  throughRunEpoch: number,
+  runtimeLocators: readonly string[],
+  db: InventoryExecutor = getDb(),
+): void {
+  assertSafeHostTaskId(taskId);
+  positiveRunEpoch(throughRunEpoch);
+  for (const runtimeLocator of runtimeLocators) {
+    db.delete(schema.hostLeasedEngineRuntimes)
+      .where(
+        and(
+          eq(schema.hostLeasedEngineRuntimes.taskId, taskId),
+          lte(schema.hostLeasedEngineRuntimes.runEpoch, throughRunEpoch),
+          eq(schema.hostLeasedEngineRuntimes.runtimeLocator, runtimeLocator),
+        ),
+      )
+      .run();
+  }
+}
+
+/**
+ * The boot sweep's owed re-stop, recorded BEFORE it starts a stopped app
+ * container to clean it (`host_credential_cleanup_restops`). Idempotent.
+ */
+export function rememberCredentialCleanupRestop(
+  input: { taskId: string; runEpoch: number; runtimeLocator: string; containerId: string },
+  db: InventoryExecutor = getDb(),
+  now = Date.now(),
+): void {
+  assertSafeHostTaskId(input.taskId);
+  positiveRunEpoch(input.runEpoch);
+  if (!/^[0-9a-f]{64}$/.test(input.containerId)) {
+    throw new Error("an owed re-stop names a container by its full id");
+  }
+  if (input.runtimeLocator.length === 0) {
+    throw new Error("an owed re-stop names its runtime");
+  }
+  db.insert(schema.hostCredentialCleanupRestops)
+    .values({
+      taskId: input.taskId,
+      containerId: input.containerId,
+      runEpoch: input.runEpoch,
+      runtimeLocator: input.runtimeLocator,
+      createdAt: now,
+    })
+    .onConflictDoNothing()
+    .run();
+}
+
+/** The task's owed re-stops, oldest first. */
+export function listCredentialCleanupRestops(
+  taskId: string,
+  db: InventoryExecutor = getDb(),
+): HostCredentialCleanupRestop[] {
+  assertSafeHostTaskId(taskId);
+  return db
+    .select()
+    .from(schema.hostCredentialCleanupRestops)
+    .where(eq(schema.hostCredentialCleanupRestops.taskId, taskId))
+    .orderBy(
+      asc(schema.hostCredentialCleanupRestops.createdAt),
+      asc(schema.hostCredentialCleanupRestops.containerId),
+    )
+    .all();
+}
+
+/** Every owed re-stop of any task. */
+export function listAllCredentialCleanupRestops(
+  db: InventoryExecutor = getDb(),
+): HostCredentialCleanupRestop[] {
+  return db
+    .select()
+    .from(schema.hostCredentialCleanupRestops)
+    .orderBy(
+      asc(schema.hostCredentialCleanupRestops.taskId),
+      asc(schema.hostCredentialCleanupRestops.containerId),
+    )
+    .all();
+}
+
+/** Only once this exact container is proven stopped again, or gone. */
+export function forgetCredentialCleanupRestop(
+  input: { taskId: string; containerId: string },
+  db: InventoryExecutor = getDb(),
+): void {
+  assertSafeHostTaskId(input.taskId);
+  db.delete(schema.hostCredentialCleanupRestops)
+    .where(
+      and(
+        eq(schema.hostCredentialCleanupRestops.taskId, input.taskId),
+        eq(schema.hostCredentialCleanupRestops.containerId, input.containerId),
+      ),
+    )
+    .run();
+}