@kelpie/server 0.1.0 → 0.3.0

package/migrations/meta/_journal.json

@@ -113,6 +113,13 @@
       "when": 1786278323968,
       "tag": "0015_peaceful_chimera",
       "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1786410884983,
+      "tag": "0016_misty_mentor",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kelpie/server",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The Kelpie service as a library: module runtime, core CRM modules, REST API, MCP surface, and the shared migration pipeline.",
   "keywords": [
     "kelpie",
@@ -51,7 +51,8 @@
     "db:generate": "node --env-file-if-exists=../../.env --env-file-if-exists=../../.env.local ../../node_modules/drizzle-kit/bin.cjs generate"
   },
   "dependencies": {
-    "@kelpie/schemas": "^0.1.0",
+    "@hono/node-server": "^2.0.12",
+    "@kelpie/schemas": "^0.3.0",
     "@node-rs/argon2": "^2.0.2",
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.32",

package/src/app.ts

@@ -1,4 +1,5 @@
 import { Hono } from 'hono'
+import type { Context } from 'hono'
 import { cors } from 'hono/cors'
 
 import type { DatabaseProbe } from './lib/database.ts'
@@ -7,9 +8,15 @@ import { PUBLIC_ROUTE_PREFIX } from './lib/http.ts'
 import { createIdFactory } from './lib/ids.ts'
 import type { IdFactory } from './lib/ids.ts'
 import type { Logger } from './lib/logger.ts'
+import type { RateLimitConfig } from './lib/rateLimit.ts'
+import { securityHeadersMiddleware } from './lib/securityHeaders.ts'
 import type { CredentialDependencies } from './modules/auth/credentials.ts'
 import { MCP_INSTRUCTIONS, MCP_ROUTE_PREFIX, MCP_SERVER_INFO } from './modules/mcp/index.ts'
 import { createMcpEndpoint } from './modules/mcp/router.ts'
+import {
+  createAuthAndApiRateLimitMiddleware,
+  createFormSubmitRateLimitMiddleware,
+} from './modules/rate-limit/middleware.ts'
 import { createIdempotencyMiddleware } from './modules/workspace/idempotencyMiddleware.ts'
 import type { ModuleContributions } from './runtime/registry.ts'
 
@@ -34,6 +41,15 @@ export interface AppDependencies {
   readonly generateRequestId?: () => string
   /** Injected so tests can pin the ids `idempotencyMiddleware` reserves rows under. */
   readonly createId?: IdFactory
+  readonly rateLimit: RateLimitConfig
+  /**
+   * Required rather than defaulted: a wrong-but-plausible fallback (trusting a
+   * spoofable header, say) would degrade the rate limiter silently instead of
+   * failing to build. The real entry points resolve this from the actual
+   * socket (`apps/kelpie/src/server.ts`); tests resolve it from a header they
+   * control (`testing/app.ts`).
+   */
+  readonly resolveClientIp: (context: Context) => string
 }
 
 /** Per-request values the middleware chain sets and handlers read. */
@@ -87,6 +103,23 @@ export function createApp(dependencies: AppDependencies): Hono<AppBindings> {
     })
   })
 
+  app.use('*', securityHeadersMiddleware)
+
+  const rateLimitDependencies = {
+    db: dependencies.credentials.db,
+    now: dependencies.credentials.now,
+    createId,
+    credentials: dependencies.credentials,
+    resolveClientIp: dependencies.resolveClientIp,
+    config: dependencies.rateLimit,
+  }
+
+  // Ahead of idempotency, so a rate-limited request never reserves an
+  // idempotency key it will not be allowed to spend. Skips `/v1/public/*`
+  // itself; `createFormSubmitRateLimitMiddleware` below covers it, mounted
+  // where the public CORS middleware requires.
+  app.use('/v1/*', createAuthAndApiRateLimitMiddleware(rateLimitDependencies))
+
   // Every module's `POST` gets this the same way, decided once here rather than
   // per route (`api.md`). It skips `/v1/public/*` itself — a public request has
   // no `Actor` to scope a key to — so it is mounted ahead of the public CORS
@@ -107,6 +140,11 @@ export function createApp(dependencies: AppDependencies): Hono<AppBindings> {
   // middleware is attached before anything can answer under the prefix.
   app.use(`${PUBLIC_ROUTE_PREFIX}/*`, PUBLIC_CORS)
 
+  // After CORS, not before: a throw ahead of it would strip the CORS headers a
+  // cross-origin embed needs to read the 429 body, and would apply to the
+  // preflight `OPTIONS` request CORS itself answers without reaching here.
+  app.use(`${PUBLIC_ROUTE_PREFIX}/*`, createFormSubmitRateLimitMiddleware(rateLimitDependencies))
+
   for (const { router } of dependencies.contributions.publicRouters) {
     app.route(PUBLIC_ROUTE_PREFIX, router)
   }
@@ -123,6 +161,14 @@ export function createApp(dependencies: AppDependencies): Hono<AppBindings> {
     logger: dependencies.logger,
   })
 
+  // The transport takes bearer keys only (`api.md`), so every call that
+  // reaches it is already the `api_key` traffic the `api` budget above
+  // exists for. Shared with `/v1` rather than a separate budget: one key's
+  // usage is one thing to protect the workspace from, whichever surface it
+  // comes through. No CORS layer to mind the order of here, unlike the forms
+  // budget — the transport checks its own `Origin` inside the handler.
+  app.use(MCP_ROUTE_PREFIX, createAuthAndApiRateLimitMiddleware(rateLimitDependencies))
+
   app.route(MCP_ROUTE_PREFIX, mcp.transport)
   app.route('/v1', mcp.catalog)
 

package/src/index.ts

@@ -1,5 +1,8 @@
 export { createApp } from './app.ts'
-export type { AppDependencies } from './app.ts'
+export type { AppDependencies, AppBindings } from './app.ts'
+
+export { WebBundleError, serveWebBundle } from './webBundle.ts'
+export type { WebBundleOptions } from './webBundle.ts'
 
 export { ConfigurationError, loadConfig } from './lib/config.ts'
 export type { Environment, KelpieConfig, LogLevel, RuntimeMode } from './lib/config.ts'

package/src/lib/config.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import { emailConfigSchema } from './email.ts'
 import type { EmailConfig } from './email.ts'
 import { describeValidationIssue } from './errors.ts'
+import { rateLimitConfigFrom, rateLimitConfigSchema } from './rateLimit.ts'
+import type { RateLimitConfig } from './rateLimit.ts'
 
 /**
  * The single place the service reads environment variables. Every other module
@@ -29,6 +31,13 @@ export interface KelpieConfig {
    * settings decide.
    */
   readonly moduleConfigPath: string | undefined
+  /**
+   * Directory holding the built web bundle, served from the same origin as the
+   * API (`webBundle.ts`). Undefined is the development case: the Vite dev server
+   * builds the pages and proxies the API, so there is no bundle on disk to serve.
+   */
+  readonly webBundleDirectory: string | undefined
+  readonly rateLimit: RateLimitConfig
 }
 
 /** Thrown at boot when the environment cannot produce a valid configuration. */
@@ -59,7 +68,9 @@ const environmentSchema = z.object({
     .refine(isPostgresUrl, { message: 'must be a postgres:// or postgresql:// connection string' }),
   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,
+  ...rateLimitConfigSchema.shape,
 })
 
 /**
@@ -82,5 +93,7 @@ export function loadConfig(environment: Environment): KelpieConfig {
     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),
   }
 }

package/src/lib/errors.ts

@@ -77,6 +77,10 @@ export class AppError extends Error {
   static conflict(message: string, details?: readonly ErrorDetail[]): AppError {
     return new AppError('conflict', message, details)
   }
+
+  static rateLimited(message = 'Too many requests'): AppError {
+    return new AppError('rate_limited', message)
+  }
 }
 
 /**

package/src/lib/ids.ts

@@ -46,6 +46,11 @@ export const idPrefixes = {
    * database is generated the same, injectable way.
    */
   idempotencyKey: 'idem',
+  /**
+   * Not returned over the wire either, for the same reason as `idempotencyKey`:
+   * a bucket is bookkeeping the rate limiter owns, not a resource with routes.
+   */
+  rateLimitBucket: 'rl',
 } as const
 
 export type ObjectKind = keyof typeof idPrefixes

package/src/lib/rateLimit.ts

@@ -0,0 +1,45 @@
+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.
+ */
+
+export interface RateLimitBudget {
+  readonly limit: number
+  readonly windowMs: number
+}
+
+export interface RateLimitConfig {
+  readonly forms: RateLimitBudget
+  readonly auth: RateLimitBudget
+  readonly api: RateLimitBudget
+}
+
+export const rateLimitConfigSchema = z.object({
+  RATE_LIMIT_FORMS_LIMIT: z.coerce.number().int().positive().default(20),
+  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_API_LIMIT: z.coerce.number().int().positive().default(600),
+  RATE_LIMIT_API_WINDOW_SECONDS: z.coerce.number().int().positive().default(60),
+})
+
+export function rateLimitConfigFrom(parsed: z.infer<typeof rateLimitConfigSchema>): RateLimitConfig {
+  return {
+    forms: {
+      limit: parsed.RATE_LIMIT_FORMS_LIMIT,
+      windowMs: parsed.RATE_LIMIT_FORMS_WINDOW_SECONDS * 1000,
+    },
+    auth: {
+      limit: parsed.RATE_LIMIT_AUTH_LIMIT,
+      windowMs: parsed.RATE_LIMIT_AUTH_WINDOW_SECONDS * 1000,
+    },
+    api: {
+      limit: parsed.RATE_LIMIT_API_LIMIT,
+      windowMs: parsed.RATE_LIMIT_API_WINDOW_SECONDS * 1000,
+    },
+  }
+}

package/src/lib/securityHeaders.ts

@@ -0,0 +1,44 @@
+import { secureHeaders } from 'hono/secure-headers'
+import type { MiddlewareHandler } from 'hono'
+
+/**
+ * `api.md`'s security headers, in two layers.
+ *
+ * `hono/secure-headers` (bundled with `hono` already; no new dependency)
+ * covers `Strict-Transport-Security`, `X-Content-Type-Options` and
+ * `Referrer-Policy`. Every other header it can add is turned off explicitly
+ * rather than left at the library's default, so a future `hono` upgrade
+ * cannot silently change what this API sends. `Cross-Origin-Resource-Policy`
+ * in particular would break the very cross-origin iframe embedding
+ * `forms/embed.ts` exists for, on any customer page that opts into
+ * `Cross-Origin-Embedder-Policy` itself.
+ *
+ * `X-Frame-Options` cannot go through the library the same way: a mount's
+ * value is fixed once, not computed per request, and the embed page is the
+ * one response in this service that must not send it (`embed.ts:229`). The
+ * wrapper below adds it everywhere else, driven by the one signal that tells
+ * the embed page apart from every other route: it is the only handler that
+ * sets its own `Content-Security-Policy`.
+ */
+const baseHeaders = secureHeaders({
+  strictTransportSecurity: true,
+  xContentTypeOptions: true,
+  referrerPolicy: true,
+  crossOriginEmbedderPolicy: false,
+  crossOriginResourcePolicy: false,
+  crossOriginOpenerPolicy: false,
+  originAgentCluster: false,
+  xDnsPrefetchControl: false,
+  xDownloadOptions: false,
+  xFrameOptions: false,
+  xPermittedCrossDomainPolicies: false,
+  xXssProtection: false,
+})
+
+export const securityHeadersMiddleware: MiddlewareHandler = async (context, next) => {
+  await baseHeaders(context, next)
+
+  if (context.res.headers.get('Content-Security-Policy') === null) {
+    context.header('X-Frame-Options', 'DENY')
+  }
+}

package/src/modules/rate-limit/middleware.ts

@@ -0,0 +1,177 @@
+import type { Context, MiddlewareHandler } from 'hono'
+
+import type { Database } from '../../lib/database.ts'
+import { AppError } from '../../lib/errors.ts'
+import { PUBLIC_ROUTE_PREFIX } from '../../lib/http.ts'
+import type { IdFactory } from '../../lib/ids.ts'
+import type { RateLimitBudget, RateLimitConfig } from '../../lib/rateLimit.ts'
+import { readBearerToken } from '../api-keys/keys.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import { incrementRateLimitBucket, pruneExpiredRateLimitBuckets } from './repository.ts'
+
+/**
+ * The three budgets `api.md` describes for `/v1`: public form submissions,
+ * unauthenticated auth endpoints, and everything else called with an API key.
+ * Split into two middlewares rather than one, because the forms budget has to
+ * sit *inside* `PUBLIC_CORS` in `app.ts` — a throw ahead of it would strip the
+ * CORS headers a cross-origin embed needs to read the 429 body — while the
+ * auth and API budgets have no CORS concern and can run earlier.
+ */
+
+export interface RateLimitMiddlewareDependencies {
+  readonly db: Database
+  readonly now: () => Date
+  readonly createId: IdFactory
+  readonly credentials: CredentialDependencies
+  readonly resolveClientIp: (context: Context) => string
+  readonly config: RateLimitConfig
+}
+
+/**
+ * Every unauthenticated `/v1/auth/*` endpoint: the ones a stranger can call to
+ * attempt credential stuffing or enumerate accounts. `/auth/logout`, `/me`,
+ * `/sessions` and changing a known password all require a session already and
+ * carry no such risk, so they are not here.
+ */
+const UNAUTHENTICATED_AUTH_PATHS: ReadonlySet<string> = new Set([
+  '/v1/auth/signup',
+  '/v1/auth/login',
+  '/v1/auth/password-reset',
+  '/v1/auth/password-reset/confirm',
+])
+
+function isFormSubmitRoute(context: Context): boolean {
+  return context.req.method === 'POST' && context.req.path.endsWith('/submit')
+}
+
+/** Floors `now` to the start of its fixed window, so every caller in the same window shares one row. */
+function windowStart(now: Date, windowMs: number): Date {
+  return new Date(Math.floor(now.getTime() / windowMs) * windowMs)
+}
+
+/**
+ * The largest configured window across all three budgets. A bucket cannot be
+ * expired before its own window elapses, so this is a safe cutoff for
+ * pruning regardless of which budget created the row.
+ */
+function maxWindowMs(config: RateLimitConfig): number {
+  return Math.max(config.forms.windowMs, config.auth.windowMs, config.api.windowMs)
+}
+
+/**
+ * Increments the bucket and throws `429` with `Retry-After` once the caller is
+ * over budget. Pruning runs only when this request started a fresh window
+ * (`count === 1`) rather than on every call, which ties cleanup frequency to
+ * how often new windows open instead of to raw request volume.
+ */
+async function enforceBudget(
+  dependencies: RateLimitMiddlewareDependencies,
+  context: Context,
+  params: { readonly scope: string; readonly key: string; readonly budget: RateLimitBudget },
+): Promise<void> {
+  const now = dependencies.now()
+  const start = windowStart(now, params.budget.windowMs)
+
+  const count = await incrementRateLimitBucket(dependencies.db, {
+    id: dependencies.createId('rateLimitBucket'),
+    scope: params.scope,
+    key: params.key,
+    windowStart: start,
+  })
+
+  if (count === 1) {
+    await pruneExpiredRateLimitBuckets(dependencies.db, new Date(now.getTime() - maxWindowMs(dependencies.config)))
+  }
+
+  if (count > params.budget.limit) {
+    const resetAt = start.getTime() + params.budget.windowMs
+    const retryAfterSeconds = Math.max(1, Math.ceil((resetAt - now.getTime()) / 1000))
+
+    context.header('Retry-After', String(retryAfterSeconds))
+    throw AppError.rateLimited()
+  }
+}
+
+/**
+ * Guards `POST /v1/public/forms/:key/submit`, keyed by the caller's IP.
+ *
+ * Mount this **after** `PUBLIC_CORS` in `app.ts`. It only recognises the
+ * submit route; every other path under the public prefix, including the embed
+ * page itself, passes through untouched.
+ */
+export function createFormSubmitRateLimitMiddleware(
+  dependencies: RateLimitMiddlewareDependencies,
+): MiddlewareHandler {
+  return async (context, next) => {
+    if (!isFormSubmitRoute(context)) {
+      await next()
+      return
+    }
+
+    await enforceBudget(dependencies, context, {
+      scope: 'forms',
+      key: dependencies.resolveClientIp(context),
+      budget: dependencies.config.forms,
+    })
+    await next()
+  }
+}
+
+/**
+ * Guards the unauthenticated auth endpoints (by IP) and every other `/v1/*`
+ * request made with an API key (by that key) — the budget that protects a
+ * workspace rather than the world. Session traffic, the product's own UI,
+ * carries no budget here.
+ *
+ * Public routes are skipped: `createFormSubmitRateLimitMiddleware` already
+ * covers them, positioned where `PUBLIC_CORS` requires. Mount this one
+ * anywhere else on `/v1/*`, ahead of idempotency so a rate-limited request
+ * never reserves an idempotency key it will not be allowed to spend.
+ */
+export function createAuthAndApiRateLimitMiddleware(
+  dependencies: RateLimitMiddlewareDependencies,
+): MiddlewareHandler {
+  return async (context, next) => {
+    const path = context.req.path
+
+    if (path === PUBLIC_ROUTE_PREFIX || path.startsWith(`${PUBLIC_ROUTE_PREFIX}/`)) {
+      await next()
+      return
+    }
+
+    if (context.req.method === 'POST' && UNAUTHENTICATED_AUTH_PATHS.has(path)) {
+      await enforceBudget(dependencies, context, {
+        scope: 'auth',
+        key: dependencies.resolveClientIp(context),
+        budget: dependencies.config.auth,
+      })
+      await next()
+      return
+    }
+
+    // Only a bearer credential can resolve to an `api_key` actor, the only
+    // kind this budget applies to, so a cookie-only request — the ordinary
+    // browser session — never pays for an actor resolution here at all.
+    const bearer = readBearerToken(context.req.header('Authorization'))
+
+    if (bearer === undefined || bearer.length === 0) {
+      await next()
+      return
+    }
+
+    const actor = await resolveActorFrom(dependencies.credentials, context)
+
+    if (actor.kind !== 'api_key') {
+      await next()
+      return
+    }
+
+    await enforceBudget(dependencies, context, {
+      scope: 'api',
+      key: actor.apiKeyId,
+      budget: dependencies.config.api,
+    })
+    await next()
+  }
+}

package/src/modules/rate-limit/repository.ts

@@ -0,0 +1,64 @@
+import { lt, sql } from 'drizzle-orm'
+
+import type { Database } from '../../lib/database.ts'
+import type { Transaction } from '../../runtime/transaction.ts'
+import { rateLimitBuckets } from './schema.ts'
+
+/** Queries for `rate_limit_buckets`. The middleware decides; these read and write. */
+
+export type Queryable = Database | Transaction
+
+export type RateLimitBucketRecord = typeof rateLimitBuckets.$inferSelect
+
+/**
+ * Increments the counter for `(scope, key, windowStart)`, creating the row on
+ * the first request of a window.
+ *
+ * One atomic upsert. Postgres's own row lock under `ON CONFLICT` is what makes
+ * concurrent requests from the same caller count correctly with no read
+ * followed by a separate write to race against — the same shape
+ * `reserveIdempotencyKey` uses, and for the same reason: two statements can't
+ * be made atomic against each other, but one can.
+ */
+export async function incrementRateLimitBucket(
+  db: Queryable,
+  params: { readonly id: string; readonly scope: string; readonly key: string; readonly windowStart: Date },
+): Promise<number> {
+  const [row] = await db
+    .insert(rateLimitBuckets)
+    .values({
+      id: params.id,
+      scope: params.scope,
+      key: params.key,
+      windowStart: params.windowStart,
+      count: 1,
+    })
+    .onConflictDoUpdate({
+      target: [rateLimitBuckets.scope, rateLimitBuckets.key, rateLimitBuckets.windowStart],
+      set: { count: sql`${rateLimitBuckets.count} + 1` },
+    })
+    .returning({ count: rateLimitBuckets.count })
+
+  if (row === undefined) {
+    throw new Error('rate limit bucket upsert returned no row')
+  }
+
+  return row.count
+}
+
+/**
+ * Sweeps buckets from windows that have fully elapsed.
+ *
+ * Enforced here rather than by a schedule, the same call `idempotency_keys`
+ * and `webhook_deliveries` make about their own growth: there is no scheduler
+ * in the service, so the middleware prunes on every increment
+ * (`middleware.ts`) and the table stays bounded by the traffic that grows it.
+ */
+export async function pruneExpiredRateLimitBuckets(db: Queryable, before: Date): Promise<number> {
+  const deleted = await db
+    .delete(rateLimitBuckets)
+    .where(lt(rateLimitBuckets.windowStart, before))
+    .returning({ id: rateLimitBuckets.id })
+
+  return deleted.length
+}

package/src/modules/rate-limit/schema.ts

@@ -0,0 +1,34 @@
+import { index, integer, pgTable, text, unique } from 'drizzle-orm/pg-core'
+
+import { createdAt, moment, primaryId } from '../../lib/columns.ts'
+
+/**
+ * Fixed-window counters backing the rate limiter (`app.ts`). Not
+ * workspace-owned, unlike every other core table: a public form submission or
+ * an unauthenticated auth attempt has no workspace to scope to, which is
+ * exactly the traffic this table exists to police. `scope` names the budget
+ * (`forms`, `auth`, `api`) and `key` is the caller within it — an IP address
+ * or an API key id.
+ *
+ * `(scope, key, window_start)` is unique rather than `(scope, key)` alone
+ * because the window boundary lives in the key: a new window is a new row, so
+ * incrementing is one atomic upsert (`repository.ts`) with no read before the
+ * write to race against. A row is left for `pruneExpiredRateLimitBuckets` to
+ * sweep once its window has elapsed rather than deleted eagerly, since nothing
+ * reads a bucket after that.
+ */
+export const rateLimitBuckets = pgTable(
+  'rate_limit_buckets',
+  {
+    id: primaryId(),
+    scope: text('scope').notNull(),
+    key: text('key').notNull(),
+    windowStart: moment('window_start').notNull(),
+    count: integer('count').notNull().default(1),
+    createdAt: createdAt(),
+  },
+  (table) => [
+    unique('rate_limit_buckets_scope_key_window_key').on(table.scope, table.key, table.windowStart),
+    index('rate_limit_buckets_window_start_idx').on(table.windowStart),
+  ],
+)

package/src/schema/index.ts

@@ -28,3 +28,4 @@ export * from '../modules/import-export/schema.ts'
 export * from '../modules/agent-tasks/schema.ts'
 export * from '../modules/webhooks/schema.ts'
 export * from '../modules/integrations/schema.ts'
+export * from '../modules/rate-limit/schema.ts'

package/src/testing/app.ts

@@ -6,6 +6,8 @@ import type { Actor } from '../lib/actor.ts'
 import type { Environment } from '../lib/config.ts'
 import type { DatabaseProbe } from '../lib/database.ts'
 import { createLogger } from '../lib/logger.ts'
+import { rateLimitConfigFrom, rateLimitConfigSchema } from '../lib/rateLimit.ts'
+import type { RateLimitConfig } from '../lib/rateLimit.ts'
 import type { KelpieModule } from '../runtime/module.ts'
 import type { ModuleContributions } from '../runtime/registry.ts'
 import type { EntitlementRegistry } from '../runtime/entitlements.ts'
@@ -14,6 +16,19 @@ import { TEST_ENVIRONMENT } from './environment.ts'
 import { createTestServices } from './services.ts'
 import type { TestServices } from './services.ts'
 
+/** The same defaults `loadConfig` produces from an empty environment: one source of numbers for both. */
+const DEFAULT_TEST_RATE_LIMIT: RateLimitConfig = rateLimitConfigFrom(rateLimitConfigSchema.parse({}))
+
+/**
+ * A caller's IP, for tests. Real entry points resolve this from the socket
+ * (`apps/kelpie/src/server.ts`); a test using `app.request()` has no socket, so
+ * it reads `X-Forwarded-For` when a test sets one to simulate distinct
+ * callers, falling back to a fixed address for everything else.
+ */
+function testClientIp(context: Context): string {
+  return context.req.header('X-Forwarded-For') ?? '203.0.113.1'
+}
+
 /**
  * Assembles an app for tests. Unlike the real boot it defaults every dependency,
  * because a test that has to spell out an environment it does not care about
@@ -38,6 +53,10 @@ export interface TestAppOptions {
    * route behaves as it did before module toggling existed.
    */
   readonly resolveActor?: (context: Context) => Promise<Actor>
+  /** Defaults to the same numbers `loadConfig` would, from an empty environment. */
+  readonly rateLimit?: RateLimitConfig
+  /** Defaults to reading `X-Forwarded-For`, so a test can simulate distinct callers. */
+  readonly resolveClientIp?: (context: Context) => string
 }
 
 export interface TestApp {
@@ -73,6 +92,8 @@ export async function createTestApp(options: TestAppOptions = {}): Promise<TestA
     credentials: { db: services.db, now: services.now },
     generateRequestId: options.generateRequestId ?? (() => 'req-test'),
     createId: services.createId,
+    rateLimit: options.rateLimit ?? DEFAULT_TEST_RATE_LIMIT,
+    resolveClientIp: options.resolveClientIp ?? testClientIp,
   })
 
   return { app, contributions, logLines, services }