@kelpie/server 0.4.0 → 0.5.0

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

@@ -39,10 +39,25 @@ const UNAUTHENTICATED_AUTH_PATHS: ReadonlySet<string> = new Set([
   '/v1/auth/login',
   '/v1/auth/password-reset',
   '/v1/auth/password-reset/confirm',
+  '/v1/auth/verify-email/confirm',
 ])
 
-function isFormSubmitRoute(context: Context): boolean {
-  return context.req.method === 'POST' && context.req.path.endsWith('/submit')
+/** The one path in the set that also carries a per-account budget. */
+const LOGIN_PATH = '/v1/auth/login'
+
+/**
+ * The public form routes that carry the forms budget: the submit POST and the
+ * embed GET. Both do database work for an unauthenticated caller, so both are
+ * metered by IP. Every other path under the public prefix passes through.
+ */
+function isMeteredFormRoute(context: Context): boolean {
+  const path = context.req.path
+
+  if (context.req.method === 'POST' && path.endsWith('/submit')) {
+    return true
+  }
+
+  return context.req.method === 'GET' && path.endsWith('/embed')
 }
 
 /** Floors `now` to the start of its fixed window, so every caller in the same window shares one row. */
@@ -51,12 +66,45 @@ function windowStart(now: Date, windowMs: number): Date {
 }
 
 /**
- * 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.
+ * The largest configured window across every budget. 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. The `login-account` window is the longest by
+ * default, so leaving it out would prune a live account bucket early.
  */
 function maxWindowMs(config: RateLimitConfig): number {
-  return Math.max(config.forms.windowMs, config.auth.windowMs, config.api.windowMs)
+  return Math.max(
+    config.forms.windowMs,
+    config.auth.windowMs,
+    config.loginAccount.windowMs,
+    config.api.windowMs,
+  )
+}
+
+/**
+ * The email a login request names, normalised the way the auth service
+ * normalises it (`modules/auth/service.ts`), or undefined when the body carries
+ * no usable one.
+ *
+ * Reads the body through Hono's cache, so the login handler's own read of it
+ * later is unaffected. A malformed body resolves to undefined here and is left
+ * for the handler to reject.
+ */
+async function readLoginEmail(context: Context): Promise<string | undefined> {
+  const body: unknown = await context.req.json().catch(() => undefined)
+
+  if (typeof body !== 'object' || body === null) {
+    return undefined
+  }
+
+  const email = (body as Record<string, unknown>).email
+
+  if (typeof email !== 'string') {
+    return undefined
+  }
+
+  const normalised = email.trim().toLowerCase()
+
+  return normalised.length === 0 ? undefined : normalised
 }
 
 /**
@@ -94,17 +142,17 @@ async function enforceBudget(
 }
 
 /**
- * Guards `POST /v1/public/forms/:key/submit`, keyed by the caller's IP.
+ * Guards the public form routes that reach the database, keyed by the caller's
+ * IP: the submit `POST` and the embed `GET`.
  *
- * 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.
+ * Mount this **after** `PUBLIC_CORS` in `app.ts`. Every other path under the
+ * public prefix passes through untouched.
  */
 export function createFormSubmitRateLimitMiddleware(
   dependencies: RateLimitMiddlewareDependencies,
 ): MiddlewareHandler {
   return async (context, next) => {
-    if (!isFormSubmitRoute(context)) {
+    if (!isMeteredFormRoute(context)) {
       await next()
       return
     }
@@ -146,6 +194,21 @@ export function createAuthAndApiRateLimitMiddleware(
         key: dependencies.resolveClientIp(context),
         budget: dependencies.config.auth,
       })
+
+      // A second budget for login, keyed on the account rather than the IP, so a
+      // distributed attack on one address is capped whatever IPs it comes from.
+      if (path === LOGIN_PATH) {
+        const email = await readLoginEmail(context)
+
+        if (email !== undefined) {
+          await enforceBudget(dependencies, context, {
+            scope: 'login-account',
+            key: email,
+            budget: dependencies.config.loginAccount,
+          })
+        }
+      }
+
       await next()
       return
     }

package/src/modules/webhooks/delivery.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 
 import type { Database } from '../../lib/database.ts'
+import type { EgressGuard } from '../../lib/egress.ts'
 import { describeThrown } from '../../lib/errors.ts'
 import type { IdFactory } from '../../lib/ids.ts'
 import type { Logger } from '../../lib/logger.ts'
@@ -115,11 +116,18 @@ export function sleepFor(milliseconds: number): Promise<void> {
  * The catch is broad because this is the process boundary: `fetch` rejects with
  * anything from a DNS failure to an abort, the set is open, and turning all of
  * it into one outcome is the port's whole job. Nothing is swallowed — the
- * reason reaches the log and the delivery is recorded as failed.
+ * reason reaches the log and the delivery is recorded as failed. A blocked
+ * private address (`egress.check`) reaches the same catch and is recorded the
+ * same way, as a failed attempt rather than a crash.
  */
-export function createHttpSender(fetchImplementation: typeof fetch = fetch): SendDelivery {
+export function createHttpSender(
+  egress: EgressGuard,
+  fetchImplementation: typeof fetch = fetch,
+): SendDelivery {
   return async (request) => {
     try {
+      await egress.check(request.url)
+
       const response = await fetchImplementation(request.url, {
         method: 'POST',
         body: request.body,

package/src/modules/webhooks/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 {
@@ -49,6 +50,7 @@ export function createWebhooksModule(
       // should stop boot, not prune by the wrong window.
       const cipher = createSecretCipher(context.config(secretEncryptionConfigSchema))
       const retention = context.config(deliveryRetentionConfigSchema)
+      const egress = createEgressGuard(context.config(egressConfigSchema))
 
       const service = createWebhooksService({
         db: context.db,
@@ -64,7 +66,7 @@ export function createWebhooksModule(
         createId: context.createId,
         now: context.now,
         cipher,
-        send: options.send ?? createHttpSender(),
+        send: options.send ?? createHttpSender(egress),
         sleep: options.sleep ?? sleepFor,
         retentionDays: retention.WEBHOOK_DELIVERY_RETENTION_DAYS,
         log: context.log,

package/src/modules/workspace/idempotencyMiddleware.ts

@@ -128,7 +128,23 @@ export function createIdempotencyMiddleware(dependencies: IdempotencyMiddlewareD
       return
     }
 
-    const actor = await resolveActorFrom(dependencies.credentials, context)
+    const actor = await resolveActorFrom(dependencies.credentials, context).catch((error: unknown) => {
+      if (error instanceof AppError && error.code === 'unauthorized') {
+        // No credential to scope a key to. The unauthenticated auth endpoints
+        // (`POST /v1/auth/login`, `/signup`, the reset pair) are the case: they
+        // must answer without a credential, so a key on one of them cannot 401
+        // here. They handle their own auth; idempotency does not apply.
+        return undefined
+      }
+
+      throw error
+    })
+
+    if (actor === undefined) {
+      await next()
+      return
+    }
+
     const workspaceId = actorWorkspaceId(actor)
 
     // Between signup and a first workspace (`POST /v1/workspaces`, `POST

package/src/modules/workspace/index.ts

@@ -1,3 +1,4 @@
+import { appUrlConfigSchema } from '../../lib/appUrl.ts'
 import type { KelpieModule } from '../../runtime/module.ts'
 import { parseModuleCapability } from '../../runtime/moduleConfig.ts'
 import { SEATS_LIMIT } from './capabilities.ts'
@@ -20,6 +21,8 @@ export function createWorkspaceModule(migrationsDirectory: string): KelpieModule
     structural: true,
 
     register(context) {
+      const config = context.config(appUrlConfigSchema)
+
       context.entitlements.declare(SEATS_LIMIT)
 
       // Answers `module.<id>` for whatever a config override left undecided
@@ -44,6 +47,7 @@ export function createWorkspaceModule(migrationsDirectory: string): KelpieModule
         createId: context.createId,
         now: context.now,
         entitlements: context.entitlements,
+        appBaseUrl: config.APP_BASE_URL,
         toggleableModuleIds: context.moduleCatalog
           .filter((entry) => !entry.structural)
           .map((entry) => entry.id),

package/src/modules/workspace/repository.ts

@@ -132,21 +132,28 @@ export async function deleteMember(db: Queryable, id: string): Promise<void> {
  */
 export async function countMemberReferences(
   db: Queryable,
+  workspaceId: string,
   memberId: string,
 ): Promise<readonly { readonly type: string; readonly count: number }[]> {
   const sources = [
-    { type: 'deal', table: deals, column: deals.ownerId },
-    { type: 'opportunity', table: opportunities, column: opportunities.ownerId },
-    { type: 'partnership', table: partnerships, column: partnerships.ownerId },
-    { type: 'raise', table: raises, column: raises.ownerId },
-    { type: 'plan_item', table: planItems, column: planItems.ownerId },
-    { type: 'decision', table: decisions, column: decisions.ownerId },
-    { type: 'note', table: notes, column: notes.authorId },
+    { type: 'deal', table: deals, column: deals.ownerId, workspaceId: deals.workspaceId },
+    { type: 'opportunity', table: opportunities, column: opportunities.ownerId, workspaceId: opportunities.workspaceId },
+    { type: 'partnership', table: partnerships, column: partnerships.ownerId, workspaceId: partnerships.workspaceId },
+    { type: 'raise', table: raises, column: raises.ownerId, workspaceId: raises.workspaceId },
+    { type: 'plan_item', table: planItems, column: planItems.ownerId, workspaceId: planItems.workspaceId },
+    { type: 'decision', table: decisions, column: decisions.ownerId, workspaceId: decisions.workspaceId },
+    { type: 'note', table: notes, column: notes.authorId, workspaceId: notes.workspaceId },
   ] as const
 
   const counted = await Promise.all(
     sources.map(async (source) => {
-      const [row] = await db.select({ total: count() }).from(source.table).where(eq(source.column, memberId))
+      // A member id is globally unique, so the workspace term is defence in
+      // depth rather than the thing that scopes the count. It keeps the query
+      // safe on its own instead of by that invariant.
+      const [row] = await db
+        .select({ total: count() })
+        .from(source.table)
+        .where(and(eq(source.column, memberId), eq(source.workspaceId, workspaceId)))
 
       return { type: source.type, count: row?.total ?? 0 }
     }),

package/src/modules/workspace/routes.ts

@@ -34,11 +34,6 @@ export const updateBody = z
 export const inviteBody = z.object({
   email: z.string().min(1),
   role: z.enum(INVITABLE_ROLES),
-  invite_url_template: z.string().min(1).includes('{token}'),
-})
-
-export const resendBody = z.object({
-  invite_url_template: z.string().min(1).includes('{token}'),
 })
 
 export const memberRoleBody = z.object({ role: z.enum(MEMBER_ROLES) })
@@ -187,7 +182,6 @@ export function mountWorkspaceRoutes(router: Hono, dependencies: WorkspaceRoutes
       context.req.param('id'),
       body.email,
       body.role,
-      body.invite_url_template,
     )
 
     return context.json(inviteResponse(invite), 201)
@@ -203,12 +197,10 @@ export function mountWorkspaceRoutes(router: Hono, dependencies: WorkspaceRoutes
   })
 
   router.post('/workspaces/:id/invites/:inviteId/resend', async (context) => {
-    const body = await readBody(context, resendBody)
     const invite = await dependencies.service.resendInvite(
       await requireActor(context),
       context.req.param('id'),
       context.req.param('inviteId'),
-      body.invite_url_template,
     )
 
     return context.json(inviteResponse(invite))

package/src/modules/workspace/service.ts

@@ -1,3 +1,4 @@
+import { APP_LINK_PATHS, buildAppLink } from '../../lib/appUrl.ts'
 import { UNIQUE_VIOLATION, isReferenceViolation, postgresErrorCode } from '../../lib/database.ts'
 import type { Database } from '../../lib/database.ts'
 import type { EmailSender } from '../../lib/email.ts'
@@ -36,6 +37,8 @@ export interface WorkspaceDependencies {
   readonly createId: IdFactory
   readonly now: () => Date
   readonly entitlements: EntitlementRegistry
+  /** The deployment's own base URL. Every invitation link is built from it. */
+  readonly appBaseUrl: string
   readonly newToken?: () => string
   /** Every non-structural module id (`runtime/module.ts`'s `moduleCatalog`), in assembly order. */
   readonly toggleableModuleIds: readonly string[]
@@ -117,10 +120,10 @@ export interface WorkspaceService {
   /** Changes a member's role, or transfers ownership when `role` is `owner`. */
   setMemberRole(actor: Actor, workspaceId: string, memberId: string, role: MemberRole): Promise<MemberView>
   removeMember(actor: Actor, workspaceId: string, memberId: string): Promise<void>
-  invite(actor: Actor, workspaceId: string, email: string, role: InvitableRole, urlTemplate: string): Promise<InviteView>
+  invite(actor: Actor, workspaceId: string, email: string, role: InvitableRole): Promise<InviteView>
   listInvites(actor: Actor, workspaceId: string): Promise<readonly InviteView[]>
   /** Issues a fresh token and expiry for an invitation, and emails it again. */
-  resendInvite(actor: Actor, workspaceId: string, inviteId: string, urlTemplate: string): Promise<InviteView>
+  resendInvite(actor: Actor, workspaceId: string, inviteId: string): Promise<InviteView>
   revokeInvite(actor: Actor, workspaceId: string, inviteId: string): Promise<void>
   /** Joins the invited workspace as the calling account. */
   acceptInvite(actor: SessionActor, token: string): Promise<WorkspaceView>
@@ -292,6 +295,26 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
     }
   }
 
+  /**
+   * Refuses an actor whose account has not verified its email address.
+   *
+   * Creating a workspace is the one action that turns a bare account into
+   * something with real access (`schema.md`), so it is where the gate lives:
+   * every CRM endpoint already refuses an actor with no workspace, which means
+   * blocking this one call is enough to block the rest.
+   */
+  async function requireVerifiedEmail(actor: SessionActor): Promise<void> {
+    const user = await authRepository.findUserById(dependencies.db, actor.userId)
+
+    if (user === undefined) {
+      throw new Error(`Session ${actor.sessionId} outlived the user row behind it`)
+    }
+
+    if (user.emailVerifiedAt === null) {
+      throw new AppError('forbidden', 'Verify your email before creating a workspace')
+    }
+  }
+
   /**
    * The membership being acted on.
    *
@@ -309,11 +332,13 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
     return target
   }
 
-  function sendInviteEmail(to: string, token: string, urlTemplate: string): Promise<void> {
+  function sendInviteEmail(to: string, token: string): Promise<void> {
+    const link = buildAppLink(dependencies.appBaseUrl, APP_LINK_PATHS.inviteAccept, token)
+
     return dependencies.email.send({
       to,
       subject: 'You have been invited to a Kelpie workspace',
-      body: `Accept the invitation within seven days:\n\n${urlTemplate.replace('{token}', token)}`,
+      body: `Accept the invitation within seven days:\n\n${link}`,
     })
   }
 
@@ -370,6 +395,8 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
 
   return {
     async create(actor, input) {
+      await requireVerifiedEmail(actor)
+
       const now = dependencies.now()
       const workspaceId = dependencies.createId('workspace')
       const memberId = dependencies.createId('teamMember')
@@ -559,7 +586,7 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
       // `schema.md`: removing a member is restricted while they own records.
       // Reported before the delete so every referencing type can be named, which
       // is what the caller needs to know what to reassign.
-      const references = await repository.countMemberReferences(dependencies.db, target.id)
+      const references = await repository.countMemberReferences(dependencies.db, workspaceId, target.id)
 
       if (references.length > 0) {
         throw AppError.conflict(
@@ -589,7 +616,7 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
       }
     },
 
-    async invite(actor, workspaceId, email, role, urlTemplate) {
+    async invite(actor, workspaceId, email, role) {
       const inviter = await requireMembership(actor, workspaceId, 'admin')
       const address = email.trim().toLowerCase()
       const now = dependencies.now()
@@ -637,7 +664,7 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
       })
 
       // Sent after commit, so a rolled-back invite never reaches an inbox.
-      await sendInviteEmail(invite.email, token, urlTemplate)
+      await sendInviteEmail(invite.email, token)
 
       return toInviteView(invite, now)
     },
@@ -650,7 +677,7 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
       return records.map((record) => toInviteView(record, now))
     },
 
-    async resendInvite(actor, workspaceId, inviteId, urlTemplate) {
+    async resendInvite(actor, workspaceId, inviteId) {
       await requireMembership(actor, workspaceId, 'admin')
       const invite = await requireInvite(workspaceId, inviteId)
 
@@ -674,7 +701,7 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
         throw AppError.notFound('Invitation not found')
       }
 
-      await sendInviteEmail(updated.email, token, urlTemplate)
+      await sendInviteEmail(updated.email, token)
 
       return toInviteView(updated, now)
     },
@@ -702,10 +729,10 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
         actor.userId,
       )
 
-      // The invitation is left alone. A link is forwarded often enough that the
-      // address on this one may not be the caller's, and revoking somebody
-      // else's invitation because you clicked their link would be worse than
-      // the refusal.
+      // The invitation is left alone rather than deleted: the caller already
+      // belongs, so this token cannot be theirs, and deleting somebody else's
+      // invitation because a different account presented it would strand the
+      // person it was actually sent to.
       if (existing !== undefined) {
         throw AppError.conflict('You already belong to that workspace')
       }
@@ -716,6 +743,14 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
         throw new Error(`Session ${actor.sessionId} outlived the user row behind it`)
       }
 
+      // An invitation names an address, not a person. Accepting it with a
+      // different account would let a leaked or forwarded token seat anyone,
+      // and would let that account claim credit for controlling an address
+      // it never proved control of.
+      if (joiner.email !== invite.email) {
+        throw AppError.unauthorized('That invitation is invalid or has expired')
+      }
+
       // Ownership is never invited, only created or transferred. The column's
       // check constraint says the same; this is the service-side half of it.
       const role: MemberRole = invite.role === 'admin' ? 'admin' : 'member'
@@ -740,14 +775,12 @@ export function createWorkspaceService(dependencies: WorkspaceDependencies): Wor
           throw error
         }
 
-        await repository.deleteInvite(tx, invite.id)
+        // A real invite link already proves control of the invited address, so
+        // accepting one satisfies the same gate a verification link would.
+        // A no-op if the account was already verified.
+        await authRepository.markEmailVerified(tx, actor.userId, now)
 
-        // Any other invitation to the joiner's own address, which their joining
-        // has just killed: accepting one is now the refusal above, and until it
-        // expires it holds a seat and lists them beside their own membership.
-        // Accepting a token addressed to somebody else is how one survives the
-        // line before it.
-        await repository.deleteInvitesForEmail(tx, invite.workspaceId, joiner.email)
+        await repository.deleteInvite(tx, invite.id)
 
         await authRepository.setActiveWorkspace(tx, actor.sessionId, invite.workspaceId)
 

package/src/modules/workspace/tools.ts

@@ -3,7 +3,7 @@ import { z } from 'zod'
 import { requireWorkspaceId } from '../../lib/actor.ts'
 import type { McpToolRegistry } from '../../runtime/module.ts'
 import { deleteResult, idArg } from '../crudTools.ts'
-import { inviteBody, inviteResponse, memberResponse, memberRoleBody, resendBody, updateBody, workspaceResponse } from './routes.ts'
+import { inviteBody, inviteResponse, memberResponse, memberRoleBody, updateBody, workspaceResponse } from './routes.ts'
 import type { WorkspaceService } from './service.ts'
 
 /**
@@ -82,19 +82,12 @@ export function registerWorkspaceTools(mcp: McpToolRegistry, service: WorkspaceS
   mcp.tool({
     name: 'workspace_invites_create',
     description:
-      'Invite somebody by email and send them the invitation. invite_url_template is the page ' +
-      'that accepts it and must contain {token}. Admin only. ' +
-      'Mirrors POST /v1/workspaces/{id}/invites.',
+      'Invite somebody by email and send them the invitation. The link is built from the ' +
+      'deployment\'s own base URL. Admin only. Mirrors POST /v1/workspaces/{id}/invites.',
     inputSchema: inviteBody,
     invoke: async (body, actor) =>
       inviteResponse(
-        await service.invite(
-          actor,
-          requireWorkspaceId(actor),
-          body.email,
-          body.role,
-          body.invite_url_template,
-        ),
+        await service.invite(actor, requireWorkspaceId(actor), body.email, body.role),
       ),
   })
 
@@ -114,16 +107,9 @@ export function registerWorkspaceTools(mcp: McpToolRegistry, service: WorkspaceS
     description:
       'Issue a fresh token and expiry for an invitation and email it again. Admin only. ' +
       'Mirrors POST /v1/workspaces/{id}/invites/{inviteId}/resend.',
-    inputSchema: resendBody.extend({ invite_id: idArg }),
-    invoke: async (args, actor) =>
-      inviteResponse(
-        await service.resendInvite(
-          actor,
-          requireWorkspaceId(actor),
-          args.invite_id,
-          args.invite_url_template,
-        ),
-      ),
+    inputSchema: z.strictObject({ invite_id: idArg }),
+    invoke: async ({ invite_id: inviteId }, actor) =>
+      inviteResponse(await service.resendInvite(actor, requireWorkspaceId(actor), inviteId)),
   })
 
   mcp.tool({

package/src/runtime/module.ts

@@ -1,4 +1,4 @@
-import type { Hono } from 'hono'
+import type { Handler, Hono, MiddlewareHandler } from 'hono'
 import type { ZodType } from 'zod'
 
 import type { Actor } from '../lib/actor.ts'
@@ -93,6 +93,30 @@ export interface ModuleContext extends ModuleServices {
    * scope every query to that. There is no other way in.
    */
   publicRoutes(mount: (router: Hono) => void): void
+  /**
+   * Declares one route at its real, full path on the app itself, outside
+   * `/v1`. Core applies the declaration; no router exists between the module
+   * and the app.
+   *
+   * Nothing is put in front of it: no actor resolution, no workspace, no
+   * `module.<id>` capability gate, and workspace settings cannot toggle it.
+   * A surface declared this way owns its access rules, normally by pairing
+   * these with `appMiddleware`. Paths at or under `/v1`, `/mcp`, or
+   * `/healthz` are refused at boot: those are core's surfaces, and `routes`
+   * is the only way under `/v1`.
+   */
+  appRoute(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, handler: Handler): void
+  /**
+   * Declares middleware for a path pattern (`/operator/api/*`), the other
+   * half of `appRoute`.
+   *
+   * The app applies every declared middleware before any declared route, in
+   * module registration order, so a pattern covers matching routes from
+   * every module, later-registered ones included. That is what lets one
+   * module guard a surface other modules add routes to. Reserved paths are
+   * refused as for `appRoute`.
+   */
+  appMiddleware(pattern: string, handler: MiddlewareHandler): void
   schema(tables: Readonly<Record<string, unknown>>, migrationsDir: string): void
   readonly mcp: McpToolRegistry
   /**

package/src/runtime/registry.ts

@@ -1,5 +1,5 @@
 import { Hono } from 'hono'
-import type { Context } from 'hono'
+import type { Context, Handler, MiddlewareHandler } from 'hono'
 
 import type { Actor } from '../lib/actor.ts'
 import { requireWorkspaceId } from '../lib/actor.ts'
@@ -30,6 +30,10 @@ export interface ModuleContributions {
   readonly routers: readonly ModuleRouter[]
   /** Routers for `/v1/public`: no credentials, CORS open. `architecture.md` boot step 5. */
   readonly publicRouters: readonly ModuleRouter[]
+  /** Middleware declared on the app itself. Applied before every `appRoutes` entry. */
+  readonly appMiddleware: readonly AppMiddlewareContribution[]
+  /** Routes declared at full paths on the app itself, outside `/v1`. */
+  readonly appRoutes: readonly AppRouteContribution[]
   readonly schemas: readonly SchemaContribution[]
   readonly mcpTools: readonly McpTool[]
   /** The bus every module subscribed to. Services publish through it after commit. */
@@ -43,6 +47,41 @@ export interface ModuleRouter {
   readonly router: Hono
 }
 
+export interface AppRouteContribution {
+  readonly moduleId: string
+  readonly method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  readonly path: string
+  readonly handler: Handler
+}
+
+export interface AppMiddlewareContribution {
+  readonly moduleId: string
+  readonly pattern: string
+  readonly handler: MiddlewareHandler
+}
+
+/**
+ * Paths `appRoute`/`appMiddleware` may not touch. `/v1` because `routes` with
+ * its gates is the only way there, the rest because they are core's own
+ * surfaces. `/mcp` mirrors `MCP_ROUTE_PREFIX`, written out because `runtime/`
+ * must not import a feature module.
+ */
+const RESERVED_APP_PATHS: readonly string[] = ['/v1', '/mcp', '/healthz']
+
+function assertMountablePath(moduleId: string, kind: string, path: string): void {
+  if (!path.startsWith('/')) {
+    throw new ModuleBootError([`module "${moduleId}" declares ${kind} "${path}", which must start with "/"`])
+  }
+
+  for (const reserved of RESERVED_APP_PATHS) {
+    if (path === reserved || path.startsWith(`${reserved}/`)) {
+      throw new ModuleBootError([
+        `module "${moduleId}" declares ${kind} "${path}" under "${reserved}", which is core's surface`,
+      ])
+    }
+  }
+}
+
 /**
  * What `registerModules` needs.
  *
@@ -87,6 +126,8 @@ export interface ModuleRuntimeOptions {
 interface Accumulator {
   readonly routers: ModuleRouter[]
   readonly publicRouters: ModuleRouter[]
+  readonly appMiddleware: AppMiddlewareContribution[]
+  readonly appRoutes: AppRouteContribution[]
   readonly schemas: SchemaContribution[]
   readonly mcpTools: McpTool[]
 }
@@ -130,6 +171,19 @@ function createModuleContext(
       accumulator.publicRouters.push({ moduleId: module.id, router })
     },
 
+    // No gate on either, unlike `routes`: a surface declared here owns its
+    // own access rules, and a per-module `module.<id>` check would hand
+    // workspaces a switch over deployment tooling they do not own.
+    appRoute(method, path, handler) {
+      assertMountablePath(module.id, 'app route', path)
+      accumulator.appRoutes.push({ moduleId: module.id, method, path, handler })
+    },
+
+    appMiddleware(pattern, handler) {
+      assertMountablePath(module.id, 'app middleware', pattern)
+      accumulator.appMiddleware.push({ moduleId: module.id, pattern, handler })
+    },
+
     schema(tables, migrationsDir) {
       accumulator.schemas.push({ moduleId: module.id, tables, migrationsDir })
     },
@@ -211,6 +265,8 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
   const accumulator: Accumulator = {
     routers: [],
     publicRouters: [],
+    appMiddleware: [],
+    appRoutes: [],
     schemas: [],
     mcpTools: [],
   }
@@ -265,6 +321,8 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
   return {
     routers: accumulator.routers,
     publicRouters: accumulator.publicRouters,
+    appMiddleware: accumulator.appMiddleware,
+    appRoutes: accumulator.appRoutes,
     schemas: accumulator.schemas,
     mcpTools: accumulator.mcpTools,
     events,