@astrale-os/cli 1.0.0-beta.9 → 1.0.0-npm-deprecated.0

package/src/connection/exchange.ts

@@ -1,311 +0,0 @@
-import type { IssuerId } from '@astrale-os/sdk/auth'
-import type { Fetch } from '@astrale-os/sdk/client'
-
-import { createAuth } from '@astrale-os/sdk/auth'
-import { credential, exchange as exchangeProtocol } from '@astrale-os/sdk/auth'
-import { call, Client } from '@astrale-os/sdk/client'
-
-import type { SourceCredentialResolver } from './credential'
-import type { ConnectionTarget } from './target'
-
-import { AstraleError } from '../errors'
-import { ExchangeCredentialCache } from '../state/exchange-credentials'
-
-const EXCHANGE_TTL_SECONDS = 120
-const MAXIMUM_RESPONSE_BYTES = 256 * 1024
-
-/** Exchange exact authenticated User authority for a Domain bearer bound to this Kernel. */
-export function createExchangeCredentialResolver(
-  target: ConnectionTarget & { readonly domainIssuer: IssuerId },
-  source: SourceCredentialResolver,
-  fetch: Fetch,
-  timeoutMs: number,
-  cache = new ExchangeCredentialCache(),
-): SourceCredentialResolver {
-  requireExchangeTransport(target)
-  return Object.freeze({
-    async resolve(kernelIssuer: IssuerId, signal: AbortSignal): Promise<string> {
-      requireLive(signal)
-      const sourceToken = await source.resolve(kernelIssuer, signal)
-      const delegationTtlSeconds = delegationLifetime(sourceToken)
-      requireLive(signal)
-
-      const client = new Client({ url: `${kernelIssuer}/invoke`, fetch, timeoutMs })
-      try {
-        const authenticated = client.as(sourceToken)
-        const auth = createAuth(async (path, input, options) => {
-          const result = await authenticated.call(call(path, input), {
-            ...options,
-            delegate: { ttlSeconds: delegationTtlSeconds },
-          })
-          return result.value
-        })
-        const user = await auth.whoami({ signal })
-        const key = Object.freeze({
-          kernelIssuer,
-          domainIssuer: target.domainIssuer,
-          user: user.id,
-        })
-        return await cache.getOrRefresh(key, async () => {
-          let envelope: string | undefined
-          for (let attempt = 0; attempt < 3; attempt += 1) {
-            try {
-              envelope = await auth.delegate(
-                user.id,
-                {
-                  audience: target.domainIssuer,
-                  ttlSeconds: delegationTtlSeconds,
-                  attenuation: { kind: 'identity', self: true },
-                },
-                { signal },
-              )
-              break
-            } catch (cause) {
-              if (attempt === 2 || !unknownFunctionOutcome(cause)) throw cause
-            }
-          }
-          if (envelope === undefined) throw new Error('Token delegation returned no credential.')
-          return exchange(target.domainIssuer, kernelIssuer, envelope, fetch, signal)
-        })
-      } finally {
-        client.close()
-      }
-    },
-  })
-}
-
-function unknownFunctionOutcome(cause: unknown): boolean {
-  if (cause === null || typeof cause !== 'object') return false
-  const error = cause as { readonly code?: unknown; readonly reason?: unknown }
-  if (error.code === 5002) return true
-  if (error.reason === null || typeof error.reason !== 'object') return false
-  return (error.reason as { readonly code?: unknown }).code === 'FUNCTION_OUTCOME_UNKNOWN'
-}
-
-function delegationLifetime(sourceToken: string): number {
-  const expiresAt = credential.inspect(sourceToken).claims.exp
-  if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt)) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_SOURCE_INVALID',
-      'The source identity credential has no valid expiration.',
-    )
-  }
-  const remaining = expiresAt - Math.ceil(Date.now() / 1_000) - 1
-  if (!Number.isSafeInteger(remaining) || remaining < 1) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_SOURCE_EXPIRED',
-      'The source identity credential has no lifetime available for token exchange.',
-    )
-  }
-  return Math.min(EXCHANGE_TTL_SECONDS, remaining)
-}
-
-async function exchange(
-  domainIssuer: IssuerId,
-  kernelIssuer: IssuerId,
-  envelope: string,
-  fetch: Fetch,
-  signal: AbortSignal,
-): Promise<{ readonly credential: string; readonly expiresAt: number }> {
-  const configurationUrl = new URL(
-    exchangeProtocol.paths(domainIssuer).configuration,
-    domainIssuer,
-  ).toString()
-  const configurationResponse = await fetchExchange(
-    fetch,
-    configurationUrl,
-    {
-      method: 'GET',
-      redirect: 'error',
-      credentials: 'omit',
-      cache: 'no-store',
-      referrerPolicy: 'no-referrer',
-      headers: { accept: 'application/json' },
-      signal,
-    },
-    'Domain issuer discovery could not be reached.',
-  )
-  if (!configurationResponse.ok) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_DISCOVERY_FAILED',
-      `Domain issuer discovery failed with HTTP ${configurationResponse.status}.`,
-    )
-  }
-  const configuration = exchangeProtocol.acceptConfiguration(
-    await boundedJson(configurationResponse, signal),
-    domainIssuer,
-  )
-  const endpoint = configuration.token_exchange_endpoint
-  if (endpoint === undefined) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_UNSUPPORTED',
-      `Domain issuer ${domainIssuer} does not advertise token exchange.`,
-      'This command has no legacy token fallback.',
-    )
-  }
-
-  const response = await fetchExchange(
-    fetch,
-    endpoint,
-    {
-      method: 'POST',
-      redirect: 'error',
-      credentials: 'omit',
-      cache: 'no-store',
-      referrerPolicy: 'no-referrer',
-      headers: {
-        authorization: `Bearer ${envelope}`,
-        accept: exchangeProtocol.MEDIA_TYPE,
-      },
-      signal,
-    },
-    'Domain token exchange could not be reached.',
-  )
-  const body = await boundedJson(response, signal)
-  if (!response.ok) {
-    let admitted: exchangeProtocol.ErrorResponse
-    try {
-      admitted = exchangeProtocol.acceptErrorResponse(body)
-    } catch (cause) {
-      if (!(cause instanceof TypeError)) throw cause
-      throw new AstraleError(
-        'TOKEN_EXCHANGE_PROTOCOL_ERROR',
-        `Token exchange failed with HTTP ${response.status} and an invalid error response.`,
-        cause instanceof Error ? cause.message : undefined,
-      )
-    }
-    throw new AstraleError(String(admitted.error.code), admitted.error.message)
-  }
-  requireExchangeResponseHeaders(response)
-  let exchanged: exchangeProtocol.Response
-  let inspected: ReturnType<typeof credential.inspect>
-  try {
-    exchanged = exchangeProtocol.acceptResponse(body)
-    inspected = credential.inspect(exchanged.token)
-  } catch (cause) {
-    if (!(cause instanceof TypeError)) throw cause
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
-      'Token exchange returned an invalid success response.',
-      cause.message,
-    )
-  }
-  if (
-    inspected.iss !== domainIssuer ||
-    inspected.aud !== kernelIssuer ||
-    inspected.claims.exp !== exchanged.expiresAt
-  ) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
-      'Token exchange returned a credential inconsistent with the requested Domain and Kernel.',
-    )
-  }
-  return Object.freeze({ credential: exchanged.token, expiresAt: exchanged.expiresAt })
-}
-
-async function fetchExchange(
-  fetch: Fetch,
-  input: string,
-  init: RequestInit,
-  message: string,
-): Promise<Response> {
-  try {
-    return await fetch(input, init)
-  } catch (cause) {
-    if (init.signal?.aborted) throw cause
-    throw new AstraleError('TOKEN_EXCHANGE_UNAVAILABLE', message, undefined, { cause })
-  }
-}
-
-function requireExchangeTransport(
-  target: ConnectionTarget & { readonly domainIssuer: IssuerId },
-): void {
-  const kernel = new URL(target.kernelIssuer)
-  const domain = new URL(target.domainIssuer)
-  if (domain.protocol === 'https:') return
-  if (domain.protocol === 'http:' && kernel.protocol === 'http:') return
-  throw new AstraleError(
-    'TOKEN_EXCHANGE_INSECURE',
-    'An HTTP Domain issuer is allowed only with an explicitly configured HTTP Kernel target.',
-  )
-}
-
-function requireExchangeResponseHeaders(response: Response): void {
-  const contentType = response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
-  if (contentType !== exchangeProtocol.MEDIA_TYPE) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
-      'Token exchange returned an unsupported Content-Type.',
-    )
-  }
-  if (
-    !response.headers
-      .get('cache-control')
-      ?.toLowerCase()
-      .split(',')
-      .some((v) => v.trim() === 'no-store')
-  ) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
-      'Token exchange response is missing Cache-Control: no-store.',
-    )
-  }
-}
-
-async function boundedJson(response: Response, signal: AbortSignal): Promise<unknown> {
-  const declared = response.headers.get('content-length')
-  if (
-    declared !== null &&
-    (!/^\d+$/u.test(declared) || Number(declared) > MAXIMUM_RESPONSE_BYTES)
-  ) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
-      'Issuer response exceeds the size limit.',
-    )
-  }
-  if (response.body === null) {
-    throw new AstraleError('TOKEN_EXCHANGE_PROTOCOL_ERROR', 'Issuer response body is missing.')
-  }
-  const reader = response.body.getReader()
-  const chunks: Uint8Array[] = []
-  let size = 0
-  try {
-    for (;;) {
-      requireLive(signal)
-      const next = await reader.read()
-      if (next.done) break
-      size += next.value.byteLength
-      if (size > MAXIMUM_RESPONSE_BYTES) {
-        throw new AstraleError(
-          'TOKEN_EXCHANGE_PROTOCOL_ERROR',
-          'Issuer response exceeds the size limit.',
-        )
-      }
-      chunks.push(next.value)
-    }
-  } finally {
-    reader.releaseLock()
-  }
-  const bytes = new Uint8Array(size)
-  let offset = 0
-  for (const chunk of chunks) {
-    bytes.set(chunk, offset)
-    offset += chunk.byteLength
-  }
-  try {
-    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)) as unknown
-  } catch (cause) {
-    throw new AstraleError(
-      'TOKEN_EXCHANGE_PROTOCOL_ERROR',
-      'Issuer response is not valid UTF-8 JSON.',
-      cause instanceof Error ? cause.message : undefined,
-    )
-  }
-}
-
-function requireLive(signal: AbortSignal): void {
-  if (!signal.aborted) return
-  throw signal.reason instanceof Error
-    ? signal.reason
-    : new DOMException('The operation was aborted.', 'AbortError')
-}

package/src/connection/failure/classify.ts

@@ -1,110 +0,0 @@
-import { AuthValueError } from '@astrale-os/sdk/auth'
-import { ClientError, ProtocolError, ResponseError, TransportError } from '@astrale-os/sdk/client'
-import { NodeUnavailableError } from '@astrale-os/sdk/client'
-import { PathError } from '@astrale-os/sdk/graph/path'
-
-import type { FailureDiagnostic, TransportDiagnosticContext } from './model'
-
-import { AstraleError } from '../../errors'
-
-export function classifyFailure(error: unknown): FailureDiagnostic {
-  if (error instanceof AstraleError) return simple(error.code, error.message, error.hint)
-  if (error instanceof TransportError) {
-    const context = transportContext(error)
-    if (context === undefined) return simple('TRANSPORT_ERROR', error.message)
-    return {
-      kind: 'transport',
-      code: lifecycleCode(error.phase),
-      message: error.message,
-      phase: error.phase,
-      context,
-    }
-  }
-  if (error instanceof ResponseError) {
-    return {
-      kind: 'response',
-      code: error.code,
-      message: error.message,
-      ...(error.reason === undefined ? {} : { reason: error.reason }),
-    }
-  }
-  if (error instanceof ClientError) {
-    const failure = sessionFailure(error)
-    if (failure !== undefined) return simple(lifecycleCode(failure), error.message)
-  }
-  if (error instanceof ProtocolError) return simple('PROTOCOL_ERROR', error.message)
-  if (error instanceof NodeUnavailableError)
-    return simple(
-      'NODE_UNAVAILABLE',
-      error.message,
-      'If this is a callable Path, use `astrale call` or `astrale introspect`.',
-    )
-  if (error instanceof PathError) return simple('PATH_INVALID', error.message)
-  if (error instanceof AuthValueError) return simple('AUTH_VALUE_INVALID', error.message)
-  if (error instanceof ClientError) return simple('CLIENT_ERROR', error.message)
-  return simple('UNEXPECTED_ERROR', 'The CLI encountered an unexpected internal failure.')
-}
-
-type TransportCode = Extract<FailureDiagnostic, { kind: 'transport' }>['code']
-type SessionFailure = 'cancelled' | 'closed' | 'timeout'
-
-function lifecycleCode(value: TransportError['phase']): TransportCode
-function lifecycleCode(value: SessionFailure): string
-function lifecycleCode(value: TransportError['phase'] | SessionFailure): string {
-  if (value === 'connect') return 'CONNECTION_ERROR'
-  if (value === 'timeout') return 'TIMEOUT'
-  if (value === 'closed') return 'DISCONNECTED'
-  return value === 'cancelled' ? 'CANCELLED' : 'TRANSPORT_ERROR'
-}
-
-function transportContext(error: TransportError): TransportDiagnosticContext | undefined {
-  const evidence = error as TransportError & {
-    readonly context?: unknown
-    readonly delivery?: unknown
-    readonly invocation?: unknown
-  }
-  if (record(evidence.context)) {
-    if (
-      evidence.context.kind === 'acquisition' &&
-      (evidence.context.resource === 'publication' || evidence.context.resource === 'bundle')
-    ) {
-      return { kind: 'acquisition', resource: evidence.context.resource }
-    }
-    if (
-      evidence.context.kind === 'invocation' &&
-      (evidence.context.delivery === 'not-sent' || evidence.context.delivery === 'unknown')
-    ) {
-      return {
-        kind: 'invocation',
-        delivery: evidence.context.delivery,
-        ...(evidence.context.invocation === undefined
-          ? {}
-          : { invocation: evidence.context.invocation }),
-      }
-    }
-  }
-  if (evidence.delivery !== 'not-sent' && evidence.delivery !== 'unknown') return undefined
-  return {
-    kind: 'invocation',
-    delivery: evidence.delivery,
-    ...(evidence.invocation === undefined ? {} : { invocation: evidence.invocation }),
-  }
-}
-
-function sessionFailure(error: ClientError): SessionFailure | undefined {
-  const failure = (error as ClientError & { readonly failure?: unknown }).failure
-  return failure === 'cancelled' || failure === 'closed' || failure === 'timeout'
-    ? failure
-    : undefined
-}
-
-function record(input: unknown): input is Readonly<Record<string, unknown>> {
-  return input !== null && typeof input === 'object' && !Array.isArray(input)
-}
-
-const simple = (code: string, message: string, hint?: string): FailureDiagnostic => ({
-  kind: 'simple',
-  code,
-  message,
-  ...(hint === undefined ? {} : { hint }),
-})

package/src/connection/failure/index.ts

@@ -1,18 +0,0 @@
-import type { OperationRecovery } from '../command'
-
-import { printFailureDebug } from '../../lib/failure-debug'
-import { classifyFailure } from './classify'
-import { renderFailure } from './render'
-
-export { functionInputIssues, schemaUpgradeHint } from '../reasons'
-
-export async function formatKernelError(
-  error: unknown,
-  machine: boolean,
-  urlArg = '',
-  debug = false,
-  options: { recovery?: OperationRecovery } = {},
-): Promise<void> {
-  renderFailure(classifyFailure(error), machine, urlArg, options.recovery)
-  if (debug) printFailureDebug(error, urlArg)
-}

package/src/connection/failure/model.ts

@@ -1,28 +0,0 @@
-export type TransportDiagnosticContext =
-  | { readonly kind: 'acquisition'; readonly resource: 'publication' | 'bundle' }
-  | {
-      readonly kind: 'invocation'
-      readonly delivery: 'not-sent' | 'unknown'
-      readonly invocation?: unknown
-    }
-
-export type FailureDiagnostic =
-  | {
-      readonly kind: 'simple'
-      readonly code: string
-      readonly message: string
-      readonly hint?: string
-    }
-  | {
-      readonly kind: 'response'
-      readonly code: number
-      readonly message: string
-      readonly reason?: unknown
-    }
-  | {
-      readonly kind: 'transport'
-      readonly code: 'CONNECTION_ERROR' | 'DISCONNECTED' | 'TIMEOUT' | 'TRANSPORT_ERROR'
-      readonly message: string
-      readonly phase: string
-      readonly context: TransportDiagnosticContext
-    }

package/src/connection/failure/render.ts

@@ -1,116 +0,0 @@
-import chalk from 'chalk'
-
-import type { OperationRecovery } from '../command'
-import type { FailureDiagnostic } from './model'
-
-import { log } from '../../lib/log'
-import {
-  functionInputIssues,
-  queryInputRepair,
-  reasonCode,
-  schemaDataRemovalHint,
-  schemaUpgradeDetails,
-  schemaUpgradeHint,
-} from '../reasons'
-
-export function renderFailure(
-  failure: FailureDiagnostic,
-  machine: boolean,
-  url: string,
-  recovery: OperationRecovery | undefined,
-): void {
-  if (failure.kind === 'transport') return renderTransport(failure, machine, url, recovery)
-  if (failure.kind === 'response') return renderResponse(failure, machine)
-  if (machine)
-    return writeRaw({ error: failure.code, message: failure.message, hint: failure.hint })
-  log.error(`${chalk.bold(failure.code)}: ${failure.message}`)
-  if (failure.hint) log.dim(`  ${failure.hint}`)
-}
-
-function renderTransport(
-  failure: Extract<FailureDiagnostic, { kind: 'transport' }>,
-  machine: boolean,
-  url: string,
-  recovery: OperationRecovery | undefined,
-): void {
-  const invocation = failure.context.kind === 'invocation' ? failure.context : undefined
-  if (machine) {
-    writeRaw({
-      error: failure.code,
-      message: failure.message,
-      phase: failure.phase,
-      transport: failure.context,
-      ...(url === '' ? {} : { url }),
-      ...(invocation?.delivery === 'unknown' && recovery !== undefined ? recovery : {}),
-    })
-    return
-  }
-  log.error(`${chalk.bold(failure.code)}: ${failure.message}`)
-  if (url) log.dim(`  target: ${url}`)
-  log.dim(`  phase: ${failure.phase}`)
-  if (failure.phase === 'connect') log.dim('  Check the target and run `astrale status`.')
-  else if (failure.phase === 'timeout') log.dim('  Try increasing `--timeout`.')
-  else if (invocation?.delivery === 'unknown') renderRecovery(recovery)
-}
-
-function renderResponse(
-  failure: Extract<FailureDiagnostic, { kind: 'response' }>,
-  machine: boolean,
-): void {
-  const code = reasonCode(failure.reason)
-  const issues = functionInputIssues(failure.reason)
-  const removalHint = schemaDataRemovalHint(failure.reason)
-  const addressNotPublic = code === 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
-  const upgrade = schemaUpgradeDetails(failure.reason)
-  const message = addressNotPublic
-    ? 'Expose the Domain through a public HTTPS URL or public tunnel, then retry.'
-    : removalHint && !machine
-      ? 'Existing business data still uses schema definitions being removed.'
-      : failure.message
-  const hint =
-    code === 'FUNCTION_INPUT_INVALID' && (machine || issues.length === 0)
-      ? 'Use `astrale introspect <path>` to see the callable input.'
-      : (removalHint ?? (upgrade ? schemaUpgradeHint(upgrade) : undefined))
-  if (machine) {
-    writeRaw({
-      error: 'RESPONSE_ERROR',
-      code: failure.code,
-      message,
-      ...(failure.reason === undefined ? {} : { reason: failure.reason }),
-      ...(hint === undefined ? {} : { hint }),
-    })
-    return
-  }
-  const label = addressNotPublic
-    ? 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
-    : removalHint
-      ? 'DATA_MIGRATION_REQUIRED'
-      : `RESPONSE_ERROR(${failure.code})`
-  log.error(`${chalk.bold(label)}: ${message}`)
-  if (code && !addressNotPublic && !removalHint) log.dim(`  reason: ${code}`)
-  for (const issue of issues)
-    console.log(
-      chalk.red(`  ${issue.path || '<input>'}: ${issue.message} (${chalk.dim(issue.code)})`),
-    )
-  const repair = queryInputRepair(failure.reason)
-  if (repair?.phase === 'plan') log.dim(`  ${repair.path ?? '/'}  ${repair.issue}`)
-  else if (repair?.phase === 'limit')
-    log.dim(`  ${repair.path ?? '/'}  ${repair.limit} limit ${repair.actual}/${repair.maximum}`)
-  else if (repair) log.dim(`  ${repair.path}  ${repair.phase} input`)
-  if (upgrade?.issue === 'issuer-changed') {
-    log.dim(`  installed issuer: ${upgrade.installedIssuer}`)
-    log.dim(`  replacement issuer: ${upgrade.replacementIssuer}`)
-  }
-  if (hint) log.dim(`  ${hint}`)
-}
-
-function renderRecovery(recovery: OperationRecovery | undefined): void {
-  if (!recovery)
-    return log.dim('  Delivery is unknown; do not automatically retry a mutating call.')
-  log.dim('  Delivery is unknown; retry with the same operation id:')
-  log.dim(`  operation: ${recovery.operation}`)
-  log.dim(`  ${recovery.retry}`)
-}
-
-const writeRaw = (payload: Record<string, unknown>): void =>
-  void process.stderr.write(`${JSON.stringify(payload)}\n`)

package/src/connection/index.ts

@@ -1,8 +0,0 @@
-export { createPathCall } from './call'
-export { runKernelCommand } from './command'
-export type { KernelCommandOpts, OperationRecovery } from './command'
-export { expandSelfInCall, expandSelfInPath, withSelfHint } from './self'
-export type { SelfExpansionMeta } from './self'
-export { withAdminClientSession, withClientSession, type ConnectionContext } from './session'
-export { registrationKeyForTarget } from './target'
-export type { AdminConnectionOptions, ConnectionOptions, ConnectionTarget } from './target'