@peers-app/peers-sdk 0.23.14 → 0.24.0

package/dist/data/invites.d.ts

@@ -0,0 +1,350 @@
+import { z } from "zod";
+import type { DataContext } from "../context/data-context";
+import { GroupMemberRole } from "./group-member-roles";
+/** Lifecycle of an invite row. */
+export declare const inviteStatusSchema: z.ZodEnum<["pending", "accepted", "declined", "expired", "revoked"]>;
+/** Lifecycle of an invite row. */
+export type InviteStatus = z.infer<typeof inviteStatusSchema>;
+/**
+ * How the invite was issued:
+ * - `direct`: a known contact was invited to a group (3a); the payload is the approval.
+ * - `approve`: group link whose join requests the inviter approves (3b).
+ * - `open`: group link any Admin+ member auto-approves (3c).
+ * - `profile`: the reusable contact QR on the Account screen.
+ * - `contact`: a one-off contact token.
+ */
+export declare const inviteModeSchema: z.ZodEnum<["direct", "approve", "open", "profile", "contact"]>;
+/** How the invite was issued. */
+export type InviteMode = z.infer<typeof inviteModeSchema>;
+/** Outbound delivery progress; `queued` rows are retried when connectivity changes. */
+export declare const inviteDeliveryStateSchema: z.ZodEnum<["queued", "sent"]>;
+/**
+ * One pending or historical invite, synced across the user's devices.
+ *
+ * Boxed payloads are encrypted to the user's box key, which every one of their devices
+ * holds, so storing them in this personal-context table is safe. Rows move to a terminal
+ * status rather than being deleted; terminal rows older than 30 days are purged.
+ */
+export declare const inviteSchema: z.ZodObject<{
+    inviteId: z.ZodEffects<z.ZodString, string, string>;
+    direction: z.ZodEnum<["in", "out"]>;
+    type: z.ZodEnum<["contact", "group"]>;
+    status: z.ZodDefault<z.ZodEnum<["pending", "accepted", "declined", "expired", "revoked"]>>;
+    mode: z.ZodEnum<["direct", "approve", "open", "profile", "contact"]>;
+    /** The other party, once known (unknown for outstanding link invites). */
+    counterpart: z.ZodOptional<z.ZodObject<{
+        userId: z.ZodEffects<z.ZodString, string, string>;
+        publicKey: z.ZodString;
+        publicBoxKey: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    }, {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    }>>;
+    /** Device the counterpart used, when they told us; lets the network layer connect early. */
+    counterpartDeviceId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    /**
+     * Correlates replies with this row: the token nonce for link invites, a fresh nonce for
+     * direct invites.
+     */
+    nonce: z.ZodOptional<z.ZodString>;
+    groupId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    groupName: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodNativeEnum<typeof GroupMemberRole>>;
+    /** The signed token: what I issued (out) or what I received/used (in). */
+    token: z.ZodOptional<z.ZodObject<{
+        v: z.ZodLiteral<1>;
+        type: z.ZodEnum<["contact", "group"]>;
+        inviter: z.ZodObject<{
+            userId: z.ZodEffects<z.ZodString, string, string>;
+            publicKey: z.ZodString;
+            publicBoxKey: z.ZodString;
+            displayName: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            publicKey: string;
+            publicBoxKey: string;
+            userId: string;
+            displayName?: string | undefined;
+        }, {
+            publicKey: string;
+            publicBoxKey: string;
+            userId: string;
+            displayName?: string | undefined;
+        }>;
+        expiresAt: z.ZodString;
+        nonce: z.ZodString;
+        epoch: z.ZodNumber;
+        uses: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<"unlimited">]>;
+        group: z.ZodOptional<z.ZodObject<{
+            groupId: z.ZodEffects<z.ZodString, string, string>;
+            name: z.ZodString;
+            publicKey: z.ZodString;
+            publicBoxKey: z.ZodString;
+            role: z.ZodNativeEnum<typeof GroupMemberRole>;
+            mode: z.ZodEnum<["approve", "open"]>;
+        }, "strict", z.ZodTypeAny, {
+            name: string;
+            role: GroupMemberRole;
+            publicKey: string;
+            groupId: string;
+            publicBoxKey: string;
+            mode: "open" | "approve";
+        }, {
+            name: string;
+            role: GroupMemberRole;
+            publicKey: string;
+            groupId: string;
+            publicBoxKey: string;
+            mode: "open" | "approve";
+        }>>;
+        signature: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: "group" | "contact";
+        nonce: string;
+        signature: string;
+        expiresAt: string;
+        v: 1;
+        inviter: {
+            publicKey: string;
+            publicBoxKey: string;
+            userId: string;
+            displayName?: string | undefined;
+        };
+        epoch: number;
+        uses: 1 | "unlimited";
+        group?: {
+            name: string;
+            role: GroupMemberRole;
+            publicKey: string;
+            groupId: string;
+            publicBoxKey: string;
+            mode: "open" | "approve";
+        } | undefined;
+    }, {
+        type: "group" | "contact";
+        nonce: string;
+        signature: string;
+        expiresAt: string;
+        v: 1;
+        inviter: {
+            publicKey: string;
+            publicBoxKey: string;
+            userId: string;
+            displayName?: string | undefined;
+        };
+        epoch: number;
+        uses: 1 | "unlimited";
+        group?: {
+            name: string;
+            role: GroupMemberRole;
+            publicKey: string;
+            groupId: string;
+            publicBoxKey: string;
+            mode: "open" | "approve";
+        } | undefined;
+    }>>;
+    /**
+     * For `in` direct invites: the GroupApproval boxed to my own user box key. For rows whose
+     * `deliveryState` is `queued`: the outbound box (already sealed to `recipientUserId`).
+     */
+    payload: z.ZodOptional<z.ZodObject<{
+        contents: z.ZodString;
+        nonce: z.ZodString;
+        fromPublicKey: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        nonce: string;
+        contents: string;
+        fromPublicKey: string;
+    }, {
+        nonce: string;
+        contents: string;
+        fromPublicKey: string;
+    }>>;
+    /** Inviter's epoch at issue time. */
+    epoch: z.ZodNumber;
+    /** For `in` rows spawned by one of my reusable `out` tokens. */
+    parentInviteId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    deliveryState: z.ZodOptional<z.ZodEnum<["queued", "sent"]>>;
+    /** Outbound recipient for `direct` invites and replies that are still queued. */
+    recipientUserId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    createdAt: z.ZodDefault<z.ZodDate>;
+    expiresAt: z.ZodDate;
+    resolvedAt: z.ZodOptional<z.ZodDate>;
+    note: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "group" | "contact";
+    direction: "in" | "out";
+    status: "pending" | "expired" | "accepted" | "declined" | "revoked";
+    expiresAt: Date;
+    createdAt: Date;
+    mode: "direct" | "open" | "approve" | "contact" | "profile";
+    epoch: number;
+    inviteId: string;
+    role?: GroupMemberRole | undefined;
+    nonce?: string | undefined;
+    groupId?: string | undefined;
+    counterpart?: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    } | undefined;
+    counterpartDeviceId?: string | undefined;
+    groupName?: string | undefined;
+    token?: {
+        type: "group" | "contact";
+        nonce: string;
+        signature: string;
+        expiresAt: string;
+        v: 1;
+        inviter: {
+            publicKey: string;
+            publicBoxKey: string;
+            userId: string;
+            displayName?: string | undefined;
+        };
+        epoch: number;
+        uses: 1 | "unlimited";
+        group?: {
+            name: string;
+            role: GroupMemberRole;
+            publicKey: string;
+            groupId: string;
+            publicBoxKey: string;
+            mode: "open" | "approve";
+        } | undefined;
+    } | undefined;
+    payload?: {
+        nonce: string;
+        contents: string;
+        fromPublicKey: string;
+    } | undefined;
+    parentInviteId?: string | undefined;
+    deliveryState?: "queued" | "sent" | undefined;
+    recipientUserId?: string | undefined;
+    resolvedAt?: Date | undefined;
+    note?: string | undefined;
+}, {
+    type: "group" | "contact";
+    direction: "in" | "out";
+    expiresAt: Date;
+    mode: "direct" | "open" | "approve" | "contact" | "profile";
+    epoch: number;
+    inviteId: string;
+    role?: GroupMemberRole | undefined;
+    nonce?: string | undefined;
+    status?: "pending" | "expired" | "accepted" | "declined" | "revoked" | undefined;
+    groupId?: string | undefined;
+    createdAt?: Date | undefined;
+    counterpart?: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    } | undefined;
+    counterpartDeviceId?: string | undefined;
+    groupName?: string | undefined;
+    token?: {
+        type: "group" | "contact";
+        nonce: string;
+        signature: string;
+        expiresAt: string;
+        v: 1;
+        inviter: {
+            publicKey: string;
+            publicBoxKey: string;
+            userId: string;
+            displayName?: string | undefined;
+        };
+        epoch: number;
+        uses: 1 | "unlimited";
+        group?: {
+            name: string;
+            role: GroupMemberRole;
+            publicKey: string;
+            groupId: string;
+            publicBoxKey: string;
+            mode: "open" | "approve";
+        } | undefined;
+    } | undefined;
+    payload?: {
+        nonce: string;
+        contents: string;
+        fromPublicKey: string;
+    } | undefined;
+    parentInviteId?: string | undefined;
+    deliveryState?: "queued" | "sent" | undefined;
+    recipientUserId?: string | undefined;
+    resolvedAt?: Date | undefined;
+    note?: string | undefined;
+}>;
+/** One pending or historical invite. */
+export type IInvite = z.infer<typeof inviteSchema>;
+/**
+ * Accessor for the personal-context {@link Invites} table.
+ *
+ * @param dataContext - Optional data context; defaults to the current singleton.
+ */
+export declare function Invites(dataContext?: DataContext): import("..").Table<{
+    type: "group" | "contact";
+    direction: "in" | "out";
+    status: "pending" | "expired" | "accepted" | "declined" | "revoked";
+    expiresAt: Date;
+    createdAt: Date;
+    mode: "direct" | "open" | "approve" | "contact" | "profile";
+    epoch: number;
+    inviteId: string;
+    role?: GroupMemberRole | undefined;
+    nonce?: string | undefined;
+    groupId?: string | undefined;
+    counterpart?: {
+        publicKey: string;
+        publicBoxKey: string;
+        userId: string;
+        displayName?: string | undefined;
+    } | undefined;
+    counterpartDeviceId?: string | undefined;
+    groupName?: string | undefined;
+    token?: {
+        type: "group" | "contact";
+        nonce: string;
+        signature: string;
+        expiresAt: string;
+        v: 1;
+        inviter: {
+            publicKey: string;
+            publicBoxKey: string;
+            userId: string;
+            displayName?: string | undefined;
+        };
+        epoch: number;
+        uses: 1 | "unlimited";
+        group?: {
+            name: string;
+            role: GroupMemberRole;
+            publicKey: string;
+            groupId: string;
+            publicBoxKey: string;
+            mode: "open" | "approve";
+        } | undefined;
+    } | undefined;
+    payload?: {
+        nonce: string;
+        contents: string;
+        fromPublicKey: string;
+    } | undefined;
+    parentInviteId?: string | undefined;
+    deliveryState?: "queued" | "sent" | undefined;
+    recipientUserId?: string | undefined;
+    resolvedAt?: Date | undefined;
+    note?: string | undefined;
+}>;
+/** Age after which terminal rows are purged. */
+export declare const INVITE_HISTORY_RETENTION_MS: number;

package/dist/data/invites.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INVITE_HISTORY_RETENTION_MS = exports.inviteSchema = exports.inviteDeliveryStateSchema = exports.inviteModeSchema = exports.inviteStatusSchema = void 0;
+exports.Invites = Invites;
+const zod_1 = require("zod");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const data_box_schema_1 = require("../invites/data-box-schema");
+const invite_token_1 = require("../invites/invite-token");
+const zod_types_1 = require("../types/zod-types");
+const group_member_roles_1 = require("./group-member-roles");
+const table_definitions_system_1 = require("./orm/table-definitions.system");
+const types_1 = require("./orm/types");
+/** Lifecycle of an invite row. */
+exports.inviteStatusSchema = zod_1.z.enum(["pending", "accepted", "declined", "expired", "revoked"]);
+/**
+ * How the invite was issued:
+ * - `direct`: a known contact was invited to a group (3a); the payload is the approval.
+ * - `approve`: group link whose join requests the inviter approves (3b).
+ * - `open`: group link any Admin+ member auto-approves (3c).
+ * - `profile`: the reusable contact QR on the Account screen.
+ * - `contact`: a one-off contact token.
+ */
+exports.inviteModeSchema = zod_1.z.enum(["direct", "approve", "open", "profile", "contact"]);
+/** Outbound delivery progress; `queued` rows are retried when connectivity changes. */
+exports.inviteDeliveryStateSchema = zod_1.z.enum(["queued", "sent"]);
+/**
+ * One pending or historical invite, synced across the user's devices.
+ *
+ * Boxed payloads are encrypted to the user's box key, which every one of their devices
+ * holds, so storing them in this personal-context table is safe. Rows move to a terminal
+ * status rather than being deleted; terminal rows older than 30 days are purged.
+ */
+exports.inviteSchema = zod_1.z.object({
+    inviteId: zod_types_1.zodPeerId,
+    direction: zod_1.z.enum(["in", "out"]).describe("Whether I issued (out) or received (in) this item"),
+    type: zod_1.z.enum(["contact", "group"]),
+    status: exports.inviteStatusSchema.default("pending"),
+    mode: exports.inviteModeSchema,
+    /** The other party, once known (unknown for outstanding link invites). */
+    counterpart: invite_token_1.inviteIdentitySchema.optional(),
+    /** Device the counterpart used, when they told us; lets the network layer connect early. */
+    counterpartDeviceId: zod_types_1.zodPeerId.optional(),
+    /**
+     * Correlates replies with this row: the token nonce for link invites, a fresh nonce for
+     * direct invites.
+     */
+    nonce: zod_1.z
+        .string()
+        .regex(/^[A-Za-z0-9_-]+$/)
+        .length(22)
+        .optional(),
+    groupId: zod_types_1.zodPeerId.optional(),
+    groupName: zod_1.z.string().optional(),
+    role: zod_1.z.nativeEnum(group_member_roles_1.GroupMemberRole).optional().describe("Granted role for group invites"),
+    /** The signed token: what I issued (out) or what I received/used (in). */
+    token: invite_token_1.peersInviteSchema.optional(),
+    /**
+     * For `in` direct invites: the GroupApproval boxed to my own user box key. For rows whose
+     * `deliveryState` is `queued`: the outbound box (already sealed to `recipientUserId`).
+     */
+    payload: data_box_schema_1.dataBoxSchema.optional(),
+    /** Inviter's epoch at issue time. */
+    epoch: zod_1.z.number().int().min(0),
+    /** For `in` rows spawned by one of my reusable `out` tokens. */
+    parentInviteId: zod_types_1.zodPeerId.optional(),
+    deliveryState: exports.inviteDeliveryStateSchema.optional(),
+    /** Outbound recipient for `direct` invites and replies that are still queued. */
+    recipientUserId: zod_types_1.zodPeerId.optional(),
+    createdAt: zod_1.z.date().default(() => new Date()),
+    expiresAt: zod_1.z.date(),
+    resolvedAt: zod_1.z.date().optional(),
+    note: zod_1.z.string().max(500).optional().describe("Sanitized status text for the UI"),
+});
+const metaData = {
+    name: "Invites",
+    description: "Pending and historical contact and group invites, synced across my devices.",
+    primaryKeyName: "inviteId",
+    fields: (0, types_1.schemaToFields)(exports.inviteSchema),
+    iconClassName: "bi bi-envelope-paper",
+    indexes: [
+        { fields: ["status"] },
+        { fields: ["direction"] },
+        { fields: ["groupId"] },
+        { fields: ["parentInviteId"] },
+        { fields: ["nonce"] },
+        { fields: ["deliveryState"] },
+    ],
+};
+(0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.inviteSchema);
+/**
+ * Accessor for the personal-context {@link Invites} table.
+ *
+ * @param dataContext - Optional data context; defaults to the current singleton.
+ */
+function Invites(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.inviteSchema);
+}
+/** Age after which terminal rows are purged. */
+exports.INVITE_HISTORY_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;

package/dist/data/users.js

@@ -93,6 +93,10 @@ let UsersTable = (() => {
             }
             // Get the old user record if it exists
             const oldUser = await this.get(user.userId);
+            if (opts.weakInsert && oldUser?.signature && !user.signature) {
+                // A weak (placeholder) write must never clobber a signed record; keep what we have.
+                return oldUser;
+            }
             await (0, user_permissions_1.verifyUserSignature)(user, oldUser);
             return super.save(user, opts);
         }

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;