@ijfw/memory-server 1.4.1 → 1.4.3

package/src/extension-quota-tracker.js

@@ -0,0 +1,305 @@
+/**
+ * extension-quota-tracker.js — IJFW v1.4.3 W9-A3 (B16)
+ *
+ * Per-extension resource quotas. Counter state lives at
+ * `~/.ijfw/state/extension-quotas.json`. Every read-modify-write goes through
+ * `withFsLock(~/.ijfw/state/extension-quotas.json.lock, fn, { staleMs })` so
+ * cross-process tool invocations cannot race the counter (SEC-H-01).
+ *
+ * "Session" semantics (SEC-M-02): one activation = one quota window. Counters
+ * reset on `activate <name>` AND on `deactivate`. NO cumulative state across
+ * activate/deactivate boundaries — a re-activated extension gets a clean slate.
+ *
+ * Wall-clock dimension (SEC-M-02): never incremented; computed on each check
+ * as `Date.now() - activated_at`.
+ *
+ * Threat boundary (ARCH-M-01): API-level accounting, NOT OS-level resource
+ * limits. See docs/EXTENSION-SECURITY.md.
+ *
+ * Frozen contract: `getQuotaUsage` return shape is the integration point with
+ * B19 dashboard. See docstring on that function.
+ */
+
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { withFsLock } from './fs-lock.js';
+
+const STATE_REL = ['.ijfw', 'state', 'extension-quotas.json'];
+
+// R12-L-02 — acquireTimeoutMs sizing rationale.
+//
+// Default fs-lock timeout is 5s. That ceiling is wrong for THIS lock for a
+// specific, measured reason: the quota tracker is the single chokepoint for
+// every concurrent tool dispatch on a session. With BACKOFF_MAX_MS=250ms in
+// fs-lock.js and ~100 contending Promise.all callers, the worst-case wait
+// approaches `100 * 250ms = 25s`. The 100-parallel correctness test in
+// test-extension-quota-tracker.js exercises exactly this; we pin
+// QUOTA_LOCK_TIMEOUT_MS=30_000 with one second of margin.
+//
+// staleMs stays at 30_000 (crash recovery, unrelated to acquisition latency).
+//
+// Audit history: codex+gemini R12 flagged the literal 30_000 as "too long for
+// hot path". The audit was treating the timeout as the *typical* wait when in
+// reality it's the worst-case ceiling under a workload the test suite
+// explicitly covers. Lowering it broke that test (see commits 45389ff +
+// a996abd in the R12-fix branch).
+const QUOTA_LOCK_TIMEOUT_MS = 30_000;
+const QUOTA_LOCK_STALE_MS = 30_000;
+
+/** Public dimensions. Manifest-side names are `max_<dim>`. */
+export const QUOTA_DIMENSIONS = Object.freeze([
+  'files_written',
+  'bytes_written',
+  'wall_clock_ms',
+]);
+
+function homeFromOpts(opts) {
+  if (opts && opts.homeDir) return opts.homeDir;
+  return process.env.HOME || process.env.USERPROFILE || homedir();
+}
+
+function statePath(home) {
+  return join(home, ...STATE_REL);
+}
+
+function lockPath(home) {
+  return statePath(home) + '.lock';
+}
+
+/**
+ * Ensure ~/.ijfw/state exists before withFsLock tries to mkdir the lock
+ * directory inside it. Cheap idempotent — first caller creates, subsequent
+ * callers no-op. Without this, the first quota call on a fresh HOME would
+ * ENOENT (parent missing).
+ */
+async function ensureStateDir(home) {
+  await mkdir(dirname(statePath(home)), { recursive: true });
+}
+
+/**
+ * Read raw quota state from disk. Returns `{}` when missing or unparseable.
+ * Caller is responsible for holding `withFsLock` for R/M/W flows.
+ */
+export async function readQuotaState(home) {
+  const h = home || homeFromOpts({});
+  try {
+    const raw = await readFile(statePath(h), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Atomic tmp+rename write of the entire quota state file. MUST be called
+ * inside `withFsLock`.
+ */
+export async function writeQuotaState(home, state) {
+  const h = home || homeFromOpts({});
+  const path = statePath(h);
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${randomBytes(4).toString('hex')}`;
+  await writeFile(tmp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  await rename(tmp, path);
+}
+
+function emptyExt() {
+  return {
+    files_written: { current: 0, writes_by_path: {} },
+    bytes_written: { current: 0 },
+    activated_at: null,
+  };
+}
+
+function ensureExt(state, extName) {
+  if (!state[extName]) state[extName] = emptyExt();
+  // Defensive: fill missing sub-fields so callers in older state files don't
+  // crash. Reading is permissive; writing is canonical.
+  if (!state[extName].files_written) state[extName].files_written = { current: 0, writes_by_path: {} };
+  if (!state[extName].files_written.writes_by_path) state[extName].files_written.writes_by_path = {};
+  if (typeof state[extName].files_written.current !== 'number') state[extName].files_written.current = 0;
+  if (!state[extName].bytes_written) state[extName].bytes_written = { current: 0 };
+  if (typeof state[extName].bytes_written.current !== 'number') state[extName].bytes_written.current = 0;
+  if (state[extName].activated_at === undefined) state[extName].activated_at = null;
+  return state[extName];
+}
+
+/**
+ * checkAndIncrement(extName, dimension, increment, limit, opts)
+ *
+ * For `files_written`: `opts.path` provides the absolute path being written;
+ * tracker deduplicates so writing the same file 10 times = 1 toward the cap.
+ *
+ * For `wall_clock_ms`: never incremented; the check compares
+ * `Date.now() - activated_at` against `limit`. `increment` is ignored.
+ *
+ * Returns { allowed, current, limit, reason? }. When `limit` is null/undefined
+ * (no quota declared), returns allowed=true and the current observed value.
+ */
+export async function checkAndIncrement(extName, dimension, increment, limit, opts = {}) {
+  if (typeof extName !== 'string' || !extName) {
+    return { allowed: false, current: 0, limit: limit ?? null, reason: 'invalid ext name' };
+  }
+  if (!QUOTA_DIMENSIONS.includes(dimension)) {
+    return { allowed: false, current: 0, limit: limit ?? null, reason: `unknown dimension: ${dimension}` };
+  }
+  const home = homeFromOpts(opts);
+
+  // Back-compat: no limit declared = no enforcement. Still record the
+  // increment so getQuotaUsage reflects activity. EXCEPT wall_clock_ms which
+  // is computed-not-stored, so skip the R/M/W entirely.
+  const limitIsNull = limit === null || limit === undefined;
+
+  await ensureStateDir(home);
+
+  if (dimension === 'wall_clock_ms') {
+    // Read-only path.
+    return await withFsLock(lockPath(home), async () => {
+      const state = await readQuotaState(home);
+      const ext = state[extName];
+      if (!ext || !ext.activated_at) {
+        // Not active — wall clock is 0.
+        return { allowed: true, current: 0, limit: limitIsNull ? null : limit };
+      }
+      const activatedMs = Date.parse(ext.activated_at);
+      const elapsed = Number.isFinite(activatedMs) ? Math.max(0, Date.now() - activatedMs) : 0;
+      if (!limitIsNull && elapsed > limit) {
+        return {
+          allowed: false,
+          current: elapsed,
+          limit,
+          reason: `wall_clock_ms ${elapsed} > limit ${limit}`,
+        };
+      }
+      return { allowed: true, current: elapsed, limit: limitIsNull ? null : limit };
+    }, { staleMs: QUOTA_LOCK_STALE_MS, acquireTimeoutMs: QUOTA_LOCK_TIMEOUT_MS });
+  }
+
+  return await withFsLock(lockPath(home), async () => {
+    const state = await readQuotaState(home);
+    const ext = ensureExt(state, extName);
+
+    let nextCurrent;
+    if (dimension === 'files_written') {
+      const path = opts && typeof opts.path === 'string' ? opts.path : null;
+      if (path && ext.files_written.writes_by_path[path]) {
+        // Already counted — dedupe.
+        nextCurrent = ext.files_written.current;
+      } else {
+        nextCurrent = ext.files_written.current + (Number.isFinite(increment) ? increment : 1);
+      }
+
+      // Enforcement check BEFORE persisting the increment.
+      if (!limitIsNull && nextCurrent > limit) {
+        return {
+          allowed: false,
+          current: ext.files_written.current,
+          limit,
+          reason: `files_written ${nextCurrent} > limit ${limit}`,
+        };
+      }
+
+      ext.files_written.current = nextCurrent;
+      if (path) ext.files_written.writes_by_path[path] = true;
+    } else {
+      // bytes_written
+      const inc = Number.isFinite(increment) ? increment : 0;
+      nextCurrent = ext.bytes_written.current + inc;
+      if (!limitIsNull && nextCurrent > limit) {
+        return {
+          allowed: false,
+          current: ext.bytes_written.current,
+          limit,
+          reason: `bytes_written ${nextCurrent} > limit ${limit}`,
+        };
+      }
+      ext.bytes_written.current = nextCurrent;
+    }
+
+    await writeQuotaState(home, state);
+    return { allowed: true, current: nextCurrent, limit: limitIsNull ? null : limit };
+  }, { staleMs: QUOTA_LOCK_STALE_MS, acquireTimeoutMs: QUOTA_LOCK_TIMEOUT_MS });
+}
+
+/**
+ * resetExtensionQuotas(extName, opts) — clears all counters for one extension.
+ * Called on `activate` (clears stale prior-session state) AND on `deactivate`.
+ *
+ * `opts.activated_at` may be passed to stamp the new activation window. When
+ * omitted, the entry is removed entirely (deactivate semantics).
+ */
+export async function resetExtensionQuotas(extName, opts = {}) {
+  if (typeof extName !== 'string' || !extName) return;
+  const home = homeFromOpts(opts);
+  await ensureStateDir(home);
+  await withFsLock(lockPath(home), async () => {
+    const state = await readQuotaState(home);
+    if (opts && typeof opts.activated_at === 'string') {
+      state[extName] = emptyExt();
+      state[extName].activated_at = opts.activated_at;
+    } else {
+      delete state[extName];
+    }
+    await writeQuotaState(home, state);
+  }, { staleMs: QUOTA_LOCK_STALE_MS, acquireTimeoutMs: QUOTA_LOCK_TIMEOUT_MS });
+}
+
+/**
+ * getQuotaUsage(extName, opts) — frozen B19 contract.
+ *
+ * Shape:
+ * {
+ *   ext_name: string,
+ *   activated_at: ISO string | null,
+ *   dimensions: {
+ *     files_written: { current: number, limit: number | null },
+ *     bytes_written: { current: number, limit: number | null },
+ *     wall_clock_ms: { current: number, limit: number | null }
+ *   }
+ * }
+ *
+ * `limit === null` → no quota declared for that dimension (chart renders
+ * "unlimited"). Limits are sourced from `opts.limits` when provided (the
+ * dashboard reads the active extension's manifest and passes them in);
+ * otherwise null.
+ *
+ * For an extName with no recorded activity: returns the shape with zeros and
+ * null limits. Never throws on missing extension.
+ */
+export async function getQuotaUsage(extName, opts = {}) {
+  const home = homeFromOpts(opts);
+  const limits = (opts && opts.limits) || {};
+  await ensureStateDir(home);
+
+  return await withFsLock(lockPath(home), async () => {
+    const state = await readQuotaState(home);
+    const ext = state[extName] || null;
+    const filesCurrent = ext && ext.files_written ? (ext.files_written.current || 0) : 0;
+    const bytesCurrent = ext && ext.bytes_written ? (ext.bytes_written.current || 0) : 0;
+    let wallCurrent = 0;
+    if (ext && ext.activated_at) {
+      const t = Date.parse(ext.activated_at);
+      if (Number.isFinite(t)) wallCurrent = Math.max(0, Date.now() - t);
+    }
+    const limitOrNull = (k) => {
+      const v = limits[k];
+      return typeof v === 'number' && Number.isFinite(v) ? v : null;
+    };
+    return {
+      ext_name: extName,
+      activated_at: ext && ext.activated_at ? ext.activated_at : null,
+      dimensions: {
+        files_written: { current: filesCurrent, limit: limitOrNull('max_files_written') },
+        bytes_written: { current: bytesCurrent, limit: limitOrNull('max_bytes_written') },
+        wall_clock_ms: { current: wallCurrent, limit: limitOrNull('max_wall_clock_ms') },
+      },
+    };
+  }, { staleMs: QUOTA_LOCK_STALE_MS, acquireTimeoutMs: QUOTA_LOCK_TIMEOUT_MS });
+}

package/src/extension-registry-ws.js

@@ -0,0 +1,347 @@
+/**
+ * extension-registry-ws.js — IJFW v1.4.3/B17 WebSocket revocation client (stub).
+ *
+ * Dormant by default. Imported via `await import(...)` ONLY when
+ * `process.env.IJFW_REGISTRY_WS_URL` is set at startup. Listening on the
+ * registry meta-key for live revocation push messages.
+ *
+ * Frozen contract (SEC-H-02):
+ *   - Source binding is explicit. Prefer `IJFW_REGISTRY_WS_SOURCE=<name>`
+ *     for an exact match in registries.json. If only `IJFW_REGISTRY_WS_URL`
+ *     is set, map to a source by origin + pathname-prefix (NEVER host-only).
+ *     Zero matches → refuse. Multiple matches → refuse with "set
+ *     IJFW_REGISTRY_WS_SOURCE".
+ *   - Signed-payload schema:
+ *       { registry_version: "1.0", source_name, source_url, updated_at,
+ *         revoked: [...], sequence_number, signature: "ed25519:<b64>" }
+ *     Canonical bytes = sorted-keys JSON minus `signature`. Replay defense:
+ *     reject any `sequence_number <= last_seen_sequence`.
+ *   - Handshake (ARCH-L-02): in the `node:net` fallback, generate a random
+ *     16-byte Sec-WebSocket-Key (base64). Expect
+ *     `Sec-WebSocket-Accept = base64(sha1(key + GUID))`. Refuse on mismatch.
+ *
+ * Zero new prod deps. Uses node:net + node:crypto + node:url.
+ *
+ * The SERVER infrastructure ships in v1.5.0; v1.4.3 only ships this CLIENT
+ * stub.
+ */
+
+import { createHash, randomBytes, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { URL } from 'node:url';
+
+import {
+  loadRegistrySources,
+  withSourceCache,
+  perSourceCachePath,
+  perSourceLockPath,
+} from './extension-registry.js';
+
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+// ---------------------------------------------------------------------------
+// Source binding (SEC-H-02)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve which source the WS client should bind to.
+ *
+ * @param {object} env — { IJFW_REGISTRY_WS_URL, IJFW_REGISTRY_WS_SOURCE }
+ * @param {Array} sources — list from loadRegistrySources()
+ * @returns {{ source: object } | { error: string }}
+ */
+export function resolveWsSource(env, sources) {
+  const explicit = env.IJFW_REGISTRY_WS_SOURCE;
+  if (typeof explicit === 'string' && explicit !== '') {
+    const found = sources.find((s) => s.name === explicit);
+    if (!found) {
+      return {
+        error: `[ijfw] IJFW_REGISTRY_WS_SOURCE='${explicit}' has no matching entry in registries.json`,
+      };
+    }
+    return { source: found };
+  }
+
+  const wsUrl = env.IJFW_REGISTRY_WS_URL;
+  if (typeof wsUrl !== 'string' || wsUrl === '') {
+    return { error: '[ijfw] neither IJFW_REGISTRY_WS_SOURCE nor IJFW_REGISTRY_WS_URL set' };
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(wsUrl);
+  } catch {
+    return { error: `[ijfw] IJFW_REGISTRY_WS_URL '${wsUrl}' is not a valid URL` };
+  }
+
+  // The WS scheme and the source's HTTPS scheme differ by protocol, so we
+  // match on host + path-prefix (NOT origin — origin includes scheme). We do
+  // however enforce TLS pairing: wss ↔ https, ws ↔ http. Cross-tier (e.g.
+  // ws:// WS endpoint paired to an https:// registry) is refused to prevent
+  // downgrade attacks where an attacker proxies plaintext push traffic for
+  // an otherwise-TLS registry.
+  const SCHEME_PAIRS = { 'wss:': 'https:', 'ws:': 'http:' };
+  const requiredSourceProto = SCHEME_PAIRS[parsed.protocol];
+  if (!requiredSourceProto) {
+    return {
+      error: `[ijfw] IJFW_REGISTRY_WS_URL '${wsUrl}' must use ws:// or wss:// scheme`,
+    };
+  }
+  const wsHost = parsed.host;
+  const wsPathPrefix = parsed.pathname.split('/').slice(0, -1).join('/');
+
+  const matches = [];
+  for (const source of sources) {
+    try {
+      const su = new URL(source.url);
+      if (su.protocol !== requiredSourceProto) continue;  // refuse cross-tier
+      const sourcePathPrefix = su.pathname.split('/').slice(0, -1).join('/');
+      if (su.host === wsHost && sourcePathPrefix === wsPathPrefix) {
+        matches.push(source);
+      }
+    } catch {
+      // skip unparseable source URLs
+    }
+  }
+
+  if (matches.length === 0) {
+    return {
+      error: `[ijfw] IJFW_REGISTRY_WS_URL '${wsUrl}' has no source binding; set IJFW_REGISTRY_WS_SOURCE=<name> explicitly`,
+    };
+  }
+  if (matches.length > 1) {
+    return {
+      error: `[ijfw] Ambiguous WS source binding for '${wsUrl}' (matches: ${matches.map((s) => s.name).join(', ')}); set IJFW_REGISTRY_WS_SOURCE=<name>`,
+    };
+  }
+  return { source: matches[0] };
+}
+
+// ---------------------------------------------------------------------------
+// Signed-payload schema verification (SEC-H-02)
+// ---------------------------------------------------------------------------
+
+function sortKeysDeep(v) {
+  if (Array.isArray(v)) return v.map(sortKeysDeep);
+  if (v !== null && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) {
+      if (v[k] === undefined) continue;
+      out[k] = sortKeysDeep(v[k]);
+    }
+    return out;
+  }
+  return v;
+}
+
+function pushPayloadCanonicalBytes(payload) {
+  const shallow = {};
+  for (const k of Object.keys(payload)) {
+    if (k === 'signature') continue;
+    shallow[k] = payload[k];
+  }
+  return Buffer.from(JSON.stringify(sortKeysDeep(shallow)), 'utf8');
+}
+
+/**
+ * Verify a WS push message.
+ *
+ * @param {object} payload
+ * @param {object} source — bound source (provides meta_key_pem, name, url)
+ * @param {number} lastSeenSequence
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export function verifyPushPayload(payload, source, lastSeenSequence) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return { valid: false, reason: 'payload must be a JSON object' };
+  }
+  if (payload.registry_version !== '1.0') {
+    return { valid: false, reason: `unsupported registry_version: ${payload.registry_version}` };
+  }
+  if (typeof payload.source_name !== 'string' || payload.source_name !== source.name) {
+    return {
+      valid: false,
+      reason: `source_name mismatch (expected '${source.name}', got '${payload.source_name}')`,
+    };
+  }
+  if (typeof payload.source_url !== 'string' || payload.source_url !== source.url) {
+    return {
+      valid: false,
+      reason: `source_url mismatch (expected '${source.url}', got '${payload.source_url}')`,
+    };
+  }
+  if (typeof payload.updated_at !== 'string') {
+    return { valid: false, reason: 'updated_at must be a string' };
+  }
+  if (!Array.isArray(payload.revoked)) {
+    return { valid: false, reason: 'revoked must be an array' };
+  }
+  if (typeof payload.sequence_number !== 'number' || !Number.isFinite(payload.sequence_number)) {
+    return { valid: false, reason: 'sequence_number must be a finite number' };
+  }
+  if (payload.sequence_number <= lastSeenSequence) {
+    return {
+      valid: false,
+      reason: `replay rejected (sequence_number ${payload.sequence_number} <= last_seen ${lastSeenSequence})`,
+    };
+  }
+  if (typeof payload.signature !== 'string' || !payload.signature.startsWith('ed25519:')) {
+    return { valid: false, reason: 'signature must be "ed25519:<base64>"' };
+  }
+
+  let metaKey;
+  try {
+    metaKey = createPublicKey(source.meta_key_pem);
+  } catch (err) {
+    return { valid: false, reason: `meta-key parse failed: ${err.message}` };
+  }
+  const sigBuf = Buffer.from(payload.signature.slice('ed25519:'.length), 'base64');
+  const bytes = pushPayloadCanonicalBytes(payload);
+  let ok;
+  try {
+    ok = cryptoVerify(null, bytes, metaKey, sigBuf);
+  } catch (err) {
+    return { valid: false, reason: `signature verify threw: ${err.message}` };
+  }
+  if (!ok) {
+    return { valid: false, reason: 'signature does not verify against source meta-key' };
+  }
+  return { valid: true };
+}
+
+/**
+ * Apply a verified push payload to the bound source's per-source cache.
+ * Merges `revoked` entries (de-dup by keyId) inside withFsLock.
+ */
+export async function applyPushPayload(payload, source) {
+  return withSourceCache(source, (cache) => {
+    const existingKeyIds = new Set((cache.revoked || []).map((r) => r.keyId));
+    const merged = [...(cache.revoked || [])];
+    for (const entry of payload.revoked) {
+      if (entry && entry.keyId && !existingKeyIds.has(entry.keyId)) {
+        existingKeyIds.add(entry.keyId);
+        merged.push({
+          keyId: entry.keyId,
+          revoked_at: entry.revoked_at || new Date().toISOString(),
+          reason: entry.reason || '',
+          superseded_by: entry.superseded_by || null,
+        });
+      }
+    }
+    return {
+      ...cache,
+      revoked: merged,
+      revocation_fetched_at: new Date().toISOString(),
+      source_name: source.name,
+      source_url: source.url,
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Handshake helpers (ARCH-L-02)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a 16-byte random base64 Sec-WebSocket-Key.
+ */
+export function generateSecWebSocketKey() {
+  return randomBytes(16).toString('base64');
+}
+
+/**
+ * Compute the expected Sec-WebSocket-Accept value for a given key.
+ */
+export function expectedAcceptValue(key) {
+  return createHash('sha1').update(key + WS_GUID).digest('base64');
+}
+
+/**
+ * Verify a server response's Sec-WebSocket-Accept against our key.
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function verifyHandshakeAccept(key, accept) {
+  if (typeof accept !== 'string' || accept === '') {
+    return { ok: false, reason: 'Sec-WebSocket-Accept header missing' };
+  }
+  const expected = expectedAcceptValue(key);
+  // constant-time compare via Buffer comparison
+  const aBuf = Buffer.from(expected, 'utf8');
+  const bBuf = Buffer.from(accept, 'utf8');
+  if (aBuf.length !== bBuf.length) {
+    return { ok: false, reason: 'Sec-WebSocket-Accept length mismatch' };
+  }
+  let diff = 0;
+  for (let i = 0; i < aBuf.length; i++) diff |= aBuf[i] ^ bBuf[i];
+  if (diff !== 0) return { ok: false, reason: 'Sec-WebSocket-Accept mismatch' };
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// Client controller (lightweight; tests drive parts in isolation).
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct a controller bound to a source. The controller exposes verify +
+ * apply hooks for the test surface; the wire-level connect path uses native
+ * `globalThis.WebSocket` when available, else `node:net`. v1.4.3 ships only
+ * the stub; the active connect loop is gated behind an explicit `connect()`
+ * call so MCP startup never accidentally opens a socket.
+ */
+export class WsRevocationClient {
+  constructor({ source }) {
+    if (!source || typeof source !== 'object') {
+      throw new Error('WsRevocationClient: source is required');
+    }
+    this.source = source;
+    this._lastSeenSequence = -Infinity;
+    this._socket = null;
+  }
+
+  /**
+   * Process an incoming JSON-text message. Returns { applied, reason }.
+   */
+  async handleMessage(raw) {
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch (err) {
+      return { applied: false, reason: `parse_error:${err.message}` };
+    }
+    const verdict = verifyPushPayload(payload, this.source, this._lastSeenSequence);
+    if (!verdict.valid) {
+      return { applied: false, reason: verdict.reason };
+    }
+    await applyPushPayload(payload, this.source);
+    this._lastSeenSequence = payload.sequence_number;
+    return { applied: true, sequence_number: payload.sequence_number };
+  }
+
+  /**
+   * Reset the replay-defense counter — test-only.
+   */
+  _resetSequenceForTest() {
+    this._lastSeenSequence = -Infinity;
+  }
+}
+
+/**
+ * Initialise the WS client at MCP startup. Caller must check
+ * `process.env.IJFW_REGISTRY_WS_URL` BEFORE importing this module.
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.env] — env override for tests
+ * @param {Array} [opts.sources] — source list override for tests
+ * @returns {Promise<{ ok: true, client: WsRevocationClient } | { ok: false, error: string }>}
+ */
+export async function initWsClient(opts = {}) {
+  const env = opts.env || process.env;
+  const sources = opts.sources || (await loadRegistrySources());
+  const resolved = resolveWsSource(env, sources);
+  if ('error' in resolved) {
+    return { ok: false, error: resolved.error };
+  }
+  return { ok: true, client: new WsRevocationClient({ source: resolved.source }) };
+}
+
+// Re-export paths so callers can introspect cache locations.
+export { perSourceCachePath, perSourceLockPath, WS_GUID };