@astrale-os/cli 1.0.0-beta.8 → 1.0.0-npm-deprecated.0

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

@@ -1,74 +0,0 @@
-import type { JWK } from 'jose'
-
-type AuthOptions = {
-  readonly issuer?: string
-  readonly subject?: string
-  readonly kid?: string
-}
-
-export type AuthBinding = {
-  readonly credential: string
-  readonly publicKey: { readonly jwk: 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
-}
-
-export function keypairPaths(subject: string, keysDir?: string): KeypairPaths
-
-export function fileExists(path: string): Promise<boolean>
-
-export function listIdentityKeys(keysDir?: string): Promise<string[]>
-
-export function generateEd25519Jwk(
-  kid: string,
-): Promise<{ readonly privateJwk: JWK; readonly publicJwk: JWK }>
-
-export function persistKeypair(
-  subject: string,
-  opts?: { readonly keysDir?: string; readonly kid?: string },
-): Promise<{ readonly publicJwk: JWK; readonly privateJwk: JWK; readonly kid: string }>
-
-/** Admit supported private/public JWKs and prove that they form one pair. */
-export function acceptKeypair(input: KeypairInput): Promise<Keypair>
-
-/** Decode and cryptographically prove a persisted subject keypair. */
-export function readKeypair(subject: string, keysDir?: string): Promise<Keypair>
-
-/** Admit and atomically persist one externally supplied subject keypair. */
-export function importKeypair(
-  subject: string,
-  input: KeypairInput,
-  keysDir?: string,
-): Promise<Keypair>
-
-export function removeKeypair(subject: string, keysDir?: string): Promise<void>
-
-export function persistAuth(keysDir?: string, opts?: AuthOptions): Promise<AuthBinding>
-
-export function loadAuth(keysDir?: string, opts?: AuthOptions): Promise<AuthBinding>
-
-export function resolveAuth(keysDir?: string, opts?: AuthOptions): Promise<AuthBinding>
-
-export function signAs(
-  subject: string,
-  keysDir?: string,
-  opts?: {
-    readonly issuer?: string
-    readonly audience?: string
-    readonly subject?: string
-  },
-): Promise<string>

package/src/keys/.spec/architecture.md

@@ -1,13 +0,0 @@
-# CLI key material
-
-This Node-only module owns the retained `@astrale-os/cli/keys` subpath. Manager keys remain on their
-legacy filenames; every other identity uses its own subject-named pair. Writes are private and
-atomic through State. Signing admits the selected private JWK algorithm and never substitutes
-manager material for a missing identity key.
-
-Externally supplied or persisted pairs cross a proof-loss boundary here. Keys accepts only supported
-algorithms, keeps paths inside the selected key directory, rejects private material in the public
-file, and proves private/public correspondence before returning or replacing files.
-
-The retained Node-only subpath contains the explicit raw-key operations required by import/export
-and scaffold consumers. Ordinary connection code receives signed credentials or public material.

package/src/keys/.spec/laws/keys.ts

@@ -1,43 +0,0 @@
-import { defineLaw } from '@astrale-os/spec/authoring'
-
-export const CLI_KEYS_IDENTITY_ISOLATED = defineLaw({
-  id: 'CLI-KEYS-IDENTITY-ISOLATED',
-  statement:
-    'Each subject signs only with its own mode-0600 keypair; missing subject material fails even when manager keys exist.',
-  tests: [
-    { file: '__tests__/keys.test.ts', id: 'TEST-CLI-KEYS-PRIVATE-MODE' },
-    { file: '__tests__/keys.test.ts', id: 'TEST-CLI-KEYS-NO-MANAGER-FALLBACK' },
-  ],
-})
-
-export const CLI_KEYS_LEGACY_READABLE = defineLaw({
-  id: 'CLI-KEYS-LEGACY-READABLE',
-  statement:
-    'Manager filenames and unstamped supported legacy algorithms remain readable without changing another identity key coordinate.',
-  tests: [
-    { file: '__tests__/keys.test.ts', id: 'TEST-CLI-KEYS-LEGACY-FILENAMES' },
-    { file: '__tests__/algorithm.test.ts', id: 'TEST-CLI-KEYS-INFERS-LEGACY-ALGORITHM' },
-  ],
-})
-
-export const CLI_KEYS_PAIR_ADMITTED = defineLaw({
-  id: 'CLI-KEYS-PAIR-ADMITTED',
-  statement:
-    'A subject path remains inside the selected key directory, and imported or persisted material is returned only after supported-algorithm and private/public correspondence proof.',
-  tests: [
-    { file: '__tests__/keys.test.ts', id: 'TEST-CLI-KEYS-PAIR-ADMISSION' },
-    { file: '__tests__/keys.test.ts', id: 'TEST-CLI-KEYS-PATH-CONFINED' },
-  ],
-})
-
-export const CLI_KEYS_CREDENTIAL_GRANT_PROFILE = defineLaw({
-  id: 'CLI-KEYS-CREDENTIAL-GRANT-PROFILE',
-  statement:
-    'A self-issued Kernel credential carries the effective subject as an already-resolved identity Grant, while an externally issued primary credential carries an identity-self Grant for Runtime resolution.',
-  tests: [
-    {
-      file: '__tests__/keys.test.ts',
-      id: 'TEST-CLI-KEYS-DISTINGUISHES-KERNEL-ROOT-GRANT',
-    },
-  ],
-})

package/src/keys/.spec/layout.ts

@@ -1,6 +0,0 @@
-import { defineLayout } from '@astrale-os/spec/authoring'
-
-export default defineLayout({
-  entries: ['__tests__/', 'algorithm.ts', 'credential.ts', 'index.ts', 'pair.ts', 'tsconfig.json'],
-  exact: true,
-})

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

@@ -1,39 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-
-import { AstraleError } from '../../errors'
-import { inferAlg } from '../algorithm'
-
-describe('inferAlg', () => {
-  test('returns explicit alg when present', () => {
-    expect(inferAlg({ alg: 'ES256' })).toBe('ES256')
-    expect(inferAlg({ alg: 'EdDSA' })).toBe('EdDSA')
-  })
-
-  /** @evidence TEST-CLI-KEYS-INFERS-LEGACY-ALGORITHM */
-  test('infers supported algorithms for legacy unstamped key files', () => {
-    expect(inferAlg({ kty: 'EC', crv: 'P-256' })).toBe('ES256')
-    expect(inferAlg({ kty: 'OKP', crv: 'Ed25519' })).toBe('EdDSA')
-  })
-
-  test('explicit alg wins over inferable shape (no second-guessing)', () => {
-    expect(inferAlg({ alg: 'ES256', kty: 'OKP', crv: 'Ed25519' })).toBe('ES256')
-  })
-
-  test('throws AstraleError with hint when no alg/crv/kty resolves', () => {
-    expect(() => inferAlg({})).toThrow(AstraleError)
-    expect(() => inferAlg({ kty: 'EC' })).toThrow(AstraleError)
-    expect(() => inferAlg({ kty: 'EC', crv: 'P-384' })).toThrow(AstraleError)
-  })
-
-  test('error message includes keyPath when provided', () => {
-    expect(() => inferAlg({}, '/path/to/broken.jwk')).toThrow(/\/path\/to\/broken\.jwk/)
-  })
-
-  test('treats empty-string alg as missing', () => {
-    expect(inferAlg({ alg: '', kty: 'EC', crv: 'P-256' })).toBe('ES256')
-  })
-
-  test('rejects unsupported explicit algorithms', () => {
-    expect(() => inferAlg({ alg: 'HS256', kty: 'oct' })).toThrow(/unsupported signing algorithm/)
-  })
-})

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

@@ -1,168 +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)
-  })
-
-  /** @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,112 +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)
-    .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'