@vex-chat/spire 2.3.4 → 2.5.0

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();
+    });
+});

package/src/__tests__/notifyFanout.spec.ts

@@ -8,6 +8,8 @@ import type { ClientManager } from "../ClientManager.ts";
 import type { Database, NotificationSubscription } from "../Database.ts";
 import type { BaseMsg } from "@vex-chat/types";
 
+import { generateKeyPairSync } from "node:crypto";
+
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { NotificationService } from "../NotificationService.ts";
@@ -535,6 +537,140 @@ describe("Spire notify fanout", () => {
         });
     });
 
+    it("sends Expo callWake pushes with opaque call data", async () => {
+        const callSubscription: NotificationSubscription = {
+            ...subscription,
+            events: ["callWake"],
+            subscriptionID: "sub-call",
+        };
+        const fetchMock = vi.fn().mockResolvedValueOnce({
+            json: () =>
+                Promise.resolve({
+                    data: [{ id: "receipt-a", status: "ok" }],
+                }),
+            ok: true,
+        });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { db } = createSpireHarness([], [callSubscription]);
+        const service = new NotificationService(db, [], () => {});
+
+        await service["notifyPush"]({
+            data: {
+                callID: "call-1",
+                expiresAt: "2026-06-05T12:01:00.000Z",
+                mailID: "mail-1",
+                mailNonce: "abcd",
+            },
+            deviceID: callSubscription.deviceID,
+            event: "callWake",
+            transmissionID: "00000000-0000-0000-0000-000000000017",
+            userID: callSubscription.userID,
+        });
+
+        const init = fetchMock.mock.calls[0]?.[1] as
+            | undefined
+            | { body?: unknown };
+        const messages = JSON.parse(String(init?.body)) as Array<{
+            body?: string;
+            data?: Record<string, unknown>;
+            title?: string;
+        }>;
+        expect(messages[0]?.title).toBe("Incoming Vex call");
+        expect(messages[0]?.body).toBe("Incoming voice call.");
+        expect(messages[0]?.data).toMatchObject({
+            callID: "call-1",
+            event: "callWake",
+            expiresAt: "2026-06-05T12:01:00.000Z",
+            mailID: "mail-1",
+            mailNonce: "abcd",
+            transmissionID: "00000000-0000-0000-0000-000000000017",
+        });
+        expect(messages[0]?.data).not.toHaveProperty("callerUserID");
+        expect(messages[0]?.data).not.toHaveProperty("sdp");
+    });
+
+    it("sends FCM call pushes as high-priority opaque data", async () => {
+        const { privateKey } = generateKeyPairSync("rsa", {
+            modulusLength: 2048,
+        });
+        const fcmSubscription: NotificationSubscription = {
+            ...subscription,
+            channel: "fcmCall",
+            events: ["callWake"],
+            platform: "android",
+            subscriptionID: "sub-fcm",
+            token: "fcm-token",
+        };
+        const fetchMock = vi
+            .fn()
+            .mockResolvedValueOnce({
+                json: () => Promise.resolve({ access_token: "access-token" }),
+                ok: true,
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+            });
+        vi.stubGlobal("fetch", fetchMock);
+
+        process.env["SPIRE_FCM_CLIENT_EMAIL"] = "spire@example.invalid";
+        process.env["SPIRE_FCM_PRIVATE_KEY"] = privateKey.export({
+            format: "pem",
+            type: "pkcs8",
+        });
+        process.env["SPIRE_FCM_PROJECT_ID"] = "vex-test";
+        try {
+            const { db } = createSpireHarness([], [fcmSubscription]);
+            const service = new NotificationService(db, [], () => {});
+
+            await service["notifyPush"]({
+                data: {
+                    callID: "call-fcm",
+                    expiresAt: "2026-06-05T12:01:00.000Z",
+                    mailID: "mail-fcm",
+                    mailNonce: "beef",
+                },
+                deviceID: fcmSubscription.deviceID,
+                event: "callWake",
+                transmissionID: "00000000-0000-0000-0000-000000000018",
+                userID: fcmSubscription.userID,
+            });
+        } finally {
+            delete process.env["SPIRE_FCM_CLIENT_EMAIL"];
+            delete process.env["SPIRE_FCM_PRIVATE_KEY"];
+            delete process.env["SPIRE_FCM_PROJECT_ID"];
+        }
+
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(fetchMock.mock.calls[0]?.[0]).toBe(
+            "https://oauth2.googleapis.com/token",
+        );
+        expect(fetchMock.mock.calls[1]?.[0]).toBe(
+            "https://fcm.googleapis.com/v1/projects/vex-test/messages:send",
+        );
+        const init = fetchMock.mock.calls[1]?.[1] as
+            | undefined
+            | { body?: unknown };
+        const body = JSON.parse(String(init?.body)) as {
+            message?: {
+                android?: { priority?: string; ttl?: string };
+                data?: Record<string, string>;
+                token?: string;
+            };
+        };
+        expect(body.message?.token).toBe("fcm-token");
+        expect(body.message?.android?.priority).toBe("HIGH");
+        expect(body.message?.data).toMatchObject({
+            callID: "call-fcm",
+            event: "callWake",
+            mailID: "mail-fcm",
+            mailNonce: "beef",
+            transmissionID: "00000000-0000-0000-0000-000000000018",
+        });
+        expect(body.message?.data).not.toHaveProperty("callerUserID");
+        expect(body.message?.data).not.toHaveProperty("sdp");
+    });
+
     it("requests the default sound for iOS visible Expo pushes only", async () => {
         const iosSubscription: NotificationSubscription = {
             ...subscription,

package/src/server/callWake.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { MailWS } from "@vex-chat/types";
+
+import { XUtils } from "@vex-chat/crypto";
+
+export interface CallWakeDispatchData {
+    callID: string;
+    expiresAt?: string | undefined;
+    mailID: string;
+    mailNonce: string;
+}
+
+export function callWakeDispatchData(
+    mail: MailWS,
+): CallWakeDispatchData | null {
+    if (mail.notify?.event !== "callWake") {
+        return null;
+    }
+    return {
+        callID: mail.notify.callID,
+        ...(mail.notify.expiresAt ? { expiresAt: mail.notify.expiresAt } : {}),
+        mailID: mail.mailID,
+        mailNonce: XUtils.encodeHex(new Uint8Array(mail.nonce)),
+    };
+}