ghostbus 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.

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                      # 59 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security, hostile input
+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

@@ -165,6 +165,30 @@ validation:
   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.4"
+  "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.4';
+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.
@@ -36,6 +36,19 @@ 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 {
@@ -245,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);
@@ -265,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; }
@@ -399,7 +416,7 @@ 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];
@@ -495,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) })),
     };
   }
@@ -596,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)); }

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/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 });