fix(review): worker-thread HEIC conversion with bomb guard, concurrency cap, and magic-byte routing (PR #151)

- Event-loop blockage: HEIC decode/encode (CPU-synchronous libheif WASM +
  jpeg-js) now runs in a per-conversion worker_threads Worker
  (src/web/heic-jpeg-worker.ts, spawned by heic-jpeg-converter.ts) with
  resourceLimits and a 30s hard timeout that terminates the worker —
  verified end-to-end under tsx and against compiled dist/ output with a
  real iPhone HEIC (event-loop max stall 52ms during conversion).
- No server-side concurrency cap: conversions now acquire a slot from the
  existing global runWithConversionLimit() pool (document-conversion-limiter),
  bounding peak decode memory/CPU across simultaneous uploads.
- Decompression bomb: header-declared dimensions are read via heic-decode's
  allocation-free `.all` path and rejected above 64MP BEFORE decode() can
  allocate width*height*4 bytes (a <300-byte crafted file can declare
  30000x30000 = 3.6GB). Regression-tested with a crafted ISOBMFF fixture
  against the real heic-decode WASM (test/heic-jpeg-core.test.ts).
- Mislabeled HEIC (documented Android/MIUI case): conversion now routes on
  ftyp magic-byte sniff of the raw buffer regardless of declared
  ext/Content-Type, so a HEIF uploaded as image/jpeg converts instead of
  415ing; the magic-mismatch 415 only fires for genuinely unrecognized bytes.
- Brand allowlist narrowed to what heic-decode's isHeic() accepts
  (heim/heis/hevm/hevs dropped — they could only ever fail conversion).
- Converted-output size: the JPEG result is checked against
  MAX_PASTE_IMAGE_BYTES (jpeg-js can inflate a within-limit HEIC past the cap).
- Deps: heic-convert replaced with its underlying heic-decode + jpeg-js
  (the wrapper could not expose the pre-decode dimension check); lockfile
  synced, drops pngjs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/types/heic-convert.d.ts

@@ -1,9 +0,0 @@
-declare module 'heic-convert' {
-  export interface ConvertOptions {
-    buffer: Buffer;
-    format: 'JPEG' | 'PNG';
-    quality?: number;
-  }
-
-  export default function convert(options: ConvertOptions): Promise<Buffer | Uint8Array | ArrayBuffer>;
-}

src/types/heic-decode.d.ts

@@ -0,0 +1,24 @@
+declare module 'heic-decode' {
+  export interface DecodedHeicImage {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+  }
+
+  /** Handle exposing header-declared dimensions WITHOUT decoding pixels. */
+  export interface HeicImageHandle {
+    width: number;
+    height: number;
+    decode(): Promise<DecodedHeicImage>;
+  }
+
+  export type HeicImageHandles = HeicImageHandle[] & { dispose(): void };
+
+  interface HeicDecode {
+    (input: { buffer: Buffer | Uint8Array }): Promise<DecodedHeicImage>;
+    all(input: { buffer: Buffer | Uint8Array }): Promise<HeicImageHandles>;
+  }
+
+  const decode: HeicDecode;
+  export default decode;
+}

src/web/heic-jpeg-converter.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Main-thread wrapper for HEIC/HEIF → JPEG conversion.
+ *
+ * The actual decode/encode (`heic-jpeg-worker.ts`) is CPU-synchronous WASM + JS,
+ * so it runs in a dedicated `worker_threads` Worker per conversion — never on
+ * the event loop that serves every session's SSE/PTY/WS traffic. On top of
+ * the worker isolation this wrapper enforces:
+ *  - the global converter concurrency cap (`runWithConversionLimit`, shared
+ *    with the pdftoppm/soffice document converters) so N simultaneous uploads
+ *    can't pin N cores / N × 256MB decode buffers at once;
+ *  - a hard timeout that terminates the worker (a wedged WASM decode can't be
+ *    cancelled cooperatively);
+ *  - the paste-image size cap on the *output* — jpeg-js is a far less
+ *    efficient encoder than HEVC, so a within-limit HEIC can inflate past
+ *    MAX_PASTE_IMAGE_BYTES.
+ */
+
+import { Worker } from 'node:worker_threads';
+import { runWithConversionLimit } from '../document-conversion-limiter.js';
+import { MAX_PASTE_IMAGE_BYTES } from '../config/buffer-limits.js';
+import { HEIC_JPEG_QUALITY, type HeicWorkerInput, type HeicWorkerResult } from './heic-jpeg-worker.js';
+
+/** Hard cap on a single conversion; the worker is terminated when it fires. */
+export const HEIC_CONVERSION_TIMEOUT_MS = 30_000;
+
+// V8-heap guardrails for the conversion worker — defense in depth only: large
+// TypedArray/WASM backing stores are external to the V8 heap, so the real
+// memory bound is the 64MP dimension pre-check in heic-jpeg-worker.ts.
+const WORKER_RESOURCE_LIMITS = { maxOldGenerationSizeMb: 1024, maxYoungGenerationSizeMb: 128, stackSizeMb: 8 };
+
+function workerUrl(): URL {
+  // Compiled installs run the tsc-emitted .js sibling in dist/; dev under tsx
+  // runs the .ts source directly (tsx's loader propagates to worker threads).
+  const file = import.meta.url.endsWith('.ts') ? './heic-jpeg-worker.ts' : './heic-jpeg-worker.js';
+  return new URL(file, import.meta.url);
+}
+
+/**
+ * Convert HEIC/HEIF bytes to JPEG bytes off-thread. Rejects on invalid input,
+ * over-limit dimensions, oversized output, timeout, or worker failure.
+ */
+export async function convertHeicToJpeg(imageBytes: Buffer): Promise<Buffer> {
+  return runWithConversionLimit(
+    () =>
+      new Promise<Buffer>((resolve, reject) => {
+        const worker = new Worker(workerUrl(), {
+          workerData: { heicInput: imageBytes, quality: HEIC_JPEG_QUALITY } satisfies HeicWorkerInput,
+          resourceLimits: WORKER_RESOURCE_LIMITS,
+        });
+        let settled = false;
+        const settle = (fn: () => void): void => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          fn();
+          void worker.terminate();
+        };
+        const timer = setTimeout(() => {
+          settle(() => reject(new Error(`HEIC conversion timed out after ${HEIC_CONVERSION_TIMEOUT_MS}ms`)));
+        }, HEIC_CONVERSION_TIMEOUT_MS);
+        worker.on('message', (msg: HeicWorkerResult) => {
+          settle(() => {
+            if (!msg.ok) {
+              reject(new Error(msg.error));
+              return;
+            }
+            const out = Buffer.from(msg.data.buffer, msg.data.byteOffset, msg.data.byteLength);
+            if (out.length > MAX_PASTE_IMAGE_BYTES) {
+              const maxMb = Math.round(MAX_PASTE_IMAGE_BYTES / (1024 * 1024));
+              reject(new Error(`converted JPEG (${out.length} bytes) exceeds the ${maxMb}MB upload limit`));
+              return;
+            }
+            resolve(out);
+          });
+        });
+        worker.on('error', (err) => settle(() => reject(err)));
+        worker.on('exit', (code) => {
+          settle(() => reject(new Error(`HEIC conversion worker exited unexpectedly (code ${code})`)));
+        });
+      })
+  );
+}

src/web/heic-jpeg-worker.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview HEIC/HEIF → JPEG conversion core + worker-thread entry.
+ *
+ * Spawned per conversion by `heic-jpeg-converter.ts` so the CPU-synchronous
+ * libheif WASM decode + jpeg-js encode never run on the server's main thread
+ * (on the event loop they would freeze every session's SSE/PTY/WS handling
+ * for seconds per photo). Input arrives via `workerData`; the result (or
+ * error message) is posted back as a single message and the thread exits.
+ *
+ * The conversion logic lives in this same file (exported, guarded bootstrap)
+ * rather than a sibling module: the worker runs from `.ts` source under tsx
+ * in dev, where relative `.js` imports don't resolve inside worker threads —
+ * only `node:` builtins are imported at top level. Unit tests import
+ * `convertHeicBufferToJpeg` directly; the bootstrap only runs when spawned
+ * with our `workerData` shape.
+ *
+ * Decompression-bomb guard: heic-decode's `.all` path exposes the
+ * header-declared {width, height} per image WITHOUT decoding pixels, while
+ * its plain decode path allocates `width * height * 4` bytes straight from
+ * those header values — a <1KB crafted file declaring 30000×30000 would
+ * demand a 3.6GB allocation. We reject anything above MAX_HEIC_DECODE_PIXELS
+ * before calling `decode()`.
+ */
+
+import { parentPort, workerData } from 'node:worker_threads';
+
+/** Max header-declared pixel count we will decode (64MP ≈ 256MB RGBA). */
+export const MAX_HEIC_DECODE_PIXELS = 64_000_000;
+
+/** JPEG quality used for converted HEIC uploads (matches heic-convert's default). */
+export const HEIC_JPEG_QUALITY = 0.92;
+
+export interface HeicWorkerInput {
+  heicInput: Uint8Array;
+  quality: number;
+}
+
+export type HeicWorkerResult = { ok: true; data: Uint8Array } | { ok: false; error: string };
+
+/**
+ * Convert HEIC/HEIF bytes to JPEG bytes. Throws on non-HEIC input, empty
+ * containers, over-limit dimensions, and non-JPEG encoder output.
+ */
+export async function convertHeicBufferToJpeg(input: Uint8Array, quality: number = HEIC_JPEG_QUALITY): Promise<Buffer> {
+  const { default: decode } = await import('heic-decode');
+  const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+  const images = await decode.all({ buffer });
+  try {
+    if (images.length === 0) throw new Error('no image found in HEIC container');
+    const { width, height } = images[0];
+    if (
+      !Number.isSafeInteger(width) ||
+      !Number.isSafeInteger(height) ||
+      width <= 0 ||
+      height <= 0 ||
+      width * height > MAX_HEIC_DECODE_PIXELS
+    ) {
+      throw new Error(
+        `HEIC dimensions ${width}x${height} exceed the ${Math.floor(MAX_HEIC_DECODE_PIXELS / 1_000_000)}MP decode limit`
+      );
+    }
+    const decoded = await images[0].decode();
+    const { encode } = await import('jpeg-js');
+    // Same output path as heic-convert's JPEG format (jpeg-js at quality*100).
+    const jpeg = encode(
+      { data: decoded.data, width: decoded.width, height: decoded.height },
+      Math.floor(quality * 100)
+    ).data;
+    const jpegBytes = Buffer.isBuffer(jpeg) ? jpeg : Buffer.from(jpeg);
+    if (jpegBytes.length < 3 || jpegBytes[0] !== 0xff || jpegBytes[1] !== 0xd8 || jpegBytes[2] !== 0xff) {
+      throw new Error('HEIC conversion did not produce JPEG bytes');
+    }
+    return jpegBytes;
+  } finally {
+    images.dispose();
+  }
+}
+
+// ── Worker bootstrap ──────────────────────────────────────────────────────
+// Runs only when spawned by heic-jpeg-converter.ts: requires a parent port
+// AND our exact workerData shape, so importing this module from the main
+// thread (or a test runner's own worker pool) stays inert.
+const request = workerData as HeicWorkerInput | null | undefined;
+if (parentPort && request && request.heicInput instanceof Uint8Array && typeof request.quality === 'number') {
+  const port = parentPort;
+  try {
+    const jpegBytes = await convertHeicBufferToJpeg(request.heicInput, request.quality);
+    port.postMessage({ ok: true, data: jpegBytes } satisfies HeicWorkerResult);
+  } catch (err: unknown) {
+    const error = err instanceof Error ? err.message : String(err);
+    port.postMessage({ ok: false, error } satisfies HeicWorkerResult);
+  }
+}

src/web/routes/session-routes.ts

@@ -54,6 +54,7 @@ import {
 } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { imageWatcher } from '../../image-watcher.js';
+import { convertHeicToJpeg } from '../heic-jpeg-converter.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
 import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
 import { MAX_CONCURRENT_SESSIONS } from '../../config/map-limits.js';
@@ -191,30 +192,18 @@ export function imageMagicMatchesExt(data: Buffer, ext: string): boolean {
       return data[0] === 0x42 && data[1] === 0x4d;
     case '.heic':
     case '.heif': {
-      // ISO Base Media File Format: size + "ftyp" + major brand.
+      // ISO Base Media File Format: size + "ftyp" + major brand. The brand
+      // list matches heic-decode's own isHeic() — accepting more brands here
+      // would only route bytes into a conversion that always throws.
       if (u32be(4) !== 0x66747970) return false;
       const brand = data.subarray(8, 12).toString('ascii');
-      return ['heic', 'heix', 'hevc', 'hevx', 'heim', 'heis', 'hevm', 'hevs', 'mif1', 'msf1'].includes(brand);
+      return ['heic', 'heix', 'hevc', 'hevx', 'mif1', 'msf1'].includes(brand);
     }
     default:
       return false;
   }
 }
 
-async function convertHeicToJpeg(imageBytes: Buffer): Promise<Buffer> {
-  const { default: convert } = await import('heic-convert');
-  const converted = await convert({ buffer: imageBytes, format: 'JPEG', quality: 0.92 });
-  const jpegBytes = Buffer.isBuffer(converted)
-    ? converted
-    : converted instanceof ArrayBuffer
-      ? Buffer.from(converted)
-      : Buffer.from(converted.buffer, converted.byteOffset, converted.byteLength);
-  if (!imageMagicMatchesExt(jpegBytes, '.jpg')) {
-    throw new Error('HEIC conversion did not produce JPEG bytes');
-  }
-  return jpegBytes;
-}
-
 // Per-(IP, sessionId) token bucket for paste-image. 30 requests/minute.
 // Bucket map entries are pruned when they drift > 1h stale to bound memory
 // against a flood of unique IP keys.
@@ -1889,22 +1878,12 @@ export function registerSessionRoutes(
       );
     }
 
-    // Sniff actual bytes — filename and Content-Type are both attacker-supplied.
-    // Polyglot HTML/PNG would otherwise pass and serve back with image/png MIME.
-    if (!imageMagicMatchesExt(imageBytes, ext)) {
-      // Diagnostic: on some Android galleries (e.g. MIUI) a WebP/HEIF is
-      // mislabeled as image/jpeg, so the declared ext passes the allowlist but
-      // the magic bytes do not. Log the real header so format mismatches can be
-      // pinned down without a reproduce-and-guess loop. The client now
-      // re-encodes images to JPEG/PNG before upload, so this should be rare.
-      console.warn(
-        `[paste-image] magic mismatch: filename=${JSON.stringify(part.filename)} mime=${JSON.stringify(part.mimetype)} declaredExt=${ext} magic=${imageBytes.subarray(0, 12).toString('hex')}`
-      );
-      reply.code(415);
-      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Image bytes do not match declared type ${ext}`);
-    }
-
-    if (ext === '.heic' || ext === '.heif') {
+    // Route HEIC on the raw bytes, NOT the declared ext/mime: on some Android
+    // galleries (e.g. MIUI) a HEIF comes back mislabeled as image/jpeg, and
+    // browsers that cannot decode HEIF upload the original file as-is — so a
+    // HEIC payload can arrive under any declared type. Filename and
+    // Content-Type are attacker-supplied anyway; only the bytes are trusted.
+    if (imageMagicMatchesExt(imageBytes, '.heic')) {
       try {
         imageBytes = await convertHeicToJpeg(imageBytes);
         ext = '.jpg';
@@ -1915,6 +1894,16 @@ export function registerSessionRoutes(
         reply.code(415);
         return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Could not convert HEIC image to JPEG');
       }
+    } else if (!imageMagicMatchesExt(imageBytes, ext)) {
+      // Sniff actual bytes — a polyglot HTML/PNG would otherwise pass and
+      // serve back with image/png MIME. Log the real header so format
+      // mismatches can be pinned down without a reproduce-and-guess loop. The
+      // client re-encodes images to JPEG/PNG before upload, so this is rare.
+      console.warn(
+        `[paste-image] magic mismatch: filename=${JSON.stringify(part.filename)} mime=${JSON.stringify(part.mimetype)} declaredExt=${ext} magic=${imageBytes.subarray(0, 12).toString('hex')}`
+      );
+      reply.code(415);
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Image bytes do not match declared type ${ext}`);
     }
 
     // Save to {workingDir}/.claude-images/