@ctrl-spc/cs 0.4.0 → 0.6.0

package/dist/screenshots.js

@@ -0,0 +1,196 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { inflateSync } from 'node:zlib';
+export const MAX_SCREENSHOT_BYTES = 20 * 1024 * 1024;
+const MAX_DECODED_SCREENSHOT_BYTES = 256 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const CRC32_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit += 1) {
+        crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    }
+    return crc >>> 0;
+});
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc = CRC32_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Read and validate the local screenshot before any hosted request is made.
+ *
+ * This validates the PNG framing and decoded scanline envelope without
+ * rewriting the user's original bytes. Interlaced images are rejected because
+ * browser and mobile screenshot tools produce standard non-interlaced PNGs,
+ * and validating Adam7 safely would add complexity without helping Phase 1.
+ */
+export async function readPngScreenshot(localPath) {
+    if (!localPath || !isAbsolute(localPath)) {
+        throw new Error('path must be an absolute local path');
+    }
+    let stat;
+    try {
+        stat = await lstat(localPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            throw new Error(`the PNG was not found at ${localPath}`);
+        throw new Error(`the PNG could not be inspected at ${localPath}: ${err.message}`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`the path is not a regular file: ${localPath}`);
+    }
+    if (stat.size === 0) {
+        throw new Error('the PNG is empty');
+    }
+    if (stat.size > MAX_SCREENSHOT_BYTES) {
+        throw new Error(`the PNG is larger than the ${MAX_SCREENSHOT_BYTES / (1024 * 1024)} MB limit`);
+    }
+    let bytes;
+    try {
+        bytes = await readFile(localPath);
+    }
+    catch (err) {
+        throw new Error(`the PNG could not be read at ${localPath}: ${err.message}`);
+    }
+    if (bytes.length !== stat.size) {
+        throw new Error('the PNG changed while it was being read; capture it again and retry');
+    }
+    if (bytes.length < PNG_SIGNATURE.length || !bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        throw new Error('the file is not a readable PNG (invalid PNG signature)');
+    }
+    let offset = 8;
+    let width = 0;
+    let height = 0;
+    let sawHeader = false;
+    let sawImageData = false;
+    let sawEnd = false;
+    let sawPalette = false;
+    let endedImageData = false;
+    let bitDepth = 0;
+    let colorType = 0;
+    const imageDataChunks = [];
+    while (offset < bytes.length) {
+        if (bytes.length - offset < 12) {
+            throw new Error('the file is not a readable PNG (truncated chunk header)');
+        }
+        const length = bytes.readUInt32BE(offset);
+        const chunkEnd = offset + 12 + length;
+        if (chunkEnd > bytes.length || chunkEnd < offset) {
+            throw new Error('the file is not a readable PNG (truncated chunk data)');
+        }
+        const typeBytes = bytes.subarray(offset + 4, offset + 8);
+        const type = typeBytes.toString('ascii');
+        if (!/^[A-Za-z]{4}$/.test(type)) {
+            throw new Error('the file is not a readable PNG (invalid chunk type)');
+        }
+        const expectedCrc = bytes.readUInt32BE(offset + 8 + length);
+        const actualCrc = crc32(bytes.subarray(offset + 4, offset + 8 + length));
+        if (actualCrc !== expectedCrc) {
+            throw new Error(`the file is not a readable PNG (${type} chunk CRC mismatch)`);
+        }
+        if (!sawHeader) {
+            if (type !== 'IHDR' || length !== 13) {
+                throw new Error('the file is not a readable PNG (missing the required IHDR header)');
+            }
+            width = bytes.readUInt32BE(offset + 8);
+            height = bytes.readUInt32BE(offset + 12);
+            bitDepth = bytes[offset + 16];
+            colorType = bytes[offset + 17];
+            const compression = bytes[offset + 18];
+            const filter = bytes[offset + 19];
+            const interlace = bytes[offset + 20];
+            const legalDepths = {
+                0: [1, 2, 4, 8, 16],
+                2: [8, 16],
+                3: [1, 2, 4, 8],
+                4: [8, 16],
+                6: [8, 16],
+            };
+            if (!legalDepths[colorType]?.includes(bitDepth)) {
+                throw new Error('the file is not a readable PNG (unsupported IHDR color type or bit depth)');
+            }
+            if (compression !== 0 || filter !== 0) {
+                throw new Error('the file is not a readable PNG (unsupported compression or filter method)');
+            }
+            if (interlace !== 0) {
+                throw new Error('the file is not a readable PNG (interlaced PNGs are not supported)');
+            }
+            sawHeader = true;
+        }
+        else if (type === 'IHDR') {
+            throw new Error('the file is not a readable PNG (duplicate IHDR header)');
+        }
+        if (type === 'PLTE') {
+            if (sawImageData || length === 0 || length % 3 !== 0 || length > 768) {
+                throw new Error('the file is not a readable PNG (invalid PLTE chunk)');
+            }
+            sawPalette = true;
+        }
+        if (type === 'IDAT') {
+            if (endedImageData) {
+                throw new Error('the file is not a readable PNG (IDAT chunks must be consecutive)');
+            }
+            sawImageData = true;
+            imageDataChunks.push(bytes.subarray(offset + 8, offset + 8 + length));
+        }
+        else if (type === 'IEND') {
+            if (length !== 0) {
+                throw new Error('the file is not a readable PNG (invalid IEND chunk)');
+            }
+            sawEnd = true;
+            offset = chunkEnd;
+            break;
+        }
+        else if (sawImageData) {
+            endedImageData = true;
+        }
+        if (/^[A-Z]/.test(type) && !['IHDR', 'PLTE', 'IDAT', 'IEND'].includes(type)) {
+            throw new Error(`the file is not a readable PNG (unsupported critical chunk ${type})`);
+        }
+        offset = chunkEnd;
+    }
+    if (!sawImageData) {
+        throw new Error('the file is not a readable PNG (missing image data)');
+    }
+    if (!sawEnd) {
+        throw new Error('the file is not a readable PNG (missing IEND chunk)');
+    }
+    if (offset !== bytes.length) {
+        throw new Error('the file is not a readable PNG (trailing data after IEND)');
+    }
+    if (width < 1 || height < 1) {
+        throw new Error('the file is not a readable PNG (width and height must be positive)');
+    }
+    if (colorType === 3 && !sawPalette) {
+        throw new Error('the file is not a readable PNG (indexed color requires a PLTE chunk)');
+    }
+    const channels = colorType === 0 || colorType === 3 ? 1 : colorType === 2 ? 3 : colorType === 4 ? 2 : 4;
+    const rowBytes = Math.ceil((width * channels * bitDepth) / 8);
+    const scanlineBytes = rowBytes + 1;
+    const expectedDecodedBytes = scanlineBytes * height;
+    if (!Number.isSafeInteger(expectedDecodedBytes) || expectedDecodedBytes > MAX_DECODED_SCREENSHOT_BYTES) {
+        throw new Error('the PNG expands beyond the 256 MB decoded screenshot limit');
+    }
+    let decoded;
+    try {
+        decoded = inflateSync(Buffer.concat(imageDataChunks), {
+            maxOutputLength: expectedDecodedBytes + 1,
+        });
+    }
+    catch (err) {
+        throw new Error(`the file is not a readable PNG (invalid compressed image data: ${err.message})`);
+    }
+    if (decoded.length !== expectedDecodedBytes) {
+        throw new Error(`the file is not a readable PNG (decoded scanline size is ${decoded.length}, expected ${expectedDecodedBytes})`);
+    }
+    for (let row = 0; row < height; row += 1) {
+        if (decoded[row * scanlineBytes] > 4) {
+            throw new Error(`the file is not a readable PNG (invalid filter byte on scanline ${row + 1})`);
+        }
+    }
+    return { bytes, width, height, sizeBytes: bytes.length };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"