@astrale-os/cli 1.0.0-beta.3 → 1.0.0-beta.31

package/src/state/.spec/api.d.ts

@@ -1,3 +1,5 @@
+import type { SessionRouteArtifact, SessionRouteStore } from '@astrale-os/sdk/client/session'
+
 /** Environment values that affect CLI-owned state placement. */
 export interface PathEnvironment {
   readonly ASTRALE_HOME?: string
@@ -17,6 +19,7 @@ export interface Paths {
   readonly idps: string
   readonly idpSessionsDir: string
   readonly exchangeCredentials: string
+  readonly sessionRoutes: string
   idpDir(name: string): string
   idpSession(identityName: string): string
 }
@@ -35,22 +38,27 @@ export const INSTANCES_PATH: string
 export const IDPS_PATH: string
 export const IDP_SESSIONS_DIR: string
 export const EXCHANGE_CREDENTIALS_PATH: string
+export const SESSION_ROUTES_PATH: string
 
 export namespace exchange {
   interface Artifact {
-    readonly version: 1
+    readonly version: 2
     readonly entries: Record<string, Entry>
   }
 
   interface Key {
     readonly kernelIssuer: string
     readonly domainIssuer: string
-    readonly user: string
+    readonly sourceIssuer: string
+    readonly sourceSubject: string
   }
 
   interface Entry {
     readonly credential: string
     readonly expiresAt: number
+    readonly user: string
+    readonly sourceIssuer: string
+    readonly sourceSubject: string
   }
 }
 
@@ -118,6 +126,17 @@ export function updateIdentityStore<Value>(
 
 /** Atomically replace one private CLI state file through a same-directory temporary file. */
 export function atomicWrite(path: string, data: string): Promise<void>
+export function atomicWriteSync(path: string, data: string): void
+
+/** CLI filesystem representation for Kernel Client's admitted confidential route artifact. */
+export class FileSessionRouteStore implements SessionRouteStore {
+  constructor(path?: string)
+  read(): unknown
+  write(artifact: SessionRouteArtifact): void
+  clear(): void
+}
+
+export const SESSION_ROUTE_STORE: Readonly<FileSessionRouteStore>
 
 export interface FileLockOptions {
   readonly pollIntervalMs?: number

package/src/state/.spec/architecture.md

@@ -11,10 +11,24 @@ The identity registry decodes the legacy unversioned shape and current V1 envelo
 exact bytes at `identities.json.v0.bak` before publishing V1. Invalid or newer files remain untouched
 and fail closed. Identity orchestration owns key and IdP-session effects above this module.
 
-The exchange registry owns a versioned `exchange.Artifact`. Each entry is keyed by the atomic
-`(Kernel issuer, Domain issuer, registered User)` identity and stores only one inspected Domain
-credential and expiry. It reuses the same atomic-write and bounded file-lock primitives, maintains
-owner-only directory and file modes, and remains distinct from Client's process-local route cache.
+The exchange registry owns a versioned `exchange.Artifact`. Each V2 entry is keyed by the atomic
+`(Kernel issuer, Domain issuer, source issuer, source subject)` identity and stores one inspected
+Domain credential, expiry, and the exact registered Kernel User proven when that credential was
+minted, together with the exact upstream source issuer and subject that selected the entry. This lets
+a warm command validate and reuse the credential before any network `whoami` without accepting a
+refresh result filed under another source identity.
+V1 is not migrated or retained; it is discarded and replaced by the next exact exchange. The
+registry reuses the same atomic-write and bounded file-lock primitives and maintains owner-only
+directory and file modes.
+
+The session-route registry is a separate representation adapter for Kernel Client's versioned,
+bounded confidential route artifact. Kernel Client exclusively owns route keying, admission, expiry,
+and stale/miss recovery. CLI owns only synchronous owner-private JSON I/O so a new CLI process can
+reuse admitted routing state without an Admin-specific shortcut. Writes are atomic snapshots; a
+lost concurrent cache update or any read/write failure is only a future cold route miss and cannot
+change product correctness.
+Authentication logout and identity deletion remove this artifact together with exchanged Domain
+credentials so locally retired authority does not leave reusable destination bearers behind.
 
 Shape decoding, migrations, and backup policy remain with each semantic registry. Commands do not
 call these primitives directly, and Kernel Client owns no CLI filesystem state.

package/src/state/.spec/layout.ts

@@ -8,6 +8,7 @@ export default defineLayout({
     'identities.ts',
     'index.ts',
     'paths.ts',
+    'session-routes.ts',
     'tsconfig.json',
   ],
   exact: true,

package/src/state/__tests__/exchange-credentials.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
-import { mkdtemp, readFile, rm, stat } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
@@ -19,11 +19,22 @@ afterEach(async () => {
 
 describe('exchange credential cache', () => {
   /** @evidence TEST-CLI-EXCHANGE-CACHE-EXACT-KEY-AND-PRIVATE-MODE */
-  test('partitions by Kernel, Domain, and User under private filesystem modes', async () => {
+  test('partitions by Kernel, Domain, and source identity under private filesystem modes', async () => {
     const cache = new ExchangeCredentialCache(path)
     const now = () => 100
     const first = key('https://kernel-a.example', 'https://domain.example', 'user-a')
-    const second = key('https://kernel-a.example', 'https://domain.example', 'user-b')
+    const partitions = [
+      first,
+      key('https://kernel-b.example', first.domainIssuer, first.sourceSubject),
+      key(first.kernelIssuer, 'https://other-domain.example', first.sourceSubject),
+      key(
+        first.kernelIssuer,
+        first.domainIssuer,
+        first.sourceSubject,
+        'https://other-source.example',
+      ),
+      key(first.kernelIssuer, first.domainIssuer, 'user-b'),
+    ]
     let refreshes = 0
 
     const resolve = (candidate: typeof first) =>
@@ -31,18 +42,16 @@ describe('exchange credential cache', () => {
         candidate,
         async () => {
           refreshes += 1
-          return {
-            credential: token(candidate, 200),
-            expiresAt: 200,
-          }
+          return entry(candidate, 200)
         },
         now,
       )
 
-    await expect(resolve(first)).resolves.toBe(token(first, 200))
-    await expect(resolve(first)).resolves.toBe(token(first, 200))
-    await expect(resolve(second)).resolves.toBe(token(second, 200))
-    expect(refreshes).toBe(2)
+    for (const candidate of partitions) {
+      await expect(resolve(candidate)).resolves.toBe(token(candidate, 200))
+      await expect(resolve(candidate)).resolves.toBe(token(candidate, 200))
+    }
+    expect(refreshes).toBe(partitions.length)
     expect((await stat(path)).mode & 0o777).toBe(0o600)
     expect((await stat(join(directory, 'private'))).mode & 0o777).toBe(0o700)
   })
@@ -56,10 +65,7 @@ describe('exchange credential cache', () => {
     const refresh = async () => {
       refreshes += 1
       await new Promise((resolve) => setTimeout(resolve, 10))
-      return {
-        credential: token(candidate, 200),
-        expiresAt: 200,
-      }
+      return entry(candidate, 200)
     }
 
     const values = await Promise.all([
@@ -77,10 +83,7 @@ describe('exchange credential cache', () => {
     const candidate = key('https://kernel.example', 'https://domain.example', 'user')
     await cache.getOrRefresh(
       candidate,
-      async () => ({
-        credential: token(candidate, 120),
-        expiresAt: 120,
-      }),
+      async () => entry(candidate, 120),
       () => 50,
     )
     let refreshes = 0
@@ -88,10 +91,7 @@ describe('exchange credential cache', () => {
       candidate,
       async () => {
         refreshes += 1
-        return {
-          credential: token(candidate, 220),
-          expiresAt: 220,
-        }
+        return entry(candidate, 220)
       },
       () => 100,
     )
@@ -99,19 +99,16 @@ describe('exchange credential cache', () => {
 
     await expect(
       cache.getOrRefresh(
-        key('https://other-kernel.example', candidate.domainIssuer, candidate.user),
-        async () => ({
-          credential: token(candidate, 220),
-          expiresAt: 220,
-        }),
+        key('https://other-kernel.example', candidate.domainIssuer, candidate.sourceSubject),
+        async () => entry(candidate, 220),
         () => 100,
       ),
     ).rejects.toThrow(/inconsistent with its cache key/i)
 
     await expect(
       cache.getOrRefresh(
-        key(candidate.kernelIssuer, candidate.domainIssuer, 'other-user'),
-        async () => ({ credential: token(candidate, 220), expiresAt: 220 }),
+        key(candidate.kernelIssuer, candidate.domainIssuer, 'other-source'),
+        async () => entry(candidate, 220),
         () => 100,
       ),
     ).rejects.toThrow(/inconsistent with its cache key/i)
@@ -125,10 +122,7 @@ describe('exchange credential cache', () => {
       await expect(
         cache.getOrRefresh(
           malformedCandidate,
-          async () => ({
-            credential: token(malformedCandidate, 220, malformed),
-            expiresAt: 220,
-          }),
+          async () => entry(malformedCandidate, 220, malformed),
           () => 100,
         ),
       ).rejects.toThrow(/inconsistent with its cache key/i)
@@ -143,10 +137,7 @@ describe('exchange credential cache', () => {
     for (const candidate of [a, b]) {
       await cache.getOrRefresh(
         candidate,
-        async () => ({
-          credential: token(candidate, 200),
-          expiresAt: 200,
-        }),
+        async () => entry(candidate, 200),
         () => 100,
       )
     }
@@ -156,10 +147,60 @@ describe('exchange credential cache', () => {
     await cache.clear()
     expect(JSON.parse(await readFile(path, 'utf8')).entries).toEqual({})
   })
+
+  test('discards the V1 cache and writes only V2 after a fresh exact exchange', async () => {
+    await mkdir(join(directory, 'private'))
+    await writeFile(
+      path,
+      JSON.stringify({
+        version: 1,
+        entries: { legacy: { credential: 'legacy', expiresAt: 999 } },
+      }),
+    )
+    const cache = new ExchangeCredentialCache(path)
+    const candidate = key('https://kernel.example', 'https://domain.example', 'source-user')
+    let refreshes = 0
+    await cache.getOrRefresh(
+      candidate,
+      async () => {
+        refreshes += 1
+        return entry(candidate, 200)
+      },
+      () => 100,
+    )
+    expect(refreshes).toBe(1)
+    const stored = JSON.parse(await readFile(path, 'utf8'))
+    expect(stored.version).toBe(2)
+    expect(JSON.stringify(stored)).not.toContain('legacy')
+  })
 })
 
-function key(kernelIssuer: string, domainIssuer: string, user: string) {
-  return { kernelIssuer, domainIssuer, user }
+function key(
+  kernelIssuer: string,
+  domainIssuer: string,
+  sourceSubject: string,
+  sourceIssuer = 'https://source.example',
+) {
+  return {
+    kernelIssuer,
+    domainIssuer,
+    sourceIssuer,
+    sourceSubject,
+  }
+}
+
+function entry(
+  candidate: ReturnType<typeof key>,
+  expiresAt: number,
+  malformed?: 'outer-delegation' | 'proof-without-delegation',
+) {
+  return {
+    credential: token(candidate, expiresAt, malformed),
+    expiresAt,
+    user: candidate.sourceSubject,
+    sourceIssuer: candidate.sourceIssuer,
+    sourceSubject: candidate.sourceSubject,
+  }
 }
 
 function token(
@@ -170,12 +211,17 @@ function token(
   const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
   const proof = `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
     iss: candidate.kernelIssuer,
-    sub: candidate.user,
+    sub: candidate.sourceSubject,
     aud: candidate.kernelIssuer,
     exp,
     ...(malformed === 'proof-without-delegation'
       ? {}
-      : { delegation: { v: 1, expr: { kind: 'identity', id: candidate.user } } }),
+      : {
+          delegation: {
+            v: 1,
+            expr: { kind: 'identity', id: candidate.sourceSubject },
+          },
+        }),
   })}.signature`
   return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
     iss: candidate.domainIssuer,

package/src/state/__tests__/files.test.ts

@@ -13,7 +13,7 @@ import {
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
-import { atomicWrite, withFileLock } from '../files'
+import { atomicWrite, atomicWriteSync, withFileLock } from '../files'
 
 let temporaryDirectory: string
 
@@ -50,6 +50,29 @@ describe('atomicWrite', () => {
   })
 })
 
+describe('atomicWriteSync', () => {
+  test('publishes a synced mode-0600 file without temporary residue', async () => {
+    const path = join(temporaryDirectory, 'sync', 'state.json')
+
+    atomicWriteSync(path, '{"value":1}')
+
+    expect(await readFile(path, 'utf-8')).toBe('{"value":1}')
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect(await readdir(join(temporaryDirectory, 'sync'))).toEqual(['state.json'])
+  })
+
+  test('does not disturb the target or retain a temporary file after failure', async () => {
+    const path = join(temporaryDirectory, 'sync-target')
+    await mkdir(path)
+    await writeFile(join(path, 'retained'), 'stable')
+
+    expect(() => atomicWriteSync(path, 'replacement')).toThrow()
+
+    expect(await readFile(join(path, 'retained'), 'utf-8')).toBe('stable')
+    expect((await readdir(temporaryDirectory)).sort()).toEqual(['sync-target'])
+  })
+})
+
 describe('withFileLock', () => {
   /** @evidence TEST-CLI-STATE-LOCK-SERIALIZES */
   test('serializes contending read-modify-write transitions', async () => {

package/src/state/__tests__/fixtures/session-route-process.ts

@@ -0,0 +1,93 @@
+import type { Transport } from '@astrale-os/sdk/client'
+
+import { issuer } from '@astrale-os/sdk/auth'
+import { call, Client } from '@astrale-os/sdk/client'
+import { ClientSession } from '@astrale-os/sdk/client/session'
+import { NodeId } from '@astrale-os/sdk/graph/node'
+import { Path } from '@astrale-os/sdk/graph/path'
+import { invocation } from '@astrale-os/sdk/invocation'
+
+import { FileSessionRouteStore } from '../../session-routes'
+
+const routePath = process.argv[2]
+if (routePath === undefined) throw new Error('route artifact path is required')
+
+const sourceEndpoint = 'https://source.kernel.test/invoke'
+const sourceIssuer = issuer.accept('https://source.kernel.test')
+const destinationEndpoint = 'https://destination.application.test/invoke'
+const target = Path.id(NodeId('session-route-fresh-process'))
+let sourceAttempts = 0
+let destinationAttempts = 0
+
+const route = invocation.acceptRoute({
+  endpoint: { http: destinationEndpoint },
+  via: {
+    kind: 'via',
+    issuer: sourceIssuer,
+    publication: {
+      origin: 'destination.application.test',
+      identity: {
+        issuer: 'https://destination.application.test',
+        subject: 'destination.application.test',
+      },
+      revision: `sha256:${'1'.padStart(64, '0')}`,
+      etag: `sha256:${'1'.padStart(64, '0')}`,
+    },
+  },
+})
+const carrier = `e30.${Buffer.from(
+  JSON.stringify({ exp: Math.floor(Date.now() / 1_000) + 600 }),
+).toString('base64url')}.signature`
+const sourceDispatch: Transport['dispatch'] = async () => {
+  sourceAttempts += 1
+  return {
+    kind: 'redirect',
+    invocation: { source: sourceIssuer, id: 'source-invocation' },
+    redirect: { route, credential: carrier },
+  }
+}
+const destinationDispatch: Transport['dispatch'] = async () => {
+  destinationAttempts += 1
+  return {
+    kind: 'value',
+    value: 'done',
+    invocation: { source: sourceIssuer, id: 'destination-invocation' },
+  }
+}
+const source = new Client({ transport: { dispatch: sourceDispatch } })
+const destination = new Client({ transport: { dispatch: destinationDispatch } })
+const session = new ClientSession({
+  kernel: sourceIssuer,
+  fetch: async () =>
+    new Response(
+      JSON.stringify({
+        protocol: 'astrale-invocation',
+        version: 1,
+        issuer: sourceIssuer,
+        endpoints: { http: sourceEndpoint },
+      }),
+      { headers: { 'content-type': 'application/json' } },
+    ),
+  pool: {
+    clientFor(
+      target: Parameters<
+        NonNullable<ConstructorParameters<typeof ClientSession>[0]['pool']>['clientFor']
+      >[0],
+    ) {
+      const url = target.transport === 'auto' ? target.endpoints.http : target.url
+      return url === sourceEndpoint ? source : destination
+    },
+  },
+  auth: { ttlSeconds: 120, resolve: () => ({ credential: 'source-credential' }) },
+  routeStore: new FileSessionRouteStore(routePath),
+  policy: { maximumRouteAgeMs: 60_000 },
+})
+
+try {
+  const value = await session.call(call(target, null))
+  console.log(JSON.stringify({ value, sourceAttempts, destinationAttempts }))
+} finally {
+  session.close()
+  source.close()
+  destination.close()
+}

package/src/state/__tests__/paths.test.ts

@@ -20,6 +20,7 @@ describe('state paths', () => {
     expect(explicit.home).toBe('/explicit/home')
     expect(explicit.keys).toBe('/environment/keys')
     expect(explicit.config).toBe(join('/explicit/home', 'config.json'))
+    expect(explicit.sessionRoutes).toBe(join('/explicit/home', 'session', 'routes.json'))
     expect(inherited.home).toBe('/environment/home')
     expect(inherited.keys).toBe('/environment/keys')
     expect(Object.isFrozen(explicit)).toBe(true)

package/src/state/__tests__/session-routes.test.ts

@@ -0,0 +1,138 @@
+import type { SessionRouteArtifact } from '@astrale-os/sdk/client/session'
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { access, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { FileSessionRouteStore } from '../session-routes'
+
+let directory: string
+let path: string
+
+beforeEach(async () => {
+  directory = await mkdtemp(join(tmpdir(), 'astrale-session-routes-'))
+  path = join(directory, 'private', 'routes.json')
+})
+
+afterEach(async () => {
+  await rm(directory, { recursive: true, force: true })
+})
+
+describe('session route file store', () => {
+  test('round-trips the Kernel-owned artifact under owner-private filesystem modes', async () => {
+    const artifact: SessionRouteArtifact = { version: 1, entries: {} }
+    const store = new FileSessionRouteStore(path)
+
+    store.write(artifact)
+
+    expect(store.read()).toEqual(artifact)
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect((await stat(join(directory, 'private'))).mode & 0o777).toBe(0o700)
+    expect(await readFile(path, 'utf8')).toBe('{"version":1,"entries":{}}\n')
+
+    store.clear()
+    await expect(access(path)).rejects.toThrow()
+    expect(() => store.clear()).not.toThrow()
+  })
+
+  test('leaves malformed representation recovery to Kernel Client as a cold miss', async () => {
+    await mkdir(join(directory, 'private'))
+    await writeFile(path, '{invalid')
+    const fixture = join(import.meta.dir, 'fixtures', 'session-route-process.ts')
+
+    expect(await runFixture(fixture, path)).toEqual({
+      value: 'done',
+      sourceAttempts: 1,
+      destinationAttempts: 1,
+    })
+    expect(JSON.parse(await readFile(path, 'utf8'))).toMatchObject({ version: 1 })
+  })
+
+  test('reuses Kernel-admitted routing state in a separate operating-system process', async () => {
+    const routePath = join(directory, 'private', 'routes.json')
+    const fixture = join(import.meta.dir, 'fixtures', 'session-route-process.ts')
+
+    const first = await runFixture(fixture, routePath)
+    const second = await runFixture(fixture, routePath)
+
+    expect(first).toEqual({ value: 'done', sourceAttempts: 1, destinationAttempts: 1 })
+    expect(second).toEqual({ value: 'done', sourceAttempts: 0, destinationAttempts: 1 })
+  })
+
+  test('publishes only complete owner-private artifacts under concurrent process writers', async () => {
+    const routePath = join(directory, 'private', 'routes.json')
+    const fixture = join(import.meta.dir, 'fixtures', 'session-route-process.ts')
+
+    const results = await Promise.all(
+      Array.from({ length: 8 }, () => runFixture(fixture, routePath)),
+    )
+    expect(results).toHaveLength(8)
+    expect(results.every((result) => result.destinationAttempts === 1)).toBe(true)
+    expect(JSON.parse(await readFile(routePath, 'utf8'))).toMatchObject({ version: 1 })
+    expect((await stat(routePath)).mode & 0o777).toBe(0o600)
+    expect(await runFixture(fixture, routePath)).toEqual({
+      value: 'done',
+      sourceAttempts: 0,
+      destinationAttempts: 1,
+    })
+  })
+
+  test('auth logout clears every persisted bearer cache through the real CLI command', async () => {
+    const routePath = join(directory, 'session', 'routes.json')
+    const exchangePath = join(directory, 'exchange', 'credentials.json')
+    await mkdir(join(directory, 'session'), { recursive: true })
+    await mkdir(join(directory, 'exchange'), { recursive: true })
+    await writeFile(routePath, '{"version":1,"entries":{"confidential":{}}}\n')
+    await writeFile(
+      exchangePath,
+      '{"version":2,"entries":{"confidential":{"credential":"bearer"}}}\n',
+    )
+
+    const child = Bun.spawn(
+      [
+        process.execPath,
+        join(import.meta.dir, '../../..', 'bin', 'astrale.ts'),
+        'auth',
+        'logout',
+        '--all',
+        '--json',
+      ],
+      {
+        env: { ...process.env, ASTRALE_HOME: directory },
+        stdout: 'pipe',
+        stderr: 'pipe',
+      },
+    )
+    const [exitCode, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ])
+
+    expect(exitCode, stderr).toBe(0)
+    expect(JSON.parse(stdout)).toEqual({ cleared: [] })
+    await expect(access(routePath)).rejects.toThrow()
+    expect(JSON.parse(await readFile(exchangePath, 'utf8'))).toEqual({ version: 2, entries: {} })
+  })
+})
+
+interface FixtureResult {
+  readonly value: string
+  readonly sourceAttempts: number
+  readonly destinationAttempts: number
+}
+
+async function runFixture(fixture: string, routePath: string): Promise<FixtureResult> {
+  const child = Bun.spawn([process.execPath, fixture, routePath], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ])
+  expect(exitCode, stderr).toBe(0)
+  return JSON.parse(stdout) as FixtureResult
+}