@tangentfeed/signaling-server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sreeraj T A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @tangentfeed/signaling-server
+
+Blind WebRTC signaling relay for tangentfeed. Handles presence and relays opaque signaling blobs; never sees your data.
+
+```bash
+npx @tangentfeed/signaling-server   # listens on :8787
+```
+
+Part of [tangentfeed](https://github.com/sreerajta/tangentfeed). MIT licensed.

package/bin/server.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Standalone runner: PORT=8787 node bin/server.mjs
+// Uses tsx-free plain import of built output; for dev: npx tsx bin/dev.mts
+import { createSignalingServer } from "../dist/index.js";
+const port = Number(process.env.PORT ?? 8787);
+const server = await createSignalingServer({ port });
+console.log(`tangentfeed signaling server listening on ws://0.0.0.0:${server.port}`);
+process.on("SIGINT", async () => { await server.close(); process.exit(0); });

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Signaling server — the only piece of infrastructure in the whole system,
+ * kept honest by knowing nothing: it never sees ops, state, or plaintext.
+ * It does two jobs: presence (who's in a space's room) and blind relay of
+ * signaling blobs (SDP offers/answers, ICE candidates) between peers.
+ *
+ * Wire (JSON over WebSocket):
+ *   client → server:  { t:"join", space, device }
+ *                     { t:"signal", to, data }        // data is opaque
+ *   server → client:  { t:"peers", devices: [...] }   // reply to join
+ *                     { t:"peer-joined", device }
+ *                     { t:"peer-left", device }
+ *                     { t:"signal", from, data }
+ *                     { t:"error", message }
+ */
+interface SignalingServer {
+    port: number;
+    close(): Promise<void>;
+}
+declare function createSignalingServer(opts?: {
+    port?: number;
+}): Promise<SignalingServer>;
+
+export { type SignalingServer, createSignalingServer };

package/dist/index.js

@@ -0,0 +1,79 @@
+// src/index.ts
+import { WebSocketServer, WebSocket } from "ws";
+function createSignalingServer(opts = {}) {
+  return new Promise((resolve, reject) => {
+    const wss = new WebSocketServer({ port: opts.port ?? 0 });
+    const rooms = /* @__PURE__ */ new Map();
+    wss.on("connection", (ws) => {
+      let me = null;
+      ws.on("message", (raw) => {
+        let msg;
+        try {
+          msg = JSON.parse(raw.toString());
+        } catch {
+          return send(ws, { t: "error", message: "invalid JSON" });
+        }
+        if (msg["t"] === "join") {
+          const space = str(msg["space"]);
+          const device = str(msg["device"]);
+          if (!space || !device) return send(ws, { t: "error", message: "join needs space and device" });
+          if (me) leave(me);
+          me = { ws, space, device };
+          const room = rooms.get(space) ?? /* @__PURE__ */ new Map();
+          const evicted = room.get(device);
+          if (evicted) evicted.ws.close(4e3, "replaced by new connection");
+          room.set(device, me);
+          rooms.set(space, room);
+          send(ws, { t: "peers", devices: [...room.keys()].filter((d) => d !== device) });
+          for (const c of room.values()) {
+            if (c.device !== device) send(c.ws, { t: "peer-joined", device });
+          }
+          return;
+        }
+        if (msg["t"] === "signal") {
+          if (!me) return send(ws, { t: "error", message: "join first" });
+          const to = str(msg["to"]);
+          const target = rooms.get(me.space)?.get(to);
+          if (!target) return;
+          send(target.ws, { t: "signal", from: me.device, data: msg["data"] });
+          return;
+        }
+        send(ws, { t: "error", message: `unknown message type` });
+      });
+      ws.on("close", () => {
+        if (me) leave(me);
+        me = null;
+      });
+    });
+    function leave(c) {
+      const room = rooms.get(c.space);
+      if (!room || room.get(c.device)?.ws !== c.ws) return;
+      room.delete(c.device);
+      if (room.size === 0) rooms.delete(c.space);
+      for (const other of room?.values() ?? []) {
+        send(other.ws, { t: "peer-left", device: c.device });
+      }
+    }
+    wss.on("listening", () => {
+      const addr = wss.address();
+      const port = typeof addr === "object" && addr ? addr.port : opts.port ?? 0;
+      resolve({
+        port,
+        close: () => new Promise((res) => {
+          for (const c of wss.clients) c.terminate();
+          wss.close(() => res());
+        })
+      });
+    });
+    wss.on("error", reject);
+  });
+}
+function send(ws, msg) {
+  if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
+}
+function str(v) {
+  return typeof v === "string" ? v : "";
+}
+export {
+  createSignalingServer
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@tangentfeed/signaling-server",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "tangentfeed-signaling": "bin/server.mjs"
+  },
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "start": "node bin/server.mjs",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "esbuild": "^0.23.0",
+    "tsup": "^8.5.0"
+  },
+  "description": "Blind WebRTC signaling relay for tangentfeed",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sreerajta/tangentfeed.git",
+    "directory": "packages/signaling-server"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}