@peers-app/peers-sdk 0.20.5 → 0.21.0

package/dist/device-pairing/device-pairing.test.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const device_1 = require("../device/device");
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const _1 = require(".");
+const NOW = 1_800_000_000_000;
+const FINGERPRINT = Array.from({ length: 32 }, (_, index) => index.toString(16).padStart(2, "0"))
+    .join(":")
+    .toUpperCase();
+describe("device pairing invitation", () => {
+    it("round-trips a versioned token and fragment URL", () => {
+        const invitation = (0, _1.createDevicePairingInvitation)({
+            serviceOrigin: "https://peers.app/path",
+            now: NOW,
+        });
+        const token = (0, _1.encodeDevicePairingInvitation)(invitation);
+        const url = (0, _1.createDevicePairingInvitationUrl)("https://app.peers.test/setup", invitation);
+        expect((0, _1.parseDevicePairingInvitation)(token, NOW)).toEqual(invitation);
+        expect((0, _1.parseDevicePairingInvitation)(url, NOW)).toEqual(invitation);
+        expect(invitation.roomId).toHaveLength(22);
+        expect(invitation.roomSecret).toHaveLength(43);
+        expect(invitation.serviceOrigin).toBe("https://peers.app");
+    });
+    it("rejects malformed, expired, unknown-version, and overlong invitations", () => {
+        const invitation = (0, _1.createDevicePairingInvitation)({
+            serviceOrigin: "https://peers.app",
+            now: NOW,
+        });
+        expect(() => (0, _1.parseDevicePairingInvitation)("not-an-invitation", NOW)).toThrow();
+        expect(() => (0, _1.parseDevicePairingInvitation)((0, _1.encodeDevicePairingInvitation)(invitation), NOW + 300_001)).toThrow();
+        expect(() => (0, _1.parseDevicePairingInvitation)((0, _1.encodeDevicePairingInvitation)({ ...invitation, version: 2 }), NOW)).toThrow();
+        expect(() => (0, _1.createDevicePairingInvitation)({
+            serviceOrigin: "https://peers.app",
+            now: NOW,
+            ttlMs: 300_001,
+        })).toThrow();
+    });
+    it("accepts only the configured bounded future clock skew", () => {
+        const skewedInvitation = (0, _1.createDevicePairingInvitation)({
+            serviceOrigin: "https://peers.app",
+            now: NOW + _1.DEVICE_PAIRING_CLOCK_SKEW_MS,
+        });
+        expect((0, _1.parseDevicePairingInvitation)((0, _1.encodeDevicePairingInvitation)(skewedInvitation), NOW)).toEqual(skewedInvitation);
+        expect(() => (0, _1.parseDevicePairingInvitation)((0, _1.encodeDevicePairingInvitation)({
+            ...skewedInvitation,
+            expiresAt: skewedInvitation.expiresAt + 1,
+        }), NOW)).toThrow();
+    });
+});
+describe("device pairing signaling", () => {
+    it("authenticates signaling and rejects modification, role substitution, and replay", () => {
+        const invitation = (0, _1.createDevicePairingInvitation)({
+            serviceOrigin: "https://peers.app",
+            now: NOW,
+        });
+        const signalingKey = (0, _1.derivePairingSignalingKey)(invitation.roomSecret);
+        const offerSdp = `v=0\r\na=fingerprint:sha-256 ${FINGERPRINT}\r\n`;
+        const signal = (0, _1.signPairingSignal)({
+            version: 1,
+            roomId: invitation.roomId,
+            senderRole: "source",
+            sequence: 1,
+            kind: "offer",
+            payload: {
+                type: "offer",
+                sdp: offerSdp,
+                endpointNonce: (0, keys_1.newToken)(32),
+            },
+        }, signalingKey);
+        expect((0, _1.verifyPairingSignal)(signal, signalingKey, {
+            roomId: invitation.roomId,
+            senderRole: "source",
+            nextSequence: 1,
+        })).toEqual(signal);
+        expect(() => (0, _1.verifyPairingSignal)({ ...signal, payload: { ...signal.payload, sdp: `${offerSdp}modified` } }, signalingKey, {
+            roomId: invitation.roomId,
+            senderRole: "source",
+            nextSequence: 1,
+        })).toThrow();
+        expect(() => (0, _1.verifyPairingSignal)(signal, signalingKey, {
+            roomId: invitation.roomId,
+            senderRole: "destination",
+            nextSequence: 1,
+        })).toThrow();
+        expect(() => (0, _1.verifyPairingSignal)(signal, signalingKey, {
+            roomId: invitation.roomId,
+            senderRole: "source",
+            nextSequence: 2,
+        })).toThrow();
+    });
+});
+describe("device pairing transcript and credentials", () => {
+    it("derives a stable transcript SAS that changes with SDP", () => {
+        const invitation = (0, _1.createDevicePairingInvitation)({
+            serviceOrigin: "https://peers.app",
+            now: NOW,
+        });
+        const source = new device_1.Device();
+        const destination = new device_1.Device();
+        const transcript = {
+            version: 1,
+            roomId: invitation.roomId,
+            sourceIdentity: (0, keys_1.openSignedObject)(source.getDeviceInfo()),
+            destinationIdentity: (0, keys_1.openSignedObject)(destination.getDeviceInfo()),
+            sourceEndpointNonce: (0, keys_1.newToken)(32),
+            destinationEndpointNonce: (0, keys_1.newToken)(32),
+            offerFingerprint: (0, _1.extractSha256SdpFingerprint)(`v=0\r\na=fingerprint:sha-256 ${FINGERPRINT}\r\n`),
+            answerFingerprint: (0, _1.extractSha256SdpFingerprint)(`v=0\r\na=fingerprint:sha-256 ${FINGERPRINT}\r\n`),
+        };
+        const hash = (0, _1.computeDevicePairingTranscriptHash)(transcript);
+        const sas = (0, _1.deriveDevicePairingSas)(invitation.roomSecret, hash);
+        const changedHash = (0, _1.computeDevicePairingTranscriptHash)({
+            ...transcript,
+            answerFingerprint: FINGERPRINT.replace("00", "FF"),
+        });
+        expect(sas).toMatch(/^\d{6}$/);
+        expect((0, _1.deriveDevicePairingSas)(invitation.roomSecret, hash)).toBe(sas);
+        expect((0, _1.deriveDevicePairingSas)(invitation.roomSecret, changedHash)).not.toBe(sas);
+    });
+    it("requires the expected identities and transcript for approval, credentials, and receipt", () => {
+        const source = new device_1.Device();
+        const destination = new device_1.Device();
+        const transcriptHash = (0, keys_1.newToken)(32);
+        const expiresAt = NOW + 60_000;
+        const approval = (0, _1.createSignedPairingApproval)(destination, "destination", transcriptHash, expiresAt);
+        expect((0, _1.verifySignedPairingApproval)(approval, {
+            publicKey: destination.publicKey,
+            transcriptHash,
+            role: "destination",
+            now: NOW,
+        })).toHaveLength(43);
+        expect(() => (0, _1.verifySignedPairingApproval)(approval, {
+            publicKey: source.publicKey,
+            transcriptHash,
+            role: "destination",
+            now: NOW,
+        })).toThrow();
+        const credentials = { userId: (0, utils_1.newid)(), secretKey: (0, keys_1.newKeys)().secretKey };
+        const destinationInfo = (0, keys_1.openSignedObject)(destination.getDeviceInfo());
+        const envelope = (0, _1.createPairingCredentialEnvelope)(source, destinationInfo, credentials, transcriptHash, expiresAt);
+        expect((0, _1.openPairingCredentialEnvelope)(destination, envelope, {
+            sourcePublicKey: source.publicKey,
+            sourcePublicBoxKey: source.publicBoxKey,
+            transcriptHash,
+            now: NOW,
+        })).toEqual({
+            version: 1,
+            transcriptHash,
+            expiresAt,
+            ...credentials,
+        });
+        expect(() => (0, _1.openPairingCredentialEnvelope)(new device_1.Device(), envelope, {
+            sourcePublicKey: source.publicKey,
+            sourcePublicBoxKey: source.publicBoxKey,
+            transcriptHash,
+            now: NOW,
+        })).toThrow();
+        const initialized = new device_1.Device(credentials.userId);
+        const initializedInfo = (0, keys_1.openSignedObject)(initialized.getDeviceInfo());
+        const receipt = (0, _1.createSignedPairingInstallationReceipt)(destination, transcriptHash, initializedInfo, NOW);
+        expect((0, _1.verifySignedPairingInstallationReceipt)(receipt, {
+            temporaryDestinationPublicKey: destination.publicKey,
+            transcriptHash,
+        })).toEqual(initializedInfo);
+    });
+    it("derives independent room-access and signaling credentials", () => {
+        const invitation = (0, _1.createDevicePairingInvitation)({
+            serviceOrigin: "https://peers.app",
+            now: NOW,
+        });
+        expect((0, _1.derivePairingRoomAccessToken)(invitation.roomSecret)).not.toBe((0, _1.derivePairingSignalingKey)(invitation.roomSecret));
+    });
+});

package/dist/device-pairing/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./constants";
+export * from "./crypto";
+export * from "./invitation";
+export * from "./signaling";
+export * from "./transcript";
+export * from "./types";

package/dist/device-pairing/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./constants"), exports);
+__exportStar(require("./crypto"), exports);
+__exportStar(require("./invitation"), exports);
+__exportStar(require("./signaling"), exports);
+__exportStar(require("./transcript"), exports);
+__exportStar(require("./types"), exports);

package/dist/device-pairing/invitation.d.ts

@@ -0,0 +1,13 @@
+import { type DevicePairingInvitation } from "./types";
+/** Creates a five-minute, high-entropy invitation for a signaling service origin. */
+export declare function createDevicePairingInvitation({ serviceOrigin, now, ttlMs, }: {
+    serviceOrigin: string;
+    now?: number;
+    ttlMs?: number;
+}): DevicePairingInvitation;
+/** Encodes an invitation as a versioned token suitable for a URL fragment or manual entry. */
+export declare function encodeDevicePairingInvitation(invitation: DevicePairingInvitation): string;
+/** Parses and validates a versioned invitation token or fragment URL. */
+export declare function parseDevicePairingInvitation(input: string, now?: number): DevicePairingInvitation;
+/** Places the invitation in a URL fragment so it is excluded from HTTP requests and access logs. */
+export declare function createDevicePairingInvitationUrl(invitationBaseUrl: string, invitation: DevicePairingInvitation): string;

package/dist/device-pairing/invitation.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDevicePairingInvitation = createDevicePairingInvitation;
+exports.encodeDevicePairingInvitation = encodeDevicePairingInvitation;
+exports.parseDevicePairingInvitation = parseDevicePairingInvitation;
+exports.createDevicePairingInvitationUrl = createDevicePairingInvitationUrl;
+const keys_1 = require("../keys");
+const constants_1 = require("./constants");
+const types_1 = require("./types");
+const INVITATION_TOKEN_PREFIX = "peers-pairing-v1.";
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+function normalizeServiceOrigin(value) {
+    const url = new URL(value);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error("Pairing service must use HTTP or HTTPS");
+    }
+    return url.origin;
+}
+function extractInvitationToken(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith(INVITATION_TOKEN_PREFIX)) {
+        return trimmed;
+    }
+    try {
+        const url = new URL(trimmed);
+        const fragment = url.hash.slice(1);
+        if (fragment.startsWith("pair=")) {
+            return decodeURIComponent(fragment.slice("pair=".length));
+        }
+        if (fragment.startsWith("pair?")) {
+            const token = new URLSearchParams(fragment.slice("pair?".length)).get("token");
+            if (token) {
+                return token;
+            }
+        }
+    }
+    catch {
+        // The generic error below deliberately avoids echoing invitation input.
+    }
+    throw new Error("Invalid pairing invitation");
+}
+/** Creates a five-minute, high-entropy invitation for a signaling service origin. */
+function createDevicePairingInvitation({ serviceOrigin, now = Date.now(), ttlMs = constants_1.DEVICE_PAIRING_TTL_MS, }) {
+    if (!Number.isSafeInteger(now) || ttlMs <= 0 || ttlMs > constants_1.DEVICE_PAIRING_TTL_MS) {
+        throw new Error("Invalid pairing invitation lifetime");
+    }
+    return types_1.devicePairingInvitationSchema.parse({
+        version: constants_1.DEVICE_PAIRING_PROTOCOL_VERSION,
+        roomId: (0, keys_1.newToken)(16),
+        roomSecret: (0, keys_1.newToken)(32),
+        expiresAt: now + ttlMs,
+        serviceOrigin: normalizeServiceOrigin(serviceOrigin),
+    });
+}
+/** Encodes an invitation as a versioned token suitable for a URL fragment or manual entry. */
+function encodeDevicePairingInvitation(invitation) {
+    const parsed = types_1.devicePairingInvitationSchema.parse(invitation);
+    return `${INVITATION_TOKEN_PREFIX}${(0, keys_1.encodeBase64)(textEncoder.encode(JSON.stringify(parsed)))}`;
+}
+/** Parses and validates a versioned invitation token or fragment URL. */
+function parseDevicePairingInvitation(input, now = Date.now()) {
+    try {
+        const token = extractInvitationToken(input);
+        if (!token.startsWith(INVITATION_TOKEN_PREFIX)) {
+            throw new Error("unsupported");
+        }
+        const encoded = token.slice(INVITATION_TOKEN_PREFIX.length);
+        const parsed = types_1.devicePairingInvitationSchema.parse(JSON.parse(textDecoder.decode((0, keys_1.decodeBase64)(encoded))));
+        if (parsed.expiresAt <= now ||
+            parsed.expiresAt > now + constants_1.DEVICE_PAIRING_TTL_MS + constants_1.DEVICE_PAIRING_CLOCK_SKEW_MS) {
+            throw new Error("expired");
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error("Invalid or expired pairing invitation");
+    }
+}
+/** Places the invitation in a URL fragment so it is excluded from HTTP requests and access logs. */
+function createDevicePairingInvitationUrl(invitationBaseUrl, invitation) {
+    const url = new URL(invitationBaseUrl);
+    url.hash = `pair=${encodeURIComponent(encodeDevicePairingInvitation(invitation))}`;
+    return url.toString();
+}

package/dist/device-pairing/signaling.d.ts

@@ -0,0 +1,9 @@
+import { type PairingRole, type PairingSignal, type UnsignedPairingSignal } from "./types";
+/** Attaches an HMAC to a validated canonical SDP or ICE signaling message. */
+export declare function signPairingSignal(signal: UnsignedPairingSignal, signalingKey: string): PairingSignal;
+/** Verifies message authentication, room/role binding, and the exact next sequence number. */
+export declare function verifyPairingSignal(signal: unknown, signalingKey: string, expected: {
+    roomId: string;
+    senderRole: PairingRole;
+    nextSequence: number;
+}): PairingSignal;

package/dist/device-pairing/signaling.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signPairingSignal = signPairingSignal;
+exports.verifyPairingSignal = verifyPairingSignal;
+const crypto_1 = require("./crypto");
+const types_1 = require("./types");
+/** Attaches an HMAC to a validated canonical SDP or ICE signaling message. */
+function signPairingSignal(signal, signalingKey) {
+    const parsed = types_1.unsignedPairingSignalSchema.parse(signal);
+    return types_1.pairingSignalSchema.parse({
+        ...parsed,
+        mac: (0, crypto_1.computePairingSignalMac)(parsed, signalingKey),
+    });
+}
+/** Verifies message authentication, room/role binding, and the exact next sequence number. */
+function verifyPairingSignal(signal, signalingKey, expected) {
+    const parsed = types_1.pairingSignalSchema.parse(signal);
+    const { mac, ...unsignedValue } = parsed;
+    const unsigned = types_1.unsignedPairingSignalSchema.parse(unsignedValue);
+    if (!(0, crypto_1.isPairingSignalMacValid)(unsigned, mac, signalingKey)) {
+        throw new Error("Pairing signaling authentication failed");
+    }
+    if (parsed.roomId !== expected.roomId ||
+        parsed.senderRole !== expected.senderRole ||
+        parsed.sequence !== expected.nextSequence) {
+        throw new Error("Pairing signaling message is out of order");
+    }
+    return parsed;
+}

package/dist/device-pairing/transcript.d.ts

@@ -0,0 +1,7 @@
+import { type DevicePairingTranscript } from "./types";
+/** Extracts a canonical set of SHA-256 DTLS fingerprints from an SDP document. */
+export declare function extractSha256SdpFingerprint(sdp: string): string;
+/** Hashes the canonical identities, nonces, room, and SDP fingerprints for one ceremony. */
+export declare function computeDevicePairingTranscriptHash(transcript: DevicePairingTranscript): string;
+/** Derives the same zero-padded six-digit SAS independently on both endpoints. */
+export declare function deriveDevicePairingSas(roomSecret: string, transcriptHash: string): string;

package/dist/device-pairing/transcript.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSha256SdpFingerprint = extractSha256SdpFingerprint;
+exports.computeDevicePairingTranscriptHash = computeDevicePairingTranscriptHash;
+exports.deriveDevicePairingSas = deriveDevicePairingSas;
+const hmac_1 = require("@noble/hashes/hmac");
+const sha2_1 = require("@noble/hashes/sha2");
+const keys_1 = require("../keys");
+const constants_1 = require("./constants");
+const types_1 = require("./types");
+const textEncoder = new TextEncoder();
+/** Extracts a canonical set of SHA-256 DTLS fingerprints from an SDP document. */
+function extractSha256SdpFingerprint(sdp) {
+    const fingerprints = new Set();
+    const expression = /^a=fingerprint:sha-256\s+([0-9a-f:]+)\s*$/gim;
+    for (const match of sdp.matchAll(expression)) {
+        const fingerprint = match[1].toUpperCase();
+        const bytes = fingerprint.split(":");
+        if (bytes.length === 32 && bytes.every((part) => /^[0-9A-F]{2}$/.test(part))) {
+            fingerprints.add(fingerprint);
+        }
+    }
+    if (fingerprints.size === 0) {
+        throw new Error("WebRTC description did not contain a SHA-256 fingerprint");
+    }
+    return [...fingerprints].sort().join(",");
+}
+/** Hashes the canonical identities, nonces, room, and SDP fingerprints for one ceremony. */
+function computeDevicePairingTranscriptHash(transcript) {
+    return types_1.pairingHashSchema.parse((0, keys_1.hashObject)(types_1.devicePairingTranscriptSchema.parse(transcript)));
+}
+/** Derives the same zero-padded six-digit SAS independently on both endpoints. */
+function deriveDevicePairingSas(roomSecret, transcriptHash) {
+    types_1.pairingHashSchema.parse(transcriptHash);
+    const digest = (0, hmac_1.hmac)(sha2_1.sha256, (0, keys_1.decodeBase64)(roomSecret), textEncoder.encode(`${constants_1.DEVICE_PAIRING_SAS_LABEL}${transcriptHash}`));
+    const value = (((digest[0] << 24) >>> 0) | (digest[1] << 16) | (digest[2] << 8) | digest[3]) >>> 0;
+    return (value % 1_000_000).toString().padStart(6, "0");
+}