gupt-sdk 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# gupt-sdk
+
+Node.js SDK for running end-to-end encrypted GUPT bots over user-selected relays.
+
+The SDK currently supports one-to-one text messages. Use a dedicated bot identity; never reuse a
+personal GUPT key.
+
+```js
+import { GuptBot } from "gupt-sdk";
+
+const bot = new GuptBot({
+  secretHex: process.env.GUPT_KEY,
+  relays: ["wss://relay-a.example", "wss://relay-b.example"],
+});
+
+bot.onMessage(async (ctx) => {
+  if (ctx.text.startsWith("/echo ")) await ctx.reply(ctx.text.slice(6));
+});
+
+bot.onError((error) => console.error(error.message));
+await bot.start();
+```
+
+At least two distinct `wss://` bootstrap relays are required. The default Originless server is
+`https://originless.gupt.app`; pass `originless` as a URL or URL array to override it.
+
+Inbound messages teach the bot both the ingress relay and the sender relay hint carried in the
+signed `p` tag. Learned hints are bounded and obvious local/private addresses are rejected. Replies
+try the ingress relay first, then the peer's learned relays and the configured bootstrap relays.
+
+By default, handlers accept all human senders with a one-second per-sender cooldown. Supply an
+`allowlist`, call `bot.allow(pubkey)`, or tune `senderCooldownMs` as needed. SDK-generated messages
+carry `bot: true` and are ignored by other SDK bots unless `acceptBotMessages` is enabled.
+
+Call `bot.stop()` during shutdown to close relay connections and cancel queued sends.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "gupt-sdk",
+  "version": "0.1.0",
+  "description": "Node.js SDK for building end-to-end encrypted GUPT bots",
+  "homepage": "https://github.com/besoeasy/gupt/tree/main/sdk#readme",
+  "bugs": "https://github.com/besoeasy/gupt/issues",
+  "license": "CC-BY-NC-4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/besoeasy/gupt.git",
+    "directory": "sdk"
+  },
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./ingestion": "./src/ingestion.js",
+    "./queue": "./src/queue.js",
+    "./relay-book": "./src/relayBook.js",
+    "./wire": "./src/wire.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
+    "@noble/secp256k1": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,301 @@
+import { IngestionPipeline, RECENCY_WINDOW_MS } from "./ingestion.js";
+import { RelayPool } from "./pool.js";
+import { SendQueue } from "./queue.js";
+import { normalizeRelayUrl, RelayBook } from "./relayBook.js";
+import {
+  buildDirectMessageEvent,
+  getPublicKey,
+  normalizePubkey,
+  normalizeSecretHex,
+} from "./wire.js";
+
+export const DEFAULT_ORIGINLESS_SERVERS = Object.freeze(["https://originless.gupt.app"]);
+export const MAX_TEXT_LENGTH = 8_000;
+export const DEFAULT_SENDER_COOLDOWN_MS = 1_000;
+export const DEFAULT_REPLY_COOLDOWN_MS = 1_000;
+export const DEFAULT_MAX_REPLIES_PER_MINUTE = 20;
+export const DEFAULT_MAX_HANDLER_BACKLOG = 100;
+
+function normalizeOriginlessUrl(value, allowPrivate) {
+  try {
+    const url = new URL(String(value || "").trim());
+    if (url.username || url.password || url.search || url.hash) return null;
+    if (url.protocol !== "https:" && !(allowPrivate && url.protocol === "http:")) return null;
+    url.pathname = url.pathname.replace(/\/upload\/?$/i, "").replace(/\/+$/, "");
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeAllowlist(values) {
+  if (values == null) return null;
+  if (!Array.isArray(values) && !(values instanceof Set)) {
+    throw new TypeError("allowlist must be an array or Set of public keys");
+  }
+  return new Set([...values].map(normalizePubkey));
+}
+
+export class GuptBot {
+  constructor({
+    secretHex,
+    relays,
+    originless = DEFAULT_ORIGINLESS_SERVERS,
+    allowlist = null,
+    senderCooldownMs = DEFAULT_SENDER_COOLDOWN_MS,
+    replyCooldownMs = DEFAULT_REPLY_COOLDOWN_MS,
+    maxRepliesPerMinute = DEFAULT_MAX_REPLIES_PER_MINUTE,
+    maxHandlerBacklog = DEFAULT_MAX_HANDLER_BACKLOG,
+    acceptBotMessages = false,
+    allowPrivateRelays = false,
+    WebSocketImpl = globalThis.WebSocket,
+    onDrop = null,
+    logger = console,
+    poolOptions = {},
+    queueOptions = {},
+  } = {}) {
+    this.secretHex = normalizeSecretHex(secretHex);
+    this.pubkey = getPublicKey(this.secretHex);
+    this.allowPrivateRelays = Boolean(allowPrivateRelays);
+
+    if (!Array.isArray(relays)) throw new TypeError("relays must be an array");
+    const normalizedRelays = relays.map((relay) => {
+      const normalized = normalizeRelayUrl(relay, {
+        allowInsecure: this.allowPrivateRelays,
+        allowPrivate: this.allowPrivateRelays,
+      });
+      if (!normalized) throw new TypeError(`Invalid relay URL: ${String(relay)}`);
+      return normalized;
+    });
+    this.relays = [...new Set(normalizedRelays)];
+    if (this.relays.length < 2) throw new TypeError("At least 2 distinct relays are required");
+
+    const originlessValues = Array.isArray(originless) ? originless : [originless];
+    this.originlessServers = [
+      ...new Set(
+        originlessValues.map((server) => {
+          const normalized = normalizeOriginlessUrl(server, this.allowPrivateRelays);
+          if (!normalized) throw new TypeError(`Invalid Originless server URL: ${String(server)}`);
+          return normalized;
+        }),
+      ),
+    ];
+    if (!this.originlessServers.length) {
+      throw new TypeError("At least 1 Originless server is required");
+    }
+
+    this.allowlist = normalizeAllowlist(allowlist);
+    this.senderCooldownMs = Math.max(0, Number(senderCooldownMs) || 0);
+    this.replyCooldownMs = Math.max(0, Number(replyCooldownMs) || 0);
+    this.maxRepliesPerMinute = Math.max(1, Number(maxRepliesPerMinute) || 1);
+    this.maxHandlerBacklog = Math.max(1, Number(maxHandlerBacklog) || 1);
+    this.acceptBotMessages = Boolean(acceptBotMessages);
+    this.logger = logger;
+    this.status = "idle";
+    this.handlers = new Set();
+    this.errorHandlers = new Set();
+    this.handlerChains = new Map();
+    this.handlerBacklogs = new Map();
+    this.lastHandledAt = new Map();
+    this.replyWindows = new Map();
+
+    this.relayBook = new RelayBook(this.relays, { allowPrivateRelays: this.allowPrivateRelays });
+    this.ingestion = new IngestionPipeline({
+      secretHex: this.secretHex,
+      pubkey: this.pubkey,
+      onDrop,
+    });
+    this.queue = new SendQueue(queueOptions);
+    this.pool = new RelayPool({
+      ...poolOptions,
+      WebSocketImpl,
+      allowPrivateRelays: this.allowPrivateRelays,
+      onEvent: (event, relayUrl) => this.receiveEvent(event, relayUrl),
+      onRelayError: (error, relayUrl) => this.emitError(error, { relayUrl }),
+    });
+  }
+
+  onMessage(handler) {
+    if (typeof handler !== "function") throw new TypeError("Message handler must be a function");
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  onError(handler) {
+    if (typeof handler !== "function") throw new TypeError("Error handler must be a function");
+    this.errorHandlers.add(handler);
+    return () => this.errorHandlers.delete(handler);
+  }
+
+  allow(pubkey) {
+    if (!this.allowlist) this.allowlist = new Set();
+    this.allowlist.add(normalizePubkey(pubkey));
+    return this;
+  }
+
+  disallow(pubkey) {
+    this.allowlist?.delete(normalizePubkey(pubkey));
+    return this;
+  }
+
+  async start() {
+    if (this.status === "running") return this;
+    if (this.status !== "idle") throw new Error("A stopped GuptBot instance cannot be restarted");
+    this.status = "starting";
+    try {
+      await this.pool.start(this.relays, () => ({
+        kinds: [4],
+        "#p": [this.pubkey],
+        since: Math.floor((Date.now() - RECENCY_WINDOW_MS) / 1000),
+        limit: 200,
+      }));
+      this.status = "running";
+      return this;
+    } catch (error) {
+      this.status = "idle";
+      throw error;
+    }
+  }
+
+  stop() {
+    if (this.status === "stopped") return;
+    this.status = "stopped";
+    this.pool.stop();
+    this.queue.stop();
+    this.ingestion.close();
+    this.handlerChains.clear();
+    this.handlerBacklogs.clear();
+  }
+
+  receiveEvent(event, relayUrl) {
+    const message = this.ingestion.ingest(event, { relayUrl });
+    if (!message) return;
+
+    const discovered = this.relayBook.learn(
+      message.senderPubkey,
+      { sourceRelay: relayUrl, hintedRelay: message.relayHint },
+      message.receivedAt,
+    );
+    for (const relay of discovered) {
+      this.pool.addRelay(relay).catch((error) => this.emitError(error, { relayUrl: relay }));
+    }
+
+    const { payload, senderPubkey } = message;
+    if (payload.type !== "text" || typeof payload.text !== "string") return;
+    if (!payload.text.trim() || payload.text.length > MAX_TEXT_LENGTH) return;
+    if (payload.bot === true && !this.acceptBotMessages) return;
+    if (this.allowlist && !this.allowlist.has(senderPubkey)) return;
+
+    const lastHandledAt = this.lastHandledAt.get(senderPubkey) || 0;
+    if (message.receivedAt - lastHandledAt < this.senderCooldownMs) return;
+    this.lastHandledAt.set(senderPubkey, message.receivedAt);
+
+    const backlog = this.handlerBacklogs.get(senderPubkey) || 0;
+    if (backlog >= this.maxHandlerBacklog) {
+      this.emitError(new Error("Handler backlog limit reached"), {
+        eventId: event.id,
+        senderPubkey,
+      });
+      return;
+    }
+
+    this.handlerBacklogs.set(senderPubkey, backlog + 1);
+    const previous = this.handlerChains.get(senderPubkey) || Promise.resolve();
+    const next = previous
+      .catch(() => {})
+      .then(() => this.dispatchMessage(message))
+      .catch((error) =>
+        this.emitError(error, { eventId: message.event.id, senderPubkey: message.senderPubkey }),
+      )
+      .finally(() => {
+        const remaining = Math.max(0, (this.handlerBacklogs.get(senderPubkey) || 1) - 1);
+        if (remaining) this.handlerBacklogs.set(senderPubkey, remaining);
+        else {
+          this.handlerBacklogs.delete(senderPubkey);
+          if (this.handlerChains.get(senderPubkey) === next)
+            this.handlerChains.delete(senderPubkey);
+        }
+      });
+    this.handlerChains.set(senderPubkey, next);
+  }
+
+  async dispatchMessage(message) {
+    const context = Object.freeze({
+      id: message.event.id,
+      senderPubkey: message.senderPubkey,
+      text: message.payload.text,
+      payload: Object.freeze({ ...message.payload }),
+      relayUrl: message.relayUrl,
+      receivedAt: message.receivedAt,
+      reply: (text) => this.reply(message.senderPubkey, text, message.relayUrl),
+    });
+    for (const handler of this.handlers) await handler(context);
+  }
+
+  async reply(peerPubkey, text, ingressRelay = null) {
+    if (this.status !== "running") throw new Error("Bot is not running");
+    const peer = normalizePubkey(peerPubkey);
+    const replyText = String(text || "").trim();
+    if (!replyText) throw new TypeError("Reply text is required");
+    if (replyText.length > MAX_TEXT_LENGTH) {
+      throw new TypeError(`Reply text cannot exceed ${MAX_TEXT_LENGTH} characters`);
+    }
+    this.reserveReply(peer);
+
+    const event = buildDirectMessageEvent({
+      secretHex: this.secretHex,
+      recipientPubkey: peer,
+      payload: {
+        type: "text",
+        text: replyText,
+        ts: Date.now(),
+        bot: true,
+      },
+    });
+    const targets = this.relayBook.replyRelays(peer, ingressRelay);
+    return this.queue.enqueue({
+      id: event.id,
+      lane: peer,
+      fn: () => this.pool.publish(targets, event),
+    });
+  }
+
+  reserveReply(peer, now = Date.now()) {
+    const cutoff = now - 60_000;
+    const window = (this.replyWindows.get(peer) || []).filter((timestamp) => timestamp > cutoff);
+    const previous = window.at(-1) || 0;
+    if (now - previous < this.replyCooldownMs) {
+      throw new Error("Reply cooldown is active for this sender");
+    }
+    if (window.length >= this.maxRepliesPerMinute) {
+      throw new Error("Per-sender reply rate limit reached");
+    }
+    window.push(now);
+    this.replyWindows.set(peer, window);
+  }
+
+  emitError(error, context = {}) {
+    if (this.errorHandlers.size) {
+      for (const handler of this.errorHandlers) handler(error, context);
+      return;
+    }
+    this.logger?.error?.("[gupt-bot]", error?.message || String(error), context);
+  }
+
+  snapshot() {
+    return {
+      status: this.status,
+      pubkey: this.pubkey,
+      relays: [...this.relays],
+      originlessServers: [...this.originlessServers],
+      relayBook: this.relayBook.snapshot(),
+      relayPool: this.pool.snapshot(),
+      sendQueue: this.queue.snapshot(),
+    };
+  }
+}
+
+export * from "./ingestion.js";
+export * from "./queue.js";
+export * from "./relayBook.js";
+export * from "./wire.js";

package/src/ingestion.js

@@ -0,0 +1,127 @@
+import {
+  assertDirectMessageEvent,
+  decryptDirectMessage,
+  getSenderRelayHint,
+  isExpiredEvent,
+  verifyEventSignature,
+} from "./wire.js";
+
+export const RECENCY_WINDOW_MS = 100_000;
+export const FUTURE_SKEW_MS = 30_000;
+export const SEEN_TTL_MS = 5 * 60_000;
+export const MAX_SEEN_EVENTS = 10_000;
+
+export class SeenEventTracker {
+  constructor({
+    ttlMs = SEEN_TTL_MS,
+    maxEntries = MAX_SEEN_EVENTS,
+    sweepIntervalMs = 60_000,
+    clock = Date.now,
+  } = {}) {
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+    this.clock = clock;
+    this.entries = new Map();
+    this.sweepTimer = setInterval(() => this.sweep(), sweepIntervalMs);
+    this.sweepTimer.unref?.();
+  }
+
+  has(id, now = this.clock()) {
+    const expiresAt = this.entries.get(id);
+    if (expiresAt == null) return false;
+    if (expiresAt <= now) {
+      this.entries.delete(id);
+      return false;
+    }
+    return true;
+  }
+
+  add(id, now = this.clock()) {
+    this.sweep(now);
+    this.entries.delete(id);
+    this.entries.set(id, now + this.ttlMs);
+    while (this.entries.size > this.maxEntries) {
+      this.entries.delete(this.entries.keys().next().value);
+    }
+  }
+
+  sweep(now = this.clock()) {
+    for (const [id, expiresAt] of this.entries) {
+      if (expiresAt <= now) this.entries.delete(id);
+    }
+  }
+
+  close() {
+    clearInterval(this.sweepTimer);
+    this.entries.clear();
+  }
+}
+
+export class IngestionPipeline {
+  constructor({
+    secretHex,
+    pubkey,
+    recencyWindowMs = RECENCY_WINDOW_MS,
+    futureSkewMs = FUTURE_SKEW_MS,
+    seenTracker = new SeenEventTracker(),
+    clock = Date.now,
+    onDrop = null,
+  }) {
+    this.secretHex = secretHex;
+    this.pubkey = pubkey;
+    this.recencyWindowMs = recencyWindowMs;
+    this.futureSkewMs = futureSkewMs;
+    this.seenTracker = seenTracker;
+    this.clock = clock;
+    this.onDrop = onDrop;
+  }
+
+  drop(reason, event, relayUrl) {
+    this.onDrop?.({ reason, eventId: event?.id || null, relayUrl });
+    return null;
+  }
+
+  ingest(event, { relayUrl = null, now = this.clock() } = {}) {
+    try {
+      assertDirectMessageEvent(event, this.pubkey);
+    } catch {
+      return this.drop("invalid-event", event, relayUrl);
+    }
+
+    const createdAt = event.created_at * 1000;
+    if (createdAt < now - this.recencyWindowMs) {
+      return this.drop("too-old", event, relayUrl);
+    }
+    if (createdAt > now + this.futureSkewMs) {
+      return this.drop("from-future", event, relayUrl);
+    }
+    if (isExpiredEvent(event, now)) {
+      return this.drop("expired", event, relayUrl);
+    }
+    if (this.seenTracker.has(event.id, now)) {
+      return this.drop("duplicate", event, relayUrl);
+    }
+    if (!verifyEventSignature(event)) {
+      return this.drop("invalid-signature", event, relayUrl);
+    }
+
+    this.seenTracker.add(event.id, now);
+
+    try {
+      return {
+        event,
+        payload: decryptDirectMessage(event, this.secretHex, this.pubkey),
+        senderPubkey: event.pubkey,
+        relayHint: getSenderRelayHint(event, this.pubkey),
+        relayUrl,
+        receivedAt: now,
+      };
+    } catch {
+      return this.drop("invalid-ciphertext", event, relayUrl);
+    }
+  }
+
+  close() {
+    this.seenTracker.close();
+  }
+}

package/src/pool.js

@@ -0,0 +1,278 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+import { isPrivateRelayHostname } from "./relayBook.js";
+
+export const CONNECT_TIMEOUT_MS = 5_000;
+export const PUBLISH_TIMEOUT_MS = 5_000;
+export const MAX_RECONNECT_DELAY_MS = 30_000;
+export const MAX_RELAY_FRAME_BYTES = 256 * 1024;
+
+async function assertPublicRelayAddress(relay, allowPrivateRelays) {
+  if (allowPrivateRelays) return;
+  const { hostname } = new URL(relay);
+  if (isPrivateRelayHostname(hostname)) throw new Error(`Private relay address rejected: ${relay}`);
+  if (isIP(hostname.replace(/^\[|\]$/g, ""))) return;
+  const addresses = await lookup(hostname, { all: true, verbatim: true });
+  if (!addresses.length || addresses.some(({ address }) => isPrivateRelayHostname(address))) {
+    throw new Error(`Relay resolved to a private address: ${relay}`);
+  }
+}
+
+function messageText(data) {
+  if (typeof data === "string") return data;
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
+  if (ArrayBuffer.isView(data)) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8");
+  }
+  return "";
+}
+
+export class RelayPool {
+  constructor({
+    WebSocketImpl = globalThis.WebSocket,
+    allowPrivateRelays = false,
+    connectTimeoutMs = CONNECT_TIMEOUT_MS,
+    publishTimeoutMs = PUBLISH_TIMEOUT_MS,
+    maxFrameBytes = MAX_RELAY_FRAME_BYTES,
+    onEvent = null,
+    onRelayError = null,
+  } = {}) {
+    if (!WebSocketImpl) throw new Error("Node.js 22.12 or newer is required for WebSocket support");
+    this.WebSocketImpl = WebSocketImpl;
+    this.allowPrivateRelays = allowPrivateRelays;
+    this.connectTimeoutMs = connectTimeoutMs;
+    this.publishTimeoutMs = publishTimeoutMs;
+    this.maxFrameBytes = maxFrameBytes;
+    this.onEvent = onEvent;
+    this.onRelayError = onRelayError;
+    this.states = new Map();
+    this.desired = new Set();
+    this.pendingPublishes = new Map();
+    this.filterFactory = null;
+    this.running = false;
+  }
+
+  async start(relays, filterFactory) {
+    if (this.running) return;
+    this.running = true;
+    this.filterFactory =
+      typeof filterFactory === "function" ? filterFactory : () => ({ ...(filterFactory || {}) });
+    const results = await Promise.allSettled(relays.map((relay) => this.addRelay(relay)));
+    if (!results.some((result) => result.status === "fulfilled")) {
+      this.stop();
+      throw new Error("Could not connect to any configured relay");
+    }
+  }
+
+  async addRelay(relay) {
+    this.desired.add(relay);
+    try {
+      return await this.connect(relay);
+    } catch (error) {
+      if (this.running) this.scheduleReconnect(relay);
+      throw error;
+    }
+  }
+
+  stateFor(relay) {
+    if (!this.states.has(relay)) {
+      this.states.set(relay, {
+        socket: null,
+        connectPromise: null,
+        reconnectAttempts: 0,
+        reconnectTimer: null,
+        subId: null,
+      });
+    }
+    return this.states.get(relay);
+  }
+
+  async connect(relay) {
+    const state = this.stateFor(relay);
+    if (state.socket?.readyState === this.WebSocketImpl.OPEN) return state.socket;
+    if (state.connectPromise) return state.connectPromise;
+
+    state.connectPromise = (async () => {
+      await assertPublicRelayAddress(relay, this.allowPrivateRelays);
+      return new Promise((resolve, reject) => {
+        const socket = new this.WebSocketImpl(relay);
+        state.socket = socket;
+        let settled = false;
+        const timeout = setTimeout(() => {
+          if (settled) return;
+          settled = true;
+          socket.close();
+          reject(new Error(`Timed out connecting to ${relay}`));
+        }, this.connectTimeoutMs);
+
+        socket.addEventListener("open", () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          state.reconnectAttempts = 0;
+          state.subId = `gupt_bot_${crypto.randomUUID().replaceAll("-", "")}`;
+          if (this.filterFactory) {
+            socket.send(JSON.stringify(["REQ", state.subId, this.filterFactory(relay)]));
+          }
+          resolve(socket);
+        });
+
+        socket.addEventListener("message", (message) => this.handleMessage(relay, state, message));
+
+        socket.addEventListener("error", () => {
+          if (!settled) {
+            settled = true;
+            clearTimeout(timeout);
+            socket.close();
+            reject(new Error(`Failed to connect to ${relay}`));
+          }
+        });
+
+        socket.addEventListener("close", () => {
+          clearTimeout(timeout);
+          if (!settled) {
+            settled = true;
+            reject(new Error(`Connection closed before opening: ${relay}`));
+          }
+          if (state.socket === socket) {
+            state.socket = null;
+            state.subId = null;
+          }
+          this.rejectPendingForRelay(relay, new Error(`Relay connection closed: ${relay}`));
+          if (this.running && this.desired.has(relay)) this.scheduleReconnect(relay);
+        });
+      });
+    })();
+
+    try {
+      return await state.connectPromise;
+    } finally {
+      state.connectPromise = null;
+    }
+  }
+
+  handleMessage(relay, state, message) {
+    const text = messageText(message.data);
+    if (!text || Buffer.byteLength(text, "utf8") > this.maxFrameBytes) return;
+
+    let frame;
+    try {
+      frame = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (!Array.isArray(frame)) return;
+
+    if (frame[0] === "EVENT" && frame[1] === state.subId && frame[2]) {
+      this.onEvent?.(frame[2], relay);
+      return;
+    }
+    if (frame[0] === "OK" && typeof frame[1] === "string") {
+      const key = `${relay}:${frame[1]}`;
+      const pending = this.pendingPublishes.get(key);
+      if (!pending) return;
+      this.pendingPublishes.delete(key);
+      clearTimeout(pending.timer);
+      if (frame[2]) pending.resolve({ relay, id: frame[1] });
+      else pending.reject(new Error(`Relay rejected event: ${String(frame[3] || "rejected")}`));
+      return;
+    }
+    if (frame[0] === "CLOSED" && frame[1] === state.subId) {
+      this.onRelayError?.(
+        new Error(`Relay closed subscription: ${String(frame[2] || relay)}`),
+        relay,
+      );
+    }
+  }
+
+  scheduleReconnect(relay) {
+    const state = this.stateFor(relay);
+    if (state.reconnectTimer || state.connectPromise) return;
+    state.reconnectAttempts++;
+    const ceiling = Math.min(1_000 * 2 ** (state.reconnectAttempts - 1), MAX_RECONNECT_DELAY_MS);
+    const delay = Math.floor(ceiling / 2 + Math.random() * (ceiling / 2));
+    state.reconnectTimer = setTimeout(() => {
+      state.reconnectTimer = null;
+      this.connect(relay).catch((error) => {
+        this.onRelayError?.(error, relay);
+        this.scheduleReconnect(relay);
+      });
+    }, delay);
+  }
+
+  publish(relays, event, { timeoutMs = this.publishTimeoutMs } = {}) {
+    const targets = [...new Set(relays)].filter(Boolean);
+    if (!targets.length) return Promise.reject(new Error("No relay available for reply"));
+    return Promise.any(targets.map((relay) => this.publishOne(relay, event, timeoutMs))).catch(
+      (error) => {
+        const reasons = error?.errors?.map((entry) => entry.message).filter(Boolean) || [];
+        throw new Error(reasons.length ? reasons.join(" | ") : "All relays rejected the event");
+      },
+    );
+  }
+
+  async publishOne(relay, event, timeoutMs) {
+    const socket = await this.connect(relay);
+    return new Promise((resolve, reject) => {
+      const key = `${relay}:${event.id}`;
+      if (this.pendingPublishes.has(key)) {
+        reject(new Error(`Event ${event.id} is already pending on ${relay}`));
+        return;
+      }
+      const timer = setTimeout(() => {
+        this.pendingPublishes.delete(key);
+        reject(new Error(`Timed out publishing to ${relay}`));
+      }, timeoutMs);
+      this.pendingPublishes.set(key, { resolve, reject, timer });
+      try {
+        socket.send(JSON.stringify(["EVENT", event]));
+      } catch (error) {
+        clearTimeout(timer);
+        this.pendingPublishes.delete(key);
+        reject(error);
+      }
+    });
+  }
+
+  rejectPendingForRelay(relay, error) {
+    for (const [key, pending] of this.pendingPublishes) {
+      if (!key.startsWith(`${relay}:`)) continue;
+      clearTimeout(pending.timer);
+      pending.reject(error);
+      this.pendingPublishes.delete(key);
+    }
+  }
+
+  stop() {
+    this.running = false;
+    for (const state of this.states.values()) {
+      clearTimeout(state.reconnectTimer);
+      state.reconnectTimer = null;
+      state.socket?.close();
+      state.socket = null;
+    }
+    for (const pending of this.pendingPublishes.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Relay pool stopped"));
+    }
+    this.pendingPublishes.clear();
+    this.desired.clear();
+  }
+
+  snapshot() {
+    return {
+      running: this.running,
+      relays: Object.fromEntries(
+        [...this.states].map(([relay, state]) => [
+          relay,
+          {
+            desired: this.desired.has(relay),
+            connected: state.socket?.readyState === this.WebSocketImpl.OPEN,
+            reconnectAttempts: state.reconnectAttempts,
+          },
+        ]),
+      ),
+    };
+  }
+}

package/src/queue.js

@@ -0,0 +1,174 @@
+export const BASE_DELAY_MS = 1_000;
+export const MAX_DELAY_MS = 3 * 60_000;
+export const MAX_ATTEMPTS = 8;
+export const GLOBAL_THROTTLE_MS = 1_200;
+export const MAX_PENDING_SENDS = 1_000;
+
+export class PermanentSendError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "PermanentSendError";
+  }
+}
+
+export class SendQueue {
+  constructor({
+    baseDelayMs = BASE_DELAY_MS,
+    maxDelayMs = MAX_DELAY_MS,
+    maxAttempts = MAX_ATTEMPTS,
+    throttleMs = GLOBAL_THROTTLE_MS,
+    maxPending = MAX_PENDING_SENDS,
+    clock = Date.now,
+  } = {}) {
+    this.baseDelayMs = Math.max(0, Number(baseDelayMs) || 0);
+    this.maxDelayMs = Math.max(this.baseDelayMs, Number(maxDelayMs) || 0);
+    this.maxAttempts = Math.max(1, Math.floor(Number(maxAttempts) || 1));
+    this.throttleMs = Math.max(0, Number(throttleMs) || 0);
+    this.maxPending = Math.max(1, Math.floor(Number(maxPending) || 1));
+    this.clock = clock;
+    this.lastStartedAt = 0;
+    this.pendingCount = 0;
+    this.lanes = new Map();
+    this.ids = new Set();
+    this.waiters = new Set();
+    this.dispatchChain = Promise.resolve();
+    this.stopped = false;
+  }
+
+  enqueue({ id, lane = "__default__", fn }) {
+    const taskId = String(id || "").trim();
+    const laneId = String(lane || "__default__");
+    if (this.stopped) return Promise.reject(new Error("Send queue is stopped"));
+    if (!taskId) return Promise.reject(new TypeError("Send task id is required"));
+    if (typeof fn !== "function") return Promise.reject(new TypeError("Send task fn is required"));
+    if (this.ids.has(taskId)) return Promise.reject(new Error(`Duplicate send task: ${taskId}`));
+    if (this.pendingCount >= this.maxPending)
+      return Promise.reject(new Error("Send queue is full"));
+
+    let resolveTask;
+    let rejectTask;
+    const result = new Promise((resolve, reject) => {
+      resolveTask = resolve;
+      rejectTask = reject;
+    });
+    const task = {
+      id: taskId,
+      fn,
+      attempts: 0,
+      resolve: resolveTask,
+      reject: rejectTask,
+    };
+
+    if (!this.lanes.has(laneId)) this.lanes.set(laneId, { running: false, tasks: [] });
+    this.lanes.get(laneId).tasks.push(task);
+    this.ids.add(taskId);
+    this.pendingCount++;
+    void this.drainLane(laneId);
+    return result;
+  }
+
+  retryDelay(attempts) {
+    return Math.min(this.baseDelayMs * 2 ** Math.max(0, attempts - 1), this.maxDelayMs);
+  }
+
+  acquireThrottle() {
+    const turn = this.dispatchChain.then(async () => {
+      const waitMs = Math.max(0, this.lastStartedAt + this.throttleMs - this.clock());
+      if (waitMs) await this.wait(waitMs);
+      if (this.stopped) throw new Error("Send queue is stopped");
+      this.lastStartedAt = this.clock();
+    });
+    this.dispatchChain = turn.catch(() => {});
+    return turn;
+  }
+
+  wait(delayMs) {
+    return new Promise((resolve) => {
+      const waiter = {
+        timer: setTimeout(() => {
+          this.waiters.delete(waiter);
+          resolve();
+        }, delayMs),
+        resolve,
+      };
+      this.waiters.add(waiter);
+    });
+  }
+
+  async drainLane(laneId) {
+    const lane = this.lanes.get(laneId);
+    if (!lane || lane.running) return;
+    lane.running = true;
+
+    try {
+      while (lane.tasks.length) {
+        const task = lane.tasks[0];
+        let completed = false;
+
+        while (!completed && task.attempts < this.maxAttempts) {
+          try {
+            await this.acquireThrottle();
+            task.attempts++;
+            const value = await task.fn({ attempt: task.attempts });
+            this.finishTask(lane, task);
+            task.resolve(value);
+            completed = true;
+          } catch (error) {
+            const final =
+              this.stopped ||
+              error instanceof PermanentSendError ||
+              task.attempts >= this.maxAttempts;
+            if (final) {
+              this.finishTask(lane, task);
+              task.reject(error);
+              completed = true;
+            } else {
+              await this.wait(this.retryDelay(task.attempts));
+            }
+          }
+        }
+      }
+    } finally {
+      lane.running = false;
+      if (!lane.tasks.length) this.lanes.delete(laneId);
+    }
+  }
+
+  finishTask(lane, task) {
+    if (lane.tasks[0] === task) lane.tasks.shift();
+    else lane.tasks.splice(lane.tasks.indexOf(task), 1);
+    this.ids.delete(task.id);
+    this.pendingCount = Math.max(0, this.pendingCount - 1);
+  }
+
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    for (const waiter of this.waiters) {
+      clearTimeout(waiter.timer);
+      waiter.resolve();
+    }
+    this.waiters.clear();
+
+    for (const lane of this.lanes.values()) {
+      for (const task of lane.tasks) task.reject(new Error("Send queue is stopped"));
+      lane.tasks.length = 0;
+    }
+    this.lanes.clear();
+    this.ids.clear();
+    this.pendingCount = 0;
+  }
+
+  snapshot() {
+    return {
+      stopped: this.stopped,
+      pendingCount: this.pendingCount,
+      lanes: Object.fromEntries(
+        [...this.lanes].map(([laneId, lane]) => [
+          laneId,
+          lane.tasks.map((task) => ({ id: task.id, attempts: task.attempts })),
+        ]),
+      ),
+    };
+  }
+}

package/src/relayBook.js

@@ -0,0 +1,174 @@
+import { isIP } from "node:net";
+
+import { normalizePubkey } from "./wire.js";
+
+export const MAX_LEARNED_RELAYS = 50;
+export const MAX_PEER_RELAYS = 10;
+export const MAX_REPLY_RELAYS = 5;
+
+function isPrivateIpv4(hostname) {
+  const parts = hostname.split(".").map(Number);
+  if (
+    parts.length !== 4 ||
+    parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return false;
+  }
+  const [a, b] = parts;
+  return (
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 198 && (b === 18 || b === 19)) ||
+    a >= 224
+  );
+}
+
+function isPrivateIpv6(hostname) {
+  const normalized = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  const mappedIpv4 = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+  return (
+    normalized === "::" ||
+    normalized === "::1" ||
+    (mappedIpv4 ? isPrivateIpv4(mappedIpv4) : false) ||
+    normalized.startsWith("fc") ||
+    normalized.startsWith("fd") ||
+    /^fe[89ab]/.test(normalized)
+  );
+}
+
+export function isPrivateRelayHostname(hostname) {
+  const normalized = String(hostname || "")
+    .replace(/^\[|\]$/g, "")
+    .toLowerCase();
+  if (
+    normalized === "localhost" ||
+    normalized.endsWith(".localhost") ||
+    normalized.endsWith(".local")
+  ) {
+    return true;
+  }
+  const family = isIP(normalized);
+  if (family === 4) return isPrivateIpv4(normalized);
+  if (family === 6) return isPrivateIpv6(normalized);
+  return false;
+}
+
+export function normalizeRelayUrl(value, { allowInsecure = false, allowPrivate = false } = {}) {
+  try {
+    const url = new URL(String(value || "").trim());
+    if (url.username || url.password || url.search || url.hash) return null;
+    if (url.protocol !== "wss:" && !(allowInsecure && url.protocol === "ws:")) return null;
+    if (!allowPrivate && isPrivateRelayHostname(url.hostname)) return null;
+    url.pathname = url.pathname.replace(/\/+$/, "") || "/";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+export class RelayBook {
+  constructor(
+    bootstrapRelays,
+    {
+      maxLearnedRelays = MAX_LEARNED_RELAYS,
+      maxPeerRelays = MAX_PEER_RELAYS,
+      maxReplyRelays = MAX_REPLY_RELAYS,
+      allowPrivateRelays = false,
+      clock = Date.now,
+    } = {},
+  ) {
+    this.allowPrivateRelays = allowPrivateRelays;
+    this.clock = clock;
+    this.maxLearnedRelays = maxLearnedRelays;
+    this.maxPeerRelays = maxPeerRelays;
+    this.maxReplyRelays = maxReplyRelays;
+    this.bootstrapRelays = [...new Set(bootstrapRelays)];
+    this.bootstrapSet = new Set(this.bootstrapRelays);
+    this.peers = new Map();
+    this.learned = new Map();
+  }
+
+  learn(peerPubkey, { sourceRelay = null, hintedRelay = null } = {}, now = this.clock()) {
+    const peer = normalizePubkey(peerPubkey);
+    const source = normalizeRelayUrl(sourceRelay, {
+      allowInsecure: this.allowPrivateRelays,
+      allowPrivate: this.allowPrivateRelays,
+    });
+    const hint = normalizeRelayUrl(hintedRelay, {
+      allowInsecure: false,
+      allowPrivate: this.allowPrivateRelays,
+    });
+    const discovered = [];
+
+    if (source) this.rememberPeerRelay(peer, source, now);
+    if (hint) {
+      this.rememberPeerRelay(peer, hint, now);
+      if (!this.bootstrapSet.has(hint)) {
+        const isNew = !this.learned.has(hint);
+        this.learned.delete(hint);
+        this.learned.set(hint, now);
+        if (isNew) discovered.push(hint);
+      }
+    }
+
+    this.enforceGlobalLimit();
+    return discovered.filter((relay) => this.learned.has(relay));
+  }
+
+  rememberPeerRelay(peer, relay, now) {
+    if (!this.peers.has(peer)) this.peers.set(peer, new Map());
+    const peerRelays = this.peers.get(peer);
+    peerRelays.delete(relay);
+    peerRelays.set(relay, now);
+    while (peerRelays.size > this.maxPeerRelays) {
+      peerRelays.delete(peerRelays.keys().next().value);
+    }
+  }
+
+  enforceGlobalLimit() {
+    while (this.learned.size > this.maxLearnedRelays) {
+      const evicted = this.learned.keys().next().value;
+      this.learned.delete(evicted);
+      for (const peerRelays of this.peers.values()) peerRelays.delete(evicted);
+    }
+  }
+
+  replyRelays(peerPubkey, ingressRelay = null) {
+    const peer = normalizePubkey(peerPubkey);
+    const ingress = normalizeRelayUrl(ingressRelay, {
+      allowInsecure: this.allowPrivateRelays,
+      allowPrivate: this.allowPrivateRelays,
+    });
+    const peerRelays = [...(this.peers.get(peer)?.entries() || [])]
+      .sort((left, right) => right[1] - left[1])
+      .map(([relay]) => relay);
+    return [...new Set([ingress, ...peerRelays, ...this.bootstrapRelays].filter(Boolean))].slice(
+      0,
+      this.maxReplyRelays,
+    );
+  }
+
+  learnedRelays() {
+    return [...this.learned.keys()];
+  }
+
+  snapshot() {
+    return {
+      bootstrapRelays: [...this.bootstrapRelays],
+      learnedRelays: this.learnedRelays(),
+      peers: Object.fromEntries(
+        [...this.peers].map(([peer, relays]) => [
+          peer,
+          [...relays.entries()]
+            .sort((left, right) => right[1] - left[1])
+            .map(([relay, lastSeenAt]) => ({ relay, lastSeenAt })),
+        ]),
+      ),
+    };
+  }
+}

package/src/wire.js

@@ -0,0 +1,202 @@
+import { gcm } from "@noble/ciphers/aes.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { hexToBytes } from "@noble/hashes/utils.js";
+import * as secp from "@noble/secp256k1";
+
+secp.hashes.sha256 = sha256;
+secp.hashes.hmacSha256 = (key, ...messages) => hmac(sha256, key, secp.etc.concatBytes(...messages));
+
+export const DM_KIND = 4;
+export const DM_TAG = "gupt-dm";
+export const RETENTION_DAYS = 100;
+export const MAX_EVENT_BYTES = 128 * 1024;
+export const MAX_CONTENT_BYTES = 96 * 1024;
+
+const HEX_64 = /^[0-9a-f]{64}$/;
+const HEX_128 = /^[0-9a-f]{128}$/;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export function normalizeSecretHex(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!HEX_64.test(normalized)) throw new TypeError("secretHex must be 64 hexadecimal characters");
+  const bytes = hexToBytes(normalized);
+  if (!secp.utils.isValidSecretKey(bytes))
+    throw new TypeError("secretHex is not a valid secp256k1 key");
+  return normalized;
+}
+
+export function normalizePubkey(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  const xOnly = /^(02|03)[0-9a-f]{64}$/.test(normalized) ? normalized.slice(2) : normalized;
+  if (!HEX_64.test(xOnly)) throw new TypeError("pubkey must be 64 hexadecimal characters");
+  return xOnly;
+}
+
+export function getPublicKey(secretHex) {
+  return secp.etc.bytesToHex(secp.schnorr.getPublicKey(hexToBytes(normalizeSecretHex(secretHex))));
+}
+
+export function serializeEvent(event) {
+  return JSON.stringify([0, event.pubkey, event.created_at, event.kind, event.tags, event.content]);
+}
+
+export function computeEventId(event) {
+  return secp.etc.bytesToHex(sha256(textEncoder.encode(serializeEvent(event))));
+}
+
+export function finalizeEvent(template, secretHex) {
+  const secret = hexToBytes(normalizeSecretHex(secretHex));
+  const event = {
+    ...template,
+    pubkey: secp.etc.bytesToHex(secp.schnorr.getPublicKey(secret)),
+    created_at: template.created_at ?? Math.floor(Date.now() / 1000),
+    tags: template.tags || [],
+    content: template.content || "",
+  };
+  event.id = computeEventId(event);
+  event.sig = secp.etc.bytesToHex(secp.schnorr.sign(hexToBytes(event.id), secret));
+  return event;
+}
+
+export function verifyEventSignature(event) {
+  try {
+    if (!HEX_64.test(event?.id) || !HEX_64.test(event?.pubkey) || !HEX_128.test(event?.sig)) {
+      return false;
+    }
+    if (computeEventId(event) !== event.id) return false;
+    return secp.schnorr.verify(
+      hexToBytes(event.sig),
+      hexToBytes(event.id),
+      hexToBytes(event.pubkey),
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function assertDirectMessageEvent(event, recipientPubkey) {
+  if (!event || typeof event !== "object" || Array.isArray(event)) {
+    throw new TypeError("Event must be an object");
+  }
+  if (event.kind !== DM_KIND) throw new TypeError("Unsupported event kind");
+  if (!Number.isSafeInteger(event.created_at) || event.created_at <= 0) {
+    throw new TypeError("Invalid event timestamp");
+  }
+  if (!HEX_64.test(event.id || "") || !HEX_64.test(event.pubkey || "")) {
+    throw new TypeError("Invalid event identity");
+  }
+  if (!HEX_128.test(event.sig || "")) throw new TypeError("Invalid event signature");
+  if (!Array.isArray(event.tags) || event.tags.length > 32) {
+    throw new TypeError("Invalid event tags");
+  }
+  for (const tag of event.tags) {
+    if (
+      !Array.isArray(tag) ||
+      tag.length === 0 ||
+      tag.length > 4 ||
+      tag.some((value) => typeof value !== "string" || value.length > 2048)
+    ) {
+      throw new TypeError("Invalid event tag");
+    }
+  }
+  if (typeof event.content !== "string") throw new TypeError("Invalid event content");
+  if (Buffer.byteLength(event.content, "utf8") > MAX_CONTENT_BYTES) {
+    throw new TypeError("Event content is too large");
+  }
+  if (Buffer.byteLength(JSON.stringify(event), "utf8") > MAX_EVENT_BYTES) {
+    throw new TypeError("Event is too large");
+  }
+
+  const self = normalizePubkey(recipientPubkey);
+  const recipientTag = event.tags.find((tag) => tag[0] === "p" && tag[1] === self);
+  if (!recipientTag) throw new TypeError("Event is not addressed to this bot");
+  if (!event.tags.some((tag) => tag[0] === "t" && tag[1] === DM_TAG)) {
+    throw new TypeError("Event is not a GUPT direct message");
+  }
+
+  return event;
+}
+
+export function getSenderRelayHint(event, recipientPubkey) {
+  const self = normalizePubkey(recipientPubkey);
+  const recipientTag = event?.tags?.find((tag) => tag[0] === "p" && tag[1] === self);
+  return typeof recipientTag?.[2] === "string" ? recipientTag[2] : null;
+}
+
+export function getExpiryTimestampSec(now = Date.now()) {
+  return Math.floor(now / 1000) + RETENTION_DAYS * 24 * 60 * 60;
+}
+
+export function isExpiredEvent(event, now = Date.now()) {
+  const expiration = event?.tags?.find((tag) => tag[0] === "expiration")?.[1];
+  if (expiration == null) return false;
+  const expiresAt = Number(expiration);
+  return !Number.isFinite(expiresAt) || expiresAt <= Math.floor(now / 1000);
+}
+
+export function getDmSharedSecret(secretHex, pubkey) {
+  const secret = hexToBytes(normalizeSecretHex(secretHex));
+  const compressedPubkey = hexToBytes(`02${normalizePubkey(pubkey)}`);
+  return sha256(secp.getSharedSecret(secret, compressedPubkey).subarray(1, 33));
+}
+
+export function encryptDm(secretHex, pubkey, plaintext, options = {}) {
+  const nonce = options.nonce
+    ? Uint8Array.from(options.nonce)
+    : globalThis.crypto.getRandomValues(new Uint8Array(12));
+  if (nonce.length !== 12) throw new TypeError("AES-GCM nonce must contain 12 bytes");
+  const ciphertext = gcm(getDmSharedSecret(secretHex, pubkey), nonce).encrypt(
+    textEncoder.encode(String(plaintext)),
+  );
+  return `v1:${Buffer.from(nonce).toString("base64")}:${Buffer.from(ciphertext).toString("base64")}`;
+}
+
+export function decryptDm(secretHex, pubkey, blob) {
+  const parts = String(blob || "").split(":");
+  if (parts.length !== 3 || parts[0] !== "v1") throw new TypeError("Unsupported ciphertext format");
+  const nonce = Buffer.from(parts[1], "base64");
+  const ciphertext = Buffer.from(parts[2], "base64");
+  if (nonce.length !== 12 || ciphertext.length < 16) throw new TypeError("Invalid ciphertext");
+  const plaintext = gcm(getDmSharedSecret(secretHex, pubkey), nonce).decrypt(ciphertext);
+  return textDecoder.decode(plaintext);
+}
+
+export function buildDirectMessageEvent({
+  secretHex,
+  recipientPubkey,
+  payload,
+  relayHint = null,
+  now = Date.now(),
+}) {
+  const recipient = normalizePubkey(recipientPubkey);
+  const content = encryptDm(secretHex, recipient, JSON.stringify(payload));
+  return finalizeEvent(
+    {
+      kind: DM_KIND,
+      created_at: Math.floor(now / 1000),
+      tags: [
+        relayHint ? ["p", recipient, String(relayHint)] : ["p", recipient],
+        ["t", DM_TAG],
+        ["expiration", String(getExpiryTimestampSec(now))],
+      ],
+      content,
+    },
+    secretHex,
+  );
+}
+
+export function decryptDirectMessage(event, secretHex, recipientPubkey) {
+  assertDirectMessageEvent(event, recipientPubkey);
+  const plaintext = decryptDm(secretHex, event.pubkey, event.content);
+  const payload = JSON.parse(plaintext);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new TypeError("Invalid direct-message payload");
+  }
+  return payload;
+}