@astrale-os/sdk 0.4.18 → 0.5.0-beta.1

package/src/auth/errors.ts

@@ -1,32 +0,0 @@
-/**
- * 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/function-context.ts

@@ -1,108 +0,0 @@
-import type { FnMap } from '@astrale-os/kernel-client'
-import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
-import type { UnresolvedIdentityExpr } from '@astrale-os/kernel-core'
-
-import { createUnresolvedGrant } from '@astrale-os/kernel-core'
-
-import type { RemoteIdentityConfig } from './identity.js'
-
-import { buildSelfExpr, buildSelfGrant } from './compose.js'
-import { bindCredentialSession } from './kernel-client.js'
-import { signCredential } from './sign.js'
-
-export type FunctionCredentialOptions = {
-  /** Credential audience. Defaults to the current/default kernel URL when known. */
-  audience?: string
-  /** Grant carried by the top-level kernel bearer. Defaults to self. */
-  grant?: UnresolvedIdentityExpr
-  /** JWT lifetime, jose-style. Default is the SDK per-request kernel TTL. */
-  ttl?: string
-}
-
-export type FunctionKernelOptions = FunctionCredentialOptions & {
-  /** Kernel URL to dial. Defaults to `audience`, then the current/default kernel URL. */
-  url?: string
-  /** Next-hop delegation for remote redirects. Defaults to the credential grant. */
-  delegation?: UnresolvedIdentityExpr
-}
-
-export type FunctionContextApi = {
-  readonly ref: string
-  credential(opts?: FunctionCredentialOptions): Promise<string>
-  kernel(opts?: FunctionKernelOptions): Promise<BoundClientSessionView<FnMap>>
-}
-
-export function makeFunctionContext(
-  identity: RemoteIdentityConfig,
-  deps: unknown,
-  opts: { ref: string; defaultKernelUrl?: string },
-): FunctionContextApi {
-  return {
-    ref: opts.ref,
-    credential: (params) =>
-      signFunctionCredential(
-        identity,
-        resolveAudience(params?.audience, opts.defaultKernelUrl, deps),
-        {
-          grant: params?.grant,
-          ttl: params?.ttl,
-        },
-      ),
-    kernel: async (params) => {
-      const kernelUrl = resolveKernelUrl(params?.url, params?.audience, opts.defaultKernelUrl, deps)
-      const grant = params?.grant ?? buildSelfExpr()
-      const credential = await signFunctionCredential(identity, params?.audience ?? kernelUrl, {
-        grant,
-        ttl: params?.ttl,
-      })
-      return bindCredentialSession(kernelUrl, credential, {
-        delegation: params?.delegation ?? grant,
-      })
-    },
-  }
-}
-
-async function signFunctionCredential(
-  identity: RemoteIdentityConfig,
-  audience: string,
-  opts: { grant?: UnresolvedIdentityExpr; ttl?: string },
-): Promise<string> {
-  const grant =
-    opts.grant === undefined ? buildSelfGrant().grant : createUnresolvedGrant(opts.grant)
-  return signCredential(
-    { grant },
-    {
-      issuer: identity.issuer,
-      subject: identity.subject,
-      audience,
-      privateKey: identity.privateKey,
-      ttl: opts.ttl ?? '30m',
-    },
-  )
-}
-
-function resolveAudience(
-  audience: string | undefined,
-  defaultKernelUrl: string | undefined,
-  deps: unknown,
-): string {
-  return resolveKernelUrl(undefined, audience, defaultKernelUrl, deps)
-}
-
-function resolveKernelUrl(
-  url: string | undefined,
-  audience: string | undefined,
-  defaultKernelUrl: string | undefined,
-  deps: unknown,
-): string {
-  const env = deps as { INSTANCE_KERNEL_URL?: unknown; KERNEL_URL?: unknown } | null | undefined
-  const resolved =
-    url ?? audience ?? defaultKernelUrl ?? env?.INSTANCE_KERNEL_URL ?? env?.KERNEL_URL
-  if (typeof resolved !== 'string' || resolved.length === 0) {
-    throw new Error(
-      'fn.kernel: no kernel URL — pass one explicitly or set INSTANCE_KERNEL_URL in the ' +
-        'worker env (managed deploys set it automatically).',
-    )
-  }
-  return resolved
-}

package/src/auth/identity.ts

@@ -1,17 +0,0 @@
-/**
- * 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
-  /** Optional inbound audience when transport addressing differs from issuer. */
-  audience?: 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

@@ -1,19 +0,0 @@
-export type { RemoteIdentityConfig } from './identity.js'
-export type { VerifiedInbound } from './verify.js'
-export type { AuthenticateResult } from './authenticate.js'
-export { authenticateRequest } from './authenticate.js'
-export { resolveInboundAuth, buildAuthContext, type ResolvedAuth } from './resolve.js'
-export { verifyInboundCredential } from './verify.js'
-export { buildComposedGrant } from './compose.js'
-export { signCredential } from './sign.js'
-export { makeDomainAuthority } from './issuer-mint.js'
-export type { DomainAuthority, MintIssuedParams } from './issuer-mint.js'
-export { makeFunctionContext } from './function-context.js'
-export type {
-  FunctionContextApi,
-  FunctionCredentialOptions,
-  FunctionKernelOptions,
-} from './function-context.js'
-export { bindKernel } from './kernel-client.js'
-export { AuthMissingError, AuthInvalidError } from './errors.js'
-export { assertPerm, requireOwnership, READ, EDIT, USE, SHARE, ALL } from './check.js'

package/src/auth/issuer-mint.ts

@@ -1,76 +0,0 @@
-/**
- * Domain authority — the worker-side mint seam for identities THIS DOMAIN issues.
- *
- * A domain worker is a trusted issuer: the kernel resolves any `(iss, sub)`
- * credential signed with the worker's key back to the graph node carrying that
- * identity. That makes the worker the natural authority for the principals it
- * materializes — an App identity a workspace installs, a per-domain role
- * umbrella, a managed user. `mint` signs such a credential (optionally carrying
- * a `grant` claim with an unresolved identity expression); `sessionFor` opens a
- * kernel session presenting it, so the worker can ACT AS an identity it issues
- * (e.g. call `@<role>::mintDelegationCredential` as the role to obtain a
- * kernel-issued delegation inner).
- *
- * Scope guard: this signs under the WORKER'S OWN issuer only — it cannot forge
- * another issuer's identities. The kernel still enforces everything downstream
- * (trust of the issuer, `frozen`, grant resolution, nested-credential rules).
- */
-
-import type { FnMap } from '@astrale-os/kernel-client'
-import type { BoundClientSessionView } from '@astrale-os/kernel-client/session'
-import type { UnresolvedIdentityExpr } from '@astrale-os/kernel-core'
-
-import { createUnresolvedGrant } from '@astrale-os/kernel-core'
-
-import type { RemoteIdentityConfig } from './identity.js'
-
-import { bindCredentialSession } from './kernel-client.js'
-import { signCredential } from './sign.js'
-
-export type DomainAuthorityRef = {
-  /** The issuer ID (used as the `iss` claim in credentials and on Identity nodes). */
-  readonly iss: string
-}
-
-export type MintIssuedParams = {
-  /** The issued identity's `sub` — must match the graph node's stored subject. */
-  subject: string
-  /** The credential's audience — the kernel (or worker) it will be presented to. */
-  audience: string
-  /**
-   * Optional `grant` claim: the identity expression the credential's holder may
-   * act as (wrapped `{v:1, expr}`). Omit for a plain self-authenticating
-   * credential — the kernel falls back to a self-grant for externally-issued
-   * credentials. Nested `credential` leaves MUST be kernel-issued delegation
-   * inners (the kernel refuses non-kernel nested credentials).
-   */
-  grant?: UnresolvedIdentityExpr
-  /** JWT lifetime, jose-style (`'60s'`, `'5m'`, `'1h'`). Default `'1h'`. */
-  ttl?: string
-}
-
-export type DomainAuthority = DomainAuthorityRef & {
-  /** Sign a credential AS an identity this domain issues. */
-  mint(params: MintIssuedParams): Promise<string>
-  /**
-   * A kernel session presenting a pre-signed credential (typically from
-   * {@link DomainAuthority.mint} with `audience = kernelUrl`).
-   */
-  sessionFor(kernelUrl: string, credential: string): BoundClientSessionView<FnMap>
-}
-
-/** Build the domain authority for one worker identity config. */
-export function makeDomainAuthority(identity: RemoteIdentityConfig): DomainAuthority {
-  return {
-    iss: identity.issuer,
-    mint: ({ subject, audience, grant, ttl }) =>
-      signCredential(grant !== undefined ? { grant: createUnresolvedGrant(grant) } : {}, {
-        issuer: identity.issuer,
-        subject,
-        audience,
-        privateKey: identity.privateKey,
-        ttl: ttl ?? '1h',
-      }),
-    sessionFor: (kernelUrl, credential) => bindCredentialSession(kernelUrl, credential),
-  }
-}

package/src/auth/kernel-client.ts

@@ -1,153 +0,0 @@
-/**
- * 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 type { UnresolvedIdentityExpr } 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,
-  allowAllDelegations,
-  delegationMintVia,
-  type BoundClientSessionView,
-} from '@astrale-os/kernel-client/session'
-
-import type { RemoteIdentityConfig } from './identity.js'
-
-import { buildComposedExpr, buildComposedGrant, buildSelfExpr } from './compose.js'
-import { signCredential } from './sign.js'
-
-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 redirects mint worker-scoped delegations via AuthApi.
- */
-export async function bindKernel(
-  delegation: Delegation,
-  kernelUrl: string,
-  config: RemoteIdentityConfig,
-): Promise<BoundClientSessionView<FnMap>> {
-  return bindSession(kernelUrl, config, buildComposedGrant(delegation).grant, () =>
-    buildComposedExpr(delegation),
-  )
-}
-
-/**
- * Shared session construction: sign a credential as this function's identity
- * carrying `grant`, bind the session to it, and wire the lazy NEXT-HOP mint.
- */
-async function bindSession(
-  kernelUrl: string,
-  config: RemoteIdentityConfig,
-  grant: unknown,
-  nextHopDelegation: () => UnresolvedIdentityExpr,
-): Promise<BoundClientSessionView<FnMap>> {
-  const credential = await signCredential(
-    { grant },
-    {
-      issuer: config.issuer,
-      subject: config.subject,
-      audience: kernelUrl,
-      privateKey: config.privateKey,
-      // Long-running handlers (a managed INSTALL saga easily runs minutes on a
-      // cold box) make kernel callbacks throughout — the default 60s wall left
-      // them unable to even write their own failure records (observed live:
-      // install wedged at 'installing' forever). The session credential is
-      // per-request and aud-bound; delegated AUTHORITY still expires with the
-      // inner delegation's own exp.
-      ttl: '30m',
-    },
-  )
-
-  // The standard mint resolves the function identity through `auth.whoami()`.
-  const session: ClientSession<FnMap> = new ClientSession<FnMap>({
-    default: kernelUrl,
-    schema: getRegistry(kernelUrl),
-    pool: getPool(kernelUrl),
-    delegation: {
-      mint: delegationMintVia(
-        () => session,
-        () => credential,
-      ),
-      ttl: DELEGATION_TTL_SECONDS,
-    },
-    delegationPolicy: {
-      ...allowAllDelegations({ default: kernelUrl }),
-      delegationFor: () => nextHopDelegation(),
-    },
-  })
-  return session.as(credential)
-}
-
-/**
- * Bind a session to a PRE-SIGNED credential — no delegation mint, no composed
- * grant; the credential IS the authority. The seam behind
- * `DomainAuthority.sessionFor` (a worker acting as an identity it issues). Pool +
- * schema registry are the same per-URL caches the composed sessions use.
- */
-export function bindCredentialSession(
-  kernelUrl: string,
-  credential: string,
-  opts: { delegation?: UnresolvedIdentityExpr } = {},
-): BoundClientSessionView<FnMap> {
-  const session: ClientSession<FnMap> = new ClientSession<FnMap>({
-    default: kernelUrl,
-    schema: getRegistry(kernelUrl),
-    pool: getPool(kernelUrl),
-    delegation: {
-      mint: delegationMintVia(
-        () => session,
-        () => credential,
-      ),
-      ttl: DELEGATION_TTL_SECONDS,
-    },
-    delegationPolicy: {
-      ...allowAllDelegations({ default: kernelUrl }),
-      delegationFor: () => opts.delegation ?? buildSelfExpr(),
-    },
-  })
-  return session.as(credential)
-}

package/src/auth/resolve.ts

@@ -1,63 +0,0 @@
-/**
- * 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.js'
-import type { RemoteIdentityConfig } from './identity.js'
-
-import { authenticateRequest } from './authenticate.js'
-import { AuthInvalidError, AuthMissingError } from './errors.js'
-
-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

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