@snowyroad/braid 0.96.8 → 0.98.0

package/README.md

@@ -107,6 +107,7 @@ with `npx @snowyroad/braid` if you did not install globally.
 | `braid tools <readonly\|full> [name]` | Set what the agent may do when channel members ask (readonly = read + reply; full = run commands + edit files) |
 | `braid ipc <compat\|strict> [name]` | Set the IPC confinement profile for a saved agent |
 | `braid scope [name]` | Show the effective OS sandbox scope; `braid scope allow <agent> <host>` approves a custom model-endpoint host |
+| `braid git-auth <set\|show\|clear> <agent> ...` | Give a saved agent git access to one repository with a local fine-grained token (`set <agent> <owner/repo> --mode <autonomous\|pr-only> [--allow-workflows] [--allow-risk-paths] [--allow-public] --token-stdin`), or show or remove that grant. See [Giving an agent git access](#giving-an-agent-git-access-without-your-credentials) |
 | `braid service <install\|uninstall\|start\|stop\|restart\|status\|logs> [name]` | Run a saved agent as a background service (starts at login, restarts on crash) — see [docs/SERVICE-MODE.md](docs/SERVICE-MODE.md) |
 | `braid update` | Update the pinned service runtime and restart all installed services atomically |
 | `braid attach [name]` | Watch a running service's live activity over the local control socket (same machine) |
@@ -231,7 +232,7 @@ descendant process and cannot be shed.
   dirs** — `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube/config`, and the bridge's own
   credential store (`~/.braid`).
 - **Network:** a curated allow-list (provider API hosts, package registries, and
-  the major source-code hosts) so normal work keeps working; everything else is
+  read-only source-content hosts such as codeload.github.com) so normal work keeps working; everything else is
   blocked. Operator-extensible.
 - **Fail-closed:** in **full** tool mode the bridge REFUSES to start if the OS
   sandbox facility is unavailable, and tells you how to fix it. In read-and-reply
@@ -243,9 +244,11 @@ descendant process and cannot be shed.
   or the `BRAID_SCOPE_ALLOW_WRITE` / `BRAID_SCOPE_ALLOW_READ` / `BRAID_SCOPE_ALLOW_DOMAINS`
   env vars (see below). Credential directories (`~/.ssh`, `~/.aws`, `~/.config/gh`,
   and the rest of the protected inventory) are reserved and CANNOT be granted: a
-  grant that lands inside one is refused at startup with a SCOPE ERROR. A tool CLI
-  that only needs network still works inside the jail (`github.com` is in the default
-  allow-list); grant a project data directory, never a credential store.
+  grant that lands inside one is refused at startup with a SCOPE ERROR. Code hosts
+  (github.com, gitlab.com, bitbucket.org) are NOT reachable from inside the jail:
+  authenticated git goes through the bridge's git tools. Grant a project data directory, never a credential store.
+
+**Code hosts are not reachable from the jail.** `github.com`, `api.github.com`, `gitlab.com` and `bitbucket.org` are a reserved set: an `--allow-domain` or `scope.network.allowedDomains` entry that reaches them is refused at startup. To accept that risk for one agent (for example, `git+https` dependencies during installs) run `braid scope allow-code-hosts <agent>`; the startup banner then carries a warning. The agent's own `git` runs with credential helpers disabled, so it cannot read your `gh` or keychain credentials. To let an agent push, fetch and open pull requests without those credentials, see [Giving an agent git access](#giving-an-agent-git-access-without-your-credentials).
 
 - **Unix socket access (Linux):** on Linux, seccomp-bpf cannot filter Unix sockets
   by path. The default `compat` IPC profile allows all pathname sockets. The `strict`
@@ -253,6 +256,27 @@ descendant process and cannot be shed.
   env-var hygiene to block common IPC paths. See [docs/ipc-profiles.md](docs/ipc-profiles.md)
   for the full profile reference, support matrix, and selection commands.
 
+### Giving an agent git access (without your credentials)
+
+Code hosts are not reachable from inside the sandbox, and the agent's own `git`
+cannot use your `gh` login or keychain. To let an agent push, fetch and open pull
+requests, give it a **grant** for one repository:
+
+- **Braid GitHub App (recommended):** in the web app, Settings > Integrations installs
+  the Braid App on the repositories you choose; then Agents > your agent > Git access
+  adds a repository and picks the mode. The Braid server mints a 1-hour token narrowed
+  to that repository each time the agent needs one; the agent never sees it.
+- **Local token (fallback):** `braid git-auth set <agent> <owner/repo> --mode <autonomous|pr-only> --token-stdin`
+  with a fine-grained token scoped to that repository (Contents and Pull requests
+  read/write, no Workflows). Stored under `~/.braid`, which the jail cannot read.
+
+Modes: **autonomous** pushes to any branch, opens and merges pull requests, and never
+waits for a human. **pr-only** pushes only to `braid/<agent>/*` branches and opens draft
+pull requests for a human to merge. In both modes pushes are fast-forward only, never
+delete or tag, and `.github/workflows` changes need the "allow workflow changes" toggle.
+The agent uses the `braid_git_status`, `braid_git_fetch`, `braid_git_push`, `braid_open_pr`
+and `braid_merge_pr` tools; Braid runs the git commands outside the sandbox.
+
 **Requirements:** macOS needs `ripgrep` (`brew install ripgrep`). Linux needs
 `bubblewrap`, `socat`, and `ripgrep`. On an unsupported platform (e.g. Windows) the
 bridge fails closed to read-and-reply.

package/dist/{chunk-QHWKKDPN.js → chunk-3SHZYLWH.js}

@@ -400,7 +400,7 @@ var InviteExpiredError = class extends Error {
   }
 };
 async function redeemInvite(relayHttpUrl, code) {
-  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-3WYFRJZR.js");
+  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-7QNDIXBN.js");
   const r = await boundedJsonFetch2(`${relayHttpUrl.replace(/\/$/, "")}/invites/redeem`, {
     method: "POST",
     headers: { "content-type": "application/json" },
@@ -492,7 +492,7 @@ function validateReplacementToken(newToken, currentToken, nowMs = Date.now()) {
   return { ok: true };
 }
 async function mintAccessToken(relayHttpUrl, agentKey, fetchFn = fetch, dpopProof) {
-  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-3WYFRJZR.js");
+  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-7QNDIXBN.js");
   const r = await boundedJsonFetch2(`${relayHttpUrl.replace(/\/$/, "")}/agents/token`, {
     method: "POST",
     headers: {
@@ -672,7 +672,7 @@ function verifyWin32Acl(target, sid, deps, userName = "") {
   }
   return unexpected;
 }
-function assertKeystorePerms(dir, agentFile, deps) {
+function assertKeystorePerms(dir, agentFile, deps, extraSecretFiles = []) {
   const platform = deps?.platform ?? process.platform;
   if (platform === "win32") {
     const d = deps ?? productionWin32Deps();
@@ -688,6 +688,11 @@ function assertKeystorePerms(dir, agentFile, deps) {
     if (filePresent) {
       verifyWin32Acl(agentFile, sid, d, userName);
     }
+    for (const extra of extraSecretFiles) {
+      if (!extra || !fsExists(extra)) continue;
+      applyWin32Acl(extra, sid, "file", d);
+      verifyWin32Acl(extra, sid, d, userName);
+    }
     return;
   }
   try {
@@ -716,6 +721,21 @@ function assertKeystorePerms(dir, agentFile, deps) {
   } catch (err) {
     if (err instanceof KeystorePermsError) throw err;
   }
+  for (const extra of extraSecretFiles) {
+    try {
+      const emode = statSync(extra).mode & 511;
+      if ((emode & 63) !== 0) {
+        throw new KeystorePermsError(
+          `[braid] refusing to start: a stored secret file is readable by other users on this machine.
+  path : ${extra}
+  mode : ${emode.toString(8).padStart(3, "0")} (expected 600)
+  fix  : chmod 600 ${extra}`
+        );
+      }
+    } catch (err) {
+      if (err instanceof KeystorePermsError) throw err;
+    }
+  }
 }
 function configDir(env = process.env) {
   const override = env.BRAID_CONFIG_DIR?.trim();
@@ -812,6 +832,7 @@ function parseScope(v) {
     if (allowedDomains) net.allowedDomains = allowedDomains;
     const deniedDomains = strArr(n.deniedDomains);
     if (deniedDomains) net.deniedDomains = deniedDomains;
+    if (typeof n.allowCodeHosts === "boolean") net.allowCodeHosts = n.allowCodeHosts;
     if (Object.keys(net).length > 0) out.network = net;
   }
   return Object.keys(out).length > 0 ? out : void 0;
@@ -1049,6 +1070,13 @@ function pinEndpoint(dir, agentName, pin) {
   agent.pinnedEndpoints = next;
   saveAgent(dir, agent);
 }
+function setScopeAllowCodeHosts(dir, agentName, value) {
+  const entry = loadAgent(dir, agentName);
+  const agent = entry.agent;
+  const network = { ...agent.scope?.network ?? {}, allowCodeHosts: value };
+  agent.scope = { ...agent.scope ?? {}, network };
+  saveAgent(dir, agent);
+}
 function updateAgentWorkspace(dir, agentName, info) {
   try {
     const entry = loadAgent(dir, agentName);
@@ -2832,13 +2860,44 @@ var DEFAULT_ALLOWED_DOMAINS = [
   // Crates.io
   "crates.io",
   "static.crates.io",
-  // Source hosts
+  // Source hosts: READ-ONLY content delivery only. The code-host write paths
+  // (github.com, api.github.com, gitlab.com, bitbucket.org) left this list on
+  // 2026-10-06 (git gateway D12/G2): with them present, an injected agent could
+  // push private files to an attacker's repo using an attacker-supplied token,
+  // no operator credential needed. Authenticated git goes through the bridge's
+  // git gateway tools; see RESERVED_CODE_HOST_DOMAINS for the enforced floor.
+  "codeload.github.com",
+  "*.githubusercontent.com"
+];
+var RESERVED_CODE_HOST_DOMAINS = [
   "github.com",
   "*.github.com",
-  "*.githubusercontent.com",
   "gitlab.com",
-  "bitbucket.org"
+  "*.gitlab.com",
+  "bitbucket.org",
+  "*.bitbucket.org"
 ];
+var RESERVED_CODE_HOST_READ_ONLY = /* @__PURE__ */ new Set(["codeload.github.com"]);
+function codeHostConflicts(allowed) {
+  const out = [];
+  for (const a of allowed) {
+    const d = a.domain.trim().toLowerCase().replace(/\.$/, "");
+    if (RESERVED_CODE_HOST_READ_ONLY.has(d)) continue;
+    for (const r of RESERVED_CODE_HOST_DOMAINS) {
+      const base = r.startsWith("*.") ? r.slice(2) : r;
+      const isAllMatch = d === "*";
+      const isReservedItself = d === r || d === base;
+      const isSubdomainOfReservedWildcard = r.startsWith("*.") && d.endsWith("." + base);
+      const isBroaderWildcard = d.startsWith("*.") && (base === d.slice(2) || base.endsWith("." + d.slice(2)));
+      const hit = isAllMatch || isReservedItself || isSubdomainOfReservedWildcard || isBroaderWildcard;
+      if (hit) {
+        out.push({ domain: a.domain, source: a.source, reservation: r });
+        break;
+      }
+    }
+  }
+  return out;
+}
 var PROVIDER_PATHS = {
   "claude-code": ["~/.claude", "~/.claude.json"],
   codex: ["~/.codex"],
@@ -3022,6 +3081,24 @@ Narrow the grant to a path outside the protected set. (Ancestor grants like "~"
     ...scope.network?.deniedDomains ?? [],
     ...parseEnvList(env["BRAID_SCOPE_DENY_DOMAINS"])
   ]);
+  const allowCodeHosts = scope.network?.allowCodeHosts === true;
+  if (!disabled && !allowCodeHosts) {
+    const labelledDomains = [
+      ...(scope.network?.allowedDomains ?? []).map((domain) => ({ domain, source: "scope.network.allowedDomains" })),
+      ...(cfg.derivedAllowedDomains ?? []).map((domain) => ({ domain, source: "derived model endpoint" })),
+      ...parseEnvList(env["BRAID_SCOPE_ALLOW_DOMAINS"]).map((domain) => ({ domain, source: "BRAID_SCOPE_ALLOW_DOMAINS" })),
+      ...(cfg.scopeFlags?.allowDomains ?? []).map((domain) => ({ domain, source: "--allow-domain" }))
+    ];
+    const hits = codeHostConflicts(labelledDomains);
+    if (hits.length > 0) {
+      const detail = hits.map((h) => `  - ${h.source}: "${h.domain}" is a code host (reserved: ${h.reservation})`).join("\n");
+      throw new Error(
+        `[braid] SCOPE ERROR: a network grant reaches a code host and was refused:
+${detail}
+The sandboxed agent must not reach code hosts directly (an injected agent could push private files anywhere on that host). Use the Braid git tools for authenticated git, or run \`braid scope allow-code-hosts <agent>\` to accept the exfiltration risk for this agent.`
+      );
+    }
+  }
   function describe() {
     const lines = [];
     if (disabled) {
@@ -3042,6 +3119,9 @@ Narrow the grant to a path outside the protected set. (Ancestor grants like "~"
       lines.push(`[scope] provider paths (writable): ${providerPaths.join(", ")}`);
     }
     lines.push(`[scope] allowed domains (${allowedDomains.length}): ${allowedDomains.slice(0, 5).join(", ")}${allowedDomains.length > 5 ? " ..." : ""}`);
+    if (allowCodeHosts) {
+      lines.push("[scope] WARNING: direct code-host egress is ON for this agent (exfiltration path accepted by the owner via `braid scope allow-code-hosts`)");
+    }
     if ((cfg.derivedAllowedDomains ?? []).length > 0) {
       lines.push(`[scope] model endpoints (derived): ${(cfg.derivedAllowedDomains ?? []).join(", ")}`);
     }
@@ -5460,6 +5540,63 @@ var RelayClient = class _RelayClient {
     const body = r.json;
     return Array.isArray(body?.emojis) ? body.emojis.filter((e) => typeof e === "string") : [];
   }
+  /** Git gateway (D4): the agent's active app grants, never tokens. Malformed entries are
+   *  skipped, unknown fields dropped. Returns null on a non-2xx or malformed body (never throws),
+   *  [] only for a genuinely empty list. */
+  async fetchGitGrants() {
+    const r = await this.httpJson("/agents/me/git-grants", { requestClass: "relay.git.grants" });
+    if (!r.ok) return null;
+    const body = r.json;
+    if (!Array.isArray(body?.grants)) return null;
+    const out = [];
+    for (const g of body.grants) {
+      if (!g || typeof g.id !== "string" || typeof g.repo !== "string") continue;
+      if (g.mode !== "autonomous" && g.mode !== "pr-only") continue;
+      const slash = g.repo.indexOf("/");
+      if (slash <= 0 || slash === g.repo.length - 1) continue;
+      out.push({
+        id: g.id,
+        source: "app",
+        repoOwner: g.repo.slice(0, slash),
+        repoName: g.repo.slice(slash + 1),
+        mode: g.mode,
+        allowWorkflows: g.allowWorkflows === true,
+        allowRiskPaths: g.allowRiskPaths === true,
+        allowPublic: g.allowPublic === true
+      });
+    }
+    return out;
+  }
+  /** Git gateway (D4): mint the repo-narrowed 1h token for ONE grant. The response body
+   *  carries the token: never log it, never put it in an error message. Null on any non-2xx
+   *  (409 grant_changed, 404 grant_not_found) or malformed body. */
+  async mintGitToken(grantId) {
+    const id = this.pathId(grantId, "grantId");
+    if (id === null) return null;
+    const r = await this.httpJson(`/agents/me/git-grants/${id}/token`, {
+      method: "POST",
+      body: JSON.stringify({}),
+      requestClass: "relay.git.mint",
+      timeoutMs: 2e4
+    });
+    if (!r.ok) return null;
+    const b = r.json;
+    if (typeof b?.token !== "string" || !b.token || typeof b.repo !== "string") return null;
+    if (b.mode !== "autonomous" && b.mode !== "pr-only") return null;
+    const expiresAt = typeof b.expiresAt === "string" ? Date.parse(b.expiresAt) : NaN;
+    if (!Number.isFinite(expiresAt)) return null;
+    return {
+      token: b.token,
+      expiresAt,
+      private: typeof b.private === "boolean" ? b.private : null,
+      defaultBranch: typeof b.defaultBranch === "string" ? b.defaultBranch : null,
+      repo: b.repo,
+      mode: b.mode,
+      allowWorkflows: b.allowWorkflows === true,
+      allowRiskPaths: b.allowRiskPaths === true,
+      allowPublic: b.allowPublic === true
+    };
+  }
   /** Post a bounded-flow reply (turn or synthesis) to the flow-scoped endpoint.
    *  agentId MUST be the agent NAME — the relay's flow gate resolves turn ownership and
    *  synthesis role via resolveAgentUUID (a name lookup); a UUID resolves to uuid.Nil -> 403. */
@@ -5701,17 +5838,26 @@ function brokerSocketPath(uuid, platform = process.platform) {
 var SourceBroker = class {
   /** `platform` injected so the win32 named-pipe branch is unit-testable on a POSIX host
    *  (same seam as startControlSocket / controlSocketPath). */
-  constructor(channelId, reader, platform = process.platform) {
+  constructor(channelId, reader, platform = process.platform, gateway) {
     this.channelId = channelId;
     this.reader = reader;
     this.platform = platform;
+    this.gateway = gateway;
   }
   channelId;
   reader;
   platform;
+  gateway;
   server = null;
   token = randomBytes(24).toString("hex");
   socketPath = "";
+  /** D15: git routes are disabled while a lisa fresh turn runs on this channel. A depth
+   *  counter, so overlapping fresh turns keep git off until the LAST one finishes:
+   *  false increments, true decrements (never below 0), enabled only at depth 0. */
+  gitDisabledDepth = 0;
+  setGitEnabled(enabled) {
+    this.gitDisabledDepth = Math.max(0, this.gitDisabledDepth + (enabled ? -1 : 1));
+  }
   async start() {
     if (this.server) throw new Error("SourceBroker already started");
     const isWin32 = this.platform === "win32";
@@ -5751,6 +5897,9 @@ var SourceBroker = class {
   // blind critic, it would silently leak the transcript the relay's read-filter is
   // deliberately withholding (D9/G2b) and defeat critic blindness. Do not add a
   // channel/flow message-read route here without addressing this.
+  // The /git/ routes (git gateway, D6/D7) are write and egress routes; they ARE gated
+  // off lisa fresh turns: ChannelSession.onLisaFreshTurn calls setGitEnabled(false)
+  // for the turn's duration, so a critic or builder round gets 403 git_disabled_for_turn (D15).
   async handle(req, res) {
     const send = (status, body2) => {
       const s = JSON.stringify(body2);
@@ -6002,6 +6151,22 @@ var SourceBroker = class {
         const r = await this.reader.appendCanvasSection(this.channelId, heading, content);
         return send(r.status, r.json ?? { ok: r.ok });
       }
+      if (req.url?.startsWith("/git/")) {
+        if (!this.gateway) return send(404, { error: "unknown route" });
+        if (this.gitDisabledDepth > 0) return send(403, { error: "git_disabled_for_turn", text: "Git tools are unavailable during this turn." });
+        const str = (v) => typeof v === "string" ? v : void 0;
+        const pathArg = str(body.path);
+        if (req.url === "/git/pr/merge") {
+          if (!(typeof body.number === "number" && Number.isInteger(body.number) && body.number > 0)) return send(400, { error: "invalid_number", text: "number must be a whole pull request number." });
+          if (body.method !== void 0 && !(typeof body.method === "string" && ["merge", "squash", "rebase"].includes(body.method))) {
+            return send(400, { error: "invalid_method", text: "method must be merge, squash or rebase." });
+          }
+        }
+        const result = req.url === "/git/status" ? await this.gateway.status(this.channelId, { path: pathArg }) : req.url === "/git/fetch" ? await this.gateway.fetch(this.channelId, { path: pathArg }) : req.url === "/git/push" ? await this.gateway.push(this.channelId, { path: pathArg, branch: str(body.branch) ?? "", sha: str(body.sha) }) : req.url === "/git/pr/open" ? await this.gateway.openPr(this.channelId, { path: pathArg, branch: str(body.branch) ?? "", title: str(body.title) ?? "", body: str(body.body), base: str(body.base) }) : req.url === "/git/pr/merge" ? await this.gateway.mergePr(this.channelId, { number: Number(body.number), method: str(body.method) }) : null;
+        if (!result) return send(404, { error: "unknown route" });
+        if (result.ok) return send(200, { ...result.data ?? {}, ok: true, text: result.text });
+        return send(result.status, { error: result.code, text: result.text });
+      }
       return send(404, { error: "unknown route" });
     } catch (err) {
       return send(500, { error: String(err) });
@@ -6225,6 +6390,29 @@ function formatRateLimitNotice(agentName, provider, message) {
   ];
 }
 
+// src/gitEnv.ts
+var AGENT_GIT_ENV = {
+  GIT_TERMINAL_PROMPT: "0",
+  GCM_INTERACTIVE: "never",
+  GIT_CONFIG_NOSYSTEM: "1"
+};
+var AGENT_GIT_CONFIG = [
+  ["credential.helper", ""],
+  ["core.askPass", ""]
+];
+function withAgentGitEnv(extra, baseGitConfigCount = process.env.GIT_CONFIG_COUNT) {
+  const out = { ...extra, ...AGENT_GIT_ENV };
+  let n = Number.parseInt(extra.GIT_CONFIG_COUNT ?? baseGitConfigCount ?? "0", 10);
+  if (!Number.isFinite(n) || n < 0) n = 0;
+  for (const [key, value] of AGENT_GIT_CONFIG) {
+    out[`GIT_CONFIG_KEY_${n}`] = key;
+    out[`GIT_CONFIG_VALUE_${n}`] = value;
+    n++;
+  }
+  out.GIT_CONFIG_COUNT = String(n);
+  return out;
+}
+
 // src/adapter.ts
 function defaultToolPolicy() {
   return { mode: "readonly", configDirAbs: resolve2(configDir(process.env)), allowReadAbs: [] };
@@ -6324,6 +6512,10 @@ function resolvePathBinary(binary, hint) {
   return found;
 }
 function launchSpecFor(agent) {
+  const spec = launchSpecForProvider(agent);
+  return { ...spec, env: withAgentGitEnv(spec.env ?? {}) };
+}
+function launchSpecForProvider(agent) {
   const cwd = process.cwd();
   switch (agent) {
     case "claude-code": {
@@ -6468,7 +6660,7 @@ function interactiveHandoffSupported(agent) {
 }
 function interactiveResumeSpecFor(agent, sessionId, cwd) {
   const build = HANDOFF_RESUME_SPECS[agent];
-  return build ? build(sessionId, cwd) : null;
+  return build ? { ...build(sessionId, cwd), env: withAgentGitEnv({}) } : null;
 }
 var defaultAcpClientFactory = (launch) => new AcpClient(launch);
 var MAX_CONSECUTIVE_RESTARTS = 3;
@@ -7911,6 +8103,9 @@ export {
   sanitizeForTty,
   restoreTerminal,
   isShellSafeName,
+  productionWin32Deps,
+  resolveCurrentUser,
+  applyWin32Acl,
   assertKeystorePerms,
   configDir,
   readPathWithFallback,
@@ -7921,6 +8116,7 @@ export {
   loadAgent,
   acquireAgentLock,
   pinEndpoint,
+  setScopeAllowCodeHosts,
   updateAgentWorkspace,
   isFilesystemRoot,
   narrowestMode,
@@ -7950,6 +8146,7 @@ export {
   scopedLaunch,
   resetScope,
   sandboxInstaller,
+  withAgentGitEnv,
   resolveClaudeBinary,
   describeClaudeBinary,
   interactiveHandoffSupported,