@peers-app/peers-sdk 0.30.6 → 0.31.1

package/dist/contracts/system/mesh-metrics-types.d.ts

@@ -2,8 +2,11 @@
 export type MeshEpisodeReason = "startup" | "resume" | "network-change" | "connection-loss";
 /** Provenance of a dial; explicit requests and group joins are also distinguished. */
 export type MeshDialReason = "own-device" | "group-network-info" | "broadcast-answer" | "configured-server" | "lan-scan" | "websocket-upgrade" | "incoming" | "direct-request" | "group-join";
-/** Bounded path categories used for lifetime counters; attempts also retain the address. */
-export type MeshPath = "websocket" | "webrtc" | "cloud" | "discovery";
+/**
+ * Bounded path categories used for lifetime counters; attempts also retain the address.
+ * `webtransport` is the PWA's direct LAN session to a desktop (absent from older devices' stats).
+ */
+export type MeshPath = "websocket" | "webrtc" | "webtransport" | "cloud" | "discovery";
 /** Failure categories, independent of free-form transport error messages. */
 export type MeshFailureReason = "ttl0" | "no-route" | "signaling-timeout" | "socket-error" | "socket-timeout" | "handshake" | "rejected" | "closed" | "superseded" | "unsupported" | "sender-not-known"
 /** This device can't encrypt to the target yet: no owner-signed row or profile for it here. */
@@ -137,7 +140,10 @@ export interface IMeshStats {
     recentEpisodes: IMeshEpisode[];
     percentiles: Record<keyof IMeshDurations, IMeshPercentiles>;
     counters: {
-        paths: Record<MeshPath, IMeshPathCounters>;
+        /** By path; `webtransport` is missing from devices older than that path. */
+        paths: Record<Exclude<MeshPath, "webtransport">, IMeshPathCounters> & {
+            webtransport?: IMeshPathCounters;
+        };
         lanScan: {
             scans: number;
             probes: number;

package/dist/device/binary-peer-connection-v2.d.ts

@@ -59,8 +59,8 @@ export interface BinaryPeerReceiveLimits {
 export declare const DEFAULT_BINARY_PEER_RECEIVE_LIMITS: Readonly<BinaryPeerReceiveLimits>;
 /** Options for wrapping a binary transport in a verified Peers connection. */
 export interface WrapBinaryPeerOptions {
-    /** Protocol identifier used for server address (e.g., 'wrtc' or 'ws') */
-    protocol: "wrtc" | "ws";
+    /** Protocol identifier, used for the server address and the transport's frame sizes. */
+    protocol: "wrtc" | "ws" | "wt";
     /** Optional hard limits for untrusted inbound messages. */
     receiveLimits?: Partial<BinaryPeerReceiveLimits>;
 }
@@ -70,7 +70,7 @@ export interface WrapBinaryPeerOptions {
  */
 export declare function createBinaryPeerSocket(connectionId: string, peer: IBinaryPeer, protocol?: string, receiveLimitOverrides?: Partial<BinaryPeerReceiveLimits>): ISocket;
 /**
- * Wraps a binary peer (WebRTC or WebSocket) into a Connection.
+ * Wraps a binary peer (WebRTC, WebTransport or WebSocket) into a Connection.
  * This is the main implementation that handles all binary protocols.
  */
 export declare function wrapBinaryPeer(connectionId: string, peer: IBinaryPeer, localDevice: Device, initiator: boolean, options: WrapBinaryPeerOptions, getTrustLevel?: ITrustLevelFn): Connection;

package/dist/device/binary-peer-connection-v2.js

@@ -57,6 +57,14 @@ const WRTC_CONFIG = {
     lowWaterMark: 32 * 1024, // 32KB
     yieldBetweenChunks: true, // CRITICAL for Go sidecar pipeline
 };
+// WebTransport reaches Node through the same sidecar pipe as WebRTC, so it is paced the same
+// way. The sidecar caps a frame at 1 MB, well above this.
+const WT_CONFIG = {
+    maxFramePayload: 64 * 1024,
+    highWaterMark: 128 * 1024,
+    lowWaterMark: 32 * 1024,
+    yieldBetweenChunks: true,
+};
 const WS_CONFIG = {
     maxFramePayload: 512 * 1024, // 512KB
     highWaterMark: 4 * 1024 * 1024, // 4MB
@@ -67,6 +75,8 @@ function getTransportConfig(protocol) {
     switch (protocol) {
         case "wrtc":
             return WRTC_CONFIG;
+        case "wt":
+            return WT_CONFIG;
         case "ws":
             return WS_CONFIG;
         default:
@@ -252,7 +262,7 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
     const rawBytesHandlers = {};
     let isClosed = false;
     const stats = (0, socket_type_1.createSocketStats)();
-    const transportType = protocol === "wrtc" ? "wrtc" : protocol === "ws" ? "ws" : "unknown";
+    const transportType = protocol === "wrtc" || protocol === "ws" || protocol === "wt" ? protocol : "unknown";
     const config = getTransportConfig(protocol);
     const receiveLimits = {
         ...exports.DEFAULT_BINARY_PEER_RECEIVE_LIMITS,
@@ -836,7 +846,7 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
 }
 // ─── Connection Wrappers ─────────────────────────────────────────────
 /**
- * Wraps a binary peer (WebRTC or WebSocket) into a Connection.
+ * Wraps a binary peer (WebRTC, WebTransport or WebSocket) into a Connection.
  * This is the main implementation that handles all binary protocols.
  */
 function wrapBinaryPeer(connectionId, peer, localDevice, initiator, options, getTrustLevel) {

package/dist/device/socket.type.d.ts

@@ -34,8 +34,15 @@ export interface ISocketStats {
 }
 /** Creates a new stats object for tracking socket throughput */
 export declare function createSocketStats(): ISocketStats;
-/** Underlying transport family of a socket. */
-export type TransportType = "ws" | "wrtc" | "unknown";
+/**
+ * Underlying transport family of a socket.
+ *
+ * - `ws`: Socket.IO over a WebSocket (a desktop's TCP listener).
+ * - `wrtc`: a WebRTC data channel.
+ * - `wt`: a WebTransport session to a desktop's sidecar (the PWA on the LAN). Not WebRTC, so
+ *   WebRTC-only policy (upgrades, route checks) leaves it alone.
+ */
+export type TransportType = "ws" | "wrtc" | "wt" | "unknown";
 /** Minimal RPC + raw-byte transport abstraction consumed by `Connection`. */
 export interface ISocket {
     id?: string;
@@ -43,6 +50,7 @@ export interface ISocket {
     /**
      * Transport type for this socket. Used to optimize chunk sizes for raw byte streaming.
      * - 'wrtc': WebRTC (64KB max due to SCTP limits)
+     * - 'wt': WebTransport through the sidecar (sized like WebRTC's sidecar path)
      * - 'ws': WebSocket (1MB+ chunks OK)
      */
     transportType?: TransportType;

package/dist/device/webtransport-address.d.ts

@@ -0,0 +1,62 @@
+/**
+ * WebTransport addresses: how a desktop tells the PWA where to reach it directly on the LAN.
+ *
+ * A desktop's sidecar serves WebTransport (HTTP/3 over QUIC) with a self-signed certificate.
+ * Browsers accept that certificate when the page passes its SHA-256 hash
+ * (`serverCertificateHashes`), so the address carries the hashes:
+ *
+ * ```text
+ * https://192.168.4.31:3333/peers#sha256=<current>,<next>
+ * ```
+ *
+ * The address goes in the device's owner-signed `reachability.addresses`, beside its WebSocket
+ * origins, so the hashes are covered by the same signature and older devices verify it unchanged.
+ * The `#sha256=` fragment is what marks an address as WebTransport: WebSocket dialers skip it and
+ * WebTransport dialers take nothing else. The server publishes the current week's hash and the
+ * next one's, so a phone holding last week's row still matches after the desktop rolls over.
+ *
+ * To dial, the client picks a connection id and opens {@link webTransportSessionUrl}; both ends
+ * then name the connection `wt:<id>` ({@link webTransportConnectionId}), because the Peers
+ * handshake binds the connection id into its frame keys.
+ */
+/** The path a desktop's WebTransport server accepts sessions on. */
+export declare const WEBTRANSPORT_PATH = "/peers";
+/** Every WebTransport connection id starts with this, on both ends. */
+export declare const WEBTRANSPORT_CONNECTION_PREFIX = "wt:";
+/** The most certificate hashes one address carries (the server publishes two). */
+export declare const MAX_WEBTRANSPORT_CERTIFICATE_HASHES = 4;
+/** A parsed WebTransport address. */
+export interface WebTransportAddress {
+    /** The session URL without the client's connection id: `https://<host>:<port>/peers`. */
+    url: string;
+    /** SHA-256 of each certificate the server may present, as unpadded base64url (43 characters). */
+    certificateHashes: string[];
+}
+/**
+ * Formats the address a desktop publishes for one of its LAN addresses.
+ *
+ * @param host An IPv4 address, an IPv6 address (bracketed for you), or a hostname.
+ * @param port The server's UDP port.
+ * @param certificateHashes The hashes to pin, current window first.
+ * @throws When the port or a hash is malformed, or there are no hashes or too many.
+ */
+export declare function formatWebTransportAddress(host: string, port: number, certificateHashes: readonly string[]): string;
+/** True when an address carries WebTransport certificate hashes (whether or not it's valid). */
+export declare function isWebTransportAddress(address: string): boolean;
+/**
+ * Parses a WebTransport address, or returns `undefined` for anything else, including a
+ * malformed one: an `https:` URL on {@link WEBTRANSPORT_PATH} with an explicit port, no
+ * credentials or query, and one to {@link MAX_WEBTRANSPORT_CERTIFICATE_HASHES} well-formed hashes.
+ */
+export declare function parseWebTransportAddress(address: string): WebTransportAddress | undefined;
+/**
+ * The URL a client opens for one session: the address's URL with the client's connection id.
+ *
+ * @param clientId 16 to 64 letters and digits, such as a `newid()`.
+ * @throws When the id doesn't fit that shape (the server would refuse it).
+ */
+export declare function webTransportSessionUrl(address: WebTransportAddress, clientId: string): string;
+/** The connection id both ends give a session the client opened with `clientId`. */
+export declare function webTransportConnectionId(clientId: string): string;
+/** Decodes one certificate hash to the 32 bytes `serverCertificateHashes` wants. */
+export declare function decodeWebTransportCertificateHash(hash: string): Uint8Array;

package/dist/device/webtransport-address.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * WebTransport addresses: how a desktop tells the PWA where to reach it directly on the LAN.
+ *
+ * A desktop's sidecar serves WebTransport (HTTP/3 over QUIC) with a self-signed certificate.
+ * Browsers accept that certificate when the page passes its SHA-256 hash
+ * (`serverCertificateHashes`), so the address carries the hashes:
+ *
+ * ```text
+ * https://192.168.4.31:3333/peers#sha256=<current>,<next>
+ * ```
+ *
+ * The address goes in the device's owner-signed `reachability.addresses`, beside its WebSocket
+ * origins, so the hashes are covered by the same signature and older devices verify it unchanged.
+ * The `#sha256=` fragment is what marks an address as WebTransport: WebSocket dialers skip it and
+ * WebTransport dialers take nothing else. The server publishes the current week's hash and the
+ * next one's, so a phone holding last week's row still matches after the desktop rolls over.
+ *
+ * To dial, the client picks a connection id and opens {@link webTransportSessionUrl}; both ends
+ * then name the connection `wt:<id>` ({@link webTransportConnectionId}), because the Peers
+ * handshake binds the connection id into its frame keys.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_WEBTRANSPORT_CERTIFICATE_HASHES = exports.WEBTRANSPORT_CONNECTION_PREFIX = exports.WEBTRANSPORT_PATH = void 0;
+exports.formatWebTransportAddress = formatWebTransportAddress;
+exports.isWebTransportAddress = isWebTransportAddress;
+exports.parseWebTransportAddress = parseWebTransportAddress;
+exports.webTransportSessionUrl = webTransportSessionUrl;
+exports.webTransportConnectionId = webTransportConnectionId;
+exports.decodeWebTransportCertificateHash = decodeWebTransportCertificateHash;
+const keys_1 = require("../keys");
+/** The path a desktop's WebTransport server accepts sessions on. */
+exports.WEBTRANSPORT_PATH = "/peers";
+/** Every WebTransport connection id starts with this, on both ends. */
+exports.WEBTRANSPORT_CONNECTION_PREFIX = "wt:";
+/** The most certificate hashes one address carries (the server publishes two). */
+exports.MAX_WEBTRANSPORT_CERTIFICATE_HASHES = 4;
+const HASH_FRAGMENT = "sha256=";
+const HASH_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const CLIENT_ID_PATTERN = /^[A-Za-z0-9]{16,64}$/;
+/**
+ * Formats the address a desktop publishes for one of its LAN addresses.
+ *
+ * @param host An IPv4 address, an IPv6 address (bracketed for you), or a hostname.
+ * @param port The server's UDP port.
+ * @param certificateHashes The hashes to pin, current window first.
+ * @throws When the port or a hash is malformed, or there are no hashes or too many.
+ */
+function formatWebTransportAddress(host, port, certificateHashes) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid WebTransport port ${port}`);
+    }
+    if (certificateHashes.length === 0 ||
+        certificateHashes.length > exports.MAX_WEBTRANSPORT_CERTIFICATE_HASHES ||
+        !certificateHashes.every((hash) => HASH_PATTERN.test(hash))) {
+        throw new Error("Invalid WebTransport certificate hashes");
+    }
+    const hostPart = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+    return `https://${hostPart}:${port}${exports.WEBTRANSPORT_PATH}#${HASH_FRAGMENT}${certificateHashes.join(",")}`;
+}
+/** True when an address carries WebTransport certificate hashes (whether or not it's valid). */
+function isWebTransportAddress(address) {
+    return address.includes(`#${HASH_FRAGMENT}`);
+}
+/**
+ * Parses a WebTransport address, or returns `undefined` for anything else, including a
+ * malformed one: an `https:` URL on {@link WEBTRANSPORT_PATH} with an explicit port, no
+ * credentials or query, and one to {@link MAX_WEBTRANSPORT_CERTIFICATE_HASHES} well-formed hashes.
+ */
+function parseWebTransportAddress(address) {
+    if (!isWebTransportAddress(address))
+        return undefined;
+    let url;
+    try {
+        url = new URL(address);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== "https:" ||
+        url.pathname !== exports.WEBTRANSPORT_PATH ||
+        // URL normalizes an explicit :443 away. It is still a valid configured UDP port.
+        (!url.port && !/^https:\/\/[^/?#]+:443\//i.test(address)) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        !url.hash.startsWith(`#${HASH_FRAGMENT}`)) {
+        return undefined;
+    }
+    const certificateHashes = url.hash.slice(1 + HASH_FRAGMENT.length).split(",");
+    if (certificateHashes.length > exports.MAX_WEBTRANSPORT_CERTIFICATE_HASHES ||
+        !certificateHashes.every((hash) => HASH_PATTERN.test(hash))) {
+        return undefined;
+    }
+    return { url: `https://${url.host}${exports.WEBTRANSPORT_PATH}`, certificateHashes };
+}
+/**
+ * The URL a client opens for one session: the address's URL with the client's connection id.
+ *
+ * @param clientId 16 to 64 letters and digits, such as a `newid()`.
+ * @throws When the id doesn't fit that shape (the server would refuse it).
+ */
+function webTransportSessionUrl(address, clientId) {
+    if (!CLIENT_ID_PATTERN.test(clientId)) {
+        throw new Error("Invalid WebTransport client id");
+    }
+    return `${address.url}?c=${clientId}`;
+}
+/** The connection id both ends give a session the client opened with `clientId`. */
+function webTransportConnectionId(clientId) {
+    return `${exports.WEBTRANSPORT_CONNECTION_PREFIX}${clientId}`;
+}
+/** Decodes one certificate hash to the 32 bytes `serverCertificateHashes` wants. */
+function decodeWebTransportCertificateHash(hash) {
+    if (!HASH_PATTERN.test(hash)) {
+        throw new Error("Invalid WebTransport certificate hash");
+    }
+    const base64 = `${hash.replace(/-/g, "+").replace(/_/g, "/")}=`;
+    return (0, keys_1.decodeBase64)(base64);
+}

package/dist/index.d.ts

@@ -19,6 +19,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/webtransport-address";
 export * from "./device-pairing";
 export * from "./events";
 export * from "./hlc";

package/dist/index.js

@@ -42,6 +42,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/webtransport-address"), exports);
 __exportStar(require("./device-pairing"), exports);
 __exportStar(require("./events"), exports);
 __exportStar(require("./hlc"), exports);

package/package.json

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