@zgeoff/atc 2.11.0 → 2.12.0

package/src/daemon/build-config-revision.ts

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+import type { TargetConfigError } from '../shared/collect-targets';
+import type { ExecutionTarget } from './build-execution-targets';
+
+/**
+ * A short digest of the target config a daemon runs with: each target's id
+ * and identity, the default target, and the config errors. Two daemons with
+ * the same targets return the same revision, and any change to them
+ * changes it.
+ */
+export function buildConfigRevision(
+  targets: readonly ExecutionTarget[],
+  defaultTarget: string | null,
+  errors: readonly TargetConfigError[],
+): string {
+  const canonical = JSON.stringify({
+    targets: targets.map((target) => [target.id, target.identity]),
+    defaultTarget,
+    errors: errors.map((error) =>
+      error.scope === 'config'
+        ? [error.scope, error.path, error.problem, error.detail]
+        : [error.scope, error.target ?? null, error.problem],
+    ),
+  });
+
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}

package/src/daemon/build-execution-targets.ts

@@ -0,0 +1,34 @@
+import type { TargetConfig } from '../shared/collect-targets';
+import { buildTargetIdentity } from './build-target-identity';
+import type { ExecutionProvider } from './execution-provider';
+import { LocalPTYProvider } from './local-pty-provider';
+
+/**
+ * A configured place sessions run, with the provider that serves it. The
+ * provider is null when this daemon has no provider of the configured kind:
+ * the target still lists, and a spawn to it fails rather than running
+ * anywhere else.
+ */
+export interface ExecutionTarget {
+  readonly id: string;
+  readonly kind: string;
+  readonly options: Readonly<Record<string, unknown>>;
+
+  // The identity a session spawned here binds to.
+  readonly identity: string;
+  readonly provider: ExecutionProvider | null;
+}
+
+/**
+ * Builds one target per configured entry, in config order, each with a
+ * provider of its kind when this daemon has one.
+ */
+export function buildExecutionTargets(configs: readonly TargetConfig[]): ExecutionTarget[] {
+  return configs.map((config) => ({
+    id: config.id,
+    kind: config.provider,
+    options: config.options,
+    identity: buildTargetIdentity(config.provider, config.options),
+    provider: config.provider === 'local-pty' ? new LocalPTYProvider() : null,
+  }));
+}

package/src/daemon/build-fleet-events.ts

@@ -23,7 +23,8 @@ export function buildFleetEvents(
   sessions: readonly SessionDescriptor[],
 ): FleetEvent[] {
   return rows.map((row) => {
-    // A restore re-mints atc ids, so the agent session id is the stable link.
+    // Rows written before atc session ids stayed stable across restores
+    // carry an earlier atc id, so the agent session id links them.
     const live =
       (row.agentSessionID === null
         ? undefined

package/src/daemon/build-payload-hash.ts

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+import { isRecord } from '../shared/report';
+
+/**
+ * The SHA-256 of a request's params as canonical JSON: object keys sorted
+ * at every depth, with the idempotency key itself left out. Two requests
+ * that differ only in key order or in their idempotency key hash the same.
+ */
+export function buildPayloadHash(params: Readonly<Record<string, unknown>>): string {
+  const { idempotencyKey: _ignored, ...payload } = params;
+
+  return createHash('sha256')
+    .update(JSON.stringify(sortKeys(payload)))
+    .digest('hex');
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortKeys(item));
+  }
+
+  if (!isRecord(value)) {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.keys(value)
+      .toSorted()
+      .map((key) => [key, sortKeys(value[key])]),
+  );
+}

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

@@ -0,0 +1,232 @@
+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',
+    ejectSession: (id, prompt) => (canSee(id) ? ctx.ejectSession(id, prompt) : 'missing'),
+    adoptSession: (id, cols, rows) => (canSee(id) ? ctx.adoptSession(id, cols, rows) : 'missing'),
+    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-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,
+  }));
+}