@snowyroad/braid 0.94.0 → 0.96.0

package/README.md

@@ -192,23 +192,30 @@ OWN login: the bridge never sends a model API key. Provider-specific notes:
 ## Security model
 
 - **Read and reply only by default.** Unless you opt in, tool permission requests
-  that execute, write, edit, delete, or fetch are denied. Your agent can read
-  context and reply with text, nothing more. Honest caveat: read-and-reply still
-  permits READING non-credential local files your agent's own permissions allow,
-  and what it reads can appear in its channel replies. Run the bridge in a
-  directory you are comfortable sharing from.
+  that execute, write, edit, delete, or fetch are denied. Your agent can read files
+  under the directory you started the bridge in (plus any `--allow-read` paths) and
+  reply with text, nothing more. Credential files (`~/.ssh`, `~/.aws`, `~/.npmrc`,
+  `~/.config/gh`, `~/.docker/config.json`, git credentials, shell history, your
+  agent's own login file, and more) are never readable through your agent's file
+  tools in either mode. Read results are never sent to Braid as activity content
+  (only file names and edit diffs or command output appear in the activity view);
+  what your agent quotes back in its own chat reply is bounded by the read
+  confinement above.
 - **Full access is an explicit opt-in,** chosen at the first-run prompt or with
   `braid tools full <name>`. Understand what that means: remote messages can drive
   local tool use on your machine. The bridge prints a warning at startup in this
   mode. (Advanced: the `BRAID_TOOL_MODE` env var, `readonly`|`full`, overrides the
-  saved choice for one run and is never persisted.)
+  saved choice for one run and is never persisted.) Reads outside the launch
+  directory are allowed in full access, except the credential files above.
 - **In both modes** the bridge denies agent access to its credential store (`~/.braid`
   or `$BRAID_CONFIG_DIR`) for permission requests it sees, strips relay credentials
   from the agent subprocess environment, and treats all channel content as untrusted
   data in prompts (fenced, never as instructions).
 - **Honest limitation:** the bridge can only gate permission requests your agent
   surfaces. Your agent's own permission settings apply first; anything your agent is
-  configured to auto-allow never reaches the bridge's policy.
+  configured to auto-allow never reaches the bridge's policy. For defense in depth,
+  Claude Code users can also set `permissions.blockReadsOutsideWorkingDirectories`
+  in their own settings to enforce the same boundary at the agent level.
 
 ## OS sandbox (scope)
 
@@ -234,9 +241,11 @@ descendant process and cannot be shed.
   write, and reach.
 - **Widen it:** add paths/domains via the `scope` block on the saved agent config,
   or the `BRAID_SCOPE_ALLOW_WRITE` / `BRAID_SCOPE_ALLOW_READ` / `BRAID_SCOPE_ALLOW_DOMAINS`
-  env vars (see below). *Granting a tool CLI:* to let the agent run `gh`, add
-  `~/.config/gh` to `allowRead` — `github.com` is already in the default network
-  allow-list, so the CLI works inside the jail.
+  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.
 
 - **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`
@@ -297,6 +306,16 @@ Provider ACP adapters (Claude Code, Codex, Gemini) are exact version-pinned and
 fetched from the npm registry on first use of that provider. The `grok` CLI is not
 an npm package; you install it yourself and the bridge resolves it from `PATH`.
 
+### Push guard + advisories (contributors)
+
+`pnpm install` sets `core.hooksPath` to `.githooks`, whose `pre-push` hook (1) scans
+exactly the commits being pushed with gitleaks against `.gitleaks.toml`, so a
+secret-looking literal never leaves your machine, and (2) refuses a push to `main`
+while `ci.yml` or `security.yml` is still running or is red. To push the one fix for
+a red main: `BRAID_FIX_RED=1 git push ...`, then wait for the gates. Emergency bypass:
+`BRAID_PUSH_FORCE=1`. Dependency advisories are checked daily by `advisories.yml` and
+surface as a GitHub issue labeled `advisory`, never as a red on an unrelated push.
+
 ## Environment variables
 
 Every variable below also accepts its pre-rename `ARP_*` twin as a fallback <!-- braid-rename: env-fallback -->