ghostbus 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.5.5 — 2026-10-11
+
+Security hardening, round 4 — the client side of the wire. Rounds 2–3 hardened what the server stores and how it authenticates; this round fuzzed what a client can *send*: MCP tool arguments over stdio JSON-RPC, board payloads end-to-end, and raw HTTP parameters. One real crash, a class of silent state corruption, and a set of numeric edge cases were found and fixed. Several surfaces audited clean and are now pinned by tests instead — the entry says which, as usual.
+
+- **A single `null` line crashed the MCP server (fixed)** — `src/mcp-server.mjs` destructured every parsed line; a client (or a prompt-injected agent driving one) that sent a bare `null`, a string, a number, or an array killed the process with an unhandled TypeError, taking the bus down for every connected agent. Non-object frames are now ignored, and message handling is wrapped so one bad message can never be fatal. Verified: the pre-fix server exits with code 1 on the first hostile line; the fixed server drops all of them and keeps answering.
+- **Tool arguments are validated against their schemas (`src/tools.mjs`)** — the tools layer passed argument values straight into the core, which coerced: a message body sent as an object was *stored* as the literal string `"[object Object]"`, a body sent as an array as its first character, a numeric file path became a state key of the same number, a `threadId` sent as an object landed in memory as `NaN` (invisible until reload, when JSON rewrote it to `null`), and a null capsule slug created a capsule named `"null"`. One shared validator now runs before dispatch: required arguments must be present, declared types are enforced (strings stay strings, numbers must be finite, arrays and plain objects must be arrays and plain objects), and violations return the suite's existing clean error results. Arguments the schema doesn't declare (the optional per-agent `token`, for one) pass through untouched.
+- **Numeric parameters are clamped in the core** — the list/sync reads trusted their numbers: `limit=0` returned *every* message (slice(-0)), `limit=-1` returned all-but-one, events the same, and a garbage `sinceSeq` cursor made `bus_sync` report an agent as caught up (`truncated: false`) while replaying nothing. Limits now clamp (≤0 → none, absurd → the documented 500 cap, non-finite → the default page size) and a garbage cursor replays honestly from the start. Message thread ids are sanitized the same way — a non-numeric `threadId` is stored as `null`, never `NaN`.
+- **`/api/wait` never waits on a garbage timeout (fixed)** — `timeout=abc` made the long-poll reply instantly with an empty inbox and `waited: true`. A non-numeric or negative timeout now means the 25 s default; real values still clamp to [0, 55] s.
+- **Board task ids escape too** — the one board interpolation not routed through `esc()` was the task id in two templates. Ids are numbers from the core, so it was unreachable in normal operation, but a hand-crafted imported snapshot could put a string there; it goes through `esc()` now like everything else.
+- **Audited, already safe — now pinned by tests.** Board data path: hostile roles, message bodies, task titles, and file names seeded through the real API come back verbatim as JSON (inert by content type), every interpolated field is escaped, and the workspace key lives in local storage and travels as a header — never in a URL. `/probe` and `/health` return exactly their documented counts-only shapes. HTTP edges: method mismatches, trailing slashes, unknown routes, and URL-encoded traversal in workspace segments (`%2e%2e%2f`) all return clean 404s; a traversal-looking file path is an inert key miss (400), never a filesystem read. CLI: missing arguments, unknown commands, and bad values already exit non-zero with one-line errors and no stack dumps — pinned as-is. Prototype pollution through tool arguments: not reachable (JSON clone discipline), canary-checked in the fuzz.
+- **Tests** — five new checks (64 in the main suite, was 59): tools-boundary validation + core clamps (including that rejected calls store nothing), a bounded stdio fuzz (hostile raw frames, one wrong-typed variant for every declared property of all 29 tools, a 100 KB body, a 300-deep nested context, then bus-integrity assertions), the board data path, HTTP parameter edges on relay + hosted, and the CLI pins. Against the 0.5.4 code the new checks fail on the crash, the coercions, and the numeric semantics; with the change the full suite is green, serverless stays 6/6, and both demos pass.
+- **Scope boundary, honestly** — what did NOT change: no tool, route, or CLI behavior changes for well-formed input (valid calls produce identical results; the fuzz asserts registered-agent counts and a normal round-trip after the battery); argument validation rejects only values the schemas never allowed; the deferred networked multi-writer store is still future work.
+
+## 0.5.4 — 2026-10-11
+
+Security hardening, round 3 — hostile input: the values a malicious (or merely buggy) client controls, followed to the filesystem, the object graph, and state validation. Audit-first as usual: two of the five surfaces turned out to be already safe, and the entry says which and why rather than dressing them up as fixes.
+
+- **Shared-file name `__proto__` corrupted the file store (fixed)** — file names are keys in one plain object, and `_putFile` blocked `..` but nothing else. Writing a file named `__proto__` invoked the prototype setter on the files map: the record became the map's *prototype*, the "file" enumerated nowhere, and the store was silently corrupt (verified against 0.5.3). `constructor` had the mirror-image problem on reads (an inherited member instead of "not found"). Now: `__proto__` / `constructor` / `prototype` are refused at write ("path is a reserved name"), treated as absent at read/delete (own-property checks), and refused inside snapshots. Names that merely look like paths (`/abs/looking.txt`, backslashes, a NUL byte) remain what they always were — inert state keys, never filesystem paths; the suite proves nothing but the one store file appears on disk.
+- **Snapshot validation deepened from shape to usability** (`validateSnapshot` in `src/core.mjs`) — a snapshot is untrusted input (hosted import, CLI import, restore), and the old check waved through states that then crashed the bus on first use: `agents: [null]` passed and bricked every subsequent operation with a TypeError, a file with non-string `text` passed and broke search/sizing, negative seq counters passed. Now entries must be objects, agents need string names, files need string text, counters must be finite and non-negative, context must be an object or null, and counts have sanity caps far above anything the bus itself can produce (stored messages trim at 10k, events at 5k; caps are 10k agents/files, 100k messages/tasks/events). Compatibility is a hard constraint and is tested: real exports produced by the current code import cleanly (hosted round trip + core restore), as they did from v0.5.0–v0.5.3 shapes. Unknown *extra* top-level keys stay allowed — rejecting them would break forward compatibility for no safety gain; every known key is typed.
+- **Workspace ids validated at every boundary (defense in depth)** — create and import already enforced `^[a-z0-9][a-z0-9-]{1,62}$` and the routes are regex-bound, so remote traversal was already refused; the thin spot was the registry *file*: `getWorkspace` trusted its keys blindly, and a planted or hand-edited entry like `../escape` made the admin list load (and the bus write) a state file **outside** the data dir. The registry is now filtered through the id rule at load (invalid entries are ignored, with a one-time stderr warning per id), and workspace resolution re-checks the id before it can become a path.
+- **Channel named `__proto__` was dropped from channel counts (fixed)** — `_listChannels` accumulated into a plain `{}`; reads of the `__proto__` key hit the prototype and the count never landed. The accumulator is a null-prototype object now; the channel counts like any other.
+- **Prototype pollution: audited, not reachable — now pinned by canaries.** State enters only through `JSON.parse`, the core's JSON round-trip clone, and object spread — all own-property semantics — and a full-codebase hunt found no recursive merge and no `Object.assign` of caller data (the remaining `Object.assign` uses build Error objects from literals). Canary checks now attempt pollution through the context writer and through restore payloads (nested `__proto__` in workspace and context) and assert `Object.prototype` stays clean. The board page was audited in the same pass: every interpolated value already goes through its `esc()` helper, and the workspace name renders via `textContent`.
+- **Audit-log injection: audited, safe.** The v0.5.3 admin audit line is a single `JSON.stringify` of a fixed-shape record (timestamp, action literal, validated workspace id, socket IP); JSON encoding escapes any control characters, and no other user-controlled string (workspace names included) reaches the line.
+- **Tests** — five new checks (59 in the main suite, was 54): reserved file names + inert path-like names (with an on-disk assertion), deep snapshot validation + pollution canaries, `__proto__` channel counting, hosted traversal refusal at create and at import (explicit id, envelope id, and state id) with a hostile-envelope refusal and a clean legit import, and the planted-registry escape. All five fail against the 0.5.3 code (54 passed, 5 failed — each for its intended reason; in the hosted check, the id-traversal asserts already passed on 0.5.3 and the red assertion is the hostile envelope importing with 201) and pass with the change; serverless stays 6/6 and both demos green.
+- **Scope boundary, honestly** — what did NOT change: no API changes; no behavior change for legitimate names, ids, or exports; the single relay's store path is still operator-supplied (argv/env) and out of the remote-input surface; the serverless pack's registry lives in a KV store where ids are opaque keys, not paths — its ids still enter only through the same validated creation, and the core fixes (reserved file names, deep snapshot validation where it applies, channel counts) flow to it through the shared core. The networked multi-writer store is still future work.
+
 ## 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.

package/README.md

@@ -23,7 +23,7 @@ Built and in use: 29 MCP tools across presence, messages, tasks, a shared worksp
 ```bash
 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                      # 54 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security
+node test.mjs                      # 64 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security, hostile input, input fuzz
 node examples/three-agent-team.mjs # planner + builder + reviewer, no human relaying
 ```
 

package/docs/hosted.md

@@ -138,6 +138,57 @@ Round 2 (v0.5.3) closed the next layer:
 - **Reporting a vulnerability:** see `SECURITY.md` at the repo root
   (private email reporting, one-business-day acknowledgement).
 
+Round 3 (v0.5.4) hardened the input surface — values a hostile or buggy
+client controls, followed to the filesystem, the object graph, and state
+validation:
+
+- **Workspace ids are validated at every boundary.** Create and import
+  require `^[a-z0-9][a-z0-9-]{1,62}$`, the workspace routes only match that
+  shape, workspace resolution re-checks it, and the registry file itself is
+  filtered through the same rule when loaded — a planted or hand-edited
+  registry entry can never turn an id into a path outside the data dir.
+- **Shared-file names are state keys, never paths.** A name that merely
+  looks like a path is stored and returned as an inert key. The three names
+  that are special to a JavaScript object — `__proto__`, `constructor`,
+  `prototype` — are refused at write, treated as absent at read, and refused
+  inside snapshots (before v0.5.4, writing a file named `__proto__`
+  silently corrupted the workspace's file map).
+- **Snapshots and imports are deeply validated.** Collection entries must
+  be usable objects (agents need string names, files need string text),
+  counters must be finite and non-negative, and counts carry sanity caps
+  far above anything the bus itself produces. Every export made by
+  v0.5.0–v0.5.3 still imports — compatibility is covered by tests, not
+  assumed.
+- **Prototype pollution is not reachable.** State enters only through
+  `JSON.parse`, JSON round-trip cloning, and spread (all own-property
+  semantics); there is no recursive merge of caller data anywhere in the
+  codebase, and the suite carries canary checks that try anyway through
+  the context writer and restore payloads.
+
+Round 4 (v0.5.5) treated the clients themselves as untrusted input —
+including MCP clients and any agent driving one:
+
+- **MCP clients are untrusted input — say it plainly.** A client (or a
+  prompt-injected agent behind one) can send any argument shapes it wants.
+  Tool arguments are validated against each tool's declared schema at the
+  tools boundary: wrong-typed or non-finite values are rejected with a
+  clean error result, never coerced into shared state, and a malformed
+  JSON-RPC frame can no longer kill the stdio server process — bad frames
+  are dropped, the bus keeps serving every other agent.
+- **Numeric parameters are clamped everywhere.** Query and argument
+  numbers (`limit`, `sinceSeq`, timeouts) that arrive as garbage,
+  negatives, or absurd magnitudes fall back to defaults and documented
+  caps instead of slice-arithmetic surprises (a `limit` of 0 or -1 used
+  to return *more* data, and a garbage sync cursor falsely reported an
+  agent as caught up).
+- **The board's data path is pinned end-to-end.** Hostile roles, message
+  bodies, task titles, and file names are served verbatim as JSON data
+  (inert by content type), the page routes every interpolated field
+  through its HTML escaper, and the workspace key lives in local storage
+  and travels as a header — never in a URL, where it would land in logs
+  and referers. `/health` and `/probe` return exactly their documented
+  counts-only shapes.
+
 ## Option B — serverless on Netlify (Blobs)
 
 `deploy/netlify/` contains a Netlify Function implementing the same multi-workspace semantics over Netlify Blobs (strong consistency):

package/package.json

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

package/src/board.html

@@ -64,7 +64,7 @@ async function refresh(){
       `<div class="agent"><strong>${esc(a.name)}</strong><span class="pill ${a.online?'green':''}">${a.online?'online':'away'}</span><br><span class="muted">${esc(a.role||'agent')}${a.capabilities?.length ? ' · ' + esc(a.capabilities.join(', ')) : ''} · last seen ${esc(a.lastSeenAt)}</span></div>`).join('') : '<span class="muted">none registered</span>';
     const open = tasks.tasks.filter(t => !['done','cancelled'].includes(t.status));
     $('tasks').innerHTML = open.length ? open.map(t =>
-      `<div class="task">#${t.id} <strong>${esc(t.title)}</strong><span class="pill ${t.status==='needs-approval'?'amber':''}">${esc(t.status)}</span><br><span class="muted">from ${esc(t.from)}${t.claimedBy ? ' · claimed by ' + esc(t.claimedBy) : ''}${t.assignee ? ' · for ' + esc(t.assignee) : ''}</span></div>`).join('') : '<span class="muted">queue is empty</span>';
+      `<div class="task">#${esc(t.id)} <strong>${esc(t.title)}</strong><span class="pill ${t.status==='needs-approval'?'amber':''}">${esc(t.status)}</span><br><span class="muted">from ${esc(t.from)}${t.claimedBy ? ' · claimed by ' + esc(t.claimedBy) : ''}${t.assignee ? ' · for ' + esc(t.assignee) : ''}</span></div>`).join('') : '<span class="muted">queue is empty</span>';
     $('files').innerHTML = files.files.length ? files.files.map(f =>
       `<div class="file">📄 ${esc(f.path)}<br><span class="muted">${f.bytes} bytes · ${esc(f.updatedBy)} · ${esc(f.updatedAt)}</span></div>`).join('') : '<span class="muted">no shared files</span>';
     $('events').innerHTML = events.events.slice().reverse().map(e =>

package/src/core.mjs

@@ -14,7 +14,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-export const GHOSTBUS_VERSION = '0.5.3';
+export const GHOSTBUS_VERSION = '0.5.5';
 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.
@@ -24,9 +24,31 @@ const hashEqHex = (aHex, bHex) => {
 };
 export const TASK_STATUSES = ['queued', 'claimed', 'needs-approval', 'done', 'cancelled'];
 const CLAIM_LEASE_MS = 15 * 60 * 1000;
+// Shared-file names are keys in one plain object, never filesystem paths —
+// but three names are special to the object itself (v0.5.4): assigning
+// files['__proto__'] invokes the prototype setter and silently replaces the
+// map's prototype (the "file" then enumerates nowhere and the store is
+// corrupted), while reading files['constructor'] / files['__proto__'] on a
+// fresh map returns inherited members instead of "not found". Writes refuse
+// the three outright; reads treat them as absent; snapshots may not carry
+// them either (validateSnapshot below).
+const RESERVED_FILE_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
 
 const now = () => new Date().toISOString();
 const clone = (v) => JSON.parse(JSON.stringify(v));
+// Untrusted numeric inputs (HTTP query params, MCP arguments, direct API
+// callers) arrive as NaN, negatives, and absurd magnitudes, and raw
+// slice(-n) arithmetic turns them into nonsense: limit=0 or NaN returned
+// EVERYTHING (slice(-0) / slice(NaN) both mean "from the start"), limit=-1
+// returned all-but-one (v0.5.5). Every list/read path clamps through here:
+// non-finite -> the default, fractional -> floored, out-of-range -> the
+// [0, max] bound; a clamped limit of 0 honestly means "return none".
+const clampLimit = (v, def, max) => {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return def;
+  return Math.max(0, Math.min(Math.floor(n), max));
+};
+const tailSlice = (arr, lim) => (lim > 0 ? arr.slice(-lim) : []);
 
 function emptyState(workspace = {}) {
   return {
@@ -236,9 +258,13 @@ export class GhostBus {
     if (to !== '*') this._existsAgent(to);
     if (!body || !String(body).trim()) throw new Error('message body required');
     this.state.msgSeq += 1;
+    // threadId names a message id; anything that isn't a positive finite
+    // number (an object used to land here as NaN, invisible to thread()
+    // until a reload quietly rewrote it to null) is simply "no thread".
+    const tid = Number(threadId);
     const msg = {
       id: this.state.msgSeq, from, to, channel: String(channel).slice(0, 64),
-      body: String(body), threadId: threadId ? Number(threadId) : null,
+      body: String(body), threadId: Number.isFinite(tid) && tid >= 1 ? Math.floor(tid) : null,
       createdAt: now(), readBy: [from],
     };
     this.state.messages.push(msg);
@@ -256,7 +282,7 @@ export class GhostBus {
     let msgs = this.state.messages.filter(m =>
       m.to === agentName || m.to === '*' || m.from === agentName);
     if (unreadOnly) msgs = msgs.filter(m => !m.readBy.includes(agentName));
-    msgs = msgs.slice(-Math.min(limit, 500));
+    msgs = tailSlice(msgs, clampLimit(limit, 50, 500));
     if (markRead) {
       let changed = false;
       for (const m of msgs) if (!m.readBy.includes(agentName)) { m.readBy.push(agentName); changed = true; }
@@ -390,8 +416,9 @@ export class GhostBus {
   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');
+    if (typeof p !== 'string' || !p || typeof text !== 'string') throw new Error('path and text required');
     if (String(p).includes('..')) throw new Error('path may not contain ..');
+    if (RESERVED_FILE_NAMES.has(p)) throw new Error('path is a reserved name');
     const prev = this.state.files[p];
     const history = prev ? [...(prev.history || []), { text: prev.text, updatedBy: prev.updatedBy, updatedAt: prev.updatedAt }].slice(-10) : [];
     this.state.files[p] = { text, updatedBy: by, updatedAt: now(), history };
@@ -403,7 +430,7 @@ export class GhostBus {
   async getFile(...args) { return this._serialized(() => this._getFile(...args)); }
   async _getFile(p, { withHistory = false } = {}) {
     await this.init();
-    const f = this.state.files[p];
+    const f = Object.prototype.hasOwnProperty.call(this.state.files, p) ? this.state.files[p] : undefined;
     if (!f) throw new Error(`file not found: ${p}`);
     const { history, ...rest } = f;
     return { path: p, ...clone(rest), versions: (history || []).length + 1, ...(withHistory ? { history: clone(history || []) } : {}) };
@@ -412,7 +439,7 @@ export class GhostBus {
   async fileHistory(...args) { return this._serialized(() => this._fileHistory(...args)); }
   async _fileHistory(p) {
     await this.init();
-    const f = this.state.files[p];
+    const f = Object.prototype.hasOwnProperty.call(this.state.files, p) ? this.state.files[p] : undefined;
     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 || []) };
   }
@@ -461,7 +488,7 @@ export class GhostBus {
   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}`);
+    if (!Object.prototype.hasOwnProperty.call(this.state.files, p)) throw new Error(`file not found: ${p}`);
     delete this.state.files[p];
     this._event('file.delete', by, `${by} deleted ${p}`);
     await this._save();
@@ -471,7 +498,9 @@ export class GhostBus {
   async listChannels(...args) { return this._serialized(() => this._listChannels(...args)); }
   async _listChannels() {
     await this.init();
-    const counts = {};
+    // Channel names are attacker-chosen strings; a null-prototype map counts
+    // '__proto__' like any other channel instead of dropping it (v0.5.4).
+    const counts = Object.create(null);
     for (const m of this.state.messages) counts[m.channel] = (counts[m.channel] || 0) + 1;
     return Object.entries(counts).map(([channel, messages]) => ({ channel, messages })).sort((a, b) => b.messages - a.messages);
   }
@@ -483,11 +512,12 @@ export class GhostBus {
     const q = String(query || '').toLowerCase().trim();
     if (q.length < 2) throw new Error('search query needs at least 2 characters');
     const hit = (text) => String(text || '').toLowerCase().includes(q);
+    const lim = clampLimit(limit, 20, 500);
     return {
       query,
-      messages: clone(this.state.messages.filter(m => hit(m.body)).slice(-limit)),
-      tasks: clone(this.state.tasks.filter(t => hit(t.title) || hit(t.body) || hit(t.result)).slice(-limit)),
-      files: Object.entries(this.state.files).filter(([p, f]) => hit(p) || hit(f.text)).slice(0, limit)
+      messages: clone(tailSlice(this.state.messages.filter(m => hit(m.body)), lim)),
+      tasks: clone(tailSlice(this.state.tasks.filter(t => hit(t.title) || hit(t.body) || hit(t.result)), lim)),
+      files: Object.entries(this.state.files).filter(([p, f]) => hit(p) || hit(f.text)).slice(0, lim)
         .map(([p, f]) => ({ path: p, updatedBy: f.updatedBy, updatedAt: f.updatedAt, excerpt: f.text.slice(0, 200) })),
     };
   }
@@ -584,14 +614,20 @@ export class GhostBus {
   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) };
+    // A garbage cursor (NaN from a non-numeric query param) used to match
+    // NOTHING and report truncated:false — an offline agent would believe
+    // itself caught up while missing everything (v0.5.5). It now means
+    // what a missing cursor means: replay from the start, limit-bounded.
+    const since = Number.isFinite(Number(sinceSeq)) ? Math.max(0, Math.floor(Number(sinceSeq))) : 0;
+    const lim = clampLimit(limit, 500, 1000);
+    const evs = this.state.events.filter(e => e.seq > since);
+    return { events: clone(evs.slice(0, lim)), headSeq: this.state.seq, truncated: evs.length > lim };
   }
 
   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)));
+    return clone(tailSlice(this.state.events, clampLimit(limit, 50, 500)));
   }
 
   async status(...args) { return this._serialized(() => this._status(...args)); }
@@ -638,13 +674,46 @@ export class GhostBus {
 }
 
 /** Shape-check a candidate workspace snapshot. Returns null when valid,
- *  otherwise a short description of the first problem found. */
+ *  otherwise a short description of the first problem found.
+ *
+ *  v0.5.4 deepened this from "the collections exist" to "the collections are
+ *  usable": a snapshot is untrusted input (hosted import, CLI import,
+ *  restore), and the shallow check waved through states that then crashed
+ *  the bus on first use — agents:[null] (agent lookups destructure entries),
+ *  a file whose text is not a string (search/sizing throw), a negative seq
+ *  counter, a '__proto__' file name (see RESERVED_FILE_NAMES). Entries must
+ *  be objects, agents need string names (they are lookup keys), files need
+ *  string text, counters must be finite and non-negative, and counts get
+ *  sanity caps set far above anything the bus itself can produce (stored
+ *  messages trim at 10k, events at 5k), so every export made by v0.5.0–0.5.3
+ *  still validates. Unknown EXTRA top-level keys stay allowed on purpose:
+ *  rejecting them would break forward compatibility with newer exports for
+ *  no safety gain — the known keys are all typed here. */
+const SNAPSHOT_CAPS = { agents: 10_000, messages: 100_000, tasks: 100_000, events: 100_000, files: 10_000 };
+const isStateObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 export function validateSnapshot(s) {
-  if (!s || typeof s !== 'object' || Array.isArray(s)) return 'not an object';
-  if (!s.workspace || typeof s.workspace !== 'object') return 'missing workspace';
-  for (const k of ['seq', 'msgSeq', 'taskSeq']) if (typeof s[k] !== 'number') return `missing numeric ${k}`;
-  for (const k of ['agents', 'messages', 'tasks', 'events']) if (!Array.isArray(s[k])) return `missing array ${k}`;
-  if (!s.files || typeof s.files !== 'object' || Array.isArray(s.files)) return 'missing files object';
+  if (!isStateObject(s)) return 'not an object';
+  if (!isStateObject(s.workspace)) return 'missing workspace';
+  if (s.workspace.id !== undefined && typeof s.workspace.id !== 'string') return 'workspace.id must be a string';
+  if (s.workspace.name !== undefined && typeof s.workspace.name !== 'string') return 'workspace.name must be a string';
+  for (const k of ['seq', 'msgSeq', 'taskSeq']) {
+    if (typeof s[k] !== 'number' || !Number.isFinite(s[k]) || s[k] < 0) return `missing numeric ${k}`;
+  }
+  for (const k of ['agents', 'messages', 'tasks', 'events']) {
+    if (!Array.isArray(s[k])) return `missing array ${k}`;
+    if (s[k].length > SNAPSHOT_CAPS[k]) return `${k} exceeds sanity cap ${SNAPSHOT_CAPS[k]}`;
+    for (const el of s[k]) if (!isStateObject(el)) return `${k} entries must be objects`;
+  }
+  for (const a of s.agents) if (typeof a.name !== 'string' || !a.name) return 'agent entries need a string name';
+  if (!isStateObject(s.files)) return 'missing files object';
+  const fileNames = Object.keys(s.files);
+  if (fileNames.length > SNAPSHOT_CAPS.files) return `files exceeds sanity cap ${SNAPSHOT_CAPS.files}`;
+  for (const name of fileNames) {
+    if (RESERVED_FILE_NAMES.has(name)) return `files may not use reserved name: ${name}`;
+    const f = s.files[name];
+    if (!isStateObject(f) || typeof f.text !== 'string') return `file ${name} must be an object with string text`;
+  }
+  if (s.context !== undefined && s.context !== null && !isStateObject(s.context)) return 'context must be an object or null';
   return null;
 }
 

package/src/handler.mjs

@@ -139,7 +139,11 @@ export function createBusHandler({ id = 'default', bus, key = '' }) {
       if (req.method === 'GET' && url.pathname === '/api/wait') {
         const agent = url.searchParams.get('agent');
         if (!agent) return send(400, { error: 'agent query param required' });
-        const timeout = Math.min(Number(url.searchParams.get('timeout') || 25), 55) * 1000;
+        // Garbage timeouts (timeout=abc -> NaN -> an instant empty reply;
+        // negative -> the same) fall back to the 25s default; real values
+        // clamp into [0, 55]s (v0.5.5).
+        const tParam = Number(url.searchParams.get('timeout') || 25);
+        const timeout = (Number.isFinite(tParam) ? Math.min(Math.max(tParam, 0), 55) : 25) * 1000;
         const sinceSeq = url.searchParams.has('sinceSeq') ? Number(url.searchParams.get('sinceSeq')) : (await bus.sync({})).headSeq;
         const immediate = await bus.sync({ sinceSeq, limit: 100 });
         const relevantNow = immediate.events.filter(ev => ev.type !== 'message.send' || ev.to === agent || ev.to === '*' || ev.actor === agent);

package/src/hosted-server.mjs

@@ -27,6 +27,10 @@
  *   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).
+ * - v0.5.4: workspace ids are validated at EVERY boundary — create, import,
+ *   route matching (regex), workspace resolution, and the registry itself
+ *   when loaded: ids become file names inside the data dir, so a planted or
+ *   hand-edited registry entry must never turn one into a path outside it.
  */
 import http from 'node:http';
 import fs from 'node:fs';
@@ -62,7 +66,26 @@ if (!REQUIRE_TOKENS) {
 
 fs.mkdirSync(dataDir, { recursive: true });
 const registryPath = path.join(dataDir, 'registry.json');
-const loadRegistry = () => { try { return JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return { workspaces: {} }; } };
+const validId = (id) => /^[a-z0-9][a-z0-9-]{1,62}$/.test(String(id || ''));
+const warnedRegistryIds = new Set();
+const loadRegistry = () => {
+  let reg;
+  try { reg = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return { workspaces: {} }; }
+  if (!reg || typeof reg !== 'object' || !reg.workspaces || typeof reg.workspaces !== 'object') return { workspaces: {} };
+  // Defense in depth (v0.5.4): create/import validate ids, but the registry
+  // is also a file on disk — never let a planted or hand-edited entry turn
+  // into a path outside the data dir via getWorkspace's `${id}.json`.
+  for (const id of Object.keys(reg.workspaces)) {
+    if (!validId(id)) {
+      if (!warnedRegistryIds.has(id)) {
+        warnedRegistryIds.add(id);
+        process.stderr.write(`ghostbus hosted: ignoring registry entry with invalid workspace id ${JSON.stringify(id)} (ids become file names inside the data dir)\n`);
+      }
+      delete reg.workspaces[id];
+    }
+  }
+  return reg;
+};
 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).
@@ -77,10 +100,10 @@ const saveRegistry = (reg) => {
   }
 };
 const sha256 = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
-const validId = (id) => /^[a-z0-9][a-z0-9-]{1,62}$/.test(String(id || ''));
 
 const buses = new Map(); // id -> {bus, handle}
 async function getWorkspace(id) {
+  if (!validId(id)) return null; // an id is a file name inside dataDir — nothing else resolves (v0.5.4)
   if (buses.has(id)) return buses.get(id);
   const reg = loadRegistry();
   const meta = reg.workspaces[id];

package/src/mcp-server.mjs

@@ -56,6 +56,12 @@ rl.on('line', async (line) => {
   if (!line.trim()) return;
   let msg;
   try { msg = JSON.parse(line); } catch { return; }
-  await handle(msg);
+  // A JSON-RPC message is a plain object. Anything else on the wire — null,
+  // a bare string/number, an array — is ignored, never fatal (v0.5.5: one
+  // bare `null` line used to throw in handle() and kill the server process
+  // for every connected agent). And handle() itself is wrapped: one bad
+  // message must never take the bus down.
+  if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return;
+  try { await handle(msg); } catch { /* a malformed message is dropped, not fatal */ }
 });
 process.stderr.write(`ghostbus mcp-server v${GHOSTBUS_VERSION} · store=${storePath} · workspace="${wsName}"\n`);

package/src/tools.mjs

@@ -35,7 +35,45 @@ export const TOOLS = [
   { name: 'bus_events', description: 'Read the provenance event log (who did what, when).', inputSchema: { type: 'object', properties: { limit: { type: 'number', default: 50 } } } },
 ];
 
+// Argument validation (v0.5.5): an MCP client — or a prompt-injected agent
+// driving one — can send ANY argument shapes, and the core bus deliberately
+// coerces a lot (String(body) turned an object body into a stored
+// "[object Object]" message; a numeric `path` became a state key). The
+// tools layer is the trust boundary, so arguments are checked against the
+// tool's own declared inputSchema here, once, instead of per-tool ad-hoc
+// checks: required arguments must be present (null counts as missing, the
+// codebase's absent-value convention), and every provided argument must
+// match its declared type — numbers must be finite, objects must be plain
+// objects (not arrays/null). Undeclared extra arguments pass through
+// untouched (several tools read an undeclared `token`). Violations throw a
+// plain Error, which both transports already surface as a clean isError /
+// 400 result — never a crash, never coerced garbage in shared state.
+const ARG_TYPE_CHECKS = {
+  string: { ok: (v) => typeof v === 'string', label: 'a string' },
+  number: { ok: (v) => typeof v === 'number' && Number.isFinite(v), label: 'a finite number' },
+  boolean: { ok: (v) => typeof v === 'boolean', label: 'a boolean' },
+  array: { ok: (v) => Array.isArray(v), label: 'an array' },
+  object: { ok: (v) => !!v && typeof v === 'object' && !Array.isArray(v), label: 'an object' },
+};
+function validateToolArgs(tool, args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    throw new Error(`tool ${tool.name}: arguments must be an object`);
+  }
+  const schema = tool.inputSchema || {};
+  for (const k of schema.required || []) {
+    if (args[k] === undefined || args[k] === null) throw new Error(`tool ${tool.name}: missing required argument "${k}"`);
+  }
+  for (const [k, spec] of Object.entries(schema.properties || {})) {
+    const v = args[k];
+    if (v === undefined || v === null) continue; // absent optional — the ?? defaults below apply
+    const check = ARG_TYPE_CHECKS[spec.type];
+    if (check && !check.ok(v)) throw new Error(`tool ${tool.name}: argument "${k}" must be ${check.label}`);
+  }
+}
+
 export async function callTool(bus, name, args = {}) {
+  const tool = TOOLS.find(t => t.name === name);
+  if (tool) validateToolArgs(tool, args);
   switch (name) {
     case 'bus_status': return bus.status();
     case 'bus_register': return bus.registerAgent({ name: args.agent, role: args.role, capabilities: args.capabilities, token: args.token ?? null });