@astrale-os/sdk 0.4.19 → 0.5.0-beta.2

package/src/define/remote-function.ts

@@ -1,184 +0,0 @@
-/**
- * Authoring a standalone remote function — a callable not bound to a class.
- * (The verb keeps the `defineRemoteFunction` name; the node it materializes is
- * the canonical kernel `Function` class, replacing the former remote-function wrapper.)
- *
- * Each entry in `defineRemoteDomain({ remoteFunctions: { ... } })` becomes:
- *   - a graph node at `/${origin}/functions/<slug>` — a first-class domain MEMBER,
- *     materialized as the kernel `Function` class and attached to the Domain via an
- *     `of_domain` edge (slug `function.<slug>`), so it is addressable by the
- *     semantic path `/:${origin}:function.<slug>` (the form a `postInstall` uses).
- *   - a Hono route on the worker at the path implied by `binding`
- *     (`/<functionsFolder>/<slug>` POST by default — the route URL is decoupled
- *     from the graph layout).
- *
- * The slug = the map key (single source of truth, no duplication). The member
- * ref (`function.<slug>`), the layout (`/<origin>/functions/<slug>`), and the
- * `of_domain` edge slug are all DERIVED from it — there is nothing else to name.
- */
-
-import type { AuthPolicy, FunctionBinding } from '@astrale-os/kernel-api/routed'
-import type { FnMap } from '@astrale-os/kernel-client'
-import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
-import type { Defer, Sleep } from '@astrale-os/kernel-server'
-import type { Context } from 'hono'
-import type { z } from 'zod'
-
-import type { FunctionContextApi } from '../auth/function-context.js'
-import type { DomainAuthority } from '../auth/issuer-mint.js'
-import type { AuthForPolicy, CallerContext, KernelForAuth, RemoteEnv } from '../method/context.js'
-import type { Step } from '../step/index.js'
-
-type RemoteFunctionBaseContext<
-  TParams,
-  TDeps = unknown,
-  TKernel = BoundClientSessionView<FnMap> | null,
-  TAuth extends AuthPolicy = AuthPolicy,
-> = {
-  /** Validated params (Zod-checked against `inputSchema`). */
-  params: TParams
-  /** Hono request context — escape hatch for headers, raw body, etc. */
-  c: Context
-  /**
-   * Resolved auth context. Its nullability follows the function's `auth`
-   * policy: non-null for the default `'required'`, `... | null` for
-   * `'optional'`, and `null` for `'public'`.
-   */
-  auth: AuthForPolicy<TAuth>
-  /** Typed dependency container injected at server startup. */
-  deps: TDeps
-  /** Local serving metadata. */
-  env: RemoteEnv
-  /**
-   * `BoundClientSessionView` to the parent kernel, bound to the composed
-   * credential `union(delegation, self)` — same shape as `RemoteContext.kernel`
-   * for `remoteMethod`, including the typed graph read/write sugar flattened onto
-   * it (`kernel.get` / `kernel.children` / `kernel.query`,
-   * `kernel.createNode` / `kernel.mutate(patch)`, …) over the `function.get` /
-   * `function.mutate` syscalls. Nullability follows {@link KernelForAuth} of the
-   * function's `auth`: non-null for the default `'required'`, `… | null` for
-   * `'optional'`, `null` for `'public'` (use `ctx.fn.kernel()` there, after
-   * verifying the upstream).
-   */
-  kernel: TKernel
-  /** Inbound kernel/peer context. Present only for authenticated invocations. */
-  caller?: CallerContext
-  /** Mint seam for identities THIS DOMAIN issues. */
-  domain: DomainAuthority
-  /** Current function identity tools. */
-  fn: FunctionContextApi
-}
-
-export type RemoteFunctionAuthorizeContext<
-  TParams,
-  TDeps = unknown,
-  TKernel = BoundClientSessionView<FnMap> | null,
-  TAuth extends AuthPolicy = AuthPolicy,
-> = RemoteFunctionBaseContext<TParams, TDeps, TKernel, TAuth>
-
-export interface RemoteFunctionContext<
-  TParams,
-  TDeps = unknown,
-  TKernel = BoundClientSessionView<FnMap> | null,
-  TAuth extends AuthPolicy = AuthPolicy,
-> extends RemoteFunctionBaseContext<TParams, TDeps, TKernel, TAuth> {
-  /** Durable-shaped step builder. Inline today, replayable by future backends. */
-  step: Step
-  /** Run independent work without making its completion part of this result. */
-  defer: Defer
-  /** Pause execution for a relative duration. Durable hosts may persist the wait. */
-  sleep: Sleep
-}
-
-export type RemoteFunctionDef<
-  TParams = unknown,
-  TResult = unknown,
-  TDeps = unknown,
-  TAuth extends AuthPolicy = 'required',
-> = {
-  /** Zod schema for the call's parameters. */
-  inputSchema: z.ZodType<TParams>
-  /** Zod schema for the call's result. */
-  outputSchema: z.ZodType<TResult>
-  /**
-   * Override the binding (URL + route shape). When absent, SDK defaults to
-   * `{ remoteUrl: ${url}/<functionsFolder>/<slug> }`. The HTTP verb (POST
-   * for functions) is applied by the worker route mounter at mount time — it is
-   * NOT stored on the binding, so the materialized `Function.binding` carries
-   * `remoteUrl` only.
-   *
-   * Use this to bind to a custom host or REST-style path. Host + path
-   * placeholders both supported.
-   */
-  binding?: FunctionBinding
-  /**
-   * Authentication policy. Defaults to `'required'`. Captured as a literal type
-   * so it drives `ctx.auth` and {@link KernelForAuth} on the
-   * `execute`/`authorize` context: omit it (or `'required'`) makes both
-   * non-null; `'optional'` widens them to `... | null`; `'public'` makes them
-   * `null` (webhooks reach the graph via `ctx.fn.kernel()`).
-   */
-  auth?: TAuth
-  /** Optional pre-execute authorization. Throw to deny. */
-  authorize?: (
-    ctx: RemoteFunctionAuthorizeContext<TParams, TDeps, KernelForAuth<TAuth>, TAuth>,
-  ) => void | Promise<void>
-  /** The function body. May be async. */
-  execute: (
-    ctx: RemoteFunctionContext<TParams, TDeps, KernelForAuth<TAuth>, TAuth>,
-  ) => TResult | Promise<TResult>
-  /** Optional human-readable description. */
-  description?: string
-}
-
-// Loosely-typed "bag" for the per-domain function maps. The PRECISE typing is
-// enforced at each `defineRemoteFunction` call site; this only has to HOLD defs
-// of ANY auth policy. We deliberately do NOT pin a single concrete `TAuth`:
-// `RemoteFunctionContext` carries `kernel: KernelForAuth<TAuth>` (an
-// auth-dependent type that resolves to a concrete union), so any single concrete
-// policy — `'required'` OR the full `AuthPolicy` union — rejects the others when
-// a handler is assigned into the bag under parameter contravariance (a public
-// handler wants `kernel: null`, a required one `kernel: Kernel`; neither fits a
-// fixed bag). Relaxing the `authorize`/`execute` PARAMS to `any` is what makes
-// the bag accept every policy; soundness is unchanged — the bag was already
-// `any, any, any`, and the real contract is checked at the call site.
-// oxlint-disable no-explicit-any
-export type AnyRemoteFunctionDef = Omit<
-  RemoteFunctionDef<any, any, any, AuthPolicy>,
-  'authorize' | 'execute'
-> & {
-  authorize?: (ctx: any) => void | Promise<void>
-  execute: (ctx: any) => any
-}
-// oxlint-enable no-explicit-any
-
-// Compile-time regression guards (pure `type` aliases — zero runtime emit, but
-// checked by `pnpm typecheck` since this file is under `src/`). Each asserts a
-// function of the given auth policy still FITS the bag. If `AnyRemoteFunctionDef`
-// ever narrows back and rejects a policy, the matching `_Assert<false>` errors.
-type _AssertTrue<T extends true> = T
-type _FnFitsBag<D> = D extends AnyRemoteFunctionDef ? true : false
-// Exported only so `noUnusedLocals` treats the assertions as used — it is NOT
-// re-exported by `../define`, so it never reaches the package's public surface.
-// A regression that makes the bag reject a policy turns the matching
-// `_AssertTrue<false>` into a compile error here.
-export type _AuthPolicyBagGuards = [
-  _AssertTrue<_FnFitsBag<RemoteFunctionDef<unknown, unknown, unknown, 'public'>>>,
-  _AssertTrue<_FnFitsBag<RemoteFunctionDef<unknown, unknown, unknown, 'optional'>>>,
-  _AssertTrue<_FnFitsBag<RemoteFunctionDef<unknown, unknown, unknown, 'required'>>>,
-]
-
-/**
- * Identity helper for authoring a RemoteFunction. Returns its argument
- * unchanged — `defineRemoteDomain` consumes the typed shape.
- */
-export function defineRemoteFunction<
-  TParams,
-  TResult,
-  TDeps = unknown,
-  TAuth extends AuthPolicy = 'required',
->(
-  def: RemoteFunctionDef<TParams, TResult, TDeps, TAuth>,
-): RemoteFunctionDef<TParams, TResult, TDeps, TAuth> {
-  return def
-}

package/src/define/view.ts

@@ -1,112 +0,0 @@
-/**
- * Authoring a `View` — iframe-mountable callable served by the domain worker.
- *
- * Each entry in `defineRemoteDomain({ views: { ... } })` becomes both:
- *   - a first-class domain MEMBER: a `View` node at `/${origin}/views/<slug>`
- *     attached to the Domain via an `of_domain` edge (slug `view.<slug>`),
- *     addressable as `/:${origin}:view.<slug>`. `<slug>` is the map key, so it
- *     lives in exactly one place.
- *   - a Hono route on the worker at the path implied by `binding`
- *     (`/<viewsFolder>/<slug>` by default).
- *
- * The graph layout (`/<origin>/views/<slug>`) is a fixed kernel convention; the
- * URL path that lands in `Function.binding.remoteUrl` is
- * `${url}/<viewsFolder>/<slug>` — DECOUPLED from the graph layout.
- *
- * The author can override the URL via `binding` — host and/or path
- * placeholders are supported (the kernel's `route` mechanism does the
- * substitution + Hono matching, same as for methods). When `render` is
- * omitted, no worker route is mounted — useful for Views whose iframe
- * lives at an external host.
- */
-
-import type { AuthPolicy, FunctionBinding } from '@astrale-os/kernel-api/routed'
-import type { EdgeEndpoint } from '@astrale-os/kernel-dsl'
-import type { Context } from 'hono'
-
-import type { FunctionContextApi } from '../auth/function-context.js'
-import type { AuthForPolicy } from '../method/context.js'
-import type { RemoteEnv } from '../method/context.js'
-
-export type ViewRenderContext<TDeps = unknown, TAuth extends AuthPolicy = AuthPolicy> = {
-  /** Hono request context — read params, headers, query, etc. */
-  c: Context
-  /**
-   * Placeholders extracted from the request URL (host + path placeholders
-   * declared in `binding.remoteUrl` / `binding.route.path`). Empty when
-   * the binding has no placeholders.
-   */
-  params: Record<string, string>
-  /**
-   * Resolved auth context. Its nullability follows the View's `auth` policy:
-   * non-null for `'required'`, `... | null` for `'optional'`, and `null` for
-   * `'public'`.
-   */
-  auth: AuthForPolicy<TAuth>
-  /** Typed dependency container injected at server startup. */
-  deps: TDeps
-  /** Local serving metadata. */
-  env: RemoteEnv
-  /** View function identity tools. Use `fn.kernel()` for server-rendered graph reads. */
-  fn: FunctionContextApi
-}
-
-export type ViewDef<TDeps = unknown, TAuth extends AuthPolicy = AuthPolicy> = {
-  /**
-   * Override the binding (URL + route shape). When absent, SDK defaults to
-   * `{ remoteUrl: ${url}/<viewsFolder>/<slug> }`. The HTTP verb (GET for
-   * views) is applied by the worker route mounter at mount time — it is NOT
-   * stored on the binding.
-   *
-   * Use this to bind to a custom host (e.g. `https://{tenant}.example.com`)
-   * or REST-style path. Host + path placeholders both supported.
-   */
-  binding?: FunctionBinding
-  /**
-   * Worker-relative path the View's iframe is served from (e.g. `'/ui/note'`),
-   * for Views backed by the client SPA instead of a `render`. The spec producer
-   * resolves it against the serving url (`binding.remoteUrl = ${url}${mount}`)
-   * at materialize time — so the dev never hardcodes a URL. Mutually exclusive
-   * with `render`; takes precedence over `binding`.
-   */
-  mount?: string
-  /**
-   * Shell handshake mode for the mounted iframe. Omit for the common case:
-   * SPA-mounted views (`mount`) use the shell handshake; inline `render` views
-   * default to `'none'` because they do not include the shell client.
-   */
-  handshake?: 'shell' | 'none'
-  /** Authentication policy. Defaults to `'required'`. */
-  auth?: TAuth
-  /**
-   * Optional pre-render authorization. Runs after auth resolution; throw to
-   * deny. SDK wraps as 403.
-   */
-  authorize?: (ctx: ViewRenderContext<TDeps, TAuth>) => void | Promise<void>
-  /**
-   * Render the iframe response. May return a redirect, a proxy, or inline
-   * HTML. When omitted, no worker route is mounted — the binding URL
-   * points elsewhere (CDN, external service).
-   */
-  render?: (ctx: ViewRenderContext<TDeps, TAuth>) => Response | Promise<Response>
-  /**
-   * Optional target(s) the View attaches to via `view_for` edge(s). Typically
-   * `selfOf(SomeClass)` to bind to a class meta-node, or a `CorePath`
-   * pointing at a specific instance. Pass an array to attach the same View
-   * to multiple targets (one `view_for` edge is materialized per entry).
-   */
-  viewFor?: EdgeEndpoint | EdgeEndpoint[]
-  /** Optional human-readable description. */
-  description?: string
-}
-
-/**
- * Identity helper for authoring a View. Returns its argument unchanged —
- * `defineRemoteDomain` consumes the typed shape and the author retains
- * full type inference on `render` / `authorize`.
- */
-export function defineView<TDeps = unknown, TAuth extends AuthPolicy = 'required'>(
-  def: ViewDef<TDeps, TAuth>,
-): ViewDef<TDeps, TAuth> {
-  return def
-}

package/src/deploy/check.ts

@@ -1,124 +0,0 @@
-import { spawnSync } from 'node:child_process'
-import { join } from 'node:path'
-
-import type { Meta } from './meta.js'
-
-import { MetaSchema } from './meta.js'
-
-export type DeployCheckOptions = {
-  /** Deployed worker URL (e.g. `https://example.astrale.ai`). */
-  url: string
-  /**
-   * Expected `meta.schemaHash` — the hash of the domain's install graph (via
-   * `buildInstallGraphHash(domain, url)`). REQUIRED to verify schema drift: when
-   * the worker advertises a `schemaHash` but this is absent, the check fails
-   * loudly rather than silently "passing" an unverified deploy. Per-domain
-   * deploy scripts compute it (`buildInstallGraphHash(...)`) and pass it.
-   */
-  expectedSchemaHash?: string
-  /**
-   * Path to the SDK repo used to read `sdkCommit`. If omitted and
-   * `workspaceRoot` is provided, defaults to `<workspaceRoot>/sdk`.
-   */
-  sdkRepoPath?: string
-  /** Astrale workspace root — enables auto-resolution of `sdkRepoPath` (`<root>/sdk`). */
-  workspaceRoot?: string
-  /** Sink for progress output. Defaults to `console.log`. */
-  log?: (line: string) => void
-}
-
-/**
- * Validate a deployed worker against local state by fetching `/meta` and
- * verifying sdkCommit / schemaHash / JWKS reachability.
- *
- * Throws on any mismatch. Returns `Meta` on success.
- */
-export async function deployCheck(opts: DeployCheckOptions): Promise<Meta> {
-  // oxlint-disable-next-line no-console
-  const log = opts.log ?? ((line: string) => console.log(line))
-  const base = opts.url.replace(/\/+$/, '')
-
-  log(`# deploy:check ${base}`)
-
-  const meta = await fetchMeta(base)
-  log(`  meta: ${JSON.stringify(meta)}`)
-  // `meta.iss` is required + non-empty by `MetaSchema`, enforced in `fetchMeta`.
-
-  await Promise.all([
-    checkSdkCommit(meta, opts, log),
-    checkSchemaHash(meta, opts, log),
-    checkJwks(meta.iss, log),
-  ])
-
-  return meta
-}
-
-async function fetchMeta(base: string): Promise<Meta> {
-  const res = await fetch(`${base}/meta`)
-  if (!res.ok) throw new Error(`GET ${base}/meta → ${res.status}`)
-  return MetaSchema.parse(await res.json())
-}
-
-async function checkSdkCommit(
-  meta: Meta,
-  opts: DeployCheckOptions,
-  log: (line: string) => void,
-): Promise<void> {
-  if (!meta.sdkCommit) {
-    log('  ! meta.sdkCommit absent — skipping sdkCommit check')
-    return
-  }
-  const sdkRepo =
-    opts.sdkRepoPath ?? (opts.workspaceRoot ? join(opts.workspaceRoot, 'sdk') : undefined)
-  if (!sdkRepo) {
-    log(`  ! no sdkRepoPath / workspaceRoot — skipping sdkCommit check`)
-    return
-  }
-  const localSha = gitHead(sdkRepo)
-  if (!localSha) {
-    log(`  ! could not read git HEAD from ${sdkRepo} — skipping sdkCommit check`)
-    return
-  }
-  if (!localSha.startsWith(meta.sdkCommit) && !meta.sdkCommit.startsWith(localSha)) {
-    throw new Error(`sdkCommit mismatch: deployed=${meta.sdkCommit} local=${localSha} (${sdkRepo})`)
-  }
-  log(`  ✓ sdkCommit ${meta.sdkCommit} matches local HEAD`)
-}
-
-async function checkSchemaHash(
-  meta: Meta,
-  opts: DeployCheckOptions,
-  log: (line: string) => void,
-): Promise<void> {
-  if (!meta.schemaHash) return
-  // Fail loud: the worker advertises a schemaHash, so a missing expected value
-  // means we CANNOT verify drift — never silently "pass" an unverified deploy.
-  if (!opts.expectedSchemaHash) {
-    throw new Error(
-      `worker advertises schemaHash=${meta.schemaHash} but no expectedSchemaHash was provided — ` +
-        `cannot verify schema drift (pass expectedSchemaHash, e.g. buildInstallGraphHash(domain, url))`,
-    )
-  }
-  if (meta.schemaHash !== opts.expectedSchemaHash) {
-    throw new Error(
-      `schemaHash mismatch: deployed=${meta.schemaHash} local=${opts.expectedSchemaHash}`,
-    )
-  }
-  log(`  ✓ schemaHash ${meta.schemaHash} matches local`)
-}
-
-async function checkJwks(iss: string, log: (line: string) => void): Promise<void> {
-  const jwksUrl = `${iss.replace(/\/+$/, '')}/.well-known/jwks.json`
-  const res = await fetch(jwksUrl)
-  if (!res.ok) throw new Error(`GET ${jwksUrl} → ${res.status}`)
-  const body = (await res.json()) as { keys?: Array<{ kid?: string }> }
-  const keys = body.keys ?? []
-  if (keys.length === 0) throw new Error(`${jwksUrl} returned no keys`)
-  log(`  ✓ JWKS resolves (${keys.length} key${keys.length === 1 ? '' : 's'})`)
-}
-
-function gitHead(repoPath: string): string | null {
-  const r = spawnSync('git', ['-C', repoPath, 'rev-parse', 'HEAD'], { encoding: 'utf-8' })
-  if (r.status !== 0) return null
-  return r.stdout.trim()
-}

package/src/deploy/index.ts

@@ -1,2 +0,0 @@
-export { MetaSchema, type Meta } from './meta.js'
-export { deployCheck, type DeployCheckOptions } from './check.js'

package/src/deploy/meta.ts

@@ -1,50 +0,0 @@
-/**
- * `/meta` payload — the contract between `createRemoteServer` (producer)
- * and `deployCheck` (verifier). Both sides parse through `MetaSchema`, so
- * a new field added here flows to both paths and drift is caught at the
- * boundary rather than silently skipped.
- *
- * Scope: **domain workers only**. Kernels rely on OIDC discovery
- * (`/.well-known/openid-configuration`) + JWKS — they have no `/meta`.
- */
-
-import { z } from 'zod'
-
-export const MetaSchema = z.object({
-  // The version of the meta payload. Incremented on any change to the payload
-  version: z.number().int().min(1).default(1),
-  /** Base URL where JWKS is published. Always stamped by `createRemoteServer`
-   *  and required by `deployCheck` to verify JWKS reachability. */
-  iss: z.string().min(1),
-  /** Short git SHA of the SDK used to build the worker. */
-  sdkCommit: z.string().optional(),
-  /** Deterministic hash of the compiled spec (`sha256:<hex>`). */
-  schemaHash: z.string().optional(),
-  /** Local directory name under `kernel/domains/<...>/` — used to auto-resolve the local spec. */
-  domainName: z.string().optional(),
-  /**
-   * Optional presentation metadata declared on the domain (`defineDomain`):
-   * `logo` (inline SVG / `data:` URL), `entrypoint` (a view slug — the domain's
-   * entry surface), and the domain's declared `roles` (registered by a workspace
-   * at app install). Served verbatim so a host UI can brand a freshly-installed
-   * domain.
-   */
-  manifest: z
-    .object({
-      logo: z.string().optional(),
-      entrypoint: z.string().optional(),
-      roles: z
-        .array(
-          z.object({
-            slug: z.string().min(1),
-            name: z.string().optional(),
-            description: z.string().optional(),
-            default: z.boolean().optional(),
-          }),
-        )
-        .optional(),
-    })
-    .optional(),
-})
-
-export type Meta = z.infer<typeof MetaSchema>

package/src/dispatch/authorize.ts

@@ -1,29 +0,0 @@
-/**
- * Shared `authorize`-hook runner.
- *
- * Both the method dispatcher (`dispatcher.ts`) and the worker-side aux routes
- * (`server/auxiliary-routes.ts`) let an author deny a call by throwing from an
- * `authorize` hook. They MUST agree on the wire semantics: an already-typed
- * `AuthorizationDeniedError` passes through unchanged (so callers can attach
- * hints), and any other thrown error is wrapped into `AuthorizationDeniedError`
- * (→ `PERMISSION_DENIED` / HTTP 403). Centralised here so the two call sites
- * cannot drift — previously the aux routes awaited `authorize` directly, so a
- * plain `Error` thrown to deny leaked out as a 500 instead of a 403.
- */
-
-import { AuthorizationDeniedError } from './errors.js'
-
-export async function runAuthorize<C>(
-  hook: (ctx: C) => void | Promise<void>,
-  ctx: C,
-): Promise<void> {
-  try {
-    await hook(ctx)
-  } catch (err) {
-    if (err instanceof AuthorizationDeniedError) throw err
-    throw new AuthorizationDeniedError(
-      err instanceof Error ? err.message : 'Authorization denied',
-      err,
-    )
-  }
-}