@astrale-os/sdk 0.2.0 → 0.3.0

package/src/method/single.ts

@@ -1,14 +1,4 @@
-/**
- * Authoring a single remote method.
- *
- * `RemoteHandler` is the typed shape an author writes for ONE method:
- * an `execute` body plus optional REST `route` (using the kernel's
- * canonical `RouteBinding`) and optional anchor `remoteUrl`.
- *
- * `MethodImpl` resolves params/result/self from a schema for a given
- * `(class, method)` pair. `remoteMethod` is the identity helper an author
- * calls per method to get full inference without writing generics by hand.
- */
+/** Authoring helpers for one schema-bound remote method. */
 
 import type { AuthPolicy, RouteBinding } from '@astrale-os/kernel-api/routed'
 import type {
@@ -19,21 +9,12 @@ import type {
 } from '@astrale-os/kernel-core/domain'
 import type { Schema } from '@astrale-os/kernel-dsl'
 
-import type { SelfResult } from '../dispatch/self'
+import type { TypedSelf } from '../dispatch/self'
 import type { KernelForAuth, RemoteContext } from './context'
 
 /**
- * Remote function handler — execute with full typed context.
- *
- * `execute` is **optional** at the type level: a handler may be a pure
- * binding stub (only `remoteUrl` / `route` set) when authored as a spec-side
- * declaration that never runs locally — the kernel resolver short-circuits
- * via `binding.remoteUrl` before reaching the handler body. The worker-side
- * declaration that actually serves the call MUST provide `execute`.
- *
- * Runtime guard: if dispatch routes to a handler that has no `execute`, the
- * dispatcher throws — that's a programmer error indicating a stub leaked into
- * a code path that was supposed to execute it.
+ * Remote method handler. `execute` is optional only for binding stubs; any
+ * handler that the dispatcher actually reaches must provide it.
  */
 export type RemoteHandler<TParams, TResult, TSelf, TDeps, TAuth extends AuthPolicy = 'required'> = {
   /** The handler body. May be async or an async generator (for `output: 'stream'`). */
@@ -62,30 +43,34 @@ export type RemoteHandler<TParams, TResult, TSelf, TDeps, TAuth extends AuthPoli
    */
   auth?: TAuth
   /**
-   * Optional pre-execute authorization check. Runs after auth resolution and
-   * `_self` resolution, before `execute`. Throw any error to deny the call —
-   * the SDK wraps it as `AuthorizationDeniedError` (mapped to wire-level
-   * `PERMISSION_DENIED`).
-   *
-   * Use for fine-grained checks the kernel's bit-level perms can't express
-   * (e.g. "only the project lead can addMember"). For straight bit-level
-   * checks, prefer the helpers in `@astrale-os/sdk` (`assertPerm`,
-   * `requireOwnership`).
-   *
-   * The kernel still enforces `has_perm` independently — `authorize` is
-   * additive ergonomic gating on top, not a replacement.
+   * Optional business authorization after auth/_self resolution. Kernel
+   * has_perm checks remain authoritative; this is additive gating.
    */
   authorize?: (
     ctx: RemoteContext<TParams, TSelf, TDeps, KernelForAuth<TAuth>, TAuth>,
   ) => void | Promise<void>
 }
 
-// `TAuth = AuthPolicy` (the full union, not the `'required'` default) keeps this
-// maximally permissive: it accepts a handler of ANY declared policy, and its
-// `ctx.kernel` widens to `BoundClientSessionView<FnMap> | null`. Used by the
-// dispatcher/index where the concrete policy is erased.
-// oxlint-disable-next-line no-explicit-any
-export type AnyRemoteHandler = RemoteHandler<any, any, any, any, AuthPolicy>
+// Post-binding indexes erase the concrete auth policy; authoring remains checked
+// at `remoteMethod`, while dispatcher/build-spec only need a policy-neutral bag.
+// oxlint-disable no-explicit-any
+export type AnyRemoteHandler = Omit<
+  RemoteHandler<any, any, any, any, AuthPolicy>,
+  'authorize' | 'execute'
+> & {
+  execute?: (ctx: any) => any
+  authorize?: (ctx: any) => void | Promise<void>
+}
+// oxlint-enable no-explicit-any
+
+// Compile-time guard: every auth policy must fit the erased handler bag.
+type _AssertTrueH<T extends true> = T
+type _HandlerFitsBag<D> = D extends AnyRemoteHandler ? true : false
+export type _MethodPolicyBagGuards = [
+  _AssertTrueH<_HandlerFitsBag<RemoteHandler<unknown, unknown, unknown, unknown, 'public'>>>,
+  _AssertTrueH<_HandlerFitsBag<RemoteHandler<unknown, unknown, unknown, unknown, 'optional'>>>,
+  _AssertTrueH<_HandlerFitsBag<RemoteHandler<unknown, unknown, unknown, unknown, 'required'>>>,
+]
 
 /**
  * Fully typed method implementation — resolves params/result/self from the
@@ -104,9 +89,17 @@ export type MethodImpl<
     self: unknown
     isStatic: infer St
   }
-    ? RemoteHandler<P, R, St extends true ? undefined : SelfResult, TDeps, TAuth>
+    ? RemoteHandler<P, R, St extends true ? undefined : TypedSelf<S['classes'][K], S>, TDeps, TAuth>
     : never
 
+/**
+ * `MethodParams` / `MethodResult` — a handler types its `params` as
+ * `MethodParams<typeof schema, 'Def', 'method'>` and its return as
+ * `MethodResult<…>`, so it never re-declares (and can't drift from) the schema.
+ * Resolved from whichever def — CLASS or INTERFACE — declares the method.
+ */
+export type { MethodParams, MethodResult } from '@astrale-os/kernel-core/domain'
+
 type ImplementableMethodName<S extends Schema, K extends MethodClassKeys<S> & string> = (
   | OwnMethodKeys<S, K>
   | NonSealedMethodKeys<S, K>

package/src/server/auxiliary-routes.ts

@@ -39,6 +39,7 @@ import type { ViewDef } from '../define/view'
 import type { CallRemoteFn } from '../dispatch/call-remote'
 import type { AuxIdentityMap } from '../dispatch/identity'
 
+import { makeIssuerMint } from '../auth/issuer-mint'
 import { makeSelfKernel } from '../auth/kernel-client'
 import { resolveInboundAuth } from '../auth/resolve'
 import { runAuthorize } from '../dispatch/authorize'
@@ -136,7 +137,17 @@ export function mountAuxiliaryRoutes<TDeps>(config: AuxiliaryRoutesConfig<TDeps>
           if (!validation.ok) {
             throw new SdkValidationError(validation.issues as SdkValidationError['issues'])
           }
-          const ctx = { params: validation.data, c, auth, deps, kernel, callRemote, selfKernel }
+          const issuer = makeIssuerMint(identity)
+          const ctx = {
+            params: validation.data,
+            c,
+            auth,
+            deps,
+            kernel,
+            issuer,
+            callRemote,
+            selfKernel,
+          }
           if (def.authorize) await runAuthorize(def.authorize, ctx)
           const result = await def.execute(ctx)
           const outValidation = validateResult(def.outputSchema, result)
@@ -216,7 +227,7 @@ function mountEntry(args: MountEntryArgs): void {
     )
   }
   // Local-dev requests target literal `localhost`, but bindings reference a
-  // logical host (`dist.localhost`) — so only enforce a Host-header match
+  // logical host (`example.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

package/src/server/create.ts

@@ -1,19 +1,6 @@
 /**
- * `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)
+ * 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'
@@ -45,21 +32,18 @@ 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.
+  // Canonical serving URL drives signing, JWKS, /meta, and install credentials.
   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.
+  // Stamp aux bindings against the same URL used as issuer.
   const { compiled, auxiliary } = materializeRemoteDomain(config.domain, iss)
 
   const dispatcher = new SdkDispatcher<TDeps>({
     compiled,
     methods,
+    // The source schema drives the rich typed `self` handed to non-static
+    // handlers (`self.node()` → BoundNode<D>, typed `self.call`).
+    schema: compiled.$.schema,
     deps: config.deps,
     privateKey: config.privateKey,
     issuer: iss,
@@ -74,12 +58,7 @@ export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): Re
     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.
+  // 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
@@ -93,6 +72,7 @@ export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): Re
     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() })),
@@ -116,23 +96,16 @@ export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): Re
       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.
+    // 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
-    // `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.
+    // Signed claims and bundle fields must agree exactly.
     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.
+    // Install credential issuer is the serving URL the kernel fetched.
     const credential = await signInstallCredential({
       privateKey: config.privateKey,
       issuer: iss,
@@ -155,12 +128,7 @@ export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): Re
   // 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.
+  // 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>({
@@ -191,10 +159,7 @@ export function createRemoteServer<TDeps>(config: RemoteServerConfig<TDeps>): Re
 
   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.
+    // Expose the canonical issuer, not the raw env URL, for graph identity stamping.
     iss,
     async start(port?: number): Promise<RemoteServerHandle> {
       const nodeStartModule = './start'
@@ -230,8 +195,7 @@ async function signInstallCredential(args: {
   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
+  // postInstall/requires are signed, not just copied into the bundle.
   return new SignJWT({
     subs: args.subs,
     nonce: args.nonce,

package/src/server/domain-entry.ts

@@ -18,6 +18,7 @@
 import type { Core, Schema } from '@astrale-os/kernel-dsl'
 import type { Hono } from 'hono'
 
+import type { DomainManifest } from '../config/define-domain'
 import type { AnyRemoteFunctionDef, ViewDef } from '../define'
 import type { SchemaMethodsImpl } from '../method'
 import type { RemoteServerConfig } from './config'
@@ -47,8 +48,17 @@ export interface DomainWorkerEntryConfig<S extends Schema, TEnv, TDeps> {
   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
@@ -84,6 +94,8 @@ export function domainWorkerEntry<TEnv, TDeps = TEnv>() {
       ...(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>({

package/src/server/index.ts

@@ -8,5 +8,4 @@ export { assets, createWorkerEntry } from './worker-entry'
 export type { WorkerEntry, WorkerEntryConfig } from './worker-entry'
 export { domainWorkerEntry } from './domain-entry'
 export type { DomainWorkerEntryConfig } from './domain-entry'
-export { workerMeta } from './worker-meta'
 export { startNodeServer } from './start'

package/src/deploy/hash-spec.ts

@@ -1,31 +0,0 @@
-import { createHash } from 'node:crypto'
-import { readFileSync } from 'node:fs'
-
-const HASH_ALGORITHM = 'sha256'
-
-/**
- * Hash a `spec.json` file deterministically. Only the schema payload
- * (`nodes` + `edges`) is hashed — the `meta` block carries `builtAt`
- * timestamps that would poison drift detection.
- *
- * Returns `sha256:<hex>`.
- */
-export function hashSpecFile(path: string): string {
-  const raw = readFileSync(path, 'utf-8')
-  const parsed = JSON.parse(raw) as { nodes?: unknown; edges?: unknown }
-  const canonical = canonicalJson({ nodes: parsed.nodes ?? [], edges: parsed.edges ?? [] })
-  return `${HASH_ALGORITHM}:${createHash(HASH_ALGORITHM).update(canonical).digest('hex')}`
-}
-
-function canonicalJson(value: unknown): string {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value)
-  if (Array.isArray(value)) return '[' + value.map(canonicalJson).join(',') + ']'
-  const keys = Object.keys(value as Record<string, unknown>).sort()
-  return (
-    '{' +
-    keys
-      .map((k) => JSON.stringify(k) + ':' + canonicalJson((value as Record<string, unknown>)[k]))
-      .join(',') +
-    '}'
-  )
-}

package/src/server/worker-meta.ts

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