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

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)
-}

package/src/auth/verify.ts

@@ -1,199 +0,0 @@
-/**
- * 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,
-  SignatureVerificationError,
-  SigningKeyNotFoundError,
-  verifyAudience,
-  verifyCredential,
-} from '@astrale-os/kernel-core'
-import { createLocalJWKSet, createRemoteJWKSet, type JWK } from 'jose'
-
-import type { RemoteIdentityConfig } from './identity.js'
-
-import { derivePublicJwk } from '../server/jwks.js'
-import { canonicalizeServingUrl } from '../server/serving-url.js'
-
-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())
-
-// JWKS resolvers cached per JWKS URL (module-level, like the pools/selfIds
-// Maps in kernel-client.ts). jose handles freshness WITHIN a resolver: 10min
-// max-age, 30s fetch cooldown, and auto-refetch on kid-miss when not cooling
-// down. The one gap — issuer restarts with new keys while the cooldown pins
-// the old set (the incident that got a prior indefinite cache removed) — is
-// covered by evict-and-retry-once in `verifyInboundCredential`, so indefinite
-// Map residency is safe and the per-call JWKS fetch is gone.
-const remoteResolvers = new Map<string, ReturnType<typeof createRemoteJWKSet>>()
-
-// Self-issued credentials verify against the worker's own in-memory key;
-// cache the local JWKS per canonical self-issuer (one key per worker) so the
-// public-JWK derivation isn't redone on every request.
-const localResolvers = new Map<string, ReturnType<typeof createLocalJWKSet>>()
-
-/** Clear cached JWKS resolvers. Used in tests when keys rotate between fixtures. */
-export function clearJwksCache(): void {
-  remoteResolvers.clear()
-  localResolvers.clear()
-}
-
-/**
- * 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.
- */
-function jwksUrlFor(issuer: string): string {
-  const normalized = /^https?:\/\//.test(issuer) ? issuer : `https://${issuer}`
-  return `${normalized}/.well-known/jwks.json`
-}
-
-function getRemoteResolver(jwksUrl: string): ReturnType<typeof createRemoteJWKSet> {
-  let resolver = remoteResolvers.get(jwksUrl)
-  if (!resolver) {
-    resolver = createRemoteJWKSet(new URL(jwksUrl))
-    remoteResolvers.set(jwksUrl, resolver)
-  }
-  return resolver
-}
-
-function getLocalResolver(
-  selfIssuer: string,
-  privateKey: RemoteIdentityConfig['privateKey'],
-): ReturnType<typeof createLocalJWKSet> {
-  let resolver = localResolvers.get(selfIssuer)
-  if (!resolver) {
-    resolver = createLocalJWKSet({ keys: [derivePublicJwk(privateKey) as JWK] })
-    localResolvers.set(selfIssuer, resolver)
-  }
-  return resolver
-}
-
-/**
- * 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 via the cached per-URL JWKS resolvers above; every JWKS
- * URL touched is recorded in `resolvedJwksUrls` so the caller can evict
- * exactly those resolvers if verification fails on an unknown signing key.
- */
-function makeResolveKeys(config: RemoteIdentityConfig, resolvedJwksUrls: Set<string>) {
-  // 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)
-
-  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 getLocalResolver(selfIssuer, config.privateKey)
-      }
-    }
-
-    const jwksUrl = jwksUrlFor(url)
-    resolvedJwksUrls.add(jwksUrl)
-    return getRemoteResolver(jwksUrl)
-  }
-}
-
-/**
- * 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 resolvedJwksUrls = new Set<string>()
-  const deps = { methodResolver, resolveKeys: makeResolveKeys(config, resolvedJwksUrls) }
-  let verified: VerifiedCredential
-  try {
-    verified = await verifyCredential(deps, credential)
-  } catch (error) {
-    // A cached resolver can hold a stale key set after the issuer rotates:
-    //  - new kid → jose kid-misses but its 30s fetch cooldown blocks the
-    //    refetch (SigningKeyNotFoundError) — the incident that got a prior
-    //    indefinite cache removed;
-    //  - SAME kid, new key material (kernel kids derive from the subject, so
-    //    a re-keyed issuer reuses its kid) → the signature check fails
-    //    (SignatureVerificationError).
-    // Both: evict the resolver(s) this verification touched and retry ONCE
-    // with fresh ones. Forged-token spam thus costs at most one JWKS fetch
-    // per bad credential — equal to the uncached per-call baseline, never
-    // worse. An empty set means self-issued — refetching can't help, rethrow.
-    const staleKeySuspect =
-      error instanceof SigningKeyNotFoundError || error instanceof SignatureVerificationError
-    if (!staleKeySuspect || resolvedJwksUrls.size === 0) throw error
-    for (const url of resolvedJwksUrls) remoteResolvers.delete(url)
-    verified = await verifyCredential(deps, credential)
-  }
-
-  // Validate audience matches this function's issuer (its serving URL).
-  // kernel-core's verifyAudience compares canonically.
-  verifyAudience(verified, (config.audience ?? 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/cli/bin.ts

@@ -1,15 +0,0 @@
-#!/usr/bin/env bun
-/**
- * `astrale-domain` bin entry. Runs under bun (native TS) so it can import the
- * project's `astrale.config.ts` directly — matching the `astrale` CLI.
- */
-
-import { run } from './run.js'
-
-run(process.argv.slice(2))
-  .then((code) => process.exit(code))
-  .catch((err: unknown) => {
-    process.stderr.write(`\x1b[31m✗\x1b[0m ${(err as Error).message ?? String(err)}\n`)
-    if (process.env.DEBUG) process.stderr.write(`${(err as Error).stack ?? ''}\n`)
-    process.exit(1)
-  })

package/src/cli/dotenv.ts

@@ -1,65 +0,0 @@
-/**
- * Minimal dotenv parser — the secrets-file boundary.
- *
- * `secrets: '.env.<env>'` in an adapter's params points a gitignored file whose
- * entire contents are secrets. `loadDotenvFile` reads it into a flat
- * `Record<string,string>` the CLI hands the adapter (injected into the local
- * runtime in dev, pushed to a secret store in prod). No `process.env` mutation,
- * no interpolation magic beyond `${VAR}` against earlier keys in the same file.
- */
-
-import { readFileSync } from 'node:fs'
-
-export function parseDotenv(contents: string): Record<string, string> {
-  const out: Record<string, string> = {}
-  for (const raw of contents.split('\n')) {
-    const line = raw.trim()
-    if (!line || line.startsWith('#')) continue
-    const match = /^(?:export\s+)?([A-Za-z_]\w*)\s*=\s*(.*)$/.exec(line)
-    if (!match) continue
-    const [, key, rawValue] = match
-    let value = rawValue.trim()
-    // Single quotes mean a LITERAL value (standard dotenv): no `${VAR}`
-    // interpolation, so a secret that legitimately contains a literal `${...}`
-    // (e.g. a password) survives intact instead of being silently blanked.
-    const singleQuoted = value.length >= 2 && value.startsWith("'") && value.endsWith("'")
-    if ((value.length >= 2 && value.startsWith('"') && value.endsWith('"')) || singleQuoted) {
-      value = value.slice(1, -1)
-    }
-    out[key] = singleQuoted
-      ? value
-      : value.replace(/\$\{(\w+)\}/g, (_, name: string) => out[name] ?? '')
-  }
-  return out
-}
-
-/** Read + parse a dotenv file. Returns `{}` if the file is absent (CI-safe). */
-export function loadDotenvFile(path: string): Record<string, string> {
-  let contents: string
-  try {
-    contents = readFileSync(path, 'utf-8')
-  } catch {
-    return {}
-  }
-  return parseDotenv(contents)
-}
-
-/**
- * Read + parse a dotenv file the preset explicitly DECLARED (`secrets:`).
- * Declared-but-absent is a wiring error (the gitignored file was never created
- * on this machine), so it throws instead of loading `{}` — silently forwarding
- * nothing surfaces much later as an empty credential at the provider. A file
- * that exists but holds no keys is legitimate (a domain with no secrets yet).
- */
-export function loadDeclaredSecrets(path: string, declaration: string): Record<string, string> {
-  let contents: string
-  try {
-    contents = readFileSync(path, 'utf-8')
-  } catch {
-    throw new Error(
-      `Secrets file '${declaration}' is declared in the preset but missing at ${path}. ` +
-        `Create it (it may be empty) or remove 'secrets:' from the preset.`,
-    )
-  }
-  return parseDotenv(contents)
-}

package/src/cli/index.ts

@@ -1,15 +0,0 @@
-/**
- * `@astrale-os/sdk/cli` — the `astrale-domain` CLI (dev | build | deploy) and
- * the dotenv secrets-file boundary, folded in from the former
- * `@astrale-os/devkit` package.
- *
- * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
- * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
- * deliberately NOT re-exported from the package barrel — pulling it into the
- * isomorphic `.` entry would poison browser/worker bundlers that traverse every
- * re-export (the same rule that keeps `./server` and `./deploy` off the barrel).
- * The bin lives at `./bin`.
- */
-
-export { run, parseArgs } from './run.js'
-export { parseDotenv, loadDotenvFile, loadDeclaredSecrets } from './dotenv.js'

package/src/cli/log.ts

@@ -1,18 +0,0 @@
-/** CLI output helpers + ANSI colours, shared by run.ts and publish.ts. */
-
-export const GREEN = '\x1b[32m'
-export const DIM = '\x1b[2m'
-export const BOLD = '\x1b[1m'
-export const YELLOW = '\x1b[33m'
-export const RED = '\x1b[31m'
-export const RESET = '\x1b[0m'
-
-export function info(msg: string): void {
-  process.stdout.write(`${DIM}›${RESET} ${msg}\n`)
-}
-export function warn(msg: string): void {
-  process.stderr.write(`${YELLOW}!${RESET} ${msg}\n`)
-}
-export function error(msg: string): void {
-  process.stderr.write(`${RED}✗${RESET} ${msg}\n`)
-}