wireweave 0.3.45 → 0.3.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wireweave",
-  "version": "0.3.45",
+  "version": "0.3.47",
   "description": "nostr + webrtc voice + data SDK. networking layer for 247420 projects.",
   "type": "module",
   "main": "./src/index.js",
@@ -10,9 +10,11 @@
     "./wireweave": "./src/wireweave.js",
     "./relay-pool": "./src/relay-pool.js",
     "./auth": "./src/auth.js",
+    "./profile": "./src/profile.js",
     "./fsm": "./src/fsm.js",
     "./voice": "./src/voice.js",
     "./data": "./src/data.js",
+    "./frame": "./src/frame.js",
     "./chat": "./src/chat.js",
     "./channels": "./src/channels.js",
     "./servers": "./src/servers.js",
@@ -22,7 +24,9 @@
     "./settings": "./src/settings.js",
     "./media": "./src/media.js",
     "./pages": "./src/pages.js",
-    "./debug": "./src/debug.js"
+    "./debug": "./src/debug.js",
+    "./dm": "./src/dm.js",
+    "./ephemeral-relay": "./src/ephemeral-relay.js"
   },
   "files": [
     "src",

package/src/bans.js

@@ -1,5 +1,7 @@
 import { dtag, parseDtag } from './dtag.js';
 
+const AUDIT_LOG_MAX = 200;
+
 export class Bans extends EventTarget {
   constructor({ relayPool, auth = null, roles = null }) {
     super();
@@ -7,10 +9,17 @@ export class Bans extends EventTarget {
     this.pool = relayPool; this.auth = auth; this.roles = roles;
     this.store = new Map();
     this.subs = new Map();
+    // In-memory audit log of moderation actions seen via subscribe(), most
+    // recent first, capped at AUDIT_LOG_MAX. Rebuilt purely from the same
+    // real relay-published events the ban/timeout/kick/unban/mute state
+    // already derives from — no separate write path, so the log can never
+    // drift from the actual enforced state.
+    this.auditLog = [];
   }
 
   isBanned(serverId, pubkey) { return !!(this.store.get(serverId)?.banned || []).includes(pubkey); }
   isKicked(serverId, pubkey) { return !!(this.store.get(serverId)?.kicked || []).includes(pubkey); }
+  isMuted(serverId, channelId, pubkey) { return !!(this.store.get(serverId)?.muted?.[channelId] || []).includes(pubkey); }
 
   isTimedOut(serverId, pubkey) {
     const t = this.store.get(serverId)?.timeouts?.[pubkey];
@@ -29,6 +38,23 @@ export class Bans extends EventTarget {
     this.pool.publish(signed);
   }
 
+  // Reverses a prior ban. A separate 'unban' d-tag namespace (not a delete
+  // of the 'ban' event — nostr relays aren't guaranteed to honor NIP-09
+  // deletion requests, and a replaceable/addressable ban event has no
+  // built-in revocation) whose presence with a newer timestamp than the
+  // matching ban event means "no longer banned" — see _applyEvent's ordering.
+  async unban(serverId, pubkey) {
+    if (!this.auth?.isLoggedIn()) throw new Error('Not logged in');
+    if (this.roles && !this.roles.isAdmin(serverId)) throw new Error('Insufficient permissions');
+    const dTag = dtag('unban', serverId, pubkey);
+    const signed = await this.auth.sign({
+      kind: 30078, created_at: Math.floor(Date.now() / 1000),
+      tags: [['d', dTag], ['server', serverId]],
+      content: JSON.stringify({ action: 'unban', pubkey, timestamp: Math.floor(Date.now() / 1000) })
+    });
+    this.pool.publish(signed);
+  }
+
   async timeout(serverId, pubkey, minutes) {
     if (!this.auth?.isLoggedIn()) throw new Error('Not logged in');
     if (this.roles && !this.roles.isAdmin(serverId)) throw new Error('Insufficient permissions');
@@ -42,6 +68,23 @@ export class Bans extends EventTarget {
     this.pool.publish(signed);
   }
 
+  // Explicit early-clear of an active timeout — publishing a new timeout
+  // event with expiry already in the past is the wire-level mechanism
+  // (mirrors how the existing subscribe() handler already deletes an
+  // expired timeout from the local store), exposed as its own method so a
+  // caller doesn't have to know that trick.
+  async clearTimeout(serverId, pubkey) {
+    if (!this.auth?.isLoggedIn()) throw new Error('Not logged in');
+    if (this.roles && !this.roles.isAdmin(serverId)) throw new Error('Insufficient permissions');
+    const dTag = dtag('timeout', serverId, pubkey);
+    const signed = await this.auth.sign({
+      kind: 30078, created_at: Math.floor(Date.now() / 1000),
+      tags: [['d', dTag], ['server', serverId]],
+      content: JSON.stringify({ action: 'timeout', pubkey, expiry: Math.floor(Date.now() / 1000) - 1 })
+    });
+    this.pool.publish(signed);
+  }
+
   async kickFromVoice(pubkey) {
     if (!this.auth?.isLoggedIn()) throw new Error('Not logged in');
     const signed = await this.auth.sign({
@@ -51,6 +94,46 @@ export class Bans extends EventTarget {
     this.pool.publish(signed);
   }
 
+  // Channel-level mute (distinct from a server-wide ban/timeout): silences
+  // one pubkey in one channel only, e.g. for a channel-specific moderator
+  // without server-wide admin rights over the whole server's ban list.
+  async mute(serverId, channelId, pubkey) {
+    if (!this.auth?.isLoggedIn()) throw new Error('Not logged in');
+    if (this.roles && !this.roles.isMod(serverId)) throw new Error('Insufficient permissions');
+    const dTag = dtag('mute', serverId, channelId, pubkey);
+    const signed = await this.auth.sign({
+      kind: 30078, created_at: Math.floor(Date.now() / 1000),
+      tags: [['d', dTag], ['server', serverId], ['channel', channelId]],
+      content: JSON.stringify({ action: 'mute', pubkey, channelId, timestamp: Math.floor(Date.now() / 1000) })
+    });
+    this.pool.publish(signed);
+  }
+
+  async unmute(serverId, channelId, pubkey) {
+    if (!this.auth?.isLoggedIn()) throw new Error('Not logged in');
+    if (this.roles && !this.roles.isMod(serverId)) throw new Error('Insufficient permissions');
+    const dTag = dtag('mute', serverId, channelId, pubkey);
+    const signed = await this.auth.sign({
+      kind: 30078, created_at: Math.floor(Date.now() / 1000),
+      tags: [['d', dTag], ['server', serverId], ['channel', channelId]],
+      content: JSON.stringify({ action: 'unmute', pubkey, channelId, timestamp: Math.floor(Date.now() / 1000) })
+    });
+    this.pool.publish(signed);
+  }
+
+  // Most-recent-first audit trail of every moderation action seen via
+  // subscribe() for this serverId (or all servers if serverId is omitted),
+  // capped at AUDIT_LOG_MAX entries.
+  getAuditLog(serverId = null) {
+    return serverId ? this.auditLog.filter((e) => e.serverId === serverId) : this.auditLog.slice();
+  }
+
+  _recordAudit(entry) {
+    this.auditLog.unshift(entry);
+    if (this.auditLog.length > AUDIT_LOG_MAX) this.auditLog.length = AUDIT_LOG_MAX;
+    this._emit('audit', { entry });
+  }
+
   subscribe(serverId) {
     if (this.subs.has(serverId)) return;
     if (!serverId) return;
@@ -66,20 +149,58 @@ export class Bans extends EventTarget {
           const dTag = event.tags.find(t => t[0] === 'd');
           if (!dTag?.[1]) return;
           const parsed = parseDtag(dTag[1]);
-          if (!parsed || !['ban', 'timeout', 'kick'].includes(parsed.ns)) return;
+          if (!parsed || !['ban', 'unban', 'timeout', 'kick', 'mute'].includes(parsed.ns)) return;
           const pubkey = parsed.parts[parsed.parts.length - 1];
-          const data = this.store.get(serverId) || { banned: [], timeouts: {}, kicked: [] };
-          if (parsed.ns === 'ban' && pubkey && !data.banned.includes(pubkey)) data.banned.push(pubkey);
-          else if (parsed.ns === 'kick' && pubkey) {
+          const data = this.store.get(serverId) || { banned: [], timeouts: {}, kicked: [], muted: {}, _banTs: {} };
+          data.muted = data.muted || {};
+          data._banTs = data._banTs || {};
+          // A relay-delivered event always carries created_at; default to
+          // "now" only for a malformed/missing value so a legitimate action
+          // is never silently dropped by an always-false comparison against
+          // undefined (0 <= undefined is false in JS).
+          const eventTs = Number.isFinite(event.created_at) ? event.created_at : Math.floor(Date.now() / 1000);
+
+          // ban/unban share one addressable slot per pubkey (different
+          // d-tag namespaces, so a relay won't collapse them as the same
+          // replaceable event) — track the newest-seen timestamp per pubkey
+          // so an out-of-order-delivered older event never undoes a newer
+          // decision, same "latest wins" discipline roles.js/settings.js
+          // already apply to their own single-namespace replaceable state.
+          if (parsed.ns === 'ban' && pubkey) {
+            if ((data._banTs[pubkey] || 0) <= eventTs) {
+              data._banTs[pubkey] = eventTs;
+              if (!data.banned.includes(pubkey)) data.banned.push(pubkey);
+            }
+          } else if (parsed.ns === 'unban' && pubkey) {
+            if ((data._banTs[pubkey] || 0) <= eventTs) {
+              data._banTs[pubkey] = eventTs;
+              data.banned = data.banned.filter((p) => p !== pubkey);
+            }
+          } else if (parsed.ns === 'kick' && pubkey) {
             data.kicked = data.kicked || [];
             if (!data.kicked.includes(pubkey)) data.kicked.push(pubkey);
           } else if (parsed.ns === 'timeout' && pubkey) {
             const body = JSON.parse(event.content);
             if (body.expiry > Math.floor(Date.now() / 1000)) (data.timeouts = data.timeouts || {})[pubkey] = { expiry: body.expiry };
             else if (data.timeouts?.[pubkey]) delete data.timeouts[pubkey];
+          } else if (parsed.ns === 'mute' && pubkey) {
+            const body = JSON.parse(event.content);
+            // d-tag shape is 'mute:<serverId>:<channelId>:<pubkey>' (see
+            // mute()/unmute() above) -> parts = [serverId, channelId,
+            // pubkey] after parseDtag strips the namespace; body.channelId
+            // is the primary source (always present, set by mute()/unmute())
+            // with the d-tag position as a defensive fallback.
+            const channelId = body.channelId ?? parsed.parts[1];
+            data.muted[channelId] = data.muted[channelId] || [];
+            if (body.action === 'unmute') data.muted[channelId] = data.muted[channelId].filter((p) => p !== pubkey);
+            else if (!data.muted[channelId].includes(pubkey)) data.muted[channelId].push(pubkey);
           }
           this.store.set(serverId, data);
           this.dispatchEvent(new CustomEvent('updated', { detail: { serverId, data } }));
+
+          let body = null;
+          try { body = JSON.parse(event.content); } catch {}
+          this._recordAudit({ serverId, ns: parsed.ns, pubkey, actor: event.pubkey, action: body?.action || parsed.ns, at: eventTs, eventId: event.id });
         } catch {}
       });
   }

package/src/data.js

@@ -1,3 +1,5 @@
+import { fragment, Reassembler, MTU_DEFAULT } from './frame.js';
+
 // STUN handles same-LAN / non-symmetric-NAT cases; TURN is required when both
 // peers sit behind symmetric or restricted-cone NAT (typical home routers,
 // most carrier-grade NAT, corporate networks). UDP, TCP, and TLS TURN variants
@@ -51,6 +53,15 @@ const PRESENCE_EXPIRY = 300000;
 const HEARTBEAT = 30000;
 const DISCONNECT_GRACE = 8000;
 const DC_LABEL = 'wireweave-data';
+// Second, parallel data channel per peer for large binary/unreliable
+// traffic (game snapshots etc) — {ordered:false, maxRetransmits:0} is the
+// real WebRTC config for "send it once, don't retransmit, don't block on
+// order" (UDP-like), distinct from DC_LABEL's default reliable/ordered
+// channel above. Large payloads sent on it are auto-fragmented per
+// frame.js's MTU-aware framing since a real RTCDataChannel message has a
+// practical ~16KB limit before cross-browser fragmentation quirks.
+const DC_LABEL_UNRELIABLE = 'wireweave-data-unreliable';
+const UNRELIABLE_DC_OPTIONS = { ordered: false, maxRetransmits: 0 };
 
 const deriveRoomId = async (namespace, room) => {
   const h = await crypto.subtle.digest('SHA-256', new TextEncoder().encode((namespace || 'default') + ':data:' + room));
@@ -67,7 +78,7 @@ const deriveRoomId = async (namespace, room) => {
 const defaultCreatePeerConnection = (config) => new RTCPeerConnection(config);
 
 export class DataSession extends EventTarget {
-  constructor({ fsm, xstate, relayPool, auth, namespace = '', dataChannelOptions = { ordered: true }, iceServers = null, createPeerConnection = defaultCreatePeerConnection }) {
+  constructor({ fsm, xstate, relayPool, auth, namespace = '', dataChannelOptions = { ordered: true }, iceServers = null, createPeerConnection = defaultCreatePeerConnection, mtu = MTU_DEFAULT, fragmentStaleMs = 10000 }) {
     super();
     if (!fsm || !xstate || !relayPool || !auth) throw new Error('DataSession: missing deps');
     this.fsm = fsm; this.xstate = xstate; this.pool = relayPool; this.auth = auth;
@@ -81,6 +92,13 @@ export class DataSession extends EventTarget {
     this.heartbeat = null; this.joinTs = 0;
     this.retrySchedule = {};
     this.displayName = '';
+    // MTU-aware unreliable channel: real WebRTC datachannel messages have a
+    // practical ~16KB limit before cross-browser fragmentation quirks —
+    // mtu is configurable (e.g. larger for controlled/native peers such as
+    // node-datachannel) but defaults to the safe browser-wide value.
+    this.mtu = mtu;
+    this.fragmentStaleMs = fragmentStaleMs;
+    this._nextMessageId = 0;
   }
 
   _initActor() {
@@ -151,6 +169,48 @@ export class DataSession extends EventTarget {
     return n;
   }
 
+  // Sends a large binary payload over the unreliable/unordered channel,
+  // auto-fragmenting per this.mtu (frame.js). Each fragment is sent as its
+  // own dc.send() call — real WebRTC {ordered:false, maxRetransmits:0}
+  // datachannel semantics mean any individual fragment can be dropped;
+  // the receiver's Reassembler tolerates that (see _wireDataChannel above).
+  // Returns false without sending anything if the unreliable channel isn't
+  // open, or if fragmentation itself throws (e.g. payload exceeds the
+  // wire-format's fragment-count ceiling — see frame.js maxPayloadBytes).
+  sendUnreliable(peerPubkey, payload) {
+    const peer = this.peers.get(peerPubkey);
+    if (!peer?.dcUnreliable || peer.dcUnreliable.readyState !== 'open') return false;
+    let frames;
+    try { frames = fragment(payload, { messageId: this._nextMessageIdFor(), mtu: this.mtu }); }
+    catch (e) { this._emit('error', { message: 'sendUnreliable fragment failed: ' + e.message }); return false; }
+    try { for (const f of frames) peer.dcUnreliable.send(f); return true; }
+    catch { return false; }
+  }
+
+  broadcastUnreliable(payload) {
+    let frames;
+    try { frames = fragment(payload, { messageId: this._nextMessageIdFor(), mtu: this.mtu }); }
+    catch (e) { this._emit('error', { message: 'broadcastUnreliable fragment failed: ' + e.message }); return 0; }
+    let n = 0;
+    for (const [, peer] of this.peers) {
+      if (peer.dcUnreliable?.readyState === 'open') {
+        try { for (const f of frames) peer.dcUnreliable.send(f); n++; } catch {}
+      }
+    }
+    return n;
+  }
+
+  // Per-session messageId counter, uint16 wraparound (see frame.js header
+  // format + the mtu-messageid-wraparound PRD note: collisions are scoped
+  // to the same peer's own overlapping in-flight traffic within staleMs,
+  // an accepted small-probability risk matching typical UDP-sequence-number
+  // designs rather than something solved perfectly here).
+  _nextMessageIdFor() {
+    const id = this._nextMessageId;
+    this._nextMessageId = (this._nextMessageId + 1) & 0xffff;
+    return id;
+  }
+
   getParticipants() { return Array.from(this.participants.values()); }
   getPeers() { return Array.from(this.peers.keys()); }
 
@@ -201,7 +261,7 @@ export class DataSession extends EventTarget {
     const fsmActor = this.xstate.createActor(this.fsm.peerMachine);
     fsmActor.subscribe((snap) => { const p = this.peers.get(peerPubkey); if (p) p.state = snap.value; });
     fsmActor.start();
-    const peer = { pc: null, dc: null, pendingCandidates: [], bufferedCandidates: [], iceTimer: null, disconnectTimer: null, failCount: 0, state: 'new', fsm: fsmActor, remoteDescSet: false };
+    const peer = { pc: null, dc: null, dcUnreliable: null, reassembler: new Reassembler({ staleMs: this.fragmentStaleMs }), pendingCandidates: [], bufferedCandidates: [], iceTimer: null, disconnectTimer: null, failCount: 0, state: 'new', fsm: fsmActor, remoteDescSet: false };
     this.peers.set(peerPubkey, peer);
     const pc = this.createPeerConnection({ iceServers: this.iceServers, bundlePolicy: 'max-bundle', iceCandidatePoolSize: 4, iceTransportPolicy: 'all' });
     peer.pc = pc;
@@ -237,13 +297,21 @@ export class DataSession extends EventTarget {
       if (pc.connectionState === 'closed') this._closePeer(peerPubkey);
     };
     if (isOfferer) {
+      // Both data channels MUST be created before createOffer() below — a
+      // channel created after the offer is negotiated is never included in
+      // that offer's SDP, so the answerer would never see it.
       try {
         const dc = pc.createDataChannel(DC_LABEL, this.dcOptions);
-        peer.dc = dc; this._wireDataChannel(dc, peer, peerPubkey);
+        peer.dc = dc; this._wireDataChannel(dc, peer, peerPubkey, false);
+      } catch {}
+      try {
+        const dcU = pc.createDataChannel(DC_LABEL_UNRELIABLE, UNRELIABLE_DC_OPTIONS);
+        peer.dcUnreliable = dcU; this._wireDataChannel(dcU, peer, peerPubkey, true);
       } catch {}
     } else {
       pc.ondatachannel = (ev) => {
-        if (ev.channel.label === DC_LABEL) { peer.dc = ev.channel; this._wireDataChannel(peer.dc, peer, peerPubkey); }
+        if (ev.channel.label === DC_LABEL) { peer.dc = ev.channel; this._wireDataChannel(peer.dc, peer, peerPubkey, false); }
+        else if (ev.channel.label === DC_LABEL_UNRELIABLE) { peer.dcUnreliable = ev.channel; this._wireDataChannel(peer.dcUnreliable, peer, peerPubkey, true); }
       };
     }
     if (isOfferer) {
@@ -252,12 +320,28 @@ export class DataSession extends EventTarget {
     }
   }
 
-  _wireDataChannel(dc, peer, peerPubkey) {
+  _wireDataChannel(dc, peer, peerPubkey, unreliable) {
     dc.binaryType = 'arraybuffer';
-    dc.onopen = () => this._emit('peer-open', { peerPubkey });
-    dc.onclose = () => this._emit('peer-close', { peerPubkey });
-    dc.onmessage = (e) => this._emit('data', { peerPubkey, data: e.data });
-    dc.onerror = (e) => this._emit('peer-error', { peerPubkey, error: e });
+    dc.onopen = () => this._emit('peer-open', { peerPubkey, unreliable });
+    dc.onclose = () => this._emit('peer-close', { peerPubkey, unreliable });
+    dc.onerror = (e) => this._emit('peer-error', { peerPubkey, unreliable, error: e });
+    if (!unreliable) {
+      dc.onmessage = (e) => this._emit('data', { peerPubkey, data: e.data, unreliable: false });
+      return;
+    }
+    // Unreliable channel carries MTU-framed fragments (see frame.js) — feed
+    // each incoming fragment into this peer's Reassembler and only emit
+    // 'data' once a full message is reassembled. A permanently-dropped
+    // fragment (real risk on {ordered:false, maxRetransmits:0}) never
+    // blocks delivery of the next message; its buffer is evicted by the
+    // Reassembler's own staleMs sweep, run lazily on every feed().
+    dc.onmessage = (e) => {
+      let payload;
+      try { payload = e.data instanceof ArrayBuffer ? e.data : (e.data?.buffer ?? e.data); } catch { return; }
+      let out;
+      try { out = peer.reassembler.feed(payload); } catch { return; }
+      if (out) this._emit('data', { peerPubkey, data: out.buffer.byteLength === out.byteLength ? out.buffer : out.slice().buffer, unreliable: true });
+    };
   }
 
   _doIceRestart(peer, peerPubkey, fsmActor) {
@@ -318,6 +402,7 @@ export class DataSession extends EventTarget {
     if (peer.iceTimer) clearTimeout(peer.iceTimer);
     if (peer.disconnectTimer) clearTimeout(peer.disconnectTimer);
     try { peer.dc?.close(); } catch {}
+    try { peer.dcUnreliable?.close(); } catch {}
     try { peer.pc?.close(); } catch {}
     this.peers.delete(peerPubkey);
     this._emit('peer-closed', { peerPubkey });
@@ -343,6 +428,8 @@ export class DataSession extends EventTarget {
         fsmState: peer.fsm?.getSnapshot().value,
         connState: peer.pc?.connectionState,
         dcState: peer.dc?.readyState || null,
+        dcUnreliableState: peer.dcUnreliable?.readyState || null,
+        pendingFragmentSets: peer.reassembler?.pendingCount() ?? 0,
         candidates: peer.pendingCandidates.length,
         buffered: peer.bufferedCandidates.length
       });

package/src/dtag.js

@@ -1,4 +1,4 @@
-const NAMESPACES = new Set(['ban', 'timeout', 'kick', 'page', 'channels', 'roles', 'settings']);
+const NAMESPACES = new Set(['ban', 'timeout', 'kick', 'page', 'channels', 'roles', 'settings', 'unban', 'mute']);
 
 // Frozen on-relay wire prefix. The brand is now wireweave but deployed events
 // carry 'zellous-' d-tags, so this is a published-contract constant — do not

package/src/ephemeral-relay.js

@@ -0,0 +1,111 @@
+// A minimal, REAL NIP-01-speaking nostr relay, meant to be spun up
+// in-process for deterministic tests independent of public relay uptime
+// (AGENTS.md's testRelay() depends on real public relays specifically to
+// mask single-relay flake — this is the complementary piece: a real relay
+// process test.js itself controls, for assertions that need to NOT flake
+// on a third party's infrastructure). This is not a mock: it's a real
+// `ws` WebSocket server that actually parses/validates/stores/relays
+// real signed nostr events per the NIP-01 wire protocol (EVENT/REQ/CLOSE/
+// EOSE/OK/NOTICE), matching the repo's real-services-only test discipline
+// (an ephemeral relay is a real relay, just short-lived and unpersisted).
+//
+// Deliberately minimal: in-memory event store (no expiry/persistence
+// needed for a test run), naive filter matching (kinds/authors/#tag/since/
+// until/limit — the filter shapes wireweave's own RelayPool actually
+// sends), and no NIP-11 relay-info document. Not meant for production use.
+
+export class EphemeralRelay {
+  constructor({ WebSocketServer, verifyEvent = null, port = 0 } = {}) {
+    if (!WebSocketServer) throw new Error('EphemeralRelay: WebSocketServer required (e.g. ws\'s WebSocketServer)');
+    this.verifyEvent = verifyEvent;
+    this.events = [];
+    this.clients = new Map(); // ws -> Map<subId, filters[]>
+    this.wss = new WebSocketServer({ port });
+    this.wss.on('connection', (ws) => this._onConnection(ws));
+  }
+
+  get port() { return this.wss.address()?.port; }
+  get url() { return 'ws://127.0.0.1:' + this.port; }
+
+  _onConnection(ws) {
+    this.clients.set(ws, new Map());
+    ws.on('message', (raw) => {
+      let msg;
+      try { msg = JSON.parse(raw.toString()); } catch { return; }
+      if (!Array.isArray(msg)) return;
+      const [type] = msg;
+      if (type === 'EVENT') this._handleEvent(ws, msg[1]);
+      else if (type === 'REQ') this._handleReq(ws, msg[1], msg.slice(2));
+      else if (type === 'CLOSE') this._handleClose(ws, msg[1]);
+    });
+    ws.on('close', () => this.clients.delete(ws));
+    ws.on('error', () => {});
+  }
+
+  _handleEvent(ws, event) {
+    if (!event?.id) return;
+    if (this.verifyEvent) {
+      let ok = false;
+      try { ok = this.verifyEvent(event); } catch { ok = false; }
+      if (!ok) { this._send(ws, ['OK', event.id, false, 'invalid: signature verification failed']); return; }
+    }
+    if (!this.events.find((e) => e.id === event.id)) {
+      this.events.push(event);
+      // Broadcast to every OTHER client's matching live subscriptions —
+      // real relay fan-out, not just an echo back to the publisher.
+      for (const [clientWs, subs] of this.clients) {
+        for (const [subId, filters] of subs) {
+          if (this._matches(event, filters)) this._send(clientWs, ['EVENT', subId, event]);
+        }
+      }
+    }
+    this._send(ws, ['OK', event.id, true, '']);
+  }
+
+  _handleReq(ws, subId, filters) {
+    if (!subId) return;
+    this.clients.get(ws)?.set(subId, filters);
+    const matched = this.events.filter((e) => this._matches(e, filters));
+    for (const e of matched) this._send(ws, ['EVENT', subId, e]);
+    this._send(ws, ['EOSE', subId]);
+  }
+
+  _handleClose(ws, subId) {
+    this.clients.get(ws)?.delete(subId);
+  }
+
+  _matches(event, filters) {
+    if (!Array.isArray(filters) || filters.length === 0) return true;
+    return filters.some((f) => this._matchesOne(event, f));
+  }
+
+  _matchesOne(event, f) {
+    if (f.ids && !f.ids.includes(event.id)) return false;
+    if (f.authors && !f.authors.includes(event.pubkey)) return false;
+    if (f.kinds && !f.kinds.includes(event.kind)) return false;
+    if (f.since != null && event.created_at < f.since) return false;
+    if (f.until != null && event.created_at > f.until) return false;
+    for (const key of Object.keys(f)) {
+      if (!key.startsWith('#')) continue;
+      const tagName = key.slice(1);
+      const wanted = f[key];
+      const has = (event.tags || []).some((t) => t[0] === tagName && wanted.includes(t[1]));
+      if (!has) return false;
+    }
+    return true;
+  }
+
+  _send(ws, msg) {
+    if (ws.readyState === 1) { try { ws.send(JSON.stringify(msg)); } catch {} }
+  }
+
+  close() {
+    return new Promise((resolve) => {
+      for (const ws of this.clients.keys()) { try { ws.close(); } catch {} }
+      this.clients.clear();
+      this.wss.close(() => resolve());
+    });
+  }
+}
+
+export const createEphemeralRelay = (opts) => new EphemeralRelay(opts);

package/src/frame.js

@@ -0,0 +1,202 @@
+// MTU-aware binary framing for unreliable/unordered WebRTC data channels.
+//
+// A real RTCDataChannel message has a practical ~16KB limit before browsers
+// start doing their own internal SCTP fragmentation with inconsistent
+// cross-browser behavior at larger sizes — see MTU_DEFAULT below. Large
+// binary payloads (game snapshots, file chunks) are split here into
+// framed fragments that each fit under a configurable MTU, sent
+// independently over an unordered/unreliable channel, and reassembled by
+// (peer, messageId) on the receiving side.
+//
+// Wire format per fragment (fixed 11-byte header, little-endian):
+//   byte 0      : version/magic (0xF7)
+//   bytes 1-2   : messageId   (uint16)
+//   bytes 3-4   : fragmentIndex (uint16, 0-based)
+//   bytes 5-6   : fragmentCount (uint16, total fragments for this message)
+//   bytes 7-10  : totalPayloadLength (uint32, full reassembled byte length)
+//   bytes 11+   : fragment payload bytes
+//
+// fragmentCount is a uint16, so a message can have at most 65535 fragments —
+// maxPayloadBytes() below enforces that bound at fragmentation time rather
+// than silently overflowing the header field.
+
+const MAGIC = 0xf7;
+const HEADER_BYTES = 11;
+
+// ~16KB is the safe practical default across current browsers before
+// RTCDataChannel's own internal fragmentation gets inconsistent
+// cross-browser (Chrome and Firefox both technically allow larger single
+// messages, but behavior at the edges has historically differed). Leave
+// headroom under 16384 for the frame header itself and any SCTP/DTLS
+// overhead the transport adds on top.
+export const MTU_DEFAULT = 16000;
+
+// fragmentCount is a uint16 field — this is a hard wire-format ceiling, not
+// a tunable. A caller handing over a payload requiring more fragments than
+// this at the configured MTU gets a clear error instead of a silently
+// wrapped/truncated header field.
+export const MAX_FRAGMENTS = 0xffff;
+
+export const maxPayloadBytes = (mtu = MTU_DEFAULT) => {
+  const perFragment = mtu - HEADER_BYTES;
+  return perFragment * MAX_FRAGMENTS;
+};
+
+const toUint8 = (payload) => {
+  if (payload instanceof Uint8Array) return payload;
+  if (payload instanceof ArrayBuffer) return new Uint8Array(payload);
+  if (ArrayBuffer.isView(payload)) return new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
+  throw new Error('frame: payload must be an ArrayBuffer or a TypedArray');
+};
+
+export const encodeHeader = ({ messageId, fragmentIndex, fragmentCount, totalPayloadLength }) => {
+  const buf = new ArrayBuffer(HEADER_BYTES);
+  const dv = new DataView(buf);
+  dv.setUint8(0, MAGIC);
+  dv.setUint16(1, messageId, true);
+  dv.setUint16(3, fragmentIndex, true);
+  dv.setUint16(5, fragmentCount, true);
+  dv.setUint32(7, totalPayloadLength, true);
+  return buf;
+};
+
+// Returns null (not a throw) on a header that doesn't parse as this frame
+// format — the caller decides whether that's a protocol violation or just
+// stray traffic on the same channel to ignore.
+export const decodeHeader = (bytes) => {
+  const u8 = toUint8(bytes);
+  if (u8.byteLength < HEADER_BYTES) return null;
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+  if (dv.getUint8(0) !== MAGIC) return null;
+  return {
+    messageId: dv.getUint16(1, true),
+    fragmentIndex: dv.getUint16(3, true),
+    fragmentCount: dv.getUint16(5, true),
+    totalPayloadLength: dv.getUint32(7, true)
+  };
+};
+
+// Splits `payload` into an array of ArrayBuffers, each a complete wire
+// fragment (header + slice), ready to hand to dc.send() one at a time.
+// A zero-length payload still produces exactly one (header-only) fragment,
+// so fragmentCount is always >= 1 and the reassembler never waits forever
+// on a message that legitimately has zero fragments.
+export const fragment = (payload, { messageId, mtu = MTU_DEFAULT }) => {
+  if (mtu <= HEADER_BYTES) throw new Error('frame: mtu must be greater than the ' + HEADER_BYTES + '-byte header');
+  const u8 = toUint8(payload);
+  const totalPayloadLength = u8.byteLength;
+  const perFragment = mtu - HEADER_BYTES;
+  const fragmentCount = Math.max(1, Math.ceil(totalPayloadLength / perFragment));
+  if (fragmentCount > MAX_FRAGMENTS) {
+    throw new Error('frame: payload of ' + totalPayloadLength + ' bytes needs ' + fragmentCount +
+      ' fragments at mtu=' + mtu + ', exceeding the ' + MAX_FRAGMENTS + '-fragment wire-format ceiling ' +
+      '(max ' + maxPayloadBytes(mtu) + ' bytes at this mtu)');
+  }
+  const out = new Array(fragmentCount);
+  for (let i = 0; i < fragmentCount; i++) {
+    const start = i * perFragment;
+    const end = Math.min(start + perFragment, totalPayloadLength);
+    const slice = u8.subarray(start, end);
+    const frameBuf = new ArrayBuffer(HEADER_BYTES + slice.byteLength);
+    new Uint8Array(frameBuf, 0, HEADER_BYTES).set(new Uint8Array(encodeHeader({
+      messageId, fragmentIndex: i, fragmentCount, totalPayloadLength
+    })));
+    new Uint8Array(frameBuf, HEADER_BYTES).set(slice);
+    out[i] = frameBuf;
+  }
+  return out;
+};
+
+const DEFAULT_STALE_MS = 10000;
+const DEFAULT_MAX_IN_FLIGHT = 256;
+
+// Reassembles fragments arriving in ANY order (unordered/unreliable channel)
+// keyed by messageId. Call feed() per incoming fragment; it returns the
+// reassembled Uint8Array once every fragment for that messageId has
+// arrived, or null while still incomplete. Incomplete sets older than
+// staleMs are evicted so a permanently-dropped fragment (real risk on an
+// unreliable channel) never leaks memory forever. A hard cap on concurrent
+// in-flight messageIds (evict-oldest) bounds memory even against a
+// misbehaving/adversarial sender that never completes a message.
+export class Reassembler {
+  constructor({ staleMs = DEFAULT_STALE_MS, maxInFlight = DEFAULT_MAX_IN_FLIGHT } = {}) {
+    this.staleMs = staleMs;
+    this.maxInFlight = maxInFlight;
+    this.sets = new Map(); // messageId -> { fragmentCount, totalPayloadLength, parts: Map<index, Uint8Array>, received, lastSeen }
+  }
+
+  // Sweeps stale incomplete sets. Called lazily on every feed() so no timer
+  // is required, but can also be called on an interval by a host that wants
+  // eviction to happen even when no new traffic arrives.
+  sweep(now = Date.now()) {
+    let evicted = 0;
+    for (const [id, set] of this.sets) {
+      if (now - set.lastSeen > this.staleMs) { this.sets.delete(id); evicted++; }
+    }
+    return evicted;
+  }
+
+  _evictOldestIfOverCap() {
+    if (this.sets.size <= this.maxInFlight) return;
+    let oldestId = null, oldestTs = Infinity;
+    for (const [id, set] of this.sets) {
+      if (set.lastSeen < oldestTs) { oldestTs = set.lastSeen; oldestId = id; }
+    }
+    if (oldestId !== null) this.sets.delete(oldestId);
+  }
+
+  // Returns the reassembled Uint8Array once complete, else null. Duplicate
+  // fragment delivery (real risk on an unreliable channel that retransmits,
+  // or an app-level resend) is idempotent — re-feeding an already-seen
+  // (messageId, fragmentIndex) pair does not double-count toward
+  // completion. Malformed/out-of-range headers are dropped, not thrown.
+  feed(rawFragment) {
+    const now = Date.now();
+    this.sweep(now);
+    const u8 = toUint8(rawFragment);
+    const header = decodeHeader(u8);
+    if (!header) return null;
+    const { messageId, fragmentIndex, fragmentCount, totalPayloadLength } = header;
+    if (fragmentCount < 1 || fragmentIndex >= fragmentCount) return null;
+
+    let set = this.sets.get(messageId);
+    if (!set) {
+      set = { fragmentCount, totalPayloadLength, parts: new Map(), received: 0, lastSeen: now };
+      this.sets.set(messageId, set);
+      this._evictOldestIfOverCap();
+    } else if (set.fragmentCount !== fragmentCount || set.totalPayloadLength !== totalPayloadLength) {
+      // Header disagrees with the in-flight set for this messageId (e.g. a
+      // wrapped-around id reused before the old set went stale) — start
+      // fresh rather than corrupt the old set's reassembly.
+      set = { fragmentCount, totalPayloadLength, parts: new Map(), received: 0, lastSeen: now };
+      this.sets.set(messageId, set);
+    }
+
+    set.lastSeen = now;
+    if (!set.parts.has(fragmentIndex)) {
+      set.parts.set(fragmentIndex, u8.subarray(HEADER_BYTES));
+      set.received++;
+    }
+
+    if (set.received < set.fragmentCount) return null;
+
+    const out = new Uint8Array(set.totalPayloadLength);
+    let offset = 0;
+    for (let i = 0; i < set.fragmentCount; i++) {
+      const part = set.parts.get(i);
+      out.set(part, offset);
+      offset += part.byteLength;
+    }
+    this.sets.delete(messageId);
+    return out;
+  }
+
+  // Introspection for debugging/verification — number of messageIds
+  // currently buffered incomplete, never permanently growing on a healthy
+  // sweep cadence.
+  pendingCount() { return this.sets.size; }
+  has(messageId) { return this.sets.has(messageId); }
+}
+
+export const createReassembler = (opts) => new Reassembler(opts);
+export { HEADER_BYTES };

package/src/index.js

@@ -1,8 +1,10 @@
 export { RelayPool, createRelayPool, RelayHealth } from './relay-pool.js';
 export { NostrAuth, createAuth } from './auth.js';
+export { Profile, createProfile } from './profile.js';
 export { createFSM } from './fsm.js';
 export { VoiceSession, createVoiceSession } from './voice.js';
 export { DataSession, createDataSession } from './data.js';
+export { fragment, encodeHeader, decodeHeader, Reassembler, createReassembler, MTU_DEFAULT, MAX_FRAGMENTS, maxPayloadBytes } from './frame.js';
 export { Chat, createChat } from './chat.js';
 export { Channels, createChannels } from './channels.js';
 export { Servers, createServers } from './servers.js';

package/src/message.js

@@ -1,22 +1,149 @@
+import { safeSetItem } from './safe-storage.js';
+
+const STORE_KEY_PREFIX = 'ww_msgbus_';
+const OUTBOX_KEY_PREFIX = 'ww_msgbus_outbox_';
+const PERSIST_DEBOUNCE_MS = 500;
+
+// Offline-first: MessageBus was purely in-memory (this.messages array,
+// capped, gone on reload). storage (any localStorage/IndexedDB-shaped
+// getItem/setItem/removeItem sync API — matches the same duck-typed
+// contract safe-storage.js/RelayPool's health persistence already use)
+// makes the message list survive a reload, keyed by `roomKey` so multiple
+// rooms/channels don't collide. sendFn is the actual network send (e.g.
+// pool.publish / a Chat.send wrapper) — add() calls it immediately if
+// online, or queues into a persisted outbox if offline/sendFn throws/isn't
+// connected, flushed automatically once flushOutbox() is called (e.g. on a
+// relay 'relay-status':'connected' event from the caller).
 export class MessageBus extends EventTarget {
-  constructor({ maxMessages = 50 } = {}) {
+  constructor({ maxMessages = 50, storage = null, roomKey = 'default', sendFn = null, isOnline = () => true } = {}) {
     super();
     this.max = maxMessages;
     this.messages = [];
     this.handlers = {};
+    this.storage = storage;
+    this.roomKey = roomKey;
+    this.sendFn = sendFn;
+    this.isOnline = isOnline;
+    this.outbox = [];
+    this._persistTimer = null;
+    this._loadPersisted();
+    this._loadOutbox();
   }
 
   handle(m) { this.handlers[m.type]?.(m); }
   register(type, fn) { this.handlers[type] = fn; }
 
+  // Adds a message locally (always, immediately — the local view is never
+  // blocked on network state) and, if a sendFn is configured, attempts the
+  // real send. Offline (isOnline() false) or a throwing/failing sendFn
+  // routes the message into a persisted outbox instead of losing it.
   add(text, { audioData = null, userId = null, username = null } = {}) {
-    const msg = { id: Date.now().toString(36) + Math.random().toString(36).slice(2), text, time: Date.now(), userId, username, audioData };
+    const msg = { id: Date.now().toString(36) + Math.random().toString(36).slice(2), text, time: Date.now(), userId, username, audioData, pending: false };
+    if (this.sendFn) {
+      const online = this.isOnline();
+      if (!online) {
+        msg.pending = true;
+        this._queueOutbox(msg);
+      } else {
+        try {
+          const result = this.sendFn(msg);
+          if (result === false) { msg.pending = true; this._queueOutbox(msg); }
+        } catch {
+          msg.pending = true;
+          this._queueOutbox(msg);
+        }
+      }
+    }
     this.messages = [...this.messages, msg];
     if (this.messages.length > this.max) this.messages = this.messages.slice(-this.max);
+    this._schedulePersist();
     this.dispatchEvent(new CustomEvent('message', { detail: msg }));
     this.dispatchEvent(new CustomEvent('messages', { detail: { list: this.messages } }));
     return msg;
   }
+
+  // Retries every outboxed (offline-queued) message through sendFn, in
+  // original order. A message that sends successfully this pass is marked
+  // pending:false and removed from the outbox; one that still fails stays
+  // queued for the next flush call. Call this when connectivity is
+  // restored (e.g. from a relay-pool 'relay-status' handler).
+  flushOutbox() {
+    if (!this.sendFn || this.outbox.length === 0) return { sent: 0, remaining: this.outbox.length };
+    const stillPending = [];
+    let sent = 0;
+    for (const msg of this.outbox) {
+      let ok = false;
+      try { ok = this.sendFn(msg) !== false; } catch { ok = false; }
+      if (ok) {
+        sent++;
+        const local = this.messages.find((m) => m.id === msg.id);
+        if (local) local.pending = false;
+      } else {
+        stillPending.push(msg);
+      }
+    }
+    this.outbox = stillPending;
+    this._persistOutbox();
+    if (sent > 0) this.dispatchEvent(new CustomEvent('messages', { detail: { list: this.messages } }));
+    this.dispatchEvent(new CustomEvent('outbox-flushed', { detail: { sent, remaining: this.outbox.length } }));
+    return { sent, remaining: this.outbox.length };
+  }
+
+  getOutbox() { return this.outbox.slice(); }
+
+  _queueOutbox(msg) {
+    this.outbox.push(msg);
+    this._persistOutbox();
+  }
+
+  _schedulePersist() {
+    if (!this.storage) return;
+    if (this._persistTimer) return;
+    this._persistTimer = setTimeout(() => { this._persistTimer = null; this._persistNow(); }, PERSIST_DEBOUNCE_MS);
+  }
+
+  _persistNow() {
+    if (!this.storage) return;
+    safeSetItem(this.storage, this, STORE_KEY_PREFIX + this.roomKey, JSON.stringify(this.messages));
+  }
+
+  _persistOutbox() {
+    if (!this.storage) return;
+    safeSetItem(this.storage, this, OUTBOX_KEY_PREFIX + this.roomKey, JSON.stringify(this.outbox));
+  }
+
+  _loadPersisted() {
+    if (!this.storage) return;
+    try {
+      const raw = this.storage.getItem(STORE_KEY_PREFIX + this.roomKey);
+      if (!raw) return;
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) this.messages = parsed.slice(-this.max);
+    } catch { /* corrupt/absent persisted messages is non-fatal */ }
+  }
+
+  _loadOutbox() {
+    if (!this.storage) return;
+    try {
+      const raw = this.storage.getItem(OUTBOX_KEY_PREFIX + this.roomKey);
+      if (!raw) return;
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) this.outbox = parsed;
+    } catch { /* corrupt/absent persisted outbox is non-fatal */ }
+  }
+
+  // Clears BOTH the in-memory list and any persisted copy — a caller
+  // switching rooms with a fresh MessageBus per room never needs this, but
+  // one reusing a single MessageBus across rooms (changing roomKey) does.
+  clear() {
+    this.messages = [];
+    this.outbox = [];
+    if (this.storage) {
+      try { this.storage.removeItem(STORE_KEY_PREFIX + this.roomKey); } catch {}
+      try { this.storage.removeItem(OUTBOX_KEY_PREFIX + this.roomKey); } catch {}
+    }
+    this.dispatchEvent(new CustomEvent('messages', { detail: { list: this.messages } }));
+  }
 }
 
 export const createMessageBus = (opts) => new MessageBus(opts);

package/src/profile.js

@@ -0,0 +1,135 @@
+// Portable nostr identity/profiles: kind:0 (NIP-01 "set_metadata") is the
+// real nostr-native replaceable event carrying name/picture/about/nip05 —
+// publishing it here means an identity (bare pubkey today) becomes portable
+// across ANY wireweave-based app (spoint etc), not just the app that first
+// created it, since any relay-connected nostr client already knows how to
+// read kind:0. chat.js already has a read-only per-Chat-instance
+// _fetchProfile/resolveProfile cache for showing names in a chat UI; this
+// module is the write path (publish your own profile) plus a
+// relay-pool-agnostic fetch-by-pubkey a non-Chat caller can use, and real
+// NIP-05 (`name@domain`) identifier verification via the domain's
+// `/.well-known/nostr.json` per the NIP-05 spec.
+
+const KIND_METADATA = 0;
+const PROFILE_CACHE_TTL_MS = 300000;
+
+export class Profile extends EventTarget {
+  constructor({ relayPool, auth, fetchImpl = null }) {
+    super();
+    if (!relayPool || !auth) throw new Error('Profile: relayPool + auth required');
+    this.pool = relayPool;
+    this.auth = auth;
+    this.fetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+    this.cache = new Map(); // pubkey -> { profile, fetchedAt, eventCreatedAt }
+    this.subs = new Map();
+  }
+
+  // Publishes (or replaces — kind:0 is a NIP-01 replaceable event, the relay
+  // keeps only the newest per-pubkey copy) your own profile metadata.
+  // `fields` is shallow-merged onto whatever's already cached for yourself
+  // so a caller can update just one field (e.g. only `picture`) without
+  // clobbering the rest.
+  async publish(fields) {
+    if (!this.auth.isLoggedIn()) throw new Error('Profile: not logged in');
+    const existing = this.cache.get(this.auth.pubkey)?.profile || {};
+    const next = { ...existing, ...fields };
+    const signed = await this.auth.sign({
+      kind: KIND_METADATA,
+      created_at: Math.floor(Date.now() / 1000),
+      tags: [],
+      content: JSON.stringify(next)
+    });
+    this.pool.publish(signed);
+    this.cache.set(this.auth.pubkey, { profile: next, fetchedAt: Date.now(), eventCreatedAt: signed.created_at });
+    this._emit('updated', { pubkey: this.auth.pubkey, profile: next });
+    return signed;
+  }
+
+  // One-shot fetch (resolves once, EOSE-driven, with a timeout) — for a
+  // caller that just needs "the current profile for this pubkey" without
+  // wanting a standing subscription. Serves from cache if fresh
+  // (PROFILE_CACHE_TTL_MS) unless forceRefresh is set.
+  async fetchOnce(pubkey, { timeoutMs = 8000, forceRefresh = false } = {}) {
+    const cached = this.cache.get(pubkey);
+    if (cached && !forceRefresh && Date.now() - cached.fetchedAt < PROFILE_CACHE_TTL_MS) return cached.profile;
+    return new Promise((resolve) => {
+      const subId = 'profile-once-' + pubkey.slice(0, 16) + '-' + Math.random().toString(36).slice(2, 8);
+      let settled = false;
+      const timer = setTimeout(() => { if (!settled) { settled = true; this.pool.unsubscribe(subId); resolve(cached?.profile ?? null); } }, timeoutMs);
+      let best = null;
+      this.pool.subscribe(subId,
+        [{ kinds: [KIND_METADATA], authors: [pubkey] }],
+        (event) => {
+          if (best && best.created_at >= event.created_at) return;
+          try { best = { created_at: event.created_at, profile: JSON.parse(event.content) }; } catch {}
+        },
+        () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          this.pool.unsubscribe(subId);
+          if (best) {
+            this.cache.set(pubkey, { profile: best.profile, fetchedAt: Date.now(), eventCreatedAt: best.created_at });
+            this._emit('updated', { pubkey, profile: best.profile });
+          }
+          resolve(best?.profile ?? cached?.profile ?? null);
+        });
+    });
+  }
+
+  // Standing subscription — calls onUpdate(profile) every time a newer
+  // kind:0 for this pubkey arrives (profile changed live), same
+  // newest-wins dedupe chat.js's _fetchProfile already uses.
+  subscribe(pubkey, onUpdate) {
+    if (this.subs.has(pubkey)) return this.subs.get(pubkey);
+    const subId = 'profile-sub-' + pubkey.slice(0, 16);
+    this.subs.set(pubkey, subId);
+    this.pool.subscribe(subId,
+      [{ kinds: [KIND_METADATA], authors: [pubkey] }],
+      (event) => {
+        const cached = this.cache.get(pubkey);
+        if (cached && cached.eventCreatedAt >= event.created_at) return;
+        let profile;
+        try { profile = JSON.parse(event.content); } catch { return; }
+        this.cache.set(pubkey, { profile, fetchedAt: Date.now(), eventCreatedAt: event.created_at });
+        this._emit('updated', { pubkey, profile });
+        onUpdate?.(profile);
+      });
+    return subId;
+  }
+
+  unsubscribe(pubkey) {
+    const subId = this.subs.get(pubkey);
+    if (subId) { this.pool.unsubscribe(subId); this.subs.delete(pubkey); }
+  }
+
+  getCached(pubkey) { return this.cache.get(pubkey)?.profile ?? null; }
+
+  // Real NIP-05 verification: fetches https://<domain>/.well-known/nostr.json
+  // and checks that names[localpart] resolves to the expected pubkey — per
+  // spec this is the ONLY trust anchor for a nip05 identifier claimed in a
+  // profile (a profile can put any string in its nip05 field; verifying it
+  // requires this real HTTP round-trip to the claimed domain, it is not
+  // something derivable from the nostr event alone). Returns false (never
+  // throws) on any network/parse/mismatch failure — an unverifiable nip05
+  // is a real, expected outcome, not an error.
+  async verifyNip05(identifier, expectedPubkey) {
+    if (!this.fetch) return false;
+    const match = /^(?:([\w.+-]+)@)?([\w.-]+)$/.exec((identifier || '').trim());
+    if (!match) return false;
+    const localpart = match[1] || '_';
+    const domain = match[2];
+    if (!domain) return false;
+    try {
+      const res = await this.fetch('https://' + domain + '/.well-known/nostr.json?name=' + encodeURIComponent(localpart));
+      if (!res.ok) return false;
+      const body = await res.json();
+      const resolved = body?.names?.[localpart];
+      return typeof resolved === 'string' && resolved === expectedPubkey;
+    } catch { return false; }
+  }
+
+  _emit(t, d) { this.dispatchEvent(new CustomEvent(t, { detail: d })); }
+}
+
+export const createProfile = (opts) => new Profile(opts);

package/src/relay-pool.js

@@ -64,7 +64,15 @@ class RelayHealth {
     this.rank = 50;
   }
 
-  recordConnectAttempt() { this.attempts++; }
+  // Recomputes rank on every attempt, not just on a successful signal —
+  // otherwise a relay that NEVER once connects (rank frozen at the ctor's
+  // neutral 50 forever, since recordConnectLatency/recordSustainedConnection/
+  // recordEoseLatency — the only other rank-recomputing call sites — never
+  // fire for it) reads as perpetually "average" no matter how many failed
+  // attempts pile up, defeating both healthReport() ranking and
+  // _maybeRotate's rank-gap rotation trigger for the exact "never connects
+  // at all" relay auto-rotation exists to route around.
+  recordConnectAttempt() { this.attempts++; this.rank = computeRank(this); }
 
   recordConnectLatency(ms) {
     this.connectLatencyMs = ewma(this.connectLatencyMs, ms);
@@ -118,8 +126,55 @@ const fnv1a = (s) => {
 
 const safeSubId = (subId) => subId.length <= 64 ? subId : subId.slice(0, 55) + '-' + fnv1a(subId);
 
+// Shared publish budget: a real token bucket, refilled continuously at
+// refillPerSec tokens/sec up to burstCap, drained one token per publish()
+// call. This is the SINGLE choke point every module's writes go through
+// (chat, dm, bans, roles, settings, servers, data-channel signaling all
+// call pool.publish()) so one shared bucket per RelayPool instance budgets
+// abuse across all of them at once, rather than each module needing (and
+// forgetting) its own independent limiter — chat.js's own 5-per-10s limiter
+// stays as an app-level UX throttle (rate-limited event + retryAfterMs for
+// a chat input box), this is the lower-level protocol-wide backstop.
+const DEFAULT_BUDGET_BURST = 30;
+const DEFAULT_BUDGET_REFILL_PER_SEC = 3;
+
+class PublishBudget {
+  constructor({ burstCap = DEFAULT_BUDGET_BURST, refillPerSec = DEFAULT_BUDGET_REFILL_PER_SEC } = {}) {
+    this.burstCap = burstCap;
+    this.refillPerSec = refillPerSec;
+    this.tokens = burstCap;
+    this.lastRefillAt = Date.now();
+  }
+
+  _refill() {
+    const now = Date.now();
+    const elapsedSec = (now - this.lastRefillAt) / 1000;
+    if (elapsedSec <= 0) return;
+    this.tokens = Math.min(this.burstCap, this.tokens + elapsedSec * this.refillPerSec);
+    this.lastRefillAt = now;
+  }
+
+  // Returns true and consumes a token if available, else false (caller
+  // decides what "budget exceeded" means — RelayPool.publish() below
+  // queues the event as pending rather than dropping it, since a
+  // rate-limited-not-lost event still eventually goes out once the bucket
+  // refills, via the same _drainPending path a disconnected relay uses).
+  tryConsume() {
+    this._refill();
+    if (this.tokens < 1) return false;
+    this.tokens -= 1;
+    return true;
+  }
+
+  retryAfterMs() {
+    this._refill();
+    if (this.tokens >= 1) return 0;
+    return Math.ceil((1 - this.tokens) / this.refillPerSec * 1000);
+  }
+}
+
 export class RelayPool extends EventTarget {
-  constructor({ relays = DEFAULT_RELAYS, verifyEvent = null, WebSocketImpl = null, storage = null, fallbackRelays = FALLBACK_RELAYS, autoRotate = true } = {}) {
+  constructor({ relays = DEFAULT_RELAYS, verifyEvent = null, WebSocketImpl = null, storage = null, fallbackRelays = FALLBACK_RELAYS, autoRotate = true, publishBudget = {} } = {}) {
     super();
     this.urls = [...relays];
     this.relays = new Map();
@@ -141,6 +196,10 @@ export class RelayPool extends EventTarget {
     for (const url of this.urls) this.health.set(url, new RelayHealth(url));
     this._loadHealth();
     this._saveHealthTimer = null;
+    // publishBudget:false disables the budget entirely (unbounded, the old
+    // behavior) — anything else (including {}) gets a real token bucket.
+    this.budget = publishBudget === false ? null : new PublishBudget(publishBudget);
+    this._budgetDrainTimer = null;
 
     // Debug-panel integration: window.__wireweave.relayPool (or relayPool2,
     // relayPool3... for additional instances) exposes healthReport() live.
@@ -199,7 +258,13 @@ export class RelayPool extends EventTarget {
   // Swap the worst currently-active relay for the best-ranked unused
   // candidate (fallback pool, or a previously-tried relay we disconnected
   // from) when the gap is large enough to be worth the churn of a new
-  // connection. Never rotates below MIN_ACTIVE_RELAYS active URLs.
+  // connection. Never rotates below MIN_ACTIVE_RELAYS active URLs. Called
+  // from every ws.onclose (both the sustained-then-dropped branch AND the
+  // never-connected/failed-fast branch) — a relay that never manages to
+  // connect at all still needs evaluating here, since that IS the
+  // "consistently unhealthy" case rotation exists to route around, and its
+  // rank already reflects the failures via recordConnectAttempt's own
+  // computeRank call once attempts >= 2 (the sample floor enforced below).
   _maybeRotate() {
     if (!this.autoRotate || this._closed) return;
     const MIN_ACTIVE_RELAYS = 2;
@@ -254,6 +319,7 @@ export class RelayPool extends EventTarget {
     this._closed = true;
     for (const [, t] of this._reconnectTimers) clearTimeout(t);
     this._reconnectTimers.clear();
+    if (this._budgetDrainTimer) { clearTimeout(this._budgetDrainTimer); this._budgetDrainTimer = null; }
     for (const [, rec] of this._acks) { clearTimeout(rec.timer); rec.resolve(false); }
     this._acks.clear();
     for (const [, r] of this.relays) {
@@ -326,11 +392,17 @@ export class RelayPool extends EventTarget {
         relay.reconnectDelay = 1000;
         health.recordSustainedConnection();
         this._scheduleSaveHealth();
-        this._maybeRotate();
       } else {
         relay.failCount++;
         relay.reconnectDelay = Math.min(relay.reconnectDelay * 2, 30000);
       }
+      // Evaluate rotation on EVERY close, not just a sustained-then-dropped
+      // connection — a relay that never manages to connect at all (the
+      // `else` branch above) is exactly the "consistently unhealthy"
+      // relay auto-rotation exists to route around, and its rank already
+      // reflects that via computeRank's uptime/latency components once
+      // `attempts >= 2` (the sample floor _maybeRotate itself enforces).
+      this._maybeRotate();
       relay._openedAt = null;
       if (this._closed) return;
       const t = setTimeout(() => this._open(url), jitter(relay.reconnectDelay));
@@ -401,7 +473,21 @@ export class RelayPool extends EventTarget {
     this.subs.delete(subId);
   }
 
+  // Budget-gated: over-budget calls are not dropped, they're queued exactly
+  // like a disconnected-relay event (via _queuePending) and flushed by the
+  // normal _drainPending path once either a relay reconnects or, for a
+  // budget-only rejection, the next successful publish()/heal() drains the
+  // backlog opportunistically. This means a caller that publishes faster
+  // than the budget allows sees eventual delivery, not silent loss — the
+  // same "fire-and-forget with delivery confidence via publishAndWait()"
+  // contract the rest of this class already documents.
   publish(event) {
+    if (this.budget && !this.budget.tryConsume()) {
+      this._emit('rate-limited', { retryAfterMs: this.budget.retryAfterMs() });
+      this._queuePending(event, new Set());
+      this._scheduleBudgetDrain();
+      return false;
+    }
     let sent = false;
     let anyDisconnected = false;
     const sentTo = new Set();
@@ -419,6 +505,38 @@ export class RelayPool extends EventTarget {
     return sent;
   }
 
+  // Live budget introspection for a debug panel / caller backoff decision.
+  budgetStatus() {
+    if (!this.budget) return { enabled: false };
+    this.budget._refill();
+    return { enabled: true, tokens: this.budget.tokens, burstCap: this.budget.burstCap, refillPerSec: this.budget.refillPerSec, retryAfterMs: this.budget.retryAfterMs() };
+  }
+
+  // A budget-rejected publish() queues into `this.pending` exactly like a
+  // disconnected-relay event, but `this.pending` otherwise only drains on
+  // ws.onopen (a relay reconnecting) — if every relay stays connected the
+  // whole time, a budget-queued event needs its OWN retry path once tokens
+  // refill, or it would sit queued until PENDING_TTL_MS expiry and get
+  // silently dropped despite the relay connection being perfectly healthy.
+  // One timer, scheduled only while budget-queued events are outstanding
+  // (never a standing interval), retries a real drain against every
+  // currently-open relay once the bucket should have refilled a token.
+  _scheduleBudgetDrain() {
+    if (this._budgetDrainTimer || !this.budget || this._closed) return;
+    const delay = Math.max(50, this.budget.retryAfterMs());
+    this._budgetDrainTimer = setTimeout(() => {
+      this._budgetDrainTimer = null;
+      if (this._closed) return;
+      let anyOpen = false;
+      for (const [url, relay] of this.relays) {
+        if (relay.ws?.readyState === 1) { anyOpen = true; this._drainPending(url, relay.ws); }
+      }
+      // Still budget-limited or nothing connected yet — keep retrying as
+      // long as there's a real backlog, so it isn't stranded until TTL.
+      if (this.pending.length > 0 && (anyOpen || this.budget.retryAfterMs() > 0)) this._scheduleBudgetDrain();
+    }, delay);
+  }
+
   // Tracks delivery per relay URL, not just "sent to at least one" — a relay
   // mid-reconnect during a partial outage otherwise never gets the event.
   _queuePending(event, sentTo) {