added /token

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: purple
-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)
+```

src/index.ts

@@ -1,5 +1,6 @@
 import http from 'http';
 import WebSocket from 'ws';
+import jwt from 'jsonwebtoken';
 import { CONFIG } from './config';
 import { connectMongo } from './db/mongo';
 import { presenceClient } from './redis/presenceClient';
@@ -9,67 +10,71 @@ 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,
-  });
+  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') {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+
+    // ── CORS headers for browser fetch ──────────────────────────────────────
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
+
+    // ── GET /health ──────────────────────────────────────────────────────────
+    if (req.method === 'GET' && url.pathname === '/health') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(
-        JSON.stringify({
-          status: 'ok',
-          connections: registry.size(),
-          ts: Date.now(),
-        })
-      );
+      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.');
+
+    // ── GET /token?uid=user1 — generates a real signed JWT for testing ───────
+    // Simple uid allowlist — only test UIDs work, not arbitrary strings
+    if (req.method === 'GET' && url.pathname === '/token') {
+      const uid = url.searchParams.get('uid') ?? '';
+      const allowed = ['user1', 'user2', 'user3', 'user4', 'user5'];
+      if (!allowed.includes(uid)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `uid must be one of: ${allowed.join(', ')}` }));
+        return;
+      }
+      const token = jwt.sign({ uid }, CONFIG.JWT_SECRET, { expiresIn: '7d' });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ token, uid, note: 'Test token — do not use in production' }));
+      return;
+    }
+
+    // ── Fallback ─────────────────────────────────────────────────────────────
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      service: 'P2P Signal Server',
+      endpoints: {
+        health: 'GET /health',
+        token:  'GET /token?uid=user1  (test only)',
+        ws:     'WS  /?token=<jwt>',
+      }
+    }));
   });
 
-  // ── 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;
-    }
+    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)
-    ) {
+    if (CONFIG.ALLOWED_ORIGINS[0] !== '*' && !CONFIG.ALLOWED_ORIGINS.includes(origin)) {
       ws.close(1008, 'Origin not allowed');
       return;
     }
@@ -79,15 +84,12 @@ async function bootstrap(): Promise<void> {
 
   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(),
@@ -95,52 +97,33 @@ async function bootstrap(): Promise<void> {
     });
   }, 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
+    client.once('error', (err: Error) => reject(new Error(`${name} Redis failed: ${err.message}`)));
     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 ────────────────────────────────────────────────────────
+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 }));
 
 async function shutdown(signal: string): Promise<void> {
-  logger.info(`Received ${signal}, shutting down gracefully`);
+  logger.info(`Received ${signal}, shutting down`);
   presenceClient.disconnect();
   messageClient.disconnect();
   process.exit(0);
 }
 
 process.on('SIGTERM', () => shutdown('SIGTERM'));
-process.on('SIGINT', () => shutdown('SIGINT'));
-
-// ── Boot ─────────────────────────────────────────────────────────────────────
+process.on('SIGINT',  () => shutdown('SIGINT'));
 
 bootstrap().catch((err) => {
   logger.error('Bootstrap failed', { error: String(err) });