@cosmicdrift/kumiko-bundled-features 0.286.0 → 0.288.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.286.0",
+  "version": "0.288.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.288.0",
+    "@cosmicdrift/kumiko-framework": "0.288.0",
+    "@cosmicdrift/kumiko-headless": "0.288.0",
+    "@cosmicdrift/kumiko-renderer": "0.288.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.288.0",
+    "@cosmicdrift/kumiko-types": "0.288.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.288.0",
+    "@cosmicdrift/kumiko-locale-es": "0.288.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/billing-foundation/__tests__/subscription-tier-sync.integration.test.ts

@@ -0,0 +1,186 @@
+// Integration test for createSubscriptionTierSync()'s onSyncError option
+// (#3027). Forces a sync failure via a dispatchSystemWrite stub that fails
+// only the tier-engine handlers (the primary billing-foundation writes run
+// for real against the test DB) — proving that "log" (default) still
+// answers the webhook successfully, while "fail-webhook" surfaces the sync
+// error all the way into the HTTP response.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { buildEntityTable, type EntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineFeature,
+  type EntityDefinition,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
+import { Hono } from "hono";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant/feature";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import type { TierMap } from "../../tier-engine/compose-app";
+import { TierEngineHandlers } from "../../tier-engine/constants";
+import { tierAssignmentEntity } from "../../tier-engine/entity";
+import { createTierEngineFeature } from "../../tier-engine/feature";
+import { SubscriptionEventTypes, SubscriptionStatuses } from "../constants";
+import { billingFoundationFeature } from "../feature";
+import {
+  createSubscriptionTierSync,
+  SUBSCRIPTION_WEBHOOK_PATH,
+  type SystemWriteResult,
+} from "../subscription-tier-sync";
+import type { SubscriptionEvent, SubscriptionProviderPlugin } from "../types";
+
+type TestTier = "free" | "pro";
+const isTierName = (v: string): v is TestTier => v === "free" || v === "pro";
+const TEST_TIER_MAP: TierMap<{ readonly maxItems: number }> = {
+  free: { features: [], caps: { maxItems: 1 } },
+  pro: { features: [], caps: { maxItems: 100 } },
+};
+
+const mockProviderFeature = defineFeature("test-mock-tier-sync-provider", (r) => {
+  r.requires("billing-foundation");
+  const plugin: SubscriptionProviderPlugin = {
+    verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody) as SubscriptionEvent,
+  };
+  r.useExtension("subscriptionProvider", "mock", plugin);
+});
+
+// Boundary-cast: SubscriptionTierSyncDeps deliberately erases the entity's
+// concrete field types to EntityDefinition (generic factory), which TS
+// can't structurally widen to on its own.
+const tierAssignmentTable = buildEntityTable(
+  "tier-assignment",
+  tierAssignmentEntity,
+) as unknown as EntityTable<EntityDefinition>;
+
+let stack: TestStack;
+let forceTierSyncFailure = false;
+
+async function dispatchSystemWrite(args: {
+  readonly handlerQn: string;
+  readonly payload: unknown;
+  readonly tenantId: TenantId;
+}): Promise<SystemWriteResult> {
+  if (
+    forceTierSyncFailure &&
+    (args.handlerQn === TierEngineHandlers.create || args.handlerQn === TierEngineHandlers.update)
+  ) {
+    return {
+      isSuccess: false,
+      error: { code: "test_forced_failure", message: "forced tier-sync failure" },
+    };
+  }
+  const systemUser = createTestUser({ id: 1, tenantId: args.tenantId, roles: ["SystemAdmin"] });
+  const res = await stack.http.write(args.handlerQn, args.payload, systemUser);
+  const body = (await res.json()) as {
+    isSuccess: boolean;
+    data?: unknown;
+    error?: { readonly code?: string; readonly message?: string };
+  };
+  return body.isSuccess
+    ? { isSuccess: true, data: body.data }
+    : { isSuccess: false, error: body.error };
+}
+
+let logApp: Hono;
+let failApp: Hono;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      billingFoundationFeature,
+      createTierEngineFeature({ defaultTier: "free", tierMap: TEST_TIER_MAP }),
+      mockProviderFeature,
+    ],
+  });
+  await createEventsTable(stack.db);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+  await unsafePushTables(stack.db, { tier_assignments: tierAssignmentTable });
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+
+  const sharedDeps = {
+    db: stack.db,
+    registry: stack.registry,
+    dispatchSystemWrite,
+    tierAssignmentTable,
+    isTierName,
+    defaultTier: "free" as const,
+  };
+
+  logApp = new Hono();
+  createSubscriptionTierSync<TestTier>(sharedDeps).wireSubscriptionWebhookRoute(logApp);
+
+  failApp = new Hono();
+  createSubscriptionTierSync<TestTier>({
+    ...sharedDeps,
+    onSyncError: "fail-webhook",
+  }).wireSubscriptionWebhookRoute(failApp);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+  resetPiiSubjectKmsForTests();
+});
+
+const webhookPath = SUBSCRIPTION_WEBHOOK_PATH.replace(":providerName", "mock");
+
+function buildEvent(tenantId: string, providerEventId: string): SubscriptionEvent {
+  return {
+    providerEventId,
+    providerName: "mock",
+    type: SubscriptionEventTypes.created,
+    tenantId,
+    providerCustomerId: `cus_${providerEventId}`,
+    providerSubscriptionId: `sub_${providerEventId}`,
+    status: SubscriptionStatuses.active,
+    tier: "pro",
+    currentPeriodEnd: "2026-06-01T00:00:00Z",
+    rawPayload: "{}",
+  };
+}
+
+describe("createSubscriptionTierSync onSyncError", () => {
+  test("default ('log'): a tier-sync failure still returns a successful webhook response", async () => {
+    forceTierSyncFailure = true;
+    const tenantId = testTenantId(9001);
+    const res = await logApp.request(webhookPath, {
+      method: "POST",
+      body: JSON.stringify(buildEvent(tenantId, "evt_log_1")),
+    });
+    forceTierSyncFailure = false;
+
+    expect(res.status).toBe(200);
+  });
+
+  test("'fail-webhook': a tier-sync failure also fails the webhook response", async () => {
+    forceTierSyncFailure = true;
+    const tenantId = testTenantId(9002);
+    const res = await failApp.request(webhookPath, {
+      method: "POST",
+      body: JSON.stringify(buildEvent(tenantId, "evt_fail_1")),
+    });
+    forceTierSyncFailure = false;
+
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("subscription_webhook_processing_failed");
+  });
+});

package/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.288.0",
+    "type": "improvement",
+    "title": "add onSyncError option to createSubscriptionTierSync",
+    "detail": "`SubscriptionTierSyncDeps<TTier>` gets an optional `onSyncError?: \"log\" | \"fail-webhook\"`\n(default `\"log\"`, matching prior behavior exactly). `\"fail-webhook\"` makes a tier-sync\nfailure also fail the webhook response, so an idempotent-retry caller (whose retry\nno-ops the already-committed primary write) gets another attempt at the sync step."
+  },
   {
     "version": "0.286.0",
     "type": "improvement",

package/src/billing-foundation/subscription-tier-sync.ts

@@ -35,6 +35,12 @@ export type SubscriptionTierSyncDeps<TTier extends string> = {
   readonly tierAssignmentTable: EntityTable<EntityDefinition>;
   readonly isTierName: (value: string) => value is TTier;
   readonly defaultTier: TTier;
+  // "log" (default): sync failure only warns, the webhook still reports
+  // success — right when the caller has no idempotent retry to lean on.
+  // "fail-webhook": sync failure fails the webhook response too, so an
+  // idempotent caller (e.g. Stripe, whose retry re-runs the already-committed
+  // primary write as a no-op) gets a second attempt at the sync step itself.
+  readonly onSyncError?: "log" | "fail-webhook";
 };
 
 export function effectiveTierFromSubscription<TTier extends string>(
@@ -116,16 +122,15 @@ export function createSubscriptionTierSync<TTier extends string>(
           tenantId: targetTenantId,
         });
         if (!result.isSuccess) return result;
-        // The primary write already committed — a webhook caller (Stripe/
-        // PayPal) that sees isSuccess:false here retries the whole event,
-        // re-running an already-succeeded side effect. Log the tier-sync
-        // failure instead of masking the primary write's success.
         const syncError = await syncTierFromSubscription(targetTenantId);
         if (syncError) {
           // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
           console.warn(
             `[subscription-tier-sync] tier sync failed for tenant ${targetTenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
           );
+          if (deps.onSyncError === "fail-webhook") {
+            return { isSuccess: false, error: syncError };
+          }
         }
         return result;
       },

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."
+  }
+]