@cosmicdrift/kumiko-bundled-features 0.286.0 → 0.287.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.286.0",
+  "version": "0.287.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -94,6 +94,8 @@
     "./auth-email-password/testing": "./src/auth-email-password/testing.ts",
     "./auth-email-password/web": "./src/auth-email-password/web/index.ts",
     "./shared/single-use-token-store": "./src/shared/single-use-token-store.ts",
+    "./shared/signed-token": "./src/shared/signed-token.ts",
+    "./shared/row-bound-grant": "./src/shared/row-bound-grant.ts",
     "./delivery": "./src/delivery/index.ts",
     "./delivery/web": "./src/delivery/web/index.ts",
     "./channel-in-app": "./src/channel-in-app/index.ts",
@@ -130,12 +132,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.286.0",
-    "@cosmicdrift/kumiko-framework": "0.286.0",
-    "@cosmicdrift/kumiko-headless": "0.286.0",
-    "@cosmicdrift/kumiko-renderer": "0.286.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.286.0",
-    "@cosmicdrift/kumiko-types": "0.286.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.287.0",
+    "@cosmicdrift/kumiko-framework": "0.287.0",
+    "@cosmicdrift/kumiko-headless": "0.287.0",
+    "@cosmicdrift/kumiko-renderer": "0.287.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.287.0",
+    "@cosmicdrift/kumiko-types": "0.287.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +166,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.286.0",
-    "@cosmicdrift/kumiko-locale-es": "0.286.0"
+    "@cosmicdrift/kumiko-locale-de": "0.287.0",
+    "@cosmicdrift/kumiko-locale-es": "0.287.0",
+    "jsqr": "^1.4.0"
   }
 }

package/src/auth-email-password/signed-token.ts

@@ -1,86 +1,4 @@
-// HMAC-signed single-purpose tokens for out-of-band auth flows
-// (password-reset, email-verification, future: magic-link).
-//
-// Format: <userId>.<expiresAtMs>.<hmac-base64url>
-//
-// The `purpose` is mixed INTO the HMAC input so a token minted for one
-// purpose (e.g. password-reset) can't be replayed against an endpoint that
-// expects another (e.g. verify-email), even if the caller knows the
-// userId and a valid expiry. Purpose is NOT carried in the token body —
-// verify() takes the purpose as argument and recomputes.
-//
-// Timing-safe comparison on verify so a valid-length forgery can't leak
-// signal through a short-circuit.
-
-import { createHmac, timingSafeEqual } from "node:crypto";
-import { Temporal } from "temporal-polyfill";
-
-export type VerifyResult =
-  | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
-  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
-
-function sign(input: string, secret: string): string {
-  return createHmac("sha256", secret).update(input).digest("base64url");
-}
-
-function payload(purpose: string, userId: string, expiresAtMs: number): string {
-  return `${purpose}:${userId}.${expiresAtMs}`;
-}
-
-export function signToken(
-  userId: string,
-  purpose: string,
-  ttlMinutes: number,
-  secret: string,
-  now: Temporal.Instant = Temporal.Now.instant(),
-): { token: string; expiresAt: Temporal.Instant } {
-  const expiresAt = now.add({ minutes: ttlMinutes });
-  const expiresAtMs = expiresAt.epochMilliseconds;
-  const signature = sign(payload(purpose, userId, expiresAtMs), secret);
-  return {
-    token: `${userId}.${expiresAtMs}.${signature}`,
-    expiresAt,
-  };
-}
-
-export function verifyToken(
-  token: string,
-  purpose: string,
-  secret: string,
-  now: Temporal.Instant = Temporal.Now.instant(),
-): VerifyResult {
-  const parts = token.split(".");
-  if (parts.length !== 3) return { ok: false, reason: "malformed" };
-  const [userId, expiresAtRaw, providedSig] = parts;
-  if (!userId || !expiresAtRaw || !providedSig) return { ok: false, reason: "malformed" };
-
-  const expiresAtMs = Number(expiresAtRaw);
-  if (!Number.isFinite(expiresAtMs) || String(expiresAtMs) !== expiresAtRaw) {
-    return { ok: false, reason: "malformed" };
-  }
-
-  const expected = sign(payload(purpose, userId, expiresAtMs), secret);
-  const expectedBuf = Buffer.from(expected, "base64url");
-  const providedBuf = Buffer.from(providedSig, "base64url");
-  // Length mismatch fails BEFORE timingSafeEqual, which throws on different
-  // lengths — but that throw itself leaks via timing. Explicit length check
-  // keeps the path uniform.
-  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
-  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
-
-  if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(expiresAtMs)) > 0) {
-    return { ok: false, reason: "expired" };
-  }
-
-  // expiresAtMs surfaces so callers (burn-store TTL, telemetry, …) don't
-  // have to re-parse the token themselves.
-  return { ok: true, userId, expiresAtMs };
-}
-
-// Canonical purposes baked into the framework. Features that introduce new
-// flows extend this set (or just pass an inline string).
-export const TokenPurpose = {
-  passwordReset: "reset",
-  emailVerification: "verify",
-  accountUnlock: "unlock",
-} as const;
+// Moved to shared/signed-token.ts — the mechanism was never specific to
+// email/password auth (user-data-rights and any row-bound grant use it too).
+// Re-exported so this feature's barrel and external importers keep working.
+export * from "../shared/signed-token";

package/src/derivatives-sharp/__tests__/render.test.ts

@@ -2,7 +2,11 @@
 // `sharp({ create: {...} })` so every case decodes real bytes end-to-end.
 
 import { describe, expect, test } from "bun:test";
-import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type {
+  ResolvedOverlayLayer,
+  VariantSpec,
+} from "@cosmicdrift/kumiko-types/derivatives-types";
+import jsQR from "jsqr";
 import sharp from "sharp";
 import { imageMetadata, renderImage } from "../render";
 
@@ -285,6 +289,247 @@ describe("renderImage — validation", () => {
   });
 });
 
+// jsQR needs a plain RGBA buffer, not sharp's own metadata/format handling —
+// this is the one test proving the AC ("readable with a phone camera") for
+// real: a pixel/byte-presence check would only prove placement, not that the
+// QR survives resize + a lossy re-encode.
+async function decodeQr(buffer: Uint8Array): Promise<string | null> {
+  const { data, info } = await sharp(buffer)
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const result = jsQR(new Uint8ClampedArray(data), info.width, info.height);
+  return result?.data ?? null;
+}
+
+async function tinyImageOverlayBase64(
+  width: number,
+  height: number,
+  color: { r: number; g: number; b: number },
+): Promise<string> {
+  const buffer = await sharp({ create: { width, height, channels: 3, background: color } })
+    .png()
+    .toBuffer();
+  return buffer.toString("base64");
+}
+
+describe("renderImage — overlays", () => {
+  test("a qr overlay is actually scannable after resize + a lossy re-encode", async () => {
+    const input = await jpegFixture(800, 800);
+    const layer: ResolvedOverlayLayer = {
+      kind: "qr",
+      data: "https://example.com/v/abc123",
+      widthPct: 0.4,
+      gravity: "south-east",
+    };
+
+    const output = await renderImage(
+      input,
+      { maxEdge: 400, format: "webp", resolvedOverlays: [layer] },
+      "image/jpeg",
+    );
+
+    expect(await decodeQr(output)).toBe("https://example.com/v/abc123");
+  });
+
+  test("an unresolved `overlays` field is inert for the renderer — only `resolvedOverlays` composites", async () => {
+    const input = await jpegFixture(400, 400);
+    const spec: VariantSpec = {
+      overlays: [{ kind: "qr", dataToken: "vehicle-1", widthPct: 0.4, gravity: "center" }],
+    };
+
+    const output = await renderImage(input, spec, "image/jpeg");
+    const baseline = await renderImage(input, {}, "image/jpeg");
+    expect(Buffer.compare(output, baseline)).toBe(0);
+  });
+
+  test("the overlay width is the same fraction of the output at two different aspect ratios", async () => {
+    // PNG in and out (spec.format unset preserves the source format) — the
+    // fraction assertion below needs exact pixel equality, which a lossy
+    // jpeg re-encode wouldn't guarantee.
+    const input = await pngFixture(800, 800, { r: 250, g: 250, b: 250 });
+    const overlayColor = { r: 10, g: 200, b: 10 };
+    const imageBase64 = await tinyImageOverlayBase64(40, 40, overlayColor);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64,
+      widthPct: 0.25,
+      gravity: "south-east",
+    };
+
+    async function overlayPixelWidth(width: number, height: number): Promise<number> {
+      const output = await renderImage(
+        input,
+        { size: { width, height }, fit: "cover", resolvedOverlays: [layer] },
+        "image/png",
+      );
+      const { data, info } = await sharp(output).raw().toBuffer({ resolveWithObject: true });
+      const y = height - 1;
+      for (let x = 0; x < width; x++) {
+        const offset = (y * info.width + x) * info.channels;
+        if (
+          data[offset] === overlayColor.r &&
+          data[offset + 1] === overlayColor.g &&
+          data[offset + 2] === overlayColor.b
+        ) {
+          return width - x;
+        }
+      }
+      throw new Error("overlay color not found in bottom row");
+    }
+
+    expect(await overlayPixelWidth(640, 360)).toBe(Math.round(640 * 0.25));
+    expect(await overlayPixelWidth(400, 400)).toBe(Math.round(400 * 0.25));
+  });
+
+  test("a square overlay on a wide output is clamped to the output height instead of overrunning it", async () => {
+    // widthPct alone would ask for an 800x800 layer (aspect-preserved from a
+    // square source) on a 1600x400 output — taller than the base image, which
+    // sharp's composite() rejects unless the resize also bounds height.
+    const outputWidth = 1600;
+    const outputHeight = 400;
+    const input = await pngFixture(outputWidth, outputHeight, { r: 250, g: 250, b: 250 });
+    const overlayColor = { r: 10, g: 200, b: 10 };
+    const imageBase64 = await tinyImageOverlayBase64(100, 100, overlayColor);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64,
+      widthPct: 0.5,
+      gravity: "center",
+    };
+
+    const output = await renderImage(input, { resolvedOverlays: [layer] }, "image/png");
+    const { data, info } = await sharp(output).raw().toBuffer({ resolveWithObject: true });
+
+    const centerX = Math.floor(info.width / 2);
+    let minY = info.height;
+    let maxY = -1;
+    for (let y = 0; y < info.height; y++) {
+      const offset = (y * info.width + centerX) * info.channels;
+      if (
+        data[offset] === overlayColor.r &&
+        data[offset + 1] === overlayColor.g &&
+        data[offset + 2] === overlayColor.b
+      ) {
+        minY = Math.min(minY, y);
+        maxY = Math.max(maxY, y);
+      }
+    }
+
+    expect(maxY).toBeGreaterThan(-1);
+    expect(maxY - minY + 1).toBeLessThanOrEqual(outputHeight);
+  });
+
+  test("an SVG overlay layer is rejected the same way a source SVG is", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64: Buffer.from(SVG_BYTES).toString("base64"),
+      widthPct: 0.3,
+      gravity: "center",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /svg/i,
+    );
+  });
+
+  test("more than MAX_OVERLAY_LAYERS throws instead of decoding+resizing each one", async () => {
+    const input = await jpegFixture(200, 200);
+    const overlays: ResolvedOverlayLayer[] = Array.from({ length: 9 }, () => ({
+      kind: "image",
+      imageBase64: "",
+      widthPct: 0.1,
+      gravity: "center",
+    }));
+
+    await expect(renderImage(input, { resolvedOverlays: overlays }, "image/jpeg")).rejects.toThrow(
+      /overlays has 9 entries/,
+    );
+  });
+
+  test("widthPct outside (0, 1] throws", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64: await tinyImageOverlayBase64(10, 10, { r: 1, g: 1, b: 1 }),
+      widthPct: 1.5,
+      gravity: "center",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /widthPct/,
+    );
+  });
+
+  test("marginPct outside [0, 0.5) throws", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64: await tinyImageOverlayBase64(10, 10, { r: 1, g: 1, b: 1 }),
+      widthPct: 0.2,
+      marginPct: 0.5,
+      gravity: "north-west",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /marginPct/,
+    );
+  });
+
+  test("a qr data length beyond MAX_QR_DATA_LENGTH throws", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "qr",
+      data: "x".repeat(1025),
+      widthPct: 0.3,
+      gravity: "center",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /qr overlay data length/,
+    );
+  });
+
+  test("an empty qr data throws instead of encoding an empty QR", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = { kind: "qr", data: "", widthPct: 0.3, gravity: "center" };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /qr overlay data length/,
+    );
+  });
+
+  test("an overlay image beyond MAX_OVERLAY_IMAGE_BYTES throws", async () => {
+    const input = await jpegFixture(200, 200);
+    const oversized = Buffer.alloc(513 * 1024, 1).toString("base64");
+    const layer: ResolvedOverlayLayer = {
+      kind: "image",
+      imageBase64: oversized,
+      widthPct: 0.3,
+      gravity: "center",
+    };
+
+    await expect(renderImage(input, { resolvedOverlays: [layer] }, "image/jpeg")).rejects.toThrow(
+      /overlay image is/,
+    );
+  });
+
+  test("a qr overlay that would render below MIN_QR_PIXEL_WIDTH throws instead of caching an unscannable image", async () => {
+    const input = await jpegFixture(200, 200);
+    const layer: ResolvedOverlayLayer = {
+      kind: "qr",
+      data: "https://example.com/v/abc123",
+      widthPct: 0.05,
+      gravity: "center",
+    };
+
+    await expect(
+      renderImage(input, { maxEdge: 200, resolvedOverlays: [layer] }, "image/jpeg"),
+    ).rejects.toThrow(/below the 160px minimum/);
+  });
+});
+
 describe("imageMetadata", () => {
   test("returns width/height/format", async () => {
     const input = await jpegFixture(320, 240);

package/src/derivatives-sharp/changes.json

@@ -1 +1,8 @@
-[]
+[
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "Render overlay layers (QR codes, badge images) onto image variants",
+    "detail": "The sharp renderer composites resolved overlay layers after resize and before final encoding. Overlay bytes go through the same SVG rejection as the source image, with DoS caps on layer count, size, and QR data length enforced in assertRenderSpecBounds."
+  }
+]

package/src/derivatives-sharp/render.ts

@@ -5,9 +5,12 @@
 import type {
   BlurRegion,
   DerivativeRendererPlugin,
+  OverlayGravity,
+  ResolvedOverlayLayer,
   VariantFit,
   VariantSpec,
 } from "@cosmicdrift/kumiko-types/derivatives-types";
+import QRCode from "qrcode";
 import type { OverlayOptions, ResizeOptions, Sharp } from "sharp";
 import sharp from "sharp";
 
@@ -25,6 +28,16 @@ const MAX_OUTPUT_EDGE = 8192;
 // unbounded region list is a CPU/RAM-multiplying DoS knob independent of
 // output size.
 const MAX_BLUR_REGIONS = 64;
+// Every layer decodes and resizes separately before the composite — an
+// unbounded list is the same CPU/RAM multiplier MAX_BLUR_REGIONS caps.
+const MAX_OVERLAY_LAYERS = 8;
+// Layer bytes ride inside the spec, which is hashed on every variant() call.
+const MAX_OVERLAY_IMAGE_BYTES = 512 * 1024;
+const MAX_QR_DATA_LENGTH = 1024;
+// Below roughly this, a QR's modules land on too few pixels to survive
+// camera capture — the AC claims phone-scannable, so an under-sized layer
+// throws instead of caching a silently unusable image.
+const MIN_QR_PIXEL_WIDTH = 160;
 // sequentialRead trades random pixel access for lower peak memory on
 // streamed formats — applied at every decode entry point below since none
 // of them need non-sequential access to the *original* bytes (extract runs
@@ -39,6 +52,18 @@ function clampSigma(sigma: number): number {
   return Math.min(MAX_SHARP_SIGMA, Math.max(MIN_SHARP_SIGMA, sigma));
 }
 
+// Shared trust boundary for every image byte source this renderer decodes —
+// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
+// alike: a base64 string in a field declaration isn't more trustworthy than
+// an upload just because it came from app code.
+function assertNotSvg(format: string | undefined): void {
+  if (format === "svg") {
+    throw new Error(
+      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
+    );
+  }
+}
+
 function assertValidRegion(region: BlurRegion): void {
   const values = [region.x, region.y, region.width, region.height];
   if (values.some((v) => !Number.isFinite(v)) || region.width <= 0 || region.height <= 0) {
@@ -86,6 +111,102 @@ async function applyBlurRegions(
   return sharp(data, SHARP_INPUT_OPTIONS).composite(overlays).toBuffer();
 }
 
+// Placement is anchored to the OUTPUT box (overlays run after resize, see
+// applyOverlays), then clamped the same way applyBlurRegions clamps its
+// region coordinates — a caller-declared marginPct can't push a layer
+// off-canvas.
+function overlayPosition(
+  gravity: OverlayGravity,
+  marginPx: number,
+  outputWidth: number,
+  outputHeight: number,
+  layerWidth: number,
+  layerHeight: number,
+): { left: number; top: number } {
+  let left: number;
+  let top: number;
+  switch (gravity) {
+    case "north-west":
+      left = marginPx;
+      top = marginPx;
+      break;
+    case "north-east":
+      left = outputWidth - layerWidth - marginPx;
+      top = marginPx;
+      break;
+    case "south-west":
+      left = marginPx;
+      top = outputHeight - layerHeight - marginPx;
+      break;
+    case "south-east":
+      left = outputWidth - layerWidth - marginPx;
+      top = outputHeight - layerHeight - marginPx;
+      break;
+    case "center":
+      left = (outputWidth - layerWidth) / 2;
+      top = (outputHeight - layerHeight) / 2;
+      break;
+    default:
+      throw new Error(`derivatives-sharp: unknown overlay gravity "${gravity satisfies never}".`);
+  }
+  const maxLeft = Math.max(0, outputWidth - layerWidth);
+  const maxTop = Math.max(0, outputHeight - layerHeight);
+  return {
+    left: Math.min(Math.max(Math.round(left), 0), maxLeft),
+    top: Math.min(Math.max(Math.round(top), 0), maxTop),
+  };
+}
+
+// Runs AFTER resize (see the AC in renderImage) so a layer sized as a
+// fraction of the output is a fraction of what the caller actually gets,
+// regardless of the source's own dimensions or `fit` crop.
+async function applyOverlays(
+  pipeline: Sharp,
+  layers: readonly ResolvedOverlayLayer[],
+): Promise<Sharp> {
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+
+  const composites: OverlayOptions[] = [];
+  for (const layer of layers) {
+    const layerBytes =
+      layer.kind === "qr"
+        ? await QRCode.toBuffer(layer.data, { margin: 1, errorCorrectionLevel: "M" })
+        : Buffer.from(layer.imageBase64, "base64");
+
+    const layerMeta = await sharp(layerBytes, SHARP_INPUT_OPTIONS).metadata();
+    assertNotSvg(layerMeta.format);
+
+    const targetWidth = Math.max(1, Math.round(info.width * layer.widthPct));
+    if (layer.kind === "qr" && targetWidth < MIN_QR_PIXEL_WIDTH) {
+      throw new Error(
+        `derivatives-sharp: qr overlay would render at ${targetWidth}px wide, below the ${MIN_QR_PIXEL_WIDTH}px minimum a camera can reliably scan.`,
+      );
+    }
+
+    // PNG (not the layer's own format) to keep any alpha through the resize.
+    // height caps the other axis too — sharp's composite() rejects an input
+    // larger than the base image, which a tall/square layer would otherwise
+    // hit once widthPct alone drives its width past the output's height.
+    const resized = await sharp(layerBytes, SHARP_INPUT_OPTIONS)
+      .resize({ width: targetWidth, height: info.height, fit: "inside" })
+      .png()
+      .toBuffer({ resolveWithObject: true });
+
+    const marginPx = Math.round(info.width * (layer.marginPct ?? 0));
+    const { left, top } = overlayPosition(
+      layer.gravity,
+      marginPx,
+      info.width,
+      info.height,
+      resized.info.width,
+      resized.info.height,
+    );
+    composites.push({ input: resized.data, left, top });
+  }
+
+  return sharp(data, SHARP_INPUT_OPTIONS).composite(composites);
+}
+
 function buildResizeOptions(width: number, height: number, fit: VariantFit): ResizeOptions {
   const options: ResizeOptions = { width, height, fit };
   if (fit === "inside") {
@@ -153,6 +274,51 @@ function applyEncoder(pipeline: Sharp, spec: VariantSpec, sourceMimeType: string
   return encode(pipeline, quality);
 }
 
+// Split out of assertRenderSpecBounds (not inlined there) purely to stay
+// under the AST-guard complexity budget — see assertRenderSpecBounds's own
+// comment. Still the single call site for every overlay bound.
+function assertOverlayLayerBounds(layer: ResolvedOverlayLayer): void {
+  if (!Number.isFinite(layer.widthPct) || layer.widthPct <= 0 || layer.widthPct > 1) {
+    throw new Error(
+      `derivatives-sharp: overlay widthPct ${layer.widthPct} is out of range — must be a finite number in (0, 1].`,
+    );
+  }
+  if (layer.marginPct !== undefined && (layer.marginPct < 0 || layer.marginPct >= 0.5)) {
+    throw new Error(
+      `derivatives-sharp: overlay marginPct ${layer.marginPct} is out of range — must be within [0, 0.5).`,
+    );
+  }
+  if (layer.kind === "qr") {
+    if (layer.data.length === 0 || layer.data.length > MAX_QR_DATA_LENGTH) {
+      throw new Error(
+        `derivatives-sharp: qr overlay data length ${layer.data.length} is out of range — must be 1–${MAX_QR_DATA_LENGTH} characters.`,
+      );
+    }
+    // skip: qr layers have no imageBase64 field to validate; this return also
+    // narrows the union below to the image variant without a cast.
+    return;
+  }
+  const byteLength = Buffer.byteLength(layer.imageBase64, "base64");
+  if (byteLength > MAX_OVERLAY_IMAGE_BYTES) {
+    throw new Error(
+      `derivatives-sharp: overlay image is ${byteLength} bytes, exceeding the limit of ${MAX_OVERLAY_IMAGE_BYTES}.`,
+    );
+  }
+}
+
+function assertOverlayBounds(layers: readonly ResolvedOverlayLayer[] | undefined): void {
+  // skip: no overlays configured for this variant, nothing to validate
+  if (!layers) return;
+  if (layers.length > MAX_OVERLAY_LAYERS) {
+    throw new Error(
+      `derivatives-sharp: overlays has ${layers.length} entries, exceeding the limit of ${MAX_OVERLAY_LAYERS} — each layer decodes and resizes separately before the composite.`,
+    );
+  }
+  for (const layer of layers) {
+    assertOverlayLayerBounds(layer);
+  }
+}
+
 // Input-validation for the DoS caps above — kept out of renderImage so the
 // complexity hotspot stays under the AST-guard budget.
 function assertRenderSpecBounds(spec: VariantSpec): void {
@@ -181,6 +347,7 @@ function assertRenderSpecBounds(spec: VariantSpec): void {
       );
     }
   }
+  assertOverlayBounds(spec.resolvedOverlays);
 }
 
 export const renderImage: DerivativeRendererPlugin["render"] = async (
@@ -194,11 +361,7 @@ export const renderImage: DerivativeRendererPlugin["render"] = async (
   // the SVG rejection from the actual bytes so a mislabeled upload can't
   // reach libvips as SVG.
   const sniffed = await sharp(input, SHARP_INPUT_OPTIONS).metadata();
-  if (sniffed.format === "svg") {
-    throw new Error(
-      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
-    );
-  }
+  assertNotSvg(sniffed.format);
 
   assertRenderSpecBounds(spec);
 
@@ -225,6 +388,10 @@ export const renderImage: DerivativeRendererPlugin["render"] = async (
     pipeline = pipeline.blur(spec.blur);
   }
 
+  if (spec.resolvedOverlays && spec.resolvedOverlays.length > 0) {
+    pipeline = await applyOverlays(pipeline, spec.resolvedOverlays);
+  }
+
   pipeline = applyEncoder(pipeline, spec, normalizedSource);
 
   const buffer = await pipeline.toBuffer();

package/src/file-derivatives/__tests__/public-variant-route.integration.test.ts

@@ -77,9 +77,23 @@ const widgetEntity = createEntity({
   },
 });
 
+// Registered as a real entity (so upload's registry-hardening resolves it)
+// but with no EXT_DERIVATIVE_PUBLIC_PREDICATE registration — the "no
+// predicate registered for this entityType" default-deny case below needs
+// an entity that upload can attach to, distinct from "the entityType string
+// isn't registered at all" (which upload now rejects before the file ever
+// reaches file_refs, see kumiko-framework#3005).
+const noPredicateEntity = createEntity({
+  table: "public_variant_no_predicate",
+  fields: {
+    img: createImageField({ variants: { thumb: { maxEdge: 160, format: "webp" } } }),
+  },
+});
+
 let predicateCalls = 0;
 const widgetPredicateFeature = defineFeature("publicvariantroutetest", (r) => {
   r.entity("widget", widgetEntity);
+  r.entity("nopredicate", noPredicateEntity);
   r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "widget", {
     isPublic: (args: DerivativePublicPredicateArgs) => {
       predicateCalls++;
@@ -161,7 +175,7 @@ async function uploadFile(
 
 describe("GET /media/:fileRefId/:variant (anonymous, default-deny)", () => {
   test("no predicate registered for the FileRef's entityType → 404", async () => {
-    const fileId = await uploadFile(userA, { entityType: "unregistered-type", entityId: "x" });
+    const fileId = await uploadFile(userA, { entityType: "nopredicate", entityId: "x" });
 
     const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
 

package/src/file-derivatives/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "Add overlay stage (QR codes, badge images) to derived image variants",
+    "detail": "VariantSpec now supports declarative overlay layers (qr via a resolver-token, or a base64 image) composited onto derived image variants. QR values are never free text — only a dataToken resolved server-side via a new extension point, keeping the anonymous derivative route from becoming an open image generator."
+  },
   {
     "version": "0.194.0",
     "type": "breaking",