@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

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

@@ -1,71 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { SignJWT } from 'jose'
-import { webcrypto } from 'node:crypto'
-
-import type { ConnectionContext } from '../session'
-
-import { expandSelfInCall, resolveSelfIdAuthenticated } from '../self'
-
-const context = Object.freeze({}) as ConnectionContext
-
-describe('resolveSelfIdAuthenticated', () => {
-  /** @evidence TEST-CLI-SELF-USES-AUTHENTICATED-EFFECTIVE-PRINCIPAL */
-  test('uses child whoami for a manager-to-child Management carrier', async () => {
-    const key = await generateEs256()
-    const credential = await new SignJWT({ carrier: 'management' })
-      .setProtectedHeader({ alg: 'ES256' })
-      .setIssuer('https://manager.example')
-      .setSubject('manager-principal')
-      .setAudience('https://child.example')
-      .sign(key)
-    const resolved = await resolveSelfIdAuthenticated(context, {
-      whoami: async (received) => {
-        expect(received).toBe(context)
-        return { id: 'child-kernel-principal', slug: 'child' }
-      },
-    })
-
-    expect(resolved).toEqual({ id: 'child-kernel-principal', slug: 'child' })
-  })
-
-  test('resolves an imported root without requiring a local registration', async () => {
-    await expect(
-      resolveSelfIdAuthenticated(context, {
-        whoami: async () => ({ id: 'manager-kernel-principal' }),
-      }),
-    ).resolves.toEqual({ id: 'manager-kernel-principal' })
-  })
-
-  test('fails closed when authenticated whoami returns no NodeId', async () => {
-    await expect(
-      resolveSelfIdAuthenticated(context, { whoami: async () => ({ id: '   ' }) }),
-    ).rejects.toMatchObject({ code: 'SELF_RESOLUTION_FAILED' })
-  })
-})
-
-describe('expandSelfInCall', () => {
-  test('expands only top-level string values after local parameter admission', async () => {
-    const callContext = {
-      auth: { whoami: async () => ({ id: 'caller-id' }) },
-      target: {},
-    } as ConnectionContext
-    const expanded = await expandSelfInCall(
-      '/:people.example.dev:class.Person:get',
-      { owner: '@self', count: 2, nested: { owner: '@self' } },
-      callContext,
-    )
-    expect(expanded.parameters).toEqual({
-      owner: '@caller-id',
-      count: 2,
-      nested: { owner: '@self' },
-    })
-  })
-})
-
-async function generateEs256(): Promise<CryptoKey> {
-  const pair = await webcrypto.subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, [
-    'sign',
-    'verify',
-  ])
-  return pair.privateKey
-}

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

@@ -1,144 +0,0 @@
-import type { AuthApi } from '@astrale-os/sdk/auth'
-import type { GraphApi } from '@astrale-os/sdk/client'
-import type { ClientSession } from '@astrale-os/sdk/client/session'
-import type { SessionRouteStore } from '@astrale-os/sdk/client/session'
-
-import { issuer } from '@astrale-os/sdk/auth'
-import { describe, expect, test } from 'bun:test'
-
-import type { AstraleConfig } from '../../lib/config'
-import type { ConnectionContext, ConnectionFactory } from '../session'
-
-import { createClientSessionOptions, withResolvedClientSession } from '../session'
-
-const target = Object.freeze({
-  url: 'https://gateway.example/instances/child/invoke',
-  kernelIssuer: issuer.accept('https://child.example'),
-})
-
-const config: AstraleConfig = {
-  issuer: 'https://cli.example',
-  admin: {
-    name: 'admin',
-    url: 'https://admin.example',
-    kernelIssuer: 'https://admin.example',
-  },
-  telemetry: { enabled: false },
-  browser: {},
-}
-
-const context: ConnectionContext = Object.freeze({
-  session: {} as ClientSession,
-  callerSession: {} as ClientSession,
-  graph: {} as GraphApi,
-  auth: {} as AuthApi,
-  target,
-})
-
-describe('connection session', () => {
-  /** @evidence TEST-CLI-CONNECTION-PINS-SOURCE-ISSUER */
-  test('pins the selected canonical Kernel issuer without a transport escape hatch', async () => {
-    const auth = { ttlSeconds: 3_600, resolve: async () => ({ credential: 'credential' }) }
-    const routeStore: SessionRouteStore = { read: () => undefined, write: () => undefined }
-    const options = createClientSessionOptions(target, globalThis.fetch, auth, 2_500, routeStore)
-
-    expect(options.kernel).toBe(target.kernelIssuer)
-    expect(options).not.toHaveProperty('url')
-    expect(options).not.toHaveProperty('sourceIssuer')
-    expect(options.routeStore).toBe(routeStore)
-  })
-
-  /** @evidence TEST-CLI-CONNECTION-OMITS-EXPLICIT-ANONYMOUS-CREDENTIAL */
-  test('constructs an anonymous Client Session without an auth resolver', () => {
-    const options = createClientSessionOptions(target, globalThis.fetch, undefined, 2_500)
-
-    expect(options.kernel).toBe(target.kernelIssuer)
-    expect(options.auth).toBeUndefined()
-    expect(Object.hasOwn(options, 'auth')).toBe(false)
-  })
-
-  /** @evidence TEST-CLI-CONNECTION-CLOSES-OWNED-CLIENTS */
-  test('closes its owned connection after success, failure, and cancellation', async () => {
-    for (const outcome of ['success', 'failure', 'cancellation'] as const) {
-      let closes = 0
-      const open: ConnectionFactory = () => ({
-        context,
-        close() {
-          closes += 1
-        },
-      })
-      const pending = withResolvedClientSession(
-        target,
-        {},
-        config,
-        async (received) => {
-          expect(received).toBe(context)
-          if (outcome === 'failure') throw new Error('action failed')
-          if (outcome === 'cancellation') throw new DOMException('cancelled', 'AbortError')
-          return 'done'
-        },
-        open,
-      )
-      if (outcome === 'success') await expect(pending).resolves.toBe('done')
-      else await expect(pending).rejects.toThrow()
-      expect(closes).toBe(1)
-    }
-  })
-
-  /** @evidence TEST-CLI-CONNECTION-REJECTS-INVALID-TIMEOUT-BEFORE-OPEN */
-  test('rejects invalid timeouts before constructing a connection', async () => {
-    for (const timeout of ['0', '-1', '1.5', 'nope', '999999999999999999999']) {
-      let opened = false
-      await expect(
-        withResolvedClientSession(
-          target,
-          { timeout },
-          config,
-          async () => undefined,
-          () => {
-            opened = true
-            throw new Error('must not open')
-          },
-        ),
-      ).rejects.toMatchObject({ code: 'INVALID_FLAG' })
-      expect(opened).toBe(false)
-    }
-
-    let receivedTimeout = 0
-    await withResolvedClientSession(
-      target,
-      { timeout: '2500' },
-      config,
-      async () => undefined,
-      (_target, timeoutMs) => {
-        receivedTimeout = timeoutMs
-        return { context, close() {} }
-      },
-    )
-    expect(receivedTimeout).toBe(2_500)
-  })
-
-  /** @evidence TEST-CLI-CONNECTION-REJECTS-ANONYMOUS-CREDENTIAL-CONFLICT */
-  test('rejects anonymous plus explicit credentials before opening a connection', async () => {
-    for (const options of [
-      { anonymous: true, as: 'alice' },
-      { anonymous: true, creds: 'token' },
-      { anonymous: true, as: 'alice', creds: 'token' },
-    ]) {
-      let opened = false
-      await expect(
-        withResolvedClientSession(
-          target,
-          options,
-          config,
-          async () => undefined,
-          () => {
-            opened = true
-            throw new Error('must not open')
-          },
-        ),
-      ).rejects.toMatchObject({ code: 'INVALID_FLAG' })
-      expect(opened).toBe(false)
-    }
-  })
-})

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

@@ -1,95 +0,0 @@
-import { issuer } from '@astrale-os/sdk/auth'
-import { describe, expect, test } from 'bun:test'
-
-import type { AstraleConfig } from '../../lib/config'
-import type { InstanceStore } from '../../lib/instance'
-
-import { resolveAdminConnectionTarget, resolveConnectionTarget } from '../target'
-
-const config: AstraleConfig = {
-  issuer: 'https://cli.example',
-  admin: {
-    name: 'control',
-    url: 'https://admin.example/api',
-    kernelIssuer: 'https://admin.example/issuer',
-    domainIssuer: 'https://admin-domain.example',
-  },
-  telemetry: { enabled: false },
-  browser: {},
-}
-
-const instances: InstanceStore = {
-  active: 'staging',
-  instances: {
-    staging: {
-      url: 'https://staging.example/api',
-      issuer: 'https://identity.staging.example',
-      defaultIdentity: 'alice',
-      caFile: '/etc/astrale/staging-ca.pem',
-    },
-  },
-}
-
-describe('connection target', () => {
-  /** @evidence TEST-CLI-CONNECTION-SELECTS-EXACT-TARGET */
-  test('preserves URL, bookmark, active, managed, and Admin target semantics', async () => {
-    expect(
-      await resolveConnectionTarget({ url: 'https://direct.example/invoke' }, config, {
-        instances,
-      }),
-    ).toEqual({
-      url: 'https://direct.example/invoke',
-      kernelIssuer: issuer.accept('https://direct.example/invoke'),
-    })
-
-    expect(await resolveConnectionTarget({}, config, { instances })).toEqual({
-      url: 'https://staging.example/api',
-      kernelIssuer: issuer.accept('https://identity.staging.example'),
-      slug: 'staging',
-      defaultIdentity: 'alice',
-      caFile: '/etc/astrale/staging-ca.pem',
-    })
-
-    expect(
-      await resolveConnectionTarget(
-        { instance: 'staging', url: 'https://override.example/invoke' },
-        config,
-        { instances },
-      ),
-    ).toMatchObject({
-      url: 'https://override.example/invoke',
-      kernelIssuer: 'https://identity.staging.example',
-      slug: 'staging',
-    })
-
-    expect(
-      await resolveConnectionTarget({ instance: 'remote' }, config, {
-        instances,
-        managed: async (slug) => ({
-          id: 'managed-id',
-          slug,
-          url: 'https://managed.example',
-          state: 'ready',
-        }),
-      }),
-    ).toEqual({
-      url: 'https://managed.example',
-      kernelIssuer: issuer.accept('https://managed.example'),
-      slug: 'remote',
-    })
-
-    expect(await resolveConnectionTarget({ instance: 'control' }, config, { instances })).toEqual({
-      url: 'https://admin.example/api',
-      kernelIssuer: issuer.accept('https://admin.example/issuer'),
-      domainIssuer: issuer.accept('https://admin-domain.example'),
-      slug: 'control',
-    })
-
-    expect(await resolveAdminConnectionTarget({}, config, instances)).toEqual({
-      url: 'https://admin.example/api',
-      kernelIssuer: issuer.accept('https://admin.example/issuer'),
-      domainIssuer: issuer.accept('https://admin-domain.example'),
-      slug: 'control',
-    })
-  })
-})

package/src/connection/auth.ts

@@ -1,265 +0,0 @@
-import type { AstraleConfig } from '../lib/config'
-import type { ConnectionOptions, ConnectionTarget } from './target'
-
-import { AuthError } from '../errors'
-import { getDefault, getIdentity, type Identity } from '../identity/registry'
-import { signAs } from '../keys/index'
-import {
-  accessTokenForAudience,
-  classifyRefreshFailure,
-  IdpAudienceMismatchError,
-} from '../lib/idp'
-import {
-  ensureFreshSession,
-  IdpSessionMissingError,
-  IdpSessionNoRefreshTokenError,
-} from '../lib/idp-session'
-import { KEYS_DIR } from '../state/index'
-
-export type KeyIdentityAuthOptions = {
-  issuer: string
-  subject?: string
-  audience: string
-}
-
-/** Pin the local identity label before a session performs any authenticated effect. */
-export async function bindCredentialIdentity<Options extends ConnectionOptions>(
-  options: Options,
-  target: ConnectionTarget,
-): Promise<Options> {
-  if (options.anonymous === true || options.creds !== undefined || options.as !== undefined) {
-    return options
-  }
-  const identity = target.defaultIdentity ?? (await getDefault()).name
-  return Object.freeze({ ...options, as: identity })
-}
-
-/**
- * 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
-    minimumRemainingSeconds?: number
-  },
-  config: AstraleConfig,
-  audience: string = config.issuer,
-  registrationKey?: 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,
-          opts.minimumRemainingSeconds,
-        )
-      return await signAs(
-        identity.subject,
-        KEYS_DIR,
-        resolveKeyIdentityAuthOptions(identity, config, audience, registrationKey),
-      )
-    }
-
-    const identity = await getDefault()
-    resolvedIdentity = identity
-    resolvedName = identity.name
-    if ((identity.source ?? 'key') === 'idp') {
-      return await resolveIdpAccessToken(
-        identity.name,
-        identity,
-        audience,
-        opts.minimumRemainingSeconds,
-      )
-    }
-
-    return await signAs(
-      identity.subject,
-      KEYS_DIR,
-      resolveKeyIdentityAuthOptions(identity, config, audience, registrationKey),
-    )
-  } 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,
-  registrationKey?: string,
-): KeyIdentityAuthOptions {
-  const registration = registrationKey ? identity.registrations?.[registrationKey] : 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,
-  minimumRemainingSeconds?: number,
-): Promise<string> {
-  let resolved
-  try {
-    resolved = await ensureFreshSession(identityName, { audience, minimumRemainingSeconds })
-  } 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 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
-    // 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
-}
-
-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) {
-    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}`,
-      )
-  }
-}

package/src/connection/call.ts

@@ -1,7 +0,0 @@
-import { call, type Call } from '@astrale-os/sdk/client'
-import { Path } from '@astrale-os/sdk/graph/path'
-
-/** Convert the CLI's untrusted text/JSON boundary into the one public Call representation. */
-export function createPathCall(path: string, input: unknown): Call {
-  return call(Path.parse(path), input as Parameters<typeof call>[1])
-}

package/src/connection/command.ts

@@ -1,67 +0,0 @@
-import chalk from 'chalk'
-
-import type { ConnectionContext } from './session'
-import type { ConnectionOptions } from './target'
-
-import { formatElapsed } from '../lib/format'
-import { spinner } from '../lib/log'
-import { isMachine, present } from '../lib/output'
-import { formatKernelError } from './errors'
-import { withClientSession } from './session'
-
-export interface KernelCommandOpts extends ConnectionOptions {
-  readonly raw?: boolean
-  readonly json?: boolean
-  readonly format?: 'yaml' | 'json'
-  readonly debug?: boolean
-}
-
-export interface OperationRecovery {
-  readonly operation: string
-  readonly retry: string
-}
-
-/**
- * Encapsulates the standard kernel command lifecycle:
- * spinner → connect → call → timing → output → error handling.
- *
- * Commands provide a `fn` that does the actual work and an optional
- * `format` callback for custom output. If `format` is omitted, the
- * result is passed to the standard `output()` function.
- */
-export async function runKernelCommand<T>(input: {
-  readonly opts: KernelCommandOpts
-  readonly label: string
-  readonly recovery?: OperationRecovery
-  readonly fn: (context: ConnectionContext) => Promise<T>
-  readonly format?: (
-    result: T,
-    options: KernelCommandOpts,
-    machine: boolean,
-  ) => void | Promise<void>
-}): Promise<void> {
-  const { opts, label, fn } = input
-  const isRaw = isMachine(opts)
-  const spin = !isRaw ? spinner(`${label}...`) : null
-  const startTime = performance.now()
-
-  try {
-    const result = await withClientSession(opts, fn)
-    const elapsed = performance.now() - startTime
-
-    spin?.succeed(`${label} ${chalk.dim(formatElapsed(elapsed))}`)
-    if (!isRaw) console.log('')
-
-    if (input.format) {
-      await input.format(result, opts, isRaw)
-    } else {
-      present(result, opts)
-    }
-  } catch (error) {
-    if (!isRaw && spin) spin.fail(`${label} failed`)
-    await formatKernelError(error, isRaw, undefined, opts.debug, {
-      recovery: input.recovery,
-    })
-    process.exit(1)
-  }
-}