@zgeoff/atc 2.19.0 → 2.22.0

package/src/daemon/daemon.ts

@@ -62,8 +62,10 @@ import { EffectRemainsError } from './effect-remains-error';
 import { EventSignal } from './event-signal';
 import { startHookServer } from './hooks';
 import { IdempotencyLedger } from './idempotency-ledger';
+import { isAllowedListenHost } from './is-allowed-listen-host';
 import { isOwnHookEvent } from './is-own-hook-event';
 import { isTreeInReach } from './is-tree-in-reach';
+import { loadListenerTokens } from './load-listener-tokens';
 import { loadTranscriptPage } from './load-transcript-page';
 import { makeHookRunner } from './make-hook-runner';
 import type { HookScope } from './make-hook-runner';
@@ -82,6 +84,8 @@ import type { Session, SessionDescriptor } from './sessions';
 import { startEventsServer } from './start-events-server';
 import { startHeadlessTurn } from './start-headless-turn';
 import { startSessionBridge } from './start-session-bridge';
+import { startTCPListener } from './start-tcp-listener';
+import type { TCPListener } from './start-tcp-listener';
 import { TapRegistry } from './tap-registry';
 import type { TargetAccess } from './target-access';
 import { writeDaemonRecord } from './write-daemon-record';
@@ -151,6 +155,10 @@ export interface DaemonOptions {
   // How long a confirm token from `session.forget` stays usable.
   readonly forgetConfirmMs?: number;
 
+  // When set, a TCP listener serves the client protocol on this address to
+  // peers whose handshake presents a token from the token file.
+  readonly listen?: ListenOptions;
+
   // Called after a client-requested quit has stopped the daemon; the real
   // entrypoint exits the process, tests leave it unset.
   readonly onQuit?: () => void;
@@ -169,11 +177,35 @@ export interface DaemonOptions {
   readonly gitTransports?: readonly string[] | InvalidGitTransports;
 }
 
+// The TCP listener's address and the file holding the tokens a handshake
+// may present.
+interface ListenOptions {
+  readonly host: string;
+  readonly port: number;
+  readonly tokenFile: string;
+
+  // How long a handshake waits once its source address has failed five
+  // times within a minute; 10 s when unset.
+  readonly failureDelayMs?: number;
+
+  // How many delayed handshakes may wait at once across every address; 64
+  // when unset.
+  readonly maxDelayedHandshakes?: number;
+}
+
 export interface DaemonHandle {
   readonly stop: () => Promise<void>;
 
   // How many client-protocol connections are open right now.
   readonly countClients: () => number;
+
+  // The port the TCP listener bound, or null without one.
+  readonly listenPort: number | null;
+
+  // Reads the token file again and closes every TCP connection whose
+  // handshake token it no longer holds. A file that fails to load drops
+  // every token and closes every TCP connection until a load succeeds.
+  readonly refreshTokens: () => void;
 }
 
 // How long a started Claude session may go without a tap before a message to
@@ -191,6 +223,13 @@ const LOCAL_PRINCIPAL = 'local';
 const IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1000;
 const IDEMPOTENCY_SWEEP_MS = 60 * 60 * 1000;
 
+// How long a TCP handshake waits once its address has failed too often.
+const HANDSHAKE_FAILURE_DELAY_MS = 10_000;
+
+// How many delayed handshakes may wait at once; a handshake over the cap is
+// refused at once.
+const MAX_DELAYED_HANDSHAKES = 64;
+
 // How long startup waits for a daemon that is shutting down to release the
 // state lock before refusing to start.
 const LOCK_WAIT_MS = 2000;
@@ -207,6 +246,10 @@ const LOCK_WAIT_MS = 2000;
 export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   let stopDaemon: (() => Promise<void>) | null = null;
 
+  // The listener's address and tokens are checked before the daemon takes
+  // anything, so a refused listener leaves no state behind.
+  const listenTokens = opts.listen === undefined ? null : requireListenTokens(opts.listen);
+
   // One daemon per state directory: the lock comes before the store, the
   // sockets, or the fleet, so a second daemon touches none of them.
   const stateDir = dirname(opts.dbPath);
@@ -1213,6 +1256,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
   const ctx: DaemonContext = {
     build: opts.build,
     daemonID: store.daemonID,
+    idempotencyRetentionMs: IDEMPOTENCY_TTL_MS,
     collectSessions: () => mgr.collectDescriptors(),
     collectSpawnDirs: async (access) => {
       const dirs = await store.collectSpawnDirs();
@@ -1243,6 +1287,7 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     loadLastUsedAgent: () => store.loadLastUsedAgent(),
     findAdapter: (kind) => mgr.findAdapter(kind),
     buildTargetAccess: (principal) => buildTargetAccess(principals, targetsByID, principal),
+    hasListedPrincipal: (principal) => principals?.has(principal) ?? false,
     findSessionGrant: (id) => {
       const s = mgr.sessions.find((x) => x.id === id);
 
@@ -1903,6 +1948,76 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     },
   };
 
+  // Releases everything the daemon holds except its listeners, on a stop
+  // and on a start that fails once it holds the lock.
+  const releaseResources = async () => {
+    clearInterval(idempotencySweep);
+    eventsServer?.stop();
+    reporter.stop(true);
+    mgr.detachAll();
+
+    for (const target of targets) {
+      target.provider?.dispose();
+    }
+
+    for (const runtime of runtimes.values()) {
+      runtime.dispose();
+    }
+
+    runtimes.clear();
+    eventSignal.dispose();
+
+    await store.stop();
+
+    try {
+      unlinkSync(recordPath);
+    } catch {}
+
+    if (opts.pidPath !== undefined) {
+      try {
+        unlinkSync(opts.pidPath);
+      } catch {}
+    }
+
+    lock.dispose();
+  };
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- a connection is a live object the daemon releases
+  const detachConnection = (connection: DaemonConnection) => {
+    clients.delete(connection);
+    ctx.detachClient(connection);
+    taps.detachAll(connection);
+  };
+
+  // The TCP listener binds before the unix socket, so a bind that fails
+  // refuses the start before any client can connect, and releases what the
+  // daemon holds, the lock included.
+  let tcpListener: TCPListener | null = null;
+
+  if (opts.listen !== undefined && listenTokens !== null) {
+    try {
+      tcpListener = startTCPListener({
+        host: opts.listen.host,
+        port: opts.listen.port,
+        tokens: listenTokens,
+        failureDelayMs: opts.listen.failureDelayMs ?? HANDSHAKE_FAILURE_DELAY_MS,
+        maxDelayedHandshakes: opts.listen.maxDelayedHandshakes ?? MAX_DELAYED_HANDSHAKES,
+        openConnection: (socket, peer) => {
+          const connection = new DaemonConnection(socket, ctx, peer);
+
+          clients.add(connection);
+
+          return connection;
+        },
+        closeConnection: detachConnection,
+      });
+    } catch (error) {
+      await releaseResources();
+
+      throw buildBindRefusal(opts.listen, error);
+    }
+  }
+
   try {
     unlinkSync(opts.socketPath);
   } catch {}
@@ -1922,52 +2037,43 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
         socket.data.drain();
       },
       close(socket) {
-        clients.delete(socket.data);
-        ctx.detachClient(socket.data);
-        taps.detachAll(socket.data);
+        detachConnection(socket.data);
       },
       error() {},
     },
   });
 
-  stopDaemon = async () => {
-    // Ends each client itself so every peer sees the close: a stopped
-    // listener does not reliably end the connections it already accepted.
-    for (const client of clients) {
-      client.dispose();
+  const refreshTokens = () => {
+    if (opts.listen === undefined || tcpListener === null) {
+      return;
     }
 
-    clearInterval(idempotencySweep);
-
-    server.stop(true);
-    eventsServer?.stop();
-    reporter.stop(true);
-    mgr.detachAll();
+    const loaded = loadListenerTokens(opts.listen.tokenFile);
 
-    for (const target of targets) {
-      target.provider?.dispose();
-    }
+    if (loaded.ok) {
+      tcpListener.setTokens(loaded.tokens);
 
-    for (const runtime of runtimes.values()) {
-      runtime.dispose();
+      return;
     }
 
-    runtimes.clear();
-    eventSignal.dispose();
+    tcpListener.setTokens(null);
 
-    await store.stop();
-
-    try {
-      unlinkSync(recordPath);
-    } catch {}
+    mgr.log(
+      `atc daemon: token reload failed (${loaded.reason}); every TCP connection is closed and refused until a reload succeeds`,
+    );
+  };
 
-    if (opts.pidPath !== undefined) {
-      try {
-        unlinkSync(opts.pidPath);
-      } catch {}
+  stopDaemon = async () => {
+    // Ends each client itself so every peer sees the close: a stopped
+    // listener does not reliably end the connections it already accepted.
+    for (const client of clients) {
+      client.dispose();
     }
 
-    lock.dispose();
+    tcpListener?.stop();
+    server.stop(true);
+
+    await releaseResources();
   };
 
   writeDaemonRecord(recordPath, {
@@ -1975,9 +2081,57 @@ export async function startDaemon(opts: DaemonOptions): Promise<DaemonHandle> {
     socketPath: opts.socketPath,
     reporterSocketPath: opts.reporterSocketPath,
     eventsSocketPath: opts.eventsSocketPath ?? null,
+    listenPort: tcpListener?.port ?? null,
   });
 
-  return { stop: stopDaemon, countClients: () => clients.size };
+  return {
+    stop: stopDaemon,
+    countClients: () => clients.size,
+    listenPort: tcpListener?.port ?? null,
+    refreshTokens,
+  };
+}
+
+// The tokens the TCP listener starts with. Throws, with the code a refused
+// start carries, for an address outside the allowed ranges or a token file
+// that fails to load, so the daemon never starts with a listener that
+// takes no token or binds where it must not.
+function requireListenTokens(listen: ListenOptions): readonly string[] {
+  if (!isAllowedListenHost(listen.host)) {
+    throw Object.assign(
+      new Error(
+        `atc daemon: --listen refuses '${listen.host}': bind a loopback address or one in 100.64.0.0/10 or fd7a:115c:a1e4::/48`,
+      ),
+      { code: 'listen_refused' },
+    );
+  }
+
+  const loaded = loadListenerTokens(listen.tokenFile);
+
+  if (!loaded.ok) {
+    throw Object.assign(new Error(`atc daemon: --token-file: ${loaded.reason}`), {
+      code: 'listen_refused',
+    });
+  }
+
+  return loaded.tokens;
+}
+
+// The refused start for a TCP listener whose bind failed, holding the
+// address and the bind error's code, such as EADDRINUSE for a port another
+// socket holds.
+function buildBindRefusal(listen: ListenOptions, error: unknown): Error {
+  const code: unknown = error instanceof Error ? Reflect.get(error, 'code') : null;
+
+  const address = listen.host.includes(':')
+    ? `[${listen.host}]:${listen.port}`
+    : `${listen.host}:${listen.port}`;
+
+  const reason = typeof code === 'string' ? code : String(error);
+
+  return Object.assign(new Error(`atc daemon: --listen cannot bind ${address} (${reason})`), {
+    code: 'listen_refused',
+  });
 }
 
 // Tells a tap its subscription is over so the `atc tap` process behind it

package/src/daemon/find-token-fingerprint.ts

@@ -0,0 +1,23 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+/**
+ * The fingerprint of the token the presented bearer token matches, or null
+ * when it matches none. The comparison runs on SHA-256 digests in constant
+ * time against every token, so neither a token's length nor which token a
+ * guess came close to shows in the timing. The fingerprint is the matched
+ * token's digest in hex, which identifies the token without holding it.
+ */
+export function findTokenFingerprint(tokens: readonly string[], presented: string): string | null {
+  const digest = createHash('sha256').update(presented).digest();
+  let matched: string | null = null;
+
+  for (const token of tokens) {
+    const candidate = createHash('sha256').update(token).digest();
+
+    if (timingSafeEqual(candidate, digest) && matched === null) {
+      matched = candidate.toString('hex');
+    }
+  }
+
+  return matched;
+}

package/src/daemon/handshake-throttle.ts

@@ -0,0 +1,47 @@
+// How far back failures count, and how many within that window delay the
+// next handshake from the same address.
+const FAILURE_WINDOW_MS = 60_000;
+const FAILURE_LIMIT = 5;
+
+/**
+ * Failed TCP handshakes per source address. Once an address has failed
+ * five times within a minute, its next handshake waits the configured
+ * delay before the daemon checks it, which slows a token guesser without
+ * locking out a peer that recovers.
+ */
+export class HandshakeThrottle {
+  private readonly delayMs: number;
+
+  private readonly failures = new Map<string, number[]>();
+
+  constructor(delayMs: number) {
+    this.delayMs = delayMs;
+  }
+
+  recordFailure(address: string, now: number): void {
+    // Only the latest failures up to the limit decide a delay, so an
+    // address never holds more than that many, however often it fails.
+    const recent = [...this.collectRecent(address, now), now].slice(-FAILURE_LIMIT);
+
+    this.failures.set(address, recent);
+  }
+
+  /**
+   * How long the next handshake from the address waits, in milliseconds.
+   */
+  getDelay(address: string, now: number): number {
+    const recent = this.collectRecent(address, now);
+
+    if (recent.length === 0) {
+      this.failures.delete(address);
+    } else {
+      this.failures.set(address, recent);
+    }
+
+    return recent.length >= FAILURE_LIMIT ? this.delayMs : 0;
+  }
+
+  private collectRecent(address: string, now: number): number[] {
+    return (this.failures.get(address) ?? []).filter((at) => now - at < FAILURE_WINDOW_MS);
+  }
+}

package/src/daemon/idempotency-ledger.ts

@@ -3,12 +3,14 @@ import type { EffectTarget, IdempotencyRecord } from '../store/idempotency-recor
 import type { StateStore } from '../store/state-store';
 import { EffectRemainsError } from './effect-remains-error';
 
-// A request's idempotency key, the hash of the payload it came with, and
-// the principal the request acts as when it is not the ledger's own.
+// A request's idempotency key, the hash of the payload it came with, the
+// principal the request acts as when it is not the ledger's own, and
+// whether it only replays a key the ledger already holds.
 export interface KeyedRequest {
   readonly key: string;
   readonly payloadHash: string;
   readonly principal?: string;
+  readonly replayOnly?: boolean;
 }
 
 interface IdempotentCall<T> {
@@ -45,6 +47,9 @@ interface IdempotentCall<T> {
  * answer; one with a different payload is `idempotency_conflict`; one whose
  * effect a stopped daemon may or may not have run is `outcome_unknown` with
  * the effect id in `data.effectRef`, and never starts the effect again.
+ * A replay-only request never claims: it answers a held key as a retry
+ * does, and refuses a key the ledger does not hold, never held or since
+ * swept, with `idempotency_key_unknown`, running nothing.
  * An effect that may still stand once its request fails is answered with
  * `outcome_unknown` and its effect id even when recording that outcome
  * fails: the claim stays held either way, and the failed write goes to the
@@ -107,6 +112,19 @@ export class IdempotencyLedger {
       key: call.keyed.key,
     };
 
+    if (call.keyed.replayOnly === true) {
+      const found = await this.store.findIdempotencyKey(id);
+
+      if (found === null) {
+        throw new DaemonError(
+          'idempotency_key_unknown',
+          `this daemon holds no ${call.operation} under idempotency key '${call.keyed.key}', so a replay-only request runs nothing`,
+        );
+      }
+
+      return answerHeldKey(call, found);
+    }
+
     const held = await this.store.claimIdempotencyKey({
       ...id,
       payloadHash: call.keyed.payloadHash,

package/src/daemon/imp-port.ts

@@ -19,8 +19,10 @@ export interface ImpPort {
   // The names of the secrets granted to an imp.
   readonly readGrants: (name: string) => Promise<readonly string[]>;
 
-  // Grants a secret to an imp; granting one it already holds changes
-  // nothing, and nothing in the result distinguishes the two.
+  // Grants a secret to an imp. impd's grant add is idempotent: granting one
+  // the imp already holds changes nothing, and impd returns no creation or
+  // ownership receipt, so nothing in the result tells a new grant from an
+  // existing one or shows who added it.
   readonly createGrant: (name: string, secret: string) => Promise<void>;
 
   // Revokes a secret from an imp, and reports whether impd held the grant.

package/src/daemon/imp-provider.ts

@@ -1,6 +1,7 @@
 import { DaemonError } from '../protocol/daemon-error';
 import { LineDecoder } from '../protocol/line-decoder';
 import { isCompiledBinary } from '../shared/is-compiled-binary';
+import { buildImpName } from './build-imp-name';
 import { buildTarArchive } from './build-tar-archive';
 import type {
   CommandResult,
@@ -20,10 +21,12 @@ import { ImpPortError } from './imp-port-error';
 /**
  * The options an `imp` target takes beside its provider: the image a new
  * imp boots, the memory it gets, the folder inside each imp that atc's
- * files go under, and the path of an atc binary already installed in the
- * image. None holds a credential.
+ * files go under, the path of an atc binary already installed in the
+ * image, and the prefix every imp name the target builds starts with.
+ * None holds a credential.
  */
 export interface ImpTargetOptions {
+  readonly impPrefix?: string;
   readonly image?: string;
   readonly memoryMib?: number;
   readonly guestDir?: string;
@@ -48,6 +51,9 @@ interface ImpProviderOptions {
 // none.
 const GUEST_DIR = '/tmp/atc';
 
+// The start of every imp name when the target sets no prefix.
+const IMP_PREFIX = 'atc-';
+
 // impd takes a lease of 10 to 3600 seconds; the daemon renews at a third of it.
 const LEASE_SECONDS = 600;
 
@@ -86,6 +92,10 @@ export class ImpProvider implements ExecutionProvider {
 
   readonly guest: GuestLayout;
 
+  // The literal start of every imp name this provider builds: the runtime
+  // namespace an impd token's imp patterns are checked against.
+  readonly impPrefix: string;
+
   private readonly port: ImpPort;
 
   private readonly target: ImpTargetOptions;
@@ -109,6 +119,7 @@ export class ImpProvider implements ExecutionProvider {
   constructor(port: ImpPort, target: ImpTargetOptions, options: ImpProviderOptions = {}) {
     this.port = port;
     this.target = target;
+    this.impPrefix = target.impPrefix ?? IMP_PREFIX;
     this.leaseSeconds = options.leaseSeconds ?? LEASE_SECONDS;
     this.reconnectDelaysMs = options.reconnectDelaysMs ?? RECONNECT_DELAYS_MS;
 
@@ -123,10 +134,15 @@ export class ImpProvider implements ExecutionProvider {
     };
   }
 
+  // The imp a host key runs on, under this provider's prefix.
+  getImpName(hostKey: string): string {
+    return buildImpName(this.impPrefix, hostKey);
+  }
+
   // Creates the host's imp when impd holds none, then takes the daemon's
   // lease, which boots or wakes the imp.
   readonly prepareHost = async (request: HostRequest): Promise<void> => {
-    const name = buildImpName(request.host);
+    const name = this.getImpName(request.host);
     const label = `atc-${request.daemonID}`;
 
     this.label = label;
@@ -181,7 +197,7 @@ export class ImpProvider implements ExecutionProvider {
 
   readonly spawnHarness = (spec: HarnessSpec): HarnessHandle => {
     const host = this.hosts.get(spec.host) ?? {
-      name: buildImpName(spec.host),
+      name: this.getImpName(spec.host),
       harnesses: 0,
       renewTimer: null,
       suspending: false,
@@ -257,7 +273,7 @@ export class ImpProvider implements ExecutionProvider {
   // carries what impd showed of the other leases.
   readonly suspendHost = async (hostKey: string): Promise<void> => {
     const host = this.hosts.get(hostKey) ?? {
-      name: buildImpName(hostKey),
+      name: this.getImpName(hostKey),
       harnesses: 0,
       renewTimer: null,
       suspending: false,
@@ -290,7 +306,7 @@ export class ImpProvider implements ExecutionProvider {
   // A destroy ends every lease on the imp with it.
   readonly destroyHost = async (hostKey: string): Promise<void> => {
     const host = this.hosts.get(hostKey);
-    const name = buildImpName(hostKey);
+    const name = this.getImpName(hostKey);
 
     if (host !== undefined) {
       this.stopRenewal(host);
@@ -405,9 +421,9 @@ export class ImpProvider implements ExecutionProvider {
     }
 
     try {
-      return await this.port.runCommand(buildImpName(hostKey), command);
+      return await this.port.runCommand(this.getImpName(hostKey), command);
     } catch (error) {
-      throw toHostRefusal(error, buildImpName(hostKey));
+      throw toHostRefusal(error, this.getImpName(hostKey));
     }
   }
 
@@ -496,17 +512,6 @@ interface ImpHost {
   suspending: boolean;
 }
 
-/**
- * The imp a host key runs on: `atc-` and the first 20 letters and digits of
- * the key, which is the atc session id of the session that owns the host.
- */
-function buildImpName(hostKey: string): string {
-  return `atc-${hostKey
-    .toLowerCase()
-    .replaceAll(/[^a-z0-9]/g, '')
-    .slice(0, 20)}`;
-}
-
 function buildImpSessionName(sessionID: string): string {
   return `atc-${sessionID
     .toLowerCase()

package/src/daemon/is-allowed-listen-host.ts

@@ -0,0 +1,63 @@
+import { isIPv4, isIPv6 } from 'node:net';
+
+// An IPv6 range as its leading 16-bit groups and how many of their bits
+// must match.
+interface IPv6Range {
+  readonly groups: readonly number[];
+  readonly bits: number;
+}
+
+// The IPv6 ranges a listener may bind in: loopback `::1/128` and the
+// tailnet range `fd7a:115c:a1e4::/48`.
+const IPV6_RANGES: readonly IPv6Range[] = [
+  { groups: [0, 0, 0, 0, 0, 0, 0, 1], bits: 128 },
+  { groups: [0xfd_7a, 0x11_5c, 0xa1_e4], bits: 48 },
+];
+
+/**
+ * Whether a TCP listener may bind the host: an IP literal that is loopback
+ * (`127.0.0.0/8`, `::1`) or inside the tailnet ranges `100.64.0.0/10` and
+ * `fd7a:115c:a1e4::/48`. The protocol carries no TLS, so a listener relies
+ * on the tailnet's encryption, and a wildcard bind or a host name, whose
+ * address could resolve anywhere, is refused.
+ */
+export function isAllowedListenHost(host: string): boolean {
+  if (isIPv4(host)) {
+    const octets = host.split('.').map(Number);
+    const first = octets[0] ?? -1;
+    const second = octets[1] ?? -1;
+
+    return first === 127 || (first === 100 && second >= 64 && second <= 127);
+  }
+
+  if (isIPv6(host)) {
+    const groups = expandIPv6Groups(host);
+
+    return groups !== null && IPV6_RANGES.some((range) => hasPrefix(groups, range));
+  }
+
+  return false;
+}
+
+// The eight 16-bit groups of an IPv6 literal, or null for a literal with an
+// embedded IPv4 tail, which no allowed range holds.
+function expandIPv6Groups(host: string): number[] | null {
+  if (host.includes('.')) {
+    return null;
+  }
+
+  const [head = '', tail] = host.split('::');
+  const headGroups = head === '' ? [] : head.split(':');
+  const tailGroups = tail === undefined || tail === '' ? [] : tail.split(':');
+  const fill = 8 - headGroups.length - tailGroups.length;
+
+  return [...headGroups, ...Array.from({ length: fill }, () => '0'), ...tailGroups].map((group) =>
+    Number.parseInt(group, 16),
+  );
+}
+
+function hasPrefix(groups: readonly number[], range: IPv6Range): boolean {
+  const whole = Math.floor(range.bits / 16);
+
+  return range.groups.slice(0, whole).every((group, index) => groups[index] === group);
+}

package/src/daemon/load-listener-tokens.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+
+// The fewest bytes a listener token may hold.
+const MIN_TOKEN_BYTES = 32;
+
+type LoadedListenerTokens =
+  | { readonly ok: true; readonly tokens: readonly string[] }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * Reads the TCP listener's token file: one or two tokens, one per line,
+ * each at least 32 bytes once surrounding whitespace is trimmed. A final
+ * newline is allowed. An unreadable file, an empty one, a blank line, a
+ * third token, or a short token makes the whole file invalid, so a broken
+ * file never leaves part of it working.
+ */
+export function loadListenerTokens(path: string): LoadedListenerTokens {
+  let text: string;
+
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+
+    return { ok: false, reason: `cannot read ${path}: ${detail}` };
+  }
+
+  const lines = (text.endsWith('\n') ? text.slice(0, -1) : text).split('\n');
+  const tokens = lines.map((line) => line.trim());
+
+  if (tokens.some((token) => Buffer.byteLength(token) < MIN_TOKEN_BYTES)) {
+    return {
+      ok: false,
+      reason: `${path} holds a token under ${MIN_TOKEN_BYTES} bytes or a blank line`,
+    };
+  }
+
+  if (tokens.length > 2) {
+    return {
+      ok: false,
+      reason: `${path} holds ${tokens.length} lines; it takes one or two tokens`,
+    };
+  }
+
+  return { ok: true, tokens };
+}