@vex-chat/spire 2.3.3 → 2.4.0

package/src/ClientManager.ts

@@ -4,6 +4,7 @@
  * Commercial licenses available at vex.wtf
  */
 
+import type { CallManager } from "./CallManager.ts";
 import type { Database } from "./Database.ts";
 import type {
     BaseMsg,
@@ -44,7 +45,9 @@ function emptyHeader() {
     return new Uint8Array(32);
 }
 
-const MAX_MSG_SIZE = 2048;
+// WebRTC SDP offers/answers are commonly several KB before encryption/packing.
+// Keep this well below HTTP body limits while allowing first-party call signals.
+const MAX_MSG_SIZE = 64 * 1024;
 
 // How many ping cycles in a row are allowed to go without a pong
 // before we declare the connection dead. With a 5s ping interval
@@ -68,6 +71,7 @@ const PING_INTERVAL_MS = 5000;
 export class ClientManager extends EventEmitter {
     private alive: boolean = true;
     private authed: boolean = false;
+    private callManager: CallManager;
     private challengeID: Uint8Array = createUint8UUID();
     private conn: WebSocket;
     private db: Database;
@@ -89,6 +93,7 @@ export class ClientManager extends EventEmitter {
     constructor(
         ws: WebSocket,
         db: Database,
+        callManager: CallManager,
         notify: (
             userID: string,
             event: string,
@@ -103,6 +108,7 @@ export class ClientManager extends EventEmitter {
         super();
         this.conn = ws;
         this.db = db;
+        this.callManager = callManager;
         this.user = null;
         this.userDetails = userDetails;
         this.device = null;
@@ -280,6 +286,25 @@ export class ClientManager extends EventEmitter {
 
     private async parseResourceMsg(msg: ResourceMsg, header: Uint8Array) {
         switch (msg.resourceType) {
+            case "call":
+                try {
+                    const event = await this.callManager.handleResource({
+                        action: msg.action,
+                        actor: {
+                            device: this.getDevice(),
+                            user: this.getUser(),
+                        },
+                        data: msg.data,
+                        transmissionID: msg.transmissionID,
+                    });
+                    this.sendSuccess(msg.transmissionID, event);
+                } catch (err: unknown) {
+                    this.sendErr(
+                        msg.transmissionID,
+                        err instanceof Error ? err.message : String(err),
+                    );
+                }
+                break;
             case "mail":
                 if (msg.action === "CREATE") {
                     const mailResult = MailWSSchema.safeParse(msg.data);

package/src/IceServers.ts

@@ -0,0 +1,185 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { IceServerConfig } from "@vex-chat/types";
+
+import { IceServerConfigSchema } from "@vex-chat/types";
+
+import { z } from "zod/v4";
+
+const CLOUDFLARE_TURN_ENDPOINT = "https://rtc.live.cloudflare.com/v1/turn/keys";
+const DEFAULT_CLOUDFLARE_TURN_TIMEOUT_MS = 5_000;
+const DEFAULT_CLOUDFLARE_TURN_TTL_SECONDS = 86_400;
+
+const cloudflareIceServersResponseSchema = z.object({
+    iceServers: z.array(IceServerConfigSchema),
+});
+
+export async function resolveIceServersFromEnv(): Promise<IceServerConfig[]> {
+    const jsonOverride = readJsonIceServersFromEnv();
+    if (jsonOverride) {
+        return jsonOverride;
+    }
+
+    const staticServers = readStaticIceServersFromEnv();
+    const cloudflareServers = await readCloudflareIceServersFromEnv();
+    return [...staticServers, ...cloudflareServers];
+}
+
+async function readCloudflareIceServersFromEnv(): Promise<IceServerConfig[]> {
+    const keyID = readEnv([
+        "SPIRE_CLOUDFLARE_TURN_KEY_ID",
+        "CLOUDFLARE_TURN_KEY_ID",
+        "TURN_KEY_ID",
+    ]);
+    const apiToken = readEnv([
+        "SPIRE_CLOUDFLARE_TURN_API_TOKEN",
+        "CLOUDFLARE_TURN_API_TOKEN",
+        "TURN_KEY_API_TOKEN",
+    ]);
+    const endpointOverride = readEnv(["SPIRE_CLOUDFLARE_TURN_ENDPOINT"]);
+    if (!keyID && !apiToken && !endpointOverride) {
+        return [];
+    }
+
+    if (!apiToken || (!keyID && !endpointOverride)) {
+        console.warn(
+            "[spire-calls] Cloudflare TURN is partially configured; set SPIRE_CLOUDFLARE_TURN_KEY_ID and SPIRE_CLOUDFLARE_TURN_API_TOKEN",
+        );
+        return [];
+    }
+
+    let endpoint = endpointOverride;
+    if (!endpoint) {
+        if (!keyID) {
+            console.warn(
+                "[spire-calls] Cloudflare TURN is partially configured; set SPIRE_CLOUDFLARE_TURN_KEY_ID and SPIRE_CLOUDFLARE_TURN_API_TOKEN",
+            );
+            return [];
+        }
+        endpoint = `${CLOUDFLARE_TURN_ENDPOINT}/${encodeURIComponent(keyID)}/credentials/generate-ice-servers`;
+    }
+    const ttl = readPositiveIntegerEnv(
+        "SPIRE_CLOUDFLARE_TURN_TTL_SECONDS",
+        DEFAULT_CLOUDFLARE_TURN_TTL_SECONDS,
+    );
+    const timeoutMs = readPositiveIntegerEnv(
+        "SPIRE_CLOUDFLARE_TURN_TIMEOUT_MS",
+        DEFAULT_CLOUDFLARE_TURN_TIMEOUT_MS,
+    );
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+
+    try {
+        const response = await fetch(endpoint, {
+            body: JSON.stringify({ ttl }),
+            headers: {
+                Authorization: `Bearer ${apiToken}`,
+                "Content-Type": "application/json",
+            },
+            method: "POST",
+            signal: controller.signal,
+        });
+
+        if (!response.ok) {
+            throw new Error(
+                `Cloudflare TURN credential request failed with ${response.status}`,
+            );
+        }
+
+        const payload = await response.json();
+        return cloudflareIceServersResponseSchema.parse(payload).iceServers;
+    } catch (err: unknown) {
+        console.warn(
+            "[spire-calls] failed to fetch Cloudflare TURN credentials",
+            err instanceof Error ? err.message : String(err),
+        );
+        return [];
+    } finally {
+        clearTimeout(timeout);
+    }
+}
+
+function readEnv(names: string[]): string | undefined {
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+
+function readJsonIceServersFromEnv(): IceServerConfig[] | null {
+    const json = process.env["SPIRE_ICE_SERVERS"]?.trim();
+    if (!json) {
+        return null;
+    }
+
+    try {
+        const parsed = JSON.parse(json) as unknown;
+        return z.array(IceServerConfigSchema).parse(parsed);
+    } catch (err: unknown) {
+        console.warn(
+            "[spire-calls] ignoring invalid SPIRE_ICE_SERVERS",
+            err instanceof Error ? err.message : String(err),
+        );
+        return null;
+    }
+}
+
+function readPositiveIntegerEnv(name: string, fallback: number): number {
+    const raw = process.env[name]?.trim();
+    if (!raw) {
+        return fallback;
+    }
+
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isInteger(parsed) && parsed > 0) {
+        return parsed;
+    }
+
+    console.warn(
+        `[spire-calls] ignoring invalid ${name}; expected a positive integer`,
+    );
+    return fallback;
+}
+
+function readStaticIceServersFromEnv(): IceServerConfig[] {
+    const servers: IceServerConfig[] = [];
+    for (const url of splitCsvEnv("SPIRE_STUN_URLS")) {
+        servers.push({ urls: url });
+    }
+
+    const turnUrls = splitCsvEnv("SPIRE_TURN_URLS");
+    if (turnUrls.length > 0) {
+        const username = process.env["SPIRE_TURN_USERNAME"]?.trim();
+        const credential = process.env["SPIRE_TURN_CREDENTIAL"]?.trim();
+        const [firstTurnUrl] = turnUrls;
+        if (!firstTurnUrl) {
+            return servers;
+        }
+        const urls: string | string[] =
+            turnUrls.length === 1 ? firstTurnUrl : turnUrls;
+        servers.push({
+            ...(credential ? { credential } : {}),
+            urls,
+            ...(username ? { username } : {}),
+        });
+    }
+
+    return servers;
+}
+
+function splitCsvEnv(name: string): string[] {
+    return (process.env[name] ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+}

package/src/NotificationService.ts

@@ -433,6 +433,7 @@ export class NotificationService {
 }
 
 function bodyForEvent(event: string): string | undefined {
+    if (event === "callInvite") return "Incoming voice call.";
     if (event === "mail") return undefined;
     if (event === "deviceRequest") return "Review the device request.";
     if (event === "deviceListChanged") return "Your device list changed.";
@@ -600,6 +601,7 @@ function shouldSendHeadlessPush(dispatch: NotificationDispatch): boolean {
 }
 
 function titleForEvent(event: string): string {
+    if (event === "callInvite") return "Incoming Vex call";
     if (event === "mail") return "New Message";
     if (event === "deviceRequest") return "Device approval request";
     if (event === "deviceListChanged") return "Vex device update";

package/src/Spire.ts

@@ -43,8 +43,10 @@ import { stringify as uuidStringify } from "uuid";
 import { WebSocketServer } from "ws";
 import { z } from "zod/v4";
 
+import { CallManager } from "./CallManager.ts";
 import { ClientManager } from "./ClientManager.ts";
 import { Database, hashPasswordArgon2, verifyPassword } from "./Database.ts";
+import { resolveIceServersFromEnv } from "./IceServers.ts";
 import { NotificationService } from "./NotificationService.ts";
 import { initApp, protect } from "./server/index.ts";
 import {
@@ -216,6 +218,7 @@ let pendingFipsKeyPair: KeyPair | null = null;
 export class Spire extends EventEmitter {
     private actionTokens: ActionToken[] = [];
     private api = express();
+    private calls: CallManager;
     private clients: ClientManager[] = [];
     private readonly commitSha = getCommitSha();
     private readonly cryptoProfile: "fips" | "tweetnacl";
@@ -264,8 +267,10 @@ export class Spire extends EventEmitter {
         // that lets attackers spoof the header and bypass rate limiting.
         // If spire is deployed without a proxy, set this to 0 instead.
         this.api.set("trust proxy", 1);
+        this.api.disable("etag");
 
         this.db = new Database(options);
+        this.calls = new CallManager(this.db, this.notify.bind(this));
         this.notifications = new NotificationService(
             this.db,
             this.clients,
@@ -468,6 +473,7 @@ export class Spire extends EventEmitter {
                     const client = new ClientManager(
                         ws,
                         this.db,
+                        this.calls,
                         this.notify.bind(this),
                         userDetails,
                     );
@@ -995,6 +1001,21 @@ export class Spire extends EventEmitter {
             }
         });
 
+        this.api.get("/calls/active", protect, (req, res) => {
+            const user = getUser(req);
+            res.setHeader(
+                "Cache-Control",
+                "no-store, no-cache, must-revalidate, proxy-revalidate",
+            );
+            res.setHeader("Pragma", "no-cache");
+            res.setHeader("Expires", "0");
+            res.json({ calls: this.calls.activeCallsForUser(user.userID) });
+        });
+
+        this.api.get("/calls/ice-servers", protect, async (_req, res) => {
+            res.json({ iceServers: await resolveIceServersFromEnv() });
+        });
+
         this.api.post(
             "/device/:id/notifications/subscriptions",
             protect,

package/src/__tests__/CallManager.spec.ts

@@ -0,0 +1,208 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { Database } from "../Database.ts";
+import type { Device, User } from "@vex-chat/types";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { CallManager } from "../CallManager.ts";
+
+const caller: User = {
+    lastSeen: "2026-06-01T00:00:00.000Z",
+    userID: "user-a",
+    username: "alice",
+};
+
+const recipient: User = {
+    lastSeen: "2026-06-01T00:00:00.000Z",
+    userID: "user-b",
+    username: "bob",
+};
+
+const callerDevice: Device = {
+    deleted: false,
+    deviceID: "device-a",
+    lastLogin: "2026-06-01T00:00:00.000Z",
+    name: "ios",
+    owner: caller.userID,
+    signKey: "aa",
+};
+
+const recipientDevice: Device = {
+    deleted: false,
+    deviceID: "device-b",
+    lastLogin: "2026-06-01T00:00:00.000Z",
+    name: "android",
+    owner: recipient.userID,
+    signKey: "bb",
+};
+
+function harness() {
+    const notify = vi.fn();
+    const db = {
+        retrieveUser: vi.fn((userID: string) =>
+            Promise.resolve(userID === recipient.userID ? recipient : null),
+        ),
+    } as unknown as Database;
+    const calls = new CallManager(db, notify);
+    return { calls, notify };
+}
+
+describe("CallManager", () => {
+    it("creates a one-to-one call invite and notifies the recipient", async () => {
+        const { calls, notify } = harness();
+
+        const event = await calls.handleResource({
+            action: "INVITE",
+            actor: { device: callerDevice, user: caller },
+            data: {
+                conversationType: "dm",
+                recipientUserID: recipient.userID,
+                signal: {
+                    description: { sdp: "offer", type: "offer" },
+                    kind: "offer",
+                },
+            },
+            transmissionID: "tx-1",
+        });
+
+        expect(event.action).toBe("invite");
+        expect(event.call.status).toBe("ringing");
+        expect(event.call.participants.map((p) => p.userID)).toEqual([
+            caller.userID,
+            recipient.userID,
+        ]);
+        expect(notify).toHaveBeenCalledWith(
+            recipient.userID,
+            "callInvite",
+            "tx-1",
+            expect.objectContaining({ action: "invite" }),
+        );
+        expect(calls.activeCallsForUser(recipient.userID)).toHaveLength(1);
+    });
+
+    it("accepts a ringing call and notifies participants", async () => {
+        const { calls, notify } = harness();
+        const invite = await calls.handleResource({
+            action: "INVITE",
+            actor: { device: callerDevice, user: caller },
+            data: {
+                conversationType: "dm",
+                recipientUserID: recipient.userID,
+            },
+            transmissionID: "tx-1",
+        });
+
+        const accepted = await calls.handleResource({
+            action: "ACCEPT",
+            actor: { device: recipientDevice, user: recipient },
+            data: {
+                callID: invite.call.callID,
+                signal: {
+                    description: { sdp: "answer", type: "answer" },
+                    kind: "answer",
+                },
+            },
+            transmissionID: "tx-2",
+        });
+
+        expect(accepted.call.status).toBe("active");
+        expect(
+            accepted.call.participants.find(
+                (p) => p.userID === recipient.userID,
+            ),
+        ).toMatchObject({
+            deviceID: recipientDevice.deviceID,
+            state: "accepted",
+        });
+        expect(notify).toHaveBeenCalledWith(
+            caller.userID,
+            "call",
+            "tx-2",
+            expect.objectContaining({ action: "accept" }),
+        );
+    });
+
+    it("relays ICE candidates only for call participants", async () => {
+        const { calls, notify } = harness();
+        const invite = await calls.handleResource({
+            action: "INVITE",
+            actor: { device: callerDevice, user: caller },
+            data: {
+                conversationType: "dm",
+                recipientUserID: recipient.userID,
+            },
+            transmissionID: "tx-1",
+        });
+
+        const ice = await calls.handleResource({
+            action: "ICE",
+            actor: { device: callerDevice, user: caller },
+            data: {
+                callID: invite.call.callID,
+                signal: {
+                    candidate: { candidate: "candidate:1" },
+                    kind: "ice",
+                },
+            },
+            transmissionID: "tx-3",
+        });
+
+        expect(ice.action).toBe("ice");
+        expect(notify).toHaveBeenCalledWith(
+            recipient.userID,
+            "call",
+            "tx-3",
+            expect.objectContaining({
+                signal: { candidate: expect.anything(), kind: "ice" },
+            }),
+        );
+
+        await expect(
+            calls.handleResource({
+                action: "ICE",
+                actor: {
+                    device: { ...callerDevice, deviceID: "device-c" },
+                    user: {
+                        lastSeen: "2026-06-01T00:00:00.000Z",
+                        userID: "user-c",
+                        username: "charlie",
+                    },
+                },
+                data: {
+                    callID: invite.call.callID,
+                    signal: { candidate: {}, kind: "ice" },
+                },
+                transmissionID: "tx-4",
+            }),
+        ).rejects.toThrow("not a participant");
+    });
+
+    it("ends a rejected call and removes it from active calls", async () => {
+        const { calls } = harness();
+        const invite = await calls.handleResource({
+            action: "INVITE",
+            actor: { device: callerDevice, user: caller },
+            data: {
+                conversationType: "dm",
+                recipientUserID: recipient.userID,
+            },
+            transmissionID: "tx-1",
+        });
+
+        const rejected = await calls.handleResource({
+            action: "REJECT",
+            actor: { device: recipientDevice, user: recipient },
+            data: { callID: invite.call.callID },
+            transmissionID: "tx-5",
+        });
+
+        expect(rejected.call.status).toBe("ended");
+        expect(calls.activeCallsForUser(caller.userID)).toEqual([]);
+        expect(calls.activeCallsForUser(recipient.userID)).toEqual([]);
+    });
+});

package/src/__tests__/IceServers.spec.ts

@@ -0,0 +1,151 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { resolveIceServersFromEnv } from "../IceServers.ts";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+    delete process.env["CLOUDFLARE_TURN_API_TOKEN"];
+    delete process.env["CLOUDFLARE_TURN_KEY_ID"];
+    delete process.env["SPIRE_CLOUDFLARE_TURN_API_TOKEN"];
+    delete process.env["SPIRE_CLOUDFLARE_TURN_ENDPOINT"];
+    delete process.env["SPIRE_CLOUDFLARE_TURN_KEY_ID"];
+    delete process.env["SPIRE_CLOUDFLARE_TURN_TIMEOUT_MS"];
+    delete process.env["SPIRE_CLOUDFLARE_TURN_TTL_SECONDS"];
+    delete process.env["SPIRE_ICE_SERVERS"];
+    delete process.env["SPIRE_STUN_URLS"];
+    delete process.env["SPIRE_TURN_CREDENTIAL"];
+    delete process.env["SPIRE_TURN_URLS"];
+    delete process.env["SPIRE_TURN_USERNAME"];
+    delete process.env["TURN_KEY_API_TOKEN"];
+    delete process.env["TURN_KEY_ID"];
+    globalThis.fetch = originalFetch;
+    vi.restoreAllMocks();
+});
+
+describe("resolveIceServersFromEnv", () => {
+    it("uses SPIRE_ICE_SERVERS as a full override", async () => {
+        process.env["SPIRE_ICE_SERVERS"] = JSON.stringify([
+            {
+                urls: ["stun:override.example:3478"],
+            },
+        ]);
+        process.env["SPIRE_STUN_URLS"] = "stun:ignored.example:3478";
+        process.env["SPIRE_CLOUDFLARE_TURN_KEY_ID"] = "turn-key";
+        process.env["SPIRE_CLOUDFLARE_TURN_API_TOKEN"] = "secret";
+        const fetchMock = vi.fn();
+        globalThis.fetch = fetchMock;
+
+        await expect(resolveIceServersFromEnv()).resolves.toEqual([
+            {
+                urls: ["stun:override.example:3478"],
+            },
+        ]);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it("combines static STUN and TURN env vars", async () => {
+        process.env["SPIRE_STUN_URLS"] =
+            "stun:one.example:3478, stun:two.example:3478";
+        process.env["SPIRE_TURN_URLS"] =
+            "turn:turn.example:3478?transport=udp, turns:turn.example:443?transport=tcp";
+        process.env["SPIRE_TURN_USERNAME"] = "static-user";
+        process.env["SPIRE_TURN_CREDENTIAL"] = "static-secret";
+
+        await expect(resolveIceServersFromEnv()).resolves.toEqual([
+            { urls: "stun:one.example:3478" },
+            { urls: "stun:two.example:3478" },
+            {
+                credential: "static-secret",
+                urls: [
+                    "turn:turn.example:3478?transport=udp",
+                    "turns:turn.example:443?transport=tcp",
+                ],
+                username: "static-user",
+            },
+        ]);
+    });
+
+    it("fetches Cloudflare TURN credentials with a TTL", async () => {
+        process.env["SPIRE_CLOUDFLARE_TURN_KEY_ID"] = "turn-key";
+        process.env["SPIRE_CLOUDFLARE_TURN_API_TOKEN"] = "secret";
+        process.env["SPIRE_CLOUDFLARE_TURN_TTL_SECONDS"] = "3600";
+
+        const fetchMock = vi.fn().mockResolvedValue({
+            json: () =>
+                Promise.resolve({
+                    iceServers: [
+                        {
+                            urls: ["stun:stun.cloudflare.com:3478"],
+                        },
+                        {
+                            credential: "generated-secret",
+                            urls: [
+                                "turn:turn.cloudflare.com:3478?transport=udp",
+                            ],
+                            username: "generated-user",
+                        },
+                    ],
+                }),
+            ok: true,
+            status: 201,
+        });
+        globalThis.fetch = fetchMock;
+
+        await expect(resolveIceServersFromEnv()).resolves.toEqual([
+            { urls: ["stun:stun.cloudflare.com:3478"] },
+            {
+                credential: "generated-secret",
+                urls: ["turn:turn.cloudflare.com:3478?transport=udp"],
+                username: "generated-user",
+            },
+        ]);
+        expect(fetchMock).toHaveBeenCalledWith(
+            "https://rtc.live.cloudflare.com/v1/turn/keys/turn-key/credentials/generate-ice-servers",
+            expect.objectContaining({
+                body: JSON.stringify({ ttl: 3600 }),
+                headers: {
+                    Authorization: "Bearer secret",
+                    "Content-Type": "application/json",
+                },
+                method: "POST",
+            }),
+        );
+    });
+
+    it("falls back to static ICE servers when Cloudflare fails", async () => {
+        process.env["SPIRE_STUN_URLS"] = "stun:local.example:3478";
+        process.env["SPIRE_CLOUDFLARE_TURN_KEY_ID"] = "turn-key";
+        process.env["SPIRE_CLOUDFLARE_TURN_API_TOKEN"] = "secret";
+
+        vi.spyOn(console, "warn").mockImplementation(() => {});
+        globalThis.fetch = vi.fn().mockResolvedValue({
+            json: () => Promise.resolve({}),
+            ok: false,
+            status: 403,
+        });
+
+        await expect(resolveIceServersFromEnv()).resolves.toEqual([
+            { urls: "stun:local.example:3478" },
+        ]);
+    });
+
+    it("ignores partial Cloudflare config", async () => {
+        process.env["SPIRE_STUN_URLS"] = "stun:local.example:3478";
+        process.env["SPIRE_CLOUDFLARE_TURN_KEY_ID"] = "turn-key";
+        const fetchMock = vi.fn();
+        globalThis.fetch = fetchMock;
+        vi.spyOn(console, "warn").mockImplementation(() => {});
+
+        await expect(resolveIceServersFromEnv()).resolves.toEqual([
+            { urls: "stun:local.example:3478" },
+        ]);
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+});