@zgeoff/atc 2.11.0 → 2.13.0

package/src/daemon/build-scoped-context.ts

@@ -0,0 +1,235 @@
+import { DaemonError } from '../protocol/daemon-error';
+import type { SessionID } from '../shared/session-id';
+import { toSessionID } from '../shared/to-session-id';
+import { buildTargetForbiddenError } from './build-target-forbidden-error';
+import { buildTargetIdentity } from './build-target-identity';
+import type { DaemonContext } from './daemon-connection';
+import type { KeyedRequest } from './idempotency-ledger';
+import type { TargetAccess, TargetGrant } from './target-access';
+
+/**
+ * The daemon as a principal with the given access sees it. Its keyed
+ * spawns and messages hold their keys in the given namespace, apart from
+ * every other namespace's. A session on a target outside the access does
+ * not exist here: every lookup of it answers as a lookup of an unknown
+ * session does, so the request's own handling refuses it with the words
+ * and data it gives a session that never existed. Lists leave such
+ * sessions out, and a spawn may use only a target the access holds, a
+ * spawn's replayed answer included. A kill, or a pin, of a session whose
+ * sub-sessions reach past the access is refused whole, before anything
+ * changes.
+ */
+export function buildScopedContext(
+  ctx: DaemonContext,
+  access: TargetAccess,
+  keyNamespace: string,
+): DaemonContext {
+  // A keyed request's key, held in this namespace alone.
+  const buildPrincipalKey = (keyed: KeyedRequest | null): KeyedRequest | null =>
+    keyed === null ? null : { ...keyed, principal: keyNamespace };
+
+  const canSee = (id: SessionID): boolean => {
+    const grant = ctx.findSessionGrant(id);
+
+    return grant !== null && access.canUse(grant);
+  };
+
+  const canUseTarget = (target: string): boolean => {
+    const targetIdentity = ctx.findTargetIdentity(target);
+
+    return targetIdentity !== null && access.canUse({ target, targetIdentity });
+  };
+
+  // The target a session is bound to: the live session's, else its fleet
+  // row's, else null for a session the daemon holds nowhere.
+  const findGrant = async (id: SessionID): Promise<TargetGrant | null> => {
+    const live = ctx.findSessionGrant(id);
+
+    if (live !== null) {
+      return live;
+    }
+
+    const fleet = await ctx.collectFleet();
+
+    const entry = fleet.find((row) => row.sessionID === id);
+
+    if (entry === undefined) {
+      return null;
+    }
+
+    return {
+      target: entry.target ?? 'local',
+      targetIdentity: entry.targetIdentity ?? buildTargetIdentity('local-pty', {}),
+    };
+  };
+
+  // Throws the refusal a fresh spawn to the session's target gets when a
+  // held key's refusal carries a session out of reach.
+  const requireSessionInReach = async (id: SessionID): Promise<void> => {
+    const grant = await findGrant(id);
+
+    if (grant !== null && !access.canUse(grant)) {
+      throw buildTargetForbiddenError(grant.target);
+    }
+  };
+
+  // Throws the refusal of a change to a session whose sub-sessions the
+  // change would reach too when any of them is out of reach. The refusal
+  // holds only the session the caller sent, never a sub-session's id or
+  // how many there are.
+  const requireTreeInReach = (id: SessionID, action: string): void => {
+    if (ctx.collectChildIDs(id).every((child) => canSee(child))) {
+      return;
+    }
+
+    throw new DaemonError(
+      'target_forbidden',
+      `this client may not ${action} session '${id}': it has a sub-session on a target this client may not use`,
+      { session: id },
+    );
+  };
+
+  return {
+    ...ctx,
+    collectSessions: () => ctx.collectSessions().filter((session) => canSee(session.id)),
+    collectAgents: () => {
+      const list = ctx.collectAgents();
+      const defaultTarget = list.spawnDefaults.target;
+
+      return {
+        ...list,
+        targets: list.targets.filter((target) => canUseTarget(target.id)),
+        spawnDefaults: {
+          ...list.spawnDefaults,
+          target: defaultTarget !== null && canUseTarget(defaultTarget) ? defaultTarget : null,
+        },
+
+        // The config file's own problem holds a path on the daemon's host,
+        // which is the owner's alone.
+        targetErrors: list.targetErrors.filter((error) => {
+          if (error.scope === 'config') {
+            return false;
+          }
+
+          return error.target === undefined || canUseTarget(error.target);
+        }),
+      };
+    },
+    collectFleet: async () => {
+      const fleet = await ctx.collectFleet();
+
+      return fleet.filter((entry) => canSee(entry.sessionID));
+    },
+    resolveSpawnTarget: (requested) => {
+      if (requested !== undefined) {
+        requireTarget(canUseTarget, requested);
+      }
+
+      const target = ctx.resolveSpawnTarget(requested);
+
+      requireTarget(canUseTarget, target);
+
+      return target;
+    },
+    spawnSession: async (plan, keyed) => {
+      let answer: Readonly<Record<string, unknown>>;
+
+      // A held key's replay is checked against the target its session was
+      // bound to, inside the spawn, before its answer leaves the daemon.
+      try {
+        answer = await ctx.spawnSession(plan, buildPrincipalKey(keyed), access);
+      } catch (error) {
+        // A held key's refusal may carry the session its spawn made.
+        if (error instanceof DaemonError && typeof error.data?.['effectRef'] === 'string') {
+          await requireSessionInReach(toSessionID(error.data['effectRef']));
+        }
+
+        throw error;
+      }
+
+      return answer;
+    },
+    killSession: (id) => {
+      if (!canSee(id)) {
+        return Promise.resolve(false);
+      }
+
+      requireTreeInReach(id, 'kill');
+
+      return ctx.killSession(id);
+    },
+    updateSession: (id, name, pinned) => {
+      if (!canSee(id)) {
+        return false;
+      }
+
+      if (pinned !== undefined) {
+        requireTreeInReach(id, 'pin');
+      }
+
+      return ctx.updateSession(id, name, pinned);
+    },
+    ackSession: (id) => canSee(id) && ctx.ackSession(id),
+    buildResumeCommand: (id) => (canSee(id) ? ctx.buildResumeCommand(id) : null),
+    readSessionScreen: (id) =>
+      canSee(id) ? ctx.readSessionScreen(id) : Promise.resolve('missing' as const),
+    answerPermission: (request, decision) => {
+      const owner = ctx.findPermissionSession(request);
+
+      return owner !== null && canSee(owner) ? ctx.answerPermission(request, decision) : 'unknown';
+    },
+    attachSession: (client, sessionID, dims) =>
+      canSee(sessionID) ? ctx.attachSession(client, sessionID, dims) : 'missing',
+    detachSession: (client, sessionID) => {
+      if (canSee(sessionID)) {
+        ctx.detachSession(client, sessionID);
+      }
+    },
+    writeSessionInput: (sessionID, data) =>
+      canSee(sessionID) ? ctx.writeSessionInput(sessionID, data) : 'missing',
+    writeSessionLine: (sessionID, text) =>
+      canSee(sessionID) ? ctx.writeSessionLine(sessionID, text) : 'missing',
+    ejectSession: (id, prompt) => (canSee(id) ? ctx.ejectSession(id, prompt) : 'missing'),
+    adoptSession: (id, cols, rows) =>
+      canSee(id) ? ctx.adoptSession(id, cols, rows) : Promise.resolve('missing' as const),
+    resizeSession: (client, sessionID, dims) =>
+      canSee(sessionID) && ctx.resizeSession(client, sessionID, dims),
+    readSessionRecord: (id) =>
+      canSee(id) ? ctx.readSessionRecord(id) : Promise.resolve('missing' as const),
+    loadSessionTranscript: (id, from, limit) =>
+      canSee(id) ? ctx.loadSessionTranscript(id, from, limit) : Promise.resolve('missing' as const),
+    readEvents: (afterID, limit, waitMs, sessionID, outer) => {
+      const merged = outer === null ? access : outer.merge(access);
+
+      return ctx.readEvents(afterID, limit, waitMs, sessionID, merged);
+    },
+    writeSessionMessage: (sessionID, from, text, keyed) =>
+      canSee(sessionID)
+        ? ctx.writeSessionMessage(sessionID, from, text, buildPrincipalKey(keyed))
+        : Promise.resolve('missing' as const),
+    readMessage: async (messageID, waitMs) => {
+      // The owner is checked before any wait, so a message outside the
+      // access answers at once, as an unknown message does.
+      const view = await ctx.readMessage(messageID, 0);
+
+      if (view === null || !canSee(view.session)) {
+        return null;
+      }
+
+      return waitMs === 0 ? view : ctx.readMessage(messageID, waitMs);
+    },
+    attachTap: (client, sessionID) =>
+      canSee(sessionID) ? ctx.attachTap(client, sessionID) : 'missing',
+    ackMessage: (client, sessionID, messageID) =>
+      canSee(sessionID)
+        ? ctx.ackMessage(client, sessionID, messageID)
+        : Promise.resolve('unknown' as const),
+  };
+}
+
+// Throws the refusal of a spawn to a target the access leaves out.
+function requireTarget(canUseTarget: (target: string) => boolean, target: string): void {
+  if (!canUseTarget(target)) {
+    throw buildTargetForbiddenError(target);
+  }
+}

package/src/daemon/build-session-lifecycle.ts

@@ -0,0 +1,52 @@
+/**
+ * A session's lifecycle as four layers, each owned by one actor:
+ *
+ * - `desired`: what the operator asked for. `run` keeps the harness
+ *   running, `sleep` keeps its host asleep with the harness inside it, and
+ *   `stop` leaves the harness ended.
+ * - `vm`: the host the harness runs on. `none` is the daemon's own machine,
+ *   which has no lifecycle of its own; `awake`, `asleep`, and `unknown` are
+ *   the last state the daemon saw of a remote host.
+ * - `harness`: the agent process. `suspended` is a process kept inside a
+ *   sleeping host, which a revive brings back as it was.
+ * - `attachment`: the daemon's own connection to the harness's output.
+ *   `local` is a harness in the daemon's process tree; `attached`,
+ *   `reattaching`, and `detached` follow the connection to a remote one.
+ */
+export interface SessionLifecycle {
+  readonly desired: 'run' | 'sleep' | 'stop';
+  readonly vm: 'none' | 'awake' | 'asleep' | 'unknown';
+  readonly harness: 'running' | 'suspended' | 'exited';
+  readonly attachment: 'local' | 'attached' | 'reattaching' | 'detached';
+}
+
+// The session facts the layers derive from.
+interface LifecycleFacts {
+  readonly desired: SessionLifecycle['desired'];
+  readonly vm: SessionLifecycle['vm'];
+  readonly attachment: SessionLifecycle['attachment'];
+
+  // Whether the harness is kept inside a sleeping host.
+  readonly suspended: boolean;
+  readonly hasHarness: boolean;
+  readonly kind: 'pty' | 'headless';
+  readonly state: 'running' | 'needs_you' | 'done' | 'exited';
+}
+
+/**
+ * Builds the four layers from a session's facts. The harness runs while the
+ * session holds a terminal or a live headless run. A harness without one is
+ * suspended while it is kept inside a sleeping host, and exited otherwise.
+ */
+export function buildSessionLifecycle(facts: Readonly<LifecycleFacts>): SessionLifecycle {
+  const running = facts.hasHarness || (facts.kind === 'headless' && facts.state !== 'exited');
+  let harness: SessionLifecycle['harness'] = 'exited';
+
+  if (running) {
+    harness = 'running';
+  } else if (facts.suspended && facts.vm === 'asleep') {
+    harness = 'suspended';
+  }
+
+  return { desired: facts.desired, vm: facts.vm, harness, attachment: facts.attachment };
+}

package/src/daemon/build-tar-archive.ts

@@ -0,0 +1,85 @@
+/**
+ * One file in an archive: its path relative to the directory it unpacks
+ * into, its bytes, and its permission bits.
+ */
+export interface ArchiveFile {
+  readonly path: string;
+  readonly content: string | Uint8Array;
+  readonly mode?: number;
+}
+
+const BLOCK = 512;
+
+/**
+ * Packs files into a POSIX ustar archive that `tar -x` unpacks, each with
+ * its parent directories created on the way. A path longer than ustar
+ * holds is refused.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- file bytes have no readonly form
+export function buildTarArchive(files: readonly ArchiveFile[]): Uint8Array {
+  const encoder = new TextEncoder();
+
+  const blocks: Uint8Array[] = [];
+
+  for (const file of files) {
+    const content = typeof file.content === 'string' ? encoder.encode(file.content) : file.content;
+
+    blocks.push(
+      buildHeader(file.path, content.length, file.mode ?? 0o644),
+      content,
+      new Uint8Array((BLOCK - (content.length % BLOCK)) % BLOCK),
+    );
+  }
+
+  // Two empty blocks end the archive.
+  blocks.push(new Uint8Array(BLOCK * 2));
+
+  const archive = new Uint8Array(blocks.reduce((total, block) => total + block.length, 0));
+
+  let at = 0;
+
+  for (const block of blocks) {
+    archive.set(block, at);
+
+    at += block.length;
+  }
+
+  return archive;
+}
+
+function buildHeader(path: string, size: number, mode: number): Uint8Array {
+  const encoder = new TextEncoder();
+
+  const name = encoder.encode(path);
+
+  if (name.length > 100) {
+    throw new Error(`archive path is longer than 100 bytes: ${path}`);
+  }
+
+  const header = new Uint8Array(BLOCK);
+
+  header.set(name, 0);
+  header.set(encoder.encode(formatOctal(mode, 8)), 100);
+  header.set(encoder.encode(formatOctal(0, 8)), 108);
+  header.set(encoder.encode(formatOctal(0, 8)), 116);
+  header.set(encoder.encode(formatOctal(size, 12)), 124);
+  header.set(encoder.encode(formatOctal(0, 12)), 136);
+
+  // The checksum counts its own field as spaces.
+  header.set(encoder.encode('        '), 148);
+
+  header[156] = '0'.codePointAt(0) ?? 0;
+
+  header.set(encoder.encode('ustar\u000000'), 257);
+
+  const checksum = header.reduce((total, byte) => total + byte, 0);
+
+  header.set(encoder.encode(`${checksum.toString(8).padStart(6, '0')}\u0000 `), 148);
+
+  return header;
+}
+
+// An octal number padded to fill its field, ending in a NUL.
+function formatOctal(value: number, width: number): string {
+  return `${value.toString(8).padStart(width - 1, '0')}\u0000`;
+}

package/src/daemon/build-target-access.ts

@@ -0,0 +1,33 @@
+import type { ExecutionTarget } from './build-execution-targets';
+import { buildTargetIdentity } from './build-target-identity';
+import { TargetAccess } from './target-access';
+
+/**
+ * The targets a principal may use. With no principals in the config, every
+ * principal gets the implicit `local` target alone: the name `local` with
+ * the identity of a `local-pty` target without options, so a `local` that
+ * now holds another provider or other options is outside it. With
+ * principals, a principal gets each target its entry lists that the config
+ * holds, at that target's identity now, and an unknown principal gets none.
+ */
+export function buildTargetAccess(
+  principals: ReadonlyMap<string, readonly string[]> | null,
+  targets: ReadonlyMap<string, ExecutionTarget>,
+  principal: string,
+): TargetAccess {
+  if (principals === null) {
+    return new TargetAccess([
+      { target: 'local', targetIdentity: buildTargetIdentity('local-pty', {}) },
+    ]);
+  }
+
+  const granted = principals.get(principal) ?? [];
+
+  return new TargetAccess(
+    granted.flatMap((id) => {
+      const target = targets.get(id);
+
+      return target === undefined ? [] : [{ target: id, targetIdentity: target.identity }];
+    }),
+  );
+}

package/src/daemon/build-target-forbidden-error.ts

@@ -0,0 +1,13 @@
+import { DaemonError } from '../protocol/daemon-error';
+
+/**
+ * The refusal of a spawn to a target the principal may not use, which a
+ * replay of a held spawn key outside the principal's reach answers with too.
+ */
+export function buildTargetForbiddenError(target: string): DaemonError {
+  return new DaemonError(
+    'target_forbidden',
+    `this client may not use execution target '${target}'. Grant it to the client under principals in config.json and restart the daemon`,
+    { target },
+  );
+}

package/src/daemon/build-target-identity.ts

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+import { sortJSONKeys } from '../shared/sort-json-keys';
+
+/**
+ * The identity a session binds to when it spawns on a target: the provider
+ * kind, a colon, and the first 16 hex digits of a sha256 over the target's
+ * options with sorted keys. A target name reused with another provider or
+ * other options has another identity. Target options hold no credential
+ * values, only references such as an environment variable's name, so the
+ * identity never derives from a secret.
+ */
+export function buildTargetIdentity(
+  kind: string,
+  options: Readonly<Record<string, unknown>>,
+): string {
+  const digest = createHash('sha256')
+    .update(JSON.stringify(sortJSONKeys(options)))
+    .digest('hex')
+    .slice(0, 16);
+
+  return `${kind}:${digest}`;
+}

package/src/daemon/build-target-list.ts

@@ -0,0 +1,50 @@
+import type { ExecutionTarget } from './build-execution-targets';
+import type { ExecutionCapabilities } from './execution-provider';
+
+export interface TargetEntry {
+  readonly id: string;
+
+  // The provider kind the config selects for the target.
+  readonly provider: string;
+
+  // The identity a session spawned on the target binds to.
+  readonly identity: string;
+
+  // Whether this daemon has a provider of that kind, so a spawn can run there.
+  readonly available: boolean;
+  readonly default: boolean;
+  readonly capabilities: ExecutionCapabilities;
+}
+
+// What a target without a provider can do: nothing.
+const NO_CAPABILITIES: ExecutionCapabilities = {
+  spawn: false,
+  attach: false,
+  input: false,
+  resize: false,
+  kill: false,
+  transfer: false,
+  run: false,
+  headless: false,
+  suspend: false,
+  destroy: false,
+};
+
+/**
+ * One `agents.list` target entry per configured target, in config order.
+ * An entry holds the target's id, provider kind, and capabilities, never its
+ * options, since those can hold a host's address or an account.
+ */
+export function buildTargetList(
+  targets: readonly ExecutionTarget[],
+  defaultTarget: string | null,
+): TargetEntry[] {
+  return targets.map((target) => ({
+    id: target.id,
+    provider: target.kind,
+    identity: target.identity,
+    available: target.provider !== null,
+    default: target.id === defaultTarget,
+    capabilities: target.provider?.capabilities ?? NO_CAPABILITIES,
+  }));
+}