@lincyaw/server 0.0.0-stage → 1.0.0-rc.1

package/src/server-routes.ts

@@ -0,0 +1,203 @@
+import { randomUUID } from 'node:crypto'
+import type { IncomingMessage } from 'node:http'
+import { errorMessage, hasRole, isRecord, jsonResponse, MAX_BODY, problemResponse, sseResponse } from '@lincyaw/kernel'
+import type { AuthoringDiagnostics, CanonicalSource, Finding, Member, PreviewDiagnostics } from '@lincyaw/kernel'
+import type { McpHost } from '@lincyaw/mcp'
+import type { ControlChannel, WindowPosition } from './control.ts'
+import type { DiagnosticStore } from './diagnostics.ts'
+import { toFocusRequest } from './focus.ts'
+import type { FocusStore } from './focus.ts'
+import { hasBearerToken, limitBody } from './http.ts'
+import type { McpTokens } from './mcp-access.ts'
+import type { ServerHost } from './server-host.ts'
+
+export const SERVER_PATH = '/__presmium/presmium.server'
+
+export interface ServerRoutesOptions {
+  control: ControlChannel
+  mcpTokens: McpTokens
+  focus: FocusStore
+  diagnostics: DiagnosticStore
+  mcpHost: McpHost
+  serverHost?: ServerHost
+  launcherToken?: string
+}
+
+export interface ServerRouteContext {
+  member: Member
+  document: string
+  req: IncomingMessage
+}
+
+/** The server's own routes under SERVER_PATH: hello, control, tokens, focus and diagnostics. */
+export function createServerRouteHandler(options: ServerRoutesOptions): (request: Request, route: string, ctx: ServerRouteContext) => Promise<Response> {
+  const { control, mcpTokens, focus, diagnostics, launcherToken } = options
+  const isFromLauncher = (request: Request) => launcherToken !== undefined && hasBearerToken(request, launcherToken)
+  const hasDocument = async (serverHost: ServerHost, document: string) => (await serverHost.documents()).some(doc => doc.dir === document)
+
+  const controlRoute = async (request: Request, { member, document, req }: ServerRouteContext): Promise<Response> => {
+    if (request.method === 'GET') {
+      const query = new URL(request.url).searchParams
+      const window = query.get('window') || randomUUID()
+      const stream = control.open(window, member, document, { observer: query.get('observe') === 'approvals' })
+      req.once('close', () => stream.end())
+      return sseResponse(stream, request.signal)
+    }
+    if (request.method !== 'POST') return problemResponse(405, 'GET or POST')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body: unknown = await limited.json().catch(() => undefined)
+    if (!isRecord(body)) return problemResponse(400, 'a JSON object')
+    if (body.type === 'answer' && typeof body.id === 'string') {
+      const status = control.answer(body.id, body.allow === true, member)
+      return status === 200 ? jsonResponse({ ok: true }) : problemResponse(status, status === 404 ? 'no such approval' : 'this member may not answer this approval')
+    }
+    if (body.type === 'report' && typeof body.window === 'string') {
+      const position = toWindowPosition(body.position)
+      const ok = control.report(body.window, member, { position, role: typeof body.role === 'string' ? body.role : undefined, status: isRecord(body.status) ? body.status : undefined })
+      return ok ? jsonResponse({ ok: true }) : problemResponse(404, 'unknown window')
+    }
+    return problemResponse(400, 'unknown message')
+  }
+
+  const tokensRoute = async (request: Request): Promise<Response> => {
+    if (!launcherToken) return problemResponse(403, 'session tokens are issued only to the host that started this service (PRESMIUM_SERVICE_TOKEN)')
+    if (!isFromLauncher(request)) return problemResponse(401, 'session tokens need Authorization: Bearer <the service token>')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body: unknown = await limited.json().catch(() => ({}))
+    const session = isRecord(body) && typeof body.session === 'string' && body.session !== '' ? body.session : undefined
+    if (request.method === 'DELETE') return jsonResponse({ revoked: mcpTokens.revokeAgentSessions(session) })
+    if (request.method !== 'POST') return problemResponse(405, 'POST or DELETE')
+    if (!isRecord(body) || typeof body.document !== 'string' || session === undefined) return problemResponse(400, '{ document, session }')
+    const document = body.document
+    if (options.serverHost && !(await hasDocument(options.serverHost, document))) return problemResponse(404, `no document ${JSON.stringify(document)}`)
+    const grant = mcpTokens.grantAgentSession(session, document)
+    return jsonResponse({ url: grant.url, token: grant.token, document }, 201)
+  }
+
+  const focusRoute = async (request: Request, member: Member): Promise<Response> => {
+    if (request.method === 'GET') {
+      const params = new URL(request.url).searchParams
+      const found = focus.find(params.has('document') ? params.get('document')! : undefined)
+      return jsonResponse(found ? { document: found.document, focus: found.focus, reported: new Date(found.at).toISOString() } : { focus: null })
+    }
+    if (request.method !== 'POST') return problemResponse(405, 'GET or POST')
+    if (launcherToken && !isFromLauncher(request)) return problemResponse(401, 'a focus report needs Authorization: Bearer <the service token>')
+    const { serverHost } = options
+    if (!serverHost) return problemResponse(409, 'this server compiles no document')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body = toFocusRequest(await limited.json().catch(() => undefined))
+    if (typeof body === 'string') return problemResponse(400, body)
+    const workspaceFocus = body.focus.filter(report => report.scope === 'workspace')
+    if (workspaceFocus.length && !hasRole(member, 'owner')) return problemResponse(403, 'workspace source selections need the owner role')
+    if (workspaceFocus.length && !serverHost.readSource) return problemResponse(400, 'this host does not read workspace source selections')
+    if (!(await hasDocument(serverHost, body.document))) return problemResponse(404, `no document ${JSON.stringify(body.document)}`)
+    try {
+      const doc = body.focus.some(report => report.scope !== 'workspace') ? (await serverHost.compile(body.document)).doc : undefined
+      const sources = new Map(await Promise.all(workspaceFocus.map(async (report) => {
+        const path = report.source!.file
+        return [path, (await serverHost.readSource!(path, member)).content] as const
+      })))
+      const record = focus.report(body.document, doc, body.focus, path => sources.get(path)!)
+      return jsonResponse({ document: record.document, focus: record.focus, reported: new Date(record.at).toISOString() })
+    } catch (error) {
+      return problemResponse(400, errorMessage(error))
+    }
+  }
+
+  const diagnosticsRoute = async (request: Request, stream: boolean, req: IncomingMessage): Promise<Response> => {
+    if (launcherToken && !isFromLauncher(request)) return problemResponse(401, 'diagnostics need Authorization: Bearer <the service token>')
+    const { serverHost } = options
+    if (!serverHost) return problemResponse(409, 'this server compiles no document')
+    const params = new URL(request.url).searchParams
+    if (request.method === 'GET') {
+      const document = params.has('document') ? params.get('document')! : undefined
+      if (document !== undefined) {
+        if (!(await hasDocument(serverHost, document))) return problemResponse(404, `no document ${JSON.stringify(document)}`)
+        await options.mcpHost.diagnostics!(document)
+      }
+      if (!stream) return jsonResponse(diagnostics.snapshot(document))
+      const connection = new AbortController()
+      req.once('close', () => connection.abort())
+      return sseResponse(diagnostics.events(document, AbortSignal.any([connection.signal, request.signal])), request.signal)
+    }
+    if (request.method !== 'POST' || stream) return problemResponse(405, stream ? 'GET' : 'GET or POST')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body: unknown = await limited.json().catch(() => undefined)
+    const report = toPreviewDiagnostics(body)
+    if (typeof report === 'string') return problemResponse(400, report)
+    if (!(await hasDocument(serverHost, report.document))) return problemResponse(404, `no document ${JSON.stringify(report.document)}`)
+    return jsonResponse({ accepted: diagnostics.report(report) })
+  }
+
+  return async (request, route, ctx) => {
+    if (route === 'hello') return jsonResponse({ member: ctx.member, document: ctx.document })
+    if (route === 'control') return await controlRoute(request, ctx)
+    if (route === 'tokens') return await tokensRoute(request)
+    if (route === 'focus') return await focusRoute(request, ctx.member)
+    if (route === 'diagnostics/authoring') {
+      if (launcherToken && !isFromLauncher(request)) return problemResponse(401, 'authoring diagnostics need the service token')
+      if (!hasRole(ctx.member, 'editor')) return problemResponse(403, 'authoring diagnostics need the role editor')
+      if (request.method !== 'POST') return problemResponse(405, 'POST')
+      if (!options.serverHost?.authoring) return problemResponse(409, 'authoring diagnostics are unavailable')
+      const limited = await limitBody(request, 64 << 10)
+      if (limited instanceof Response) return limited
+      const report = toAuthoringDiagnostics(await limited.json().catch(() => undefined))
+      if (typeof report === 'string') return problemResponse(400, report)
+      if (!(await hasDocument(options.serverHost, report.document))) return problemResponse(404, 'no such authoring document')
+      diagnostics.reportAuthoring(report, ctx.member.id)
+      return jsonResponse({ accepted: true })
+    }
+    if (route === 'diagnostics' || route === 'diagnostics/events') return await diagnosticsRoute(request, route === 'diagnostics/events', ctx.req)
+    return problemResponse(404, 'not found')
+  }
+}
+
+function toAuthoringDiagnostics(body: unknown): AuthoringDiagnostics | string {
+  if (!isRecord(body) || Object.keys(body).some(key => !['document', 'instance', 'findings'].includes(key))
+    || typeof body.document !== 'string' || body.document.length > 1024 || typeof body.instance !== 'string' || !/^workbench:[a-zA-Z0-9.-]{1,80}$/.test(body.instance)
+    || !Array.isArray(body.findings) || body.findings.length > 20) return 'authoring diagnostics need document, workbench instance and at most 20 findings'
+  const findings: AuthoringDiagnostics['findings'] = []
+  for (const item of body.findings) {
+    if (!isRecord(item) || Object.keys(item).some(key => !['checkId', 'severity', 'message', 'authoringSource'].includes(key))
+      || typeof item.checkId !== 'string' || !item.checkId.startsWith('presmium.workbench.') || item.checkId.length > 100
+      || item.severity !== 'error' || typeof item.message !== 'string' || item.message.length > 600) return 'invalid authoring diagnostic'
+    let source: CanonicalSource | undefined
+    if (item.authoringSource !== undefined) {
+      const value = item.authoringSource
+      if (!isRecord(value) || Object.keys(value).some(key => !['documentId', 'version', 'fingerprint'].includes(key))
+        || !['documentId', 'version'].every(key => typeof value[key] === 'string' && (value[key] as string).length > 0 && (value[key] as string).length <= 200)
+        || typeof value.fingerprint !== 'string' || !/^[a-f\d]{16}$/.test(value.fingerprint)) return 'invalid authoring diagnostic source'
+      source = { documentId: value.documentId as string, version: value.version as string, fingerprint: value.fingerprint }
+    }
+    findings.push({ checkId: item.checkId, severity: 'error', message: item.message, ...source ? { authoringSource: source } : {} })
+  }
+  return { document: body.document, instance: body.instance, findings }
+}
+
+function toPreviewDiagnostics(body: unknown): PreviewDiagnostics | string {
+  if (!isRecord(body) || typeof body.document !== 'string' || (body.renderer !== 'web' && body.renderer !== 'slides') || typeof body.instance !== 'string' || !body.instance || typeof body.revision !== 'string' || !Array.isArray(body.findings)) return 'a preview diagnostic report needs document, renderer, instance, revision and findings'
+  const findings: Finding[] = []
+  for (const item of body.findings) {
+    if (!isRecord(item) || typeof item.checkId !== 'string' || typeof item.message !== 'string' || !['error', 'warning', 'info'].includes(String(item.severity))) return 'each diagnostic needs checkId, severity and message'
+    if (item.hint !== undefined && typeof item.hint !== 'string') return 'a diagnostic hint must be text'
+    if (item.source !== undefined && (!isRecord(item.source) || typeof item.source.file !== 'string' || (item.source.line !== undefined && (!Number.isInteger(item.source.line) || Number(item.source.line) < 1)))) return 'a diagnostic source needs a file and an optional positive line'
+    findings.push({ checkId: item.checkId, severity: item.severity as Finding['severity'], message: item.message, ...item.hint ? { hint: item.hint as string } : {}, ...item.source ? { source: item.source as Finding['source'] } : {} })
+  }
+  return { document: body.document, renderer: body.renderer, instance: body.instance, revision: body.revision, findings }
+}
+
+function toWindowPosition(value: unknown): WindowPosition | undefined {
+  if (!isRecord(value) || typeof value.slide !== 'number' || typeof value.step !== 'number') return undefined
+  const { trail } = value
+  return {
+    slide: value.slide,
+    step: value.step,
+    ...typeof value.view === 'string' ? { view: value.view } : {},
+    ...typeof value.section === 'string' ? { section: value.section } : {},
+    ...Array.isArray(trail) && trail.length <= 10_000 && trail.every(key => typeof key === 'string') ? { trail: trail as string[] } : {},
+  }
+}

package/src/server.ts

@@ -0,0 +1,307 @@
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs'
+import type { IncomingMessage } from 'node:http'
+import { dirname } from 'node:path'
+import { APPROVALS, errorMessage, hasRole, MAX_BODY, MCP_ENDPOINT, problemResponse } from '@lincyaw/kernel'
+import type { ApprovalKind, Logger, Member, ProxySpec, Route, ServiceToken } from '@lincyaw/kernel'
+import { pluginLogger } from '@lincyaw/compiler'
+import { createPresmiumMcp } from '@lincyaw/mcp'
+import type { McpCaller } from '@lincyaw/mcp'
+import { authenticate, machineHosts } from './auth.ts'
+import type { MachineHosts } from './auth.ts'
+import type { Refusal } from './auth.ts'
+import { ControlChannel } from './control.ts'
+import type { ApprovalPolicy } from './control.ts'
+import { FocusStore } from './focus.ts'
+import { DiagnosticStore } from './diagnostics.ts'
+import { bearer, createProxy, header, isLoopback, limitBody, listen, nodeServer, normalizeHostName, urlHost } from './http.ts'
+import type { Decision, ProxyTarget } from './http.ts'
+import { McpTokens } from './mcp-access.ts'
+import { serverMcpHost } from './mcp-host.ts'
+import { Mounts } from './mounts.ts'
+import { createServerRouteHandler, SERVER_PATH } from './server-routes.ts'
+import type { ServedDocument, ServerHost } from './server-host.ts'
+
+function isMcp(path: string): boolean {
+  return path === '/mcp' || path.startsWith('/mcp/')
+}
+
+export interface ServerOptions {
+  mode: 'dev' | 'serve'
+  listenAddress?: string
+  port?: number
+  document(dir: string): Promise<ServedDocument | undefined>
+  serverHost?: ServerHost
+  settings?: Record<string, Record<string, unknown>>
+  approvals?: Partial<Record<ApprovalKind, ApprovalPolicy>>
+  /** The origin to forward a path of the site to (in `serve`): the dev server that serves it. */
+  forward?(path: string): string | undefined | Promise<string | undefined>
+  operatorDir?: string
+  /**
+   * The address browsers use when a reverse proxy fronts the server: its host is trusted as this machine's, and pages
+   * are advertised under it. A path (`https://host/user/a/preview/`) is the base below which the proxy forwards the
+   * unchanged path; the server's own routes are found below it, and still at the root for calls on its own address.
+   */
+  publicUrl?: string
+  stateFile?: string
+  mcp?(request: Request, access: McpCaller): Promise<Response>
+  env?: NodeJS.ProcessEnv
+  approvalTimeoutMs?: number
+  log?: Logger
+  diagnostics?: DiagnosticStore
+}
+
+export interface PresmiumServer {
+  url: string
+  /** The address browsers use: `publicUrl` when given, else `url`. */
+  publicUrl: string
+  port: number
+  mcpToken: string
+  services: [ServiceToken<unknown>, unknown][]
+  control: ControlChannel
+  diagnostics: DiagnosticStore
+  serverHost?: ServerHost
+  unmount(dir: string, options?: { preserveFocus?: boolean }): Promise<void>
+  close(): Promise<void>
+}
+
+function parsePluginPath(pathname: string): { plugin: string, path: string, raw: string, plain: boolean } | undefined {
+  const match = /^\/__presmium\/([^/]+)\/?(.*)$/.exec(pathname)
+  if (!match) return undefined
+  const raw = match[2]!
+  let path = raw
+  let plain = !/%(?:2f|5c)/i.test(raw) && !raw.includes('\\')
+  try {
+    path = decodeURIComponent(raw)
+  } catch {
+    plain = false
+  }
+  if (path.split('/').some(part => part === '.' || part === '..')) plain = false
+  return { plugin: match[1]!, path, raw, plain }
+}
+
+function findRoute(routes: Record<string, Route> | undefined, path: string): { route: Route, rest: string, key: string } | undefined {
+  if (!routes) return undefined
+  if (routes[path] && !path.endsWith('/*')) return { route: routes[path]!, rest: '', key: path }
+  let best: { route: Route, rest: string, key: string } | undefined
+  for (const [key, route] of Object.entries(routes)) {
+    if (!key.endsWith('/*')) continue
+    const prefix = key.slice(0, -1)
+    const base = key.slice(0, -2)
+    if ((path.startsWith(prefix) || path === base) && (!best || key.length > best.key.length)) best = { route, rest: path.slice(prefix.length), key }
+  }
+  return best
+}
+
+function findProxy(proxies: ProxySpec[] | undefined, path: string): { spec: ProxySpec, rest: string } | undefined {
+  for (const spec of proxies ?? []) {
+    const base = spec.path.replace(/^\/+|\/+$/g, '')
+    if (path === base || path.startsWith(`${base}/`)) return { spec, rest: path.slice(base.length) }
+  }
+  return undefined
+}
+
+function requestedDocument(headers: IncomingMessage['headers'], url: URL): string {
+  const value = header(headers, 'presmium-document') ?? url.searchParams.get('document') ?? ''
+  try {
+    return decodeURIComponent(value).replace(/^\/+|\/+$/g, '')
+  } catch {
+    return value
+  }
+}
+
+function remoteListenRefusal(mode: ServerOptions['mode'], listenAddress: string, port: number | undefined): string | undefined {
+  if (mode === 'serve' || isLoopback(listenAddress)) return undefined
+  const at = port || 'its port'
+  return `presmium ${mode} listens on this machine only, not on ${listenAddress}: it serves the one user who runs it. To use it from another machine, forward its port over SSH (ssh -L ${at}:127.0.0.1:${at} <this machine>), or use presmium serve --host`
+}
+
+export async function startServer(options: ServerOptions): Promise<PresmiumServer> {
+  const env = options.env ?? process.env
+  const log = options.log ?? pluginLogger('presmium server')
+  const listenAddress = options.listenAddress ?? '127.0.0.1'
+  const refused = remoteListenRefusal(options.mode, listenAddress, options.port)
+  if (refused) throw new Error(refused)
+  const basePath = options.publicUrl ? `${new URL(options.publicUrl).pathname.replace(/\/+$/, '')}/` : '/'
+  const inner = (path: string) => basePath !== '/' && path.startsWith(basePath) ? path.slice(basePath.length - 1) : path
+  const machine = machineHosts(listenAddress)
+  const publicHost = options.publicUrl ? normalizeHostName(new URL(options.publicUrl).host) : undefined
+  const local: MachineHosts = publicHost ? host => host === publicHost || machine(host) : machine
+
+  const control = new ControlChannel({
+    policy: options.approvals ?? {},
+    timeoutMs: options.approvalTimeoutMs,
+  })
+  let url = ''
+  const mcpTokens = new McpTokens(() => url)
+  const services: [ServiceToken<unknown>, unknown][] = [[APPROVALS, control.approvals], [MCP_ENDPOINT, mcpTokens.endpoint]]
+  const ownServices = new Map(services.map(([token, implementation]) => [token.id, implementation]))
+  const ownService = <T>(token: ServiceToken<T>) => ownServices.get(token.id) as T | undefined
+  const focus = new FocusStore()
+  const diagnostics = options.diagnostics ?? new DiagnosticStore()
+  const mounts = new Mounts({ document: options.document, ownService, settings: options.settings, operatorDir: options.operatorDir, env, diagnostics, log })
+
+  const mcpHost = serverMcpHost({
+    serverHost: options.serverHost,
+    control,
+    command: options.mode,
+    mount: async dir => (await mounts.mount(dir))?.doc,
+    mounted: () => mounts.documents(),
+    service: ownService,
+    focus,
+    diagnostics,
+  })
+  const mcp = options.mcp ? undefined : createPresmiumMcp(mcpHost)
+  const serverRoute = createServerRouteHandler({ control, mcpTokens, focus, diagnostics, mcpHost, serverHost: options.serverHost, launcherToken: env.PRESMIUM_SERVICE_TOKEN || undefined })
+
+  const members = new WeakMap<IncomingMessage, Member | Refusal>()
+  const memberOf = (req: IncomingMessage): Member | Refusal => {
+    let found = members.get(req)
+    if (!found) members.set(req, found = authenticate(req, local))
+    return found
+  }
+
+  const refuse = (refusal: Refusal): Decision => ({ kind: 'answer', response: problemResponse(refusal.status, refusal.message) })
+
+  const decide = async (req: IncomingMessage): Promise<Decision> => {
+    const url = new URL(req.url ?? '/', 'http://presmium')
+    const path = inner(url.pathname)
+    const member = memberOf(req)
+    if ('status' in member) return refuse(member)
+    const target = parsePluginPath(path)
+    if (target && !target.plain) return refuse({ status: 400, message: 'a path with a . or .. part or an encoded separator' })
+    if (isMcp(path)) return { kind: 'fetch' }
+    if (target) {
+      if (target.plugin === 'presmium.server') return { kind: 'fetch' }
+      if (findRoute(options.serverHost?.routes?.[target.plugin], target.path)) return { kind: 'fetch' }
+      const proxy = await proxyOf(target, requestedDocument(req.headers, url), member, url.search)
+      return proxy ?? { kind: 'fetch' }
+    }
+    const forward = options.mode === 'serve' ? await options.forward?.(url.pathname) : undefined
+    if (!forward) return { kind: 'answer', response: problemResponse(404, 'not found') }
+    const site = new URL(forward)
+    const lan = !isLoopback(header(req.headers, 'host'))
+    const headers = lan ? { host: site.host, ...header(req.headers, 'origin') ? { origin: site.origin } : {} } : undefined
+    return { kind: 'proxy', to: { target: forward, path: req.url ?? '/', ...headers ? { headers } : {} } }
+  }
+
+  const proxyOf = async (target: { plugin: string, path: string, raw: string }, dir: string, member: Member, search: string): Promise<Decision | undefined> => {
+    const contribution = (await mounts.mount(dir))?.contributions.get(target.plugin)
+    const found = findProxy(contribution?.proxies, target.path)
+    if (!found) return undefined
+    const role = found.spec.role ?? 'editor'
+    if (!hasRole(member, role)) return refuse({ status: 403, message: `this proxy needs the role ${role}` })
+    const base = found.spec.path.split('/').filter(Boolean).length
+    const rest = target.raw.split('/').slice(base).join('/')
+    const path = `${rest ? `/${rest}` : found.rest || '/'}${search}`
+    return { kind: 'proxy', to: { target: found.spec.target, path, headers: found.spec.headers } }
+  }
+
+  const decideUpgrade = async (req: IncomingMessage): Promise<{ to?: ProxyTarget, status?: number }> => {
+    const decision = await decide(req)
+    if (decision.kind === 'proxy') return { to: decision.to }
+    return { status: decision.kind === 'answer' ? decision.response.status : 404 }
+  }
+
+  const serveMcp = async (request: Request): Promise<Response> => {
+    const given = bearer(request.headers.get('authorization'))
+    const caller = mcpTokens.callerOf(given)
+    if (!caller) return problemResponse(401, 'MCP needs an Authorization: Bearer token')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const response = await (options.mcp ? options.mcp(limited, caller) : mcp!.fetch(limited, caller))
+    return mcpTokens.tieToGrant(given!, response)
+  }
+
+  const pluginRoute = async (request: Request, target: { plugin: string, path: string }, member: Member, document: string): Promise<Response> => {
+    let found = findRoute(options.serverHost?.routes?.[target.plugin], target.path)
+    if (!found) {
+      const known = await mounts.mount(document)
+      if (!known) return problemResponse(404, `no document ${JSON.stringify(document)}`)
+      found = findRoute(known.contributions.get(target.plugin)?.routes, target.path)
+    }
+    if (!found) return problemResponse(404, 'not found')
+    const role = found.route.role ?? 'editor'
+    if (!hasRole(member, role)) return problemResponse(403, `this route needs the role ${role}`)
+    const limited = await limitBody(request, found.route.maxBody ?? MAX_BODY)
+    if (limited instanceof Response) return limited
+    try {
+      const response = await found.route.handle(limited, { member, document, rest: found.rest })
+      return response.headers.has('cache-control') ? response : withHeaders(response, { 'Cache-Control': 'no-store' })
+    } catch (error) {
+      log.error(`route ${target.plugin}/${target.path} failed: ${errorMessage(error)}`)
+      return problemResponse(500, errorMessage(error))
+    }
+  }
+
+  const handle = async (request: Request, req: IncomingMessage): Promise<Response> => {
+    const url = new URL(request.url)
+    const path = inner(url.pathname)
+    const member = memberOf(req)
+    if ('status' in member) return problemResponse(member.status, member.message)
+    const document = requestedDocument(req.headers, url)
+    if (isMcp(path)) return serveMcp(request)
+    if (path.startsWith(`${SERVER_PATH}/`)) return await serverRoute(request, path.slice(SERVER_PATH.length + 1), { member, document, req })
+    const target = parsePluginPath(path)
+    if (!target) return problemResponse(404, 'not found')
+    return await pluginRoute(request, target, member, document)
+  }
+
+  const proxy = createProxy()
+  const http = nodeServer({ decide, decideUpgrade, fetch: handle, proxy })
+  let closing: Promise<void> | undefined
+  const close = (): Promise<void> => closing ??= Promise.resolve().then(async () => {
+    mounts.stop()
+    mcpTokens.revokeAgentSessions()
+    control.close()
+    await mcp?.close().catch((error: unknown) => log.error(`MCP failed to close: ${errorMessage(error)}`))
+    try {
+      await mounts.close()
+    } finally {
+      try { proxy.close() }
+      finally { await http.close() }
+    }
+  })
+  let port: number
+  try {
+    port = await listen(http.server, options.port ?? (options.mode === 'dev' ? 0 : 4310), listenAddress)
+    url = `http://${urlHost(listenAddress)}:${port}`
+    log.debug(`listening at ${url}`)
+    if (options.stateFile) {
+      mkdirSync(dirname(options.stateFile), { recursive: true })
+      writeFileSync(options.stateFile, `${JSON.stringify({ url, mcp: `${url}/mcp`, token: mcpTokens.processMcpToken, pid: process.pid }, null, 2)}\n`, { mode: 0o600 })
+      chmodSync(options.stateFile, 0o600)
+    }
+  } catch (error) {
+    await close().catch((cleanup: unknown) => log.error(`the server failed to close after startup failed: ${errorMessage(cleanup)}`))
+    throw error
+  }
+
+  return {
+    url,
+    publicUrl: options.publicUrl?.replace(/\/+$/, '') ?? url,
+    port,
+    mcpToken: mcpTokens.processMcpToken,
+    services,
+    control,
+    serverHost: options.serverHost,
+    diagnostics,
+    async unmount(dir, unmountOptions = {}) {
+      if (!unmountOptions.preserveFocus) focus.forget(dir)
+      await mounts.unmount(dir)
+    },
+    close,
+  }
+}
+
+function withHeaders(response: Response, headers: Record<string, string>): Response {
+  for (const [name, value] of Object.entries(headers)) {
+    try {
+      response.headers.set(name, value)
+    } catch {
+      const copy = new Response(response.body, response)
+      for (const [n, v] of Object.entries(headers)) copy.headers.set(n, v)
+      return copy
+    }
+  }
+  return response
+}