@cosmicdrift/kumiko-bundled-features 0.319.0 → 0.320.0

package/src/mail-transport-smtp/feature.ts

@@ -25,14 +25,21 @@
 //   - `config` — für die Tenant-Config-Keys
 //   - `secrets` — für das verschlüsselte SMTP-Password
 
+import type { lookup } from "node:dns/promises";
 import {
   createSmtpTransport,
   type EmailTransport,
 } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import {
+  BlockedHostError,
+  HostResolutionError,
+  MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  type MailConnectTarget,
+  readAllowedPrivateMailHostsFromEnv,
   requireDefined,
   requireNonEmpty,
   requireSecretSet,
+  resolveMailConnectTarget,
 } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   MAIL_TRANSPORT_EXTENSION,
@@ -41,9 +48,41 @@ import {
 } from "@cosmicdrift/kumiko-bundled-features/mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { access, createTenantConfig, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import * as z from "zod";
 
 const FEATURE_NAME = "mail-transport-smtp";
 
+const log = createFallbackLogger(FEATURE_NAME);
+
+// Operator escape hatch for an internal relay or a dev/test SMTP server
+// (mailpit, MailHog): KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, an operator env
+// var never a tenant-config value, so a tenant can never grant themselves
+// the private-host bypass. Declared here (not duplicated in
+// inbound-provider-imap's envSchema) since both features read the same
+// var and composeEnvSchema rejects two features declaring the same key —
+// see foundation-shared/mail-host-policy.ts for the shared reader + the
+// guard this feeds.
+export const mailTransportSmtpEnvSchema = z.object({
+  [MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
+    .string()
+    .optional()
+    .describe(
+      "Comma-separated operator allowlist of private/internal hosts (e.g. a local mailpit/greenmail dev server) that bypass the public-address check for SMTP and IMAP host config. Shared with inbound-provider-imap — never a tenant-config value.",
+    ),
+});
+
+// Test-only DNS seam — production never calls this, resolveMailConnectTarget
+// defaults to the real resolver. Lets tests pin deterministic, network-free
+// host resolutions instead of depending on real DNS for a placeholder host.
+// Reset it in afterEach/afterAll — this is module-global state.
+let mailHostLookup: typeof lookup | undefined;
+
+export function setSmtpMailHostLookup(fn: typeof lookup | undefined): void {
+  mailHostLookup = fn;
+}
+
 // =============================================================================
 // Feature-definition
 // =============================================================================
@@ -60,6 +99,7 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
   r.requires("config");
   r.requires("secrets");
   r.requires("mail-foundation");
+  r.envSchema(mailTransportSmtpEnvSchema);
 
   // Provider-secret. Sensitive: redact-helper for admin-UI display.
   const password = r.secret("smtp.password", {
@@ -134,6 +174,18 @@ export const SMTP_PASSWORD = mailTransportSmtpFeature.exports.password;
 // Internal: build the EmailTransport from tenant config + secret
 // =============================================================================
 
+// Tenant-visible for both a blocked host and a DNS failure — must not
+// reveal which one occurred, or the host itself. Built once so a
+// HostResolutionError raised for the other branch can reuse the exact same
+// `.message` string byte-for-byte instead of just a similar hint.
+function mailHostUnreachableError(): UnconfiguredError {
+  return new UnconfiguredError({
+    feature: FEATURE_NAME,
+    key: "host",
+    hint: "host is not reachable or not allowed",
+  });
+}
+
 async function buildSmtpTransport(
   ctx: MailTransportContext,
   tenantId: string,
@@ -177,12 +229,35 @@ async function buildSmtpTransport(
 
   const password = await readPassword(ctx, tenantId);
 
+  let target: MailConnectTarget;
+  try {
+    target = await resolveMailConnectTarget(host, {
+      allowedPrivateMailHosts: readAllowedPrivateMailHostsFromEnv(),
+      lookupFn: mailHostLookup,
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    // Both branches throw the exact same tenant-visible message text — the
+    // blocked-vs-unresolvable distinction and the host itself stay
+    // server-log-only. Class stays distinct: UnconfiguredError (422, a
+    // config problem, no retry) for a blocked host vs HostResolutionError
+    // (transient, retried) for a DNS failure — see mailHostUnreachableError().
+    const unreachable = mailHostUnreachableError();
+    if (err instanceof BlockedHostError) {
+      log.warn("rejected blocked host", { host, reason });
+      throw unreachable;
+    }
+    log.warn("host resolution failed", { host, reason });
+    throw new HostResolutionError(unreachable.message);
+  }
+
   return createSmtpTransport({
-    host,
+    host: target.host,
     port,
     secure,
     from,
     auth: { user: authUser, pass: password },
+    ...(target.servername && { servername: target.servername }),
   });
 }
 

package/src/mail-transport-smtp/index.ts

@@ -1,3 +1,8 @@
 // Public API of the mail-transport-smtp bundled-feature.
 
-export { mailTransportSmtpFeature, SMTP_PASSWORD } from "./feature";
+export {
+  mailTransportSmtpEnvSchema,
+  mailTransportSmtpFeature,
+  SMTP_PASSWORD,
+  setSmtpMailHostLookup,
+} from "./feature";

package/src/personal-access-tokens/__tests__/pat.integration.test.ts

@@ -9,6 +9,7 @@ import {
   isPiiCiphertext,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createInMemoryFileProvider } from "@cosmicdrift/kumiko-framework/files";
 import {
   setupTestStack,
   type TestStack,
@@ -124,6 +125,10 @@ beforeAll(async () => {
       // ≤2 requests per (distinct) token, so this ceiling never trips them.
       patRateLimiter: createInMemoryLoginRateLimiter(3, 60_000),
     },
+    // Only exercised by the route-guard describe block below (POST/GET
+    // /api/files) — proves the guard blocks a PAT there even though the
+    // route is actually mounted and reachable for a JWT/cookie caller.
+    files: { storageProvider: createInMemoryFileProvider() },
   });
   h = makeSessionHelpers(stack, TENANT);
 
@@ -550,3 +555,57 @@ describe("PAT list projection (fw#2548 Teil B)", () => {
     expect(expired.rows[0]?.status).toBe("expired");
   });
 });
+
+describe("PAT route guard: dispatcher routes only (#security)", () => {
+  test("PAT → GET /api/sse → 403, even with a granted scope", async () => {
+    const actor = await actorFor("route-guard-sse@example.com");
+    const token = await mintToken(actor);
+    const res = await stack.http.raw("GET", "/api/sse", undefined, {
+      Authorization: `Bearer ${token}`,
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("access_denied");
+  });
+
+  test("PAT → POST /api/files → 403 (route is mounted — a JWT gets past the guard to the 400 validation)", async () => {
+    const actor = await actorFor("route-guard-files-post@example.com");
+    const token = await mintToken(actor);
+    const patRes = await h.authedPost("/api/files", token);
+    expect(patRes.status).toBe(403);
+
+    const jwt = await loginToken("route-guard-files-post@example.com");
+    const jwtRes = await h.authedPost("/api/files", jwt);
+    expect(jwtRes.status).toBe(400);
+  });
+
+  test("PAT → GET /api/files/:id → 403 (a JWT gets past the guard to the 404 not_found)", async () => {
+    const actor = await actorFor("route-guard-files-get@example.com");
+    const token = await mintToken(actor);
+    const patRes = await stack.http.raw("GET", "/api/files/does-not-exist", undefined, {
+      Authorization: `Bearer ${token}`,
+    });
+    expect(patRes.status).toBe(403);
+
+    const jwt = await loginToken("route-guard-files-get@example.com");
+    const jwtRes = await stack.http.raw("GET", "/api/files/does-not-exist", undefined, {
+      Authorization: `Bearer ${jwt}`,
+    });
+    expect(jwtRes.status).toBe(404);
+  });
+
+  test("PAT → GET /api/auth/tenants → 403 (a JWT reaches the real 200)", async () => {
+    const actor = await actorFor("route-guard-tenants@example.com");
+    const token = await mintToken(actor);
+    const patRes = await stack.http.raw("GET", "/api/auth/tenants", undefined, {
+      Authorization: `Bearer ${token}`,
+    });
+    expect(patRes.status).toBe(403);
+
+    const jwt = await loginToken("route-guard-tenants@example.com");
+    const jwtRes = await stack.http.raw("GET", "/api/auth/tenants", undefined, {
+      Authorization: `Bearer ${jwt}`,
+    });
+    expect(jwtRes.status).toBe(200);
+  });
+});

package/src/sessions/__tests__/sessions.integration.test.ts

@@ -100,6 +100,11 @@ beforeEach(async () => {
     userSessionTable,
     eventsTable,
   ]);
+  // login.write.ts is `per: "ip+handler"` rate-limited (20/60s). h.login()
+  // goes through stack.http.raw with no socket address, so every test in
+  // this file shares one "unknown" IP bucket — flush it per test so the
+  // file's cumulative login() calls can't push a later test over the cap.
+  await stack.redis.flushNamespace();
 });
 
 describe("sessions feature — login → check → revoke → rejected", () => {

package/src/shared/password-hashing.test.ts

@@ -1,15 +1,15 @@
 import { describe, expect, test } from "bun:test";
 import { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
 
-const medianMs = async (fn: () => Promise<unknown>, runs = 5): Promise<number> => {
-  const samples: number[] = [];
-  for (let i = 0; i < runs; i++) {
-    const start = performance.now();
-    await fn();
-    samples.push(performance.now() - start);
-  }
-  samples.sort((a, b) => a - b);
-  return samples[Math.floor(samples.length / 2)] ?? 0;
+const timeMs = async (fn: () => Promise<unknown>): Promise<number> => {
+  const start = performance.now();
+  await fn();
+  return performance.now() - start;
+};
+
+const median = (samples: readonly number[]): number => {
+  const sorted = [...samples].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)] ?? 0;
 };
 
 // #774: the login no-user path must cost the same argon2 latency as a real
@@ -24,12 +24,20 @@ describe("verifyDummyPassword (anti-enumeration timing)", () => {
     // warm the lazily-cached dummy hash so we time the verify, not the one-off hash
     await verifyDummyPassword("warmup");
 
-    const realMs = await medianMs(() => verifyPassword(realHash, "wrong-password"));
-    const dummyMs = await medianMs(() => verifyDummyPassword("wrong-password"));
+    // Interleaved so both paths see the same machine load: two back-to-back
+    // median blocks drift apart on a busy CI runner and skew the ratio.
+    const realSamples: number[] = [];
+    const dummySamples: number[] = [];
+    for (let i = 0; i < 7; i++) {
+      realSamples.push(await timeMs(() => verifyPassword(realHash, "wrong-password")));
+      dummySamples.push(await timeMs(() => verifyDummyPassword("wrong-password")));
+    }
+    const realMs = median(realSamples);
+    const dummyMs = median(dummySamples);
 
     // A skipped miss-path (the bug) is sub-millisecond; a real argon2 verify
-    // is ~20ms. A half-of-real floor is a wide, non-flaky bound that still
-    // fails hard if the dummy verify is ever removed.
+    // is ~20ms. A half-of-real floor still fails hard if the dummy verify is
+    // ever removed.
     expect(dummyMs).toBeGreaterThan(realMs * 0.5);
   });
 });

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

@@ -0,0 +1,131 @@
+// Host-egress guard tests for performWebhookDispatch — spec.url is
+// request-controlled (see webhook-runner.ts header), so it must resolve to
+// a public address before any connect is attempted, mirroring the SMTP/
+// IMAP host guard.
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import type { lookup } from "node:dns/promises";
+import {
+  performWebhookDispatch,
+  setWebhookFetch,
+  setWebhookHostLookup,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+} from "../webhook-runner";
+
+function fakeLookupFor(addressesByHost: Readonly<Record<string, string>>): typeof lookup {
+  return (async (hostname: string) => {
+    const address = addressesByHost[hostname];
+    if (!address) throw new Error(`ENOTFOUND ${hostname}`);
+    return [{ address, family: 4 }];
+  }) as unknown as typeof lookup;
+}
+
+const fetchMock = mock<typeof fetch>();
+
+afterEach(() => {
+  fetchMock.mockReset();
+  setWebhookFetch(fetch);
+  setWebhookHostLookup(undefined);
+  delete process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+});
+
+describe("performWebhookDispatch — host-egress guard", () => {
+  test("a private IP-literal host is rejected before any connect attempt", async () => {
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    const result = await performWebhookDispatch({
+      url: "http://10.0.0.5/hook",
+      method: "POST",
+      headers: {},
+    });
+    expect(result.ok).toBe(false);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("a hostname resolving to a private address is rejected, without leaking the resolved address", async () => {
+    setWebhookHostLookup(fakeLookupFor({ "internal.example": "127.0.0.1" }));
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    const result = await performWebhookDispatch({
+      url: "http://internal.example/hook",
+      method: "POST",
+      headers: {},
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).not.toContain("127.0.0.1");
+    }
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("a DNS resolution failure surfaces as a delivery error, not a thrown exception", async () => {
+    setWebhookHostLookup(fakeLookupFor({}));
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    const result = await performWebhookDispatch({
+      url: "http://nowhere.example/hook",
+      method: "POST",
+      headers: {},
+    });
+    expect(result.ok).toBe(false);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("a blocked host and a DNS resolution failure produce the exact same tenant-visible error, without the host", async () => {
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+
+    const blocked = await performWebhookDispatch({
+      url: "http://10.0.0.5/hook",
+      method: "POST",
+      headers: {},
+    });
+    setWebhookHostLookup(fakeLookupFor({}));
+    const unresolvable = await performWebhookDispatch({
+      url: "http://nowhere.example/hook",
+      method: "POST",
+      headers: {},
+    });
+
+    expect(blocked.ok).toBe(false);
+    expect(unresolvable.ok).toBe(false);
+    if (blocked.ok || unresolvable.ok) throw new Error("unreachable");
+    expect(blocked.error).toBe(unresolvable.error);
+    expect(blocked.error).not.toContain("10.0.0.5");
+    expect(unresolvable.error).not.toContain("nowhere.example");
+  });
+
+  test("an operator-allowlisted private host bypasses resolution and keeps its raw url", async () => {
+    process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "webhook-receiver.internal";
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    fetchMock.mockResolvedValueOnce(new Response(null, { status: 200 }));
+
+    const result = await performWebhookDispatch({
+      url: "http://webhook-receiver.internal/hook",
+      method: "POST",
+      headers: {},
+    });
+
+    expect(result.ok).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [calledUrl] = fetchMock.mock.calls[0]!;
+    expect(String(calledUrl)).toBe("http://webhook-receiver.internal/hook");
+  });
+
+  test("a public hostname is pinned to its resolved address, keeping the original host as Host header and TLS SNI", async () => {
+    setWebhookHostLookup(fakeLookupFor({ "hooks.example.com": "203.0.113.9" }));
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    fetchMock.mockResolvedValueOnce(new Response(null, { status: 200 }));
+
+    const result = await performWebhookDispatch({
+      url: "https://hooks.example.com/incident",
+      method: "POST",
+      headers: {},
+    });
+
+    expect(result.ok).toBe(true);
+    const [calledUrl, init] = fetchMock.mock.calls[0]!;
+    expect(String(calledUrl)).toBe("https://203.0.113.9/incident");
+    const headers = init?.headers as Headers;
+    expect(headers.get("host")).toBe("hooks.example.com");
+    expect((init as unknown as { tls?: { servername: string } })?.tls?.servername).toBe(
+      "hooks.example.com",
+    );
+  });
+});

package/src/step-dispatcher/changes.json

@@ -1 +1,14 @@
-[]
+[
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "webhook dispatch failures no longer distinguish a blocked host from a DNS failure",
+    "detail": "`performWebhookDispatch` returns the same generic error\n(\"webhook host is not reachable or not allowed\") for both a blocked\nhost and a DNS resolution failure, instead of two distinguishable\nstrings that also embedded the target hostname in the delivery-attempt\nevent payload. The hostname and the underlying error are now logged via\nthe feature's own logger instead of being included in the result."
+  },
+  {
+    "version": "0.320.0",
+    "type": "breaking",
+    "title": "A webhook.send target host must resolve to a public address",
+    "migration": "A workflow or handler pointing `r.step.webhook.send` at an internal\nreceiver or a local dev/test endpoint (localhost or a private IP) now\ngets a delivery error (step.dispatch-failed) unless that host is\nexplicitly allowed. Set the operator env var (comma-separated, read at\ndispatch time — no boot-time code call needed) before starting the\nprocess:\n  KUMIKO_WEBHOOK_ALLOWED_PRIVATE_HOSTS=webhook-receiver.internal\nThis is an operator env var, not a tenant/workflow-config value — a\nworkflow author cannot add their own host to this list. A DNS resolution\nfailure for a genuinely unreachable host now surfaces as a distinct\ndelivery error instead of only failing later inside `fetch()`."
+  }
+]

package/src/step-dispatcher/feature.ts

@@ -8,8 +8,22 @@
 // the audit trail lives in the event log only — no separate status table.
 
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
 import { type MailSpec, performMailDispatch } from "./mail-runner";
-import { performWebhookDispatch, type WebhookSpec } from "./webhook-runner";
+import {
+  performWebhookDispatch,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  type WebhookSpec,
+} from "./webhook-runner";
+
+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 const STEP_DISPATCH_AGGREGATE_TYPE = "step-dispatch";
 export const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-requested";
@@ -37,6 +51,7 @@ export function createStepDispatcherFeature(): FeatureDefinition {
       category: "infrastructure",
       recommended: false,
     });
+    r.envSchema(stepDispatcherEnvSchema);
 
     r.multiStreamProjection({
       name: "step-dispatcher",

package/src/step-dispatcher/index.ts

@@ -1,4 +1,8 @@
-export { createStepDispatcherFeature, STEP_DISPATCH_AGGREGATE_TYPE } from "./feature";
+export {
+  createStepDispatcherFeature,
+  STEP_DISPATCH_AGGREGATE_TYPE,
+  stepDispatcherEnvSchema,
+} from "./feature";
 export {
   type MailDispatchResult,
   type MailSpec,
@@ -8,8 +12,11 @@ export {
 } from "./mail-runner";
 export {
   performWebhookDispatch,
+  readAllowedPrivateWebhookHostsFromEnv,
   setWebhookFetch,
+  setWebhookHostLookup,
   setWebhookSecretResolver,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
   type WebhookDispatchResult,
   type WebhookSpec,
   webhookSpecSchema,

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

@@ -1,8 +1,56 @@
 // 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.
 
+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 * as z from "zod";
 
+const log = createFallbackLogger("step-dispatcher");
+
+export const WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_WEBHOOK_ALLOWED_PRIVATE_HOSTS";
+
+/** Parses the comma-separated operator allowlist env var. Never throws —
+ *  an unset or empty value just means no bypass. */
+export function readAllowedPrivateWebhookHostsFromEnv(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): readonly string[] {
+  const raw = env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
+  if (!raw) return [];
+  return raw
+    .split(",")
+    .map((host) => host.trim())
+    .filter((host) => host.length > 0);
+}
+
+// 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;
+}
+
 export const webhookSpecSchema = z.object({
   url: z.string(),
   method: z.enum(["POST", "PUT", "PATCH"]),
@@ -38,11 +86,55 @@ export function setWebhookFetch(fn: typeof fetch): void {
   fetchImpl = fn;
 }
 
+function buildWebhookHeaders(
+  spec: WebhookSpec,
+): { 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 };
+  const secret = secretResolver(spec.auth.secretRef);
+  if (!secret) {
+    return { ok: false, error: `secret "${spec.auth.secretRef}" not configured` };
+  }
+  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 }
+> {
+  const isAllowedPrivateHost = readAllowedPrivateWebhookHostsFromEnv().some(
+    (candidate) => candidate.toLowerCase() === url.hostname.toLowerCase(),
+  );
+  if (isAllowedPrivateHost) 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): Promise<WebhookDispatchResult> {
-  // SSRF guard at the primitive boundary: only http(s), and never follow
-  // redirects — 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.
+  // 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);
@@ -53,22 +145,16 @@ export async function performWebhookDispatch(spec: WebhookSpec): Promise<Webhook
     return { ok: false, error: `unsupported url scheme "${url.protocol}"` };
   }
 
-  const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
-  if (spec.auth) {
-    const secret = secretResolver(spec.auth.secretRef);
-    if (!secret) {
-      return { ok: false, error: `secret "${spec.auth.secretRef}" not configured` };
-    }
-    if (spec.auth.kind === "bearer") {
-      headers["authorization"] = `Bearer ${secret}`;
-    } else {
-      headers[spec.auth.name] = secret;
-    }
-  }
+  const headers = buildWebhookHeaders(spec);
+  if (!headers.ok) return headers;
+
+  const target = await resolveWebhookFetchTarget(spec.url, url, headers.headers);
+  if (!target.ok) return target;
+
   try {
-    const res = await fetchImpl(spec.url, {
+    const res = await fetchImpl(target.fetchUrl, {
+      ...target.requestInit,
       method: spec.method,
-      headers,
       redirect: "manual",
       body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
     });

package/src/subscription-stripe/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "subscription-stripe narrows a recurring price interval to a closed union instead of widening on an unrecognized Stripe value",
+    "detail": "stripe >= 22.5 widened Recurring.Interval to an open union. mapStripePrice now maps anything outside RecurringInterval (\"day\" | \"week\" | \"month\" | \"year\") to null via isKnownRecurringInterval, the same as a one-off price, instead of letting an unrecognized interval leak into ProviderPrice untyped. stripe bumped to 22.6.2. Closes #3312."
+  },
   {
     "version": "0.319.0",
     "type": "fix",

package/src/user-data-rights/__tests__/anonymous-deletion.integration.test.ts

@@ -75,6 +75,12 @@ afterAll(async () => {
 beforeEach(async () => {
   verifyCalls.length = 0;
   await resetTestTables(stack.db, [userTable, tenantComplianceProfileTable, eventsTable]);
+  // request-deletion-by-email/confirm-deletion-by-token are `per: "ip"`
+  // rate-limited (10/60s). All calls here go through stack.http.raw with no
+  // socket address, so every test in this file lands in the same shared
+  // "unknown" IP bucket — flush it per test so one test's calls can't push
+  // a later, unrelated test over the cap.
+  await stack.redis.flushNamespace();
 });
 
 async function seedAlice(status: string = USER_STATUS.Active, email: string = ALICE_EMAIL) {
@@ -198,6 +204,11 @@ describe("anonymous deletion flow", () => {
     // instead of a single run (probabilistic test).
     for (let i = 0; i < 20; i++) {
       await resetTestTables(stack.db, [userTable, tenantComplianceProfileTable, eventsTable]);
+      // Both handlers below are `per: "ip"` rate-limited (10/60s); this loop's
+      // own 3 calls/iteration would otherwise trip that limiter well before
+      // the 20th repetition, which has nothing to do with the concurrency
+      // behaviour under test.
+      await stack.redis.flushNamespace();
       await seedAlice();
       verifyCalls.length = 0;
       await stack.http.raw("POST", "/api/write", {