@astrale-os/cli 0.8.1-alpha.5 → 0.8.1-alpha.7

package/src/connection/__tests__/exchange.test.ts

@@ -158,9 +158,44 @@ describe('Domain token exchange', () => {
       code: 'TOKEN_EXCHANGE_PROTOCOL_ERROR',
     })
   })
+
+  test('rejects success responses without no-store or with malformed fields', async () => {
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', EXPIRES_AT)
+    const cache = () => new ExchangeCredentialCache(join(directory, crypto.randomUUID()))
+    const resolver = (fetch: Fetch) =>
+      createExchangeCredentialResolver(
+        TARGET,
+        { resolve: async () => SOURCE_TOKEN },
+        fetch,
+        5_000,
+        cache(),
+      )
+
+    await expect(
+      resolver(exchangeFetch(exchanged, { cacheControl: false })).resolve(
+        KERNEL,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      message: 'Token exchange response is missing Cache-Control: no-store.',
+    })
+    await expect(
+      resolver(exchangeFetch(exchanged, { body: { token: 7, expiresAt: 'soon' } })).resolve(
+        KERNEL,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+      message: 'Token exchange returned an invalid success response.',
+    })
+  })
 })
 
-function exchangeFetch(exchanged: string): Fetch {
+function exchangeFetch(
+  exchanged: string,
+  options: { readonly body?: unknown; readonly cacheControl?: boolean } = {},
+): Fetch {
   return async (input, init) => {
     const url = String(input)
     if (url === INVOCATION) {
@@ -174,11 +209,17 @@ function exchangeFetch(exchanged: string): Fetch {
       )
     }
     if (url.endsWith('/.well-known/openid-configuration')) return jsonResponse(configuration(true))
-    return jsonResponse(
-      { token: exchanged, expiresAt: EXPIRES_AT },
-      200,
-      'application/vnd.astrale+json',
+    const response = new Response(
+      JSON.stringify(options.body ?? { token: exchanged, expiresAt: EXPIRES_AT }),
+      {
+        status: 200,
+        headers: {
+          'content-type': 'application/vnd.astrale+json',
+          ...(options.cacheControl === false ? {} : { 'cache-control': 'no-store' }),
+        },
+      },
     )
+    return response
   }
 }
 

package/src/connection/__tests__/reasons.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test'
+
+import { functionInputIssues, queryInputRepair } from '../reasons'
+
+describe('public reason presentation admission', () => {
+  /** @evidence TEST-CLI-CONNECTION-ADMITS-BOUNDED-REASONS */
+  test('admits bounded public callable issues and filters unsafe additions', () => {
+    expect(
+      functionInputIssues({
+        code: 'FUNCTION_INPUT_INVALID',
+        details: {
+          issues: [
+            {
+              code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+              path: '/issuer',
+              message: 'Object is missing required property issuer.',
+            },
+            {
+              code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+              path: '/slug',
+              message: 'Object is missing required property slug.',
+            },
+            {
+              code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+              path: '/unsafe',
+              message: 'private\ndiagnostic',
+            },
+          ],
+        },
+      }),
+    ).toEqual([
+      {
+        code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+        path: '/issuer',
+        message: 'Object is missing required property issuer.',
+      },
+      {
+        code: 'VALUE_SCHEMA_INSTANCE_INVALID',
+        path: '/slug',
+        message: 'Object is missing required property slug.',
+      },
+    ])
+  })
+
+  test('admits exact Query repair variants and rejects unbounded additions', () => {
+    expect(
+      queryInputRepair({
+        code: 'QUERY_INPUT_INVALID',
+        details: {
+          phase: 'plan',
+          issue: 'QUERY_DEFINITION_NOT_EDGE',
+          path: '/steps/0/via/0',
+        },
+      }),
+    ).toEqual({
+      phase: 'plan',
+      issue: 'QUERY_DEFINITION_NOT_EDGE',
+      path: '/steps/0/via/0',
+    })
+    expect(
+      queryInputRepair({
+        code: 'QUERY_INPUT_INVALID',
+        details: { phase: 'limit', limit: 'steps', maximum: 4, actual: 5 },
+      }),
+    ).toEqual({ phase: 'limit', limit: 'steps', maximum: 4, actual: 5 })
+    expect(
+      queryInputRepair({
+        code: 'QUERY_INPUT_INVALID',
+        details: {
+          phase: 'plan',
+          issue: 'QUERY_DEFINITION_NOT_EDGE',
+          path: '/steps/0/via/0',
+          provider: 'private',
+        },
+      }),
+    ).toBeUndefined()
+  })
+})

package/src/connection/auth.ts

@@ -162,7 +162,7 @@ async function resolveIdpAccessToken(
       )
     }
     if (e instanceof IdpSessionNoRefreshTokenError) {
-      throw new Error(wrongAudienceHint(identityName, identity, audience))
+      throw classifyNoRefreshTokenError(audience, identity.audience, e)
     }
     // 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
@@ -182,6 +182,16 @@ async function resolveIdpAccessToken(
   return token
 }
 
+export function classifyNoRefreshTokenError(
+  requestedAudience: string,
+  sourceAudience: string | undefined,
+  error: IdpSessionNoRefreshTokenError,
+): IdpSessionNoRefreshTokenError | IdpAudienceMismatchError {
+  return sourceAudience !== undefined && sourceAudience !== requestedAudience
+    ? new IdpAudienceMismatchError(requestedAudience, sourceAudience)
+    : error
+}
+
 /** A refresh attempt failed for a reason that re-login will NOT fix. */
 export class IdpRefreshTransientError extends Error {
   constructor(message: string) {
@@ -224,11 +234,3 @@ function refreshFailureError(identityName: string, identity: Identity, cause: un
       )
   }
 }
-
-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/connection/command.ts

@@ -53,7 +53,7 @@ export async function runKernelCommand<T>(input: {
     }
   } catch (error) {
     if (!isRaw && spin) spin.fail(`${label} failed`)
-    await formatKernelError(error, isRaw, undefined, opts.debug, { credential: opts.creds })
+    await formatKernelError(error, isRaw, undefined, opts.debug)
     process.exit(1)
   }
 }

package/src/connection/credential.ts

@@ -94,6 +94,9 @@ export function createCliCredential(
 
 /** Reject contradictory explicit credential selections before identity or network access. */
 export function validateCredentialSelection(options: ConnectionOptions): void {
+  if (options.as !== undefined && options.creds !== undefined) {
+    throw new AstraleError('INVALID_FLAG', '--as cannot be combined with --creds.')
+  }
   if (options.anonymous !== true) return
   const conflicting = [
     ...(options.as === undefined ? [] : ['--as']),

package/src/connection/errors.ts

@@ -1,21 +1,24 @@
 import chalk from 'chalk'
 
-import type { SelfExpansionMeta } from './self'
-
 import { AstraleError } from '../errors'
-import { decodeJwtExpiration, readLocalStatus, type LocalStatus } from '../lib/local-status'
+import { readLocalStatus, type LocalStatus } from '../lib/local-status'
 import { log } from '../lib/log'
+import {
+  functionInputIssues,
+  queryInputRepair,
+  reasonCode,
+  schemaUpgradeDetails,
+  schemaUpgradeHint,
+  type FunctionInputIssue,
+  type QueryInputRepair,
+} from './reasons'
 
-type FieldError = { path: string[]; code: string; message: string }
-type InvariantError = { code: string; message: string; context?: unknown }
+export { functionInputIssues, schemaUpgradeHint } from './reasons'
 
 /**
  * Format and display a kernel client error.
  *
- * Handles AstraleError (CLI-local) and every error class exported by
- * @astrale-os/kernel-client: ConnectionError, DisconnectedError,
- * TimeoutError, AuthenticationError, PermissionDeniedError, NotFoundError,
- * KernelError and its subclasses (ValidationError, InvariantViolationError).
+ * Handles CLI-local errors plus the current Kernel Client public error families.
  *
  * When `debug` is true, additional diagnostic information (class name, full
  * error chain, attached url/details) is printed after the user-facing line.
@@ -25,12 +28,10 @@ export async function formatKernelError(
   isRaw: boolean,
   urlArg = '',
   debug = false,
-  opts: { credential?: string } = {},
 ): Promise<void> {
   const url =
     urlArg || (error instanceof Error ? ((error as Error & { url?: string }).url ?? '') : '')
   const localContext = await contextForError(error)
-  const credentialExpiration = opts.credential ? decodeJwtExpiration(opts.credential) : null
   // Handle AstraleError (AuthError, etc.) with structured hints
   if (error instanceof AstraleError) {
     if (isRaw) {
@@ -52,173 +53,213 @@ export async function formatKernelError(
   const name = error.name
 
   switch (name) {
-    case 'ConnectionError':
-      if (isRaw)
-        writeRaw({ error: 'CONNECTION_ERROR', message: error.message, url, context: localContext })
-      else {
-        log.error(`Could not connect to ${chalk.bold(url || 'kernel')}`)
-        log.dim(`  ${error.message}`)
-        log.dim('  Is the kernel running? Try: astrale status')
-        printLocalContext(localContext)
-      }
-      break
-
-    case 'DisconnectedError':
-      if (isRaw) writeRaw({ error: 'DISCONNECTED', message: error.message })
-      else {
-        log.error('Connection closed while request was pending')
-        log.dim('  The kernel may have been stopped or restarted. Retry the command.')
-      }
-      break
-
-    case 'TimeoutError': {
-      const timeoutMs = (error as { timeoutMs?: number }).timeoutMs
-      if (isRaw) writeRaw({ error: 'TIMEOUT', message: error.message, timeoutMs })
-      else {
-        log.error(`Request timed out after ${timeoutMs ?? '?'}ms`)
-        log.dim('  Try increasing with --timeout')
-      }
-      break
-    }
-
-    case 'AuthenticationError': {
-      const reason = (error as { reason?: string }).reason ?? 'unknown'
-      if (isRaw)
-        writeRaw({
-          error: 'AUTH_ERROR',
-          reason,
-          message: error.message,
-          credential: credentialExpiration,
-          context: localContext,
-        })
-      else {
-        log.error(`Authentication failed: ${error.message}`)
-        if (reason === 'missing')
-          log.dim('  No credential was sent. Run: astrale identity create <name>')
-        else if (reason === 'invalid')
-          log.dim('  Credential is invalid — check issuer/keypair. Try: astrale identity whoami')
-        else if (reason === 'expired') log.dim('  Credential expired — sign a fresh one')
-        if (credentialExpiration) {
-          const state = credentialExpiration.expired ? 'expired' : 'expires'
-          log.dim(`  Credential ${state} at ${credentialExpiration.expiresAt}`)
-        }
-        printLocalContext(localContext)
-      }
-      break
-    }
-
-    case 'PermissionDeniedError':
-      if (isRaw) writeRaw({ error: 'PERMISSION_DENIED', message: error.message })
-      else {
-        log.error(`Permission denied: ${error.message}`)
-        log.dim('  Your identity does not have the required permissions for this operation')
-      }
-      break
-
-    case 'NotFoundError': {
-      const cleanMsg = stripMethodSuffix(error.message)
-      const selfMeta = (error as Error & { expandedFromSelf?: SelfExpansionMeta }).expandedFromSelf
-      // kernel-client maps both NOT_FOUND (the node doesn't exist) and
-      // METHOD_NOT_FOUND (the method doesn't exist on a real node) to
-      // `NotFoundError`. Firing the authenticated-principal hint for the
-      // method case is misleading. Gate on the message referencing the
-      // expanded id — node lookup errors mention `@<id>` whereas method
-      // errors mention the method path.
-      const selfHintApplies = selfMeta && error.message.includes(`@${selfMeta.selfId}`)
-      if (isRaw) {
-        const payload: Record<string, unknown> = { error: 'NOT_FOUND', message: cleanMsg }
-        if (selfHintApplies) payload.expandedFromSelf = selfMeta
-        writeRaw(payload)
-      } else {
-        log.error(`Not found: ${cleanMsg}`)
-        log.dim('  Check the path/ID and that the instance is booted')
-        if (selfHintApplies && selfMeta) {
-          const where = selfMeta.slug ? ` on "${selfMeta.slug}"` : ''
-          log.dim(
-            `  @self resolved through authenticated Identity.whoami to @${selfMeta.selfId}${where}.`,
-          )
-          log.dim('  Check that the requested node path still exists for that principal.')
-        }
-      }
-      break
-    }
-
-    case 'ValidationError': {
-      const errors = (error as { errors?: FieldError[] }).errors ?? []
-      if (isRaw) writeRaw({ error: 'VALIDATION_ERROR', message: error.message, details: errors })
-      else {
-        log.error('Validation Error')
-        if (errors.length > 0) {
-          for (const e of errors) {
-            console.log(chalk.red(`  ${e.path.join('.')}: ${e.message} (${chalk.dim(e.code)})`))
-          }
-        } else {
-          // Server often sends details in message but empty errors array
-          console.log(chalk.red(`  ${error.message}`))
-        }
-        log.dim('  Use `astrale call <path> --describe` to see the expected schema')
-      }
+    case 'TransportError':
+      presentTransportError(error, isRaw, url, localContext)
       break
-    }
-
-    case 'InvariantViolationError': {
-      const errors = (error as { errors?: InvariantError[] }).errors ?? []
-      if (isRaw) writeRaw({ error: 'INVARIANT_VIOLATION', message: error.message, details: errors })
-      else {
-        log.error('Invariant Violation')
-        for (const e of errors) {
-          console.log(chalk.red(`  ${e.code}: ${e.message}`))
-          if (e.context) console.log(chalk.dim(`    ${JSON.stringify(e.context)}`))
-        }
-      }
-      break
-    }
 
     case 'ResponseError': {
       const code = (error as { readonly code?: unknown }).code
       const reason = (error as { readonly reason?: unknown }).reason
+      const codeOfReason = reasonCode(reason)
+      const inputIssues = functionInputIssues(reason)
+      const queryRepair = queryInputRepair(reason)
+      const upgrade = schemaUpgradeDetails(reason)
+      const removalHint = schemaDataRemovalHint(reason)
+      const domainAddressNotPublic = codeOfReason === 'SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC'
+      const displayMessage = domainAddressNotPublic
+        ? 'Expose the Domain through a public HTTPS URL or public tunnel, then retry.'
+        : removalHint !== undefined && !isRaw
+          ? 'Existing business data still uses schema definitions being removed.'
+          : error.message
+      const hint =
+        codeOfReason === 'FUNCTION_INPUT_INVALID' && (isRaw || inputIssues.length === 0)
+          ? 'Use `astrale introspect <path>` to see the callable input.'
+          : (removalHint ?? (upgrade === undefined ? undefined : schemaUpgradeHint(upgrade)))
       if (isRaw) {
         writeRaw({
           error: 'RESPONSE_ERROR',
           ...(code === undefined ? {} : { code }),
-          message: error.message,
+          message: displayMessage,
           ...(reason === undefined ? {} : { reason }),
+          ...(hint === undefined ? {} : { hint }),
         })
       } else {
         log.error(
-          `${chalk.bold(code === undefined ? 'RESPONSE_ERROR' : `RESPONSE_ERROR(${String(code)})`)}: ${error.message}`,
+          domainAddressNotPublic
+            ? `${chalk.bold('SCHEMA_DOMAIN_ADDRESS_NOT_PUBLIC')}: ${displayMessage}`
+            : removalHint !== undefined
+              ? `${chalk.bold('DATA_MIGRATION_REQUIRED')}: ${displayMessage}`
+              : `${chalk.bold(code === undefined ? 'RESPONSE_ERROR' : `RESPONSE_ERROR(${String(code)})`)}: ${displayMessage}`,
         )
-        if (
-          reason !== null &&
-          typeof reason === 'object' &&
-          typeof (reason as { readonly code?: unknown }).code === 'string'
-        ) {
-          log.dim(`  reason: ${(reason as { readonly code: string }).code}`)
+        if (codeOfReason !== undefined && !domainAddressNotPublic && removalHint === undefined) {
+          log.dim(`  reason: ${codeOfReason}`)
+        }
+        presentFunctionInputIssues(inputIssues)
+        if (queryRepair !== undefined) presentQueryInputRepair(queryRepair)
+        if (upgrade?.expected !== undefined) {
+          log.dim(`  installed issuer: ${upgrade.expected}`)
+        }
+        if (upgrade?.actual !== undefined) {
+          log.dim(`  replacement issuer: ${upgrade.actual}`)
         }
+        if (hint !== undefined) log.dim(`  ${hint}`)
       }
       break
     }
 
-    case 'KernelError': {
-      const code = (error as { code?: number | string }).code ?? 'UNKNOWN'
-      const type = (error as { type?: string }).type ?? 'KERNEL_ERROR'
-      if (isRaw) writeRaw({ error: type, code, message: error.message })
-      else log.error(`${chalk.bold(`${type}(${code})`)}: ${error.message}`)
-      break
+    default: {
+      const mapped = mapPublicError(error)
+      if (isRaw) {
+        writeRaw({
+          error: mapped.code,
+          message: mapped.message,
+          ...(mapped.hint === undefined ? {} : { hint: mapped.hint }),
+          ...(mapped.timeoutMs === undefined ? {} : { timeoutMs: mapped.timeoutMs }),
+        })
+      } else {
+        log.error(`${chalk.bold(mapped.code)}: ${mapped.message}`)
+        if (mapped.hint) log.dim(`  ${mapped.hint}`)
+      }
     }
-
-    default:
-      // Catch-all: include class name so diagnosis is possible even without --debug
-      if (isRaw) writeRaw({ error: name || 'UNKNOWN', message: error.message })
-      else log.error(`${chalk.bold(name || 'Error')}: ${error.message}`)
   }
 
   if (debug) printDebug(error, url)
 }
 
-/** Strip internal `::methodName` suffixes from paths in error messages (e.g., "/path::listChildren" → "/path") */
-export function stripMethodSuffix(msg: string): string {
-  return msg.replace(/(\/[^"\s:]+)::([a-zA-Z]\w*)/g, '$1')
+function schemaDataRemovalHint(reason: unknown): string | undefined {
+  if (reason === null || typeof reason !== 'object') return undefined
+  const value = reason as { readonly code?: unknown; readonly details?: unknown }
+  if (value.code !== 'DATA_MIGRATION_REQUIRED') return undefined
+  if (value.details === null || typeof value.details !== 'object') return undefined
+
+  const requirements = (value.details as { readonly requirements?: unknown }).requirements
+  if (
+    !Array.isArray(requirements) ||
+    requirements.length === 0 ||
+    !requirements.every(
+      (requirement) =>
+        requirement !== null &&
+        typeof requirement === 'object' &&
+        (requirement as { readonly operation?: unknown }).operation === 'remove-facts' &&
+        (requirement as { readonly reason?: unknown }).reason === 'destructive-change',
+    )
+  ) {
+    return undefined
+  }
+
+  return 'Delete this data explicitly, then retry. No data was deleted.'
+}
+
+function mapPublicError(error: Error): {
+  code: string
+  message: string
+  hint?: string
+  timeoutMs?: number
+} {
+  const name = error.name
+  if (name === 'PathError') {
+    return { code: 'PATH_INVALID', message: error.message }
+  }
+  if (name === 'NodeUnavailableError') {
+    return {
+      code: 'NODE_UNAVAILABLE',
+      message: error.message,
+      hint: 'If this is a callable Path, use `astrale call` or `astrale introspect`.',
+    }
+  }
+  if (name === 'AuthValueError') {
+    return { code: 'AUTH_VALUE_INVALID', message: error.message }
+  }
+  if (name === 'ClientError' && /timed out/i.test(error.message)) {
+    const timeoutMs = (error as { timeoutMs?: number }).timeoutMs
+    return {
+      code: 'TIMEOUT',
+      message: error.message,
+      hint: 'Try increasing with --timeout',
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    }
+  }
+  if (name === 'ClientError' && /Publication discovery returned HTTP/i.test(error.message)) {
+    return {
+      code: 'KERNEL_DISCOVERY_FAILED',
+      message: error.message,
+      hint: 'Pass the Kernel issuer URL (no /invoke suffix), e.g. https://host/kernel/host',
+    }
+  }
+  return { code: name && name !== 'Error' ? name : 'UNKNOWN', message: error.message }
+}
+
+function presentTransportError(
+  error: Error,
+  isRaw: boolean,
+  url: string,
+  context: LocalStatus | undefined,
+): void {
+  const phase = transportPhase(error)
+  const delivery = transportDelivery(error)
+  const code =
+    phase === 'connect'
+      ? 'CONNECTION_ERROR'
+      : phase === 'timeout'
+        ? 'TIMEOUT'
+        : phase === 'closed'
+          ? 'DISCONNECTED'
+          : 'TRANSPORT_ERROR'
+  if (isRaw) {
+    writeRaw({
+      error: code,
+      message: error.message,
+      ...(url === '' ? {} : { url }),
+      ...(phase === undefined ? {} : { phase }),
+      ...(delivery === undefined ? {} : { delivery }),
+      ...(context === undefined ? {} : { context }),
+    })
+    return
+  }
+  log.error(`${chalk.bold(code)}: ${error.message}`)
+  if (url !== '') log.dim(`  target: ${url}`)
+  if (phase !== undefined) log.dim(`  phase: ${phase}`)
+  if (phase === 'connect') log.dim('  Check the target and run `astrale status`.')
+  else if (phase === 'timeout') log.dim('  Try increasing `--timeout`.')
+  else if (delivery === 'unknown') {
+    log.dim('  Delivery is unknown; do not automatically retry a mutating call.')
+  }
+  printLocalContext(context)
+}
+
+function presentFunctionInputIssues(issues: readonly FunctionInputIssue[]): void {
+  for (const issue of issues) {
+    const location = issue.path === undefined || issue.path === '' ? '<input>' : issue.path
+    console.log(chalk.red(`  ${location}: ${issue.message} (${chalk.dim(issue.code)})`))
+  }
+}
+
+function presentQueryInputRepair(repair: QueryInputRepair): void {
+  if (repair.phase === 'plan') {
+    log.dim(`  ${repair.path ?? '/'}  ${repair.issue}`)
+    return
+  }
+  if (repair.phase === 'limit') {
+    log.dim(`  ${repair.path ?? '/'}  ${repair.limit} limit ${repair.actual}/${repair.maximum}`)
+    return
+  }
+  log.dim(`  ${repair.path}  ${repair.phase} input`)
+}
+
+function transportPhase(error: Error): string | undefined {
+  const phase = (error as Error & { readonly phase?: unknown }).phase
+  return phase === 'connect' ||
+    phase === 'send' ||
+    phase === 'receive' ||
+    phase === 'timeout' ||
+    phase === 'closed'
+    ? phase
+    : undefined
+}
+
+function transportDelivery(error: Error): string | undefined {
+  const delivery = (error as Error & { readonly delivery?: unknown }).delivery
+  return delivery === 'not-sent' || delivery === 'unknown' ? delivery : undefined
 }
 
 function writeRaw(payload: Record<string, unknown>): void {
@@ -227,7 +268,7 @@ function writeRaw(payload: Record<string, unknown>): void {
 
 async function contextForError(error: unknown): Promise<LocalStatus | undefined> {
   if (!(error instanceof Error)) return undefined
-  if (error.name !== 'AuthenticationError' && error.name !== 'ConnectionError') return undefined
+  if (error.name !== 'TransportError') return undefined
   return readLocalStatus().catch(() => undefined)
 }
 

package/src/connection/exchange.ts

@@ -156,6 +156,7 @@ async function exchange(
     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.`,
@@ -165,8 +166,19 @@ async function exchange(
     throw new AstraleError(String(admitted.error.code), admitted.error.message)
   }
   requireExchangeResponseHeaders(response)
-  const exchanged = exchangeProtocol.acceptResponse(body)
-  const inspected = credential.inspect(exchanged.token)
+  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 ||