spck 0.3.1 → 0.4.0

package/src/connection/hmac.ts

@@ -55,10 +55,23 @@ export function validateHMAC(message: JSONRPCRequest, signingKey: string): boole
   // Reconstruct the message that was signed (must match client's _computeHMAC)
   // Client uses: const { timestamp, hmac, ...rest } = request
   // So we need to include all fields except timestamp and hmac
+  // Strip any Buffer values from params before JSON.stringify,
+  // since they serialize inconsistently across environments. Both sides must do this.
+  let params = message.params;
+  if (params && typeof params === 'object') {
+    const cleanParams: any = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (!Buffer.isBuffer(v)) {
+        cleanParams[k] = v;
+      }
+    }
+    params = cleanParams;
+  }
+
   const payload: any = {
     jsonrpc: message.jsonrpc,
     method: message.method,
-    params: message.params,
+    params,
     id: message.id,
     nonce: message.nonce
   };

package/src/proxy/ProxyClient.ts

@@ -704,11 +704,17 @@ export class ProxyClient {
       // Route to appropriate service with socket wrapper
       const result = await RPCRouter.route(message as JSONRPCRequest, connection.socketWrapper as any);
 
+      // If result is an async iterable, stream it as binary chunks (__binaryChunk protocol)
+      if (result != null && typeof result[Symbol.asyncIterator] === 'function') {
+        await this.sendBinaryChunked(connectionId, message.id ?? null, result);
+        return;
+      }
+
       // Send response
       const response: JSONRPCResponse = {
         jsonrpc: '2.0',
         result,
-        id: message.id || null,
+        id: message.id ?? null,
       };
 
       this.sendToClient(connectionId, 'rpc', response);
@@ -721,13 +727,59 @@ export class ProxyClient {
           ErrorCode.INTERNAL_ERROR,
           error.message || 'Internal error'
         ),
-        id: message.id || null,
+        id: message.id ?? null,
       };
 
       this.sendToClient(connectionId, 'rpc', response);
     }
   }
 
+  /**
+   * Stream an async iterable of Buffers to the client using the __binaryChunk protocol.
+   * Each chunk is sent as a Socket.IO binary attachment (no base64).
+   * The client assembles chunks and resolves the pending RPC request.
+   */
+  private async sendBinaryChunked(
+    connectionId: string,
+    requestId: number | string | null,
+    iterable: any
+  ): Promise<void> {
+    if (!this.socket) return;
+    const chunkId = crypto.randomBytes(8).toString('hex');
+    const total: number = iterable.totalChunks;
+    const sizeMB = iterable.size ? `~${Math.round(iterable.size / 1024 / 1024 * 10) / 10}MB` : '?';
+    console.log(`📦 Binary streaming: ${total} chunks (${sizeMB}) for request ${requestId}`);
+
+    try {
+      let index = 0;
+      for await (const chunk of iterable) {
+        // Emit directly (bypass sendToClient/needsChunking) — Socket.IO handles Buffer natively
+        this.socket.emit('rpc', {
+          connectionId,
+          data: {
+            __binaryChunk: true,
+            chunkId,
+            requestId,
+            index,
+            total,
+            data: chunk, // Buffer — Socket.IO sends as binary attachment
+          },
+        });
+        index++;
+      }
+    } catch (error: any) {
+      // Stream error — send a normal RPC error so the client rejects the pending request
+      this.socket.emit('rpc', {
+        connectionId,
+        data: {
+          jsonrpc: '2.0',
+          id: requestId,
+          error: createRPCError(ErrorCode.INTERNAL_ERROR, error.message || 'Binary stream error'),
+        },
+      });
+    }
+  }
+
   /**
    * Send message to client via proxy
    * Automatically chunks large payloads (>800kB)

package/src/services/FilesystemService.ts

@@ -56,6 +56,22 @@ export class FilesystemService {
           result = await this.readFile(safePath!, params);
           logFsRead(method, params, deviceId, true, undefined, { size: result.size, encoding: result.encoding });
           return result;
+        case 'stat':
+          result = await this.stat(safePath!);
+          logFsRead(method, params, deviceId, true, undefined, { size: result.size });
+          return result;
+        case 'readFileBinary':
+          result = await this.readFileBinary(safePath!, params);
+          logFsRead(method, params, deviceId, true, undefined,
+            result.rangeLength !== undefined
+              ? { size: result.size, offset: result.rangeOffset, length: result.rangeLength }
+              : { size: result.size, totalChunks: result.totalChunks }
+          );
+          return result;
+        case 'writeBinary':
+          result = await this.writeBinary(safePath!, params);
+          logFsWrite(method, params, deviceId, true, undefined, { size: result.size });
+          return result;
         case 'write':
           result = await this.write(safePath!, params);
           logFsWrite(method, params, deviceId, true, undefined, { size: result.size });
@@ -114,7 +130,7 @@ export class FilesystemService {
     } catch (err) {
       error = err;
       // Determine if this was a read or write operation for logging
-      const readOps = ['exists', 'readFile', 'getFileHash', 'readdir', 'readdirDeep', 'bulkExists', 'lstat'];
+      const readOps = ['exists', 'readFile', 'getFileHash', 'readdir', 'readdirDeep', 'bulkExists', 'lstat', 'stat'];
       if (readOps.includes(method)) {
         logFsRead(method, params, deviceId, false, error);
       } else {
@@ -129,8 +145,11 @@ export class FilesystemService {
    * Prevents directory traversal and symlink escape attacks
    */
   private async validatePath(userPath: string): Promise<string> {
+    // Strip query string and fragment (cache-busters sent by the browser)
+    const cleanPath = userPath.split('?')[0].split('#')[0];
+
     // Normalize path
-    const normalized = path.normalize(userPath);
+    const normalized = path.normalize(cleanPath);
 
     // Prevent directory traversal
     if (normalized.includes('..')) {
@@ -251,11 +270,132 @@ export class FilesystemService {
   /**
    * Read file contents
    */
+  private async stat(safePath: string): Promise<any> {
+    try {
+      const stats = await fs.stat(safePath);
+      return {
+        size: stats.size,
+        mtime: stats.mtimeMs,
+        isFile: stats.isFile(),
+        isDirectory: stats.isDirectory(),
+      };
+    } catch (error: any) {
+      if (error.code === 'ENOENT') {
+        throw createRPCError(ErrorCode.FILE_NOT_FOUND, `File not found: ${safePath}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Binary read — returns an async iterable of Buffer chunks.
+   * ProxyClient detects the iterable and streams chunks to the client via __binaryChunk protocol.
+   * File handle is opened once and held for the full iteration (atomic w.r.t. the file descriptor).
+   */
+  private async readFileBinary(safePath: string, params: any): Promise<any> {
+    const CHUNK_SIZE = params.chunkSize || 750 * 1024;
+
+    let stats: any;
+    try {
+      stats = await fs.stat(safePath);
+    } catch (error: any) {
+      if (error.code === 'ENOENT') {
+        throw createRPCError(ErrorCode.FILE_NOT_FOUND, `File not found: ${safePath}`);
+      }
+      throw error;
+    }
+
+    const totalSize = stats.size;
+
+    // Range read: single-chunk iterable for a specific byte range (used by video streaming)
+    if (params.offset !== undefined) {
+      const offset = params.offset as number;
+      const rangeLength = Math.min(
+        params.length !== undefined ? (params.length as number) : (totalSize - offset),
+        totalSize - offset
+      );
+      if (offset < 0 || rangeLength < 0) {
+        throw createRPCError(ErrorCode.INVALID_PARAMS, 'Invalid range parameters');
+      }
+      const iterable = {
+        totalChunks: 1,
+        size: totalSize,
+        rangeOffset: offset,
+        rangeLength,
+        async *[Symbol.asyncIterator]() {
+          const fh = await fs.open(safePath, 'r');
+          try {
+            const buf = Buffer.alloc(rangeLength);
+            if (rangeLength > 0) await fh.read(buf, 0, rangeLength, offset);
+            yield buf;
+          } finally {
+            await fh.close();
+          }
+        }
+      };
+      return iterable;
+    }
+
+    const totalChunks = Math.max(1, Math.ceil(totalSize / CHUNK_SIZE));
+
+    // Return an async iterable. ProxyClient will detect [Symbol.asyncIterator] and stream chunks.
+    const iterable = {
+      totalChunks,
+      size: totalSize,
+      async *[Symbol.asyncIterator]() {
+        const fh = await fs.open(safePath, 'r');
+        try {
+          for (let i = 0; i < totalChunks; i++) {
+            const offset = i * CHUNK_SIZE;
+            const length = Math.min(CHUNK_SIZE, totalSize - offset);
+            const buf = Buffer.alloc(length);
+            if (length > 0) await fh.read(buf, 0, length, offset);
+            yield buf;
+          }
+        } finally {
+          await fh.close();
+        }
+      }
+    };
+    return iterable;
+  }
+
+  /**
+   * Binary write — receives the full buffer as a Socket.IO binary attachment.
+   * No accumulation needed; ProxyClient routes directly once Socket.IO reassembles the binary.
+   */
+  private async writeBinary(safePath: string, params: any): Promise<any> {
+    const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.alloc(0);
+    return this.write(safePath, { ...params, contents: buffer, encoding: 'binary' });
+  }
+
   private async readFile(safePath: string, params: any): Promise<any> {
     try {
       const stats = await fs.stat(safePath);
 
-      // Check file size limit
+      const encoding = params.encoding || 'utf8';
+
+      // Range read: bypass maxFileSize limit since we only read a small chunk
+      if (params.offset !== undefined) {
+        const offset = params.offset as number;
+        const length = Math.min(
+          params.length !== undefined ? (params.length as number) : (stats.size - offset),
+          stats.size - offset
+        );
+        if (offset < 0 || length <= 0) {
+          throw createRPCError(ErrorCode.INVALID_PARAMS, 'Invalid range parameters');
+        }
+        const fh = await fs.open(safePath, 'r');
+        try {
+          const buf = Buffer.alloc(length);
+          await fh.read(buf, 0, length, offset);
+          return { buffer: buf, size: stats.size, offset, length, encoding: 'binary' };
+        } finally {
+          await fh.close();
+        }
+      }
+
+      // Check file size limit for full reads
       const maxSize = parseFileSize(this.config.maxFileSize);
       if (stats.size > maxSize) {
         throw createRPCError(
@@ -265,8 +405,6 @@ export class FilesystemService {
         );
       }
 
-      const encoding = params.encoding || 'utf8';
-
       if (encoding === 'binary') {
         // Binary file - return buffer directly in response
         const buffer = await fs.readFile(safePath);
@@ -325,25 +463,9 @@ export class FilesystemService {
 
     // Write file (atomic or regular)
     if (atomic) {
-      // Use write-file-atomic for atomic writes
-      if (encoding === 'binary') {
-        const buffer = typeof params.contents === 'string'
-          ? Buffer.from(params.contents, 'base64')
-          : Buffer.from(params.contents || Buffer.alloc(0));
-        await writeFileAtomic(safePath, buffer);
-      } else {
-        await writeFileAtomic(safePath, params.contents, { encoding });
-      }
+      await writeFileAtomic(safePath, params.contents, { encoding });
     } else {
-      // Regular write
-      if (encoding === 'binary') {
-        const buffer = typeof params.contents === 'string'
-          ? Buffer.from(params.contents, 'base64')
-          : Buffer.from(params.contents || Buffer.alloc(0));
-        await fs.writeFile(safePath, buffer);
-      } else {
-        await fs.writeFile(safePath, params.contents, encoding);
-      }
+      await fs.writeFile(safePath, params.contents, encoding);
     }
 
     // Set executable if requested
@@ -462,6 +584,9 @@ export class FilesystemService {
    */
   private async getFileHash(safePath: string): Promise<any> {
     const hash = await this.getFileHashValue(safePath);
+    if (hash === null) {
+      return { hash: null, size: 0, mtime: 0 };
+    }
     const stats = await fs.stat(safePath);
 
     return {