agent-comm-hub 0.6.0 → 0.7.1

package/lib/index.js

@@ -1,7 +1,8 @@
 // src/index.ts
 import { createServer } from "node:http";
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { randomBytes as randomBytes2 } from "node:crypto";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2 } from "node:path";
 
 // src/herdr-ctl.ts
 import { execFile } from "node:child_process";
@@ -452,6 +453,8 @@ var AgentHub = class {
   lastSeen = /* @__PURE__ */ new Map();
   /** Identity metadata keyed by peer id; outlives registration (see {@link PeerProfile}). */
   profiles = /* @__PURE__ */ new Map();
+  /** Named channels (group channel), keyed by group id. */
+  groups = /* @__PURE__ */ new Map();
   gcTimer;
   /** Stop the idle GC (call when the hub shuts down). */
   dispose() {
@@ -491,6 +494,7 @@ var AgentHub = class {
   /** Remove a peer and its queued messages; pending waiters resolve as
    * timeouts. The profile is kept so a reconnecting peer keeps its alias. */
   unregister(peerId) {
+    if ((this.queues.get(peerId) ?? []).length > 0) this.options.onMailboxesChanged?.();
     this.queues.delete(peerId);
     for (const waiter of this.waiters.get(peerId) ?? []) {
       clearTimeout(waiter.timer);
@@ -631,9 +635,20 @@ var AgentHub = class {
     if (!original) throw new Error(`cannot ack unknown message: ${ref}`);
     return this.route(from, original.from, "ack", JSON.stringify(ack), ref);
   }
-  /** Recent messages involving `peer` (inbound and outbound), newest first. */
+  /** Recent messages involving `peer` (inbound and outbound, plus group
+   * channels the peer belongs to), newest first. */
   history(peerId, limit) {
-    const filtered = this.historyRing.filter((message) => message.from === peerId || message.to === peerId || message.to === BROADCAST);
+    const memberOf = new Set(
+      [...this.groups.values()].filter((group) => group.members.includes(peerId)).map((group) => group.id)
+    );
+    const filtered = this.historyRing.filter(
+      (message) => message.from === peerId || message.to === peerId || message.to === BROADCAST || message.channel !== void 0 && memberOf.has(message.channel)
+    );
+    return filtered.slice(-Math.max(0, limit)).reverse();
+  }
+  /** Recent messages of one group channel, newest first. */
+  historyChannel(groupId, limit) {
+    const filtered = this.historyRing.filter((message) => message.channel === groupId || message.to === groupId && message.channel === void 0 && this.groups.has(groupId));
     return filtered.slice(-Math.max(0, limit)).reverse();
   }
   /** Most recent messages across every peer, unfiltered (newest first).
@@ -642,10 +657,175 @@ var AgentHub = class {
   historyAll(limit) {
     return this.historyRing.slice(-Math.max(0, limit)).reverse();
   }
+  // ---- groups (group channel) ------------------------------------------------
+  /** Create a channel; throws when the id is taken or a member is unknown. */
+  createGroup(id, members, createdBy, name) {
+    if (this.groups.has(id)) throw new Error(`group already exists: ${id}`);
+    if (!PEER_ID_PATTERN.test(id)) throw new Error(`invalid group id: ${id} (expected [A-Za-z0-9._:-]{1,64})`);
+    const unique = [...new Set(members)];
+    if (unique.length === 0) throw new Error("a group needs at least one member");
+    for (const member of unique) {
+      if (!this.lastSeen.has(member)) throw new Error(`unknown member peer: ${member}`);
+    }
+    if (!unique.includes(createdBy)) unique.unshift(createdBy);
+    const group = { id, members: unique, createdBy, createdAt: Date.now(), ...name !== void 0 && name !== "" ? { name } : {} };
+    this.groups.set(id, group);
+    this.options.onGroupsChanged?.();
+    return group;
+  }
+  /** Remove a channel (its history rows stay — attribution is unchanged). */
+  deleteGroup(id) {
+    if (!this.groups.delete(id)) return false;
+    this.options.onGroupsChanged?.();
+    return true;
+  }
+  groupOf(id) {
+    return this.groups.get(id);
+  }
+  /** Add a registered peer to an existing channel, so they can send and read
+   * it like any other member. Throws when the group is unknown, the peer is
+   * not registered, or it is already inside. */
+  addGroupMember(groupId, member) {
+    const group = this.groups.get(groupId);
+    if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+    if (group.members.includes(member)) throw new Error(`peer '${member}' is already a member of group '${groupId}'`);
+    if (!this.lastSeen.has(member)) throw new Error(`unknown member peer: ${member}`);
+    group.members.push(member);
+    this.options.onGroupsChanged?.();
+    return group;
+  }
+  /** Remove a member from a channel. The creator cannot be removed (it would
+   * orphan the channel's management). Throws when the group or the membership
+   * is missing. */
+  removeGroupMember(groupId, member) {
+    const group = this.groups.get(groupId);
+    if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+    if (member === group.createdBy) throw new Error(`cannot remove the group creator '${member}'`);
+    const index = group.members.indexOf(member);
+    if (index === -1) throw new Error(`peer '${member}' is not a member of group '${groupId}'`);
+    group.members.splice(index, 1);
+    this.options.onGroupsChanged?.();
+    return group;
+  }
+  /** All groups (snapshot copy), insertion order. */
+  allGroups() {
+    return [...this.groups.values()].map((group) => ({ ...group, members: [...group.members] }));
+  }
+  /** Send a chat message to every member of a group except the sender;
+   * members that went offline are skipped (they read the group history).
+   * The message carries `to` and `channel` = the group id. */
+  sendToGroup(from, groupId, content) {
+    const group = this.groups.get(groupId);
+    if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+    if (!group.members.includes(from)) throw new Error(`peer '${from}' is not a member of group '${groupId}'`);
+    const message = {
+      id: randomUUID(),
+      from,
+      to: groupId,
+      kind: "chat",
+      content,
+      channel: groupId,
+      ts: Date.now()
+    };
+    this.lastSeen.set(from, message.ts);
+    for (const member of group.members) {
+      if (member !== from && this.lastSeen.has(member)) this.deliver(member, message);
+    }
+    return message;
+  }
+  /** Snapshot of every group for persistence. */
+  exportGroups() {
+    return this.allGroups();
+  }
+  /** Load persisted groups at boot (same validation as createGroup, minus
+   * the "members must be online" rule — members reconnect later). */
+  importGroups(groups) {
+    if (!Array.isArray(groups)) return 0;
+    let count = 0;
+    for (const raw of groups) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const candidate = raw;
+      if (typeof candidate.id !== "string" || !PEER_ID_PATTERN.test(candidate.id) || this.groups.has(candidate.id)) continue;
+      if (!Array.isArray(candidate.members) || candidate.members.length === 0) continue;
+      const members = [...new Set(candidate.members.filter((m) => typeof m === "string" && PEER_ID_PATTERN.test(m)))];
+      if (members.length === 0) continue;
+      this.groups.set(candidate.id, {
+        id: candidate.id,
+        members,
+        createdBy: typeof candidate.createdBy === "string" && PEER_ID_PATTERN.test(candidate.createdBy) ? candidate.createdBy : members[0],
+        createdAt: typeof candidate.createdAt === "number" && Number.isFinite(candidate.createdAt) ? candidate.createdAt : Date.now(),
+        ...typeof candidate.name === "string" && candidate.name !== "" ? { name: candidate.name } : {}
+      });
+      count++;
+    }
+    return count;
+  }
+  // ---- persistence import/export (remote-mode SQLite store) -----------
+  /** Restore the history ring at boot. Shape-invalid rows are dropped; only
+   * the newest {@link HubOptions.historyLimit} survive. */
+  importHistory(messages) {
+    if (!Array.isArray(messages)) return 0;
+    const valid = [];
+    for (const raw of messages) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const m = raw;
+      if (typeof m.id !== "string" || typeof m.from !== "string" || typeof m.to !== "string" || typeof m.content !== "string" || typeof m.ts !== "number") continue;
+      if (KINDS.includes(m.kind) === false) continue;
+      valid.push({
+        id: m.id,
+        from: m.from,
+        to: m.to,
+        kind: m.kind,
+        content: m.content,
+        ...typeof m.ref === "string" ? { ref: m.ref } : {},
+        ...typeof m.channel === "string" ? { channel: m.channel } : {},
+        ts: m.ts
+      });
+    }
+    for (const message of valid.slice(-this.options.historyLimit)) this.historyRing.push(message);
+    return Math.min(valid.length, this.options.historyLimit);
+  }
+  /** Snapshot of every offline mailbox, keyed by peer (persistence). */
+  exportMailboxes() {
+    const out = {};
+    for (const [peer, queue] of this.queues) {
+      if (queue.length > 0) out[peer] = queue.map((message) => ({ ...message }));
+    }
+    return out;
+  }
+  /** Restore offline mailboxes at boot (peer reconnects and drains later). */
+  importMailboxes(mailboxes) {
+    if (typeof mailboxes !== "object" || mailboxes === null) return 0;
+    let count = 0;
+    for (const [peer, queue] of Object.entries(mailboxes)) {
+      if (!Array.isArray(queue) || queue.length === 0) continue;
+      const restored = [];
+      for (const raw of queue) {
+        if (typeof raw !== "object" || raw === null) continue;
+        const m = raw;
+        if (typeof m.id !== "string" || typeof m.from !== "string" || typeof m.content !== "string" || typeof m.ts !== "number") continue;
+        restored.push({
+          id: m.id,
+          from: m.from,
+          to: typeof m.to === "string" ? m.to : peer,
+          kind: KINDS.includes(m.kind) ? m.kind : "chat",
+          content: m.content,
+          ...typeof m.ref === "string" ? { ref: m.ref } : {},
+          ...typeof m.channel === "string" ? { channel: m.channel } : {},
+          ts: m.ts
+        });
+      }
+      if (restored.length > 0) {
+        this.queues.set(peer, restored.slice(-this.options.maxQueue));
+        count += restored.length;
+      }
+    }
+    return count;
+  }
   /**
-   * Live summary for the status tool. `livePeers` (sessions with a live SSE
-   * stream) count as connected even without recent tool activity.
-   */
+  * Live summary for the status tool. `livePeers` (sessions with a live SSE
+  * stream) count as connected even without recent tool activity.
+  */
   status(livePeers) {
     const now = Date.now();
     return {
@@ -669,7 +849,7 @@ var AgentHub = class {
   poll(peerId, from) {
     const queue = this.queues.get(peerId) ?? [];
     const drained = from === void 0 ? queue.splice(0, queue.length) : drainFrom(queue, from);
-    for (const message of drained) this.remember(message);
+    if (drained.length > 0) this.options.onMailboxesChanged?.();
     return drained;
   }
   /**
@@ -752,12 +932,15 @@ var AgentHub = class {
     if (queue.length >= this.options.maxQueue) queue.shift();
     queue.push(message);
     this.queues.set(target, queue);
+    this.remember(message);
     this.options.onQueued?.(message, target);
   }
-  /** Append a delivered message to the history ring. */
+  /** Append a delivered message to the history ring (and fire the
+   * persistence hook — one call per message, delivered or queued). */
   remember(message) {
     this.historyRing.push(message);
     if (this.historyRing.length > this.options.historyLimit) this.historyRing.splice(0, this.historyRing.length - this.options.historyLimit);
+    this.options.onMessage?.(message);
   }
 };
 function drainFrom(queue, from) {
@@ -775,13 +958,159 @@ function omit(value, key) {
   return rest;
 }
 
+// src/auth.ts
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+var ANON_JOIN_PEER = "__join__";
+var TOKEN_PATTERN = /^[A-Za-z0-9._:-]{16,128}$/;
+function loadTokenFile(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`auth token file unreadable: ${file} (${error.message})`);
+  }
+  const rows = parsed?.tokens;
+  if (!Array.isArray(rows)) throw new Error(`auth token file ${file}: expected {"tokens":[...]}`);
+  const table = /* @__PURE__ */ new Map();
+  const peers = /* @__PURE__ */ new Set();
+  rows.forEach((row, index) => {
+    const msg = (why) => `auth token file ${file}: entry #${index + 1} ${why}`;
+    if (typeof row !== "object" || row === null) throw new Error(msg("is not an object"));
+    const { token, peer, role, owner } = row;
+    if (typeof token !== "string" || !TOKEN_PATTERN.test(token)) {
+      throw new Error(msg("has an invalid token (expect 16-128 chars of [A-Za-z0-9._:-])"));
+    }
+    if (typeof peer !== "string" || !PEER_ID_PATTERN.test(peer) || peer === "all") {
+      throw new Error(msg(`has an invalid peer id '${String(peer)}'`));
+    }
+    if (role !== "agent" && role !== "manager") {
+      throw new Error(msg(`has an invalid role '${String(role)}' (expected 'agent' | 'manager')`));
+    }
+    if (owner !== void 0 && typeof owner !== "string") throw new Error(msg("has a non-string owner"));
+    if (table.has(token)) throw new Error(msg("duplicates a token"));
+    if (peers.has(peer)) {
+      throw new Error(msg(`maps a second token to peer '${peer}' (two tokens sharing a peer share its mailbox)`));
+    }
+    table.set(token, { peer, role, ...typeof owner === "string" && owner !== "" ? { owner } : {} });
+    peers.add(peer);
+  });
+  if (table.size === 0) throw new Error(`auth token file ${file}: no tokens defined`);
+  return table;
+}
+function tokenTable(map) {
+  return {
+    authenticate: (token) => token === void 0 ? void 0 : map.get(token)
+  };
+}
+function watchTokenFile(file, log) {
+  let table = loadTokenFile(file);
+  const reload = () => {
+    try {
+      const next = loadTokenFile(file);
+      table = next;
+      log.info(`auth tokens reloaded: ${table.size} entr(ies)`);
+    } catch (error) {
+      log.warn(`auth token reload ignored, keeping previous table: ${error.message}`);
+    }
+  };
+  log.info(`auth tokens loaded: ${table.size} entr(ies) from ${file}`);
+  let mtime = statMtime(file);
+  const timer = setInterval(() => {
+    const current = statMtime(file);
+    if (current === mtime) return;
+    mtime = current;
+    reload();
+  }, 2e3);
+  timer.unref?.();
+  return { authenticate: (token) => token === void 0 ? void 0 : table.get(token), reload };
+}
+function statMtime(file) {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+function bearerFromHeaders(headers) {
+  const raw = Array.isArray(headers.authorization) ? headers.authorization[0] : headers.authorization;
+  if (raw === void 0) return void 0;
+  const match = /^Bearer\s+(.+)$/.exec(raw.trim());
+  return match === null ? void 0 : match[1];
+}
+function generateToken() {
+  return randomBytes(24).toString("base64url");
+}
+function readTokens(file) {
+  if (!existsSync(file)) return [];
+  try {
+    return [...loadTokenFile(file).entries()].map(([token, id]) => ({
+      token,
+      peer: id.peer,
+      role: id.role,
+      ...id.owner !== void 0 ? { owner: id.owner } : {}
+    }));
+  } catch (error) {
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8"));
+      if (Array.isArray(parsed.tokens) && parsed.tokens.length === 0) return [];
+    } catch {
+    }
+    throw error;
+  }
+}
+function writeTokenFile(file, rows) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ tokens: rows }, null, 2) + "\n", "utf8");
+  renameSync(tmp, file);
+}
+function addToken(file, row) {
+  const token = row.token ?? generateToken();
+  if (!TOKEN_PATTERN.test(token)) {
+    throw new Error(`invalid token provided (expect 16-128 chars of [A-Za-z0-9._:-])`);
+  }
+  const peers = new Set(readTokens(file).map((t) => t.peer));
+  if (peers.has(row.peer)) {
+    throw new Error(`peer '${row.peer}' already has a token \u2014 remove it first to rotate (see \`auth remove\`)`);
+  }
+  const owner = row.owner !== void 0 && row.owner !== "" ? row.owner : void 0;
+  const identity = { token, peer: row.peer, role: row.role, ...owner !== void 0 ? { owner } : {} };
+  const next = [...readTokens(file), identity];
+  loadTokenFileVoid(next);
+  writeTokenFile(file, next);
+  return identity;
+}
+function removeToken(file, peer) {
+  const tokens = readTokens(file);
+  const kept = tokens.filter((t) => t.peer !== peer);
+  if (kept.length === tokens.length) return false;
+  writeTokenFile(file, kept);
+  return true;
+}
+function loadTokenFileVoid(rows) {
+  const table = /* @__PURE__ */ new Map();
+  const peers = /* @__PURE__ */ new Set();
+  for (const { token, peer, role, owner } of rows) {
+    if (!TOKEN_PATTERN.test(token)) throw new Error(`invalid token for peer '${peer}'`);
+    if (!PEER_ID_PATTERN.test(peer) || peer === "all") throw new Error(`invalid peer id '${peer}'`);
+    if (role !== "agent" && role !== "manager") throw new Error(`invalid role '${role}'`);
+    if (table.has(token)) throw new Error("duplicate token");
+    if (peers.has(peer)) throw new Error(`duplicate peer '${peer}'`);
+    table.set(token, { peer, role, ...owner !== void 0 && owner !== "" ? { owner } : {} });
+    peers.add(peer);
+  }
+}
+
 // src/hub-tools.ts
 var DEFAULT_WAIT_MS = 3e4;
 function present(message) {
-  const { ref, ...rest } = message;
+  const { ref, channel, ...rest } = message;
   return {
     ...rest,
     ...ref !== void 0 ? { ref } : {},
+    ...channel !== void 0 ? { channel } : {},
     content: decodeContent(message.kind, message.content)
   };
 }
@@ -801,7 +1130,8 @@ function autoRegisterPeer(hub, registry, sessionId, clientName, clientVersion) {
   const bound = registry.peerFor(sessionId);
   if (bound !== void 0) return bound;
   if (registry.isSuppressed(sessionId)) return void 0;
-  const peerId = sanitizePeerId(clientName ?? "agent");
+  const tokenPeer = registry.tokenFor(sessionId)?.peer;
+  const peerId = tokenPeer === ANON_JOIN_PEER ? `join-${sanitizePeerId(clientName ?? "agent")}-${Math.random().toString(36).slice(2, 6)}` : tokenPeer ?? sanitizePeerId(clientName ?? "agent");
   if (!hub.has(peerId)) {
     hub.register(peerId, {
       ...clientName !== void 0 ? { name: clientName } : {},
@@ -822,16 +1152,31 @@ function livePeersFor(registry) {
 }
 function rosterFor(hub, registry) {
   const status = hub.status(livePeersFor(registry));
+  const peerIps = /* @__PURE__ */ new Map();
+  const peerAnon = /* @__PURE__ */ new Map();
+  for (const [session, peer] of registry.peerBindings) {
+    const ip = registry.sessionIps.get(session);
+    if (ip !== void 0) {
+      const list = peerIps.get(peer) ?? [];
+      if (!list.includes(ip)) list.push(ip);
+      peerIps.set(peer, list);
+    }
+    const identity = registry.tokenFor(session);
+    if (identity?.anonymous === true) peerAnon.set(peer, true);
+  }
   return status.peers.map((peer) => {
     const profile = hub.profileOf(peer.id);
     const alias = profile?.alias;
     const clientName = profile?.clientName;
     const clientVersion = profile?.clientVersion;
+    const ips = peerIps.get(peer.id);
     return {
       id: peer.id,
       ...alias !== void 0 ? { alias } : {},
       ...clientName !== void 0 ? { clientName } : {},
       ...clientVersion !== void 0 ? { clientVersion } : {},
+      ...peerAnon.get(peer.id) === true ? { anonymous: true } : {},
+      ...ips !== void 0 && ips.length > 0 ? { clientIps: ips } : {},
       connected: peer.connected,
       lastSeenMs: peer.lastSeenMs
     };
@@ -866,6 +1211,7 @@ function hubTools(hub, registry, options) {
     from: message.from,
     to: message.to,
     kind: message.kind,
+    ...message.channel !== void 0 ? { channel: message.channel } : {},
     ts: message.ts
   });
   const presentWait = (result) => result.type === "timeout" ? result : { type: "message", message: present(result.message) };
@@ -880,7 +1226,8 @@ function hubTools(hub, registry, options) {
     }
     return herdr;
   };
-  const requireManager = (peer, action) => {
+  const requireManager = (peer, action, sessionId) => {
+    if (registry.tokenFor(sessionId)?.role === "manager") return;
     const managers = options.managerPeers ?? "all";
     if (managers !== "all" && !managers.has(peer)) {
       throw new Error(`peer '${peer}' is not a hub manager \u2014 ${action} requires manager rights`);
@@ -912,6 +1259,10 @@ function hubTools(hub, registry, options) {
           throw new Error(`reserved peer id: ${peerId} (it is the broadcast address)`);
         }
         const alias = args.alias === void 0 ? void 0 : sanitizeAlias(String(args.alias));
+        const tokenPeer = registry.tokenFor(sessionId)?.peer;
+        if (tokenPeer !== void 0 && peerId !== tokenPeer) {
+          throw new Error(`your identity is bound to your access token ('${tokenPeer}') \u2014 ask a hub manager to rename you`);
+        }
         if (hub.has(peerId) && registry.peerFor(sessionId) !== peerId) {
           throw new Error(`peer already registered by another connection: ${peerId}`);
         }
@@ -953,7 +1304,7 @@ function hubTools(hub, registry, options) {
         const caller = registry.peerFor(sessionId);
         if (caller === void 0) throw new Error("not registered \u2014 call bridge_register(peerId) first");
         const target = String(args.peer);
-        requireManager(caller, `kicking '${target}'`);
+        requireManager(caller, `kicking '${target}'`, sessionId);
         if (!hub.has(target)) {
           return { ok: true, peerId: null, kicked: false };
         }
@@ -970,14 +1321,14 @@ function hubTools(hub, registry, options) {
         peerId: optStr("New routing id for `peer` \u2014 a true rename that moves all state (manager only). Target must be a registered peer."),
         peer: optStr("Whose name/id to change; default yourself. Changing another peer requires manager rights.")
       }),
-      handler: wrap(true, async (args, peer) => {
+      handler: wrap(true, async (args, peer, sessionId) => {
         const hasAlias = args.alias !== void 0;
         const hasPeerId = args.peerId !== void 0;
         if (!hasAlias && !hasPeerId) {
           throw new Error("nothing to rename: pass alias and/or peerId");
         }
         let target = args.peer === void 0 ? peer : String(args.peer);
-        if (target !== peer) requireManager(peer, `renaming '${target}'`);
+        if (target !== peer) requireManager(peer, `renaming '${target}'`, sessionId);
         let previousId;
         if (hasPeerId) {
           if (args.peer === void 0) {
@@ -1078,16 +1429,98 @@ function hubTools(hub, registry, options) {
       name: "bridge_history",
       description: 'Recent messages involving you (newest first). Use to refresh context after a reconnect. Reading ANOTHER peer\'s conversation \u2014 or `peer: "all"` for the unfiltered tail \u2014 requires manager rights (hub managerPeers).',
       inputSchema: schema({ peer: optStr('PeerId whose conversation to inspect; "all" = every peer; default: yourself. Other peers / "all" require manager rights.'), limit: int("How many messages to return (default 20).") }),
-      handler: wrap(true, async (args, peer) => {
+      handler: wrap(true, async (args, peer, sessionId) => {
         const limit = Math.min(args.limit === void 0 ? 20 : Number(args.limit), 1e3);
         const target = args.peer === void 0 ? peer : String(args.peer);
         if (target !== peer) {
-          requireManager(peer, `reading ${target === BROADCAST ? "the full history" : `peer '${target}' history`} requires manager rights`);
+          requireManager(peer, `reading ${target === BROADCAST ? "the full history" : `peer '${target}' history`}`, sessionId);
+        }
+        if (args.channel !== void 0) {
+          const groupId = String(args.channel);
+          const group = hub.groupOf(groupId);
+          if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+          if (!group.members.includes(peer)) requireManager(peer, `reading group '${groupId}' history`, sessionId);
+          return { messages: hub.historyChannel(groupId, limit).map(present) };
         }
         const messages = target === BROADCAST ? hub.historyAll(limit) : hub.history(target, limit);
         return { messages: messages.map(present) };
       })
     },
+    // ---- group tools (group channel) ---------------------------------------------
+    // A group routes one message to several members; the message carries
+    // channel = group id. Offline members are skipped (they read history) —
+    // unlike direct sends, which fail on unknown recipients.
+    {
+      name: "bridge_group_create",
+      description: "Create a group channel. You become a member automatically; `members` lists additional peerIds (each must be registered). Members exchange messages via bridge_group_send; anyone in the group reads its history with bridge_history { channel }. Use bridge_group_delete to remove (creator or manager).",
+      inputSchema: schema(
+        {
+          group: str("Unique group id: letters/digits/._:- , 1-64 chars."),
+          name: optStr("Optional display name."),
+          members: { type: "array", items: { type: "string" }, description: "Member peerIds (you are added automatically; duplicates ignored)." }
+        },
+        ["group"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const groupId = String(args.group);
+        const members = Array.isArray(args.members) ? args.members.map(String) : [];
+        const group = hub.createGroup(groupId, members, peer, args.name === void 0 ? void 0 : String(args.name));
+        return { ok: true, group: { id: group.id, ...group.name !== void 0 ? { name: group.name } : {}, members: group.members, createdBy: group.createdBy } };
+      })
+    },
+    {
+      name: "bridge_group_send",
+      description: "Send a chat message to every member of a group channel except yourself. Offline members are skipped (they catch up via bridge_history { channel }). You must be a member.",
+      inputSchema: schema({ group: str("Group id from bridge_group_create / bridge_group_list."), message: str("The message text.") }, ["group", "message"]),
+      handler: wrap(true, async (args, peer) => receipt(hub.sendToGroup(peer, String(args.group), String(args.message))))
+    },
+    {
+      name: "bridge_group_list",
+      description: "List every group channel with its members and creator.",
+      inputSchema: schema({}),
+      handler: wrap(true, async () => ({ groups: hub.allGroups() }))
+    },
+    {
+      name: "bridge_group_delete",
+      description: "Delete a group channel (history rows are kept). The creator or a hub manager may delete.",
+      inputSchema: schema({ group: str("Group id to delete.") }, ["group"]),
+      handler: wrap(true, async (args, peer, sessionId) => {
+        const groupId = String(args.group);
+        const group = hub.groupOf(groupId);
+        if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+        if (group.createdBy !== peer) requireManager(peer, `deleting group '${groupId}'`, sessionId);
+        hub.deleteGroup(groupId);
+        return { ok: true, group: groupId };
+      })
+    },
+    {
+      name: "bridge_group_add_member",
+      description: "Add a registered peer to a group channel; the new member can then send to it and read its history. The creator or a hub manager may add.",
+      inputSchema: schema({ group: str("Group id from bridge_group_create / bridge_group_list."), member: str("peerId of the new member.") }, ["group", "member"]),
+      handler: wrap(true, async (args, peer, sessionId) => {
+        const groupId = String(args.group);
+        const member = String(args.member);
+        const group = hub.groupOf(groupId);
+        if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+        if (group.createdBy !== peer) requireManager(peer, `adding a member to group '${groupId}'`, sessionId);
+        const updated = hub.addGroupMember(groupId, member);
+        return { ok: true, group: { id: updated.id, members: updated.members } };
+      })
+    },
+    {
+      name: "bridge_group_remove_member",
+      description: "Remove a member from a group channel; they stop receiving its messages (history rows are kept). The creator or a hub manager may remove; the creator itself cannot be removed.",
+      inputSchema: schema({ group: str("Group id from bridge_group_create / bridge_group_list."), member: str("peerId to remove.") }, ["group", "member"]),
+      handler: wrap(true, async (args, peer, sessionId) => {
+        const groupId = String(args.group);
+        const member = String(args.member);
+        const group = hub.groupOf(groupId);
+        if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+        if (group.createdBy !== peer) requireManager(peer, `removing a member from group '${groupId}'`, sessionId);
+        const updated = hub.removeGroupMember(groupId, member);
+        return { ok: true, group: { id: updated.id, members: updated.members } };
+      })
+    },
     // ---- herdr control tools ------------------------------------------
     // These type into real agent terminals via the herdr runtime. They are
     // gated by checkControl and documented as physical input: unlike
@@ -1290,6 +1723,16 @@ function hubTools(hub, registry, options) {
 
 // src/mcp-server.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
+import { readFileSync as readFileSync2 } from "node:fs";
+var ADMIN_PATH = "/admin";
+var ADMIN_API_PATH = "/admin/api";
+var adminPageCache;
+function adminPage() {
+  if (adminPageCache === void 0) {
+    adminPageCache = readFileSync2(new URL("../assets/admin.html", import.meta.url), "utf8");
+  }
+  return adminPageCache;
+}
 var SUPPORTED_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var LATEST_VERSION = SUPPORTED_VERSIONS[0];
 var MAX_BODY_BYTES = 1048576;
@@ -1362,8 +1805,24 @@ var SessionRegistry = class {
   isSuppressed(sessionId) {
     return sessionId !== void 0 && this.suppressedAuto.has(sessionId);
   }
+  /** Session → client IP (remote mode: the admin roster shows where a peer
+   * connects from, so the operator can tell Zhang San's kimi-code from Li Si's). */
+  sessionIps = /* @__PURE__ */ new Map();
   /** Sessions with a live SSE stream (server→client channel). */
   liveStreams = /* @__PURE__ */ new Set();
+  /** Session → token identity (remote auth mode only; see src/auth.ts).
+   * The TOKEN, not the client-reported name, decides the peer id, so two
+   * users running the same client get distinct peers. */
+  tokenBindings = /* @__PURE__ */ new Map();
+  /** Bind a session to its token identity (at initialize / SSE open). */
+  bindToken(sessionId, identity) {
+    this.tokenBindings.set(sessionId, identity);
+  }
+  /** Token identity bound to a session, if remote auth is in use. */
+  tokenFor(sessionId) {
+    if (sessionId === void 0) return void 0;
+    return this.tokenBindings.get(sessionId);
+  }
   /** Mark a session's SSE stream open (server→client channel alive). */
   markSseOpen(sessionId) {
     this.liveStreams.add(sessionId);
@@ -1422,18 +1881,29 @@ var SessionRegistry = class {
 var McpStreamableHttpServer = class {
   constructor(tools, info, registry, log = () => {
   }, onInitialize = () => {
-  }) {
+  }, authenticate, adminApi) {
     this.tools = tools;
     this.info = info;
     this.registry = registry;
     this.log = log;
     this.onInitialize = onInitialize;
+    this.authenticate = authenticate;
+    this.adminApi = adminApi;
   }
   sseStreams = /* @__PURE__ */ new Map();
   /** Attach request handling for `path` (e.g. `/mcp`) to an http server. */
   attach(server, path2) {
     server.on("request", (req, res) => {
       const url = new URL(req.url ?? "/", "http://localhost");
+      if (url.pathname === ADMIN_PATH && req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+        res.end(adminPage());
+        return;
+      }
+      if (url.pathname.startsWith(ADMIN_API_PATH) && this.adminApi !== void 0) {
+        void this.handleAdminApi(req, res, url);
+        return;
+      }
       if (url.pathname !== path2) {
         res.writeHead(404, { "Content-Type": "application/json" }).end(JSON.stringify({ error: "not found" }));
         return;
@@ -1483,7 +1953,14 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
     }
   }
   handleGet(req, res) {
+    if (this.authenticate !== void 0 && this.authenticate(req) === void 0) {
+      res.writeHead(401, { ...corsHeaders(), "Content-Type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify({ error: "unauthorized: missing or invalid bearer token" }));
+      return;
+    }
     const sessionId = this.registry.ensureSession(this.registry.sessionIdFor(req));
+    const identity = this.authenticate?.(req);
+    if (identity !== void 0) this.registry.bindToken(sessionId, identity);
     res.writeHead(200, {
       ...corsHeaders(),
       "Content-Type": "text/event-stream; charset=utf-8",
@@ -1499,7 +1976,79 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
       this.registry.markSseClosed(sessionId);
     });
   }
+  /** Reject a request without a valid token (remote auth mode). */
+  unauthorized(res, id, why) {
+    res.writeHead(401, { ...corsHeaders(), "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32001, message: `unauthorized: ${why}` } }));
+  }
+  /** Management API for the bundled admin page: issue/revoke tokens and list
+   * them. Like everything else, each call is authenticated by `authenticate`
+   * and must resolve to a MANAGER role — an agent token gets 403. */
+  async handleAdminApi(req, res, url) {
+    const respond = (status, body) => {
+      res.writeHead(status, { ...corsHeaders(), "Content-Type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify(body));
+    };
+    const identity = this.authenticate?.(req);
+    if (identity === void 0) {
+      respond(401, { error: "unauthorized: manager token required" });
+      return;
+    }
+    if (identity.role !== "manager") {
+      respond(403, { error: "forbidden: this API needs a manager-role token" });
+      return;
+    }
+    const api = this.adminApi;
+    const seg = url.pathname.slice(ADMIN_API_PATH.length).replace(/^\/+|\/+$/g, "").split("/");
+    if (req.method === "GET" && seg[0] === "tokens") {
+      respond(200, { tokens: api.listTokens(url.searchParams.get("reveal") === "1") });
+      return;
+    }
+    if (req.method === "POST" && seg[0] === "tokens" && seg[1] === "add") {
+      let input;
+      try {
+        input = JSON.parse((await readBody(req)).toString("utf8"));
+      } catch (error) {
+        respond(400, { error: `bad json: ${error.message}` });
+        return;
+      }
+      try {
+        const created = api.addToken({
+          peer: String(input.peer ?? ""),
+          role: String(input.role ?? "agent"),
+          owner: input.owner === void 0 ? void 0 : String(input.owner)
+        });
+        respond(200, { created });
+      } catch (error) {
+        respond(400, { error: error.message });
+      }
+      return;
+    }
+    if (req.method === "DELETE" && seg[0] === "tokens" && seg[1] === "remove" && seg[2] !== void 0) {
+      respond(200, { removed: api.removeToken(decodeURIComponent(seg[2])) });
+      return;
+    }
+    respond(404, { error: "not found" });
+  }
   async handlePost(req, res) {
+    let authIdentity;
+    if (this.authenticate !== void 0) {
+      authIdentity = this.authenticate(req);
+      if (authIdentity === void 0) {
+        this.unauthorized(res, null, "missing or invalid bearer token");
+        return;
+      }
+      const existingSession = this.registry.sessionIdFor(req);
+      const bound = existingSession === void 0 ? void 0 : this.registry.tokenFor(existingSession);
+      const bothAnonymous = bound?.anonymous === true && authIdentity.anonymous === true;
+      if (bound !== void 0 && !bothAnonymous && (bound.peer !== authIdentity.peer || bound.role !== authIdentity.role)) {
+        this.unauthorized(res, null, "token does not match this session");
+        return;
+      }
+      if (existingSession !== void 0 && bound === void 0 && !authIdentity.anonymous) {
+        this.registry.bindToken(existingSession, authIdentity);
+      }
+    }
     let body;
     try {
       body = await readBody(req);
@@ -1520,12 +2069,13 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
     }
     const id = message.id ?? null;
     const sessionId = this.registry.sessionIdFor(req);
+    if (sessionId !== void 0) this.registry.sessionIps.set(sessionId, clientIp(req));
     if (id === null) {
       res.writeHead(202, { ...corsHeaders(), "Content-Length": "0" }).end();
       return;
     }
     try {
-      const { result, extraHeaders } = await this.dispatch(message, sessionId);
+      const { result, extraHeaders } = await this.dispatch(message, sessionId, authIdentity);
       res.writeHead(200, {
         ...corsHeaders(),
         "Content-Type": "application/json; charset=utf-8",
@@ -1538,7 +2088,7 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
       this.jsonRpcError(res, id, code, error.message, void 0, messageProtocolVersion(req));
     }
   }
-  async dispatch(message, sessionId) {
+  async dispatch(message, sessionId, authIdentity) {
     const method = message.method ?? "";
     switch (method) {
       case "initialize": {
@@ -1549,6 +2099,9 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
         if (clientName !== void 0) {
           this.registry.noteClient(newSessionId, clientName, clientVersion);
         }
+        if (authIdentity !== void 0) {
+          this.registry.bindToken(newSessionId, authIdentity);
+        }
         this.onInitialize(newSessionId, clientName, clientVersion);
         const requested = message.params?.protocolVersion;
         const protocolVersion = typeof requested === "string" && SUPPORTED_VERSIONS.includes(requested) ? requested : LATEST_VERSION;
@@ -1612,6 +2165,14 @@ function rpcError(code, message) {
 function messageProtocolVersion(req) {
   return req.headers["mcp-protocol-version"] ?? LATEST_VERSION;
 }
+function clientIp(req) {
+  const forwarded = req.headers["x-forwarded-for"];
+  const raw = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+  if (typeof raw === "string" && raw.trim() !== "") {
+    return raw.split(",")[0].trim();
+  }
+  return (req.socket.remoteAddress ?? "?").replace(/^::ffff:/, "");
+}
 function corsHeaders() {
   return {
     "Access-Control-Allow-Origin": "*",
@@ -1637,9 +2198,149 @@ function readBody(req) {
   });
 }
 
+// src/persist.ts
+import { DatabaseSync } from "node:sqlite";
+var KIND_NAMES = ["chat", "task", "notice", "ack"];
+function messageToRow(message) {
+  return [message.id, message.from, message.to, message.kind, message.content, message.ref ?? null, message.channel ?? null, message.ts];
+}
+function rowToMessage(row) {
+  const id = row.id;
+  const from = row.from_peer;
+  const to = row.to_peer;
+  const kind = row.kind;
+  const content = row.content;
+  const ts = row.ts;
+  if (typeof id !== "string" || typeof from !== "string" || typeof to !== "string" || typeof content !== "string" || typeof ts !== "number") return void 0;
+  if (!KIND_NAMES.includes(kind)) return void 0;
+  return {
+    id,
+    from,
+    to,
+    kind,
+    content,
+    ...typeof row.ref === "string" && row.ref !== "" ? { ref: row.ref } : {},
+    ...typeof row.channel === "string" && row.channel !== "" ? { channel: row.channel } : {},
+    ts
+  };
+}
+var SQLiteStateStore = class {
+  constructor(file, historyLimit, log) {
+    this.historyLimit = historyLimit;
+    this.db = new DatabaseSync(file);
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS profiles (
+        id TEXT PRIMARY KEY, alias TEXT, client_name TEXT, client_version TEXT, registered_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS messages (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL, from_peer TEXT NOT NULL,
+        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, ts INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS mailboxes (
+        peer TEXT NOT NULL, seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL, from_peer TEXT NOT NULL,
+        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, ts INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS groups (
+        id TEXT PRIMARY KEY, name TEXT, members TEXT NOT NULL, created_by TEXT NOT NULL, created_at INTEGER NOT NULL
+      );
+    `);
+    log.info(`sqlite state open: ${file}`);
+  }
+  db;
+  buffer = [];
+  /** Buffer one history message (called per message via the hub hook). */
+  appendMessage(message) {
+    this.buffer.push(message);
+  }
+  /** Insert buffered messages and re-snapshot mailboxes/profiles/groups. */
+  flush(snapshot) {
+    const insert = this.db.prepare(
+      "INSERT INTO messages (id, from_peer, to_peer, kind, content, ref, channel, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+    );
+    for (const message of this.buffer.splice(0, this.buffer.length)) {
+      insert.run(...messageToRow(message));
+    }
+    this.db.exec("DELETE FROM mailboxes");
+    const insertMail = this.db.prepare(
+      "INSERT INTO mailboxes (peer, id, from_peer, to_peer, kind, content, ref, channel, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+    );
+    for (const [peer, queue] of Object.entries(snapshot.mailboxes)) {
+      for (const message of queue) insertMail.run(peer, ...messageToRow(message));
+    }
+    this.db.exec("DELETE FROM profiles");
+    const insertProfile = this.db.prepare(
+      "INSERT INTO profiles (id, alias, client_name, client_version, registered_at) VALUES (?, ?, ?, ?, ?)"
+    );
+    for (const profile of snapshot.profiles) {
+      insertProfile.run(profile.id, profile.alias ?? null, profile.clientName ?? null, profile.clientVersion ?? null, profile.registeredAt);
+    }
+    this.db.exec("DELETE FROM groups");
+    const insertGroup = this.db.prepare(
+      "INSERT INTO groups (id, name, members, created_by, created_at) VALUES (?, ?, ?, ?, ?)"
+    );
+    for (const group of snapshot.groups) {
+      insertGroup.run(group.id, group.name ?? null, JSON.stringify(group.members), group.createdBy, group.createdAt);
+    }
+    const row = this.db.prepare("SELECT COUNT(*) AS n FROM messages").get();
+    const total = Number(row.n);
+    if (total > this.historyLimit * 2) {
+      this.db.exec(`DELETE FROM messages WHERE seq <= (SELECT MAX(seq) FROM messages) - ${this.historyLimit}`);
+    }
+  }
+  /** Read everything persisted so far (boot restore). */
+  load() {
+    const profiles = [];
+    for (const row of this.db.prepare("SELECT * FROM profiles").all()) {
+      if (typeof row.id !== "string") continue;
+      profiles.push({
+        id: row.id,
+        ...typeof row.alias === "string" && row.alias !== "" ? { alias: row.alias } : {},
+        ...typeof row.client_name === "string" && row.client_name !== "" ? { clientName: row.client_name } : {},
+        ...typeof row.client_version === "string" && row.client_version !== "" ? { clientVersion: row.client_version } : {},
+        registeredAt: typeof row.registered_at === "number" ? row.registered_at : Date.now()
+      });
+    }
+    const messages = [];
+    for (const row of this.db.prepare("SELECT * FROM messages ORDER BY seq").all()) {
+      const message = rowToMessage(row);
+      if (message !== void 0) messages.push(message);
+    }
+    const mailboxes = {};
+    for (const row of this.db.prepare("SELECT * FROM mailboxes ORDER BY seq").all()) {
+      if (typeof row.peer !== "string") continue;
+      const message = rowToMessage(row);
+      if (message === void 0) continue;
+      (mailboxes[row.peer] ??= []).push(message);
+    }
+    const groups = [];
+    for (const row of this.db.prepare("SELECT * FROM groups").all()) {
+      if (typeof row.id !== "string" || typeof row.members !== "string") continue;
+      try {
+        const members = JSON.parse(row.members);
+        if (!Array.isArray(members) || members.length === 0) continue;
+        groups.push({
+          id: row.id,
+          members: members.filter((m) => typeof m === "string"),
+          createdBy: typeof row.created_by === "string" ? row.created_by : "",
+          createdAt: typeof row.created_at === "number" ? row.created_at : Date.now(),
+          ...typeof row.name === "string" && row.name !== "" ? { name: row.name } : {}
+        });
+      } catch {
+      }
+    }
+    return { profiles, messages, mailboxes, groups };
+  }
+  /** Final flush + close (hub shutdown). */
+  close(snapshot) {
+    this.flush(snapshot);
+    this.db.close();
+  }
+};
+
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.6.0";
+var SERVER_VERSION = "0.7.1";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -1661,16 +2362,39 @@ var DEFAULT_CONFIG = {
   // are NOT managers — they keep chatting, a GUI manages.
   managerPeers: ["agent-hub-cli"]
 };
+function authTokensAdmin(file, reloadAuth) {
+  if (file === void 0) return void 0;
+  return {
+    listTokens: (reveal) => readTokens(file).map((r) => ({
+      token: reveal ? r.token : `${r.token.slice(0, 6)}\u2026${r.token.slice(-4)}`,
+      peer: r.peer,
+      role: r.role,
+      ...r.owner !== void 0 ? { owner: r.owner } : {}
+    })),
+    addToken: (input) => {
+      const row = addToken(file, { peer: input.peer, role: input.role, owner: input.owner });
+      reloadAuth?.();
+      return { token: row.token, peer: row.peer, role: row.role, ...row.owner !== void 0 ? { owner: row.owner } : {} };
+    },
+    removeToken: (peer) => {
+      const ok = removeToken(file, peer);
+      if (ok) reloadAuth?.();
+      return ok;
+    },
+    reloadAuth: () => reloadAuth?.()
+  };
+}
 function writeRosterFile(file, profiles) {
-  mkdirSync(dirname(file), { recursive: true });
+  mkdirSync2(dirname2(file), { recursive: true });
   const tmp = `${file}.tmp`;
-  writeFileSync(tmp, JSON.stringify({ version: 1, savedAt: Date.now(), profiles }), "utf8");
-  renameSync(tmp, file);
+  writeFileSync2(tmp, JSON.stringify({ version: 1, savedAt: Date.now(), profiles }), "utf8");
+  renameSync2(tmp, file);
 }
 function startHub(config = {}, log = console) {
   const overrides = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== void 0));
   const resolved = { ...DEFAULT_CONFIG, ...overrides };
   let mcp;
+  let dbStore;
   const pushRoster = () => {
     mcp.notifyAll("notifications/message", {
       level: "info",
@@ -1685,24 +2409,51 @@ function startHub(config = {}, log = console) {
       data: { event: "message", message: present(message) }
     });
   };
+  const managerSet = resolved.managerPeers === "all" ? void 0 : new Set(resolved.managerPeers);
+  const pushRelay = (message) => {
+    const managers = [];
+    for (const sessionId of registry.liveSessions()) {
+      const peer = registry.peerFor(sessionId);
+      if (peer === void 0) continue;
+      if (registry.tokenFor(sessionId)?.role === "manager" || managerSet === void 0 || managerSet.has(peer)) {
+        managers.push(sessionId);
+      }
+    }
+    if (managers.length > 0) {
+      mcp.notify(managers, "notifications/message", {
+        level: "info",
+        logger: "bridge",
+        data: { event: "message", message: present(message) }
+      });
+    }
+  };
   let saveTimer;
   let rosterDirty = false;
-  const flushRoster = () => {
-    if (resolved.stateFile === void 0 || !rosterDirty) return;
-    rosterDirty = false;
-    try {
-      writeRosterFile(resolved.stateFile, hub.exportProfiles());
-    } catch (error) {
-      log.warn(`roster save failed: ${error.message}`);
+  let dbDirty = false;
+  const flushSaves = () => {
+    if (rosterDirty && resolved.stateFile !== void 0) {
+      rosterDirty = false;
+      try {
+        writeRosterFile(resolved.stateFile, hub.exportProfiles());
+      } catch (error) {
+        log.warn(`roster save failed: ${error.message}`);
+      }
+    }
+    if (dbDirty && dbStore !== void 0) {
+      dbDirty = false;
+      try {
+        dbStore.flush({ mailboxes: hub.exportMailboxes(), profiles: hub.exportProfiles(), groups: hub.exportGroups() });
+      } catch (error) {
+        log.warn(`sqlite flush failed: ${error.message}`);
+      }
     }
   };
-  const scheduleRosterSave = () => {
-    if (resolved.stateFile === void 0) return;
-    rosterDirty = true;
+  const scheduleSave = () => {
+    if (resolved.stateFile === void 0 && dbStore === void 0) return;
     if (saveTimer !== void 0) return;
     saveTimer = setTimeout(() => {
       saveTimer = void 0;
-      flushRoster();
+      flushSaves();
     }, 500);
     saveTimer.unref?.();
   };
@@ -1713,6 +2464,30 @@ function startHub(config = {}, log = console) {
     connectedWindowMs: resolved.connectedWindowMs,
     peerIdleTimeoutMs: resolved.peerIdleTimeoutMs,
     onPeerGc: (peerId) => registry.unbindPeerId(peerId),
+    // Remote persistence: buffer every history append; re-snapshot when a
+    // mailbox is consumed so drained messages cannot resurrect on restart.
+    // Also relay every message to manager sessions (the relay stream view) —
+    // best-effort; a notification failure must never break routing.
+    onMessage: (message) => {
+      if (dbStore !== void 0) {
+        dbStore.appendMessage(message);
+        dbDirty = true;
+      }
+      try {
+        pushRelay(message);
+      } catch (error) {
+        log.warn(`relay notification failed: ${error.message}`);
+      }
+    },
+    onMailboxesChanged: () => {
+      if (dbStore === void 0) return;
+      dbDirty = true;
+    },
+    onGroupsChanged: () => {
+      if (dbStore === void 0) return;
+      dbDirty = true;
+      scheduleSave();
+    },
     // The idle GC must never evict a peer whose session has a live SSE channel.
     isPeerLive: (peerId) => livePeersFor(registry).has(peerId),
     // SSE event push: roster changes and queued-mail hints. Best-effort — a
@@ -1723,7 +2498,9 @@ function startHub(config = {}, log = console) {
       } catch (error) {
         log.warn(`peers_changed notification failed: ${error.message}`);
       }
-      scheduleRosterSave();
+      rosterDirty = true;
+      dbDirty = true;
+      scheduleSave();
     },
     onQueued: (message, target) => {
       try {
@@ -1734,9 +2511,39 @@ function startHub(config = {}, log = console) {
     }
   });
   const registry = new SessionRegistry();
-  if (resolved.stateFile !== void 0) {
+  if (resolved.db !== void 0) {
+    try {
+      dbStore = new SQLiteStateStore(resolved.db, resolved.historyLimit, log);
+      const state = dbStore.load();
+      const importedProfiles = hub.importProfiles(state.profiles);
+      if (state.profiles.length === 0 && resolved.stateFile !== void 0) {
+        try {
+          const legacy = JSON.parse(readFileSync3(resolved.stateFile, "utf8"));
+          const migrated = hub.importProfiles(legacy.profiles);
+          if (migrated > 0) log.info(`roster migrated: ${migrated} profile(s) from ${resolved.stateFile} into ${resolved.db}`);
+        } catch (error) {
+          if (error.code !== "ENOENT") {
+            log.warn(`legacy roster import failed: ${error.message}`);
+          }
+        }
+      } else if (importedProfiles > 0) {
+        log.info(`roster restored: ${importedProfiles} profile(s) from ${resolved.db}`);
+      }
+      const restoredMessages = hub.importHistory(state.messages);
+      const restoredQueued = hub.importMailboxes(state.mailboxes);
+      const restoredGroups = hub.importGroups(state.groups);
+      if (restoredMessages + restoredQueued + restoredGroups > 0) {
+        log.info(`state restored from ${resolved.db}: ${restoredMessages} message(s), ${restoredQueued} queued, ${restoredGroups} group(s)`);
+        dbDirty = true;
+      }
+    } catch (error) {
+      dbStore = void 0;
+      log.warn(`sqlite state unavailable (${error.message}); running memory-only`);
+    }
+  }
+  if (dbStore === void 0 && resolved.stateFile !== void 0) {
     try {
-      const parsed = JSON.parse(readFileSync(resolved.stateFile, "utf8"));
+      const parsed = JSON.parse(readFileSync3(resolved.stateFile, "utf8"));
       const imported = hub.importProfiles(parsed.profiles);
       if (imported > 0) log.info(`roster restored: ${imported} profile(s) from ${resolved.stateFile}`);
     } catch (error) {
@@ -1752,6 +2559,25 @@ function startHub(config = {}, log = console) {
     socketPath: resolved.herdrSocketPath,
     sendRequest: resolved.herdrSendRequest
   });
+  let auth;
+  let authReload;
+  if (resolved.authTokens !== void 0) {
+    const table = watchTokenFile(resolved.authTokens, {
+      info: (message) => log.info(message),
+      warn: (message) => log.warn(message)
+    });
+    authReload = table.reload;
+    auth = (req) => {
+      const presented = bearerFromHeaders(req.headers);
+      if (presented !== void 0) return table.authenticate(presented);
+      if (resolved.allowJoin === true) {
+        return { peer: ANON_JOIN_PEER, role: "agent", anonymous: true };
+      }
+      return void 0;
+    };
+  } else if (resolved.allowJoin === true) {
+    auth = (req) => ({ peer: ANON_JOIN_PEER, role: "agent", anonymous: true });
+  }
   mcp = new McpStreamableHttpServer(
     hubTools(hub, registry, {
       defaultWaitMs: resolved.defaultWaitMs,
@@ -1765,12 +2591,26 @@ function startHub(config = {}, log = console) {
     (message) => log.warn(message),
     (sessionId, clientName, clientVersion) => {
       try {
+        const identity = registry.tokenFor(sessionId);
+        if (identity?.anonymous === true && identity.peer === ANON_JOIN_PEER) {
+          let candidate = `join-${sanitizePeerId(clientName ?? "agent")}-${randomBytes2(2).toString("hex")}`;
+          while (hub.has(candidate)) {
+            candidate = `join-${sanitizePeerId(clientName ?? "agent")}-${randomBytes2(2).toString("hex")}`;
+          }
+          registry.bindToken(sessionId, { ...identity, peer: candidate });
+        }
         const peer = autoRegisterPeer(hub, registry, sessionId, clientName, clientVersion);
-        if (peer !== void 0) log.info(`peer joined: ${peer}`);
+        if (peer !== void 0) {
+          const owner = registry.tokenFor(sessionId)?.owner;
+          const anon = registry.tokenFor(sessionId)?.anonymous === true ? " (anonymous join)" : "";
+          log.info(`peer joined: ${peer}${owner !== void 0 ? ` (owner: ${owner})` : ""}${anon}`);
+        }
       } catch (error) {
         log.warn(`auto-register failed: ${error.message}`);
       }
-    }
+    },
+    auth,
+    authTokensAdmin(resolved.authTokens, authReload)
   );
   const server = createServer();
   mcp.attach(server, resolved.path);
@@ -1790,7 +2630,15 @@ function startHub(config = {}, log = console) {
         clearTimeout(saveTimer);
         saveTimer = void 0;
       }
-      flushRoster();
+      flushSaves();
+      if (dbStore !== void 0) {
+        try {
+          dbStore.close({ mailboxes: hub.exportMailboxes(), profiles: hub.exportProfiles(), groups: hub.exportGroups() });
+        } catch (error) {
+          log.warn(`sqlite close failed: ${error.message}`);
+        }
+        dbStore = void 0;
+      }
       server.closeAllConnections?.();
       server.close();
     }
@@ -1810,13 +2658,21 @@ export {
   PEER_ID_PATTERN,
   SERVER_NAME,
   SERVER_VERSION,
+  SQLiteStateStore,
   SessionRegistry,
+  addToken,
   autoRegisterPeer,
   decodeContent,
   encodeContent,
+  generateToken,
   hubTools,
+  loadTokenFile,
   present,
+  readTokens,
+  removeToken,
   sanitizeAlias,
   sanitizePeerId,
-  startHub
+  startHub,
+  tokenTable,
+  watchTokenFile
 };