ghostbus 0.5.0 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.5.3 — 2026-10-11
+
+Security hardening, round 2 — the layer under the v0.5.2 defaults. v0.5.2 made enforcement the default; this round removes the sharp edges an attacker could still lean on: non-timing-safe secret compares, unthrottled key guessing at the hosted layer, unbounded request bodies, framable HTML pages, world-readable data files, and internal error text leaking to clients.
+
+- **Timing-safe secret comparisons everywhere** — the hosted router compared workspace keys with `sha256(given) === meta.keyHash` (plain `===` on a digest), and the core compared agent-token hashes the same way. Both now use `crypto.timingSafeEqual` over the digests (new exported `hashMatches` in `src/handler.mjs`, shared by the router, the core token check, and the serverless pack, whose `wsKeyOk` had the same plain compare). A full-codebase audit found no other secret comparisons.
+- **Failed-auth throttle at the hosted layer** (`src/hosted-server.mjs`) — the handler's 300 req/min limiter only throttles traffic already inside a workspace; nothing slowed down guessing admin or workspace keys. Now: 30 failed auth attempts per minute per IP → `429` on the admin surface and on workspace routes until the window rolls. Successful auth never counts; `/health` and `/probe` stay open so an operator can watch an attack happen.
+- **Request bodies capped at 1 MB** (`readJsonBody` in `src/handler.mjs`) — both body readers accumulated without a cap (past a 5 MB socket-destroy with no useful response). One shared reader now enforces a commented `MAX_BODY_BYTES = 1_000_000` on hosted admin routes, in-workspace routes, and the single relay; over the cap the client gets a clean `413` JSON error and the socket is dropped after the response. File contents travel as JSON in GhostBus, so legitimate traffic fits comfortably; a workspace *import* over 1 MB must be restored from a state file / the CLI instead of over HTTP (stated in `docs/hosted.md`).
+- **HTML pages carry frame/CSP protection** — the board (`src/handler.mjs`) and the hosted landing page are served with `X-Frame-Options: DENY` and a `Content-Security-Policy`: `default-src 'self'`, `frame-ancestors 'none'`, `object-src 'none'`. Both pages are single self-contained documents (inline script/style, same-origin fetches, zero external resources), so the CSP allows `'unsafe-inline'` for script/style specifically — no eval, no external origins.
+- **Data files are written 0600** — the registry and workspace state files hold every key/token hash; `FileStore.save` (core, so the single relay benefits too) and `saveRegistry` plus the hosted import write now create their temp files with mode 0600 (plus a chmod before the atomic rename), and the mode rides through the rename. Existing files tighten on their next save.
+- **Error hygiene** — the single relay and the hosted server returned raw `e.message` in 500s. Both now log the real error (with stack) to stderr and answer a generic `{ error: 'internal error' }`. The handler's 400s are unchanged on purpose: those are deliberate, client-facing validation/auth errors thrown by the core, not internal faults.
+- **Admin audit log** (`src/hosted-server.mjs`) — every admin action (workspace create, delete, rotate-key, export, import) emits one structured stderr line: timestamp, action, workspace id, source IP. Never a key, never a hash. On a paid host, that stderr stream is the operator's audit trail.
+- **SECURITY.md** — new at the repo root: latest-release-only support, private reporting to gdev6145@gmail.com, one-business-day acknowledgement (the studio's stated support posture), and scope notes.
+- **Tests** — three new checks (54 in the main suite, was 51): HTML headers + 0600 file modes + audit lines (create/rotate/delete, asserting no key material appears in stderr); the 1 MB cap returning 413 on hosted-admin, in-workspace, and single-relay routes; and the failed-auth throttle (30 bad keys → 401 each, then even the correct key → 429, admin too, health still 200). All three fail against the 0.5.2 servers (51 passed, 3 failed, each for its intended reason) and pass with the change; serverless stays 6/6 and both demos green. The timing-safe change is covered functionally by the existing right-key/wrong-key checks at every layer — a timing side channel is not observable from a functional test, so that one is verified by the audit above rather than a red/green run.
+- **Scope boundary, honestly** — what did NOT change: no API or behavior change for legitimate clients; storage format and locations; the local stdio/CLI trust model; the serverless pack's opt-in token posture (only its key compare was aligned); the deferred networked multi-writer store is still future work. One judgment call to know about: throttling is per-IP and in-memory — behind a shared NAT, one guesser can 429 a whole office's *unauthenticated* attempts for a minute; authenticated traffic with a valid key is only blocked while the throttle is tripped, and the window is short by design.
+
+## 0.5.2 — 2026-10-11
+
+Security hardening — the pre-pilot pass. A cold source review scored GhostBus 7.4/10 with security maturity its lowest mark (5.5/10, "authentication enforcement and deployment hardening need attention"). That was the right call to answer before any hosted workspace carries a stranger's work — or their money:
+
+- **Hosted: per-agent token enforcement is now the DEFAULT** (`src/hosted-server.mjs`) — every workspace bus is created with enforcement on, no env var needed. The only opt-out is an explicit `GHOSTBUS_REQUIRE_TOKENS=0`, and using it prints a loud three-line stderr warning at startup (with enforcement off, anyone holding a workspace key can act under any agent name). Header comment updated to match.
+- **Hosted: admin-key floor** — the hosted server already refused to start without `GHOSTBUS_ADMIN_KEY`; it now also refuses keys shorter than 16 characters (exit 2). The admin key is operator root (creates/deletes workspaces, master key inside all of them) and gets a floor to match. Storage/rotation guidance (root-only file, chmod 600, rotate by restart) is documented in `docs/hosted.md`.
+- **Single relay: exposure is never silent** (`src/http-server.mjs`) — Node's `listen()` binds all network interfaces, not just loopback. Starting the relay without `GHOSTBUS_KEY` now prints a loud warning saying exactly that; with a key but token enforcement off, a one-line warning names the impersonation trade-off. Semantics unchanged: local trust is still the relay's default model.
+- **Docs** — new "Security & deployment hardening" section in `docs/hosted.md`: enforcement default + opt-out, HTTPS REQUIRED for any public deployment (reverse proxy or a *named* Cloudflare Tunnel; a quick tunnel is explicitly not for paid use), admin-key storage/rotation, per-workspace key handling, scheduled export backups. README hosted section points at it.
+- **Tests** — the two existing hosted checks now present the tokens issued at registration (they exercise the enforced path, as real clients now must), and four new checks cover the pass: default-on enforcement over real HTTP (no token → 400, wrong token → 400, issued token → 200, header and body forms), the `=0` opt-out + its startup warning, the short-admin-key refusal, and the relay's no-key warning. All four fail against the 0.5.1 servers (47 passed, 4 failed) and pass with the change.
+- **Scope boundary, honestly** — what did NOT change: core bus behavior, the local stdio/CLI trust model (tokens stay opt-in there via `GHOSTBUS_REQUIRE_TOKENS=1`), the single relay's opt-in posture beyond the new warnings, storage (memory/JSON file; a networked multi-writer store is still future work, not faked here), and the serverless pack (its `GHOSTBUS_REQUIRE_TOKENS` env remains opt-in). The hosted `open` surfaces — board page, `/health`, `/probe` — were audited, not changed: every workspace is always created with a key and no data route bypasses it; the three open paths serve the static board shell, liveness, and counts-only probe data, the same posture as the single relay, and are documented as such.
+- 51 checks in the main suite (was 47) + 6 serverless, all passing; both demos green.
+
+## 0.5.1 — 2026-10-09
+
+Reliability fix — the operation-level race above the v0.4.1 FileStore fix:
+
+- **Per-Bus mutation mutex** — every public operation on a `GhostBus` (register/heartbeat, message send, task create/claim/complete/comment, file put/delete, capsule/context writes, token ops, snapshot restore, and reads) now runs its whole load → mutate → save cycle inside a per-instance promise-chain mutex (`_serialized` in src/core.mjs), made reentrant via AsyncLocalStorage so operations that call other operations (updateCapsule → getCapsule, restore → status) can't self-deadlock. Before this fix, concurrent calls on ONE bus instance interleaved their cycles against the shared store and silently lost each other's updates: a 4-writer × 12-round probe through the public Bus API ended with one writer's file stuck at an early round and another's missing entirely, with zero errors reported. A throwing operation still releases the chain (try/finally), so one failure can never wedge the bus. Public API and behavior are unchanged.
+- **Scope boundary, honestly** — the mutex serializes operations within one Bus instance in one process. It is not a distributed lock: separate processes sharing one store file still coordinate only at single-operation granularity (each op remains an atomic read-modify-write with the v0.4.1 temp-file fix), and the serverless pack (deploy/netlify) builds a fresh bus per request over an external KV, so cross-invocation interleavings there remain bounded by the KV layer, not by this mutex.
+- **Regression tests in the main suite** — three new checks: concurrent writers lose no updates (4 writers × 12 rounds, verified on disk via a fresh instance), concurrent mixed ops (tasks + messages + files at once) all land with unique task ids, and a throwing operation releases the mutex (with a wedge timeout). All three fail on the pre-fix core (44 passed, 3 failed) and pass with the fix.
+- 47 checks in the main suite (was 44) + 6 serverless, all passing; both demos green.
+
 ## 0.5.0 — 2026-10-08
 
 The operator release — running a hosted bus day-to-day:

package/PLAN.md

@@ -1,6 +1,6 @@
 # GhostBus — Agent-to-Agent Message Bus / Shared Workspace MCP
 
-**Status:** PUBLISHED — v0.5.0 live Oct 8, 2026 (github.com/littlestjames82-sys/ghostbus). v0.5.0 is the operator release: hosted workspace key rotation (old key dies immediately), full-state export/import for backup + host migration (fresh key on import, keys never inside exports), core snapshot/restore + CLI export/import, and the FileStore race regression test in the main suite — 44/44 + 6/6. v0.4.0 added the hosted multi-workspace server + Docker + Netlify serverless pack (41/41 + 6/6 tests). v0.4.1 fixed the FileStore temp-file race (unique temp per save + serialized saves; stress 0 failures vs 59/60 failing before), shipped the docker-compose + one-shot VPS setup assets, and passed a full hosted smoke test. Still not deployed to a public host — that waits on Ryan's VPS choice. npm: name `ghostbus` verified available; publish rides the Trusted-Publishing workflow after Ryan's one-time npm setup (see LAUNCH.md).
+**Status:** PUBLISHED — v0.5.1 live Oct 9, 2026 (github.com/littlestjames82-sys/ghostbus). v0.5.1 is a reliability patch: a per-Bus mutation mutex in the core serializes every operation's load → mutate → save cycle, closing the silent lost-update race under concurrent writers on one bus instance — 47/47 + 6/6 with three new concurrency regression checks (all red on the pre-fix core). v0.5.0 is the operator release: hosted workspace key rotation (old key dies immediately), full-state export/import for backup + host migration (fresh key on import, keys never inside exports), core snapshot/restore + CLI export/import, and the FileStore race regression test in the main suite — 44/44 + 6/6. v0.4.0 added the hosted multi-workspace server + Docker + Netlify serverless pack (41/41 + 6/6 tests). v0.4.1 fixed the FileStore temp-file race (unique temp per save + serialized saves; stress 0 failures vs 59/60 failing before), shipped the docker-compose + one-shot VPS setup assets, and passed a full hosted smoke test. Still not deployed to a public host — that waits on Ryan's VPS choice. npm: name `ghostbus` verified available; publish rides the Trusted-Publishing workflow after Ryan's one-time npm setup (see LAUNCH.md).
 **Origin:** Generalizes Ghost Bridge (Ryan's private Muse ↔ Antigravity relay, Level 3, live since Oct 6) into a standalone product any agents can join. Ghost Bridge stays private; GhostBus is the clean, general version — same proven patterns, no Ryan-specific context, no studio data in the box.
 
 ## The problem (one line)

package/README.md

@@ -6,12 +6,24 @@ Agents today work alone in separate windows — when two of them need to coopera
 
 Zero dependencies. Node 18+. MIT.
 
+## Install
+
+```bash
+npm install ghostbus
+```
+
+GhostBus is published on npm as [`ghostbus`](https://www.npmjs.com/package/ghostbus) (v0.5.0) — zero dependencies, Node 18+. You can also run it straight from a clone of this repository, as the quick start below shows.
+
+## Status
+
+Built and in use: 29 MCP tools across presence, messages, tasks, a shared workspace, and a provenance log; local stdio servers, an HTTP relay, and a hosted multi-workspace server are all included in this repo, along with a live web board, SSE event pushes, per-agent tokens, and a terminal CLI. See `CHANGELOG.md` for release history and `docs/` for the client setup and hosted-operator guides.
+
 ## Quick start
 
 ```bash
-git clone <this repo> ghostbus && cd ghostbus
+git clone https://github.com/littlestjames82-sys/ghostbus.git ghostbus && cd ghostbus
 node examples/two-agent-demo.mjs   # watch a planner and a builder cooperate
-node test.mjs                      # 40 checks: core, tokens, capsules, dependencies, sync, persistence, MCP stdio, HTTP, SSE, CLI
+node test.mjs                      # 54 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security
 node examples/three-agent-team.mjs # planner + builder + reviewer, no human relaying
 ```
 
@@ -46,6 +58,8 @@ GHOSTBUS_ADMIN_KEY=pick-a-long-secret node src/hosted-server.mjs --port 8388
 
 One process serves many **isolated** workspaces under `/w/<id>/` — each with its own key (issued once at creation, hash-only in the registry), board, REST, MCP, SSE and probe. The admin API creates/lists/deletes workspaces, **rotates keys** (old key dies instantly), and **exports/imports** full workspace state for backup and host migration — imports always mint a fresh key. A Dockerfile and a serverless Netlify/Blobs pack are included. Operator guide: `docs/hosted.md`.
 
+Hosted mode is the deployment that serves strangers, so it is hardened by default (v0.5.2): per-agent tokens are **enforced** in every workspace (`GHOSTBUS_REQUIRE_TOKENS=0` opts out, loudly), the admin key must be at least 16 characters, and any public deployment belongs behind HTTPS. Details: the "Security & deployment hardening" section of `docs/hosted.md`.
+
 Same tools over `POST /mcp`, plus a REST mirror under `/api/*`. `/health` and a counts-only `/probe` stay open for monitoring and wake hooks. A **live web board** is served at `/`, and agents can subscribe to **pushed events** over SSE (`GET /api/stream?agent=<name>`) instead of polling. Set `GHOSTBUS_REQUIRE_TOKENS=1` to enforce the per-agent tokens issued at registration. There's also a terminal CLI (`src/cli.mjs`) and full client setup docs in `docs/client-setup.md`.
 
 ## The 29 tools
@@ -77,6 +91,19 @@ Same tools over `POST /mcp`, plus a REST mirror under `/api/*`. `/health` and a
 
 GhostBus generalizes a private relay that has run in production for one studio's own agents since Oct 2026 (task handoffs, shared project capsules, a live board). This is the clean, general version of that proven pattern. Built by Ghost Developer Studio.
 
+## From Ghost Developer Studio
+
+GhostBus is one part of the studio's agent-infrastructure family:
+
+- **Visual roadmap board** — where every studio product stands, in one picture: [ghost-roadmaps](https://github.com/littlestjames82-sys/ghost-roadmaps)
+- **GhostGuard** — the governance layer for autonomous systems: [ghostguard](https://github.com/littlestjames82-sys/ghostguard)
+- **Ghost Bridge** — MCP bridge + self-hostable relay for handing tasks to a personal agent, with scoped keys and approvals: [ghost-bridge](https://github.com/littlestjames82-sys/ghost-bridge)
+- **Ghost Hands** — governed, recorded, replayable agent hands for the web: [ghost-hands](https://github.com/littlestjames82-sys/ghost-hands)
+- **Agent Seatbelt** — deterministic guardrails that gate what an AI coding agent does before it does it: [agent-seatbelt](https://github.com/littlestjames82-sys/agent-seatbelt)
+- **Ghost Developer Studio storefront** — [storefront](https://github.com/littlestjames82-sys/storefront)
+
+Built in public by Ryan Cotten / Ghost Developer Studio.
+
 ## License
 
 MIT — see `LICENSE`.

package/docs/hosted.md

@@ -53,20 +53,97 @@ Everything from the single-workspace relay works under the prefix:
 
 - Board: `https://host/w/acme/` (asks for the workspace key in-page)
 - REST: `https://host/w/acme/api/*` with header `x-bus-key: <workspace key>`
-- MCP: `POST https://host/w/acme/mcp` (same header; plus `x-agent-token` when token mode is on)
+- MCP: `POST https://host/w/acme/mcp` (same header; plus `x-agent-token` — per-agent token enforcement is ON by default in hosted mode, see below)
 - Probe (open, counts only): `GET https://host/w/acme/probe`
 - Push: SSE at `/w/acme/api/stream?agent=…`, long-poll at `/w/acme/api/wait?agent=…`
 
 The admin key also works as a master key inside any workspace — treat it like root: operators only, never hand it to agents.
 
-Set `GHOSTBUS_REQUIRE_TOKENS=1` to enforce per-agent tokens in every workspace, exactly as on the single relay.
+## Security & deployment hardening
+
+The hosted server is the one GhostBus deployment that serves people other than
+the operator, so its defaults are stricter than the local relay's (v0.5.2):
+
+- **Per-agent tokens are enforced by default** in every workspace: an agent
+  registers once, receives its token once, and must present it
+  (`x-agent-token` header or `token` field) for every act. A stolen agent
+  *name* alone cannot impersonate it. `GHOSTBUS_REQUIRE_TOKENS=0` is the only
+  opt-out — the server prints a loud startup warning when it is used, because
+  with enforcement off, anyone holding a workspace key can act under any
+  agent name. Don't disable it for a public or paid deployment.
+- **HTTPS is REQUIRED for any public deployment.** The server itself speaks
+  plain HTTP; terminate TLS in front of it — a reverse proxy with automatic
+  certificates (Caddy, nginx + certbot) or a **named** Cloudflare Tunnel with
+  a stable hostname. A Cloudflare *quick* tunnel (`trycloudflare.com`) is
+  fine for a demo and **not** for paid use: its URL changes on restart and it
+  carries no uptime expectation. Never expose the plain-HTTP port directly.
+- **Admin key hygiene.** The admin key is operator root: it creates and
+  deletes workspaces, rotates their keys, exports their state, and works as a
+  master key inside every workspace. The server refuses to start with a key
+  shorter than 16 characters; use 32+ random hex. Store it in a root-only
+  file, never in the repo, a ticket, or a chat log:
+  ```bash
+  head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' > /root/ghostbus-admin-key
+  chmod 600 /root/ghostbus-admin-key
+  GHOSTBUS_ADMIN_KEY=$(cat /root/ghostbus-admin-key) node src/hosted-server.mjs
+  ```
+  (The shipped `deploy/docker/vps-setup.sh` already generates it this way.)
+  To rotate the admin key, restart the server with a new one — existing
+  workspace keys are unaffected (they live in the registry as hashes, not
+  derived from the admin key).
+- **Per-workspace keys.** Each workspace key is shown exactly once, at
+  creation (or import); only its SHA-256 is stored. Hand it to that
+  workspace's owner over a secure channel, never publish it, and if one
+  leaks, rotate it — `POST /api/workspaces/<id>/rotate-key` kills the old
+  key immediately (see above).
+- **Backups are a schedule, not a feature.** The data dir *is* the state
+  (`registry.json` + one `<id>.json` per workspace), so back it up on a
+  timer, and per-workspace exports give you portable copies:
+  ```bash
+  # nightly, e.g. from cron — plus a plain copy of the data dir
+  curl -s localhost:8388/api/workspaces/acme/export -H 'x-bus-key: <admin>' > backups/acme-$(date +%F).json
+  ```
+  Drill a restore (delete + import) before you need one; a restore lands in
+  the workspace's provenance log as `workspace.restore`.
+
+Round 2 (v0.5.3) closed the next layer:
+
+- **Timing-safe secret comparisons everywhere.** Workspace keys (hosted
+  router + serverless pack) and per-agent tokens (core) are compared with
+  `crypto.timingSafeEqual` over SHA-256 digests — no `===` on secrets
+  anywhere in the codebase.
+- **Failed-auth throttling at the hosted layer.** The in-workspace limiter
+  (300 req/min/IP) never covered *guessing*: 30 failed auth attempts per
+  minute from one IP now gets 429s on the admin surface and on workspace
+  routes until the window rolls. Successful auth never counts toward it;
+  `/health` and `/probe` stay open so operators can see an attack.
+- **Request bodies are capped at 1 MB** on every JSON route (hosted admin,
+  in-workspace, single relay). Over the cap: a clean `413` JSON error.
+  File contents travel as JSON in GhostBus, so legitimate files fit
+  comfortably — but a workspace *import* larger than 1 MB must be restored
+  by placing the state file in the data dir (or via the CLI), not over HTTP.
+- **HTML pages can't be framed and carry a CSP.** The board and the hosted
+  landing page answer with `X-Frame-Options: DENY` and a
+  `Content-Security-Policy` (`default-src 'self'`, `frame-ancestors 'none'`;
+  inline script/style are allowed specifically because both pages are
+  single self-contained documents with zero external resources).
+- **Data files are written owner-only (0600).** The registry and every
+  workspace state file hold key/token hashes; they are created 0600 through
+  the same atomic temp+rename writes as before.
+- **Admin actions are audit-logged.** Every workspace create, delete,
+  rotate-key, export, and import writes one structured stderr line
+  (timestamp, action, workspace id, source IP) — never a key or a hash.
+  Point the hosted process's stderr at your log collector and that *is*
+  the operator audit trail.
+- **Reporting a vulnerability:** see `SECURITY.md` at the repo root
+  (private email reporting, one-business-day acknowledgement).
 
 ## Option B — serverless on Netlify (Blobs)
 
 `deploy/netlify/` contains a Netlify Function implementing the same multi-workspace semantics over Netlify Blobs (strong consistency):
 
 1. Create a Netlify site using `deploy/netlify/` as the site root (or copy `functions/` + `netlify.toml` into a site).
-2. Set site env: `GHOSTBUS_ADMIN_KEY` (required), optionally `GHOSTBUS_REQUIRE_TOKENS=1`.
+2. Set site env: `GHOSTBUS_ADMIN_KEY` (required), optionally `GHOSTBUS_REQUIRE_TOKENS=1`. (The serverless pack keeps token enforcement opt-in via this env; the Node hosted server above enforces by default since v0.5.2.)
 3. Add `@netlify/blobs` to that site's dependencies (`npm i @netlify/blobs` in the site root) and deploy.
 
 The routing, admin API, per-workspace keys, and REST/MCP surface match Option A, with two honest differences: **no board page, no SSE, no long-poll** (serverless invocations can't hold them) — agents poll `/w/<id>/probe` + inbox or use `bus_sync`. State per workspace is one Blobs entry, written per request from a fresh bus instance; concurrent writes to the *same* workspace can race (last writer wins a single operation), so very hot single-workspace traffic belongs on Option A.

package/package.json

@@ -44,5 +44,5 @@
     "hosted": "node src/hosted-server.mjs"
   },
   "type": "module",
-  "version": "0.5.0"
+  "version": "0.5.3"
 }

package/src/core.mjs

@@ -12,9 +12,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
 
-export const GHOSTBUS_VERSION = '0.5.0';
+export const GHOSTBUS_VERSION = '0.5.3';
 const sha256 = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
+// Timing-safe equality for hex digests (v0.5.3): secret comparisons must not
+// short-circuit on the first differing character the way === does.
+const hashEqHex = (aHex, bHex) => {
+  const a = Buffer.from(String(aHex)); const b = Buffer.from(String(bHex));
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+};
 export const TASK_STATUSES = ['queued', 'claimed', 'needs-approval', 'done', 'cancelled'];
 const CLAIM_LEASE_MS = 15 * 60 * 1000;
 
@@ -61,7 +68,11 @@ export class FileStore {
       await fs.promises.mkdir(path.dirname(this.file), { recursive: true });
       const tmp = this.file + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 10);
       try {
-        await fs.promises.writeFile(tmp, JSON.stringify(state, null, 2));
+        // State files hold token hashes — owner-only (0600) from birth
+        // (v0.5.3). The mode rides through the atomic rename; the chmod
+        // covers filesystems/umasks that would otherwise widen it.
+        await fs.promises.writeFile(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+        await fs.promises.chmod(tmp, 0o600).catch(() => {});
         await fs.promises.rename(tmp, this.file); // atomic replace
       } finally {
         await fs.promises.unlink(tmp).catch(() => {});
@@ -82,12 +93,44 @@ export class GhostBus {
     // Registration issues the token once; only its sha256 is stored.
     this.requireTokens = !!opts.requireTokens;
     this.listeners = new Set(); // live event subscribers (SSE relay)
+    // Mutation mutex (v0.5.1): a promise chain serializing every public
+    // operation's load -> mutate -> save cycle on THIS instance. Without it,
+    // concurrent calls interleave their cycles against the shared store and
+    // silently lose each other's updates (one op's reload discards another's
+    // not-yet-saved state). The AsyncLocalStorage marker makes the chain
+    // reentrant: public methods that call other public methods (updateCapsule
+    // -> getCapsule, restore -> status, heartbeat -> listAgents) run inline
+    // instead of deadlocking on their own queue.
+    this._chain = Promise.resolve();
+    this._als = new AsyncLocalStorage();
+  }
+
+  /**
+   * Run `fn` inside this bus's serialized section. Callers queue FIFO on the
+   * promise chain; a throwing operation still releases the chain (finally),
+   * so one failure can never wedge the bus. Scope: per Bus instance, in this
+   * process — it cannot span processes sharing one store file (each op there
+   * is still a single atomic read-modify-write) nor serverless invocations.
+   */
+  async _serialized(fn) {
+    if (this._als.getStore() === this) return fn();
+    const prev = this._chain;
+    let release;
+    const gate = new Promise((resolve) => { release = resolve; });
+    this._chain = prev.then(() => gate);
+    await prev;
+    try {
+      return await this._als.run(this, fn);
+    } finally {
+      release();
+    }
   }
 
   /** Subscribe to provenance events as they happen. Returns an unsubscribe fn. */
   onEvent(fn) { this.listeners.add(fn); return () => this.listeners.delete(fn); }
 
-  async init() {
+  async init() { return this._serialized(() => this._init()); }
+  async _init() {
     // Shared (file) stores are re-read on every call: several processes
     // (stdio servers, the CLI, a relay) can then share ONE workspace file
     // and actually see each other's writes. Each mutation is a fresh
@@ -127,7 +170,7 @@ export class GhostBus {
     const a = this._agent(name);
     if (!a) throw Object.assign(new Error(`agent not registered: ${name}`), { code: 'UNKNOWN_AGENT' });
     if (this.requireTokens && a.tokenHash) {
-      if (!token || sha256(token) !== a.tokenHash) {
+      if (!token || !hashEqHex(sha256(token), a.tokenHash)) {
         throw Object.assign(new Error(`agent token required or wrong for: ${name}`), { code: 'AGENT_AUTH' });
       }
     }
@@ -136,7 +179,8 @@ export class GhostBus {
   }
 
   // ---------- agents ----------
-  async registerAgent({ name, role = '', capabilities = [], token = null }) {
+  async registerAgent(...args) { return this._serialized(() => this._registerAgent(...args)); }
+  async _registerAgent({ name, role = '', capabilities = [], token = null }) {
     await this.init();
     if (!name || typeof name !== 'string') throw new Error('agent name required');
     name = name.trim();
@@ -163,7 +207,8 @@ export class GhostBus {
     return { agent: this._publicAgent(agent), rejoined: false, token: rawToken, tokenNote: 'Store this token — it is shown once and only its hash is kept. Present it as `token` (tools) or x-agent-token (HTTP) when the bus runs with requireTokens.' };
   }
 
-  async rotateAgentToken({ name, token = null }) {
+  async rotateAgentToken(...args) { return this._serialized(() => this._rotateAgentToken(...args)); }
+  async _rotateAgentToken({ name, token = null }) {
     await this.init();
     const a = this._requireAgent(name, token);
     const rawToken = crypto.randomBytes(24).toString('hex');
@@ -173,16 +218,19 @@ export class GhostBus {
     return { agent: this._publicAgent(a), token: rawToken, tokenNote: 'New token — the old one no longer works. Shown once.' };
   }
 
-  async heartbeat({ name, token = null }) {
+  async heartbeat(...args) { return this._serialized(() => this._heartbeat(...args)); }
+  async _heartbeat({ name, token = null }) {
     await this.init();
     const a = this._requireAgent(name, token);
     return { agent: this._publicAgent(a), agents: await this.listAgents() };
   }
 
-  async listAgents() { await this.init(); return this.state.agents.map(a => this._publicAgent(a)); }
+  async listAgents(...args) { return this._serialized(() => this._listAgents(...args)); }
+  async _listAgents() { await this.init(); return this.state.agents.map(a => this._publicAgent(a)); }
 
   // ---------- messages ----------
-  async sendMessage({ from, to = '*', body, channel = 'general', threadId = null, token = null }) {
+  async sendMessage(...args) { return this._serialized(() => this._sendMessage(...args)); }
+  async _sendMessage({ from, to = '*', body, channel = 'general', threadId = null, token = null }) {
     await this.init();
     this._requireAgent(from, token);
     if (to !== '*') this._existsAgent(to);
@@ -201,7 +249,8 @@ export class GhostBus {
   }
 
   /** Messages visible to `agent`: addressed to it, broadcast, or sent by it. Unread-first filtering optional. */
-  async inbox(agentName, { unreadOnly = false, limit = 50, markRead = true, token = null } = {}) {
+  async inbox(...args) { return this._serialized(() => this._inbox(...args)); }
+  async _inbox(agentName, { unreadOnly = false, limit = 50, markRead = true, token = null } = {}) {
     await this.init();
     this._requireAgent(agentName, token);
     let msgs = this.state.messages.filter(m =>
@@ -216,7 +265,8 @@ export class GhostBus {
     return clone(msgs);
   }
 
-  async thread(id) {
+  async thread(...args) { return this._serialized(() => this._thread(...args)); }
+  async _thread(id) {
     await this.init();
     const root = this.state.messages.find(m => m.id === Number(id));
     if (!root) throw new Error(`message not found: ${id}`);
@@ -224,7 +274,8 @@ export class GhostBus {
   }
 
   // ---------- tasks ----------
-  async createTask({ from, title, body = '', assignee = null, priority = 'normal', needsApproval = false, blockedBy = [], token = null }) {
+  async createTask(...args) { return this._serialized(() => this._createTask(...args)); }
+  async _createTask({ from, title, body = '', assignee = null, priority = 'normal', needsApproval = false, blockedBy = [], token = null }) {
     await this.init();
     this._requireAgent(from, token);
     if (assignee) this._existsAgent(assignee);
@@ -257,7 +308,8 @@ export class GhostBus {
     }
   }
 
-  async listTasks({ status = null, assignee = null } = {}) {
+  async listTasks(...args) { return this._serialized(() => this._listTasks(...args)); }
+  async _listTasks({ status = null, assignee = null } = {}) {
     await this.init();
     this._expireClaims(); await this._save();
     let tasks = this.state.tasks;
@@ -266,7 +318,8 @@ export class GhostBus {
     return clone(tasks.sort((a, b) => b.id - a.id));
   }
 
-  async approveTask(id, { by, token = null }) {
+  async approveTask(...args) { return this._serialized(() => this._approveTask(...args)); }
+  async _approveTask(id, { by, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     const task = this._task(id);
@@ -279,7 +332,8 @@ export class GhostBus {
   }
 
   /** Claim is exclusive: a second claim while a lease is live fails loudly. */
-  async claimTask(id, { by, token = null }) {
+  async claimTask(...args) { return this._serialized(() => this._claimTask(...args)); }
+  async _claimTask(id, { by, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     this._expireClaims();
@@ -298,7 +352,8 @@ export class GhostBus {
     return clone(task);
   }
 
-  async completeTask(id, { by, result = '', token = null }) {
+  async completeTask(...args) { return this._serialized(() => this._completeTask(...args)); }
+  async _completeTask(id, { by, result = '', token = null }) {
     await this.init();
     this._requireAgent(by, token);
     const task = this._task(id);
@@ -311,7 +366,8 @@ export class GhostBus {
     return clone(task);
   }
 
-  async cancelTask(id, { by, token = null }) {
+  async cancelTask(...args) { return this._serialized(() => this._cancelTask(...args)); }
+  async _cancelTask(id, { by, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     const task = this._task(id);
@@ -330,7 +386,8 @@ export class GhostBus {
   }
 
   // ---------- shared workspace: files + context + board ----------
-  async putFile({ by, path: p, text, token = null }) {
+  async putFile(...args) { return this._serialized(() => this._putFile(...args)); }
+  async _putFile({ by, path: p, text, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     if (!p || typeof text !== 'string') throw new Error('path and text required');
@@ -343,7 +400,8 @@ export class GhostBus {
     return { path: p, bytes: Buffer.byteLength(text) };
   }
 
-  async getFile(p, { withHistory = false } = {}) {
+  async getFile(...args) { return this._serialized(() => this._getFile(...args)); }
+  async _getFile(p, { withHistory = false } = {}) {
     await this.init();
     const f = this.state.files[p];
     if (!f) throw new Error(`file not found: ${p}`);
@@ -351,19 +409,22 @@ export class GhostBus {
     return { path: p, ...clone(rest), versions: (history || []).length + 1, ...(withHistory ? { history: clone(history || []) } : {}) };
   }
 
-  async fileHistory(p) {
+  async fileHistory(...args) { return this._serialized(() => this._fileHistory(...args)); }
+  async _fileHistory(p) {
     await this.init();
     const f = this.state.files[p];
     if (!f) throw new Error(`file not found: ${p}`);
     return { path: p, current: { text: f.text, updatedBy: f.updatedBy, updatedAt: f.updatedAt }, history: clone(f.history || []) };
   }
 
-  async listFiles() {
+  async listFiles(...args) { return this._serialized(() => this._listFiles(...args)); }
+  async _listFiles() {
     await this.init();
     return Object.entries(this.state.files).map(([p, f]) => ({ path: p, bytes: Buffer.byteLength(f.text), updatedBy: f.updatedBy, updatedAt: f.updatedAt }));
   }
 
-  async putContext({ by, context, token = null }) {
+  async putContext(...args) { return this._serialized(() => this._putContext(...args)); }
+  async _putContext({ by, context, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     if (!context || typeof context !== 'object' || Array.isArray(context)) throw new Error('context must be an object');
@@ -373,13 +434,15 @@ export class GhostBus {
     return { ok: true };
   }
 
-  async getContext() {
+  async getContext(...args) { return this._serialized(() => this._getContext(...args)); }
+  async _getContext() {
     await this.init();
     if (!this.state.context) throw new Error('no context published yet');
     return clone(this.state.context);
   }
 
-  async addTaskComment(id, { by, body, token = null }) {
+  async addTaskComment(...args) { return this._serialized(() => this._addTaskComment(...args)); }
+  async _addTaskComment(id, { by, body, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     if (!body || !String(body).trim()) throw new Error('comment body required');
@@ -394,7 +457,8 @@ export class GhostBus {
     return clone(task);
   }
 
-  async deleteFile({ by, path: p, token = null }) {
+  async deleteFile(...args) { return this._serialized(() => this._deleteFile(...args)); }
+  async _deleteFile({ by, path: p, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     if (!this.state.files[p]) throw new Error(`file not found: ${p}`);
@@ -404,7 +468,8 @@ export class GhostBus {
     return { path: p, deleted: true };
   }
 
-  async listChannels() {
+  async listChannels(...args) { return this._serialized(() => this._listChannels(...args)); }
+  async _listChannels() {
     await this.init();
     const counts = {};
     for (const m of this.state.messages) counts[m.channel] = (counts[m.channel] || 0) + 1;
@@ -412,7 +477,8 @@ export class GhostBus {
   }
 
   /** Full-text search across messages, tasks, and shared files. */
-  async search(query, { limit = 20 } = {}) {
+  async search(...args) { return this._serialized(() => this._search(...args)); }
+  async _search(query, { limit = 20 } = {}) {
     await this.init();
     const q = String(query || '').toLowerCase().trim();
     if (q.length < 2) throw new Error('search query needs at least 2 characters');
@@ -437,7 +503,8 @@ export class GhostBus {
   }
 
   /** Read a project capsule, creating it from the template on first touch when create=true. */
-  async getCapsule(slug, { create = false, title = '', by = null, token = null } = {}) {
+  async getCapsule(...args) { return this._serialized(() => this._getCapsule(...args)); }
+  async _getCapsule(slug, { create = false, title = '', by = null, token = null } = {}) {
     await this.init();
     const pth = this._capsulePath(slug);
     if (!this.state.files[pth]) {
@@ -451,7 +518,8 @@ export class GhostBus {
   }
 
   /** Replace one capsule section (State / Decisions / Next) or append to the Session log. */
-  async updateCapsule(slug, { by, section, text, token = null }) {
+  async updateCapsule(...args) { return this._serialized(() => this._updateCapsule(...args)); }
+  async _updateCapsule(slug, { by, section, text, token = null }) {
     await this.init();
     this._requireAgent(by, token);
     await this.getCapsule(slug, { create: true, by, token });
@@ -477,13 +545,15 @@ export class GhostBus {
     return this.getFile(pth);
   }
 
-  async listCapsules() {
+  async listCapsules(...args) { return this._serialized(() => this._listCapsules(...args)); }
+  async _listCapsules() {
     await this.init();
     return Object.keys(this.state.files).filter(p => p.startsWith('capsules/') && p.endsWith('.md')).map(p => p.slice('capsules/'.length, -3)).sort();
   }
 
   /** A human-readable board rendered from live state — the shared picture at a glance. */
-  async board() {
+  async board(...args) { return this._serialized(() => this._board(...args)); }
+  async _board() {
     await this.init();
     this._expireClaims();
     const s = this.state;
@@ -511,18 +581,21 @@ export class GhostBus {
 
   /** Catch-up sync: every event after `sinceSeq`, plus the current head seq.
    *  An agent that was offline replays exactly what it missed — nothing more. */
-  async sync({ sinceSeq = 0, limit = 500 } = {}) {
+  async sync(...args) { return this._serialized(() => this._sync(...args)); }
+  async _sync({ sinceSeq = 0, limit = 500 } = {}) {
     await this.init();
     const evs = this.state.events.filter(e => e.seq > Number(sinceSeq));
     return { events: clone(evs.slice(0, Math.min(limit, 1000))), headSeq: this.state.seq, truncated: evs.length > Math.min(limit, 1000) };
   }
 
-  async events({ limit = 50 } = {}) {
+  async events(...args) { return this._serialized(() => this._events(...args)); }
+  async _events({ limit = 50 } = {}) {
     await this.init();
     return clone(this.state.events.slice(-Math.min(limit, 500)));
   }
 
-  async status() {
+  async status(...args) { return this._serialized(() => this._status(...args)); }
+  async _status() {
     await this.init();
     this._expireClaims();
     const s = this.state;
@@ -540,7 +613,8 @@ export class GhostBus {
   /** Full-state snapshot for backup / migration. The state holds agent token
    *  HASHES only, never plaintext secrets; workspace keys live outside the
    *  state (hosted registry) and are never part of a snapshot. */
-  async snapshot() {
+  async snapshot(...args) { return this._serialized(() => this._snapshot(...args)); }
+  async _snapshot() {
     await this.init();
     return clone(this.state);
   }
@@ -549,7 +623,8 @@ export class GhostBus {
    *  The snapshot is shape-validated, the workspace identity is preserved
    *  unless the snapshot carries one, and the restore itself is recorded
    *  in the provenance log. Returns the post-restore status. */
-  async restore(snapshot, { by = 'operator' } = {}) {
+  async restore(...args) { return this._serialized(() => this._restore(...args)); }
+  async _restore(snapshot, { by = 'operator' } = {}) {
     await this.init();
     const bad = validateSnapshot(snapshot);
     if (bad) throw Object.assign(new Error(`invalid snapshot: ${bad}`), { code: 'BAD_SNAPSHOT' });

package/src/handler.mjs

@@ -24,6 +24,56 @@ const hashEq = (given, expected) => {
   return a.length === b.length && crypto.timingSafeEqual(a, b);
 };
 export const keyMatches = (given, expected) => !!expected && !!given && hashEq(given, expected);
+// Timing-safe check of a presented secret against a STORED sha256 hex digest
+// (v0.5.3) — the hosted router and the core token check compare against
+// hashes at rest, never against raw keys.
+export const hashMatches = (given, storedHashHex) => {
+  if (!given || !storedHashHex) return false;
+  const a = Buffer.from(crypto.createHash('sha256').update(String(given)).digest('hex'));
+  const b = Buffer.from(String(storedHashHex));
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+};
+
+// JSON request-body cap (v0.5.3): file contents travel inside JSON bodies in
+// this codebase, so 1 MB is generous for messages/tasks/files while keeping
+// a single request from exhausting memory. Over the cap the reader rejects
+// with code BODY_TOO_LARGE and the route answers 413.
+export const MAX_BODY_BYTES = 1_000_000;
+export function readJsonBody(req, limit = MAX_BODY_BYTES) {
+  return new Promise((resolve, reject) => {
+    let size = 0; let done = false;
+    const chunks = [];
+    req.on('data', (c) => {
+      if (done) return;
+      size += c.length;
+      if (size > limit) {
+        done = true;
+        req.pause(); // stop reading; the route answers 413 and drops the socket
+        reject(Object.assign(new Error(`request body too large (limit ${limit} bytes)`), { code: 'BODY_TOO_LARGE' }));
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on('end', () => {
+      if (done) return; done = true;
+      const data = Buffer.concat(chunks).toString('utf8');
+      try { resolve(data ? JSON.parse(data) : {}); } catch { resolve(null); }
+    });
+    req.on('error', () => { if (!done) { done = true; resolve(null); } });
+  });
+}
+
+// Headers for the HTML pages (board + hosted landing), v0.5.3. Both pages are
+// single self-contained documents: inline <script>/<style> and same-origin
+// fetches only, zero external resources — so the CSP allows 'unsafe-inline'
+// for script/style specifically (no eval, no external origins, no plugins)
+// and forbids framing outright.
+export const HTML_SECURITY_HEADERS = {
+  'x-frame-options': 'DENY',
+  'content-security-policy': "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+};
+
+const TOO_LARGE = Symbol('body-too-large');
 
 export function createBusHandler({ id = 'default', bus, key = '' }) {
   const buckets = new Map();
@@ -51,13 +101,19 @@ export function createBusHandler({ id = 'default', bus, key = '' }) {
     if (!rateOk(req) && url.pathname !== '/health' && url.pathname !== '/probe') {
       return send(429, { error: 'rate limit: 300 requests/min per IP per workspace' });
     }
-    const readBody = () => new Promise((resolve) => {
-      let data = ''; req.on('data', c => { data += c; if (data.length > 5_000_000) req.destroy(); });
-      req.on('end', () => { try { resolve(data ? JSON.parse(data) : {}); } catch { resolve(null); } });
-    });
+    const send413 = () => {
+      try {
+        res.writeHead(413, { 'content-type': 'application/json', connection: 'close' });
+        res.end(JSON.stringify({ error: `request body too large (limit ${MAX_BODY_BYTES} bytes)` }), () => { try { req.destroy(); } catch {} });
+      } catch {}
+    };
+    const readBody = async () => {
+      try { return await readJsonBody(req); }
+      catch (e) { if (e && e.code === 'BODY_TOO_LARGE') { send413(); return TOO_LARGE; } throw e; }
+    };
 
     try {
-      if (req.method === 'GET' && url.pathname === '/') { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }); return res.end(BOARD_HTML); }
+      if (req.method === 'GET' && url.pathname === '/') { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', ...HTML_SECURITY_HEADERS }); return res.end(BOARD_HTML); }
       if (req.method === 'GET' && url.pathname === '/health') return send(200, { ok: true, server: 'ghostbus', workspace: id, version: GHOSTBUS_VERSION });
       if (req.method === 'GET' && url.pathname === '/probe') {
         const s = await bus.status();
@@ -103,6 +159,7 @@ export function createBusHandler({ id = 'default', bus, key = '' }) {
 
       if (req.method === 'POST' && url.pathname === '/mcp') {
         const msg = await readBody();
+        if (msg === TOO_LARGE) return; // 413 already sent
         if (!msg) return send(400, { error: 'invalid JSON body' });
         if (msg.method === 'tools/list') return send(200, { jsonrpc: '2.0', id: msg.id, result: { tools: TOOLS } });
         if (msg.method === 'tools/call') {
@@ -118,6 +175,7 @@ export function createBusHandler({ id = 'default', bus, key = '' }) {
       }
 
       const body = ['POST', 'PUT', 'DELETE'].includes(req.method) ? await readBody().catch(() => ({})) : {};
+      if (body === TOO_LARGE) return; // 413 already sent
       const safeBody = body && typeof body === 'object' ? body : {};
       const q = Object.fromEntries(url.searchParams);
 

package/src/hosted-server.mjs

@@ -18,26 +18,47 @@
  *     GET    /api/workspaces/<id>/export   -> full-state export envelope (backup/migrate)
  *     POST   /api/workspaces/import {id?, name?, state|export} -> {id, name, key (once)}
  * - Registry + one data file per workspace live in the data dir.
- *   Set GHOSTBUS_REQUIRE_TOKENS=1 to enforce per-agent tokens in all workspaces.
+ * - Per-agent tokens are ENFORCED in all workspaces by default (v0.5.2):
+ *   hosted mode serves strangers, so a stolen agent name must not be enough
+ *   to act. GHOSTBUS_REQUIRE_TOKENS=0 is the only opt-out and starts with a
+ *   loud warning. GHOSTBUS_ADMIN_KEY is required and must be at least 16
+ *   characters — it is the operator root key (see docs/hosted.md).
+ * - v0.5.3: workspace-key checks are timing-safe, failed auth is throttled
+ *   per IP at this layer, JSON bodies are capped at 1 MB (413), registry +
+ *   workspace files are written 0600, HTML pages carry CSP/frame headers,
+ *   and every admin action is audit-logged to stderr (never keys/hashes).
  */
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { createBus, FileStore, GHOSTBUS_VERSION, validateSnapshot } from './core.mjs';
-import { createBusHandler, keyMatches } from './handler.mjs';
+import { createBusHandler, keyMatches, hashMatches, readJsonBody, MAX_BODY_BYTES, HTML_SECURITY_HEADERS } from './handler.mjs';
 
 const argv = process.argv.slice(2);
 const argVal = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
 const port = Number(argVal('--port') || process.env.GHOSTBUS_PORT || 8388);
 const dataDir = argVal('--data-dir') || process.env.GHOSTBUS_DATA_DIR || './ghostbus-hosted';
 const ADMIN_KEY = process.env.GHOSTBUS_ADMIN_KEY || '';
-const REQUIRE_TOKENS = process.env.GHOSTBUS_REQUIRE_TOKENS === '1';
+// v0.5.2: enforcement is the hosted DEFAULT. Only an explicit
+// GHOSTBUS_REQUIRE_TOKENS=0 turns it off (anything else, including unset,
+// means on) — the hosted server is the one deployment that serves people
+// other than the operator, so the safe posture cannot be opt-in.
+const REQUIRE_TOKENS = process.env.GHOSTBUS_REQUIRE_TOKENS !== '0';
 
 if (!ADMIN_KEY) {
   process.stderr.write('GHOSTBUS_ADMIN_KEY is required for the hosted server (workspace creation must not be open).\n');
   process.exit(2);
 }
+if (ADMIN_KEY.length < 16) {
+  process.stderr.write('GHOSTBUS_ADMIN_KEY is too short: use at least 16 characters (32+ random hex recommended). The admin key is the operator root key — it creates/deletes workspaces and acts as a master key inside every one of them.\n');
+  process.exit(2);
+}
+if (!REQUIRE_TOKENS) {
+  process.stderr.write('WARNING: GHOSTBUS_REQUIRE_TOKENS=0 — per-agent token enforcement is DISABLED in every workspace.\n');
+  process.stderr.write('WARNING: anyone holding a workspace key can act under ANY agent name in that workspace (impersonation).\n');
+  process.stderr.write('WARNING: hosted mode serves strangers; run with enforcement on unless you have a specific reason not to.\n');
+}
 
 fs.mkdirSync(dataDir, { recursive: true });
 const registryPath = path.join(dataDir, 'registry.json');
@@ -45,9 +66,11 @@ const loadRegistry = () => { try { return JSON.parse(fs.readFileSync(registryPat
 const saveRegistry = (reg) => {
   // Unique temp per save: two processes sharing this registry must never
   // collide on one fixed '.tmp' name (first rename wins, second throws ENOENT).
+  // The registry holds every workspace's key hash — owner-only (0600, v0.5.3).
   const tmp = registryPath + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 10);
   try {
-    fs.writeFileSync(tmp, JSON.stringify(reg, null, 2));
+    fs.writeFileSync(tmp, JSON.stringify(reg, null, 2), { mode: 0o600 });
+    try { fs.chmodSync(tmp, 0o600); } catch { /* mode already applied on create */ }
     fs.renameSync(tmp, registryPath);
   } finally {
     try { fs.unlinkSync(tmp); } catch { /* already renamed away */ }
@@ -81,9 +104,38 @@ const wsKeyOk = (req, meta) => {
   const given = req.headers['x-bus-key'] || String(req.headers.authorization || '').replace(/^Bearer\s+/i, '');
   if (!given) return false;
   if (keyMatches(given, ADMIN_KEY)) return true; // master key
-  return sha256(given) === meta.keyHash;
+  return hashMatches(given, meta.keyHash); // timing-safe vs the stored hash (v0.5.3)
+};
+
+// Failed-auth throttle (v0.5.3): the in-workspace handler limiter (300/min)
+// throttles traffic that is already inside a workspace, but nothing slowed
+// down *guessing* at the hosted layer — admin keys and workspace keys were
+// unthrottled. Track FAILED auth per IP; past the limit, admin + workspace
+// routes answer 429 until the window rolls. Successful auth never counts.
+const AUTH_FAIL_LIMIT = 30;            // failed auth attempts per window per IP
+const AUTH_FAIL_WINDOW_MS = 60_000;    // one-minute window
+const authFails = new Map(); // ip -> {start, count}
+const clientIp = (req) => (req.socket && req.socket.remoteAddress) || 'unknown';
+const authThrottled = (ip) => {
+  const b = authFails.get(ip);
+  return !!b && Date.now() - b.start <= AUTH_FAIL_WINDOW_MS && b.count >= AUTH_FAIL_LIMIT;
+};
+const noteAuthFail = (ip) => {
+  const t = Date.now();
+  let b = authFails.get(ip);
+  if (!b || t - b.start > AUTH_FAIL_WINDOW_MS) { b = { start: t, count: 0 }; authFails.set(ip, b); }
+  b.count += 1;
 };
 
+// Operator audit trail (v0.5.3): one structured stderr line per admin
+// action, so a paid host has a record of who did what to which workspace.
+// NEVER log keys or hashes — ids, actions, timestamps, source IPs only.
+const audit = (action, id, req) => {
+  process.stderr.write(JSON.stringify({ ts: new Date().toISOString(), audit: 'admin', action, workspace: id, ip: clientIp(req) }) + '\n');
+};
+
+const TOO_LARGE = Symbol('body-too-large');
+
 const LANDING = `<!doctype html><html><head><meta charset="utf-8"><title>GhostBus Hosted</title>
 <style>body{font-family:system-ui;background:#0e0c14;color:#ece8f5;margin:0;padding:40px}h1{font-size:22px}code{background:#17131f;padding:2px 7px;border-radius:6px;color:#c9b8ff}p{color:#9b8fb5;max-width:640px;line-height:1.55}</style></head>
 <body><h1>👻 GhostBus Hosted</h1>
@@ -99,19 +151,34 @@ const server = http.createServer(async (req, res) => {
   };
   res.setHeader('x-content-type-options', 'nosniff');
   res.setHeader('referrer-policy', 'no-referrer');
-  const readBody = () => new Promise((resolve) => {
-    let data = ''; req.on('data', c => { data += c; if (data.length > 5_000_000) req.destroy(); });
-    req.on('end', () => { try { resolve(data ? JSON.parse(data) : {}); } catch { resolve(null); } });
-  });
+  const ip = clientIp(req);
+  const adminDenied = () => { noteAuthFail(ip); return send(401, { error: 'admin key required' }); };
+  const readBody = async () => {
+    try { return await readJsonBody(req); }
+    catch (e) {
+      if (e && e.code === 'BODY_TOO_LARGE') {
+        try {
+          res.writeHead(413, { 'content-type': 'application/json', connection: 'close' });
+          res.end(JSON.stringify({ error: `request body too large (limit ${MAX_BODY_BYTES} bytes)` }), () => { try { req.destroy(); } catch {} });
+        } catch {}
+        return TOO_LARGE;
+      }
+      throw e;
+    }
+  };
 
   try {
-    if (req.method === 'GET' && url.pathname === '/') { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }); return res.end(LANDING); }
+    if (req.method === 'GET' && url.pathname === '/') { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', ...HTML_SECURITY_HEADERS }); return res.end(LANDING); }
     if (req.method === 'GET' && url.pathname === '/health') return send(200, { ok: true, server: 'ghostbus-hosted', version: GHOSTBUS_VERSION, workspaces: Object.keys(loadRegistry().workspaces).length });
 
     // ---- admin ----
+    // Failed-auth throttle (v0.5.3): sustained key guessing gets 429s on the
+    // whole admin surface before any key is even compared.
+    if (url.pathname.startsWith('/api/workspaces') && authThrottled(ip)) return send(429, { error: 'too many failed auth attempts — try again shortly' });
     if (url.pathname === '/api/workspaces' && req.method === 'POST') {
-      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      if (!isAdmin(req)) return adminDenied();
       const body = await readBody();
+      if (body === TOO_LARGE) return; // 413 already sent
       if (!body) return send(400, { error: 'invalid JSON body' });
       const reg = loadRegistry();
       const id = body.id || `ws-${crypto.randomBytes(4).toString('hex')}`;
@@ -120,10 +187,11 @@ const server = http.createServer(async (req, res) => {
       const key = crypto.randomBytes(24).toString('hex');
       reg.workspaces[id] = { name: String(body.name || id).slice(0, 120), keyHash: sha256(key), createdAt: new Date().toISOString() };
       saveRegistry(reg);
+      audit('create', id, req);
       return send(201, { id, name: reg.workspaces[id].name, key, keyNote: 'Workspace key — shown ONCE, only its hash is stored. Agents use it as x-bus-key (or Bearer) under /w/' + id + '/.', board: `/w/${id}/` });
     }
     if (url.pathname === '/api/workspaces' && req.method === 'GET') {
-      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      if (!isAdmin(req)) return adminDenied();
       const reg = loadRegistry();
       const out = [];
       for (const [id, meta] of Object.entries(reg.workspaces)) {
@@ -135,7 +203,7 @@ const server = http.createServer(async (req, res) => {
     }
     const rotateMatch = url.pathname.match(/^\/api\/workspaces\/([a-z0-9-]+)\/rotate-key$/);
     if (req.method === 'POST' && rotateMatch) {
-      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      if (!isAdmin(req)) return adminDenied();
       const reg = loadRegistry();
       const id = rotateMatch[1];
       if (!reg.workspaces[id]) return send(404, { error: `no such workspace: ${id}` });
@@ -146,20 +214,23 @@ const server = http.createServer(async (req, res) => {
       // Refresh the cached meta so the old key dies immediately, not on restart.
       const cached = buses.get(id);
       if (cached) cached.meta = reg.workspaces[id];
+      audit('rotate-key', id, req);
       return send(200, { id, key, keyNote: 'New workspace key — shown ONCE. The previous key is invalid from this moment.', keyRotatedAt: reg.workspaces[id].keyRotatedAt });
     }
     const exportMatch = url.pathname.match(/^\/api\/workspaces\/([a-z0-9-]+)\/export$/);
     if (req.method === 'GET' && exportMatch) {
-      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      if (!isAdmin(req)) return adminDenied();
       const id = exportMatch[1];
       const w = await getWorkspace(id);
       if (!w) return send(404, { error: `no such workspace: ${id}` });
       const state = await w.bus.snapshot();
+      audit('export', id, req);
       return send(200, { ghostbusExport: 1, version: GHOSTBUS_VERSION, exportedAt: new Date().toISOString(), workspace: { id, name: w.meta.name }, state });
     }
     if (url.pathname === '/api/workspaces/import' && req.method === 'POST') {
-      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      if (!isAdmin(req)) return adminDenied();
       const body = await readBody();
+      if (body === TOO_LARGE) return; // 413 already sent
       if (!body) return send(400, { error: 'invalid JSON body' });
       // Accept either a full export envelope or a bare {state} / raw state.
       const env = body.ghostbusExport ? body : null;
@@ -178,15 +249,17 @@ const server = http.createServer(async (req, res) => {
       // the bus sees exactly what a restart would see.
       const file = path.join(dataDir, `${id}.json`);
       const tmp = file + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 10);
-      fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+      fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 }); // state file: owner-only (v0.5.3)
+      try { fs.chmodSync(tmp, 0o600); } catch { /* mode already applied on create */ }
       fs.renameSync(tmp, file);
+      audit('import', id, req);
       const w = await getWorkspace(id);
       const status = await w.bus.status();
       return send(201, { id, name, key, keyNote: 'Workspace key — shown ONCE, only its hash is stored. Imported workspaces always get a FRESH key; the source key is not carried over.', agents: status.agents, messages: status.messages, tasks: status.tasks.total, board: `/w/${id}/` });
     }
     const delMatch = url.pathname.match(/^\/api\/workspaces\/([a-z0-9-]+)$/);
     if (req.method === 'DELETE' && delMatch) {
-      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      if (!isAdmin(req)) return adminDenied();
       const reg = loadRegistry();
       const id = delMatch[1];
       if (!reg.workspaces[id]) return send(404, { error: `no such workspace: ${id}` });
@@ -194,6 +267,7 @@ const server = http.createServer(async (req, res) => {
       saveRegistry(reg);
       buses.delete(id); handlers.delete(id);
       try { fs.unlinkSync(path.join(dataDir, `${id}.json`)); } catch {}
+      audit('delete', id, req);
       return send(200, { id, deleted: true });
     }
 
@@ -207,13 +281,15 @@ const server = http.createServer(async (req, res) => {
       sub.pathname = wMatch[2] || '/';
       // Open surfaces mirror the single relay: board page, health, probe.
       const open = sub.pathname === '/' || sub.pathname === '/health' || sub.pathname === '/probe';
-      if (!open && !wsKeyOk(req, w.meta)) return send(401, { error: 'missing or wrong workspace key' });
+      if (!open && authThrottled(ip)) return send(429, { error: 'too many failed auth attempts — try again shortly' });
+      if (!open && !wsKeyOk(req, w.meta)) { noteAuthFail(ip); return send(401, { error: 'missing or wrong workspace key' }); }
       return handlerFor(id, w.bus)(req, res, sub);
     }
 
     return send(404, { error: 'not found' });
   } catch (e) {
-    return send(500, { error: e.message });
+    process.stderr.write(`ghostbus hosted: internal error: ${(e && e.stack) || e}\n`);
+    return send(500, { error: 'internal error' });
   }
 });
 

package/src/http-server.mjs

@@ -23,14 +23,25 @@ const storePath = argVal('--store') || process.env.GHOSTBUS_STORE || './ghostbus
 const wsName = argVal('--name') || process.env.GHOSTBUS_WORKSPACE_NAME || 'GhostBus Workspace';
 const KEY = process.env.GHOSTBUS_KEY || '';
 
+const REQUIRE_TOKENS = process.env.GHOSTBUS_REQUIRE_TOKENS === '1';
 const store = storePath === ':memory:' ? new MemoryStore() : new FileStore(storePath);
-const bus = await createBus(store, { name: wsName }, { requireTokens: process.env.GHOSTBUS_REQUIRE_TOKENS === '1' });
+const bus = await createBus(store, { name: wsName }, { requireTokens: REQUIRE_TOKENS });
 const handle = createBusHandler({ id: 'default', bus, key: KEY });
 
 const server = http.createServer((req, res) => {
   const url = new URL(req.url, 'http://localhost');
-  handle(req, res, url).catch((e) => { try { res.writeHead(500, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: e.message })); } catch {} });
+  handle(req, res, url).catch((e) => { process.stderr.write(`ghostbus relay: internal error: ${(e && e.stack) || e}\n`); try { res.writeHead(500, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: 'internal error' })); } catch {} });
 });
 server.listen(port, () => {
   process.stderr.write(`ghostbus http relay v${GHOSTBUS_VERSION} · http://127.0.0.1:${port} · store=${storePath} · auth=${KEY ? 'workspace key required' : 'open (set GHOSTBUS_KEY)'}\n`);
+  // Node's listen() with no host binds ALL network interfaces, not just
+  // loopback — the 127.0.0.1 above is the local URL, not a bind restriction.
+  // Local trust is the relay's default model and stays unchanged, but an
+  // unkeyed or tokenless relay must never be network-reachable *silently*.
+  if (!KEY) {
+    process.stderr.write('WARNING: GHOSTBUS_KEY is not set — this relay is OPEN: anyone who can reach this port can read and write the workspace.\n');
+    process.stderr.write('WARNING: the relay listens on all network interfaces, not just localhost. Set GHOSTBUS_KEY (a long secret) before exposing it beyond this machine, or firewall the port.\n');
+  } else if (!REQUIRE_TOKENS) {
+    process.stderr.write('WARNING: per-agent tokens are not enforced (GHOSTBUS_REQUIRE_TOKENS is not 1): anyone holding the workspace key can act under any agent name. The relay listens on all network interfaces — set GHOSTBUS_REQUIRE_TOKENS=1 if untrusted agents share the key.\n');
+  }
 });