@cosmicdrift/kumiko-samples 0.365.1 → 0.367.0

package/packages/bundled-features/src/delivery/handlers/unsubscribe-address.write.ts

@@ -2,14 +2,20 @@ import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { upsertAddressOptOut } from "../address-opt-out.js";
+import { currentNotificationType } from "../notification-type-aliases.js";
+
+// Also the payload an app job receives with `trigger: { on: DeliveryHandlers.unsubscribeAddress }`
+// after a committed address opt-out (the tenant is the job's `ctx.triggeredBy.tenantId`).
+export const unsubscribeAddressPayloadSchema = z.object({
+  addressHash: z.string().min(1),
+  notificationType: z.string().min(1),
+  channel: z.string().min(1),
+});
+export type UnsubscribeAddressPayload = z.infer<typeof unsubscribeAddressPayloadSchema>;
 
 export const unsubscribeAddressWrite = defineWriteHandler({
   name: "unsubscribeAddress",
-  schema: z.object({
-    addressHash: z.string().min(1),
-    notificationType: z.string().min(1),
-    channel: z.string().min(1),
-  }),
+  schema: unsubscribeAddressPayloadSchema,
   access: { roles: access.systemAdmin },
   // Only reachable via createUnsubscribeRoutes' POST dispatchSystemWrite, once
   // verify() has already proven the address-token signature — not a surface
@@ -18,7 +24,8 @@ export const unsubscribeAddressWrite = defineWriteHandler({
   description:
     "Records a no-account address opt-out for one notificationType/channel combination; dispatched by the signed unsubscribe route, not meant for UI callers.",
   handler: async (event, ctx) => {
-    const { addressHash, notificationType, channel } = event.payload;
+    const { addressHash, channel } = event.payload;
+    const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
     const { tenantId } = event.user;
 
     if (!ctx.systemDb) {

package/packages/bundled-features/src/delivery/handlers/unsubscribe-user.write.ts

@@ -1,6 +1,7 @@
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { currentNotificationType } from "../notification-type-aliases.js";
 import { upsertPreference } from "../upsert-preference.js";
 
 export const unsubscribeUserWrite = defineWriteHandler({
@@ -20,7 +21,8 @@ export const unsubscribeUserWrite = defineWriteHandler({
   handler: async (event, ctx) => {
     // userId comes from the payload, not event.user.id — the caller here is
     // the system user dispatchSystemWrite runs as, not the user unsubscribing.
-    const { userId, notificationType, channel } = event.payload;
+    const { userId, channel } = event.payload;
+    const notificationType = currentNotificationType(ctx.registry, event.payload.notificationType);
     const { tenantId } = event.user;
 
     if (!ctx.systemDb) {

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

@@ -63,6 +63,10 @@ export {
   type RateLimitConfig,
 } from "./delivery-service.js";
 export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature.js";
+export {
+  type UnsubscribeAddressPayload,
+  unsubscribeAddressPayloadSchema,
+} from "./handlers/unsubscribe-address.write.js";
 export { createDeliveryNotifyFactory } from "./notify-factory.js";
 export {
   deliveryAttemptsTable,
@@ -94,3 +98,5 @@ export {
   type UnsubscribeRouteOptions,
   type UnsubscribeTokenPayload,
 } from "./unsubscribe.js";
+export type { UnsubscribeLinkConfig } from "./unsubscribe-link.js";
+export { UNSUBSCRIBE_PAGE_EN } from "./unsubscribe-page-strings.js";

package/packages/bundled-features/src/delivery/notification-type-aliases.ts

@@ -0,0 +1,13 @@
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+
+export function notificationTypeNames(registry: Registry, type: string): readonly string[] {
+  const renamedFrom = registry.getAllNotifications().get(type)?.renamedFrom ?? [];
+  return [type, ...renamedFrom];
+}
+
+export function currentNotificationType(registry: Registry, type: string): string {
+  for (const [name, definition] of registry.getAllNotifications()) {
+    if (definition.renamedFrom?.includes(type)) return name;
+  }
+  return type;
+}

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

@@ -15,6 +15,7 @@ import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service.js"
 import { collectChannels, createDeliveryService } from "./delivery-service.js";
 import { createDeliveryNotifyFactory } from "./notify-factory.js";
 import type { DeliveryService } from "./types.js";
+import type { UnsubscribeLinkConfig } from "./unsubscribe-link.js";
 
 export type CreateDeliveryTestContextOptions = {
   readonly tenantUserIdsQuery?: string;
@@ -27,6 +28,7 @@ export type CreateDeliveryTestContextOptions = {
   readonly idempotencyRedis?: Redis;
   readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
   readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
+  readonly unsubscribeLinks?: UnsubscribeLinkConfig;
 };
 
 /**

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

@@ -1,6 +1,7 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
+  ConfigAccessor,
   DeliveryErrorCode,
   NotifyDeliveryStatus,
   NotifyDispatched,
@@ -39,6 +40,9 @@ export type ChannelContext = {
   // Chat channels read their per-tenant webhook URL / bot token from it.
   // Absent when no secrets feature/KEK is wired.
   readonly secrets?: SecretsContext | undefined;
+  // The tenant's own config accessor, built server-side for this tenantId. Absent when the
+  // delivery service has no tenantConfigFor and the job context carries no config.
+  readonly config?: ConfigAccessor | undefined;
   // Renders a stored mail template, the tenant's own or the system fallback.
   readonly renderMail?: (payload: MailPayload) => Promise<RenderedMail>;
   // Reads the bytes behind an attachment ref at send time. Absent when no file storage is wired.

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

@@ -0,0 +1,73 @@
+import { publicOriginOf } from "@cosmicdrift/kumiko-framework/api";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { hashUnsubscribeAddress } from "./address-opt-out.js";
+import { DELIVERY_UNSUBSCRIBE_PATH } from "./constants.js";
+import type { ChannelContext } from "./types.js";
+import { signAddressUnsubscribeToken, signUnsubscribeToken } from "./unsubscribe.js";
+
+/** Secret shared with `createUnsubscribeRoutes` plus the public origin the links point at. */
+export type UnsubscribeLinkConfig = {
+  readonly secret: string;
+  readonly baseUrl: string;
+  /** The sending tenant's own public origin (subdomain or custom domain), null when it has
+   *  none. The host must serve this app's `/api` routes. Null, a throw or an unusable value
+   *  fall back to `baseUrl`, so a missing tenant origin never fails a send. */
+  readonly tenantOrigin?: (ctx: ChannelContext) => Promise<string | null | undefined>;
+};
+
+export type UnsubscribeLinkRecipient =
+  | { readonly kind: "user"; readonly userId: string }
+  | { readonly kind: "address"; readonly address: string };
+
+// https only, unless the app itself runs on plain http (local dev): a tenant origin must not
+// downgrade the link that carries the token.
+function isUsableTenantOrigin(origin: string, baseUrl: string): boolean {
+  return (
+    origin.startsWith("https://") || (baseUrl.startsWith("http://") && origin.startsWith("http://"))
+  );
+}
+
+export async function unsubscribeLinkOrigin(
+  config: UnsubscribeLinkConfig,
+  ctx: ChannelContext,
+  onFallback: (reason: string) => void,
+): Promise<string> {
+  if (config.tenantOrigin === undefined) return config.baseUrl;
+  let resolved: string | null | undefined;
+  try {
+    resolved = await config.tenantOrigin(ctx);
+  } catch (err) {
+    onFallback(`tenantOrigin threw (${err instanceof Error ? err.name : typeof err})`);
+    return config.baseUrl;
+  }
+  if (resolved === null || resolved === undefined) return config.baseUrl;
+  const origin = publicOriginOf(resolved);
+  if (origin === undefined || !isUsableTenantOrigin(origin, config.baseUrl)) {
+    onFallback("tenantOrigin returned no usable https origin");
+    return config.baseUrl;
+  }
+  return origin;
+}
+
+// Undefined means "no link": without a blind-index key an address opt-out could never be
+// matched again, and a mail without a link is better than a failed send.
+export async function buildUnsubscribeUrl(
+  config: UnsubscribeLinkConfig,
+  origin: string,
+  recipient: UnsubscribeLinkRecipient,
+  scope: {
+    tenantId: TenantId;
+    notificationType: string;
+    channel: string;
+    locale: string | undefined;
+  },
+): Promise<string | undefined> {
+  if (recipient.kind === "address" && hashUnsubscribeAddress(recipient.address) === undefined) {
+    return undefined;
+  }
+  const token =
+    recipient.kind === "user"
+      ? await signUnsubscribeToken({ ...scope, userId: recipient.userId }, config.secret)
+      : await signAddressUnsubscribeToken({ ...scope, address: recipient.address }, config.secret);
+  return `${origin}${DELIVERY_UNSUBSCRIBE_PATH}?token=${encodeURIComponent(token)}`;
+}

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

@@ -0,0 +1,17 @@
+import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
+
+// The pages behind a mailed unsubscribe link speak the mail's language, so their texts live in
+// the mail translations: English here, other languages in the locale packages.
+export const UNSUBSCRIBE_PAGE_EN = {
+  "mail.unsubscribe.confirmTitle": "Unsubscribe",
+  "mail.unsubscribe.confirmQuestion": "Unsubscribe from these emails?",
+  "mail.unsubscribe.confirmButton": "Unsubscribe",
+  "mail.unsubscribe.doneTitle": "Unsubscribed",
+  "mail.unsubscribe.doneMessage": "You have been unsubscribed.",
+  "mail.unsubscribe.undoButton": "Undo",
+  "mail.unsubscribe.resubscribedTitle": "Subscribed again",
+  "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.",
+  "mail.unsubscribe.failed": "That did not work. Please try again later.",
+} as const;
+
+registerMailTranslations("en", UNSUBSCRIBE_PAGE_EN);

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

@@ -6,6 +6,7 @@ import {
   signatureRoute,
 } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { mailT, resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
 import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as jose from "jose";
@@ -17,6 +18,14 @@ import {
   DeliveryErrors,
   DeliveryHandlers,
 } from "./constants.js";
+import "./unsubscribe-page-strings.js";
+
+// The mail's locale, so the pages behind the link speak the mail's language. Optional: links
+// signed before the claim existed keep verifying and fall back to English.
+const localeClaimSchema = z
+  .string()
+  .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/)
+  .optional();
 
 // Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
 // wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
@@ -32,6 +41,7 @@ const unsubscribeJwtPayloadSchema = z.object({
   tenantId: z.string().min(1),
   notificationType: z.string().min(1),
   channel: z.string().min(1),
+  locale: localeClaimSchema,
 });
 
 // Address-token payload. `sub` and `addressHash` are the same value (the
@@ -45,6 +55,7 @@ const addressUnsubscribeJwtPayloadSchema = z.object({
   notificationType: z.string().min(1),
   channel: z.string().min(1),
   addressHash: z.string().min(1),
+  locale: localeClaimSchema,
 });
 
 export type UnsubscribeTokenPayload = {
@@ -52,6 +63,7 @@ export type UnsubscribeTokenPayload = {
   readonly tenantId: TenantId;
   readonly notificationType: string;
   readonly channel: string;
+  readonly locale?: string | undefined;
 };
 
 export type AddressUnsubscribeTokenPayload = {
@@ -59,6 +71,7 @@ export type AddressUnsubscribeTokenPayload = {
   readonly address: string;
   readonly notificationType: string;
   readonly channel: string;
+  readonly locale?: string | undefined;
 };
 
 /**
@@ -87,6 +100,11 @@ function assertUnsubscribeSecret(secret: string, caller: string): void {
   }
 }
 
+// An unusable locale is left out instead of failing the send; the pages then fall back to English.
+function localeClaim(locale: string | undefined): { locale?: string } {
+  return locale !== undefined && localeClaimSchema.safeParse(locale).success ? { locale } : {};
+}
+
 const UNSUBSCRIBE_TOKEN_INVALID_BODY = {
   error: { code: "unsubscribe_token_invalid", message: "Invalid or expired token" },
 } as const;
@@ -101,6 +119,7 @@ export async function signUnsubscribeToken(
     tenantId: payload.tenantId,
     notificationType: payload.notificationType,
     channel: payload.channel,
+    ...localeClaim(payload.locale),
   })
     .setProtectedHeader({ alg: "HS256" })
     .setSubject(String(payload.userId))
@@ -136,6 +155,7 @@ export async function signAddressUnsubscribeToken(
       channel: payload.channel,
       addressHash,
       kind: "address",
+      ...localeClaim(payload.locale),
     })
       .setProtectedHeader({ alg: "HS256" })
       .setSubject(addressHash)
@@ -154,6 +174,7 @@ type VerifiedUnsubscribe =
       readonly addressHash: string;
       readonly notificationType: string;
       readonly channel: string;
+      readonly locale: string | undefined;
     }
   | {
       readonly kind: "user";
@@ -161,6 +182,7 @@ type VerifiedUnsubscribe =
       readonly userId: string;
       readonly notificationType: string;
       readonly channel: string;
+      readonly locale: string | undefined;
     };
 
 // RFC 8058 fixed value — both the List-Unsubscribe-Post header and the body a
@@ -183,6 +205,7 @@ async function signResubscribeToken(
     tenantId: verified.tenantId,
     notificationType: verified.notificationType,
     channel: verified.channel,
+    ...localeClaim(verified.locale),
   };
   const jwt =
     verified.kind === "address"
@@ -254,6 +277,7 @@ async function verifyUnsubscribeToken(
         addressHash: parsed.addressHash,
         notificationType: parsed.notificationType,
         channel: parsed.channel,
+        locale: parsed.locale,
       };
     }
 
@@ -274,6 +298,7 @@ async function verifyUnsubscribeToken(
       userId: parsed.sub,
       notificationType: parsed.notificationType,
       channel: parsed.channel,
+      locale: parsed.locale,
     };
   } catch (err) {
     if (err instanceof ExtraRouteRejection) throw err;
@@ -358,40 +383,68 @@ async function dispatchResubscribeWrite(
   return isResubscribeLimitReached(dispatched.error) ? "limit_reached" : "failed";
 }
 
-function confirmationPage(token: string): string {
+function pageLocale(locale: string | undefined): string {
+  return resolveMailLocale(locale ?? "en");
+}
+
+function htmlPage(locale: string, title: string, bodyHtml: string): string {
   return `<!doctype html>
-<html>
+<html lang="${escapeHtmlAttr(locale)}">
 <head>
 <meta charset="utf-8">
 <meta name="robots" content="noindex">
-<title>Unsubscribe</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtmlAttr(title)}</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>
+${bodyHtml}
 </body>
 </html>`;
 }
 
-function unsubscribedPage(resubscribeToken: string): string {
-  return `<!doctype html>
-<html>
-<head>
-<meta charset="utf-8">
-<meta name="robots" content="noindex">
-<title>Unsubscribed</title>
-</head>
-<body>
-<p>You have been unsubscribed.</p>
+function confirmationPage(token: string, locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.confirmTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmQuestion"))}</p>
+<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
+<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmButton"))}</button>
+</form>`,
+  );
+}
+
+function unsubscribedPage(resubscribeToken: string, locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.doneTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.doneMessage"))}</p>
 <form method="post" action="${DELIVERY_RESUBSCRIBE_PATH}">
 <input type="hidden" name="token" value="${escapeHtmlAttr(resubscribeToken)}">
-<button type="submit">Undo</button>
-</form>
-</body>
-</html>`;
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.undoButton"))}</button>
+</form>`,
+  );
+}
+
+function resubscribedPage(locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.resubscribedTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.resubscribedMessage"))}</p>`,
+  );
+}
+
+function failedPage(locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  const message = mailT(lang, "mail.unsubscribe.failed");
+  return htmlPage(lang, message, `<p>${escapeHtmlAttr(message)}</p>`);
+}
+
+function isFormRequest(contentType: string | undefined): boolean {
+  return contentType?.includes("application/x-www-form-urlencoded") === true;
 }
 
 // One-click clients put the token in the query string; only the
@@ -431,7 +484,7 @@ export function createUnsubscribeRoutes(
   assertUnsubscribeSecret(options.secret, "createUnsubscribeRoutes");
   const encodedSecret = new TextEncoder().encode(options.secret);
 
-  const confirmRoute = signatureRoute<{ token: string }>({
+  const confirmRoute = signatureRoute<{ token: string; locale: string | undefined }>({
     method: "GET",
     path: DELIVERY_UNSUBSCRIBE_PATH,
     entry: "signature",
@@ -444,11 +497,11 @@ export function createUnsubscribeRoutes(
           "missing unsubscribe token",
         );
       }
-      await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
-      return { token };
+      const verified = await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
+      return { token, locale: verified.locale };
     },
-    handler: async (c, { token }) =>
-      c.html(confirmationPage(token), 200, CONFIRMATION_PAGE_HEADERS),
+    handler: async (c, { token, locale }) =>
+      c.html(confirmationPage(token, locale), 200, CONFIRMATION_PAGE_HEADERS),
   });
 
   const writeRoute = signatureRoute<VerifiedUnsubscribe>({
@@ -463,11 +516,13 @@ export function createUnsubscribeRoutes(
       // (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(failedPage(verified.locale), 500, { "Cache-Control": "no-store" });
       }
-      return c.html(unsubscribedPage(await signResubscribeToken(verified, encodedSecret)), 200, {
-        "Cache-Control": "no-store",
-      });
+      return c.html(
+        unsubscribedPage(await signResubscribeToken(verified, encodedSecret), verified.locale),
+        200,
+        { "Cache-Control": "no-store" },
+      );
     },
   });
 
@@ -482,6 +537,14 @@ export function createUnsubscribeRoutes(
       verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret, "resubscribe"),
     handler: async (c, verified, deps) => {
       const outcome = await dispatchResubscribeWrite(verified, deps);
+      // The undo button on the unsubscribed page posts a form; a browser should land on a page.
+      if (isFormRequest(c.req.header("content-type"))) {
+        return outcome === "success"
+          ? c.html(resubscribedPage(verified.locale), 200, { "Cache-Control": "no-store" })
+          : c.html(failedPage(verified.locale), outcome === "limit_reached" ? 409 : 500, {
+              "Cache-Control": "no-store",
+            });
+      }
       if (outcome === "limit_reached") {
         return c.json({ error: { code: DeliveryErrors.resubscribeLimitReached } }, 409, {
           "Cache-Control": "no-store",

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

@@ -15,7 +15,7 @@ export const derivativesSharpFeature = defineFeature(FEATURE_NAME, (r) => {
     category: "storage",
     recommended: false,
   });
-  r.requires("file-derivatives");
+  r.requires({ features: ["file-derivatives"] });
 
   const plugin: DerivativeRendererPlugin = { render: renderImage };
   r.useExtension(EXT_DERIVATIVE_RENDERER, "image/*", plugin);

package/packages/bundled-features/src/document-ingest-foundation/feature.ts

@@ -132,9 +132,9 @@ export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) =
   });
   // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
   // tenant-subject ciphertext and needs the destroy hook below.
-  r.requires("config", "tenant-lifecycle");
+  r.requires({ features: ["config", "tenant-lifecycle"] });
 
-  r.entity("documentExtract", documentExtractEntity);
+  r.entity({ name: "documentExtract", ...documentExtractEntity });
   r.useExtension(EXT_TENANT_DATA, "documentExtract", {
     destroy: documentExtractTenantDestroyHook,
   });

package/packages/bundled-features/src/file-derivatives/feature.ts

@@ -111,12 +111,12 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
     });
     // Needs a storage provider to read the original + write the variant —
     // without file-foundation there's nothing to derive from or write to.
-    r.requires("file-foundation");
+    r.requires({ features: ["file-foundation"] });
     // variant() reads fileRefsTable, which "files" (not file-foundation)
     // owns — without this, mounting file-derivatives + file-foundation
     // alone boots fine but fails at request-time with a SQL error the first
     // time variant() runs.
-    r.requires("files");
+    r.requires({ features: ["files"] });
 
     r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
       onRegister: () => {
@@ -164,7 +164,7 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
         // tenant's public variants from staying reachable — require the
         // dependency so a missing mount fails boot, not the tenant check
         // silently no-op-ing at request time.
-        r.requires("tenant");
+        r.requires({ features: ["tenant"] });
         r.queryHandler(publicVariantByFileRefQuery);
       }
 

package/packages/bundled-features/src/file-foundation/feature.ts

@@ -46,7 +46,7 @@ export const fileFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
     category: "storage",
     recommended: false,
   });
-  r.requires("config");
+  r.requires({ features: ["config"] });
 
   r.extendsRegistrar(EXT_FILE_PROVIDER, {
     onRegister: () => {

package/packages/bundled-features/src/file-provider-inmemory/feature.ts

@@ -68,10 +68,10 @@ export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
     category: "storage",
     recommended: false,
   });
-  // Kein r.requires("config") + kein r.requires("secrets") — der
+  // Kein requires auf "config" oder "secrets" — der
   // In-Memory-Provider hat keine Config + kein Secret. Nur die
   // file-foundation muss da sein (Plugin-extension-point).
-  r.requires("file-foundation");
+  r.requires({ features: ["file-foundation"] });
 
   const plugin: FileProviderPlugin = {
     build: async (_ctx: FileProviderContext, tenantId: string): Promise<FileStorageProvider> => {

package/packages/bundled-features/src/file-provider-s3/feature.ts

@@ -47,9 +47,9 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
     category: "storage",
     recommended: false,
   });
-  r.requires("config");
-  r.requires("secrets");
-  r.requires("file-foundation");
+  r.requires({ features: ["config"] });
+  r.requires({ features: ["secrets"] });
+  r.requires({ features: ["file-foundation"] });
 
   const secretAccessKey = r.secret("s3.secretAccessKey", {
     label: { en: "S3 secret access key" },

package/packages/bundled-features/src/file-provider-s3-env/feature.ts

@@ -42,10 +42,10 @@ export const fileProviderS3EnvFeature = defineFeature(FEATURE_NAME, (r) => {
     category: "storage",
     recommended: false,
   });
-  // No r.requires("config") / r.requires("secrets") — credentials come from
+  // No requires on "config" or "secrets" — credentials come from
   // env, not the per-tenant config + secrets store. Only the file-foundation
   // plugin-extension-point must be mounted.
-  r.requires("file-foundation");
+  r.requires({ features: ["file-foundation"] });
 
   const plugin: FileProviderPlugin = {
     // tenantId ignored: one shared bucket serves all tenants (isolation via

package/packages/bundled-features/src/files/README.md

@@ -5,7 +5,7 @@ Sprint-1.5 Refactor (Pre-Sprint-2).
 
 ## Was es macht
 
-Deklariert `r.entity("fileRef", ...)` für die DB-Tabelle die das
+Deklariert `r.entity({ name: "fileRef", ... })` für die DB-Tabelle die das
 Framework via `createFileRoutes` (multipart-Upload + binary-Download)
 bewirtschaftet. Das öffnet die Tür für Cross-Feature-Hooks:
 

package/packages/bundled-features/src/files-tenant-data/index.ts

@@ -39,7 +39,7 @@ export function createFilesTenantDataFeature(): FeatureDefinition {
       category: "compliance",
       recommended: false,
     });
-    r.requires("tenant-lifecycle");
+    r.requires({ features: ["tenant-lifecycle"] });
     r.optionalRequires("files");
 
     r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy: fileRefTenantDestroyHook });

package/packages/bundled-features/src/folders/feature.ts

@@ -58,8 +58,8 @@ function registerFolders(
   if (toggleable !== undefined) r.toggleable(toggleable);
 
   const folderAssignmentEntity = createFolderAssignmentEntity(ownership, parents);
-  r.entity("folder", folderEntity);
-  r.entity("folder-assignment", folderAssignmentEntity);
+  r.entity({ name: "folder", ...folderEntity });
+  r.entity({ name: "folder-assignment", ...folderAssignmentEntity });
 
   // Folder catalog — plain CRUD, no custom logic. update is rename (and, in a
   // later stage, reparent: it accepts changes.parentId, optimistic-locked).

package/packages/bundled-features/src/folders-user-data/index.ts

@@ -20,7 +20,7 @@ export const foldersUserDataFeature = defineFeature("folders-user-data", (r) =>
   // OPTIONAL: if it's mounted toggleable(default=false) (e.g. per-tenant via
   // tier), a hard r.requires would throw an "effectively disabled" boot
   // warning even though the folder entities exist and the hooks work fine.
-  r.requires("user-data-rights");
+  r.requires({ features: ["user-data-rights"] });
   r.optionalRequires("folders");
   r.useExtension(EXT_USER_DATA, "folder", {
     export: folderExportHook,

package/packages/bundled-features/src/form-draft/feature.ts

@@ -30,11 +30,11 @@ function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>):
   // config is optional: the retention-days key only resolves when the
   // config feature is mounted (ctx.configResolver present) — the cleanup
   // job already falls back to FORM_DRAFT_DEFAULT_RETENTION_DAYS otherwise
-  // (see handlers/cleanup.job.ts). A hard r.requires("config") would break
+  // (see handlers/cleanup.job.ts). A hard r.requires({ features: ["config"] }) would break
   // every app that mounts form-draft without config, which is a breaking
   // change no minor/patch release should introduce silently.
   r.optionalRequires("config");
-  r.entity("form-draft", formDraftEntity);
+  r.entity({ name: "form-draft", ...formDraftEntity });
 
   r.writeHandler(saveDraftWrite);
   r.writeHandler(discardDraftWrite);

package/packages/bundled-features/src/form-draft-user-data/index.ts

@@ -12,7 +12,7 @@ export const formDraftUserDataFeature = defineFeature("form-draft-user-data", (r
   r.describe(
     "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `form-draft` feature's `form-draft` entity. Mounts the EXT_USER_DATA export hook so a user's saved drafts are included in the user-data export bundle, and a delete hook that physically removes the user's own draft rows on forget. Kept separate from `form-draft` so form-draft consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `form-draft`.",
   );
-  r.requires("user-data-rights");
+  r.requires({ features: ["user-data-rights"] });
   r.optionalRequires("form-draft");
   r.useExtension(EXT_USER_DATA, "form-draft", {
     export: formDraftExportHook,