@kelpie/server 0.4.1 → 0.5.0

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,

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,
 }

package/src/webBundle.ts

@@ -25,6 +25,14 @@ import { MCP_ROUTE_PREFIX } from './modules/mcp/index.ts'
 export interface WebBundleOptions {
   /** Directory holding the built `index.html` and its assets. */
   readonly directory: string
+  /**
+   * Prefixes the assembly's own modules answer on beyond core's, via
+   * `appRoute`/`appMiddleware`. An unmatched GET under one stays a JSON
+   * error instead of becoming the app shell, the same rule `/v1` gets. The
+   * assembly names them here because only it knows which of its declared
+   * paths are API rather than pages.
+   */
+  readonly apiPrefixes?: readonly string[]
 }
 
 /** The bundle directory does not hold a build. Thrown at boot, never per request. */
@@ -36,15 +44,16 @@ export class WebBundleError extends Error {
 }
 
 /**
- * The prefixes `createApp` answers on.
+ * The prefixes `createApp` itself answers on.
  *
  * `/v1/public` needs no entry of its own: it sits under `/v1`. `MCP_ROUTE_PREFIX`
  * is imported rather than written out, so moving the endpoint moves this with it.
+ * An assembly's own API prefixes arrive through `WebBundleOptions.apiPrefixes`.
  */
-const API_PREFIXES: readonly string[] = ['/v1', MCP_ROUTE_PREFIX, '/healthz']
+const CORE_API_PREFIXES: readonly string[] = ['/v1', MCP_ROUTE_PREFIX, '/healthz']
 
-function isApiRequest(path: string): boolean {
-  return API_PREFIXES.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))
+function isApiRequestFor(prefixes: readonly string[]): (path: string) => boolean {
+  return (path) => prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))
 }
 
 /**
@@ -60,7 +69,10 @@ function isApiRequest(path: string): boolean {
  * not a page request, and only a `GET` or a `HEAD` can sensibly be answered with
  * a document.
  */
-function webRequestsOnly(handler: MiddlewareHandler): MiddlewareHandler {
+function webRequestsOnly(
+  isApiRequest: (path: string) => boolean,
+  handler: MiddlewareHandler,
+): MiddlewareHandler {
   return async (context, next) => {
     const isDocumentRequest = context.req.method === 'GET' || context.req.method === 'HEAD'
 
@@ -93,10 +105,12 @@ export function serveWebBundle(app: Hono<AppBindings>, options: WebBundleOptions
     )
   }
 
+  const isApiRequest = isApiRequestFor([...CORE_API_PREFIXES, ...(options.apiPrefixes ?? [])])
+
   // Two registrations rather than one: `serveStatic` calls `next()` when it
   // finds no file, which is exactly the signal the fallback needs. A request
   // for a real asset is answered by the first and never reaches the second.
-  app.use('*', webRequestsOnly(serveStatic({ root: directory })))
+  app.use('*', webRequestsOnly(isApiRequest, serveStatic({ root: directory })))
 
   // The single-page fallback. The app decides what to draw from the address, so
   // a deep link to `/people/per_01J…` has to return the same `index.html` even
@@ -106,5 +120,5 @@ export function serveWebBundle(app: Hono<AppBindings>, options: WebBundleOptions
   // does by default. Narrowing this by `Accept` would turn a stale asset
   // reference into a clean 404, and would also turn `curl /people/per_01J…`
   // into one, so it is left alone.
-  app.use('*', webRequestsOnly(serveStatic({ path: indexHtml })))
+  app.use('*', webRequestsOnly(isApiRequest, serveStatic({ path: indexHtml })))
 }