@meshwhisper/node 0.1.1 → 0.2.0

package/dist/index.js

@@ -31,24 +31,47 @@
 // ============================================================
 import * as http from 'node:http';
 import * as https from 'node:https';
+import * as nodeCrypto from 'node:crypto';
+import * as path from 'node:path';
 import { WebSocketServer, WebSocket } from 'ws';
 import Database from 'better-sqlite3';
+import { FederationManager, FEDERATION_SUBPROTOCOL, loadOrCreateFederationKey, loadPeersConfig, loadBlocklist, } from './federation.js';
 // ============================================================
 // Configuration
 // ============================================================
 const PORT = parseInt(process.env.PORT ?? '8080', 10);
-const BLOB_TTL_HOURS = parseInt(process.env.BLOB_TTL_HOURS ?? '72', 10);
+// Default 30 days. The previous 72h was tight enough that anyone offline
+// for a long weekend lost messages. Storage cost is small in absolute terms
+// because chaff dominates the relay's traffic, not real blobs. SDK clients
+// listen on the same window to ensure blobs aren't stranded under
+// destHashes the recipient stops asking for.
+const BLOB_TTL_HOURS = parseInt(process.env.BLOB_TTL_HOURS ?? '720', 10);
 const MAX_BLOB_SIZE = parseInt(process.env.MAX_BLOB_SIZE ?? String(256 * 1024), 10); // 256 KB
 const MAX_BLOBS_PER_HASH = parseInt(process.env.MAX_BLOBS_PER_HASH ?? '500', 10);
 const MEDIA_TTL_HOURS = parseInt(process.env.MEDIA_TTL_HOURS ?? String(7 * 24), 10); // 7 days
+const MAX_ARCHIVE_SIZE = parseInt(process.env.MAX_ARCHIVE_SIZE ?? String(12 * 1024 * 1024), 10); // 12 MB
 const MAX_MEDIA_SIZE = parseInt(process.env.MAX_MEDIA_SIZE ?? String(50 * 1024 * 1024), 10); // 50 MB
 const PRUNE_INTERVAL_MS = 5 * 60 * 1000; // prune expired blobs every 5 minutes
 const PUSH_WEBHOOK_URL = process.env.PUSH_WEBHOOK_URL ?? null;
 const DB_PATH = process.env.DB_PATH ?? './meshwhisper.db';
-// Rate limiting (per IP, sliding window)
+// Rate limiting (per IP, sliding window).
+//
+// Buckets are coarse on purpose — one budget per bucket per IP per minute.
+// Operators tune via env vars; the defaults are deliberately generous so
+// well-behaved clients almost never hit them, while still catching obvious
+// abuse (scripted enumeration, blob spam, etc).
+//
+// TRUST_PROXY controls whether X-Forwarded-For is honoured when computing
+// the per-IP key. Default OFF — a direct-exposed node would otherwise let
+// an attacker spoof the header to evade limits. Set TRUST_PROXY=1 (or any
+// truthy value) when running behind nginx / Caddy / Cloudflare etc., which
+// is the expected production deployment shape.
 const RATE_WINDOW_MS = 60_000; // 1 minute window
 const RATE_LIMIT_MEDIA = parseInt(process.env.RATE_LIMIT_MEDIA ?? '20', 10); // uploads/min
-const RATE_LIMIT_DIR = parseInt(process.env.RATE_LIMIT_DIR ?? '60', 10); // registrations/min
+const RATE_LIMIT_DIR = parseInt(process.env.RATE_LIMIT_DIR ?? '60', 10); // writes/min on directory/opks/policy
+const RATE_LIMIT_READ = parseInt(process.env.RATE_LIMIT_READ ?? '300', 10); // reads/min (GETs)
+const RATE_LIMIT_ARCHIVE = parseInt(process.env.RATE_LIMIT_ARCHIVE ?? '30', 10); // archive PUTs/min
+const TRUST_PROXY = /^(1|true|yes|on)$/i.test(process.env.TRUST_PROXY ?? '');
 /** Canonical external base URL for constructing media download links.
  *  Set this when the Node is behind a reverse proxy (nginx, Caddy, Cloudflare).
  *  Example: BASE_URL=https://msg.myapp.com
@@ -61,6 +84,13 @@ const db = new Database(DB_PATH);
 // Enable WAL mode for better concurrent read performance
 db.pragma('journal_mode = WAL');
 db.pragma('foreign_keys = ON');
+// Migrate existing prekey_bundles table if columns are missing (added for username support)
+for (const col of ['username', 'namespace']) {
+    try {
+        db.exec(`ALTER TABLE prekey_bundles ADD COLUMN ${col} TEXT`);
+    }
+    catch { /* already exists */ }
+}
 db.exec(`
   CREATE TABLE IF NOT EXISTS blobs (
     id          INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -79,8 +109,10 @@ db.exec(`
   );
 
   CREATE TABLE IF NOT EXISTS prekey_bundles (
-    key    TEXT PRIMARY KEY,
-    bundle TEXT NOT NULL
+    key       TEXT PRIMARY KEY,
+    bundle    TEXT NOT NULL,
+    username  TEXT,
+    namespace TEXT
   );
 
   CREATE TABLE IF NOT EXISTS media (
@@ -88,6 +120,50 @@ db.exec(`
     data      BLOB    NOT NULL,
     stored_at INTEGER NOT NULL
   );
+
+  CREATE TABLE IF NOT EXISTS opks (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    identity_key TEXT    NOT NULL,
+    opk_public   TEXT    NOT NULL,
+    stored_at    INTEGER NOT NULL,
+    UNIQUE (identity_key, opk_public)
+  );
+  CREATE INDEX IF NOT EXISTS opks_identity_key ON opks (identity_key);
+
+  -- TOFU auth for DELETE /opks. Identity_pubkey is the user's Ed25519
+  -- public key hex (cross-namespace). First DELETE establishes the hash;
+  -- subsequent DELETEs must match.
+  CREATE TABLE IF NOT EXISTS opk_auth (
+    identity_pubkey TEXT PRIMARY KEY,
+    auth_hash       TEXT NOT NULL,
+    stored_at       INTEGER NOT NULL
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS prekey_username_idx
+    ON prekey_bundles (namespace, username)
+    WHERE username IS NOT NULL;
+
+  CREATE TABLE IF NOT EXISTS archives (
+    peer_id    TEXT    PRIMARY KEY,
+    auth_hash  TEXT    NOT NULL,
+    data       BLOB    NOT NULL,
+    stored_at  INTEGER NOT NULL,
+    size       INTEGER NOT NULL
+  );
+
+  -- Per-namespace policy controlling username ownership semantics.
+  -- 'signed-transfer' (default for unrecorded namespaces): username is sticky
+  --   to whichever identity first claims it; a different key cannot take it
+  --   over via a plain re-registration. Re-publishing with the SAME key is
+  --   always allowed (covers bundle refresh and key-rotation flows).
+  -- 'last-writer-wins': legacy/opt-in behavior — a fresh key claiming a taken
+  --   username silently displaces the prior owner. Useful for password-derived
+  --   identities where re-deriving the same key from credentials is the
+  --   recovery story.
+  CREATE TABLE IF NOT EXISTS namespace_policy (
+    namespace       TEXT PRIMARY KEY,
+    username_policy TEXT NOT NULL CHECK (username_policy IN ('signed-transfer', 'last-writer-wins')),
+    set_at          INTEGER NOT NULL
+  );
 `);
 // Prepared statements
 const stmts = {
@@ -112,37 +188,103 @@ const stmts = {
     deletePush: db.prepare('DELETE FROM push_registrations WHERE dest_hash = ?'),
     countPush: db.prepare('SELECT COUNT(*) AS cnt FROM push_registrations'),
     // prekey bundles
-    upsertPrekey: db.prepare(`INSERT INTO prekey_bundles (key, bundle) VALUES (?, ?)
-     ON CONFLICT(key) DO UPDATE SET bundle = excluded.bundle`),
-    getPrekey: db.prepare('SELECT bundle FROM prekey_bundles WHERE key = ?'),
+    upsertPrekey: db.prepare(`INSERT INTO prekey_bundles (key, bundle, username, namespace) VALUES (?, ?, ?, ?)
+     ON CONFLICT(key) DO UPDATE SET
+       bundle    = excluded.bundle,
+       username  = COALESCE(excluded.username, username),
+       namespace = COALESCE(excluded.namespace, namespace)`),
+    getPrekey: db.prepare('SELECT bundle, username FROM prekey_bundles WHERE key = ?'),
+    getPrekeyByUsername: db.prepare('SELECT key, bundle FROM prekey_bundles WHERE namespace = ? AND username = ?'),
     countPrekeys: db.prepare('SELECT COUNT(*) AS cnt FROM prekey_bundles'),
+    // opks
+    insertOpk: db.prepare('INSERT OR IGNORE INTO opks (identity_key, opk_public, stored_at) VALUES (?, ?, ?)'),
+    countOpksForKey: db.prepare('SELECT COUNT(*) AS cnt FROM opks WHERE identity_key = ?'),
+    countOpks: db.prepare('SELECT COUNT(*) AS cnt FROM opks'),
+    // Purges every OPK row for one (namespace, publicKey) pair. Used by the
+    // SDK's one-shot migration after the OPK-resurrection fix to clear out
+    // zombie entries that the buggy bulk re-upload left behind. The auth_hash
+    // check (separate TOFU table below) prevents anyone other than the
+    // identity owner from purging the pool.
+    deleteOpksForKey: db.prepare('DELETE FROM opks WHERE identity_key = ?'),
+    // opk_auth (TOFU per identity)
+    getOpkAuthHash: db.prepare('SELECT auth_hash FROM opk_auth WHERE identity_pubkey = ?'),
+    insertOpkAuthHash: db.prepare('INSERT OR IGNORE INTO opk_auth (identity_pubkey, auth_hash, stored_at) VALUES (?, ?, ?)'),
     // media
     insertMedia: db.prepare('INSERT INTO media (id, data, stored_at) VALUES (?, ?, ?)'),
     getMedia: db.prepare('SELECT data, stored_at FROM media WHERE id = ?'),
     deleteMedia: db.prepare('DELETE FROM media WHERE id = ?'),
     pruneMedia: db.prepare('DELETE FROM media WHERE stored_at < ?'),
     countMedia: db.prepare('SELECT COUNT(*) AS cnt FROM media'),
+    // namespace policy
+    getNamespacePolicy: db.prepare('SELECT username_policy FROM namespace_policy WHERE namespace = ?'),
+    insertNamespacePolicy: db.prepare('INSERT OR IGNORE INTO namespace_policy (namespace, username_policy, set_at) VALUES (?, ?, ?)'),
+    // archives
+    upsertArchive: db.prepare(`INSERT INTO archives (peer_id, auth_hash, data, stored_at, size)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(peer_id) DO UPDATE SET
+       data      = excluded.data,
+       stored_at = excluded.stored_at,
+       size      = excluded.size
+     WHERE auth_hash = excluded.auth_hash`),
+    getArchiveAuthHash: db.prepare('SELECT auth_hash FROM archives WHERE peer_id = ?'),
+    getArchiveData: db.prepare('SELECT data FROM archives WHERE peer_id = ?'),
+    insertArchiveFirstTime: db.prepare('INSERT OR IGNORE INTO archives (peer_id, auth_hash, data, stored_at, size) VALUES (?, ?, ?, ?, ?)'),
+    countArchives: db.prepare('SELECT COUNT(*) AS cnt FROM archives'),
 };
+// Atomic OPK claim: SELECT + DELETE in a single transaction so two concurrent
+// initiators can never claim the same one-time pre-key.
+const claimOpkTx = db.transaction((identityKey) => {
+    const row = db.prepare('SELECT id, opk_public FROM opks WHERE identity_key = ? LIMIT 1').get(identityKey);
+    if (!row)
+        return null;
+    db.prepare('DELETE FROM opks WHERE id = ?').run(row.id);
+    return row.opk_public;
+});
 const rateLimitState = new Map();
-/** Returns true if the request is within limits, false if it should be rejected. */
+/**
+ * Returns ok=true if the request is within limits. On rejection, retryAfterSeconds
+ * is the number of whole seconds until the current window rolls over (clamped to ≥1).
+ */
 function checkRateLimit(ip, bucket, maxPerWindow) {
     const key = `${bucket}:${ip}`;
     const now = Date.now();
     const entry = rateLimitState.get(key);
     if (!entry || now - entry.windowStart >= RATE_WINDOW_MS) {
         rateLimitState.set(key, { count: 1, windowStart: now });
-        return true;
+        return { ok: true, retryAfterSeconds: 0 };
+    }
+    if (entry.count >= maxPerWindow) {
+        const remainingMs = RATE_WINDOW_MS - (now - entry.windowStart);
+        return { ok: false, retryAfterSeconds: Math.max(1, Math.ceil(remainingMs / 1000)) };
     }
-    if (entry.count >= maxPerWindow)
-        return false;
     entry.count++;
+    return { ok: true, retryAfterSeconds: 0 };
+}
+/**
+ * Apply a rate limit at the start of a request handler. On rejection writes
+ * a 429 with a Retry-After header and returns true (caller should `return`).
+ * On accept returns false (caller continues).
+ */
+function rateLimited(req, res, bucket, maxPerWindow) {
+    const r = checkRateLimit(getClientIp(req), bucket, maxPerWindow);
+    if (r.ok)
+        return false;
+    if (metrics.rateLimitRejections[bucket] !== undefined) {
+        metrics.rateLimitRejections[bucket]++;
+    }
+    res.setHeader('Retry-After', String(r.retryAfterSeconds));
+    sendJson(res, 429, { error: 'Too many requests', retryAfter: r.retryAfterSeconds });
     return true;
 }
 function getClientIp(req) {
-    // Respect X-Forwarded-For when behind a proxy
-    const forwarded = req.headers['x-forwarded-for'];
-    if (typeof forwarded === 'string')
-        return forwarded.split(',')[0].trim();
+    // X-Forwarded-For is only honoured when the operator has set TRUST_PROXY,
+    // otherwise an attacker on a direct-exposed node could spoof the header
+    // to evade per-IP rate limiting.
+    if (TRUST_PROXY) {
+        const forwarded = req.headers['x-forwarded-for'];
+        if (typeof forwarded === 'string')
+            return forwarded.split(',')[0].trim();
+    }
     return req.socket.remoteAddress ?? 'unknown';
 }
 function pruneRateLimitState() {
@@ -153,6 +295,28 @@ function pruneRateLimitState() {
     }
 }
 // ============================================================
+// Observability counters — surfaced via the /metrics endpoint in
+// Prometheus text exposition format. Cheap, in-process, reset on
+// every restart (which is what Prometheus expects from counters).
+// ============================================================
+const NODE_STARTED_AT_MS = Date.now();
+const metrics = {
+    httpRequestsTotal: 0,
+    // Indexed by Prometheus-style status family label ("2xx", "3xx", etc.)
+    // plus exact "429" because that's the one operators alert on most.
+    httpStatus: { '2xx': 0, '3xx': 0, '4xx': 0, '5xx': 0, '429': 0 },
+    rateLimitRejections: { dir: 0, media: 0, read: 0, archive: 0 },
+    websocketConnectionsTotal: 0,
+};
+function recordHttpStatus(status) {
+    metrics.httpRequestsTotal++;
+    if (status === 429)
+        metrics.httpStatus['429']++;
+    const family = `${Math.floor(status / 100)}xx`;
+    if (metrics.httpStatus[family] !== undefined)
+        metrics.httpStatus[family]++;
+}
+// ============================================================
 // Packet header constants (must match SDK wire format)
 //
 // Binary layout (all big-endian):
@@ -184,7 +348,8 @@ function storeBlob(destHash, data) {
         if (oldest)
             stmts.deleteBlob.run(oldest.id);
     }
-    stmts.insertBlob.run(destHash, Buffer.from(data), Date.now());
+    const result = stmts.insertBlob.run(destHash, Buffer.from(data), Date.now());
+    return Number(result.lastInsertRowid);
 }
 function pullBlobs(destHash) {
     const rows = stmts.pullBlobs.all(destHash);
@@ -252,12 +417,124 @@ function notifyPush(destHash, reg) {
 function directoryKey(namespace, publicKey) {
     return `${namespace}:${publicKey}`;
 }
-function registerPrekey(namespace, publicKey, bundle) {
-    stmts.upsertPrekey.run(directoryKey(namespace, publicKey), bundle);
+const USERNAME_RE = /^[a-z0-9_-]{3,30}$/;
+function validateUsername(raw) {
+    const u = raw.toLowerCase().trim();
+    return USERNAME_RE.test(u) ? u : null;
+}
+function getNamespaceUsernamePolicy(namespace) {
+    const row = stmts.getNamespacePolicy.get(namespace);
+    return row?.username_policy ?? 'signed-transfer';
+}
+// Wire format for username-transfer authorizations. The signed bytes MUST
+// match what the SDK produces; see `src/sdk/username-transfer.ts`. Bumping
+// the version tag breaks old tokens — fine, transfer tokens are short-lived.
+function canonicalTransferMessage(namespace, username, toPublicKeyHex, expiresAt) {
+    return Buffer.from([
+        'meshwhisper.username-transfer.v1',
+        namespace,
+        username,
+        toPublicKeyHex,
+        String(expiresAt),
+    ].join('\n'), 'utf8');
+}
+// DER SubjectPublicKeyInfo prefix for a raw Ed25519 public key.
+// Lets `nodeCrypto.createPublicKey` ingest a 32-byte key without
+// pulling in an external Ed25519 library.
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+function verifyTransferAuth(namespace, username, newOwnerPublicKeyHex, currentOwnerPublicKeyHex, auth) {
+    if (typeof auth.expiresAt !== 'number' || !Number.isFinite(auth.expiresAt))
+        return false;
+    if (Date.now() > auth.expiresAt)
+        return false;
+    // fromPublicKey in the request is informational; the relay binds
+    // verification to the actual current owner. We still cross-check
+    // so an obviously-mismatched token is rejected early.
+    if (typeof auth.fromPublicKey === 'string' &&
+        auth.fromPublicKey.toLowerCase() !== currentOwnerPublicKeyHex.toLowerCase()) {
+        return false;
+    }
+    let signatureBytes;
+    try {
+        signatureBytes = Buffer.from(auth.signature, 'base64');
+    }
+    catch {
+        return false;
+    }
+    if (signatureBytes.length !== 64)
+        return false;
+    let publicKeyBytes;
+    try {
+        publicKeyBytes = Buffer.from(currentOwnerPublicKeyHex, 'hex');
+    }
+    catch {
+        return false;
+    }
+    if (publicKeyBytes.length !== 32)
+        return false;
+    let publicKey;
+    try {
+        publicKey = nodeCrypto.createPublicKey({
+            key: Buffer.concat([ED25519_SPKI_PREFIX, publicKeyBytes]),
+            format: 'der',
+            type: 'spki',
+        });
+    }
+    catch {
+        return false;
+    }
+    const message = canonicalTransferMessage(namespace, username, newOwnerPublicKeyHex, auth.expiresAt);
+    try {
+        return nodeCrypto.verify(null, message, publicKey, signatureBytes);
+    }
+    catch {
+        return false;
+    }
 }
-function lookupPrekey(namespace, publicKey) {
+const registerPrekeyTx = db.transaction((namespace, publicKey, bundle, username, transferAuth) => {
+    const key = directoryKey(namespace, publicKey);
+    if (username) {
+        const existing = stmts.getPrekeyByUsername.get(namespace, username);
+        if (existing && existing.key !== key) {
+            const policy = getNamespaceUsernamePolicy(namespace);
+            if (policy === 'last-writer-wins') {
+                // Legacy/opt-in: displace the prior owner without proof.
+                db.prepare('DELETE FROM prekey_bundles WHERE key = ?').run(existing.key);
+            }
+            else if (transferAuth) {
+                // Signed-transfer policy with handover token: verify the prior owner
+                // authorized this takeover. existing.key is `${namespace}:${publicKey}`;
+                // splitting on the last colon recovers the publicKey hex (which itself
+                // never contains a colon).
+                const lastColon = existing.key.lastIndexOf(':');
+                const currentOwnerHex = lastColon >= 0 ? existing.key.slice(lastColon + 1) : '';
+                const ok = verifyTransferAuth(namespace, username, publicKey, currentOwnerHex, transferAuth);
+                if (!ok)
+                    return 'invalid_transfer_auth';
+                db.prepare('DELETE FROM prekey_bundles WHERE key = ?').run(existing.key);
+            }
+            else {
+                // Signed-transfer policy, no token — reject takeover.
+                return 'username_taken';
+            }
+        }
+    }
+    stmts.upsertPrekey.run(key, bundle, username, namespace);
+    return 'ok';
+});
+function lookupPrekeyByPublicKey(namespace, publicKey) {
     const row = stmts.getPrekey.get(directoryKey(namespace, publicKey));
-    return row?.bundle ?? null;
+    if (!row)
+        return null;
+    return { bundle: row.bundle, ...(row.username ? { username: row.username } : {}) };
+}
+function lookupPrekeyByUsername(namespace, username) {
+    const row = stmts.getPrekeyByUsername.get(namespace, username);
+    if (!row)
+        return null;
+    // key format is "namespace:publicKey"
+    const publicKey = row.key.slice(namespace.length + 1);
+    return { bundle: row.bundle, publicKey };
 }
 // ============================================================
 // Media store — SQLite-backed, TTL-based encrypted blob storage
@@ -296,6 +573,32 @@ function pruneExpiredMedia() {
 const clientsByHash = new Map();
 /** Reverse map so we can clean up on disconnect. */
 const hashesPerClient = new Map();
+const activitySubscribers = new Set();
+let activityBucket = { in: 0, fwd: 0, queue: 0, wake: 0, drain: 0 };
+function bumpActivity(type) {
+    if (activitySubscribers.size === 0)
+        return; // no-op when nobody is watching
+    activityBucket[type] += 1;
+}
+function flushActivity() {
+    if (activitySubscribers.size === 0)
+        return;
+    const total = activityBucket.in + activityBucket.fwd + activityBucket.queue +
+        activityBucket.wake + activityBucket.drain;
+    if (total === 0)
+        return;
+    const payload = `data: ${JSON.stringify(activityBucket)}\n\n`;
+    for (const res of activitySubscribers) {
+        try {
+            res.write(payload);
+        }
+        catch { /* dead connection — cleaned on close */ }
+    }
+    activityBucket = { in: 0, fwd: 0, queue: 0, wake: 0, drain: 0 };
+}
+// Flush at ~4 Hz: fast enough to feel live, slow enough to obscure
+// individual sends and keep CPU usage trivial.
+setInterval(flushActivity, 250);
 function registerClient(ws, destHashes) {
     const existing = hashesPerClient.get(ws);
     if (existing) {
@@ -325,6 +628,7 @@ function deliverQueuedBlobs(ws, destHashes) {
         for (const blob of blobs) {
             if (ws.readyState === WebSocket.OPEN) {
                 ws.send(blob, { binary: true });
+                bumpActivity('drain');
             }
         }
     }
@@ -338,34 +642,61 @@ function handleRelayPacket(data, sender) {
     const destHash = readDestHash(data);
     if (!destHash)
         return; // malformed header
+    bumpActivity('in');
+    // Always store the blob first so it survives regardless of delivery outcome.
+    // This prevents a race where the recipient's WebSocket is still in the
+    // registry (close event not yet fired) but the peer has already called
+    // terminate(): we'd forward to the stale socket and the store-and-forward
+    // delivery on reconnect would never happen.
+    const blobId = storeBlob(destHash, data);
     const recipient = clientsByHash.get(destHash);
     if (recipient && recipient !== sender && recipient.readyState === WebSocket.OPEN) {
-        // Recipient is connected — forward directly
-        recipient.send(data, { binary: true });
+        // Recipient appears connected — deliver immediately AND delete from store.
+        // If the send fails (connection dropped between readyState check and write),
+        // the blob stays in the store and will be delivered on the next reconnect.
+        recipient.send(data, { binary: true }, (err) => {
+            if (!err) {
+                // Delivery succeeded — purge from store so it isn't delivered twice
+                stmts.deleteBlob.run(blobId);
+                bumpActivity('fwd');
+            }
+            // On error: blob remains in store for reconnect delivery
+        });
     }
     else {
-        // Recipient offline (or same socket) — store for later delivery
-        storeBlob(destHash, data);
-        // Wake the recipient via push if they have a registered token
+        // Recipient offline (or same socket) — already stored above.
+        bumpActivity('queue');
+        // Wake the recipient via push if they have a registered token.
         const pushReg = getPushRegistration(destHash);
-        if (pushReg)
+        if (pushReg) {
             notifyPush(destHash, pushReg);
+            bumpActivity('wake');
+        }
+        else if (federation) {
+            // No connected client and no push registration — this destHash may
+            // be homed on a federated peer. Forward best-effort. The local
+            // store (above) is kept as a harmless safety net; it expires per
+            // BLOB_TTL like everything else.
+            federation.forwardFromLocal(data);
+        }
     }
 }
 // ============================================================
 // WebSocket server
 // ============================================================
 function handleWebSocketConnection(ws) {
-    ws.on('message', (raw) => {
-        if (raw instanceof ArrayBuffer) {
-            handleRelayPacket(new Uint8Array(raw), ws);
-            return;
-        }
-        if (Buffer.isBuffer(raw)) {
-            handleRelayPacket(new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength), ws);
+    ws.on('message', (raw, isBinary) => {
+        // Binary frames are relay packets
+        if (isBinary) {
+            if (raw instanceof ArrayBuffer) {
+                handleRelayPacket(new Uint8Array(raw), ws);
+            }
+            else if (Buffer.isBuffer(raw)) {
+                handleRelayPacket(new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength), ws);
+            }
             return;
         }
-        // JSON control message
+        // Text frames are JSON control messages
         try {
             const msg = JSON.parse(raw.toString());
             if (msg.type === 'hello' && Array.isArray(msg.destHashes)) {
@@ -422,6 +753,7 @@ function sendJson(res, status, body) {
         'Access-Control-Allow-Origin': '*',
     });
     res.end(payload);
+    recordHttpStatus(status);
 }
 async function handleHttp(req, res) {
     const url = new URL(req.url ?? '/', `http://localhost`);
@@ -430,12 +762,42 @@ async function handleHttp(req, res) {
     if (method === 'OPTIONS') {
         res.writeHead(204, {
             'Access-Control-Allow-Origin': '*',
-            'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-            'Access-Control-Allow-Headers': 'Content-Type',
+            'Access-Control-Allow-Methods': 'GET, POST, PUT, OPTIONS',
+            'Access-Control-Allow-Headers': 'Content-Type, Authorization',
         });
         res.end();
         return;
     }
+    // Anonymous live activity stream (Server-Sent Events) — public, no auth.
+    // Emits a JSON object every ~250ms when the relay handled any traffic in
+    // that window. Counts only — no destination hashes, no IPs, no per-event
+    // metadata. Safe to expose to anyone watching the public site.
+    if (url.pathname === '/events' && method === 'GET') {
+        // Per-IP cap on SSE subscriptions. Each subscriber holds a long-lived
+        // connection; cap prevents a single peer from exhausting socket budget.
+        if (rateLimited(req, res, 'read', RATE_LIMIT_READ))
+            return;
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-store',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no', // disable nginx buffering for SSE
+            'Access-Control-Allow-Origin': '*',
+        });
+        res.write(': connected\n\n');
+        activitySubscribers.add(res);
+        const heartbeat = setInterval(() => {
+            try {
+                res.write(': hb\n\n');
+            }
+            catch { /* ignored */ }
+        }, 15_000);
+        req.on('close', () => {
+            clearInterval(heartbeat);
+            activitySubscribers.delete(res);
+        });
+        return;
+    }
     // Health check
     if (url.pathname === '/health' && method === 'GET') {
         sendJson(res, 200, {
@@ -445,16 +807,77 @@ async function handleHttp(req, res) {
             prekeyEntries: stmts.countPrekeys.get().cnt,
             pushRegistrations: stmts.countPush.get().cnt,
             mediaEntries: stmts.countMedia.get().cnt,
+            opkEntries: stmts.countOpks.get().cnt,
+            archiveEntries: stmts.countArchives.get().cnt,
+            federationPeersConfigured: federation?.stats.peersConfigured ?? 0,
+            federationPeersConnected: federation?.connectedPeerCount() ?? 0,
         });
         return;
     }
+    // Prometheus-format metrics. Includes gauges (current state) and
+    // counters (cumulative since boot). Not rate-limited so a scraper
+    // can poll on its own schedule. Operators wanting to keep this
+    // private should gate it at the reverse proxy.
+    if (url.pathname === '/metrics' && method === 'GET') {
+        const lines = [];
+        const emit = (name, help, type, value, labels) => {
+            lines.push(`# HELP ${name} ${help}`);
+            lines.push(`# TYPE ${name} ${type}`);
+            const labelStr = labels
+                ? `{${Object.entries(labels).map(([k, v]) => `${k}="${v}"`).join(',')}}`
+                : '';
+            lines.push(`${name}${labelStr} ${value}`);
+        };
+        const emitLabeled = (name, help, type, labelName, values) => {
+            lines.push(`# HELP ${name} ${help}`);
+            lines.push(`# TYPE ${name} ${type}`);
+            for (const [label, value] of Object.entries(values)) {
+                lines.push(`${name}{${labelName}="${label}"} ${value}`);
+            }
+        };
+        // Uptime
+        emit('meshwhisper_uptime_seconds', 'Seconds since this node started', 'gauge', Math.floor((Date.now() - NODE_STARTED_AT_MS) / 1000));
+        // Live counts (gauges)
+        emit('meshwhisper_clients_connected', 'Currently connected WebSocket clients', 'gauge', clientsByHash.size);
+        emit('meshwhisper_stored_blobs', 'Encrypted blobs currently queued for offline delivery', 'gauge', stmts.countBlobs.get().cnt);
+        emit('meshwhisper_prekey_entries', 'Registered prekey-bundle entries in the directory', 'gauge', stmts.countPrekeys.get().cnt);
+        emit('meshwhisper_push_registrations', 'Active push-notification registrations', 'gauge', stmts.countPush.get().cnt);
+        emit('meshwhisper_media_entries', 'Encrypted media blobs currently stored', 'gauge', stmts.countMedia.get().cnt);
+        emit('meshwhisper_opk_entries', 'Unused one-time prekeys in the pool', 'gauge', stmts.countOpks.get().cnt);
+        emit('meshwhisper_archive_entries', 'Stored per-identity encrypted archives', 'gauge', stmts.countArchives.get().cnt);
+        // Counters
+        emit('meshwhisper_http_requests_total', 'Total HTTP requests served since startup', 'counter', metrics.httpRequestsTotal);
+        emitLabeled('meshwhisper_http_responses_total', 'HTTP responses by status family (plus 429 broken out)', 'counter', 'status', metrics.httpStatus);
+        emitLabeled('meshwhisper_rate_limit_rejections_total', 'Rate-limit (429) rejections by bucket', 'counter', 'bucket', metrics.rateLimitRejections);
+        emit('meshwhisper_websocket_connections_total', 'Total WebSocket connections accepted since startup', 'counter', metrics.websocketConnectionsTotal);
+        // Federation (zeroes when federation is dormant)
+        emit('meshwhisper_federation_peers_configured', 'Federation peers in the allow-list', 'gauge', federation?.stats.peersConfigured ?? 0);
+        emit('meshwhisper_federation_peers_connected', 'Federation peers with an established handshake', 'gauge', federation?.connectedPeerCount() ?? 0);
+        emit('meshwhisper_federation_forwards_sent_total', 'PacketForward frames sent to peers', 'counter', federation?.stats.forwardsSentTotal ?? 0);
+        emit('meshwhisper_federation_forwards_received_total', 'PacketForward frames received from peers', 'counter', federation?.stats.forwardsReceivedTotal ?? 0);
+        emit('meshwhisper_federation_delivered_locally_total', 'Federation packets delivered to a connected local client', 'counter', federation?.stats.deliveredLocallyTotal ?? 0);
+        emit('meshwhisper_federation_stored_locally_total', 'Federation packets stored for a local offline device', 'counter', federation?.stats.storedLocallyTotal ?? 0);
+        emit('meshwhisper_federation_forwarded_onward_total', 'Federation packets forwarded to further peers', 'counter', federation?.stats.forwardedOnwardTotal ?? 0);
+        emit('meshwhisper_federation_drops_duplicate_total', 'Federation packets dropped by the packet-id cache', 'counter', federation?.stats.dropsDuplicateTotal ?? 0);
+        emit('meshwhisper_federation_drops_ttl_total', 'Federation packets dropped by hop-count exhaustion', 'counter', federation?.stats.dropsTtlTotal ?? 0);
+        emit('meshwhisper_federation_handshake_failures_total', 'Failed federation handshakes', 'counter', federation?.stats.handshakeFailuresTotal ?? 0);
+        emit('meshwhisper_federation_drops_rate_limited_total', 'Federation frames dropped by per-peer rate limiting', 'counter', federation?.stats.dropsRateLimitedTotal ?? 0);
+        emit('meshwhisper_federation_handshake_rejections_blocked_total', 'Handshakes rejected by the blocklist', 'counter', federation?.stats.handshakeRejectionsBlockedTotal ?? 0);
+        const body = lines.join('\n') + '\n';
+        res.writeHead(200, {
+            'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
+            'Content-Length': Buffer.byteLength(body),
+            'Access-Control-Allow-Origin': '*',
+        });
+        res.end(body);
+        recordHttpStatus(200);
+        return;
+    }
     // Register prekey bundle
-    // POST /directory  { namespace, publicKey, bundle }
+    // POST /directory  { namespace, publicKey, bundle, username? }
     if (url.pathname === '/directory' && method === 'POST') {
-        if (!checkRateLimit(getClientIp(req), 'dir', RATE_LIMIT_DIR)) {
-            sendJson(res, 429, { error: 'Too many requests' });
+        if (rateLimited(req, res, 'dir', RATE_LIMIT_DIR))
             return;
-        }
         let body;
         try {
             body = JSON.parse(await parseBody(req));
@@ -470,35 +893,254 @@ async function handleHttp(req, res) {
             sendJson(res, 400, { error: 'Missing required fields: namespace, publicKey, bundle' });
             return;
         }
-        registerPrekey(namespace, publicKey, bundle);
+        let username = null;
+        if (typeof body.username === 'string' && body.username) {
+            username = validateUsername(body.username);
+            if (!username) {
+                sendJson(res, 400, { error: 'Invalid username: 3–30 chars, a–z 0–9 _ -' });
+                return;
+            }
+        }
+        let transferAuth = null;
+        if (body.transferAuth && typeof body.transferAuth === 'object') {
+            const ta = body.transferAuth;
+            if (typeof ta.fromPublicKey === 'string' &&
+                typeof ta.expiresAt === 'number' &&
+                typeof ta.signature === 'string') {
+                transferAuth = {
+                    fromPublicKey: ta.fromPublicKey,
+                    expiresAt: ta.expiresAt,
+                    signature: ta.signature,
+                };
+            }
+            else {
+                sendJson(res, 400, { error: 'Invalid transferAuth shape' });
+                return;
+            }
+        }
+        const result = registerPrekeyTx(namespace, publicKey, bundle, username, transferAuth);
+        if (result === 'username_taken') {
+            sendJson(res, 409, {
+                error: 'Username already claimed by a different identity in this namespace',
+            });
+            return;
+        }
+        if (result === 'invalid_transfer_auth') {
+            sendJson(res, 403, {
+                error: 'transferAuth invalid: signature, expiry, or sender mismatch',
+            });
+            return;
+        }
         sendJson(res, 200, { ok: true });
         return;
     }
+    // Set or read namespace policy
+    // POST /namespace-policy { namespace, usernamePolicy }
+    //   First writer wins. Once set, the policy is sticky. Re-POSTing the
+    //   same value returns 200; a different value returns 409.
+    // GET  /namespace-policy?namespace=
+    //   Returns the effective policy. Falls back to defaults when no row.
+    if (url.pathname === '/namespace-policy' && method === 'POST') {
+        if (rateLimited(req, res, 'dir', RATE_LIMIT_DIR))
+            return;
+        let body;
+        try {
+            body = JSON.parse(await parseBody(req));
+        }
+        catch {
+            sendJson(res, 400, { error: 'Invalid JSON body' });
+            return;
+        }
+        const { namespace, usernamePolicy } = body;
+        if (typeof namespace !== 'string' || !namespace) {
+            sendJson(res, 400, { error: 'Missing required field: namespace' });
+            return;
+        }
+        if (usernamePolicy !== 'signed-transfer' && usernamePolicy !== 'last-writer-wins') {
+            sendJson(res, 400, {
+                error: "usernamePolicy must be 'signed-transfer' or 'last-writer-wins'",
+            });
+            return;
+        }
+        stmts.insertNamespacePolicy.run(namespace, usernamePolicy, Date.now());
+        const current = getNamespaceUsernamePolicy(namespace);
+        if (current !== usernamePolicy) {
+            sendJson(res, 409, {
+                error: 'Namespace policy already set to a different value',
+                currentPolicy: current,
+            });
+            return;
+        }
+        sendJson(res, 200, { ok: true, usernamePolicy: current });
+        return;
+    }
+    if (url.pathname === '/namespace-policy' && method === 'GET') {
+        if (rateLimited(req, res, 'read', RATE_LIMIT_READ))
+            return;
+        const namespace = url.searchParams.get('namespace');
+        if (!namespace) {
+            sendJson(res, 400, { error: 'Missing query param: namespace' });
+            return;
+        }
+        sendJson(res, 200, {
+            namespace,
+            usernamePolicy: getNamespaceUsernamePolicy(namespace),
+        });
+        return;
+    }
     // Lookup prekey bundle
     // GET /directory?namespace=&publicKey=
+    // GET /directory?namespace=&username=alice
     if (url.pathname === '/directory' && method === 'GET') {
+        // Username/publicKey lookup is the natural endpoint for an enumeration
+        // attempt — bucket separately from writes so a busy lookup workload
+        // doesn't starve registrations and vice versa.
+        if (rateLimited(req, res, 'read', RATE_LIMIT_READ))
+            return;
+        const namespace = url.searchParams.get('namespace');
+        const usernameParam = url.searchParams.get('username');
+        const publicKeyParam = url.searchParams.get('publicKey');
+        if (!namespace) {
+            sendJson(res, 400, { error: 'Missing query param: namespace' });
+            return;
+        }
+        if (usernameParam) {
+            const username = validateUsername(usernameParam);
+            if (!username) {
+                sendJson(res, 400, { error: 'Invalid username' });
+                return;
+            }
+            const result = lookupPrekeyByUsername(namespace, username);
+            if (!result) {
+                sendJson(res, 404, { error: 'User not found' });
+                return;
+            }
+            sendJson(res, 200, { bundle: result.bundle, publicKey: result.publicKey, username });
+            return;
+        }
+        if (!publicKeyParam) {
+            sendJson(res, 400, { error: 'Missing query param: publicKey or username' });
+            return;
+        }
+        const result = lookupPrekeyByPublicKey(namespace, publicKeyParam);
+        if (!result) {
+            sendJson(res, 404, { error: 'Prekey bundle not found' });
+            return;
+        }
+        sendJson(res, 200, { bundle: result.bundle, ...(result.username ? { username: result.username } : {}) });
+        return;
+    }
+    // Upload one-time pre-keys for a user
+    // POST /opks  { namespace, publicKey, opks: string[] }  (base64 public keys)
+    if (url.pathname === '/opks' && method === 'POST') {
+        if (rateLimited(req, res, 'dir', RATE_LIMIT_DIR))
+            return;
+        let body;
+        try {
+            body = JSON.parse(await parseBody(req));
+        }
+        catch {
+            sendJson(res, 400, { error: 'Invalid JSON body' });
+            return;
+        }
+        const { namespace, publicKey, opks } = body;
+        if (typeof namespace !== 'string' || !namespace ||
+            typeof publicKey !== 'string' || !publicKey ||
+            !Array.isArray(opks) || opks.length === 0) {
+            sendJson(res, 400, { error: 'Missing required fields: namespace, publicKey, opks[]' });
+            return;
+        }
+        const MAX_OPKS_PER_UPLOAD = 20;
+        const MAX_OPKS_PER_IDENTITY = 100;
+        const batch = opks.slice(0, MAX_OPKS_PER_UPLOAD).filter((o) => typeof o === 'string' && o.length > 0);
+        const identityKey = directoryKey(namespace, publicKey);
+        const existing = stmts.countOpksForKey.get(identityKey).cnt;
+        const canStore = Math.max(0, MAX_OPKS_PER_IDENTITY - existing);
+        const toStore = batch.slice(0, canStore);
+        const now = Date.now();
+        for (const opk of toStore) {
+            stmts.insertOpk.run(identityKey, opk, now);
+        }
+        sendJson(res, 200, { ok: true, stored: toStore.length });
+        return;
+    }
+    // Purge all OPKs for a (namespace, publicKey) pair.
+    // DELETE /opks  { namespace, publicKey }
+    // Authorization: Bearer <token>
+    //
+    // TOFU auth: first DELETE for a given publicKey establishes the auth hash;
+    // subsequent DELETEs must present a token whose SHA-256 matches the stored
+    // hash. Identity_pubkey is cross-namespace so the same person purging
+    // their pool in different namespaces uses the same token.
+    //
+    // Used by the SDK's one-shot OPK-pool migration to clear zombie entries
+    // left by the pre-fix bulk re-upload bug. Apps don't need to call this
+    // directly — the SDK runs it on first init after the fix.
+    if (url.pathname === '/opks' && method === 'DELETE') {
+        if (rateLimited(req, res, 'dir', RATE_LIMIT_DIR))
+            return;
+        const auth = req.headers['authorization'];
+        if (!auth || !auth.startsWith('Bearer ')) {
+            sendJson(res, 401, { error: 'Missing bearer token' });
+            return;
+        }
+        const token = auth.slice('Bearer '.length).trim();
+        let body;
+        try {
+            body = JSON.parse(await parseBody(req));
+        }
+        catch {
+            sendJson(res, 400, { error: 'Invalid JSON body' });
+            return;
+        }
+        const { namespace, publicKey } = body;
+        if (typeof namespace !== 'string' || !namespace || typeof publicKey !== 'string' || !publicKey) {
+            sendJson(res, 400, { error: 'Missing required fields: namespace, publicKey' });
+            return;
+        }
+        const incomingHash = nodeCrypto.createHash('sha256').update(token).digest('hex');
+        // TOFU: insert-or-ignore establishes the hash on first call. Subsequent
+        // calls succeed only if the hash matches what's already stored.
+        stmts.insertOpkAuthHash.run(publicKey, incomingHash, Date.now());
+        const existing = stmts.getOpkAuthHash.get(publicKey);
+        if (!existing || existing.auth_hash !== incomingHash) {
+            sendJson(res, 403, { error: 'Invalid OPK pool token' });
+            return;
+        }
+        const result = stmts.deleteOpksForKey.run(directoryKey(namespace, publicKey));
+        sendJson(res, 200, { ok: true, deleted: result.changes });
+        return;
+    }
+    // Claim one one-time pre-key for a user (atomic — removes it from the pool)
+    // GET /opks/claim?namespace=&publicKey=
+    if (url.pathname === '/opks/claim' && method === 'GET') {
+        // OPK claim is a write-like operation (each call atomically consumes a
+        // one-time prekey from the pool). Bucket with the other write endpoints
+        // so the directory budget gates abuse — an attacker draining a victim's
+        // OPK pool to force fallback to the signed-prekey-only handshake is the
+        // primary risk this addresses.
+        if (rateLimited(req, res, 'dir', RATE_LIMIT_DIR))
+            return;
         const namespace = url.searchParams.get('namespace');
         const publicKey = url.searchParams.get('publicKey');
         if (!namespace || !publicKey) {
             sendJson(res, 400, { error: 'Missing query params: namespace, publicKey' });
             return;
         }
-        const bundle = lookupPrekey(namespace, publicKey);
-        if (!bundle) {
-            sendJson(res, 404, { error: 'Prekey bundle not found' });
+        const opk = claimOpkTx(directoryKey(namespace, publicKey));
+        if (!opk) {
+            sendJson(res, 404, { error: 'No one-time pre-keys available' });
             return;
         }
-        sendJson(res, 200, { bundle });
+        sendJson(res, 200, { opk });
         return;
     }
     // Upload encrypted media blob
     // POST /media  (binary body, Content-Length required)
     // Returns: { id, url, expiresAt }
     if (url.pathname === '/media' && method === 'POST') {
-        if (!checkRateLimit(getClientIp(req), 'media', RATE_LIMIT_MEDIA)) {
-            sendJson(res, 429, { error: 'Too many requests' });
+        if (rateLimited(req, res, 'media', RATE_LIMIT_MEDIA))
             return;
-        }
         const contentLength = parseInt(req.headers['content-length'] ?? '0', 10);
         if (contentLength > MAX_MEDIA_SIZE) {
             sendJson(res, 413, { error: `Payload too large (max ${MAX_MEDIA_SIZE} bytes)` });
@@ -535,6 +1177,8 @@ async function handleHttp(req, res) {
     // GET /media/:id
     const mediaMatch = url.pathname.match(/^\/media\/([0-9a-f]{32})$/);
     if (mediaMatch && method === 'GET') {
+        if (rateLimited(req, res, 'read', RATE_LIMIT_READ))
+            return;
         const data = fetchMedia(mediaMatch[1]);
         if (!data) {
             sendJson(res, 404, { error: 'Media not found or expired' });
@@ -549,6 +1193,78 @@ async function handleHttp(req, res) {
         res.end(data);
         return;
     }
+    // Upload encrypted archive
+    // PUT /archive/:peerId  Authorization: Bearer <token>
+    const archivePutMatch = url.pathname.match(/^\/archive\/([0-9a-f]{64})$/);
+    if (archivePutMatch && method === 'PUT') {
+        if (rateLimited(req, res, 'archive', RATE_LIMIT_ARCHIVE))
+            return;
+        const peerId = archivePutMatch[1];
+        const authHeader = req.headers['authorization'] ?? '';
+        const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7).trim() : '';
+        if (!token) {
+            sendJson(res, 401, { error: 'Missing Authorization header' });
+            return;
+        }
+        const contentLength = parseInt(req.headers['content-length'] ?? '0', 10);
+        if (contentLength > MAX_ARCHIVE_SIZE) {
+            sendJson(res, 413, { error: `Archive too large (max ${MAX_ARCHIVE_SIZE} bytes)` });
+            return;
+        }
+        const chunks = [];
+        let received = 0;
+        let aborted = false;
+        await new Promise((resolve, reject) => {
+            req.on('data', (chunk) => {
+                received += chunk.length;
+                if (received > MAX_ARCHIVE_SIZE) {
+                    aborted = true;
+                    req.destroy();
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            req.on('end', resolve);
+            req.on('error', reject);
+        });
+        if (aborted) {
+            sendJson(res, 413, { error: `Archive too large (max ${MAX_ARCHIVE_SIZE} bytes)` });
+            return;
+        }
+        const data = Buffer.concat(chunks);
+        const incomingHash = nodeCrypto.createHash('sha256').update(token).digest('hex');
+        // First write: INSERT OR IGNORE sets the auth_hash. The upsert only
+        // succeeds when auth_hash matches, preventing overwrites by other parties.
+        stmts.insertArchiveFirstTime.run(peerId, incomingHash, data, Date.now(), data.length);
+        const existing = stmts.getArchiveAuthHash.get(peerId);
+        if (!existing || existing.auth_hash !== incomingHash) {
+            sendJson(res, 403, { error: 'Invalid archive token' });
+            return;
+        }
+        stmts.upsertArchive.run(peerId, incomingHash, data, Date.now(), data.length);
+        sendJson(res, 200, { ok: true, size: data.length });
+        return;
+    }
+    // Download encrypted archive
+    // GET /archive/:peerId  (no auth — content is client-encrypted)
+    const archiveGetMatch = url.pathname.match(/^\/archive\/([0-9a-f]{64})$/);
+    if (archiveGetMatch && method === 'GET') {
+        if (rateLimited(req, res, 'read', RATE_LIMIT_READ))
+            return;
+        const row = stmts.getArchiveData.get(archiveGetMatch[1]);
+        if (!row) {
+            sendJson(res, 404, { error: 'Archive not found' });
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'application/octet-stream',
+            'Content-Length': row.data.length,
+            'Access-Control-Allow-Origin': '*',
+            'Cache-Control': 'no-store',
+        });
+        res.end(row.data);
+        return;
+    }
     sendJson(res, 404, { error: 'Not found' });
 }
 // ============================================================
@@ -560,11 +1276,89 @@ const httpServer = http.createServer((req, res) => {
         res.writeHead(500).end();
     });
 });
+// ============================================================
+// Federation (docs/federation.md v1)
+//
+// Dormant unless a peers file with at least one entry exists. The
+// classifyLocal callback answers "can this packet be handled here?":
+//   - a connected client holds the destHash       → deliver  ('delivered')
+//   - a push registration exists for the destHash → store+wake ('stored';
+//     the device is homed here, currently offline)
+//   - neither                                     → 'unknown' (forward onward)
+// ============================================================
+const FEDERATION_KEY_FILE = process.env.FEDERATION_KEY_FILE
+    ?? path.join(path.dirname(DB_PATH), 'federation-key.json');
+const FEDERATION_PEERS_FILE = process.env.FEDERATION_PEERS_FILE
+    ?? path.join(path.dirname(DB_PATH), 'federation-peers.json');
+const FEDERATION_BLOCKLIST_FILE = process.env.FEDERATION_BLOCKLIST_FILE
+    ?? path.join(path.dirname(DB_PATH), 'federation-blocklist.json');
+// FEDERATION_MODE: 'off' | 'allowlist' | 'open'.
+//   off       — dormant regardless of peers file
+//   allowlist — only pre-approved pubkeys; v1 behavior
+//   open      — accept any peer completing the handshake (recommended once
+//               you're comfortable; per-peer rate limiting is the abuse
+//               boundary). Peers file becomes the outbound bootstrap list.
+// Unset (back-compat): allowlist when the peers file has entries, else off.
+const federationPeersConfig = loadPeersConfig(FEDERATION_PEERS_FILE);
+const FEDERATION_MODE_RAW = (process.env.FEDERATION_MODE ?? '').toLowerCase();
+const federationMode = FEDERATION_MODE_RAW === 'open' ? 'open'
+    : FEDERATION_MODE_RAW === 'allowlist' ? 'allowlist'
+        : FEDERATION_MODE_RAW === 'off' ? 'off'
+            : (federationPeersConfig.length > 0 ? 'allowlist' : 'off');
+const FEDERATION_MAX_PEERS = parseInt(process.env.FEDERATION_MAX_PEERS ?? '64', 10);
+const FEDERATION_RATE_LIMIT = parseInt(process.env.FEDERATION_RATE_LIMIT ?? '6000', 10); // frames/min/peer
+const federation = federationMode !== 'off'
+    ? new FederationManager({
+        key: loadOrCreateFederationKey(FEDERATION_KEY_FILE),
+        peers: federationPeersConfig,
+        mode: federationMode,
+        blockedPubkeys: loadBlocklist(FEDERATION_BLOCKLIST_FILE),
+        maxPeers: FEDERATION_MAX_PEERS,
+        rateLimitPerMin: FEDERATION_RATE_LIMIT,
+        classifyLocal: (packet) => {
+            const destHash = readDestHash(packet);
+            if (!destHash)
+                return 'delivered'; // malformed — swallow, don't propagate
+            const recipient = clientsByHash.get(destHash);
+            if (recipient && recipient.readyState === WebSocket.OPEN) {
+                // Same store-then-deliver race protection as the client path.
+                const blobId = storeBlob(destHash, packet);
+                recipient.send(packet, { binary: true }, (err) => {
+                    if (!err)
+                        stmts.deleteBlob.run(blobId);
+                });
+                bumpActivity('fwd');
+                return 'delivered';
+            }
+            const pushReg = getPushRegistration(destHash);
+            if (pushReg) {
+                storeBlob(destHash, packet);
+                notifyPush(destHash, pushReg);
+                bumpActivity('wake');
+                return 'stored';
+            }
+            return 'unknown';
+        },
+    })
+    : null;
+if (federation) {
+    federation.start();
+    console.log(`[federation] mode=${federationMode}, ${federationPeersConfig.length} configured peer(s), max ${FEDERATION_MAX_PEERS}`);
+}
 const wss = new WebSocketServer({ noServer: true });
 wss.on('connection', (ws) => {
+    metrics.websocketConnectionsTotal++;
     handleWebSocketConnection(ws);
 });
 httpServer.on('upgrade', (req, socket, head) => {
+    // Federation peers negotiate the meshwhisper-federation.v1 subprotocol;
+    // everything else is a regular client-relay connection.
+    const offered = (req.headers['sec-websocket-protocol'] ?? '')
+        .split(',').map((s) => s.trim());
+    if (federation && offered.includes(FEDERATION_SUBPROTOCOL)) {
+        federation.handleUpgrade(req, socket, head);
+        return;
+    }
     wss.handleUpgrade(req, socket, head, (ws) => {
         wss.emit('connection', ws, req);
     });
@@ -576,11 +1370,16 @@ const pruneInterval = setInterval(() => {
     pruneRateLimitState();
 }, PRUNE_INTERVAL_MS);
 pruneInterval.unref();
-httpServer.listen(PORT, () => {
+// Default to '::' (IPv6 wildcard) which also accepts IPv4 on Linux (bindv6only=0).
+// Set LISTEN_HOST=0.0.0.0 to restrict to IPv4 only.
+const LISTEN_HOST = process.env.LISTEN_HOST ?? '::';
+httpServer.listen(PORT, LISTEN_HOST, () => {
     console.log(`MeshWhisper Node listening on port ${PORT}`);
     console.log(`  Relay:     ws://localhost:${PORT}`);
     console.log(`  Directory: http://localhost:${PORT}/directory`);
+    console.log(`  OPKs:      http://localhost:${PORT}/opks`);
     console.log(`  Media:     http://localhost:${PORT}/media`);
+    console.log(`  Archive:   http://localhost:${PORT}/archive/:peerId`);
     console.log(`  Health:    http://localhost:${PORT}/health`);
     console.log(`  Database:  ${DB_PATH}`);
     console.log(`  Blob TTL:  ${BLOB_TTL_HOURS}h`);