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

package/src/identity/__tests__/fixtures/registry-journey.ts

@@ -0,0 +1,53 @@
+import { fileExists, keypairPaths } from '../../../keys/index'
+import { KEYS_DIR } from '../../../state/index'
+import {
+  createIdentity,
+  exportIdentity,
+  importIdentity,
+  deleteIdentity,
+  getDefault,
+  readIdentities,
+  setDefault,
+  setIdentityMode,
+  setRegistration,
+  upsertIdpIdentity,
+} from '../../index'
+
+await createIdentity('alice')
+await createIdentity('bob', { mode: 'remote' })
+await importIdentity(await exportIdentity('alice'), { name: 'alice-alias' })
+await setDefault('alice')
+await setIdentityMode('bob', 'local')
+await setRegistration('alice', 'production', {
+  iss: 'https://kernel.example',
+  sub: 'node-alice',
+  registeredAt: '2026-08-11T12:00:00.000Z',
+})
+
+let selectedDeletion = ''
+try {
+  await deleteIdentity('alice')
+} catch (error) {
+  selectedDeletion = error instanceof Error ? error.message : String(error)
+}
+await deleteIdentity('bob')
+await deleteIdentity('alice-alias')
+await upsertIdpIdentity('workos', {
+  subject: 'user_123',
+  idp: 'workos',
+  issuer: 'https://idp.example',
+  audience: 'https://kernel.example',
+  use: false,
+})
+
+const store = await readIdentities()
+const selected = await getDefault()
+console.log(
+  JSON.stringify({
+    store,
+    selected,
+    selectedDeletion,
+    aliceKey: await fileExists(keypairPaths('alice', KEYS_DIR).privatePath),
+    bobKey: await fileExists(keypairPaths('bob', KEYS_DIR).privatePath),
+  }),
+)

package/src/identity/__tests__/registration.test.ts

@@ -0,0 +1,64 @@
+import type { ProvisionRequest } from '@astrale-os/sdk/auth'
+
+import { LocalBinding } from '@astrale-os/sdk/graph/model'
+import { expect, test } from 'bun:test'
+
+import { submitIdentityProvision } from '../registration'
+
+/** @evidence TEST-CLI-IDENTITY-REGISTER-DOMAIN-MEDIATED */
+test('submits the exact self-proven request through an explicit Domain callable', async () => {
+  const binding = LocalBinding('identity')
+  const request = {
+    idempotencyKey: 'identity-register:operator',
+    mutation: {
+      format: 'astrale.graph.mutation',
+      version: 'v2',
+      preconditions: [],
+      operations: [],
+    },
+    identities: {
+      identity: {
+        credentials: {
+          publicKey: { kty: 'EC', crv: 'P-256', x: 'x', y: 'y', alg: 'ES256' },
+          proof: 'self-proven-request.jwt.signature',
+        },
+      },
+    },
+  } as unknown as ProvisionRequest
+  const calls: unknown[] = []
+  let directCalls = 0
+  const result = await submitIdentityProvision({
+    binding,
+    request,
+    via: '/:ops.example:function.provisionOperator',
+    direct: {
+      async provision() {
+        directCalls += 1
+        throw new Error('direct provision must not run')
+      },
+    },
+    callable: {
+      async call(call) {
+        calls.push(call)
+        return {
+          createdNodes: { identity: 'operator-node' },
+          identities: {
+            identity: { issuer: 'https://identity.example', subject: 'operator-node' },
+          },
+        }
+      },
+    },
+  })
+
+  expect(directCalls).toBe(0)
+  expect(calls).toHaveLength(1)
+  expect(JSON.parse(JSON.stringify(calls[0]))).toEqual({
+    target: '/:ops.example:function.provisionOperator',
+    input: JSON.parse(JSON.stringify(request)),
+  })
+  expect(result).toEqual({
+    iss: 'https://identity.example',
+    sub: 'operator-node',
+    nodeId: 'operator-node',
+  })
+})

package/src/identity/__tests__/registry.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+describe('identity registry journey', () => {
+  let root = ''
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'astrale-identity-registry-'))
+  })
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  /** @evidence TEST-CLI-IDENTITY-REGISTRY-JOURNEY */
+  test('runs create, selection, registration, mode, IdP, and deletion in a real process', async () => {
+    const child = Bun.spawn(
+      [process.execPath, join(import.meta.dir, 'fixtures', 'registry-journey.ts')],
+      {
+        env: { ...process.env, ASTRALE_HOME: root },
+        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)
+
+    const result = JSON.parse(stdout) as {
+      store: {
+        default: string
+        identities: Record<
+          string,
+          {
+            source?: string
+            mode?: string
+            registrations?: Record<string, { iss: string; sub: string; registeredAt: string }>
+          }
+        >
+      }
+      selected: { name: string; subject: string }
+      selectedDeletion: string
+      aliceKey: boolean
+      bobKey: boolean
+    }
+    expect(result.store.default).toBe('alice')
+    expect(Object.keys(result.store.identities).sort()).toEqual(['alice', 'manager', 'workos'])
+    expect(result.store.identities.alice.registrations?.production).toEqual({
+      iss: 'https://kernel.example',
+      sub: 'node-alice',
+      registeredAt: '2026-08-11T12:00:00.000Z',
+    })
+    expect(result.store.identities.workos).toMatchObject({ source: 'idp', mode: 'remote' })
+    expect(result.selected).toMatchObject({ name: 'alice', subject: 'alice' })
+    expect(result.selectedDeletion).toContain('Cannot delete the default identity')
+    expect(result.aliceKey).toBe(true)
+    expect(result.bobKey).toBe(false)
+
+    const persisted = JSON.parse(await readFile(join(root, 'identities.json'), 'utf-8')) as {
+      version?: unknown
+    }
+    expect(persisted.version).toBe(1)
+    expect(stdout).not.toContain('"d":')
+  })
+})

package/src/identity/__tests__/transfer.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { access, mkdtemp, readFile, readdir, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { keypairPaths, persistKeypair, readKeypair } from '../../keys/index'
+import { readIdentityStore, updateIdentityStore } from '../../state/index'
+import {
+  decodeIdentityExport,
+  encodeIdentityExport,
+  exportIdentity,
+  importIdentity,
+  isEncryptedIdentityExport,
+  writeIdentityExport,
+  type IdentityExport,
+} from '../index'
+
+describe('identity transfer', () => {
+  let root = ''
+  let statePath = ''
+  let keysDir = ''
+  const now = () => new Date('2026-08-11T12:00:00.000Z')
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'astrale-identity-transfer-'))
+    statePath = join(root, 'identities.json')
+    keysDir = join(root, 'keys')
+  })
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  async function envelope(subject: string, suffix: string): Promise<IdentityExport> {
+    const pair = await persistKeypair(subject, {
+      keysDir: join(root, `source-${suffix}`),
+      kid: `${subject}-${suffix}`,
+    })
+    return decodeIdentityExport(
+      JSON.stringify({
+        version: 1,
+        subject,
+        mode: 'local',
+        kid: pair.kid,
+        issuer: 'https://identity.example',
+        privateJwk: pair.privateJwk,
+        publicJwk: pair.publicJwk,
+      }),
+    )
+  }
+
+  /** @evidence TEST-CLI-IDENTITY-TRANSFER-REJECTS */
+  test('rejects malformed, newer, and mismatched content before durable mutation', async () => {
+    await expect(decodeIdentityExport('{')).rejects.toThrow(/not valid JSON/)
+    await expect(
+      decodeIdentityExport(
+        JSON.stringify({
+          version: 2,
+          subject: 'alice',
+          mode: 'local',
+          privateJwk: {},
+          publicJwk: {},
+        }),
+      ),
+    ).rejects.toThrow(/invalid or unsupported shape/)
+
+    const alice = await envelope('alice', 'a')
+    const bob = await envelope('bob', 'b')
+    const forged = {
+      ...alice,
+      publicJwk: { ...bob.publicJwk, kid: alice.kid },
+    } as IdentityExport
+    const mismatch = await importIdentity(forged, {
+      state: { path: statePath, now },
+      keysDir,
+    }).catch((error) => error)
+    expect(mismatch).toBeInstanceOf(Error)
+    expect((mismatch as Error).message).toMatch(/do not form a valid matching pair/)
+    expect((mismatch as Error).message).not.toContain(String(alice.privateJwk.d))
+
+    await expect(access(statePath)).rejects.toThrow()
+    await expect(access(keypairPaths('alice', keysDir).privatePath)).rejects.toThrow()
+  })
+
+  /** @evidence TEST-CLI-IDENTITY-TRANSFER-ROUNDTRIP */
+  test('converges legacy, V1, and encrypted representations on one envelope', async () => {
+    const current = await envelope('alice', 'roundtrip')
+    const { version: _, ...legacy } = current
+    expect(await decodeIdentityExport(JSON.stringify(legacy))).toEqual(current)
+
+    const plaintext = await encodeIdentityExport(current)
+    expect(isEncryptedIdentityExport(plaintext)).toBe(false)
+    expect(await decodeIdentityExport(plaintext)).toEqual(current)
+
+    const encrypted = await encodeIdentityExport(current, 'correct-horse-battery')
+    expect(isEncryptedIdentityExport(encrypted)).toBe(true)
+    expect(await decodeIdentityExport(encrypted, 'correct-horse-battery')).toEqual(current)
+    await expect(decodeIdentityExport(encrypted, 'wrong')).rejects.toThrow(/Could not decrypt/)
+  })
+
+  /** @evidence TEST-CLI-IDENTITY-TRANSFER-SCHEMA */
+  test('keeps the portable V1 JSON Schema aligned with the admitted identity envelope', async () => {
+    const schemaPath = fileURLToPath(
+      new URL('../.spec/schemas/identity-export-v1.schema.json', import.meta.url),
+    )
+    const schema = JSON.parse(await readFile(schemaPath, 'utf8')) as {
+      readonly $id: string
+      readonly additionalProperties: boolean
+      readonly required: readonly string[]
+      readonly properties: Readonly<Record<string, unknown>>
+    }
+    const identityEnvelope = await envelope('manager-principal', 'host-bootstrap')
+
+    expect(schema.$id).toBe('https://schemas.astrale.ai/cli/identity-export/1')
+    expect(schema.additionalProperties).toBe(false)
+    expect(schema.required).toEqual(['version', 'subject', 'privateJwk', 'publicJwk'])
+    expect(Object.keys(schema.properties).sort()).toEqual(
+      ['issuer', 'kid', 'mode', 'privateJwk', 'publicJwk', 'subject', 'version'].sort(),
+    )
+    await expect(decodeIdentityExport(JSON.stringify(identityEnvelope))).resolves.toEqual(
+      identityEnvelope,
+    )
+  })
+
+  /** @evidence TEST-CLI-IDENTITY-IMPORT-ORDERED */
+  test('checks conflicts before key replacement and publishes registry after keys', async () => {
+    const first = await envelope('alice', 'first')
+    const imported = await importIdentity(first, {
+      name: 'operator',
+      state: { path: statePath, now },
+      keysDir,
+    })
+    expect(imported.subject).toBe('alice')
+    expect((await readKeypair('alice', keysDir)).kid).toBe(first.kid)
+    expect((await readIdentityStore({ path: statePath })).identities.operator).toEqual(imported)
+
+    const privatePath = keypairPaths('alice', keysDir).privatePath
+    const originalPrivate = await readFile(privatePath, 'utf-8')
+    const replacement = await envelope('alice', 'replacement')
+    await expect(
+      importIdentity(replacement, {
+        name: 'operator',
+        state: { path: statePath, now },
+        keysDir,
+      }),
+    ).rejects.toThrow('already exists')
+    expect(await readFile(privatePath, 'utf-8')).toBe(originalPrivate)
+
+    await updateIdentityStore(
+      (store) => ({
+        next: {
+          ...store,
+          identities: {
+            ...store.identities,
+            remote: {
+              subject: 'remote-user',
+              createdAt: now().toISOString(),
+              source: 'idp',
+              mode: 'remote',
+              idp: 'workos',
+              issuer: 'https://idp.example',
+            },
+          },
+        },
+        value: undefined,
+      }),
+      { path: statePath, now },
+    )
+    await expect(
+      importIdentity(await envelope('remote-user', 'remote'), {
+        name: 'remote',
+        replace: true,
+        state: { path: statePath, now },
+        keysDir,
+      }),
+    ).rejects.toThrow(/IdP-backed/)
+    await expect(access(keypairPaths('remote-user', keysDir).privatePath)).rejects.toThrow()
+  })
+
+  /** @evidence TEST-CLI-IDENTITY-EXPORT-PRIVATE */
+  test('exports a proven pair through one atomic mode-0600 file', async () => {
+    await importIdentity(await envelope('alice', 'export'), {
+      state: { path: statePath, now },
+      keysDir,
+    })
+    const exported = await exportIdentity('alice', {
+      state: { path: statePath, now },
+      keysDir,
+    })
+    const path = join(root, 'alice.identity.json')
+    await writeIdentityExport(path, await encodeIdentityExport(exported))
+
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect(await decodeIdentityExport(await readFile(path, 'utf-8'))).toEqual(exported)
+    expect((await readdir(root)).some((entry) => entry.endsWith('.tmp'))).toBe(false)
+  })
+})

package/src/identity/index.ts

@@ -0,0 +1,23 @@
+export {
+  createIdentity,
+  deleteIdentity,
+  getDefault,
+  getIdentity,
+  readIdentities,
+  setDefault,
+  setIdentityMode,
+  setRegistration,
+  upsertIdpIdentity,
+} from './registry'
+export {
+  decodeIdentityExport,
+  encodeIdentityExport,
+  exportIdentity,
+  importIdentity,
+  isEncryptedIdentityExport,
+  writeIdentityExport,
+} from './transfer'
+export { acceptProvisionedIdentity, submitIdentityProvision } from './registration'
+export type { IdentityProvisionSubmission, IdentityRegistrationResult } from './registration'
+export type { Identity, IdentityStore, Registration } from './registry'
+export type { IdentityExport, IdentityFileOptions, IdentityImportOptions } from './transfer'

package/src/identity/registration.ts

@@ -0,0 +1,72 @@
+import type { Call } from '@astrale-os/kernel-client'
+import type { ProvisionRequest } from '@astrale-os/sdk/auth'
+import type { LocalBinding } from '@astrale-os/sdk/graph/model'
+
+import { call } from '@astrale-os/kernel-client'
+import { issuer } from '@astrale-os/sdk/auth'
+import { NodeId } from '@astrale-os/sdk/graph/node'
+import { Path } from '@astrale-os/sdk/graph/path'
+
+export interface IdentityRegistrationResult {
+  readonly iss: string
+  readonly sub: string
+  readonly nodeId?: string
+}
+
+export interface IdentityProvisionSubmission {
+  readonly request: ProvisionRequest
+  readonly binding: LocalBinding
+  readonly via?: string
+  readonly direct: {
+    provision(request: ProvisionRequest): Promise<unknown>
+  }
+  readonly callable: {
+    call(call: Call): Promise<unknown>
+  }
+}
+
+/** Submit one prepared request either directly or through its explicit Domain authority owner. */
+export async function submitIdentityProvision(
+  input: IdentityProvisionSubmission,
+): Promise<IdentityRegistrationResult> {
+  const result =
+    input.via === undefined
+      ? await input.direct.provision(input.request)
+      : await input.callable.call(
+          // Client admits the portable value before transport. ProvisionRequest is the
+          // stricter semantic type but does not declare the portable Object index signature.
+          call(Path.parse(input.via), input.request as unknown as Call['input']),
+        )
+  return acceptProvisionedIdentity(result, input.binding)
+}
+
+/** Admit only the exact binding the CLI prepared; remote callables remain untrusted input. */
+export function acceptProvisionedIdentity(
+  value: unknown,
+  binding: LocalBinding,
+): IdentityRegistrationResult {
+  const result = record(value, 'Provision result')
+  const identities = record(result.identities, 'Provision result identities')
+  const identity = record(identities[binding], 'Provision result identity binding')
+  const createdNodes = record(result.createdNodes, 'Provision result created Nodes')
+  const node = createdNodes[binding]
+  return Object.freeze({
+    iss: issuer.accept(text(identity.issuer, 'Provisioned Identity issuer')),
+    sub: text(identity.subject, 'Provisioned Identity subject'),
+    ...(node === undefined ? {} : { nodeId: NodeId(text(node, 'Provisioned Identity Node')) }),
+  })
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object.`)
+  }
+  return value as Record<string, unknown>
+}
+
+function text(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${label} must be non-empty text.`)
+  }
+  return value
+}

package/src/identity/registry.ts

@@ -0,0 +1,172 @@
+import { persistKeypair, removeKeypair } from '../keys/index'
+import { deleteIdpSession } from '../lib/idp'
+import { validateName } from '../lib/validation'
+import {
+  readIdentityStore,
+  updateIdentityStore,
+  type Identity,
+  type IdentityMode,
+  type IdentityStore,
+  type Registration,
+  ExchangeCredentialCache,
+} from '../state/index'
+
+export type { Identity, IdentityStore, Registration } from '../state/index'
+
+export async function readIdentities(): Promise<IdentityStore> {
+  return readIdentityStore()
+}
+
+export async function createIdentity(
+  name: string,
+  options: {
+    readonly subject?: string
+    readonly mode?: IdentityMode
+    readonly issuer?: string
+    readonly kid?: string
+  } = {},
+): Promise<Identity> {
+  validateName(name, 'Identity')
+  return updateIdentityStore(async (store) => {
+    if (store.identities[name]) throw new Error(`Identity "${name}" already exists`)
+
+    const subject = options.subject ?? name
+    const generated = await persistKeypair(subject, { kid: options.kid })
+    const identity: Identity = {
+      subject,
+      createdAt: new Date().toISOString(),
+      source: 'key',
+      mode: options.mode ?? 'local',
+      kid: generated.kid,
+      issuer: options.issuer,
+    }
+    return {
+      next: { ...store, identities: { ...store.identities, [name]: identity } },
+      value: identity,
+    }
+  })
+}
+
+export async function deleteIdentity(name: string): Promise<void> {
+  await updateIdentityStore(async (store) => {
+    const entry = store.identities[name]
+    if (!entry) throw new Error(`Identity "${name}" not found`)
+    if (store.default === name) {
+      throw new Error(
+        `Cannot delete the default identity "${name}". Switch default first with: astrale identity use <other>`,
+      )
+    }
+    if ((entry.source ?? 'key') === 'idp') await deleteIdpSession(name)
+    else if (!hasAnotherKeyIdentity(store, name, entry.subject)) await removeKeypair(entry.subject)
+
+    const { [name]: _, ...identities } = store.identities
+    return { next: { ...store, identities }, value: undefined }
+  })
+  await new ExchangeCredentialCache().clear()
+}
+
+function hasAnotherKeyIdentity(store: IdentityStore, name: string, subject: string): boolean {
+  return Object.entries(store.identities).some(
+    ([candidateName, candidate]) =>
+      candidateName !== name &&
+      (candidate.source ?? 'key') === 'key' &&
+      candidate.subject === subject,
+  )
+}
+
+export async function setDefault(name: string): Promise<void> {
+  await updateIdentityStore((store) => {
+    if (!store.identities[name]) throw new Error(`Identity "${name}" not found`)
+    return { next: { ...store, default: name }, value: undefined }
+  })
+}
+
+export async function getDefault(): Promise<Identity & { readonly name: string }> {
+  const store = await readIdentities()
+  const identity = store.identities[store.default]
+  if (!identity) {
+    throw new Error(
+      `Default identity "${store.default}" not found. Run: astrale identity create ${store.default}`,
+    )
+  }
+  return { ...identity, name: store.default }
+}
+
+export async function getIdentity(name: string): Promise<Identity> {
+  const store = await readIdentities()
+  const identity = store.identities[name]
+  if (!identity) {
+    throw new Error(`Identity "${name}" not found. Run: astrale identity create ${name}`)
+  }
+  return identity
+}
+
+export async function upsertIdpIdentity(
+  name: string,
+  options: {
+    readonly subject: string
+    readonly idp: string
+    readonly issuer: string
+    readonly audience?: string
+    readonly claims?: Readonly<Record<string, unknown>>
+    readonly use?: boolean
+  },
+): Promise<Identity> {
+  validateName(name, 'Identity')
+  validateName(options.idp, 'IdP')
+  return updateIdentityStore((store) => {
+    const existing = store.identities[name]
+    if (existing && (existing.source ?? 'key') !== 'idp') {
+      throw new Error(`Identity "${name}" already exists and is key-backed`)
+    }
+    const identity: Identity = {
+      subject: options.subject,
+      createdAt: existing?.createdAt ?? new Date().toISOString(),
+      source: 'idp',
+      mode: 'remote',
+      idp: options.idp,
+      issuer: options.issuer,
+      audience: options.audience,
+      claims: options.claims,
+      registrations: existing?.registrations,
+    }
+    return {
+      next: {
+        default: options.use === false ? store.default : name,
+        identities: { ...store.identities, [name]: identity },
+      },
+      value: identity,
+    }
+  })
+}
+
+export async function setRegistration(
+  name: string,
+  instanceSlug: string,
+  registration: Registration,
+): Promise<void> {
+  await updateIdentityStore((store) => {
+    const entry = store.identities[name]
+    if (!entry) throw new Error(`Identity "${name}" not found`)
+    const identity: Identity = {
+      ...entry,
+      registrations: { ...entry.registrations, [instanceSlug]: registration },
+    }
+    return {
+      next: { ...store, identities: { ...store.identities, [name]: identity } },
+      value: undefined,
+    }
+  })
+}
+
+export async function setIdentityMode(name: string, mode: IdentityMode): Promise<void> {
+  await updateIdentityStore((store) => {
+    const entry = store.identities[name]
+    if (!entry) throw new Error(`Identity "${name}" not found`)
+    const identity: Identity = { ...entry, mode }
+    return {
+      next: { ...store, identities: { ...store.identities, [name]: identity } },
+      value: undefined,
+    }
+  })
+}