@astrale-os/cli 0.4.0-alpha.13

package/src/lib/keys.ts

@@ -0,0 +1,294 @@
+import { generateKeyPair, exportJWK, importJWK, SignJWT, type JWK } from 'jose'
+import { randomUUID } from 'node:crypto'
+import { readFile, mkdir, access, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { IdentityKeyMissingError } from '../errors'
+import { inferAlg } from './domain-identity'
+import { atomicWrite } from './fs-atomic'
+import { log } from './log'
+import { KEYS_DIR } from './paths'
+
+const LEGACY_MANAGER_PRIVATE = 'manager.private.jwk'
+const LEGACY_MANAGER_PUBLIC = 'manager.public.jwk'
+
+// Default issuer/audience for the host-mode manager's own credential. The
+// manager kernel mounts at `/host` (the reserved host slug — SPEC §5.2).
+const DEFAULT_MANAGER_ISSUER = 'http://localhost:4400/host'
+
+type AuthOptions = {
+  issuer?: string
+  subject?: string
+  kid?: string
+}
+
+export type AuthBinding = {
+  credential: string
+  publicKey: { jwk: JWK }
+}
+
+export type KeypairPaths = {
+  privatePath: string
+  publicPath: string
+}
+
+/**
+ * Per-identity keypair paths. `manager` stays on the legacy filenames so
+ * existing installs keep working; other subjects use `<subject>.*.jwk`.
+ */
+export function keypairPaths(subject: string, keysDir: string = KEYS_DIR): KeypairPaths {
+  if (subject === 'manager') {
+    return {
+      privatePath: join(keysDir, LEGACY_MANAGER_PRIVATE),
+      publicPath: join(keysDir, LEGACY_MANAGER_PUBLIC),
+    }
+  }
+  return {
+    privatePath: join(keysDir, `${subject}.private.jwk`),
+    publicPath: join(keysDir, `${subject}.public.jwk`),
+  }
+}
+
+export async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** List identity names that have a private key on disk. */
+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 {
+    return []
+  }
+}
+
+/**
+ * Generate a fresh Ed25519 keypair as plain JWKs (not persisted).
+ *
+ * Used by the domain scaffold to stamp worker key files with a real,
+ * internally-consistent pair — defense against drift between `d` and `x`
+ * (historical template copies had a mismatched `x`, making every scaffold
+ * inherit a broken pair). Same crypto as ES256 elsewhere in the CLI but
+ * EdDSA/Ed25519 matches the worker runtime convention.
+ */
+export async function generateEd25519Jwk(
+  kid: string,
+): Promise<{ privateJwk: JWK; 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 }
+}
+
+/**
+ * Generate a new keypair for `subject`, persist atomically with 0o600
+ * perms, and return the JWKs + kid. Overwrites any existing keys.
+ */
+export async function persistKeypair(
+  subject: string,
+  opts?: { keysDir?: string; kid?: string },
+): Promise<{ publicJwk: JWK; privateJwk: JWK; kid: string }> {
+  const keysDir = opts?.keysDir ?? KEYS_DIR
+  const { privatePath, publicPath } = keypairPaths(subject, keysDir)
+  await mkdir(keysDir, { recursive: true })
+
+  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 atomicWrite(privatePath, JSON.stringify(privateJwk, null, 2))
+  await atomicWrite(publicPath, JSON.stringify(publicJwk, null, 2))
+
+  return { publicJwk, privateJwk, kid }
+}
+
+/** Remove a subject's keypair files. Idempotent. */
+export async function removeKeypair(subject: string, keysDir: string = KEYS_DIR): Promise<void> {
+  const { privatePath, publicPath } = keypairPaths(subject, keysDir)
+  for (const p of [privatePath, publicPath]) {
+    try {
+      await unlink(p)
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+// Legacy signal: warn once per session when an unknown subject falls back
+// to the manager key.
+const warnedFallback = new Set<string>()
+
+async function loadSigningMaterial(
+  subject: string,
+  keysDir: string,
+): Promise<{ privateJwk: JWK; publicJwk: JWK; kid: string }> {
+  const { privatePath, publicPath } = keypairPaths(subject, keysDir)
+
+  if (await fileExists(privatePath)) {
+    const privateJwk = JSON.parse(await readFile(privatePath, 'utf-8')) as JWK
+    const publicJwk = JSON.parse(await readFile(publicPath, 'utf-8')) as JWK
+    return {
+      privateJwk,
+      publicJwk,
+      kid: (privateJwk.kid as string | undefined) ?? `${subject}-key`,
+    }
+  }
+
+  if (process.env.ASTRALE_STRICT_IDENTITIES === '1') {
+    throw new IdentityKeyMissingError(subject)
+  }
+
+  // Manager always uses its own file. Any other subject falls through
+  // to the manager key with a one-shot warning so the migration window
+  // stays visible without being noisy.
+  if (subject === 'manager') throw new IdentityKeyMissingError(subject)
+
+  const { privatePath: mgrPrivate, publicPath: mgrPublic } = keypairPaths('manager', keysDir)
+  if (!(await fileExists(mgrPrivate))) throw new IdentityKeyMissingError(subject)
+
+  if (!warnedFallback.has(subject)) {
+    log.warn(
+      `Legacy shared-key mode for "${subject}" — run \`astrale identity create ${subject}\` to generate a dedicated key.`,
+    )
+    warnedFallback.add(subject)
+  }
+  const privateJwk = JSON.parse(await readFile(mgrPrivate, 'utf-8')) as JWK
+  const publicJwk = JSON.parse(await readFile(mgrPublic, 'utf-8')) as JWK
+  return {
+    privateJwk,
+    publicJwk,
+    kid: (privateJwk.kid as string | undefined) ?? 'manager-key',
+  }
+}
+
+/**
+ * Sign a self-identity credential (`grant: identity/self`) from a private
+ * JWK. Shared by `persistAuth`, `loadAuth`, and `signAs` so the protected
+ * header and claim set stay identical across all three; the only thing that
+ * varies is how each caller obtains the key material and which
+ * subject/audience it stamps.
+ */
+async function signIdentityCredential(args: {
+  privateJwk: JWK
+  kid: string
+  issuer: string
+  subject: string
+  audience: string
+}): Promise<string> {
+  const alg = inferAlg(args.privateJwk as Record<string, unknown>)
+  const privateKey = await importJWK(args.privateJwk, alg)
+  return new SignJWT({ grant: { v: 1, expr: { kind: 'identity', self: true } } })
+    .setProtectedHeader({ alg, kid: args.kid })
+    .setIssuer(args.issuer)
+    .setSubject(args.subject)
+    .setAudience(args.audience)
+    .sign(privateKey)
+}
+
+/**
+ * Generate a new keypair, persist to disk, and return a signed credential.
+ * Wraps the manager init path — use `persistKeypair` for bare keypair generation.
+ */
+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 } }
+}
+
+/**
+ * Load existing keys from disk and sign a fresh credential.
+ */
+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 } }
+}
+
+/**
+ * Load existing keys if present, otherwise generate and persist new ones.
+ */
+export async function resolveAuth(
+  keysDir: string = KEYS_DIR,
+  opts?: AuthOptions,
+): Promise<AuthBinding> {
+  const subject = opts?.subject ?? 'manager'
+  const { privatePath } = keypairPaths(subject, keysDir)
+  if (await fileExists(privatePath)) {
+    return loadAuth(keysDir, opts)
+  }
+  return persistAuth(keysDir, opts)
+}
+
+/**
+ * Sign a JWT as a specific subject. Uses the subject's own keypair when
+ * present; falls back to the manager key (with a one-shot warning) for
+ * unknown subjects until `ASTRALE_STRICT_IDENTITIES=1` is set.
+ */
+export async function signAs(
+  subject: string,
+  keysDir: string = KEYS_DIR,
+  opts?: { issuer?: string; audience?: string; 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/lib/local-status.ts

@@ -0,0 +1,152 @@
+import { decodeJwt } from 'jose'
+
+import type { AstraleConfig } from './config'
+
+import { resolveAdminTargetFromStore } from './admin-target'
+import { DEFAULT_CONFIG, readConfig } from './config'
+import { readIdentities, type IdentityStore } from './identity'
+import { isSessionExpired, readIdpSession, type IdpSession } from './idp'
+import { readInstances, type InstanceStore } from './instance'
+
+export type LocalInstanceStatus = {
+  active: string
+  url: string
+  issuer: string | null
+  defaultIdentity: string | null
+} | null
+
+export type LocalAdminStatus =
+  | {
+      name: string
+      url: string
+      issuer: string
+      source: string
+      configured: boolean
+    }
+  | {
+      error: string
+    }
+
+export type LocalIdentityStatus = {
+  name: string
+  subject: string
+  source: 'key' | 'idp'
+  idp: string | null
+  session: {
+    cached: boolean
+    requiresLogin?: boolean
+    hasRefreshToken?: boolean
+  } | null
+} | null
+
+export type LocalStatus = {
+  admin: LocalAdminStatus
+  instance: LocalInstanceStatus
+  identity: LocalIdentityStatus
+}
+
+export type JwtExpiration = {
+  expiresAt: string
+  expired: boolean
+}
+
+export async function readLocalStatus(): Promise<LocalStatus> {
+  const [instances, identities, config] = await Promise.all([
+    // Read-only: status / `setup --plan` must never trigger a sanitize-writeback.
+    readInstances(undefined, { persist: false }),
+    readIdentities(),
+    readConfig(),
+  ])
+  return buildLocalStatus(instances, identities, async (name) => readIdpSession(name), config)
+}
+
+export async function buildLocalStatus(
+  instances: InstanceStore,
+  identities: IdentityStore,
+  readSession: (identityName: string) => Promise<IdpSession | null>,
+  config: AstraleConfig = DEFAULT_CONFIG,
+): Promise<LocalStatus> {
+  const activeEntry = instances.active ? instances.instances[instances.active] : undefined
+  const instance = instances.active
+    ? {
+        active: instances.active,
+        url: activeEntry?.url ?? '',
+        issuer: activeEntry?.issuer ?? null,
+        defaultIdentity: activeEntry?.defaultIdentity ?? null,
+      }
+    : null
+
+  const identityEntry = identities.identities[identities.default]
+  const admin = buildAdminStatus(config, instances)
+  if (!identityEntry) {
+    return { admin, instance, identity: null }
+  }
+
+  const source = identityEntry.source ?? 'key'
+  const session =
+    source === 'idp'
+      ? await readSession(identities.default)
+          .then((value) => {
+            if (!value) return { cached: false }
+            const expiresAt =
+              value.expires_at ??
+              expClaimToIso(value.claims?.exp) ??
+              expClaimToIso(identityEntry.claims?.exp)
+            const hasRefreshToken = !!value.refresh_token
+            return {
+              cached: true,
+              requiresLogin:
+                !hasRefreshToken &&
+                isSessionExpired({ expires_at: expiresAt, access_token: value.access_token }),
+              hasRefreshToken,
+            }
+          })
+          .catch(() => ({ cached: false }))
+      : null
+
+  return {
+    admin,
+    instance,
+    identity: {
+      name: identities.default,
+      subject: identityEntry.subject,
+      source,
+      idp: identityEntry.idp ?? null,
+      session,
+    },
+  }
+}
+
+function buildAdminStatus(config: AstraleConfig, instances: InstanceStore): LocalAdminStatus {
+  try {
+    const target = resolveAdminTargetFromStore({}, config, instances)
+    return {
+      name: target.name,
+      url: target.url,
+      issuer: target.issuer,
+      source: target.source,
+      configured: target.configured,
+    }
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+function expClaimToIso(value: unknown): string | undefined {
+  if (typeof value !== 'number') return undefined
+  return new Date(value * 1000).toISOString()
+}
+
+export function decodeJwtExpiration(token: string, nowMs = Date.now()): JwtExpiration | null {
+  try {
+    const payload = decodeJwt(token)
+    if (typeof payload.exp !== 'number') return null
+    const expiresMs = payload.exp * 1000
+    return {
+      expiresAt: new Date(expiresMs).toISOString(),
+      expired: expiresMs <= nowMs,
+    }
+  } catch {
+    return null
+  }
+}

package/src/lib/log.ts

@@ -0,0 +1,116 @@
+import chalk from 'chalk'
+import ora, { type Ora } from 'ora'
+
+import { AstraleError, NotImplementedError } from '../errors'
+import { formatElapsed } from './format'
+
+export const log = {
+  info: (msg: string) => console.log(chalk.blue('ℹ'), msg),
+  success: (msg: string) => console.log(chalk.green('✔'), msg),
+  warn: (msg: string) => console.log(chalk.yellow('⚠'), msg),
+  error: (msg: string) => console.error(chalk.red('✖'), msg),
+  step: (msg: string) => console.log(chalk.cyan('→'), msg),
+  dim: (msg: string) => console.log(chalk.dim(msg)),
+}
+
+/** Report an error with hint (when present) and exit. */
+export function fatal(e: unknown): never {
+  // Ctrl-C at an interactive (@inquirer/prompts) prompt — exit quietly with the
+  // SIGINT convention, not a red error line.
+  if (e instanceof Error && e.name === 'ExitPromptError') process.exit(130)
+  const msg = e instanceof Error ? e.message : String(e)
+  log.error(msg)
+  if (e instanceof AstraleError && e.hint) log.dim(`  hint: ${e.hint}`)
+  process.exit(1)
+}
+
+/** Shortcut for stub commands that aren't wired in v1 (§15). */
+export function fatalNotImplemented(feature: string, hint?: string): never {
+  fatal(new NotImplementedError(feature, hint))
+}
+
+/** Maximum time a spinner may run before being forcefully stopped. */
+const SPINNER_SAFETY_MS = 60_000
+
+const IS_CI = !!(process.env.CI || process.env.CONTINUOUS_INTEGRATION || process.env.NO_SPINNER)
+
+/**
+ * Run an async operation behind a spinner. Pass `enabled: false` for
+ * machine-readable output modes. Errors are rethrown after the spinner is
+ * stopped (✖ label failed).
+ *
+ * On success the spinner line is cleared — commands print their own result.
+ * Pass `opts.success` to instead persist a single final line
+ * (✔ <success text> <elapsed>) so a command ends on one line, not a
+ * spinner line + result line pair.
+ */
+export async function withSpinner<T>(
+  label: string,
+  enabled: boolean,
+  fn: () => Promise<T>,
+  opts: { success?: (result: T) => string } = {},
+): Promise<T> {
+  if (!enabled) return await fn()
+  const spin = spinner(`${label}...`)
+  const start = performance.now()
+  try {
+    const result = await fn()
+    if (opts.success) {
+      spin.succeed(`${opts.success(result)} ${chalk.dim(formatElapsed(performance.now() - start))}`)
+    } else {
+      spin.stop()
+    }
+    return result
+  } catch (error) {
+    spin.fail(`${label} failed`)
+    throw error
+  }
+}
+
+export function spinner(text: string): Ora {
+  const target = process.stderr
+
+  if (!target.writable || IS_CI) {
+    return ora({ text, isEnabled: false })
+  }
+
+  // Hand ora the bare stream: ora 9 hooks `stream.write` by assignment to
+  // interleave external writes, so any wrapper here must survive that
+  // mutation (a get-only Proxy recurses infinitely and kills the spinner).
+  // Backpressure is ora's job now — it pauses rendering until 'drain'.
+  const spin = ora({ text, color: 'cyan', stream: target }).start()
+
+  const safety = setTimeout(() => {
+    if (spin.isSpinning) spin.stop()
+  }, SPINNER_SAFETY_MS)
+  safety.unref()
+
+  const onTargetError = () => {
+    if (spin.isSpinning) spin.stop()
+  }
+  target.once('error', onTargetError)
+
+  const cleanup = () => {
+    clearTimeout(safety)
+    target.removeListener('error', onTargetError)
+  }
+
+  const origSucceed = spin.succeed.bind(spin)
+  const origFail = spin.fail.bind(spin)
+  const origStop = spin.stop.bind(spin)
+
+  spin.succeed = (text?: string) => {
+    cleanup()
+    return origSucceed(text)
+  }
+  spin.fail = (text?: string) => {
+    cleanup()
+    return origFail(text)
+  }
+  spin.stop = () => {
+    cleanup()
+    return origStop()
+  }
+
+  return spin
+}