feat: add WebRTC signaling server plugin

melvincarvalho · melvincarvalho · commit a18467f4eee4 · 2026-03-15T11:07:34.000+01:00
Lightweight signaling server for WebRTC peer-to-peer connections. Relays SDP offers/answers and ICE candidates between authenticated users. The actual media/data flows directly between peers. - New plugin: src/webrtc/index.js (~110 lines) - CLI: --webrtc, --webrtc-path - Env: JSS_WEBRTC, JSS_WEBRTC_PATH - WebSocket endpoint at /.webrtc (default) - WebID-based authentication required - Peer presence notifications (join/leave) Fixes JavaScriptSolidServer#207
diff --git a/bin/jss.js b/bin/jss.js
@@ -65,6 +65,9 @@ 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('--activitypub', 'Enable ActivityPub federation')
   .option('--no-activitypub', 'Disable ActivityPub federation')
   .option('--ap-username <name>', 'ActivityPub username (default: me)')
@@ -142,6 +145,8 @@ program
         nostr: config.nostr,
         nostrPath: config.nostrPath,
         nostrMaxEvents: config.nostrMaxEvents,
+        webrtc: config.webrtc,
+        webrtcPath: config.webrtcPath,
         activitypub: config.activitypub,
         apUsername: config.apUsername,
         apDisplayName: config.apDisplayName,
@@ -186,6 +191,7 @@ 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.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');
diff --git a/src/config.js b/src/config.js
@@ -54,6 +54,10 @@ export const defaults = {
   nostrPath: '/relay',
   nostrMaxEvents: 1000,
 
+  // WebRTC signaling
+  webrtc: false,
+  webrtcPath: '/.webrtc',
+
   // ActivityPub federation
   activitypub: false,
   apUsername: 'me',
@@ -134,6 +138,8 @@ const envMap = {
   JSS_NOSTR: 'nostr',
   JSS_NOSTR_PATH: 'nostrPath',
   JSS_NOSTR_MAX_EVENTS: 'nostrMaxEvents',
+  JSS_WEBRTC: 'webrtc',
+  JSS_WEBRTC_PATH: 'webrtcPath',
   JSS_ACTIVITYPUB: 'activitypub',
   JSS_AP_USERNAME: 'apUsername',
   JSS_AP_DISPLAY_NAME: 'apDisplayName',
diff --git a/src/server.js b/src/server.js
@@ -18,6 +18,7 @@ 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';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -74,6 +75,9 @@ 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';
   // ActivityPub federation is OFF by default
   const activitypubEnabled = options.activitypub ?? false;
   const apUsername = options.apUsername ?? 'me';
@@ -240,6 +244,11 @@ export function createServer(options = {}) {
     });
   }
 
+  // Register WebRTC signaling if enabled
+  if (webrtcEnabled) {
+    fastify.register(webrtcPlugin, { path: webrtcPath });
+  }
+
   // Register ActivityPub plugin if enabled
   if (activitypubEnabled) {
     fastify.register(activityPubPlugin, {
diff --git a/src/webrtc/index.js b/src/webrtc/index.js
@@ -0,0 +1,120 @@
+/**
+ * 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 flows 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",     peers: ["<webid>", ...] }
+ */
+
+import websocket from '@fastify/websocket';
+import { getWebIdFromRequestAsync } from '../auth/token.js';
+
+// Connected peers: webId → WebSocket
+const peers = new Map();
+
+/**
+ * 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';
+
+  await fastify.register(websocket);
+
+  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
+    const existing = peers.get(webId);
+    if (existing) {
+      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)
+    }));
+
+    // Notify other peers that someone came online
+    broadcast(webId, { type: 'peer-joined', webId });
+
+    socket.on('message', (data) => {
+      let msg;
+      try {
+        msg = JSON.parse(data.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;
+      }
+
+      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;
+      }
+
+      // Relay the message, replacing 'to' with 'from'
+      const relay = { ...msg, from: webId };
+      delete relay.to;
+      target.send(JSON.stringify(relay));
+    });
+
+    socket.on('close', () => {
+      peers.delete(webId);
+      broadcast(webId, { type: 'peer-left', webId });
+    });
+
+    socket.on('error', () => {
+      peers.delete(webId);
+    });
+  });
+}
+
+/**
+ * Send a message to all connected peers except the sender
+ */
+function broadcast(senderWebId, msg) {
+  const data = JSON.stringify(msg);
+  for (const [id, socket] of peers) {
+    if (id !== senderWebId && socket.readyState === 1) {
+      socket.send(data);
+    }
+  }
+}
+
+export default webrtcPlugin;
