@astrale-os/sdk 0.4.18 → 0.5.0-beta.1

package/src/server/config.ts

@@ -1,85 +0,0 @@
-/**
- * `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.js'
-
-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

@@ -1,210 +0,0 @@
-/**
- * Remote-domain server entry point. The worker serving URL is the issuer; each
- * method/view/function signs with its own semantic subject.
- */
-
-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/index.js'
-import type { RemoteServerConfig } from './config.js'
-import type { RemoteServer, RemoteServerHandle } from './handle.js'
-
-import { MetaSchema } from '../deploy/meta.js'
-import { SdkDispatcher } from '../dispatch/dispatcher.js'
-import { buildAuxIdentityMap } from '../dispatch/identity.js'
-import { buildMethodIndex } from '../dispatch/resolve.js'
-import { buildInstallGraph, buildInstallGraphHash } from '../domain/build-spec.js'
-import { toSdkContract } from '../domain/contract.js'
-import { materializeRemoteDomain } from '../domain/define.js'
-import { mountAuxiliaryRoutes } from './auxiliary-routes.js'
-import { derivePublicJwk } from './jwks.js'
-import { canonicalizeServingUrl } from './serving-url.js'
-
-export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): RemoteServer {
-  const methods = buildMethodIndex(config.domain.methods)
-  // Canonical serving URL drives signing, JWKS, /meta, and install credentials.
-  const iss = canonicalizeServingUrl(config.url)
-
-  // Stamp aux bindings against the same URL used as issuer.
-  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.env.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],
-  }
-
-  // Normal /meta schemaHash is the deterministic install-graph hash; explicit overrides win.
-  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,
-    ...(config.domain.manifest ? { manifest: config.domain.manifest } : {}),
-  }
-  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)
-    }
-
-    // The signed graph is built for this serving URL; the kernel verifies it as-is.
-    const graph = buildInstallGraph(config.domain, iss)
-    const graphHash = await hashInstallGraph(graph)
-    const origin = compiled.$.origin
-    // Signed claims and bundle fields must agree exactly.
-    const bundleExtras = {
-      ...(config.postInstall ? { postInstall: config.postInstall } : {}),
-      ...(config.requires && config.requires.length > 0 ? { requires: config.requires } : {}),
-    }
-    // Install credential issuer is the serving URL the kernel fetched.
-    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: '*' }
-
-  // Aux routes mount before the kernel catch-all and sign with their member subjects.
-  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({
-    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,
-    // Expose the canonical issuer, not the raw env URL, for graph identity stamping.
-    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 copied into the bundle.
-  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)
-}

package/src/server/domain-entry.ts

@@ -1,125 +0,0 @@
-/**
- * `domainWorkerEntry` — the one-call worker entry for a standalone domain.
- *
- * It folds the three steps every hand-rolled worker used to wire by hand —
- * compile the runtime domain (`defineRemoteDomain`), build the server
- * (`createRemoteServer`), and wrap it in the shared fetch plumbing
- * (`createWorkerEntry`) — into a single declaration. The author passes the raw
- * modules (`schema` / `methods` / `views` / `functions`) plus the identity and
- * deploy bits; the helper does the rest. This is what the cloudflare adapter's
- * codegen emits, and the recommended surface for a hand-rolled worker.
- *
- * Drop down to `createWorkerEntry` + `defineRemoteDomain` (from
- * `@astrale-os/sdk/domain`) only when the worker needs something this config
- * can't express — e.g. a serving-URL-dependent domain build (views stamped with
- * the live url) or a globally-injected signing key resolved per request.
- */
-
-import type { Core, Schema } from '@astrale-os/kernel-dsl'
-import type { Hono } from 'hono'
-
-import type { DomainManifest } from '../config/define-domain.js'
-import type { AnyRemoteFunctionDef, ViewDef } from '../define/index.js'
-import type { SchemaMethodsImpl } from '../method/index.js'
-import type { RemoteServerConfig } from './config.js'
-import type { WorkerEntry, WorkerEntryConfig } from './worker-entry.js'
-
-import { defineRemoteDomain } from '../domain/index.js'
-import { createWorkerEntry } from './worker-entry.js'
-
-export interface DomainWorkerEntryConfig<S extends Schema, TEnv, TDeps> {
-  /** The domain schema. */
-  schema: S
-  /** Method implementations, typed against `schema` under `TDeps`. */
-  methods: SchemaMethodsImpl<S, TDeps>
-  /** Optional Core override (extra genesis nodes / wiring). */
-  core?: Core<S>
-  /** Views (iframe-mountable UIs) keyed by slug. */
-  views?: Record<string, ViewDef<TDeps>>
-  /** Standalone Functions (callables not bound to a class) keyed by slug. */
-  functions?: Record<string, AnyRemoteFunctionDef>
-
-  /**
-   * The worker's signing key (its `iss` identity material). A static JWK, or a
-   * resolver from `env` for keys injected as a secret / shared globally.
-   */
-  privateKey: JsonWebKey | ((env: TEnv) => JsonWebKey)
-  /** Cross-domain deps by origin — verified present at install. */
-  requires?: readonly string[]
-  /** Typed colon-path the kernel calls once as __SYSTEM__ after install. */
-  postInstall?: string
-  /**
-   * Physical tree path for the Domain node (absolute, e.g. `/domains/acme`);
-   * default `/domains/<origin>`. Rides in on the `...domain` spread from
-   * `defineDomain`; declared here so it is captured (not silently dropped like a
-   * spread prop absent from this type) and forwarded to `defineRemoteDomain`.
-   */
-  path?: string
-  /** Provenance stamped on `/meta`. */
-  meta?: RemoteServerConfig<TDeps>['meta']
-  /** Presentation metadata (logo / initial view) stamped on `/meta`. */
-  manifest?: DomainManifest
-
-  /**
-   * Map the worker `env` to the handler dependency container. Defaults to
-   * passing `env` straight through (the common case where handlers read
-   * bindings directly).
-   */
-  deps?: (env: TEnv, url: string) => TDeps
-  /** Optional pre-built host Hono app (CORS / logging / extra routes). */
-  app?: (env: TEnv) => Hono
-
-  // ── createWorkerEntry plumbing (passed through verbatim) ──────────────────
-  resolveUrl?: WorkerEntryConfig<TEnv>['resolveUrl']
-  selfBinding?: WorkerEntryConfig<TEnv>['selfBinding']
-  routeSubrequest?: WorkerEntryConfig<TEnv>['routeSubrequest']
-  before?: WorkerEntryConfig<TEnv>['before']
-  rewriteRequest?: WorkerEntryConfig<TEnv>['rewriteRequest']
-}
-
-/**
- * Curried so `TDeps` can be fixed explicitly (it types `methods`/`views`) while
- * `S` is inferred from `schema` — mirroring `defineRemoteDomain`. The common
- * case `domainWorkerEntry<Env>()({ … })` leaves `TDeps = TEnv` (handlers read
- * the env directly); pass both — `domainWorkerEntry<Env, Deps>()` — when the
- * handler deps differ from the worker bindings and a `deps` mapper is supplied.
- */
-export function domainWorkerEntry<TEnv, TDeps = TEnv>() {
-  return function <S extends Schema>(
-    config: DomainWorkerEntryConfig<S, TEnv, TDeps>,
-  ): WorkerEntry<TEnv> {
-    const domain = defineRemoteDomain<TDeps>()({
-      schema: config.schema,
-      methods: config.methods,
-      ...(config.core ? { core: config.core } : {}),
-      ...(config.views ? { views: config.views } : {}),
-      ...(config.functions ? { remoteFunctions: config.functions } : {}),
-      ...(config.manifest ? { manifest: config.manifest } : {}),
-      ...(config.path ? { path: config.path } : {}),
-    })
-
-    return createWorkerEntry<TEnv>({
-      ...(config.resolveUrl ? { resolveUrl: config.resolveUrl } : {}),
-      ...(config.selfBinding ? { selfBinding: config.selfBinding } : {}),
-      ...(config.routeSubrequest ? { routeSubrequest: config.routeSubrequest } : {}),
-      ...(config.before ? { before: config.before } : {}),
-      ...(config.rewriteRequest ? { rewriteRequest: config.rewriteRequest } : {}),
-      // `createWorkerEntry` conflates the worker env and the handler deps into a
-      // single type param; we keep them distinct in the public config and bridge
-      // here. The runtime deps (and the methods typed against them) are correct;
-      // only this assembly is cast.
-      build: (url, env) =>
-        ({
-          domain,
-          deps: config.deps ? config.deps(env, url) : (env as unknown as TDeps),
-          url,
-          privateKey:
-            typeof config.privateKey === 'function' ? config.privateKey(env) : config.privateKey,
-          ...(config.requires && config.requires.length > 0 ? { requires: config.requires } : {}),
-          ...(config.postInstall ? { postInstall: config.postInstall } : {}),
-          ...(config.meta ? { meta: config.meta } : {}),
-          ...(config.app ? { app: config.app(env) } : {}),
-        }) as unknown as RemoteServerConfig<TEnv>,
-    })
-  }
-}

package/src/server/handle.ts

@@ -1,37 +0,0 @@
-/**
- * `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

@@ -1,19 +0,0 @@
-export { createRemoteServer } from './create.js'
-export type { RemoteServerConfig } from './config.js'
-export type { RemoteServer, RemoteServerHandle } from './handle.js'
-export { derivePublicJwk } from './jwks.js'
-export { requireEnv } from './require-env.js'
-export { canonicalizeServingUrl } from './serving-url.js'
-export { assets, createAppWorkerEntry, createWorkerEntry } from './worker-entry.js'
-export type {
-  AppWorkerEntryConfig,
-  Fetcher,
-  WorkerApp,
-  WorkerEntry,
-  WorkerEntryConfig,
-} from './worker-entry.js'
-export { domainWorkerEntry } from './domain-entry.js'
-export type { DomainWorkerEntryConfig } from './domain-entry.js'
-export { serviceWorkerEntry } from './service-entry.js'
-export type { ServiceWorkerEntryConfig, ServiceWorkerIdentityEnv } from './service-entry.js'
-export { startNodeServer } from './start.js'

package/src/server/jwks.ts

@@ -1,18 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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}`)
-}