@astrale-os/cli 0.8.0-alpha.0 → 0.8.1-alpha.2

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

@@ -0,0 +1,224 @@
+import type { Fetch } from '@astrale-os/kernel-client'
+
+import { issuer } from '@astrale-os/sdk/auth'
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { ExchangeCredentialCache } from '../../state/exchange-credentials'
+import { createExchangeCredentialResolver } from '../exchange'
+
+const KERNEL = issuer.accept('https://kernel.example')
+const DOMAIN = issuer.accept('https://admin.example')
+const TARGET = { url: `${KERNEL}/api`, kernelIssuer: KERNEL, domainIssuer: DOMAIN }
+const INVOCATION = `${KERNEL}/invoke`
+const EXPIRES_AT = Math.floor(Date.now() / 1_000) + 500
+const SOURCE_EXPIRES_AT = Math.floor(Date.now() / 1_000) + 120
+const SOURCE_TOKEN = token(
+  issuer.accept('https://workos.example'),
+  KERNEL,
+  'user-1',
+  SOURCE_EXPIRES_AT,
+)
+let directory: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(join(tmpdir(), 'astrale-exchange-'))
+})
+
+afterEach(async () => {
+  await rm(directory, { recursive: true, force: true })
+})
+
+describe('Domain token exchange', () => {
+  /** @evidence TEST-CLI-EXCHANGE-WHOAMI-DELEGATE-EXCHANGE-CACHE */
+  test('runs the exact User to Kernel to Domain journey and reuses the bound token', async () => {
+    const observed: Array<{
+      url: string
+      init: RequestInit | undefined
+      body?: Record<string, any>
+    }> = []
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', EXPIRES_AT)
+    const fetch: Fetch = async (input, init) => {
+      const url = String(input)
+      if (url === INVOCATION) {
+        const body = JSON.parse(await new Response(init?.body).text()) as Record<string, any>
+        observed.push({ url, init, body })
+        const index = observed.filter((entry) => entry.url === INVOCATION).length
+        return invocationResponse(
+          body.id,
+          index === 1
+            ? { id: 'user-1' }
+            : index === 2
+              ? 'kernel-destination-envelope'
+              : { id: 'user-1' },
+          new Headers(init?.headers).get('accept')!,
+        )
+      }
+      observed.push({ url, init })
+      if (url.endsWith('/.well-known/openid-configuration')) {
+        return jsonResponse(configuration(true))
+      }
+      if (url.endsWith('/.well-known/astrale/token')) {
+        expect(init?.body).toBeUndefined()
+        expect(new Headers(init?.headers).get('authorization')).toBe(
+          'Bearer kernel-destination-envelope',
+        )
+        return jsonResponse(
+          { token: exchanged, expiresAt: EXPIRES_AT },
+          200,
+          'application/vnd.astrale+json',
+        )
+      }
+      throw new Error(`unexpected URL ${url}`)
+    }
+    const sourceAudiences: string[] = []
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      {
+        async resolve(audience) {
+          sourceAudiences.push(audience)
+          return SOURCE_TOKEN
+        },
+      },
+      fetch,
+      5_000,
+      new ExchangeCredentialCache(join(directory, 'credentials.json')),
+    )
+
+    expect(await resolver.resolve(KERNEL, new AbortController().signal)).toBe(exchanged)
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).resolves.toBe(exchanged)
+
+    const kernelRequests = observed.filter((entry) => entry.url === INVOCATION)
+    expect(kernelRequests).toHaveLength(3)
+    expect(kernelRequests[0]!.body).toMatchObject({
+      credential: SOURCE_TOKEN,
+      call: { input: {} },
+    })
+    expect(kernelRequests[1]!.body).toMatchObject({
+      credential: SOURCE_TOKEN,
+      call: {
+        input: {
+          audience: DOMAIN,
+          attenuation: { kind: 'identity', self: true },
+        },
+      },
+    })
+    const delegatedTtl = kernelRequests[1]!.body!.call.input.ttlSeconds
+    expect(delegatedTtl).toBeGreaterThan(0)
+    expect(delegatedTtl).toBeLessThan(120)
+    expect(sourceAudiences).toEqual([KERNEL, KERNEL])
+    expect(
+      observed.filter((entry) => entry.url.endsWith('/.well-known/astrale/token')),
+    ).toHaveLength(1)
+  })
+
+  /** @evidence TEST-CLI-EXCHANGE-NO-LEGACY-FALLBACK */
+  test('fails closed when issuer discovery does not advertise exchange', async () => {
+    const fetch: Fetch = async (input, init) => {
+      const url = String(input)
+      if (url === INVOCATION) {
+        const body = JSON.parse(await new Response(init?.body).text()) as Record<string, any>
+        return invocationResponse(
+          body.id,
+          body.call.input && Object.keys(body.call.input).length === 0
+            ? { id: 'user-1' }
+            : 'kernel-destination-envelope',
+          new Headers(init?.headers).get('accept')!,
+        )
+      }
+      if (url.endsWith('/.well-known/openid-configuration'))
+        return jsonResponse(configuration(false))
+      throw new Error('exchange endpoint must not be called')
+    }
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => SOURCE_TOKEN },
+      fetch,
+      5_000,
+      new ExchangeCredentialCache(join(directory, 'credentials.json')),
+    )
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_UNSUPPORTED',
+    })
+  })
+
+  test('rejects an exchanged token bound to another Kernel', async () => {
+    const wrong = token(DOMAIN, issuer.accept('https://other-kernel.example'), 'user-1', EXPIRES_AT)
+    const fetch = exchangeFetch(wrong)
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => SOURCE_TOKEN },
+      fetch,
+      5_000,
+      new ExchangeCredentialCache(join(directory, 'credentials.json')),
+    )
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_PROTOCOL_ERROR',
+    })
+  })
+})
+
+function exchangeFetch(exchanged: string): Fetch {
+  return async (input, init) => {
+    const url = String(input)
+    if (url === INVOCATION) {
+      const body = JSON.parse(await new Response(init?.body).text()) as Record<string, any>
+      return invocationResponse(
+        body.id,
+        body.call.input && Object.keys(body.call.input).length === 0
+          ? { id: 'user-1' }
+          : 'kernel-destination-envelope',
+        new Headers(init?.headers).get('accept')!,
+      )
+    }
+    if (url.endsWith('/.well-known/openid-configuration')) return jsonResponse(configuration(true))
+    return jsonResponse(
+      { token: exchanged, expiresAt: EXPIRES_AT },
+      200,
+      'application/vnd.astrale+json',
+    )
+  }
+}
+
+function configuration(enabled: boolean) {
+  return {
+    issuer: DOMAIN,
+    jwks_uri: `${DOMAIN}/.well-known/jwks.json`,
+    subject_types_supported: ['public'],
+    id_token_signing_alg_values_supported: ['EdDSA'],
+    ...(enabled ? { token_exchange_endpoint: `${DOMAIN}/.well-known/astrale/token` } : {}),
+  }
+}
+
+function invocationResponse(id: number, result: unknown, contentType: string): Response {
+  return new Response(JSON.stringify({ id, result }), {
+    headers: { 'content-type': contentType, 'cache-control': 'no-store' },
+  })
+}
+
+function jsonResponse(value: unknown, status = 200, contentType = 'application/json'): Response {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: { 'content-type': contentType, 'cache-control': 'no-store' },
+  })
+}
+
+function token(iss: string, aud: string, user: string, exp: number): string {
+  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
+  const proof = `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
+    iss: aud,
+    sub: user,
+    aud,
+    exp,
+    delegation: { v: 1, expr: { kind: 'identity', id: user } },
+  })}.signature`
+  return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
+    iss,
+    sub: 'admin-domain',
+    aud,
+    exp,
+    grant: { v: 1, expr: { kind: 'identity', credential: proof } },
+  })}.signature`
+}

package/src/connection/__tests__/fixtures/localhost-cert.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDJTCCAg2gAwIBAgIULD/vMZdJ/u94wRaoyRt5crvKLL0wDQYJKoZIhvcNAQEL
+BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI2MDgxMTE0MDUxNFoXDTM2MDgw
+ODE0MDUxNFowFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF
+AAOCAQ8AMIIBCgKCAQEApheXGRylshfFubAJ1sBoecE9q+giTVJZlAKqXE+Cp/wn
+CQv/uOMQtus6ikSjDmyk8/qiSRAGZYzmZjjt5ICttav7Kb0krdRAnOSB9zd4+hEP
+jq7O5IcAlriey8KKZInugB7GD7HDVGKYPrJpJrOmfxXW0s1Vj55nehP3vn59obfH
+EE4mJ50SV9k/VS5AZ3nJHQwKyGjIKvkHI9Ll0++Wu5/ny84TwYkgY8RYwMwfj2Z0
+ltqGo7bsanwk3JFfrphBSYteAxcgF0Y//Vv557RnM2+zX7W6K1FD7s7Nen4/vx01
+cEacj59lNTDANUNJNNj+cCpol4Ie7Krk0deq/Ih3KQIDAQABo28wbTAdBgNVHQ4E
+FgQU7+UbkfznwiPgzxoBtkPHay+Ifu8wHwYDVR0jBBgwFoAU7+UbkfznwiPgzxoB
+tkPHay+Ifu8wDwYDVR0TAQH/BAUwAwEB/zAaBgNVHREEEzARgglsb2NhbGhvc3SH
+BH8AAAEwDQYJKoZIhvcNAQELBQADggEBAGsPr3yfMuVyCuPQMCaUAWY8Qulepl1V
+NIvqyEAb94F1L8Mfh3UNPF9UljBGcI1RBL8e21iNF7vnR0WBF2SSTlf18/qcErVA
+4A7AwlqIVUXjERN9wKesCS/w92CBswLxq/6KrnLahngoBW/tDJ/uzZLXvSdCnYG7
+NMZMpIB0rLdT6GYr1KT/hUSKOKLqC5x0WtEAdoIOqCyYaZrxso4gIicPMWTS3Eho
+9wzXiIHOme9rtlEPnDPVseuIw2ADRPQHAHXiIlyUcJwmt01mgAKPoMp3wCgTaj2H
+NO7KMXAdJgGmmrCkP3dOWri81NlQVoOrbE432bAfKE7S+KehDYJpeAU=
+-----END CERTIFICATE-----

package/src/connection/__tests__/fixtures/localhost-key.base64

@@ -0,0 +1 @@
+LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2Z0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktnd2dnU2tBZ0VBQW9JQkFRQ21GNWNaSEtXeUY4VzUKc0FuV3dHaDV3VDJyNkNKTlVsbVVBcXBjVDRLbi9DY0pDLys0NHhDMjZ6cUtSS01PYktUeitxSkpFQVpsak9abQpPTzNrZ0syMXEvc3B2U1N0MUVDYzVJSDNOM2o2RVErT3JzN2tod0NXdUo3THdvcGtpZTZBSHNZUHNjTlVZcGcrCnNta21zNlovRmRiU3pWV1BubWQ2RS9lK2ZuMmh0OGNRVGlZbm5SSlgyVDlWTGtCbmVja2REQXJJYU1ncStRY2oKMHVYVDc1YTduK2ZMemhQQmlTQmp4RmpBekIrUFpuU1cyb2FqdHV4cWZDVGNrVit1bUVGSmkxNERGeUFYUmovOQpXL25udEdjemI3TmZ0Ym9yVVVQdXpzMTZmaisvSFRWd1JweVBuMlUxTU1BMVEwazAyUDV3S21pWGdoN3NxdVRSCjE2cjhpSGNwQWdNQkFBRUNnZ0VBRHZPRnJ3V0VwdXo3NkJUQU5mdzVDMmpKVCszRUZMaktob2ZjNVJWbE9oRDUKUkplM2ErSEkwZWFIN1FWenRpc3lpQ0h5Tk9pRDR1VlZvak1TdXlTWVBvZmVRcW9ib0toQUxyOWxNYWRsTlFHUApLSFYwKzE1cHY2ZWI1OVM1MTRZUkdhaHJoT01vSmJNQWFIaHYvY05qUkFKbnhhOGxPaG4wejZqM2ZzYnRNVDd3Ck11dFpVMm85RWRjc09iUHBnemlnZVFEbmw0NVlNbFVsLzY5b2lSR2w0NWw1a2xyaUtMdk9YQWcydWJXTFR0QWYKWVJjeW9mOEdySmFXL1F5ZmRGVVloRUUydVNqUHNyMkFLMVNsMlBDZ1FZNmRNOUZZaDVkckZSNDU1R0VDUm94MApoaFVZS1NQRFhVU1VESUNMcVZ2UTdlOEhTMlVvUXZiaUdRRndMZHp3d1FLQmdRRGJYUVBMNlA5UDRZQ2tUZFFtCnQ4TTNvSlNYbXZHd2JRcTd2WVU5K3ZSYkMyYWRHekljaWYyT1E5OFFsc0R3Yy9XQ2psT01GalJjdTk3NVBueGsKR0RTZXZFdHpjR0JidkwzS094VzJybHo0NnVKOGw2MTkyMkE0a3BUbTNHREdBNFFabE9UZ2tWSkZyWHR5WDVXaApBQ1FkY0twWURFSXRYZm5kUXV5dGZ4anNzUUtCZ1FEQjFQQ2x3bkZqOHFMa2RMZ2xlODczLzJsdC9taGZFcnA5CmNJYkxtdFY3allsZDlzZExJb3RUL2ZyOU9odjUvKzdIUFBGNmQrb3pBcUpQSnBmVjhnNUpWMWhON1pRVWY4eW8KSldTbTZyRWphL0hWRCtsVENBLy9neU1DcFRGTXRhU2wraFBhcVpRb2ZWRm1BRm9OWjFrR0oxdm9iaEhhVmlwSwpQTHFrVGFIditRS0JnUUNydmtFd3JuVGxwNW0rQ2FrbHZ3MjZTYURNcVdTOFNrTHpCY2lCNUM3WDhTOGZwYUV3Ck11RXZOdmczMXErc0VqMlBQN3N0bkZ6V2xjaFd2NU5JRXFOdis5L2V1NGJWakFuVGdUclkwZDY4aTdsUzdyWEkKS2E5RjI0MTB5ZW1DWGxKWWJQaGMwYW5tSDVMYzB2VWxIaVVvWDRNZWVFcC9sbW4vejF2WjRmNHpvUUtCZ0V3MQpVN1JvWWJxaFFFaEFWOUpzL2kvbFhPZGhPbG4rL0JHcnQyTy82YVdkUFdBVFVjSUp2K3Z6Rk1hUkhVVEt5bS9OClYwZ0djNjlBbnQ0dDEwN0h6N1FvUWxESlV3cElRUWZ2UThhWXliS2FrMGRvN1J5M004c0xIUzNDRTBNTXU4S0MKTTJJcWdGVDNDSlRwR0g3aW5rN2NGTGVxNXh3SCtyS2JjK3A3bDJySkFvR0JBSmIxVDRpZFZPdmFZRFlINE1pUwpmUUpGU29QaFZqaklURmU2aG5hNkN0akNHdXoySGNqdXpRMWVFcVhRbzVIYkxRaGdYQnpsM3pUZllYTDJMWGhWCk9WRDB3UmJ2MFAyUk5nNXpqUERQMU8vL2ZISDFkc1hFUzNCZ2t6M3czUnduZXhucXZIRTU5Vm5VQ01yUnFOREYKeXAwVkQzM1F6aWhuRFdScWxhVUxSTit4Ci0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0K

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

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+
+import type { ConnectionContext } from '../session'
+import type { AdminConnectionOptions } from '../target'
+
+import { lookupManagedInstance } from '../session'
+
+describe('implicit managed target owner discovery', () => {
+  test('keeps target credentials out of the admin inventory lookup', async () => {
+    const owned = {
+      id: 'owned-id',
+      slug: 'owned',
+      url: 'https://owned.eu.astrale.ai',
+      state: 'ready',
+    } as const
+    let capturedOptions: AdminConnectionOptions | undefined
+    const openAdmin = async <Value>(
+      options: AdminConnectionOptions,
+      action: (context: ConnectionContext) => Promise<Value>,
+    ): Promise<Value> => {
+      capturedOptions = options
+      return action({} as ConnectionContext)
+    }
+    const connect = async () => ({ list: async () => [owned] }) as never
+
+    await lookupManagedInstance(
+      'owned',
+      {
+        as: 'target-identity',
+        creds: 'target-delegation',
+        timeout: '45000',
+      },
+      openAdmin,
+      connect,
+    )
+
+    expect(capturedOptions).toEqual({ timeout: '45000' })
+  })
+})

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

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test'
+import { SignJWT } from 'jose'
+import { webcrypto } from 'node:crypto'
+
+import { resolveSelfIdAuthenticated } from '../self'
+
+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 opts = { creds: credential, url: 'https://manager.example/children/child/invoke' }
+
+    const resolved = await resolveSelfIdAuthenticated(opts, {
+      whoami: async (received) => {
+        expect(received).toBe(opts)
+        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(
+        { as: 'platform-root', url: 'https://manager.example/invoke' },
+        { 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({}, { whoami: async () => ({ id: '   ' }) }),
+    ).rejects.toMatchObject({ name: 'SelfResolutionError' })
+  })
+})
+
+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

@@ -0,0 +1,140 @@
+import type { AuthApi } from '@astrale-os/kernel-client/auth'
+import type { GraphApi } from '@astrale-os/kernel-client/graph'
+import type { ClientSession } from '@astrale-os/kernel-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 },
+}
+
+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 options = createClientSessionOptions(target, globalThis.fetch, auth, 2_500)
+
+    expect(options.kernel).toBe(target.kernelIssuer)
+    expect(options).not.toHaveProperty('url')
+    expect(options).not.toHaveProperty('sourceIssuer')
+  })
+
+  /** @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

@@ -0,0 +1,93 @@
+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 },
+}
+
+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',
+        }),
+      }),
+    ).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/{kernel → connection}/auth.ts

@@ -1,7 +1,8 @@
 import type { AstraleConfig } from '../lib/config'
 
 import { AuthError } from '../errors'
-import { getDefault, getIdentity, type Identity } from '../lib/identity'
+import { getDefault, getIdentity, type Identity } from '../identity/registry'
+import { signAs } from '../keys/index'
 import {
   accessTokenForAudience,
   classifyRefreshFailure,
@@ -12,8 +13,7 @@ import {
   IdpSessionMissingError,
   IdpSessionNoRefreshTokenError,
 } from '../lib/idp-session'
-import { signAs } from '../lib/keys'
-import { KEYS_DIR } from '../lib/paths'
+import { KEYS_DIR } from '../state/index'
 
 export type KeyIdentityAuthOptions = {
   issuer: string
@@ -37,7 +37,7 @@ export async function resolveCredential(
   opts: { as?: string; creds?: string; defaultIdentity?: string },
   config: AstraleConfig,
   audience: string = config.issuer,
-  instanceSlug?: string,
+  registrationKey?: string,
 ): Promise<string> {
   if (opts.creds) return opts.creds
   // Track the resolved identity so the catch block can tailor its hint: an
@@ -60,7 +60,7 @@ export async function resolveCredential(
       return await signAs(
         identity.subject,
         KEYS_DIR,
-        resolveKeyIdentityAuthOptions(identity, config, audience, instanceSlug),
+        resolveKeyIdentityAuthOptions(identity, config, audience, registrationKey),
       )
     }
 
@@ -74,7 +74,7 @@ export async function resolveCredential(
     return await signAs(
       identity.subject,
       KEYS_DIR,
-      resolveKeyIdentityAuthOptions(identity, config, audience, instanceSlug),
+      resolveKeyIdentityAuthOptions(identity, config, audience, registrationKey),
     )
   } catch (e) {
     const message = e instanceof Error ? e.message : 'Failed to resolve credentials'
@@ -128,9 +128,9 @@ export function resolveKeyIdentityAuthOptions(
   identity: Identity,
   config: AstraleConfig,
   audience: string = config.issuer,
-  instanceSlug?: string,
+  registrationKey?: string,
 ): KeyIdentityAuthOptions {
-  const registration = instanceSlug ? identity.registrations?.[instanceSlug] : undefined
+  const registration = registrationKey ? identity.registrations?.[registrationKey] : undefined
   return {
     issuer:
       registration?.iss ?? identity.issuer ?? systemIdentityIssuer(identity, audience, config),

package/src/connection/call.ts

@@ -0,0 +1,7 @@
+import { call, type Call } from '@astrale-os/kernel-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])
+}