@cosmicdrift/kumiko-bundled-features 0.319.0 → 0.321.0

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

@@ -0,0 +1,283 @@
+// 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 { createSecret, type SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  performWebhookDispatch,
+  setWebhookFetch,
+  setWebhookHostLookup,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  type WebhookDispatchDeps,
+} 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>();
+
+const TEST_TENANT_ID = "11111111-1111-4111-8111-111111111111";
+const TEST_USER_ID = "22222222-2222-4222-8222-222222222222";
+
+const noSecretsDeps: WebhookDispatchDeps = {
+  tenantId: TEST_TENANT_ID,
+  userId: TEST_USER_ID,
+  secrets: undefined,
+};
+
+function fakeSecrets(value: string | undefined) {
+  const get = mock(async () => (value === undefined ? undefined : createSecret(value)));
+  const secrets: SecretsContext = {
+    get,
+    has: async () => value !== undefined,
+    set: async () => {},
+    delete: async () => true,
+  };
+  return { secrets, get };
+}
+
+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: {},
+      },
+      noSecretsDeps,
+    );
+    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: {},
+      },
+      noSecretsDeps,
+    );
+    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: {},
+      },
+      noSecretsDeps,
+    );
+    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: {},
+      },
+      noSecretsDeps,
+    );
+    setWebhookHostLookup(fakeLookupFor({}));
+    const unresolvable = await performWebhookDispatch(
+      {
+        url: "http://nowhere.example/hook",
+        method: "POST",
+        headers: {},
+      },
+      noSecretsDeps,
+    );
+
+    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: {},
+      },
+      noSecretsDeps,
+    );
+
+    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: {},
+      },
+      noSecretsDeps,
+    );
+
+    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",
+    );
+  });
+});
+
+describe("performWebhookDispatch — auth.secret resolution", () => {
+  test("bearer auth sends the tenant's secret under the Authorization header", async () => {
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    fetchMock.mockResolvedValueOnce(new Response(null, { status: 200 }));
+    process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "hooks.example";
+    const { secrets, get } = fakeSecrets("tok_live_abc123");
+
+    const result = await performWebhookDispatch(
+      {
+        url: "http://hooks.example/hook",
+        method: "POST",
+        headers: {},
+        auth: { kind: "bearer", secret: "incident-hook" },
+      },
+      { tenantId: TEST_TENANT_ID, userId: TEST_USER_ID, secrets },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(get).toHaveBeenCalledWith(TEST_TENANT_ID, "step-dispatcher:webhook-auth.incident-hook", {
+      userId: TEST_USER_ID,
+      handlerName: "step-dispatcher:webhook.send",
+    });
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(new Headers(init?.headers).get("authorization")).toBe("Bearer tok_live_abc123");
+  });
+
+  test("header auth sends the tenant's secret under the configured header name", async () => {
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    fetchMock.mockResolvedValueOnce(new Response(null, { status: 200 }));
+    process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "hooks.example";
+    const { secrets } = fakeSecrets("shared-secret-xyz");
+
+    const result = await performWebhookDispatch(
+      {
+        url: "http://hooks.example/hook",
+        method: "POST",
+        headers: {},
+        auth: { kind: "header", name: "x-hub-signature", secret: "incident-hook" },
+      },
+      { tenantId: TEST_TENANT_ID, userId: TEST_USER_ID, secrets },
+    );
+
+    expect(result.ok).toBe(true);
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(new Headers(init?.headers).get("x-hub-signature")).toBe("shared-secret-xyz");
+  });
+
+  test("a missing secret fails without leaking the secret name or fetching", async () => {
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "hooks.example";
+    const { secrets } = fakeSecrets(undefined);
+
+    const result = await performWebhookDispatch(
+      {
+        url: "http://hooks.example/hook",
+        method: "POST",
+        headers: {},
+        auth: { kind: "bearer", secret: "incident-hook" },
+      },
+      { tenantId: TEST_TENANT_ID, userId: TEST_USER_ID, secrets },
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.error).toBe("webhook auth secret is not available");
+    expect(result.error).not.toContain("incident-hook");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("an undefined secrets context fails the same generic way as a missing secret", async () => {
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    process.env[WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR] = "hooks.example";
+
+    const result = await performWebhookDispatch(
+      {
+        url: "http://hooks.example/hook",
+        method: "POST",
+        headers: {},
+        auth: { kind: "bearer", secret: "incident-hook" },
+      },
+      noSecretsDeps,
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.error).toBe("webhook auth secret is not available");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("an invalid url is rejected before any secret is read", async () => {
+    setWebhookFetch(fetchMock as unknown as typeof fetch);
+    const { secrets, get } = fakeSecrets("should-never-be-read");
+
+    const result = await performWebhookDispatch(
+      {
+        url: "not-a-url",
+        method: "POST",
+        headers: {},
+        auth: { kind: "bearer", secret: "incident-hook" },
+      },
+      { tenantId: TEST_TENANT_ID, userId: TEST_USER_ID, secrets },
+    );
+
+    expect(result.ok).toBe(false);
+    expect(get).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});

package/src/step-dispatcher/changes.json

@@ -1 +1,21 @@
-[]
+[
+  {
+    "version": "0.321.0",
+    "type": "breaking",
+    "title": "Webhook auth secrets are now tenant-owned via the secrets feature, not a global env var",
+    "detail": "`r.step.webhook.send`'s `auth` config renamed `secretRef` → `secret`. The\nvalue is now a name inside the tenant-owned secrets namespace\n`step-dispatcher:webhook-auth.<secret>` (secrets feature), resolved via\n`SecretsContext.get()` at dispatch time with an audit read stamped with\nthe triggering event's userId (or the system actor for cron/resume\ndispatches). `setWebhookSecretResolver` / the `WEBHOOK_SECRET_*` env\nconvention are gone. `performWebhookDispatch(spec)` now takes a required\nsecond `deps: { tenantId, userId, secrets }` argument.",
+    "migration": "Mount `createSecretsFeature()` (with a `MasterKeyProvider`) alongside\n`createStepDispatcherFeature()` — boot-validation now fails without it.\nFor each tenant that uses `r.step.webhook.send` with `auth`, set the\ncredential via `secrets:write:set` under\n`step-dispatcher:webhook-auth.<secret>` (the same name passed as\n`auth.secret`). Rename `auth.secretRef` → `auth.secret` at every\n`r.step.webhook.send({ auth: {...} })` call site. Remove any\n`WEBHOOK_SECRET_*` env vars — they're no longer read.\n\nA `step.dispatch-requested` event already enqueued before this upgrade\n(still carrying the old `secretRef` shape) fails validation on drain and\nis recorded as `step.dispatch-failed` with `error: \"invalid dispatch\npayload\"` instead of silently resolving a stale ref — drain the queue (or\naccept the one-time failed event) before deploying.\n\nTests calling `performWebhookDispatch` directly or using\n`setWebhookSecretResolver` must pass a `SecretsContext` (or `undefined`)\nvia the new `deps` argument instead."
+  },
+  {
+    "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,44 +8,92 @@
 // the audit trail lives in the event log only — no separate status table.
 
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { type MailSpec, performMailDispatch } from "./mail-runner";
-import { performWebhookDispatch, type WebhookSpec } from "./webhook-runner";
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import * as z from "zod";
+import { mailSpecSchema, performMailDispatch } from "./mail-runner";
+import {
+  performWebhookDispatch,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  webhookSpecSchema,
+} 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";
 export const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
 export const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
 
-type DispatchRequestedPayload =
-  | {
-      readonly stepKind: "webhook.send";
-      readonly spec: WebhookSpec;
-      readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
-    }
-  | {
-      readonly stepKind: "mail.send";
-      readonly spec: MailSpec;
-    };
+// 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.
+const dispatchRequestedPayloadSchema = z.discriminatedUnion("stepKind", [
+  z.object({
+    stepKind: z.literal("webhook.send"),
+    spec: webhookSpecSchema,
+    retry: z.object({ times: z.number(), backoff: z.enum(["exponential", "linear"]) }).optional(),
+  }),
+  z.object({ stepKind: z.literal("mail.send"), spec: mailSpecSchema }),
+]);
+
+// 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 rawStepKindSchema = z.object({ stepKind: z.string() });
+
+function rawStepKindOf(payload: unknown): string {
+  const parsed = rawStepKindSchema.safeParse(payload);
+  return parsed.success ? parsed.data.stepKind : "unknown";
+}
 
 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`.",
+      "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.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 payload = event.payload as DispatchRequestedPayload;
+          const parsed = dispatchRequestedPayloadSchema.safeParse(event.payload);
+          if (!parsed.success) {
+            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,
+              },
+            });
+            // skip: invalid payload already recorded via step.dispatch-failed above, nothing left to dispatch
+            return;
+          }
+          const payload = parsed.data;
           const result =
             payload.stepKind === "webhook.send"
-              ? await performWebhookDispatch(payload.spec)
+              ? await performWebhookDispatch(payload.spec, {
+                  tenantId: event.tenantId,
+                  userId: event.metadata.userId || SYSTEM_USER_ID,
+                  secrets: ctx.secrets,
+                })
               : await performMailDispatch(payload.spec);
           if (result.ok) {
             await ctx.unsafeAppendEvent({

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,9 +12,14 @@ export {
 } from "./mail-runner";
 export {
   performWebhookDispatch,
+  readAllowedPrivateWebhookHostsFromEnv,
   setWebhookFetch,
-  setWebhookSecretResolver,
+  setWebhookHostLookup,
+  WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,
+  WEBHOOK_AUTH_SECRET_KEY_PREFIX,
+  type WebhookDispatchDeps,
   type WebhookDispatchResult,
   type WebhookSpec,
+  webhookAuthSecretKey,
   webhookSpecSchema,
 } from "./webhook-runner";

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

@@ -1,8 +1,82 @@
 // 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";
 
+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;
+}
+
+// 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._-]*$/);
+
 export const webhookSpecSchema = z.object({
   url: z.string(),
   method: z.enum(["POST", "PUT", "PATCH"]),
@@ -10,8 +84,12 @@ export const webhookSpecSchema = z.object({
   body: z.unknown().optional(),
   auth: z
     .union([
-      z.object({ kind: z.literal("bearer"), secretRef: z.string() }),
-      z.object({ kind: z.literal("header"), name: z.string(), secretRef: z.string() }),
+      z.object({ kind: z.literal("bearer"), secret: webhookAuthSecretNameSchema }),
+      z.object({
+        kind: z.literal("header"),
+        name: z.string(),
+        secret: webhookAuthSecretNameSchema,
+      }),
     ])
     .optional(),
 });
@@ -22,27 +100,81 @@ export type WebhookDispatchResult =
   | { readonly ok: true; readonly status: number }
   | { readonly ok: false; readonly error: string };
 
-// Resolves a secretRef via the test-injectable secret-store. Default
-// implementation reads from process.env at the prefix WEBHOOK_SECRET_.
-// Tests pass a custom resolver via setWebhookSecretResolver.
-let secretResolver: (ref: string) => string | undefined = (ref) =>
-  process.env[`WEBHOOK_SECRET_${ref}`];
-
-export function setWebhookSecretResolver(fn: (ref: string) => string | undefined): void {
-  secretResolver = fn;
-}
-
 let fetchImpl: typeof fetch = globalThis.fetch.bind(globalThis);
 
 export function setWebhookFetch(fn: typeof fetch): void {
   fetchImpl = fn;
 }
 
-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.
+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 };
+  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 };
+  }
+  const secret = revealed.reveal();
+  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,
+  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);
@@ -53,22 +185,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 = 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(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,
     });