@peers-app/peers-sdk 0.20.5 → 0.21.0

package/dist/device-pairing/types.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devicePairingStateSchema = exports.devicePairingPhaseSchema = exports.signedPairingInstallationReceiptSchema = exports.pairingInstallationReceiptContentsSchema = exports.pairingCredentialEnvelopeSchema = exports.pairingCredentialContentsSchema = exports.signedPairingApprovalSchema = exports.pairingApprovalContentsSchema = exports.pairingDescriptionSchema = exports.pairingDevicePresentationSchema = exports.devicePairingTranscriptSchema = exports.devicePairingIceServersAckSchema = exports.devicePairingRoomReadyAckSchema = exports.devicePairingSignalingAckSchema = exports.devicePairingSignalingErrorCodeSchema = exports.devicePairingDeleteRoomRequestSchema = exports.devicePairingJoinRoomRequestSchema = exports.devicePairingCreateRoomRequestSchema = exports.pairingSignalSchema = exports.unsignedPairingSignalSchema = exports.pairingIceServerSchema = exports.pairingIceCandidateSchema = exports.pairingSessionDescriptionSchema = exports.devicePairingInvitationSchema = exports.pairingRoleSchema = exports.pairingEndpointNonceSchema = exports.pairingHashSchema = exports.pairingRoomSecretSchema = exports.pairingRoomIdSchema = void 0;
+const zod_1 = require("zod");
+const devices_1 = require("../data/devices");
+const zod_types_1 = require("../types/zod-types");
+const constants_1 = require("./constants");
+const base64UrlSchema = zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/);
+/** A random 128-bit pairing-room identifier encoded as unpadded base64url. */
+exports.pairingRoomIdSchema = base64UrlSchema.length(22);
+/** A random 256-bit pairing-room secret encoded as unpadded base64url. */
+exports.pairingRoomSecretSchema = base64UrlSchema.length(43);
+/** A SHA-256 value encoded as unpadded base64url. */
+exports.pairingHashSchema = base64UrlSchema.length(43);
+/** A random 256-bit endpoint nonce encoded as unpadded base64url. */
+exports.pairingEndpointNonceSchema = base64UrlSchema.length(43);
+/** Source and destination roles in a two-party pairing room. */
+exports.pairingRoleSchema = zod_1.z.enum(["source", "destination"]);
+/** Versioned invitation shared out-of-band from the signed-in source. */
+exports.devicePairingInvitationSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    roomSecret: exports.pairingRoomSecretSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+    serviceOrigin: zod_1.z
+        .string()
+        .url()
+        .max(2048)
+        .refine((value) => {
+        const url = new URL(value);
+        return (url.protocol === "https:" || url.protocol === "http:") && url.origin === value;
+    }, "Expected an HTTP(S) origin without a path"),
+})
+    .strict();
+/** WebRTC session description carried inside an authenticated signaling message. */
+exports.pairingSessionDescriptionSchema = zod_1.z
+    .object({
+    type: zod_1.z.enum(["offer", "answer"]),
+    sdp: zod_1.z
+        .string()
+        .min(1)
+        .max(64 * 1024),
+    endpointNonce: exports.pairingEndpointNonceSchema,
+})
+    .strict();
+/** ICE candidate carried inside an authenticated signaling message. */
+exports.pairingIceCandidateSchema = zod_1.z
+    .object({
+    candidate: zod_1.z.string().min(1).max(4096),
+    sdpMid: zod_1.z.string().max(256).nullable().optional(),
+    sdpMLineIndex: zod_1.z.number().int().min(0).max(65535).nullable().optional(),
+    usernameFragment: zod_1.z.string().max(256).nullable().optional(),
+})
+    .strict();
+const iceUrlSchema = zod_1.z
+    .string()
+    .min(1)
+    .max(2048)
+    .refine((value) => value.startsWith("stun:") || value.startsWith("turn:") || value.startsWith("turns:"), "Expected a STUN or TURN URL");
+/** Validated ICE server configuration issued to a pairing-room member. */
+exports.pairingIceServerSchema = zod_1.z
+    .object({
+    urls: zod_1.z.union([iceUrlSchema, zod_1.z.array(iceUrlSchema).min(1).max(16)]),
+    username: zod_1.z.string().min(1).max(256).optional(),
+    credential: zod_1.z.string().min(1).max(512).optional(),
+})
+    .strict()
+    .refine((value) => (value.username === undefined && value.credential === undefined) ||
+    (value.username !== undefined && value.credential !== undefined), "TURN username and credential must be supplied together");
+const pairingSignalBase = {
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    senderRole: exports.pairingRoleSchema,
+    sequence: zod_1.z.number().int().positive(),
+};
+/** Unsigned offer, answer, or ICE message before its signaling MAC is attached. */
+exports.unsignedPairingSignalSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("offer"),
+        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("offer") }).strict(),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("answer"),
+        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("answer") }).strict(),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("candidate"),
+        payload: exports.pairingIceCandidateSchema,
+    })
+        .strict(),
+]);
+/** HMAC-authenticated offer, answer, or ICE signaling message. */
+exports.pairingSignalSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("offer"),
+        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("offer") }).strict(),
+        mac: exports.pairingHashSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("answer"),
+        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("answer") }).strict(),
+        mac: exports.pairingHashSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...pairingSignalBase,
+        kind: zod_1.z.literal("candidate"),
+        payload: exports.pairingIceCandidateSchema,
+        mac: exports.pairingHashSchema,
+    })
+        .strict(),
+]);
+/** Request from the source to create a bounded signaling room. */
+exports.devicePairingCreateRoomRequestSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+    roomAccessTokenHash: exports.pairingHashSchema,
+})
+    .strict();
+/** Request from the destination to occupy the second room slot. */
+exports.devicePairingJoinRoomRequestSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    roomAccessToken: exports.pairingHashSchema,
+})
+    .strict();
+/** Request from the source to tear down its signaling room. */
+exports.devicePairingDeleteRoomRequestSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    roomAccessToken: exports.pairingHashSchema,
+})
+    .strict();
+/** Public signaling-service error codes that do not echo attacker input. */
+exports.devicePairingSignalingErrorCodeSchema = zod_1.z.enum([
+    "invalid",
+    "not-found",
+    "occupied",
+    "expired",
+    "forbidden",
+    "rate-limited",
+    "too-large",
+    "out-of-order",
+]);
+const devicePairingSignalingFailureSchema = zod_1.z
+    .object({
+    ok: zod_1.z.literal(false),
+    code: exports.devicePairingSignalingErrorCodeSchema,
+})
+    .strict();
+/** Acknowledgement returned by every signaling-room command. */
+exports.devicePairingSignalingAckSchema = zod_1.z.discriminatedUnion("ok", [
+    zod_1.z.object({ ok: zod_1.z.literal(true) }).strict(),
+    devicePairingSignalingFailureSchema,
+]);
+/** Acknowledgement proving room creation/join and its service-authoritative expiry. */
+exports.devicePairingRoomReadyAckSchema = zod_1.z.discriminatedUnion("ok", [
+    zod_1.z
+        .object({
+        ok: zod_1.z.literal(true),
+        expiresAt: zod_1.z.number().int().positive(),
+    })
+        .strict(),
+    devicePairingSignalingFailureSchema,
+]);
+/** Acknowledgement containing room-bound, short-lived ICE configuration. */
+exports.devicePairingIceServersAckSchema = zod_1.z.discriminatedUnion("ok", [
+    zod_1.z
+        .object({
+        ok: zod_1.z.literal(true),
+        iceServers: zod_1.z.array(exports.pairingIceServerSchema).min(1).max(8),
+    })
+        .strict(),
+    devicePairingSignalingFailureSchema,
+]);
+/** Canonical transcript input derived independently by both endpoints. */
+exports.devicePairingTranscriptSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    roomId: exports.pairingRoomIdSchema,
+    sourceIdentity: devices_1.deviceInfoSchema,
+    destinationIdentity: devices_1.deviceInfoSchema,
+    sourceEndpointNonce: exports.pairingEndpointNonceSchema,
+    destinationEndpointNonce: exports.pairingEndpointNonceSchema,
+    offerFingerprint: zod_1.z.string().min(1).max(256),
+    answerFingerprint: zod_1.z.string().min(1).max(256),
+})
+    .strict();
+/** Renderer-safe presentation of the remote endpoint. */
+exports.pairingDevicePresentationSchema = zod_1.z
+    .object({
+    deviceName: devices_1.displayNameSchema.optional(),
+    userName: devices_1.displayNameSchema.optional(),
+    deviceType: zod_1.z.string().max(64).optional(),
+})
+    .strict();
+/** Payload exchanged by `pairing.describe` after the normal Connection handshake. */
+exports.pairingDescriptionSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    transcriptHash: exports.pairingHashSchema,
+    device: devices_1.deviceInfoSchema,
+    presentation: exports.pairingDevicePresentationSchema,
+})
+    .strict();
+/** Contents of a signed, single-use user approval. */
+exports.pairingApprovalContentsSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    approvalId: exports.pairingEndpointNonceSchema,
+    transcriptHash: exports.pairingHashSchema,
+    role: exports.pairingRoleSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+})
+    .strict();
+/** Signed approval bound to one transcript and endpoint identity. */
+exports.signedPairingApprovalSchema = zod_1.z
+    .object({
+    contents: exports.pairingApprovalContentsSchema,
+    signature: base64UrlSchema.length(86),
+    publicKey: base64UrlSchema.length(43),
+})
+    .strict();
+/** Account credentials encrypted directly to the temporary destination identity. */
+exports.pairingCredentialContentsSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    transcriptHash: exports.pairingHashSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+    userId: zod_types_1.zodPeerId,
+    secretKey: base64UrlSchema.length(86),
+})
+    .strict();
+/** Signed-and-boxed credential envelope sent over the WebRTC Connection. */
+exports.pairingCredentialEnvelopeSchema = zod_1.z
+    .object({
+    contents: base64UrlSchema.min(1).max(4096),
+    nonce: base64UrlSchema.length(32),
+    fromPublicKey: base64UrlSchema.length(43),
+})
+    .strict();
+/** Contents of the temporary destination identity's signed installation receipt. */
+exports.pairingInstallationReceiptContentsSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    transcriptHash: exports.pairingHashSchema,
+    initializedDevice: devices_1.deviceInfoSchema,
+    installedAt: zod_1.z.number().int().positive(),
+})
+    .strict();
+/** Receipt proving installation on the authenticated temporary destination endpoint. */
+exports.signedPairingInstallationReceiptSchema = zod_1.z
+    .object({
+    contents: exports.pairingInstallationReceiptContentsSchema,
+    signature: base64UrlSchema.length(86),
+    publicKey: base64UrlSchema.length(43),
+})
+    .strict();
+/** Renderer-visible phases of the short-lived pairing ceremony. */
+exports.devicePairingPhaseSchema = zod_1.z.enum([
+    "idle",
+    "inviting",
+    "connecting",
+    "comparing",
+    "waiting-for-approval",
+    "transferring",
+    "complete",
+    "rejected",
+    "error",
+]);
+/** Sanitized pairing state safe to publish across the host/renderer boundary. */
+exports.devicePairingStateSchema = zod_1.z
+    .object({
+    sessionId: zod_types_1.zodPeerId.optional(),
+    role: exports.pairingRoleSchema.optional(),
+    phase: exports.devicePairingPhaseSchema,
+    expiresAt: zod_1.z.number().int().positive().optional(),
+    remoteDevice: exports.pairingDevicePresentationSchema.optional(),
+    sas: zod_1.z
+        .string()
+        .regex(/^\d{6}$/)
+        .optional(),
+    error: zod_1.z.string().max(256).optional(),
+})
+    .strict();

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from "./device/get-trust-level-fn";
 export * from "./device/socket.type";
 export * from "./device/socket-io-binary-peer";
 export * from "./device/tx-encoding";
+export * from "./device-pairing";
 export * from "./events";
 export * from "./group-invite";
 export * from "./keys";

package/dist/index.js

@@ -34,6 +34,7 @@ __exportStar(require("./device/get-trust-level-fn"), exports);
 __exportStar(require("./device/socket.type"), exports);
 __exportStar(require("./device/socket-io-binary-peer"), exports);
 __exportStar(require("./device/tx-encoding"), exports);
+__exportStar(require("./device-pairing"), exports);
 __exportStar(require("./events"), exports);
 __exportStar(require("./group-invite"), exports);
 __exportStar(require("./keys"), exports);

package/dist/rpc-types.d.ts

@@ -1,5 +1,6 @@
 import type { IDeviceDatabaseQueryResult, IDeviceOperationStatus, IDeviceToolRunInput } from "./contracts/system/device-operations-contract";
 import type { ITool } from "./data/tools";
+import type { DevicePairingCeremonyAction, DevicePairingStartDestinationInput, DevicePairingStartSourceResult, DevicePairingState } from "./device-pairing";
 import type { IConsoleLog } from "./logging/console-logs.table";
 /** Named event payload sent across the frontend RPC bridge. */
 export interface IEventData<T = any> {
@@ -63,6 +64,13 @@ export declare const rpcServerCalls: {
     seedBundledPeersCore: (dataContextId?: string) => Promise<boolean>;
     setUserIdAndSecretKey: (userId: string, secretKey: string) => Promise<void>;
     getUserId: () => Promise<string | undefined>;
+    devicePairingStartSource: () => Promise<DevicePairingStartSourceResult>;
+    devicePairingStartDestination: (input: DevicePairingStartDestinationInput) => Promise<DevicePairingState>;
+    devicePairingApprove: (input: DevicePairingCeremonyAction) => Promise<DevicePairingState>;
+    devicePairingReject: (input: DevicePairingCeremonyAction) => Promise<DevicePairingState>;
+    devicePairingCancel: (input: DevicePairingCeremonyAction) => Promise<DevicePairingState>;
+    devicePairingGetState: () => Promise<DevicePairingState>;
+    devicePairingGetInvitationUrl: () => Promise<string | undefined>;
     encryptData: (value: string, groupId?: string) => Promise<string>;
     /**
      * Decrypt (if secret) and copy a persistent variable's value to the system clipboard

package/dist/rpc-types.js

@@ -21,6 +21,13 @@ exports.rpcServerCalls = {
     seedBundledPeersCore: rpcStub("seedBundledPeersCore"),
     setUserIdAndSecretKey: rpcStub("setUserIdAndSecretKey"),
     getUserId: rpcStub("getUserId"),
+    devicePairingStartSource: rpcStub("devicePairingStartSource"),
+    devicePairingStartDestination: rpcStub("devicePairingStartDestination"),
+    devicePairingApprove: rpcStub("devicePairingApprove"),
+    devicePairingReject: rpcStub("devicePairingReject"),
+    devicePairingCancel: rpcStub("devicePairingCancel"),
+    devicePairingGetState: rpcStub("devicePairingGetState"),
+    devicePairingGetInvitationUrl: rpcStub("devicePairingGetInvitationUrl"),
     encryptData: rpcStub("encryptData"),
     /**
      * Decrypt (if secret) and copy a persistent variable's value to the system clipboard

package/dist/types/peer-device.d.ts

@@ -1,41 +1,77 @@
-import type { GroupMemberRole, IChangeRecord } from "../data";
+import type { GroupMemberRole, IChangeRecord, IDeviceInfo } from "../data";
 import type { DataFilter, IDataQueryParams } from "../data/orm";
+import type { ISignedObject } from "../keys";
+/** A remotely addressable Peers device that can exchange data and mesh messages. */
 export interface IPeerDevice {
+    /** Stable identifier for this device installation. */
     deviceId: string;
+    /** User identity that owns this device. */
     userId: string;
+    /** Role used when this device participates in a shared group. */
     role: GroupMemberRole;
+    /** Lists change records available from this device. */
     listChanges(filter?: DataFilter<IChangeRecord>, opts?: IDataQueryParams<IChangeRecord>): Promise<IChangeRecord[]>;
+    /** Returns current connectivity and resource information for this device. */
     getNetworkInfo(): Promise<INetworkInfo>;
+    /** Reports the latest change timestamp applied from another device. */
     notifyOfChanges(deviceId: string, timestampLastApplied: number): Promise<void>;
+    /** Sends a routed message to another device. */
     sendDeviceMessage(message: IDeviceMessage): Promise<any>;
 }
+/** A signed, routable message exchanged through the Peers device mesh. */
 export interface IDeviceMessage<T = any> {
+    /** Unique identifier used for deduplication and retention. */
     deviceMessageId: string;
+    /** Device that originated the message. */
     fromDeviceId: string;
+    /** Signed source identity used to bootstrap fresh same-user devices. */
+    fromDeviceInfo?: ISignedObject<IDeviceInfo>;
+    /** Intended destination device. */
     toDeviceId: string;
+    /** Personal or group data context in which the message is valid. */
     dataContextId: string;
+    /** Remaining forwarding hops. */
     ttl: number;
+    /** Signed or boxed application payload while in transit. */
     payload: T;
+    /** Device IDs through which the message has already passed. */
     hops: string[];
+    /** Optional preferred route supplied by routing intelligence. */
     suggestedPath?: string[];
 }
+/** Connectivity, synchronization, and resource snapshot reported by a device. */
 export interface INetworkInfo {
+    /** Device that produced this snapshot. */
     deviceId: string;
+    /** Latest change timestamp applied by the reporting device. */
     timestampLastApplied: number;
+    /** Current direct device connections. */
     connections: IDeviceConnection[];
+    /** Device IDs this device prefers to connect to. */
     preferredDeviceIds: string[];
+    /** Current CPU utilization percentage. */
     cpuPercent: number;
+    /** Current memory utilization percentage. */
     memPercent: number;
+    /** Number of additional direct connections available. */
     connectionSlotsAvailable: number;
 }
+/** Health and synchronization metadata for one direct device connection. */
 export interface IDeviceConnection {
+    /** Connected remote device. */
     deviceId: string;
+    /** Observed round-trip latency in milliseconds. */
     latencyMs: number;
+    /** Observed request error rate. */
     errorRate: number;
+    /** Latest change timestamp applied by the remote device. */
     timestampLastApplied: number;
+    /** Optional cleanup callback for closing the connection. */
     onClose?(): Promise<void>;
+    /** Whether the connection has already closed. */
     closed?: boolean;
 }
+/** Shared tuning constants for device synchronization and routing. */
 export declare const PeerDeviceConsts: Readonly<{
     readonly MAX_CONNECTIONS: 30;
     readonly RESYNC_INTERVAL: 300000;
@@ -46,6 +82,7 @@ export declare const PeerDeviceConsts: Readonly<{
     readonly TIMEOUT_MAX: 30000;
     readonly NETWORK_INFO_CACHE_TIME: 1000;
 }>;
+/** Availability and queue information for a requested file chunk. */
 export type IFileChunkInfo = {
     hasChunk: false;
 } | {

package/dist/types/peer-device.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PeerDeviceConsts = void 0;
+/** Shared tuning constants for device synchronization and routing. */
 exports.PeerDeviceConsts = Object.freeze({
     // TODO set this based on device type (desktops and servers should be able to handle 100 connections)
     MAX_CONNECTIONS: 30,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.20.5",
+  "version": "0.21.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"