ghostbus 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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                      # 59 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security, hostile input
 node examples/three-agent-team.mjs # planner + builder + reviewer, no human relaying
 ```
 

package/docs/hosted.md

@@ -138,6 +138,33 @@ 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.
+
 ## 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.4"
 }

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.4';
 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,6 +24,15 @@ 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));
@@ -392,6 +401,7 @@ export class GhostBus {
     this._requireAgent(by, token);
     if (!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 +413,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 +422,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 +471,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 +481,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);
   }
@@ -638,13 +650,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/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];