@kelpie/server 0.11.0 → 0.13.0

package/src/runtime/registry.ts

@@ -13,12 +13,15 @@ import type { EntitlementRegistry } from './entitlements.ts'
 import { createEventBus } from './events.ts'
 import type { EventBus } from './events.ts'
 import type {
+  CompletedSignIn,
+  ExternalSignInHandler,
   KelpieModule,
   McpTool,
   ModuleCatalogEntry,
   ModuleContext,
   ModuleServices,
   SchemaContribution,
+  VerifiedIdentity,
 } from './module.ts'
 import { createModuleConfigProvider, moduleCapabilityName, validateModuleConfig } from './moduleConfig.ts'
 import { ModuleBootError, orderModules } from './order.ts'
@@ -84,6 +87,117 @@ function assertMountablePath(moduleId: string, kind: string, path: string): void
   }
 }
 
+/** Verb methods a module can call on the router — full Hono set. */
+const ROUTER_VERB_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'all'] as const
+type RouterVerbMethod = (typeof ROUTER_VERB_METHODS)[number]
+
+function isRouterVerbMethod(name: string): name is RouterVerbMethod {
+  return (ROUTER_VERB_METHODS as readonly string[]).includes(name)
+}
+
+/**
+ * Wraps a Hono router so every route the module registers runs `gate` first,
+ * and only that module's own routes. The straightforward alternative —
+ * `router.use('*', gate)` — attaches at `/v1/*` on the app once the router is
+ * mounted (Hono flattens sub-routers onto the parent prefix), so the gate
+ * fires for every module's routes, not just this module's. Prepending the gate
+ * to each declared route keeps the check local.
+ *
+ * The full router surface is covered so a future contributor cannot silently
+ * reintroduce the leak by reaching for a method that was not wrapped:
+ *
+ * - HTTP verbs and `on`: prepend `gate`, then the module's handlers.
+ * - `use(pattern, ...)` at a specific path: prepend `gate`, then the mw.
+ * - `route(subPath, subApp)`: recursively wrap `subApp` before mounting, so
+ *   every route it contributes still runs the gate first.
+ *
+ * And the calls that cannot be made module-local through wrapping fail at
+ * boot with a message naming the module, rather than shipping a subtle leak:
+ *
+ * - `use()` with no path, `use('*')`, `use('/*')`, `use('/')`: any of these
+ *   register a middleware at `/v1/*` on the parent app once the router is
+ *   mounted — the exact bug this wrapper prevents. A module that wants to
+ *   share middleware across many of its routes must name a specific path
+ *   (`/things/*`) or attach the middleware per route.
+ * - `notFound` / `onError`: fire for every unmatched or failing `/v1`
+ *   request once the router is flattened, so a module's handler would run
+ *   for other modules' traffic. Handle failures inside the module's own
+ *   route handlers instead.
+ */
+function gateRouter(router: Hono, moduleId: string, gate: MiddlewareHandler): Hono {
+  const proxy: Hono = new Proxy(router, {
+    get(target, property, receiver) {
+      if (typeof property !== 'string') {
+        return Reflect.get(target, property, receiver)
+      }
+
+      if (isRouterVerbMethod(property)) {
+        return (path: string, ...handlers: Handler[]): Hono => {
+          const method = target[property] as (path: string, ...handlers: Handler[]) => Hono
+          method.call(target, path, gate, ...handlers)
+          return proxy
+        }
+      }
+
+      if (property === 'on') {
+        return (
+          method: string | string[],
+          path: string | string[],
+          ...handlers: Handler[]
+        ): Hono => {
+          target.on(method as never, path as never, gate, ...handlers)
+          return proxy
+        }
+      }
+
+      if (property === 'use') {
+        return (...args: unknown[]): Hono => {
+          const first = args[0]
+          const isAppWide =
+            typeof first !== 'string' || first === '*' || first === '/*' || first === '/'
+
+          if (isAppWide) {
+            throw new ModuleBootError([
+              `module "${moduleId}" called router.use() with an app-wide pattern (${
+                typeof first === 'string' ? `"${first}"` : 'no path'
+              }). Hono flattens the module router onto "/v1", so this would fire for every module's routes. Name a specific path ("/things/*") or attach middleware per route.`,
+            ])
+          }
+
+          const [pattern, ...handlers] = args as [string, ...MiddlewareHandler[]]
+          target.use(pattern, gate, ...handlers)
+          return proxy
+        }
+      }
+
+      if (property === 'route') {
+        return (path: string, subApp: Hono): Hono => {
+          // The sub-app's routes were registered on it before this call, so a
+          // proxy over `subApp` cannot retroactively prepend the gate to them.
+          // Instead attach the gate as middleware scoped to the sub-router's
+          // mount prefix on this router — once flattened onto `/v1`, the
+          // middleware covers exactly `/v1${path}/*`, which is the module's
+          // own routes. `use` must land before `route` so composition order
+          // runs the gate first.
+          target.use(`${path.replace(/\/+$/, '')}/*`, gate)
+          target.route(path, subApp)
+          return proxy
+        }
+      }
+
+      if (property === 'notFound' || property === 'onError') {
+        throw new ModuleBootError([
+          `module "${moduleId}" called router.${property}(). A module router's ${property} fires for every unmatched or failing "/v1" request once the router is mounted; handle failures inside the module's own route handlers instead.`,
+        ])
+      }
+
+      return Reflect.get(target, property, receiver)
+    },
+  }) as Hono
+
+  return proxy
+}
+
 /**
  * What `registerModules` needs.
  *
@@ -180,6 +294,46 @@ class EmailSenderProxy implements EmailSender {
   }
 }
 
+/**
+ * Completes a sign-in for an identity a module verified elsewhere.
+ *
+ * Same shape as `EmailSenderProxy`, and for the same reason: one module owns
+ * the implementation, every module reaches it through this object, and a
+ * consumer captures the proxy at register time but only calls it at request
+ * time, so registration order does not matter.
+ *
+ * Exactly one installer, unlike email's named registry: there is one `users`
+ * table and one session cookie, so "which implementation" is never a question
+ * an assembly should have to answer.
+ */
+class ExternalSignInProxy {
+  private target: ExternalSignInHandler | undefined = undefined
+  private installedBy: string | undefined = undefined
+
+  install(moduleId: string, handler: ExternalSignInHandler): void {
+    if (this.installedBy !== undefined) {
+      throw new ModuleBootError([
+        `module "${moduleId}" provides external sign-in, but module "${this.installedBy}" already did`,
+      ])
+    }
+
+    this.target = handler
+    this.installedBy = moduleId
+  }
+
+  complete(context: Context, identity: VerifiedIdentity): Promise<CompletedSignIn> {
+    if (this.target === undefined) {
+      return Promise.reject(
+        new Error(
+          'external sign-in used before a module installed it. Is the auth module in the assembly?',
+        ),
+      )
+    }
+
+    return this.target(context, identity)
+  }
+}
+
 /**
  * The name the runtime uses for its built-in log sender. Reserved: a module
  * that tries to register under this name fails boot.
@@ -204,11 +358,20 @@ function createModuleContext(
   moduleCatalog: readonly ModuleCatalogEntry[],
   emailProxy: EmailSenderProxy,
   providers: Map<string, RegisteredProvider>,
+  externalSignIn: ExternalSignInProxy,
 ): ModuleContext {
   return {
     ...options.services,
     email: emailProxy,
 
+    provideExternalSignIn(handler) {
+      externalSignIn.install(module.id, handler)
+    },
+
+    completeExternalSignIn(context, identity) {
+      return externalSignIn.complete(context, identity)
+    },
+
     provideEmailSender(name, build) {
       if (name === LOG_PROVIDER_NAME) {
         throw new ModuleBootError([
@@ -230,22 +393,25 @@ function createModuleContext(
     routes(mount) {
       const router = new Hono()
 
-      // Gate first, so it runs before anything `mount` adds: Hono composes a
-      // path's handlers in the order they were registered on this router,
-      // middleware included, and registering after the routes it should guard
-      // would run it too late to block them.
+      // Gate must run before anything `mount` adds. A `router.use('*', gate)`
+      // here would attach at `/v1/*` on the app after mounting (Hono flattens
+      // the sub-router onto the parent prefix), which would fire the gate for
+      // every module's routes, not just this one's. So the gate is prepended
+      // to each individual route through `gateRouter` instead.
       if (module.structural !== true && options.resolveActor !== undefined) {
         const { resolveActor } = options
-
-        router.use('*', async (context, next) => {
+        const gate: MiddlewareHandler = async (context, next) => {
           const actor = await resolveActor(context)
 
           await requireCapability(entitlements, requireWorkspaceId(actor), moduleCapabilityName(module.id))
           await next()
-        })
+        }
+
+        mount(gateRouter(router, module.id, gate))
+      } else {
+        mount(router)
       }
 
-      mount(router)
       accumulator.routers.push({ moduleId: module.id, router })
     },
 
@@ -348,6 +514,7 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
   const entitlements = options.entitlements ?? createEntitlementRegistry()
   const emailProxy = new EmailSenderProxy()
   const emailProviders = new Map<string, RegisteredProvider>()
+  const externalSignIn = new ExternalSignInProxy()
 
   // The built-in log provider is always available, no module required. Named
   // 'log' in kelpie.config.ts's email.provider picks this one. Built eagerly
@@ -429,6 +596,7 @@ export async function registerModules(options: ModuleRuntimeOptions): Promise<Mo
       moduleCatalog,
       emailProxy,
       emailProviders,
+      externalSignIn,
     )
 
     try {

package/src/schema/index.ts

@@ -20,6 +20,7 @@ export * from '../modules/opportunities/schema.ts'
 export * from '../modules/partnerships/schema.ts'
 export * from '../modules/raises/schema.ts'
 export * from '../modules/hiring/schema.ts'
+export * from '../modules/events/schema.ts'
 export * from '../modules/plans/schema.ts'
 export * from '../modules/decisions/schema.ts'
 export * from '../modules/notes/schema.ts'

package/src/testing/app.ts

@@ -1,3 +1,4 @@
+import type { PublicRegion } from '@kelpie/schemas'
 import type { Context, Hono } from 'hono'
 
 import { createApp } from '../app.ts'
@@ -61,6 +62,13 @@ export interface TestAppOptions {
   readonly runtimeMode?: RuntimeMode
   /** Reported through `GET /v1/public/config`. Defaults to unset. */
   readonly siteName?: string
+  /**
+   * Reported through `GET /v1/public/config` and consulted by the `auth`
+   * module's `signUp` and `completeExternalSignIn`. Defaults to `true` (open).
+   */
+  readonly signupsEnabled?: boolean
+  /** Reported through `GET /v1/public/config`. Defaults to `[]`. */
+  readonly regions?: readonly PublicRegion[]
 }
 
 export interface TestApp {
@@ -94,7 +102,10 @@ export async function createTestApp(options: TestAppOptions = {}): Promise<TestA
     ...(options.entitlements === undefined ? {} : { entitlements: options.entitlements }),
     ...(options.moduleConfig === undefined ? {} : { moduleConfig: options.moduleConfig }),
     ...(options.resolveActor === undefined ? {} : { resolveActor: options.resolveActor }),
-    services,
+    services: {
+      ...services,
+      ...(options.signupsEnabled === undefined ? {} : { signupsEnabled: options.signupsEnabled }),
+    },
   })
 
   const app = createApp({
@@ -108,6 +119,8 @@ export async function createTestApp(options: TestAppOptions = {}): Promise<TestA
     resolveClientIp: options.resolveClientIp ?? testClientIp,
     ...(options.runtimeMode === undefined ? {} : { runtimeMode: options.runtimeMode }),
     ...(options.siteName === undefined ? {} : { siteName: options.siteName }),
+    ...(options.signupsEnabled === undefined ? {} : { signupsEnabled: options.signupsEnabled }),
+    ...(options.regions === undefined ? {} : { regions: options.regions }),
   })
 
   return { app, contributions, logLines, services }

package/src/testing/client.ts

@@ -132,7 +132,17 @@ export function createTestClient(app: Hono<AppBindings>, db: Database): TestClie
         throw new Error(`Creating workspace ${slug} answered ${String(created.status)}`)
       }
 
-      return { cookie, workspaceId: readString(await created.json(), 'id') }
+      const workspaceId = readString(await created.json(), 'id')
+      const seeded = await send('POST', `/v1/workspaces/${workspaceId}/handbook/seed`, {
+        body: { handbook_template: 'startup' },
+        cookie,
+      })
+
+      if (seeded.status !== 201) {
+        throw new Error(`Seeding handbook for ${slug} answered ${String(seeded.status)}`)
+      }
+
+      return { cookie, workspaceId }
     },
   }
 }