@peers-app/peers-sdk 0.8.0 → 0.8.2

package/dist/data/files/file-read-stream.d.ts

@@ -4,6 +4,7 @@ export declare class FileReadStream {
     private fileRecord;
     private fileTable;
     private preloadChunksCount;
+    private skipVerification;
     private chunkHashes;
     private currentChunkIndex;
     private currentChunkBuffer;
@@ -11,7 +12,7 @@ export declare class FileReadStream {
     private positionInChunk;
     private totalPosition;
     private eof;
-    constructor(fileRecord: IFile, fileTable: FilesTable, preloadChunksCount?: number);
+    constructor(fileRecord: IFile, fileTable: FilesTable, preloadChunksCount?: number, skipVerification?: boolean);
     private loadChunkHashes;
     private loadChunkByIndex;
     private preloadChunks;

package/dist/data/files/file-read-stream.js

@@ -7,6 +7,7 @@ class FileReadStream {
     fileRecord;
     fileTable;
     preloadChunksCount;
+    skipVerification;
     chunkHashes = null;
     currentChunkIndex = 0;
     currentChunkBuffer = null;
@@ -14,10 +15,11 @@ class FileReadStream {
     positionInChunk = 0;
     totalPosition = 0;
     eof = false;
-    constructor(fileRecord, fileTable, preloadChunksCount = 2) {
+    constructor(fileRecord, fileTable, preloadChunksCount = 2, skipVerification = false) {
         this.fileRecord = fileRecord;
         this.fileTable = fileTable;
         this.preloadChunksCount = preloadChunksCount;
+        this.skipVerification = skipVerification;
     }
     async loadChunkHashes() {
         if (this.chunkHashes !== null) {
@@ -55,10 +57,12 @@ class FileReadStream {
                 throw new Error(`Chunk ${chunkHash} not found in storage or peers`);
             }
         }
-        // Verify chunk integrity
-        const actualChunkHash = (0, keys_1.hashBytes)(chunk);
-        if (actualChunkHash !== chunkHash) {
-            throw new Error(`Chunk integrity check failed: expected ${chunkHash}, got ${actualChunkHash}`);
+        // Verify chunk integrity (skip for trusted local reads)
+        if (!this.skipVerification) {
+            const actualChunkHash = (0, keys_1.hashBytes)(chunk);
+            if (actualChunkHash !== chunkHash) {
+                throw new Error(`Chunk integrity check failed: expected ${chunkHash}, got ${actualChunkHash}`);
+            }
         }
         return chunk;
     }

package/dist/data/files/files.d.ts

@@ -20,9 +20,11 @@ export declare class FilesTable extends Table<IFile> {
      * @returns The inserted file record
      */
     saveFileRecord(fileRecord: IFile): Promise<IFile>;
-    openReadStream(fileId: string, preloadChunksCount?: number): Promise<FileReadStream | null>;
+    openReadStream(fileId: string, preloadChunksCount?: number, skipVerification?: boolean): Promise<FileReadStream | null>;
     saveFile(metaData: IFileInput, data: Uint8Array | string): Promise<IFile>;
-    getFileContents(fileId: string): Promise<Uint8Array | null>;
+    getFileContents(fileId: string, opts?: {
+        skipVerification?: boolean;
+    }): Promise<Uint8Array | null>;
     deleteFile(fileId: string): Promise<void>;
     createIndexFileRecursively(chunkHashes: string[]): Promise<string>;
     loadChunkHashesRecursively(indexFileId: string): Promise<string[]>;

package/dist/data/files/files.js

@@ -39,12 +39,12 @@ class FilesTable extends orm_1.Table {
     async saveFileRecord(fileRecord) {
         return await super.save(fileRecord);
     }
-    async openReadStream(fileId, preloadChunksCount) {
+    async openReadStream(fileId, preloadChunksCount, skipVerification) {
         const fileRecord = await this.get(fileId);
         if (!fileRecord) {
             return null;
         }
-        return new file_read_stream_1.FileReadStream(fileRecord, this, preloadChunksCount);
+        return new file_read_stream_1.FileReadStream(fileRecord, this, preloadChunksCount, skipVerification);
     }
     async saveFile(metaData, data) {
         // Use FileWriteStream internally to ensure consistent chunking logic
@@ -60,9 +60,9 @@ class FilesTable extends orm_1.Table {
         // Finalize and return the result
         return await writeStream.finalize();
     }
-    async getFileContents(fileId) {
+    async getFileContents(fileId, opts) {
         // Use FileReadStream internally to ensure consistent chunk reading logic
-        const readStream = await this.openReadStream(fileId);
+        const readStream = await this.openReadStream(fileId, undefined, opts?.skipVerification);
         if (!readStream) {
             return null;
         }

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

@@ -0,0 +1,54 @@
+import { Connection } from "./connection";
+import { Device } from "./device";
+import { ISocket } from "./socket.type";
+type ITrustLevelFn = Connection['getTrustLevel'];
+/**
+ * Generic binary peer interface supporting both WebRTC and libp2p transports.
+ * Provides a unified abstraction for binary data channel communication.
+ */
+export interface IBinaryPeer {
+    on(event: 'data', handler: (data: Buffer | Uint8Array) => void): void;
+    on(event: 'close', handler: () => void): void;
+    on(event: 'drain', handler: () => void): void;
+    send(data: string | Uint8Array | Buffer): void;
+    destroy(): void;
+    /**
+     * Returns the number of bytes currently buffered waiting to be sent.
+     * Used for backpressure detection. Returns 0 if not supported.
+     */
+    getBufferedAmount?(): number;
+}
+export type IWebRTCPeer = IBinaryPeer;
+export type ILibp2pPeer = IBinaryPeer;
+export interface WrapBinaryPeerOptions {
+    /** Protocol identifier used for server address (e.g., 'wrtc', 'libp2p', or 'ws') */
+    protocol: 'wrtc' | 'libp2p' | 'ws';
+    /**
+     * Mark the transport as already secure (encrypted at transport layer).
+     * When true, sets secureLocal and secureRemote to skip application-level encryption.
+     */
+    markTransportSecure?: boolean;
+}
+/**
+ * Creates an ISocket from a binary peer without creating a full Connection.
+ * Useful when you need to pass custom localServerAddresses to the Connection.
+ */
+export declare function createBinaryPeerSocket(connectionId: string, peer: IBinaryPeer, protocol?: string): ISocket;
+/**
+ * Wraps a binary peer (WebRTC, libp2p, 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;
+/**
+ * Wraps a WebRTC peer into a Connection.
+ * Backwards-compatible wrapper around wrapBinaryPeer.
+ * WebRTC is encrypted at the transport layer (DTLS-SRTP), so we skip application-level encryption.
+ */
+export declare function wrapWrtc(connectionId: string, peer: IWebRTCPeer, localDevice: Device, initiator: boolean, getTrustLevel?: ITrustLevelFn): Connection;
+/**
+ * Wraps a libp2p peer into a Connection.
+ * Backwards-compatible wrapper around wrapBinaryPeer.
+ * libp2p is encrypted at the transport layer (noise protocol), so we skip application-level encryption.
+ */
+export declare function wrapLibp2p(connectionId: string, peer: ILibp2pPeer, localDevice: Device, initiator: boolean, getTrustLevel?: ITrustLevelFn): Connection;
+export {};

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

@@ -0,0 +1,350 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBinaryPeerSocket = createBinaryPeerSocket;
+exports.wrapBinaryPeer = wrapBinaryPeer;
+exports.wrapWrtc = wrapWrtc;
+exports.wrapLibp2p = wrapLibp2p;
+const msgpack_1 = require("@msgpack/msgpack");
+const connection_1 = require("./connection");
+const get_trust_level_fn_1 = require("./get-trust-level-fn");
+const streamed_socket_1 = require("./streamed-socket");
+const utils_1 = require("../utils");
+const tx_encoding_1 = require("./tx-encoding");
+// Protocol discriminator bytes for multiplexing RPC and raw byte streams
+const PROTOCOL_RPC = 0x00;
+const PROTOCOL_RAW_BYTES = 0x01;
+// Threshold for routing large RPC messages through raw bytes streaming
+// Messages larger than this will be automatically chunked with backpressure handling
+const LARGE_MESSAGE_THRESHOLD = 64 * 1024; // 64KB
+// Reserved stream ID for RPC messages sent via raw bytes
+const RPC_STREAM_ID = '__rpc';
+// Encode message metadata + data into a single Uint8Array
+function encodeMessage(message) {
+    // Check if args/result is a Uint8Array - if so, flag it to keep it as raw bytes
+    let isUint8ArrayData = false;
+    if (message.type === 'call' && message.args instanceof Uint8Array) {
+        isUint8ArrayData = true;
+    }
+    else if (message.type === 'callback' && message.result instanceof Uint8Array) {
+        isUint8ArrayData = true;
+    }
+    // Encode metadata using msgpack (without args/result/error - those go in data)
+    const metadata = {
+        type: message.type,
+        callbackId: message.callbackId,
+        ...(message.eventName !== undefined && { eventName: message.eventName }),
+        ...(isUint8ArrayData && { isUint8ArrayData: true }),
+    };
+    const metadataBytes = (0, msgpack_1.encode)(metadata);
+    const metadataLength = metadataBytes.length;
+    // Encode the data payload (args, result, or error)
+    let dataBytes;
+    if (message.type === 'call' && message.args !== undefined) {
+        // If args is already a Uint8Array, use it directly without txEncode
+        if (isUint8ArrayData) {
+            dataBytes = message.args;
+        }
+        else {
+            dataBytes = (0, tx_encoding_1.txEncode)(message.args);
+        }
+    }
+    else if (message.type === 'callback') {
+        if (message.error !== undefined) {
+            dataBytes = (0, tx_encoding_1.txEncode)({ error: message.error });
+        }
+        else if (isUint8ArrayData) {
+            // If result is a Uint8Array, use it directly
+            dataBytes = message.result;
+        }
+        else {
+            dataBytes = (0, tx_encoding_1.txEncode)({ result: message.result });
+        }
+    }
+    else {
+        dataBytes = new Uint8Array(0);
+    }
+    // Create combined buffer: [4 bytes length][metadata][data]
+    const combined = new Uint8Array(4 + metadataLength + dataBytes.length);
+    // Write metadata length as 32-bit unsigned integer (big-endian)
+    const view = new DataView(combined.buffer, combined.byteOffset, combined.byteLength);
+    view.setUint32(0, metadataLength, false); // big-endian
+    // Write metadata
+    combined.set(metadataBytes, 4);
+    // Write data
+    combined.set(dataBytes, 4 + metadataLength);
+    return combined;
+}
+// Decode binary message back into IMessage
+function decodeMessage(bytes) {
+    // Read metadata length
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const metadataLength = view.getUint32(0, false); // big-endian
+    // Extract metadata
+    const metadataBytes = bytes.subarray(4, 4 + metadataLength);
+    const metadata = (0, msgpack_1.decode)(metadataBytes);
+    // Extract data
+    const dataBytes = bytes.subarray(4 + metadataLength);
+    const message = {
+        type: metadata.type,
+        callbackId: metadata.callbackId,
+        eventName: metadata.eventName,
+    };
+    // Decode the data payload
+    if (dataBytes.length > 0) {
+        if (message.type === 'call') {
+            // If it was a Uint8Array, use it directly without txDecode
+            if (metadata.isUint8ArrayData) {
+                message.args = dataBytes;
+            }
+            else {
+                message.args = (0, tx_encoding_1.txDecode)(dataBytes);
+            }
+        }
+        else if (message.type === 'callback') {
+            if (metadata.isUint8ArrayData) {
+                // If it was a Uint8Array result, use it directly
+                message.result = dataBytes;
+            }
+            else {
+                const decoded = (0, tx_encoding_1.txDecode)(dataBytes);
+                if (decoded.error !== undefined) {
+                    message.error = decoded.error;
+                }
+                else {
+                    message.result = decoded.result;
+                }
+            }
+        }
+    }
+    return message;
+}
+/**
+ * Creates an ISocket from a binary peer without creating a full Connection.
+ * Useful when you need to pass custom localServerAddresses to the Connection.
+ */
+function createBinaryPeerSocket(connectionId, peer, protocol = 'binary') {
+    const handlers = {};
+    const callbacks = {};
+    const rawBytesHandlers = {};
+    let isClosed = false;
+    const stats = (0, streamed_socket_1.createSocketStats)();
+    // Map protocol string to TransportType (needed early for threshold calculations)
+    const transportType = protocol === 'wrtc' ? 'wrtc' :
+        protocol === 'libp2p' ? 'libp2p' :
+            protocol === 'ws' ? 'ws' : 'unknown';
+    // Core sendRawBytes implementation - defined early so sendRPCData can use it
+    const sendRawBytesImpl = async (streamId, data) => {
+        const streamIdBytes = new TextEncoder().encode(streamId);
+        const packet = new Uint8Array(1 + 2 + streamIdBytes.length + data.length);
+        packet[0] = PROTOCOL_RAW_BYTES;
+        const view = new DataView(packet.buffer, packet.byteOffset, packet.byteLength);
+        view.setUint16(1, streamIdBytes.length, false);
+        packet.set(streamIdBytes, 3);
+        packet.set(data, 3 + streamIdBytes.length);
+        // Use transport-specific thresholds for backpressure
+        const HIGH_WATER_MARK = transportType === 'wrtc' ? 128 * 1024 : 4 * 1024 * 1024;
+        const LOW_WATER_MARK = transportType === 'wrtc' ? 32 * 1024 : 2 * 1024 * 1024;
+        if (peer.getBufferedAmount && peer.getBufferedAmount() > HIGH_WATER_MARK) {
+            await new Promise(resolve => {
+                const checkDrain = () => {
+                    if (!peer.getBufferedAmount || peer.getBufferedAmount() < LOW_WATER_MARK) {
+                        resolve();
+                    }
+                    else {
+                        setTimeout(checkDrain, 5);
+                    }
+                };
+                peer.on('drain', resolve);
+                checkDrain();
+            });
+        }
+        stats.bytesSent += packet.length;
+        stats.messagesSent++;
+        peer.send(packet);
+    };
+    // Helper to send RPC messages - routes large messages through raw bytes streaming
+    const sendRPCData = async (encoded) => {
+        if (encoded.length > LARGE_MESSAGE_THRESHOLD) {
+            // Large message: use raw bytes streaming with backpressure
+            await sendRawBytesImpl(RPC_STREAM_ID, encoded);
+        }
+        else {
+            // Small message: send directly
+            const withProtocol = new Uint8Array(1 + encoded.length);
+            withProtocol[0] = PROTOCOL_RPC;
+            withProtocol.set(encoded, 1);
+            stats.bytesSent += withProtocol.length;
+            stats.messagesSent++;
+            peer.send(withProtocol);
+        }
+    };
+    // Handle incoming data
+    peer.on('data', async (data) => {
+        try {
+            const bytes = new Uint8Array(data);
+            stats.bytesReceived += bytes.length;
+            stats.messagesReceived++;
+            if (bytes.length === 0)
+                return;
+            const protocolType = bytes[0];
+            // Handle raw bytes stream
+            if (protocolType === PROTOCOL_RAW_BYTES) {
+                if (bytes.length < 3)
+                    return;
+                const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+                const streamIdLength = view.getUint16(1, false);
+                if (bytes.length < 3 + streamIdLength)
+                    return;
+                const streamIdBytes = bytes.subarray(3, 3 + streamIdLength);
+                const streamId = new TextDecoder().decode(streamIdBytes);
+                const payload = bytes.subarray(3 + streamIdLength);
+                // Check if this is an RPC message sent via raw bytes (for large payloads)
+                if (streamId === RPC_STREAM_ID) {
+                    handleRPCMessage(payload, handlers, callbacks, sendRPCData);
+                    return;
+                }
+                const handler = rawBytesHandlers[streamId];
+                if (handler)
+                    handler(payload);
+                return;
+            }
+            // Handle RPC messages
+            if (protocolType === PROTOCOL_RPC) {
+                const rpcBytes = bytes.subarray(1);
+                handleRPCMessage(rpcBytes, handlers, callbacks, sendRPCData);
+                return;
+            }
+            // Legacy format (no discriminator) for backwards compatibility
+            handleRPCMessage(bytes, handlers, callbacks, sendRPCData);
+        }
+        catch (err) {
+            console.error(`Error parsing ${protocol} message:`, err);
+        }
+    });
+    // Handle closure
+    peer.on('close', () => {
+        if (isClosed)
+            return;
+        isClosed = true;
+        socket.connected = false;
+    });
+    const socket = {
+        id: connectionId,
+        connected: true,
+        handlesOwnEncoding: true,
+        transportType,
+        stats,
+        emit(eventName, args, callback) {
+            const callbackId = (0, utils_1.newid)();
+            callbacks[callbackId] = callback;
+            const message = { type: 'call', eventName, args, callbackId };
+            const encoded = encodeMessage(message);
+            sendRPCData(encoded);
+        },
+        on(eventName, handler) {
+            handlers[eventName] = handler;
+        },
+        removeAllListeners(eventName) {
+            if (eventName) {
+                delete handlers[eventName];
+            }
+            else {
+                Object.keys(handlers).forEach(key => delete handlers[key]);
+            }
+        },
+        disconnect() {
+            peer.destroy();
+        },
+        sendRawBytes: sendRawBytesImpl,
+        onRawBytes(streamId, handler) {
+            rawBytesHandlers[streamId] = handler;
+        },
+        removeRawBytesHandler(streamId) {
+            delete rawBytesHandlers[streamId];
+        }
+    };
+    return socket;
+}
+// Helper to handle RPC message parsing
+// sendRPCData automatically routes large messages through raw bytes streaming
+function handleRPCMessage(bytes, handlers, callbacks, sendRPCData) {
+    const message = decodeMessage(bytes);
+    if (message.type === 'callback') {
+        const callback = callbacks[message.callbackId];
+        if (callback) {
+            delete callbacks[message.callbackId];
+            callback(message.error, message.result);
+        }
+        return;
+    }
+    if (message.type === 'call') {
+        const handler = handlers[message.eventName];
+        if (!handler) {
+            console.error(`No handler for event: ${message.eventName}`);
+            return;
+        }
+        try {
+            const callback = (err, result) => {
+                const responseMessage = {
+                    type: 'callback',
+                    callbackId: message.callbackId,
+                };
+                if (err)
+                    responseMessage.error = err;
+                else
+                    responseMessage.result = result;
+                const encoded = encodeMessage(responseMessage);
+                // Use sendRPCData which auto-routes large responses through raw bytes
+                sendRPCData(encoded);
+            };
+            handler(message.args, callback);
+        }
+        catch (error) {
+            console.error("Error in handler", { eventName: message.eventName, error });
+            const errorMessage = {
+                type: 'callback',
+                callbackId: message.callbackId,
+                error: error.message
+            };
+            const encoded = encodeMessage(errorMessage);
+            sendRPCData(encoded);
+        }
+    }
+}
+/**
+ * Wraps a binary peer (WebRTC, libp2p, or WebSocket) into a Connection.
+ * This is the main implementation that handles all binary protocols.
+ */
+function wrapBinaryPeer(connectionId, peer, localDevice, initiator, options, getTrustLevel) {
+    const { protocol, markTransportSecure } = options;
+    // Create the socket wrapper using shared implementation
+    const socket = createBinaryPeerSocket(connectionId, peer, protocol);
+    const serverAddress = `${protocol}://${connectionId}`;
+    const localServerAddresses = initiator ? undefined : [serverAddress];
+    if (process.env.NODE_ENV !== 'test') {
+        getTrustLevel ??= (0, get_trust_level_fn_1.getTrustLevelFn)(localDevice, serverAddress);
+    }
+    const connection = new connection_1.Connection(socket, localDevice, localServerAddresses, getTrustLevel);
+    // Mark transport as secure if applicable (WebRTC DTLS-SRTP, libp2p noise, wss)
+    if (markTransportSecure) {
+        connection.secureLocal = true;
+        connection.secureRemote = true;
+    }
+    return connection;
+}
+/**
+ * Wraps a WebRTC peer into a Connection.
+ * Backwards-compatible wrapper around wrapBinaryPeer.
+ * WebRTC is encrypted at the transport layer (DTLS-SRTP), so we skip application-level encryption.
+ */
+function wrapWrtc(connectionId, peer, localDevice, initiator, getTrustLevel) {
+    return wrapBinaryPeer(connectionId, peer, localDevice, initiator, { protocol: 'wrtc', markTransportSecure: true }, getTrustLevel);
+}
+/**
+ * Wraps a libp2p peer into a Connection.
+ * Backwards-compatible wrapper around wrapBinaryPeer.
+ * libp2p is encrypted at the transport layer (noise protocol), so we skip application-level encryption.
+ */
+function wrapLibp2p(connectionId, peer, localDevice, initiator, getTrustLevel) {
+    return wrapBinaryPeer(connectionId, peer, localDevice, initiator, { protocol: 'libp2p', markTransportSecure: true }, getTrustLevel);
+}

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

@@ -0,0 +1 @@
+export {};