initial commit

Dockerfile

@@ -0,0 +1,32 @@
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+# Install deps first (layer cache friendly)
+COPY package*.json ./
+RUN npm ci --only=production=false
+
+COPY . .
+RUN npm run build
+
+# ── Production image ──────────────────────────────────────────────────────────
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+# Non-root user for HF container security
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+
+# Copy only what we need
+COPY --from=builder /app/dist         ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+
+USER appuser
+
+# HF Spaces requires port 7860
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -qO- http://localhost:7860/health || exit 1
+
+CMD ["node", "dist/index.js"]

README.md

@@ -1,11 +1,194 @@
+# P2P Signal Server
+
+Real-time WebRTC signaling server for 10,000 concurrent users.  
+Runs on **Hugging Face Spaces Free Tier** (Docker, port 7860).
+
+---
+
+## Architecture
+
+```
+Client A ──WS──► HF Space (Signal Server)
+                     │
+                     ├─ Redis Bucket 1 (Presence)   uid→socketId, online/offline
+                     ├─ Redis Bucket 2 (Msg Queue)  offline_msgs:{uid} list
+                     ├─ MongoDB Atlas               user profiles, friend lists
+                     └─ Supabase Storage            media files (server sees 0 bytes)
+
+Client A ◄──────────────────────────────► Client B   (WebRTC P2P after handshake)
+         ◄── WS relay fallback if ICE fails ─────────►
+```
+
+---
+
+## Quick Start
+
+### 1. Clone & install
+
+```bash
+git clone https://github.com/you/p2p-signal-server
+cd p2p-signal-server
+npm install
+cp .env.example .env
+# Fill in all values in .env
+npm run dev
+```
+
+### 2. Build & run (Docker)
+
+```bash
+docker build -t p2p-signal .
+docker run --env-file .env -p 7860:7860 p2p-signal
+```
+
 ---
-title: Chatapi
-emoji: 🏆
-colorFrom: yellow
-colorTo: yellow
-sdk: docker
-pinned: false
-short_description: A simple chatting api
+
+## Required Secrets
+
+Add all of these to **HF Spaces → Settings → Repository Secrets**.
+
+| Variable | How to get it |
+|---|---|
+| `JWT_SECRET` | `node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"` |
+| `REDIS_PRESENCE_URL` | [Upstash](https://upstash.com) → Create Redis DB #1 → Copy Redis URL |
+| `REDIS_MESSAGE_URL` | Upstash → Create Redis DB **#2** (separate!) → Copy Redis URL |
+| `MONGO_URI` | [MongoDB Atlas](https://cloud.mongodb.com) → M0 Free → Connect → Driver URL |
+| `SUPABASE_URL` | [Supabase](https://supabase.com) → Project Settings → API → Project URL |
+| `SUPABASE_SERVICE_KEY` | Supabase → Project Settings → API → `service_role` key |
+| `SUPABASE_BUCKET` | Create a bucket named `media` in Supabase Storage, set to **public** |
+| `TURN_URL` | [metered.ca/tools/openrelay](https://www.metered.ca/tools/openrelay/) free TURN |
+| `TURN_USERNAME` | From the same TURN provider |
+| `TURN_CREDENTIAL` | From the same TURN provider |
+| `ALLOWED_ORIGINS` | Your frontend domain(s), comma-separated e.g. `https://myapp.vercel.app` |
+
+Optional (have defaults):
+
+| Variable | Default | Notes |
+|---|---|---|
+| `PORT` | `7860` | Must stay 7860 for HF Spaces |
+| `STUN_SERVERS` | Google STUN | Comma-separated stun: URIs |
+| `PRESENCE_TTL_S` | `60` | Redis TTL for online status |
+| `OFFLINE_MSG_TTL_S` | `604800` | 7 days — how long to hold queued msgs |
+| `HEARTBEAT_INTERVAL_MS` | `30000` | Client sends ping every 30s |
+| `MAX_FILE_SIZE_MB` | `99` | Max single file size |
+| `MAX_FILE_COUNT` | `10` | Max files per upload request |
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## HF Spaces Deploy
+
+1. Create a new Space → **Docker** SDK
+2. Push this repo to the Space's git remote
+3. Add all secrets in Space settings
+4. The Space will auto-build via the Dockerfile
+
+Health check: `GET /health` → `{ status: 'ok', connections: N, ts: epoch }`
+
+---
+
+## WebSocket Protocol
+
+Connect: `wss://your-space.hf.space?token=<JWT>`
+
+### Client → Server
+
+```jsonc
+// Heartbeat (every 30s)
+{ "type": "heartbeat", "payload": {} }
+
+// Send a text message
+{ "type": "message", "payload": { "toUid": "bob", "type": "text", "content": "Hello" } }
+
+// Send a media message (after uploading to Supabase)
+{ "type": "message", "payload": { "toUid": "bob", "type": "media", "content": "https://...", "mediaType": "image/jpeg" } }
+
+// Request signed upload URLs
+{ "type": "get-upload-url", "requestId": "abc123",
+  "payload": { "files": [{ "fileName": "photo.jpg", "mimeType": "image/jpeg", "sizeBytes": 1048576 }] } }
+
+// WebRTC offer
+{ "type": "offer", "payload": { "toUid": "bob", "sdp": { ...RTCSessionDescription } } }
+
+// WebRTC answer
+{ "type": "answer", "payload": { "toUid": "alice", "sdp": { ...RTCSessionDescription } } }
+
+// ICE candidate
+{ "type": "ice-candidate", "payload": { "toUid": "bob", "candidate": { ...RTCIceCandidate } } }
+
+// WS relay fallback (when ICE fails)
+{ "type": "relay", "payload": { "toUid": "bob", "data": { ...anything } } }
+
+// Friend actions
+{ "type": "friend", "payload": { "action": "send-request", "targetUid": "bob" } }
+{ "type": "friend", "payload": { "action": "accept",       "targetUid": "alice" } }
+{ "type": "friend", "payload": { "action": "reject",       "targetUid": "alice" } }
+{ "type": "friend", "payload": { "action": "remove",       "targetUid": "bob" } }
+{ "type": "friend", "payload": { "action": "list" } }
+{ "type": "friend", "payload": { "action": "status", "targetUid": "bob" } }
+```
+
+### Server → Client
+
+```jsonc
+{ "type": "connected",      "payload": { "uid": "...", "socketId": "..." } }
+{ "type": "ice-servers",    "payload": { "iceServers": [...] } }
+{ "type": "offline-flush",  "payload": { "messages": [...], "count": N } }
+{ "type": "message",        "payload": { "fromUid": "...", "content": "...", ... } }
+{ "type": "peer-online",    "payload": { "uid": "bob" } }
+{ "type": "peer-offline",   "payload": { "uid": "bob" } }
+{ "type": "upload-url",     "payload": { "urls": [{ "signedUrl", "objectPath", "publicUrl" }] } }
+{ "type": "offer",          "payload": { "fromUid": "...", "sdp": {...} } }
+{ "type": "answer",         "payload": { "fromUid": "...", "sdp": {...} } }
+{ "type": "ice-candidate",  "payload": { "fromUid": "...", "candidate": {...} } }
+{ "type": "relay",          "payload": { "fromUid": "...", "data": {...} } }
+{ "type": "error",          "payload": { "message": "..." } }
+```
+
+---
+
+## File Upload Flow
+
+```
+1. Client → server: { type: 'get-upload-url', payload: { files: [...] } }
+2. Server → Supabase: createSignedUploadUrl (no bytes transferred)
+3. Server → client: { type: 'upload-url', payload: { urls: [...] } }
+4. Client → Supabase: PUT file directly (server sees 0 bytes, HF RAM unaffected)
+5. Client → server: { type: 'message', payload: { type: 'media', content: publicUrl } }
+6. Server → recipient: deliver or queue offline
+```
+
+---
+
+## File Structure
+
+```
+src/
+├── index.ts                    # Entry point, HTTP+WS server
+├── config.ts                   # All env vars, ICE server builder
+├── db/
+│   └── mongo.ts                # MongoDB connection, User + Message models
+├── redis/
+│   ├── presenceClient.ts       # Bucket 1: uid→socketId, online/offline
+│   └── messageClient.ts        # Bucket 2: offline message queue
+├── services/
+│   ├── connectionRegistry.ts   # In-process socket map + zombie pruner
+│   ├── supabaseService.ts      # Signed URL generation, file validation
+│   └── friendService.ts        # Friend request/accept/remove logic
+├── handlers/
+│   ├── connectionHandler.ts    # WS connect/disconnect, message router
+│   ├── signalingHandler.ts     # WebRTC SDP/ICE forwarding
+│   ├── messageHandler.ts       # Text/media delivery + offline queue
+│   ├── fileHandler.ts          # Upload URL generation
+│   └── friendHandler.ts        # Friend CRUD over WS
+├── middleware/
+│   └── rateLimiter.ts          # Token bucket, 20 conn/IP/60s
+├── models/
+│   └── friend.ts               # FriendRequest mongoose model
+└── utils/
+    ├── jwt.ts                  # Token verification (uid always from JWT)
+    ├── logger.ts               # Structured JSON logger
+    └── protocol.ts             # WS message types + safe serialization
+
+client-reference/
+└── client.ts                   # Browser client (copy into your frontend)
+```

client-reference/client.ts

@@ -0,0 +1,429 @@
+/**
+ * P2P Signal Client — Browser Reference Implementation
+ *
+ * Drop this into your frontend (React/Vue/Vanilla).
+ * It handles:
+ *   - WS connection + JWT auth
+ *   - Heartbeat loop
+ *   - WebRTC offer/answer/ICE
+ *   - Auto-fallback to WS relay on ICE failure
+ *   - File upload via Supabase signed URL
+ *   - Offline message receipt on reconnect
+ *
+ * Usage:
+ *   const client = new P2PClient({ serverUrl, token, onMessage, onPeerOnline, onPeerOffline });
+ *   await client.connect();
+ *   await client.sendMessage({ toUid, type: 'text', content: 'Hello!' });
+ *   await client.callPeer(peerUid);  // initiates WebRTC
+ */
+
+export interface P2PClientOptions {
+  serverUrl: string;       // wss://your-space.hf.space
+  token: string;           // JWT from your auth system
+  onMessage?: (msg: EnvelopeMessage) => void;
+  onPeerOnline?: (uid: string) => void;
+  onPeerOffline?: (uid: string) => void;
+  onOfflineFlush?: (messages: EnvelopeMessage[]) => void;
+  onP2PData?: (fromUid: string, data: unknown) => void;  // P2P channel data
+  heartbeatIntervalMs?: number;
+}
+
+export interface EnvelopeMessage {
+  fromUid: string;
+  toUid: string;
+  type: 'text' | 'media';
+  content: string;
+  mediaType?: string;
+  sentAt: number;
+}
+
+interface IceServerConfig {
+  urls: string;
+  username?: string;
+  credential?: string;
+}
+
+export class P2PClient {
+  private ws: WebSocket | null = null;
+  private myUid: string | null = null;
+  private socketId: string | null = null;
+  private iceServers: IceServerConfig[] = [];
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectAttempts = 0;
+
+  // uid → RTCPeerConnection
+  private peerConnections = new Map<string, RTCPeerConnection>();
+  // uid → RTCDataChannel (P2P)
+  private dataChannels = new Map<string, RTCDataChannel>();
+  // uid → 'p2p' | 'relay' (fallback mode)
+  private peerMode = new Map<string, 'p2p' | 'relay'>();
+
+  private opts: Required<P2PClientOptions>;
+
+  constructor(opts: P2PClientOptions) {
+    this.opts = {
+      heartbeatIntervalMs: 30_000,
+      onMessage: () => {},
+      onPeerOnline: () => {},
+      onPeerOffline: () => {},
+      onOfflineFlush: () => {},
+      onP2PData: () => {},
+      ...opts,
+    };
+  }
+
+  // ── Connection ─────────────────────────────────────────────────────────────
+
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const url = `${this.opts.serverUrl}?token=${encodeURIComponent(this.opts.token)}`;
+      this.ws = new WebSocket(url);
+      this.ws.binaryType = 'arraybuffer';
+
+      this.ws.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.startHeartbeat();
+      };
+
+      this.ws.onmessage = (evt) => {
+        const msg = this.parseServer(evt.data as string);
+        if (!msg) return;
+        this.handleServer(msg, resolve, reject);
+      };
+
+      this.ws.onclose = () => {
+        this.stopHeartbeat();
+        this.scheduleReconnect();
+      };
+
+      this.ws.onerror = () => {
+        reject(new Error('WebSocket connection failed'));
+      };
+    });
+  }
+
+  disconnect(): void {
+    this.stopHeartbeat();
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.ws?.close();
+  }
+
+  // ── Heartbeat ──────────────────────────────────────────────────────────────
+
+  private startHeartbeat(): void {
+    this.heartbeatTimer = setInterval(() => {
+      this.send('heartbeat', {});
+    }, this.opts.heartbeatIntervalMs);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  // ── Reconnect ──────────────────────────────────────────────────────────────
+
+  private scheduleReconnect(): void {
+    const delay = Math.min(1000 * 2 ** this.reconnectAttempts, 30_000);
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(() => {
+      this.connect().catch(() => {}); // Will schedule again on failure
+    }, delay);
+  }
+
+  // ── Sending ────────────────────────────────────────────────────────────────
+
+  private send(type: string, payload: Record<string, unknown>, requestId?: string): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+    this.ws.send(JSON.stringify({ type, payload, requestId }));
+  }
+
+  /** Send a text or media message to a peer */
+  sendMessage(opts: {
+    toUid: string;
+    type: 'text' | 'media';
+    content: string;
+    mediaType?: string;
+  }): void {
+    // If P2P channel is open and healthy, use it
+    const dc = this.dataChannels.get(opts.toUid);
+    const mode = this.peerMode.get(opts.toUid);
+
+    if (mode === 'p2p' && dc?.readyState === 'open') {
+      dc.send(JSON.stringify({ ...opts, fromUid: this.myUid, sentAt: Date.now() }));
+      return;
+    }
+
+    // Otherwise use WS signaling server (relay or direct delivery)
+    this.send('message', {
+      toUid: opts.toUid,
+      type: opts.type,
+      content: opts.content,
+      mediaType: opts.mediaType ?? null,
+      clientMsgId: crypto.randomUUID(),
+    });
+  }
+
+  // ── File upload ────────────────────────────────────────────────────────────
+
+  /**
+   * Request signed upload URLs and upload files directly to Supabase.
+   * Returns array of public URLs for use in sendMessage({ type: 'media' }).
+   */
+  async uploadFiles(files: File[]): Promise<string[]> {
+    const requestId = crypto.randomUUID();
+
+    // Request signed URLs from server
+    const urlsPromise = this.waitForRequestId<{ urls: Array<{ signedUrl: string; publicUrl: string; fileName: string }> }>(
+      requestId
+    );
+
+    this.send('get-upload-url', {
+      files: files.map(f => ({
+        fileName: f.name,
+        mimeType: f.type,
+        sizeBytes: f.size,
+      })),
+    }, requestId);
+
+    const { urls } = await urlsPromise;
+
+    // Upload each file directly to Supabase (server sees 0 bytes)
+    const publicUrls = await Promise.all(
+      urls.map(async ({ signedUrl, publicUrl, fileName }, i) => {
+        const file = files.find(f => f.name === fileName) ?? files[i];
+        await fetch(signedUrl, {
+          method: 'PUT',
+          headers: { 'Content-Type': file.type },
+          body: file,
+        });
+        return publicUrl;
+      })
+    );
+
+    return publicUrls;
+  }
+
+  // ── WebRTC ─────────────────────────────────────────────────────────────────
+
+  /** Initiate a WebRTC connection to peerUid */
+  async callPeer(peerUid: string): Promise<void> {
+    const pc = this.createPeerConnection(peerUid);
+
+    // Create data channel (caller side)
+    const dc = pc.createDataChannel('chat', { ordered: true });
+    this.setupDataChannel(peerUid, dc);
+
+    const offer = await pc.createOffer();
+    await pc.setLocalDescription(offer);
+
+    this.send('offer', {
+      toUid: peerUid,
+      sdp: pc.localDescription,
+    });
+  }
+
+  private createPeerConnection(peerUid: string): RTCPeerConnection {
+    // Close existing if any
+    this.peerConnections.get(peerUid)?.close();
+
+    const pc = new RTCPeerConnection({ iceServers: this.iceServers });
+    this.peerConnections.set(peerUid, pc);
+    this.peerMode.set(peerUid, 'p2p');
+
+    // ICE candidate forwarding
+    pc.onicecandidate = (evt) => {
+      if (evt.candidate) {
+        this.send('ice-candidate', { toUid: peerUid, candidate: evt.candidate });
+      }
+    };
+
+    // ── Fallback: if ICE fails, switch to WS relay ────────────────────────
+    pc.oniceconnectionstatechange = () => {
+      if (pc.iceConnectionState === 'failed' || pc.iceConnectionState === 'disconnected') {
+        console.warn(`[P2P] ICE failed for ${peerUid} — switching to WS relay`);
+        this.peerMode.set(peerUid, 'relay');
+        // Close the dead connection
+        pc.close();
+        this.peerConnections.delete(peerUid);
+        this.dataChannels.delete(peerUid);
+      }
+    };
+
+    // Callee side: accept incoming data channel
+    pc.ondatachannel = (evt) => {
+      this.setupDataChannel(peerUid, evt.channel);
+    };
+
+    return pc;
+  }
+
+  private setupDataChannel(peerUid: string, dc: RTCDataChannel): void {
+    this.dataChannels.set(peerUid, dc);
+
+    dc.onopen = () => {
+      console.info(`[P2P] Data channel open with ${peerUid}`);
+      this.peerMode.set(peerUid, 'p2p');
+    };
+
+    dc.onmessage = (evt) => {
+      try {
+        const data = JSON.parse(evt.data as string) as unknown;
+        this.opts.onP2PData(peerUid, data);
+      } catch {
+        this.opts.onP2PData(peerUid, evt.data);
+      }
+    };
+
+    dc.onclose = () => {
+      console.info(`[P2P] Data channel closed with ${peerUid}`);
+      this.dataChannels.delete(peerUid);
+      // Fall back to WS relay
+      this.peerMode.set(peerUid, 'relay');
+    };
+  }
+
+  // ── Server message handler ────────────────────────────────────────────────
+
+  private requestCallbacks = new Map<string, (payload: unknown) => void>();
+
+  private waitForRequestId<T>(requestId: string): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.requestCallbacks.delete(requestId);
+        reject(new Error(`Request ${requestId} timed out`));
+      }, 15_000);
+
+      this.requestCallbacks.set(requestId, (payload) => {
+        clearTimeout(timer);
+        resolve(payload as T);
+      });
+    });
+  }
+
+  private parseServer(raw: string): Record<string, unknown> | null {
+    try { return JSON.parse(raw) as Record<string, unknown>; }
+    catch { return null; }
+  }
+
+  private async handleServer(
+    msg: Record<string, unknown>,
+    onConnected: () => void,
+    onConnectError: (e: Error) => void
+  ): Promise<void> {
+    const type = msg.type as string;
+    const payload = (msg.payload ?? {}) as Record<string, unknown>;
+    const requestId = msg.requestId as string | undefined;
+
+    // Resolve pending request callbacks
+    if (requestId && this.requestCallbacks.has(requestId)) {
+      this.requestCallbacks.get(requestId)!(payload);
+      this.requestCallbacks.delete(requestId);
+    }
+
+    switch (type) {
+      case 'connected':
+        this.myUid = payload.uid as string;
+        this.socketId = payload.socketId as string;
+        onConnected();
+        break;
+
+      case 'ice-servers':
+        this.iceServers = payload.iceServers as IceServerConfig[];
+        break;
+
+      case 'message':
+        this.opts.onMessage(payload as unknown as EnvelopeMessage);
+        break;
+
+      case 'offline-flush': {
+        const messages = payload.messages as EnvelopeMessage[];
+        this.opts.onOfflineFlush(messages);
+        break;
+      }
+
+      case 'peer-online':
+        this.opts.onPeerOnline(payload.uid as string);
+        break;
+
+      case 'peer-offline': {
+        const offlineUid = payload.uid as string;
+        this.opts.onPeerOffline(offlineUid);
+        // Switch to relay mode for this peer
+        this.peerMode.set(offlineUid, 'relay');
+        break;
+      }
+
+      case 'offer': {
+        const fromUid = payload.fromUid as string;
+        const pc = this.createPeerConnection(fromUid);
+        await pc.setRemoteDescription(payload.sdp as RTCSessionDescriptionInit);
+        const answer = await pc.createAnswer();
+        await pc.setLocalDescription(answer);
+        this.send('answer', { toUid: fromUid, sdp: pc.localDescription });
+        break;
+      }
+
+      case 'answer': {
+        const fromUid = payload.fromUid as string;
+        const pc = this.peerConnections.get(fromUid);
+        if (pc) await pc.setRemoteDescription(payload.sdp as RTCSessionDescriptionInit);
+        break;
+      }
+
+      case 'ice-candidate': {
+        const fromUid = payload.fromUid as string;
+        const pc = this.peerConnections.get(fromUid);
+        if (pc && payload.candidate) {
+          await pc.addIceCandidate(payload.candidate as RTCIceCandidateInit);
+        }
+        break;
+      }
+
+      case 'relay':
+        // Message arrived via WS relay fallback
+        this.opts.onMessage(payload as unknown as EnvelopeMessage);
+        break;
+
+      case 'error':
+        console.error('[P2P Server Error]', payload.message);
+        break;
+    }
+  }
+
+  // ── Friend helpers ────────────────────────────────────────────────────────
+
+  sendFriendRequest(toUid: string): void {
+    this.send('friend', { action: 'send-request', targetUid: toUid });
+  }
+
+  acceptFriendRequest(fromUid: string): void {
+    this.send('friend', { action: 'accept', targetUid: fromUid });
+  }
+
+  rejectFriendRequest(fromUid: string): void {
+    this.send('friend', { action: 'reject', targetUid: fromUid });
+  }
+
+  removeFriend(uid: string): void {
+    this.send('friend', { action: 'remove', targetUid: uid });
+  }
+
+  async getFriends(): Promise<Array<{ uid: string; online: boolean }>> {
+    const requestId = crypto.randomUUID();
+    const result = await this.waitForRequestId<{ friends: Array<{ uid: string; online: boolean }> }>(requestId);
+    this.send('friend', { action: 'list' }, requestId);
+    return result.friends;
+  }
+
+  // ── Getters ───────────────────────────────────────────────────────────────
+
+  get uid(): string | null { return this.myUid; }
+  get connected(): boolean { return this.ws?.readyState === WebSocket.OPEN; }
+  getPeerMode(peerUid: string): 'p2p' | 'relay' | 'none' {
+    return this.peerMode.get(peerUid) ?? 'none';
+  }
+}

package.json

@@ -0,0 +1,29 @@
+{
+  "name": "p2p-signal-server",
+  "version": "1.0.0",
+  "description": "P2P WebRTC signaling server with offline queuing",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "lint": "eslint src/**/*.ts"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.39.0",
+    "dotenv": "^16.3.1",
+    "ioredis": "^5.3.2",
+    "jsonwebtoken": "^9.0.2",
+    "mongoose": "^8.1.0",
+    "uuid": "^9.0.0",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.5",
+    "@types/node": "^20.10.0",
+    "@types/uuid": "^9.0.7",
+    "@types/ws": "^8.5.10",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.3.2"
+  }
+}

src/config.ts

@@ -0,0 +1,76 @@
+import dotenv from 'dotenv';
+dotenv.config();
+
+function require_env(key: string): string {
+  const val = process.env[key];
+  if (!val) throw new Error(`Missing required env variable: ${key}`);
+  return val;
+}
+
+function optional_env(key: string, fallback: string): string {
+  return process.env[key] || fallback;
+}
+
+export const CONFIG = {
+  // Server
+  PORT: parseInt(optional_env('PORT', '7860'), 10),
+  NODE_ENV: optional_env('NODE_ENV', 'production'),
+  ALLOWED_ORIGINS: optional_env('ALLOWED_ORIGINS', '*').split(',').map(s => s.trim()),
+
+  // Auth
+  JWT_SECRET: require_env('JWT_SECRET'),
+
+  // Redis — Two separate buckets
+  REDIS_PRESENCE_URL: require_env('REDIS_PRESENCE_URL'),
+  REDIS_MESSAGE_URL: require_env('REDIS_MESSAGE_URL'),
+
+  // MongoDB
+  MONGO_URI: require_env('MONGO_URI'),
+
+  // Supabase
+  SUPABASE_URL: require_env('SUPABASE_URL'),
+  SUPABASE_SERVICE_KEY: require_env('SUPABASE_SERVICE_KEY'),
+  SUPABASE_BUCKET: optional_env('SUPABASE_BUCKET', 'media'),
+
+  // WebRTC ICE Servers
+  STUN_SERVERS: optional_env(
+    'STUN_SERVERS',
+    'stun:stun.l.google.com:19302,stun:stun1.l.google.com:19302'
+  )
+    .split(',')
+    .map(s => s.trim()),
+  TURN_URL: optional_env('TURN_URL', ''),
+  TURN_USERNAME: optional_env('TURN_USERNAME', ''),
+  TURN_CREDENTIAL: optional_env('TURN_CREDENTIAL', ''),
+
+  // File limits
+  MAX_FILE_SIZE_BYTES: parseInt(optional_env('MAX_FILE_SIZE_MB', '99'), 10) * 1024 * 1024,
+  MAX_FILE_COUNT: parseInt(optional_env('MAX_FILE_COUNT', '10'), 10),
+
+  // TTLs
+  PRESENCE_TTL_S: parseInt(optional_env('PRESENCE_TTL_S', '60'), 10),
+  OFFLINE_MSG_TTL_S: parseInt(optional_env('OFFLINE_MSG_TTL_S', '604800'), 10),
+  HEARTBEAT_INTERVAL_MS: parseInt(optional_env('HEARTBEAT_INTERVAL_MS', '30000'), 10),
+} as const;
+
+/** Build the ICE server config array sent to clients */
+export function buildIceServers(): RTCIceServerConfig[] {
+  const servers: RTCIceServerConfig[] = CONFIG.STUN_SERVERS.map(url => ({ urls: url }));
+
+  if (CONFIG.TURN_URL) {
+    servers.push({
+      urls: CONFIG.TURN_URL,
+      username: CONFIG.TURN_USERNAME,
+      credential: CONFIG.TURN_CREDENTIAL,
+    });
+  }
+
+  return servers;
+}
+
+// We type this loosely — WebRTC types are not in Node by default
+interface RTCIceServerConfig {
+  urls: string;
+  username?: string;
+  credential?: string;
+}

src/db/mongo.ts

@@ -0,0 +1,104 @@
+import mongoose, { Schema, Document, Model } from 'mongoose';
+import { CONFIG } from '../config';
+import { logger } from '../utils/logger';
+
+// ── Connection ────────────────────────────────────────────────────────────────
+
+let isConnected = false;
+
+export async function connectMongo(): Promise<void> {
+  if (isConnected) return;
+
+  mongoose.set('strictQuery', true);
+
+  await mongoose.connect(CONFIG.MONGO_URI, {
+    maxPoolSize: 10,           // Conserve connections on free tier
+    serverSelectionTimeoutMS: 5000,
+    socketTimeoutMS: 30000,
+  });
+
+  isConnected = true;
+  logger.info('MongoDB connected');
+
+  mongoose.connection.on('error', (err: Error) =>
+    logger.error('MongoDB connection error', { error: err.message })
+  );
+  mongoose.connection.on('disconnected', () => {
+    isConnected = false;
+    logger.warn('MongoDB disconnected');
+  });
+}
+
+// ── User Profile Model ────────────────────────────────────────────────────────
+
+export interface IUser extends Document {
+  uid: string;
+  displayName: string;
+  avatarUrl?: string;
+  friends: string[];         // Array of UIDs
+  blockedUsers: string[];
+  settings: {
+    notifications: boolean;
+    theme: 'light' | 'dark';
+  };
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const UserSchema = new Schema<IUser>(
+  {
+    uid: { type: String, required: true, unique: true, index: true },
+    displayName: { type: String, required: true, maxlength: 64 },
+    avatarUrl: { type: String, default: null },
+    friends: { type: [String], default: [] },
+    blockedUsers: { type: [String], default: [] },
+    settings: {
+      notifications: { type: Boolean, default: true },
+      theme: { type: String, enum: ['light', 'dark'], default: 'dark' },
+    },
+  },
+  {
+    timestamps: true,
+    // Lean queries by default for read-heavy paths
+  }
+);
+
+// Compound index for friend-list lookups
+UserSchema.index({ uid: 1, friends: 1 });
+
+export const UserModel: Model<IUser> = mongoose.model<IUser>('User', UserSchema);
+
+// ── Persistent Message Log (optional, for history) ────────────────────────────
+
+export interface IMessage extends Document {
+  fromUid: string;
+  toUid: string;
+  type: 'text' | 'media';
+  content: string;           // Text body or Supabase URL
+  mediaType?: string;        // MIME type for media messages
+  delivered: boolean;
+  createdAt: Date;
+}
+
+const MessageSchema = new Schema<IMessage>(
+  {
+    fromUid: { type: String, required: true, index: true },
+    toUid: { type: String, required: true, index: true },
+    type: { type: String, enum: ['text', 'media'], required: true },
+    content: { type: String, required: true, maxlength: 4096 },
+    mediaType: { type: String, default: null },
+    delivered: { type: Boolean, default: false, index: true },
+  },
+  {
+    timestamps: true,
+    // TTL index: auto-delete messages older than 30 days to save Atlas space
+    expireAfterSeconds: 60 * 60 * 24 * 30,
+  }
+);
+
+MessageSchema.index({ fromUid: 1, toUid: 1, createdAt: -1 });
+
+export const MessageModel: Model<IMessage> = mongoose.model<IMessage>(
+  'Message',
+  MessageSchema
+);

src/handlers/connectionHandler.ts

@@ -0,0 +1,150 @@
+import WebSocket from 'ws';
+import { IncomingMessage } from 'http';
+import { v4 as uuidv4 } from 'uuid';
+import { verifyToken, extractToken } from '../utils/jwt';
+import { safeSend, parseClientMessage, ClientMessage } from '../utils/protocol';
+import { setOnline, setOffline, refreshPresence } from '../redis/presenceClient';
+import { flushOfflineQueue } from '../redis/messageClient';
+import { registry } from '../services/connectionRegistry';
+import { buildIceServers } from '../config';
+import { logger } from '../utils/logger';
+import { handleSignaling } from './signalingHandler';
+import { handleMessage } from './messageHandler';
+import { handleFileRequest } from './fileHandler';
+import { handleFriend } from './friendHandler';
+
+export async function onConnection(
+  ws: WebSocket,
+  req: IncomingMessage
+): Promise<void> {
+  // ── 1. Authenticate ──────────────────────────────────────────────────────
+  let uid: string;
+  try {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+    const token = extractToken(
+      req.headers.authorization,
+      url.searchParams.get('token') ?? undefined
+    );
+    const payload = verifyToken(token);
+    uid = payload.uid;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'Auth failed';
+    ws.send(JSON.stringify({ type: 'error', payload: { message: msg }, ts: Date.now() }));
+    ws.terminate();
+    return;
+  }
+
+  const socketId = uuidv4();
+
+  // ── 2. Register in process registry + Redis Bucket 1 ────────────────────
+  registry.add(socketId, uid, ws);
+
+  // Redis errors must NOT crash the connection handler
+  try {
+    await setOnline(uid, socketId);
+  } catch (err) {
+    logger.error('setOnline failed', { uid, error: String(err) });
+  }
+
+  logger.info('Client connected', { uid, socketId, total: registry.size() });
+
+  // ── 3. Send welcome + ICE server config ─────────────────────────────────
+  safeSend(ws, 'connected', { uid, socketId });
+  safeSend(ws, 'ice-servers', { iceServers: buildIceServers() });
+
+  // ── 4. Flush offline message queue (Bucket 2) ────────────────────────────
+  try {
+    const pending = await flushOfflineQueue(uid);
+    if (pending.length > 0) {
+      safeSend(ws, 'offline-flush', { messages: pending, count: pending.length });
+      logger.info('Flushed offline queue', { uid, count: pending.length });
+    }
+  } catch (err) {
+    logger.error('Offline flush failed', { uid, error: String(err) });
+  }
+
+  // ── 5. Message router ────────────────────────────────────────────────────
+  ws.on('message', (raw) => {
+    const msg = parseClientMessage(raw);
+    if (!msg) return; // Malformed — silently drop
+
+    registry.heartbeat(socketId); // Any message counts as a heartbeat
+
+    routeMessage(ws, uid, socketId, msg).catch((err: unknown) => {
+      logger.error('Message handler error', { uid, type: msg.type, error: String(err) });
+    });
+  });
+
+  // ── 6. Cleanup on disconnect ─────────────────────────────────────────────
+  ws.on('close', () => {
+    registry.remove(socketId);
+    setOffline(uid).catch((err: unknown) =>
+      logger.error('setOffline failed', { uid, error: String(err) })
+    );
+    logger.info('Client disconnected', { uid, socketId, total: registry.size() });
+  });
+
+  ws.on('error', (err) => {
+    logger.error('WebSocket error', { uid, socketId, error: err.message });
+    ws.terminate();
+  });
+}
+
+// ── Message router ────────────────────────────────────────────────────────────
+
+async function routeMessage(
+  ws: WebSocket,
+  uid: string,
+  socketId: string,
+  msg: ClientMessage
+): Promise<void> {
+  switch (msg.type) {
+    case 'heartbeat':
+      await refreshPresence(uid).catch(() => {}); // Best effort
+      break;
+
+    case 'offer':
+    case 'answer':
+    case 'ice-candidate':
+      await handleSignaling(ws, uid, msg);
+      break;
+
+    case 'message':
+      await handleMessage(ws, uid, msg);
+      break;
+
+    case 'get-upload-url':
+      await handleFileRequest(ws, uid, msg);
+      break;
+
+    case 'relay':
+      await handleRelay(ws, uid, msg);
+      break;
+
+    case 'friend':
+      await handleFriend(ws, uid, msg);
+      break;
+
+    default:
+      safeSend(ws, 'error', { message: `Unknown message type: ${msg.type}` });
+  }
+}
+
+// ── WebSocket relay fallback (when WebRTC ICE fails) ─────────────────────────
+
+async function handleRelay(
+  _senderWs: WebSocket,
+  fromUid: string,
+  msg: ClientMessage
+): Promise<void> {
+  const toUid = msg.payload.toUid as string | undefined;
+  if (!toUid || typeof toUid !== 'string') return;
+
+  const target = registry.getByUid(toUid);
+  if (!target) return;
+
+  safeSend(target.ws, 'relay', {
+    fromUid,
+    data: msg.payload.data,
+  }, msg.requestId);
+}

src/handlers/fileHandler.ts

@@ -0,0 +1,78 @@
+import WebSocket from 'ws';
+import { ClientMessage, safeSend } from '../utils/protocol';
+import {
+  generateUploadUrl,
+  validateFileRequest,
+  validateFileCount,
+  FileUploadRequest,
+} from '../services/supabaseService';
+import { logger } from '../utils/logger';
+
+/**
+ * Handles type: 'get-upload-url'
+ *
+ * Client sends:
+ * {
+ *   files: Array<{ fileName: string, mimeType: string, sizeBytes: number }>
+ * }
+ *
+ * Server responds with:
+ * {
+ *   urls: Array<{ signedUrl, objectPath, publicUrl, fileName }>
+ * }
+ *
+ * The client then PUTs each file directly to Supabase using the signedUrl.
+ * HF server never sees any file bytes — memory usage stays near 0.
+ *
+ * After upload, the client sends a type: 'message' with type: 'media' and
+ * the publicUrl as the content field.
+ */
+export async function handleFileRequest(
+  ws: WebSocket,
+  uid: string,
+  msg: ClientMessage
+): Promise<void> {
+  const files = msg.payload.files as FileUploadRequest[] | undefined;
+
+  // ── Validate count ────────────────────────────────────────────────────────
+  if (!Array.isArray(files)) {
+    safeSend(ws, 'error', { message: 'files must be an array' }, msg.requestId);
+    return;
+  }
+
+  const countError = validateFileCount(files.length);
+  if (countError) {
+    safeSend(ws, 'error', { message: countError }, msg.requestId);
+    return;
+  }
+
+  // ── Validate each file ────────────────────────────────────────────────────
+  for (const f of files) {
+    const fileError = validateFileRequest(f);
+    if (fileError) {
+      safeSend(ws, 'error', { message: fileError }, msg.requestId);
+      return;
+    }
+  }
+
+  // ── Generate signed URLs ──────────────────────────────────────────────────
+  try {
+    const results = await Promise.all(
+      files.map(async (f) => {
+        const result = await generateUploadUrl(uid, f);
+        return {
+          fileName: f.fileName,
+          signedUrl: result.signedUrl,
+          objectPath: result.objectPath,
+          publicUrl: result.publicUrl,
+        };
+      })
+    );
+
+    safeSend(ws, 'upload-url', { urls: results }, msg.requestId);
+    logger.info('Signed URLs generated', { uid, count: results.length });
+  } catch (err) {
+    logger.error('generateUploadUrl failed', { uid, error: String(err) });
+    safeSend(ws, 'error', { message: 'Failed to generate upload URL' }, msg.requestId);
+  }
+}

src/handlers/friendHandler.ts

@@ -0,0 +1,105 @@
+import WebSocket from 'ws';
+import { ClientMessage, safeSend } from '../utils/protocol';
+import {
+  sendFriendRequest,
+  acceptFriendRequest,
+  rejectFriendRequest,
+  removeFriend,
+  getFriendList,
+  areFriends,
+} from '../services/friendService';
+import { isOnline } from '../redis/presenceClient';
+import { registry } from '../services/connectionRegistry';
+import { logger } from '../utils/logger';
+
+/**
+ * Routes friend-related WS actions.
+ * Called from connectionHandler's routeMessage for type: 'friend'
+ *
+ * Payload shape: { action, targetUid, ...extras }
+ * Actions: send-request | accept | reject | remove | list | status
+ */
+export async function handleFriend(
+  ws: WebSocket,
+  uid: string,
+  msg: ClientMessage
+): Promise<void> {
+  const { action, targetUid } = msg.payload as { action?: string; targetUid?: string };
+
+  if (!action) {
+    safeSend(ws, 'error', { message: 'action is required' }, msg.requestId);
+    return;
+  }
+
+  switch (action) {
+    case 'send-request': {
+      if (!targetUid) { safeSend(ws, 'error', { message: 'targetUid required' }, msg.requestId); return; }
+      if (targetUid === uid) { safeSend(ws, 'error', { message: 'Cannot friend yourself' }, msg.requestId); return; }
+      await sendFriendRequest(uid, targetUid);
+      safeSend(ws, 'message', { ack: true, action: 'send-request', targetUid }, msg.requestId);
+
+      // Notify the target if online
+      const targetMeta = registry.getByUid(targetUid);
+      if (targetMeta) {
+        safeSend(targetMeta.ws, 'message', { type: 'friend-request', fromUid: uid });
+      }
+      break;
+    }
+
+    case 'accept': {
+      if (!targetUid) { safeSend(ws, 'error', { message: 'targetUid required' }, msg.requestId); return; }
+      const ok = await acceptFriendRequest(targetUid, uid); // targetUid sent the request
+      safeSend(ws, 'message', { ack: true, action: 'accept', success: ok }, msg.requestId);
+
+      if (ok) {
+        const targetMeta = registry.getByUid(targetUid);
+        if (targetMeta) {
+          safeSend(targetMeta.ws, 'message', { type: 'friend-accepted', fromUid: uid });
+        }
+      }
+      break;
+    }
+
+    case 'reject': {
+      if (!targetUid) { safeSend(ws, 'error', { message: 'targetUid required' }, msg.requestId); return; }
+      await rejectFriendRequest(targetUid, uid);
+      safeSend(ws, 'message', { ack: true, action: 'reject' }, msg.requestId);
+      break;
+    }
+
+    case 'remove': {
+      if (!targetUid) { safeSend(ws, 'error', { message: 'targetUid required' }, msg.requestId); return; }
+      await removeFriend(uid, targetUid);
+      safeSend(ws, 'message', { ack: true, action: 'remove' }, msg.requestId);
+      break;
+    }
+
+    case 'list': {
+      const friends = await getFriendList(uid);
+      // Bulk check online status from Redis
+      const statusChecks = await Promise.allSettled(friends.map(f => isOnline(f)));
+      const withStatus = friends.map((f, i) => ({
+        uid: f,
+        online: statusChecks[i].status === 'fulfilled' && statusChecks[i].value === true,
+      }));
+      safeSend(ws, 'message', { action: 'list', friends: withStatus }, msg.requestId);
+      break;
+    }
+
+    case 'status': {
+      if (!targetUid) { safeSend(ws, 'error', { message: 'targetUid required' }, msg.requestId); return; }
+      // Only allow checking status of friends
+      const isFriend = await areFriends(uid, targetUid);
+      if (!isFriend) {
+        safeSend(ws, 'error', { message: 'Not friends with this user' }, msg.requestId);
+        return;
+      }
+      const online = await isOnline(targetUid);
+      safeSend(ws, 'message', { action: 'status', uid: targetUid, online }, msg.requestId);
+      break;
+    }
+
+    default:
+      safeSend(ws, 'error', { message: `Unknown friend action: ${action}` }, msg.requestId);
+  }
+}

src/handlers/messageHandler.ts

@@ -0,0 +1,108 @@
+import WebSocket from 'ws';
+import { ClientMessage, safeSend } from '../utils/protocol';
+import { isOnline } from '../redis/presenceClient';
+import { enqueueOfflineMessage } from '../redis/messageClient';
+import { registry } from '../services/connectionRegistry';
+import { MessageModel } from '../db/mongo';
+import { logger } from '../utils/logger';
+
+const MAX_TEXT_LENGTH = 4096;
+
+/**
+ * Handles type: 'message'
+ *
+ * Payload shape:
+ * {
+ *   toUid: string,
+ *   type: 'text' | 'media',
+ *   content: string,        // text body or Supabase media URL
+ *   mediaType?: string,     // MIME type for media
+ *   clientMsgId?: string,   // Client-generated idempotency ID
+ * }
+ *
+ * Flow:
+ *   If recipient online  → push directly to their WS
+ *   If recipient offline → enqueue in Redis Bucket 2
+ *   Always               → persist to MongoDB for history
+ */
+export async function handleMessage(
+  senderWs: WebSocket,
+  fromUid: string,
+  msg: ClientMessage
+): Promise<void> {
+  const { toUid, type, content, mediaType, clientMsgId } = msg.payload as {
+    toUid?: string;
+    type?: string;
+    content?: string;
+    mediaType?: string;
+    clientMsgId?: string;
+  };
+
+  // ── Validate ──────────────────────────────────────────────────────────────
+  if (!toUid || typeof toUid !== 'string') {
+    safeSend(senderWs, 'error', { message: 'toUid is required' }, msg.requestId);
+    return;
+  }
+  if (toUid === fromUid) {
+    safeSend(senderWs, 'error', { message: 'Cannot message yourself' }, msg.requestId);
+    return;
+  }
+  if (!content || typeof content !== 'string') {
+    safeSend(senderWs, 'error', { message: 'content is required' }, msg.requestId);
+    return;
+  }
+  if (type !== 'text' && type !== 'media') {
+    safeSend(senderWs, 'error', { message: 'type must be text or media' }, msg.requestId);
+    return;
+  }
+  if (type === 'text' && content.length > MAX_TEXT_LENGTH) {
+    safeSend(senderWs, 'error', { message: `Text exceeds ${MAX_TEXT_LENGTH} chars` }, msg.requestId);
+    return;
+  }
+
+  const envelope: Record<string, unknown> = {
+    fromUid,
+    toUid,
+    type,
+    content,
+    mediaType: mediaType ?? null,
+    clientMsgId: clientMsgId ?? null,
+    sentAt: Date.now(),
+  };
+
+  // ── Persist to MongoDB ────────────────────────────────────────────────────
+  // Fire-and-forget — do not block message delivery on DB write
+  MessageModel.create({
+    fromUid,
+    toUid,
+    type,
+    content,
+    mediaType: mediaType ?? undefined,
+    delivered: false,
+  }).catch((err: unknown) =>
+    logger.error('MongoDB message persist failed', { error: String(err) })
+  );
+
+  // ── Deliver ───────────────────────────────────────────────────────────────
+  const targetMeta = registry.getByUid(toUid);
+
+  if (targetMeta) {
+    // Online — deliver directly
+    safeSend(targetMeta.ws, 'message', envelope);
+    logger.debug('Message delivered live', { fromUid, toUid, type });
+  } else {
+    // Double-check Redis in case peer is on a different process (future multi-node)
+    const online = await isOnline(toUid).catch(() => false);
+
+    if (!online) {
+      // Enqueue in Redis Bucket 2
+      await enqueueOfflineMessage(toUid, envelope).catch((err: unknown) =>
+        logger.error('enqueueOfflineMessage failed', { toUid, error: String(err) })
+      );
+      logger.debug('Message queued offline', { fromUid, toUid });
+    }
+  }
+
+  // Ack the sender
+  safeSend(senderWs, 'message', { ack: true, clientMsgId: clientMsgId ?? null }, msg.requestId);
+}

src/handlers/signalingHandler.ts

@@ -0,0 +1,83 @@
+import WebSocket from 'ws';
+import { ClientMessage } from '../utils/protocol';
+import { safeSend, ServerMessageType } from '../utils/protocol';
+import { isOnline } from '../redis/presenceClient';
+import { enqueueOfflineMessage } from '../redis/messageClient';
+import { registry } from '../services/connectionRegistry';
+import { logger } from '../utils/logger';
+
+/**
+ * Handles WebRTC signaling:
+ *   - offer / answer / ice-candidate are forwarded to the target peer.
+ *   - If the peer is offline, the signal is dropped (SDP signals don't
+ *     queue — they are ephemeral). Only chat messages queue offline.
+ *
+ * WebRTC fallback to WS relay:
+ *   When a client detects iceConnectionState === 'failed' or 'disconnected',
+ *   it switches to type: 'relay' messages instead.
+ *   The server relays those via handleRelay in connectionHandler.ts.
+ *   This handler is only responsible for SDP/ICE forwarding.
+ */
+export async function handleSignaling(
+  _senderWs: WebSocket,
+  fromUid: string,
+  msg: ClientMessage
+): Promise<void> {
+  const toUid = msg.payload.toUid as string | undefined;
+  if (!toUid || typeof toUid !== 'string') {
+    logger.warn('Signaling message missing toUid', { fromUid, type: msg.type });
+    return;
+  }
+
+  // Security: block self-signaling
+  if (toUid === fromUid) return;
+
+  const target = registry.getByUid(toUid);
+
+  if (!target) {
+    // Peer not on this process — check Redis
+    const online = await isOnline(toUid).catch(() => false);
+    if (!online) {
+      // Peer offline — signal is ephemeral, inform the sender
+      safeSend(_senderWs, 'peer-offline', { uid: toUid });
+    }
+    // In a multi-node deployment: publish to Redis pub/sub here
+    // for cross-node delivery. Single-node (HF): nothing to do.
+    return;
+  }
+
+  // Forward the signal verbatim to the peer
+  const forwardType = msg.type as ServerMessageType;
+  safeSend(
+    target.ws,
+    forwardType,
+    {
+      fromUid,
+      sdp: msg.payload.sdp,
+      candidate: msg.payload.candidate,
+    },
+    msg.requestId
+  );
+
+  logger.debug('Signal forwarded', { type: msg.type, fromUid, toUid });
+}
+
+/**
+ * Notify a user that a specific peer has come online.
+ * Called from connectionHandler after the user connects.
+ */
+export function notifyPeerOnline(targetUid: string, peerUid: string): void {
+  const target = registry.getByUid(targetUid);
+  if (!target) return;
+  safeSend(target.ws, 'peer-online', { uid: peerUid });
+}
+
+/**
+ * Notify a user that a specific peer has gone offline.
+ * Called from connectionHandler on disconnect.
+ */
+export function notifyPeerOffline(targetUid: string, peerUid: string): void {
+  const target = registry.getByUid(targetUid);
+  if (!target) return;
+  safeSend(target.ws, 'peer-offline', { uid: peerUid });
+}

src/index.ts

@@ -0,0 +1,148 @@
+import http from 'http';
+import WebSocket from 'ws';
+import { CONFIG } from './config';
+import { connectMongo } from './db/mongo';
+import { presenceClient } from './redis/presenceClient';
+import { messageClient } from './redis/messageClient';
+import { onConnection } from './handlers/connectionHandler';
+import { registry } from './services/connectionRegistry';
+import { isRateLimited } from './middleware/rateLimiter';
+import { logger } from './utils/logger';
+
+// ── Graceful startup ─────────────────────────────────────────────────────────
+
+async function bootstrap(): Promise<void> {
+  logger.info('Starting P2P Signal Server', {
+    port: CONFIG.PORT,
+    env: CONFIG.NODE_ENV,
+  });
+
+  // Connect dependencies — fail fast if they are unreachable
+  await connectMongo();
+
+  // Redis clients connect automatically on instantiation;
+  // wait for 'ready' event before accepting traffic
+  await Promise.all([
+    waitRedisReady(presenceClient, 'Presence'),
+    waitRedisReady(messageClient, 'Message'),
+  ]);
+
+  // ── HTTP health endpoint ─────────────────────────────────────────────────
+  // HF Spaces probes / to check the container is alive
+  const httpServer = http.createServer((req, res) => {
+    if (req.method === 'GET' && req.url === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          status: 'ok',
+          connections: registry.size(),
+          ts: Date.now(),
+        })
+      );
+      return;
+    }
+    // All other HTTP requests: 426 Upgrade Required
+    res.writeHead(426, { 'Content-Type': 'text/plain' });
+    res.end('This server only accepts WebSocket connections.');
+  });
+
+  // ── WebSocket server ─────────────────────────────────────────────────────
+  const wss = new WebSocket.Server({
+    server: httpServer,
+    // No per-message deflate — compresses well but costs CPU on HF free tier
+    perMessageDeflate: false,
+    // Limit frame size to 64 KB to protect against memory exhaustion
+    maxPayload: 65536,
+    // Manual upgrade handling for rate limiting
+    handleProtocols: () => false,
+  });
+
+  wss.on('connection', async (ws: WebSocket, req: http.IncomingMessage) => {
+    // Rate limit check
+    if (isRateLimited(req)) {
+      ws.close(1008, 'Rate limit exceeded');
+      return;
+    }
+
+    // CORS check — only allow configured origins
+    const origin = req.headers.origin ?? '';
+    if (
+      CONFIG.ALLOWED_ORIGINS[0] !== '*' &&
+      !CONFIG.ALLOWED_ORIGINS.includes(origin)
+    ) {
+      ws.close(1008, 'Origin not allowed');
+      return;
+    }
+
+    await onConnection(ws, req);
+  });
+
+  wss.on('error', (err) => logger.error('WSS error', { error: err.message }));
+
+  // ── Zombie socket pruner ─────────────────────────────────────────────────
+  // Kill sockets that missed 3× the heartbeat window (90s default)
+  const ZOMBIE_TIMEOUT_MS = CONFIG.HEARTBEAT_INTERVAL_MS * 3;
+  setInterval(() => {
+    const pruned = registry.pruneZombies(ZOMBIE_TIMEOUT_MS);
+    if (pruned > 0) logger.warn('Pruned zombie sockets', { pruned });
+  }, ZOMBIE_TIMEOUT_MS);
+
+  // ── Metrics logger ───────────────────────────────────────────────────────
+  setInterval(() => {
+    logger.info('Server metrics', {
+      connections: registry.size(),
+      memMB: Math.round(process.memoryUsage().rss / 1024 / 1024),
+    });
+  }, 60_000);
+
+  // ── Listen ───────────────────────────────────────────────────────────────
+  httpServer.listen(CONFIG.PORT, '0.0.0.0', () => {
+    logger.info(`Server listening on port ${CONFIG.PORT}`);
+  });
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function waitRedisReady(client: any, name: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (client.status === 'ready') { resolve(); return; }
+    client.once('ready', resolve);
+    client.once('error', (err: Error) =>
+      reject(new Error(`${name} Redis failed: ${err.message}`))
+    );
+    // Timeout after 10s
+    setTimeout(() => reject(new Error(`${name} Redis connection timeout`)), 10_000);
+  });
+}
+
+// ── Global error boundaries ���─────────────────────────────────────────────────
+// Unhandled rejections must not crash the HF container
+
+process.on('unhandledRejection', (reason) => {
+  logger.error('Unhandled rejection', { reason: String(reason) });
+});
+
+process.on('uncaughtException', (err) => {
+  logger.error('Uncaught exception', { error: err.message, stack: err.stack });
+  // Do NOT exit — HF container restart is slow
+});
+
+// ── Graceful shutdown ────────────────────────────────────────────────────────
+
+async function shutdown(signal: string): Promise<void> {
+  logger.info(`Received ${signal}, shutting down gracefully`);
+  presenceClient.disconnect();
+  messageClient.disconnect();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
+// ── Boot ─────────────────────────────────────────────────────────────────────
+
+bootstrap().catch((err) => {
+  logger.error('Bootstrap failed', { error: String(err) });
+  process.exit(1);
+});

src/middleware/rateLimiter.ts

@@ -0,0 +1,56 @@
+import { IncomingMessage } from 'http';
+
+/**
+ * Simple in-process token bucket rate limiter for WS upgrade requests.
+ * Prevents a single IP from opening thousands of connections on HF free tier.
+ *
+ * Limits: 20 connections per IP per 60 seconds.
+ */
+
+interface Bucket {
+  tokens: number;
+  lastRefill: number;
+}
+
+const CAPACITY = 20;
+const REFILL_RATE = 20;      // tokens per window
+const WINDOW_MS = 60_000;    // 60 seconds
+
+const buckets = new Map<string, Bucket>();
+
+// Prune old entries every 5 minutes to prevent memory leak
+setInterval(() => {
+  const cutoff = Date.now() - WINDOW_MS * 2;
+  for (const [ip, bucket] of buckets) {
+    if (bucket.lastRefill < cutoff) buckets.delete(ip);
+  }
+}, 300_000).unref();
+
+export function isRateLimited(req: IncomingMessage): boolean {
+  const ip =
+    (req.headers['x-forwarded-for'] as string | undefined)?.split(',')[0]?.trim() ??
+    req.socket.remoteAddress ??
+    'unknown';
+
+  const now = Date.now();
+  let bucket = buckets.get(ip);
+
+  if (!bucket) {
+    bucket = { tokens: CAPACITY - 1, lastRefill: now };
+    buckets.set(ip, bucket);
+    return false;
+  }
+
+  // Refill based on elapsed time
+  const elapsed = now - bucket.lastRefill;
+  if (elapsed >= WINDOW_MS) {
+    bucket.tokens = CAPACITY - 1;
+    bucket.lastRefill = now;
+    return false;
+  }
+
+  if (bucket.tokens <= 0) return true;
+
+  bucket.tokens--;
+  return false;
+}

src/models/friend.ts

@@ -0,0 +1,34 @@
+import mongoose, { Schema, Document, Model } from 'mongoose';
+
+/**
+ * FriendRequest model — tracks pending/accepted/rejected friend requests.
+ * Used by REST-style HTTP upgrade calls (future) or future REST API layer.
+ */
+export interface IFriendRequest extends Document {
+  fromUid: string;
+  toUid: string;
+  status: 'pending' | 'accepted' | 'rejected';
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const FriendRequestSchema = new Schema<IFriendRequest>(
+  {
+    fromUid: { type: String, required: true, index: true },
+    toUid: { type: String, required: true, index: true },
+    status: {
+      type: String,
+      enum: ['pending', 'accepted', 'rejected'],
+      default: 'pending',
+    },
+  },
+  { timestamps: true }
+);
+
+// Prevent duplicate requests
+FriendRequestSchema.index({ fromUid: 1, toUid: 1 }, { unique: true });
+
+export const FriendRequestModel: Model<IFriendRequest> = mongoose.model<IFriendRequest>(
+  'FriendRequest',
+  FriendRequestSchema
+);

src/redis/messageClient.ts

@@ -0,0 +1,93 @@
+import Redis from 'ioredis';
+import { CONFIG } from '../config';
+import { logger } from '../utils/logger';
+
+/**
+ * Redis Bucket 2 — Offline Message Queue
+ *
+ * Key schema:
+ *   offline_msgs:{uid}  → Redis List of JSON-encoded message strings
+ *                          Each list key has OFFLINE_MSG_TTL_S TTL.
+ *
+ * Entirely separate Redis instance from Bucket 1.
+ */
+const messageClient = new Redis(CONFIG.REDIS_MESSAGE_URL, {
+  maxRetriesPerRequest: 2,
+  connectTimeout: 5000,
+  lazyConnect: false,
+  enableReadyCheck: true,
+  keepAlive: 10000,
+});
+
+messageClient.on('connect', () => logger.info('Message Redis connected'));
+messageClient.on('error', (err: Error) =>
+  logger.error('Message Redis error', { error: err.message })
+);
+messageClient.on('reconnecting', () => logger.warn('Message Redis reconnecting'));
+
+export { messageClient };
+
+// ── Key builder ──────────────────────────────────────────────────────────────
+
+const queueKey = (uid: string) => `offline_msgs:${uid}`;
+
+// Max messages to queue per user — prevents memory abuse at 10k scale
+const MAX_QUEUE_LENGTH = 200;
+
+// ── Operations ───────────────────────────────────────────────────────────────
+
+/** Push a serialized message onto the offline queue for a user. */
+export async function enqueueOfflineMessage(
+  toUid: string,
+  message: Record<string, unknown>
+): Promise<void> {
+  const key = queueKey(toUid);
+  const serialized = JSON.stringify(message);
+
+  // RPUSH then cap the list, then refresh TTL — 3 commands in a pipeline
+  const pipeline = messageClient.pipeline();
+  pipeline.rpush(key, serialized);
+  // Trim to MAX_QUEUE_LENGTH (drop oldest if overflow)
+  pipeline.ltrim(key, -MAX_QUEUE_LENGTH, -1);
+  pipeline.expire(key, CONFIG.OFFLINE_MSG_TTL_S);
+  await pipeline.exec();
+}
+
+/**
+ * Atomically pop all queued messages for a uid.
+ * Uses LRANGE + DEL so no message is double-delivered.
+ * Returns parsed message objects.
+ */
+export async function flushOfflineQueue(
+  toUid: string
+): Promise<Array<Record<string, unknown>>> {
+  const key = queueKey(toUid);
+
+  // LRANGE 0 -1 gets everything; DEL removes the key atomically-ish
+  // For true atomicity at high scale, this could be a Lua script —
+  // but for HF free tier the risk of race is negligible.
+  const pipeline = messageClient.pipeline();
+  pipeline.lrange(key, 0, -1);
+  pipeline.del(key);
+  const results = await pipeline.exec();
+
+  if (!results || !results[0] || results[0][0]) return [];
+
+  const rawList = results[0][1] as string[];
+  const parsed: Array<Record<string, unknown>> = [];
+
+  for (const raw of rawList) {
+    try {
+      parsed.push(JSON.parse(raw) as Record<string, unknown>);
+    } catch {
+      // Corrupted entry — skip
+    }
+  }
+
+  return parsed;
+}
+
+/** How many messages are queued for a user. Useful for dashboards. */
+export async function getQueueLength(uid: string): Promise<number> {
+  return messageClient.llen(queueKey(uid));
+}

src/redis/presenceClient.ts

@@ -0,0 +1,77 @@
+import Redis from 'ioredis';
+import { CONFIG } from '../config';
+import { logger } from '../utils/logger';
+
+/**
+ * Redis Bucket 1 — Presence
+ *
+ * Key schema:
+ *   presence:uid:{uid}   → socket_id  (TTL = PRESENCE_TTL_S)
+ *   status:uid:{uid}     → "online"   (TTL = PRESENCE_TTL_S)
+ *
+ * Separate client instance so Bucket 1 errors never affect Bucket 2.
+ */
+const presenceClient = new Redis(CONFIG.REDIS_PRESENCE_URL, {
+  maxRetriesPerRequest: 2,
+  connectTimeout: 5000,
+  lazyConnect: false,
+  enableReadyCheck: true,
+  // Keep-alive so the HF container connection stays warm
+  keepAlive: 10000,
+});
+
+presenceClient.on('connect', () => logger.info('Presence Redis connected'));
+presenceClient.on('error', (err: Error) =>
+  logger.error('Presence Redis error', { error: err.message })
+);
+presenceClient.on('reconnecting', () => logger.warn('Presence Redis reconnecting'));
+
+export { presenceClient };
+
+// ── Key builders ─────────────────────────────────────────────────────────────
+
+const presenceKey = (uid: string) => `presence:uid:${uid}`;
+const statusKey = (uid: string) => `status:uid:${uid}`;
+
+// ── Operations ───────────────────────────────────────────────────────────────
+
+/** Map uid → socketId, mark user online. Called on WS connect. */
+export async function setOnline(uid: string, socketId: string): Promise<void> {
+  const ttl = CONFIG.PRESENCE_TTL_S;
+  // MULTI/EXEC keeps it atomic
+  await presenceClient
+    .multi()
+    .set(presenceKey(uid), socketId, 'EX', ttl)
+    .set(statusKey(uid), 'online', 'EX', ttl)
+    .exec();
+}
+
+/** Refresh TTL on heartbeat. Does not overwrite the socket id. */
+export async function refreshPresence(uid: string): Promise<void> {
+  const ttl = CONFIG.PRESENCE_TTL_S;
+  await presenceClient
+    .multi()
+    .expire(presenceKey(uid), ttl)
+    .expire(statusKey(uid), ttl)
+    .exec();
+}
+
+/** Remove user from presence. Called on WS close. */
+export async function setOffline(uid: string): Promise<void> {
+  await presenceClient
+    .multi()
+    .del(presenceKey(uid))
+    .del(statusKey(uid))
+    .exec();
+}
+
+/** Returns the socket id for a uid, or null if offline. */
+export async function getSocketId(uid: string): Promise<string | null> {
+  return presenceClient.get(presenceKey(uid));
+}
+
+/** Returns true if the user is online. */
+export async function isOnline(uid: string): Promise<boolean> {
+  const status = await presenceClient.get(statusKey(uid));
+  return status === 'online';
+}

src/services/connectionRegistry.ts

@@ -0,0 +1,100 @@
+import WebSocket from 'ws';
+
+/**
+ * In-process map of uid → WebSocket.
+ * This is NOT distributed state (that lives in Redis Bucket 1).
+ * This map is only valid for THIS process instance.
+ *
+ * On HF Spaces (single container), this is sufficient.
+ * For multi-instance horizontal scale: replace with Redis pub/sub routing.
+ */
+
+interface SocketMeta {
+  ws: WebSocket;
+  uid: string;
+  socketId: string;
+  connectedAt: number;
+  lastHeartbeat: number;
+}
+
+// Two-way map for O(1) lookups in both directions
+const byUid = new Map<string, SocketMeta>();
+const bySocketId = new Map<string, SocketMeta>();
+
+export const registry = {
+  /** Register a new connection */
+  add(socketId: string, uid: string, ws: WebSocket): void {
+    const meta: SocketMeta = {
+      ws,
+      uid,
+      socketId,
+      connectedAt: Date.now(),
+      lastHeartbeat: Date.now(),
+    };
+    // Remove any stale entry for this uid (reconnect scenario)
+    const existing = byUid.get(uid);
+    if (existing) {
+      bySocketId.delete(existing.socketId);
+      // Close the old zombie socket if it is still "open"
+      if (existing.ws.readyState === WebSocket.OPEN) {
+        existing.ws.terminate();
+      }
+    }
+    byUid.set(uid, meta);
+    bySocketId.set(socketId, meta);
+  },
+
+  /** Remove a connection by socketId */
+  remove(socketId: string): SocketMeta | undefined {
+    const meta = bySocketId.get(socketId);
+    if (!meta) return undefined;
+    bySocketId.delete(socketId);
+    // Only remove from byUid if this socket is still the current one
+    if (byUid.get(meta.uid)?.socketId === socketId) {
+      byUid.delete(meta.uid);
+    }
+    return meta;
+  },
+
+  /** Get WebSocket for a uid */
+  getByUid(uid: string): SocketMeta | undefined {
+    return byUid.get(uid);
+  },
+
+  /** Get WebSocket by its socketId */
+  getBySocketId(socketId: string): SocketMeta | undefined {
+    return bySocketId.get(socketId);
+  },
+
+  /** Update heartbeat timestamp */
+  heartbeat(socketId: string): void {
+    const meta = bySocketId.get(socketId);
+    if (meta) meta.lastHeartbeat = Date.now();
+  },
+
+  /** How many sockets are active right now */
+  size(): number {
+    return bySocketId.size;
+  },
+
+  /**
+   * Zombie pruner — iterates all connections and terminates any that
+   * haven't sent a heartbeat within 3× the expected interval.
+   * Called by a setInterval in index.ts.
+   */
+  pruneZombies(maxSilenceMs: number): number {
+    const now = Date.now();
+    let pruned = 0;
+    for (const [socketId, meta] of bySocketId) {
+      if (now - meta.lastHeartbeat > maxSilenceMs) {
+        meta.ws.terminate();
+        bySocketId.delete(socketId);
+        if (byUid.get(meta.uid)?.socketId === socketId) {
+          byUid.delete(meta.uid);
+        }
+        pruned++;
+      }
+    }
+    return pruned;
+  },
+};

src/services/friendService.ts

@@ -0,0 +1,61 @@
+import { UserModel } from '../db/mongo';
+import { FriendRequestModel } from '../models/friend';
+import { logger } from '../utils/logger';
+
+/**
+ * Check if two users are friends. Used before allowing signaling to prevent
+ * stranger signaling attacks — only friends can initiate WebRTC offers.
+ */
+export async function areFriends(uidA: string, uidB: string): Promise<boolean> {
+  const user = await UserModel.findOne({ uid: uidA, friends: uidB }, '_id').lean();
+  return !!user;
+}
+
+/** Send a friend request (fromUid → toUid). Idempotent. */
+export async function sendFriendRequest(fromUid: string, toUid: string): Promise<void> {
+  await FriendRequestModel.findOneAndUpdate(
+    { fromUid, toUid },
+    { status: 'pending' },
+    { upsert: true, new: true }
+  );
+}
+
+/** Accept a friend request. Adds each user to the other's friends list. */
+export async function acceptFriendRequest(fromUid: string, toUid: string): Promise<boolean> {
+  const req = await FriendRequestModel.findOneAndUpdate(
+    { fromUid, toUid, status: 'pending' },
+    { status: 'accepted' }
+  );
+  if (!req) return false;
+
+  // Add to both users' friend lists atomically
+  await Promise.all([
+    UserModel.updateOne({ uid: toUid }, { $addToSet: { friends: fromUid } }),
+    UserModel.updateOne({ uid: fromUid }, { $addToSet: { friends: toUid } }),
+  ]);
+
+  return true;
+}
+
+/** Reject a friend request. */
+export async function rejectFriendRequest(fromUid: string, toUid: string): Promise<void> {
+  await FriendRequestModel.findOneAndUpdate(
+    { fromUid, toUid, status: 'pending' },
+    { status: 'rejected' }
+  );
+}
+
+/** Remove a friend (unfriend). Removes from both sides. */
+export async function removeFriend(uidA: string, uidB: string): Promise<void> {
+  await Promise.all([
+    UserModel.updateOne({ uid: uidA }, { $pull: { friends: uidB } }),
+    UserModel.updateOne({ uid: uidB }, { $pull: { friends: uidA } }),
+  ]);
+  logger.info('Friendship removed', { uidA, uidB });
+}
+
+/** Get a user's friend list. Returns array of UIDs. */
+export async function getFriendList(uid: string): Promise<string[]> {
+  const user = await UserModel.findOne({ uid }, 'friends').lean();
+  return (user?.friends as string[]) ?? [];
+}

src/services/supabaseService.ts

@@ -0,0 +1,110 @@
+import { createClient, SupabaseClient } from '@supabase/supabase-js';
+import { v4 as uuidv4 } from 'uuid';
+import { CONFIG } from '../config';
+import { logger } from '../utils/logger';
+
+// ── Singleton client ──────────────────────────────────────────────────────────
+
+let _client: SupabaseClient | null = null;
+
+function getClient(): SupabaseClient {
+  if (!_client) {
+    _client = createClient(CONFIG.SUPABASE_URL, CONFIG.SUPABASE_SERVICE_KEY, {
+      auth: { persistSession: false },
+    });
+  }
+  return _client;
+}
+
+// ── Allowed MIME types ────────────────────────────────────────────────────────
+
+const ALLOWED_MIME: Set<string> = new Set([
+  'image/jpeg',
+  'image/png',
+  'image/gif',
+  'image/webp',
+  'video/mp4',
+  'video/webm',
+  'audio/mpeg',
+  'audio/ogg',
+  'audio/webm',
+  'application/pdf',
+]);
+
+// ── File validation ───────────────────────────────────────────────────────────
+
+export interface FileUploadRequest {
+  fileName: string;
+  mimeType: string;
+  sizeBytes: number;
+}
+
+export interface UploadUrlResult {
+  signedUrl: string;
+  objectPath: string;
+  publicUrl: string;
+}
+
+export function validateFileRequest(req: FileUploadRequest): string | null {
+  if (!ALLOWED_MIME.has(req.mimeType)) {
+    return `MIME type ${req.mimeType} is not allowed`;
+  }
+  if (req.sizeBytes > CONFIG.MAX_FILE_SIZE_BYTES) {
+    return `File exceeds ${CONFIG.MAX_FILE_SIZE_BYTES / 1024 / 1024} MB limit`;
+  }
+  // Strip path traversal from filename
+  const safeName = req.fileName.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 128);
+  if (!safeName) return 'Invalid file name';
+  return null;
+}
+
+export function validateFileCount(count: number): string | null {
+  if (count > CONFIG.MAX_FILE_COUNT) {
+    return `Cannot upload more than ${CONFIG.MAX_FILE_COUNT} files at once`;
+  }
+  if (count < 1) return 'File count must be at least 1';
+  return null;
+}
+
+// ── Signed upload URL generation ─────────────────────────────────────────────
+
+/**
+ * Generates a Supabase signed upload URL.
+ * The client uses this to PUT the file directly to Supabase — HF server
+ * never buffers any bytes, keeping memory usage at ~0 for file transfers.
+ *
+ * URL expires in 60 seconds — client must begin upload immediately.
+ */
+export async function generateUploadUrl(
+  uploaderUid: string,
+  req: FileUploadRequest
+): Promise<UploadUrlResult> {
+  const supabase = getClient();
+
+  // Sanitize file name
+  const safeName = req.fileName.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 128);
+  const ext = safeName.split('.').pop() ?? 'bin';
+
+  // Unique path per user prevents collisions and leakage
+  const objectPath = `users/${uploaderUid}/${uuidv4()}.${ext}`;
+
+  const { data, error } = await supabase.storage
+    .from(CONFIG.SUPABASE_BUCKET)
+    .createSignedUploadUrl(objectPath);
+
+  if (error || !data) {
+    logger.error('Supabase signed URL failed', { error: error?.message });
+    throw new Error('Could not generate upload URL');
+  }
+
+  // Derive the public URL (bucket must be public, or use signed read URL)
+  const { data: urlData } = supabase.storage
+    .from(CONFIG.SUPABASE_BUCKET)
+    .getPublicUrl(objectPath);
+
+  return {
+    signedUrl: data.signedUrl,
+    objectPath,
+    publicUrl: urlData.publicUrl,
+  };
+}

src/utils/jwt.ts

@@ -0,0 +1,42 @@
+import jwt from 'jsonwebtoken';
+import { CONFIG } from '../config';
+
+export interface JWTPayload {
+  uid: string;
+  iat?: number;
+  exp?: number;
+}
+
+/**
+ * Verifies a JWT and returns the decoded payload.
+ * Throws if the token is invalid or expired.
+ * The uid is ALWAYS extracted from the verified token — never from client input.
+ */
+export function verifyToken(token: string): JWTPayload {
+  const decoded = jwt.verify(token, CONFIG.JWT_SECRET) as JWTPayload;
+
+  if (!decoded.uid || typeof decoded.uid !== 'string') {
+    throw new Error('JWT payload missing uid field');
+  }
+
+  // Sanitize uid to prevent Redis key injection
+  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(decoded.uid)) {
+    throw new Error('JWT uid contains invalid characters');
+  }
+
+  return decoded;
+}
+
+/** Extract Bearer token from Upgrade/Authorization header or query param */
+export function extractToken(
+  authHeader: string | undefined,
+  queryToken: string | undefined
+): string {
+  if (authHeader?.startsWith('Bearer ')) {
+    return authHeader.slice(7).trim();
+  }
+  if (queryToken) {
+    return queryToken.trim();
+  }
+  throw new Error('No authorization token provided');
+}

src/utils/logger.ts

@@ -0,0 +1,30 @@
+import { CONFIG } from '../config';
+
+type Level = 'info' | 'warn' | 'error' | 'debug';
+
+const LEVELS: Record<Level, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+const MIN_LEVEL = CONFIG.NODE_ENV === 'production' ? LEVELS.info : LEVELS.debug;
+
+function log(level: Level, msg: string, meta?: Record<string, unknown>): void {
+  if (LEVELS[level] < MIN_LEVEL) return;
+
+  const entry = JSON.stringify({
+    ts: new Date().toISOString(),
+    level,
+    msg,
+    ...(meta ?? {}),
+  });
+
+  if (level === 'error') {
+    process.stderr.write(entry + '\n');
+  } else {
+    process.stdout.write(entry + '\n');
+  }
+}
+
+export const logger = {
+  info: (msg: string, meta?: Record<string, unknown>) => log('info', msg, meta),
+  warn: (msg: string, meta?: Record<string, unknown>) => log('warn', msg, meta),
+  error: (msg: string, meta?: Record<string, unknown>) => log('error', msg, meta),
+  debug: (msg: string, meta?: Record<string, unknown>) => log('debug', msg, meta),
+};

src/utils/protocol.ts

@@ -0,0 +1,98 @@
+import WebSocket from 'ws';
+
+// ── Inbound message types (client → server) ──────────────────────────────────
+export type ClientMessageType =
+  | 'heartbeat'
+  | 'offer'
+  | 'answer'
+  | 'ice-candidate'
+  | 'message'
+  | 'get-upload-url'
+  | 'relay'
+  | 'friend';
+
+// ── Outbound message types (server → client) ──────────────────────────────────
+export type ServerMessageType =
+  | 'connected'
+  | 'ice-servers'
+  | 'offer'
+  | 'answer'
+  | 'ice-candidate'
+  | 'message'
+  | 'upload-url'
+  | 'relay'
+  | 'peer-online'
+  | 'peer-offline'
+  | 'offline-flush'
+  | 'error';
+
+export interface ClientMessage {
+  type: ClientMessageType;
+  payload: Record<string, unknown>;
+  // requestId allows client to correlate responses
+  requestId?: string;
+}
+
+export interface ServerMessage {
+  type: ServerMessageType;
+  payload: Record<string, unknown>;
+  requestId?: string;
+  ts: number; // epoch ms
+}
+
+/**
+ * Parse and validate an incoming raw WS message.
+ * Returns null if the data is malformed — caller should silently drop.
+ */
+export function parseClientMessage(raw: WebSocket.RawData): ClientMessage | null {
+  try {
+    const str = raw.toString('utf8');
+    if (str.length > 65536) return null; // 64 KB hard cap — protects against flood
+
+    const obj = JSON.parse(str) as unknown;
+
+    if (
+      typeof obj !== 'object' ||
+      obj === null ||
+      typeof (obj as Record<string, unknown>).type !== 'string'
+    ) {
+      return null;
+    }
+
+    return obj as ClientMessage;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Serialize a server message.
+ * Using a single Buffer allocation avoids repeated JSON.stringify on hot paths.
+ */
+export function buildServerMessage(
+  type: ServerMessageType,
+  payload: Record<string, unknown>,
+  requestId?: string
+): Buffer {
+  const msg: ServerMessage = { type, payload, requestId, ts: Date.now() };
+  return Buffer.from(JSON.stringify(msg), 'utf8');
+}
+
+/**
+ * Send a message to a WebSocket, catching send errors silently.
+ * Avoids crashing the process when a socket closes mid-send.
+ */
+export function safeSend(
+  ws: WebSocket,
+  type: ServerMessageType,
+  payload: Record<string, unknown>,
+  requestId?: string
+): void {
+  if (ws.readyState !== WebSocket.OPEN) return;
+
+  try {
+    ws.send(buildServerMessage(type, payload, requestId));
+  } catch {
+    // Socket probably closed between the readyState check and send — ignore
+  }
+}

tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "exactOptionalPropertyTypes": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}