@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/delivery/unsubscribe.ts

@@ -0,0 +1,429 @@
+import {
+  type ExtraRouteDefinition,
+  ExtraRouteRejection,
+  type SignatureExtraRouteDeps,
+  type SignatureExtraRouteVerifyRequest,
+  signatureRoute,
+} from "@cosmicdrift/kumiko-framework/api";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import * as jose from "jose";
+import * as z from "zod";
+import { hashUnsubscribeAddress } from "./address-opt-out.js";
+import {
+  DELIVERY_RESUBSCRIBE_PATH,
+  DELIVERY_UNSUBSCRIBE_PATH,
+  DeliveryErrors,
+  DeliveryHandlers,
+} from "./constants.js";
+
+// Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
+// wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
+//
+// `kind` is explicitly typed as "absent or undefined, nothing else" here
+// (not bare `.optional()`, which would also accept any other value on an
+// unrelated key) so an address-token payload — which always carries
+// `kind: "address"` — fails this schema instead of silently parsing with
+// `addressHash` mistaken for a userId.
+const unsubscribeJwtPayloadSchema = z.object({
+  kind: z.undefined().optional(),
+  sub: z.string().min(1),
+  tenantId: z.string().min(1),
+  notificationType: z.string().min(1),
+  channel: z.string().min(1),
+});
+
+// Address-token payload. `sub` and `addressHash` are the same value (the
+// subject claim IS the blind-index hash) — kept as two fields because the
+// subject claim is jose's own mechanism while `addressHash` is what the
+// route actually writes; the handler cross-checks them below.
+const addressUnsubscribeJwtPayloadSchema = z.object({
+  kind: z.literal("address"),
+  sub: z.string().min(1),
+  tenantId: z.string().min(1),
+  notificationType: z.string().min(1),
+  channel: z.string().min(1),
+  addressHash: z.string().min(1),
+});
+
+export type UnsubscribeTokenPayload = {
+  readonly userId: string;
+  readonly tenantId: TenantId;
+  readonly notificationType: string;
+  readonly channel: string;
+};
+
+export type AddressUnsubscribeTokenPayload = {
+  readonly tenantId: TenantId;
+  readonly address: string;
+  readonly notificationType: string;
+  readonly channel: string;
+};
+
+/**
+ * `secret` must be a value dedicated to unsubscribe-token signing — do NOT
+ * reuse the app's session `JWT_SECRET`. The app mounting `extraRoutes:
+ * [...createUnsubscribeRoutes({ secret })]` signs outgoing links with the
+ * same value via `signUnsubscribeToken` / `signAddressUnsubscribeToken`.
+ */
+export type UnsubscribeRouteOptions = {
+  readonly secret: string;
+};
+
+const UNSUBSCRIBE_EXPIRY = "7d";
+const MIN_UNSUBSCRIBE_SECRET_LENGTH = 32;
+
+function assertUnsubscribeSecret(secret: string, caller: string): void {
+  if (secret.length < MIN_UNSUBSCRIBE_SECRET_LENGTH) {
+    throw new Error(
+      `${caller}: secret must be ≥${MIN_UNSUBSCRIBE_SECRET_LENGTH} chars (HMAC-SHA256 token signing)`,
+    );
+  }
+}
+
+const UNSUBSCRIBE_TOKEN_INVALID_BODY = {
+  error: { code: "unsubscribe_token_invalid", message: "Invalid or expired token" },
+} as const;
+
+export async function signUnsubscribeToken(
+  payload: UnsubscribeTokenPayload,
+  secret: string,
+): Promise<string> {
+  assertUnsubscribeSecret(secret, "signUnsubscribeToken");
+  const encodedSecret = new TextEncoder().encode(secret);
+  return new jose.SignJWT({
+    tenantId: payload.tenantId,
+    notificationType: payload.notificationType,
+    channel: payload.channel,
+  })
+    .setProtectedHeader({ alg: "HS256" })
+    .setSubject(String(payload.userId))
+    .setIssuer("kumiko:unsubscribe")
+    .setIssuedAt()
+    .setExpirationTime(UNSUBSCRIBE_EXPIRY)
+    .sign(encodedSecret);
+}
+
+/**
+ * Signs an unsubscribe link for a recipient ADDRESS with no user account
+ * (direct sends via `ctx.notify(type, { route: { email } })`). Throws when
+ * no blind-index key is configured — fail closed, since without a key the
+ * opt-out row this token later writes could never be matched against a
+ * future send (the hash wouldn't be reproducible).
+ */
+export async function signAddressUnsubscribeToken(
+  payload: AddressUnsubscribeTokenPayload,
+  secret: string,
+): Promise<string> {
+  assertUnsubscribeSecret(secret, "signAddressUnsubscribeToken");
+  const addressHash = hashUnsubscribeAddress(payload.address);
+  if (addressHash === undefined) {
+    throw new Error(
+      "signAddressUnsubscribeToken requires a configured blind-index key (configureBlindIndexKey)",
+    );
+  }
+  const encodedSecret = new TextEncoder().encode(secret);
+  return (
+    new jose.SignJWT({
+      tenantId: payload.tenantId,
+      notificationType: payload.notificationType,
+      channel: payload.channel,
+      addressHash,
+      kind: "address",
+    })
+      .setProtectedHeader({ alg: "HS256" })
+      .setSubject(addressHash)
+      .setIssuer("kumiko:unsubscribe")
+      .setIssuedAt()
+      // No expiry, unlike the user token above: this same token also signs
+      // the resubscribe (undo) direction, and an unsubscribe link mailed out
+      // today must keep working indefinitely — there's no signed-in flow for
+      // a no-account address to request a fresh link from.
+      .sign(encodedSecret)
+  );
+}
+
+type VerifiedUnsubscribe =
+  | {
+      readonly kind: "address";
+      readonly tenantId: TenantId;
+      readonly addressHash: string;
+      readonly notificationType: string;
+      readonly channel: string;
+    }
+  | {
+      readonly kind: "user";
+      readonly tenantId: TenantId;
+      readonly userId: string;
+      readonly notificationType: string;
+      readonly channel: string;
+    };
+
+// RFC 8058 fixed value — both the List-Unsubscribe-Post header and the body a
+// one-click client POSTs.
+export const DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE = "List-Unsubscribe=One-Click" as const;
+
+const CONFIRMATION_PAGE_HEADERS = {
+  "Cache-Control": "no-store",
+  "Referrer-Policy": "no-referrer",
+} as const;
+
+// Every throw here must become the same ExtraRouteRejection(400,
+// unsubscribe_token_invalid) — anything else falls through to the
+// framework's generic 401 extra_route_signature_invalid mapping, which
+// would leak jose's internal error text into the response body.
+async function verifyUnsubscribeToken(
+  token: string | undefined,
+  encodedSecret: Uint8Array,
+): Promise<VerifiedUnsubscribe> {
+  try {
+    if (!token) {
+      throw new ExtraRouteRejection(
+        400,
+        UNSUBSCRIBE_TOKEN_INVALID_BODY,
+        "missing unsubscribe token",
+      );
+    }
+
+    const { payload: verifiedPayload } = await jose.jwtVerify(token, encodedSecret, {
+      issuer: "kumiko:unsubscribe",
+    });
+
+    const addressAttempt = addressUnsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
+    if (addressAttempt.success) {
+      const parsed = addressAttempt.data;
+      if (parsed.sub !== parsed.addressHash) {
+        throw new ExtraRouteRejection(
+          400,
+          UNSUBSCRIBE_TOKEN_INVALID_BODY,
+          "address token subject mismatch",
+        );
+      }
+      // @cast-boundary engine-bridge — string post-zod → branded TenantId
+      const tenantId = parsed.tenantId as TenantId;
+      return {
+        kind: "address",
+        tenantId,
+        addressHash: parsed.addressHash,
+        notificationType: parsed.notificationType,
+        channel: parsed.channel,
+      };
+    }
+
+    const userAttempt = unsubscribeJwtPayloadSchema.safeParse(verifiedPayload);
+    if (!userAttempt.success) {
+      throw new ExtraRouteRejection(
+        400,
+        UNSUBSCRIBE_TOKEN_INVALID_BODY,
+        "unsubscribe token payload matched neither schema",
+      );
+    }
+    const parsed = userAttempt.data;
+    // @cast-boundary engine-bridge — string post-zod → branded TenantId
+    const tenantId = parsed.tenantId as TenantId;
+    return {
+      kind: "user",
+      tenantId,
+      userId: parsed.sub,
+      notificationType: parsed.notificationType,
+      channel: parsed.channel,
+    };
+  } catch (err) {
+    if (err instanceof ExtraRouteRejection) throw err;
+    throw new ExtraRouteRejection(
+      400,
+      UNSUBSCRIBE_TOKEN_INVALID_BODY,
+      "unsubscribe token verification failed",
+    );
+  }
+}
+
+async function dispatchUnsubscribeWrite(
+  verified: VerifiedUnsubscribe,
+  deps: SignatureExtraRouteDeps,
+): Promise<boolean> {
+  const payload =
+    verified.kind === "address"
+      ? {
+          addressHash: verified.addressHash,
+          notificationType: verified.notificationType,
+          channel: verified.channel,
+        }
+      : {
+          userId: verified.userId,
+          notificationType: verified.notificationType,
+          channel: verified.channel,
+        };
+
+  const dispatched = await deps.dispatchSystemWrite({
+    handlerQn:
+      verified.kind === "address"
+        ? DeliveryHandlers.unsubscribeAddress
+        : DeliveryHandlers.unsubscribeUser,
+    tenantId: verified.tenantId,
+    payload,
+  });
+  return dispatched.isSuccess;
+}
+
+// "limit_reached" is a distinct outcome, not a generic failure: it's the
+// address-side generation cap (removeAddressOptOut) refusing to delete the
+// opt-out row so unsubscribe always still works — the route answers 409,
+// not the 500 a real write failure gets.
+type ResubscribeOutcome = "success" | "limit_reached" | "failed";
+
+function isResubscribeLimitReached(error: { readonly details?: unknown }): boolean {
+  const details = error.details;
+  return (
+    typeof details === "object" &&
+    details !== null &&
+    "reason" in details &&
+    details.reason === DeliveryErrors.resubscribeLimitReached
+  );
+}
+
+async function dispatchResubscribeWrite(
+  verified: VerifiedUnsubscribe,
+  deps: SignatureExtraRouteDeps,
+): Promise<ResubscribeOutcome> {
+  const payload =
+    verified.kind === "address"
+      ? {
+          addressHash: verified.addressHash,
+          notificationType: verified.notificationType,
+          channel: verified.channel,
+        }
+      : {
+          userId: verified.userId,
+          notificationType: verified.notificationType,
+          channel: verified.channel,
+        };
+
+  const dispatched = await deps.dispatchSystemWrite({
+    handlerQn:
+      verified.kind === "address"
+        ? DeliveryHandlers.resubscribeAddress
+        : DeliveryHandlers.resubscribeUser,
+    tenantId: verified.tenantId,
+    payload,
+  });
+  if (dispatched.isSuccess) return "success";
+  return isResubscribeLimitReached(dispatched.error) ? "limit_reached" : "failed";
+}
+
+function confirmationPage(token: string): string {
+  return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="robots" content="noindex">
+<title>Unsubscribe</title>
+</head>
+<body>
+<p>Unsubscribe from these emails?</p>
+<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
+<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
+<button type="submit">Unsubscribe</button>
+</form>
+</body>
+</html>`;
+}
+
+// One-click clients put the token in the query string; only the
+// confirmation-page form submits it in the body.
+function tokenFromPostRequest(request: SignatureExtraRouteVerifyRequest): string | undefined {
+  return tokenFromRequestBody(request) ?? request.query["token"];
+}
+
+// Resubscribe is deliberately NOT reachable via the query string — a mail
+// client's link prefetcher (or a scanner) following an unsubscribe link
+// eagerly is the exact threat model unsubscribe's one-click POST body
+// convention is built to avoid; resubscribe carries the same risk in
+// reverse (a prefetch that undoes a real opt-out) and gets no query-param
+// fallback at all.
+function tokenFromRequestBody(request: SignatureExtraRouteVerifyRequest): string | undefined {
+  const contentType = request.headers["content-type"];
+  if (contentType?.includes("application/x-www-form-urlencoded")) {
+    return new URLSearchParams(request.rawBody).get("token") || undefined;
+  }
+  if (contentType?.includes("application/json")) {
+    try {
+      const parsed = JSON.parse(request.rawBody) as { token?: unknown };
+      return typeof parsed.token === "string" ? parsed.token : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+// GET renders a confirmation page without writing; POST performs the opt-out.
+export function createUnsubscribeRoutes(
+  options: UnsubscribeRouteOptions,
+): readonly ExtraRouteDefinition[] {
+  assertUnsubscribeSecret(options.secret, "createUnsubscribeRoutes");
+  const encodedSecret = new TextEncoder().encode(options.secret);
+
+  const confirmRoute = signatureRoute<{ token: string }>({
+    method: "GET",
+    path: DELIVERY_UNSUBSCRIBE_PATH,
+    entry: "signature",
+    verify: async ({ query }) => {
+      const token = query["token"];
+      if (!token) {
+        throw new ExtraRouteRejection(
+          400,
+          UNSUBSCRIBE_TOKEN_INVALID_BODY,
+          "missing unsubscribe token",
+        );
+      }
+      await verifyUnsubscribeToken(token, encodedSecret);
+      return { token };
+    },
+    handler: async (c, { token }) =>
+      c.html(confirmationPage(token), 200, CONFIRMATION_PAGE_HEADERS),
+  });
+
+  const writeRoute = signatureRoute<VerifiedUnsubscribe>({
+    method: "POST",
+    path: DELIVERY_UNSUBSCRIBE_PATH,
+    entry: "signature",
+    verify: async (request) => verifyUnsubscribeToken(tokenFromPostRequest(request), encodedSecret),
+    handler: async (c, verified, deps) => {
+      // Token-verify passed — everything below is a legitimate write. Don't
+      // swallow write-errors as "invalid token", that would mask real bugs
+      // (e.g. events-table missing, DB down) behind a misleading 400.
+      const succeeded = await dispatchUnsubscribeWrite(verified, deps);
+      if (!succeeded) {
+        return c.html("Unsubscribe failed", 500, { "Cache-Control": "no-store" });
+      }
+      return c.html("You have been unsubscribed.", 200, { "Cache-Control": "no-store" });
+    },
+  });
+
+  // Undo direction: token only from the JSON/form body, never the query
+  // (see tokenFromRequestBody) — no GET confirmation-page variant,
+  // this is a one-shot POST from the unsubscribe-page's "Undo" button.
+  const resubscribeRoute = signatureRoute<VerifiedUnsubscribe>({
+    method: "POST",
+    path: DELIVERY_RESUBSCRIBE_PATH,
+    entry: "signature",
+    verify: async (request) => verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret),
+    handler: async (c, verified, deps) => {
+      const outcome = await dispatchResubscribeWrite(verified, deps);
+      if (outcome === "limit_reached") {
+        return c.json({ error: { code: DeliveryErrors.resubscribeLimitReached } }, 409, {
+          "Cache-Control": "no-store",
+        });
+      }
+      if (outcome === "failed") {
+        return c.json({ error: { code: "resubscribe_failed" } }, 500, {
+          "Cache-Control": "no-store",
+        });
+      }
+      return c.json({ isSuccess: true }, 200, { "Cache-Control": "no-store" });
+    },
+  });
+
+  return [confirmRoute, writeRoute, resubscribeRoute];
+}

package/packages/bundled-features/src/delivery/upsert-preference.ts

@@ -0,0 +1,154 @@
+// Race-safe upsert for notification-preferences. Pre-ES this was a single
+// `onConflictDoUpdate` statement on the preferences table; post-ES we go
+// through the event-store executor, which doesn't offer a built-in upsert.
+// Splitting into lookup + create|update re-opens the race window for
+// concurrent requests — typical case: a user clicks the same "unsubscribe"
+// email link three times in a second.
+//
+// The fix: the aggregate id is deterministic (tenant+user+type+channel), so
+// concurrent first-time clicks collide at the event-store append itself
+// (expectedVersion 0, confined to a savepoint) instead of racing past two
+// independent creates and leaving an orphaned `created` event behind. The
+// loser's create() comes back as a `version_conflict` failure; re-lookup and
+// fall through to update, or no-op if the winner already set the target
+// `enabled` state.
+
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
+import { notificationPreferenceEntity, notificationPreferencesTable } from "./tables.js";
+
+const executor = createEventStoreExecutor(
+  notificationPreferencesTable,
+  notificationPreferenceEntity,
+  { entityName: "notification-preference" },
+);
+
+// Konkretes Lookup-Result-Shape — nur die Felder die der upsert
+// tatsächlich für den Update-Path braucht. Vermeidet `row["x"] as T` index-
+// access casts; der Generic-Param am fetchOne macht den Cast zentralisiert
+// im Helper (db-row-boundary), nicht 4× pro Callsite.
+type PreferenceLookupRow = {
+  readonly id: string;
+  readonly version: number;
+  readonly enabled: boolean;
+};
+
+// @wrapper-known semantic-alias
+async function lookup(
+  db: TenantDb,
+  tenantId: TenantId,
+  userId: string,
+  notificationType: string,
+  channel: string,
+): Promise<PreferenceLookupRow | undefined> {
+  return fetchOne<PreferenceLookupRow>(db, notificationPreferencesTable, {
+    tenantId,
+    userId,
+    notificationType,
+    channel,
+  });
+}
+
+export type UpsertPreferenceInput = {
+  readonly tenantId: TenantId;
+  readonly userId: string;
+  readonly notificationType: string;
+  readonly channel: string;
+  readonly enabled: boolean;
+};
+
+// One row per (tenant, user, type, channel): folding the tuple into the
+// aggregate id means two concurrent first-time clicks collide on the same
+// stream at append instead of racing two independent creates.
+function preferenceAggregateId(
+  tenantId: TenantId,
+  userId: string,
+  notificationType: string,
+  channel: string,
+): string {
+  return generateDeterministicId(
+    "delivery:notification-preference",
+    `${tenantId}|${userId}|${notificationType}|${channel}`,
+  );
+}
+
+/**
+ * Idempotent "set-this-preference-to-enabled-state" against the preferences
+ * aggregate stream. Emits either `.created` (first time) or `.updated`
+ * (subsequent) and converges a concurrent create-race onto the winner's row.
+ */
+export async function upsertPreference(
+  db: TenantDb,
+  actor: SessionUser,
+  input: UpsertPreferenceInput,
+): Promise<WriteResult<UpsertPreferenceInput>> {
+  const existing = await lookup(
+    db,
+    input.tenantId,
+    input.userId,
+    input.notificationType,
+    input.channel,
+  );
+
+  if (existing) {
+    if (existing.enabled === input.enabled) return { isSuccess: true, data: input };
+    const result = await executor.update(
+      {
+        id: existing.id,
+        version: existing.version,
+        changes: { enabled: input.enabled },
+      },
+      actor,
+      db,
+    );
+    if (!result.isSuccess) return result;
+    return { isSuccess: true, data: input };
+  }
+
+  const id = preferenceAggregateId(
+    input.tenantId,
+    input.userId,
+    input.notificationType,
+    input.channel,
+  );
+  const created = await executor.create(
+    {
+      id,
+      userId: input.userId,
+      notificationType: input.notificationType,
+      channel: input.channel,
+      enabled: input.enabled,
+    },
+    actor,
+    db,
+  );
+  if (created.isSuccess) return { isSuccess: true, data: input };
+  if (created.error.code !== "version_conflict") return created;
+
+  // Race-fallback: another request's create already won this deterministic
+  // id between our lookup and this create. Re-lookup and converge onto its
+  // row — no-op if it already set the target `enabled`, since relooking the
+  // same version and updating would version_conflict all but one loser.
+  const afterRace = await lookup(
+    db,
+    input.tenantId,
+    input.userId,
+    input.notificationType,
+    input.channel,
+  );
+  if (!afterRace) return created;
+  if (afterRace.enabled === input.enabled) return { isSuccess: true, data: input };
+  const result = await executor.update(
+    {
+      id: afterRace.id,
+      version: afterRace.version,
+      changes: { enabled: input.enabled },
+    },
+    actor,
+    db,
+  );
+  if (!result.isSuccess) return result;
+  return { isSuccess: true, data: input };
+}

package/packages/bundled-features/src/delivery/web/client-plugin.tsx

@@ -0,0 +1,19 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { DELIVERY_FEATURE, DELIVERY_STATUS_CELL_COMPONENT } from "../public-names.js";
+import { DeliveryStatusCell } from "./delivery-status-cell.js";
+
+export type DeliveryClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function deliveryClient(options?: DeliveryClientOptions): ClientFeatureDefinition {
+  return {
+    name: DELIVERY_FEATURE,
+    columnRenderers: {
+      [DELIVERY_STATUS_CELL_COMPONENT]: DeliveryStatusCell,
+    },
+    ...(options?.translations !== undefined && { translations: options.translations }),
+  };
+}

package/packages/bundled-features/src/delivery/web/delivery-status-cell.tsx

@@ -0,0 +1,26 @@
+// @runtime client
+// Column-renderer for the delivery-log screen's status column, registered
+// via `deliveryClient()`'s `columnRenderers` map (screen.columns[].renderer
+// in feature.ts). The list frame itself is the generic declarative
+// projectionList renderer — only this one cell stays TSX.
+
+import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+import { StatusBadge, type StatusTone } from "@cosmicdrift/kumiko-renderer-web";
+import type { ReactNode } from "react";
+import { DeliveryStatus } from "../public-names.js";
+
+const STATUS_TONE: Readonly<Record<string, StatusTone>> = {
+  [DeliveryStatus.sent]: "ok",
+  [DeliveryStatus.failed]: "bad",
+  [DeliveryStatus.queued]: "muted",
+  [DeliveryStatus.skipped]: "muted",
+};
+
+export function DeliveryStatusCell({ row }: ColumnRendererProps): ReactNode {
+  const status = typeof row["status"] === "string" ? row["status"] : "";
+  return (
+    <StatusBadge tone={STATUS_TONE[status] ?? "muted"} testId="delivery-status-cell">
+      {status}
+    </StatusBadge>
+  );
+}

package/packages/bundled-features/src/delivery/web/index.ts

@@ -0,0 +1,3 @@
+// @runtime client
+export { type DeliveryClientOptions, deliveryClient } from "./client-plugin.js";
+export { DeliveryStatusCell } from "./delivery-status-cell.js";

package/packages/bundled-features/src/derivatives-sharp/changes.json

@@ -0,0 +1,19 @@
+[
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Overlay and blur intermediates are lossless and QR overlays render crisp at their final size",
+    "detail": "The sharp renderer buffers intermediates losslessly before overlays and blur regions, so a JPEG source no longer gains an extra compression generation. QR overlays are generated at their final size and checked against the smaller of output width and height before generation, so a flat output can no longer cache an unscannable QR."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Overlay marginPct must be finite"
+  },
+  {
+    "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/packages/bundled-features/src/derivatives-sharp/feature.ts

@@ -0,0 +1,22 @@
+// kumiko-feature-version: 1
+
+import { defineFeature, EXT_DERIVATIVE_RENDERER } from "@cosmicdrift/kumiko-framework/engine";
+import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { renderImage } from "./render.js";
+
+const FEATURE_NAME = "derivatives-sharp";
+
+export const derivativesSharpFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    "Registers an `image/*` renderer against the `derivativeRenderer` extension point declared by `file-derivatives`, backed by sharp. Supports resize/fit (cover, inside, contain), format conversion with quality (webp, avif, jpeg), whole-image blur, and blurring individual regions burned in before resize (see BlurRegion). EXIF orientation is applied and then normalized away, and all other EXIF (including GPS) is dropped. Server-only: sharp is a native binding — never import this from client code.",
+  );
+  r.uiHints({
+    displayLabel: "File Derivatives · Sharp",
+    category: "storage",
+    recommended: false,
+  });
+  r.requires("file-derivatives");
+
+  const plugin: DerivativeRendererPlugin = { render: renderImage };
+  r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);
+});

package/packages/bundled-features/src/derivatives-sharp/index.ts

@@ -0,0 +1,2 @@
+export { derivativesSharpFeature } from "./feature.js";
+export { imageMetadata } from "./render.js";