@astrale-os/cli 1.0.0-beta.32 → 1.0.0-beta.43

package/src/keys/__tests__/keys.test.ts

@@ -1,172 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
-import { decodeJwt, decodeProtectedHeader } from 'jose'
-import { access, mkdtemp, rm, stat, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-
-import { IdentityKeyMissingError } from '../../errors'
-import {
-  generateEd25519Jwk,
-  importKeypair,
-  keypairPaths,
-  listIdentityKeys,
-  persistKeypair,
-  readKeypair,
-  removeKeypair,
-  signAs,
-} from '../index'
-
-describe('DESIGN — per-identity keys', () => {
-  let tmp = ''
-
-  beforeEach(async () => {
-    tmp = await mkdtemp(join(tmpdir(), 'astrale-keys-test-'))
-  })
-
-  afterEach(async () => {
-    await rm(tmp, { recursive: true, force: true })
-  })
-
-  /** @evidence TEST-CLI-KEYS-LEGACY-FILENAMES */
-  test('keypairPaths routes manager to legacy filenames', () => {
-    const p = keypairPaths('manager', tmp)
-    expect(p.privatePath.endsWith('manager.private.jwk')).toBe(true)
-    expect(p.publicPath.endsWith('manager.public.jwk')).toBe(true)
-  })
-
-  test('keypairPaths routes others to <name>.*.jwk', () => {
-    const p = keypairPaths('alice', tmp)
-    expect(p.privatePath.endsWith('alice.private.jwk')).toBe(true)
-    expect(p.publicPath.endsWith('alice.public.jwk')).toBe(true)
-  })
-
-  /** @evidence TEST-CLI-KEYS-PATH-CONFINED */
-  test('keypairPaths rejects subjects that escape the selected key directory', () => {
-    expect(() => keypairPaths('../alice', tmp)).toThrow(/cannot name a key file/)
-    expect(() => keypairPaths('/alice', tmp)).toThrow(/cannot name a key file/)
-    expect(() => keypairPaths('', tmp)).toThrow(/cannot name a key file/)
-  })
-
-  /** @evidence TEST-CLI-KEYS-PRIVATE-MODE */
-  test('persistKeypair writes both files with kid and private mode', async () => {
-    const result = await persistKeypair('alice', { keysDir: tmp })
-    expect(result.kid).toMatch(/^alice-key-/)
-    const { privatePath, publicPath } = keypairPaths('alice', tmp)
-    await access(privatePath)
-    await access(publicPath)
-    expect((await stat(privatePath)).mode & 0o777).toBe(0o600)
-    expect((await stat(publicPath)).mode & 0o777).toBe(0o600)
-  })
-
-  test('signAs(alice) works when alice has her own key', async () => {
-    await persistKeypair('alice', { keysDir: tmp })
-    const jwt = await signAs('alice', tmp)
-    expect(jwt.split('.').length).toBe(3)
-    const claims = decodeJwt(jwt)
-    expect(claims.iat).toBeUndefined()
-    expect(claims.exp).toBeNumber()
-    expect((claims.exp as number) * 1_000).toBeGreaterThan(Date.now() + 299_000)
-  })
-
-  /** @evidence TEST-CLI-KEYS-DISTINGUISHES-KERNEL-ROOT-GRANT */
-  test('signAs resolves self-issued Kernel root grants and preserves external self grants', async () => {
-    await persistKeypair('manager-principal', { keysDir: tmp })
-    await persistKeypair('alice', { keysDir: tmp })
-    const kernel = 'https://kernel.example/kernel/host'
-
-    const root = decodeJwt(
-      await signAs('manager-principal', tmp, {
-        issuer: kernel,
-        audience: kernel,
-      }),
-    )
-    expect(root).toMatchObject({
-      iss: kernel,
-      sub: 'manager-principal',
-      aud: kernel,
-      grant: { v: 1, expr: { kind: 'identity', id: 'manager-principal' } },
-    })
-
-    const external = decodeJwt(
-      await signAs('alice', tmp, {
-        issuer: 'https://identity.example',
-        audience: kernel,
-      }),
-    )
-    expect(external).toMatchObject({
-      iss: 'https://identity.example',
-      sub: 'alice',
-      aud: kernel,
-      grant: { v: 1, expr: { kind: 'identity', self: true } },
-    })
-  })
-
-  test('signAs(alice) uses the key file algorithm for EdDSA identities', async () => {
-    const { privateJwk, publicJwk } = await generateEd25519Jwk('alice-ed25519')
-    const { privatePath, publicPath } = keypairPaths('alice', tmp)
-    await writeFile(privatePath, JSON.stringify(privateJwk, null, 2))
-    await writeFile(publicPath, JSON.stringify(publicJwk, null, 2))
-
-    const jwt = await signAs('alice', tmp)
-
-    expect(decodeProtectedHeader(jwt).alg).toBe('EdDSA')
-  })
-
-  /** @evidence TEST-CLI-KEYS-PAIR-ADMISSION */
-  test('import and read prove one matching supported keypair before publication', async () => {
-    const alice = await persistKeypair('alice', { keysDir: join(tmp, 'alice-source') })
-    const bob = await persistKeypair('bob', { keysDir: join(tmp, 'bob-source') })
-    const importedDir = join(tmp, 'imported')
-
-    await expect(
-      importKeypair(
-        'alice',
-        { privateJwk: alice.privateJwk, publicJwk: { ...bob.publicJwk, kid: alice.kid } },
-        importedDir,
-      ),
-    ).rejects.toThrow(/do not form a valid matching pair/)
-    await expect(access(keypairPaths('alice', importedDir).privatePath)).rejects.toThrow()
-
-    const imported = await importKeypair(
-      'alice',
-      { privateJwk: alice.privateJwk, publicJwk: alice.publicJwk },
-      importedDir,
-    )
-    expect(imported.kid).toBe(alice.kid)
-    expect((await readKeypair('alice', importedDir)).publicJwk).toEqual(alice.publicJwk)
-
-    await expect(
-      importKeypair(
-        'unsafe-public',
-        { privateJwk: alice.privateJwk, publicJwk: alice.privateJwk },
-        importedDir,
-      ),
-    ).rejects.toThrow(/must not contain private key material/)
-  })
-
-  /** @evidence TEST-CLI-KEYS-NO-MANAGER-FALLBACK */
-  test('signAs(alice) never falls back to the manager key', async () => {
-    await persistKeypair('manager', { keysDir: tmp })
-    await expect(signAs('alice', tmp)).rejects.toThrow(IdentityKeyMissingError)
-  })
-
-  test('signAs errors when no keys at all', async () => {
-    await expect(signAs('manager', tmp)).rejects.toThrow(IdentityKeyMissingError)
-  })
-
-  test('removeKeypair is idempotent', async () => {
-    await persistKeypair('alice', { keysDir: tmp })
-    await removeKeypair('alice', tmp)
-    await removeKeypair('alice', tmp)
-    const { privatePath } = keypairPaths('alice', tmp)
-    await expect(access(privatePath)).rejects.toThrow()
-  })
-
-  test('listIdentityKeys returns names with private keys', async () => {
-    await persistKeypair('manager', { keysDir: tmp })
-    await persistKeypair('alice', { keysDir: tmp })
-    await persistKeypair('bob', { keysDir: tmp })
-    const names = await listIdentityKeys(tmp)
-    expect(names.sort()).toEqual(['alice', 'bob', 'manager'])
-  })
-})

package/src/keys/algorithm.ts

@@ -1,33 +0,0 @@
-import { AstraleError } from '../errors'
-
-/**
- * Resolve the JOSE algorithm to use with this key. Prefers `privateJwk.alg`
- * when present, falls back to inferring from `crv`/`kty` so keys generated
- * by older CLIs that did not stamp `alg`. Throws when neither form resolves.
- */
-export function inferAlg(privateJwk: Record<string, unknown>, keyPath?: string): string {
-  const explicit = privateJwk.alg
-  if (typeof explicit === 'string' && explicit.length > 0) {
-    if (explicit === 'ES256' || explicit === 'EdDSA') return explicit
-    throw unsupportedAlgorithm(explicit, keyPath)
-  }
-  const crv = privateJwk.crv
-  const kty = privateJwk.kty
-  if (kty === 'EC' && crv === 'P-256') return 'ES256'
-  if (kty === 'OKP' && crv === 'Ed25519') return 'EdDSA'
-  const where = keyPath ? ` at ${keyPath}` : ''
-  throw new AstraleError(
-    'INVALID_KEY_FILE',
-    `JWK${where} is missing both \`alg\` and a recognizable \`(kty, crv)\` pair — cannot pick a signing algorithm.`,
-    'Re-stamp the file with `"alg": "ES256"` (P-256 EC keys) or `"alg": "EdDSA"` (Ed25519 OKP keys), or regenerate via `astrale domain init` / `astrale identity create`.',
-  )
-}
-
-function unsupportedAlgorithm(algorithm: string, keyPath?: string): AstraleError {
-  const where = keyPath ? ` at ${keyPath}` : ''
-  return new AstraleError(
-    'INVALID_KEY_FILE',
-    `JWK${where} selects unsupported signing algorithm ${JSON.stringify(algorithm)}.`,
-    'Use an ES256 P-256 key or an EdDSA Ed25519 key.',
-  )
-}

package/src/keys/credential.ts

@@ -1,113 +0,0 @@
-import { importJWK, SignJWT, type JWK } from 'jose'
-
-import { IdentityKeyMissingError } from '../errors'
-import { KEYS_DIR } from '../state/index'
-import { inferAlg } from './algorithm'
-import { fileExists, keypairPaths, persistKeypair, readKeypair } from './pair'
-
-const DEFAULT_MANAGER_ISSUER = 'http://localhost:4400/host'
-
-type AuthOptions = {
-  readonly issuer?: string
-  readonly subject?: string
-  readonly kid?: string
-}
-
-export type AuthBinding = {
-  readonly credential: string
-  readonly publicKey: { readonly jwk: JWK }
-}
-
-async function loadSigningMaterial(
-  subject: string,
-  keysDir: string,
-): Promise<{ privateJwk: JWK; publicJwk: JWK; kid: string }> {
-  const { privatePath } = keypairPaths(subject, keysDir)
-  if (!(await fileExists(privatePath))) throw new IdentityKeyMissingError(subject)
-
-  const pair = await readKeypair(subject, keysDir)
-  return { ...pair, kid: pair.kid ?? `${subject}-key` }
-}
-
-async function signIdentityCredential(options: {
-  readonly privateJwk: JWK
-  readonly kid: string
-  readonly issuer: string
-  readonly subject: string
-  readonly audience: string
-}): Promise<string> {
-  const alg = inferAlg(options.privateJwk as Record<string, unknown>)
-  const privateKey = await importJWK(options.privateJwk, alg)
-  const expr =
-    options.issuer === options.audience
-      ? { kind: 'identity' as const, id: options.subject }
-      : { kind: 'identity' as const, self: true as const }
-  return new SignJWT({ grant: { v: 1, expr } })
-    .setProtectedHeader({ alg, kid: options.kid })
-    .setIssuer(options.issuer)
-    .setSubject(options.subject)
-    .setAudience(options.audience)
-    .setExpirationTime('5m')
-    .sign(privateKey)
-}
-
-export async function persistAuth(
-  keysDir: string = KEYS_DIR,
-  opts?: AuthOptions,
-): Promise<AuthBinding> {
-  const issuer = opts?.issuer ?? DEFAULT_MANAGER_ISSUER
-  const subject = opts?.subject ?? 'manager'
-  const kid = opts?.kid ?? `${subject}-key`
-  const { privateJwk, publicJwk } = await persistKeypair(subject, { keysDir, kid })
-  const credential = await signIdentityCredential({
-    privateJwk,
-    kid,
-    issuer,
-    subject,
-    audience: issuer,
-  })
-  return { credential, publicKey: { jwk: publicJwk } }
-}
-
-export async function loadAuth(
-  keysDir: string = KEYS_DIR,
-  opts?: AuthOptions,
-): Promise<AuthBinding> {
-  const issuer = opts?.issuer ?? DEFAULT_MANAGER_ISSUER
-  const subject = opts?.subject ?? 'manager'
-  const { privateJwk, publicJwk, kid } = await loadSigningMaterial(subject, keysDir)
-  const credential = await signIdentityCredential({
-    privateJwk,
-    kid,
-    issuer,
-    subject,
-    audience: issuer,
-  })
-  return { credential, publicKey: { jwk: publicJwk } }
-}
-
-export async function resolveAuth(
-  keysDir: string = KEYS_DIR,
-  opts?: AuthOptions,
-): Promise<AuthBinding> {
-  const subject = opts?.subject ?? 'manager'
-  const { privatePath } = keypairPaths(subject, keysDir)
-  return (await fileExists(privatePath)) ? loadAuth(keysDir, opts) : persistAuth(keysDir, opts)
-}
-
-export async function signAs(
-  subject: string,
-  keysDir: string = KEYS_DIR,
-  opts?: { readonly issuer?: string; readonly audience?: string; readonly subject?: string },
-): Promise<string> {
-  const issuer = opts?.issuer ?? DEFAULT_MANAGER_ISSUER
-  const audience = opts?.audience ?? issuer
-  const { privateJwk, kid } = await loadSigningMaterial(subject, keysDir)
-  return signIdentityCredential({
-    privateJwk,
-    kid,
-    issuer,
-    subject: opts?.subject ?? subject,
-    audience,
-  })
-}

package/src/keys/index.ts

@@ -1,14 +0,0 @@
-export {
-  acceptKeypair,
-  fileExists,
-  generateEd25519Jwk,
-  importKeypair,
-  keypairPaths,
-  listIdentityKeys,
-  persistKeypair,
-  readKeypair,
-  removeKeypair,
-} from './pair'
-export { loadAuth, persistAuth, resolveAuth, signAs } from './credential'
-export type { Keypair, KeypairInput, KeypairPaths } from './pair'
-export type { AuthBinding } from './credential'

package/src/keys/pair.ts

@@ -1,219 +0,0 @@
-import { compactVerify, CompactSign, exportJWK, generateKeyPair, importJWK, type JWK } from 'jose'
-import { randomUUID } from 'node:crypto'
-import { access, mkdir, readFile, unlink } from 'node:fs/promises'
-import { dirname, join, resolve } from 'node:path'
-
-import { AstraleError } from '../errors'
-import { atomicWrite, KEYS_DIR } from '../state/index'
-import { inferAlg } from './algorithm'
-
-const LEGACY_MANAGER_PRIVATE = 'manager.private.jwk'
-const LEGACY_MANAGER_PUBLIC = 'manager.public.jwk'
-
-export type KeypairPaths = {
-  readonly privatePath: string
-  readonly publicPath: string
-}
-
-export interface Keypair {
-  readonly privateJwk: JWK
-  readonly publicJwk: JWK
-  readonly kid?: string
-}
-
-export interface KeypairInput {
-  readonly privateJwk: unknown
-  readonly publicJwk: unknown
-}
-
-/** Preserve manager filenames and confine every subject file to the selected key directory. */
-export function keypairPaths(subject: string, keysDir: string = KEYS_DIR): KeypairPaths {
-  if (
-    subject.length === 0 ||
-    subject.includes('\0') ||
-    subject.includes('/') ||
-    subject.includes('\\')
-  ) {
-    throw invalidKeySubject(subject)
-  }
-  const filenames =
-    subject === 'manager'
-      ? { private: LEGACY_MANAGER_PRIVATE, public: LEGACY_MANAGER_PUBLIC }
-      : { private: `${subject}.private.jwk`, public: `${subject}.public.jwk` }
-
-  return {
-    privatePath: confinedKeyPath(keysDir, filenames.private, subject),
-    publicPath: confinedKeyPath(keysDir, filenames.public, subject),
-  }
-}
-
-function confinedKeyPath(keysDir: string, filename: string, subject: string): string {
-  const path = join(keysDir, filename)
-  if (dirname(resolve(path)) !== resolve(keysDir)) throw invalidKeySubject(subject)
-  return path
-}
-
-function invalidKeySubject(subject: string): AstraleError {
-  return new AstraleError(
-    'INVALID_KEY_SUBJECT',
-    `Identity subject ${JSON.stringify(subject)} cannot name a key file.`,
-    'Use a non-empty subject without path separators.',
-  )
-}
-
-function invalidKeypair(message: string): AstraleError {
-  return new AstraleError('INVALID_KEYPAIR', message, 'Import a supported matching keypair.')
-}
-
-function acceptJwk(input: unknown, role: 'private' | 'public'): JWK {
-  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
-    throw invalidKeypair(`The ${role} JWK must be an object.`)
-  }
-  const jwk = { ...input } as JWK
-  if (jwk.kid !== undefined && (typeof jwk.kid !== 'string' || jwk.kid.length === 0)) {
-    throw invalidKeypair(`The ${role} JWK kid must be a non-empty string when present.`)
-  }
-  return jwk
-}
-
-export async function acceptKeypair(input: KeypairInput): Promise<Keypair> {
-  const privateJwk = acceptJwk(input.privateJwk, 'private')
-  const publicJwk = acceptJwk(input.publicJwk, 'public')
-  if (!Object.hasOwn(privateJwk, 'd')) {
-    throw invalidKeypair('The private JWK does not contain private key material.')
-  }
-  if (Object.hasOwn(publicJwk, 'd')) {
-    throw invalidKeypair('The public JWK must not contain private key material.')
-  }
-
-  const privateAlg = inferAlg(privateJwk as Record<string, unknown>)
-  const publicAlg = inferAlg(publicJwk as Record<string, unknown>)
-  if (privateAlg !== publicAlg) {
-    throw invalidKeypair(
-      `The private and public JWK algorithms differ (${privateAlg} versus ${publicAlg}).`,
-    )
-  }
-  if (privateJwk.kid && publicJwk.kid && privateJwk.kid !== publicJwk.kid) {
-    throw invalidKeypair('The private and public JWK key IDs differ.')
-  }
-
-  try {
-    const [privateKey, publicKey] = await Promise.all([
-      importJWK(privateJwk, privateAlg),
-      importJWK(publicJwk, publicAlg),
-    ])
-    const proof = await new CompactSign(new TextEncoder().encode('astrale-keypair-proof'))
-      .setProtectedHeader({ alg: privateAlg })
-      .sign(privateKey)
-    await compactVerify(proof, publicKey, { algorithms: [publicAlg] })
-  } catch {
-    throw invalidKeypair('The private and public JWKs do not form a valid matching pair.')
-  }
-
-  return { privateJwk, publicJwk, kid: privateJwk.kid ?? publicJwk.kid }
-}
-
-export async function fileExists(path: string): Promise<boolean> {
-  try {
-    await access(path)
-    return true
-  } catch (error) {
-    if ((error as { code?: string }).code === 'ENOENT') return false
-    throw error
-  }
-}
-
-export async function listIdentityKeys(keysDir: string = KEYS_DIR): Promise<string[]> {
-  try {
-    const { readdir } = await import('node:fs/promises')
-    const entries = await readdir(keysDir)
-    const names = new Set<string>()
-    for (const entry of entries) {
-      if (entry === LEGACY_MANAGER_PRIVATE) names.add('manager')
-      else if (entry.endsWith('.private.jwk')) names.add(entry.replace(/\.private\.jwk$/, ''))
-    }
-    return Array.from(names).sort()
-  } catch (error) {
-    if ((error as { code?: string }).code === 'ENOENT') return []
-    throw error
-  }
-}
-
-export async function generateEd25519Jwk(
-  kid: string,
-): Promise<{ readonly privateJwk: JWK; readonly publicJwk: JWK }> {
-  const { publicKey, privateKey } = await generateKeyPair('EdDSA', {
-    crv: 'Ed25519',
-    extractable: true,
-  })
-  const privateJwk = await exportJWK(privateKey)
-  const publicJwk = await exportJWK(publicKey)
-  privateJwk.alg = 'EdDSA'
-  publicJwk.alg = 'EdDSA'
-  privateJwk.kid = kid
-  publicJwk.kid = kid
-  return { privateJwk, publicJwk }
-}
-
-export async function persistKeypair(
-  subject: string,
-  opts?: { readonly keysDir?: string; readonly kid?: string },
-): Promise<{ readonly publicJwk: JWK; readonly privateJwk: JWK; readonly kid: string }> {
-  const keysDir = opts?.keysDir ?? KEYS_DIR
-  const { publicKey, privateKey } = await generateKeyPair('ES256', { extractable: true })
-  const publicJwk = await exportJWK(publicKey)
-  const privateJwk = await exportJWK(privateKey)
-  const kid = opts?.kid ?? `${subject}-key-${randomUUID().slice(0, 8)}`
-  publicJwk.kid = kid
-  privateJwk.kid = kid
-  publicJwk.alg = 'ES256'
-  privateJwk.alg = 'ES256'
-
-  await writeKeypair(subject, { privateJwk, publicJwk, kid }, keysDir)
-  return { publicJwk, privateJwk, kid }
-}
-
-export async function readKeypair(subject: string, keysDir: string = KEYS_DIR): Promise<Keypair> {
-  const { privatePath, publicPath } = keypairPaths(subject, keysDir)
-  try {
-    const [privateRaw, publicRaw] = await Promise.all([
-      readFile(privatePath, 'utf-8'),
-      readFile(publicPath, 'utf-8'),
-    ])
-    return await acceptKeypair({
-      privateJwk: JSON.parse(privateRaw) as unknown,
-      publicJwk: JSON.parse(publicRaw) as unknown,
-    })
-  } catch (error) {
-    if (error instanceof AstraleError) throw error
-    throw invalidKeypair(`Could not read the keypair for identity ${JSON.stringify(subject)}.`)
-  }
-}
-
-export async function importKeypair(
-  subject: string,
-  input: KeypairInput,
-  keysDir: string = KEYS_DIR,
-): Promise<Keypair> {
-  const pair = await acceptKeypair(input)
-  await writeKeypair(subject, pair, keysDir)
-  return pair
-}
-
-async function writeKeypair(subject: string, pair: Keypair, keysDir: string): Promise<void> {
-  const { privatePath, publicPath } = keypairPaths(subject, keysDir)
-  await mkdir(keysDir, { recursive: true })
-  await atomicWrite(privatePath, JSON.stringify(pair.privateJwk, null, 2))
-  await atomicWrite(publicPath, JSON.stringify(pair.publicJwk, null, 2))
-}
-
-export async function removeKeypair(subject: string, keysDir: string = KEYS_DIR): Promise<void> {
-  const { privatePath, publicPath } = keypairPaths(subject, keysDir)
-  for (const path of [privatePath, publicPath]) {
-    try {
-      await unlink(path)
-    } catch (error) {
-      if ((error as { code?: string }).code !== 'ENOENT') throw error
-    }
-  }
-}

package/src/keys/tsconfig.json

@@ -1,6 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": { "types": ["@types/node"] },
-  "include": ["*.ts"],
-  "exclude": ["__tests__"]
-}