@astrale-os/sdk 0.1.0

package/src/server/handle.ts

@@ -0,0 +1,37 @@
+/**
+ * `RemoteServer` and `RemoteServerHandle` — output shapes for the SDK server.
+ *
+ * `RemoteServer` is what `createRemoteServer` returns: the assembled Hono
+ * app plus a Node convenience helper. `RemoteServerHandle` is what `start()`
+ * resolves to: the bound port and a `close()` function for graceful shutdown.
+ */
+
+import type { Hono } from 'hono'
+
+export type RemoteServer = {
+  /**
+   * The assembled Hono app. Use `app.fetch` for any runtime
+   * (Bun, Deno, Cloudflare Workers, or Node via `@hono/node-server`).
+   */
+  app: Hono
+  /**
+   * The worker's canonical serving URL — its `iss` identity (full URL, trailing
+   * slash stripped, base path preserved). The single value the dispatcher signs
+   * with and the kernel pins. Read it to seed `Identity.iss` on graph nodes so
+   * the seeded value matches the signing issuer (never re-derive from a raw env).
+   */
+  iss: string
+  /**
+   * Convenience helper: start a Node HTTP server on the given port using
+   * `@hono/node-server` (loaded via dynamic import). For other runtimes,
+   * use `app.fetch` directly.
+   */
+  start: (port?: number) => Promise<RemoteServerHandle>
+}
+
+export type RemoteServerHandle = {
+  /** The port the server is listening on (resolved even if `port: 0` was requested). */
+  port: number
+  /** Stop the server and release the port. */
+  close: () => Promise<void>
+}

package/src/server/index.ts

@@ -0,0 +1,10 @@
+export { createRemoteServer } from './create'
+export type { RemoteServerConfig } from './config'
+export type { RemoteServer, RemoteServerHandle } from './handle'
+export { derivePublicJwk } from './jwks'
+export { requireEnv } from './require-env'
+export { canonicalizeServingUrl } from './serving-url'
+export { createWorkerEntry } from './worker-entry'
+export type { WorkerEntry, WorkerEntryConfig } from './worker-entry'
+export { workerMeta } from './worker-meta'
+export { startNodeServer } from './start'

package/src/server/jwks.ts

@@ -0,0 +1,18 @@
+/**
+ * Derive a public JWK from a private one.
+ *
+ * Strips the private components for both EC keys (drops `d`) and RSA keys
+ * (drops `d`, `p`, `q`, `dp`, `dq`, `qi`, and `oth` — the additional-primes
+ * array on multi-prime RSA keys). The result is safe to publish at
+ * `<url>/.well-known/jwks.json` so downstream verifiers can validate
+ * signatures the server produced.
+ */
+
+export function derivePublicJwk(privateKey: JsonWebKey): Record<string, unknown> {
+  // oxlint-disable-next-line no-unused-vars
+  const { d, p, q, dp, dq, qi, oth, ...publicJwk } = privateKey as unknown as Record<
+    string,
+    unknown
+  >
+  return publicJwk
+}

package/src/server/require-env.ts

@@ -0,0 +1,19 @@
+/**
+ * Read a string-typed env var (process.env on Node, the Worker `env` binding
+ * on Cloudflare) and throw a clear error if it is missing or empty.
+ *
+ * Use this for **identity-bearing** values (issuer, baseDomain, audience,
+ * worker URL) where a guessed default silently mints wrong JWTs or bakes
+ * wrong refs into persisted artifacts. The conventional `?? 'literal'`
+ * fallback is the anti-pattern this exists to replace.
+ *
+ * In local dev these live in each domain worker's `worker/.dev.vars` (read
+ * natively by `wrangler dev`), so this throw never fires in a properly-prepared
+ * dev environment — only when wiring is genuinely missing.
+ */
+export function requireEnv(env: unknown, name: string, hint?: string): string {
+  const v = (env as Record<string, unknown> | null | undefined)?.[name]
+  if (typeof v === 'string' && v.length > 0) return v
+  const help = hint ? ` (${hint})` : ''
+  throw new Error(`Missing required env var: ${name}${help}`)
+}

package/src/server/serving-url.ts

@@ -0,0 +1,28 @@
+/**
+ * Canonicalize a worker's serving URL into its `iss` identity.
+ *
+ * Returns the full URL with trailing slash(es) stripped — the base path is
+ * preserved (an issuer may carry a non-empty path, like `…/kernel/host`). This
+ * is the single canonical form used for outbound signing, the JWKS issuer,
+ * `/meta`, the install credential, and any `Identity.iss` a domain seeds, so the
+ * value a worker SIGNS always matches the value the kernel LOOKS UP (the kernel
+ * canonicalizes the verified `iss` the same way and does an exact-match lookup).
+ *
+ * Throws if `url` is not a parseable absolute URL.
+ */
+// INVARIANT (cross-repo): issuer PRODUCERS must strip trailing path slashes
+// BEFORE a value becomes an iss. kernel-core's `normalizeIssuerId` only strips
+// a lone trailing slash on an EMPTY path, so `https://x/base/` and
+// `https://x/base` are distinct issuer identities to the kernel — this
+// function and the kernel's `installSourceBase` both pre-strip with the same
+// rule so the two sides can never mint diverging identities for one worker.
+export function canonicalizeServingUrl(url: string): string {
+  try {
+    return new URL(url).href.replace(/\/+$/, '')
+  } catch {
+    throw new Error(
+      `canonicalizeServingUrl: expected a full URL (got "${url}") — ` +
+        'it is the worker serving URL and its JWT issuer identity.',
+    )
+  }
+}

package/src/server/start.ts

@@ -0,0 +1,37 @@
+/**
+ * Node HTTP convenience starter.
+ *
+ * Dynamically imports `@hono/node-server` so the SDK stays runtime-agnostic
+ * — only Node consumers actually pull in the dep. For Bun / Deno /
+ * Cloudflare, consumers go through `server.app.fetch` directly.
+ */
+
+import type { Hono } from 'hono'
+
+import type { RemoteServerHandle } from './handle'
+
+export async function startNodeServer(app: Hono, port = 3000): Promise<RemoteServerHandle> {
+  const { serve } = await import('@hono/node-server')
+  // oxlint-disable-next-line no-explicit-any
+  const server = serve({ fetch: app.fetch, port }) as any
+
+  await new Promise<void>((resolve, reject) => {
+    if (server.listening) return resolve()
+    server.once('listening', () => resolve())
+    // Without this, a bind failure (e.g. EADDRINUSE on a busy port) emits
+    // `'error'` and never `'listening'`, leaving the Promise — and startup —
+    // hung forever with no diagnostic.
+    server.once('error', (err: Error) => reject(err))
+  })
+
+  const address = server.address() as { port: number; address: string } | null
+  const actualPort = address?.port ?? port
+
+  return {
+    port: actualPort,
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((err: Error | null) => (err ? reject(err) : resolve()))
+      }),
+  }
+}

package/src/server/worker-entry.ts

@@ -0,0 +1,122 @@
+/**
+ * `createWorkerEntry` — the shared worker `fetch` plumbing every Astrale domain
+ * worker (and the cloudflare adapter's codegen) needs, so it lives in ONE place
+ * instead of being copy-pasted per worker:
+ *
+ *   • resolve the serving URL (== `iss`), canonicalize it (so the value matches
+ *     what `createRemoteServer` signs with and the kernel pins), and cache the
+ *     built app per distinct URL;
+ *   • optional self-binding routing: when a `SELF` service binding is provided,
+ *     route same-host subrequests (e.g. `ctx.callRemote` back into this domain)
+ *     through it — Cloudflare forbids a Worker fetching its own hostname. This is
+ *     the ONLY reason a `globalThis.fetch` override is installed, and only when a
+ *     `selfBinding` is configured;
+ *   • optional SPA hook (e.g. `/ui/*` served from an `ASSETS` binding).
+ *
+ * The worker's OWN JWKS (`<url>/.well-known/jwks.json`) is served as a normal
+ * route by `createRemoteServer`; the verifier resolves a self-issued credential
+ * from the in-memory key (see `auth/verify.ts`), so no self-fetch shim is needed.
+ *
+ * The worker file is then just schema + methods + a `build(url, env)` callback.
+ */
+
+import type { RemoteServerConfig } from './config'
+
+import { createRemoteServer } from './create'
+import { requireEnv } from './require-env'
+import { canonicalizeServingUrl } from './serving-url'
+
+type Fetcher = { fetch(request: Request): Response | Promise<Response> }
+type App = { fetch(request: Request): Response | Promise<Response> }
+
+export interface WorkerEntryConfig<TDeps> {
+  /**
+   * Build the `createRemoteServer` config for the resolved serving `url`. Called
+   * once per distinct URL (the resulting app is cached), with the same `env` the
+   * request carries — so it can read additional bindings (e.g. a base domain).
+   */
+  build: (url: string, env: TDeps) => RemoteServerConfig<TDeps>
+  /**
+   * Resolve the raw serving URL from `env` (+ the per-request origin, for workers
+   * that fall back to the request host). Defaults to the `WORKER_URL` env var.
+   * The result is always canonicalized before use.
+   */
+  resolveUrl?: (env: TDeps, requestOrigin: string) => string
+  /** Optional: the `SELF` service binding used to route same-host subrequests. */
+  selfBinding?: (env: TDeps) => Fetcher | null | undefined
+  /**
+   * Optional: handle a request before it reaches the kernel app — e.g. serve a
+   * SPA under `/ui/*` or a same-origin `/api/*` endpoint the view calls. Return
+   * a `Response` to short-circuit, or `undefined` to fall through to the domain
+   * dispatch.
+   */
+  before?: (
+    env: TDeps,
+    url: URL,
+    request: Request,
+  ) => Response | undefined | Promise<Response | undefined>
+  /**
+   * Optional: transform the request on the fall-through path, just before it
+   * reaches the kernel app (e.g. rewrite the hostname for wildcard-subdomain
+   * routing). Not applied when `before` short-circuits.
+   */
+  rewriteRequest?: (env: TDeps, request: Request) => Request
+}
+
+export interface WorkerEntry<TDeps> {
+  fetch(request: Request, env: TDeps): Response | Promise<Response>
+}
+
+export function createWorkerEntry<TDeps>(config: WorkerEntryConfig<TDeps>): WorkerEntry<TDeps> {
+  let cache: { url: string; origin: string; app: App } | null = null
+  let self: Fetcher | null = null
+
+  function getApp(url: string, env: TDeps): App {
+    if (cache && cache.url === url) return cache.app
+    const { app } = createRemoteServer<TDeps>(config.build(url, env))
+    cache = { url, origin: new URL(url).origin, app }
+    return app
+  }
+
+  // A Worker can't fetch its own hostname. When a SELF service binding is
+  // configured, route same-host subrequests (e.g. `ctx.callRemote` back into
+  // this domain) through it. This is the only reason to override
+  // `globalThis.fetch` — workers without a `selfBinding` get no global mutation.
+  // (A self-issued credential's JWKS is resolved in-memory by the verifier, not
+  // fetched — see `auth/verify.ts` — so no self-JWKS interception is needed.)
+  if (config.selfBinding) {
+    const originalFetch = globalThis.fetch
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      if (cache && self) {
+        const href =
+          typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+        try {
+          if (new URL(href).origin === cache.origin) return self.fetch(new Request(input, init))
+        } catch {
+          // non-absolute URL — fall through to the original fetch
+        }
+      }
+      return originalFetch(input, init)
+    }) as typeof fetch
+  }
+
+  return {
+    async fetch(request: Request, env: TDeps): Promise<Response> {
+      if (config.selfBinding) self ??= config.selfBinding(env) ?? null
+      // Only parse the request URL when a hook actually needs it.
+      const requestUrl = config.before || config.resolveUrl ? new URL(request.url) : null
+      if (config.before && requestUrl) {
+        // Await so an async `before` that resolves to `undefined` falls through
+        // (a returned Promise<undefined> would otherwise be sent as the response).
+        const handled = await config.before(env, requestUrl, request)
+        if (handled !== undefined) return handled
+      }
+      const raw = config.resolveUrl
+        ? config.resolveUrl(env, requestUrl!.origin)
+        : requireEnv(env, 'WORKER_URL', "the worker's public serving URL (its iss identity)")
+      const url = canonicalizeServingUrl(raw)
+      const dispatched = config.rewriteRequest ? config.rewriteRequest(env, request) : request
+      return getApp(url, env).fetch(dispatched)
+    },
+  }
+}

package/src/server/worker-meta.ts

@@ -0,0 +1,25 @@
+/**
+ * Build the `/meta` provenance block for a domain worker: the build-injected
+ * `SDK_COMMIT` / `SCHEMA_HASH` globals plus the domain name. A field is omitted
+ * when its global isn't defined.
+ *
+ * `SDK_COMMIT` / `SCHEMA_HASH` are `--define`'d into the worker bundle at build
+ * time; the bundler applies that text replacement to this inlined helper too, so
+ * reading them here behaves exactly as the per-worker block this replaces.
+ */
+declare const SDK_COMMIT: string | undefined
+declare const SCHEMA_HASH: string | undefined
+
+export function workerMeta(domainName: string): {
+  sdkCommit?: string
+  schemaHash?: string
+  domainName: string
+} {
+  const sdkCommit = typeof SDK_COMMIT === 'string' ? SDK_COMMIT : undefined
+  const schemaHash = typeof SCHEMA_HASH === 'string' ? SCHEMA_HASH : undefined
+  return {
+    ...(sdkCommit ? { sdkCommit } : {}),
+    ...(schemaHash ? { schemaHash } : {}),
+    domainName,
+  }
+}