javascript-solid-server 0.0.107 → 0.0.109

package/README.md

@@ -162,6 +162,10 @@ jss --help             # Show help
 | `--mongo` | Enable MongoDB-backed /db/ route | false |
 | `--mongo-url <url>` | MongoDB connection URL | mongodb://localhost:27017 |
 | `--mongo-database <name>` | MongoDB database name | solid |
+| `--webrtc` | Enable WebRTC signaling server | false |
+| `--webrtc-path <path>` | WebRTC signaling WebSocket path | /.webrtc |
+| `--tunnel` | Enable tunnel proxy (decentralized ngrok) | false |
+| `--tunnel-path <path>` | Tunnel WebSocket path | /.tunnel |
 | `-q, --quiet` | Suppress logs | false |
 
 ### Environment Variables
@@ -195,6 +199,7 @@ export JSS_PAY_RATE=10
 export JSS_MONGO=true
 export JSS_MONGO_URL=mongodb://localhost:27017
 export JSS_MONGO_DATABASE=solid
+export JSS_WEBRTC=true
 jss start
 ```
 
@@ -823,6 +828,72 @@ curl -X DELETE http://localhost:3000/db/alice/notes/1 \
 
 Supported formats: `50MB`, `1GB`, `500KB`, `1TB`
 
+## WebRTC Signaling
+
+Peer-to-peer communication via WebRTC, using JSS as the signaling server. Once peers are connected, all media and data flows directly between them.
+
+```bash
+jss start --webrtc
+```
+
+### How It Works
+
+1. Both peers connect to `wss://your.pod/.webrtc` (WebID auth required)
+2. Caller sends an SDP offer targeting the callee's WebID
+3. JSS relays the offer/answer and ICE candidates between peers
+4. Once a direct path is found, the peer-to-peer connection is established
+5. JSS steps out — video, audio, files, and data flow directly between peers
+
+### Protocol
+
+Messages are JSON over WebSocket:
+
+```js
+// Send an offer to another user
+{ "type": "offer", "to": "https://bob.example/profile/card#me", "sdp": "..." }
+
+// Receive an offer from another user
+{ "type": "offer", "from": "https://alice.example/profile/card#me", "sdp": "..." }
+
+// ICE candidate exchange
+{ "type": "candidate", "to": "https://bob.example/profile/card#me", "candidate": {...} }
+
+// Hang up
+{ "type": "hangup", "to": "https://bob.example/profile/card#me" }
+```
+
+On connect, peers receive a list of online users and get notified when others join or leave.
+
+## Tunnel Proxy (Decentralized ngrok)
+
+Expose a local dev server to the internet through your JSS pod. A tunnel client connects via WebSocket, registers a name, and receives proxied HTTP requests.
+
+```bash
+jss start --tunnel
+```
+
+### How It Works
+
+1. Tunnel client connects to `wss://your.pod/.tunnel` (WebID auth required)
+2. Client registers a name: `{ "type": "register", "name": "myapp" }`
+3. Public URL becomes available at `https://your.pod/tunnel/myapp/`
+4. HTTP requests to that URL are serialized and sent to the tunnel client over WebSocket
+5. Tunnel client forwards to localhost, returns the response
+
+### Tunnel Client Protocol
+
+```js
+// 1. Register a tunnel
+→ { "type": "register", "name": "myapp" }
+← { "type": "registered", "name": "myapp", "url": "/tunnel/myapp/" }
+
+// 2. Receive proxied HTTP requests
+← { "type": "request", "id": "uuid", "method": "GET", "path": "/api/hello", "headers": {...} }
+
+// 3. Return the response
+→ { "type": "response", "id": "uuid", "status": 200, "headers": {...}, "body": "..." }
+```
+
 ## HTTP 402 Paid Access
 
 Monetize API endpoints with per-request satoshi payments. Resources under `/pay/*` require NIP-98 authentication and a positive balance.

package/bin/jss.js

@@ -65,6 +65,12 @@ program
   .option('--no-nostr', 'Disable Nostr relay')
   .option('--nostr-path <path>', 'Nostr relay WebSocket path (default: /relay)')
   .option('--nostr-max-events <n>', 'Max events in relay memory (default: 1000)', parseInt)
+  .option('--webrtc', 'Enable WebRTC signaling server')
+  .option('--no-webrtc', 'Disable WebRTC signaling server')
+  .option('--webrtc-path <path>', 'WebRTC signaling WebSocket path (default: /.webrtc)')
+  .option('--tunnel', 'Enable tunnel proxy (decentralized ngrok)')
+  .option('--no-tunnel', 'Disable tunnel proxy')
+  .option('--tunnel-path <path>', 'Tunnel WebSocket path (default: /.tunnel)')
   .option('--activitypub', 'Enable ActivityPub federation')
   .option('--no-activitypub', 'Disable ActivityPub federation')
   .option('--ap-username <name>', 'ActivityPub username (default: me)')
@@ -142,6 +148,10 @@ program
         nostr: config.nostr,
         nostrPath: config.nostrPath,
         nostrMaxEvents: config.nostrMaxEvents,
+        webrtc: config.webrtc,
+        webrtcPath: config.webrtcPath,
+        tunnel: config.tunnel,
+        tunnelPath: config.tunnelPath,
         activitypub: config.activitypub,
         apUsername: config.apUsername,
         apDisplayName: config.apDisplayName,
@@ -186,6 +196,8 @@ program
         if (config.solidosUi) console.log('  SolidOS UI: enabled (modern interface)');
         if (config.git) console.log('  Git: enabled (clone/push support)');
         if (config.nostr) console.log(`  Nostr: enabled (${config.nostrPath})`);
+        if (config.webrtc) console.log(`  WebRTC: enabled (${config.webrtcPath || '/.webrtc'})`);
+        if (config.tunnel) console.log(`  Tunnel: enabled (${config.tunnelPath || '/.tunnel'})`);
         if (config.activitypub) console.log(`  ActivityPub: enabled (@${config.apUsername || 'me'})`);
         if (config.singleUser) console.log(`  Single-user: ${config.singleUserName || 'me'} (registration disabled)`);
         else if (config.inviteOnly) console.log('  Registration: invite-only');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.107",
+  "version": "0.0.109",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

package/src/config.js

@@ -54,6 +54,14 @@ export const defaults = {
   nostrPath: '/relay',
   nostrMaxEvents: 1000,
 
+  // WebRTC signaling
+  webrtc: false,
+  webrtcPath: '/.webrtc',
+
+  // Tunnel (decentralized ngrok)
+  tunnel: false,
+  tunnelPath: '/.tunnel',
+
   // ActivityPub federation
   activitypub: false,
   apUsername: 'me',
@@ -134,6 +142,10 @@ const envMap = {
   JSS_NOSTR: 'nostr',
   JSS_NOSTR_PATH: 'nostrPath',
   JSS_NOSTR_MAX_EVENTS: 'nostrMaxEvents',
+  JSS_WEBRTC: 'webrtc',
+  JSS_WEBRTC_PATH: 'webrtcPath',
+  JSS_TUNNEL: 'tunnel',
+  JSS_TUNNEL_PATH: 'tunnelPath',
   JSS_ACTIVITYPUB: 'activitypub',
   JSS_AP_USERNAME: 'apUsername',
   JSS_AP_DISPLAY_NAME: 'apDisplayName',

package/src/handlers/pay.js

@@ -424,13 +424,17 @@ export function createPayHandler(options = {}) {
         return reply.code(400).send({ error: 'Amount must be positive' });
       }
 
-      // Check sat balance
+      // Determine payment currency — chain-specific (e.g. "tbtc4") or generic "sat"
+      const currency = (body?.currency && payChains && payChains.includes(body.currency))
+        ? body.currency : null;
+
+      // Check balance
       const didUri = pubkeyToDidNostr(pubkey);
       const ledger = await readLedger();
-      const balance = getBalance(ledger, didUri);
+      const balance = getBalance(ledger, didUri, currency);
       if (balance < satCost) {
         return reply.code(402).send({
-          error: 'Insufficient sat balance',
+          error: `Insufficient ${currency || 'sat'} balance`,
           balance,
           cost: satCost,
           rate: payRate,
@@ -457,8 +461,8 @@ export function createPayHandler(options = {}) {
         return reply.code(500).send({ error: `Transfer failed: ${err.message}` });
       }
 
-      // Debit sats from buyer
-      debit(ledger, didUri, satCost);
+      // Debit from buyer
+      debit(ledger, didUri, satCost, currency);
       await writeLedger(ledger);
 
       return reply.send({
@@ -466,8 +470,8 @@ export function createPayHandler(options = {}) {
         ticker,
         cost: satCost,
         rate: payRate,
-        balance: getBalance(ledger, didUri),
-        unit: 'sat',
+        balance: getBalance(ledger, didUri, currency),
+        unit: currency || 'sat',
         txid: result.txid,
         proof: {
           state: result.state,
@@ -984,21 +988,41 @@ export function createPayHandler(options = {}) {
 
       const didUri = pubkeyToDidNostr(pubkey);
       const ledger = await readLedger();
-      const { success, balance } = debit(ledger, didUri, cost);
 
-      if (!success) {
-        return reply.code(402).send({
+      // Try generic sat balance first, then fall back to chain balances
+      const currency = request.headers['x-pay-currency'] || null;
+      let payUnit = currency && payChains && payChains.includes(currency) ? currency : null;
+      let result = debit(ledger, didUri, cost, payUnit);
+
+      // If generic sat failed and no explicit currency, try each chain balance
+      if (!result.success && !payUnit && payChains) {
+        for (const chainId of payChains) {
+          result = debit(ledger, didUri, cost, chainId);
+          if (result.success) { payUnit = chainId; break; }
+        }
+      }
+
+      if (!result.success) {
+        const response = {
           error: 'Payment Required',
-          balance,
+          balance: result.balance,
           cost,
           unit: 'sat',
           deposit: '/pay/.deposit'
-        });
+        };
+        if (payChains) {
+          response.balances = {};
+          for (const chainId of payChains) {
+            response.balances[chainId] = getBalance(ledger, didUri, chainId);
+          }
+        }
+        return reply.code(402).send(response);
       }
 
       await writeLedger(ledger);
-      reply.header('X-Balance', String(balance));
+      reply.header('X-Balance', String(result.balance));
       reply.header('X-Cost', String(cost));
+      if (payUnit) reply.header('X-Pay-Currency', payUnit);
       return; // continue to normal resource handler
     }
 

package/src/server.js

@@ -18,6 +18,8 @@ import { createPayHandler, isPayRequest } from './handlers/pay.js';
 import { activityPubPlugin, getActorHandler } from './ap/index.js';
 import { remoteStoragePlugin } from './remotestorage.js';
 import { dbPlugin } from './db/index.js';
+import { webrtcPlugin } from './webrtc/index.js';
+import { tunnelPlugin } from './tunnel/index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -74,6 +76,12 @@ export function createServer(options = {}) {
   const nostrEnabled = options.nostr ?? false;
   const nostrPath = options.nostrPath ?? '/relay';
   const nostrMaxEvents = options.nostrMaxEvents ?? 1000;
+  // WebRTC signaling is OFF by default
+  const webrtcEnabled = options.webrtc ?? false;
+  const webrtcPath = options.webrtcPath ?? '/.webrtc';
+  // Tunnel proxy is OFF by default
+  const tunnelEnabled = options.tunnel ?? false;
+  const tunnelPath = options.tunnelPath ?? '/.tunnel';
   // ActivityPub federation is OFF by default
   const activitypubEnabled = options.activitypub ?? false;
   const apUsername = options.apUsername ?? 'me';
@@ -240,6 +248,16 @@ export function createServer(options = {}) {
     });
   }
 
+  // Register WebRTC signaling if enabled
+  if (webrtcEnabled) {
+    fastify.register(webrtcPlugin, { path: webrtcPath });
+  }
+
+  // Register tunnel proxy if enabled
+  if (tunnelEnabled) {
+    fastify.register(tunnelPlugin, { path: tunnelPath });
+  }
+
   // Register ActivityPub plugin if enabled
   if (activitypubEnabled) {
     fastify.register(activityPubPlugin, {
@@ -331,6 +349,15 @@ export function createServer(options = {}) {
       return;
     }
 
+    // Allow WebRTC and tunnel endpoints through when enabled
+    const urlNoQuery = request.url.split('?')[0];
+    if (tunnelEnabled && (urlNoQuery === tunnelPath || urlNoQuery.startsWith('/tunnel/'))) {
+      return;
+    }
+    if (webrtcEnabled && urlNoQuery === webrtcPath) {
+      return;
+    }
+
     const segments = request.url.split('/').map(s => s.split('?')[0]); // Remove query strings
     const hasForbiddenDotfile = segments.some(seg =>
       seg.startsWith('.') &&
@@ -405,6 +432,8 @@ export function createServer(options = {}) {
         request.url.startsWith('/storage/') ||
         (payEnabled && isPayRequest(request.url)) ||
         (mongoEnabled && (request.url === '/db' || request.url.startsWith('/db/'))) ||
+        (webrtcEnabled && (request.url === webrtcPath || request.url.startsWith(webrtcPath + '?'))) ||
+        (tunnelEnabled && (request.url === tunnelPath || request.url.startsWith(tunnelPath + '?') || request.url.startsWith('/tunnel/'))) ||
         mashlibPaths.some(p => request.url === p || request.url.startsWith(p + '.'))) {
       return;
     }

package/src/tunnel/index.js

@@ -0,0 +1,226 @@
+/**
+ * Tunnel Plugin — Decentralized ngrok
+ *
+ * Tunnels HTTP traffic to a local dev server through JSS via WebSocket.
+ * A tunnel client connects over WebSocket, registers a name, and receives
+ * proxied HTTP requests which it forwards to localhost.
+ *
+ * Usage: jss start --tunnel
+ * Tunnel client connects to: wss://your.pod/.tunnel
+ * Public URL: https://your.pod/tunnel/{name}/path
+ *
+ * Tunnel client protocol (JSON over WebSocket):
+ *   → { type: "register", name: "myapp" }
+ *   ← { type: "registered", name: "myapp", url: "/tunnel/myapp/" }
+ *   ← { type: "request", id: "<uuid>", method: "GET", path: "/api/hello", headers: {...}, body: "..." }
+ *   → { type: "response", id: "<uuid>", status: 200, headers: {...}, body: "..." }
+ *   ← { type: "error", message: "..." }
+ */
+
+import websocket from '@fastify/websocket';
+import { getWebIdFromRequestAsync } from '../auth/token.js';
+import { randomUUID } from 'crypto';
+
+const REQUEST_TIMEOUT = 30000; // 30s timeout for tunnel responses
+const MAX_MESSAGE_SIZE = 10 * 1024 * 1024; // 10MB
+
+/**
+ * @param {object} fastify - Fastify instance
+ * @param {object} options - Options
+ * @param {string} options.path - WebSocket path for tunnel clients (default: '/.tunnel')
+ */
+export async function tunnelPlugin(fastify, options = {}) {
+  const wsPath = options.path || '/.tunnel';
+
+  // Instance-scoped: tunnel name → { socket, webId }
+  const tunnels = new Map();
+  // Pending HTTP requests waiting for tunnel response: id → { resolve, timer }
+  const pending = new Map();
+
+  if (!fastify.websocketServer) {
+    await fastify.register(websocket);
+  }
+
+  fastify.addHook('onClose', async () => {
+    for (const [, tunnel] of tunnels) {
+      tunnel.socket.close();
+    }
+    tunnels.clear();
+    for (const [, p] of pending) {
+      clearTimeout(p.timer);
+      p.resolve({ status: 502, headers: {}, body: 'Tunnel shutting down' });
+    }
+    pending.clear();
+  });
+
+  // WebSocket endpoint for tunnel clients
+  fastify.get(wsPath, { websocket: true }, async (connection, request) => {
+    const socket = connection.socket;
+
+    // Authenticate
+    const { webId } = await getWebIdFromRequestAsync(request);
+    if (!webId) {
+      socket.send(JSON.stringify({ type: 'error', message: 'Authentication required' }));
+      socket.close();
+      return;
+    }
+
+    let tunnelName = null;
+
+    socket.on('message', (data) => {
+      const raw = Buffer.isBuffer(data) ? data : Buffer.from(data);
+      if (raw.byteLength > MAX_MESSAGE_SIZE) {
+        socket.send(JSON.stringify({ type: 'error', message: 'Message too large' }));
+        return;
+      }
+
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        socket.send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
+        return;
+      }
+
+      if (msg.type === 'register') {
+        // Register a tunnel name
+        const name = (msg.name || '').replace(/[^a-zA-Z0-9_-]/g, '');
+        if (!name) {
+          socket.send(JSON.stringify({ type: 'error', message: 'Invalid tunnel name' }));
+          return;
+        }
+
+        const existing = tunnels.get(name);
+        if (existing && existing.webId !== webId) {
+          socket.send(JSON.stringify({ type: 'error', message: 'Tunnel name taken by another user' }));
+          return;
+        }
+
+        // Close old tunnel with same name from same user
+        if (existing) {
+          existing.socket.close();
+        }
+
+        tunnelName = name;
+        tunnels.set(name, { socket, webId });
+        socket.send(JSON.stringify({ type: 'registered', name, url: `/tunnel/${name}/` }));
+
+      } else if (msg.type === 'response') {
+        // Tunnel client returning an HTTP response
+        if (!msg.id) return;
+        const p = pending.get(msg.id);
+        if (p) {
+          clearTimeout(p.timer);
+          pending.delete(msg.id);
+          p.resolve({
+            status: msg.status || 502,
+            headers: msg.headers || {},
+            body: msg.body || '',
+            bodyEncoding: msg.bodyEncoding
+          });
+        }
+      }
+    });
+
+    socket.on('close', () => {
+      if (tunnelName && tunnels.get(tunnelName)?.socket === socket) {
+        tunnels.delete(tunnelName);
+        // Resolve pending requests for this tunnel only with 502
+        for (const [id, p] of pending) {
+          if (p.tunnelName === tunnelName) {
+            clearTimeout(p.timer);
+            pending.delete(id);
+            p.resolve({ status: 502, headers: {}, body: 'Tunnel disconnected' });
+          }
+        }
+      }
+    });
+
+    socket.on('error', () => {});
+  });
+
+  // HTTP proxy: /tunnel/{name}/*
+  fastify.all('/tunnel/:name/*', async (request, reply) => {
+    const { name } = request.params;
+    const tunnel = tunnels.get(name);
+
+    if (!tunnel || tunnel.socket.readyState !== 1) {
+      return reply.code(502).send({ error: 'Bad Gateway', message: 'Tunnel not connected' });
+    }
+
+    // Build the downstream path (strip /tunnel/{name} prefix)
+    const fullPath = request.url.replace(`/tunnel/${name}`, '') || '/';
+    const id = randomUUID();
+
+    // Serialize the HTTP request
+    const tunnelReq = Object.create(null);
+    tunnelReq.type = 'request';
+    tunnelReq.id = id;
+    tunnelReq.method = request.method;
+    tunnelReq.path = fullPath;
+    tunnelReq.headers = Object.create(null);
+    // Forward relevant headers (skip hop-by-hop)
+    const skipHeaders = new Set(['host', 'connection', 'upgrade', 'transfer-encoding', 'cookie', 'authorization', 'proxy-authorization']);
+    for (const [k, v] of Object.entries(request.headers)) {
+      if (!skipHeaders.has(k.toLowerCase())) {
+        tunnelReq.headers[k] = v;
+      }
+    }
+    // Forward body if present
+    if (request.body) {
+      tunnelReq.body = Buffer.isBuffer(request.body)
+        ? request.body.toString('base64')
+        : typeof request.body === 'string' ? request.body : JSON.stringify(request.body);
+      tunnelReq.bodyEncoding = Buffer.isBuffer(request.body) ? 'base64' : 'utf8';
+    }
+
+    // Send to tunnel client and wait for response
+    const responsePromise = new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        resolve({ status: 504, headers: {}, body: 'Gateway Timeout' });
+      }, REQUEST_TIMEOUT);
+      pending.set(id, { resolve, timer, tunnelName: name });
+    });
+
+    try {
+      tunnel.socket.send(JSON.stringify(tunnelReq));
+    } catch {
+      const p = pending.get(id);
+      if (p) { clearTimeout(p.timer); pending.delete(id); }
+      return reply.code(502).send({ error: 'Bad Gateway', message: 'Failed to reach tunnel client' });
+    }
+
+    const res = await responsePromise;
+
+    // Set response headers
+    const hopHeaders = new Set(['connection', 'transfer-encoding', 'keep-alive', 'set-cookie']);
+    for (const [k, v] of Object.entries(res.headers)) {
+      if (!hopHeaders.has(k.toLowerCase())) {
+        reply.header(k, v);
+      }
+    }
+
+    // Decode body if base64
+    const body = res.bodyEncoding === 'base64' && res.body
+      ? Buffer.from(res.body, 'base64')
+      : res.body || '';
+
+    return reply.code(res.status).send(body);
+  });
+
+  // Also handle /tunnel/{name} without trailing path
+  fastify.all('/tunnel/:name', async (request, reply) => {
+    // Redirect to add trailing slash, or proxy as root
+    const { name } = request.params;
+    const tunnel = tunnels.get(name);
+
+    if (!tunnel || tunnel.socket.readyState !== 1) {
+      return reply.code(502).send({ error: 'Bad Gateway', message: 'Tunnel not connected' });
+    }
+
+    return reply.redirect(308, `/tunnel/${name}/`);
+  });
+}
+
+export default tunnelPlugin;

package/src/webrtc/index.js

@@ -0,0 +1,159 @@
+/**
+ * WebRTC Signaling Server Plugin
+ *
+ * Lightweight signaling server for WebRTC peer-to-peer connections.
+ * Relays SDP offers/answers and ICE candidates between authenticated users.
+ * The actual media/data flow directly between peers — JSS just introduces them.
+ *
+ * Usage: jss start --webrtc
+ * Endpoint: wss://your.pod/.webrtc
+ *
+ * Protocol (JSON over WebSocket):
+ *   → { type: "offer",     to: "<webid>", sdp: "..." }
+ *   → { type: "answer",    to: "<webid>", sdp: "..." }
+ *   → { type: "candidate", to: "<webid>", candidate: {...} }
+ *   → { type: "hangup",    to: "<webid>" }
+ *   ← { type: "offer",     from: "<webid>", sdp: "..." }
+ *   ← { type: "answer",    from: "<webid>", sdp: "..." }
+ *   ← { type: "candidate", from: "<webid>", candidate: {...} }
+ *   ← { type: "hangup",    from: "<webid>" }
+ *   ← { type: "error",     message: "..." }
+ *   ← { type: "peers",     you: "<webid>", peers: ["<webid>", ...] }
+ *   ← { type: "peer-joined", webId: "<webid>" }
+ *   ← { type: "peer-left",   webId: "<webid>" }
+ */
+
+import websocket from '@fastify/websocket';
+import { getWebIdFromRequestAsync } from '../auth/token.js';
+
+const ALLOWED_TYPES = new Set(['offer', 'answer', 'candidate', 'hangup']);
+const MAX_MESSAGE_SIZE = 64 * 1024; // 64KB
+
+/**
+ * Register WebRTC signaling routes on Fastify instance
+ *
+ * @param {object} fastify - Fastify instance
+ * @param {object} options - Options
+ * @param {string} options.path - WebSocket path (default: '/.webrtc')
+ */
+export async function webrtcPlugin(fastify, options = {}) {
+  const path = options.path || '/.webrtc';
+
+  // Instance-scoped peer state
+  const peers = new Map();
+
+  // Only register @fastify/websocket if not already registered
+  if (!fastify.websocketServer) {
+    await fastify.register(websocket);
+  }
+
+  // Clean up all connections on server close
+  fastify.addHook('onClose', async () => {
+    for (const [, socket] of peers) {
+      socket.close();
+    }
+    peers.clear();
+  });
+
+  function broadcast(senderWebId, msg) {
+    const data = JSON.stringify(msg);
+    for (const [id, socket] of peers) {
+      if (id !== senderWebId && socket.readyState === 1) {
+        try { socket.send(data); } catch { /* socket closed between check and send */ }
+      }
+    }
+  }
+
+  fastify.get(path, { websocket: true }, async (connection, request) => {
+    const socket = connection.socket;
+
+    // Authenticate the connection
+    const { webId } = await getWebIdFromRequestAsync(request);
+    if (!webId) {
+      socket.send(JSON.stringify({ type: 'error', message: 'Authentication required' }));
+      socket.close();
+      return;
+    }
+
+    // Register this peer (close old connection if reconnecting)
+    const existing = peers.get(webId);
+    const isReconnect = !!existing;
+    if (existing) {
+      peers.delete(webId);
+      existing.close();
+    }
+    peers.set(webId, socket);
+    socket.webId = webId;
+
+    // Notify the peer of their identity and online peers
+    socket.send(JSON.stringify({
+      type: 'peers',
+      you: webId,
+      peers: [...peers.keys()].filter(id => id !== webId)
+    }));
+
+    // Only broadcast peer-joined for new connections, not reconnects
+    if (!isReconnect) {
+      broadcast(webId, { type: 'peer-joined', webId });
+    }
+
+    socket.on('message', (data) => {
+      // Enforce max message size (Buffer.byteLength for reliable byte count)
+      const raw = Buffer.isBuffer(data) ? data : Buffer.from(data);
+      if (raw.byteLength > MAX_MESSAGE_SIZE) {
+        socket.send(JSON.stringify({ type: 'error', message: 'Message too large' }));
+        return;
+      }
+
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        socket.send(JSON.stringify({ type: 'error', message: 'Invalid JSON' }));
+        return;
+      }
+
+      if (!msg.to || !msg.type) {
+        socket.send(JSON.stringify({ type: 'error', message: 'Missing "to" or "type" field' }));
+        return;
+      }
+
+      // Only relay known signaling types
+      if (!ALLOWED_TYPES.has(msg.type)) {
+        socket.send(JSON.stringify({ type: 'error', message: `Unknown type "${msg.type}"` }));
+        return;
+      }
+
+      const target = peers.get(msg.to);
+      if (!target || target.readyState !== 1) {
+        socket.send(JSON.stringify({ type: 'error', message: 'Peer not online', peer: msg.to }));
+        return;
+      }
+
+      // Build relay payload with whitelisted fields only (prevent prototype pollution)
+      const relay = Object.create(null);
+      relay.type = msg.type;
+      relay.from = webId;
+      if (typeof msg.sdp === 'string') relay.sdp = msg.sdp;
+      if (msg.candidate != null && typeof msg.candidate === 'object' && !Array.isArray(msg.candidate)) {
+        relay.candidate = msg.candidate;
+      }
+      try { target.send(JSON.stringify(relay)); } catch {
+        socket.send(JSON.stringify({ type: 'error', message: 'Peer not online', peer: msg.to }));
+      }
+    });
+
+    socket.on('close', () => {
+      // Only remove if this socket is still the registered one (not replaced by reconnect)
+      if (peers.get(webId) === socket) {
+        peers.delete(webId);
+        broadcast(webId, { type: 'peer-left', webId });
+      }
+    });
+
+    // Error handler: close event will follow and handle cleanup
+    socket.on('error', () => {});
+  });
+}
+
+export default webrtcPlugin;

package/test/tunnel.test.js

@@ -0,0 +1,202 @@
+/**
+ * Tunnel Proxy Tests
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import { WebSocket } from 'ws';
+import {
+  startTestServer,
+  stopTestServer,
+  createTestPod,
+  getBaseUrl,
+  getPodToken
+} from './helpers.js';
+
+describe('Tunnel Proxy', () => {
+  let wsUrl, baseUrl;
+
+  before(async () => {
+    await startTestServer({ tunnel: true });
+    await createTestPod('tunneler');
+    baseUrl = getBaseUrl();
+    wsUrl = baseUrl.replace('http', 'ws') + '/.tunnel';
+  });
+
+  after(async () => {
+    await stopTestServer();
+  });
+
+  function connectTunnel() {
+    const token = getPodToken('tunneler');
+    return new WebSocket(wsUrl, {
+      headers: { 'Authorization': `Bearer ${token}` }
+    });
+  }
+
+  function waitMsg(ws, type, timeout = 5000) {
+    return new Promise((resolve, reject) => {
+      function handler(data) {
+        const msg = JSON.parse(data.toString());
+        if (msg.type === type) {
+          clearTimeout(timer);
+          ws.removeListener('message', handler);
+          ws.removeListener('close', onClose);
+          resolve(msg);
+        }
+      }
+      function onClose() {
+        clearTimeout(timer);
+        ws.removeListener('message', handler);
+        reject(new Error(`WebSocket closed while waiting for "${type}"`));
+      }
+      const timer = setTimeout(() => {
+        ws.removeListener('message', handler);
+        ws.removeListener('close', onClose);
+        reject(new Error(`Timeout waiting for "${type}"`));
+      }, timeout);
+      ws.on('message', handler);
+      ws.on('close', onClose);
+    });
+  }
+
+  describe('Registration', () => {
+    it('should reject unauthenticated connections', async () => {
+      const ws = new WebSocket(wsUrl);
+      const msg = await waitMsg(ws, 'error');
+      assert.ok(msg.message.includes('Authentication'));
+      ws.close();
+    });
+
+    it('should register a tunnel name', async () => {
+      const ws = connectTunnel();
+      await new Promise(r => ws.on('open', r));
+
+      ws.send(JSON.stringify({ type: 'register', name: 'myapp' }));
+      const msg = await waitMsg(ws, 'registered');
+      assert.strictEqual(msg.name, 'myapp');
+      assert.strictEqual(msg.url, '/tunnel/myapp/');
+
+      ws.close();
+      await new Promise(r => setTimeout(r, 50));
+    });
+
+    it('should reject invalid tunnel names', async () => {
+      const ws = connectTunnel();
+      await new Promise(r => ws.on('open', r));
+
+      ws.send(JSON.stringify({ type: 'register', name: '...' }));
+      const msg = await waitMsg(ws, 'error');
+      assert.ok(msg.message.includes('Invalid'));
+
+      ws.close();
+      await new Promise(r => setTimeout(r, 50));
+    });
+  });
+
+  describe('HTTP Proxying', () => {
+    it('should proxy GET requests through the tunnel', async () => {
+      const ws = connectTunnel();
+      await new Promise(r => ws.on('open', r));
+
+      // Register tunnel
+      ws.send(JSON.stringify({ type: 'register', name: 'testapp' }));
+      await waitMsg(ws, 'registered');
+
+      // Listen for tunnel requests and respond
+      ws.on('message', (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.type === 'request') {
+          ws.send(JSON.stringify({
+            type: 'response',
+            id: msg.id,
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ hello: 'world', path: msg.path })
+          }));
+        }
+      });
+
+      // Make HTTP request through the tunnel
+      const res = await fetch(`${baseUrl}/tunnel/testapp/api/hello`);
+      assert.strictEqual(res.status, 200);
+      const body = await res.json();
+      assert.strictEqual(body.hello, 'world');
+      assert.strictEqual(body.path, '/api/hello');
+
+      ws.close();
+      await new Promise(r => setTimeout(r, 50));
+    });
+
+    it('should proxy POST requests with body', async () => {
+      const ws = connectTunnel();
+      await new Promise(r => ws.on('open', r));
+
+      ws.send(JSON.stringify({ type: 'register', name: 'postapp' }));
+      await waitMsg(ws, 'registered');
+
+      ws.on('message', (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.type === 'request') {
+          assert.strictEqual(msg.method, 'POST');
+          ws.send(JSON.stringify({
+            type: 'response',
+            id: msg.id,
+            status: 201,
+            headers: { 'content-type': 'text/plain' },
+            body: 'Created'
+          }));
+        }
+      });
+
+      const res = await fetch(`${baseUrl}/tunnel/postapp/items`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: 'test' })
+      });
+      assert.strictEqual(res.status, 201);
+      assert.strictEqual(await res.text(), 'Created');
+
+      ws.close();
+      await new Promise(r => setTimeout(r, 50));
+    });
+
+    it('should return 502 for unregistered tunnel', async () => {
+      const res = await fetch(`${baseUrl}/tunnel/nonexistent/path`);
+      assert.strictEqual(res.status, 502);
+    });
+
+    it('should forward custom headers', async () => {
+      const ws = connectTunnel();
+      await new Promise(r => ws.on('open', r));
+
+      ws.send(JSON.stringify({ type: 'register', name: 'headerapp' }));
+      await waitMsg(ws, 'registered');
+
+      let receivedHeaders;
+      ws.on('message', (data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.type === 'request') {
+          receivedHeaders = msg.headers;
+          ws.send(JSON.stringify({
+            type: 'response',
+            id: msg.id,
+            status: 200,
+            headers: { 'x-custom-response': 'from-tunnel' },
+            body: 'ok'
+          }));
+        }
+      });
+
+      const res = await fetch(`${baseUrl}/tunnel/headerapp/`, {
+        headers: { 'X-Custom-Request': 'to-tunnel' }
+      });
+      assert.strictEqual(res.status, 200);
+      assert.strictEqual(res.headers.get('x-custom-response'), 'from-tunnel');
+      assert.strictEqual(receivedHeaders['x-custom-request'], 'to-tunnel');
+
+      ws.close();
+      await new Promise(r => setTimeout(r, 50));
+    });
+  });
+});

package/test/webrtc.test.js

@@ -0,0 +1,212 @@
+/**
+ * WebRTC Signaling Server Tests
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import { WebSocket } from 'ws';
+import {
+  startTestServer,
+  stopTestServer,
+  createTestPod,
+  getBaseUrl,
+  getPodToken
+} from './helpers.js';
+
+describe('WebRTC Signaling', () => {
+  let wsUrl;
+
+  before(async () => {
+    await startTestServer({ webrtc: true });
+    await createTestPod('alice');
+    await createTestPod('bob');
+    const base = getBaseUrl();
+    wsUrl = base.replace('http', 'ws') + '/.webrtc';
+  });
+
+  after(async () => {
+    await stopTestServer();
+  });
+
+  /** Create an authenticated WebSocket for a pod user */
+  function connectPeer(podName) {
+    const token = getPodToken(podName);
+    const ws = new WebSocket(wsUrl, {
+      headers: { 'Authorization': `Bearer ${token}` }
+    });
+    return ws;
+  }
+
+  /** Connect a peer and wait for the 'peers' welcome message */
+  async function connectAndWait(podName) {
+    const ws = connectPeer(podName);
+    const msg = await waitForMessage(ws, 'peers');
+    return { ws, ...msg };
+  }
+
+  /** Wait for a specific message type from a WebSocket */
+  function waitForMessage(ws, type, timeout = 3000) {
+    return new Promise((resolve, reject) => {
+      function handler(data) {
+        const msg = JSON.parse(data.toString());
+        if (msg.type === type) {
+          clearTimeout(timer);
+          ws.removeListener('message', handler);
+          ws.removeListener('close', onClose);
+          resolve(msg);
+        }
+      }
+      function onClose() {
+        clearTimeout(timer);
+        ws.removeListener('message', handler);
+        reject(new Error(`WebSocket closed while waiting for "${type}"`));
+      }
+      const timer = setTimeout(() => {
+        ws.removeListener('message', handler);
+        ws.removeListener('close', onClose);
+        reject(new Error(`Timeout waiting for "${type}"`));
+      }, timeout);
+      ws.on('message', handler);
+      ws.on('close', onClose);
+    });
+  }
+
+  /** Collect messages from a WebSocket for a duration */
+  function collectMessages(ws, duration = 500) {
+    return new Promise((resolve) => {
+      const msgs = [];
+      const handler = (data) => msgs.push(JSON.parse(data.toString()));
+      ws.on('message', handler);
+      setTimeout(() => {
+        ws.removeListener('message', handler);
+        resolve(msgs);
+      }, duration);
+    });
+  }
+
+  describe('Authentication', () => {
+    it('should reject unauthenticated connections', async () => {
+      const ws = new WebSocket(wsUrl);
+
+      const msg = await waitForMessage(ws, 'error');
+      assert.strictEqual(msg.type, 'error');
+      assert.ok(msg.message.includes('Authentication'));
+      ws.close();
+    });
+
+    it('should accept authenticated connections', async () => {
+      const ws = connectPeer('alice');
+
+      const msg = await waitForMessage(ws, 'peers');
+      assert.strictEqual(msg.type, 'peers');
+      assert.ok(msg.you, 'Should include own WebID');
+      assert.ok(Array.isArray(msg.peers), 'Should include peers list');
+      ws.close();
+    });
+  });
+
+  describe('Peer Presence and Signaling Relay', () => {
+    it('should handle full signaling lifecycle', async () => {
+      // Alice connects first — should see no peers
+      const { ws: alice, you: aliceId } = await connectAndWait('alice');
+
+      // Bob joins — set up listener for peer-joined before bob connects
+      const joinPromise = waitForMessage(alice, 'peer-joined');
+      const { ws: bob, you: bobId, peers: bobPeerList } = await connectAndWait('bob');
+
+      // Bob should see alice in the peer list
+      assert.strictEqual(bobPeerList.length, 1, 'Bob should see Alice');
+
+      // Alice should get peer-joined notification
+      const joinMsg = await joinPromise;
+      assert.strictEqual(joinMsg.type, 'peer-joined');
+
+      // 1. Alice sends offer to Bob
+      const offerPromise = waitForMessage(bob, 'offer');
+      alice.send(JSON.stringify({ type: 'offer', to: bobId, sdp: 'v=0\r\n' }));
+
+      const offer = await offerPromise;
+      assert.strictEqual(offer.type, 'offer');
+      assert.strictEqual(offer.from, aliceId);
+      assert.ok(offer.sdp, 'Should include SDP');
+      assert.strictEqual(offer.to, undefined, 'Should strip "to" field');
+
+      // 2. Bob sends answer to Alice
+      const answerPromise = waitForMessage(alice, 'answer');
+      bob.send(JSON.stringify({ type: 'answer', to: aliceId, sdp: 'v=0\r\n' }));
+
+      const answer = await answerPromise;
+      assert.strictEqual(answer.type, 'answer');
+      assert.strictEqual(answer.from, bobId);
+
+      // 3. Alice sends ICE candidate to Bob
+      const candidatePromise = waitForMessage(bob, 'candidate');
+      alice.send(JSON.stringify({
+        type: 'candidate', to: bobId,
+        candidate: { candidate: 'candidate:1 1 UDP 2122252543 192.168.1.1 12345 typ host', sdpMid: '0' }
+      }));
+
+      const candidate = await candidatePromise;
+      assert.strictEqual(candidate.type, 'candidate');
+      assert.ok(candidate.candidate.candidate);
+
+      // 4. Alice sends hangup to Bob
+      const hangupPromise = waitForMessage(bob, 'hangup');
+      alice.send(JSON.stringify({ type: 'hangup', to: bobId }));
+
+      const hangup = await hangupPromise;
+      assert.strictEqual(hangup.type, 'hangup');
+      assert.strictEqual(hangup.from, aliceId);
+
+      // 5. Bob leaves — alice should get notified
+      const leavePromise = waitForMessage(alice, 'peer-left');
+      bob.close();
+
+      const leaveMsg = await leavePromise;
+      assert.strictEqual(leaveMsg.type, 'peer-left');
+
+      alice.close();
+      await new Promise(r => setTimeout(r, 100));
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should reject invalid JSON', async () => {
+      const alice = connectPeer('alice');
+      await waitForMessage(alice, 'peers');
+
+      alice.send('not json');
+      const err = await waitForMessage(alice, 'error');
+      assert.strictEqual(err.message, 'Invalid JSON');
+
+      alice.close();
+    });
+
+    it('should reject messages without "to" field', async () => {
+      const alice = connectPeer('alice');
+      await waitForMessage(alice, 'peers');
+
+      alice.send(JSON.stringify({ type: 'offer', sdp: '...' }));
+      const err = await waitForMessage(alice, 'error');
+      assert.ok(err.message.includes('Missing'));
+
+      alice.close();
+    });
+
+    it('should error when target peer is not online', async () => {
+      const alice = connectPeer('alice');
+      await waitForMessage(alice, 'peers');
+
+      alice.send(JSON.stringify({
+        type: 'offer',
+        to: 'https://nobody.example/profile/card#me',
+        sdp: '...'
+      }));
+      const err = await waitForMessage(alice, 'error');
+      assert.ok(err.message.includes('not online'));
+
+      alice.close();
+      await new Promise(r => setTimeout(r, 50));
+    });
+  });
+});