@bondsmith/bondsmithd 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# bondsmithd
+
+Local daemon that manages tmux-backed terminal sessions on your machine and exposes them to the
+Bondsmith web app over a signed WebSocket protocol. Runs entirely on your own machine — no code,
+terminal output, or session data is ever sent anywhere except the Bondsmith account you explicitly
+pair it with.
+
+## Install
+
+```bash
+npm install -g @bondsmith/bondsmithd
+```
+
+Requires Node >=24 and `tmux` (`brew install tmux` on macOS). `node-pty`, the one native
+dependency, ships prebuilt binaries for macOS (Intel and Apple Silicon) and installs without
+compiling anything on supported platforms.
+
+## Running
+
+```bash
+bondsmithd
+```
+
+On first run, `bondsmithd` prints a pairing code and URL — confirm it from your Bondsmith account
+to trust this machine. After that, `bondsmithd` just needs to be running for the Bondsmith web app
+to see and control sessions on this machine.
+
+Start it from a normal interactive shell, not a stripped-down context (a bare `launchd`/login-item
+invocation, a minimal CI shell, etc.). The daemon passes its own `process.env` through to every
+tmux session it creates, so sessions inherit your real `PATH`, version manager shims
+(`mise`/`nvm`/etc.), and tools like `claude` or `pnpm` — the same environment you'd get opening a
+new terminal tab. A stripped environment at daemon-start time means the same stripped environment
+in every session it launches.
+
+Environment variables (all optional):
+
+```
+PORT=4577                                    # defaults to 4577
+ALLOWED_ORIGINS=https://app.bondsmith.dev
+BONDSMITH_RELAY_URL=wss://relay.bondsmith.dev # defaults to a local-only address; set this for a real install
+```
+
+`BONDSMITH_DEV_TUNNEL_TOKEN` also exists but only applies to the legacy direct-connection path
+(`BONDSMITH_RELAY_ENABLED=false`) — should not be set by hand for a normal install.
+
+## What it does
+
+- Creates, lists, attaches to, and stops tmux sessions prefixed `bondsmith-*`.
+- Never enumerates or manages tmux sessions it didn't create.
+- Attaches a real PTY (`tmux attach-session`) so whatever is running inside (`claude`, `opencode`,
+  `bash`, anything) behaves exactly as it would in a normal terminal.
+- Keeps tmux itself as the only source of truth — no database. Restarting the daemon rediscovers
+  running sessions from tmux.
+
+## Production connectivity (current status)
+
+`bondsmithd` connects outbound to the Bondsmith relay by default (`BONDSMITH_RELAY_ENABLED=true`),
+which is what a production account actually uses — no dev-tunnel token involved. Point
+`BONDSMITH_RELAY_URL` at `wss://relay.bondsmith.dev` for a real install (see "Environment
+variables" above); it defaults to a local-only address for monorepo development.
+
+The dev-tunnel-token requirement only applies to the legacy direct-connection path
+(`BONDSMITH_RELAY_ENABLED=false`), which still 404s the token-handoff route in production by
+design — that path is for local debugging only, not a real install.
+
+## Security model
+
+- Every connection is validated against the daemon's `ALLOWED_ORIGINS` and completes a
+  cryptographic handshake — a fresh, single-use, daemon-issued challenge signed by a controller key
+  the daemon has explicitly and locally trusted. See "Pairing" above for how a controller key
+  becomes trusted in the first place.
+- Every sensitive command AND every sensitive read (session listing, workspace status, diffs, plus
+  every state-changing action) must arrive as part of that same authenticated, signed connection —
+  read access is not treated as lower-risk than write access, since a read can expose session
+  metadata and source code just as much as a write can change it.
+- Replay protection is connection-scoped and lives entirely in the daemon's memory — nothing about
+  it is persisted to disk, so a browser reload or reconnect always starts a clean, independent
+  session.
+- Revoking trust for a controller (from your Bondsmith account) closes its active connections
+  within a bounded time, whether or not it's mid-session.
+- Only ever touches tmux sessions it created itself, named `bondsmith-<uuid>`.
+- All tmux/PTY invocations use argv arrays, never shell string interpolation.
+- PTY/terminal contents are never logged or persisted by the daemon itself.
+- This is not a confidentiality boundary against a compromised network path between your machine
+  and Bondsmith Cloud — the design assumes source, protocol behavior, and the daemon binary itself
+  are fully observable by an attacker, and derives its guarantees from cryptographic signing and
+  local trust decisions, never from secrecy of the code. The dev-tunnel admission token described
+  under "Production connectivity" above is the one exception (a genuine shared-secret mechanism),
+  but it only applies to the legacy direct-connection path, not the relay path a real install uses.
+
+Full design detail: `docs/architecture/local-sessions-auth-decision-log.md` in the
+[bondsmith repository](https://github.com/ellis-river-ventures/bondsmith).
+
+## Contributing / developing bondsmithd itself
+
+This section is for people working in the `bondsmith` monorepo, not for installed users of the
+published package.
+
+```bash
+pnpm --filter @bondsmith/bondsmithd dev
+```
+
+This is deliberately **not** part of `pnpm dev` / `turbo dev` — it needs tmux and a native module
+on the host, and it's opt-in tooling, not a service the rest of the stack depends on.
+
+**node-pty is pinned to `1.2.0-beta.15`, not the `1.1.0` stable release.** `1.1.0`'s prebuilt
+`darwin-arm64` binary fails immediately with `posix_spawnp failed` on Node 24 (verified on macOS
+15/Apple Silicon) — any spawn, not just tmux, crashes the whole daemon process. The `1.2.0-beta`
+line has a prebuild that works correctly on Node 24. Don't downgrade to a `node-pty` stable release
+without first confirming `pty.spawn(...)` actually works on your Node version.
+
+For local development, create a `.env` file in this directory (or export the vars directly):
+
+```
+PORT=4577
+ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:4000,http://127.0.0.1:4000
+```
+
+Port 4000 is included because that's where `make dev`'s Docker Compose stack serves the web app
+(`docker-compose.dev.yml` maps `4000:4000`); port 3000 covers running `apps/web` directly via
+`pnpm dev:web` instead.
+
+The web app needs `NEXT_PUBLIC_LOCAL_AGENT_DAEMON_URL=ws://127.0.0.1:4577` set wherever it reads
+its env from — under `make dev` that's the repo-root `.env.local` (referenced by
+`docker-compose.dev.yml`'s `env_file`), not `apps/web/.env.local`.
+
+### Publishing
+
+`pnpm --filter @bondsmith/bondsmithd build` bundles `@bondsmith/local-agent-protocol` directly into
+`dist/index.js` (see `tsup.config.ts`'s `noExternal`) — the published package has no `workspace:*`
+dependency and no runtime dependency on that package existing on any registry. Only `dist/index.js`,
+`package.json`, and this README are published (see `package.json`'s `files`); sourcemaps and every
+other repo file are excluded.
+
+### Non-goals (current scope)
+
+No cloud execution, no multi-machine support, no session sharing, no Claude/OpenCode API
+integration, no agent-output parsing or detection, no terminal history storage or session
+recording.