@astrale-os/sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,77 @@
+// ─── Method authoring ────────────────────────────────────────────────────
+export type {
+  RemoteContext,
+  RemoteHandler,
+  MethodImpl,
+  ClassMethodsImpl,
+  InterfaceMethodsImpl,
+  SchemaMethodsImpl,
+} from './method'
+export { remoteMethod, remoteClassMethods, remoteInterfaceMethods } from './method'
+
+// ─── Domain ──────────────────────────────────────────────────────────────
+export { defineRemoteDomain, buildInstallGraph, buildInstallGraphHash } from './domain'
+export type { RemoteDomain, RemoteDomainConfig } from './domain'
+
+// ─── Declarative resource helpers ────────────────────────────────────────
+// Author Views (iframe-mountable) and RemoteFunctions (standalone callables)
+// at the domain definition site. Each `defineView` / `defineRemoteFunction`
+// entry is auto-materialized by `defineRemoteDomain` into a graph node (a
+// `View`, or the canonical kernel `Function` for standalone callables) under
+// the reserved views / functions folder, keyed by its map slug; the same
+// entry's `render` / `execute` (+ auth hooks) is mounted as a worker route by
+// `createRemoteServer`.
+export { defineView, defineRemoteFunction } from './define'
+export type { ViewDef, ViewRenderContext, RemoteFunctionDef, RemoteFunctionContext } from './define'
+
+// ─── Server ──────────────────────────────────────────────────────────────
+// `createRemoteServer` dynamically imports `@hono/node-server` via `./server/start`.
+// Exporting the server surface from the barrel poisons browser bundlers
+// (Vite/esbuild) that traverse every re-export and try to bundle the dynamic
+// chunk — which fails on Node built-ins. Consumers that need the server
+// runtime import from '@astrale-os/sdk/server' directly.
+
+// ─── Deploy ──────────────────────────────────────────────────────────────
+// `deployCheck` and `hashSpecFile` use Node-only modules (`node:crypto`,
+// `node:fs`, `node:child_process`) at module load time. Exporting them from
+// the barrel poisons browser bundlers (Vite/esbuild) that transitively load
+// every re-export. Consumers that need them import from './deploy' directly.
+export { MetaSchema } from './deploy/meta'
+export type { Meta } from './deploy/meta'
+
+// ─── Route binding (re-exported from kernel-api for consumer convenience) ─
+export type {
+  AuthPolicy,
+  RouteBinding,
+  FunctionBinding,
+  CredentialSource,
+  SingleCredentialSource,
+  HttpMethod,
+  RouteBody,
+  OutputMode,
+} from '@astrale-os/kernel-api/routed'
+
+// ─── Auth ────────────────────────────────────────────────────────────────
+export type { RemoteIdentityConfig, AuthenticateResult } from './auth'
+export { authenticateRequest, buildComposedGrant, signCredential } from './auth'
+export { AuthMissingError, AuthInvalidError } from './auth'
+export { assertPerm, requireOwnership, READ, EDIT, USE, SHARE, ALL } from './auth'
+export type {
+  AuthContext,
+  Attestation,
+  Authenticated,
+  Delegation,
+  IdentityId,
+  IssuerId,
+} from '@astrale-os/kernel-core'
+export { selfGrant } from '@astrale-os/kernel-core'
+
+// ─── Dispatch (escape hatch for custom integrations) ─────────────────────
+export { SdkDispatcher, type SdkDispatcherConfig } from './dispatch'
+export {
+  AuthorizationDeniedError,
+  MethodNotFoundError,
+  SdkValidationError,
+  SdkResultValidationError,
+} from './dispatch'
+export type { SelfResult, CallRemoteFn } from './dispatch'

package/src/method/class.ts

@@ -0,0 +1,148 @@
+/**
+ * Class-level method aggregation.
+ *
+ * Where `RemoteHandler` describes one method, the types here describe a
+ * whole class's worth of methods. `ClassMethodsImpl<S, K, TDeps>` enforces
+ * that every implementable method on class `K` is provided. The interface
+ * variant handles abstract definitions; the schema variant indexes by class
+ * name.
+ *
+ * `remoteClassMethods` is the identity helper an author calls when supplying
+ * a class's full method record — it gives full inference for the class
+ * methods at once, complementing `remoteMethod` (one method at a time).
+ */
+
+import type {
+  DefForInterface,
+  InterfaceMethodDefs,
+  InterfaceMethodKeys,
+  MethodClassKeys,
+  NonSealedMethodKeys,
+  OwnMethodKeys,
+  ResolveParams,
+  ResolveReturn,
+  SealedKeys,
+} from '@astrale-os/kernel-core/domain'
+import type { ImplementableOwnKeys, Schema } from '@astrale-os/kernel-dsl'
+
+import type { SelfResult } from '../dispatch/self'
+import type { MethodImpl, RemoteHandler } from './single'
+
+/** Per-class method implementations for a remote domain. */
+export type ClassMethodsImpl<
+  S extends Schema,
+  K extends MethodClassKeys<S> & string,
+  TDeps = unknown,
+> = {
+  [M in OwnMethodKeys<S, K>]: MethodImpl<S, K, M, TDeps>
+} & {
+  [M in NonSealedMethodKeys<S, K>]: MethodImpl<S, K, M, TDeps>
+} & {
+  [M in SealedKeys<S, K>]?: never
+}
+
+/** Resolve interface method handler directly (InterfaceMethodKeys ≠ MethodKeys). */
+type InterfaceMethodHandler<
+  S extends Schema,
+  K extends string,
+  M extends string,
+  TDeps,
+> = M extends keyof InterfaceMethodDefs<S, K>
+  ? InterfaceMethodDefs<S, K>[M] extends { readonly config: infer MC }
+    ? MC extends { readonly static: true }
+      ? RemoteHandler<ResolveParams<MC>, ResolveReturn<MC>, undefined, TDeps>
+      : // Non-static interface methods receive the same `self` the dispatcher
+        // actually delivers — `SelfResult` ({ path, id? }) — exactly as the
+        // class-method path (`MethodImpl`) does. The node's declared props are
+        // NOT hydrated at runtime, so a node-typed self would be unsound.
+        RemoteHandler<ResolveParams<MC>, ResolveReturn<MC>, SelfResult, TDeps>
+    : never
+  : never
+
+/** Per-interface method implementations. */
+export type InterfaceMethodsImpl<
+  S extends Schema,
+  K extends InterfaceMethodKeys<S> & string,
+  TDeps = unknown,
+> = {
+  [M in ImplementableOwnKeys<DefForInterface<S, K>> & string]: InterfaceMethodHandler<
+    S,
+    K,
+    M,
+    TDeps
+  >
+}
+
+/**
+ * Namespace-keyed full schema methods map, parameterized by deps.
+ * Handlers for classes and interfaces live under distinct `class` / `interface`
+ * slots, preventing name collisions between a class and an interface with the
+ * same name.
+ *
+ * `interface` is optional — schemas without non-abstract interface methods
+ * (or with no interfaces at all) do not need to provide it.
+ */
+export type SchemaMethodsImpl<S extends Schema, TDeps = unknown> = {
+  class: { [K in MethodClassKeys<S> & string]: ClassMethodsImpl<S, K, TDeps> }
+  interface?: { [K in InterfaceMethodKeys<S> & string]: InterfaceMethodsImpl<S, K, TDeps> }
+}
+
+type RejectSealedKeys<S extends Schema, K extends string, I> = keyof I &
+  SealedKeys<S, K> extends never
+  ? I
+  : `Error: sealed methods must not be implemented by class '${K}': ${keyof I & SealedKeys<S, K> & string}`
+
+/** Identity helper for authoring one class's remote methods with full schema typing. */
+export function remoteClassMethods<TDeps>(): <
+  S extends Schema,
+  K extends MethodClassKeys<S> & string,
+  I extends ClassMethodsImpl<S, K, TDeps>,
+>(
+  schema: S,
+  className: K,
+  impl: I & RejectSealedKeys<S, K, I>,
+) => I
+export function remoteClassMethods<
+  S extends Schema,
+  K extends MethodClassKeys<S> & string,
+  I extends ClassMethodsImpl<S, K>,
+>(schema: S, className: K, impl: I & RejectSealedKeys<S, K, I>): I
+export function remoteClassMethods(...args: unknown[]) {
+  if (args.length === 0) {
+    return (...innerArgs: unknown[]) => innerArgs[2]
+  }
+
+  return args[2]
+}
+
+/**
+ * Identity helper for authoring one interface's remote methods with full
+ * schema typing — the interface-hosted counterpart of `remoteClassMethods`.
+ *
+ * Methods declared on an interface (e.g. a static `createNote` on `NoteOps`)
+ * live under the `interface:` slot of `SchemaMethodsImpl`. Without this helper
+ * an author has to fall back to `any` (there is no other way to name the
+ * per-method handler type — `InterfaceMethodHandler` is internal). Returns the
+ * per-interface impl object the `interface: { <Name>: … }` slot expects.
+ */
+export function remoteInterfaceMethods<TDeps>(): <
+  S extends Schema,
+  K extends InterfaceMethodKeys<S> & string,
+  I extends InterfaceMethodsImpl<S, K, TDeps>,
+>(
+  schema: S,
+  interfaceName: K,
+  impl: I,
+) => I
+export function remoteInterfaceMethods<
+  S extends Schema,
+  K extends InterfaceMethodKeys<S> & string,
+  I extends InterfaceMethodsImpl<S, K>,
+>(schema: S, interfaceName: K, impl: I): I
+export function remoteInterfaceMethods(...args: unknown[]) {
+  if (args.length === 0) {
+    return (...innerArgs: unknown[]) => innerArgs[2]
+  }
+
+  return args[2]
+}

package/src/method/context.ts

@@ -0,0 +1,45 @@
+/**
+ * `RemoteContext` — what every remote method handler receives at runtime.
+ *
+ * Assembled by the dispatch pipeline before calling `execute`. Carries the
+ * validated params, the resolved auth context, the bound node instance (for
+ * non-static methods), the typed dependency container, and a
+ * `BoundClientSessionView` to call back into the parent kernel.
+ */
+
+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 { CallRemoteFn } from '../dispatch/call-remote'
+
+export type RemoteContext<TParams, TSelf, TDeps> = {
+  /** Validated params (Zod-checked against the method's `inputSchema`). */
+  params: TParams
+  /** Auth context resolved from the inbound delegation credential. `null` for public or unauthenticated optional methods. */
+  auth: AuthContext | null
+  /** Bound node instance — `undefined` for static methods. */
+  self: TSelf
+  /** Typed dependency container injected at server startup. */
+  deps: TDeps
+  /** The worker's own serving URL */
+  url: string
+  /**
+   * `BoundClientSessionView` to the parent kernel, bound to the composed
+   * credential `union(delegation, self)`. `null` when `auth: 'public'`, or
+   * `auth: 'optional'` with no inbound credential. Use for kernel syscalls +
+   * same-domain methods. For ANOTHER worker's remote method use
+   * {@link RemoteContext.callRemote} — `kernel.call` to a remote method fails
+   * the audience check.
+   */
+  kernel: BoundClientSessionView<FnMap> | null
+  /**
+   * Call another worker's remote method (a Function with `binding.remoteUrl`),
+   * re-minting the credential for the target's audience so it isn't rejected at
+   * authentication. Throws on a public/unauthenticated request (no credential
+   * to mint from). The calling Function's identity must hold `USE` on
+   * `Identity.mintDelegationCredential` AND the target method's own grants —
+   * `callRemote` fixes the audience, not authorization.
+   */
+  callRemote: CallRemoteFn
+}

package/src/method/index.ts

@@ -0,0 +1,5 @@
+export type { RemoteContext } from './context'
+export type { RemoteHandler, AnyRemoteHandler, MethodImpl } from './single'
+export { remoteMethod } from './single'
+export type { ClassMethodsImpl, InterfaceMethodsImpl, SchemaMethodsImpl } from './class'
+export { remoteClassMethods, remoteInterfaceMethods } from './class'

package/src/method/single.ts

@@ -0,0 +1,133 @@
+/**
+ * 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.
+ */
+
+import type { AuthPolicy, RouteBinding } from '@astrale-os/kernel-api/routed'
+import type {
+  MethodClassKeys,
+  ClassMethodConfig,
+  NonSealedMethodKeys,
+  OwnMethodKeys,
+} from '@astrale-os/kernel-core/domain'
+import type { Schema } from '@astrale-os/kernel-dsl'
+
+import type { SelfResult } from '../dispatch/self'
+import type { 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.
+ */
+export type RemoteHandler<TParams, TResult, TSelf, TDeps> = {
+  /** The handler body. May be async or an async generator (for `output: 'stream'`). */
+  execute?: (
+    ctx: RemoteContext<TParams, TSelf, TDeps>,
+  ) => TResult | Promise<TResult> | AsyncGenerator<TResult>
+  /**
+   * Optional REST binding — attaches a native HTTP route to this method.
+   * Uses the kernel's canonical `RouteBinding` type directly.
+   */
+  route?: RouteBinding
+  /**
+   * Optional anchor URL — marks this method as anchored to a specific host.
+   * May contain `{name}` placeholders matching fields in the input schema.
+   * If absent, the method is ambient (mounts on whatever server loads the domain).
+   */
+  remoteUrl?: string
+  /** Optional human-readable description. Appears in generated docs. */
+  description?: string
+  /** Authentication policy. Defaults to `'required'` when absent. */
+  auth?: AuthPolicy
+  /**
+   * 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.
+   */
+  authorize?: (ctx: RemoteContext<TParams, TSelf, TDeps>) => void | Promise<void>
+}
+
+// oxlint-disable-next-line no-explicit-any
+export type AnyRemoteHandler = RemoteHandler<any, any, any, any>
+
+/**
+ * Fully typed method implementation — resolves params/result/self from the
+ * schema, wraps in `RemoteHandler` with deps.
+ */
+export type MethodImpl<
+  S extends Schema,
+  K extends MethodClassKeys<S> & string,
+  M extends string,
+  TDeps = unknown,
+> =
+  ClassMethodConfig<S, K, M> extends {
+    params: infer P
+    result: infer R
+    self: unknown
+    isStatic: infer St
+  }
+    ? RemoteHandler<P, R, St extends true ? undefined : SelfResult, TDeps>
+    : never
+
+type ImplementableMethodName<S extends Schema, K extends MethodClassKeys<S> & string> = (
+  | OwnMethodKeys<S, K>
+  | NonSealedMethodKeys<S, K>
+) &
+  string
+
+/**
+ * Identity helper for authoring one remote method with full schema-driven typing.
+ *
+ * Two-form calling convention:
+ *  - `remoteMethod<TDeps>()` — curried form; captures deps type, returns a
+ *     per-schema helper. Use when you want deps typed.
+ *  - `remoteMethod(schema, className, methodName, impl)` — direct form with
+ *     `unknown` deps.
+ */
+export function remoteMethod<TDeps>(): <
+  S extends Schema,
+  K extends MethodClassKeys<S> & string,
+  M extends ImplementableMethodName<S, K>,
+>(
+  schema: S,
+  className: K,
+  methodName: M,
+  impl: MethodImpl<S, K, M, TDeps>,
+) => MethodImpl<S, K, M, TDeps>
+export function remoteMethod<
+  S extends Schema,
+  K extends MethodClassKeys<S> & string,
+  M extends ImplementableMethodName<S, K>,
+>(schema: S, className: K, methodName: M, impl: MethodImpl<S, K, M>): MethodImpl<S, K, M>
+export function remoteMethod(...args: unknown[]) {
+  if (args.length === 0) {
+    return (...innerArgs: unknown[]) => innerArgs[3]
+  }
+
+  return args[3]
+}