@astrale-os/sdk 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# SDK
+
+Astrale Remote Domain SDK — define and deploy domains as standalone Hono servers.
+
+[![CI](https://github.com/astrale-os/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/astrale-os/sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Install
+
+```bash
+npm install @astrale-os/sdk
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 22+
+- pnpm 10+
+
+### Setup
+
+The SDK is consumed as a submodule of the main Astrale workspace:
+
+```bash
+git clone --recursive https://github.com/astrale-os/workspace.git
+cd workspace
+pnpm install
+```
+
+### Commands
+
+```bash
+pnpm typecheck      # Type check
+pnpm test           # Run tests
+pnpm lint           # Lint
+pnpm format         # Format
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@astrale-os/sdk",
+  "version": "0.1.0",
+  "description": "Astrale Remote Domain SDK - Define and deploy domains as standalone Hono servers",
+  "keywords": [
+    "astrale",
+    "domain",
+    "hono",
+    "remote",
+    "sdk"
+  ],
+  "license": "MIT",
+  "author": "Astrale",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astrale-os/sdk.git"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./deploy": {
+      "types": "./dist/deploy/index.d.ts",
+      "import": "./dist/deploy/index.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@astrale-os/kernel-api": ">=0.4.0 <1.0.0",
+    "@astrale-os/kernel-client": ">=0.1.0 <1.0.0",
+    "@astrale-os/kernel-core": ">=0.3.0 <1.0.0",
+    "@astrale-os/kernel-dsl": ">=0.1.0 <1.0.0",
+    "@astrale-os/kernel-server": ">=0.4.0 <1.0.0",
+    "hono": "^4.6.20",
+    "jose": "^6.1.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@astrale-os/kernel-host": ">=0.4.0 <1.0.0",
+    "@astrale-os/kernel-test": ">=0.4.0 <1.0.0",
+    "@astrale-os/ox": ">=0.1.0 <1.0.0",
+    "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.0",
+    "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
+    "@commitlint/cli": "~20.3.1",
+    "@commitlint/config-conventional": "~20.3.1",
+    "@hono/node-server": "^1.19.12",
+    "@types/node": "^22.0.0",
+    "@typescript/native-preview": "latest",
+    "husky": "~9.1.7",
+    "lint-staged": "~16.2.7",
+    "oxfmt": "latest",
+    "oxlint": "latest",
+    "typescript": "~6.0.1-rc",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@hono/node-server": "^1.19.0"
+  },
+  "peerDependenciesMeta": {
+    "@hono/node-server": {
+      "optional": true
+    }
+  },
+  "lint-staged": {
+    "*.{js,cjs,mjs,ts,tsx}": [
+      "oxlint --fix",
+      "oxfmt --write"
+    ],
+    "*.{json,yml,yaml}": [
+      "oxfmt --write"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "preinstall": "node .check-workspace.cjs",
+    "build": "tsgo",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run --config __tests__/vitest.config.ts",
+    "test:watch": "vitest --config __tests__/vitest.config.ts",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "format": "pnpm exec oxfmt --write .",
+    "format:check": "pnpm exec oxfmt --check ."
+  }
+}

package/src/auth/authenticate.ts

@@ -0,0 +1,51 @@
+/**
+ * Authentication orchestrator.
+ *
+ * Verifies an inbound credential, extracts the delegation it carries,
+ * and binds a `BoundClientSessionView` for outbound kernel calls. Delegates
+ * the real work to `verify`, `compose` + `sign` (inside `kernel-client`),
+ * and returns a generic `Authenticated` result plus the bound view.
+ */
+
+import type { FnMap } from '@astrale-os/kernel-client'
+import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
+import type { Authenticated, CredentialInput } from '@astrale-os/kernel-core'
+
+import { IdentityId, selfGrant } from '@astrale-os/kernel-core'
+
+import type { RemoteIdentityConfig } from './identity'
+
+import { bindKernel } from './kernel-client'
+import { verifyInboundCredential } from './verify'
+
+export type AuthenticateResult = {
+  authenticated: Authenticated
+  kernel: BoundClientSessionView<FnMap> | null
+}
+
+/**
+ * Verifies an inbound credential and binds a call-back kernel view. The `sub`
+ * claim on the outbound credential is the function's own identity, taken from
+ * `config.subject` (the function node's path), so the kernel matches an
+ * existing function identity instead of provisioning a generic one.
+ */
+export async function authenticateRequest(
+  credential: CredentialInput,
+  config: RemoteIdentityConfig,
+): Promise<AuthenticateResult> {
+  const { verified, issuer, attestation, delegation } = await verifyInboundCredential(
+    credential,
+    config,
+  )
+
+  const authenticated: Authenticated = {
+    credential: { raw: credential, verified },
+    grant: selfGrant(IdentityId(verified.sub)),
+    attestation,
+    delegation,
+  }
+
+  const kernel = await bindKernel(delegation, issuer, config)
+
+  return { authenticated, kernel }
+}

package/src/auth/check.ts

@@ -0,0 +1,73 @@
+/**
+ * Permission-check helpers for `RemoteHandler.authorize` hooks.
+ *
+ * The kernel already enforces `has_perm` independently — these helpers just
+ * give worker authors a one-line ergonomic way to fail-fast in `authorize`
+ * (so the dispatch never even calls `execute`) instead of letting the
+ * downstream `kernel.call` raise a less specific error mid-flight.
+ *
+ * Pattern:
+ *
+ * ```ts
+ * remoteMethod(WorkerSchema, 'Project', 'addMember', {
+ *   remoteUrl: BASE_URL,
+ *   authorize: async ({ self, auth, kernel }) => {
+ *     await assertPerm(kernel, self.path.raw, auth.principal, EDIT)
+ *   },
+ *   execute: async (ctx) => { ... },
+ * })
+ * ```
+ *
+ * Helpers throw `AuthorizationDeniedError` so the dispatch wrapper can
+ * surface them to the client as `PERMISSION_DENIED` cleanly.
+ */
+
+import type { FnMap } from '@astrale-os/kernel-client'
+import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
+import type { IdentityId } from '@astrale-os/kernel-core'
+
+import { SHARE } from '@astrale-os/kernel-core'
+
+import { AuthorizationDeniedError } from '../dispatch/errors'
+
+export { ALL, EDIT, READ, SHARE, USE } from '@astrale-os/kernel-core'
+
+/**
+ * Throws `AuthorizationDeniedError` if `principal` lacks `requiredBits` on
+ * `target`. `requiredBits` is a bitmask — pass `READ | EDIT` to require both.
+ *
+ * Implementation: calls `@<principal>::checkPerm` on the kernel (the
+ * `checkPerm` syscall lives on the Identity, not the target). Cheap; adds
+ * one round-trip to the dispatch path.
+ */
+export async function assertPerm(
+  kernel: BoundClientSessionView<FnMap> | null,
+  target: string,
+  principal: IdentityId | null | undefined,
+  requiredBits: number,
+): Promise<void> {
+  if (!kernel) {
+    throw new AuthorizationDeniedError('No kernel client — cannot verify permissions')
+  }
+  if (!principal) {
+    throw new AuthorizationDeniedError('No authenticated principal')
+  }
+  const ok = (await kernel.call(`@${principal}::checkPerm`, {
+    node: target,
+    perms: requiredBits,
+  })) as boolean
+  if (!ok) {
+    throw new AuthorizationDeniedError(
+      `Permission denied on "${target}" — required bits=${requiredBits} for principal "${principal}"`,
+    )
+  }
+}
+
+/** Shortcut for "caller has SHARE bit on target" (the closest thing to "owns it"). */
+export async function requireOwnership(
+  kernel: BoundClientSessionView<FnMap> | null,
+  target: string,
+  principal: IdentityId | null | undefined,
+): Promise<void> {
+  await assertPerm(kernel, target, principal, SHARE)
+}

package/src/auth/compose.ts

@@ -0,0 +1,31 @@
+/**
+ * Outbound grant expression building.
+ *
+ * Builds a composed grant expression for kernel calls:
+ *   grant = union(credential(delegationJWT), self)
+ *
+ * The kernel resolves this by verifying the delegation JWT (kernel-signed)
+ * to get the caller's scoped identity, and resolving self to the function's
+ * identity. Union means either identity's permissions work.
+ */
+
+import type { Delegation } from '@astrale-os/kernel-core'
+
+import {
+  createUnresolvedGrant,
+  unresolvedCredential,
+  unresolvedSelf,
+  unresolvedUnion,
+} from '@astrale-os/kernel-core'
+
+/**
+ * Build the grant expression that unions the caller's delegated access
+ * with the function's own identity.
+ *
+ * @param delegation - Delegation extracted from the inbound credential
+ * @returns The unresolved grant object with version and expression
+ */
+export function buildComposedGrant(delegation: Delegation) {
+  const expr = unresolvedUnion(unresolvedCredential(delegation.credential), unresolvedSelf())
+  return { grant: createUnresolvedGrant(expr) }
+}

package/src/auth/errors.ts

@@ -0,0 +1,32 @@
+/**
+ * Errors thrown by the auth bridge.
+ *
+ * Each implements `KernelErrorClassifiable` so `kernel-api/dispatch` can
+ * convert them into typed `KernelErrorPayload` values automatically.
+ */
+
+import type { KernelErrorPayload, KernelErrorClassifiable } from '@astrale-os/kernel-api'
+
+import { KERNEL_ERROR_CODES } from '@astrale-os/kernel-api'
+
+export class AuthMissingError extends Error implements KernelErrorClassifiable {
+  constructor() {
+    super('Missing credentials')
+    this.name = 'AuthMissingError'
+  }
+
+  toKernelErrorPayload(): KernelErrorPayload {
+    return { code: KERNEL_ERROR_CODES.AUTH_MISSING, message: this.message }
+  }
+}
+
+export class AuthInvalidError extends Error implements KernelErrorClassifiable {
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause })
+    this.name = 'AuthInvalidError'
+  }
+
+  toKernelErrorPayload(): KernelErrorPayload {
+    return { code: KERNEL_ERROR_CODES.AUTH_INVALID, message: this.message }
+  }
+}

package/src/auth/identity.ts

@@ -0,0 +1,15 @@
+/**
+ * Identity configuration for a remote domain server.
+ *
+ * The issuer must be reachable via JWKS at `<issuer>/.well-known/jwks.json`
+ * (or registered in the kernel's trust store). The private key is used to
+ * sign outbound composed credentials.
+ */
+export type RemoteIdentityConfig = {
+  /** This service's issuer (URL where its JWKS is served, or a registered ID) */
+  issuer: string
+  /** This service's subject identifier (e.g. "task-service") */
+  subject: string
+  /** Private key for signing outbound credentials */
+  privateKey: JsonWebKey
+}

package/src/auth/index.ts

@@ -0,0 +1,11 @@
+export type { RemoteIdentityConfig } from './identity'
+export type { VerifiedInbound } from './verify'
+export type { AuthenticateResult } from './authenticate'
+export { authenticateRequest } from './authenticate'
+export { resolveInboundAuth, buildAuthContext, type ResolvedAuth } from './resolve'
+export { verifyInboundCredential } from './verify'
+export { buildComposedGrant } from './compose'
+export { signCredential } from './sign'
+export { bindKernel } from './kernel-client'
+export { AuthMissingError, AuthInvalidError } from './errors'
+export { assertPerm, requireOwnership, READ, EDIT, USE, SHARE, ALL } from './check'

package/src/auth/kernel-client.ts

@@ -0,0 +1,107 @@
+/**
+ * Call-back kernel client.
+ *
+ * Every authenticated inbound request produces a `BoundClientSessionView` the
+ * handler uses to call back into the parent kernel. The view is bound to
+ * a composed credential (`union(delegation, self)`) so the kernel
+ * enforces both the caller's scoped identity and the function's own.
+ *
+ * The connection pool and schema registry are cached per kernel URL and reused
+ * across requests. The `ClientSession` itself is per-request: it carries a
+ * delegation mint bound to the calling function's own subject (`config.subject`)
+ * so a remote-bound call (one that redirects to another worker) mints a
+ * worker-scoped credential for the audience the kernel puts on the redirect
+ * (`CallRedirection.iss`) — the worker→worker dance, done reactively instead of
+ * the old proactive `lookupRemoteBinding` resolve-then-dial.
+ */
+
+import type { Delegation } from '@astrale-os/kernel-core'
+
+import { KernelClient, SchemaRegistry, type FnMap } from '@astrale-os/kernel-client'
+import { ClientPool } from '@astrale-os/kernel-client/pool'
+import { ClientSession, type BoundClientSessionView } from '@astrale-os/kernel-client/session'
+
+import type { RemoteIdentityConfig } from './identity'
+
+import { buildComposedGrant } from './compose'
+import { signCredential } from './sign'
+
+const DELEGATION_TTL_SECONDS = 3600
+
+// Shared per kernel URL — the expensive, identity-agnostic state. Sessions are
+// NOT shared (each binds a subject-specific delegation mint), but the pool
+// (connections) and registry (learned schemas) are reused across them.
+const pools = new Map<string, ClientPool<FnMap>>()
+const registries = new Map<string, SchemaRegistry>()
+
+function getRegistry(url: string): SchemaRegistry {
+  let registry = registries.get(url)
+  if (!registry) {
+    registry = new SchemaRegistry()
+    registries.set(url, registry)
+  }
+  return registry
+}
+
+function getPool(url: string): ClientPool<FnMap> {
+  const cached = pools.get(url)
+  if (cached) return cached
+  const registry = getRegistry(url)
+  const pool = new ClientPool<FnMap>({
+    clientFactory: (u) => new KernelClient<FnMap>({ url: u, schema: registry }),
+  })
+  pools.set(url, pool)
+  return pool
+}
+
+/**
+ * Build a `BoundClientSessionView` that signs outbound calls as the composed
+ * identity (the caller's delegation unioned with this function's own
+ * identity). Remote-bound calls auto-follow the kernel's redirect and mint a
+ * worker-scoped delegation via `@<subject>::mintDelegationCredential`.
+ */
+export async function bindKernel(
+  delegation: Delegation,
+  kernelUrl: string,
+  config: RemoteIdentityConfig,
+): Promise<BoundClientSessionView<FnMap>> {
+  const { grant } = buildComposedGrant(delegation)
+  const composed = await signCredential(
+    { grant },
+    {
+      issuer: config.issuer,
+      subject: config.subject,
+      audience: kernelUrl,
+      privateKey: config.privateKey,
+    },
+  )
+
+  // Self-reference in the mint closure is lazy — it only fires on a delegation
+  // cache miss while following a redirect, long after construction.
+  const session: ClientSession<FnMap> = new ClientSession<FnMap>({
+    default: kernelUrl,
+    schema: getRegistry(kernelUrl),
+    pool: getPool(kernelUrl),
+    delegation: {
+      // `@<subject>::mintDelegationCredential` satisfies the syscall's
+      // `self.id === auth.principal` invariant (composed's subject IS the
+      // principal). `skipDelegation` keeps this mint from re-entering itself —
+      // it targets the kernel (same origin), so no delegation is needed.
+      mint: async (audience) => {
+        const envelope = await session.call(
+          `@${config.subject}::mintDelegationCredential`,
+          { audience, delegation: { kind: 'identity', self: true }, ttl: DELEGATION_TTL_SECONDS },
+          { credential: composed, skipDelegation: true },
+        )
+        if (typeof envelope !== 'string') {
+          throw new Error(
+            `mintDelegationCredential returned ${typeof envelope}, expected a credential string`,
+          )
+        }
+        return { credential: envelope, ttl: DELEGATION_TTL_SECONDS }
+      },
+      ttl: DELEGATION_TTL_SECONDS,
+    },
+  })
+  return session.as(composed)
+}

package/src/auth/resolve.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared inbound-credential resolution.
+ *
+ * Consumed by both `SdkDispatcher` (kernel envelope) and `mountAuxiliaryRoutes`
+ * (View / RemoteFunction routes). Centralises the auth-policy three-way
+ * (`'required'` / `'optional'` / `'public'`) and the wrap of underlying
+ * verification errors into canonical `AuthMissingError` / `AuthInvalidError`.
+ */
+
+import type { AuthPolicy } from '@astrale-os/kernel-api/routed'
+import type {
+  AuthContext,
+  Authenticated,
+  CredentialInput,
+  IdentityId,
+} from '@astrale-os/kernel-core'
+
+import { isKernelErrorClassifiable } from '@astrale-os/kernel-api'
+
+import type { AuthenticateResult } from './authenticate'
+import type { RemoteIdentityConfig } from './identity'
+
+import { authenticateRequest } from './authenticate'
+import { AuthInvalidError, AuthMissingError } from './errors'
+
+export type ResolvedAuth = {
+  auth: AuthContext | null
+  kernel: AuthenticateResult['kernel']
+}
+
+export async function resolveInboundAuth(
+  credential: CredentialInput,
+  policy: AuthPolicy | undefined,
+  identity: RemoteIdentityConfig,
+): Promise<ResolvedAuth> {
+  const effective = policy ?? 'required'
+
+  if (effective === 'public') return { auth: null, kernel: null }
+  if (effective === 'optional' && !credential) return { auth: null, kernel: null }
+  if (effective === 'required' && !credential) throw new AuthMissingError()
+
+  try {
+    const result = await authenticateRequest(credential, identity)
+    return { auth: buildAuthContext(result.authenticated), kernel: result.kernel }
+  } catch (err) {
+    // kernel-core auth errors (UntrustedIssuerError, TrustPolicyDeniedError, …)
+    // already self-classify with a discriminating `data.type`. Rethrow them
+    // unchanged so that classification survives to the wire; only wrap
+    // genuinely unclassified errors into the generic AuthInvalidError.
+    if (isKernelErrorClassifiable(err)) throw err
+    throw new AuthInvalidError(err instanceof Error ? err.message : 'Authentication failed', err)
+  }
+}
+
+export function buildAuthContext(authenticated: Authenticated): AuthContext {
+  return {
+    credential: authenticated.credential,
+    principal: authenticated.credential.verified.sub as unknown as IdentityId,
+    grant: authenticated.grant!,
+    attestation: authenticated.attestation,
+    delegation: authenticated.delegation,
+  }
+}

package/src/auth/sign.ts

@@ -0,0 +1,36 @@
+/**
+ * JWT signing utilities for outbound composed credentials.
+ */
+
+import { deriveAllowedAlgorithms } from '@astrale-os/kernel-core'
+import { SignJWT, importJWK } from 'jose'
+
+/**
+ * Sign a credential JWT with the given claims and identity config.
+ */
+export async function signCredential(
+  claims: Record<string, unknown>,
+  config: {
+    issuer: string
+    subject: string
+    audience: string
+    privateKey: JsonWebKey
+    /** JWT lifetime as a jose-compatible string (e.g. '60s', '5m', '1h'). Default: '60s'. */
+    ttl?: string
+  },
+): Promise<string> {
+  const alg = deriveAllowedAlgorithms(config.privateKey)[0]
+  if (!alg) {
+    throw new Error(`Cannot derive algorithm from JWK: kty=${config.privateKey.kty}`)
+  }
+  const key = await importJWK(config.privateKey, alg)
+
+  return new SignJWT(claims)
+    .setProtectedHeader({ alg })
+    .setIssuer(config.issuer)
+    .setSubject(config.subject)
+    .setAudience(config.audience)
+    .setIssuedAt()
+    .setExpirationTime(config.ttl ?? '60s')
+    .sign(key)
+}