@astrale-os/sdk 0.1.0

package/src/auth/verify.ts

@@ -0,0 +1,138 @@
+/**
+ * Inbound credential verification.
+ *
+ * Uses kernel-core's credential verification infrastructure
+ * (CredentialMethodResolver, MethodRegistry) instead of manual JWT handling.
+ * Not tied to JWT — supports any credential method kernel-core provides.
+ */
+
+import type {
+  Attestation,
+  CredentialInput,
+  Delegation,
+  IssuerId,
+  VerifiedCredential,
+} from '@astrale-os/kernel-core'
+
+import {
+  CredentialMethodResolver,
+  MethodRegistry,
+  verifyAudience,
+  verifyCredential,
+} from '@astrale-os/kernel-core'
+import { createLocalJWKSet, createRemoteJWKSet, type JWK } from 'jose'
+
+import type { RemoteIdentityConfig } from './identity'
+
+import { derivePublicJwk } from '../server/jwks'
+import { canonicalizeServingUrl } from '../server/serving-url'
+
+export type VerifiedInbound = {
+  /** The full verified credential (iss, sub, aud, claims) */
+  verified: VerifiedCredential
+  /** Issuer URL (from credential's iss claim) */
+  issuer: string
+  /** Attestation — proves caller can invoke this function */
+  attestation: Attestation
+  /** Delegation — scoped caller permissions as kernel-signed credential */
+  delegation: Delegation
+}
+
+const methodResolver = new CredentialMethodResolver(new MethodRegistry())
+
+/**
+ * Build the key resolver for one verifying server. Captures `config` so it can
+ * short-circuit the server's OWN issuer (`config.issuer`): a self-issued
+ * credential is verified against the in-memory public key, never fetched — a
+ * Worker can't fetch its own hostname, and it already holds the key. Every other
+ * issuer is resolved live via JWKS (`createRemoteJWKSet`).
+ */
+function makeResolveKeys(config: RemoteIdentityConfig) {
+  // The worker's own canonical iss. STRICT: `config.issuer` is the serving URL
+  // by contract (both producers — buildIdentityMap / buildAuxIdentityMap — feed
+  // it `canonicalizeServingUrl(config.url)`), so a value that doesn't parse is
+  // a construction-time config error. Swallowing it would silently disable
+  // self-verification and route self-issued credentials to a JWKS fetch on the
+  // worker's own hostname — which Cloudflare forbids — turning a config bug
+  // into an opaque per-call failure.
+  const selfIssuer = canonicalizeServingUrl(config.issuer)
+
+  // TODO(cache): Re-add JWKS caching with a short TTL or kid-miss retry.
+  // A prior implementation cached `createRemoteJWKSet` per issuer URL
+  // indefinitely. jose's internal cache (30s cooldown, 10min max-age) caused
+  // stale keys when the issuer restarted — the resolver served old keys and
+  // jose refused to refetch within the cooldown window. On CF Workers the
+  // module-level Map persisted across requests, making it worse. For now we
+  // create a fresh resolver per call (jose deduplicates concurrent fetches).
+  return async (issuer: IssuerId, _method: string, _kid?: string) => {
+    const url = issuer as string
+
+    // Self-issued credential (iss == this worker's own serving URL): resolve
+    // from the in-memory public key. Never fetch self — Cloudflare forbids a
+    // Worker fetching its own hostname, and the published JWKS is this key.
+    if (selfIssuer !== undefined) {
+      let canonical: string | undefined
+      try {
+        canonical = canonicalizeServingUrl(url)
+      } catch {
+        canonical = undefined
+      }
+      if (canonical === selfIssuer) {
+        return createLocalJWKSet({ keys: [derivePublicJwk(config.privateKey) as JWK] })
+      }
+    }
+
+    // M-28 fix: a bare-slug iss (`mails.localhost`) makes
+    // `new URL('mails.localhost/.well-known/jwks.json')` throw "Invalid
+    // URL string". The dispatcher's identity map normalizes the iss it
+    // signs with, but inbound creds from older clients may still carry
+    // the slug form. Coerce to a URL with a default `https://` scheme
+    // (matches kernel.astrale.ai canonical form). If the actual receiver
+    // is on http://localhost the receiver-side resolver still works
+    // because both endpoints are on localhost — but for prod targets
+    // requiring TLS this is the right default.
+    const normalized = /^https?:\/\//.test(url) ? url : `https://${url}`
+    return createRemoteJWKSet(new URL(`${normalized}/.well-known/jwks.json`))
+  }
+}
+
+/**
+ * Verify an inbound delegation credential using kernel-core's verification.
+ *
+ * @throws AuthenticationError subclasses from kernel-core on verification failure
+ */
+export async function verifyInboundCredential(
+  credential: CredentialInput,
+  config: RemoteIdentityConfig,
+): Promise<VerifiedInbound> {
+  // Verify using kernel-core's credential verification pipeline
+  const verified = await verifyCredential(
+    {
+      methodResolver,
+      resolveKeys: makeResolveKeys(config),
+    },
+    credential,
+  )
+
+  // Validate audience matches this function's issuer (its serving URL).
+  // kernel-core's verifyAudience compares canonically.
+  verifyAudience(verified, config.issuer as IssuerId)
+
+  // Extract attestation and delegation from claims
+  const attestation = verified.claims.attestation as Attestation | undefined
+  if (!attestation?.expr) {
+    throw new Error('Credential missing attestation')
+  }
+
+  const delegation = verified.claims.delegation as Delegation | undefined
+  if (!delegation?.credential) {
+    throw new Error('Credential missing delegation')
+  }
+
+  return {
+    verified,
+    issuer: verified.iss as string,
+    attestation,
+    delegation,
+  }
+}

package/src/define/index.ts

@@ -0,0 +1,9 @@
+export { defineView } from './view'
+export type { ViewDef, ViewRenderContext } from './view'
+
+export { defineRemoteFunction } from './remote-function'
+export type {
+  AnyRemoteFunctionDef,
+  RemoteFunctionContext,
+  RemoteFunctionDef,
+} from './remote-function'

package/src/define/remote-function.ts

@@ -0,0 +1,96 @@
+/**
+ * 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, the former distribution `RemoteFunction`.)
+ *
+ * Each entry in `defineRemoteDomain({ remoteFunctions: { ... } })` becomes:
+ *   - a graph node at `/${origin}/core/<functionsFolder>/<slug>`, materialized
+ *     as the kernel `Function` class by `buildCorePath` so kernel discovery /
+ *     `View.resolve` can list it. The `core/` anchor appears in the GRAPH path only.
+ *   - a Hono route on the worker at the path implied by `binding`
+ *     (`/<functionsFolder>/<slug>` POST by default — no `core/` in the URL).
+ *
+ * The slug = the map key (single source of truth, no duplication).
+ *
+ * `ref` is auto-derived as `function.<slug>` if omitted — used as
+ * `Function.ref` on the graph node and as the dispatch key.
+ */
+
+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 { AuthContext } from '@astrale-os/kernel-core'
+import type { Context } from 'hono'
+import type { z } from 'zod'
+
+import type { CallRemoteFn } from '../dispatch/call-remote'
+
+export type RemoteFunctionContext<TParams, TDeps = unknown> = {
+  /** Validated params (Zod-checked against `inputSchema`). */
+  params: TParams
+  /** Hono request context — escape hatch for headers, raw body, etc. */
+  c: Context
+  /** Resolved auth context. `null` when `auth: 'public'` or absent. */
+  auth: AuthContext | null
+  /** Typed dependency container injected at server startup. */
+  deps: TDeps
+  /**
+   * `BoundClientSessionView` to the parent kernel, bound to the composed
+   * credential `union(delegation, self)` — same shape as `RemoteContext.kernel`
+   * for `remoteMethod`. `null` when `auth: 'public'`, or `auth: 'optional'`
+   * with no inbound credential.
+   */
+  kernel: BoundClientSessionView<FnMap> | null
+  /**
+   * Call another worker's remote method, re-minting the credential for the
+   * target's audience. Same contract as {@link RemoteContext.callRemote}: throws
+   * on a public/unauthenticated request; needs `USE` on
+   * `Identity.mintDelegationCredential` + the target method's grants.
+   */
+  callRemote: CallRemoteFn
+}
+
+export type RemoteFunctionDef<TParams = unknown, TResult = unknown, TDeps = unknown> = {
+  /**
+   * Canonical callable identity. Auto-derived as `function.<slug>` (where
+   * `<slug>` is the map key) when omitted. Stored as `Function.ref` on the
+   * graph node and used by the kernel dispatcher to route the call.
+   */
+  ref?: string
+  /** 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'`. */
+  auth?: AuthPolicy
+  /** Optional pre-execute authorization. Throw to deny. */
+  authorize?: (ctx: RemoteFunctionContext<TParams, TDeps>) => void | Promise<void>
+  /** The function body. May be async. */
+  execute: (ctx: RemoteFunctionContext<TParams, TDeps>) => TResult | Promise<TResult>
+  /** Optional human-readable description. */
+  description?: string
+}
+
+// oxlint-disable-next-line no-explicit-any
+export type AnyRemoteFunctionDef = RemoteFunctionDef<any, any, any>
+
+/**
+ * Identity helper for authoring a RemoteFunction. Returns its argument
+ * unchanged — `defineRemoteDomain` consumes the typed shape.
+ */
+export function defineRemoteFunction<TParams, TResult, TDeps = unknown>(
+  def: RemoteFunctionDef<TParams, TResult, TDeps>,
+): RemoteFunctionDef<TParams, TResult, TDeps> {
+  return def
+}

package/src/define/view.ts

@@ -0,0 +1,91 @@
+/**
+ * Authoring a `View` — iframe-mountable callable served by the domain worker.
+ *
+ * Each entry in `defineRemoteDomain({ views: { ... } })` becomes both:
+ *   - a graph node at `/${origin}/core/<viewsFolder>/<slug>` (auto-materialized
+ *     by the SDK; the `core/` segment is the universal anchor injected by
+ *     `buildCorePath`. `<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 — note: no `core/` in the URL).
+ *
+ * The `core/` segment appears in the GRAPH path only; the URL path that
+ * lands in `Function.binding.remoteUrl` is `${url}/<viewsFolder>/<slug>`.
+ *
+ * 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 { AuthContext } from '@astrale-os/kernel-core'
+import type { EdgeEndpoint } from '@astrale-os/kernel-dsl'
+import type { Context } from 'hono'
+
+export type ViewRenderContext<TDeps = unknown> = {
+  /** 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. `null` when `auth: 'public'` or absent. */
+  auth: AuthContext | null
+  /** Typed dependency container injected at server startup. */
+  deps: TDeps
+}
+
+export type ViewDef<TDeps = unknown> = {
+  /**
+   * 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
+  /** Authentication policy. Defaults to `'required'`. */
+  auth?: AuthPolicy
+  /**
+   * Optional pre-render authorization. Runs after auth resolution; throw to
+   * deny. SDK wraps as 403.
+   */
+  authorize?: (ctx: ViewRenderContext<TDeps>) => 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>) => 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>(def: ViewDef<TDeps>): ViewDef<TDeps> {
+  return def
+}

package/src/deploy/check.ts

@@ -0,0 +1,124 @@
+import { spawnSync } from 'node:child_process'
+import { join } from 'node:path'
+
+import type { Meta } from './meta'
+
+import { MetaSchema } from './meta'
+
+export type DeployCheckOptions = {
+  /** Deployed worker URL (e.g. `https://dist.astrale.ai`). */
+  url: string
+  /**
+   * Expected `meta.schemaHash` — the hash of the locally-built `spec.json`
+   * (via `hashSpecFile`). 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 (`hashSpecFile('./spec.json')`) 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. hashSpecFile('./spec.json'))`,
+    )
+  }
+  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/hash-spec.ts

@@ -0,0 +1,31 @@
+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/deploy/index.ts

@@ -0,0 +1,3 @@
+export { MetaSchema, type Meta } from './meta'
+export { hashSpecFile } from './hash-spec'
+export { deployCheck, type DeployCheckOptions } from './check'

package/src/deploy/meta.ts

@@ -0,0 +1,25 @@
+/**
+ * `/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({
+  /** 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(),
+})
+
+export type Meta = z.infer<typeof MetaSchema>

package/src/dispatch/authorize.ts

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

package/src/dispatch/call-remote.ts

@@ -0,0 +1,48 @@
+/**
+ * `ctx.callRemote` — call ANOTHER worker's remote method from a handler.
+ *
+ * A worker's `kernel.call('/dom/class.X/method', …)` signs `aud = <kernel>`,
+ * which is correct for a **kernel syscall** (it runs in the kernel) but is
+ * rejected by a **remote method** (a Function with `binding.remoteUrl`, i.e.
+ * another worker) — the target worker verifies `aud` against its own identity
+ * and throws `Credential audience mismatch` at authentication.
+ *
+ * `callRemote` is now a thin wrapper over the bound kernel session: the kernel
+ * resolves a remote-bound path to a redirect carrying the worker's URL and its
+ * `iss`, and the session (configured in `bindKernel`) follows it reactively —
+ * minting a kernel-signed delegation envelope scoped to that `iss` via the
+ * caller's own `@<subject>::mintDelegationCredential`, then dialing the worker.
+ * Instance-method `self` is injected by the kernel resolver into the redirect,
+ * so a bare `kernel.call(path, params)` is all that's needed here.
+ *
+ * Prerequisite (authorization, unchanged): the calling Function's identity must
+ * hold `USE` on `Identity.mintDelegationCredential` AND the target method's own
+ * grants — the session only fixes the audience (authentication), not grants.
+ */
+
+import type { ClientSessionCallOptions } from '@astrale-os/kernel-client/session'
+
+/** Minimal kernel-call surface callRemote needs (the bound view satisfies it). */
+type KernelCaller = {
+  call: (method: string, params: unknown, opts?: ClientSessionCallOptions) => Promise<unknown>
+}
+
+export type CallRemoteFn = (path: string, params?: Record<string, unknown>) => Promise<unknown>
+
+/**
+ * Build the `callRemote` helper for one handler invocation. `kernel` is the
+ * handler's bound kernel view (or `null` for a public/unauthenticated request,
+ * where `callRemote` cannot mint and throws on use).
+ */
+export function makeCallRemote(kernel: KernelCaller | null): CallRemoteFn {
+  return async (path, params = {}) => {
+    if (!kernel) {
+      throw new Error(
+        'callRemote requires an authenticated request — no kernel credential (public method?)',
+      )
+    }
+    // The bound session auto-follows the kernel's redirect and mints for the
+    // worker's `iss`; a remote-bound path therefore just works as a kernel.call.
+    return kernel.call(path, params)
+  }
+}