@twinsearth/w2m-dsh-plugin 1.1.15 → 1.1.17

package/src/relay/fleet-messages.mjs

@@ -0,0 +1,145 @@
+/**
+ * Fleet chat: plain-text messages scoped to a SESSION, with a byte budget.
+ *
+ * ## Why the session is the scope
+ *
+ * The operator's decision: messages belong to the conversation, like a group chat, and disappear with it. A machine that
+ * joins or leaves a session changes who can read the flow, but never rewrites what was said -- and deleting the session
+ * deletes the history, because keeping it would be a second, silently-growing store nobody asked for.
+ *
+ * ## The quota, as specified
+ *
+ * 100 MB per fleet per 24 hours is the baseline; when that is exceeded, the 7-day retention figure is compared and the
+ * larger is kept, capped at 200 MB:
+ *
+ *     limit = min(hardCap, max(quota24h, used7d))
+ *
+ * A message over the limit is REFUSED with the current usage attached -- never silently dropped, and never accepted by
+ * evicting somebody else's words. The relay is the only clock here: a client-chosen timestamp would let one machine
+ * claim its messages are older than they are.
+ *
+ * ## Sharding is not this file
+ *
+ * This keeps the authoritative list in memory for the relay to serve and to shard out; distributing encrypted shards
+ * across the fleet's machines is the next step and depends on this shape staying the same.
+ */
+
+/** 100 MB per 24h per fleet (operator decision). */
+export const QUOTA_24H_BYTES = 100 * 1024 * 1024;
+/** Hard ceiling regardless of how much the 7-day window would allow. */
+export const HARD_CAP_BYTES = 200 * 1024 * 1024;
+/** Retention window used for the "keep the larger" comparison. */
+export const RETENTION_DAYS = 7;
+/** One message. Text is cheap; a 4 KiB cap keeps a single paste from eating the budget. */
+export const MAX_MESSAGE_BYTES = 4 * 1024;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * @param {{now?: () => number, quota24hBytes?: number, hardCapBytes?: number, retentionDays?: number,
+ *          maxMessageBytes?: number}} [options]
+ */
+export function createFleetMessages(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now();
+  const quota24hBytes = Number.isInteger(options.quota24hBytes) ? options.quota24hBytes : QUOTA_24H_BYTES;
+  const hardCapBytes = Number.isInteger(options.hardCapBytes) ? options.hardCapBytes : HARD_CAP_BYTES;
+  const retentionDays = Number.isInteger(options.retentionDays) ? options.retentionDays : RETENTION_DAYS;
+  const maxMessageBytes = Number.isInteger(options.maxMessageBytes) ? options.maxMessageBytes : MAX_MESSAGE_BYTES;
+
+  /**
+   * Notification subscribers. An event carries NO text: the notification says "there is something new to read", and the
+   * reader fetches the text through the endpoint that already authenticates them. Putting the text in a broadcast would
+   * send every message to every connected listener regardless of session membership.
+   */
+  const listeners = new Set();
+  /** session_id -> [{ message_id, session_id, machine_id, text, at_ms, bytes }] */
+  const sessions = new Map();
+  let seq = 0;
+
+  const all = () => {
+    const out = [];
+    for (const rows of sessions.values()) out.push(...rows);
+    return out;
+  };
+
+  function usage() {
+    const t = now();
+    const day = all().filter((m) => t - m.at_ms <= DAY_MS);
+    const week = all().filter((m) => t - m.at_ms <= retentionDays * DAY_MS);
+    const sum = (rows) => rows.reduce((total, m) => total + m.bytes, 0);
+    return { used_24h_bytes: sum(day), used_retention_bytes: sum(week), messages: all().length };
+  }
+
+  function limitBytes() {
+    const { used_retention_bytes: week } = usage();
+    return Math.min(hardCapBytes, Math.max(quota24hBytes, week));
+  }
+
+  /**
+   * @param {{session_id: string, fleet_id?: string|null, machine_id: string, text: string}} input
+   * @returns {{ok: true, message: object} | {ok: false, code: string, detail?: object}}
+   */
+  function post(input) {
+    const sessionId = typeof input?.session_id === 'string' ? input.session_id.trim() : '';
+    if (sessionId === '') return { ok: false, code: 'BAD_SESSION' };
+    const machineId = typeof input?.machine_id === 'string' ? input.machine_id.trim() : '';
+    if (machineId === '') return { ok: false, code: 'BAD_MACHINE' };
+    if (typeof input?.text !== 'string') return { ok: false, code: 'NOT_TEXT' };
+    const text = input.text;
+    if (text.trim() === '') return { ok: false, code: 'EMPTY_TEXT' };
+    // Reject control characters (except tab/newline): "plain text" is a contract, not a preference.
+    // Control characters are the thing being rejected here, so the rule that forbids them in a pattern
+    // does not apply -- the escape IS the contract.
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(text)) return { ok: false, code: 'NOT_TEXT' };
+    const bytes = Buffer.byteLength(text, 'utf8');
+    if (bytes > maxMessageBytes) return { ok: false, code: 'MESSAGE_TOO_LARGE', detail: { bytes, maxBytes: maxMessageBytes } };
+
+    const before = usage();
+    const limit = limitBytes();
+    if (before.used_24h_bytes + bytes > limit) {
+      return { ok: false, code: 'FLEET_QUOTA_EXCEEDED', detail: { used_24h_bytes: before.used_24h_bytes, limit_bytes: limit, bytes } };
+    }
+
+    seq += 1;
+    const message = {
+      message_id: 'msg-' + String(seq).padStart(6, '0'),
+      session_id: sessionId,
+      fleet_id: typeof input?.fleet_id === 'string' ? input.fleet_id : null,
+      machine_id: machineId,
+      text,
+      at_ms: now(),
+      bytes,
+    };
+    if (!sessions.has(sessionId)) sessions.set(sessionId, []);
+    sessions.get(sessionId).push(message);
+    for (const listener of listeners) {
+      if (listener.sessionId !== null && listener.sessionId !== sessionId) continue;
+      try { listener.fn({ session_id: sessionId, message_id: message.message_id, machine_id: message.machine_id, at_ms: message.at_ms }); }
+      catch { /* a dead listener must not fail the write */ }
+    }
+    return { ok: true, message };
+  }
+
+  /** Read one session's flow. \`since_ms\` is exclusive; the order is the order it was said. */
+  function list({ session_id: sessionId, since_ms: sinceMs = null, limit = 50 } = {}) {
+    const rows = sessions.get(sessionId) ?? [];
+    const filtered = Number.isFinite(sinceMs) ? rows.filter((m) => m.at_ms > sinceMs) : rows;
+    const capped = filtered.slice(-Math.max(1, Math.min(limit, 200)));
+    return { ok: true, messages: capped.map((m) => ({ ...m })), count: capped.length };
+  }
+
+  /** Deleting a session deletes its history -- the operator's rule, not a side effect. */
+  function deleteSession(sessionId) {
+    return sessions.delete(sessionId);
+  }
+
+  /** @param {string|null} sessionId null subscribes to every session; returns the unsubscribe function. */
+  function subscribe(sessionId, fn) {
+    const listener = { sessionId: typeof sessionId === 'string' && sessionId !== '' ? sessionId : null, fn };
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  return { post, list, usage, limitBytes, deleteSession, subscribe, _sessions: sessions };
+}

package/src/relay/message-shards.mjs

@@ -0,0 +1,124 @@
+/**
+ * Chat history, encrypted and split across the fleet's own machines.
+ *
+ * ## The three rules that keep "distributed storage" from becoming "lost data"
+ *
+ * 1. **Rebuildable.** Any single message must be recoverable from the shards that exist, and the metadata says where they
+ *    are: \`{machine_id, part, total, sha256}\` per shard. A reader never has to guess who holds what.
+ * 2. **Offline tolerated.** Each part is assigned to **two distinct** machines. One machine being down is the normal
+ *    case, not the failure case, and a single copy would make it a data-loss case.
+ * 3. **Integrity.** Every shard carries sha256 of its own bytes. A shard that does not match is corrupt and is named;
+ *    it is never silently decrypted into garbage. Missing shards are named too -- "some data is gone" without saying
+ *    which part is gone is not a report, it is a shrug.
+ *
+ * ## Encryption
+ *
+ * AES-256-GCM with a key derived from the fleet key (the same secret that already authorises joining, so no new
+ * long-lived secret appears). The IV is generated per day-batch and travels in the header; the auth tag is verified before
+ * any plaintext is returned, so a wrong key or a tampered ciphertext fails loudly.
+ *
+ * ## What this file does NOT do
+ *
+ * It does not decide where the machines are or how bytes reach them. It produces the shards and reassembles them; the
+ * relay owns transport. Keeping the split here is what makes it testable without a fleet.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+
+/** Default slice size for one shard: small enough to distribute, large enough not to explode the shard count. */
+export const DEFAULT_SHARD_BYTES = 256 * 1024;
+/** Two copies, per rule 2. */
+export const DEFAULT_REPLICAS = 2;
+
+const sha256 = (buffer) => createHash('sha256').update(buffer).digest('hex');
+const dayKey = (atMs) => new Date(atMs).toISOString().slice(0, 10);
+
+/** Derive the encryption key from the fleet key. Same secret, different purpose, separated label. */
+export function deriveShardKey(fleetKey) {
+  if (typeof fleetKey !== 'string' || fleetKey === '') throw new TypeError('fleetKey must be a non-empty string');
+  return createHash('sha256').update('w2m-chat-shards-v1').update('\u0000').update(fleetKey).digest();
+}
+
+/**
+ * Split one day's messages into encrypted shards and assign each part to replica machines.
+ *
+ * @param {{messages: object[], fleetKey: string, machines: string[], shardBytes?: number, replicas?: number,
+ *          at_ms?: number}} input
+ * @returns {{ok: true, day: string, shards: object[], header: object} | {ok: false, code: string}}
+ */
+export function buildShards({ messages, fleetKey, machines, shardBytes = DEFAULT_SHARD_BYTES, replicas = DEFAULT_REPLICAS, at_ms }) {
+  if (!Array.isArray(messages) || messages.length === 0) return { ok: false, code: 'NOTHING_TO_SHARD' };
+  if (!Array.isArray(machines) || machines.length === 0) return { ok: false, code: 'NO_MACHINES' };
+  if (replicas > machines.length) return { ok: false, code: 'NOT_ENOUGH_MACHINES', detail: { machines: machines.length, replicas } };
+  const key = deriveShardKey(fleetKey);
+  const at = Number.isFinite(at_ms) ? at_ms : messages[0].at_ms ?? Date.now();
+  const day = dayKey(at);
+  const plaintext = Buffer.from(JSON.stringify(messages), 'utf8');
+
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  const sealed = Buffer.concat([ciphertext, tag]);
+
+  const total = Math.max(1, Math.ceil(sealed.length / shardBytes));
+  const shards = [];
+  for (let part = 0; part < total; part += 1) {
+    const body = sealed.subarray(part * shardBytes, (part + 1) * shardBytes);
+    const digest = sha256(body);
+    // Rule 2: distinct machines per part, rotating so the copies are not all on the same pair.
+    const holders = [];
+    for (let r = 0; r < replicas; r += 1) holders.push(machines[(part + r) % machines.length]);
+    for (const machineId of holders) {
+      shards.push({
+        day, part, total, machine_id: machineId, sha256: digest,
+        bytes: body.length, body: body.toString('base64'),
+      });
+    }
+  }
+  return { ok: true, day, shards, header: { iv: iv.toString('base64'), algorithm: 'aes-256-gcm', total, day } };
+}
+
+/**
+ * Reassemble the day's messages from whatever shards are available.
+ *
+ * Every failure is named: a missing part, a corrupt part, and a failed authentication are three different operational
+ * facts and a caller that cannot tell them apart cannot decide whether to retry another replica.
+ *
+ * @param {{shards: object[], header: object, fleetKey: string}} input
+ * @returns {{ok: true, messages: object[]} | {ok: false, code: string, detail?: object}}
+ */
+export function assembleShards({ shards, header, fleetKey }) {
+  if (!Array.isArray(shards) || shards.length === 0) return { ok: false, code: 'NO_SHARDS' };
+  if (header === null || typeof header !== 'object') return { ok: false, code: 'NO_HEADER' };
+  const total = header.total;
+  const byPart = new Map();
+  for (const shard of shards) {
+    if (sha256(Buffer.from(shard.body, 'base64')) !== shard.sha256) {
+      return { ok: false, code: 'SHARD_CORRUPT', detail: { part: shard.part, machine_id: shard.machine_id } };
+    }
+    if (!byPart.has(shard.part)) byPart.set(shard.part, shard);
+  }
+  const missing = [];
+  for (let part = 0; part < total; part += 1) if (!byPart.has(part)) missing.push(part);
+  if (missing.length > 0) return { ok: false, code: 'MISSING_SHARDS', detail: { missing } };
+
+  const ordered = [];
+  for (let part = 0; part < total; part += 1) ordered.push(Buffer.from(byPart.get(part).body, 'base64'));
+  const sealed = Buffer.concat(ordered);
+  const tag = sealed.subarray(sealed.length - 16);
+  const ciphertext = sealed.subarray(0, sealed.length - 16);
+  try {
+    const decipher = createDecipheriv('aes-256-gcm', deriveShardKey(fleetKey), Buffer.from(header.iv, 'base64'));
+    decipher.setAuthTag(tag);
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return { ok: true, messages: JSON.parse(plaintext.toString('utf8')) };
+  } catch {
+    // Wrong key or tampered ciphertext: never return partial plaintext.
+    return { ok: false, code: 'AUTH_FAILED' };
+  }
+}
+
+/** Which shards does a reader hold for one machine? Transport uses this; it does not read the bodies. */
+export function shardsForMachine(shards, machineId) {
+  return shards.filter((shard) => shard.machine_id === machineId).map(({ body, ...meta }) => meta);
+}

package/src/relay/server.mjs

@@ -21,7 +21,8 @@ import {
   ProtocolError,
   RabbitState,
   rfc3339,
-} from './state.mjs';
+} from './state.mjs';
+import { createFleetMessages } from './fleet-messages.mjs';
 import { createJoinChallenges } from './join-challenge.mjs';
 import { createAdmission } from './admission.mjs';
 import { Persistence } from './persistence.mjs';
@@ -1037,6 +1038,75 @@ export class RelayServer {
       return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...result });
     }
 
+    /* ---- v1.1.17: fleet chat ---- */
+    //
+    // Both endpoints sit AFTER the device gate on purpose: a message must be attributable to a paired machine, and
+    // "who said this" is exactly the machine_id the token resolves to -- never a body field, which would let one machine
+    // speak as another. The refusal codes from the store are passed through unchanged (FLEET_QUOTA_EXCEEDED included)
+    // because a caller that cannot tell "too big" from "over quota" from "not text" cannot tell the operator what to do.
+    this.fleetMessages ??= createFleetMessages({ now: () => this.state.nowMs() });
+
+    if (method === 'POST' && path === '/v1/fleet/messages') {
+      const body = takeJson();
+      const posted = this.fleetMessages.post({
+        session_id: body.session_id,
+        fleet_id: typeof body.fleet_id === 'string' ? body.fleet_id : null,
+        machine_id: device.machine_id,
+        text: body.text,
+      });
+      if (posted.ok !== true) {
+        throw new ProtocolError('BAD_REQUEST', 'message refused: ' + posted.code, { code: posted.code, ...(posted.detail ?? {}) });
+      }
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), message: posted.message });
+    }
+
+    if (method === 'GET' && path === '/v1/fleet/messages/stream') {
+      /**
+       * v1.1.17: a notification channel, not a message channel.
+       *
+       * The event carries the id and the session -- never the text -- so a client that connects learns "something was
+       * said" and then fetches it through GET /v1/fleet/messages, which is where membership is actually checked. A
+       * broadcast carrying text would hand every message to every connected listener and make the check decorative.
+       *
+       * The stream sits behind the device gate: an unpaired client cannot listen.
+       */
+      const sessionId = url.searchParams.get('session_id');
+      res.writeHead(200, {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-store',
+        connection: 'keep-alive',
+        'x-accel-buffering': 'no',
+      });
+      res.write(': connected\n\n');
+      if (typeof res.flushHeaders === 'function') res.flushHeaders();
+      const keepalive = setInterval(() => { try { res.write(': keepalive\n\n'); } catch { /* closed */ } }, 15_000);
+      if (typeof keepalive.unref === 'function') keepalive.unref();
+      const unsubscribe = this.fleetMessages.subscribe(sessionId, (event) => {
+        try {
+          res.write('event: new_message\ndata: ' + JSON.stringify(event) + '\n\n');
+        } catch { /* the reader went away; close() below cleans up */ }
+      });
+      const done = () => { clearInterval(keepalive); unsubscribe(); try { res.end(); } catch { /* already closed */ } };
+      req.on('close', done);
+      return undefined;
+    }
+
+    if (method === 'GET' && path === '/v1/fleet/messages') {
+      const sinceRaw = url.searchParams.get('since_ms');
+      const limitRaw = url.searchParams.get('limit');
+      const listed = this.fleetMessages.list({
+        session_id: url.searchParams.get('session_id') ?? '',
+        since_ms: sinceRaw === null ? null : Number(sinceRaw),
+        limit: limitRaw === null ? 50 : Number(limitRaw),
+      });
+      return sendJson(res, 200, {
+        protocol_version: PROTOCOL_VERSION,
+        rabbit_time: this.state.nowIso(),
+        ...listed,
+        usage: this.fleetMessages.usage(),   // shown with every read so a client can warn before the quota refuses a post
+      });
+    }
+
     throw new ProtocolError('NOT_FOUND', `no route for ${method} ${path}`, { method, path });
   }