@snowyroad/braid 0.97.0 → 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) |
@@ -247,7 +248,7 @@ descendant process and cannot be shed.
   (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.
+**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`
@@ -255,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-2OHYN3KD.js → chunk-3SHZYLWH.js}

@@ -400,7 +400,7 @@ var InviteExpiredError = class extends Error {
   }
 };
 async function redeemInvite(relayHttpUrl, code) {
-  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-7LMCYNHB.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-7LMCYNHB.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();
@@ -5520,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. */
@@ -5761,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";
@@ -5811,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);
@@ -6062,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) });
@@ -7998,6 +8103,9 @@ export {
   sanitizeForTty,
   restoreTerminal,
   isShellSafeName,
+  productionWin32Deps,
+  resolveCurrentUser,
+  applyWin32Acl,
   assertKeystorePerms,
   configDir,
   readPathWithFallback,