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

package/src/connection/.spec/laws/connection.ts

@@ -0,0 +1,181 @@
+import { defineLaw } from '@astrale-os/spec/authoring'
+
+export const CLI_CONNECTION_TARGET = defineLaw({
+  id: 'CLI-CONNECTION-TARGET',
+  statement:
+    'Explicit URL, explicit instance, active bookmark, managed lookup, and Admin target selection preserve the existing precedence while returning the exact invocation URL and issuer separately.',
+  tests: [
+    {
+      file: '__tests__/target.test.ts',
+      id: 'TEST-CLI-CONNECTION-SELECTS-EXACT-TARGET',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_DOMAIN_EXCHANGE = defineLaw({
+  id: 'CLI-CONNECTION-DOMAIN-EXCHANGE',
+  statement:
+    'A target with an explicit Domain issuer resolves the source credential, authenticates whoami at the exact Kernel, requests explicit self attenuation for that User and Domain audience, posts the resulting envelope to the discovered standard endpoint, and returns only a Domain token bound back to the same Kernel; there is no inferred issuer or legacy broker fallback.',
+  tests: [
+    {
+      file: '__tests__/exchange.test.ts',
+      id: 'TEST-CLI-EXCHANGE-WHOAMI-DELEGATE-EXCHANGE-CACHE',
+    },
+    {
+      file: '__tests__/exchange.test.ts',
+      id: 'TEST-CLI-EXCHANGE-NO-LEGACY-FALLBACK',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_HOP_CREDENTIAL = defineLaw({
+  id: 'CLI-CONNECTION-HOP-CREDENTIAL',
+  statement:
+    'A source hop resolves a fresh credential only when its session-pinned issuer equals the selected source issuer; a destination hop requires the same selected resolver and returns a fresh delegation for the witnessed Publication issuer, never the source credential, with its TTL bounded strictly inside any source JWT expiry.',
+  tests: [
+    {
+      file: '__tests__/credential.test.ts',
+      id: 'TEST-CLI-CONNECTION-RESOLVES-CREDENTIAL-PER-HOP',
+    },
+    {
+      file: '__tests__/credential.test.ts',
+      id: 'TEST-CLI-CONNECTION-DELEGATES-VIA-SOURCE-AUTH',
+    },
+    {
+      file: '__tests__/credential.test.ts',
+      id: 'TEST-CLI-CONNECTION-REJECTS-HOP-SOURCE-ISSUER-MISMATCH',
+    },
+    {
+      file: '__tests__/credential.test.ts',
+      id: 'TEST-CLI-CONNECTION-BOUNDS-DELEGATION-TO-SOURCE-EXPIRY',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_EXPLICIT_ANONYMOUS = defineLaw({
+  id: 'CLI-CONNECTION-EXPLICIT-ANONYMOUS',
+  statement:
+    'An explicit anonymous selection suppresses ambient, bookmark-default, and local credentials by omitting the Host credential capability; it is rejected before connection construction when combined with --as or --creds.',
+  tests: [
+    {
+      file: '__tests__/credential.test.ts',
+      id: 'TEST-CLI-CONNECTION-OMITS-EXPLICIT-ANONYMOUS-CREDENTIAL',
+    },
+    {
+      file: '__tests__/session.test.ts',
+      id: 'TEST-CLI-CONNECTION-REJECTS-ANONYMOUS-CREDENTIAL-CONFLICT',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_SOURCE_ISSUER = defineLaw({
+  id: 'CLI-CONNECTION-SOURCE-ISSUER',
+  statement:
+    'CLI constructs ClientSession once with sourceIssuer equal to the selected ConnectionTarget issuer independently from its invocation URL, so path-multiplexed Kernels do not substitute root Publication discovery; every credential hop repeats that pin.',
+  tests: [
+    {
+      file: '__tests__/session.test.ts',
+      id: 'TEST-CLI-CONNECTION-PINS-SOURCE-ISSUER',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_ISSUER_DISCOVERY = defineLaw({
+  id: 'CLI-CONNECTION-ISSUER-DISCOVERY',
+  statement:
+    'When invocation URL and issuer differ, liveness probes resolve OIDC metadata at the pinned issuer and reject metadata that declares any other issuer before fetching its keys.',
+  tests: [
+    {
+      file: '../lib/__tests__/meta.test.ts',
+      id: 'TEST-CLI-CONNECTION-PROBES-PINNED-ISSUER',
+    },
+    {
+      file: '../lib/__tests__/meta.test.ts',
+      id: 'TEST-CLI-CONNECTION-REJECTS-DISCOVERY-ISSUER-MISMATCH',
+    },
+  ],
+})
+
+export const CLI_AUTH_REGISTRATION_TARGET = defineLaw({
+  id: 'CLI-AUTH-REGISTRATION-TARGET',
+  statement:
+    'Key identity registration lookup uses the same target key for bookmark, managed, Admin, and direct URL calls that identity registration stores.',
+  tests: [
+    {
+      file: '__tests__/auth.test.ts',
+      id: 'TEST-CLI-AUTH-USES-DIRECT-URL-REGISTRATION',
+    },
+  ],
+})
+
+export const CLI_SELF_AUTHENTICATED_PRINCIPAL = defineLaw({
+  id: 'CLI-SELF-AUTHENTICATED-PRINCIPAL',
+  statement:
+    '@self resolves only from authenticated Identity.whoami on the selected target, so delegated carriers use their effective principal and never an unverified JWT subject or stale local registration.',
+  tests: [
+    {
+      file: '__tests__/self.test.ts',
+      id: 'TEST-CLI-SELF-USES-AUTHENTICATED-EFFECTIVE-PRINCIPAL',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_TERMINAL_CLOSE = defineLaw({
+  id: 'CLI-CONNECTION-TERMINAL-CLOSE',
+  statement:
+    'The Client Session and direct source-Auth client close exactly once after action success, failure, or cancellation.',
+  tests: [
+    {
+      file: '__tests__/session.test.ts',
+      id: 'TEST-CLI-CONNECTION-CLOSES-OWNED-CLIENTS',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_TIMEOUT = defineLaw({
+  id: 'CLI-CONNECTION-TIMEOUT',
+  statement:
+    'The CLI accepts only a positive integer timeout before constructing a Client Session and applies it to both source-Auth and Session operations.',
+  tests: [
+    {
+      file: '__tests__/session.test.ts',
+      id: 'TEST-CLI-CONNECTION-REJECTS-INVALID-TIMEOUT-BEFORE-OPEN',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_CA_SCOPE = defineLaw({
+  id: 'CLI-CONNECTION-CA-SCOPE',
+  statement:
+    'A selected bookmark CA file changes only the Fetch capability owned by this connection and leaves non-HTTPS requests on the injected fallback Fetch.',
+  tests: [
+    {
+      file: '__tests__/ca-fetch.test.ts',
+      id: 'TEST-CLI-CONNECTION-SCOPES-CUSTOM-CA-TO-HTTPS-FETCH',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_CALL_SHAPE = defineLaw({
+  id: 'CLI-CONNECTION-CALL-SHAPE',
+  statement:
+    'Caller-authored path text and input enter Client as exactly one public Call; the CLI retains no optional callable hint, caller ETag, or second dispatch representation.',
+  tests: [
+    {
+      file: '__tests__/call.test.ts',
+      id: 'TEST-CLI-CONNECTION-CREATES-ONE-CANONICAL-CALL',
+    },
+  ],
+})
+
+export const CLI_CONNECTION_PUBLIC_SEMANTIC_REASON = defineLaw({
+  id: 'CLI-CONNECTION-PUBLIC-SEMANTIC-REASON',
+  statement:
+    'Machine-mode Kernel command failures preserve the admitted ResponseError code and public semantic reason so scripts can distinguish conflicts such as revision guards and required data migrations without parsing prose.',
+  tests: [
+    {
+      file: '__tests__/errors.test.ts',
+      id: 'TEST-CLI-CONNECTION-PRESERVES-PUBLIC-SEMANTIC-REASON',
+    },
+  ],
+})

package/src/connection/.spec/layout.ts

@@ -0,0 +1,19 @@
+import { defineLayout } from '@astrale-os/spec/authoring'
+
+export default defineLayout({
+  entries: [
+    '__tests__/',
+    'auth.ts',
+    'call.ts',
+    'command.ts',
+    'credential.ts',
+    'errors.ts',
+    'exchange.ts',
+    'index.ts',
+    'self.ts',
+    'session.ts',
+    'target.ts',
+    'tsconfig.json',
+  ],
+  exact: true,
+})

package/src/{kernel → connection}/__tests__/auth.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test'
 
+import type { Identity } from '../../identity/index'
 import type { AstraleConfig } from '../../lib/config'
-import type { Identity } from '../../lib/identity'
 
 import { resolveKeyIdentityAuthOptions } from '../auth'
 
@@ -10,7 +10,7 @@ const config: AstraleConfig = {
   admin: {
     name: 'admin',
     url: 'https://admin.eu.astrale.ai/api',
-    issuer: 'https://admin.eu.astrale.ai/api',
+    kernelIssuer: 'https://admin.eu.astrale.ai/api',
   },
   telemetry: { enabled: true },
 }
@@ -75,4 +75,28 @@ describe('resolveKeyIdentityAuthOptions', () => {
       audience: 'https://prod.example.com',
     })
   })
+
+  /** @evidence TEST-CLI-AUTH-USES-DIRECT-URL-REGISTRATION */
+  test('uses a registration stored for a direct URL target', () => {
+    const url = 'https://kernel.example/invoke'
+    const identity: Identity = {
+      subject: 'alice',
+      source: 'key',
+      mode: 'local',
+      createdAt: '2026-01-01T00:00:00.000Z',
+      registrations: {
+        [url]: {
+          iss: 'https://kernel.example/identity/alice',
+          sub: 'alice-node',
+          registeredAt: '2026-01-01T00:00:00.000Z',
+        },
+      },
+    }
+
+    expect(resolveKeyIdentityAuthOptions(identity, config, 'https://kernel.example', url)).toEqual({
+      issuer: 'https://kernel.example/identity/alice',
+      subject: 'alice-node',
+      audience: 'https://kernel.example',
+    })
+  })
 })

package/src/connection/__tests__/ca-fetch.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { Buffer } from 'node:buffer'
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+import { fetchWithCaFile } from '../../lib/ca-fetch'
+
+const certificateFile = fileURLToPath(new URL('fixtures/localhost-cert.pem', import.meta.url))
+// Public test-only key material is encoded so repository secret scanners do not mistake it for a credential.
+const keyFile = fileURLToPath(new URL('fixtures/localhost-key.base64', import.meta.url))
+let server: Bun.Server<unknown> | undefined
+
+afterEach(async () => {
+  if (server !== undefined) {
+    await server.stop(true)
+  }
+  server = undefined
+})
+
+describe('connection CA fetch', () => {
+  /** @evidence TEST-CLI-CONNECTION-SCOPES-CUSTOM-CA-TO-HTTPS-FETCH */
+  test('trusts the selected HTTPS CA and leaves plain HTTP on the fallback Fetch', async () => {
+    const [certificate, encodedKey] = await Promise.all([
+      readFile(certificateFile),
+      readFile(keyFile, 'utf8'),
+    ])
+    const key = Buffer.from(encodedKey.trim(), 'base64')
+    server = Bun.serve({
+      hostname: '127.0.0.1',
+      port: 0,
+      tls: { cert: certificate, key },
+      fetch: () => new Response('trusted'),
+    })
+
+    const requests: Array<{ input: RequestInfo | URL; init?: RequestInit }> = []
+    const fallback = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      requests.push({ input, init })
+      return new Response('fallback')
+    }) as typeof fetch
+    const scoped = fetchWithCaFile(certificateFile, fallback)
+    const init = { method: 'POST', body: 'payload' } satisfies RequestInit
+
+    const httpsUrl = `https://127.0.0.1:${server.port}/invoke`
+    const httpsResponse = await scoped(httpsUrl)
+    expect(await httpsResponse.text()).toBe('trusted')
+    expect(httpsResponse.url).toBe(httpsUrl)
+    expect(httpsResponse.redirected).toBe(false)
+    await expect(
+      scoped('http://localhost:8080/invoke', init).then((value) => value.text()),
+    ).resolves.toBe('fallback')
+    expect(requests).toEqual([{ input: 'http://localhost:8080/invoke', init }])
+  })
+})

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

@@ -0,0 +1,17 @@
+import { describe, expect, test } from 'bun:test'
+
+import { createPathCall } from '../call'
+
+describe('createPathCall', () => {
+  /** @evidence TEST-CLI-CONNECTION-CREATES-ONE-CANONICAL-CALL */
+  test('creates one path Call without legacy routing hints', () => {
+    expect(
+      JSON.parse(
+        JSON.stringify(createPathCall('/:kernel.astrale.ai:function.query', { value: 1 })),
+      ),
+    ).toEqual({
+      target: '/:kernel.astrale.ai:function.query',
+      input: { value: 1 },
+    })
+  })
+})

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

@@ -0,0 +1,109 @@
+import type { SessionAuth } from '@astrale-os/kernel-client/session'
+
+import { issuer, type IssuerId } from '@astrale-os/sdk/auth'
+import { Path } from '@astrale-os/sdk/graph/path'
+import { describe, expect, test } from 'bun:test'
+
+import type { AstraleConfig } from '../../lib/config'
+
+import { createCliCredential, createConnectionCredential } from '../credential'
+
+const SOURCE = issuer.accept('https://kernel.example')
+const TARGET_CALL = Object.freeze({
+  target: Path.parse('/:example.dev:function.call').raw,
+  input: { value: 1 },
+}) satisfies Parameters<SessionAuth['resolve']>[0]
+const config: AstraleConfig = {
+  issuer: 'https://cli.example',
+  admin: { name: 'admin', url: SOURCE, kernelIssuer: SOURCE },
+  telemetry: { enabled: false },
+}
+
+describe('connection credential', () => {
+  /** @evidence TEST-CLI-CONNECTION-RESOLVES-SOURCE-AUTH-BEFORE-ROUTING */
+  test('resolves source authority without destination knowledge', async () => {
+    const audiences: IssuerId[] = []
+    const calls: unknown[] = []
+    const auth = createConnectionCredential(SOURCE, {
+      async resolve(audience) {
+        audiences.push(audience)
+        return `source:${audience}`
+      },
+    })
+    const signal = new AbortController().signal
+
+    calls.push(TARGET_CALL)
+    await expect(auth.resolve(TARGET_CALL, signal)).resolves.toEqual({
+      credential: `source:${SOURCE}`,
+    })
+
+    expect(auth.ttlSeconds).toBe(60)
+    expect(audiences).toEqual([SOURCE])
+    expect(calls).toEqual([TARGET_CALL])
+  })
+
+  /** @evidence TEST-CLI-CONNECTION-BOUNDS-REMOTE-CARRIER-TO-SOURCE-LIFETIME */
+  test('bounds destination delegation to the current source credential lifetime', async () => {
+    const expiresAt = Math.ceil(Date.now() / 1_000) + 120
+    const auth = createConnectionCredential(SOURCE, {
+      async resolve() {
+        return token(expiresAt)
+      },
+    })
+
+    const resolved = await auth.resolve(TARGET_CALL, new AbortController().signal)
+    expect(resolved.credential).toBe(token(expiresAt))
+    expect(resolved.delegate?.ttlSeconds).toBeGreaterThan(0)
+    expect(resolved.delegate?.ttlSeconds).toBeLessThan(120)
+  })
+
+  /** @evidence TEST-CLI-CONNECTION-USES-RAW-SOURCE-CREDENTIAL */
+  test('binds explicit CLI credentials to source-Kernel auth only', async () => {
+    const auth = createCliCredential(
+      { url: `${SOURCE}/invoke`, kernelIssuer: SOURCE, slug: 'source' },
+      { creds: 'raw-source-token' },
+      config,
+    )
+    if (auth === undefined) throw new Error('expected authenticated credential')
+
+    await expect(auth.resolve(TARGET_CALL, new AbortController().signal)).resolves.toEqual({
+      credential: 'raw-source-token',
+    })
+  })
+
+  /** @evidence TEST-CLI-CONNECTION-OMITS-EXPLICIT-ANONYMOUS-CREDENTIAL */
+  test('omits the auth capability for an explicit anonymous session', () => {
+    const auth = createCliCredential(
+      { url: `${SOURCE}/invoke`, kernelIssuer: SOURCE, defaultIdentity: 'ambient-default' },
+      { anonymous: true },
+      config,
+    )
+
+    expect(auth).toBeUndefined()
+  })
+
+  /** @evidence TEST-CLI-CONNECTION-PROPAGATES-AUTH-CANCELLATION */
+  test('passes the live Session operation signal to source credential resolution', async () => {
+    const controller = new AbortController()
+    const reason = new Error('cancelled')
+    const auth = createConnectionCredential(SOURCE, {
+      async resolve(_audience, signal) {
+        expect(signal).toBe(controller.signal)
+        throw signal.reason
+      },
+    })
+    controller.abort(reason)
+
+    await expect(auth.resolve(TARGET_CALL, controller.signal)).rejects.toBe(reason)
+  })
+})
+
+function token(exp: number): string {
+  const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
+  return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
+    iss: SOURCE,
+    sub: 'principal',
+    aud: SOURCE,
+    exp,
+  })}.signature`
+}

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

@@ -0,0 +1,96 @@
+import { ResponseError } from '@astrale-os/kernel-client'
+import { describe, expect, test } from 'bun:test'
+
+import { formatKernelError, stripMethodSuffix } from '../errors'
+
+const CONFLICT = 4001
+
+describe('stripMethodSuffix', () => {
+  test('strips ::listChildren from path', () => {
+    expect(stripMethodSuffix('Path not found: "/nonexistent::listChildren"')).toBe(
+      'Path not found: "/nonexistent"',
+    )
+  })
+
+  test('strips ::get from path', () => {
+    expect(stripMethodSuffix('Path not found: "/some/path::get"')).toBe(
+      'Path not found: "/some/path"',
+    )
+  })
+
+  test('strips any method name', () => {
+    expect(stripMethodSuffix('"/kernel.astrale.ai/Root::describe"')).toBe(
+      '"/kernel.astrale.ai/Root"',
+    )
+  })
+
+  test('does not strip from non-path strings', () => {
+    expect(stripMethodSuffix('regular::text')).toBe('regular::text')
+  })
+
+  test('handles multiple paths in one message', () => {
+    expect(stripMethodSuffix('"/a/b::get" and "/c/d::list"')).toBe('"/a/b" and "/c/d"')
+  })
+
+  test('preserves messages without method suffixes', () => {
+    expect(stripMethodSuffix('No path found')).toBe('No path found')
+  })
+
+  test('does not strip single colon (not a method dispatch)', () => {
+    expect(stripMethodSuffix('"/a/b:notMethod"')).toBe('"/a/b:notMethod"')
+  })
+})
+
+describe('formatKernelError', () => {
+  /** @evidence TEST-CLI-CONNECTION-PRESERVES-PUBLIC-SEMANTIC-REASON */
+  test('preserves a Kernel-admitted semantic reason in machine output', async () => {
+    const writes: string[] = []
+    const original = process.stderr.write
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      writes.push(typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
+      return true
+    }) as typeof process.stderr.write
+    try {
+      await formatKernelError(
+        new ResponseError(CONFLICT, 'Schema change requires migration.', {
+          code: 'DATA_MIGRATION_REQUIRED',
+          details: {
+            requirements: [
+              {
+                operation: 'validate-existing',
+                reason: 'invalid-existing',
+                subject: {
+                  kind: 'definition',
+                  ref: { origin: 'x.test', kind: 'class', name: 'X' },
+                },
+                work: { observedFacts: 1 },
+              },
+            ],
+          },
+        }),
+        true,
+      )
+    } finally {
+      process.stderr.write = original
+    }
+    expect(writes).toHaveLength(1)
+    expect(JSON.parse(writes[0]!)).toEqual({
+      error: 'RESPONSE_ERROR',
+      code: CONFLICT,
+      message: 'Schema change requires migration.',
+      reason: {
+        code: 'DATA_MIGRATION_REQUIRED',
+        details: {
+          requirements: [
+            {
+              operation: 'validate-existing',
+              reason: 'invalid-existing',
+              subject: { kind: 'definition', ref: { origin: 'x.test', kind: 'class', name: 'X' } },
+              work: { observedFacts: 1 },
+            },
+          ],
+        },
+      },
+    })
+  })
+})