@astrale-os/cli 0.4.0-alpha.13

package/src/lib/fs-atomic.ts

@@ -0,0 +1,126 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/** Write-tmp-then-rename so readers never observe a partial file. Mode 0600. */
+export async function atomicWrite(path: string, data: string): Promise<void> {
+  const tmp = `${path}.${randomUUID()}.tmp`
+  await writeFile(tmp, data, { mode: 0o600 })
+  await rename(tmp, path)
+}
+
+export type FileLockOptions = {
+  /** Delay between acquisition attempts while another process holds the lock. */
+  pollIntervalMs?: number
+  /** A lock file whose mtime is older than this is considered abandoned. */
+  staleAfterMs?: number
+  /** Give up acquiring after this long. */
+  timeoutMs?: number
+}
+
+/**
+ * Run `fn` under a cross-process mutex backed by a create-exclusive lock file.
+ *
+ * Contenders poll until the holder releases (unlinks) the lock. Abandoned
+ * locks are taken over when the holder pid is dead or the file's mtime
+ * exceeds `staleAfterMs` — a crash mid-section can therefore delay other
+ * processes by up to `staleAfterMs`, never deadlock them.
+ */
+export async function withFileLock<T>(
+  lockPath: string,
+  fn: () => Promise<T>,
+  opts: FileLockOptions = {},
+): Promise<T> {
+  const pollIntervalMs = opts.pollIntervalMs ?? 100
+  const staleAfterMs = opts.staleAfterMs ?? 30_000
+  const timeoutMs = opts.timeoutMs ?? 60_000
+  const deadline = Date.now() + timeoutMs
+
+  for (;;) {
+    const acquired = await tryAcquire(lockPath)
+    if (acquired) {
+      try {
+        return await fn()
+      } finally {
+        await unlink(lockPath).catch(() => undefined)
+      }
+    }
+    if (await takeoverIfAbandoned(lockPath, staleAfterMs)) continue
+    if (Date.now() >= deadline) {
+      throw new Error(`Timed out after ${timeoutMs}ms waiting for lock ${lockPath}`)
+    }
+    await sleep(pollIntervalMs)
+  }
+}
+
+async function tryAcquire(lockPath: string): Promise<boolean> {
+  try {
+    const handle = await open(lockPath, 'wx', 0o600)
+    try {
+      await handle.writeFile(
+        JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }),
+      )
+    } finally {
+      await handle.close()
+    }
+    return true
+  } catch (e) {
+    const code = (e as { code?: string }).code
+    if (code === 'EEXIST') return false
+    if (code === 'ENOENT') {
+      await mkdir(dirname(lockPath), { recursive: true })
+      return tryAcquire(lockPath)
+    }
+    throw e
+  }
+}
+
+/**
+ * Remove the lock if its holder is gone (dead pid, fast) or it outlived
+ * `staleAfterMs` (mtime, covers unreadable pids and cross-container holders).
+ * Returns true when the caller should immediately retry acquisition —
+ * `open('wx')` re-arbitrates between concurrent takeover candidates.
+ */
+async function takeoverIfAbandoned(lockPath: string, staleAfterMs: number): Promise<boolean> {
+  try {
+    const info = await stat(lockPath)
+    if (Date.now() - info.mtimeMs > staleAfterMs) {
+      await unlink(lockPath).catch(() => undefined)
+      return true
+    }
+  } catch (e) {
+    // Lock vanished between attempts: holder released — retry right away.
+    if ((e as { code?: string }).code === 'ENOENT') return true
+    throw e
+  }
+  const pid = await readLockPid(lockPath)
+  if (pid !== undefined && pid !== process.pid && !isPidAlive(pid)) {
+    await unlink(lockPath).catch(() => undefined)
+    return true
+  }
+  return false
+}
+
+async function readLockPid(lockPath: string): Promise<number | undefined> {
+  try {
+    const raw = await readFile(lockPath, 'utf-8')
+    const pid = (JSON.parse(raw) as { pid?: unknown }).pid
+    return typeof pid === 'number' ? pid : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    // EPERM means the pid exists but belongs to another user — still alive.
+    return (e as { code?: string }).code === 'EPERM'
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/lib/identity.ts

@@ -0,0 +1,256 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { z } from 'zod'
+
+import { deleteIdpSession } from './idp'
+import { persistKeypair, removeKeypair } from './keys'
+import { log } from './log'
+import { IDENTITIES_PATH } from './paths'
+import { RegistryModeSchema, validateName, type RegistryMode } from './validation'
+
+export const RegistrationSchema = z.object({
+  iss: z.string(),
+  sub: z.string(),
+  registeredAt: z.string(),
+})
+
+export const IdentitySchema = z.object({
+  subject: z.string(),
+  createdAt: z.string(),
+  /** `key` identities sign local JWTs; `idp` identities reuse OAuth/OIDC access tokens. */
+  source: z.enum(['key', 'idp']).optional(),
+  // `local` = machine-only, `remote` = mirrored via astrale cloud (§2.7).
+  mode: RegistryModeSchema.optional(),
+  /** JWK thumbprint of the identity keypair. Optional for legacy entries. */
+  kid: z.string().optional(),
+  /** IdP registry name for source=idp identities. */
+  idp: z.string().optional(),
+  /** OIDC issuer for source=idp identities. */
+  issuer: z.string().url().optional(),
+  /** Optional preferred audience used during IdP login/refresh flows. */
+  audience: z.string().optional(),
+  /** Non-secret claims snapshot from the last successful IdP login. */
+  claims: z.record(z.string(), z.unknown()).optional(),
+  /**
+   * Cache of `(iss, sub)` pairs returned by `Identity::registerIdentity`,
+   * keyed by instance slug. Populated by `astrale identity register`; consulted
+   * by `resolveCredential` so `--as <name> -i <instance>` signs JWTs the kernel
+   * accepts.
+   */
+  registrations: z.record(z.string(), RegistrationSchema).optional(),
+})
+
+export type Registration = z.infer<typeof RegistrationSchema>
+
+export const IdentityStoreSchema = z.object({
+  default: z.string(),
+  identities: z.record(z.string(), IdentitySchema),
+})
+
+export type Identity = z.infer<typeof IdentitySchema>
+export type IdentityStore = z.infer<typeof IdentityStoreSchema>
+
+function seed(): IdentityStore {
+  return {
+    default: 'manager',
+    identities: {
+      manager: {
+        subject: 'manager',
+        createdAt: new Date().toISOString(),
+        source: 'key',
+        mode: 'local',
+      },
+    },
+  }
+}
+
+export async function readIdentities(): Promise<IdentityStore> {
+  try {
+    const raw = await readFile(IDENTITIES_PATH, 'utf-8')
+    return IdentityStoreSchema.parse(JSON.parse(raw))
+  } catch (e) {
+    if (e instanceof z.ZodError) {
+      log.warn(`Invalid identities at ${IDENTITIES_PATH} — using defaults`)
+    } else if ((e as { code?: string }).code !== 'ENOENT') {
+      // Present-but-unreadable file (malformed JSON → SyntaxError, or a
+      // non-missing-file read error). ENOENT is the legitimate first-run
+      // case and stays silent; anything else would otherwise be discarded
+      // and could be overwritten by a later writeIdentities.
+      log.warn(`Could not read identities at ${IDENTITIES_PATH} — using defaults`)
+    }
+    return seed()
+  }
+}
+
+export async function writeIdentities(store: IdentityStore): Promise<void> {
+  await mkdir(dirname(IDENTITIES_PATH), { recursive: true })
+  await writeFile(IDENTITIES_PATH, JSON.stringify(store, null, 2) + '\n')
+}
+
+export async function createIdentity(
+  name: string,
+  opts: {
+    subject?: string
+    mode?: RegistryMode
+    issuer?: string
+    kid?: string
+    skipKeygen?: boolean
+  } = {},
+): Promise<Identity> {
+  validateName(name, 'Identity')
+  const store = await readIdentities()
+  if (store.identities[name]) {
+    throw new Error(`Identity "${name}" already exists`)
+  }
+  const subject = opts.subject ?? name
+  let kid: string | undefined
+  if (!opts.skipKeygen) {
+    const result = await persistKeypair(subject)
+    kid = result.kid
+  }
+  const identity: Identity = {
+    subject,
+    createdAt: new Date().toISOString(),
+    source: 'key',
+    mode: opts.mode ?? 'local',
+    kid: opts.kid ?? kid,
+    issuer: opts.issuer,
+  }
+  store.identities[name] = identity
+  await writeIdentities(store)
+  return identity
+}
+
+export async function upsertKeyIdentity(
+  name: string,
+  opts: {
+    subject: string
+    mode?: RegistryMode
+    issuer?: string
+    kid?: string
+  },
+): Promise<Identity> {
+  validateName(name, 'Identity')
+  const store = await readIdentities()
+  const existing = store.identities[name]
+  if (existing && (existing.source ?? 'key') !== 'key') {
+    throw new Error(`Identity "${name}" already exists and is IdP-backed`)
+  }
+  const identity: Identity = {
+    subject: opts.subject,
+    createdAt: existing?.createdAt ?? new Date().toISOString(),
+    source: 'key',
+    mode: opts.mode ?? existing?.mode ?? 'local',
+    kid: opts.kid,
+    issuer: opts.issuer,
+  }
+  store.identities[name] = identity
+  await writeIdentities(store)
+  return identity
+}
+
+export async function deleteIdentity(name: string): Promise<void> {
+  const store = await readIdentities()
+  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 {
+    await removeKeypair(entry.subject)
+  }
+  delete store.identities[name]
+  await writeIdentities(store)
+}
+
+export async function setDefault(name: string): Promise<void> {
+  const store = await readIdentities()
+  if (!store.identities[name]) {
+    throw new Error(`Identity "${name}" not found`)
+  }
+  store.default = name
+  await writeIdentities(store)
+}
+
+export async function getDefault(): Promise<Identity & { 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,
+  opts: {
+    subject: string
+    idp: string
+    issuer: string
+    audience?: string
+    claims?: Record<string, unknown>
+    use?: boolean
+  },
+): Promise<Identity> {
+  validateName(name, 'Identity')
+  validateName(opts.idp, 'IdP')
+  const store = await readIdentities()
+  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: opts.subject,
+    createdAt: existing?.createdAt ?? new Date().toISOString(),
+    source: 'idp',
+    mode: 'remote',
+    idp: opts.idp,
+    issuer: opts.issuer,
+    audience: opts.audience,
+    claims: opts.claims,
+    registrations: existing?.registrations,
+  }
+  store.identities[name] = identity
+  if (opts.use !== false) store.default = name
+  await writeIdentities(store)
+  return identity
+}
+
+/** Record (or replace) the kernel-derived (iss, sub) pair for an identity on a target instance. */
+export async function setRegistration(
+  name: string,
+  instanceSlug: string,
+  registration: Registration,
+): Promise<void> {
+  const store = await readIdentities()
+  const entry = store.identities[name]
+  if (!entry) throw new Error(`Identity "${name}" not found`)
+  entry.registrations = { ...entry.registrations, [instanceSlug]: registration }
+  await writeIdentities(store)
+}
+
+/** Migrate an identity to a new registry mode (local ↔ remote, §2.7). */
+export async function setIdentityMode(name: string, mode: RegistryMode): Promise<void> {
+  const store = await readIdentities()
+  const entry = store.identities[name]
+  if (!entry) throw new Error(`Identity "${name}" not found`)
+  entry.mode = mode
+  await writeIdentities(store)
+}

package/src/lib/idp-session.ts

@@ -0,0 +1,134 @@
+import { withFileLock } from './fs-atomic'
+import {
+  accessTokenForAudience,
+  classifyRefreshFailure,
+  idpSessionPath,
+  OAuthTokenError,
+  readIdpSession,
+  refreshSession,
+  type IdpSession,
+} from './idp'
+import { orgIdForAudience } from './instance'
+import { fetchOrgHint } from './meta'
+
+/** No cached session file exists for the identity — only a login creates one. */
+export class IdpSessionMissingError extends Error {
+  readonly identityName: string
+
+  constructor(identityName: string) {
+    super(`No cached IdP session for "${identityName}"`)
+    this.name = 'IdpSessionMissingError'
+    this.identityName = identityName
+  }
+}
+
+/** The session needs a refresh but never received a refresh token. */
+export class IdpSessionNoRefreshTokenError extends Error {
+  readonly identityName: string
+
+  constructor(identityName: string) {
+    super(`IdP session for "${identityName}" has no refresh token`)
+    this.name = 'IdpSessionNoRefreshTokenError'
+    this.identityName = identityName
+  }
+}
+
+export type EnsureFreshSessionOptions = {
+  audience?: string
+  organizationId?: string
+  /**
+   * Org-hint resolver, consulted only when a refresh actually happens.
+   * Defaults to `fetchOrgHint`; injectable for tests.
+   */
+  resolveOrganizationId?: (audience: string) => Promise<string | undefined>
+}
+
+export function idpSessionLockPath(identityName: string): string {
+  // Lives next to the session file; listIdpSessions only picks up *.json.
+  return `${idpSessionPath(identityName)}.lock`
+}
+
+/**
+ * Return a session holding a fresh access token for `audience`, refreshing it
+ * if needed. This is the ONLY correct way to refresh: WorkOS refresh tokens
+ * are single-use, so two processes refreshing concurrently burn the same
+ * token — the loser's `invalid_grant` can revoke the whole upstream session.
+ * All refreshes therefore serialize on a per-identity file lock, and waiters
+ * re-read the rotated session instead of re-exchanging.
+ *
+ * `IdpAudienceMismatchError` propagates verbatim (the session is healthy; the
+ * IdP just won't mint that audience).
+ */
+export async function ensureFreshSession(
+  identityName: string,
+  opts: EnsureFreshSessionOptions = {},
+): Promise<IdpSession> {
+  const session = await readIdpSession(identityName)
+  if (!session) throw new IdpSessionMissingError(identityName)
+  if (accessTokenForAudience(session, opts.audience)) return session
+  if (!session.refresh_token) throw new IdpSessionNoRefreshTokenError(identityName)
+
+  return withFileLock(idpSessionLockPath(identityName), async () => {
+    // Re-read under the lock: a process that held the lock before us may have
+    // already rotated the session — using its result is the whole point.
+    const current = await readIdpSession(identityName)
+    if (!current) throw new IdpSessionMissingError(identityName)
+    if (accessTokenForAudience(current, opts.audience)) return current
+
+    // Org resolution order: explicit > bookmarked-at-create > router lookup.
+    const bookmarkOrg =
+      opts.organizationId ?? (opts.audience ? await orgIdForAudience(opts.audience) : undefined)
+    const organizationId =
+      bookmarkOrg ??
+      (opts.audience
+        ? await (opts.resolveOrganizationId ?? fetchOrgHint)(opts.audience)
+        : undefined)
+    try {
+      return await refreshSession(identityName, current, {
+        audience: opts.audience,
+        organizationId,
+      })
+    } catch (e) {
+      // A bookmarked org can go stale (instance deleted/recreated elsewhere).
+      // On an org rejection, retry once with the router's view and let the
+      // bookmark heal on the next `instance create`.
+      if (
+        bookmarkOrg &&
+        !opts.organizationId &&
+        opts.audience &&
+        classifyRefreshFailure(e) === 'org-rejected'
+      ) {
+        const routerOrg = await (opts.resolveOrganizationId ?? fetchOrgHint)(opts.audience)
+        if (routerOrg && routerOrg !== bookmarkOrg) {
+          return await refreshSession(identityName, current, {
+            audience: opts.audience,
+            organizationId: routerOrg,
+          })
+        }
+      }
+      const rescued = await rescueAfterInvalidGrant(identityName, current, opts.audience, e)
+      if (rescued) return rescued
+      throw e
+    }
+  })
+}
+
+/**
+ * Last-resort race recovery: an `invalid_grant` ("refresh token already
+ * exchanged") can mean a non-locking process — an older CLI build, or a
+ * stale-lock takeover window — won the exchange and saved the rotated
+ * session. If the file changed since we read it and now serves the audience,
+ * use it instead of declaring the session dead.
+ */
+async function rescueAfterInvalidGrant(
+  identityName: string,
+  seen: IdpSession,
+  audience: string | undefined,
+  error: unknown,
+): Promise<IdpSession | undefined> {
+  if (!(error instanceof OAuthTokenError) || error.code !== 'invalid_grant') return undefined
+  const latest = await readIdpSession(identityName).catch(() => null)
+  if (!latest || latest.updatedAt === seen.updatedAt) return undefined
+  if (!accessTokenForAudience(latest, audience)) return undefined
+  return latest
+}