644ac22 · 080845b · 60150e3
@@ -0,0 +1,35 @@
# The crew's shell
An agent's shell runs inside Claude Code's sandbox (`src/crew/sandbox.ts` is
the policy, `src/crew/claude.ts` the settings): the network is the forge and
the package registry, writes stay in the clone and the run's own `tmpDir`,
and the machine's temp directory, the forge's data and the operator's
credentials are unreadable. No command runs outside it on request.
## Running this repository's tests inside it
On Linux the sandbox refuses the bind of a unix socket, and the forge's
internal listener (the git hooks' door) is one. Claude Code can only allow
unix sockets all or none, which would open every socket the machine has, so
the boundary is kept instead: a run's environment carries
`FORGE_TEST_SOCKET=port`, and the forge listens on a loopback port
(`tcp:127.0.0.1:<port>`, `src/git/hook-address.ts`) where it would use a
socket. Loopback ports were already allowed (`allowLocalBinding`), and
`localhost` outside the sandbox stays unreachable.
What an agent can run: the type check and `bun test` over `test/`, with no
      
        sentinelcrew
        1mo ago
        outdated
      
      Not accurate: the two hardening suites are not the only socket-bound ones. The egress proxy (startEgress) and the env-data/app sockets bind unix sockets too, and their suites fail under FORGE_TEST_SOCKET=port.
    
failures. A cell reaches its egress proxy through a unix socket, which cannot
be put on a port, so in port mode `cellsAvailable()` answers no
(`FORGE_TEST_SOCKET=port: no unix sockets`) and deploys and checks run
uncontained, as with `FORGE_CELLS=off`. The suites that are about sockets and
cells themselves skip in port mode and show as skipped: stale-socket recovery
and two forges on one data directory (`test/hardening.test.ts`), the egress
proxy and the cell-limit and probe suites (`test/contain.test.ts`), and the
socket-copy test in `test/apps-adversarial.test.ts`. The forge's check runs
them on every push and sends the log back.
Not proven from inside a sandbox: that a sandboxed shell reaches its own server
and is still refused `localhost` outside the sandbox and every `denyRead` path.
Nesting a sandbox is not possible there, so `test/crew-sandbox.test.ts` checks
the settings that enforce it (`allowLocalBinding` on, `allowAllUnixSockets` off,
the `denyRead` list) and not the boundary itself.
@@ -7,6 +7,7 @@
import type { MailConfig, Mailer } from "./kernel/mail.ts";
import type { Database } from "bun:sqlite";
import type { Decider } from "./crew/decide.ts";
import { randomBytes } from "node:crypto";
import { mkdirSync } from "node:fs";
import { join, resolve } from "node:path";
import { migrations } from "./core/schema.ts";
@@ -133,6 +134,10 @@
export interface App {
  readonly log: Log;
  readonly reposRoot: string;
  readonly socketPath: string;
  /** Where the internal listener answers: `socketPath`, or a loopback port (`git/hook-address.ts`). */
  readonly hookAddress: { current: string };
  /** Per-boot secret every internal request must carry (`FORGE_HOOK_SECRET` in a hook's env). */
  readonly hookSecret: string;
  close(): void;
}
@@ -144,6 +149,7 @@
export function createApp(config: ForgeConfig): App {
  const dataDir = resolve(config.dataDir);
  const reposRoot = join(dataDir, "repos");
  mkdirSync(reposRoot, { recursive: true });
  const socketPath = join(dataDir, `forge-${id()}.sock`);
  const db = openDb(join(dataDir, "forge.db"), migrations);
  // Hand-installed new-account guards become the `guard_new_accounts`
@@ -168,7 +174,9 @@
export function createApp(config: ForgeConfig): App {
    reposRoot,
    // This process's own: two forges share a data directory for the length
    // of a release, and each spawns git with its own socket in the env.
    socketPath: join(dataDir, `forge-${id()}.sock`),
    socketPath,
    hookAddress: { current: socketPath },
    hookSecret: randomBytes(32).toString("hex"),
    close: () => {
      // The pooled `cat-file` readers for this forge's repos are processes,
      // and processes outlive a closed database unless somebody says
@@ -33,6 +33,7 @@
import {
} from "node:fs";
import { availableParallelism, tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { portInsteadOfSocket } from "../git/hook-address.ts";
import { relay, startEgress, type Egress } from "./egress.ts";
export interface Limits {
@@ -154,6 +155,10 @@
export function cellsAvailable(): Promise<
async function probe(): Promise<{ ok: true } | { ok: false; reason: string }> {
  if (process.env["FORGE_CELLS"] === "off")
    return { ok: false, reason: "FORGE_CELLS=off" };
  // A cell reaches its proxy through a unix socket; a sandbox that put the
  // forge on loopback ports (a crew run's `bun test`) cannot bind one.
  if (portInsteadOfSocket())
    return { ok: false, reason: "FORGE_TEST_SOCKET=port: no unix sockets" };
  if (process.platform !== "linux")
    return { ok: false, reason: `no cells on ${process.platform}` };
  for (const tool of ["bwrap", "socat"])
@@ -120,7 +120,7 @@
export function systemPrompt(input: BriefInput): string {
  }
  lines.push(
    "",
    "Your shell is sandboxed: writes stay in the clone, the network is the forge and the package registry, and you cannot signal processes you started in an earlier command. If you start the app to try it, do it inside one command that also stops it (`bun run src/server.ts & pid=$!; sleep 2; curl …; kill $pid`). Anything left running is stopped by the forge when you finish; it is not a failure, but it is noise.",
    "Your shell is sandboxed: writes stay in the clone, the network is the forge and the package registry, and you cannot signal processes you started in an earlier command. If you start the app to try it, do it inside one command that also stops it (`bun run src/server.ts & pid=$!; sleep 2; curl …; kill $pid`). Anything left running is stopped by the forge when you finish; it is not a failure, but it is noise. Never leave the sandbox: it cannot be asked to. Inside it you can run the type check and `bun test` (FORGE_TEST_SOCKET=port is already set, so servers listen on loopback ports in place of unix sockets). The suites about unix sockets and cells themselves (stale-socket recovery, the egress proxy, cell limits) are skipped in that mode and named as skipped; the forge's check runs them on every push. Run what covers your change; the forge runs the whole check on your push and sends you its log.",
      
        sentinelcrew
        1mo ago
        outdated
      
      This says bun test runs inside the sandbox. At this head, in port mode, apps-adversarial, apps-token and contain fail with Failed to listen at …/out.sock (src/apps/egress.ts) and on app sockets. Either make them run or name exactly what the check runs instead. An agent told everything is green that then sees 24 red tests will chase them.
    
    "",
    "Work carefully and finish. If the task is unclear, impossible, or not something you should do, do not guess: make your last message start with `DECLINED:` followed by exactly why. Nothing is pushed then, and a person reads it.",
  );
@@ -921,6 +921,9 @@
async function work(
      env["CLAUDE_CODE_TMPDIR"] = runTmp;
      env["TMPDIR"] = runTmp;
    }
    // The sandbox refuses a unix socket's bind; the forge's own servers take
    // a loopback port instead (`git/hook-address.ts`), so `bun test` runs.
    if (sandbox.enforced) env["FORGE_TEST_SOCKET"] = "port";
      
        sentinelcrew
        1mo ago
        
      
      No test would fail without this line. Assert that a sandboxed run's environment carries FORGE_TEST_SOCKET=port and that an unsandboxed run's does not.
    
    // One deadline for the run, whatever it takes to get there: the token
    // dies ten minutes after it, so a second invocation gets what is left.
    const deadline = Date.now() + options.runTimeoutMs;
@@ -0,0 +1,42 @@
/**
 * Where the forge's internal listener answers: a unix socket path, or
 * `tcp:<host>:<port>` on loopback. Production uses the socket. A sandbox
 * that refuses the bind (an agent running `bun test`) sets
 * `FORGE_TEST_SOCKET=port` and the listener takes a loopback port instead,
 * so no unix socket is ever exposed to the sandbox to get there.
 */
const TCP = /^tcp:(127\.0\.0\.1):([0-9]{1,5})$/;
/** The address of a loopback listener. */
export function tcpAddress(port: number): string {
  return `tcp:127.0.0.1:${port}`;
}
/** Whether the environment asks for a loopback port in place of a unix socket. */
export function portInsteadOfSocket(
  env: Record<string, string | undefined> = process.env,
): boolean {
  return env["FORGE_TEST_SOCKET"] === "port";
}
/** The URL and fetch option that reach `path` at `address`. */
export function internalRequest(
  address: string,
  path: string,
): { url: string; init: { unix?: string } } {
  const tcp = TCP.exec(address);
  if (tcp !== null)
    return { url: `http://${tcp[1]}:${tcp[2]}${path}`, init: {} };
  return { url: `http://forge${path}`, init: { unix: address } };
}
/** `fetch` against the internal listener, wherever it is. */
export function fetchInternal(
  address: string,
  path: string,
  init: RequestInit = {},
): Promise<Response> {
  const target = internalRequest(address, path);
  return fetch(target.url, { ...init, ...target.init } as RequestInit);
}
@@ -24,12 +24,26 @@
export interface HookRequest {
  readonly gitEnv: Record<string, string>;
}
/** The header that carries the per-boot secret to the internal listener. */
export const HOOK_SECRET_HEADER = "x-forge-hook-secret";
export const FORWARDED_GIT_ENV = [
  "GIT_OBJECT_DIRECTORY",
  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
  "GIT_QUARANTINE_PATH",
] as const;
/** Only the quarantine variables a hook may forward reach git. */
export function forwardedGitEnv(env: unknown): Record<string, string> {
  const kept: Record<string, string> = {};
  if (typeof env !== "object" || env === null) return kept;
  for (const name of FORWARDED_GIT_ENV) {
    const value = (env as Record<string, unknown>)[name];
    if (typeof value === "string") kept[name] = value;
  }
  return kept;
}
export function parseHookStdin(text: string): RefUpdate[] {
  const updates: RefUpdate[] = [];
  for (const line of text.split("\n")) {
@@ -10,7 +10,12 @@
import { chmod } from "node:fs/promises";
import { join } from "node:path";
import { FORWARDED_GIT_ENV, parseHookStdin } from "./hook-protocol.ts";
import { fetchInternal } from "./hook-address.ts";
import {
  FORWARDED_GIT_ENV,
  HOOK_SECRET_HEADER,
  parseHookStdin,
} from "./hook-protocol.ts";
const HOOK_NAMES = ["pre-receive", "post-receive"] as const;
type HookName = (typeof HOOK_NAMES)[number];
@@ -52,6 +57,7 @@
function selfInvocation(): { runtime: string; entry: string | undefined } {
/** Env for a receive-pack spawn so its hooks can reach back into the forge. */
export function hookEnv(input: {
  socketPath: string;
  secret: string;
  repoId: string;
  actorId: string;
}): Record<string, string> {
@@ -59,6 +65,7 @@
export function hookEnv(input: {
  const env: Record<string, string> = {
    FORGE_RUNTIME: self.runtime,
    FORGE_SOCKET: input.socketPath,
    FORGE_HOOK_SECRET: input.secret,
    FORGE_REPO_ID: input.repoId,
    FORGE_ACTOR_ID: input.actorId,
  };
@@ -97,10 +104,12 @@
export async function runHookClient(hook: HookName): Promise<never> {
  }
  try {
    const response = await fetch("http://forge/internal/hook", {
      unix: socket,
    const response = await fetchInternal(socket, "/internal/hook", {
      method: "POST",
      headers: { "content-type": "application/json" },
      headers: {
        "content-type": "application/json",
        [HOOK_SECRET_HEADER]: process.env.FORGE_HOOK_SECRET ?? "",
      },
      // A forge that has stopped answering must not become a push that never
      // returns. Without a deadline this relay waits forever, and the git
      // process holding the repo's ref lock waits with it — one wedged forge
@@ -53,6 +53,11 @@
import {
  serviceRpc,
  type GitService,
} from "../git/smart-http.ts";
import { timingSafeEqual } from "node:crypto";
import {
  forwardedGitEnv,
  HOOK_SECRET_HEADER,
} from "../git/hook-protocol.ts";
import { lstat, readdir, rm } from "node:fs/promises";
import { rmSync } from "node:fs";
import { join } from "node:path";
@@ -399,6 +404,7 @@
import {
  resolveAppHost,
} from "../apps/proxy.ts";
import { portInsteadOfSocket, tcpAddress } from "../git/hook-address.ts";
import { closeHostedChildren, resolveHostedChild } from "../spawn/host.ts";
import { getVerifiedDomain } from "../core/domains.ts";
@@ -812,7 +818,8 @@
export function buildRouter(): Router<Handler> {
    withGitAccess(ctx, "git-receive-pack", (dir, repoId) =>
      serviceRpc(dir, "git-receive-pack", ctx.request, {
        env: hookEnv({
          socketPath: ctx.app.socketPath,
          socketPath: ctx.app.hookAddress.current,
          secret: ctx.app.hookSecret,
          repoId,
          actorId: ctx.auth.user?.id ?? "",
        }),
@@ -1379,8 +1386,16 @@
const fromStored = (stored: StoredResponse, replay: boolean): Response =>
// ---- the internal server (unix socket, hooks only) ----
/** Whether the request carries this boot's hook secret (constant-time). */
function hookCallerAllowed(app: App, request: Request): boolean {
  const given = Buffer.from(request.headers.get(HOOK_SECRET_HEADER) ?? "");
  const want = Buffer.from(app.hookSecret);
  return given.length === want.length && timingSafeEqual(given, want);
}
async function handleHook(app: App, request: Request): Promise<Response> {
  const input = (await request.json()) as HookRequest;
  const parsed = (await request.json()) as HookRequest;
      
        sentinelcrew
        1mo ago
        outdated
      
      Good hardening. It is the hook protocol's concept, though: move it to src/git/hook-protocol.ts next to FORWARDED_GIT_ENV rather than exporting a helper from the server module.
    
      
        sentinelcrew
        1mo ago
        
      
      The secret gates this, so it is low. The body is still cast rather than checked, though: a null or non-object body throws here and comes back as a 500. A shape check returning 400 would match the validate-at-the-boundary rule now that this listener can be a TCP port.
    
  const input: HookRequest = { ...parsed, gitEnv: forwardedGitEnv(parsed.gitEnv) };
  const repo = getRepoById(app.db, input.repoId);
  if (!repo) return new Response("unknown repository", { status: 400 });
@@ -1716,9 +1731,15 @@
export async function serve(app: App): Promise<Servers> {
    },
  });
  const onPort = portInsteadOfSocket();
  const internal = Bun.serve({
    unix: app.socketPath,
    ...(onPort ? { hostname: "127.0.0.1", port: 0 } : { unix: app.socketPath }),
    fetch(request) {
      // The socket's file mode used to be the only door check; a loopback
      // port has none, so every internal request proves the boot secret.
      if (!hookCallerAllowed(app, request)) {
        return new Response("forbidden", { status: 403 });
      }
      const url = new URL(request.url);
      if (request.method === "POST" && url.pathname === "/internal/hook") {
        return handleHook(app, request);
@@ -1727,6 +1748,7 @@
export async function serve(app: App): Promise<Servers> {
    },
  });
  if (onPort) app.hookAddress.current = tcpAddress(internal.port ?? 0);
  const port = web.port ?? 0;
  return {
    url: `http://localhost:${port}`,
@@ -274,7 +274,8 @@
async function serveGitCommand(
  const dir = repoDir(forge.reposRoot, repo.ownerName, repo.name);
  const env: Record<string, string> = write
    ? hookEnv({
        socketPath: forge.socketPath,
        socketPath: forge.hookAddress.current,
        secret: forge.hookSecret,
        repoId: repo.id,
        actorId: user?.id ?? "",
      })
@@ -10,6 +10,7 @@
import {
  type Notifier,
} from "../src/crew/notify.ts";
import { queueAgentRun } from "../src/crew/dispatch.ts";
import { fetchInternal } from "../src/git/hook-address.ts";
import { addComment, openIssue } from "../src/actions/issues.ts";
import { createRepo } from "../src/actions/repos.ts";
import { signUp } from "../src/actions/users.ts";
@@ -343,9 +344,9 @@
describe("accounts: the owner sees, suspends and removes", () => {
    // What git's pre-receive hook asks the forge once the pack is in: the
    // ref update, from the account that pushed it.
    const ask = () =>
      fetch("http://forge/internal/hook", {
        unix: app.socketPath,
      fetchInternal(app.hookAddress.current, "/internal/hook", {
        method: "POST",
        headers: { "x-forge-hook-secret": app.hookSecret },
        body: JSON.stringify({
          hook: "pre-receive",
          repoId: made.value.id,
@@ -69,6 +69,9 @@
import {
} from "../src/runs/log.ts";
import { grantedCookie } from "./helpers/identity.ts";
import { gitClientEnv } from "./helpers/git-client.ts";
import { portInsteadOfSocket } from "../src/git/hook-address.ts";
const testBySocket = portInsteadOfSocket() ? test.skip : test;
const DOMAIN = "apps.test";
@@ -634,7 +637,8 @@
describe("ensureEnvData path safety", () => {
    );
  });
  test("a copy of an app's data leaves its sockets behind", async () => {
  // Binds a unix socket itself; the check runs it where a sandbox refuses.
  testBySocket("a copy of an app's data leaves its sockets behind", async () => {
    // An app that keeps a socket in its data — a forge does — must not
    // make a preview impossible, let alone take the forge down with it.
    const source = join(dataDir, "with-socket");
@@ -47,6 +47,11 @@
import type { Repo } from "../src/core/repos.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { readRunLog } from "../src/runs/log.ts";
import { missing } from "./helpers/tools.ts";
import { portInsteadOfSocket } from "../src/git/hook-address.ts";
// Cells and their egress proxy bind unix sockets, which a sandbox refuses
// (FORGE_TEST_SOCKET=port); these run in the forge's check instead.
const bySocket = portInsteadOfSocket() ? describe.skip : describe;
describe("egress: what a cell may reach", () => {
  test("a declared name matches exactly, or below a *. wildcard, on 80 and 443", () => {
@@ -145,7 +150,7 @@
describe("egress: what a cell may reach", () => {
  });
});
describe("egress: the proxy forwards what is allowed, byte for byte, and refuses the rest", () => {
bySocket("egress: the proxy forwards what is allowed, byte for byte, and refuses the rest", () => {
  let dir: string;
  let upstream: ReturnType<typeof Bun.serve>;
  let socket: string;
@@ -253,7 +258,7 @@
describe("egress: the proxy forwards what is allowed, byte for byte, and refuses
  });
});
describe("egress, reported: an undeclared public host goes through and is counted; a private one never does", () => {
bySocket("egress, reported: an undeclared public host goes through and is counted; a private one never does", () => {
  let dir: string;
  let socket: string;
  let egress: { close(): void };
@@ -473,7 +478,8 @@
describe("cells hide every mount that may carry a secret", () => {
const noCells =
  process.env["FORGE_CELLS"] === "off" ||
  missing("bwrap", "socat") ||
  process.platform !== "linux";
  process.platform !== "linux" ||
  portInsteadOfSocket();
/** What the probe tries, from inside a deploy or a check. */
function probeSource(targets: {
@@ -20,6 +20,18 @@
import { createRepo } from "../src/actions/repos.ts";
import { createRun, getRun, noteRunProgress } from "../src/core/runs.ts";
import { createUser } from "../src/core/users.ts";
import { sandboxLine } from "../src/web/studio/sandbox.ts";
import {
  fetchInternal,
  internalRequest,
  tcpAddress,
} from "../src/git/hook-address.ts";
import { addToCrew, createAgent } from "../src/actions/crew.ts";
import { assignIssue, openIssue } from "../src/actions/issues.ts";
import { commitToBranch } from "../src/actions/repos.ts";
import { startCrew } from "../src/crew/dispatch.ts";
import { listRuns } from "../src/core/runs.ts";
import { serve } from "../src/http/server.ts";
import { readFileSync } from "node:fs";
import { claudeSettings } from "../src/crew/claude.ts";
import {
  dataInTemp,
@@ -225,3 +237,187 @@
describe("the shell sandbox denies the whole data directory but the agent's own
    expect(denied(join(dataDir, "crew/quill"), policy().denyRead)).toBe(true);
  });
});
describe("a sandboxed run can run this repository's tests (#1107)", () => {
      
        sentinelcrew
        1mo ago
        
      
      The issue asks this file to prove that a sandboxed run reaches its own server and is still refused localhost outside the sandbox and every denyRead path. These tests check settings keys and the env variable, not the boundary. Add the proof, or state plainly why it cannot run here and open the follow-up issue.
    
  test("the settings keep the boundary: no unix socket is let through", () => {
    const settings = claudeSettings(
      sandboxPolicy({
      
        sentinelcrew
        1mo ago
        outdated
      
      A 404 on /internal/nothing shows the listener is bound, not that the hook works or is gated. Assert that an unauthenticated /internal/hook gets a 403 and that one carrying the secret is answered.
    
        dataDir: "/tmp/forge-sandbox-test",
        agentName: "scout",
        urls: [],
        runId: "01abcdefghijklmnop",
      }),
    ).sandbox as { network: Record<string, unknown> };
    expect(settings.network["allowAllUnixSockets"]).toBeUndefined();
    expect(settings.network["allowUnixSockets"]).toBeUndefined();
  });
  test("in port mode no cell is offered: its proxy socket cannot be bound", async () => {
    const script = `import { cellsAvailable } from "./src/apps/contain.ts"; console.log(JSON.stringify(await cellsAvailable()))`;
    const run = Bun.spawnSync([process.execPath, "-e", script], {
      env: { ...process.env, FORGE_TEST_SOCKET: "port", FORGE_CELLS: "" },
      cwd: join(import.meta.dir, ".."),
    });
    const answer = JSON.parse(run.stdout.toString());
    expect(answer.ok).toBe(false);
    expect(answer.reason).toContain("FORGE_TEST_SOCKET=port");
  });
  test("the internal listener takes a loopback port where the socket cannot be bound, and gates it", async () => {
    const was = process.env["FORGE_TEST_SOCKET"];
    process.env["FORGE_TEST_SOCKET"] = "port";
    const dataDir = await mkdtemp(join(tmpdir(), "forge-sandbox-port-"));
    const app = createApp({ dataDir, port: 0 });
    const { serve } = await import("../src/http/server.ts");
      
        sentinelcrew
        1mo ago
        
      
      serve is already imported at the top of the file. The dynamic import here is redundant, and the same goes for the await import of forwardedGitEnv and systemPrompt below. The file also imports from ../src/actions/repos.ts and ../src/core/runs.ts twice; fold those into the existing import lines.
    
    const servers = await serve(app);
    try {
      const address = app.hookAddress.current;
      expect(address).toMatch(/^tcp:127\.0\.0\.1:\d+$/);
      expect(existsSync(app.socketPath)).toBe(false);
      const post = (headers: Record<string, string>) =>
        fetchInternal(address, "/internal/hook", {
          method: "POST",
          headers,
          body: JSON.stringify({ hook: "pre-receive", repoId: "nope", actorId: "", updates: [], gitEnv: {} }),
        });
      expect((await post({})).status).toBe(403);
      expect((await post({ "x-forge-hook-secret": "wrong" })).status).toBe(403);
      expect((await fetchInternal(address, "/internal/nothing")).status).toBe(403);
      // With the secret the hook is answered (an unknown repository: 400).
      const ok = await post({ "x-forge-hook-secret": app.hookSecret });
      expect(ok.status).toBe(400);
      expect(await ok.text()).toBe("unknown repository");
    } finally {
      servers.stop();
      app.close();
      await rm(dataDir, { recursive: true, force: true });
      if (was === undefined) delete process.env["FORGE_TEST_SOCKET"];
      else process.env["FORGE_TEST_SOCKET"] = was;
    }
  });
  test("a hook's git environment is cut to the quarantine variables", async () => {
    const { forwardedGitEnv } = await import("../src/git/hook-protocol.ts");
    expect(
      forwardedGitEnv({
        GIT_OBJECT_DIRECTORY: "/q",
        GIT_DIR: "/etc",
        GIT_CONFIG_COUNT: "1",
        GIT_QUARANTINE_PATH: 5,
      }),
    ).toEqual({ GIT_OBJECT_DIRECTORY: "/q" });
    expect(forwardedGitEnv(null)).toEqual({});
  });
  test("addresses are a socket path or loopback only", () => {
    expect(internalRequest("/d/forge-x.sock", "/p")).toEqual({
      url: "http://forge/p",
      init: { unix: "/d/forge-x.sock" },
    });
    expect(internalRequest(tcpAddress(4321), "/p").url).toBe(
      "http://127.0.0.1:4321/p",
    );
    // Not loopback: treated as a path, never as a host to dial.
    expect(internalRequest("tcp:10.0.0.1:80", "/p").url).toBe("http://forge/p");
  });
  test("the brief tells the agent what it can run and never to leave the sandbox", async () => {
    const { systemPrompt } = await import("../src/crew/brief.ts");
    const prompt = systemPrompt({
      agent: { user: { username: "bot", displayName: "" }, brief: "" },
      repo: { ownerName: "alice", name: "square", defaultBranch: "main" },
      issue: { number: 1 },
      branch: "bot/1",
      forgeUrl: "http://forge.test",
      isApp: false,
    } as never);
    expect(prompt).toContain("Never leave the sandbox");
    expect(prompt).toContain("FORGE_TEST_SOCKET=port");
    expect(prompt).not.toMatch(/sandbox (off|disabled)|outside the sandbox/i);
  });
});
describe("a sandboxed run pushes through a port-mode forge (#1107)", () => {
  async function runWith() {
    const was = process.env["FORGE_TEST_SOCKET"];
    process.env["FORGE_TEST_SOCKET"] = "port";
    const dataDir = await mkdtemp(join(tmpdir(), "forge-sandbox-push-"));
    const app = createApp({ dataDir, port: 0 });
    const servers = await serve(app);
    // Bound; from here only the runner may put it in a run's environment.
    delete process.env["FORGE_TEST_SOCKET"];
    const seen = join(dataDir, "seen");
    const fake = join(dataDir, "fake-claude");
    writeFileSync(
      fake,
      `#!/bin/sh
if [ "$1" = "--version" ]; then echo "2.1.0 (fake)"; exit 0; fi
IFS= read -r first
echo "\${FORGE_TEST_SOCKET:-unset}" > "${seen}.env"
echo "x" >> W.md; git add -A; git commit -qm w
git push origin HEAD:refs/pull/9 > "${seen}.pull" 2>&1
git push -q -u origin HEAD > "${seen}.branch" 2>&1
echo '{"type":"result","subtype":"success","is_error":false,"result":"ok","total_cost_usd":0.01,"num_turns":1,"session_id":"s","terminal_reason":"completed"}'
`,
    );
    chmodSync(fake, 0o755);
    const crew = await startCrew(app, {
      forgeUrl: servers.url,
      localUrl: servers.url,
      binary: fake,
      concurrency: 1,
      budgetUsd: 1,
      runTimeoutMs: 60_000,
    });
    try {
      const alice = await createUser(app.db, { trusted: true,
        username: "alice",
        email: "[email protected]",
        password: "a-good-passphrase",
        adminIfFirst: true,
      });
      if (!alice.ok) throw new Error(alice.error);
      const made = await createAgent(app, alice.value, { username: "bot", brief: "b" });
      if (!made.ok) throw new Error(String(made.error));
      const repo = await createRepo(app, alice.value, { name: "garden" });
      if (!repo.ok) throw new Error(String(repo.error));
      const seeded = await commitToBranch(app, alice.value, repo.value, {
        message: "Start",
        files: [{ path: "README.md", content: "# g\n" }],
      });
      if (!seeded.ok) throw new Error(JSON.stringify(seeded.error));
      addToCrew(app, alice.value, repo.value, "bot");
      const issue = openIssue(app, alice.value, repo.value, { title: "Plant", body: "x" });
      if (!issue.ok) throw new Error(String(issue.error));
      assignIssue(app, alice.value, repo.value, issue.value, made.value.user);
      const deadline = Date.now() + 30_000;
      while (Date.now() < deadline) {
        const run = listRuns(app.db, repo.value.id, { kind: "agent" })[0];
        if (run && ["ok", "failed", "cancelled"].includes(run.state)) break;
        await Bun.sleep(100);
      }
      const read = (n: string) => (existsSync(`${seen}.${n}`) ? readFileSync(`${seen}.${n}`, "utf8") : "");
      return { env: read("env").trim(), pull: read("pull"), branch: read("branch"), address: app.hookAddress.current };
    } finally {
      await crew.stop();
      servers.stop();
      app.close();
      await rm(dataDir, { recursive: true, force: true });
      if (was === undefined) delete process.env["FORGE_TEST_SOCKET"];
      else process.env["FORGE_TEST_SOCKET"] = was;
    }
  }
  // `startCrew` probes the host itself, so the run is sandboxed exactly
  // where this host can hold it to one; the env must follow that.
  test("a sandboxed run carries FORGE_TEST_SOCKET=port, an unsandboxed one does not; a real push meets the pre-receive verdict over the port", async () => {
    const enforced = (await sandboxAvailable()).ok;
    const r = await runWith();
    expect(r.env).toBe(enforced ? "port" : "unset");
    expect(r.address).toMatch(/^tcp:/);
    expect(r.pull).toContain("refs/pull/* is reserved");
    // The ordinary branch push went through the same door.
    expect(r.branch).not.toContain("hook relay failed");
    expect(r.branch).not.toContain("forbidden");
  }, 60_000);
});
@@ -5,6 +5,7 @@
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { portInsteadOfSocket } from "../src/git/hook-address.ts";
import { lstat, mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -82,7 +83,11 @@
describe("reconcile refreshes hooks (H-1)", () => {
  });
});
describe("two forges on one data directory", () => {
// These two are about unix socket files themselves; where the sandbox
// refuses the bind (FORGE_TEST_SOCKET=port) the check runs them instead.
const bySocket = portInsteadOfSocket() ? describe.skip : describe;
bySocket("two forges on one data directory", () => {
  test("a socket another forge still answers on is left alone, and this forge boots beside it", async () => {
    const dataDir = await mkdtemp(join(tmpdir(), "forge-harden-share-"));
    const app = createApp({ dataDir, port: 0 });
@@ -142,7 +147,7 @@
describe("two forges on one data directory", () => {
  });
});
describe("stale socket recovery (H-2)", () => {
bySocket("stale socket recovery (H-2)", () => {
  test("a real SIGKILL-orphaned socket inode does not block boot", async () => {
    const dataDir = await mkdtemp(join(tmpdir(), "forge-harden-sock-"));
    const app = createApp({ dataDir, port: 0 });
		@@ -0,0 +1,35 @@
	1	# The crew's shell
	2
	3	An agent's shell runs inside Claude Code's sandbox (`src/crew/sandbox.ts` is
	4	the policy, `src/crew/claude.ts` the settings): the network is the forge and
	5	the package registry, writes stay in the clone and the run's own `tmpDir`,
	6	and the machine's temp directory, the forge's data and the operator's
	7	credentials are unreadable. No command runs outside it on request.
	8
	9	## Running this repository's tests inside it
	10
	11	On Linux the sandbox refuses the bind of a unix socket, and the forge's
	12	internal listener (the git hooks' door) is one. Claude Code can only allow
	13	unix sockets all or none, which would open every socket the machine has, so
	14	the boundary is kept instead: a run's environment carries
	15	`FORGE_TEST_SOCKET=port`, and the forge listens on a loopback port
	16	(`tcp:127.0.0.1:<port>`, `src/git/hook-address.ts`) where it would use a
	17	socket. Loopback ports were already allowed (`allowLocalBinding`), and
	18	`localhost` outside the sandbox stays unreachable.
	19
	20	What an agent can run: the type check and `bun test` over `test/`, with no
		sentinelcrew 1mo ago outdated Not accurate: the two hardening suites are not the only socket-bound ones. The egress proxy (`startEgress`) and the env-data/app sockets bind unix sockets too, and their suites fail under FORGE_TEST_SOCKET=port.
	21	failures. A cell reaches its egress proxy through a unix socket, which cannot
	22	be put on a port, so in port mode `cellsAvailable()` answers no
	23	(`FORGE_TEST_SOCKET=port: no unix sockets`) and deploys and checks run
	24	uncontained, as with `FORGE_CELLS=off`. The suites that are about sockets and
	25	cells themselves skip in port mode and show as skipped: stale-socket recovery
	26	and two forges on one data directory (`test/hardening.test.ts`), the egress
	27	proxy and the cell-limit and probe suites (`test/contain.test.ts`), and the
	28	socket-copy test in `test/apps-adversarial.test.ts`. The forge's check runs
	29	them on every push and sends the log back.
	30
	31	Not proven from inside a sandbox: that a sandboxed shell reaches its own server
	32	and is still refused `localhost` outside the sandbox and every `denyRead` path.
	33	Nesting a sandbox is not possible there, so `test/crew-sandbox.test.ts` checks
	34	the settings that enforce it (`allowLocalBinding` on, `allowAllUnixSockets` off,
	35	the `denyRead` list) and not the boundary itself.
		@@ -7,6 +7,7 @@
7	7	import type { MailConfig, Mailer } from "./kernel/mail.ts";
8	8	import type { Database } from "bun:sqlite";
9	9	import type { Decider } from "./crew/decide.ts";
	10	import { randomBytes } from "node:crypto";
10	11	import { mkdirSync } from "node:fs";
11	12	import { join, resolve } from "node:path";
12	13	import { migrations } from "./core/schema.ts";
		@@ -133,6 +134,10 @@ export interface App {
133	134	readonly log: Log;
134	135	readonly reposRoot: string;
135	136	readonly socketPath: string;
	137	/** Where the internal listener answers: `socketPath`, or a loopback port (`git/hook-address.ts`). */
	138	readonly hookAddress: { current: string };
	139	/** Per-boot secret every internal request must carry (`FORGE_HOOK_SECRET` in a hook's env). */
	140	readonly hookSecret: string;
136	141	close(): void;
137	142	}
138	143
		@@ -144,6 +149,7 @@ export function createApp(config: ForgeConfig): App {
144	149	const dataDir = resolve(config.dataDir);
145	150	const reposRoot = join(dataDir, "repos");
146	151	mkdirSync(reposRoot, { recursive: true });
	152	const socketPath = join(dataDir, `forge-${id()}.sock`);
147	153
148	154	const db = openDb(join(dataDir, "forge.db"), migrations);
149	155	// Hand-installed new-account guards become the `guard_new_accounts`
		@@ -168,7 +174,9 @@ export function createApp(config: ForgeConfig): App {
168	174	reposRoot,
169	175	// This process's own: two forges share a data directory for the length
170	176	// of a release, and each spawns git with its own socket in the env.
171		socketPath: join(dataDir, `forge-${id()}.sock`),
	177	socketPath,
	178	hookAddress: { current: socketPath },
	179	hookSecret: randomBytes(32).toString("hex"),
172	180	close: () => {
173	181	// The pooled `cat-file` readers for this forge's repos are processes,
174	182	// and processes outlive a closed database unless somebody says
		@@ -33,6 +33,7 @@ import {
33	33	} from "node:fs";
34	34	import { availableParallelism, tmpdir } from "node:os";
35	35	import { dirname, join } from "node:path";
	36	import { portInsteadOfSocket } from "../git/hook-address.ts";
36	37	import { relay, startEgress, type Egress } from "./egress.ts";
37	38
38	39	export interface Limits {
		@@ -154,6 +155,10 @@ export function cellsAvailable(): Promise<
154	155	async function probe(): Promise<{ ok: true } \| { ok: false; reason: string }> {
155	156	if (process.env["FORGE_CELLS"] === "off")
156	157	return { ok: false, reason: "FORGE_CELLS=off" };
	158	// A cell reaches its proxy through a unix socket; a sandbox that put the
	159	// forge on loopback ports (a crew run's `bun test`) cannot bind one.
	160	if (portInsteadOfSocket())
	161	return { ok: false, reason: "FORGE_TEST_SOCKET=port: no unix sockets" };
157	162	if (process.platform !== "linux")
158	163	return { ok: false, reason: `no cells on ${process.platform}` };
159	164	for (const tool of ["bwrap", "socat"])
		@@ -120,7 +120,7 @@ export function systemPrompt(input: BriefInput): string {
120	120	}
121	121	lines.push(
122	122	"",
123		"Your shell is sandboxed: writes stay in the clone, the network is the forge and the package registry, and you cannot signal processes you started in an earlier command. If you start the app to try it, do it inside one command that also stops it (`bun run src/server.ts & pid=$!; sleep 2; curl …; kill $pid`). Anything left running is stopped by the forge when you finish; it is not a failure, but it is noise.",
	123	"Your shell is sandboxed: writes stay in the clone, the network is the forge and the package registry, and you cannot signal processes you started in an earlier command. If you start the app to try it, do it inside one command that also stops it (`bun run src/server.ts & pid=$!; sleep 2; curl …; kill $pid`). Anything left running is stopped by the forge when you finish; it is not a failure, but it is noise. Never leave the sandbox: it cannot be asked to. Inside it you can run the type check and `bun test` (FORGE_TEST_SOCKET=port is already set, so servers listen on loopback ports in place of unix sockets). The suites about unix sockets and cells themselves (stale-socket recovery, the egress proxy, cell limits) are skipped in that mode and named as skipped; the forge's check runs them on every push. Run what covers your change; the forge runs the whole check on your push and sends you its log.",
		sentinelcrew 1mo ago outdated This says `bun test` runs inside the sandbox. At this head, in port mode, apps-adversarial, apps-token and contain fail with `Failed to listen at …/out.sock` (src/apps/egress.ts) and on app sockets. Either make them run or name exactly what the check runs instead. An agent told everything is green that then sees 24 red tests will chase them.
124	124	"",
125	125	"Work carefully and finish. If the task is unclear, impossible, or not something you should do, do not guess: make your last message start with `DECLINED:` followed by exactly why. Nothing is pushed then, and a person reads it.",
126	126	);
		@@ -921,6 +921,9 @@ async function work(
921	921	env["CLAUDE_CODE_TMPDIR"] = runTmp;
922	922	env["TMPDIR"] = runTmp;
923	923	}
	924	// The sandbox refuses a unix socket's bind; the forge's own servers take
	925	// a loopback port instead (`git/hook-address.ts`), so `bun test` runs.
	926	if (sandbox.enforced) env["FORGE_TEST_SOCKET"] = "port";
		sentinelcrew 1mo ago No test would fail without this line. Assert that a sandboxed run's environment carries `FORGE_TEST_SOCKET=port` and that an unsandboxed run's does not.
924	927	// One deadline for the run, whatever it takes to get there: the token
925	928	// dies ten minutes after it, so a second invocation gets what is left.
926	929	const deadline = Date.now() + options.runTimeoutMs;
		@@ -0,0 +1,42 @@
	1	/**
	2	* Where the forge's internal listener answers: a unix socket path, or
	3	* `tcp:<host>:<port>` on loopback. Production uses the socket. A sandbox
	4	* that refuses the bind (an agent running `bun test`) sets
	5	* `FORGE_TEST_SOCKET=port` and the listener takes a loopback port instead,
	6	* so no unix socket is ever exposed to the sandbox to get there.
	7	*/
	8
	9	const TCP = /^tcp:(127\.0\.0\.1):([0-9]{1,5})$/;
	10
	11	/** The address of a loopback listener. */
	12	export function tcpAddress(port: number): string {
	13	return `tcp:127.0.0.1:${port}`;
	14	}
	15
	16	/** Whether the environment asks for a loopback port in place of a unix socket. */
	17	export function portInsteadOfSocket(
	18	env: Record<string, string \| undefined> = process.env,
	19	): boolean {
	20	return env["FORGE_TEST_SOCKET"] === "port";
	21	}
	22
	23	/** The URL and fetch option that reach `path` at `address`. */
	24	export function internalRequest(
	25	address: string,
	26	path: string,
	27	): { url: string; init: { unix?: string } } {
	28	const tcp = TCP.exec(address);
	29	if (tcp !== null)
	30	return { url: `http://${tcp[1]}:${tcp[2]}${path}`, init: {} };
	31	return { url: `http://forge${path}`, init: { unix: address } };
	32	}
	33
	34	/** `fetch` against the internal listener, wherever it is. */
	35	export function fetchInternal(
	36	address: string,
	37	path: string,
	38	init: RequestInit = {},
	39	): Promise<Response> {
	40	const target = internalRequest(address, path);
	41	return fetch(target.url, { ...init, ...target.init } as RequestInit);
	42	}
		@@ -24,12 +24,26 @@ export interface HookRequest {
24	24	readonly gitEnv: Record<string, string>;
25	25	}
26	26
	27	/** The header that carries the per-boot secret to the internal listener. */
	28	export const HOOK_SECRET_HEADER = "x-forge-hook-secret";
	29
27	30	export const FORWARDED_GIT_ENV = [
28	31	"GIT_OBJECT_DIRECTORY",
29	32	"GIT_ALTERNATE_OBJECT_DIRECTORIES",
30	33	"GIT_QUARANTINE_PATH",
31	34	] as const;
32	35
	36	/** Only the quarantine variables a hook may forward reach git. */
	37	export function forwardedGitEnv(env: unknown): Record<string, string> {
	38	const kept: Record<string, string> = {};
	39	if (typeof env !== "object" \|\| env === null) return kept;
	40	for (const name of FORWARDED_GIT_ENV) {
	41	const value = (env as Record<string, unknown>)[name];
	42	if (typeof value === "string") kept[name] = value;
	43	}
	44	return kept;
	45	}
	46
33	47	export function parseHookStdin(text: string): RefUpdate[] {
34	48	const updates: RefUpdate[] = [];
35	49	for (const line of text.split("\n")) {
		@@ -10,7 +10,12 @@
10	10
11	11	import { chmod } from "node:fs/promises";
12	12	import { join } from "node:path";
13		import { FORWARDED_GIT_ENV, parseHookStdin } from "./hook-protocol.ts";
	13	import { fetchInternal } from "./hook-address.ts";
	14	import {
	15	FORWARDED_GIT_ENV,
	16	HOOK_SECRET_HEADER,
	17	parseHookStdin,
	18	} from "./hook-protocol.ts";
14	19
15	20	const HOOK_NAMES = ["pre-receive", "post-receive"] as const;
16	21	type HookName = (typeof HOOK_NAMES)[number];
		@@ -52,6 +57,7 @@ function selfInvocation(): { runtime: string; entry: string \| undefined } {
52	57	/** Env for a receive-pack spawn so its hooks can reach back into the forge. */
53	58	export function hookEnv(input: {
54	59	socketPath: string;
	60	secret: string;
55	61	repoId: string;
56	62	actorId: string;
57	63	}): Record<string, string> {
		@@ -59,6 +65,7 @@ export function hookEnv(input: {
59	65	const env: Record<string, string> = {
60	66	FORGE_RUNTIME: self.runtime,
61	67	FORGE_SOCKET: input.socketPath,
	68	FORGE_HOOK_SECRET: input.secret,
62	69	FORGE_REPO_ID: input.repoId,
63	70	FORGE_ACTOR_ID: input.actorId,
64	71	};
		@@ -97,10 +104,12 @@ export async function runHookClient(hook: HookName): Promise<never> {
97	104	}
98	105
99	106	try {
100		const response = await fetch("http://forge/internal/hook", {
101		unix: socket,
	107	const response = await fetchInternal(socket, "/internal/hook", {
102	108	method: "POST",
103		headers: { "content-type": "application/json" },
	109	headers: {
	110	"content-type": "application/json",
	111	[HOOK_SECRET_HEADER]: process.env.FORGE_HOOK_SECRET ?? "",
	112	},
104	113	// A forge that has stopped answering must not become a push that never
105	114	// returns. Without a deadline this relay waits forever, and the git
106	115	// process holding the repo's ref lock waits with it — one wedged forge
		@@ -53,6 +53,11 @@ import {
53	53	serviceRpc,
54	54	type GitService,
55	55	} from "../git/smart-http.ts";
	56	import { timingSafeEqual } from "node:crypto";
	57	import {
	58	forwardedGitEnv,
	59	HOOK_SECRET_HEADER,
	60	} from "../git/hook-protocol.ts";
56	61	import { lstat, readdir, rm } from "node:fs/promises";
57	62	import { rmSync } from "node:fs";
58	63	import { join } from "node:path";
		@@ -399,6 +404,7 @@ import {
399	404	resolveAppHost,
400	405	} from "../apps/proxy.ts";
401	406
	407	import { portInsteadOfSocket, tcpAddress } from "../git/hook-address.ts";
402	408	import { closeHostedChildren, resolveHostedChild } from "../spawn/host.ts";
403	409	import { getVerifiedDomain } from "../core/domains.ts";
404	410
		@@ -812,7 +818,8 @@ export function buildRouter(): Router<Handler> {
812	818	withGitAccess(ctx, "git-receive-pack", (dir, repoId) =>
813	819	serviceRpc(dir, "git-receive-pack", ctx.request, {
814	820	env: hookEnv({
815		socketPath: ctx.app.socketPath,
	821	socketPath: ctx.app.hookAddress.current,
	822	secret: ctx.app.hookSecret,
816	823	repoId,
817	824	actorId: ctx.auth.user?.id ?? "",
818	825	}),
		@@ -1379,8 +1386,16 @@ const fromStored = (stored: StoredResponse, replay: boolean): Response =>
1379	1386
1380	1387	// ---- the internal server (unix socket, hooks only) ----
1381	1388
	1389	/** Whether the request carries this boot's hook secret (constant-time). */
	1390	function hookCallerAllowed(app: App, request: Request): boolean {
	1391	const given = Buffer.from(request.headers.get(HOOK_SECRET_HEADER) ?? "");
	1392	const want = Buffer.from(app.hookSecret);
	1393	return given.length === want.length && timingSafeEqual(given, want);
	1394	}
	1395
1382	1396	async function handleHook(app: App, request: Request): Promise<Response> {
1383		const input = (await request.json()) as HookRequest;
	1397	const parsed = (await request.json()) as HookRequest;
		sentinelcrew 1mo ago outdated Good hardening. It is the hook protocol's concept, though: move it to `src/git/hook-protocol.ts` next to `FORWARDED_GIT_ENV` rather than exporting a helper from the server module. sentinelcrew 1mo ago The secret gates this, so it is low. The body is still cast rather than checked, though: a `null` or non-object body throws here and comes back as a 500. A shape check returning 400 would match the validate-at-the-boundary rule now that this listener can be a TCP port.
	1398	const input: HookRequest = { ...parsed, gitEnv: forwardedGitEnv(parsed.gitEnv) };
1384	1399	const repo = getRepoById(app.db, input.repoId);
1385	1400	if (!repo) return new Response("unknown repository", { status: 400 });
1386	1401
		@@ -1716,9 +1731,15 @@ export async function serve(app: App): Promise<Servers> {
1716	1731	},
1717	1732	});
1718	1733
	1734	const onPort = portInsteadOfSocket();
1719	1735	const internal = Bun.serve({
1720		unix: app.socketPath,
	1736	...(onPort ? { hostname: "127.0.0.1", port: 0 } : { unix: app.socketPath }),
1721	1737	fetch(request) {
	1738	// The socket's file mode used to be the only door check; a loopback
	1739	// port has none, so every internal request proves the boot secret.
	1740	if (!hookCallerAllowed(app, request)) {
	1741	return new Response("forbidden", { status: 403 });
	1742	}
1722	1743	const url = new URL(request.url);
1723	1744	if (request.method === "POST" && url.pathname === "/internal/hook") {
1724	1745	return handleHook(app, request);
		@@ -1727,6 +1748,7 @@ export async function serve(app: App): Promise<Servers> {
1727	1748	},
1728	1749	});
1729	1750
	1751	if (onPort) app.hookAddress.current = tcpAddress(internal.port ?? 0);
1730	1752	const port = web.port ?? 0;
1731	1753	return {
1732	1754	url: `http://localhost:${port}`,
		@@ -274,7 +274,8 @@ async function serveGitCommand(
274	274	const dir = repoDir(forge.reposRoot, repo.ownerName, repo.name);
275	275	const env: Record<string, string> = write
276	276	? hookEnv({
277		socketPath: forge.socketPath,
	277	socketPath: forge.hookAddress.current,
	278	secret: forge.hookSecret,
278	279	repoId: repo.id,
279	280	actorId: user?.id ?? "",
280	281	})