@amenophis1er/foreman 0.1.7 → 0.1.9

package/src/gitwork.ts

@@ -0,0 +1,239 @@
+/**
+ * Git around a mission: which branch a folder is on, a branch of its own for
+ * each mission, and the commit that closes one.
+ *
+ * A mission is a unit of work; in a repository, a branch makes it one in
+ * git too — isolation, a diff that is exactly the mission, an easy revert,
+ * a pull request if there is a remote. Foreman creates the branch and
+ * commits on it. It never merges, and it pushes only when the human presses
+ * the button that says so — once, for that branch, to open the pull request.
+ */
+import { execFile } from 'node:child_process';
+
+export interface GitInfo {
+  repo: boolean;
+  /** Current branch; a short sha when detached. */
+  branch?: string;
+  /** Uncommitted changes, tracked or untracked. */
+  dirty?: boolean;
+  head?: string | null;
+  /** `origin`'s URL when there is one, so the UI can say "has a remote". */
+  remote?: string;
+}
+
+/** Recorded on a run that got a branch of its own. */
+export interface MissionGit {
+  branch: string;
+  /** Where it was made from: the branch (or short sha) that was checked out. */
+  base: string;
+  baseHead: string | null;
+  /** Commits on the branch since `baseHead`, updated when the mission closes. */
+  commits?: number;
+  /** The closing commit, when the mission's work was committed. */
+  commit?: string;
+}
+
+function git(args: string[], cwd: string, timeoutMs = 15_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, {
+      cwd, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, encoding: 'utf8',
+      env: { ...process.env, GIT_PAGER: 'cat', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' },
+    }, (err, stdout, stderr) => {
+      if (err) reject(new Error(`git ${args[0]}: ${(stderr || err.message).trim()}`));
+      else resolve(String(stdout));
+    });
+  });
+}
+
+/** What git says about a folder; `{ repo: false }` for anything that is not a work tree. Never throws. */
+export async function gitInfo(folder: string): Promise<GitInfo> {
+  try {
+    const inside = (await git(['rev-parse', '--is-inside-work-tree'], folder)).trim();
+    if (inside !== 'true') return { repo: false };
+  } catch {
+    return { repo: false };
+  }
+  const info: GitInfo = { repo: true };
+  try {
+    const ref = (await git(['rev-parse', '--abbrev-ref', 'HEAD'], folder)).trim();
+    info.branch = ref === 'HEAD' ? (await git(['rev-parse', '--short', 'HEAD'], folder)).trim() : ref;
+  } catch {
+    // An empty repository: HEAD names a branch with no commits yet.
+    try { info.branch = (await git(['symbolic-ref', '--short', 'HEAD'], folder)).trim(); } catch { /* leave unset */ }
+  }
+  try { info.head = (await git(['rev-parse', '--verify', 'HEAD'], folder)).trim() || null; } catch { info.head = null; }
+  try { info.dirty = (await git(['status', '--porcelain', '--untracked-files=normal'], folder)).trim().length > 0; } catch { /* unknown */ }
+  try { info.remote = (await git(['remote', 'get-url', 'origin'], folder)).trim() || undefined; } catch { /* no remote */ }
+  return info;
+}
+
+/** `foreman/<first words of the brief>-<id tail>`: readable in `git branch`, unique per run. */
+export function missionBranchName(mission: string, runId: string): string {
+  const first = mission.split('\n').find((l) => l.trim())?.trim() ?? 'mission';
+  const slug = first.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').split('-').filter(Boolean).slice(0, 6).join('-').slice(0, 40).replace(/-+$/, '') || 'mission';
+  const tail = runId.replace(/[^a-z0-9]/gi, '').slice(-4).toLowerCase();
+  return `foreman/${slug}-${tail}`;
+}
+
+/**
+ * A branch of the mission's own, made from what is checked out now.
+ * Uncommitted changes come along, as `checkout -b` always does. Resolves to
+ * the record for the run, or to one sentence on why it could not.
+ */
+export async function startMissionBranch(folder: string, mission: string, runId: string): Promise<MissionGit | { error: string }> {
+  const info = await gitInfo(folder);
+  if (!info.repo) return { error: 'not a git repository' };
+  const branch = missionBranchName(mission, runId);
+  try {
+    await git(['checkout', '-b', branch], folder);
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+  return { branch, base: info.branch ?? 'HEAD', baseHead: info.head ?? null };
+}
+
+/**
+ * Back on the mission's branch for a resume. Returns null when already or
+ * now there, else why not — a dirty tree that would be clobbered, typically.
+ */
+export async function ensureMissionBranch(folder: string, branch: string): Promise<string | null> {
+  const info = await gitInfo(folder);
+  if (!info.repo) return 'the folder is no longer a git repository';
+  if (info.branch === branch) return null;
+  try {
+    await git(['checkout', branch], folder);
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
+/**
+ * Commits whatever the mission left uncommitted, on its branch, as the user
+ * (their git config), falling back to a Foreman identity only when the
+ * repository has none. Then counts the branch's commits since its base.
+ */
+export async function closeMissionBranch(folder: string, g: MissionGit, message: string): Promise<MissionGit & { committed: boolean; error?: string }> {
+  const out: MissionGit & { committed: boolean; error?: string } = { ...g, committed: false };
+  try {
+    const info = await gitInfo(folder);
+    if (!info.repo) return { ...out, error: 'not a git repository' };
+    if (info.branch !== g.branch) return { ...out, error: `the folder is on ${info.branch ?? 'another branch'}, not ${g.branch}; nothing committed` };
+    if (info.dirty) {
+      await git(['add', '-A', '--', '.'], folder);
+      const identity = ['-c', 'user.name=Foreman', '-c', 'user.email=foreman@localhost'];
+      const hasName = await git(['config', 'user.name'], folder).then((v) => v.trim().length > 0).catch(() => false);
+      await git([...(hasName ? [] : identity), 'commit', '-q', '-m', message], folder);
+      out.commit = (await git(['rev-parse', '--short', 'HEAD'], folder)).trim();
+      out.committed = true;
+    }
+    if (g.baseHead) {
+      out.commits = Number((await git(['rev-list', '--count', `${g.baseHead}..HEAD`], folder)).trim()) || 0;
+    } else {
+      out.commits = Number((await git(['rev-list', '--count', 'HEAD'], folder)).trim()) || 0;
+    }
+  } catch (err) {
+    out.error = err instanceof Error ? err.message : String(err);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The pull request: the one outward-facing act, and only ever on a button
+// ---------------------------------------------------------------------------
+
+/** `git@github.com:o/r.git` or `https://host/o/r(.git)` → the repository's web page. Null for anything else. */
+export function remoteWebUrl(remote: string | undefined): { host: string; web: string; path: string } | null {
+  if (!remote) return null;
+  let m = /^git@([^:]+):(.+?)(?:\.git)?\/?$/.exec(remote.trim());
+  if (m) return { host: m[1].toLowerCase(), path: m[2], web: `https://${m[1]}/${m[2]}` };
+  m = /^ssh:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+?)(?:\.git)?\/?$/.exec(remote.trim());
+  if (m) return { host: m[1].toLowerCase(), path: m[2], web: `https://${m[1]}/${m[2]}` };
+  m = /^https?:\/\/(?:[^@/]+@)?([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(remote.trim());
+  if (m) return { host: m[1].toLowerCase(), path: m[2], web: `https://${m[1]}/${m[2]}` };
+  return null;
+}
+
+/** Where a human finishes the pull request in a browser when `gh` is not around: GitHub, GitLab and Bitbucket forms; null elsewhere. */
+export function compareUrl(remote: string | undefined, base: string, branch: string): string | null {
+  const r = remoteWebUrl(remote);
+  if (!r) return null;
+  const enc = encodeURIComponent;
+  if (r.host === 'github.com' || r.host.endsWith('.github.com')) return `${r.web}/compare/${enc(base)}...${enc(branch)}?expand=1`;
+  if (r.host.includes('gitlab')) return `${r.web}/-/merge_requests/new?merge_request%5Bsource_branch%5D=${enc(branch)}&merge_request%5Btarget_branch%5D=${enc(base)}`;
+  if (r.host.includes('bitbucket')) return `${r.web}/pull-requests/new?source=${enc(branch)}&dest=${enc(base)}`;
+  return `${r.web}`;
+}
+
+/** The pull request as Foreman drafts it: the run's title, and a body a reviewer can read without opening Foreman. */
+export function prDraft(run: { title?: string; mission: string; costUsd: number; costBasis?: string; git?: MissionGit }, missionDoc: string | null): { title: string; body: string } {
+  const first = run.mission.split('\n').find((l) => l.trim())?.trim() ?? 'Mission';
+  const title = (run.title || first).slice(0, 120);
+  const boxes = (missionDoc ?? '').split('\n').filter((l) => /^\s*[-*] \[[ xX]\]/.test(l)).map((l) => l.trim());
+  const spend = run.costBasis === 'priced' || run.costBasis === undefined ? `$${run.costUsd.toFixed(2)}` : run.costBasis;
+  const parts = [
+    '## Mission', '', run.mission.trim(), '',
+  ];
+  if (boxes.length) parts.push('## Done when', '', ...boxes, '');
+  parts.push('---', `Run by [Foreman](https://github.com/amenophis1er/foreman) on branch \`${run.git?.branch ?? ''}\` from \`${run.git?.base ?? ''}\` · spend ${spend}.`);
+  return { title, body: parts.join('\n') };
+}
+
+/** `git push -u origin <branch>`, as the user. Null on success, git's reason otherwise. */
+export async function pushBranch(folder: string, branch: string): Promise<string | null> {
+  try {
+    await git(['push', '-u', 'origin', branch], folder, 5 * 60_000);
+    return null;
+  } catch (err) {
+    const t = err instanceof Error ? err.message : String(err);
+    if (/could not read Username|Authentication failed|Permission denied|terminal prompts disabled/i.test(t)) {
+      return 'Git could not authenticate to the remote. Set up a credential helper or gh auth, or use an SSH remote with a key this machine has.';
+    }
+    return t.replace(/^git push:\s*/, 'git push failed: ');
+  }
+}
+
+/** Is GitHub's CLI here and signed in? Best effort, a few seconds at most. */
+export async function ghReady(): Promise<{ present: boolean; authed: boolean }> {
+  return new Promise((resolve) => {
+    execFile('gh', ['auth', 'status'], { timeout: 8_000 }, (err) => {
+      if (err && (err as NodeJS.ErrnoException).code === 'ENOENT') return resolve({ present: false, authed: false });
+      resolve({ present: true, authed: !err });
+    });
+  });
+}
+
+/** What became of a pull request, from gh: open, merged or closed. Null when gh cannot say. */
+export function pullRequestState(folder: string, url: string): Promise<{ state: 'open' | 'merged' | 'closed'; mergedAt?: string; number?: number } | null> {
+  return new Promise((resolve) => {
+    execFile('gh', ['pr', 'view', url, '--json', 'state,mergedAt,number'], {
+      cwd: folder, timeout: 15_000, env: { ...process.env, GH_PROMPT_DISABLED: '1' },
+    }, (err, stdout) => {
+      if (err) return resolve(null);
+      try {
+        const d = JSON.parse(String(stdout)) as { state?: string; mergedAt?: string | null; number?: number };
+        const state = d.state === 'MERGED' ? 'merged' : d.state === 'CLOSED' ? 'closed' : d.state === 'OPEN' ? 'open' : null;
+        resolve(state ? { state, mergedAt: d.mergedAt ?? undefined, number: d.number } : null);
+      } catch { resolve(null); }
+    });
+  });
+}
+
+/** `gh pr create`, as the user. Resolves to the PR's URL, or to why not. */
+export function createPullRequest(folder: string, opts: { base: string; branch: string; title: string; body: string }): Promise<{ url?: string; error?: string }> {
+  return new Promise((resolve) => {
+    execFile('gh', ['pr', 'create', '--base', opts.base, '--head', opts.branch, '--title', opts.title, '--body', opts.body], {
+      cwd: folder, timeout: 60_000, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, GH_PROMPT_DISABLED: '1', GIT_TERMINAL_PROMPT: '0' },
+    }, (err, stdout, stderr) => {
+      if (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return resolve({ error: 'gh is not installed' });
+        const t = String(stderr || err.message).trim();
+        const existing = /already exists:\s*(https?:\S+)/.exec(t);
+        if (existing) return resolve({ url: existing[1] });
+        return resolve({ error: `gh pr create: ${t.split('\n').filter(Boolean).pop() ?? t}` });
+      }
+      const url = String(stdout).split('\n').map((l) => l.trim()).find((l) => /^https?:\/\//.test(l));
+      resolve(url ? { url } : { error: 'gh did not return a pull request URL' });
+    });
+  });
+}

package/src/guard.test.ts

@@ -0,0 +1,104 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import type http from 'node:http';
+import { requestAllowed, pathPermitted } from './guard.js';
+
+const PORT = 4177;
+const TAILNET = { ip: '100.94.221.98', dnsName: 'laptop.tail1234.ts.net' };
+const OPTS = { port: PORT, tailnet: TAILNET };
+
+/** A request as the guard sees one: a method and a bag of headers. */
+function req(method: string, headers: Record<string, string>) {
+  return { method, headers: headers as http.IncomingHttpHeaders };
+}
+
+test('requestAllowed: the hosts Foreman answers to', () => {
+  assert.deepEqual(requestAllowed(req('GET', { host: `localhost:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: `127.0.0.1:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: `[::1]:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: `100.94.221.98:${PORT}` }), OPTS), { ok: true });
+  // The MagicDNS name with Foreman's port, and with whatever port
+  // `tailscale serve` put in front of it — including none at all (443).
+  assert.deepEqual(requestAllowed(req('GET', { host: `laptop.tail1234.ts.net:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: 'laptop.tail1234.ts.net' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: 'laptop.tail1234.ts.net:8443' }), OPTS), { ok: true });
+  // Case never matters in a host name.
+  assert.deepEqual(requestAllowed(req('GET', { host: 'LapTop.Tail1234.TS.net' }), OPTS), { ok: true });
+});
+
+test('requestAllowed: an unrecognised or missing Host is 421 (DNS rebinding)', () => {
+  assert.deepEqual(requestAllowed(req('GET', { host: `evil.example:${PORT}` }), OPTS), {
+    ok: false, status: 421, error: 'unrecognised Host',
+  });
+  assert.deepEqual(requestAllowed(req('GET', {}), OPTS), {
+    ok: false, status: 421, error: 'unrecognised Host',
+  });
+  // A neighbouring name is not the tailnet name.
+  assert.equal(requestAllowed(req('GET', { host: 'notlaptop.tail1234.ts.net' }), OPTS).ok, false);
+  // No tailnet: its address is not special.
+  assert.equal(requestAllowed(req('GET', { host: `100.94.221.98:${PORT}` }), { port: PORT, tailnet: null }).ok, false);
+});
+
+test('requestAllowed: safe methods pass on Host alone, whatever the Origin', () => {
+  const ok = req('GET', { host: `localhost:${PORT}`, origin: 'http://evil.example' });
+  assert.deepEqual(requestAllowed(ok, OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('HEAD', { host: `localhost:${PORT}`, origin: 'http://evil.example' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('OPTIONS', { host: `localhost:${PORT}`, origin: 'http://evil.example' }), OPTS), { ok: true });
+  // Including the event stream, which is how the dashboard stays live.
+  assert.deepEqual(requestAllowed(req('GET', { host: `127.0.0.1:${PORT}`, 'sec-fetch-site': 'cross-site' }), OPTS), { ok: true });
+});
+
+test('requestAllowed: an unsafe method with a foreign Origin is refused', () => {
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: 'http://evil.example' }), OPTS), {
+    ok: false, status: 403, error: 'cross-site request refused',
+  });
+  // Right name, wrong port: a different origin to the browser and to us.
+  assert.equal(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: 'http://localhost:9999' }), OPTS).ok, false);
+  // Not a web origin at all.
+  assert.equal(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: 'null' }), OPTS).ok, false);
+  assert.equal(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: 'file://' }), OPTS).ok, false);
+});
+
+test('requestAllowed: an unsafe method from Foreman’s own page is allowed', () => {
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: `http://localhost:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('DELETE', { host: `127.0.0.1:${PORT}`, origin: `http://127.0.0.1:${PORT}` }), OPTS), { ok: true });
+  // The phone, through `tailscale serve` on 443: HTTPS, no port in the Origin.
+  assert.deepEqual(requestAllowed(req('POST', { host: 'laptop.tail1234.ts.net', origin: 'https://laptop.tail1234.ts.net' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: `100.94.221.98:${PORT}`, origin: `http://100.94.221.98:${PORT}` }), OPTS), { ok: true });
+});
+
+test('requestAllowed: with no Origin, Sec-Fetch-Site decides', () => {
+  // curl, src/cli.ts, the Telegram paths and the tests: neither header.
+  assert.deepEqual(requestAllowed(req('POST', { host: `127.0.0.1:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, 'sec-fetch-site': 'same-origin' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, 'sec-fetch-site': 'none' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, 'sec-fetch-site': 'cross-site' }), OPTS), {
+    ok: false, status: 403, error: 'cross-site request refused',
+  });
+  assert.equal(requestAllowed(req('POST', { host: `localhost:${PORT}`, 'sec-fetch-site': 'same-site' }), OPTS).ok, false);
+});
+
+test('requestAllowed: FOREMAN_BIND=all takes any Host, and Origin must match it', () => {
+  const all = { port: PORT, tailnet: null, bindAll: true };
+  assert.deepEqual(requestAllowed(req('GET', { host: '192.168.1.20:4177' }), all), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: 'foreman.lan' }), all), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: 'foreman.lan', origin: 'http://foreman.lan' }), all), { ok: true });
+  assert.equal(requestAllowed(req('POST', { host: 'foreman.lan', origin: 'http://evil.example' }), all).ok, false);
+  // Even wide open, a request with no Host at all is not one we can place.
+  assert.equal(requestAllowed(req('GET', {}), all).ok, false);
+});
+
+test('pathPermitted: at a root, under one, and never through ..', () => {
+  const roots = ['/Users/me/Projects', '/Users/me/work'];
+  assert.equal(pathPermitted('/Users/me/Projects', roots), true);
+  assert.equal(pathPermitted('/Users/me/Projects/foreman/src', roots), true);
+  assert.equal(pathPermitted('/Users/me/work', roots), true);
+  assert.equal(pathPermitted('/etc', roots), false);
+  assert.equal(pathPermitted('/Users/me', roots), false);
+  // A neighbour that merely shares a prefix is outside.
+  assert.equal(pathPermitted('/Users/me/Projects-backup', roots), false);
+  // Traversal is resolved before it is judged.
+  assert.equal(pathPermitted('/Users/me/Projects/../../../etc/passwd', roots), false);
+  assert.equal(pathPermitted('/Users/me/Projects/foreman/../other', roots), true);
+  assert.equal(pathPermitted('/Users/me/Projects/foreman', []), false);
+});

package/src/guard.ts

@@ -0,0 +1,131 @@
+/**
+ * Who is allowed to talk to Foreman, and from where.
+ *
+ * Foreman has no login: it trusts the network it listens on (loopback, and
+ * the tailnet when there is one). That trust is only worth anything if a
+ * request really comes from there, and two ordinary browser behaviours break
+ * it without any network access at all:
+ *
+ *  - DNS rebinding. A page on `evil.example` can point its own name at
+ *    127.0.0.1 and then fetch `http://evil.example:4177/runs` — same-origin
+ *    as far as the browser is concerned, so no CORS preflight, and the
+ *    response goes back to the attacker. The packets do arrive on loopback;
+ *    what gives it away is the Host header, which still says
+ *    `evil.example:4177`. Refusing every Host that is not a name Foreman
+ *    actually answers to closes it — hence 421 Misdirected Request.
+ *
+ *  - Cross-site writes. Any page the operator happens to visit can POST a
+ *    form or `fetch(..., {mode:'no-cors'})` at `http://localhost:4177/mkdir`.
+ *    The browser labels those: an `Origin` header on the request, or
+ *    `Sec-Fetch-Site: cross-site`. Unsafe methods are refused unless that
+ *    label says the request came from Foreman's own page.
+ *
+ * Non-browser callers — curl, `src/cli.ts`, the Telegram code paths, the
+ * tests — send neither header, and are left alone. This is a guard against
+ * the browser, not an authentication scheme; it does not pretend to keep out
+ * anyone who can already open a socket to the port.
+ */
+import type http from 'node:http';
+import path from 'node:path';
+import { underAnyRoot } from './policy.js';
+
+/** What a Host header may say, given the port and the tailnet. */
+interface GuardOpts {
+  port: number;
+  tailnet: { ip: string; dnsName?: string } | null;
+  /** `FOREMAN_BIND=all`: the operator opened it wide on purpose, so any Host is theirs. */
+  bindAll?: boolean;
+}
+
+export type GuardVerdict = { ok: true } | { ok: false; status: 421 | 403; error: string };
+
+/** Methods that cannot change anything, so a cross-site one is harmless. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/**
+ * The `host:port` strings Foreman answers to. The MagicDNS name is kept
+ * separately because `tailscale serve` may front it on 443 (or any other
+ * HTTPS port), so its port is whatever the proxy chose and cannot be checked.
+ */
+function expectedHosts(opts: GuardOpts): { exact: Set<string>; anyPort: Set<string> } {
+  const exact = new Set([
+    `localhost:${opts.port}`,
+    `127.0.0.1:${opts.port}`,
+    `[::1]:${opts.port}`,
+  ]);
+  if (opts.tailnet?.ip) exact.add(`${opts.tailnet.ip}:${opts.port}`);
+  const anyPort = new Set<string>();
+  if (opts.tailnet?.dnsName) anyPort.add(opts.tailnet.dnsName.toLowerCase());
+  return { exact, anyPort };
+}
+
+/** `laptop.ts.net:8443` → `laptop.ts.net`; `[::1]:4177` → `[::1]`. */
+function hostOnly(hostHeader: string): string {
+  if (hostHeader.startsWith('[')) return hostHeader.slice(0, hostHeader.indexOf(']') + 1);
+  const i = hostHeader.lastIndexOf(':');
+  return i > 0 ? hostHeader.slice(0, i) : hostHeader;
+}
+
+function hostRecognised(host: string, opts: GuardOpts): boolean {
+  const h = host.toLowerCase();
+  const { exact, anyPort } = expectedHosts(opts);
+  return exact.has(h) || anyPort.has(hostOnly(h));
+}
+
+/**
+ * Is this request one Foreman should answer? Host first (rebinding), then —
+ * for anything that can change state — the browser's own account of where the
+ * request came from.
+ */
+export function requestAllowed(
+  req: { method?: string; headers: http.IncomingHttpHeaders },
+  opts: GuardOpts,
+): GuardVerdict {
+  const host = typeof req.headers.host === 'string' ? req.headers.host.trim() : '';
+  if (!opts.bindAll) {
+    if (!host || !hostRecognised(host, opts)) return { ok: false, status: 421, error: 'unrecognised Host' };
+  } else if (!host) {
+    return { ok: false, status: 421, error: 'unrecognised Host' };
+  }
+
+  const method = (req.method ?? 'GET').toUpperCase();
+  if (SAFE_METHODS.has(method)) return { ok: true };
+
+  const origin = typeof req.headers.origin === 'string' ? req.headers.origin.trim() : '';
+  if (origin) {
+    return originAllowed(origin, host, opts)
+      ? { ok: true }
+      : { ok: false, status: 403, error: 'cross-site request refused' };
+  }
+  // No Origin: either a non-browser caller (curl, the CLI, the tests), or a
+  // browser that told us where it came from the other way. `same-origin` and
+  // `none` (typed in the address bar) are ours; `cross-site` and `same-site`
+  // are not.
+  const fetchSite = String(req.headers['sec-fetch-site'] ?? '').trim().toLowerCase();
+  if (!fetchSite || fetchSite === 'same-origin' || fetchSite === 'none') return { ok: true };
+  return { ok: false, status: 403, error: 'cross-site request refused' };
+}
+
+/** An Origin is ours when it is http/https at a host we answer to. */
+function originAllowed(origin: string, host: string, opts: GuardOpts): boolean {
+  let u: URL;
+  try { u = new URL(origin); } catch { return false; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  // With bindAll there is no list to check against, so the standard
+  // same-origin rule is the honest one: the Origin must be the Host.
+  if (opts.bindAll) {
+    const authority = u.host.toLowerCase();
+    return authority === host.toLowerCase();
+  }
+  return hostRecognised(u.host.toLowerCase(), opts);
+}
+
+/**
+ * May Foreman look at (or write into) `target`? True when it resolves to one
+ * of `roots` or somewhere beneath one. `path.resolve` collapses `..` first,
+ * so `~/Projects/../../etc` is judged as `/etc` and refused; containment
+ * itself is `underAnyRoot`, which is already the rule the permission cards use.
+ */
+export function pathPermitted(target: string, roots: Iterable<string>): boolean {
+  return underAnyRoot(path.resolve(target), roots);
+}

package/src/http-body.test.ts

@@ -0,0 +1,42 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  ATTACHMENT_BODY_LIMIT, BodyError, DEFAULT_BODY_LIMIT, bodyLimitFor, parseBody,
+} from './http-body.js';
+
+test('bodyLimitFor: only POST /attachments gets the large cap', () => {
+  assert.equal(bodyLimitFor('POST', '/attachments'), ATTACHMENT_BODY_LIMIT);
+  assert.equal(bodyLimitFor('post', '/attachments'), ATTACHMENT_BODY_LIMIT);
+  assert.equal(bodyLimitFor('GET', '/attachments'), DEFAULT_BODY_LIMIT);
+  assert.equal(bodyLimitFor('POST', '/mkdir'), DEFAULT_BODY_LIMIT);
+  assert.equal(bodyLimitFor('POST', '/attachments/extra'), DEFAULT_BODY_LIMIT);
+  assert.equal(bodyLimitFor(undefined, '/runs'), DEFAULT_BODY_LIMIT);
+});
+
+test('parseBody: an empty body is an empty object', () => {
+  assert.deepEqual(parseBody(''), {});
+  assert.deepEqual(parseBody('   '), {});
+  assert.deepEqual(parseBody(Buffer.alloc(0)), {});
+});
+
+test('parseBody: an object comes back as itself', () => {
+  assert.deepEqual(parseBody('{"a":1,"b":"x"}'), { a: 1, b: 'x' });
+  assert.deepEqual(parseBody(Buffer.from('{"nested":{"k":true}}')), { nested: { k: true } });
+});
+
+test('parseBody: JSON that is not an object has no fields to read', () => {
+  assert.deepEqual(parseBody('[1,2,3]'), {});
+  assert.deepEqual(parseBody('42'), {});
+  assert.deepEqual(parseBody('null'), {});
+  assert.deepEqual(parseBody('"hello"'), {});
+});
+
+test('parseBody: junk is the client’s fault, not a 500', () => {
+  assert.throws(() => parseBody('{bad'), (err: unknown) => {
+    assert.ok(err instanceof BodyError);
+    assert.equal(err.status, 400);
+    assert.equal(err.message, 'invalid JSON body');
+    return true;
+  });
+  assert.throws(() => parseBody('{"a":}'), BodyError);
+});

package/src/http-body.ts

@@ -0,0 +1,57 @@
+/**
+ * How much request body Foreman will read, and what a bad one costs.
+ *
+ * Every route reads its JSON into memory. Without a cap, one request with a
+ * long-running body holds the process's whole heap hostage — no authentication
+ * stands between a stray script and that, and the operator's other missions
+ * die with the server. So there is a cap, and exceeding it is a 413 rather
+ * than an OOM.
+ *
+ * The cap is per route rather than global because one route is legitimately
+ * huge: attachments arrive base64-encoded inside the JSON body, and
+ * `src/attachments.ts` already allows ten files of 10 MiB each — roughly
+ * 133 MiB on the wire once base64 has added its third. Every other route
+ * carries a mission brief or a settings object, which 1 MiB covers many times
+ * over.
+ */
+
+/** Enough for any brief, settings blob or model list; small enough to be free. */
+export const DEFAULT_BODY_LIMIT = 1 * 1024 * 1024;
+
+/** Ten 10 MiB files, base64-inflated, plus room for the JSON around them. */
+export const ATTACHMENT_BODY_LIMIT = 128 * 1024 * 1024;
+
+/** A body problem with the answer already decided: 400 for junk, 413 for too much. */
+export class BodyError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+    this.name = 'BodyError';
+  }
+}
+
+/** The cap for this route: the large one only where large bodies are the point. */
+export function bodyLimitFor(method: string | undefined, pathname: string): number {
+  const m = (method ?? '').toUpperCase();
+  return m === 'POST' && pathname === '/attachments' ? ATTACHMENT_BODY_LIMIT : DEFAULT_BODY_LIMIT;
+}
+
+/**
+ * The body as an object. An empty body is `{}` (routes read optional fields
+ * off it and validate for themselves), and so is valid JSON that is not one —
+ * an array, a number or a bare string has none of the named fields the
+ * handlers destructure, so it is the empty object as far as they can tell.
+ * Only unparseable input is an error, and it is the client's: 400, not a 500
+ * whose body is the text of a `SyntaxError`.
+ */
+export function parseBody(buf: Buffer | string): Record<string, unknown> {
+  const text = typeof buf === 'string' ? buf : buf.toString();
+  if (!text.trim()) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new BodyError(400, 'invalid JSON body');
+  }
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>) : {};
+}

package/src/memory.test.ts

@@ -0,0 +1,46 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { MEMORY_CAP_BYTES, memorySection, readMemory, scrubSecrets, writeMemory } from './memory.js';
+
+test('scrubSecrets removes what looks like a credential and keeps the line readable', () => {
+  const r = scrubSecrets([
+    'Run tests with: npm test',
+    'ANTHROPIC_API_KEY=sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123456789',
+    'GitHub token ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345 is in the CI',
+    'aws: AKIAIOSFODNN7EXAMPLE',
+    'Bearer: abcdefghijklmnopqrstuvwxyz1234567890',
+    'The port 8420 is taken by the preview server',
+  ].join('\n'));
+  assert.ok(r.redacted >= 4, String(r.redacted));
+  assert.match(r.text, /^Run tests with: npm test$/m);
+  assert.match(r.text, /^ANTHROPIC_API_KEY=\[redacted\]$/m);
+  assert.doesNotMatch(r.text, /ghp_ABCDEF/);
+  assert.doesNotMatch(r.text, /AKIAIOSFODNN7EXAMPLE/);
+  assert.match(r.text, /port 8420 is taken/);
+});
+
+test('writeMemory: full-page replace, secrets stripped, capped at a page or two, then readMemory sees it', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'memory-'));
+  const w = await writeMemory(dir, '# Notes\n- tests: npm test\n- API_TOKEN=abcdefghijklmnop1234\n');
+  assert.equal(w.redacted, 1); assert.equal(w.trimmed, false);
+  const m = await readMemory(dir);
+  assert.match(m.text, /- tests: npm test\n- API_TOKEN=\[redacted\]\n$/);
+  assert.ok(m.updatedAt);
+  const big = await writeMemory(dir, Array.from({ length: 2000 }, (_, i) => `- line ${i} about the project`).join('\n'));
+  assert.equal(big.trimmed, true);
+  assert.ok(big.bytes <= MEMORY_CAP_BYTES);
+  assert.ok((await readFile(path.join(dir, '.foreman', 'MEMORY.md'), 'utf8')).endsWith('\n'));
+});
+
+test('memorySection: the director is told to write an empty memory; workers and the planner get nothing for empty; all get the page otherwise', () => {
+  assert.match(memorySection('', 'director'), /empty\. Before you finish, write it with mcp__foreman__remember/);
+  assert.equal(memorySection('', 'worker'), '');
+  assert.equal(memorySection('', 'planner'), '');
+  const s = memorySection('- port 8420 is taken', 'worker');
+  assert.match(s, /PROJECT MEMORY — what earlier crews learned/);
+  assert.match(s, /---\n- port 8420 is taken\n---/);
+  assert.match(memorySection('x', 'planner'), /Ground your advice in it/);
+});