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

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

@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  IDENTITY_STORE_VERSION,
+  IdentityStateError,
+  readIdentityStore,
+  updateIdentityStore,
+  type IdentityStore,
+} from '../identities'
+
+let directory: string
+let path: string
+
+const legacy = JSON.stringify(
+  {
+    default: 'manager',
+    identities: {
+      manager: {
+        subject: 'manager',
+        createdAt: '2024-01-01T00:00:00.000Z',
+        source: 'key',
+        mode: 'local',
+      },
+    },
+  },
+  null,
+  2,
+)
+
+beforeEach(async () => {
+  directory = await mkdtemp(join(tmpdir(), 'astrale-identity-state-'))
+  path = join(directory, 'identities.json')
+})
+
+afterEach(async () => {
+  await rm(directory, { recursive: true, force: true })
+})
+
+describe('identity state', () => {
+  /** @evidence TEST-CLI-STATE-IDENTITY-READ-SAFE */
+  test('reads missing, legacy, and current state without writing', async () => {
+    const missing = await readIdentityStore({
+      path,
+      now: () => new Date('2025-01-01T00:00:00.000Z'),
+    })
+    expect(missing.identities.manager.createdAt).toBe('2025-01-01T00:00:00.000Z')
+    await expect(readFile(path, 'utf-8')).rejects.toThrow()
+
+    await writeFile(path, legacy)
+    expect((await readIdentityStore({ path })).default).toBe('manager')
+    expect(await readFile(path, 'utf-8')).toBe(legacy)
+    await expect(readFile(`${path}.v0.bak`, 'utf-8')).rejects.toThrow()
+
+    const current = `${JSON.stringify({ version: IDENTITY_STORE_VERSION, ...missing })}\n`
+    await writeFile(path, current)
+    expect((await readIdentityStore({ path })).identities.manager.subject).toBe('manager')
+    expect(await readFile(path, 'utf-8')).toBe(current)
+  })
+
+  /** @evidence TEST-CLI-STATE-IDENTITY-FAILS-CLOSED */
+  test('rejects malformed and unsupported state without replacing it', async () => {
+    for (const raw of ['{', JSON.stringify({ version: 2, default: 'manager', identities: {} })]) {
+      await writeFile(path, raw)
+      const error = await readIdentityStore({ path }).catch((caught) => caught)
+      expect(error).toBeInstanceOf(IdentityStateError)
+      expect((error as IdentityStateError).code).toBe(
+        raw === '{' ? 'IDENTITY_STATE_INVALID' : 'IDENTITY_STATE_VERSION_UNSUPPORTED',
+      )
+      expect(await readFile(path, 'utf-8')).toBe(raw)
+    }
+  })
+
+  /** @evidence TEST-CLI-STATE-IDENTITY-MIGRATES */
+  test('backs up exact legacy bytes before the first V1 mutation', async () => {
+    await writeFile(path, legacy)
+
+    await updateIdentityStore(
+      (current) => ({ next: { ...current, default: 'alice' }, value: undefined }),
+      { path },
+    )
+
+    expect(await readFile(`${path}.v0.bak`, 'utf-8')).toBe(legacy)
+    expect((await stat(`${path}.v0.bak`)).mode & 0o777).toBe(0o600)
+    const written = JSON.parse(await readFile(path, 'utf-8')) as {
+      version: number
+      default: string
+    }
+    expect(written).toMatchObject({ version: 1, default: 'alice' })
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+  })
+
+  /** @evidence TEST-CLI-STATE-IDENTITY-CONCURRENT */
+  test('retains concurrent selection and registration from separate processes', async () => {
+    const alice = {
+      subject: 'alice',
+      createdAt: '2025-01-01T00:00:00.000Z',
+      source: 'key' as const,
+      mode: 'local' as const,
+    }
+    const bob = { ...alice, subject: 'bob' }
+    await writeFile(
+      path,
+      JSON.stringify({
+        version: IDENTITY_STORE_VERSION,
+        default: 'manager',
+        identities: {
+          manager: { ...alice, subject: 'manager' },
+          alice,
+          bob,
+        },
+      }),
+    )
+    const fixture = join(import.meta.dir, 'fixtures', 'identity-transition.ts')
+    const commands = [
+      ['default', 'alice'],
+      ...Array.from({ length: 8 }, (_, index) => ['registration', 'bob', `instance-${index}`]),
+    ]
+    const processes = commands.map((args) =>
+      Bun.spawn({
+        cmd: ['bun', fixture, ...args],
+        env: { ...process.env, ASTRALE_HOME: directory },
+        stdout: 'pipe',
+        stderr: 'pipe',
+      }),
+    )
+    const outcomes = await Promise.all(
+      processes.map(async (process) => ({
+        code: await process.exited,
+        stderr: await new Response(process.stderr).text(),
+      })),
+    )
+    expect(outcomes).toEqual(outcomes.map(() => ({ code: 0, stderr: '' })))
+
+    const store: IdentityStore = await readIdentityStore({ path })
+    expect(store.default).toBe('alice')
+    expect(Object.keys(store.identities.bob.registrations ?? {})).toHaveLength(8)
+    await expect(readFile(`${path}.lock`, 'utf-8')).rejects.toThrow()
+  })
+})

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

@@ -0,0 +1,27 @@
+import { describe, expect, test } from 'bun:test'
+import { join } from 'node:path'
+
+import { createPaths } from '../paths'
+
+describe('state paths', () => {
+  /** @evidence TEST-CLI-STATE-PATHS-CAPTURED */
+  test('captures explicit and environment coordinates once', () => {
+    const environment: Record<string, string | undefined> = {
+      ASTRALE_HOME: '/environment/home',
+      ASTRALE_KEYS_DIR: '/environment/keys',
+      ASTRALE_DATA_DIR: '/environment/data',
+    }
+    const explicit = createPaths('/explicit/home', environment)
+    const inherited = createPaths(undefined, environment)
+
+    environment.ASTRALE_HOME = '/changed/home'
+    environment.ASTRALE_KEYS_DIR = '/changed/keys'
+
+    expect(explicit.home).toBe('/explicit/home')
+    expect(explicit.keys).toBe('/environment/keys')
+    expect(explicit.config).toBe(join('/explicit/home', 'config.json'))
+    expect(inherited.home).toBe('/environment/home')
+    expect(inherited.keys).toBe('/environment/keys')
+    expect(Object.isFrozen(explicit)).toBe(true)
+  })
+})

package/src/state/exchange-credentials.ts

@@ -0,0 +1,219 @@
+import { credential, grant } from '@astrale-os/sdk/auth'
+import { chmod, mkdir, readFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import { atomicWrite, withFileLock } from './files'
+import { EXCHANGE_CREDENTIALS_PATH } from './paths'
+
+const VERSION = 1
+const MINIMUM_REMAINING_SECONDS = 30
+
+export namespace exchange {
+  export interface Artifact {
+    readonly version: 1
+    readonly entries: Record<string, Entry>
+  }
+
+  export interface Key {
+    readonly kernelIssuer: string
+    readonly domainIssuer: string
+    readonly user: string
+  }
+
+  export interface Entry {
+    readonly credential: string
+    readonly expiresAt: number
+  }
+}
+
+export class ExchangeCredentialCache {
+  private readonly refreshing = new Map<string, Promise<string>>()
+
+  constructor(private readonly path = EXCHANGE_CREDENTIALS_PATH) {}
+
+  getOrRefresh(
+    key: exchange.Key,
+    refresh: () => Promise<exchange.Entry>,
+    now = () => Math.floor(Date.now() / 1_000),
+  ): Promise<string> {
+    const encoded = encodeKey(key)
+    const current = this.refreshing.get(encoded)
+    if (current !== undefined) return current
+    const pending = this.getOrRefreshOnce(key, encoded, refresh, now).finally(() => {
+      this.refreshing.delete(encoded)
+    })
+    this.refreshing.set(encoded, pending)
+    return pending
+  }
+
+  async deleteKernel(kernelIssuer: string): Promise<void> {
+    await this.transition((store) => {
+      for (const encoded of Object.keys(store.entries)) {
+        const key = decodeKey(encoded)
+        if (key === undefined || key.kernelIssuer === kernelIssuer) delete store.entries[encoded]
+      }
+    })
+  }
+
+  async clear(): Promise<void> {
+    await this.transition((store) => {
+      for (const encoded of Object.keys(store.entries)) delete store.entries[encoded]
+    })
+  }
+
+  private async getOrRefreshOnce(
+    key: exchange.Key,
+    encoded: string,
+    refresh: () => Promise<exchange.Entry>,
+    now: () => number,
+  ): Promise<string> {
+    return withFileLock(`${this.path}.lock`, async () => {
+      await ensurePrivateDirectory(this.path)
+      const store = await readStore(this.path)
+      const changed = scrub(store, now())
+      const cached = store.entries[encoded]
+      if (cached !== undefined && validEntry(key, cached, now())) {
+        if (changed) await writeStore(this.path, store)
+        return cached.credential
+      }
+
+      const next = await refresh()
+      if (!validEntry(key, next, now(), 1)) {
+        throw new Error('Token exchange returned a credential inconsistent with its cache key.')
+      }
+      store.entries[encoded] = Object.freeze({ ...next })
+      await writeStore(this.path, store)
+      return next.credential
+    })
+  }
+
+  private async transition(change: (store: exchange.Artifact) => void): Promise<void> {
+    await withFileLock(`${this.path}.lock`, async () => {
+      await ensurePrivateDirectory(this.path)
+      const store = await readStore(this.path)
+      change(store)
+      await writeStore(this.path, store)
+    })
+  }
+}
+
+async function readStore(path: string): Promise<exchange.Artifact> {
+  try {
+    const input = JSON.parse(await readFile(path, 'utf8')) as unknown
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) return emptyStore()
+    const value = input as Record<string, unknown>
+    if (
+      value.version !== VERSION ||
+      value.entries === null ||
+      typeof value.entries !== 'object' ||
+      Array.isArray(value.entries)
+    ) {
+      return emptyStore()
+    }
+    return { version: VERSION, entries: { ...(value.entries as Record<string, exchange.Entry>) } }
+  } catch {
+    return emptyStore()
+  }
+}
+
+function emptyStore(): exchange.Artifact {
+  return { version: VERSION, entries: {} }
+}
+
+async function writeStore(path: string, store: exchange.Artifact): Promise<void> {
+  await atomicWrite(path, `${JSON.stringify(store, null, 2)}\n`)
+  await chmod(path, 0o600)
+}
+
+async function ensurePrivateDirectory(path: string): Promise<void> {
+  const directory = dirname(path)
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+  await chmod(directory, 0o700)
+}
+
+function validEntry(
+  key: exchange.Key,
+  entry: exchange.Entry,
+  now: number,
+  minimumRemaining = MINIMUM_REMAINING_SECONDS,
+): boolean {
+  if (
+    entry === null ||
+    typeof entry !== 'object' ||
+    Reflect.ownKeys(entry).length !== 2 ||
+    typeof entry.credential !== 'string' ||
+    entry.credential.length === 0 ||
+    !Number.isSafeInteger(entry.expiresAt) ||
+    entry.expiresAt - now < minimumRemaining
+  ) {
+    return false
+  }
+  try {
+    const inspected = credential.inspect(entry.credential)
+    const carried = grant.acceptUnresolved(inspected.claims.grant).expr
+    if (
+      carried.kind !== 'identity' ||
+      !('credential' in carried) ||
+      typeof carried.credential !== 'string'
+    ) {
+      return false
+    }
+    const proof = credential.inspect(carried.credential)
+    const issued = proof.claims.delegation
+    if (
+      issued === null ||
+      typeof issued !== 'object' ||
+      Array.isArray(issued) ||
+      Reflect.ownKeys(issued).length !== 2 ||
+      !Object.hasOwn(issued, 'v') ||
+      !Object.hasOwn(issued, 'expr') ||
+      Reflect.get(issued, 'v') !== 1
+    ) {
+      return false
+    }
+    grant.accept({ expr: Reflect.get(issued, 'expr') })
+    return (
+      inspected.iss === key.domainIssuer &&
+      inspected.aud === key.kernelIssuer &&
+      inspected.claims.exp === entry.expiresAt &&
+      !Object.hasOwn(inspected.claims, 'delegation') &&
+      proof.iss === key.kernelIssuer &&
+      proof.sub === key.user &&
+      proof.aud === key.kernelIssuer
+    )
+  } catch {
+    return false
+  }
+}
+
+function encodeKey(key: exchange.Key): string {
+  return JSON.stringify([key.kernelIssuer, key.domainIssuer, key.user])
+}
+
+function decodeKey(input: string): exchange.Key | undefined {
+  try {
+    const value = JSON.parse(input) as unknown
+    if (
+      !Array.isArray(value) ||
+      value.length !== 3 ||
+      value.some((part) => typeof part !== 'string' || part.length === 0)
+    ) {
+      return undefined
+    }
+    return { kernelIssuer: value[0]!, domainIssuer: value[1]!, user: value[2]! }
+  } catch {
+    return undefined
+  }
+}
+
+function scrub(store: Pick<exchange.Artifact, 'entries'>, now: number): boolean {
+  let changed = false
+  for (const [encoded, entry] of Object.entries(store.entries)) {
+    const key = decodeKey(encoded)
+    if (key === undefined || !validEntry(key, entry, now, 1)) {
+      delete store.entries[encoded]
+      changed = true
+    }
+  }
+  return changed
+}

package/src/state/files.ts

@@ -0,0 +1,129 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, open, readFile, rename, stat, unlink } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/** Atomically publish one complete private state file through a same-directory temporary file. */
+export async function atomicWrite(path: string, data: string): Promise<void> {
+  const directory = dirname(path)
+  const temporary = `${path}.${randomUUID()}.tmp`
+  await mkdir(directory, { recursive: true })
+
+  let handle: Awaited<ReturnType<typeof open>> | undefined
+  try {
+    handle = await open(temporary, 'wx', 0o600)
+    await handle.writeFile(data)
+    await handle.sync()
+    await handle.close()
+    handle = undefined
+    await rename(temporary, path)
+
+    const directoryHandle = await open(directory, 'r')
+    try {
+      await directoryHandle.sync()
+    } finally {
+      await directoryHandle.close()
+    }
+  } catch (error) {
+    await handle?.close().catch(() => undefined)
+    await unlink(temporary).catch(() => undefined)
+    throw error
+  }
+}
+
+export interface FileLockOptions {
+  readonly pollIntervalMs?: number
+  readonly staleAfterMs?: number
+  readonly timeoutMs?: number
+}
+
+/** Run one transition under a bounded cross-process create-exclusive lock. */
+export async function withFileLock<Value>(
+  lockPath: string,
+  transition: () => Promise<Value>,
+  options: FileLockOptions = {},
+): Promise<Value> {
+  const pollIntervalMs = options.pollIntervalMs ?? 100
+  const staleAfterMs = options.staleAfterMs ?? 30_000
+  const timeoutMs = options.timeoutMs ?? 60_000
+  const deadline = Date.now() + timeoutMs
+
+  for (;;) {
+    if (await tryAcquire(lockPath)) {
+      try {
+        return await transition()
+      } finally {
+        await unlink(lockPath).catch(() => undefined)
+      }
+    }
+    if (await takeoverIfAbandoned(lockPath, staleAfterMs)) continue
+    if (Date.now() >= deadline) {
+      throw new Error(`Timed out after ${timeoutMs}ms waiting for lock ${lockPath}`)
+    }
+    await sleep(pollIntervalMs)
+  }
+}
+
+async function tryAcquire(lockPath: string): Promise<boolean> {
+  try {
+    const handle = await open(lockPath, 'wx', 0o600)
+    try {
+      await handle.writeFile(
+        JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }),
+      )
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    return true
+  } catch (error) {
+    const code = (error as { code?: string }).code
+    if (code === 'EEXIST') return false
+    if (code === 'ENOENT') {
+      await mkdir(dirname(lockPath), { recursive: true })
+      return tryAcquire(lockPath)
+    }
+    throw error
+  }
+}
+
+async function takeoverIfAbandoned(lockPath: string, staleAfterMs: number): Promise<boolean> {
+  try {
+    const info = await stat(lockPath)
+    if (Date.now() - info.mtimeMs > staleAfterMs) {
+      await unlink(lockPath).catch(() => undefined)
+      return true
+    }
+  } catch (error) {
+    if ((error as { code?: string }).code === 'ENOENT') return true
+    throw error
+  }
+
+  const pid = await readLockPid(lockPath)
+  if (pid !== undefined && pid !== process.pid && !isPidAlive(pid)) {
+    await unlink(lockPath).catch(() => undefined)
+    return true
+  }
+  return false
+}
+
+async function readLockPid(lockPath: string): Promise<number | undefined> {
+  try {
+    const value = (JSON.parse(await readFile(lockPath, 'utf-8')) as { pid?: unknown }).pid
+    return typeof value === 'number' ? value : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as { code?: string }).code === 'EPERM'
+  }
+}
+
+function sleep(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}