@peers-app/peers-sdk 0.23.14 → 0.25.0

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

@@ -308,6 +308,79 @@ describe("device-election", () => {
             expect(result).toBeDefined();
             expect([device1, device2, device3]).toContain(result?.deviceId);
         });
+        describe("alternativeRoutes", () => {
+            it("never sheds a device whose only known route is through us when others have alternatives", () => {
+                const stranded = (0, utils_1.newid)();
+                const others = [(0, utils_1.newid)(), (0, utils_1.newid)(), (0, utils_1.newid)()];
+                const connections = [
+                    // worst latency and most groups would normally make this the victim
+                    { ...createConnection(stranded, 900, 0.5), groups: ["g"], alternativeRoutes: 0 },
+                    ...others.map((id) => ({
+                        ...createConnection(id, 5, 0.001),
+                        groups: ["g", "h"],
+                        alternativeRoutes: 3,
+                    })),
+                ];
+                for (let i = 0; i < 20; i++) {
+                    const result = (0, device_election_1.getLeastPreferredConnection)({
+                        connections: (0, lodash_1.shuffle)(connections),
+                        preferredDeviceIds: [],
+                        preferredByDeviceIds: [],
+                    });
+                    expect(result).toBeDefined();
+                    expect(result?.deviceId).not.toBe(stranded);
+                    expect(others).toContain(result?.deviceId);
+                }
+            });
+            it("falls back to the usual ordering when no candidate is known to have alternatives", () => {
+                const device1 = (0, utils_1.newid)();
+                const device2 = (0, utils_1.newid)();
+                const connections = [
+                    { ...createConnection(device1, 10, 0.001), groups: ["g"], alternativeRoutes: 0 },
+                    { ...createConnection(device2, 500, 0.5), groups: ["g"], alternativeRoutes: 0 },
+                ];
+                const result = (0, device_election_1.getLeastPreferredConnection)({
+                    connections,
+                    preferredDeviceIds: [],
+                    preferredByDeviceIds: [],
+                });
+                expect(result?.deviceId).toBe(device2);
+            });
+            it("treats unknown topology as neither protected nor preferred", () => {
+                const unknown = (0, utils_1.newid)();
+                const stranded = (0, utils_1.newid)();
+                const connected = (0, utils_1.newid)();
+                const connections = [
+                    { ...createConnection(unknown, 500, 0.5), groups: ["g"] },
+                    { ...createConnection(stranded, 10, 0.001), groups: ["g"], alternativeRoutes: 0 },
+                    { ...createConnection(connected, 10, 0.001), groups: ["g"], alternativeRoutes: 2 },
+                ];
+                for (let i = 0; i < 20; i++) {
+                    const result = (0, device_election_1.getLeastPreferredConnection)({
+                        connections: (0, lodash_1.shuffle)(connections),
+                        preferredDeviceIds: [],
+                        preferredByDeviceIds: [],
+                    });
+                    // the stranded device is excluded; unknown stays in the pool and loses on latency
+                    expect(result?.deviceId).toBe(unknown);
+                }
+            });
+            it("still respects preference tiers before route protection", () => {
+                const stranded = (0, utils_1.newid)();
+                const preferred = (0, utils_1.newid)();
+                const connections = [
+                    { ...createConnection(stranded), groups: ["g"], alternativeRoutes: 0 },
+                    { ...createConnection(preferred), groups: ["g"], alternativeRoutes: 4 },
+                ];
+                // the only non-preferred candidate is the stranded one, so the tier leaves just it
+                const result = (0, device_election_1.getLeastPreferredConnection)({
+                    connections,
+                    preferredDeviceIds: [preferred],
+                    preferredByDeviceIds: [],
+                });
+                expect(result?.deviceId).toBe(stranded);
+            });
+        });
     });
     describe("Network simulations", () => {
         it.skip("should work as connections grow", () => {

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

@@ -1,7 +1,15 @@
-/** Wire-protocol version for the temporary device-pairing ceremony. */
-export declare const DEVICE_PAIRING_PROTOCOL_VERSION: 1;
-/** Maximum lifetime of a pairing invitation and signaling room. */
+/**
+ * Wire-protocol version for the temporary device-pairing ceremony.
+ *
+ * - v2: reversed roles + PAKE.
+ * - v3: negotiated data transport (WebRTC or direct WebSocket); endpoint nonces move from the
+ *   SDP descriptions into the transport messages and the transcript binds `transportBinding`.
+ */
+export declare const DEVICE_PAIRING_PROTOCOL_VERSION: 3;
+/** Maximum lifetime of a pairing code and its signaling room. */
 export declare const DEVICE_PAIRING_TTL_MS: number;
+/** Largest nameplate the service allocates; codes read `<1..9999>-<word>-<word>-<word>`. */
+export declare const DEVICE_PAIRING_MAX_NAMEPLATE = 9999;
 /** Socket.IO namespace reserved for device-pairing signaling. */
 export declare const DEVICE_PAIRING_SIGNALING_NAMESPACE = "/device-pairing-v1";
 /** Dedicated Socket.IO engine path with a pairing-sized transport buffer. */
@@ -22,13 +30,23 @@ export declare const DEVICE_PAIRING_MAX_SIGNAL_BYTES: number;
 export declare const DEVICE_PAIRING_MAX_TRANSPORT_BYTES: number;
 /** Maximum ICE candidates accepted from either endpoint. */
 export declare const DEVICE_PAIRING_MAX_ICE_CANDIDATES_PER_ROLE = 64;
+/** Maximum direct WebSocket URLs a destination may advertise in its transport options. */
+export declare const DEVICE_PAIRING_MAX_WEBSOCKET_URLS = 8;
+/**
+ * Socket.IO namespace a destination hosts for the direct WebSocket pairing transport. The
+ * source authenticates with the PAKE-derived WebSocket token in `auth.token`.
+ */
+export declare const DEVICE_PAIRING_WEBSOCKET_NAMESPACE = "/device-pairing-transport-v1";
 /** Maximum tolerated source/destination wall-clock difference. */
 export declare const DEVICE_PAIRING_CLOCK_SKEW_MS: number;
 /** Event name used to publish renderer-safe pairing state. */
 export declare const DEVICE_PAIRING_STATE_EVENT = "device-pairing:state";
-/** Domain-separation label for the room bearer credential. */
-export declare const DEVICE_PAIRING_ROOM_ACCESS_LABEL = "peers-pairing-room-access-v1";
-/** Domain-separation label for signaling message authentication. */
-export declare const DEVICE_PAIRING_SIGNALING_LABEL = "peers-pairing-signaling-v1";
-/** Domain-separation label for the six-digit short authentication string. */
-export declare const DEVICE_PAIRING_SAS_LABEL = "peers-pairing-sas-v1";
+/** Domain-separation label for the PAKE-derived signaling authentication key. */
+export declare const DEVICE_PAIRING_SIGNALING_LABEL = "peers-pairing-signaling-v3";
+/** Domain-separation label for the PAKE-derived transcript confirmation key. */
+export declare const DEVICE_PAIRING_CONFIRM_LABEL = "peers-pairing-confirm-v3";
+/**
+ * Domain-separation label for the token a source presents when it connects to a destination's
+ * direct WebSocket pairing listener. Derived from the signaling key; never sent via the relay.
+ */
+export declare const DEVICE_PAIRING_WEBSOCKET_TOKEN_LABEL = "peers-pairing-websocket-token-v3";

package/dist/device-pairing/constants.js

@@ -1,10 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEVICE_PAIRING_SAS_LABEL = exports.DEVICE_PAIRING_SIGNALING_LABEL = exports.DEVICE_PAIRING_ROOM_ACCESS_LABEL = exports.DEVICE_PAIRING_STATE_EVENT = exports.DEVICE_PAIRING_CLOCK_SKEW_MS = exports.DEVICE_PAIRING_MAX_ICE_CANDIDATES_PER_ROLE = exports.DEVICE_PAIRING_MAX_TRANSPORT_BYTES = exports.DEVICE_PAIRING_MAX_SIGNAL_BYTES = exports.DEVICE_PAIRING_SIGNALING_EVENTS = exports.DEVICE_PAIRING_SIGNALING_PATH = exports.DEVICE_PAIRING_SIGNALING_NAMESPACE = exports.DEVICE_PAIRING_TTL_MS = exports.DEVICE_PAIRING_PROTOCOL_VERSION = void 0;
-/** Wire-protocol version for the temporary device-pairing ceremony. */
-exports.DEVICE_PAIRING_PROTOCOL_VERSION = 1;
-/** Maximum lifetime of a pairing invitation and signaling room. */
+exports.DEVICE_PAIRING_WEBSOCKET_TOKEN_LABEL = exports.DEVICE_PAIRING_CONFIRM_LABEL = exports.DEVICE_PAIRING_SIGNALING_LABEL = exports.DEVICE_PAIRING_STATE_EVENT = exports.DEVICE_PAIRING_CLOCK_SKEW_MS = exports.DEVICE_PAIRING_WEBSOCKET_NAMESPACE = exports.DEVICE_PAIRING_MAX_WEBSOCKET_URLS = exports.DEVICE_PAIRING_MAX_ICE_CANDIDATES_PER_ROLE = exports.DEVICE_PAIRING_MAX_TRANSPORT_BYTES = exports.DEVICE_PAIRING_MAX_SIGNAL_BYTES = exports.DEVICE_PAIRING_SIGNALING_EVENTS = exports.DEVICE_PAIRING_SIGNALING_PATH = exports.DEVICE_PAIRING_SIGNALING_NAMESPACE = exports.DEVICE_PAIRING_MAX_NAMEPLATE = exports.DEVICE_PAIRING_TTL_MS = exports.DEVICE_PAIRING_PROTOCOL_VERSION = void 0;
+/**
+ * Wire-protocol version for the temporary device-pairing ceremony.
+ *
+ * - v2: reversed roles + PAKE.
+ * - v3: negotiated data transport (WebRTC or direct WebSocket); endpoint nonces move from the
+ *   SDP descriptions into the transport messages and the transcript binds `transportBinding`.
+ */
+exports.DEVICE_PAIRING_PROTOCOL_VERSION = 3;
+/** Maximum lifetime of a pairing code and its signaling room. */
 exports.DEVICE_PAIRING_TTL_MS = 5 * 60 * 1000;
+/** Largest nameplate the service allocates; codes read `<1..9999>-<word>-<word>-<word>`. */
+exports.DEVICE_PAIRING_MAX_NAMEPLATE = 9999;
 /** Socket.IO namespace reserved for device-pairing signaling. */
 exports.DEVICE_PAIRING_SIGNALING_NAMESPACE = "/device-pairing-v1";
 /** Dedicated Socket.IO engine path with a pairing-sized transport buffer. */
@@ -25,13 +33,23 @@ exports.DEVICE_PAIRING_MAX_SIGNAL_BYTES = 72 * 1024;
 exports.DEVICE_PAIRING_MAX_TRANSPORT_BYTES = 96 * 1024;
 /** Maximum ICE candidates accepted from either endpoint. */
 exports.DEVICE_PAIRING_MAX_ICE_CANDIDATES_PER_ROLE = 64;
+/** Maximum direct WebSocket URLs a destination may advertise in its transport options. */
+exports.DEVICE_PAIRING_MAX_WEBSOCKET_URLS = 8;
+/**
+ * Socket.IO namespace a destination hosts for the direct WebSocket pairing transport. The
+ * source authenticates with the PAKE-derived WebSocket token in `auth.token`.
+ */
+exports.DEVICE_PAIRING_WEBSOCKET_NAMESPACE = "/device-pairing-transport-v1";
 /** Maximum tolerated source/destination wall-clock difference. */
 exports.DEVICE_PAIRING_CLOCK_SKEW_MS = 2 * 60 * 1000;
 /** Event name used to publish renderer-safe pairing state. */
 exports.DEVICE_PAIRING_STATE_EVENT = "device-pairing:state";
-/** Domain-separation label for the room bearer credential. */
-exports.DEVICE_PAIRING_ROOM_ACCESS_LABEL = "peers-pairing-room-access-v1";
-/** Domain-separation label for signaling message authentication. */
-exports.DEVICE_PAIRING_SIGNALING_LABEL = "peers-pairing-signaling-v1";
-/** Domain-separation label for the six-digit short authentication string. */
-exports.DEVICE_PAIRING_SAS_LABEL = "peers-pairing-sas-v1";
+/** Domain-separation label for the PAKE-derived signaling authentication key. */
+exports.DEVICE_PAIRING_SIGNALING_LABEL = "peers-pairing-signaling-v3";
+/** Domain-separation label for the PAKE-derived transcript confirmation key. */
+exports.DEVICE_PAIRING_CONFIRM_LABEL = "peers-pairing-confirm-v3";
+/**
+ * Domain-separation label for the token a source presents when it connects to a destination's
+ * direct WebSocket pairing listener. Derived from the signaling key; never sent via the relay.
+ */
+exports.DEVICE_PAIRING_WEBSOCKET_TOKEN_LABEL = "peers-pairing-websocket-token-v3";

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

@@ -0,0 +1,46 @@
+/** Role in the one-round CPace exchange; the initiator's share is listed first in the transcript. */
+export type CpaceRole = "initiator" | "responder";
+/** Inputs that both parties must agree on for the exchange to succeed. */
+export interface CpaceParameters {
+    /** Password-related string (PRS); for pairing, the code words. */
+    password: Uint8Array;
+    /** Channel identifier (CI) binding the exchange to one rendezvous. */
+    channelId: Uint8Array;
+    /** Optional session id (sid); empty when the channel identifier is already unique. */
+    sessionId?: Uint8Array;
+    /** Associated data sent alongside the initiator's share. */
+    initiatorAd?: Uint8Array;
+    /** Associated data sent alongside the responder's share. */
+    responderAd?: Uint8Array;
+}
+/** One party's in-progress exchange. */
+export interface CpaceSession {
+    /** Public share (32-byte X25519 u-coordinate) to send to the other party. */
+    readonly share: Uint8Array;
+    /**
+     * Consumes the remote share and returns the 64-byte ISK.
+     * @throws when the remote share encodes a low-order point (the exchange must be aborted).
+     */
+    finish(remoteShare: Uint8Array): Uint8Array;
+}
+/** LEB128 length prefix as defined by the draft's `prepend_len`. */
+export declare function cpacePrependLength(data: Uint8Array): Uint8Array;
+/** Length-prefixed concatenation (`lv_cat`). */
+export declare function cpaceLvCat(...parts: Uint8Array[]): Uint8Array;
+/** Builds the `generator_string` that is hashed into the secret generator. */
+export declare function cpaceGeneratorString(password: Uint8Array, channelId: Uint8Array, sessionId: Uint8Array): Uint8Array;
+/** Elligator 2 map from a field element to a Curve25519 u-coordinate (RFC 9380 `map_to_curve_elligator2`). */
+export declare function cpaceElligator2(u: bigint): Uint8Array;
+/** Derives the password-dependent generator `g` for one exchange. */
+export declare function cpaceCalculateGenerator(password: Uint8Array, channelId: Uint8Array, sessionId?: Uint8Array): Uint8Array;
+/** X25519 scalar multiplication that rejects results in the small subgroup (`scalar_mult_vfy`). */
+export declare function cpaceScalarMultVerify(scalar: Uint8Array, point: Uint8Array): Uint8Array;
+/** Initiator/responder transcript (`transcript_ir`). */
+export declare function cpaceTranscript(initiatorShare: Uint8Array, initiatorAd: Uint8Array, responderShare: Uint8Array, responderAd: Uint8Array): Uint8Array;
+/** Final ISK derivation: `H(lv_cat(DSI_ISK, sid, K) || transcript)`. */
+export declare function cpaceDeriveIsk(sharedPoint: Uint8Array, sessionId: Uint8Array, transcript: Uint8Array): Uint8Array;
+/**
+ * Starts one side of a CPace exchange. The returned share is safe to send in the clear.
+ * `scalar` may be injected for deterministic test vectors; production callers omit it.
+ */
+export declare function cpaceStart(role: CpaceRole, parameters: CpaceParameters, scalar?: Uint8Array): CpaceSession;

package/dist/device-pairing/cpace.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cpacePrependLength = cpacePrependLength;
+exports.cpaceLvCat = cpaceLvCat;
+exports.cpaceGeneratorString = cpaceGeneratorString;
+exports.cpaceElligator2 = cpaceElligator2;
+exports.cpaceCalculateGenerator = cpaceCalculateGenerator;
+exports.cpaceScalarMultVerify = cpaceScalarMultVerify;
+exports.cpaceTranscript = cpaceTranscript;
+exports.cpaceDeriveIsk = cpaceDeriveIsk;
+exports.cpaceStart = cpaceStart;
+const sha2_1 = require("@noble/hashes/sha2");
+const nacl = require("tweetnacl");
+/**
+ * CPace balanced PAKE over X25519 with SHA-512 (cipher suite `CPace255`), implemented per
+ * draft-irtf-cfrg-cpace. Both parties derive the same 64-byte intermediate session key (ISK)
+ * if and only if they used the same password, channel identifier, and session id, and saw
+ * each other's public shares unmodified. A wrong password yields an unrelated ISK; nothing
+ * about the password can be recovered from the transcript.
+ *
+ * Group operations use `tweetnacl`'s X25519 (`scalarMult`); the Elligator 2 map that turns
+ * the hashed password into a secret generator is implemented here on `bigint` field
+ * arithmetic (Curve25519, `A = 486662`, `Z = 2`). Verified against the draft's test vectors.
+ */
+const FIELD_PRIME = 2n ** 255n - 19n;
+const CURVE_A = 486662n;
+const ELLIGATOR_Z = 2n;
+const FIELD_SIZE_BYTES = 32;
+const HASH_BLOCK_BYTES = 128;
+const DSI = new TextEncoder().encode("CPace255");
+const DSI_ISK = new TextEncoder().encode("CPace255_ISK");
+function mod(value) {
+    const result = value % FIELD_PRIME;
+    return result >= 0n ? result : result + FIELD_PRIME;
+}
+function modPow(base, exponent) {
+    let result = 1n;
+    let current = mod(base);
+    let remaining = exponent;
+    while (remaining > 0n) {
+        if (remaining & 1n) {
+            result = mod(result * current);
+        }
+        current = mod(current * current);
+        remaining >>= 1n;
+    }
+    return result;
+}
+function modInverse(value) {
+    return modPow(value, FIELD_PRIME - 2n);
+}
+/** LEB128 length prefix as defined by the draft's `prepend_len`. */
+function cpacePrependLength(data) {
+    const prefix = [];
+    let length = data.length;
+    while (true) {
+        if (length < 128) {
+            prefix.push(length);
+        }
+        else {
+            prefix.push((length & 0x7f) + 0x80);
+        }
+        length >>= 7;
+        if (length === 0) {
+            break;
+        }
+    }
+    return concatBytes(Uint8Array.from(prefix), data);
+}
+/** Length-prefixed concatenation (`lv_cat`). */
+function cpaceLvCat(...parts) {
+    return concatBytes(...parts.map((part) => cpacePrependLength(part)));
+}
+function concatBytes(...parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+/** Builds the `generator_string` that is hashed into the secret generator. */
+function cpaceGeneratorString(password, channelId, sessionId) {
+    const zeroPadLength = Math.max(0, HASH_BLOCK_BYTES - 1 - cpacePrependLength(password).length - cpacePrependLength(DSI).length);
+    return cpaceLvCat(DSI, password, new Uint8Array(zeroPadLength), channelId, sessionId);
+}
+function decodeUCoordinate(bytes) {
+    const copy = Uint8Array.from(bytes);
+    copy[FIELD_SIZE_BYTES - 1] &= 0x7f;
+    let value = 0n;
+    for (let index = copy.length - 1; index >= 0; index--) {
+        value = (value << 8n) | BigInt(copy[index]);
+    }
+    return value;
+}
+function encodeUCoordinate(value) {
+    const bytes = new Uint8Array(FIELD_SIZE_BYTES);
+    let remaining = mod(value);
+    for (let index = 0; index < FIELD_SIZE_BYTES; index++) {
+        bytes[index] = Number(remaining & 0xffn);
+        remaining >>= 8n;
+    }
+    return bytes;
+}
+/** Elligator 2 map from a field element to a Curve25519 u-coordinate (RFC 9380 `map_to_curve_elligator2`). */
+function cpaceElligator2(u) {
+    const v = mod(-CURVE_A * modInverse(1n + ELLIGATOR_Z * u * u));
+    const legendre = modPow(mod(v * v * v + CURVE_A * v * v + v), (FIELD_PRIME - 1n) / 2n);
+    const x = mod(legendre * v - (1n - legendre) * CURVE_A * modInverse(2n));
+    return encodeUCoordinate(x);
+}
+/** Derives the password-dependent generator `g` for one exchange. */
+function cpaceCalculateGenerator(password, channelId, sessionId = new Uint8Array(0)) {
+    const digest = (0, sha2_1.sha512)(cpaceGeneratorString(password, channelId, sessionId));
+    return cpaceElligator2(decodeUCoordinate(digest.slice(0, FIELD_SIZE_BYTES)));
+}
+function isAllZero(bytes) {
+    let accumulator = 0;
+    for (const byte of bytes) {
+        accumulator |= byte;
+    }
+    return accumulator === 0;
+}
+/** X25519 scalar multiplication that rejects results in the small subgroup (`scalar_mult_vfy`). */
+function cpaceScalarMultVerify(scalar, point) {
+    if (scalar.length !== FIELD_SIZE_BYTES || point.length !== FIELD_SIZE_BYTES) {
+        throw new Error("CPace shares must be 32 bytes");
+    }
+    const result = nacl.scalarMult(scalar, point);
+    if (isAllZero(result)) {
+        throw new Error("CPace received a low-order point");
+    }
+    return result;
+}
+/** Initiator/responder transcript (`transcript_ir`). */
+function cpaceTranscript(initiatorShare, initiatorAd, responderShare, responderAd) {
+    return concatBytes(cpaceLvCat(initiatorShare, initiatorAd), cpaceLvCat(responderShare, responderAd));
+}
+/** Final ISK derivation: `H(lv_cat(DSI_ISK, sid, K) || transcript)`. */
+function cpaceDeriveIsk(sharedPoint, sessionId, transcript) {
+    return (0, sha2_1.sha512)(concatBytes(cpaceLvCat(DSI_ISK, sessionId, sharedPoint), transcript));
+}
+/**
+ * Starts one side of a CPace exchange. The returned share is safe to send in the clear.
+ * `scalar` may be injected for deterministic test vectors; production callers omit it.
+ */
+function cpaceStart(role, parameters, scalar = nacl.randomBytes(FIELD_SIZE_BYTES)) {
+    const sessionId = parameters.sessionId ?? new Uint8Array(0);
+    const initiatorAd = parameters.initiatorAd ?? new Uint8Array(0);
+    const responderAd = parameters.responderAd ?? new Uint8Array(0);
+    const generator = cpaceCalculateGenerator(parameters.password, parameters.channelId, sessionId);
+    const share = cpaceScalarMultVerify(scalar, generator);
+    let finished = false;
+    return {
+        share,
+        finish(remoteShare) {
+            if (finished) {
+                throw new Error("CPace session already finished");
+            }
+            finished = true;
+            const sharedPoint = cpaceScalarMultVerify(scalar, remoteShare);
+            const transcript = role === "initiator"
+                ? cpaceTranscript(share, initiatorAd, remoteShare, responderAd)
+                : cpaceTranscript(remoteShare, initiatorAd, share, responderAd);
+            const isk = cpaceDeriveIsk(sharedPoint, sessionId, transcript);
+            scalar.fill(0);
+            sharedPoint.fill(0);
+            return isk;
+        },
+    };
+}

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

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cpace_1 = require("./cpace");
+// Test vectors from draft-irtf-cfrg-cpace, "CPace using group X25519 and hash SHA-512".
+const VECTOR = {
+    PRS: "50617373776F7264",
+    CI: "0B415F696E69746961746F720B425F726573706F6E646572",
+    sid: "7E4B4791D6A8EF019B936C79FB7F2C57",
+    g: "D04BF6D41F6A289632A2E929FA29BEBD51092512A7829FDDE7D314B62F05A73F",
+    ya: "21B4F4BD9E64ED355C3EB676A28EBEDAF6D8F17BDC365995B319097153044080",
+    ADa: "414461",
+    Ya: "1D13C89278CDADD826F6D8D7F887701430F8380DDC17611CDD6DC989CE0C9F32",
+    yb: "848B0779FF415F0AF4EA14DF9DD1D3C29AC41D836C7808896C4EBA19C51AC40A",
+    ADb: "414462",
+    Yb: "248CCCF6D5CDC3646F0AD593F9E6CEF4E69D4945F8372E623512ECEA32185623",
+    K: "5B067EFFBDC0B2A0E1D907B21EBB25CFEDB96A852179A847C37E43EE71322C6B",
+    ISK_IR: "6E19B875F7A561D6B3CA3DBB9EF42AC55DE3E717881018204B8922B4D5E53BB2AA82C300BEA7B65D2B671DA71922DDF6472301B79BC270ADFA8BF413285F2263",
+};
+// scalar_mult_vfy vectors: low-order (and non-canonical low-order) inputs abort; the rest
+// must produce the draft's exact outputs, proving bit #255 is cleared before the ladder.
+const VFY_SCALAR = "AF46E36BF0527C9D3B16154B82465EDD62144C0AC1FC5A18506A2244BA449AFF";
+const LOW_ORDER_POINTS = [
+    "0000000000000000000000000000000000000000000000000000000000000000",
+    "0100000000000000000000000000000000000000000000000000000000000000",
+    "ECFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7F",
+    "E0EB7A7C3B41B8AE1656E3FAF19FC46ADA098DEB9C32B1FD866205165F49B800",
+    "5F9C95BCA3508C24B1D0B1559C83EF5B04445CC4581C8E86D8224EDDD09F1157",
+    "EDFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7F",
+    "EEFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7F",
+];
+const NON_CANONICAL_POINTS = [
+    [
+        "DAFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",
+        "D8E2C776BBACD510D09FD9278B7EDCD25FC5AE9ADFBA3B6E040E8D3B71B21806",
+    ],
+    [
+        "DBFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",
+        "C85C655EBE8BE44BA9C0FFDE69F2FE10194458D137F09BBFF725CE58803CDB38",
+    ],
+    [
+        "D9FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF",
+        "DB64DAFA9B8FDD136914E61461935FE92AA372CB056314E1231BC4EC12417456",
+    ],
+    [
+        "CDEB7A7C3B41B8AE1656E3FAF19FC46ADA098DEB9C32B1FD866205165F49B880",
+        "E062DCD5376D58297BE2618C7498F55BAA07D7E03184E8AADA20BCA28888BF7A",
+    ],
+    [
+        "4C9C95BCA3508C24B1D0B1559C83EF5B04445CC4581C8E86D8224EDDD09F11D7",
+        "993C6AD11C4C29DA9A56F7691FD0FF8D732E49DE6250B6C2E80003FF4629A175",
+    ],
+];
+function hex(value) {
+    return Uint8Array.from(Buffer.from(value, "hex"));
+}
+function toHex(value) {
+    return Buffer.from(value).toString("hex").toUpperCase();
+}
+describe("cpace string utilities", () => {
+    it("matches prepend_len and lv_cat vectors", () => {
+        expect(toHex((0, cpace_1.cpacePrependLength)(new Uint8Array(0)))).toBe("00");
+        expect(toHex((0, cpace_1.cpacePrependLength)(Buffer.from("1234")))).toBe("0431323334");
+        expect(toHex((0, cpace_1.cpacePrependLength)(new Uint8Array(128))).slice(0, 4)).toBe("8001");
+        expect(toHex((0, cpace_1.cpaceLvCat)(Buffer.from("1234"), Buffer.from("5"), new Uint8Array(0), Buffer.from("678")))).toBe("043132333401350003363738");
+    });
+    it("matches transcript_ir vector", () => {
+        expect(toHex((0, cpace_1.cpaceTranscript)(Buffer.from("123"), Buffer.from("PartyA"), Buffer.from("234"), Buffer.from("PartyB")))).toBe("03313233065061727479410332333406506172747942");
+    });
+});
+describe("cpace CPace255 vectors", () => {
+    it("derives the generator string and secret generator", () => {
+        const generatorString = (0, cpace_1.cpaceGeneratorString)(hex(VECTOR.PRS), hex(VECTOR.CI), hex(VECTOR.sid));
+        expect(generatorString).toHaveLength(170);
+        expect(toHex(generatorString).startsWith("0843506163653235350850617373776F72646D00")).toBe(true);
+        expect(toHex((0, cpace_1.cpaceCalculateGenerator)(hex(VECTOR.PRS), hex(VECTOR.CI), hex(VECTOR.sid)))).toBe(VECTOR.g);
+    });
+    it("derives both shares, the shared point, and the initiator/responder ISK", () => {
+        const parameters = {
+            password: hex(VECTOR.PRS),
+            channelId: hex(VECTOR.CI),
+            sessionId: hex(VECTOR.sid),
+            initiatorAd: hex(VECTOR.ADa),
+            responderAd: hex(VECTOR.ADb),
+        };
+        const initiator = (0, cpace_1.cpaceStart)("initiator", parameters, hex(VECTOR.ya));
+        const responder = (0, cpace_1.cpaceStart)("responder", parameters, hex(VECTOR.yb));
+        expect(toHex(initiator.share)).toBe(VECTOR.Ya);
+        expect(toHex(responder.share)).toBe(VECTOR.Yb);
+        expect(toHex((0, cpace_1.cpaceScalarMultVerify)(hex(VECTOR.ya), hex(VECTOR.Yb)))).toBe(VECTOR.K);
+        expect(toHex((0, cpace_1.cpaceDeriveIsk)(hex(VECTOR.K), hex(VECTOR.sid), (0, cpace_1.cpaceTranscript)(hex(VECTOR.Ya), hex(VECTOR.ADa), hex(VECTOR.Yb), hex(VECTOR.ADb))))).toBe(VECTOR.ISK_IR);
+        const initiatorIsk = toHex(initiator.finish(hex(VECTOR.Yb)));
+        const responderIsk = toHex(responder.finish(hex(VECTOR.Ya)));
+        expect(initiatorIsk).toBe(VECTOR.ISK_IR);
+        expect(responderIsk).toBe(VECTOR.ISK_IR);
+    });
+    it("rejects low-order points and clears bit #255 of non-canonical inputs", () => {
+        for (const point of LOW_ORDER_POINTS) {
+            expect(() => (0, cpace_1.cpaceScalarMultVerify)(hex(VFY_SCALAR), hex(point))).toThrow(/low-order/);
+        }
+        for (const [point, expected] of NON_CANONICAL_POINTS) {
+            expect(toHex((0, cpace_1.cpaceScalarMultVerify)(hex(VFY_SCALAR), hex(point)))).toBe(expected);
+        }
+    });
+    it("produces unrelated keys for different passwords and identical keys for the same password", () => {
+        const shared = { channelId: Buffer.from("channel"), sessionId: new Uint8Array(0) };
+        const good = (0, cpace_1.cpaceStart)("initiator", { ...shared, password: Buffer.from("guitar-revenge") });
+        const right = (0, cpace_1.cpaceStart)("responder", { ...shared, password: Buffer.from("guitar-revenge") });
+        const wrong = (0, cpace_1.cpaceStart)("responder", { ...shared, password: Buffer.from("guitar-reward") });
+        const rightShare = Uint8Array.from(right.share);
+        const wrongShare = Uint8Array.from(wrong.share);
+        const goodShare = Uint8Array.from(good.share);
+        expect(toHex(right.finish(goodShare))).toBe(toHex(good.finish(rightShare)));
+        const second = (0, cpace_1.cpaceStart)("initiator", { ...shared, password: Buffer.from("guitar-revenge") });
+        expect(toHex(wrong.finish(Uint8Array.from(second.share)))).not.toBe(toHex(second.finish(wrongShare)));
+    });
+});

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

@@ -1,25 +1,50 @@
 import type { IDeviceInfo } from "../data/devices";
 import type { Device } from "../device/device";
-import { type PairingCredentialContents, type PairingRole, type SignedPairingApproval, type SignedPairingInstallationReceipt, type UnsignedPairingSignal } from "./types";
-/** Derives the high-entropy bearer credential presented when joining a room. */
-export declare function derivePairingRoomAccessToken(roomSecret: string): string;
-/** Hashes a room bearer credential before the source gives its verifier to the service. */
-export declare function hashPairingRoomAccessToken(roomAccessToken: string): string;
-/** Derives the client-only key used to authenticate SDP and ICE messages. */
-export declare function derivePairingSignalingKey(roomSecret: string): string;
+import { type PairingCode } from "./pairing-code";
+import { type PairingConfirmation, type PairingConfirmationContents, type PairingCredentialContents, type PairingRole, type SignedPairingInstallationReceipt, type UnsignedPairingSignal } from "./types";
+/** Symmetric keys both endpoints derive from the PAKE intermediate session key. */
+export interface PairingSessionKeys {
+    /** Authenticates transport, SDP, and ICE signaling relayed by the service. */
+    signalingKey: string;
+    /** Authenticates the post-handshake transcript confirmation. */
+    confirmKey: string;
+}
+/** One endpoint's in-progress PAKE over the pairing code. */
+export interface PairingPake {
+    /** Base64url public share to send in the `pake` signal. */
+    share: string;
+    /** Consumes the remote share and derives the session keys; throws on an invalid share. */
+    finish(remoteShare: string): PairingSessionKeys;
+}
+/**
+ * Starts CPace for one role. The source is the initiator and the destination the responder;
+ * the exchange is bound to the service origin and nameplate so a relayed share from another
+ * room cannot be replayed.
+ */
+export declare function startPairingPake(role: PairingRole, code: PairingCode, serviceOrigin: string): PairingPake;
+/** Derives independent signaling and confirmation keys from a PAKE intermediate session key. */
+export declare function derivePairingSessionKeys(isk: Uint8Array): PairingSessionKeys;
+/**
+ * Derives the token a source presents (`auth.token`) when it connects to the destination's direct
+ * WebSocket pairing listener. Both endpoints compute it from the signaling key, so it never
+ * travels through the rendezvous; a socket without it is refused before any Connection exists.
+ */
+export declare function derivePairingWebSocketToken(signalingKey: string): string;
 /** Computes the MAC over the canonical unsigned signaling envelope. */
 export declare function computePairingSignalMac(signal: UnsignedPairingSignal, signalingKey: string): string;
 /** Verifies a signaling MAC without short-circuiting on the first differing byte. */
 export declare function isPairingSignalMacValid(signal: UnsignedPairingSignal, mac: string, signalingKey: string): boolean;
-/** Creates a signed, expiring approval for one pairing transcript. */
-export declare function createSignedPairingApproval(device: Device, role: PairingRole, transcriptHash: string, expiresAt: number): SignedPairingApproval;
-/** Verifies an approval's signature, endpoint identity, transcript, role, and lifetime. */
-export declare function verifySignedPairingApproval(approval: SignedPairingApproval, expected: {
-    publicKey: string;
-    transcriptHash: string;
+/** Builds the local `pairing.confirm` message authenticated with the PAKE confirmation key. */
+export declare function createPairingConfirmation(contents: Omit<PairingConfirmationContents, "version">, confirmKey: string): PairingConfirmation;
+/**
+ * Verifies the remote confirmation's MAC, role, transcript, and identity binding.
+ * A MAC failure means the other endpoint used a different code or saw a different transcript.
+ */
+export declare function verifyPairingConfirmation(value: unknown, confirmKey: string, expected: {
     role: PairingRole;
-    now?: number;
-}): string;
+    transcriptHash: string;
+    device: IDeviceInfo;
+}): PairingConfirmation;
 /** Signs and encrypts account credentials directly to the temporary destination identity. */
 export declare function createPairingCredentialEnvelope(sourceDevice: Device, destinationDevice: IDeviceInfo, credentials: {
     userId: string;