@astrale-os/cli 0.4.0-alpha.13

package/src/kernel/auth.ts

@@ -0,0 +1,234 @@
+import type { AstraleConfig } from '../lib/config'
+
+import { AuthError } from '../errors'
+import { getDefault, getIdentity, type Identity } from '../lib/identity'
+import {
+  accessTokenForAudience,
+  classifyRefreshFailure,
+  IdpAudienceMismatchError,
+} from '../lib/idp'
+import {
+  ensureFreshSession,
+  IdpSessionMissingError,
+  IdpSessionNoRefreshTokenError,
+} from '../lib/idp-session'
+import { signAs } from '../lib/keys'
+import { KEYS_DIR } from '../lib/paths'
+
+export type KeyIdentityAuthOptions = {
+  issuer: string
+  subject?: string
+  audience: string
+}
+
+/**
+ * Resolve a signed JWT credential from CLI options.
+ *
+ * The **audience** is passed in explicitly by the caller because transport URL
+ * and kernel issuer can differ for remote deployments.
+ *
+ * Three cases, in order of priority:
+ *   1. `opts.creds` — pre-signed credential, returned as-is.
+ *   2. `opts.as` — sign as a named local identity.
+ *   3. Default — sign as the active local identity. If the identity has a
+ *      registration for the target instance, use that target-issued `(iss, sub)`.
+ */
+export async function resolveCredential(
+  opts: { as?: string; creds?: string; defaultIdentity?: string },
+  config: AstraleConfig,
+  audience: string = config.issuer,
+  instanceSlug?: string,
+): Promise<string> {
+  if (opts.creds) return opts.creds
+  // Track the resolved identity so the catch block can tailor its hint: an
+  // IdP-backed identity whose session lapsed needs `astrale auth login`, not
+  // the `astrale identity create` keypair hint that suits local key identities.
+  let resolvedIdentity: Identity | undefined
+  let resolvedName: string | undefined
+  try {
+    const identityName = opts.as ?? opts.defaultIdentity
+    // Explicit `--as` wins: sign with that identity's key. When the identity
+    // has a registration record for the targeted instance (populated by
+    // `astrale identity register`), use the kernel-derived `(iss, sub)` so the
+    // JWT matches what the kernel published under its issuer store.
+    if (identityName) {
+      const identity = await getIdentity(identityName)
+      resolvedIdentity = identity
+      resolvedName = identityName
+      if ((identity.source ?? 'key') === 'idp')
+        return await resolveIdpAccessToken(identityName, identity, audience)
+      return await signAs(
+        identity.subject,
+        KEYS_DIR,
+        resolveKeyIdentityAuthOptions(identity, config, audience, instanceSlug),
+      )
+    }
+
+    const identity = await getDefault()
+    resolvedIdentity = identity
+    resolvedName = identity.name
+    if ((identity.source ?? 'key') === 'idp') {
+      return await resolveIdpAccessToken(identity.name, identity, audience)
+    }
+
+    return await signAs(
+      identity.subject,
+      KEYS_DIR,
+      resolveKeyIdentityAuthOptions(identity, config, audience, instanceSlug),
+    )
+  } catch (e) {
+    const message = e instanceof Error ? e.message : 'Failed to resolve credentials'
+    const hint = resolveCredentialHint(opts, resolvedIdentity, resolvedName, e)
+    throw new AuthError(message, hint)
+  }
+}
+
+function resolveCredentialHint(
+  opts: { as?: string; defaultIdentity?: string },
+  identity: Identity | undefined,
+  name: string | undefined,
+  error?: unknown,
+): string {
+  // Audience mismatch: the IdP minted a token for a different `aud` than the
+  // target requires (e.g. WorkOS stamps a fixed API audience and ignores the
+  // requested one). Re-login mints the *same* aud again, so don't suggest it —
+  // point at targeting an instance whose audience matches what the IdP issues.
+  if (error instanceof IdpAudienceMismatchError) {
+    return error.actual
+      ? `The IdP issues tokens for audience ${error.actual}, not the target's ${error.requested}. Target an instance whose URL/issuer is ${error.actual} (re-login won't change the audience).`
+      : `The IdP did not mint a token for the target audience ${error.requested}, and re-login won't change it. Target an instance whose audience the IdP issues, or reconfigure the bookmark/IdP.`
+  }
+  // Org-membership rejection: the session is healthy; the org we scoped the
+  // token to doesn't hold this user. Re-login can never fix it.
+  if (error instanceof IdpOrgMembershipError) {
+    return 'This instance might belong to a different account.'
+  }
+  // Transient IdP outage: the cached session is still valid — retrying is the
+  // fix, not re-login.
+  if (error instanceof IdpRefreshTransientError) {
+    return 'The IdP could not be reached. Check the network and retry — the cached session is likely still valid.'
+  }
+  // IdP-backed identities fail when the cached session expires or the upstream
+  // session is terminated (e.g. WorkOS "Session has already ended"). Re-login,
+  // don't recreate keys.
+  if (identity && (identity.source ?? 'key') === 'idp' && name) {
+    const idpFlag = identity.idp ? ` --idp ${identity.idp}` : ''
+    return `IdP session for "${name}" has expired. Run: astrale auth login --name ${name}${idpFlag}`
+  }
+  if (opts.as) {
+    return 'Check identity name. Available identities: astrale identity list'
+  }
+  if (opts.defaultIdentity) {
+    return `Check bookmark default identity "${opts.defaultIdentity}". Available identities: astrale identity list`
+  }
+  return 'Run `astrale identity create <name>` to set up keys'
+}
+
+export function resolveKeyIdentityAuthOptions(
+  identity: Identity,
+  config: AstraleConfig,
+  audience: string = config.issuer,
+  instanceSlug?: string,
+): KeyIdentityAuthOptions {
+  const registration = instanceSlug ? identity.registrations?.[instanceSlug] : undefined
+  return {
+    issuer:
+      registration?.iss ?? identity.issuer ?? systemIdentityIssuer(identity, audience, config),
+    subject: registration?.sub,
+    audience,
+  }
+}
+
+function systemIdentityIssuer(identity: Identity, audience: string, config: AstraleConfig): string {
+  // Imported kernel bootstrap keys are subject=system and are published by the
+  // target kernel's JWKS. Without a stored issuer, signing them as the
+  // placeholder CLI issuer makes the kernel try OIDC discovery for a
+  // non-resolving host — use the audience (the target kernel) instead.
+  return identity.subject === 'system' ? audience : config.issuer
+}
+
+async function resolveIdpAccessToken(
+  identityName: string,
+  identity: Identity,
+  audience: string,
+): Promise<string> {
+  let resolved
+  try {
+    resolved = await ensureFreshSession(identityName, { audience })
+  } catch (e) {
+    if (e instanceof IdpSessionMissingError) {
+      throw new Error(
+        `No cached IdP session for "${identityName}". Run: astrale auth login --idp ${identity.idp ?? '<idp>'}`,
+      )
+    }
+    if (e instanceof IdpSessionNoRefreshTokenError) {
+      throw new Error(wrongAudienceHint(identityName, identity, audience))
+    }
+    // An audience mismatch means the session is healthy but the IdP won't
+    // mint this audience — re-login is futile, so propagate it verbatim for
+    // the hint logic to handle.
+    if (e instanceof IdpAudienceMismatchError) throw e
+    throw refreshFailureError(identityName, identity, e)
+  }
+
+  const token = accessTokenForAudience(resolved, audience)
+  if (!token) {
+    throw new Error(
+      `IdP token for "${identityName}" was not minted for target audience ${audience}. ` +
+        `Run: astrale auth login --name ${identityName} --idp ${identity.idp ?? '<idp>'} --audience ${audience}`,
+    )
+  }
+
+  return token
+}
+
+/** A refresh attempt failed for a reason that re-login will NOT fix. */
+export class IdpRefreshTransientError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'IdpRefreshTransientError'
+  }
+}
+
+/** The IdP refused to scope the session to the target's organization. */
+export class IdpOrgMembershipError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'IdpOrgMembershipError'
+  }
+}
+
+function refreshFailureError(identityName: string, identity: Identity, cause: unknown): Error {
+  const reason = cause instanceof Error ? cause.message : String(cause)
+  const idpFlag = identity.idp ? ` --idp ${identity.idp}` : ''
+  // Only a definitively dead grant (invalid_grant: WorkOS idle/absolute
+  // timeout, logout elsewhere, reuse-detection revocation) warrants a
+  // re-login. Network failures and IdP 5xx leave the cached session valid —
+  // telling the user to re-login for those would burn a perfectly good
+  // session.
+  switch (classifyRefreshFailure(cause)) {
+    case 'transient':
+      return new IdpRefreshTransientError(
+        `Could not reach the IdP to refresh the session for "${identityName}" (${reason}). ` +
+          'The cached session is likely still valid — retry the command.',
+      )
+    case 'org-rejected':
+      // Healthy session, wrong org — re-login can never fix it.
+      return new IdpOrgMembershipError(
+        `The IdP refused to scope "${identityName}" to this instance's organization (${reason}).`,
+      )
+    default:
+      return new Error(
+        `IdP session for "${identityName}" could not be refreshed (${reason}). ` +
+          `The cached session has expired or ended — run: astrale auth login --name ${identityName}${idpFlag}`,
+      )
+  }
+}
+
+function wrongAudienceHint(identityName: string, identity: Identity, audience: string): string {
+  return (
+    `IdP token for "${identityName}" was not minted for target audience ${audience}, ` +
+    'and the cached session cannot be refreshed. ' +
+    `Run: astrale auth login --name ${identityName} --idp ${identity.idp ?? '<idp>'} --audience ${audience}`
+  )
+}

package/src/kernel/ca-fetch.ts

@@ -0,0 +1,119 @@
+import type { IncomingHttpHeaders, request as httpRequest } from 'node:http'
+
+import { Buffer } from 'node:buffer'
+import { readFileSync } from 'node:fs'
+import { request as httpsRequest } from 'node:https'
+
+export function fetchWithCaFile(
+  caFile: string,
+  fallback: typeof fetch = globalThis.fetch,
+): typeof fetch {
+  const ca = readFileSync(caFile)
+  const fallbackFetch = fallback.bind(globalThis)
+
+  return (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const url = requestUrl(input)
+    if (url.protocol !== 'https:') return fallbackFetch(input, init)
+    return fetchWithNode(url, init, ca)
+  }) as typeof fetch
+}
+
+function requestUrl(input: RequestInfo | URL): URL {
+  if (input instanceof URL) return input
+  if (typeof input === 'string') return new URL(input)
+  return new URL(input.url)
+}
+
+function fetchWithNode(url: URL, init: RequestInit | undefined, ca: Buffer): Promise<Response> {
+  return new Promise((resolve, reject) => {
+    const headers = headersInitToRecord(init?.headers)
+    const request = httpsRequest(
+      url,
+      {
+        method: init?.method ?? 'GET',
+        headers,
+        ca,
+      },
+      (response) => {
+        const chunks: Buffer[] = []
+        response.on('data', (chunk) =>
+          chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)),
+        )
+        response.on('end', () => {
+          resolve(
+            new Response(Buffer.concat(chunks), {
+              status: response.statusCode ?? 0,
+              statusText: response.statusMessage,
+              headers: responseHeaders(response.headers),
+            }),
+          )
+        })
+      },
+    )
+
+    request.on('error', reject)
+    if (init?.signal) {
+      if (init.signal.aborted)
+        request.destroy(new DOMException('The operation was aborted.', 'AbortError'))
+      init.signal.addEventListener(
+        'abort',
+        () => request.destroy(new DOMException('The operation was aborted.', 'AbortError')),
+        { once: true },
+      )
+    }
+
+    writeBody(request, init?.body)
+      .then(() => request.end())
+      .catch((error) => request.destroy(error))
+  })
+}
+
+async function writeBody(
+  request: ReturnType<typeof httpRequest>,
+  body: BodyInit | null | undefined,
+): Promise<void> {
+  if (body === undefined || body === null) return
+  if (typeof body === 'string') {
+    request.write(body)
+    return
+  }
+  if (body instanceof Uint8Array) {
+    request.write(body)
+    return
+  }
+  if (body instanceof ArrayBuffer) {
+    request.write(Buffer.from(body))
+    return
+  }
+  if (body instanceof Blob) {
+    request.write(Buffer.from(await body.arrayBuffer()))
+    return
+  }
+  throw new Error(`Unsupported request body type for CA-backed fetch`)
+}
+
+function headersInitToRecord(headers: HeadersInit | undefined): Record<string, string> {
+  if (!headers) return {}
+  if (headers instanceof Headers) {
+    const out: Record<string, string> = {}
+    headers.forEach((value, key) => {
+      out[key] = value
+    })
+    return out
+  }
+  if (Array.isArray(headers)) return Object.fromEntries(headers.map(([key, value]) => [key, value]))
+  return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, String(value)]))
+}
+
+function responseHeaders(headers: IncomingHttpHeaders): Headers {
+  const out = new Headers()
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === undefined) continue
+    if (Array.isArray(value)) {
+      for (const entry of value) out.append(key, entry)
+    } else {
+      out.set(key, value)
+    }
+  }
+  return out
+}

package/src/kernel/client.ts

@@ -0,0 +1,191 @@
+import { KernelClient, type FnMap } from '@astrale-os/kernel-client'
+import { ClientSession } from '@astrale-os/kernel-client/session'
+
+import type { AdminTargetCommandOpts } from '../lib/admin-target'
+import type { KernelCommandOpts } from './types'
+
+import { AstraleError } from '../errors'
+import { ADMIN_INSTANCE, type InstanceInfo } from '../lib/admin-instance'
+import { readConfig } from '../lib/config'
+import { resolveInstanceTarget, type ResolvedInstanceTarget } from '../lib/instance-target'
+import { resolveCredential } from './auth'
+import { fetchWithCaFile } from './ca-fetch'
+import { mintRemoteCredential } from './remote-routing'
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+export type ClientContext = {
+  /** High-level call surface — bound to `credential` via ClientSession.identity. */
+  client: ClientSession<FnMap>
+  credential: string
+  url: string
+  config: Awaited<ReturnType<typeof readConfig>>
+}
+
+type ResolvedKernelTarget = {
+  url: string
+  audience: string
+  slug?: string
+  defaultIdentity?: string
+  caFile?: string
+}
+
+/**
+ * Connect to a kernel instance, run `fn`, then disconnect.
+ * The new client is lazy: construction does no I/O. We only need to
+ * release sockets on the way out.
+ */
+export async function withKernelClient<T>(
+  opts: KernelCommandOpts,
+  fn: (ctx: ClientContext) => Promise<T>,
+): Promise<T> {
+  const config = await readConfig()
+  // Ad-hoc `--url` — unknown kernel. Stamp the URL itself as audience,
+  // no slug for per-instance signing.
+  let target: ResolvedKernelTarget
+  if (opts.url && !opts.instance) {
+    const resolved = await resolveInstanceTarget(
+      { source: 'url', url: opts.url },
+      { config, admin: adminLookupOpts(opts) },
+    )
+    target = resolvedToKernelTarget(resolved)
+  } else {
+    const resolved = await resolveInstanceTarget(
+      opts.instance ? { source: 'name', name: opts.instance } : { source: 'active' },
+      {
+        config,
+        admin: adminLookupOpts(opts),
+        managed: (slug) => lookupManagedInstance(slug, opts),
+      },
+    )
+    target = resolvedToKernelTarget(resolved, opts.url)
+  }
+
+  return withResolvedKernelClient(opts, config, target, fn)
+}
+
+async function lookupManagedInstance(slug: string, opts: KernelCommandOpts): Promise<InstanceInfo> {
+  return await withAdminKernelClient(
+    adminLookupOpts(opts),
+    async (ctx) => (await ctx.client.call(`${ADMIN_INSTANCE}/info`, { id: slug })) as InstanceInfo,
+  )
+}
+
+function adminLookupOpts(opts: KernelCommandOpts): KernelCommandOpts & AdminTargetCommandOpts {
+  return {
+    as: opts.as,
+    creds: opts.creds,
+    timeout: opts.timeout,
+    debug: opts.debug,
+  }
+}
+
+function resolvedToKernelTarget(
+  target: ResolvedInstanceTarget,
+  urlOverride?: string,
+): ResolvedKernelTarget {
+  return {
+    url: urlOverride ?? target.url,
+    audience: target.issuer,
+    slug: target.name,
+    defaultIdentity: target.defaultIdentity,
+    caFile: target.caFile,
+  }
+}
+
+export async function withAdminKernelClient<T>(
+  opts: KernelCommandOpts & AdminTargetCommandOpts,
+  fn: (ctx: ClientContext) => Promise<T>,
+): Promise<T> {
+  const config = await readConfig()
+  const target = await resolveInstanceTarget({ source: 'admin' }, { config, admin: opts })
+  return withResolvedKernelClient(
+    opts,
+    config,
+    {
+      url: target.url,
+      audience: target.issuer,
+      slug: target.name,
+      defaultIdentity: target.defaultIdentity,
+      caFile: target.caFile,
+    },
+    fn,
+  )
+}
+
+async function withResolvedKernelClient<T>(
+  opts: KernelCommandOpts,
+  config: Awaited<ReturnType<typeof readConfig>>,
+  target: ResolvedKernelTarget,
+  fn: (ctx: ClientContext) => Promise<T>,
+): Promise<T> {
+  const credential = await resolveCredential(
+    { ...opts, defaultIdentity: target.defaultIdentity },
+    config,
+    target.audience,
+    target.slug,
+  )
+
+  // CLI is short-lived and one-shot per command. Skip the WS upgrade
+  // (saves up to 5s on hangs) and disable HTTP retries (saves ~7s of
+  // exponential backoff on ECONNREFUSED / 5xx). The user can re-run.
+  const requestTimeout = resolveTimeoutMs(opts.timeout)
+  const fetchImpl = target.caFile ? fetchWithCaFile(target.caFile) : undefined
+  // The delegation mint references `client` lazily — it only fires on a cache
+  // miss during an actual remote call, long after this binding is initialised,
+  // so the self-reference inside the closure is safe.
+  const client: ClientSession<FnMap> = new ClientSession<FnMap>({
+    default: target.url,
+    identity: credential,
+    // Remote-bound functions redirect to a worker that verifies `aud` against
+    // its own identity. The session follows the redirect and mints a worker-
+    // scoped delegation here, for the audience the kernel carries on the
+    // redirect (`redirection.iss`, surfaced by the default iss-aware policy).
+    delegation: {
+      mint: async (audience) => ({
+        credential: await mintRemoteCredential(client, audience, credential),
+        ttl: 3600,
+      }),
+      ttl: 3600,
+    },
+    pool: {
+      clientFactory: (u) =>
+        new KernelClient<FnMap>({
+          url: u,
+          requestTimeout,
+          defaultTransport: 'http',
+          retry: { maxAttempts: 1 },
+          ...(fetchImpl ? { fetch: fetchImpl } : {}),
+        }),
+    },
+  })
+  await client.ready()
+
+  try {
+    return await fn({ client, credential, url: target.url, config })
+  } catch (error) {
+    // Attach url so formatKernelError can display it in connection errors
+    if (error instanceof Error) (error as Error & { url?: string }).url = target.url
+    throw error
+  } finally {
+    client.disconnect()
+  }
+}
+
+function resolveTimeoutMs(raw: string | undefined): number {
+  if (raw === undefined) return DEFAULT_TIMEOUT_MS
+  if (!/^\d+$/.test(raw)) {
+    throw new AstraleError(
+      'INVALID_FLAG',
+      `Invalid --timeout value "${raw}" — expected a positive integer (milliseconds)`,
+    )
+  }
+  const n = Number.parseInt(raw, 10)
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new AstraleError(
+      'INVALID_FLAG',
+      `Invalid --timeout value "${raw}" — must be a positive integer`,
+    )
+  }
+  return n
+}