@meshwhisper/node 0.1.1 → 0.2.1

package/README.md

@@ -0,0 +1,46 @@
+# @meshwhisper/node
+
+The [MeshWhisper](https://github.com/twotwoonethree/meshwhisper) relay node — packet relay, store-and-forward, push-notification forwarding, encrypted media storage, encrypted archive storage, username/prekey directory, and relay-to-relay federation, in a single binary.
+
+The node never holds a decryption key. Everything it relays, stores, or queues is opaque ciphertext; clients encrypt on-device with PQXDH + Double Ratchet via [`@meshwhisper/sdk`](https://www.npmjs.com/package/@meshwhisper/sdk).
+
+## Quickstart
+
+The easiest path is the CLI, which writes a Docker Compose deployment around this package:
+
+```bash
+npx @meshwhisper/cli init
+```
+
+Or run it directly:
+
+```bash
+npm install -g @meshwhisper/node
+BASE_URL=https://relay.myapp.com DB_PATH=./meshwhisper.db meshwhisper-node
+```
+
+Listens on port 8080 (`PORT` to change). Put TLS in front of it (Caddy: `reverse_proxy localhost:8080`). Verify with `curl https://relay.myapp.com/health` or `npx @meshwhisper/cli doctor`.
+
+## Key environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `8080` | HTTP/WebSocket listen port |
+| `BASE_URL` | — | Public URL; **required** for media download links to be reachable |
+| `DB_PATH` | `./meshwhisper.db` | SQLite database location |
+| `BLOB_TTL_HOURS` | `720` | How long queued messages wait for offline recipients (30 days) |
+| `MEDIA_TTL_HOURS` | `168` | Encrypted media retention |
+| `PUSH_WEBHOOK_URL` | — | `@meshwhisper/push-service` endpoint for offline wake signals |
+| `TRUST_PROXY` | unset | Set to `1` behind a reverse proxy so rate limiting sees real client IPs |
+| `FEDERATION_MODE` | off | `open` joins the relay mesh — your node forwards packets for other relays and they for yours; `allowlist` for explicit peering |
+
+Full reference, including federation, backups, and metrics: [self-hosting guide](https://github.com/twotwoonethree/meshwhisper/blob/main/docs/self-hosting.md).
+
+## Operational features
+
+- Per-IP rate limiting on every endpoint
+- Prometheus metrics at `/metrics`, health at `/health`
+- Hot backup via bundled sqlite: `sqlite3 meshwhisper.db ".backup backup.db"`
+- Federation wire protocol specified in [docs/federation.md](https://github.com/twotwoonethree/meshwhisper/blob/main/docs/federation.md)
+
+MIT

package/dist/federation.d.ts

@@ -0,0 +1,99 @@
+import * as nodeCrypto from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+export declare const FEDERATION_SUBPROTOCOL = "meshwhisper-federation.v1";
+/** Admission policy. 'open' accepts any peer that completes the handshake
+ *  (Tor-middle-node posture — the project's recommended setting once a
+ *  mesh exists); 'allowlist' requires the pubkey to be pre-approved. */
+export type FederationMode = 'allowlist' | 'open';
+export interface FederationKey {
+    publicKeyHex: string;
+    privateKey: nodeCrypto.KeyObject;
+}
+/**
+ * Load the node's federation keypair from `keyPath`, generating and
+ * persisting a fresh one if the file doesn't exist. Stored shape:
+ * { publicKeyHex, privateKeyPkcs8Base64 }.
+ */
+export declare function loadOrCreateFederationKey(keyPath: string): FederationKey;
+export interface PeerConfig {
+    pubkey: string;
+    /** Present = this node initiates outbound connections to the peer. */
+    url?: string;
+}
+/** Load { peers: [...] } from `peersPath`. Missing file = no peers = federation dormant. */
+export declare function loadPeersConfig(peersPath: string): PeerConfig[];
+/**
+ * Load the reactive blocklist: { "blocked": ["<pubkeyhex>", ...] }.
+ * Checked at handshake time — a blocked pubkey is rejected regardless of
+ * mode. Evicting an already-connected peer requires a restart in v1.
+ */
+export declare function loadBlocklist(blocklistPath: string): Set<string>;
+export declare function buildHandshakeCanonical(initiatorPubkeyHex: string, responderPubkeyHex: string, initiatorNonceHex: string, responderNonceHex: string): Buffer;
+type LocalOutcome = 'delivered' | 'stored' | 'unknown';
+export interface FederationStats {
+    peersConfigured: number;
+    peersConnected: number;
+    forwardsSentTotal: number;
+    forwardsReceivedTotal: number;
+    deliveredLocallyTotal: number;
+    storedLocallyTotal: number;
+    forwardedOnwardTotal: number;
+    dropsDuplicateTotal: number;
+    dropsTtlTotal: number;
+    dropsRateLimitedTotal: number;
+    handshakeFailuresTotal: number;
+    handshakeRejectionsBlockedTotal: number;
+}
+export declare class FederationManager {
+    private readonly key;
+    private readonly mode;
+    private readonly allowedPubkeys;
+    private readonly blockedPubkeys;
+    private readonly maxPeers;
+    private readonly rateLimitPerMin;
+    private readonly peers;
+    private readonly cache;
+    private readonly classifyLocal;
+    private readonly wss;
+    private stopped;
+    readonly stats: FederationStats;
+    constructor(opts: {
+        key: FederationKey;
+        peers: PeerConfig[];
+        classifyLocal: (packet: Uint8Array) => LocalOutcome;
+        /** Admission policy. Default 'allowlist' (v1 behavior). */
+        mode?: FederationMode;
+        /** Pubkeys rejected at handshake regardless of mode. */
+        blockedPubkeys?: Set<string>;
+        /** Open-mode cap on total simultaneously-tracked peers (configured +
+         *  dynamically admitted). Handshakes beyond the cap are rejected. */
+        maxPeers?: number;
+        /** Per-peer PacketForward frames accepted per minute; excess dropped. */
+        rateLimitPerMin?: number;
+    });
+    private newPeerState;
+    /** Dial every peer that has a url. Inbound peers connect to us instead. */
+    start(): void;
+    stop(): void;
+    connectedPeerCount(): number;
+    /** Route an HTTP upgrade with the federation subprotocol into the manager. */
+    handleUpgrade(req: IncomingMessage, socket: import('node:stream').Duplex, head: Buffer): void;
+    /**
+     * Forward a locally-received packet (from one of our own clients)
+     * whose destHash we have no local knowledge of. Mints a fresh
+     * packetId, forwardCount = 0, fans out to every established peer.
+     */
+    forwardFromLocal(packet: Uint8Array): void;
+    private fanOut;
+    private dial;
+    private scheduleReconnect;
+    private teardownPeer;
+    /** One-shot wait for the next message on a socket (handshake phases). */
+    private nextMessage;
+    private runInitiatorHandshake;
+    private runResponderHandshake;
+    private establishPeer;
+    private handleFrame;
+}
+export {};
+//# sourceMappingURL=federation.d.ts.map

package/dist/federation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../src/federation.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,UAAU,MAAM,aAAa,CAAC;AAG1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,eAAO,MAAM,sBAAsB,8BAA8B,CAAC;AAgBlE;;wEAEwE;AACxE,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,MAAM,CAAC;AAOlD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CA0BxE;AAID,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,EAAE,CAW/D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAShE;AAID,wBAAgB,uBAAuB,CACrC,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,iBAAiB,EAAE,MAAM,EACzB,iBAAiB,EAAE,MAAM,GACxB,MAAM,CAWR;AA8FD,KAAK,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAkBvD,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,+BAA+B,EAAE,MAAM,CAAC;CACzC;AAID,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAc;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAc;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuC;IACrE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,OAAO,CAAS;IAExB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAa7B;gBAEU,IAAI,EAAE;QAChB,GAAG,EAAE,aAAa,CAAC;QACnB,KAAK,EAAE,UAAU,EAAE,CAAC;QACpB,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,YAAY,CAAC;QACpD,2DAA2D;QAC3D,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,wDAAwD;QACxD,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC7B;6EACqE;QACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,yEAAyE;QACzE,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B;IAmBD,OAAO,CAAC,YAAY;IAcpB,2EAA2E;IAC3E,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,IAAI;IASZ,kBAAkB,IAAI,MAAM;IAM5B,8EAA8E;IAC9E,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAS7F;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAU1C,OAAO,CAAC,MAAM;IAgBd,OAAO,CAAC,IAAI;IAiBZ,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,YAAY;IAgBpB,yEAAyE;IACzE,OAAO,CAAC,WAAW;YAwBL,qBAAqB;YA6BrB,qBAAqB;IAyDnC,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,WAAW;CAqDpB"}

package/dist/federation.js

@@ -0,0 +1,539 @@
+// ============================================================
+// MeshWhisper Node — Federation (node-to-node packet forwarding)
+//
+// Implements docs/federation.md v1:
+//   - Pairwise peering between explicitly allow-listed nodes
+//   - Mutual Ed25519 handshake over a WebSocket with the
+//     `meshwhisper-federation.v1` subprotocol
+//   - Length-prefixed binary frames: PacketForward + Heartbeat
+//   - Loop prevention via a packet-id LRU
+//   - TTL (hop-count) exhaustion
+//   - Reconnect with exponential backoff for outbound peers
+//
+// The module is deliberately self-contained: index.ts hands it an
+// allow-list + keypair + a single `classifyLocal` callback that
+// answers "can this packet be delivered or stored locally?", and the
+// module handles everything else. The relay's existing client-relay
+// path is untouched.
+// ============================================================
+import { WebSocketServer, WebSocket } from 'ws';
+import * as nodeCrypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const FEDERATION_SUBPROTOCOL = 'meshwhisper-federation.v1';
+// ---- Wire constants (docs/federation.md "Forwarding wire format") ----
+const WIRE_VERSION = 0x01;
+const FRAME_PACKET_FORWARD = 0x01;
+const FRAME_HEARTBEAT = 0x02;
+const MAX_HOPS = parseInt(process.env.FEDERATION_MAX_HOPS ?? '3', 10);
+const MAX_FRAME_BODY = 8192;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_TIMEOUT_MS = 90_000;
+const PACKET_ID_CACHE_SIZE = 1024;
+const PACKET_ID_TTL_MS = 60_000;
+const RECONNECT_BACKOFF_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 32_000, 60_000];
+// DER wrappers so node:crypto can ingest raw Ed25519 key bytes.
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+/**
+ * Load the node's federation keypair from `keyPath`, generating and
+ * persisting a fresh one if the file doesn't exist. Stored shape:
+ * { publicKeyHex, privateKeyPkcs8Base64 }.
+ */
+export function loadOrCreateFederationKey(keyPath) {
+    if (fs.existsSync(keyPath)) {
+        const raw = JSON.parse(fs.readFileSync(keyPath, 'utf8'));
+        const privateKey = nodeCrypto.createPrivateKey({
+            key: Buffer.from(raw.privateKeyPkcs8Base64, 'base64'),
+            format: 'der',
+            type: 'pkcs8',
+        });
+        return { publicKeyHex: raw.publicKeyHex, privateKey };
+    }
+    const { publicKey, privateKey } = nodeCrypto.generateKeyPairSync('ed25519');
+    const spki = publicKey.export({ format: 'der', type: 'spki' });
+    const publicKeyHex = spki.subarray(spki.length - 32).toString('hex');
+    const pkcs8 = privateKey.export({ format: 'der', type: 'pkcs8' });
+    fs.mkdirSync(path.dirname(keyPath), { recursive: true });
+    fs.writeFileSync(keyPath, JSON.stringify({
+        publicKeyHex,
+        privateKeyPkcs8Base64: pkcs8.toString('base64'),
+    }, null, 2), { mode: 0o600 });
+    return { publicKeyHex, privateKey };
+}
+/** Load { peers: [...] } from `peersPath`. Missing file = no peers = federation dormant. */
+export function loadPeersConfig(peersPath) {
+    if (!fs.existsSync(peersPath))
+        return [];
+    try {
+        const raw = JSON.parse(fs.readFileSync(peersPath, 'utf8'));
+        return (raw.peers ?? []).filter((p) => typeof p?.pubkey === 'string' && /^[0-9a-f]{64}$/.test(p.pubkey));
+    }
+    catch {
+        console.error(`[federation] malformed peers file at ${peersPath} — federation dormant`);
+        return [];
+    }
+}
+/**
+ * Load the reactive blocklist: { "blocked": ["<pubkeyhex>", ...] }.
+ * Checked at handshake time — a blocked pubkey is rejected regardless of
+ * mode. Evicting an already-connected peer requires a restart in v1.
+ */
+export function loadBlocklist(blocklistPath) {
+    if (!fs.existsSync(blocklistPath))
+        return new Set();
+    try {
+        const raw = JSON.parse(fs.readFileSync(blocklistPath, 'utf8'));
+        return new Set((raw.blocked ?? []).filter((p) => /^[0-9a-f]{64}$/.test(p)));
+    }
+    catch {
+        console.error(`[federation] malformed blocklist at ${blocklistPath} — ignoring`);
+        return new Set();
+    }
+}
+// ---- Canonical handshake message ----
+export function buildHandshakeCanonical(initiatorPubkeyHex, responderPubkeyHex, initiatorNonceHex, responderNonceHex) {
+    return Buffer.from([
+        FEDERATION_SUBPROTOCOL,
+        initiatorPubkeyHex,
+        responderPubkeyHex,
+        initiatorNonceHex,
+        responderNonceHex,
+    ].join('\n'), 'utf8');
+}
+function verifyWithRawPubkey(pubkeyHex, message, signature) {
+    if (signature.length !== 64)
+        return false;
+    let keyObj;
+    try {
+        keyObj = nodeCrypto.createPublicKey({
+            key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(pubkeyHex, 'hex')]),
+            format: 'der',
+            type: 'spki',
+        });
+    }
+    catch {
+        return false;
+    }
+    try {
+        return nodeCrypto.verify(null, message, keyObj, signature);
+    }
+    catch {
+        return false;
+    }
+}
+function encodeHello(h) {
+    const buf = Buffer.alloc(1 + 32 + 16 + 4);
+    buf.writeUInt8(h.version, 0);
+    Buffer.from(h.pubkeyHex, 'hex').copy(buf, 1);
+    Buffer.from(h.nonceHex, 'hex').copy(buf, 33);
+    buf.writeUInt32BE(h.capabilities, 49);
+    return buf;
+}
+function decodeHello(buf) {
+    if (buf.length !== 53)
+        return null;
+    return {
+        version: buf.readUInt8(0),
+        pubkeyHex: buf.subarray(1, 33).toString('hex'),
+        nonceHex: buf.subarray(33, 49).toString('hex'),
+        capabilities: buf.readUInt32BE(49),
+    };
+}
+// ---- Data frame codec ----
+function encodeFrame(frameType, body) {
+    const out = Buffer.alloc(1 + 4 + body.length);
+    out.writeUInt8(frameType, 0);
+    out.writeUInt32BE(body.length, 1);
+    body.copy(out, 5);
+    return out;
+}
+function decodeFrame(buf) {
+    if (buf.length < 5)
+        return null;
+    const frameType = buf.readUInt8(0);
+    const length = buf.readUInt32BE(1);
+    if (length > MAX_FRAME_BODY)
+        return null;
+    if (buf.length !== 5 + length)
+        return null;
+    return { frameType, body: buf.subarray(5) };
+}
+// ---- Packet-id LRU (loop prevention) ----
+class PacketIdCache {
+    entries = new Map(); // id → insertedAt
+    /** Returns true if the id was already present (within TTL). Inserts otherwise. */
+    checkAndInsert(idHex) {
+        const now = Date.now();
+        const existing = this.entries.get(idHex);
+        if (existing !== undefined && now - existing < PACKET_ID_TTL_MS) {
+            return true;
+        }
+        // Refresh / insert. Evict oldest beyond capacity (Map preserves insertion order).
+        this.entries.delete(idHex);
+        this.entries.set(idHex, now);
+        while (this.entries.size > PACKET_ID_CACHE_SIZE) {
+            const oldest = this.entries.keys().next().value;
+            this.entries.delete(oldest);
+        }
+        return false;
+    }
+}
+// ---- Manager ----
+export class FederationManager {
+    key;
+    mode;
+    allowedPubkeys;
+    blockedPubkeys;
+    maxPeers;
+    rateLimitPerMin;
+    peers = new Map(); // pubkeyHex → state
+    cache = new PacketIdCache();
+    classifyLocal;
+    wss;
+    stopped = false;
+    stats = {
+        peersConfigured: 0,
+        peersConnected: 0,
+        forwardsSentTotal: 0,
+        forwardsReceivedTotal: 0,
+        deliveredLocallyTotal: 0,
+        storedLocallyTotal: 0,
+        forwardedOnwardTotal: 0,
+        dropsDuplicateTotal: 0,
+        dropsTtlTotal: 0,
+        dropsRateLimitedTotal: 0,
+        handshakeFailuresTotal: 0,
+        handshakeRejectionsBlockedTotal: 0,
+    };
+    constructor(opts) {
+        this.key = opts.key;
+        this.classifyLocal = opts.classifyLocal;
+        this.mode = opts.mode ?? 'allowlist';
+        this.blockedPubkeys = opts.blockedPubkeys ?? new Set();
+        this.maxPeers = opts.maxPeers ?? 64;
+        this.rateLimitPerMin = opts.rateLimitPerMin ?? 6000; // ≈100 frames/sec
+        this.allowedPubkeys = new Set(opts.peers.map((p) => p.pubkey));
+        for (const p of opts.peers) {
+            this.peers.set(p.pubkey, this.newPeerState(p, false));
+        }
+        this.stats.peersConfigured = opts.peers.length;
+        this.wss = new WebSocketServer({
+            noServer: true,
+            handleProtocols: (protocols) => protocols.has(FEDERATION_SUBPROTOCOL) ? FEDERATION_SUBPROTOCOL : false,
+        });
+    }
+    newPeerState(config, dynamic) {
+        return {
+            config,
+            ws: null,
+            established: false,
+            reconnectAttempt: 0,
+            reconnectTimer: null,
+            heartbeatTimer: null,
+            lastFrameAt: 0,
+            dynamic,
+            frameWindow: { count: 0, windowStart: 0 },
+        };
+    }
+    /** Dial every peer that has a url. Inbound peers connect to us instead. */
+    start() {
+        for (const state of this.peers.values()) {
+            if (state.config.url)
+                this.dial(state);
+        }
+    }
+    stop() {
+        this.stopped = true;
+        for (const state of this.peers.values()) {
+            if (state.reconnectTimer)
+                clearTimeout(state.reconnectTimer);
+            if (state.heartbeatTimer)
+                clearInterval(state.heartbeatTimer);
+            state.ws?.close();
+        }
+    }
+    connectedPeerCount() {
+        let n = 0;
+        for (const s of this.peers.values())
+            if (s.established)
+                n++;
+        return n;
+    }
+    /** Route an HTTP upgrade with the federation subprotocol into the manager. */
+    handleUpgrade(req, socket, head) {
+        this.wss.handleUpgrade(req, socket, head, (ws) => {
+            this.runResponderHandshake(ws).catch(() => {
+                this.stats.handshakeFailuresTotal++;
+                try {
+                    ws.close();
+                }
+                catch { /* already closed */ }
+            });
+        });
+    }
+    /**
+     * Forward a locally-received packet (from one of our own clients)
+     * whose destHash we have no local knowledge of. Mints a fresh
+     * packetId, forwardCount = 0, fans out to every established peer.
+     */
+    forwardFromLocal(packet) {
+        if (packet.byteLength > MAX_FRAME_BODY - 17)
+            return; // can't fit in a frame body
+        const packetId = nodeCrypto.randomBytes(16);
+        // Insert into our own cache so a loop back to us is dropped.
+        this.cache.checkAndInsert(packetId.toString('hex'));
+        this.fanOut(packetId, 0, Buffer.from(packet), null);
+    }
+    // ---- internals ----
+    fanOut(packetId, forwardCount, packet, excludePubkey) {
+        const body = Buffer.alloc(17 + packet.length);
+        packetId.copy(body, 0);
+        body.writeUInt8(forwardCount, 16);
+        packet.copy(body, 17);
+        const frame = encodeFrame(FRAME_PACKET_FORWARD, body);
+        for (const [pubkey, state] of this.peers) {
+            if (pubkey === excludePubkey)
+                continue;
+            if (!state.established || !state.ws || state.ws.readyState !== WebSocket.OPEN)
+                continue;
+            try {
+                state.ws.send(frame, { binary: true });
+                this.stats.forwardsSentTotal++;
+            }
+            catch { /* dead socket — heartbeat will reap */ }
+        }
+    }
+    dial(state) {
+        if (this.stopped || !state.config.url)
+            return;
+        const ws = new WebSocket(state.config.url, FEDERATION_SUBPROTOCOL);
+        state.ws = ws;
+        ws.on('open', () => {
+            this.runInitiatorHandshake(ws, state).catch(() => {
+                this.stats.handshakeFailuresTotal++;
+                try {
+                    ws.close();
+                }
+                catch { /* already closed */ }
+            });
+        });
+        ws.on('error', () => { });
+        ws.on('close', () => {
+            this.teardownPeer(state);
+            this.scheduleReconnect(state);
+        });
+    }
+    scheduleReconnect(state) {
+        if (this.stopped || !state.config.url || state.reconnectTimer)
+            return;
+        const delay = RECONNECT_BACKOFF_MS[Math.min(state.reconnectAttempt, RECONNECT_BACKOFF_MS.length - 1)];
+        state.reconnectAttempt++;
+        state.reconnectTimer = setTimeout(() => {
+            state.reconnectTimer = null;
+            this.dial(state);
+        }, delay);
+    }
+    teardownPeer(state) {
+        state.established = false;
+        state.ws = null;
+        if (state.heartbeatTimer) {
+            clearInterval(state.heartbeatTimer);
+            state.heartbeatTimer = null;
+        }
+        // Dynamically-admitted peers leave the map entirely on disconnect so
+        // the open-mode cap frees up. We hold no reconnect duty for them —
+        // they dial us again whenever they want back in.
+        if (state.dynamic) {
+            this.peers.delete(state.config.pubkey);
+        }
+        this.stats.peersConnected = this.connectedPeerCount();
+    }
+    /** One-shot wait for the next message on a socket (handshake phases). */
+    nextMessage(ws, timeoutMs = 10_000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error('handshake timeout'));
+            }, timeoutMs);
+            const onMessage = (raw) => {
+                cleanup();
+                resolve(Buffer.isBuffer(raw) ? raw : Buffer.from(raw));
+            };
+            const onClose = () => {
+                cleanup();
+                reject(new Error('closed during handshake'));
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                ws.off('message', onMessage);
+                ws.off('close', onClose);
+            };
+            ws.once('message', onMessage);
+            ws.once('close', onClose);
+        });
+    }
+    async runInitiatorHandshake(ws, state) {
+        const myNonce = nodeCrypto.randomBytes(16);
+        ws.send(encodeHello({
+            version: WIRE_VERSION,
+            pubkeyHex: this.key.publicKeyHex,
+            nonceHex: myNonce.toString('hex'),
+            capabilities: 0,
+        }), { binary: true });
+        const serverHello = decodeHello(await this.nextMessage(ws));
+        if (!serverHello)
+            throw new Error('malformed ServerHello');
+        if (serverHello.version !== WIRE_VERSION)
+            throw new Error('peer rejected handshake');
+        if (serverHello.pubkeyHex !== state.config.pubkey)
+            throw new Error('peer pubkey mismatch');
+        const canonical = buildHandshakeCanonical(this.key.publicKeyHex, serverHello.pubkeyHex, myNonce.toString('hex'), serverHello.nonceHex);
+        ws.send(nodeCrypto.sign(null, canonical, this.key.privateKey), { binary: true });
+        const serverSig = await this.nextMessage(ws);
+        if (!verifyWithRawPubkey(serverHello.pubkeyHex, canonical, serverSig)) {
+            throw new Error('peer signature invalid');
+        }
+        state.reconnectAttempt = 0;
+        this.establishPeer(state, ws);
+    }
+    async runResponderHandshake(ws) {
+        const clientHello = decodeHello(await this.nextMessage(ws));
+        if (!clientHello)
+            throw new Error('malformed ClientHello');
+        const reject = () => {
+            ws.send(encodeHello({
+                version: 0x00,
+                pubkeyHex: this.key.publicKeyHex,
+                nonceHex: '0'.repeat(32),
+                capabilities: 0,
+            }), { binary: true });
+            throw new Error('handshake rejected');
+        };
+        if (clientHello.version !== WIRE_VERSION)
+            reject();
+        if (this.blockedPubkeys.has(clientHello.pubkeyHex)) {
+            this.stats.handshakeRejectionsBlockedTotal++;
+            reject();
+        }
+        if (this.mode === 'allowlist' && !this.allowedPubkeys.has(clientHello.pubkeyHex))
+            reject();
+        if (this.mode === 'open' &&
+            !this.peers.has(clientHello.pubkeyHex) &&
+            this.peers.size >= this.maxPeers)
+            reject();
+        const myNonce = nodeCrypto.randomBytes(16);
+        ws.send(encodeHello({
+            version: WIRE_VERSION,
+            pubkeyHex: this.key.publicKeyHex,
+            nonceHex: myNonce.toString('hex'),
+            capabilities: 0,
+        }), { binary: true });
+        const canonical = buildHandshakeCanonical(clientHello.pubkeyHex, this.key.publicKeyHex, clientHello.nonceHex, myNonce.toString('hex'));
+        const clientSig = await this.nextMessage(ws);
+        if (!verifyWithRawPubkey(clientHello.pubkeyHex, canonical, clientSig)) {
+            throw new Error('initiator signature invalid');
+        }
+        ws.send(nodeCrypto.sign(null, canonical, this.key.privateKey), { binary: true });
+        let state = this.peers.get(clientHello.pubkeyHex);
+        if (!state) {
+            // Open mode: dynamically admit. (Unreachable under allowlist —
+            // the admission check above would have rejected.)
+            state = this.newPeerState({ pubkey: clientHello.pubkeyHex }, true);
+            this.peers.set(clientHello.pubkeyHex, state);
+        }
+        // If a stale connection exists (e.g. both sides dialed), prefer the new one.
+        if (state.ws && state.ws !== ws) {
+            try {
+                state.ws.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.establishPeer(state, ws);
+    }
+    establishPeer(state, ws) {
+        state.ws = ws;
+        state.established = true;
+        state.lastFrameAt = Date.now();
+        this.stats.peersConnected = this.connectedPeerCount();
+        console.log(`[federation] peer ${state.config.pubkey.slice(0, 12)}… connected`);
+        ws.on('message', (raw) => {
+            state.lastFrameAt = Date.now();
+            const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+            this.handleFrame(buf, state);
+        });
+        ws.on('close', () => {
+            console.log(`[federation] peer ${state.config.pubkey.slice(0, 12)}… disconnected`);
+            this.teardownPeer(state);
+            this.scheduleReconnect(state);
+        });
+        state.heartbeatTimer = setInterval(() => {
+            if (Date.now() - state.lastFrameAt > HEARTBEAT_TIMEOUT_MS) {
+                try {
+                    ws.close();
+                }
+                catch { /* close handler reaps */ }
+                return;
+            }
+            const body = Buffer.alloc(8);
+            body.writeBigInt64BE(BigInt(Date.now()), 0);
+            try {
+                ws.send(encodeFrame(FRAME_HEARTBEAT, body), { binary: true });
+            }
+            catch { /* reaped on close */ }
+        }, HEARTBEAT_INTERVAL_MS);
+    }
+    handleFrame(buf, fromState) {
+        const frame = decodeFrame(buf);
+        if (!frame) {
+            // Malformed or oversized — close per spec.
+            try {
+                fromState.ws?.close();
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        if (frame.frameType === FRAME_HEARTBEAT)
+            return; // lastFrameAt already updated
+        if (frame.frameType !== FRAME_PACKET_FORWARD)
+            return; // unknown type — ignore (forward-compat)
+        if (frame.body.length < 17 + 31)
+            return; // packetId + forwardCount + minimum packet header
+        // Per-peer rate limiting — the abuse boundary in open mode. Sliding
+        // 60s window; excess frames are silently dropped (not a disconnect:
+        // legitimate bursts shouldn't sever the link).
+        const now = Date.now();
+        if (now - fromState.frameWindow.windowStart >= 60_000) {
+            fromState.frameWindow = { count: 0, windowStart: now };
+        }
+        fromState.frameWindow.count++;
+        if (fromState.frameWindow.count > this.rateLimitPerMin) {
+            this.stats.dropsRateLimitedTotal++;
+            return;
+        }
+        const packetIdHex = frame.body.subarray(0, 16).toString('hex');
+        const forwardCount = frame.body.readUInt8(16);
+        const packet = frame.body.subarray(17);
+        this.stats.forwardsReceivedTotal++;
+        if (this.cache.checkAndInsert(packetIdHex)) {
+            this.stats.dropsDuplicateTotal++;
+            return;
+        }
+        if (forwardCount >= MAX_HOPS) {
+            this.stats.dropsTtlTotal++;
+            return;
+        }
+        const outcome = this.classifyLocal(packet);
+        if (outcome === 'delivered') {
+            this.stats.deliveredLocallyTotal++;
+            return;
+        }
+        if (outcome === 'stored') {
+            this.stats.storedLocallyTotal++;
+            return;
+        }
+        // Unknown locally — forward onward, excluding the peer it came from.
+        this.stats.forwardedOnwardTotal++;
+        this.fanOut(frame.body.subarray(0, 16), forwardCount + 1, Buffer.from(packet), fromState.config.pubkey);
+    }
+}
+//# sourceMappingURL=federation.js.map