@vantran-se/openchamber-web 1.24.4 → 2.0.2

package/server/lib/spaces/errors.js

@@ -0,0 +1,8 @@
+export class SpaceError extends Error {
+  constructor(code, message, details = null) {
+    super(message);
+    this.name = 'SpaceError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/server/lib/spaces/exec-http.js

@@ -0,0 +1,94 @@
+// One HTTP request inside a container, over `exec` and nothing else, so that it works for every
+// place. The two channels written on top of this, `space-server.js` and `gatekeeper-channel.js`,
+// share these pieces: the curl argv, the request as a curl config, and the answer parser.
+//
+// Everything that comes back is untrusted. What listens on the port inside can be agent code.
+
+import { SpaceError } from './errors.js';
+import { IMAGE_CURL } from './layout.js';
+
+// How much text from inside a container an error message may carry.
+const ERROR_TAIL_CHARACTERS = 2_000;
+
+// How much of an answer's header block the host is willing to parse. A real answer is about 1 KB.
+const MAX_HEADER_BYTES = 64 * 1024;
+const MAX_HEADER_LINES = 200;
+
+// Exit codes of a `docker exec` that failed by itself: no such container, container not running,
+// curl missing. curl uses 1 too. Measured with curl 7.88.1: a listener that answers `hello` gives
+// exit code 1 and `curl: (1) Received HTTP/0.9 when not allowed`. curl starts every error line
+// with `curl:`, so one of these codes means "exec failed" only when stderr does not start like that.
+export const EXEC_FAILED_CODES = [1, 125, 126, 127];
+export const isFromCurl = (stderr) => String(stderr ?? '').trimStart().startsWith('curl:');
+
+// The CLI of an exec was killed. For a request that says something about the inside, not about a Docker step.
+export const EXEC_INTERRUPTED_CODES = ['command_timeout', 'command_killed'];
+
+export const tail = (text) => String(text ?? '').trim().slice(-ERROR_TAIL_CHARACTERS);
+
+/**
+ * The curl arguments. `--disable` must stay first: it is what keeps curl away from the
+ * `~/.curlrc` of the user inside, which the agent can write. `--noproxy '*'` must stay too:
+ * a space has proxy variables in its environment, and measured with curl 7.88.1, curl sends
+ * even a request to 127.0.0.1 to that proxy without it.
+ */
+export const buildCurlArgs = (timeoutSeconds) => [
+  IMAGE_CURL, '--disable', '--noproxy', '*', '--silent', '--show-error', '--include',
+  '--max-time', String(timeoutSeconds), '--config', '-',
+];
+
+// A quoted value in a curl config file. Backslash escapes are the only special syntax inside the quotes.
+const quoteConfigValue = (value) => {
+  const text = String(value);
+  if (text.includes('\0')) {
+    throw new SpaceError('invalid_request', 'A request to a container cannot hold a NUL character');
+  }
+  return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}"`;
+};
+
+/**
+ * The whole request as a curl config for stdin. A cookie, a token or a grant's secret in it
+ * therefore shows up in no argument list, on the host or inside the container.
+ */
+export const buildCurlConfig = ({ url, method, headers = {}, body = null }) => [
+  `url = ${quoteConfigValue(url)}`,
+  `request = ${quoteConfigValue(method)}`,
+  // Without this curl asks "Expect: 100-continue" for a large body and the answer gets two header blocks.
+  'header = "Expect:"',
+  ...Object.entries(headers).map(([name, value]) => `header = ${quoteConfigValue(`${name}: ${value}`)}`),
+  // `data-raw`, because `data-binary` reads a body that starts with `@` as a file name.
+  ...(body === null ? [] : [`data-raw = ${quoteConfigValue(body)}`]),
+].join('\n');
+
+/**
+ * The answer of whatever listens on the port. `unreadable(why)` makes the error of the calling
+ * channel, so each one keeps its own code and its own words.
+ *
+ * Header names go into an object without a prototype, so `__proto__` or `constructor` is one more name.
+ */
+export function parseResponse(output, unreadable) {
+  const headerEnd = output.indexOf('\r\n\r\n');
+  // The cap comes before any work on the header block, so a huge block costs the host nothing.
+  if (headerEnd > MAX_HEADER_BYTES) {
+    throw unreadable(`answered with more than ${MAX_HEADER_BYTES} bytes of headers`);
+  }
+  const [statusLine, ...headerLines] = output.slice(0, Math.max(headerEnd, 0)).split('\r\n');
+  const status = Number.parseInt(/^HTTP\/[\d.]+ (\d{3})/.exec(statusLine)?.[1] ?? '', 10);
+  if (headerEnd < 0 || Number.isNaN(status)) {
+    throw unreadable('answered with something that is not HTTP');
+  }
+  if (headerLines.length > MAX_HEADER_LINES) {
+    throw unreadable(`answered with more than ${MAX_HEADER_LINES} header lines`);
+  }
+  const headers = Object.create(null);
+  for (const line of headerLines) {
+    const colon = line.indexOf(':');
+    if (colon > 0) {
+      const name = line.slice(0, colon).trim().toLowerCase();
+      // Pushed, not copied: a copy per line is quadratic in the lines that the inside chooses to send.
+      headers[name] ??= [];
+      headers[name].push(line.slice(colon + 1).trim());
+    }
+  }
+  return { status, headers, body: output.slice(headerEnd + 4) };
+}

package/server/lib/spaces/gatekeeper-channel.js

@@ -0,0 +1,202 @@
+// The host's channel to the gatekeeper of a space, written once on top of `exec` for every place.
+// The space cannot see it: the control listener binds the gatekeeper's own loopback, and the
+// requests run as `curl` inside the gatekeeper container.
+//
+// Every secret the host delivers, a grant's key above all, travels on the stdin of an `exec` as a
+// curl config. It is in no argument list, on the host or inside, in no label and in no file.
+
+import { readFileSync } from 'node:fs';
+
+import { SpaceError } from './errors.js';
+import {
+  EXEC_FAILED_CODES,
+  EXEC_INTERRUPTED_CODES,
+  buildCurlArgs,
+  buildCurlConfig,
+  isFromCurl,
+  parseResponse,
+  tail,
+} from './exec-http.js';
+import { ROLE_GATEKEEPER } from './labels.js';
+import {
+  GATEKEEPER_CONTROL_HOST,
+  GATEKEEPER_CONTROL_PORT,
+  GATEKEEPER_PROGRAM_DIRECTORY,
+  GATEKEEPER_PROGRAM_PATH,
+  IMAGE_ONLY_PATH,
+  IMAGE_SH,
+} from './layout.js';
+
+/**
+ * The gatekeeper's program, read from the file beside this one. `packages/web` ships `server/`
+ * as plain files, so this works in the published package as it does in a checkout.
+ */
+export const GATEKEEPER_PROGRAM = readFileSync(new URL('./gatekeeper-program.cjs', import.meta.url), 'utf8');
+
+const REQUEST_SECONDS = 20;
+// The gatekeeper answers in milliseconds. A long attempt would only delay the wall-clock deadline.
+const HEALTH_SECONDS = 3;
+const READY_TIMEOUT_MS = 60_000;
+const READY_PAUSE_MS = 250;
+// A second stop for a caller whose clock stands still. The deadline is the real limit.
+const READY_MAX_ATTEMPTS = 1_000;
+
+// A journal record is five small fields. These caps are what the host is willing to read back.
+const MAX_JOURNAL_RECORDS = 1_000;
+const MAX_JOURNAL_BODY_CHARACTERS = 1024 * 1024;
+const MAX_JOURNAL_FIELD_CHARACTERS = 256;
+
+// The program goes through a temporary name, so the waiting container never runs half a file.
+const WRITE_PROGRAM_SCRIPT = [
+  IMAGE_ONLY_PATH,
+  `mkdir -p ${GATEKEEPER_PROGRAM_DIRECTORY}`,
+  `&& cat > ${GATEKEEPER_PROGRAM_PATH}.new && mv ${GATEKEEPER_PROGRAM_PATH}.new ${GATEKEEPER_PROGRAM_PATH}`,
+].join(' ');
+
+const pause = (milliseconds) => new Promise((resolve) => { setTimeout(resolve, milliseconds); });
+
+const unreadableAnswer = (why) => new SpaceError('gatekeeper_answer_unreadable', `The gatekeeper of the space ${why}`);
+
+/**
+ * One field of a journal record, as text and no longer than the host reads. A list or an object
+ * where a field should be comes out empty, because a record's fields are text and numbers.
+ */
+const text = (value) => (value === null || value === undefined || value instanceof Object ? '' : String(value).slice(0, MAX_JOURNAL_FIELD_CHARACTERS));
+
+/**
+ * `exec` is the place operation: `(spaceId, argv, { stdin, timeoutMs, target })`. `target` names
+ * the container, and this channel always asks for the gatekeeper.
+ *
+ * Everything that comes back is untrusted, exactly as with the server inside a space. No answer
+ * makes this module throw anything but a SpaceError.
+ */
+export function createGatekeeperChannel({ exec, wait = pause, now = Date.now }) {
+  const execInGatekeeper = (spaceId, argv, options) => exec(spaceId, argv, { ...options, target: ROLE_GATEKEEPER });
+
+  /** The program travels on stdin. It is in no argument, on the host or inside. */
+  const writeProgram = async (spaceId) => {
+    const result = await execInGatekeeper(spaceId, [IMAGE_SH, '-c', WRITE_PROGRAM_SCRIPT], { stdin: GATEKEEPER_PROGRAM });
+    if (result.code !== 0) {
+      throw new SpaceError('gatekeeper_setup_failed', `Could not store the gatekeeper's program: ${tail(result.stderr) || `exit code ${result.code}`}`);
+    }
+  };
+
+  /** One HTTP request to the control listener. Resolves `{ status, headers, body }` for any status. */
+  const request = async (spaceId, { method = 'GET', path, body = null, timeoutSeconds = REQUEST_SECONDS }) => {
+    const config = buildCurlConfig({
+      url: `http://${GATEKEEPER_CONTROL_HOST}:${GATEKEEPER_CONTROL_PORT}${path}`,
+      method,
+      headers: body === null ? {} : { 'Content-Type': 'application/json' },
+      body,
+    });
+    let result;
+    try {
+      result = await execInGatekeeper(spaceId, buildCurlArgs(timeoutSeconds), { stdin: `${config}\n`, timeoutMs: (timeoutSeconds + 10) * 1000 });
+    } catch (error) {
+      // Too much output is an answer from inside, not an interrupted Docker step.
+      if (error.code === 'command_output_too_large') {
+        throw unreadableAnswer('answered with more data than the host accepts');
+      }
+      // No Docker step was interrupted here, so this must not look like one to a rollback.
+      if (EXEC_INTERRUPTED_CODES.includes(error.code)) {
+        throw new SpaceError('gatekeeper_unreachable', `The request to the gatekeeper did not finish in time: ${error.message}`, { curlExitCode: null, execFailed: false });
+      }
+      throw error;
+    }
+    if (result.code !== 0) {
+      throw new SpaceError(
+        'gatekeeper_unreachable',
+        `The gatekeeper of the space did not answer: ${tail(result.stderr) || `curl exit code ${result.code}`}`,
+        { curlExitCode: result.code, execFailed: EXEC_FAILED_CODES.includes(result.code) && !isFromCurl(result.stderr) },
+      );
+    }
+    return parseResponse(result.stdout, unreadableAnswer);
+  };
+
+  /** A control request that must succeed. Anything but 200 is a refusal the caller must see. */
+  const command = async (spaceId, path, body, what) => {
+    const answer = await request(spaceId, { method: 'POST', path, body: JSON.stringify(body) });
+    if (answer.status !== 200) {
+      throw new SpaceError('gatekeeper_refused', `The gatekeeper refused to ${what}: ${tail(answer.body) || `status ${answer.status}`}`, { status: answer.status });
+    }
+  };
+
+  /**
+   * Resolves when the control listener answers, which it does only after the corridor and the
+   * window accept connections. The wait ends at a wall-clock deadline whatever happens inside.
+   */
+  const waitUntilReady = async (spaceId) => {
+    const started = now();
+    let last = 'no answer yet';
+    for (let attempt = 0; attempt < READY_MAX_ATTEMPTS && now() - started < READY_TIMEOUT_MS; attempt += 1) {
+      try {
+        const answer = await request(spaceId, { path: '/health', timeoutSeconds: HEALTH_SECONDS });
+        if (answer.status === 200) {
+          return;
+        }
+        last = `the control channel answered ${answer.status}`;
+      } catch (error) {
+        const fromInside = error.code === 'gatekeeper_answer_unreadable'
+          || (error.code === 'gatekeeper_unreachable' && error.details?.execFailed !== true);
+        if (!fromInside) {
+          throw error;
+        }
+        last = error.message;
+      }
+      await wait(READY_PAUSE_MS);
+    }
+    throw new SpaceError(
+      'gatekeeper_not_ready',
+      `The gatekeeper of the space did not become ready within ${Math.round((now() - started) / 1000)} seconds (${last}). Look at the output of its container.`,
+    );
+  };
+
+  /**
+   * The network mode and the allowlist, live. A gatekeeper that was just started allows nothing
+   * until this call, so a space never reaches further than the host last said it may.
+   */
+  const setNetwork = (spaceId, { mode, domains = [] }) => command(spaceId, '/network', { mode, domains }, 'change the network of this space');
+
+  /** One "uses without seeing" grant. The secret is in the body, so it stays out of every argument list. */
+  const addGrant = (spaceId, { id, upstream, header, secret }) => command(spaceId, '/grants', { id, upstream, header, secret }, `add the grant '${id}'`);
+
+  /**
+   * What the gatekeeper allowed and refused. The answer comes out of a container, so it is read
+   * as data: known fields only, capped in count and in length, and never trusted to be complete.
+   * `dropped` says how many records the ring buffer has thrown away.
+   */
+  const readJournal = async (spaceId) => {
+    const answer = await request(spaceId, { path: '/journal' });
+    if (answer.status !== 200) {
+      throw unreadableAnswer(`answered ${answer.status} for its journal`);
+    }
+    if (answer.body.length > MAX_JOURNAL_BODY_CHARACTERS) {
+      throw unreadableAnswer(`answered with a journal of ${answer.body.length} characters, more than the ${MAX_JOURNAL_BODY_CHARACTERS} the host reads`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(answer.body);
+    } catch {
+      throw unreadableAnswer('answered with a journal that is not JSON');
+    }
+    if (!parsed || !Array.isArray(parsed.records)) {
+      throw unreadableAnswer('answered with a journal that holds no records');
+    }
+    return {
+      records: parsed.records.slice(0, MAX_JOURNAL_RECORDS).map((entry) => {
+        // Only an object has our fields. A string or a list would answer `at` with a method of its own.
+        const record = entry instanceof Object && !Array.isArray(entry) ? entry : {};
+        return {
+          at: text(record.at),
+          listener: text(record.listener),
+          host: text(record.host),
+          port: Number.isSafeInteger(record.port) ? record.port : 0,
+          decision: text(record.decision),
+        };
+      }),
+      dropped: Number.isSafeInteger(parsed.dropped) && parsed.dropped >= 0 ? parsed.dropped : 0,
+    };
+  };
+
+  return { writeProgram, waitUntilReady, setNetwork, addGrant, readJournal };
+}

package/server/lib/spaces/gatekeeper-channel.test.js

@@ -0,0 +1,215 @@
+import { describe, expect, it } from 'vitest';
+
+import { SpaceError } from './errors.js';
+import { GATEKEEPER_PROGRAM, createGatekeeperChannel } from './gatekeeper-channel.js';
+
+const ID = 'a1b2c3d4e5f6';
+const SECRET = 'sk-the-real-key-the-space-never-sees';
+const http = (status, body) => `HTTP/1.1 ${status} OK\r\nContent-Type: application/json\r\n\r\n${body}`;
+const ok = (stdout = '') => ({ code: 0, stdout, stderr: '' });
+
+/**
+ * A channel on a recording `exec`. `answers` are returned in turn, the last one repeats.
+ * Nothing sleeps: the clock moves by the pause in `wait`.
+ */
+const channelWith = (...answers) => {
+  const calls = [];
+  let clock = 1_000_000;
+  const exec = async (spaceId, argv, options) => {
+    calls.push({ spaceId, argv, options });
+    const answer = answers.length > 1 ? answers.shift() : answers[0];
+    if (answer instanceof Error) throw answer;
+    return answer;
+  };
+  const wait = async (milliseconds) => { clock += milliseconds; };
+  return { channel: createGatekeeperChannel({ exec, wait, now: () => clock }), calls };
+};
+
+describe('gatekeeper channel: the program', () => {
+  it('is the file beside this module, and it is one self-contained script', () => {
+    expect(GATEKEEPER_PROGRAM).toContain("require('node:net')");
+    expect(GATEKEEPER_PROGRAM.length).toBeGreaterThan(2_000);
+  });
+
+  it('travels on stdin into the tmpfs, through a temporary name, and is in no argument', async () => {
+    const { channel, calls } = channelWith(ok());
+    await channel.writeProgram(ID);
+
+    expect(calls).toEqual([{
+      spaceId: ID,
+      argv: [
+        '/bin/sh', '-c',
+        'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; mkdir -p /tmp/openchamber-gatekeeper && cat > /tmp/openchamber-gatekeeper/gatekeeper.cjs.new && mv /tmp/openchamber-gatekeeper/gatekeeper.cjs.new /tmp/openchamber-gatekeeper/gatekeeper.cjs',
+      ],
+      options: { stdin: GATEKEEPER_PROGRAM, target: 'gatekeeper' },
+    }]);
+  });
+
+  it('says what failed inside the gatekeeper', async () => {
+    const { channel } = channelWith({ code: 1, stdout: '', stderr: 'sh: 1: cannot create: No space left on device\n' });
+    await expect(channel.writeProgram(ID)).rejects.toMatchObject({ code: 'gatekeeper_setup_failed', message: expect.stringContaining('No space left on device') });
+  });
+});
+
+describe('gatekeeper channel: control requests', () => {
+  it('reaches the control listener on the gatekeeper loopback, with --disable and --noproxy first', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '{"ok":true}')));
+    await channel.setNetwork(ID, { mode: 'allowlist', domains: ['api.anthropic.com'] });
+
+    expect(calls[0].options.target).toBe('gatekeeper');
+    expect(calls[0].argv.slice(0, 4)).toEqual(['/usr/bin/curl', '--disable', '--noproxy', '*']);
+    expect(calls[0].options.stdin.split('\n')).toEqual([
+      'url = "http://127.0.0.1:9099/network"',
+      'request = "POST"',
+      'header = "Expect:"',
+      'header = "Content-Type: application/json"',
+      'data-raw = "{\\"mode\\":\\"allowlist\\",\\"domains\\":[\\"api.anthropic.com\\"]}"',
+      '',
+    ]);
+  });
+
+  it('keeps a grant\'s secret out of every argument list, on the host and inside', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '{"ok":true}')));
+    await channel.addGrant(ID, { id: 'anthropic', upstream: 'https://api.anthropic.com/v1', header: 'x-api-key', secret: SECRET });
+
+    expect(calls[0].argv.join(' ')).not.toContain(SECRET);
+    expect(calls[0].options.stdin).toContain(SECRET);
+  });
+
+  it('reports a refusal from the control channel, with what it said', async () => {
+    const { channel } = channelWith(ok(http(400, '{"error":"mode is \\"allowlist\\" or \\"open\\""}')));
+    await expect(channel.setNetwork(ID, { mode: 'everything', domains: [] })).rejects.toMatchObject({
+      code: 'gatekeeper_refused',
+      details: { status: 400 },
+      message: expect.stringContaining('allowlist'),
+    });
+  });
+
+  it('says when nothing answers, with the curl exit code', async () => {
+    const { channel } = channelWith({ code: 7, stdout: '', stderr: 'curl: (7) Failed to connect to 127.0.0.1 port 9099\n' });
+    await expect(channel.readJournal(ID)).rejects.toMatchObject({ code: 'gatekeeper_unreachable', details: { curlExitCode: 7 } });
+  });
+
+  it.each([
+    ['an answer that is not HTTP', ok('garbage')],
+    ['more output than the host accepts', Object.assign(new Error('too much'), { code: 'command_output_too_large' })],
+  ])('rejects %s as unreadable', async (title, answer) => {
+    const { channel } = channelWith(answer);
+    const error = await channel.readJournal(ID).catch((caught) => caught);
+    expect(error).toBeInstanceOf(SpaceError);
+    expect(error.code).toBe('gatekeeper_answer_unreadable');
+  });
+
+  it('maps an exec that timed out to "unreachable", never to an interrupted Docker step', async () => {
+    for (const code of ['command_timeout', 'command_killed']) {
+      const { channel } = channelWith(Object.assign(new Error('docker exec did not finish'), { code }));
+      const error = await channel.readJournal(ID).catch((caught) => caught);
+      expect(error.code).toBe('gatekeeper_unreachable');
+      expect(error.details.execFailed).toBe(false);
+    }
+  });
+
+  it('lets a failure of the place through', async () => {
+    const failure = Object.assign(new Error('spawn docker ENOENT'), { code: 'command_spawn_failed' });
+    const { channel } = channelWith(failure);
+    await expect(channel.readJournal(ID)).rejects.toBe(failure);
+  });
+});
+
+describe('gatekeeper channel: journal', () => {
+  const record = { at: '2026-09-20T10:00:00.000Z', listener: 'corridor', host: 'api.anthropic.com', port: 443, decision: 'allow' };
+
+  it('reads the records and how many the ring buffer dropped', async () => {
+    const { channel } = channelWith(ok(http(200, JSON.stringify({ records: [record], dropped: 12 }))));
+    expect(await channel.readJournal(ID)).toEqual({ records: [record], dropped: 12 });
+  });
+
+  it('keeps the five fields of a record and nothing else the gatekeeper sends', async () => {
+    const hostile = { ...record, path: '/v1/messages?key=leak', body: 'a body', secret: SECRET, extra: { deep: true } };
+    const { channel } = channelWith(ok(http(200, JSON.stringify({ records: [hostile], dropped: 0 }))));
+
+    const journal = await channel.readJournal(ID);
+    expect(Object.keys(journal.records[0])).toEqual(['at', 'listener', 'host', 'port', 'decision']);
+    expect(JSON.stringify(journal)).not.toContain(SECRET);
+  });
+
+  it('caps the records it reads, and the length of every field', async () => {
+    // The gatekeeper keeps 500 records, so more than a thousand means something inside is wrong.
+    const many = Array.from({ length: 2_000 }, () => ({ ...record, host: 'x'.repeat(400) }));
+    const { channel } = channelWith(ok(http(200, JSON.stringify({ records: many, dropped: -1 }))));
+
+    const journal = await channel.readJournal(ID);
+    expect(journal.records).toHaveLength(1_000);
+    expect(journal.records[0].host).toHaveLength(256);
+    expect(journal.dropped).toBe(0);
+  });
+
+  it('refuses a journal larger than the host reads, instead of spending the time on it', async () => {
+    const { channel } = channelWith(ok(http(200, JSON.stringify({ records: [{ ...record, host: 'x'.repeat(2 * 1024 * 1024) }] }))));
+    await expect(channel.readJournal(ID)).rejects.toMatchObject({ code: 'gatekeeper_answer_unreadable' });
+  });
+
+  it.each([
+    ['a body that is not JSON', '<html>'],
+    ['a journal without records', '{"dropped":0}'],
+    ['records that are not a list', '{"records":"none"}'],
+    ['null', 'null'],
+  ])('rejects %s instead of answering an empty journal', async (title, body) => {
+    const { channel } = channelWith(ok(http(200, body)));
+    await expect(channel.readJournal(ID)).rejects.toMatchObject({ code: 'gatekeeper_answer_unreadable' });
+  });
+
+  it('turns a record of another shape into empty fields, and never throws', async () => {
+    const { channel } = channelWith(ok(http(200, JSON.stringify({ records: [null, 'text', { port: 'many' }] }))));
+    expect(await channel.readJournal(ID)).toEqual({
+      records: [
+        { at: '', listener: '', host: '', port: 0, decision: '' },
+        { at: '', listener: '', host: '', port: 0, decision: '' },
+        { at: '', listener: '', host: '', port: 0, decision: '' },
+      ],
+      dropped: 0,
+    });
+  });
+});
+
+describe('gatekeeper channel: waitUntilReady', () => {
+  const refused = { code: 7, stdout: '', stderr: 'curl: (7) Failed to connect' };
+
+  it('waits through "nothing listens yet" and resolves when the control channel answers', async () => {
+    const { channel, calls } = channelWith(refused, refused, ok(http(200, '{"ready":true}')));
+    await channel.waitUntilReady(ID);
+    expect(calls).toHaveLength(3);
+  });
+
+  it('gives up at the deadline and says what it saw last', async () => {
+    const { channel } = channelWith(refused);
+    const error = await channel.waitUntilReady(ID).catch((caught) => caught);
+    expect(error).toBeInstanceOf(SpaceError);
+    expect(error.code).toBe('gatekeeper_not_ready');
+    expect(error.message).toMatch(/within 60 seconds \(.*Failed to connect/);
+  });
+
+  it.each([
+    ['a listener that does not speak HTTP', { code: 1, stdout: '', stderr: 'curl: (1) Received HTTP/0.9 when not allowed\n' }],
+    ['an answer that is not HTTP', ok('garbage')],
+    ['a 503 from the control channel', ok(http(503, '{}'))],
+    ['an exec that timed out', Object.assign(new Error('docker exec did not finish'), { code: 'command_timeout' })],
+  ])('counts %s as "not ready yet"', async (title, hostile) => {
+    const { channel, calls } = channelWith(hostile);
+    await expect(channel.waitUntilReady(ID)).rejects.toMatchObject({ code: 'gatekeeper_not_ready' });
+    expect(calls.length).toBeGreaterThan(1);
+  });
+
+  it('stops at once when the container is gone', async () => {
+    const { channel, calls } = channelWith({ code: 1, stdout: '', stderr: 'Error response from daemon: container abc is not running' });
+    await expect(channel.waitUntilReady(ID)).rejects.toMatchObject({ code: 'gatekeeper_unreachable', details: { execFailed: true } });
+    expect(calls).toHaveLength(1);
+  });
+
+  it('asks with a short time limit, so a listener that never answers costs little', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '{"ready":true}')));
+    await channel.waitUntilReady(ID);
+    expect(calls[0].argv).toContain('3');
+    expect(calls[0].options.timeoutMs).toBe(13_000);
+  });
+});