@cosmicdrift/kumiko-bundled-features 0.326.1 → 0.327.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.326.1",
+  "version": "0.327.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>",
@@ -134,12 +134,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.326.1",
-    "@cosmicdrift/kumiko-framework": "0.326.1",
-    "@cosmicdrift/kumiko-headless": "0.326.1",
-    "@cosmicdrift/kumiko-renderer": "0.326.1",
-    "@cosmicdrift/kumiko-renderer-web": "0.326.1",
-    "@cosmicdrift/kumiko-types": "0.326.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.327.0",
+    "@cosmicdrift/kumiko-framework": "0.327.0",
+    "@cosmicdrift/kumiko-headless": "0.327.0",
+    "@cosmicdrift/kumiko-renderer": "0.327.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.327.0",
+    "@cosmicdrift/kumiko-types": "0.327.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.326.1",
-    "@cosmicdrift/kumiko-locale-es": "0.326.1",
+    "@cosmicdrift/kumiko-locale-de": "0.327.0",
+    "@cosmicdrift/kumiko-locale-es": "0.327.0",
     "jsqr": "^1.4.0"
   }
 }

package/src/step-dispatcher/__tests__/step-dispatcher-pii.integration.test.ts

@@ -0,0 +1,268 @@
+// step-dispatcher crypto-shredding (fw#2057): the dispatch-requested payload
+// carries recipient/subject/body/url/headers as ciphertext under a
+// per-dispatch record key; the dispatcher decrypts to send, then erases the
+// key once the outcome is recorded — redelivery after that must be a no-op.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  decryptPiiValueForSubject,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  KeyErasedError,
+  PII_CIPHERTEXT_PREFIX,
+  PII_ERASED_SENTINEL,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import {
+  defineFeature,
+  defineWriteHandler,
+  stepsPipeline,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  resetEventStore,
+  setupTestStack,
+  type TestStack,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
+import * as z from "zod";
+import { createSecretsFeature } from "../../secrets";
+import {
+  createStepDispatcherFeature,
+  type MailDispatchResult,
+  type MailSpec,
+  setMailRunner,
+  setWebhookFetch,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+} from "../index";
+
+const DISPATCH_REQUESTED = "kumiko:system:step.dispatch-requested";
+const DISPATCHED = "kumiko:system:step.dispatched";
+const DISPATCH_FAILED = "kumiko:system:step.dispatch-failed";
+
+const probeFeature = defineFeature("step-pii-probe", (r) => {
+  r.requires.step("mail.send");
+  r.requires.step("webhook.send");
+
+  r.writeHandler(
+    defineWriteHandler({
+      name: "notify-mail",
+      schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
+      access: { roles: ["Admin"] },
+      perform: stepsPipeline<{ to: string; subject: string; body: string }, { ok: true }>(
+        ({ event, r }) => [
+          r.step.mail.send({
+            to: () => event.payload.to,
+            subject: () => event.payload.subject,
+            body: () => event.payload.body,
+            mode: "deferred",
+          }),
+          r.step.return(() => ({ isSuccess: true as const, data: { ok: true as const } })),
+        ],
+      ),
+    }),
+  );
+
+  r.writeHandler(
+    defineWriteHandler({
+      name: "notify-webhook",
+      schema: z.object({ url: z.string(), token: z.string() }),
+      access: { roles: ["Admin"] },
+      perform: stepsPipeline<{ url: string; token: string }, { ok: true }>(({ event, r }) => [
+        r.step.webhook.send({
+          url: () => event.payload.url,
+          headers: () => ({ "x-probe-token": event.payload.token }),
+          body: () => ({ secretNote: "webhook-body-secret" }),
+          mode: "deferred",
+        }),
+        r.step.return(() => ({ isSuccess: true as const, data: { ok: true as const } })),
+      ]),
+    }),
+  );
+});
+
+const admin = createTestUser({ roles: ["Admin"] });
+const fetchMock = mock<typeof fetch>();
+const mailMock = mock<(spec: MailSpec) => Promise<MailDispatchResult>>();
+const originalAllowedPrivateHostsEnv = process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+
+let stack: TestStack;
+let kms: InMemoryKmsAdapter;
+
+type EventRow = { aggregateId: string; payload: Record<string, unknown> };
+
+async function eventsOfType(type: string): Promise<EventRow[]> {
+  return (await selectMany(stack.db, eventsTable, { type })) as unknown as EventRow[];
+}
+
+async function drain(): Promise<void> {
+  await stack.eventDispatcher?.runOnce();
+}
+
+async function requestedRow(): Promise<EventRow> {
+  const rows = await eventsOfType(DISPATCH_REQUESTED);
+  expect(rows).toHaveLength(1);
+  return rows[0]!;
+}
+
+async function expectKeyErased(aggregateId: string): Promise<void> {
+  await expect(
+    kms.getKey({ kind: "record", entity: "step-dispatch", id: aggregateId }),
+  ).rejects.toBeInstanceOf(KeyErasedError);
+}
+
+beforeAll(async () => {
+  // hooks.example is a placeholder host — operator allowlist instead of DNS.
+  process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "hooks.example";
+  setWebhookFetch(fetchMock as unknown as typeof fetch);
+  setMailRunner(async (spec: MailSpec) => mailMock(spec));
+  stack = await setupTestStack({
+    features: [createStepDispatcherFeature(), createSecretsFeature(), probeFeature],
+    systemHooks: [],
+  });
+});
+
+afterAll(async () => {
+  if (originalAllowedPrivateHostsEnv === undefined) {
+    delete process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+  } else {
+    process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = originalAllowedPrivateHostsEnv;
+  }
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  fetchMock.mockReset();
+  mailMock.mockReset();
+  mailMock.mockResolvedValue({ ok: true, status: 202 });
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+  await resetEventStore(stack, []);
+  await stack.redis.flushNamespace();
+  await stack.eventDispatcher?.ensureRegistered();
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+const MAIL_INPUT = { to: "ops@example.com", subject: "Server down", body: "Disk is full" };
+
+describe("step-dispatcher payload crypto-shredding", () => {
+  test("mail.send: ciphertext at rest, plaintext to the runner, key erased after dispatched", async () => {
+    await stack.http.writeOk("step-pii-probe:write:notify-mail", MAIL_INPUT, admin);
+
+    const requested = await requestedRow();
+    const keyPrefix = `${PII_CIPHERTEXT_PREFIX}record:step-dispatch:${requested.aggregateId}:`;
+    for (const field of ["to", "subject", "body"]) {
+      const stored = String(requested.payload[field]);
+      expect(stored.startsWith(keyPrefix)).toBe(true);
+    }
+    expect(JSON.stringify(requested.payload)).not.toContain("ops@example.com");
+    expect(JSON.stringify(requested.payload)).not.toContain("Disk is full");
+
+    await drain();
+
+    expect(mailMock).toHaveBeenCalledTimes(1);
+    expect(mailMock).toHaveBeenCalledWith({
+      to: "ops@example.com",
+      subject: "Server down",
+      body: "Disk is full",
+    });
+    expect(await eventsOfType(DISPATCHED)).toHaveLength(1);
+    await expectKeyErased(requested.aggregateId);
+    const afterErase = await decryptPiiValueForSubject(
+      kms,
+      String(requested.payload["to"]),
+      { requestId: "test" },
+      "to",
+    );
+    expect(afterErase).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("failed delivery erases the key too", async () => {
+    mailMock.mockResolvedValue({ ok: false, error: "550 <ops@example.com> rejected" });
+    await stack.http.writeOk("step-pii-probe:write:notify-mail", MAIL_INPUT, admin);
+    const requested = await requestedRow();
+
+    await drain();
+
+    const failed = await eventsOfType(DISPATCH_FAILED);
+    expect(failed).toHaveLength(1);
+    expect(failed[0]?.payload["error"]).toBe("mail delivery failed");
+    expect(JSON.stringify(failed[0]?.payload)).not.toContain("ops@example.com");
+    await expectKeyErased(requested.aggregateId);
+  });
+
+  test("redelivery after the erase neither re-sends nor throws nor records a second outcome", async () => {
+    await stack.http.writeOk("step-pii-probe:write:notify-mail", MAIL_INPUT, admin);
+    await drain();
+    expect(mailMock).toHaveBeenCalledTimes(1);
+
+    await asRawClient(stack.db).unsafe(
+      `UPDATE kumiko_event_consumers SET last_processed_event_id = 0 WHERE name LIKE '%step-dispatcher%'`,
+    );
+    await drain();
+
+    expect(mailMock).toHaveBeenCalledTimes(1);
+    expect(await eventsOfType(DISPATCHED)).toHaveLength(1);
+    expect(await eventsOfType(DISPATCH_FAILED)).toHaveLength(0);
+  });
+
+  test("a key erased before any outcome ends as a generic dispatch-failed, without sending", async () => {
+    await stack.http.writeOk("step-pii-probe:write:notify-mail", MAIL_INPUT, admin);
+    const requested = await requestedRow();
+    await kms.eraseKey({ kind: "record", entity: "step-dispatch", id: requested.aggregateId });
+
+    await drain();
+
+    expect(mailMock).not.toHaveBeenCalled();
+    const failed = await eventsOfType(DISPATCH_FAILED);
+    expect(failed).toHaveLength(1);
+    expect(failed[0]?.payload["error"]).toBe(
+      "dispatch payload erased before an outcome was recorded",
+    );
+  });
+
+  test("ciphertext without a configured KMS ends as generic dispatch-failed", async () => {
+    await stack.http.writeOk("step-pii-probe:write:notify-mail", MAIL_INPUT, admin);
+    resetPiiSubjectKmsForTests();
+
+    await drain();
+
+    expect(mailMock).not.toHaveBeenCalled();
+    const failed = await eventsOfType(DISPATCH_FAILED);
+    expect(failed).toHaveLength(1);
+    expect(JSON.stringify(failed[0]?.payload)).not.toContain("ops@example.com");
+  });
+
+  test("webhook.send: url, headers and body are ciphertext at rest and plaintext to fetch", async () => {
+    fetchMock.mockResolvedValueOnce(new Response(null, { status: 200 }));
+    await stack.http.writeOk(
+      "step-pii-probe:write:notify-webhook",
+      { url: "https://hooks.example/secret-path", token: "probe-token" },
+      admin,
+    );
+
+    const requested = await requestedRow();
+    for (const field of ["url", "headersJson", "bodyJson"]) {
+      expect(isPiiCiphertext(requested.payload[field])).toBe(true);
+    }
+    expect(JSON.stringify(requested.payload)).not.toContain("secret-path");
+    expect(JSON.stringify(requested.payload)).not.toContain("probe-token");
+    expect(JSON.stringify(requested.payload)).not.toContain("webhook-body-secret");
+
+    await drain();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [calledUrl, init] = fetchMock.mock.calls[0]!;
+    expect(calledUrl).toBe("https://hooks.example/secret-path");
+    expect(new Headers(init?.headers).get("x-probe-token")).toBe("probe-token");
+    expect(JSON.parse(init?.body as string)).toEqual({ secretNote: "webhook-body-secret" });
+    expect(await eventsOfType(DISPATCHED)).toHaveLength(1);
+    await expectKeyErased(requested.aggregateId);
+  });
+});

package/src/step-dispatcher/__tests__/webhook-runner.test.ts

@@ -276,8 +276,22 @@ describe("performWebhookDispatch — auth.secret resolution", () => {
       { tenantId: TEST_TENANT_ID, userId: TEST_USER_ID, secrets },
     );
 
-    expect(result.ok).toBe(false);
+    expect(result).toEqual({ ok: false, error: "invalid url" });
     expect(get).not.toHaveBeenCalled();
     expect(fetchMock).not.toHaveBeenCalled();
   });
+
+  test("a failing request never echoes the request url into the delivery error", async () => {
+    setWebhookHostLookup(fakeLookupFor({ "secret-host.example": "203.0.113.9" }));
+    setWebhookFetch((async () => {
+      throw new TypeError("connect ECONNREFUSED https://secret-host.example/hook?token=abc");
+    }) as unknown as typeof fetch);
+
+    const result = await performWebhookDispatch(
+      { url: "https://secret-host.example/hook?token=abc", method: "POST", headers: {} },
+      { tenantId: TEST_TENANT_ID, userId: TEST_USER_ID, secrets: undefined },
+    );
+
+    expect(result).toEqual({ ok: false, error: "webhook request failed (TypeError)" });
+  });
 });

package/src/step-dispatcher/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.327.0",
+    "type": "breaking",
+    "title": "step.dispatch-requested payloads are flat and crypto-shredded; kumiko:system:* events have a declared PII stance",
+    "migration": "No code change is needed for r.step.mail.send / r.step.webhook.send callers. The step.dispatch-requested payload changed from a nested `spec` object to flat fields (mail.send: to as JSON string, subject, body, from; webhook.send: url, method, headersJson, bodyJson, auth, retry). With a subject KMS configured, those fields are encrypted under a per-dispatch record key (record:step-dispatch:<aggregateId>) that the step-dispatcher erases once the outcome is recorded (Art. 17 via crypto-shredding). There is no legacy branch: a dispatch-requested event still in flight at upgrade (old nested shape) ends as step.dispatch-failed with error \"invalid dispatch payload\", so drain the queue before deploying or accept the one-time failed event. Webhook delivery errors no longer echo the URL or the raw request error. mail.send delivery errors are recorded as a generic \"mail delivery failed\"; the adapter's raw error goes to the step-dispatcher log. Code reading dispatch-requested payloads directly must switch to the flat shape. A new kumiko:system:* event type must be added to SYSTEM_EVENT_PII_STANCES (crypto/system-event-pii.ts); encryptEventPayloadPii throws for an undeclared system type. SYSTEM_EVENT_PREFIX and AGGREGATE_TRANSFERRED_EVENT_TYPE now live in crypto/system-event-pii.ts, and the STEP_DISPATCH_* constants are exported from @cosmicdrift/kumiko-framework/engine instead of engine/steps/webhook-send."
+  },
   {
     "version": "0.321.0",
     "type": "breaking",

package/src/step-dispatcher/feature.ts

@@ -2,21 +2,39 @@
 // requests (webhook.send, mail.send, ...) after their TX commits.
 //
 // Listens on the `kumiko:system:step.dispatch-requested` system event
-// (registry-bypassed, see append-event-core.ts SYSTEM_EVENT_PREFIX).
+// (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 { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+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 { mailSpecSchema, performMailDispatch } from "./mail-runner";
+import { type MailSpec, mailSpecSchema, performMailDispatch } from "./mail-runner";
 import {
   performWebhookDispatch,
   WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  type WebhookSpec,
   webhookSpecSchema,
 } from "./webhook-runner";
 
+const log = createFallbackLogger("step-dispatcher");
+
 export const stepDispatcherEnvSchema = z.object({
   [WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
     .string()
@@ -26,26 +44,43 @@ export const stepDispatcherEnvSchema = z.object({
     ),
 });
 
-export const STEP_DISPATCH_AGGREGATE_TYPE = "step-dispatch";
-export const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-requested";
-export const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
-export const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
+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 (unsafeAppendEvent), so a payload in an older or
-// foreign shape must end as dispatch-failed, never reach performWebhookDispatch.
+// 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"),
-    spec: webhookSpecSchema,
+    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"), spec: mailSpecSchema }),
+  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() });
 
@@ -54,6 +89,105 @@ function rawStepKindOf(payload: unknown): string {
   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(
@@ -71,44 +205,85 @@ export function createStepDispatcherFeature(): FeatureDefinition {
       name: "step-dispatcher",
       apply: {
         [STEP_DISPATCH_REQUESTED_TYPE]: async (event, _tx, ctx) => {
-          const parsed = dispatchRequestedPayloadSchema.safeParse(event.payload);
-          if (!parsed.success) {
+          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: STEP_DISPATCH_FAILED_TYPE,
-              payload: {
-                stepKind: rawStepKindOf(event.payload),
-                error: INVALID_DISPATCH_PAYLOAD_ERROR,
-                attempt: 1,
-              },
+              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 =
-            payload.stepKind === "webhook.send"
-              ? await performWebhookDispatch(payload.spec, {
+            dispatchSpec.stepKind === "webhook.send"
+              ? await performWebhookDispatch(dispatchSpec.spec, {
                   tenantId: event.tenantId,
                   userId: event.metadata.userId || SYSTEM_USER_ID,
                   secrets: ctx.secrets,
                 })
-              : await performMailDispatch(payload.spec);
+              : await performMailDispatch(dispatchSpec.spec);
           if (result.ok) {
-            await ctx.unsafeAppendEvent({
-              aggregateId: event.aggregateId,
-              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
-              type: STEP_DISPATCHED_TYPE,
-              payload: { stepKind: payload.stepKind, status: result.status },
+            await recordOutcome(STEP_DISPATCHED_TYPE, {
+              stepKind: payload.stepKind,
+              status: result.status,
             });
           } else {
-            await ctx.unsafeAppendEvent({
-              aggregateId: event.aggregateId,
-              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
-              type: STEP_DISPATCH_FAILED_TYPE,
-              payload: { stepKind: payload.stepKind, error: result.error, attempt: 1 },
-            });
+            if (payload.stepKind === "mail.send") {
+              log.warn("mail dispatch failed", {
+                aggregateId: event.aggregateId,
+                reason: result.error,
+              });
+              await recordFailure(payload.stepKind, MAIL_DELIVERY_FAILED_ERROR);
+            } else {
+              await recordFailure(payload.stepKind, result.error);
+            }
           }
         },
       },

package/src/step-dispatcher/webhook-runner.ts

@@ -179,7 +179,7 @@ export async function performWebhookDispatch(
   try {
     url = new URL(spec.url);
   } catch {
-    return { ok: false, error: `invalid url "${spec.url}"` };
+    return { ok: false, error: "invalid url" };
   }
   if (url.protocol !== "http:" && url.protocol !== "https:") {
     return { ok: false, error: `unsupported url scheme "${url.protocol}"` };
@@ -203,6 +203,10 @@ export async function performWebhookDispatch(
     }
     return { ok: true, status: res.status };
   } catch (err) {
-    return { ok: false, error: err instanceof Error ? err.message : String(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/src/workflow-runner/__tests__/resume-loop.integration.test.ts

@@ -79,7 +79,7 @@ const retryWorkflow: WorkflowDefinition = defineWorkflow({
       do: [
         r.step.compute("gate", (ctx) => {
           const attempt = ctx.workflow?.retryAttempt ?? 1;
-          if (attempt === 1) throw new Error("first-attempt-fails");
+          if (attempt === 1) throw new Error("send to jane.doe@example.com failed");
           return attempt;
         }),
       ],
@@ -289,6 +289,9 @@ describe("workflow-runner resume loop", () => {
       WORKFLOW_RETRY_SCHEDULED_TYPE,
     ]);
     expect(rowsAfterSuspend[1]!["payload"]).toMatchObject({ stepIndex: 0, attempt: 1 });
+    // The event outlives an erase, so it carries the error class only.
+    expect(rowsAfterSuspend[1]!["payload"]["error"]).toBe("workflow step failed (Error)");
+    expect(JSON.stringify(rowsAfterSuspend[1]!["payload"])).not.toContain("jane.doe@example.com");
 
     await tamperWakeAtToPast(runId, 0);
     await runResumeDueRunsJob();

package/src/workflow-runner/__tests__/workflow-runner.integration.test.ts

@@ -52,7 +52,7 @@ const failingWorkflow: WorkflowDefinition = defineWorkflow({
   idempotencyKey: ({ payload }) => (payload as { runKey: string }).runKey,
   steps: stepsPipeline(({ r }) => [
     r.step.compute("boom", () => {
-      throw new Error("boom-explicit-failure");
+      throw new Error("boom-explicit-failure for jane.doe@example.com");
     }),
     r.step.return({ isSuccess: true, data: undefined }),
   ]),
@@ -186,7 +186,7 @@ describe("workflow-runner event-trigger", () => {
     });
   });
 
-  test("error path: a throwing step writes run-failed with the error text, no run-completed", async () => {
+  test("error path: a throwing step writes run-failed with a generic error text, no run-completed", async () => {
     const runKey = crypto.randomUUID();
     const runId = workflowRunAggregateId(failingWorkflow.name, runKey);
     // The registrar namespaces every MSP as `<feature>:projection:<name>`.
@@ -223,7 +223,10 @@ describe("workflow-runner event-trigger", () => {
       WORKFLOW_RUN_FAILED_TYPE,
     ]);
     expect(rows[1]!["payload"]).toMatchObject({ workflowName: failingWorkflow.name, stepIndex: 0 });
-    expect(String(rows[1]!["payload"]["error"])).toContain("boom-explicit-failure");
+    // The event outlives an erase, so it carries the error class only.
+    expect(rows[1]!["payload"]["error"]).toBe("workflow step failed (Error)");
+    expect(JSON.stringify(rows[1]!["payload"])).not.toContain("boom-explicit-failure");
+    expect(JSON.stringify(rows[1]!["payload"])).not.toContain("jane.doe@example.com");
 
     // Second pass has nothing left to redeliver — the same trigger event
     // never spawns a second run-started for this runId. `processed` counts

package/src/workflow-runner/changes.json

@@ -1 +1,8 @@
-[]
+[
+  {
+    "version": "0.327.0",
+    "type": "breaking",
+    "title": "Workflow run-failed and retry.scheduled events store a generic error text instead of the raw error",
+    "migration": "The `error` field of workflow.run-failed and workflow.retry.scheduled events is now generic, \"workflow step failed (<error class>)\" (or \"(unknown error)\" for non-Error throwables), because the raw text can contain recipients or payload fragments and would survive an erase. The raw error goes to the log (namespace workflow-runner, and the framework logger for retry). Code that parses the `error` text must switch to `reason` (machine-readable, set for definition changes) or to the logs. Already stored events keep their old text. The texts for an unregistered workflow and a definition-fingerprint mismatch are unchanged. describeWorkflowStepError is exported from @cosmicdrift/kumiko-framework/engine."
+  }
+]

package/src/workflow-runner/event-trigger.ts

@@ -16,14 +16,18 @@ import type {
   WriteEvent,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
+  describeWorkflowStepError,
   WORKFLOW_AGGREGATE_TYPE,
   WORKFLOW_RUN_FAILED_TYPE,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { workflowRunAggregateId } from "./aggregate-id";
 import { registerEventWakeup } from "./event-subscriber";
 import { startAndRunWorkflow, type WorkflowRunFailedPayload } from "./runner";
 import { registerWorkflow } from "./workflow-registry";
 
+const log = createFallbackLogger("workflow-runner");
+
 export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefinition): void {
   // Populate the workflow-registry unconditionally, before the event-trigger
   // guard below — resume-run (framework#2513 Phase 2) looks workflows up by
@@ -89,10 +93,16 @@ export function registerEventTrigger(r: FeatureRegistrar, workflow: WorkflowDefi
             handlerCtx: ctx as never,
           });
         } catch (error) {
-          const failedPayload: WorkflowRunFailedPayload = {
+          log.warn("workflow run failed", {
+            runId,
             workflowName: workflow.name,
             stepIndex: 0,
             error: String(error),
+          });
+          const failedPayload: WorkflowRunFailedPayload = {
+            workflowName: workflow.name,
+            stepIndex: 0,
+            error: describeWorkflowStepError(error),
           };
           await ctx.unsafeAppendEvent({
             aggregateId: runId,

package/src/workflow-runner/handlers/resume-run.write.ts

@@ -31,6 +31,7 @@ import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   buildPipelineSteps,
   computeDefinitionFingerprint,
+  describeWorkflowStepError,
   getStep,
   type HandlerContext,
   runStepList,
@@ -48,6 +49,7 @@ import {
   type WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import * as z from "zod";
 import {
   isResumableSuspension,
@@ -59,6 +61,8 @@ import {
 import { workflowRunPendingTable } from "../tables";
 import { getWorkflow } from "../workflow-registry";
 
+const log = createFallbackLogger("workflow-runner");
+
 const resumeRunSchema = z.object({
   runId: z.string().min(1),
   stepIndex: z.number().int().nonnegative(),
@@ -338,10 +342,11 @@ export const resumeRunHandler: WriteHandlerDef = {
       });
       return { isSuccess: true, data: { outcome: "completed" as const } };
     } catch (error) {
+      log.warn("workflow run failed", { runId, workflowName, stepIndex, error: String(error) });
       const failedPayload: WorkflowRunFailedPayload = {
         workflowName,
         stepIndex,
-        error: String(error),
+        error: describeWorkflowStepError(error),
       };
       await appendRunFailed(ctx, runId, failedPayload);
       return { isSuccess: true, data: { outcome: "failed" as const } };

package/src/workflow-runner/runner.ts

@@ -57,10 +57,12 @@ export type WorkflowRunCompletedPayload = {
 export type WorkflowRunFailedPayload = {
   readonly workflowName: string;
   readonly stepIndex: number;
+  // Generic text (class name only), never the raw error message: the event
+  // survives an erase. The raw error goes to the log.
   readonly error: string;
   // Machine-readable failure category — set by resume-run for a Q7
   // fingerprint mismatch ("workflow_definition_changed"); absent for a
-  // plain pipeline-step failure (the `error` string is human-readable only).
+  // plain pipeline-step failure (the `error` string is generic).
   readonly reason?: string;
 };