@kelpie/server 0.4.0 → 0.5.0

package/migrations/meta/_journal.json

@@ -127,6 +127,13 @@
       "when": 1786490413323,
       "tag": "0017_drop_integration_connections",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1786656430307,
+      "tag": "0018_hard_mystique",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelpie/server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Kelpie service as a library: module runtime, core CRM modules, REST API, MCP surface, and the shared migration pipeline.",
   "keywords": [
     "kelpie",
@@ -52,16 +52,18 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.0.12",
-    "@kelpie/schemas": "^0.4.0",
+    "@kelpie/schemas": "^0.5.0",
     "@node-rs/argon2": "^2.0.2",
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.32",
+    "nodemailer": "^9.0.5",
     "postgres": "^3.4.9",
     "ulid": "^3.0.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
+    "@types/nodemailer": "^8.0.1",
     "drizzle-kit": "^0.31.10",
     "vite": "^8.2.0",
     "vitest": "^4.1.10"

package/src/app.ts

@@ -172,6 +172,22 @@ export function createApp(dependencies: AppDependencies): Hono<AppBindings> {
   app.route(MCP_ROUTE_PREFIX, mcp.transport)
   app.route('/v1', mcp.catalog)
 
+  // Module declarations on the app itself, outside /v1 (`runtime/module.ts`).
+  // Middleware first, all of it, then routes: within one request Hono
+  // composes matching handlers in registration order, so this is what makes
+  // a declared pattern cover matching routes from every module, whichever
+  // registered first. Registered after core's own surfaces above, so nothing
+  // here can run ahead of them. Not rate limited: the `/v1` budgets are
+  // per-workspace-credential, and a declared surface owns its own access
+  // rules.
+  for (const middleware of dependencies.contributions.appMiddleware) {
+    app.use(middleware.pattern, middleware.handler)
+  }
+
+  for (const route of dependencies.contributions.appRoutes) {
+    app.on(route.method, route.path, route.handler)
+  }
+
   app.onError((error, context) => {
     if (error instanceof AppError) {
       return context.json(toErrorBody(error), error.status)

package/src/index.ts

@@ -7,6 +7,8 @@ export type { WebBundleOptions } from './webBundle.ts'
 export { ConfigurationError, loadConfig } from './lib/config.ts'
 export type { Environment, KelpieConfig, LogLevel, RuntimeMode } from './lib/config.ts'
 
+export { resolveClientIpFrom } from './lib/clientIp.ts'
+
 export { ModuleConfigFileError, readModuleConfigFile } from './lib/moduleConfig.ts'
 
 export {
@@ -105,7 +107,13 @@ export { KEY_KINDS, kindOfSecret, mintKey, parseKeyKind, readBearerToken } from
 export type { KeyKind, MintedKey } from './modules/api-keys/keys.ts'
 
 export { registerModules } from './runtime/registry.ts'
-export type { ModuleContributions, ModuleRouter, ModuleRuntimeOptions } from './runtime/registry.ts'
+export type {
+  AppMiddlewareContribution,
+  AppRouteContribution,
+  ModuleContributions,
+  ModuleRouter,
+  ModuleRuntimeOptions,
+} from './runtime/registry.ts'
 export type { ModuleServices } from './runtime/module.ts'
 
 export type { Actor, ApiKeyActor, SessionActor } from './modules/auth/actor.ts'

package/src/lib/appUrl.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod'
+
+/**
+ * The deployment's own base URL, and how token links in transactional mail are
+ * built from it.
+ *
+ * The service builds every reset, verification, and invite link itself, from a
+ * configured base URL. It does not build them from a URL the caller sends. A
+ * caller-supplied link lets anyone point a real Kelpie email at any address,
+ * which is an account-takeover path. The base URL is set once per deployment,
+ * beside the database URL and the mail provider.
+ */
+
+const APP_BASE_URL_MESSAGE = 'must be an absolute http:// or https:// URL, e.g. https://crm.example.com'
+
+/** True when the value is an absolute http(s) URL with no embedded credentials. */
+function isValidBaseUrl(value: string): boolean {
+  let url: URL
+
+  try {
+    url = new URL(value)
+  } catch {
+    return false
+  }
+
+  const protocolAllowed = url.protocol === 'http:' || url.protocol === 'https:'
+
+  return protocolAllowed && url.username.length === 0 && url.password.length === 0
+}
+
+/** The one variable the auth and workspace modules read to build their links. */
+export const appUrlConfigSchema = z.object({
+  APP_BASE_URL: z.string().refine(isValidBaseUrl, { message: APP_BASE_URL_MESSAGE }),
+})
+
+export type AppUrlConfig = z.infer<typeof appUrlConfigSchema>
+
+/**
+ * The browser app's routes for each token-carrying link. They match the paths
+ * the single-page app serves (`packages/ui`), so a link built here reaches a
+ * real page once that bundle is deployed at `APP_BASE_URL`.
+ */
+export const APP_LINK_PATHS = {
+  passwordReset: '/reset-password',
+  verifyEmail: '/verify-email',
+  inviteAccept: '/join',
+} as const
+
+/**
+ * Builds a link at the deployment's base URL, carrying the token as a query
+ * parameter.
+ *
+ * `new URL(path, baseUrl)` resolves the path against the base, so a base with a
+ * trailing slash and one without give the same result. The token is base64url
+ * and needs no escaping. `searchParams` encodes it regardless, rather than trust
+ * that.
+ */
+export function buildAppLink(baseUrl: string, path: string, token: string): string {
+  const url = new URL(path, baseUrl)
+
+  url.searchParams.set('token', token)
+
+  return url.toString()
+}

package/src/lib/clientIp.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolving the caller's IP when the service sits behind trusted proxies.
+ *
+ * The rate limiter keys on this, so trusting it wrongly matters both ways: read a
+ * forgeable header and an attacker rotates it to dodge the limit; ignore a real
+ * proxy and every caller collapses into one bucket behind the load balancer.
+ *
+ * The deployment states how many proxies stand in front of it
+ * (`TRUSTED_PROXY_HOP_COUNT`). Zero, the default, means the service is reached
+ * directly and the socket address is the client. A positive count means the last
+ * N entries of `X-Forwarded-For` were written by infrastructure this deployment
+ * controls, so the entry just left of them is the client as the outermost trusted
+ * proxy saw it, which no earlier hop could forge.
+ */
+
+/**
+ * @param socketAddress The address the TCP connection arrived from.
+ * @param forwardedFor The raw `X-Forwarded-For` header, or undefined.
+ * @param hopCount How many trusted proxies stand in front of the service.
+ * @returns The client's IP. Falls back to the socket address whenever the header
+ *   is absent or holds fewer entries than the configured hop count, so a
+ *   misconfiguration over-limits rather than trusts a forgeable position.
+ */
+export function resolveClientIpFrom(
+  socketAddress: string,
+  forwardedFor: string | undefined,
+  hopCount: number,
+): string {
+  if (hopCount <= 0 || forwardedFor === undefined) {
+    return socketAddress
+  }
+
+  const entries = forwardedFor
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+
+  const index = entries.length - hopCount
+
+  return index >= 0 ? (entries[index] ?? socketAddress) : socketAddress
+}

package/src/lib/config.ts

@@ -38,6 +38,12 @@ export interface KelpieConfig {
    */
   readonly webBundleDirectory: string | undefined
   readonly rateLimit: RateLimitConfig
+  /**
+   * How many trusted proxies stand in front of the service. Zero means it is
+   * reached directly and the socket address is the client. Positive means the
+   * client IP is read from `X-Forwarded-For` (`lib/clientIp.ts`).
+   */
+  readonly trustedProxyHopCount: number
 }
 
 /** Thrown at boot when the environment cannot produce a valid configuration. */
@@ -69,31 +75,43 @@ const environmentSchema = z.object({
   LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
   KELPIE_MODULE_CONFIG_PATH: z.string().min(1).optional(),
   WEB_BUNDLE_DIR: z.string().min(1).optional(),
-  ...emailConfigSchema.shape,
+  TRUSTED_PROXY_HOP_COUNT: z.coerce.number().int().nonnegative().default(0),
   ...rateLimitConfigSchema.shape,
 })
 
 /**
  * Parses an environment into a validated config.
  *
+ * `emailConfigSchema` is a discriminated union, so it is parsed separately
+ * from the rest: a union has no flat `.shape` to spread into `environmentSchema`,
+ * only its own `EMAIL_PROVIDER`-keyed branches. Problems from both parses are
+ * combined into one error, preserving the "every missing variable at once" rule.
+ *
  * @param environment Raw variables, normally `process.env`.
  * @throws ConfigurationError listing every invalid or missing variable.
  */
 export function loadConfig(environment: Environment): KelpieConfig {
-  const result = environmentSchema.safeParse(environment)
+  const environmentResult = environmentSchema.safeParse(environment)
+  const emailResult = emailConfigSchema.safeParse(environment)
+
+  if (!environmentResult.success || !emailResult.success) {
+    const problems = [
+      ...(environmentResult.success ? [] : environmentResult.error.issues.map(describeValidationIssue)),
+      ...(emailResult.success ? [] : emailResult.error.issues.map(describeValidationIssue)),
+    ]
 
-  if (!result.success) {
-    throw new ConfigurationError(result.error.issues.map(describeValidationIssue))
+    throw new ConfigurationError(problems)
   }
 
   return {
-    runtimeMode: result.data.NODE_ENV,
-    port: result.data.PORT,
-    databaseUrl: result.data.DATABASE_URL,
-    logLevel: result.data.LOG_LEVEL,
-    email: { EMAIL_PROVIDER: result.data.EMAIL_PROVIDER, EMAIL_FROM: result.data.EMAIL_FROM },
-    moduleConfigPath: result.data.KELPIE_MODULE_CONFIG_PATH,
-    webBundleDirectory: result.data.WEB_BUNDLE_DIR,
-    rateLimit: rateLimitConfigFrom(result.data),
+    runtimeMode: environmentResult.data.NODE_ENV,
+    port: environmentResult.data.PORT,
+    databaseUrl: environmentResult.data.DATABASE_URL,
+    logLevel: environmentResult.data.LOG_LEVEL,
+    email: emailResult.data,
+    moduleConfigPath: environmentResult.data.KELPIE_MODULE_CONFIG_PATH,
+    webBundleDirectory: environmentResult.data.WEB_BUNDLE_DIR,
+    rateLimit: rateLimitConfigFrom(environmentResult.data),
+    trustedProxyHopCount: environmentResult.data.TRUSTED_PROXY_HOP_COUNT,
   }
 }

package/src/lib/egress.ts

@@ -0,0 +1,149 @@
+import { lookup } from 'node:dns/promises'
+import { isIP } from 'node:net'
+import { z } from 'zod'
+
+/**
+ * An optional guard against outbound POSTs to private or reserved addresses.
+ *
+ * Webhook and agent endpoints are customer-supplied, and a self-hosted Kelpie
+ * legitimately posts to an internal host such as `http://automation.internal`.
+ * So the guard is off by default (`lib/url.ts` says the same). A hosted
+ * deployment, where a customer must not be able to aim a delivery at the
+ * metadata service or a neighbour's database, sets `BLOCK_PRIVATE_EGRESS=true`.
+ *
+ * The check resolves the host and refuses the request when any resolved address
+ * is loopback, private, link-local, unique-local, or otherwise reserved. It runs
+ * just before the fetch. That leaves a narrow rebinding window between this
+ * lookup and the connection's own; the senders already pass `redirect: 'manual'`,
+ * which closes the redirect-based bypass, and a hosted deployment pairs this with
+ * network-level egress rules. It is defence in depth, not the only defence.
+ */
+
+export const egressConfigSchema = z.object({
+  BLOCK_PRIVATE_EGRESS: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((value) => value === 'true'),
+})
+
+export type EgressConfig = z.infer<typeof egressConfigSchema>
+
+/** Thrown when a target resolves to an address the guard refuses. */
+export class BlockedEgressError extends Error {
+  constructor(host: string, address: string) {
+    super(`Refusing to connect to ${host}: ${address} is a private or reserved address`)
+    this.name = 'BlockedEgressError'
+  }
+}
+
+/** True for an IPv4 address in a loopback, private, link-local, or reserved range. */
+function isPrivateIpv4(ip: string): boolean {
+  const parts = ip.split('.').map((part) => Number(part))
+
+  if (parts.length !== 4 || parts.some((part) => Number.isNaN(part) || part < 0 || part > 255)) {
+    return false
+  }
+
+  const [a, b] = parts as [number, number, number, number]
+
+  if (a === 0 || a === 10 || a === 127) {
+    return true
+  }
+
+  if (a === 169 && b === 254) {
+    // Link-local, which is where the cloud metadata service (169.254.169.254) lives.
+    return true
+  }
+
+  if (a === 172 && b >= 16 && b <= 31) {
+    return true
+  }
+
+  if (a === 192 && b === 168) {
+    return true
+  }
+
+  if (a === 100 && b >= 64 && b <= 127) {
+    // Carrier-grade NAT.
+    return true
+  }
+
+  // Multicast (224.0.0.0/4) and reserved (240.0.0.0/4), including broadcast.
+  return a >= 224
+}
+
+/** True for an IPv6 address in a loopback, unspecified, link-local, or unique-local range. */
+function isPrivateIpv6(ip: string): boolean {
+  const lower = ip.toLowerCase()
+
+  if (lower === '::1' || lower === '::') {
+    return true
+  }
+
+  const mapped = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/u.exec(lower)
+
+  if (mapped?.[1] !== undefined) {
+    // An IPv4 address written in IPv6 form resolves by its IPv4 rules.
+    return isPrivateIpv4(mapped[1])
+  }
+
+  const firstHextet = Number.parseInt(lower.split(':')[0] || '0', 16)
+
+  // fe80::/10 link-local.
+  if ((firstHextet & 0xffc0) === 0xfe80) {
+    return true
+  }
+
+  // fc00::/7 unique-local.
+  return (firstHextet & 0xfe00) === 0xfc00
+}
+
+function isPrivateAddress(ip: string): boolean {
+  return isIP(ip) === 6 ? isPrivateIpv6(ip) : isPrivateIpv4(ip)
+}
+
+export interface EgressGuard {
+  /**
+   * @throws BlockedEgressError when the URL's host resolves to a private or
+   *   reserved address. Resolves normally when the guard is off, or when every
+   *   resolved address is public.
+   */
+  check(url: string): Promise<void>
+}
+
+/**
+ * Builds the guard. When `BLOCK_PRIVATE_EGRESS` is false the guard is a no-op, so
+ * a self-hosted deployment keeps reaching its internal endpoints.
+ *
+ * @param resolveHost Injected so a test can classify a host without real DNS.
+ */
+export function createEgressGuard(
+  config: EgressConfig,
+  resolveHost: (host: string) => Promise<readonly string[]> = defaultResolveHost,
+): EgressGuard {
+  if (!config.BLOCK_PRIVATE_EGRESS) {
+    return { check: () => Promise.resolve() }
+  }
+
+  return {
+    async check(url) {
+      const host = new URL(url).hostname
+      // A bracketed IPv6 literal arrives with its brackets; `URL.hostname` keeps
+      // them, and `isIP` wants them gone.
+      const bareHost = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host
+      const addresses = isIP(bareHost) !== 0 ? [bareHost] : await resolveHost(bareHost)
+
+      for (const address of addresses) {
+        if (isPrivateAddress(address)) {
+          throw new BlockedEgressError(host, address)
+        }
+      }
+    },
+  }
+}
+
+async function defaultResolveHost(host: string): Promise<readonly string[]> {
+  const results = await lookup(host, { all: true })
+
+  return results.map((result) => result.address)
+}

package/src/lib/email.ts

@@ -1,5 +1,7 @@
+import nodemailer from 'nodemailer'
 import { z } from 'zod'
 
+import { describeThrown } from './errors.ts'
 import type { Logger } from './logger.ts'
 
 /**
@@ -7,9 +9,15 @@ import type { Logger } from './logger.ts'
  * and account-change notifications, nothing else. Kelpie never sends outreach
  * email.
  *
- * Roadmap decision 4: the provider is configured, never hardcoded. Core ships the
- * port and the `log` provider. Real providers ship as modules, so the open-source
- * assembly has no vendor account baked into it.
+ * Roadmap decision 4: the provider is configured, never hardcoded. Core ships
+ * the port and two providers, `log` and `smtp`. Both need no vendor account a
+ * deployment doesn't already have, which is what keeps them in core rather than
+ * a module, per `modules.md`'s split test. A provider that does need one
+ * (Resend, Postmark, Mailtrap, SendGrid) is a commercial integration under that
+ * same test and belongs in a module: it supplies its own `EmailSender` from its
+ * own config, and an assembly's entry point wires it into `services.email` in
+ * place of `createEmailSender`, the same way `kelpie-cloud/src/server.ts` wires
+ * this one today.
  */
 
 export interface EmailMessage {
@@ -22,12 +30,28 @@ export interface EmailSender {
   send(message: EmailMessage): Promise<void>
 }
 
-export const emailConfigSchema = z.object({
-  EMAIL_PROVIDER: z.enum(['log']),
+const logEmailConfigSchema = z.object({
+  EMAIL_PROVIDER: z.literal('log'),
   EMAIL_FROM: z.string().min(1),
 })
 
+const smtpEmailConfigSchema = z.object({
+  EMAIL_PROVIDER: z.literal('smtp'),
+  EMAIL_FROM: z.string().min(1),
+  SMTP_HOST: z.string().min(1),
+  SMTP_PORT: z.coerce.number().int().positive().max(65535),
+  SMTP_SECURE: z.enum(['true', 'false']).transform((value) => value === 'true'),
+  SMTP_USER: z.string().min(1),
+  SMTP_PASSWORD: z.string().min(1),
+})
+
+export const emailConfigSchema = z.discriminatedUnion('EMAIL_PROVIDER', [
+  logEmailConfigSchema,
+  smtpEmailConfigSchema,
+])
+
 export type EmailConfig = z.infer<typeof emailConfigSchema>
+export type SmtpEmailConfig = z.infer<typeof smtpEmailConfigSchema>
 
 /**
  * Writes the message to the log instead of sending it. For self-hosted
@@ -51,15 +75,59 @@ export function createLogEmailSender(logger: Logger, from: string): EmailSender
   }
 }
 
+/**
+ * What `createSmtpEmailSender` sends a message through. A real deployment gets
+ * one backed by `nodemailer`; a test injects one that records calls, so the
+ * sender is verifiable without a container running a real SMTP conversation.
+ */
+export interface SmtpTransport {
+  sendMail(message: { from: string; to: string; subject: string; text: string }): Promise<unknown>
+}
+
+function createNodemailerTransport(config: SmtpEmailConfig): SmtpTransport {
+  return nodemailer.createTransport({
+    host: config.SMTP_HOST,
+    port: config.SMTP_PORT,
+    secure: config.SMTP_SECURE,
+    auth: { user: config.SMTP_USER, pass: config.SMTP_PASSWORD },
+  })
+}
+
+/** Sends over SMTP. `transport` defaults to a real connection built from `config`. */
+export function createSmtpEmailSender(
+  config: SmtpEmailConfig,
+  logger: Logger,
+  transport: SmtpTransport = createNodemailerTransport(config),
+): EmailSender {
+  return {
+    async send(message) {
+      try {
+        await transport.sendMail({
+          from: config.EMAIL_FROM,
+          to: message.to,
+          subject: message.subject,
+          text: message.body,
+        })
+      } catch (cause) {
+        const reason = describeThrown(cause)
+        logger.error('smtp send failed', { to: message.to, reason })
+        throw new Error(`Failed to send email to ${message.to} over SMTP: ${reason}`, { cause })
+      }
+    },
+  }
+}
+
 /**
  * Builds the configured sender.
  *
- * @throws Never. An unknown provider cannot reach here: the config schema is an
- *   enum, so boot rejects it first.
+ * @throws Never. An unknown provider cannot reach here: the config schema is a
+ *   discriminated union, so boot rejects it first.
  */
 export function createEmailSender(config: EmailConfig, logger: Logger): EmailSender {
   switch (config.EMAIL_PROVIDER) {
     case 'log':
       return createLogEmailSender(logger, config.EMAIL_FROM)
+    case 'smtp':
+      return createSmtpEmailSender(config, logger)
   }
 }

package/src/lib/ids.ts

@@ -9,6 +9,8 @@ export const idPrefixes = {
   user: 'usr',
   session: 'ses',
   passwordResetToken: 'pwr',
+  /** Never returned over the wire either, for the same reason as `passwordResetToken`. */
+  emailVerificationToken: 'evt',
   teamMember: 'mem',
   invite: 'inv',
   apiKey: 'key',

package/src/lib/rateLimit.ts

@@ -1,10 +1,10 @@
 import { z } from 'zod'
 
 /**
- * Budgets for the three request classes `api.md` rate-limits: public form
- * submissions, unauthenticated auth endpoints, and everything else under an
- * API key. Roadmap Phase 6: self-host packaging calls for this with nothing to
- * configure, so every variable here is optional and defaulted.
+ * Budgets for the request classes `api.md` rate-limits: public form submissions,
+ * unauthenticated auth endpoints by IP, login by account, and everything else
+ * under an API key. Roadmap Phase 6: self-host packaging calls for this with
+ * nothing to configure, so every variable here is optional and defaulted.
  */
 
 export interface RateLimitBudget {
@@ -15,6 +15,12 @@ export interface RateLimitBudget {
 export interface RateLimitConfig {
   readonly forms: RateLimitBudget
   readonly auth: RateLimitBudget
+  /**
+   * Login attempts for one email address, whatever IP they come from. The `auth`
+   * budget alone caps one IP, so a botnet spread across many addresses could
+   * still grind one account. This is the per-account half of that defence.
+   */
+  readonly loginAccount: RateLimitBudget
   readonly api: RateLimitBudget
 }
 
@@ -23,6 +29,8 @@ export const rateLimitConfigSchema = z.object({
   RATE_LIMIT_FORMS_WINDOW_SECONDS: z.coerce.number().int().positive().default(60),
   RATE_LIMIT_AUTH_LIMIT: z.coerce.number().int().positive().default(10),
   RATE_LIMIT_AUTH_WINDOW_SECONDS: z.coerce.number().int().positive().default(60),
+  RATE_LIMIT_LOGIN_ACCOUNT_LIMIT: z.coerce.number().int().positive().default(10),
+  RATE_LIMIT_LOGIN_ACCOUNT_WINDOW_SECONDS: z.coerce.number().int().positive().default(900),
   RATE_LIMIT_API_LIMIT: z.coerce.number().int().positive().default(600),
   RATE_LIMIT_API_WINDOW_SECONDS: z.coerce.number().int().positive().default(60),
 })
@@ -37,6 +45,10 @@ export function rateLimitConfigFrom(parsed: z.infer<typeof rateLimitConfigSchema
       limit: parsed.RATE_LIMIT_AUTH_LIMIT,
       windowMs: parsed.RATE_LIMIT_AUTH_WINDOW_SECONDS * 1000,
     },
+    loginAccount: {
+      limit: parsed.RATE_LIMIT_LOGIN_ACCOUNT_LIMIT,
+      windowMs: parsed.RATE_LIMIT_LOGIN_ACCOUNT_WINDOW_SECONDS * 1000,
+    },
     api: {
       limit: parsed.RATE_LIMIT_API_LIMIT,
       windowMs: parsed.RATE_LIMIT_API_WINDOW_SECONDS * 1000,

package/src/modules/agent-tasks/dispatch.ts

@@ -1,4 +1,5 @@
 import type { Database } from '../../lib/database.ts'
+import type { EgressGuard } from '../../lib/egress.ts'
 import { describeThrown } from '../../lib/errors.ts'
 import type { Logger } from '../../lib/logger.ts'
 import { SecretDecryptionError } from '../../lib/secrets.ts'
@@ -49,11 +50,17 @@ export type SendDispatch = (request: DispatchRequest) => Promise<DispatchOutcome
  * The catch is broad because this is the process boundary: `fetch` rejects
  * with anything from a DNS failure to an abort, and turning all of it into one
  * outcome is the port's whole job. Nothing is swallowed — the reason lands on
- * the run.
+ * the run. A blocked private address (`egress.check`) reaches the same catch
+ * and lands on the run the same way.
  */
-export function createHttpSender(fetchImplementation: typeof fetch = fetch): SendDispatch {
+export function createHttpSender(
+  egress: EgressGuard,
+  fetchImplementation: typeof fetch = fetch,
+): SendDispatch {
   return async (request) => {
     try {
+      await egress.check(request.url)
+
       const response = await fetchImplementation(request.url, {
         method: 'POST',
         body: request.body,

package/src/modules/agent-tasks/index.ts

@@ -1,3 +1,4 @@
+import { createEgressGuard, egressConfigSchema } from '../../lib/egress.ts'
 import { createSecretCipher, secretEncryptionConfigSchema } from '../../lib/secrets.ts'
 import type { KelpieModule } from '../../runtime/module.ts'
 import { createDispatchEngine, createHttpSender } from './dispatch.ts'
@@ -48,12 +49,13 @@ export function createAgentTasksModule(
       // key means no stored auth header can ever be read back, and finding that
       // out when a dispatch quietly fails is far too late.
       const cipher = createSecretCipher(context.config(secretEncryptionConfigSchema))
+      const egress = createEgressGuard(context.config(egressConfigSchema))
 
       const engine = createDispatchEngine({
         db: context.db,
         now: context.now,
         cipher,
-        send: options.send ?? createHttpSender(),
+        send: options.send ?? createHttpSender(egress),
         log: context.log,
       })