@vantran-se/openchamber-web 2.0.3 → 2.0.5

package/server/lib/spaces/layout.js

@@ -63,9 +63,11 @@ export const SPACE_TOKEN_PATH = `${SPACE_TOKEN_DIRECTORY}/token`;
 // The gatekeeper, the space's only way out. It sits on the space's internal network under this
 // name and on the space's own outer network, and nothing else joins either of them.
 export const GATEKEEPER_ALIAS = 'gatekeeper';
-// The two listeners the space may see. They bind every interface of the gatekeeper, because
-// the space's network is the point of them.
-const GATEKEEPER_BIND_HOST = '0.0.0.0';
+// The two listeners the space may see. They bind the gatekeeper's own address on the space's
+// network and nothing else: on a Linux Docker host every local process can reach the bridge the
+// outer network is, and a window listening there would spend the user's key for anyone on the
+// machine. The address is known only once the container runs, so the host writes it into this
+// file beside the program, and the container command names the file.
 export const GATEKEEPER_CORRIDOR_PORT = 3128;
 export const GATEKEEPER_WINDOW_PORT = 8080;
 // The control channel. It binds the gatekeeper's own loopback, so only an `exec` from the host
@@ -74,14 +76,22 @@ export const GATEKEEPER_WINDOW_PORT = 8080;
 export const GATEKEEPER_CONTROL_HOST = '127.0.0.1';
 export const GATEKEEPER_CONTROL_PORT = 9099;
 
-// Where the space sends its traffic. The window's own URL, `http://gatekeeper:8080/model/<grant>`,
-// belongs to whoever writes a provider configuration, which no stage does yet.
+// Where the space sends its traffic: the corridor, and for a grant the window under that grant's id.
 const GATEKEEPER_CORRIDOR_URL = `http://${GATEKEEPER_ALIAS}:${GATEKEEPER_CORRIDOR_PORT}`;
+/** The URL inside the space that reaches a grant's upstream through the window. */
+export const spaceWindowUrl = (grantId) => `http://${GATEKEEPER_ALIAS}:${GATEKEEPER_WINDOW_PORT}/model/${grantId}`;
 
 // The gatekeeper's program arrives over `exec` on stdin, into the container's tmpfs. It is far
 // larger than the tools filler, and a `node -e` argument of that size was never tried on Windows.
 export const GATEKEEPER_PROGRAM_DIRECTORY = '/tmp/openchamber-gatekeeper';
 export const GATEKEEPER_PROGRAM_PATH = `${GATEKEEPER_PROGRAM_DIRECTORY}/gatekeeper.cjs`;
+export const GATEKEEPER_BIND_PATH = `${GATEKEEPER_PROGRAM_DIRECTORY}/bind`;
+
+// OpenCode's global configuration inside a space, where the host writes the provider
+// configuration that sends model calls through the window. The agent can change it; the
+// gatekeeper is what enforces, this only cooperates.
+export const SPACE_OPENCODE_CONFIG_DIRECTORY = `${SPACE_HOME}/.config/opencode`;
+export const SPACE_OPENCODE_CONFIG_PATH = `${SPACE_OPENCODE_CONFIG_DIRECTORY}/opencode.json`;
 
 const IMAGE_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin';
 
@@ -103,8 +113,9 @@ export const IMAGE_TIMEOUT = '/usr/bin/timeout';
 export const IMAGE_ONLY_PATH = `PATH=${IMAGE_PATH};`;
 
 /**
- * The environment of a space. The password of the server inside and
- * OPENCODE_AUTH_CONTENT never go here: container env is readable through `inspect`.
+ * The environment of a space. Neither the password of the server inside nor any credential ever
+ * goes here: container env is readable through `inspect`, and the hardening check allows no
+ * variable beyond these and the base image's own.
  */
 export const SPACE_ENVIRONMENT = Object.freeze({
   HOME: SPACE_HOME,
@@ -145,6 +156,29 @@ const SERVER_SCRIPT = [
 /** The command of a space container. A fixed script, nothing in it varies per space. */
 export const SPACE_SERVER_COMMAND = Object.freeze([IMAGE_SH, '-c', SERVER_SCRIPT]);
 
+// The bridge of `connect`: runs inside the space over `docker exec --interactive`, joins its stdin
+// and stdout to the loopback port of the server inside, and ends when either side ends. It
+// leaves only after its last write to stdout has gone out: an exit on the socket's close would
+// drop what is still buffered. The two standard streams are Node's own, which cope with a pipe
+// that is full; a plain file stream on the descriptor failed with a system error there,
+// measured on macOS with a four-megabyte answer. One line, as every fixed program that travels
+// as an argument. It uses `net`, which no proxy variable of the space touches, and reads nothing
+// from the space but its two arguments.
+export const CONNECT_BRIDGE_PROGRAM = [
+  'const net = require("node:net");',
+  'const [host, port] = process.argv.slice(1);',
+  'const socket = net.connect({ host, port: Number(port) });',
+  'const leave = (code) => process.stdout.write("", () => process.exit(code));',
+  'socket.on("error", (error) => { process.stderr.write(String(error.code || error.message)); leave(1); });',
+  'socket.on("connect", () => { process.stdin.pipe(socket); socket.pipe(process.stdout, { end: false }); });',
+  'socket.on("close", () => leave(0));',
+  'process.stdin.on("error", () => socket.destroy());',
+  'process.stdout.on("error", () => socket.destroy());',
+].join(' ');
+
+/** The command that `connect` runs inside a space: the bridge to the server inside, on the image's Node. */
+export const SPACE_CONNECT_COMMAND = Object.freeze([IMAGE_NODE, '-e', CONNECT_BRIDGE_PROGRAM, SPACE_SERVER_HOST, String(SPACE_SERVER_PORT)]);
+
 /**
  * The environment of a gatekeeper. It holds no secret and never will: grants arrive on the
  * stdin of an `exec` and live in the program's memory. HOME points into the tmpfs, because the
@@ -170,7 +204,7 @@ const GATEKEEPER_CONTROL_CONNECTIONS = 8;
 const GATEKEEPER_SCRIPT = [
   `while [ ! -s ${GATEKEEPER_PROGRAM_PATH} ]; do ${IMAGE_SLEEP} 0.2; done;`,
   `exec ${IMAGE_NODE} ${GATEKEEPER_PROGRAM_PATH}`,
-  GATEKEEPER_BIND_HOST,
+  GATEKEEPER_BIND_PATH,
   String(GATEKEEPER_CORRIDOR_PORT),
   String(GATEKEEPER_WINDOW_PORT),
   String(GATEKEEPER_CONTROL_PORT),

package/server/lib/spaces/manager.js

@@ -1,5 +1,5 @@
 import { SpaceError } from './errors.js';
-import { createSpaceId, hashProjectDirectory, normalizeSpaceName } from './labels.js';
+import { createSpaceId, hashProjectDirectory, normalizeSpaceName, requireSpaceId } from './labels.js';
 
 // Memory limit of a new space. Swap adds nothing on top of it.
 const DEFAULT_SPACE_MEMORY_BYTES = 4 * 1024 * 1024 * 1024;
@@ -29,10 +29,11 @@ export function createSpaceManager({ registry, now = () => new Date() }) {
     return result;
   };
 
-  const createSpace = async ({ placeId, projectDirectory, name }) => {
+  // `id` may be given, so a caller that announces a creation before it is done names the same space.
+  const createSpace = async ({ placeId, projectDirectory, name, id = createSpaceId() }) => {
     const place = requirePlace(placeId);
     const spec = {
-      id: createSpaceId(),
+      id: requireSpaceId(id),
       name: normalizeSpaceName(name),
       project: hashProjectDirectory(projectDirectory),
       created: now().toISOString(),

package/server/lib/spaces/manager.test.js

@@ -29,6 +29,12 @@ describe('createSpaceManager', () => {
     expect(await manager.listSpaces({ placeId: 'memory' })).toEqual([{ ...listedFields, state: 'running', orphans: [], damaged: false, missing: [] }]);
   });
 
+  it('takes the id a caller announced before the creation, and refuses one that is not a space id', async () => {
+    const manager = managerFor(createMemoryPlace());
+    expect((await manager.createSpace({ ...REQUEST, id: 'a1b2c3d4e5f6' })).id).toBe('a1b2c3d4e5f6');
+    await expect(manager.createSpace({ ...REQUEST, id: 'not-an-id' })).rejects.toMatchObject({ code: 'invalid_space_id' });
+  });
+
   it('names the place that does not exist', async () => {
     const manager = managerFor(createMemoryPlace());
 

package/server/lib/spaces/places/code-out.docker.live.test.js

@@ -0,0 +1,412 @@
+// Code out, from a real space on a real Docker daemon. Runs only with OPENCHAMBER_TEST_DOCKER=1.
+// The bait comes in through code in, a scripted agent works inside, and its result comes out over
+// `git fetch` through `docker exec` and is applied both ways. The escape attempts of TESTING.md that
+// belong to code out run from inside, each with its control. Every test makes a space of its own
+// and a repository of its own, so each runs alone as well as in order, and removes its space.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createTestHost, forConfig, hostState, makeBait, removeTestHosts, unexpectedChanges } from '../code-in-bait.js';
+import { createSpaceId, hashProjectDirectory, spaceResourceName } from '../labels.js';
+import { runCommand } from '../run-command.js';
+import { LIVE_DOCKER_ENABLED, createLiveDockerPlace } from './docker-live-support.js';
+
+const CREATE_TIMEOUT_MS = 25 * 60_000;
+const WIN = process.platform === 'win32';
+const IMAGE_PATH = 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin;';
+// The same sizing as the hanging tests of code in: a measured `docker exec` round trip, with a 6 s
+// host timeout and a 5 s margin as the floor.
+const hangTiming = (roundTripMs) => {
+  const hostTimeoutMs = Math.max(6000, 3 * roundTripMs + 3000);
+  const innerMarginSeconds = Math.max(5, Math.ceil((4 * roundTripMs + 4000) / 1000));
+  return { roundTripMs, hostTimeoutMs, innerMarginSeconds, innerLimitMs: hostTimeoutMs + innerMarginSeconds * 1000 };
+};
+// The docker calls between `started` and the fetch, where the limit inside begins to count: `execArgv`
+// inspects, and the snapshot's `exec` inspects and runs.
+const DOCKER_CALLS_BEFORE_FETCH = 3;
+
+// What the agent can plant for the fetch out: git in the space reads its global config, and
+// `uploadpack.packObjectsHook` from there runs in place of pack-objects. This one never ends.
+const PLANT_HANGING_PACK_HOOK = [
+  IMAGE_PATH,
+  'printf "#!/bin/sh\\nexec /bin/sleep 1000\\n" > "$HOME/hang-pack" &&',
+  'chmod 755 "$HOME/hang-pack" &&',
+  'git config --global uploadpack.packObjectsHook "$HOME/hang-pack"',
+].join(' ');
+// A `packObjectsHook` that sends a pack without end: a header that promises a million objects,
+// then one incompressible megabyte after another. Only the host's size cap stops it before its deadline.
+const ENDLESS_PACK = [
+  "const zlib = require('node:zlib'); const crypto = require('node:crypto');",
+  "process.stdout.on('error', () => process.exit(0));",
+  "const head = Buffer.alloc(12); head.write('PACK'); head.writeUInt32BE(2, 4); head.writeUInt32BE(1000000, 8); process.stdout.write(head);",
+  'const blob = () => { let size = 1 << 20; const bytes = [(3 << 4) | (size & 15)]; size >>= 4;',
+  'while (size) { bytes[bytes.length - 1] |= 0x80; bytes.push(size & 0x7f); size >>= 7; }',
+  'return Buffer.concat([Buffer.from(bytes), zlib.deflateSync(crypto.randomBytes(1 << 20))]); };',
+  "const pump = () => { while (process.stdout.write(blob())) {} process.stdout.once('drain', pump); }; pump();",
+].join(' ');
+const PLANT_ENDLESS_PACK_HOOK = [
+  IMAGE_PATH,
+  'printf "%s" "$1" > "$HOME/endless-pack.js" &&',
+  'printf "#!/bin/sh\\nexec /usr/local/bin/node %s\\n" "$HOME/endless-pack.js" > "$HOME/endless-pack" &&',
+  'chmod 755 "$HOME/endless-pack" &&',
+  'git config --global uploadpack.packObjectsHook "$HOME/endless-pack"',
+].join(' ');
+const COUNT_ENDLESS = 'PATH=/usr/bin:/bin; n=0; for p in /proc/[0-9]*; do tr "\\000" " " < "$p/cmdline" 2>/dev/null | grep -q "^/usr/local/bin/node /home/space/endless-pack.js" && n=$((n+1)); done; echo $n';
+const COUNT_SLEEPERS = 'PATH=/usr/bin:/bin; n=0; for p in /proc/[0-9]*; do tr "\\000" " " < "$p/cmdline" 2>/dev/null | grep -q "^/bin/sleep 1000" && n=$((n+1)); done; echo $n';
+// The processes of a fetch out: the image's `timeout`, the upload-pack under it and its pack-objects.
+// Anchored, so the counting script's own command line never counts.
+const COUNT_UPLOADERS = 'PATH=/usr/bin:/bin; n=0; for p in /proc/[0-9]*; do tr "\\000" " " < "$p/cmdline" 2>/dev/null | grep -qE "^(/usr/bin/timeout |/usr/bin/git upload-pack |git pack-objects )" && n=$((n+1)); done; echo $n';
+
+const pause = (milliseconds) => new Promise((resolve) => { setTimeout(resolve, milliseconds); });
+
+/** How many host processes name this container on their command line. The docker CLI of an exec always does. */
+async function hostProcessesNaming(container) {
+  if (WIN) {
+    const script = `@(Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '*${container}*' -and $_.ProcessId -ne $PID }).Count`;
+    const result = await runCommand('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script]);
+    return Number(result.stdout.trim());
+  }
+  const result = await runCommand('ps', ['-A', '-o', 'command=']);
+  return result.stdout.split('\n').filter((command) => command.includes(container)).length;
+}
+
+/** Waits up to two seconds for the host processes that name the container to be gone. It must finish before the limit inside. */
+async function hostProcessesGone(container, innerLimitAt) {
+  let count = await hostProcessesNaming(container);
+  for (let attempt = 0; attempt < 8 && count > 0; attempt += 1) {
+    await pause(250);
+    count = await hostProcessesNaming(container);
+  }
+  expect(Date.now(), 'the host check ran into the limit inside the space and proves nothing').toBeLessThan(innerLimitAt);
+  return count === 0;
+}
+
+describe.skipIf(!LIVE_DOCKER_ENABLED)('code out: docker (live)', () => {
+  let place;
+  let dispose = async () => {};
+  let host;
+  let timing;
+
+  const inside = (spaceId, script, args = []) => place.exec(spaceId, ['/bin/sh', '-c', `${IMAGE_PATH} ${script}`, 'sh', ...args], { timeoutMs: 120_000 });
+
+  /**
+   * A space of its own with a bait repository of its own brought in. `history: false` leaves the
+   * space's repository shallow. `agent(script)` runs a script in the space's project folder as the agent.
+   */
+  const spaceWithCode = async (name, { history = true } = {}) => {
+    const spec = { id: createSpaceId(), name, project: hashProjectDirectory(`/code/out/${name}`), created: new Date().toISOString(), memoryBytes: 1024 * 1024 * 1024 };
+    await place.create(spec);
+    const bait = makeBait(host, { name: `bait ${spec.id}` });
+    const codeIn = host.codeIn(place);
+    const came = await codeIn.bringCodeIn({ repository: bait.repo, spaceId: spec.id });
+    if (history) await codeIn.sendHistory({ repository: bait.repo, spaceId: spec.id, spacePath: came.spacePath, base: came.base });
+    const agent = async (script, args = []) => {
+      const result = await inside(spec.id, `cd "$1" && shift && ${script}`, [came.spacePath, ...args]);
+      expect(result.code, `the agent's script failed: ${result.stderr}`).toBe(0);
+      return result.stdout;
+    };
+    const codeOut = host.codeOut(place);
+    const request = (extra = {}) => ({ repository: bait.repo, spaceId: spec.id, spacePath: came.spacePath, ...extra });
+    return { ...bait, id: spec.id, came, agent, codeOut, request, out: (extra) => codeOut.bringCodeOut(request(extra)), remove: () => place.remove(spec.id) };
+  };
+
+  beforeAll(async () => {
+    ({ place, dispose } = createLiveDockerPlace());
+    host = createTestHost({ ownHome: false });
+    // The slowest of three round trips of `docker exec` sizes the hanging test. The space is removed afterwards.
+    const probe = { id: createSpaceId(), name: 'Code out probe', project: hashProjectDirectory('/code/out/probe'), created: new Date().toISOString(), memoryBytes: 512 * 1024 * 1024 };
+    await place.create(probe);
+    let roundTripMs = 0;
+    for (let sample = 0; sample < 3; sample += 1) {
+      const sampleStarted = Date.now();
+      await place.exec(probe.id, ['/bin/true']);
+      roundTripMs = Math.max(roundTripMs, Date.now() - sampleStarted);
+    }
+    timing = hangTiming(roundTripMs);
+    await place.remove(probe.id);
+  }, CREATE_TIMEOUT_MS);
+
+  afterAll(async () => {
+    await dispose();
+    removeTestHosts();
+  }, CREATE_TIMEOUT_MS);
+
+  it('brings the agent\'s work out and applies it as a branch and as uncommitted changes', async () => {
+    const space = await spaceWithCode('Code out');
+    const { repo, g } = space;
+    await space.agent('printf "committed\\n" > committed.txt && printf "#!/bin/sh\\necho tool\\n" > tool.sh && chmod 755 tool.sh && git add committed.txt tool.sh && git commit --quiet -m "the agent commits"');
+    const agentHead = (await space.agent('git rev-parse HEAD')).trim();
+    await space.agent('printf "uncommitted\\n" >> tracked-to-edit.txt && printf "untracked\\n" > untracked-in-the-space.txt && git add untracked-in-the-space.txt');
+    const statusInside = await space.agent('git status --porcelain=v1 --untracked-files=all');
+    const before = hostState(repo);
+
+    const out = await space.out();
+    expect(g(['rev-parse', `${out.result}^`]).trim()).toBe(agentHead);
+    expect(g(['log', '-1', '--format=%s', out.result]).trim()).toBe('openchamber: uncommitted changes from the space');
+    expect(out.changedPaths).toBe(4);
+    expect(out.nestedRepositories).toEqual({ count: 0, paths: [] });
+    expect(out.unmerged).toEqual({ count: 0, paths: [] });
+    expect(await space.agent('git status --porcelain=v1 --untracked-files=all')).toBe(statusInside);
+    expect(unexpectedChanges(before, hostState(repo), { spaceIds: [space.id], codeOut: true })).toEqual([]);
+
+    const statusBefore = g(['--no-optional-locks', 'status', '--porcelain=v1', '--untracked-files=all']);
+    await space.codeOut.applyAsBranch({ repository: repo, spaceId: space.id, branch: 'from-the-space' });
+    expect(g(['rev-parse', 'refs/heads/from-the-space']).trim()).toBe(out.result);
+    expect(g(['ls-tree', 'refs/heads/from-the-space', 'tool.sh']).split(' ')[0]).toBe('100755');
+    expect(g(['--no-optional-locks', 'status', '--porcelain=v1', '--untracked-files=all'])).toBe(statusBefore);
+
+    expect(await space.codeOut.applyAsChanges({ repository: repo, spaceId: space.id })).toEqual({
+      status: 'applied', appliedPaths: 4, remembered: true, nestedRepositories: { count: 0, paths: [] }, conflicted: { count: 0, paths: [] },
+    });
+    const status = g(['--no-optional-locks', 'status', '--porcelain=v1', '--untracked-files=all']);
+    // The branch the space started from is unchanged; what came out is in the working tree, uncommitted.
+    expect(status).toContain('?? committed.txt\n');
+    expect(status).toContain('?? tool.sh\n');
+    expect(status).toContain('?? untracked-in-the-space.txt\n');
+    expect(status).toContain('MM tracked-to-edit.txt\n');
+    expect(fs.readFileSync(path.join(repo, 'tracked-to-edit.txt'), 'utf8')).toBe('one\ntwo staged\nthree unstaged\nuncommitted\n');
+    // The exec bit is lost on Windows, where git does not track it in a working tree.
+    if (!WIN) expect(fs.statSync(path.join(repo, 'tool.sh')).mode & 0o777).toBe(0o755);
+
+    // The agent works on, and a second apply brings only what is new since the first one.
+    await space.agent('printf "more\\n" > second-round.txt');
+    const second = await space.out();
+    expect(await space.codeOut.applyAsChanges({ repository: repo, spaceId: space.id })).toMatchObject({ status: 'applied', appliedPaths: 1, remembered: true });
+    expect(g(['rev-parse', `refs/openchamber/spaces/${space.id}/applied`]).trim()).toBe(second.result);
+    expect(fs.readFileSync(path.join(repo, 'second-round.txt'), 'utf8')).toBe('more\n');
+    expect(await space.codeOut.applyAsChanges({ repository: repo, spaceId: space.id })).toEqual({ status: 'nothing_to_apply' });
+
+    // The user and the agent change the same line: from then on this space is applied as a branch.
+    await space.agent('printf "more, from the agent\\n" > second-round.txt');
+    const third = await space.out();
+    fs.writeFileSync(path.join(repo, 'second-round.txt'), 'more, from the user\n');
+    const refused = await space.codeOut.applyAsChanges({ repository: repo, spaceId: space.id }).catch((error) => error);
+    expect(refused).toMatchObject({ code: 'changes_do_not_apply' });
+    expect(refused.message).toMatch(/applied as a branch/);
+    expect(fs.readFileSync(path.join(repo, 'second-round.txt'), 'utf8')).toBe('more, from the user\n');
+    const closed = await space.codeOut.applyAsChanges({ repository: repo, spaceId: space.id }).catch((error) => error);
+    expect(closed).toMatchObject({ code: 'changes_route_closed' });
+    // The branch still holds the whole work, the rounds already applied included.
+    const branch = await space.codeOut.applyAsBranch({ repository: repo, spaceId: space.id, branch: 'the-whole-work' });
+    expect(branch.commit).toBe(third.result);
+    expect(g(['ls-tree', '-r', '--name-only', 'refs/heads/the-whole-work']).split('\n')).toEqual(expect.arrayContaining(['committed.txt', 'second-round.txt', 'tool.sh']));
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+
+  it('comes out of a space whose history has not arrived, and the user\'s repository stays complete', async () => {
+    const space = await spaceWithCode('Code out, shallow', { history: false });
+    expect((await space.agent('git rev-parse --is-shallow-repository')).trim()).toBe('true');
+    await space.agent('printf "from a shallow space\\n" > shallow.txt');
+    const out = await space.out();
+    expect(space.g(['cat-file', 'blob', `${out.result}:shallow.txt`])).toBe('from a shallow space\n');
+    expect(fs.existsSync(path.join(space.repo, '.git', 'shallow'))).toBe(false);
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+
+  // TESTING.md: "Make the host run something through apply: git hooks, tags, refs outside the
+  // quarantine namespace."
+  it('runs nothing the agent planted on the host, and takes no tag and no ref but the result', async () => {
+    const space = await spaceWithCode('Code out, planted');
+    const hostMarker = path.join(host.root, `planted-ran-${space.id}`);
+    // The planted hook marks the host's own folder, and only when that folder exists, which it does on
+    // the host and never inside: a Windows path given to `touch` inside is a relative name full of
+    // backslashes, and the file it made there travelled out in the result as part of the work. Forward
+    // slashes, so the sh of Git for Windows reads the path as it is. Where it ran inside, it also marks
+    // the repository's own git folder, which is never part of a snapshot.
+    const hook = [
+      '#!/bin/sh',
+      `m="${forConfig(hostMarker)}"`,
+      '[ -d "$(dirname "$m")" ] && touch "$m"',
+      'touch "$(git rev-parse --git-dir)/planted-hook-ran"',
+      'exit 0',
+      '',
+    ].join('\n');
+    // Hooks and a filter in the space's own repository, a hooks folder and a filter in its tree, tags and refs.
+    const plant = [
+      'printf "%s" "$1" > .git/hooks/reference-transaction && chmod 755 .git/hooks/reference-transaction &&',
+      'git config filter.planted.smudge "touch .git/planted-filter-ran; cat" && git config filter.planted.clean cat &&',
+      'mkdir -p .githooks && cp .git/hooks/reference-transaction .githooks/post-checkout &&',
+      'printf "* filter=planted\\n" > .gitattributes && printf "[core]\\n\\thooksPath = .githooks\\n" > .gitconfig &&',
+      'git add --all && git commit --quiet -m planted &&',
+      'git tag planted-light && git tag -a -m annotated planted-annotated && git update-ref refs/heads/planted-branch HEAD &&',
+      'rm -f .git/planted-hook-ran',
+    ].join(' ');
+    await space.agent(plant, [hook]);
+    // Nothing of the marks landed in the project folder inside, where the snapshot would take it.
+    expect(await space.agent('git status --porcelain --untracked-files=all')).toBe('');
+    const refsBefore = space.g(['for-each-ref', '--format=%(refname)']).split('\n').filter(Boolean);
+
+    await space.out();
+    // The control: the planted hook really ran, inside, when the snapshot wrote its ref.
+    expect(await space.agent('[ -e .git/planted-hook-ran ] && echo ran; true')).toBe('ran\n');
+    expect(space.g(['for-each-ref', '--format=%(refname)']).split('\n').filter(Boolean)).toEqual([...refsBefore, `refs/openchamber/spaces/${space.id}/result`].sort());
+    await space.codeOut.applyAsBranch({ repository: space.repo, spaceId: space.id, branch: 'from-the-space' });
+    await space.codeOut.applyAsChanges({ repository: space.repo, spaceId: space.id });
+    expect(fs.existsSync(path.join(space.repo, '.githooks', 'post-checkout'))).toBe(true);
+    expect(fs.existsSync(hostMarker)).toBe(false);
+    // The control, on the host: the planted hook that came out is a working hook that marks the host
+    // when git is told to use it, so its silence above is the host not running it, not a dud.
+    const probe = spawnSync('git', ['-C', space.repo, '-c', 'core.hooksPath=.githooks', 'checkout', '--quiet', '-b', 'probe'], { env: host.environment, encoding: 'utf8', windowsHide: true });
+    expect(probe.status, probe.stderr).toBe(0);
+    expect(fs.existsSync(hostMarker)).toBe(true);
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+
+  // A hook of the agent's can reach its parent git's stdout through /proc and write a commit id of its
+  // own there, then move the result ref to that commit. The snapshot sends everything it runs to
+  // /dev/null, so what the host reads first is still the snapshot's own id, and the moved ref is
+  // refused rather than taken. The verifier who found this showed that removing the redirect makes
+  // the host take the planted commit.
+  it('does not let a hook print into the report through its parent\'s stdout', async () => {
+    const space = await spaceWithCode('Code out, stdout hook');
+    const planted = (await space.agent([
+      'blob=$(printf "planted\\n" | git hash-object -w --stdin) &&',
+      'tree=$(printf "100644 blob %s\\tplanted.txt\\n" "$blob" | git mktree) &&',
+      'git commit-tree "$tree" -p HEAD -m planted',
+    ].join(' '))).trim();
+    const hook = [
+      '#!/bin/sh',
+      '[ "$1" = committed ] || exit 0',
+      'marker="$(git rev-parse --git-dir)/stdout-hook-ran"',
+      '[ -e "$marker" ] && exit 0',
+      ': > "$marker"',
+      `printf '%s\\n' ${planted} > /proc/$PPID/fd/1`,
+      `( sleep 1; git update-ref refs/openchamber/result ${planted} ) &`,
+      'exit 0',
+      '',
+    ].join('\n');
+    await space.agent('printf "%s" "$1" > .git/hooks/reference-transaction && chmod 755 .git/hooks/reference-transaction && printf "work\\n" > work.txt', [hook]);
+    const before = hostState(space.repo);
+    const failure = await space.out().catch((error) => error);
+    // The control: the hook ran on the snapshot's own ref write.
+    expect(await space.agent('[ -e .git/stdout-hook-ran ] && echo ran; true')).toBe('ran\n');
+    expect(failure).toMatchObject({ code: 'result_ref_missing', details: { step: 'fetch into the quarantine' } });
+    expect(unexpectedChanges(before, hostState(space.repo), { spaceIds: [] })).toEqual([]);
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+
+  // TESTING.md: "Get tree paths such as `.git/hooks/x`, `.GIT`, `..`, or `a/../../x` past the host's
+  // object checks." Each tree is built inside with the space's own git, past its path checks.
+  it('refuses hostile tree names at the quarantine, and brings the same kind of tree out with an ordinary name', async () => {
+    const space = await spaceWithCode('Code out, hostile trees');
+    const planted = [
+      'blob=$(printf "planted\\n" | git hash-object -w --stdin) &&',
+      'entry() { /usr/local/bin/node -e "process.stdout.write(Buffer.concat([Buffer.from(process.argv[1] + \' \' + process.argv[2] + String.fromCharCode(0)), Buffer.from(process.argv[3], \'hex\')]))" "$1" "$2" "$3" | git hash-object -t tree --literally -w --stdin; } &&',
+      'if [ "$1" = ".git/hooks/x" ]; then t=$(entry 100644 x $blob) && t=$(entry 40000 hooks $t) && tree=$(entry 40000 .git $t); else tree=$(entry 100644 "$1" $blob); fi &&',
+      'git update-ref HEAD $(git commit-tree $tree -p HEAD -m planted)',
+    ].join(' ');
+    const head = (await space.agent('git rev-parse HEAD')).trim();
+    const before = hostState(space.repo);
+    for (const name of ['.git', '.GIT', 'git~1', '.git ', '..', 'a/../../x', '.git/hooks/x']) {
+      await space.agent(planted, [name]);
+      const failure = await space.out().catch((error) => error);
+      expect(failure, name).toMatchObject({ code: 'code_out_failed', details: { step: 'fetch into the quarantine' } });
+      expect(unexpectedChanges(before, hostState(space.repo), { spaceIds: [] }), name).toEqual([]);
+      await space.agent('git update-ref HEAD "$1"', [head]);
+    }
+    // The control: built the same way, an ordinary name comes out. The planted commit is the parent
+    // of the result, whose own tree is the working tree the snapshot took.
+    await space.agent(planted, ['ordinary.txt']);
+    const out = await space.out();
+    expect(space.g(['cat-file', 'blob', `${out.result}^:ordinary.txt`])).toBe('planted\n');
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+
+  // TESTING.md: "write through a symlink or into `.git/` when applied as a patch". `.git/` cannot come
+  // out at all, see above; a folder of the space where the user has a link is refused at apply.
+  it('writes nothing through a link the user has where the space made a folder, and brings a link to outside in as a link only', async () => {
+    const space = await spaceWithCode('Code out, links');
+    const outside = path.join(host.root, `outside-${space.id}`);
+    fs.mkdirSync(outside);
+    await space.agent('mkdir -p cache && printf "through the link\\n" > cache/planted.txt && ln -s /etc/passwd link-outside');
+    const out = await space.out();
+    // The control: the result does hold the file and the link.
+    expect(space.g(['cat-file', 'blob', `${out.result}:cache/planted.txt`])).toBe('through the link\n');
+    expect(space.g(['ls-tree', out.result, 'link-outside']).split(' ')[0]).toBe('120000');
+    fs.appendFileSync(path.join(space.repo, '.git', 'info', 'exclude'), 'cache\n');
+    fs.symlinkSync(outside, path.join(space.repo, 'cache'), WIN ? 'junction' : 'dir');
+    const before = hostState(space.repo);
+    // Refused by the host's own look at the folders on the way, not by git: Git for Windows writes
+    // through a junction.
+    await expect(space.codeOut.applyAsChanges({ repository: space.repo, spaceId: space.id })).rejects.toMatchObject({ code: 'changes_blocked_by_link', details: { path: 'cache' } });
+    expect(fs.readdirSync(outside)).toEqual([]);
+    // The one thing a refused apply writes: from now on this space is applied as a branch.
+    expect(unexpectedChanges(before, hostState(space.repo), { spaceIds: [] })).toEqual([`.git/refs/openchamber/spaces/${space.id}/changes-closed`]);
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+
+  // TESTING.md: "Hang the result fetch forever ... The host's timeout ... must end it, and the process
+  // left inside the space must be cleaned up."
+  it('ends a fetch that the space never answers at the host timeout, with no host process left and nothing inside after its limit', async () => {
+    const space = await spaceWithCode('Code out, hanging');
+    await space.agent('printf "work\\n" > work.txt');
+    expect((await inside(space.id, PLANT_HANGING_PACK_HOOK)).code).toBe(0);
+    const before = hostState(space.repo);
+    const started = Date.now();
+    const failure = await space.out({ timeoutMs: timing.hostTimeoutMs, innerMarginSeconds: timing.innerMarginSeconds }).catch((error) => error);
+    expect(failure).toMatchObject({ code: 'code_out_failed', details: { step: 'fetch into the quarantine', cause: 'command_timeout' } });
+    // The control: the planted hook really held the fetch inside, and still does.
+    expect(Number((await inside(space.id, COUNT_SLEEPERS)).stdout)).toBeGreaterThan(0);
+    expect(await hostProcessesGone(spaceResourceName(space.id, 'space'), started + timing.innerLimitMs)).toBe(true);
+    const bound = started + timing.innerLimitMs + (DOCKER_CALLS_BEFORE_FETCH + 2) * timing.roundTripMs + 3000;
+    let emptied = false;
+    while (!emptied && Date.now() <= bound + 500) {
+      emptied = (await inside(space.id, COUNT_SLEEPERS)).stdout === '0\n';
+      if (!emptied) await pause(500);
+    }
+    expect(emptied, 'the fetch inside outlived the limit inside the space').toBe(true);
+    expect(unexpectedChanges(before, hostState(space.repo), { spaceIds: [] })).toEqual([]);
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+
+  // TESTING.md: "... or fill the host's disk with it. The host's ... size cap must end" it. A space
+  // that sends without end is stopped by the cap long before the deadline, which is what shows that
+  // the cap watches the transfer while it runs, not only once it is over.
+  it('stops a space that sends without end at the size cap, long before the deadline, with nothing left on the host or inside', async () => {
+    const space = await spaceWithCode('Code out, endless');
+    await space.agent('printf "work\\n" > work.txt');
+    expect((await inside(space.id, PLANT_ENDLESS_PACK_HOOK, [ENDLESS_PACK])).code).toBe(0);
+    const before = hostState(space.repo);
+    const started = Date.now();
+    const failure = await space.out({ maxTransferBytes: 4 * 1024 * 1024, timeoutMs: 90_000 }).catch((error) => error);
+    expect(failure).toMatchObject({ code: 'result_transfer_too_large', details: { step: 'fetch into the quarantine' } });
+    expect(Date.now() - started).toBeLessThan(60_000);
+    expect(await hostProcessesGone(spaceResourceName(space.id, 'space'), started + 95_000)).toBe(true);
+    expect(unexpectedChanges(before, hostState(space.repo), { spaceIds: [] })).toEqual([]);
+    // Nothing of it runs inside once the limit there has passed.
+    let emptied = false;
+    while (!emptied && Date.now() <= started + 100_000) {
+      emptied = (await inside(space.id, COUNT_ENDLESS)).stdout === '0\n';
+      if (!emptied) await pause(500);
+    }
+    expect(emptied).toBe(true);
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+
+  // TESTING.md: "... or fill the host's disk with it. The host's ... size cap must end" it.
+  it('stops a fetch that passes the size cap, with no host process left, and brings the same work out with room for it', async () => {
+    const space = await spaceWithCode('Code out, large');
+    await space.agent('head -c 16777216 /dev/urandom > large.bin');
+    const before = hostState(space.repo);
+    const failure = await space.out({ maxTransferBytes: 4 * 1024 * 1024, timeoutMs: 120_000 }).catch((error) => error);
+    expect(failure).toMatchObject({ code: 'result_transfer_too_large', details: { step: 'fetch into the quarantine' } });
+    expect(await hostProcessesGone(spaceResourceName(space.id, 'space'), Date.now() + 60_000)).toBe(true);
+    expect(unexpectedChanges(before, hostState(space.repo), { spaceIds: [] })).toEqual([]);
+    // Nothing of the fetch runs inside once the limit there has passed.
+    const bound = Date.now() + 125_000;
+    let emptied = false;
+    while (!emptied && Date.now() <= bound) {
+      emptied = (await inside(space.id, COUNT_UPLOADERS)).stdout === '0\n';
+      if (!emptied) await pause(500);
+    }
+    expect(emptied).toBe(true);
+    // The control: with the default cap the same result comes out.
+    const out = await space.out();
+    expect(out.changedBytes).toBe(16 * 1024 * 1024);
+    await space.remove();
+  }, CREATE_TIMEOUT_MS);
+});

package/server/lib/spaces/places/contract-suite.js

@@ -1,6 +1,8 @@
 // The contract every place must pass. Stage 8 to 10 places run this same suite.
 // `setup` resolves `{ place, dispose }`. `dispose` cleans up and may assert that nothing is left.
 
+import http from 'node:http';
+
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 import { createSpaceId, hashProjectDirectory } from '../labels.js';
@@ -23,6 +25,17 @@ export function runPlaceContractSuite(title, { enabled = true, setup }) {
 
     const listed = async () => (await place.list()).find((space) => space.id === spec.id);
 
+    /** One HTTP request over a channel that `connect` gave, as the dispatcher's agent makes it. */
+    const requestOver = (stream, path) => new Promise((resolve, reject) => {
+      const request = http.request({ path, headers: { host: '127.0.0.1' }, createConnection: () => stream }, (response) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => resolve({ status: response.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+      });
+      request.on('error', reject);
+      request.end();
+    });
+
     beforeAll(async () => {
       ({ place, dispose } = await setup());
     });
@@ -111,11 +124,29 @@ export function runPlaceContractSuite(title, { enabled = true, setup }) {
       expect(hostname.stdout).not.toBe((await place.exec(spec.id, ['cat', '/etc/hostname'], { target: 'gatekeeper' })).stdout);
     });
 
+    // Added in stage 4a. `connect` is the dispatcher's way to the server inside: a stream that
+    // carries HTTP to it and nothing else. It must reach the server of this space, and it
+    // must end cleanly when the caller lets go, so an agent can hold and reuse it.
+    it('connects to the server inside the space', async () => {
+      const stream = await place.connect(spec.id);
+      const answer = await requestOver(stream, '/health');
+      expect(answer.status).toBe(200);
+      expect(JSON.parse(answer.body)).toMatchObject({ isOpenCodeReady: true });
+      const closed = new Promise((resolve) => stream.once('close', resolve));
+      stream.destroy();
+      await closed;
+    });
+
     it('stops the space and lists it as exited', async () => {
       await place.stop(spec.id);
       expect(await listed()).toMatchObject({ state: 'exited' });
     });
 
+    // Added in stage 4a, for the same reason as the argv: a stopped space has no server to reach.
+    it('connects to no stopped space', async () => {
+      await expect(place.connect(spec.id)).rejects.toMatchObject({ code: 'space_not_running' });
+    });
+
     // Added in stage 3a. git starts the argv itself, and a stopped container answers it only with
     // the runtime's own words, so a place refuses a stopped space here with a code of its own.
     it('hands out no argv for a stopped space', async () => {
@@ -149,6 +180,11 @@ export function runPlaceContractSuite(title, { enabled = true, setup }) {
       await expect(place.execArgv(spec.id)).rejects.toThrow();
     });
 
+    // Added in stage 4a, with the same reasoning as the argv.
+    it('connects to no space that is gone', async () => {
+      await expect(place.connect(spec.id)).rejects.toThrow();
+    });
+
     it('treats removing a missing space as done', async () => {
       expect(await place.remove(spec.id)).toEqual({ removed: [], failed: [] });
     });