@astrale-os/sdk 0.1.0

package/src/server/auxiliary-routes.ts

@@ -0,0 +1,336 @@
+/**
+ * Mount worker-side routes for `defineView` and `defineRemoteFunction` entries.
+ *
+ * Each entry's effective `FunctionBinding` is resolved once at boot (host
+ * pattern, path, http verb) and a Hono route is registered that runs the
+ * shared SDK auth pipeline (verify inbound credential, optionally enforce /
+ * optional / public), Zod validation of input AND output (RemoteFunction
+ * only — Views are transport-only), the author's `authorize` hook, and
+ * finally `render` / `execute`.
+ *
+ * Bindings whose host is not a sub-domain of this worker's host are skipped
+ * (the graph node was still materialized; the route lives elsewhere).
+ */
+
+import type { FnMap } from '@astrale-os/kernel-client'
+import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
+import type { AuthContext } from '@astrale-os/kernel-core'
+import type { Context, Hono } from 'hono'
+
+import {
+  isKernelErrorClassifiable,
+  KERNEL_ERROR_CODES,
+  kernelErrorHttpStatus,
+  type KernelErrorPayload,
+} from '@astrale-os/kernel-api'
+import {
+  isSubdomainOf,
+  matchHost,
+  compileHostMatcher,
+  parseUrlTemplate,
+  type FunctionBinding,
+  type AuthPolicy,
+} from '@astrale-os/kernel-api/routed'
+import { buildCorsHeaders, type CorsConfig } from '@astrale-os/kernel-server'
+
+import type { RemoteIdentityConfig } from '../auth/identity'
+import type { AnyRemoteFunctionDef } from '../define/remote-function'
+import type { ViewDef } from '../define/view'
+import type { CallRemoteFn } from '../dispatch/call-remote'
+import type { AuxIdentityMap } from '../dispatch/identity'
+
+import { resolveInboundAuth } from '../auth/resolve'
+import { runAuthorize } from '../dispatch/authorize'
+import { makeCallRemote } from '../dispatch/call-remote'
+import { SdkResultValidationError, SdkValidationError } from '../dispatch/errors'
+import { validateParams, validateResult } from '../dispatch/validate'
+
+export type AuxiliaryRoutesConfig<TDeps> = {
+  app: Hono
+  /** This worker's serving URL — used to filter bindings that point elsewhere. */
+  url: string
+  views?: Record<string, ViewDef<TDeps>>
+  viewBindings?: Record<string, FunctionBinding>
+  remoteFunctions?: Record<string, AnyRemoteFunctionDef>
+  remoteFunctionBindings?: Record<string, FunctionBinding>
+  deps: TDeps
+  /**
+   * Per-route identity configs (keyed by slug) — one entry per View and
+   * one per RemoteFunction. Build via `buildAuxIdentityMap(compiled, key, issuer)`
+   * from `sdk/src/dispatch/identity.ts`.
+   */
+  identities: AuxIdentityMap
+  /**
+   * CORS policy applied to every mounted route: per-route `app.options(...)`
+   * preflight and `Access-Control-Allow-*` headers on success + error
+   * responses. Required so callers (always `createRemoteServer`) keep the
+   * kernel-envelope and aux-route policies in sync.
+   */
+  cors: CorsConfig
+}
+
+export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>): void {
+  const {
+    app,
+    url,
+    views,
+    viewBindings,
+    remoteFunctions,
+    remoteFunctionBindings,
+    deps,
+    identities,
+    cors,
+  } = config
+
+  const workerHost = parseUrlTemplate(url).hostPattern
+  const corsHeaders = buildCorsHeaders(cors)
+
+  if (views && viewBindings) {
+    for (const [slug, def] of Object.entries(views)) {
+      const binding = viewBindings[slug]
+      if (!binding || !def.render) continue
+      const identity = requireAuxIdentity('view', slug, identities.views[slug])
+      mountEntry({
+        app,
+        binding,
+        workerHost,
+        defaultMethod: 'GET',
+        auth: def.auth,
+        identity,
+        corsHeaders,
+        // Views are transport-only (iframe HTML/redirect) — the kernel client
+        // built by `resolveInboundAuth` is intentionally NOT forwarded. Code
+        // inside the loaded iframe talks back to the kernel via the shell
+        // (WebSocket), not via this worker route.
+        run: async ({ c, params, auth }) => {
+          if (def.authorize) await runAuthorize(def.authorize, { c, params, auth, deps })
+          return def.render!({ c, params, auth, deps })
+        },
+      })
+    }
+  }
+
+  if (remoteFunctions && remoteFunctionBindings) {
+    for (const [slug, def] of Object.entries(remoteFunctions)) {
+      const binding = remoteFunctionBindings[slug]
+      if (!binding) continue
+      const identity = requireAuxIdentity('remote function', slug, identities.remoteFunctions[slug])
+      mountEntry({
+        app,
+        binding,
+        workerHost,
+        defaultMethod: 'POST',
+        auth: def.auth,
+        identity,
+        corsHeaders,
+        run: async ({ c, auth, kernel, callRemote }) => {
+          const rawBody: unknown = await c.req.json().catch(() => ({}))
+          const validation = validateParams(def.inputSchema, rawBody)
+          if (!validation.ok) {
+            throw new SdkValidationError(validation.issues as SdkValidationError['issues'])
+          }
+          const ctx = { params: validation.data, c, auth, deps, kernel, callRemote }
+          if (def.authorize) await runAuthorize(def.authorize, ctx)
+          const result = await def.execute(ctx)
+          const outValidation = validateResult(def.outputSchema, result)
+          if (!outValidation.ok) {
+            throw new SdkResultValidationError(
+              outValidation.issues as SdkResultValidationError['issues'],
+              def.ref,
+            )
+          }
+          return c.json({ result: outValidation.data })
+        },
+      })
+    }
+  }
+}
+
+// ── Internal ───────────────────────────────────────────────────────────────
+
+/**
+ * Every materialized aux callable must have an identity in the install-time
+ * `subs` claim — a missing one means the build pipeline passed a compiled
+ * domain that doesn't include this callable to `buildAuxIdentityMap()`.
+ */
+function requireAuxIdentity(
+  kind: 'view' | 'remote function',
+  slug: string,
+  identity: RemoteIdentityConfig | undefined,
+): RemoteIdentityConfig {
+  if (identity) return identity
+  throw new Error(
+    `mountAuxiliaryRoutes: no identity registered for ${kind} "${slug}". ` +
+      `Pass a compiled domain that includes this ${kind} to buildAuxIdentityMap().`,
+  )
+}
+
+type RunArgs = {
+  c: Context
+  params: Record<string, string>
+  auth: AuthContext | null
+  kernel: BoundClientSessionView<FnMap> | null
+  callRemote: CallRemoteFn
+}
+
+type MountEntryArgs = {
+  app: Hono
+  binding: FunctionBinding
+  workerHost: string
+  defaultMethod: 'GET' | 'POST'
+  run: (args: RunArgs) => Promise<Response>
+  auth?: AuthPolicy
+  identity: RemoteIdentityConfig
+  corsHeaders: Record<string, string>
+}
+
+const PLACEHOLDER_RE = /\{(\w+)([+*])?\}/g
+
+function mountEntry(args: MountEntryArgs): void {
+  const { app, binding, workerHost, defaultMethod, run, auth, identity, corsHeaders } = args
+
+  const remoteUrl = binding.remoteUrl
+  if (!remoteUrl) return
+
+  const parsed = parseUrlTemplate(remoteUrl)
+  if (parsed.hostPattern && !isSubdomainOf(parsed.hostPattern, workerHost)) return
+
+  const fullPath = joinPath(parsed.basePath, binding.route?.path ?? '')
+  const honoPath = toHonoPath(fullPath)
+  const httpMethod = binding.route?.method ?? defaultMethod
+  // `route.method` can be any `HttpMethod` (PUT/PATCH/DELETE/*), but only GET
+  // and POST are wired below. Fail loudly at mount time rather than silently
+  // registering no handler (which would 404 the real request while the OPTIONS
+  // preflight still reports the route exists).
+  if (httpMethod !== 'GET' && httpMethod !== 'POST') {
+    throw new Error(
+      `mountAuxiliaryRoutes: unsupported HTTP method "${httpMethod}" for route "${honoPath}". ` +
+        `Aux routes (views / remote functions) support only GET and POST.`,
+    )
+  }
+  // Local-dev requests target literal `localhost`, but bindings reference a
+  // logical host (`dist.localhost`) — so only enforce a Host-header match
+  // when the binding has actual placeholders to extract.
+  const hostMatcher =
+    parsed.hostPlaceholders.length > 0 ? compileHostMatcher(parsed.hostPattern) : null
+  const pathParamNames = collectPlaceholderNames(fullPath)
+
+  const handler = async (c: Context): Promise<Response> => {
+    // Apply CORS to every response. `c.json(...)` / `c.body(...)` pick up the
+    // headers via the Hono context; raw `Response` objects — a View's `render`
+    // return, and `errorResponse` in the catch — do NOT, so the final returned
+    // Response is also passed through `applyCorsToResponse`.
+    applyCorsToContext(c, corsHeaders)
+    try {
+      let hostParams: Record<string, string> = {}
+      if (hostMatcher) {
+        const match = matchHost(hostMatcher, c.req.header('host') ?? '')
+        if (!match) return c.notFound()
+        hostParams = match
+      }
+
+      const pathParams: Record<string, string> = {}
+      for (const name of pathParamNames) {
+        const value = c.req.param(name)
+        if (value !== undefined) pathParams[name] = decodeURIComponent(value)
+      }
+
+      const { auth: resolvedAuth, kernel } = await resolveInboundAuth(
+        stripBearerPrefix(c.req.header('authorization') ?? ''),
+        auth,
+        identity,
+      )
+
+      const response = await run({
+        c,
+        params: { ...hostParams, ...pathParams },
+        auth: resolvedAuth,
+        kernel,
+        callRemote: makeCallRemote(kernel),
+      })
+      return applyCorsToResponse(response, corsHeaders)
+    } catch (err) {
+      return applyCorsToResponse(errorResponse(err), corsHeaders)
+    }
+  }
+
+  if (httpMethod === 'GET') app.get(honoPath, handler)
+  else if (httpMethod === 'POST') app.post(honoPath, handler)
+
+  // Per-route preflight — mirrors `createKernelApp`'s per-route
+  // `app.options(...)` pattern (kernel/server/app/create.ts:112,145). Avoid
+  // a wildcard `app.options('*', ...)`: it would intercept the kernel
+  // envelope's own preflights mounted later on this same Hono instance.
+  app.options(honoPath, (c) => {
+    applyCorsToContext(c, corsHeaders)
+    return c.body(null, 204)
+  })
+}
+
+function applyCorsToContext(c: Context, headers: Record<string, string>): void {
+  for (const [name, value] of Object.entries(headers)) c.header(name, value)
+}
+
+function applyCorsToResponse(response: Response, headers: Record<string, string>): Response {
+  try {
+    for (const [name, value] of Object.entries(headers)) response.headers.set(name, value)
+    return response
+  } catch {
+    // Some Responses have immutable headers — notably `Response.redirect(...)`,
+    // which a View's `render` is documented to return. Rebuild with a mutable
+    // header copy so CORS still applies (status / body / location preserved).
+    const merged = new Headers(response.headers)
+    for (const [name, value] of Object.entries(headers)) merged.set(name, value)
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: merged,
+    })
+  }
+}
+
+function collectPlaceholderNames(path: string): string[] {
+  return [...path.matchAll(PLACEHOLDER_RE)].map((m) => m[1]!)
+}
+
+/**
+ * Serialize an error as the canonical kernel error envelope
+ * `{ error: { code, message, data } }` with the matching HTTP status. This is
+ * the exact shape the routed client (`kernel-client` HttpRoutedTransport.
+ * decodeError) parses — it routes on `error.code` and reads `error.data` for
+ * field-level detail (a flat `{ error: '<string>' }` body silently degrades to
+ * a generic INTERNAL_ERROR client-side). Every SDK error class (AuthMissingError,
+ * SdkValidationError, SdkResultValidationError, AuthorizationDeniedError, …) plus
+ * the kernel-core errors `resolveInboundAuth` rethrows all implement
+ * `toKernelErrorPayload`, so one branch covers them; only a raw non-classifiable
+ * Error falls back to 500.
+ */
+function errorResponse(err: unknown): Response {
+  const payload: KernelErrorPayload = isKernelErrorClassifiable(err)
+    ? err.toKernelErrorPayload()
+    : {
+        code: KERNEL_ERROR_CODES.INTERNAL_ERROR,
+        message: err instanceof Error ? err.message : 'Internal error',
+      }
+  return Response.json({ error: payload }, { status: kernelErrorHttpStatus(payload.code) })
+}
+
+function joinPath(a: string, b: string): string {
+  if (!b) return a
+  if (!a) return b
+  const left = a.endsWith('/') ? a.slice(0, -1) : a
+  const right = b.startsWith('/') ? b : `/${b}`
+  return `${left}${right}` || '/'
+}
+
+/** Convert `/foo/{id}` / `/{name+}` / `/{name*}` to Hono syntax. */
+function toHonoPath(path: string): string {
+  return path
+    .replace(/\{(\w+)\+\}/g, ':$1{.+}')
+    .replace(/\{(\w+)\*\}/g, ':$1{.*}')
+    .replace(/\{(\w+)\}/g, ':$1')
+}
+
+function stripBearerPrefix(value: string): string {
+  return value.trim().replace(/^Bearer\s+/i, '')
+}

package/src/server/config.ts

@@ -0,0 +1,85 @@
+/**
+ * `RemoteServerConfig` — input shape for `createRemoteServer`.
+ *
+ * Identity is per-function: `iss` = the worker's serving URL (`config.url`),
+ * `sub` = the function path, signed on each dispatch. No single `subject`.
+ */
+
+import type { CorsConfig, WsAdapter } from '@astrale-os/kernel-server'
+import type { Context } from 'hono'
+import type { Hono } from 'hono'
+
+import type { RemoteDomain } from '../domain/define'
+
+export type RemoteServerConfig<TDeps> = {
+  /** Domain produced by `defineRemoteDomain(...)`. */
+  domain: RemoteDomain
+  /** Dependency container passed to every handler as `ctx.deps`. */
+  deps: TDeps
+  /**
+   * Server URL — the serving location AND the worker's JWT issuer identity
+   * (`iss`), decoupled from the addressing `origin` slug.
+   *
+   * The server's public key is published at `<url>/.well-known/jwks.json`
+   * so downstream verifiers can validate credentials signed by this server.
+   */
+  url: string
+  /** Private key used to sign outbound credentials. Public form is exposed via JWKS. */
+  privateKey: JsonWebKey
+  /** Allowed transports. `'http'` is mandatory. `'ws'` is opt-in. Defaults to `['http']`. */
+  transports?: readonly ('http' | 'ws')[]
+  /**
+   * Runtime-specific WS adapter (from `hono/bun`, `@hono/node-ws`, `hono/deno`).
+   * Required when `transports` includes `'ws'`.
+   */
+  ws?: WsAdapter
+  /** CORS configuration. Defaults to `{ origin: '*' }`. */
+  cors?: CorsConfig
+  /** Optional health endpoint path (defaults to `/health`; `false` disables). */
+  health?: string | false
+  /** Pre-existing Hono app to attach to (for nesting the SDK under a parent router). */
+  app?: Hono
+  /**
+   * Provenance stamped onto the auto-mounted `/meta` endpoint. Typically
+   * injected at build time by the bundler so downstream tooling can detect
+   * version drift between deployed server and expected schema.
+   */
+  meta?: {
+    sdkCommit?: string
+    schemaHash?: string
+    domainName?: string
+  }
+  /**
+   * Typed colon-path to a callable the installing kernel calls ONCE as the
+   * system identity, immediately after the domain installs. Use it to seed
+   * nodes and self-grant. Must be a semantic domain path under this domain's
+   * own origin (`/:origin:class.X:seed` / `/:origin:interface.Ops:seed`) — the
+   * kernel's origin guard refuses absolute tree paths, which cannot prove
+   * their origin from the string alone. Returned verbatim in the install
+   * bundle (a routing hint — the signed `graph_hash` already constrains what
+   * the callable can be).
+   *
+   * Example: `/:crm.acme.dev:class.Note:seed`
+   */
+  postInstall?: string
+  /**
+   * Cross-domain dependencies by origin. Returned in the install bundle; the
+   * kernel verifies each origin is already present on the instance before
+   * installing, and refuses with a clear error if one is missing.
+   */
+  requires?: readonly string[]
+  /**
+   * Optional private install hook. Throw to deny the install request.
+   * The public URL install contract still receives no caller kernel
+   * credential; private installs use the bearer token only.
+   */
+  install?: {
+    authorize?: (args: {
+      c: Context
+      token?: string
+      kernelIssuer: string
+      nonce: string
+      deps: TDeps
+    }) => void | Promise<void>
+  }
+}

package/src/server/create.ts

@@ -0,0 +1,249 @@
+/**
+ * `createRemoteServer` — the SDK's entry point for running a remote domain.
+ *
+ * Identity is per-function: the dispatcher signs `iss` = the worker's serving
+ * URL (`effectiveIssuer`, decoupled from the addressing `origin`) and `sub` =
+ * the origin-addressed function path on each dispatch.
+ *
+ * Composes:
+ *   methods             ← Map keyed by BoundMethod.ref (built by dispatch/resolve)
+ *   effectiveIssuer     ← config.issuer ?? config.url
+ *   dispatcher          ← SdkDispatcher(compiled, methods, deps, privateKey)
+ *   jwks                ← derivePublicJwk(privateKey), keyed by effectiveIssuer
+ *   /meta               ← provenance endpoint (sdkCommit, schemaHash, domainName)
+ *   auxiliary routes    ← view / remote-function handlers from defineRemoteDomain
+ *   app                 ← createKernelApp(dispatcher, contracts, host, jwks, transports, ...)
+ *   start               ← startNodeServer(app, port)
+ */
+
+import type { JwksKeys } from '@astrale-os/kernel-server'
+
+import { deriveAllowedAlgorithms } from '@astrale-os/kernel-core'
+import {
+  collectFunctionSubs,
+  domainInstallRequestSchema,
+  hashInstallGraph,
+} from '@astrale-os/kernel-core/domain'
+import { createKernelApp } from '@astrale-os/kernel-server'
+import { Hono } from 'hono'
+import { importJWK, SignJWT } from 'jose'
+
+import type { ViewDef } from '../define'
+import type { RemoteServerConfig } from './config'
+import type { RemoteServer, RemoteServerHandle } from './handle'
+
+import { MetaSchema } from '../deploy/meta'
+import { SdkDispatcher } from '../dispatch/dispatcher'
+import { buildAuxIdentityMap } from '../dispatch/identity'
+import { buildMethodIndex } from '../dispatch/resolve'
+import { buildInstallGraph, buildInstallGraphHash } from '../domain/build-spec'
+import { toSdkContract } from '../domain/contract'
+import { materializeRemoteDomain } from '../domain/define'
+import { mountAuxiliaryRoutes } from './auxiliary-routes'
+import { derivePublicJwk } from './jwks'
+import { canonicalizeServingUrl } from './serving-url'
+
+export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): RemoteServer {
+  const methods = buildMethodIndex(config.domain.methods)
+  // The worker's identity (`iss`) is its full serving URL (base path included,
+  // trailing slash stripped) — decoupled from the addressing `origin` slug. One
+  // canonical value drives outbound signing, the JWKS issuer, `/meta`, and the
+  // install credential. Must equal the URL the kernel fetched the domain at.
+  const iss = canonicalizeServingUrl(config.url)
+
+  // Re-materialize the domain with the real serving url (`iss`) so the aux
+  // View/Function `binding.remoteUrl` resolve to this host — the define-time
+  // placeholder is discarded. `compiled`/`auxiliary` drive everything below;
+  // `iss` is the single source for both bindings and identity.
+  const { compiled, auxiliary } = materializeRemoteDomain(config.domain, iss)
+
+  const dispatcher = new SdkDispatcher<TDeps>({
+    compiled,
+    methods,
+    deps: config.deps,
+    privateKey: config.privateKey,
+    issuer: iss,
+    // The canonicalized serving URL, NOT the raw config.url: `ctx.url` is
+    // documented as the worker's `iss` identity, so the two must be one value.
+    url: iss,
+  })
+
+  const publicJwk = derivePublicJwk(config.privateKey)
+  const jwks: JwksKeys = {
+    issuer: iss,
+    loadOwnKeys: async () => [publicJwk],
+  }
+
+  // `/meta`'s `schemaHash` is computed from the LIVE domain graph (lazy +
+  // cached). `hashInstallGraph` is id-independent/deterministic, so an
+  // independent build (a deploy script) produces the SAME hash — `deployCheck`
+  // can compare its expected value against this and detect genuine schema drift.
+  // An explicit `config.meta.schemaHash` still wins as an override for
+  // offline/pinned spec producers, but normal deploys omit it.
+  let cachedSchemaHash: Promise<string> | null = null
+  const resolveSchemaHash = (): Promise<string> =>
+    config.meta?.schemaHash !== undefined
+      ? Promise.resolve(config.meta.schemaHash)
+      : (cachedSchemaHash ??= buildInstallGraphHash(config.domain, iss))
+
+  // Register `/meta` on the host app before `createKernelApp` mounts its
+  // catch-all routes so the verbatim path wins.
+  const hostApp = config.app ?? new Hono()
+  const metaBase = {
+    iss,
+    sdkCommit: config.meta?.sdkCommit,
+    domainName: config.meta?.domainName ?? compiled.$.origin,
+  }
+  hostApp.get('/meta', async (c) =>
+    c.json(MetaSchema.parse({ ...metaBase, schemaHash: await resolveSchemaHash() })),
+  )
+  hostApp.post('/_astrale/install-domain', async (c) => {
+    const parsed = domainInstallRequestSchema.safeParse(await c.req.json().catch(() => null))
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid install request', issues: parsed.error.issues }, 400)
+    }
+
+    const token = bearerToken(c.req.header('authorization'))
+    try {
+      await config.install?.authorize?.({
+        c,
+        ...(token ? { token } : {}),
+        kernelIssuer: parsed.data.kernelIssuer,
+        nonce: parsed.data.nonce,
+        deps: config.deps,
+      })
+    } catch (err) {
+      return c.json({ error: 'Install denied', message: (err as Error).message }, 403)
+    }
+
+    // Build the install graph. `buildInstallGraph` re-materializes the domain
+    // with the serving url (`iss`), so every `binding.remoteUrl` points at this
+    // host — the same single value as the credential's `iss` below. The kernel
+    // hashes exactly this graph; no install-time rewrite.
+    const graph = buildInstallGraph(config.domain, iss)
+    const graphHash = await hashInstallGraph(graph)
+    const origin = compiled.$.origin
+    // `postInstall` + `requires` ride in BOTH the signed credential claims and
+    // the bundle body, and the kernel rejects any bundle field that disagrees
+    // with its signed claim — so derive them once and reuse for both.
+    const bundleExtras = {
+      ...(config.postInstall ? { postInstall: config.postInstall } : {}),
+      ...(config.requires && config.requires.length > 0 ? { requires: config.requires } : {}),
+    }
+    // The credential's `iss` is the worker's serving URL (`iss`, computed above)
+    // — the kernel pins it to the URL it fetched the domain at and verifies this
+    // credential against that issuer's JWKS.
+    const credential = await signInstallCredential({
+      privateKey: config.privateKey,
+      issuer: iss,
+      audience: parsed.data.kernelIssuer,
+      nonce: parsed.data.nonce,
+      graphHash,
+      subs: collectFunctionSubs(compiled),
+      ...bundleExtras,
+    })
+
+    return c.json({
+      origin,
+      graph,
+      identity: { credential },
+      ...bundleExtras,
+    })
+  })
+
+  // Resolved once and shared between the kernel envelope (createKernelApp) and
+  // the aux routes (mountAuxiliaryRoutes) so both honor the same policy.
+  const cors = config.cors ?? { origin: '*' }
+
+  // Worker-side wires for defineView / defineRemoteFunction. Mounted before
+  // the kernel catch-all. Each aux route gets its own per-slug identity
+  // (issuer + key + the aux node's AbsolutePath as subject) so outbound
+  // `kernel.call(...)` from a handler signs with that path — matching the
+  // identity the install-time `subs` claim registered for the node, the
+  // same way Methods work.
+  if (auxiliary) {
+    const auxIdentities = buildAuxIdentityMap(compiled, config.privateKey, iss)
+    mountAuxiliaryRoutes<TDeps>({
+      app: hostApp,
+      url: auxiliary.url,
+      // oxlint-disable-next-line no-explicit-any
+      views: config.domain.views as Record<string, ViewDef<TDeps>> | undefined,
+      viewBindings: auxiliary.viewBindings,
+      remoteFunctions: config.domain.remoteFunctions,
+      remoteFunctionBindings: auxiliary.remoteFunctionBindings,
+      deps: config.deps,
+      identities: auxIdentities,
+      cors,
+    })
+  }
+
+  const { app } = createKernelApp({
+    kernel: dispatcher,
+    domain: config.domain.methods.map(toSdkContract),
+    host: { url: config.url },
+    jwks,
+    transports: config.transports,
+    cors,
+    health: config.health,
+    app: hostApp,
+    ws: config.ws,
+  })
+
+  return {
+    app,
+    // The canonical serving URL = the worker's `iss` identity. Exposed so a
+    // worker that also seeds `Identity.iss` on graph nodes (e.g. recruitment's
+    // self-seed) stamps the SAME canonical value the dispatcher signs with —
+    // never the raw env.WORKER_URL — so the kernel's exact-match lookup resolves.
+    iss,
+    async start(port?: number): Promise<RemoteServerHandle> {
+      const nodeStartModule = './start'
+      const { startNodeServer } = await import(nodeStartModule)
+      return startNodeServer(app, port)
+    },
+  }
+}
+
+function bearerToken(header: string | undefined): string | undefined {
+  if (!header) return undefined
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim())
+  return match?.[1]
+}
+
+async function signInstallCredential(args: {
+  privateKey: JsonWebKey
+  issuer: string
+  audience: string
+  nonce: string
+  graphHash: string
+  subs: string[]
+  postInstall?: string
+  requires?: readonly string[]
+}): Promise<string> {
+  const alg = deriveAllowedAlgorithms(args.privateKey)[0]
+  if (!alg) {
+    throw new Error(
+      `createRemoteServer: cannot derive install signing algorithm from JWK (kty=${args.privateKey.kty}).`,
+    )
+  }
+  const kid = (args.privateKey as unknown as Record<string, unknown>).kid
+  const header = typeof kid === 'string' ? { alg, kid } : { alg }
+  const key = await importJWK(args.privateKey, alg)
+
+  // `postInstall` + `requires` are signed (not just carried in the bundle) so a
+  // MITM can't retarget the system-authority hook or forge dependencies
+  return new SignJWT({
+    subs: args.subs,
+    nonce: args.nonce,
+    graph_hash: args.graphHash,
+    ...(args.postInstall ? { postInstall: args.postInstall } : {}),
+    ...(args.requires ? { requires: args.requires } : {}),
+  })
+    .setProtectedHeader(header)
+    .setIssuer(args.issuer)
+    .setSubject(args.issuer)
+    .setAudience(args.audience)
+    .setIssuedAt()
+    .setExpirationTime('10m')
+    .sign(key)
+}