@nifrajs/image 0.1.0-alpha.1

package/dist/sign.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Signed image URLs — a portable, **synchronous** HMAC-SHA256 so the (sync) `selfHostedLoader` can sign
+ * URLs inline, on any runtime including the edge (WebCrypto's HMAC is async-only; `node:crypto` isn't on
+ * Workers). A signed URL lets `createImageHandler` reject any `(src, w, q)` it didn't authorize —
+ * shutting down resize-bombing (width/quality enumeration) and locking the endpoint to your own images.
+ *
+ * Pure JS, dependency-free, KAT-tested against the SHA-256 / RFC 4231 HMAC vectors. The secret never
+ * leaves the bytes you pass in.
+ */
+/** HMAC-SHA256 of `message` under `key` (both UTF-8 strings) → lowercase hex. The primitive behind URL
+ * signing; exported for tests (RFC 4231 vectors) and advanced use. */
+export declare function hmacSha256Hex(key: string, message: string): string;
+/** The fields a signature covers. Newline-delimited into a canonical string (newlines can't appear in
+ * a URL query value, so the join is unambiguous). `q`/`exp` are normalized to `""` when absent so the
+ * signer and verifier agree. */
+export interface ImageSignatureParts {
+    readonly src: string;
+    readonly w: string;
+    readonly q?: string | undefined;
+    readonly exp?: string | undefined;
+}
+/** Compute the URL signature (base64url HMAC-SHA256) for a set of image params. Guards (and so does
+ * the verify path, which calls through here) against a sub-256-bit secret. */
+export declare function signImageParams(secret: string, parts: ImageSignatureParts): string;
+/**
+ * Verify a request's signature against `secret` (constant-time) and, when an `exp` is present, that it
+ * hasn't passed `nowSeconds`. Returns `false` for a missing/forged/expired signature.
+ */
+export declare function verifyImageParams(secret: string, parts: ImageSignatureParts, signature: string, nowSeconds: number): boolean;
+//# sourceMappingURL=sign.d.ts.map

package/dist/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgHH;sEACsE;AACtE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAiBD;;gCAEgC;AAChC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;IAGlB,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAClC;AASD;8EAC8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAOlF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,mBAAmB,EAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAMT"}

package/dist/sign.js

@@ -0,0 +1,161 @@
+/**
+ * Signed image URLs — a portable, **synchronous** HMAC-SHA256 so the (sync) `selfHostedLoader` can sign
+ * URLs inline, on any runtime including the edge (WebCrypto's HMAC is async-only; `node:crypto` isn't on
+ * Workers). A signed URL lets `createImageHandler` reject any `(src, w, q)` it didn't authorize —
+ * shutting down resize-bombing (width/quality enumeration) and locking the endpoint to your own images.
+ *
+ * Pure JS, dependency-free, KAT-tested against the SHA-256 / RFC 4231 HMAC vectors. The secret never
+ * leaves the bytes you pass in.
+ */
+// FIPS 180-4 SHA-256 round constants.
+// biome-ignore format: the 64 constants read best as an 8×8 grid.
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotr = (x, n) => ((x >>> n) | (x << (32 - n))) >>> 0;
+/** SHA-256 of a byte array → 32-byte digest. */
+function sha256(data) {
+    const len = data.length;
+    const bitLen = len * 8;
+    // Pad: 0x80, then zeros, so the total is ≡ 56 (mod 64), then the 64-bit big-endian bit length.
+    const padded = (56 - ((len + 1) % 64) + 64) % 64;
+    const total = len + 1 + padded + 8;
+    const msg = new Uint8Array(total);
+    msg.set(data);
+    msg[len] = 0x80;
+    const dv = new DataView(msg.buffer);
+    dv.setUint32(total - 8, Math.floor(bitLen / 0x1_0000_0000)); // high word (0 for our sizes)
+    dv.setUint32(total - 4, bitLen >>> 0);
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let off = 0; off < total; off += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = dv.getUint32(off + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const a = w[i - 15];
+            const b = w[i - 2];
+            const s0 = (rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3)) >>> 0;
+            const s1 = (rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10)) >>> 0;
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let hh = h[7];
+        for (let i = 0; i < 64; i++) {
+            const s1 = (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) >>> 0;
+            const ch = ((e & f) ^ (~e & g)) >>> 0;
+            const t1 = (hh + s1 + ch + K[i] + w[i]) >>> 0;
+            const s0 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) >>> 0;
+            const maj = ((a & b) ^ (a & c) ^ (b & c)) >>> 0;
+            const t2 = (s0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + hh) >>> 0;
+    }
+    const out = new Uint8Array(32);
+    const odv = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++)
+        odv.setUint32(i * 4, h[i]);
+    return out;
+}
+const BLOCK = 64;
+/** HMAC-SHA256 (RFC 2104) of `message` under `key` → 32-byte tag. */
+function hmacSha256(key, message) {
+    let k = key.length > BLOCK ? sha256(key) : key;
+    if (k.length < BLOCK) {
+        const padded = new Uint8Array(BLOCK);
+        padded.set(k);
+        k = padded;
+    }
+    const inner = new Uint8Array(BLOCK + message.length);
+    const outer = new Uint8Array(BLOCK + 32);
+    for (let i = 0; i < BLOCK; i++) {
+        inner[i] = k[i] ^ 0x36;
+        outer[i] = k[i] ^ 0x5c;
+    }
+    inner.set(message, BLOCK);
+    outer.set(sha256(inner), BLOCK);
+    return sha256(outer);
+}
+const encoder = new TextEncoder();
+const hex = (bytes) => {
+    let s = "";
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, "0");
+    return s;
+};
+/** HMAC-SHA256 of `message` under `key` (both UTF-8 strings) → lowercase hex. The primitive behind URL
+ * signing; exported for tests (RFC 4231 vectors) and advanced use. */
+export function hmacSha256Hex(key, message) {
+    return hex(hmacSha256(encoder.encode(key), encoder.encode(message)));
+}
+/** base64url (RFC 4648 §5, unpadded) of a byte array — URL-safe, compact (43 chars for a 32-byte tag). */
+function base64url(bytes) {
+    let binary = "";
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Constant-time string compare — length-independent of where the first difference is. */
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+const canonical = (p) => `${p.src}\n${p.w}\n${p.q ?? ""}\n${p.exp ?? ""}`;
+// 256-bit secret floor — mirrors @nifrajs/core's HMAC guard. This package is dependency-free (ships
+// its own SHA-256), so the constant is inlined rather than imported.
+const MIN_SECRET_BYTES = 32;
+/** Compute the URL signature (base64url HMAC-SHA256) for a set of image params. Guards (and so does
+ * the verify path, which calls through here) against a sub-256-bit secret. */
+export function signImageParams(secret, parts) {
+    if (encoder.encode(secret).length < MIN_SECRET_BYTES) {
+        throw new Error(`[nifra/image] signing secret must be at least ${MIN_SECRET_BYTES} bytes (256-bit). Generate one with: openssl rand -base64 32`);
+    }
+    return base64url(hmacSha256(encoder.encode(secret), encoder.encode(canonical(parts))));
+}
+/**
+ * Verify a request's signature against `secret` (constant-time) and, when an `exp` is present, that it
+ * hasn't passed `nowSeconds`. Returns `false` for a missing/forged/expired signature.
+ */
+export function verifyImageParams(secret, parts, signature, nowSeconds) {
+    if (parts.exp !== undefined) {
+        if (!/^\d+$/.test(parts.exp))
+            return false;
+        if (Number(parts.exp) < nowSeconds)
+            return false; // expired
+    }
+    return safeEqual(signImageParams(secret, parts), signature);
+}
+//# sourceMappingURL=sign.js.map

package/dist/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@nifrajs/image",
+  "version": "0.1.0-alpha.1",
+  "description": "Image optimization for nifra — a CLS-safe responsive <Image> + pluggable loaders (CDN or self-hosted) + pure-JS dimension reading. Zero-dependency core; optional Bun.Image-backed resize endpoint at @nifrajs/image/server.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "bun": "./src/server.ts",
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./backends": {
+      "bun": "./src/backend.ts",
+      "types": "./dist/backend.d.ts",
+      "default": "./dist/backend.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/image"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/backend.ts

@@ -0,0 +1,273 @@
+/**
+ * `@nifrajs/image/backends` — the codec seam + the official {@link ImageBackend} implementations, kept
+ * **dependency-free and edge-safe** (no `node:` imports), so the WASM backend can run on Workers /
+ * Vercel-Edge / Deno-Deploy. `createImageHandler` (in `@nifrajs/image/server`, Node-only — it touches the
+ * filesystem) consumes this seam and owns all request-level security; a backend only
+ * decodes/resizes/encodes and translates codec failures into {@link ImageProcessingError}.
+ *
+ * Pick a backend for your runtime:
+ * - {@link bunImageBackend} — `Bun.Image` (libjpeg-turbo / libspng / libwebp). Bun servers.
+ * - {@link sharpImageBackend} — pass your `sharp` import. Node servers.
+ * - {@link wasmImageBackend} — pass WASM codecs (e.g. jSquash). Any runtime, including the edge.
+ */
+
+import { imageDimensions } from "./dimensions.ts"
+
+/** Output formats nifra's endpoint can emit. AVIF is intentionally excluded — `Bun.Image` reports
+ * `ERR_IMAGE_FORMAT_UNSUPPORTED` for AVIF encode on common platforms, so offering it would 500. */
+export type OutputFormat = "webp" | "jpeg" | "png"
+
+export const CONTENT_TYPE: Record<OutputFormat, string> = {
+  webp: "image/webp",
+  jpeg: "image/jpeg",
+  png: "image/png",
+}
+
+/** Header-only probe of a source image: intrinsic dimensions + decoded format. Must be cheap (no full
+ * decode) — it gates the decompression-bomb and no-upscale checks before the expensive resize. */
+export interface ImageProbe {
+  readonly width: number
+  readonly height: number
+  /** Lowercased source format as the codec sees it (`"png"`, `"jpeg"`, `"webp"`, `"gif"`, …). */
+  readonly format: string
+}
+
+export interface ResizeInput {
+  readonly bytes: Uint8Array
+  /** Target width in px — already clamped to `[1, maxWidth]` **and** to the source's intrinsic width
+   * (the handler never asks a backend to upscale). Aspect ratio is preserved. */
+  readonly width: number
+  /** Encoder quality `1..100` (ignored for lossless `png`). */
+  readonly quality: number
+  readonly format: OutputFormat
+}
+
+export interface ResizeOutput {
+  readonly bytes: Uint8Array
+  readonly contentType: string
+  readonly format: OutputFormat
+}
+
+/**
+ * The codec seam. The handler owns all request-level security (validation, SSRF, byte/pixel caps,
+ * concurrency, caching); a backend only decodes/resizes/encodes. Backends MUST translate codec failures
+ * into {@link ImageProcessingError} so the handler can map them to stable HTTP statuses.
+ */
+export interface ImageBackend {
+  /** Cheap, header-only metadata read. Throws {@link ImageProcessingError} (`decode` / `too_large`). */
+  probe(bytes: Uint8Array): Promise<ImageProbe>
+  /** Decode → resize to `input.width` (aspect-preserving) → encode to `input.format`. */
+  transform(input: ResizeInput): Promise<ResizeOutput>
+}
+
+/** Normalized, backend-agnostic processing failure. Lets the handler map codec errors to HTTP status
+ * without coupling to any one codec's error codes. */
+export class ImageProcessingError extends Error {
+  constructor(
+    readonly kind: "decode" | "too_large" | "unsupported",
+    message: string,
+  ) {
+    super(message)
+    this.name = "ImageProcessingError"
+  }
+}
+
+// --- Bun.Image backend -------------------------------------------------------------------------------
+
+/** Minimal structural type for the `Bun.Image` surface this backend uses (avoids a hard Bun type dep). */
+interface BunImageCtor {
+  new (
+    input: Uint8Array,
+  ): {
+    metadata(): Promise<{ width: number; height: number; format: string }>
+    resize(width: number): BunImageChain
+  }
+}
+interface BunImageChain {
+  webp(opts: { quality: number }): { bytes(): Promise<Uint8Array> }
+  jpeg(opts: { quality: number }): { bytes(): Promise<Uint8Array> }
+  png(): { bytes(): Promise<Uint8Array> }
+}
+
+/**
+ * {@link ImageBackend} backed by `Bun.Image` (libjpeg-turbo / libspng / libwebp, decoded off the main
+ * thread). Requires the Bun runtime. The default backend of `createImageHandler`.
+ */
+export function bunImageBackend(): ImageBackend {
+  if (typeof (globalThis as { Bun?: unknown }).Bun === "undefined") {
+    throw new Error("[nifra/image] bunImageBackend() requires the Bun runtime")
+  }
+  const Image = (globalThis as unknown as { Bun: { Image: BunImageCtor } }).Bun.Image
+  return {
+    async probe(bytes) {
+      try {
+        const md = await new Image(bytes).metadata()
+        return { width: md.width, height: md.height, format: String(md.format).toLowerCase() }
+      } catch (err) {
+        throw toBunError(err)
+      }
+    },
+    async transform({ bytes, width, quality, format }) {
+      try {
+        const img = new Image(bytes).resize(width)
+        const encoded =
+          format === "webp"
+            ? img.webp({ quality })
+            : format === "jpeg"
+              ? img.jpeg({ quality })
+              : img.png()
+        const out = await encoded.bytes()
+        return { bytes: out, contentType: CONTENT_TYPE[format], format }
+      } catch (err) {
+        throw toBunError(err)
+      }
+    },
+  }
+}
+
+/** Map a `Bun.Image` failure to a normalized {@link ImageProcessingError}. */
+function toBunError(err: unknown): ImageProcessingError {
+  if (err instanceof ImageProcessingError) return err
+  const code = (err as { code?: string } | null)?.code ?? ""
+  if (code === "ERR_IMAGE_TOO_MANY_PIXELS") {
+    return new ImageProcessingError("too_large", "source image exceeds the codec pixel limit")
+  }
+  if (code === "ERR_IMAGE_FORMAT_UNSUPPORTED") {
+    return new ImageProcessingError("unsupported", "image format not supported by the codec")
+  }
+  return new ImageProcessingError("decode", "source is not a decodable image")
+}
+
+// --- sharp backend (Node) ----------------------------------------------------------------------------
+
+/** The slice of a [sharp](https://sharp.pixelplumbing.com) instance this backend uses. Declared
+ * structurally so `@nifrajs/image` has no dependency on sharp — pass your own `sharp` import. */
+export type SharpLike = (input: Uint8Array) => SharpInstance
+interface SharpInstance {
+  metadata(): Promise<{ width?: number; height?: number; format?: string }>
+  resize(options: { width: number; withoutEnlargement?: boolean }): SharpInstance
+  webp(options: { quality: number }): SharpInstance
+  jpeg(options: { quality: number }): SharpInstance
+  png(): SharpInstance
+  toBuffer(): Promise<Uint8Array>
+}
+
+/**
+ * {@link ImageBackend} backed by [sharp](https://sharp.pixelplumbing.com) (libvips) for Node servers.
+ * Pass your `sharp` import — `@nifrajs/image` never imports it, so it stays dependency-free and you control
+ * the version:
+ *
+ * ```ts
+ * import sharp from "sharp"
+ * createImageHandler({ backend: sharpImageBackend(sharp), root: "./public" })
+ * ```
+ */
+export function sharpImageBackend(sharp: SharpLike): ImageBackend {
+  return {
+    async probe(bytes) {
+      try {
+        const md = await sharp(bytes).metadata()
+        if (md.width === undefined || md.height === undefined) {
+          throw new ImageProcessingError("decode", "sharp could not read image dimensions")
+        }
+        return { width: md.width, height: md.height, format: String(md.format ?? "").toLowerCase() }
+      } catch (err) {
+        throw toSharpError(err)
+      }
+    },
+    async transform({ bytes, width, quality, format }) {
+      try {
+        // `withoutEnlargement` is belt-and-braces: the handler already clamps width ≤ intrinsic.
+        const pipeline = sharp(bytes).resize({ width, withoutEnlargement: true })
+        const encoded =
+          format === "webp"
+            ? pipeline.webp({ quality })
+            : format === "jpeg"
+              ? pipeline.jpeg({ quality })
+              : pipeline.png()
+        return { bytes: await encoded.toBuffer(), contentType: CONTENT_TYPE[format], format }
+      } catch (err) {
+        throw toSharpError(err)
+      }
+    },
+  }
+}
+
+/** Map a sharp failure to a normalized {@link ImageProcessingError} by its message. */
+function toSharpError(err: unknown): ImageProcessingError {
+  if (err instanceof ImageProcessingError) return err
+  const message = (err instanceof Error ? err.message : "").toLowerCase()
+  if (message.includes("pixel limit") || message.includes("too large")) {
+    return new ImageProcessingError("too_large", "source image exceeds sharp's pixel limit")
+  }
+  if (message.includes("unsupported image format") || message.includes("bad seek")) {
+    return new ImageProcessingError("decode", "sharp could not decode the source image")
+  }
+  return new ImageProcessingError("decode", "sharp failed to process the image")
+}
+
+// --- WASM backend (edge-portable) --------------------------------------------------------------------
+
+/** A decoded image: RGBA pixels + dimensions — the lingua franca of WASM codecs (jSquash, Photon, …). */
+export interface DecodedImage {
+  /** RGBA bytes, length `width * height * 4`. */
+  readonly data: Uint8Array
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * Pluggable WASM codec set — decode/resize/encode. Declared structurally so `@nifrajs/image` depends on no
+ * WASM library; wire your own (jSquash is the common pure-WASM, edge-safe choice). The handler probes
+ * dimensions from the source header (bomb-safe), so `decode` runs only inside `transform`.
+ */
+export interface WasmImageCodecs {
+  /** Decode any supported encoded image → RGBA. Throw on undecodable input. */
+  decode(bytes: Uint8Array): Promise<DecodedImage> | DecodedImage
+  /** Resize RGBA to the target dimensions (the handler keeps the aspect ratio). */
+  resize(image: DecodedImage, width: number, height: number): Promise<DecodedImage> | DecodedImage
+  /** Encode RGBA → the target format's bytes. */
+  encode(
+    image: DecodedImage,
+    format: OutputFormat,
+    quality: number,
+  ): Promise<Uint8Array> | Uint8Array
+}
+
+/**
+ * {@link ImageBackend} backed by injected WASM codecs — the only backend that runs on the **edge**
+ * (Workers / Vercel-Edge / Deno-Deploy), where neither `Bun.Image` nor sharp exists. `probe` reads the
+ * source header via nifra's dependency-free reader (so decompression bombs are rejected before any
+ * decode); `transform` decodes → resizes (aspect-preserving) → encodes through your codecs.
+ *
+ * ```ts
+ * import decode from "@jsquash/jpeg/decode"; import resize from "@jsquash/resize"
+ * import encodeWebp from "@jsquash/webp/encode" // …+ png/jpeg encoders
+ * const backend = wasmImageBackend({ decode, resize: (img, w, h) => resize(img, { width: w, height: h }), encode })
+ * ```
+ */
+export function wasmImageBackend(codecs: WasmImageCodecs): ImageBackend {
+  return {
+    async probe(bytes) {
+      const info = imageDimensions(bytes) // header-only — never allocates a decoded buffer
+      if (info === null) {
+        throw new ImageProcessingError("decode", "unrecognized image header")
+      }
+      return { width: info.width, height: info.height, format: info.format }
+    },
+    async transform({ bytes, width, quality, format }) {
+      try {
+        const decoded = await codecs.decode(bytes)
+        // Aspect-preserving: the handler hands a width already clamped to the intrinsic width.
+        const height = Math.max(1, Math.round((decoded.height * width) / decoded.width))
+        const resized =
+          width === decoded.width ? decoded : await codecs.resize(decoded, width, height)
+        const out = await codecs.encode(resized, format, quality)
+        return { bytes: out, contentType: CONTENT_TYPE[format], format }
+      } catch (err) {
+        if (err instanceof ImageProcessingError) throw err
+        throw new ImageProcessingError("decode", "wasm codec failed to process the image")
+      }
+    },
+  }
+}

package/src/dimensions.ts

@@ -0,0 +1,129 @@
+/**
+ * Read an image's intrinsic dimensions from its file **header**, in pure JS — no decode, no codec, no
+ * dependency. Supports PNG, JPEG, GIF, and WebP (VP8/VP8L/VP8X). Used to give `<Image>` CLS-safe
+ * `width`/`height` (build-time tooling can pre-read them into a manifest).
+ */
+export type ImageFormat = "png" | "jpeg" | "gif" | "webp"
+
+export interface ImageInfo {
+  readonly width: number
+  readonly height: number
+  readonly format: ImageFormat
+}
+
+const png = (b: Uint8Array, dv: DataView): ImageInfo | null => {
+  // 8-byte signature, then IHDR (length+type), then width/height as big-endian uint32 @16/@20.
+  if (b.length < 24 || b[0] !== 0x89 || b[1] !== 0x50 || b[2] !== 0x4e || b[3] !== 0x47) return null
+  return { width: dv.getUint32(16), height: dv.getUint32(20), format: "png" }
+}
+
+const gif = (b: Uint8Array, dv: DataView): ImageInfo | null => {
+  // 'GIF', then the logical-screen width/height as little-endian uint16 @6/@8.
+  if (b.length < 10 || b[0] !== 0x47 || b[1] !== 0x49 || b[2] !== 0x46) return null
+  return { width: dv.getUint16(6, true), height: dv.getUint16(8, true), format: "gif" }
+}
+
+const jpeg = (b: Uint8Array, dv: DataView): ImageInfo | null => {
+  if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8) return null
+  let offset = 2
+  while (offset + 9 < b.length) {
+    if (dv.getUint8(offset) !== 0xff) return null // not aligned on a marker → malformed
+    const marker = dv.getUint8(offset + 1)
+    // SOF0..SOF15 carry the frame's height/width — except DHT(c4)/DNL(c8)/DAC(cc).
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      return { height: dv.getUint16(offset + 5), width: dv.getUint16(offset + 7), format: "jpeg" }
+    }
+    offset += 2 + dv.getUint16(offset + 2) // skip this segment (2-byte marker + segment length)
+  }
+  return null
+}
+
+const webp = (b: Uint8Array, dv: DataView): ImageInfo | null => {
+  // 'RIFF' .... 'WEBP' then a VP8 / VP8L / VP8X chunk.
+  if (b.length < 30 || b[0] !== 0x52 || b[1] !== 0x49 || b[8] !== 0x57 || b[9] !== 0x45) return null
+  const chunk = String.fromCharCode(
+    b[12] as number,
+    b[13] as number,
+    b[14] as number,
+    b[15] as number,
+  )
+  if (chunk === "VP8 ") {
+    // lossy: 14-bit width/height (little-endian) at @26/@28, masked to 14 bits.
+    return {
+      width: dv.getUint16(26, true) & 0x3fff,
+      height: dv.getUint16(28, true) & 0x3fff,
+      format: "webp",
+    }
+  }
+  if (chunk === "VP8L") {
+    // lossless: after the 0x2f signature @20, 14-bit (width-1) then 14-bit (height-1), bit-packed LE.
+    if (b[20] !== 0x2f) return null
+    const bits = dv.getUint32(21, true)
+    return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1, format: "webp" }
+  }
+  if (chunk === "VP8X") {
+    // extended: 24-bit (width-1) then 24-bit (height-1), little-endian, at @24/@27.
+    const w = (b[24] as number) | ((b[25] as number) << 8) | ((b[26] as number) << 16)
+    const h = (b[27] as number) | ((b[28] as number) << 8) | ((b[29] as number) << 16)
+    return { width: w + 1, height: h + 1, format: "webp" }
+  }
+  return null
+}
+
+/** Parse intrinsic dimensions + format from image header bytes, or `null` if unrecognized/too short. */
+export function imageDimensions(bytes: Uint8Array): ImageInfo | null {
+  if (bytes.length < 4) return null
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  return png(bytes, dv) ?? gif(bytes, dv) ?? jpeg(bytes, dv) ?? webp(bytes, dv)
+}
+
+/**
+ * Read just the leading bytes of an image file (via the platform `Bun.file`/`fetch` blob) and parse its
+ * dimensions. Build-time tooling: pre-read dimensions into a manifest so `<Image>` is CLS-safe without
+ * hardcoding sizes. Reads at most `maxBytes` (default 64 KB — enough for any header).
+ */
+export async function readImageDimensions(
+  source: { arrayBuffer(): Promise<ArrayBuffer>; stream?: () => ReadableStream<Uint8Array> },
+  maxBytes = 65_536,
+): Promise<ImageInfo | null> {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+    throw new Error("[nifra/image] readImageDimensions: maxBytes must be a positive safe integer")
+  }
+  if (source.stream !== undefined) {
+    const reader = source.stream().getReader()
+    const chunks: Uint8Array[] = []
+    let total = 0
+    let reachedEof = false
+    try {
+      while (total < maxBytes) {
+        const { done, value } = await reader.read()
+        if (done) {
+          reachedEof = true
+          break
+        }
+        const remaining = maxBytes - total
+        const chunk = value.byteLength > remaining ? value.subarray(0, remaining) : value
+        chunks.push(chunk)
+        total += chunk.byteLength
+        if (value.byteLength > remaining) {
+          await reader.cancel()
+          reachedEof = true
+          break
+        }
+      }
+      if (!reachedEof) await reader.cancel()
+    } finally {
+      reader.releaseLock()
+    }
+    const bytes = new Uint8Array(total)
+    let offset = 0
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+    return imageDimensions(bytes)
+  }
+  const buf = await source.arrayBuffer()
+  const bytes = new Uint8Array(buf)
+  return imageDimensions(bytes.length > maxBytes ? bytes.subarray(0, maxBytes) : bytes)
+}