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

package/src/identity/transfer.ts

@@ -0,0 +1,187 @@
+import { compactDecrypt, CompactEncrypt, type JWK } from 'jose'
+import { z } from 'zod'
+
+import { AstraleError } from '../errors'
+import { acceptKeypair, importKeypair, readKeypair } from '../keys/index'
+import { validateName, validateUrl } from '../lib/validation'
+import {
+  atomicWrite,
+  readIdentityStore,
+  updateIdentityStore,
+  type Identity,
+  type IdentityMode,
+  type IdentityStoreOptions,
+} from '../state/index'
+
+const IDENTITY_EXPORT_VERSION = 1 as const
+const JwkSchema = z.record(z.string(), z.unknown())
+const IdentityExportFields = {
+  subject: z.string().min(1),
+  mode: z.enum(['local', 'remote']).optional(),
+  kid: z.string().min(1).optional(),
+  issuer: z.string().url().optional(),
+  privateJwk: JwkSchema,
+  publicJwk: JwkSchema,
+}
+const LegacyIdentityExportSchema = z.object(IdentityExportFields).strict()
+const IdentityExportV1Schema = z
+  .object({ version: z.literal(IDENTITY_EXPORT_VERSION), ...IdentityExportFields })
+  .strict()
+
+export interface IdentityFileOptions {
+  readonly state?: IdentityStoreOptions
+  readonly keysDir?: string
+}
+
+export interface IdentityExport {
+  readonly version: 1
+  readonly subject: string
+  readonly mode: IdentityMode
+  readonly kid?: string
+  readonly issuer?: string
+  readonly privateJwk: JWK
+  readonly publicJwk: JWK
+}
+
+export interface IdentityImportOptions extends IdentityFileOptions {
+  readonly name?: string
+  readonly issuer?: string
+  readonly replace?: boolean
+}
+
+export function isEncryptedIdentityExport(raw: string): boolean {
+  const content = raw.trim()
+  return !content.startsWith('{') && content.split('.').length === 5
+}
+
+export async function decodeIdentityExport(
+  raw: string,
+  passphrase?: string,
+): Promise<IdentityExport> {
+  let json = raw
+  if (isEncryptedIdentityExport(raw)) {
+    if (passphrase === undefined) {
+      throw invalidExport('This encrypted identity export requires a passphrase.')
+    }
+    try {
+      const { plaintext } = await compactDecrypt(raw.trim(), new TextEncoder().encode(passphrase), {
+        keyManagementAlgorithms: ['PBES2-HS256+A128KW'],
+        contentEncryptionAlgorithms: ['A256GCM'],
+      })
+      json = new TextDecoder().decode(plaintext)
+    } catch {
+      throw invalidExport('Could not decrypt the identity export.')
+    }
+  }
+
+  let input: unknown
+  try {
+    input = JSON.parse(json)
+  } catch {
+    throw invalidExport('The identity export is not valid JSON.')
+  }
+
+  let decoded: z.infer<typeof LegacyIdentityExportSchema>
+  try {
+    decoded = hasVersion(input)
+      ? IdentityExportV1Schema.parse(input)
+      : LegacyIdentityExportSchema.parse(input)
+  } catch {
+    throw invalidExport('The identity export has an invalid or unsupported shape.')
+  }
+
+  const pair = await acceptKeypair({
+    privateJwk: decoded.privateJwk,
+    publicJwk: decoded.publicJwk,
+  })
+  if (decoded.kid && pair.kid && decoded.kid !== pair.kid) {
+    throw invalidExport('The envelope key ID differs from its JWK key ID.')
+  }
+
+  return {
+    version: IDENTITY_EXPORT_VERSION,
+    subject: decoded.subject,
+    mode: decoded.mode ?? 'local',
+    kid: decoded.kid ?? pair.kid,
+    issuer: decoded.issuer,
+    privateJwk: pair.privateJwk,
+    publicJwk: pair.publicJwk,
+  }
+}
+
+export async function encodeIdentityExport(
+  envelope: IdentityExport,
+  passphrase?: string,
+): Promise<string> {
+  const plaintext = JSON.stringify(envelope, null, 2)
+  if (passphrase === undefined) return plaintext
+  return new CompactEncrypt(new TextEncoder().encode(plaintext))
+    .setProtectedHeader({ alg: 'PBES2-HS256+A128KW', enc: 'A256GCM' })
+    .encrypt(new TextEncoder().encode(passphrase))
+}
+
+export async function exportIdentity(
+  name: string,
+  options: IdentityFileOptions = {},
+): Promise<IdentityExport> {
+  const store = await readIdentityStore(options.state)
+  const identity = store.identities[name]
+  if (!identity)
+    throw new Error(`Identity "${name}" not found. Run: astrale identity create ${name}`)
+  if ((identity.source ?? 'key') !== 'key') {
+    throw new Error(`Identity "${name}" is IdP-backed and has no transferable local keypair`)
+  }
+  const pair = await readKeypair(identity.subject, options.keysDir)
+  return {
+    version: IDENTITY_EXPORT_VERSION,
+    subject: identity.subject,
+    mode: identity.mode ?? 'local',
+    kid: identity.kid ?? pair.kid,
+    issuer: identity.issuer,
+    privateJwk: pair.privateJwk,
+    publicJwk: pair.publicJwk,
+  }
+}
+
+export async function importIdentity(
+  envelope: IdentityExport,
+  options: IdentityImportOptions = {},
+): Promise<Identity> {
+  const name = options.name ?? envelope.subject
+  validateName(name, 'Identity')
+  if (options.issuer !== undefined) validateUrl(options.issuer)
+
+  return updateIdentityStore(async (store) => {
+    const existing = store.identities[name]
+    if (existing && !options.replace) throw new Error(`Identity "${name}" already exists`)
+    if (existing && (existing.source ?? 'key') !== 'key') {
+      throw new Error(`Identity "${name}" already exists and is IdP-backed`)
+    }
+
+    const pair = await importKeypair(envelope.subject, envelope, options.keysDir)
+    const identity: Identity = {
+      subject: envelope.subject,
+      createdAt: existing?.createdAt ?? (options.state?.now?.() ?? new Date()).toISOString(),
+      source: 'key',
+      mode: envelope.mode,
+      kid: envelope.kid ?? pair.kid,
+      issuer: options.issuer ?? envelope.issuer,
+    }
+    return {
+      next: { ...store, identities: { ...store.identities, [name]: identity } },
+      value: identity,
+    }
+  }, options.state)
+}
+
+export async function writeIdentityExport(path: string, content: string): Promise<void> {
+  await atomicWrite(path, content)
+}
+
+function hasVersion(input: unknown): input is { readonly version: unknown } {
+  return typeof input === 'object' && input !== null && Object.hasOwn(input, 'version')
+}
+
+function invalidExport(message: string): AstraleError {
+  return new AstraleError('INVALID_IDENTITY_EXPORT', message)
+}

package/src/identity/tsconfig.json

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

package/src/index.ts

@@ -0,0 +1 @@
+export {}

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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,13 @@
+# 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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,39 @@
+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

@@ -0,0 +1,168 @@
+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

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1,112 @@
+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,
+  })
+}