spck 0.3.1 → 0.4.0

package/dist/connection/hmac.js

@@ -48,10 +48,22 @@ export function validateHMAC(message, signingKey) {
     // 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 = {};
+        for (const [k, v] of Object.entries(params)) {
+            if (!Buffer.isBuffer(v)) {
+                cleanParams[k] = v;
+            }
+        }
+        params = cleanParams;
+    }
     const payload = {
         jsonrpc: message.jsonrpc,
         method: message.method,
-        params: message.params,
+        params,
         id: message.id,
         nonce: message.nonce
     };

package/dist/proxy/ProxyClient.d.ts

@@ -83,6 +83,12 @@ export declare class ProxyClient {
      * Handle RPC message from client
      */
     private handleRPCMessage;
+    /**
+     * 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 sendBinaryChunked;
     /**
      * Send message to client via proxy
      * Automatically chunks large payloads (>800kB)

package/dist/proxy/ProxyClient.js

@@ -552,11 +552,16 @@ export class ProxyClient {
             requireValidHMAC(message, this.connectionSettings.secret);
             // Route to appropriate service with socket wrapper
             const result = await RPCRouter.route(message, connection.socketWrapper);
+            // 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 = {
                 jsonrpc: '2.0',
                 result,
-                id: message.id || null,
+                id: message.id ?? null,
             };
             this.sendToClient(connectionId, 'rpc', response);
         }
@@ -565,11 +570,53 @@ export class ProxyClient {
             const response = {
                 jsonrpc: '2.0',
                 error: error.code && error.message ? error : createRPCError(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.
+     */
+    async sendBinaryChunked(connectionId, requestId, iterable) {
+        if (!this.socket)
+            return;
+        const chunkId = crypto.randomBytes(8).toString('hex');
+        const total = 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) {
+            // 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/dist/services/FilesystemService.d.ts

@@ -32,6 +32,18 @@ export declare class FilesystemService {
     /**
      * Read file contents
      */
+    private stat;
+    /**
+     * 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 readFileBinary;
+    /**
+     * 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 writeBinary;
     private readFile;
     /**
      * Write file contents

package/dist/services/FilesystemService.js

@@ -47,6 +47,20 @@ 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 });
@@ -106,7 +120,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);
             }
@@ -121,8 +135,10 @@ export class FilesystemService {
      * Prevents directory traversal and symlink escape attacks
      */
     async validatePath(userPath) {
+        // 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('..')) {
             throw createRPCError(ErrorCode.INVALID_PATH, 'Invalid path: directory traversal not allowed');
@@ -220,15 +236,126 @@ export class FilesystemService {
     /**
      * Read file contents
      */
+    async stat(safePath) {
+        try {
+            const stats = await fs.stat(safePath);
+            return {
+                size: stats.size,
+                mtime: stats.mtimeMs,
+                isFile: stats.isFile(),
+                isDirectory: stats.isDirectory(),
+            };
+        }
+        catch (error) {
+            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).
+     */
+    async readFileBinary(safePath, params) {
+        const CHUNK_SIZE = params.chunkSize || 750 * 1024;
+        let stats;
+        try {
+            stats = await fs.stat(safePath);
+        }
+        catch (error) {
+            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;
+            const rangeLength = Math.min(params.length !== undefined ? params.length : (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.
+     */
+    async writeBinary(safePath, params) {
+        const buffer = Buffer.isBuffer(params.data) ? params.data : Buffer.alloc(0);
+        return this.write(safePath, { ...params, contents: buffer, encoding: 'binary' });
+    }
     async readFile(safePath, params) {
         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;
+                const length = Math.min(params.length !== undefined ? params.length : (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(ErrorCode.FILE_TOO_LARGE, `File too large: ${stats.size} bytes (max: ${this.config.maxFileSize})`, { size: stats.size, maxSize });
             }
-            const encoding = params.encoding || 'utf8';
             if (encoding === 'binary') {
                 // Binary file - return buffer directly in response
                 const buffer = await fs.readFile(safePath);
@@ -280,28 +407,10 @@ export class FilesystemService {
         const atomic = params.atomic || false;
         // 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
         if (params.executable) {
@@ -391,6 +500,9 @@ export class FilesystemService {
      */
     async getFileHash(safePath) {
         const hash = await this.getFileHashValue(safePath);
+        if (hash === null) {
+            return { hash: null, size: 0, mtime: 0 };
+        }
         const stats = await fs.stat(safePath);
         return {
             hash,

package/dist/services/__tests__/FilesystemService.test.js

@@ -62,6 +62,16 @@ describe('FilesystemService', () => {
             const result = await service.handle('exists', { path: '//test.txt' }, mockSocket);
             expect(result.exists).toBe(true);
         });
+        it('should strip query strings from paths (cache-busters)', async () => {
+            await fs.writeFile(path.join(testRoot, 'logo.png'), 'data');
+            const result = await service.handle('exists', { path: '/logo.png?b=1775829760178' }, mockSocket);
+            expect(result.exists).toBe(true);
+        });
+        it('should strip URL fragments from paths', async () => {
+            await fs.writeFile(path.join(testRoot, 'page.html'), '<html/>');
+            const result = await service.handle('exists', { path: '/page.html#section' }, mockSocket);
+            expect(result.exists).toBe(true);
+        });
     });
     describe('File Operations - exists', () => {
         it('should return true for existing file', async () => {
@@ -163,19 +173,17 @@ describe('FilesystemService', () => {
             }, mockSocket);
             expect(result.success).toBe(true);
         });
-        it('should write binary file from base64-encoded string', async () => {
+        it('should write binary file via writeBinary (Buffer, single chunk)', async () => {
             const bytes = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]); // PNG header
-            const base64 = bytes.toString('base64');
-            const result = await service.handle('write', { path: '/image.png', contents: base64, encoding: 'binary' }, mockSocket);
+            const result = await service.handle('writeBinary', { path: '/image.png', uploadId: 'upload-1', chunk: 0, totalChunks: 1, data: bytes }, mockSocket);
             expect(result.success).toBe(true);
             expect(result.sha256).toBeTruthy();
             const written = await fs.readFile(path.join(testRoot, 'image.png'));
             expect(written).toEqual(bytes);
         });
-        it('should write binary file atomically from base64-encoded string', async () => {
+        it('should write binary file atomically via writeBinary', async () => {
             const bytes = Buffer.from([0x00, 0x01, 0x02, 0x03, 0xFF, 0xFE, 0xFD]);
-            const base64 = bytes.toString('base64');
-            const result = await service.handle('write', { path: '/data.bin', contents: base64, encoding: 'binary', atomic: true }, mockSocket);
+            const result = await service.handle('writeBinary', { path: '/data.bin', uploadId: 'upload-2', chunk: 0, totalChunks: 1, data: bytes, atomic: true }, mockSocket);
             expect(result.success).toBe(true);
             const written = await fs.readFile(path.join(testRoot, 'data.bin'));
             expect(written).toEqual(bytes);
@@ -186,11 +194,10 @@ describe('FilesystemService', () => {
             const written = await fs.readFile(path.join(testRoot, 'empty.bin'));
             expect(written.length).toBe(0);
         });
-        it('should preserve all byte values when writing binary via base64', async () => {
+        it('should preserve all byte values when writing binary via writeBinary', async () => {
             // Full range of byte values 0x00–0xFF
             const bytes = Buffer.from(Array.from({ length: 256 }, (_, i) => i));
-            const base64 = bytes.toString('base64');
-            await service.handle('write', { path: '/allbytes.bin', contents: base64, encoding: 'binary' }, mockSocket);
+            await service.handle('writeBinary', { path: '/allbytes.bin', uploadId: 'upload-3', chunk: 0, totalChunks: 1, data: bytes }, mockSocket);
             const written = await fs.readFile(path.join(testRoot, 'allbytes.bin'));
             expect(written).toEqual(bytes);
         });
@@ -265,6 +272,25 @@ describe('FilesystemService', () => {
             expect(result.size).toBe(Buffer.from(content).length);
             expect(result.mtime).toBeGreaterThan(0);
         });
+        it('should return null hash when file does not exist', async () => {
+            const result = await service.handle('getFileHash', { path: '/nonexistent.txt' }, mockSocket);
+            expect(result.hash).toBeNull();
+            expect(result.size).toBe(0);
+            expect(result.mtime).toBe(0);
+        });
+        it('should return null hash after file is deleted', async () => {
+            await fs.writeFile(path.join(testRoot, 'deleted.txt'), 'some content');
+            // Verify hash exists before deletion
+            const before = await service.handle('getFileHash', { path: '/deleted.txt' }, mockSocket);
+            expect(before.hash).not.toBeNull();
+            // Delete the file
+            await fs.unlink(path.join(testRoot, 'deleted.txt'));
+            // Should gracefully return null hash instead of throwing ENOENT
+            const after = await service.handle('getFileHash', { path: '/deleted.txt' }, mockSocket);
+            expect(after.hash).toBeNull();
+            expect(after.size).toBe(0);
+            expect(after.mtime).toBe(0);
+        });
     });
     describe('File Operations - remove', () => {
         it('should remove file', async () => {
@@ -597,6 +623,208 @@ describe('FilesystemService', () => {
             });
         });
     });
+    describe('File Operations - stat', () => {
+        it('should return size, mtime, isFile, isDirectory for a file', async () => {
+            const content = 'hello stat';
+            await fs.writeFile(path.join(testRoot, 'stat-file.txt'), content);
+            const result = await service.handle('stat', { path: '/stat-file.txt' }, mockSocket);
+            expect(result.size).toBe(Buffer.byteLength(content));
+            expect(result.mtime).toBeGreaterThan(0);
+            expect(result.isFile).toBe(true);
+            expect(result.isDirectory).toBe(false);
+        });
+        it('should report isDirectory for a directory', async () => {
+            await fs.mkdir(path.join(testRoot, 'statdir'));
+            const result = await service.handle('stat', { path: '/statdir' }, mockSocket);
+            expect(result.isDirectory).toBe(true);
+            expect(result.isFile).toBe(false);
+        });
+        it('should throw FILE_NOT_FOUND for missing path', async () => {
+            await expect(service.handle('stat', { path: '/no-such-file.txt' }, mockSocket)).rejects.toMatchObject({ code: ErrorCode.FILE_NOT_FOUND });
+        });
+    });
+    describe('File Operations - readFile (range read)', () => {
+        let fileContent;
+        const FILE = '/range.bin';
+        beforeEach(async () => {
+            // 100-byte file: byte value equals its index
+            fileContent = Buffer.from(Array.from({ length: 100 }, (_, i) => i));
+            await fs.writeFile(path.join(testRoot, 'range.bin'), fileContent);
+        });
+        it('should read a byte range from the middle of the file', async () => {
+            const result = await service.handle('readFile', { path: FILE, offset: 10, length: 20 }, mockSocket);
+            expect(result.buffer).toEqual(fileContent.subarray(10, 30));
+            expect(result.offset).toBe(10);
+            expect(result.length).toBe(20);
+            expect(result.size).toBe(100);
+            expect(result.encoding).toBe('binary');
+        });
+        it('should read from offset 0', async () => {
+            const result = await service.handle('readFile', { path: FILE, offset: 0, length: 5 }, mockSocket);
+            expect(result.buffer).toEqual(fileContent.subarray(0, 5));
+        });
+        it('should read to end of file when length reaches past EOF', async () => {
+            // Request 50 bytes starting at offset 80 — only 20 bytes remain
+            const result = await service.handle('readFile', { path: FILE, offset: 80, length: 50 }, mockSocket);
+            expect(result.buffer).toEqual(fileContent.subarray(80, 100));
+            expect(result.length).toBe(20);
+        });
+        it('should use remaining bytes when length is omitted', async () => {
+            const result = await service.handle('readFile', { path: FILE, offset: 90 }, mockSocket);
+            expect(result.buffer).toEqual(fileContent.subarray(90));
+            expect(result.length).toBe(10);
+        });
+        it('should bypass the maxFileSize limit for range reads', async () => {
+            // Create a file larger than the 10 MB limit
+            const bigPath = path.join(testRoot, 'big.bin');
+            const bigBuf = Buffer.alloc(11 * 1024 * 1024, 0xab);
+            await fs.writeFile(bigPath, bigBuf);
+            // Full read should fail with FILE_TOO_LARGE
+            await expect(service.handle('readFile', { path: '/big.bin' }, mockSocket)).rejects.toMatchObject({ code: ErrorCode.FILE_TOO_LARGE });
+            // Range read of the same file must succeed
+            const result = await service.handle('readFile', { path: '/big.bin', offset: 0, length: 64 }, mockSocket);
+            expect(result.buffer.length).toBe(64);
+            expect(result.size).toBe(bigBuf.length);
+        });
+        it('should throw INVALID_PARAMS when offset is negative', async () => {
+            await expect(service.handle('readFile', { path: FILE, offset: -1, length: 10 }, mockSocket)).rejects.toMatchObject({ code: ErrorCode.INVALID_PARAMS });
+        });
+        it('should throw INVALID_PARAMS when range produces zero length', async () => {
+            // offset at end-of-file → length clamps to 0
+            await expect(service.handle('readFile', { path: FILE, offset: 100, length: 10 }, mockSocket)).rejects.toMatchObject({ code: ErrorCode.INVALID_PARAMS });
+        });
+        it('should throw FILE_NOT_FOUND for range read on missing file', async () => {
+            await expect(service.handle('readFile', { path: '/missing.bin', offset: 0, length: 10 }, mockSocket)).rejects.toMatchObject({ code: ErrorCode.FILE_NOT_FOUND });
+        });
+    });
+    async function collectBinary(iterable) {
+        const parts = [];
+        for await (const chunk of iterable)
+            parts.push(chunk);
+        return Buffer.concat(parts);
+    }
+    describe('File Operations - readFileBinary (async iterable)', () => {
+        it('should return async iterable with correct metadata for small file', async () => {
+            const content = Buffer.from([0x89, 0x50, 0x4E, 0x47]); // PNG header
+            await fs.writeFile(path.join(testRoot, 'small.png'), content);
+            const result = await service.handle('readFileBinary', { path: '/small.png' }, mockSocket);
+            expect(result.totalChunks).toBe(1);
+            expect(result.size).toBe(4);
+            expect(typeof result[Symbol.asyncIterator]).toBe('function');
+            expect(await collectBinary(result)).toEqual(content);
+        });
+        it('should stream multi-chunk file with correct chunk sizes', async () => {
+            const CHUNK = 512;
+            const content = Buffer.from(Array.from({ length: 1500 }, (_, i) => i % 256));
+            await fs.writeFile(path.join(testRoot, 'multi.bin'), content);
+            const result = await service.handle('readFileBinary', { path: '/multi.bin', chunkSize: CHUNK }, mockSocket);
+            expect(result.totalChunks).toBe(3);
+            expect(result.size).toBe(1500);
+            const chunks = [];
+            for await (const chunk of result) {
+                expect(Buffer.isBuffer(chunk)).toBe(true);
+                chunks.push(chunk);
+            }
+            expect(chunks.length).toBe(3);
+            expect(Buffer.concat(chunks)).toEqual(content);
+        });
+        it('should reassemble to exact original bytes', async () => {
+            const content = Buffer.from(Array.from({ length: 256 }, (_, i) => i));
+            await fs.writeFile(path.join(testRoot, 'allbytes2.bin'), content);
+            const result = await service.handle('readFileBinary', { path: '/allbytes2.bin', chunkSize: 100 }, mockSocket);
+            expect(await collectBinary(result)).toEqual(content);
+        });
+        it('should handle empty file', async () => {
+            await fs.writeFile(path.join(testRoot, 'empty2.bin'), Buffer.alloc(0));
+            const result = await service.handle('readFileBinary', { path: '/empty2.bin' }, mockSocket);
+            expect(result.size).toBe(0);
+            expect(result.totalChunks).toBe(1);
+            expect((await collectBinary(result)).length).toBe(0);
+        });
+        it('should throw FILE_NOT_FOUND for missing file', async () => {
+            await expect(service.handle('readFileBinary', { path: '/missing.bin' }, mockSocket)).rejects.toMatchObject({ code: ErrorCode.FILE_NOT_FOUND });
+        });
+        it('should support concurrent reads of the same file without interference', async () => {
+            const content = Buffer.from(Array.from({ length: 300 }, (_, i) => i % 256));
+            await fs.writeFile(path.join(testRoot, 'concurrent.bin'), content);
+            // Start two reads concurrently
+            const [r1, r2] = await Promise.all([
+                service.handle('readFileBinary', { path: '/concurrent.bin', chunkSize: 100 }, mockSocket),
+                service.handle('readFileBinary', { path: '/concurrent.bin', chunkSize: 150 }, mockSocket),
+            ]);
+            const [buf1, buf2] = await Promise.all([collectBinary(r1), collectBinary(r2)]);
+            expect(buf1).toEqual(content);
+            expect(buf2).toEqual(content);
+        });
+        it('should return sha256-verifiable content matching the written file', async () => {
+            const content = Buffer.from('binary content for hash check');
+            await fs.writeFile(path.join(testRoot, 'hashcheck.bin'), content);
+            const expected = crypto.createHash('sha256').update(content).digest('hex');
+            const result = await service.handle('readFileBinary', { path: '/hashcheck.bin' }, mockSocket);
+            const assembled = await collectBinary(result);
+            const actual = crypto.createHash('sha256').update(assembled).digest('hex');
+            expect(actual).toBe(expected);
+        });
+    });
+    describe('File Operations - writeBinary', () => {
+        it('should write binary Buffer directly', async () => {
+            const bytes = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+            const result = await service.handle('writeBinary', { path: '/out.png', data: bytes }, mockSocket);
+            expect(result.success).toBe(true);
+            expect(result.sha256).toBeTruthy();
+            expect(await fs.readFile(path.join(testRoot, 'out.png'))).toEqual(bytes);
+        });
+        it('should write all byte values correctly', async () => {
+            const bytes = Buffer.from(Array.from({ length: 256 }, (_, i) => i));
+            await service.handle('writeBinary', { path: '/allbytes3.bin', data: bytes }, mockSocket);
+            expect(await fs.readFile(path.join(testRoot, 'allbytes3.bin'))).toEqual(bytes);
+        });
+        it('should write atomically when requested', async () => {
+            const bytes = Buffer.from([0x00, 0x01, 0x02, 0x03, 0xFF]);
+            const result = await service.handle('writeBinary', { path: '/atomic.bin', data: bytes, atomic: true }, mockSocket);
+            expect(result.success).toBe(true);
+            expect(await fs.readFile(path.join(testRoot, 'atomic.bin'))).toEqual(bytes);
+        });
+        it('should return sha256 of written content', async () => {
+            const bytes = Buffer.from([0x01, 0x02, 0x03, 0x04]);
+            const expected = crypto.createHash('sha256').update(bytes).digest('hex');
+            const result = await service.handle('writeBinary', { path: '/sha.bin', data: bytes }, mockSocket);
+            expect(result.sha256).toBe(expected);
+        });
+        it('should overwrite existing file', async () => {
+            await fs.writeFile(path.join(testRoot, 'overwrite.bin'), Buffer.from([0xFF, 0xFF]));
+            const newBytes = Buffer.from([0x01, 0x02, 0x03]);
+            await service.handle('writeBinary', { path: '/overwrite.bin', data: newBytes }, mockSocket);
+            expect(await fs.readFile(path.join(testRoot, 'overwrite.bin'))).toEqual(newBytes);
+        });
+        it('should detect write conflict when expectedHash does not match', async () => {
+            const original = Buffer.from([0xAA, 0xBB]);
+            await fs.writeFile(path.join(testRoot, 'conflict.bin'), original);
+            await expect(service.handle('writeBinary', {
+                path: '/conflict.bin',
+                data: Buffer.from([0x01]),
+                expectedHash: 'deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
+            }, mockSocket)).rejects.toMatchObject({ code: ErrorCode.WRITE_CONFLICT });
+        });
+        it('should write when expectedHash matches current file', async () => {
+            const original = Buffer.from([0xAA, 0xBB, 0xCC]);
+            await fs.writeFile(path.join(testRoot, 'match.bin'), original);
+            const correctHash = crypto.createHash('sha256').update(original).digest('hex');
+            const result = await service.handle('writeBinary', {
+                path: '/match.bin',
+                data: Buffer.from([0x11, 0x22]),
+                expectedHash: correctHash,
+            }, mockSocket);
+            expect(result.success).toBe(true);
+        });
+        it('round-trip: writeBinary then readFileBinary returns identical bytes', async () => {
+            const bytes = Buffer.from(Array.from({ length: 512 }, (_, i) => (i * 7 + 13) % 256));
+            await service.handle('writeBinary', { path: '/roundtrip.bin', data: bytes }, mockSocket);
+            const iterable = await service.handle('readFileBinary', { path: '/roundtrip.bin', chunkSize: 200 }, mockSocket);
+            const readBack = await collectBinary(iterable);
+            expect(readBack).toEqual(bytes);
+        });
+    });
     describe('Unknown Methods', () => {
         it('should throw error for unknown method', async () => {
             await expect(service.handle('unknownMethod', {}, mockSocket)).rejects.toMatchObject({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spck",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "CLI tool for Spck Editor - provides remote filesystem, git, browser proxing, and terminal access",
   "type": "module",
   "main": "dist/index.js",