@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/step-dispatcher/feature.ts

@@ -0,0 +1,299 @@
+// step-dispatcher — bundled-feature that drains deferred Tier-2 step
+// requests (webhook.send, mail.send, ...) after their TX commits.
+//
+// Listens on the `kumiko:system:step.dispatch-requested` system event
+// (registry-bypassed, see SYSTEM_EVENT_PREFIX).
+// Performs the side-effect and emits `kumiko:system:step.dispatched`
+// or `kumiko:system:step.dispatch-failed` back onto the same stream so
+// the audit trail lives in the event log only — no separate status table.
+
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiValueForSubject,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  defineFeature,
+  type FeatureDefinition,
+  STEP_DISPATCH_AGGREGATE_TYPE,
+  STEP_DISPATCH_FAILED_TYPE,
+  STEP_DISPATCH_REQUESTED_TYPE,
+  STEP_DISPATCHED_TYPE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import * as z from "zod";
+import {
+  type MailSpec,
+  mailSpecSchema,
+  performMailDispatch,
+  redactEmailAddresses,
+} from "./mail-runner.js";
+import {
+  performWebhookDispatch,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS,
+  type WebhookSpec,
+  webhookSpecSchema,
+} from "./webhook-runner.js";
+
+const log = createFallbackLogger("step-dispatcher");
+
+export const stepDispatcherEnvSchema = z.object({
+  [WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
+    .string()
+    .optional()
+    .describe(
+      "Comma-separated operator allowlist of private/internal hosts (e.g. a local webhook-receiver for dev/test) that bypass the public-address check for webhook.send targets. Never a tenant-config value.",
+    ),
+});
+
+export { STEP_DISPATCH_AGGREGATE_TYPE };
+
+// PII fields of the flat payload are ciphertext under the per-dispatch
+// record key (system-event-pii.ts). `to`/`headersJson`/`bodyJson` are JSON
+// strings because event PII encryption only handles top-level strings.
+// Runtime-validated instead of cast — `event.payload` is `unknown` at the
+// MSP-apply boundary, so a payload in another shape must end as
+// dispatch-failed, never reach the runners.
+const dispatchRequestedPayloadSchema = z.discriminatedUnion("stepKind", [
+  z.object({
+    stepKind: z.literal("webhook.send"),
+    url: z.string(),
+    method: webhookSpecSchema.shape.method,
+    headersJson: z.string(),
+    bodyJson: z.string().optional(),
+    auth: webhookSpecSchema.shape.auth,
+    retry: z.object({ times: z.number(), backoff: z.enum(["exponential", "linear"]) }).optional(),
+  }),
+  z.object({
+    stepKind: z.literal("mail.send"),
+    to: z.string(),
+    subject: z.string(),
+    body: z.string(),
+    from: z.string().optional(),
+  }),
+]);
+
+type DispatchRequestedPayload = z.infer<typeof dispatchRequestedPayloadSchema>;
+
+// zod issue messages can echo the invalid value (e.g. a rejected url) back
+// into the tenant-visible dispatch-failed event — keep this generic.
+const INVALID_DISPATCH_PAYLOAD_ERROR = "invalid dispatch payload";
+const PAYLOAD_UNREADABLE_ERROR = "dispatch payload is not readable";
+// Adapter errors (e.g. SMTP 550) usually echo the recipient address; the
+// dispatch-failed text outlives the payload erase, so only this is persisted.
+const MAIL_DELIVERY_FAILED_ERROR = "mail delivery failed";
+const PAYLOAD_ERASED_ERROR = "dispatch payload erased before an outcome was recorded";
+
+const rawStepKindSchema = z.object({ stepKind: z.string() });
+
+function rawStepKindOf(payload: unknown): string {
+  const parsed = rawStepKindSchema.safeParse(payload);
+  return parsed.success ? parsed.data.stepKind : "unknown";
+}
+
+const jsonStringSchema = z.string().transform((raw, refinementCtx) => {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed;
+  } catch {
+    refinementCtx.addIssue({ code: "custom", message: "invalid json" });
+    return z.NEVER;
+  }
+});
+
+const headersJsonSchema = jsonStringSchema.pipe(z.record(z.string(), z.string()));
+const mailToJsonSchema = jsonStringSchema.pipe(mailSpecSchema.shape.to);
+
+type PayloadFieldName = "to" | "subject" | "body" | "from" | "url" | "headersJson" | "bodyJson";
+
+function piiFieldsOf(payload: DispatchRequestedPayload): readonly PayloadFieldName[] {
+  return payload.stepKind === "mail.send"
+    ? ["to", "subject", "body", "from"]
+    : ["url", "headersJson", "bodyJson"];
+}
+
+function payloadFieldValue(
+  payload: DispatchRequestedPayload,
+  field: PayloadFieldName,
+): string | undefined {
+  const values: Readonly<Partial<Record<PayloadFieldName, string>>> =
+    payload.stepKind === "mail.send"
+      ? { to: payload.to, subject: payload.subject, body: payload.body, from: payload.from }
+      : { url: payload.url, headersJson: payload.headersJson, bodyJson: payload.bodyJson };
+  return values[field];
+}
+
+type ReadPayloadResult =
+  | { readonly kind: "ready"; readonly fields: Readonly<Partial<Record<PayloadFieldName, string>>> }
+  | { readonly kind: "erased" }
+  | { readonly kind: "unreadable" };
+
+async function readPayloadFields(payload: DispatchRequestedPayload): Promise<ReadPayloadResult> {
+  const kms = configuredPiiSubjectKms();
+  const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
+  const fields: Partial<Record<PayloadFieldName, string>> = {};
+  for (const field of piiFieldsOf(payload)) {
+    const value = payloadFieldValue(payload, field);
+    if (value === undefined) continue;
+    if (!isPiiCiphertext(value)) {
+      fields[field] = value;
+      continue;
+    }
+    if (!kms) return { kind: "unreadable" };
+    const plain = await decryptPiiValueForSubject(kms, value, { requestId }, field);
+    if (plain === PII_ERASED_SENTINEL) return { kind: "erased" };
+    fields[field] = plain;
+  }
+  return { kind: "ready", fields };
+}
+
+type DispatchSpec =
+  | { readonly stepKind: "mail.send"; readonly spec: MailSpec }
+  | { readonly stepKind: "webhook.send"; readonly spec: WebhookSpec };
+
+// Parse failures return null — the caller records a generic error, never the
+// (decrypted) values.
+function buildDispatchSpec(
+  payload: DispatchRequestedPayload,
+  fields: Readonly<Partial<Record<PayloadFieldName, string>>>,
+): DispatchSpec | null {
+  if (payload.stepKind === "mail.send") {
+    const to = mailToJsonSchema.safeParse(fields.to);
+    if (!to.success || fields.subject === undefined || fields.body === undefined) return null;
+    return {
+      stepKind: "mail.send",
+      spec: {
+        to: to.data,
+        subject: fields.subject,
+        body: fields.body,
+        ...(fields.from !== undefined && { from: fields.from }),
+      },
+    };
+  }
+  const headers = headersJsonSchema.safeParse(fields.headersJson);
+  if (!headers.success || fields.url === undefined) return null;
+  let body: unknown;
+  if (fields.bodyJson !== undefined) {
+    const parsedBody = jsonStringSchema.safeParse(fields.bodyJson);
+    if (!parsedBody.success) return null;
+    body = parsedBody.data;
+  }
+  return {
+    stepKind: "webhook.send",
+    spec: {
+      url: fields.url,
+      method: payload.method,
+      headers: headers.data,
+      ...(body !== undefined && { body }),
+      ...(payload.auth && { auth: payload.auth }),
+    },
+  };
+}
+
+export function createStepDispatcherFeature(): FeatureDefinition {
+  return defineFeature("step-dispatcher", (r) => {
+    r.describe(
+      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.",
+    );
+    r.secretNamespace("webhook-auth", WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS);
+    r.uiHints({
+      displayLabel: "Step Dispatcher · Deferred Side-Effects",
+      category: "infrastructure",
+      recommended: false,
+    });
+    r.envSchema(stepDispatcherEnvSchema);
+    r.requires("secrets");
+
+    r.multiStreamProjection({
+      name: "step-dispatcher",
+      apply: {
+        [STEP_DISPATCH_REQUESTED_TYPE]: async (event, _tx, ctx) => {
+          const kms = configuredPiiSubjectKms();
+          const requestId = requestContext.get()?.requestId ?? "step-dispatcher";
+
+          // Outcome events are plaintext and generic; the request payload's
+          // per-dispatch key is erased right after, so the PII dies with the
+          // dispatch instead of living in the event log.
+          const recordOutcome = async (
+            type: typeof STEP_DISPATCHED_TYPE | typeof STEP_DISPATCH_FAILED_TYPE,
+            payload: Record<string, unknown>,
+          ): Promise<void> => {
+            await ctx.unsafeAppendEvent({
+              aggregateId: event.aggregateId,
+              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+              type,
+              payload,
+            });
+            await kms?.eraseKey(
+              { kind: "record", entity: STEP_DISPATCH_AGGREGATE_TYPE, id: event.aggregateId },
+              { requestId, eraseReason: "step-dispatch-outcome-recorded" },
+            );
+          };
+          const recordFailure = (stepKind: string, error: string) =>
+            recordOutcome(STEP_DISPATCH_FAILED_TYPE, { stepKind, error, attempt: 1 });
+
+          const parsed = dispatchRequestedPayloadSchema.safeParse(event.payload);
+          if (!parsed.success) {
+            await recordFailure(rawStepKindOf(event.payload), INVALID_DISPATCH_PAYLOAD_ERROR);
+            // skip: invalid payload already recorded via step.dispatch-failed above, nothing left to dispatch
+            return;
+          }
+          const payload = parsed.data;
+
+          const read = await readPayloadFields(payload);
+          if (read.kind === "unreadable") {
+            await recordFailure(payload.stepKind, PAYLOAD_UNREADABLE_ERROR);
+            // skip: unreadable payload already recorded via step.dispatch-failed above
+            return;
+          }
+          if (read.kind === "erased") {
+            const stream = await ctx.loadAggregate(event.aggregateId);
+            const hasOutcome = stream.some(
+              (e) => e.type === STEP_DISPATCHED_TYPE || e.type === STEP_DISPATCH_FAILED_TYPE,
+            );
+            // skip: redelivery after the key was erased — the outcome is already recorded
+            if (hasOutcome) return;
+            await recordFailure(payload.stepKind, PAYLOAD_ERASED_ERROR);
+            // skip: erased payload recorded via step.dispatch-failed above
+            return;
+          }
+
+          const dispatchSpec = buildDispatchSpec(payload, read.fields);
+          if (!dispatchSpec) {
+            await recordFailure(payload.stepKind, INVALID_DISPATCH_PAYLOAD_ERROR);
+            // skip: unparseable payload already recorded via step.dispatch-failed above
+            return;
+          }
+          const result =
+            dispatchSpec.stepKind === "webhook.send"
+              ? await performWebhookDispatch(dispatchSpec.spec, {
+                  tenantId: event.tenantId,
+                  userId: event.metadata.userId || SYSTEM_USER_ID,
+                  secrets: ctx.secrets,
+                })
+              : await performMailDispatch(dispatchSpec.spec);
+          if (result.ok) {
+            await recordOutcome(STEP_DISPATCHED_TYPE, {
+              stepKind: payload.stepKind,
+              status: result.status,
+            });
+          } else {
+            if (payload.stepKind === "mail.send") {
+              log.warn("mail dispatch failed", {
+                aggregateId: event.aggregateId,
+                reason: redactEmailAddresses(result.error),
+              });
+              await recordFailure(payload.stepKind, MAIL_DELIVERY_FAILED_ERROR);
+            } else {
+              await recordFailure(payload.stepKind, result.error);
+            }
+          }
+        },
+      },
+    });
+  });
+}

package/packages/bundled-features/src/step-dispatcher/index.ts

@@ -0,0 +1,25 @@
+export {
+  createStepDispatcherFeature,
+  STEP_DISPATCH_AGGREGATE_TYPE,
+  stepDispatcherEnvSchema,
+} from "./feature.js";
+export {
+  type MailDispatchResult,
+  type MailSpec,
+  mailSpecSchema,
+  performMailDispatch,
+  setMailRunner,
+} from "./mail-runner.js";
+export {
+  performWebhookDispatch,
+  readAllowedPrivateWebhookHostsFromEnv,
+  setWebhookFetch,
+  setWebhookHostLookup,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  WEBHOOK_AUTH_SECRET_KEY_PREFIX,
+  type WebhookDispatchDeps,
+  type WebhookDispatchResult,
+  type WebhookSpec,
+  webhookAuthSecretKey,
+  webhookSpecSchema,
+} from "./webhook-runner.js";

package/packages/bundled-features/src/step-dispatcher/mail-runner.ts

@@ -0,0 +1,39 @@
+// Mail execution logic — separated from feature.ts and tests-injectable.
+// Production wiring (mail-foundation transport) is a follow-up; the
+// default impl throws so a missing setMailRunner is loud, not silent.
+
+import * as z from "zod";
+
+export const mailSpecSchema = z.object({
+  to: z.union([z.string(), z.array(z.string())]),
+  subject: z.string(),
+  body: z.string(),
+  from: z.string().optional(),
+});
+
+export type MailSpec = z.infer<typeof mailSpecSchema>;
+
+export type MailDispatchResult =
+  | { readonly ok: true; readonly status: number }
+  | { readonly ok: false; readonly error: string };
+
+let mailRunner: (spec: MailSpec) => Promise<MailDispatchResult> = async () => ({
+  ok: false,
+  error:
+    "no mail-runner configured — call setMailRunner() with a mail-foundation transport adapter",
+});
+
+export function setMailRunner(fn: (spec: MailSpec) => Promise<MailDispatchResult>): void {
+  mailRunner = fn;
+}
+
+// @wrapper-known entry-point
+export async function performMailDispatch(spec: MailSpec): Promise<MailDispatchResult> {
+  return mailRunner(spec);
+}
+
+// Adapter errors usually quote the rejected recipient ("550 <ops@example.com> rejected"); the
+// address must not outlive the crypto-shredded dispatch payload in logs.
+export function redactEmailAddresses(text: string): string {
+  return text.replace(/[^\s<>,;"']+@[^\s<>,;"']+/g, "[redacted-address]");
+}

package/packages/bundled-features/src/step-dispatcher/webhook-runner.ts

@@ -0,0 +1,221 @@
+// Webhook execution logic — separated from feature.ts so tests can stub
+// the fetch without touching the MSP wiring.
+//
+// `spec.url` is request-controlled (a write-handler or workflow step reads
+// it straight from tenant/user input — see samples/recipes/webhook-step for
+// the reference usage), so it gets the same connect-time host-egress guard
+// as tenant-supplied SMTP/IMAP hosts: resolve once, reject a private/
+// reserved address, and pin the connect to the resolved address (Host
+// header + TLS SNI keep the original hostname for cert validation).
+//
+// `allowedPrivateWebhookHosts` is the operator's own escape hatch for an
+// internal receiver or a dev/test endpoint — an operator env var
+// (KUMIKO_WEBHOOK_ALLOWED_PRIVATE_HOSTS), never a tenant-config key, so a
+// tenant can never grant themselves the bypass. Own key, not the mail
+// features' — step-dispatcher has no dependency relation to mail-transport-
+// smtp/inbound-provider-imap and shouldn't require mounting them.
+//
+// `auth.secret` resolves through the secrets feature under the tenant-owned
+// namespace `step-dispatcher:webhook-auth.<secret>` — the target URL is
+// tenant/request-controlled, so a webhook can never read a platform-wide or
+// another tenant's secret.
+
+import type { lookup } from "node:dns/promises";
+import {
+  BlockedHostError,
+  buildPinnedRequest,
+  HostResolutionError,
+  resolvePublicHostname,
+} from "@cosmicdrift/kumiko-framework/http";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { TenantId } from "@cosmicdrift/kumiko-types/identifiers";
+import * as z from "zod";
+import { isHostAllowlisted, readHostAllowlistFromEnv } from "../foundation-shared/index.js";
+
+const log = createFallbackLogger("step-dispatcher");
+
+export const WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_WEBHOOK_ALLOWED_PRIVATE_HOSTS";
+
+export function readAllowedPrivateWebhookHostsFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): readonly string[] {
+  return readHostAllowlistFromEnv(WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR, env);
+}
+
+// Test-only DNS seam — production never calls this, resolvePublicHostname
+// defaults to the real resolver. Reset it in afterEach/afterAll — this is
+// module-global state.
+let webhookHostLookup: typeof lookup | undefined;
+
+export function setWebhookHostLookup(fn: typeof lookup | undefined): void {
+  webhookHostLookup = fn;
+}
+
+// Tenant-owned namespace every webhook auth secret lives under in the
+// secrets feature. Applied at resolution time, never at step-build time,
+// so `auth.secret` stays a short, human-picked name (e.g. "smtp.password")
+// while the stored key stays collision-free with every other feature's
+// secrets.
+export const WEBHOOK_AUTH_SECRET_KEY_PREFIX = "step-dispatcher:webhook-auth.";
+
+export function webhookAuthSecretKey(name: string): string {
+  return `${WEBHOOK_AUTH_SECRET_KEY_PREFIX}${name}`;
+}
+
+const WEBHOOK_AUTH_SECRET_NAME_MAX_LENGTH = 100 - WEBHOOK_AUTH_SECRET_KEY_PREFIX.length;
+
+const webhookAuthSecretNameSchema = z
+  .string()
+  .min(1)
+  .max(WEBHOOK_AUTH_SECRET_NAME_MAX_LENGTH)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+
+// The same schema validates `auth.secret` in the step spec and the suffix the
+// secrets handlers accept under the namespace, so the two cannot drift. The
+// prefix itself is derived from the feature name by r.secretNamespace; the
+// boot test pins it to WEBHOOK_AUTH_SECRET_KEY_PREFIX.
+export const WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS = {
+  label: { en: "Webhook auth secrets" },
+  scope: "tenant",
+  nameSchema: webhookAuthSecretNameSchema,
+} as const;
+
+export const webhookSpecSchema = z.object({
+  url: z.string(),
+  method: z.enum(["POST", "PUT", "PATCH"]),
+  headers: z.record(z.string(), z.string()),
+  body: z.unknown().optional(),
+  auth: z
+    .union([
+      z.object({ kind: z.literal("bearer"), secret: webhookAuthSecretNameSchema }),
+      z.object({
+        kind: z.literal("header"),
+        name: z.string(),
+        secret: webhookAuthSecretNameSchema,
+      }),
+    ])
+    .optional(),
+});
+
+export type WebhookSpec = z.infer<typeof webhookSpecSchema>;
+
+export type WebhookDispatchResult =
+  | { readonly ok: true; readonly status: number }
+  | { readonly ok: false; readonly error: string };
+
+let fetchImpl: typeof fetch = globalThis.fetch.bind(globalThis);
+
+export function setWebhookFetch(fn: typeof fetch): void {
+  fetchImpl = fn;
+}
+
+export type WebhookDispatchDeps = {
+  readonly tenantId: TenantId;
+  readonly userId: string;
+  readonly secrets: SecretsContext | undefined;
+};
+
+// Never includes the secret name or value — spec.auth.secret is a
+// tenant-chosen name, but the error still reaches the tenant via the
+// dispatch-failed event, so it stays generic.
+const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not available";
+
+async function buildWebhookHeaders(
+  spec: WebhookSpec,
+  deps: WebhookDispatchDeps,
+): Promise<{ ok: true; headers: Record<string, string> } | { ok: false; error: string }> {
+  const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
+  if (!spec.auth) return { ok: true, headers };
+  if (!deps.secrets) return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
+  // A throwing get (corrupt envelope, rotated key, KMS error) must become a
+  // dispatch-failed event; rethrowing would retry and dead-letter the whole
+  // step-dispatcher consumer for every tenant.
+  let secret: string;
+  try {
+    const revealed = await deps.secrets.get(deps.tenantId, webhookAuthSecretKey(spec.auth.secret), {
+      userId: deps.userId,
+      handlerName: "step-dispatcher:webhook.send",
+    });
+    if (!revealed) return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
+    secret = revealed.reveal();
+  } catch {
+    log.warn("webhook auth secret lookup failed", { tenantId: deps.tenantId });
+    return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
+  }
+  if (spec.auth.kind === "bearer") {
+    headers["authorization"] = `Bearer ${secret}`;
+  } else {
+    headers[spec.auth.name] = secret;
+  }
+  return { ok: true, headers };
+}
+
+async function resolveWebhookFetchTarget(
+  rawUrl: string,
+  url: URL,
+  headers: Record<string, string>,
+): Promise<
+  { ok: true; fetchUrl: string | URL; requestInit: RequestInit } | { ok: false; error: string }
+> {
+  if (isHostAllowlisted(url.hostname, readAllowedPrivateWebhookHostsFromEnv()))
+    return { ok: true, fetchUrl: rawUrl, requestInit: { headers } };
+  try {
+    const resolved = await resolvePublicHostname(url.hostname, webhookHostLookup);
+    const pinned = buildPinnedRequest(url, resolved, { headers });
+    return { ok: true, fetchUrl: pinned.url, requestInit: pinned.init };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    if (err instanceof BlockedHostError || err instanceof HostResolutionError) {
+      log.warn("webhook host unreachable", { host: url.hostname, reason });
+      return { ok: false, error: "webhook host is not reachable or not allowed" };
+    }
+    throw err;
+  }
+}
+
+export async function performWebhookDispatch(
+  spec: WebhookSpec,
+  deps: WebhookDispatchDeps,
+): Promise<WebhookDispatchResult> {
+  // Host-egress guard at the primitive boundary: only http(s), the target
+  // host must resolve to a public address (unless operator-allowlisted),
+  // and redirects are never followed — a 3xx could point at an internal/
+  // metadata target and the spec carries secrets (auth) that would be
+  // forwarded there. A webhook destination that redirects now surfaces as
+  // a delivery error instead.
+  let url: URL;
+  try {
+    url = new URL(spec.url);
+  } catch {
+    return { ok: false, error: "invalid url" };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return { ok: false, error: `unsupported url scheme "${url.protocol}"` };
+  }
+
+  const headers = await buildWebhookHeaders(spec, deps);
+  if (!headers.ok) return headers;
+
+  const target = await resolveWebhookFetchTarget(spec.url, url, headers.headers);
+  if (!target.ok) return target;
+
+  try {
+    const res = await fetchImpl(target.fetchUrl, {
+      ...target.requestInit,
+      method: spec.method,
+      redirect: "manual",
+      body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
+    });
+    if (!res.ok) {
+      return { ok: false, error: `HTTP ${res.status}: ${res.statusText}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (err) {
+    // err.message can echo the request URL; this text outlives the payload erase.
+    return {
+      ok: false,
+      error: `webhook request failed (${err instanceof Error ? err.name : "unknown error"})`,
+    };
+  }
+}

package/packages/bundled-features/src/subscription-mollie/changes.json

@@ -0,0 +1,28 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "Mollie checkout carries consentId through payment and subscription metadata",
+    "detail": "`consentId` from the checkout options is stored in the first payment's metadata, copied onto the subscription created from it, and returned as `SubscriptionEvent.consentId` when valid. `cancelSubscription` stays unimplemented for Mollie.",
+    "migration": "No code change needed."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "Mollie webhooks no longer archive the subscription and payment objects",
+    "detail": "Subscription events parsed from Mollie webhooks no longer include the serialized subscription and trigger payment, which can carry consumer name and account data."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "Mollie one-off prices no longer need an interval; a subscription price without one is rejected",
+    "detail": "`MolliePriceConfig.interval` is now optional so one-off prices (credit top-ups, `mode: \"payment\"`) no longer need a dummy interval. A price without `interval` booked as a subscription now fails at checkout creation, and a paid first payment for such a price creates no Mollie subscription (a warning is logged). The \"checkout url is null\" error no longer blames first-payment mandates for one-off payments.",
+    "migration": "Mollie checkout creation now throws for a subscription price without `interval`; set `interval` on every subscription price (one-off `mode: \"payment\"` prices need none)."
+  },
+  {
+    "version": "0.318.0",
+    "type": "fix",
+    "title": "subscription-mollie now advertises its priceToTier map to billing-foundation",
+    "detail": "createSubscriptionMollieFeature already required and validated a priceToTier option (drift-checked against priceToConfig at boot), but never put it on the SubscriptionProviderPlugin object it registers. billing-foundation's new create-checkout-session hardening rejects any mode:\"subscription\" checkout from a provider with no priceToTier as provider_has_no_price_catalog. Without this fix, every existing Mollie-configured app would fail every subscription checkout after upgrading."
+  }
+]

package/packages/bundled-features/src/subscription-mollie/constants.ts

@@ -0,0 +1,33 @@
+// Feature name
+export const SUBSCRIPTION_MOLLIE_FEATURE = "subscription-mollie" as const;
+
+// entityName under den der Plugin gegen "subscriptionProvider"
+// registriert. Matcht den path-segment in der webhook-URL
+// `/api/subscription/webhook/mollie`.
+export const MOLLIE_PROVIDER_NAME = "mollie" as const;
+
+// =============================================================================
+// Mollie-Webhook-Pattern (anders als Stripe!)
+// =============================================================================
+//
+// Mollie sendet bei JEDEM event nur die ID im body (form-urlencoded
+// oder JSON). Plugin muss IMMER lazy-fetchen via Mollie-API:
+//   - `id=tr_xxx`  → payment-id, fetch payment + subscription
+//   - `id=sub_xxx` → subscription-id, fetch subscription direkt
+//
+// **Keine native HMAC-sig-verify** in Mollie-SDK 4.5.0. Mollie's
+// Sicherheits-Modell stützt sich auf nicht-guessable IDs (~10^25
+// brute-force-space) + API-Lookup-Validation (garbage-id → 401 von
+// Mollie-API). Plus: App-Builder kann zusätzlich einen URL-Token-
+// Wrapper vor die Foundation-route schalten (eigener extraRoute der
+// einen secret-token im URL-Pfad verifiziert + dann an die Foundation
+// weiterreicht).
+//
+// **Event-Type-Mapping** ist heuristisch — Mollie hat keine explicit-
+// typed events:
+//   - sub_xxx + status=canceled/completed     → SubscriptionEventTypes.canceled
+//   - sub_xxx + status=active/pending         → SubscriptionEventTypes.updated
+//   - tr_xxx + sequenceType=first + paid      → SubscriptionEventTypes.created
+//   - tr_xxx + sequenceType=recurring + paid  → SubscriptionEventTypes.invoicePaid
+//   - tr_xxx + sequenceType=recurring + failed → SubscriptionEventTypes.invoicePaymentFailed
+//   - alles andere                            → null (foundation 200 ignored)