@kelpie/server 0.4.1 → 0.5.1

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,6 +1,7 @@
+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'
+import { SEATS_LIMIT, WORKSPACE_ACCESS } from './capabilities.ts'
 import * as repository from './repository.ts'
 import { mountWorkspaceRoutes } from './routes.ts'
 import * as schema from './schema.ts'
@@ -20,7 +21,10 @@ export function createWorkspaceModule(migrationsDirectory: string): KelpieModule
     structural: true,
 
     register(context) {
+      const config = context.config(appUrlConfigSchema)
+
       context.entitlements.declare(SEATS_LIMIT)
+      context.entitlements.declare(WORKSPACE_ACCESS)
 
       // Answers `module.<id>` for whatever a config override left undecided
       // (`runtime/registry.ts` registers that provider first, ahead of this
@@ -44,6 +48,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/modules/workspace/workspaceAccessMiddleware.ts

@@ -0,0 +1,76 @@
+import type { Context, MiddlewareHandler } from 'hono'
+
+import { AppError } from '../../lib/errors.ts'
+import type { EntitlementRegistry } from '../../runtime/entitlements.ts'
+import { actorWorkspaceId } from '../auth/actor.ts'
+import { resolveActorFrom } from '../auth/credentials.ts'
+import type { CredentialDependencies } from '../auth/credentials.ts'
+import { WORKSPACE_ACCESS } from './capabilities.ts'
+
+/**
+ * `POST /v1/*` and every `/mcp` call carry a fixed workspace for the whole
+ * request (`api.md`): a session or key resolves to one `Actor.workspaceId`,
+ * and every query it makes is scoped to that workspace server-side. This
+ * blocks the request outright when that workspace's `workspace.access`
+ * entitlement is not granted — inert in a self-hosted assembly, since
+ * nothing registers a `GrantProvider` that answers it there
+ * (`capabilities.ts`).
+ *
+ * Mounted the same way as `createIdempotencyMiddleware`: tolerates the
+ * no-credential case, since an unauthenticated `/v1/auth/*` call has
+ * nothing to check, and ahead of idempotency in `app.ts` so a blocked
+ * request never reserves a key it will not be allowed to spend.
+ *
+ * Exempts `/v1/auth/*` and `/v1/account*`: they manage the *account*, not
+ * the workspace, and a member of a workspace this gate has locked out
+ * still needs to sign in, sign out, and see their own account to have any
+ * chance of understanding why. There is no `/v1` endpoint to switch a
+ * session to a different workspace membership — a session is bound to one
+ * at login — so there is nothing further to exempt for that case.
+ */
+function isExempt(path: string): boolean {
+  return path.startsWith('/v1/auth/') || path.startsWith('/v1/account')
+}
+
+export interface WorkspaceAccessMiddlewareDependencies extends CredentialDependencies {
+  readonly entitlements: EntitlementRegistry
+}
+
+export function createWorkspaceAccessMiddleware(
+  dependencies: WorkspaceAccessMiddlewareDependencies,
+): MiddlewareHandler {
+  return async (context: Context, next) => {
+    if (isExempt(context.req.path)) {
+      await next()
+      return
+    }
+
+    const actor = await resolveActorFrom(dependencies, context).catch((error: unknown) => {
+      if (error instanceof AppError && error.code === 'unauthorized') {
+        // No credential to check a workspace against. The handler this
+        // reaches answers its own 401; there is nothing this gate can add.
+        return undefined
+      }
+
+      throw error
+    })
+
+    const workspaceId = actor === undefined ? null : actorWorkspaceId(actor)
+
+    // Between signup and a first workspace there is nothing to gate
+    // (`POST /v1/workspaces`, `POST /v1/invites/accept`): the same case
+    // `createIdempotencyMiddleware` lets through unscoped.
+    if (workspaceId === null) {
+      await next()
+      return
+    }
+
+    const entitlement = await dependencies.entitlements.check(workspaceId, WORKSPACE_ACCESS.name)
+
+    if (entitlement.kind === 'flag' && !entitlement.granted) {
+      throw new AppError('entitlement_required', 'This workspace does not have access')
+    }
+
+    await next()
+  }
+}

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,

package/src/testing/client.ts

@@ -1,6 +1,9 @@
+import { eq } from 'drizzle-orm'
 import type { Hono } from 'hono'
 
 import type { AppBindings } from '../app.ts'
+import type { Database } from '../lib/database.ts'
+import { users } from '../modules/auth/schema.ts'
 
 /**
  * An HTTP client for integration tests, plus the two setups almost every suite
@@ -68,7 +71,8 @@ export function readCursor(payload: unknown): string | null {
   return payload.next_cursor
 }
 
-export function createTestClient(app: Hono<AppBindings>): TestClient {
+/** @param db Verifies a fresh signup directly, so almost every suite can start from a working owner. */
+export function createTestClient(app: Hono<AppBindings>, db: Database): TestClient {
   function send(method: string, path: string, options: TestRequestOptions = {}): Promise<Response> {
     return Promise.resolve(
       app.request(path, {
@@ -83,15 +87,31 @@ export function createTestClient(app: Hono<AppBindings>): TestClient {
     )
   }
 
+  /**
+   * Signs up and verifies directly against the database.
+   *
+   * These suites are about the CRM, not verification: going through the real
+   * emailed link for every signup would mean threading the email spy through
+   * this client too, for a step almost nothing here is testing. `auth.test.ts`
+   * and `workspace.test.ts` cover the real link.
+   */
   async function signUp(email: string): Promise<string> {
     const response = await send('POST', '/v1/auth/signup', {
-      body: { email, name: 'Someone', password: 'correct horse battery staple' },
+      body: {
+        email,
+        name: 'Someone',
+        password: 'correct horse battery staple',
+      },
     })
 
     if (response.status !== 201) {
       throw new Error(`Signing up ${email} answered ${String(response.status)}`)
     }
 
+    const accountId = readString(readRecord(await response.json()).account, 'id')
+
+    await db.update(users).set({ emailVerifiedAt: new Date() }).where(eq(users.id, accountId))
+
     // Only the cookie's name=value matters to a later request; the attributes
     // after the first semicolon are for a browser.
     return (response.headers.get('Set-Cookie') ?? '').split(';')[0] ?? ''

package/src/testing/environment.ts

@@ -16,7 +16,11 @@ import type { Environment } from '../lib/config.ts'
  */
 export const TEST_SECRET_ENCRYPTION_KEY = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA='
 
+/** The base URL every emailed link is built from in tests. */
+export const TEST_APP_BASE_URL = 'https://kelpie.test'
+
 export const TEST_ENVIRONMENT: Environment = {
   NODE_ENV: 'test',
   SECRET_ENCRYPTION_KEY: TEST_SECRET_ENCRYPTION_KEY,
+  APP_BASE_URL: TEST_APP_BASE_URL,
 }