@astrale-os/cli 0.4.0-alpha.13

package/src/commands/admin/status.ts

@@ -0,0 +1,61 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+
+import { resolveAdminTargetFromStore } from '../../lib/admin-target'
+import { readConfig } from '../../lib/config'
+import { getDefault } from '../../lib/identity'
+import { readInstances } from '../../lib/instance'
+import { fatal, log } from '../../lib/log'
+import { isMachine, output, RAW_OUTPUT_OPTIONS, type RawOutputOpts } from '../../lib/output'
+
+type AdminStatus = {
+  target: ReturnType<typeof resolveAdminTargetFromStore>
+  identity: {
+    name: string
+    registered: boolean
+  } | null
+}
+
+export default {
+  name: 'status',
+  description: 'Show configured admin kernel target',
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (opts: RawOutputOpts) => {
+    try {
+      const [config, instances, identity] = await Promise.all([
+        readConfig(),
+        readInstances(),
+        getDefault().catch(() => null),
+      ])
+      const target = resolveAdminTargetFromStore({}, config, instances)
+      const status: AdminStatus = {
+        target,
+        identity: identity
+          ? {
+              name: identity.name,
+              registered: !!identity.registrations?.[target.registrationSlug],
+            }
+          : null,
+      }
+
+      if (isMachine(opts)) {
+        output(status, opts)
+        return
+      }
+
+      console.log(chalk.bold('Admin'))
+      console.log(`  ${chalk.bold(target.name)} ${chalk.dim(target.url)}`)
+      console.log(`  issuer: ${chalk.dim(target.issuer)}`)
+      console.log(`  source: ${target.source}`)
+      if (status.identity) {
+        const mark = status.identity.registered ? chalk.green('yes') : chalk.yellow('no')
+        console.log(`  identity ${status.identity.name} registered: ${mark}`)
+      } else {
+        log.dim('  No default identity. Run: astrale identity create <name>')
+      }
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/admin/use.ts

@@ -0,0 +1,77 @@
+import type { CommandDefinition } from '../../command'
+
+import { AdminTargetConfigSchema, DEFAULT_ADMIN_TARGET_NAME } from '../../lib/admin-target'
+import { readConfig, writeConfig } from '../../lib/config'
+import { resolveInstance } from '../../lib/instance'
+import { fatal, log } from '../../lib/log'
+
+type AdminUseOpts = {
+  url?: string
+  name?: string
+  issuer?: string
+}
+
+export default {
+  name: 'use',
+  description: 'Set the admin kernel target',
+  afterHelpText: `
+Behavior:
+  The admin target is the admin kernel used by admin-backed commands such as
+  \`astrale instance create\`, \`astrale instance list\`, and
+  \`astrale instance delete\`. It is independent from the active instance used
+  by normal kernel calls.
+
+Examples:
+  $ astrale admin use admin
+  $ astrale admin use --url https://admin.eu.astrale.ai/api
+  $ astrale admin status
+`,
+  arguments: [{ name: 'bookmark', description: 'Bookmarked admin instance', required: false }],
+  options: [
+    { flags: '--url <url>', description: 'Direct admin kernel URL' },
+    {
+      flags: '--name <name>',
+      description: 'Friendly name / registration slug for direct URL admin target',
+    },
+    { flags: '--issuer <url>', description: 'Admin kernel issuer/audience if different from URL' },
+  ],
+  action: async (bookmark: string | undefined, opts: AdminUseOpts) => {
+    try {
+      if (bookmark && opts.url) {
+        fatal('Choose either a bookmark argument or --url, not both')
+      }
+
+      const config = await readConfig()
+      if (opts.url) {
+        const name = opts.name ?? DEFAULT_ADMIN_TARGET_NAME
+        await writeConfig({
+          ...config,
+          admin: AdminTargetConfigSchema.parse({
+            name,
+            url: opts.url,
+            issuer: opts.issuer ?? opts.url,
+          }),
+        })
+        log.success(`Admin target: ${name} (${opts.url})`)
+        return
+      }
+
+      if (!bookmark) {
+        fatal(
+          'Missing admin target. Use: astrale admin use <bookmark> or astrale admin use --url <url>',
+        )
+      }
+
+      const resolved = await resolveInstance(bookmark)
+      await writeConfig({
+        ...config,
+        admin: AdminTargetConfigSchema.parse({
+          instance: resolved.name,
+        }),
+      })
+      log.success(`Admin target: ${resolved.name} (${resolved.url})`)
+    } catch (e) {
+      fatal(e)
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/auth/login.ts

@@ -0,0 +1,82 @@
+import type { CommandDefinition } from '../../command'
+
+import { type IdpSession } from '../../lib/idp'
+import { log } from '../../lib/log'
+import { loginViaIdp, type LoginFlowOpts } from '../../lib/login-flow'
+import { isMachine, output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+
+type LoginOpts = LoginFlowOpts & {
+  device?: boolean
+  raw?: boolean
+  json?: boolean
+}
+
+export default {
+  name: 'login',
+  description: 'Authenticate with an IdP and store an IdP-backed identity',
+  options: [
+    { flags: '--idp <name>', description: 'IdP registry name (defaults when exactly one exists)' },
+    { flags: '--name <name>', description: 'Local identity name to create/update' },
+    { flags: '--scope <scope>', description: 'OAuth scope override' },
+    { flags: '--audience <audience>', description: 'OAuth audience/resource parameter' },
+    { flags: '--client-id <id>', description: 'OAuth client ID override' },
+    { flags: '--client-secret-env <name>', description: 'Env var containing the client secret' },
+    { flags: '--client-credentials', description: 'Use OAuth client_credentials grant' },
+    { flags: '--device', description: 'Use OAuth device authorization flow (default)' },
+    {
+      flags: '--code <code>',
+      description: 'Exchange an authorization code instead of device auth',
+    },
+    { flags: '--redirect-uri <url>', description: 'Redirect URI for authorization-code exchange' },
+    {
+      flags: '--code-verifier <value>',
+      description: 'PKCE verifier for authorization-code exchange',
+    },
+    {
+      flags: '--no-use',
+      description: 'Do not switch the default identity to the logged-in identity',
+    },
+    ...RAW_OUTPUT_OPTIONS,
+  ],
+  afterHelpText: `
+Examples:
+  $ astrale auth login --idp workos --device
+  $ astrale auth login --idp workos --client-credentials \\
+      --client-secret-env WORKOS_CLIENT_SECRET --audience https://api.example.com
+  $ astrale auth login --idp workos --code <code> --redirect-uri http://127.0.0.1:8787/callback
+
+Notes:
+  Device auth is the default because it matches CLI use. Token values are
+  cached locally for credential resolution but are never printed.
+`,
+  action: async (opts: LoginOpts) => {
+    const { session, identityName, idpName } = await loginViaIdp(opts)
+
+    if (isMachine(opts)) {
+      output(publicSession(session), opts)
+      return
+    }
+
+    log.success(`Logged in as "${identityName}" via IdP "${idpName}"`)
+    log.dim(`  subject: ${session.subject}`)
+    if (session.expires_at) log.dim(`  expires_at: ${session.expires_at}`)
+    if (opts.use !== false) log.dim('  default identity updated')
+  },
+} satisfies CommandDefinition
+
+function publicSession(session: IdpSession): Record<string, unknown> {
+  return {
+    identity: session.identity,
+    idp: session.idp,
+    issuer: session.issuer,
+    subject: session.subject,
+    audience: session.audience,
+    token_type: session.token_type,
+    scope: session.scope,
+    expires_at: session.expires_at,
+    has_access_token: !!session.access_token,
+    has_id_token: !!session.id_token,
+    has_refresh_token: !!session.refresh_token,
+    updatedAt: session.updatedAt,
+  }
+}

package/src/commands/auth/logout.ts

@@ -0,0 +1,50 @@
+import type { CommandDefinition } from '../../command'
+
+import { getDefault, readIdentities } from '../../lib/identity'
+import { deleteIdpSession, listIdpSessions } from '../../lib/idp'
+import { log } from '../../lib/log'
+import { output, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+
+export default {
+  name: 'logout',
+  description: 'Clear cached IdP session tokens',
+  options: [
+    { flags: '--name <name>', description: 'Identity session to clear' },
+    { flags: '--all', description: 'Clear every cached IdP session' },
+    ...RAW_OUTPUT_OPTIONS,
+  ],
+  action: async (opts: { name?: string; all?: boolean; raw?: boolean; json?: boolean }) => {
+    let names: string[]
+    if (opts.all) {
+      names = (await listIdpSessions()).map((session) => session.identity)
+    } else if (opts.name) {
+      names = [opts.name]
+    } else {
+      const identity = await getDefault()
+      if ((identity.source ?? 'key') !== 'idp') {
+        throw new Error('Default identity is not IdP-backed. Pass --name or --all.')
+      }
+      names = [identity.name]
+    }
+
+    for (const name of names) await deleteIdpSession(name)
+
+    if (opts.raw || opts.json) {
+      output({ cleared: names }, opts)
+      return
+    }
+    if (names.length === 0) {
+      log.dim('  No cached IdP sessions')
+      return
+    }
+    log.success(`Cleared IdP session${names.length === 1 ? '' : 's'}: ${names.join(', ')}`)
+
+    const store = await readIdentities()
+    const stale = names.filter((name) => store.identities[name]?.source === 'idp')
+    if (stale.length > 0) {
+      log.dim(
+        '  IdP identity records remain; delete them with `astrale identity delete <name>` if needed.',
+      )
+    }
+  },
+} satisfies CommandDefinition

package/src/commands/auth/status.ts

@@ -0,0 +1,86 @@
+import chalk from 'chalk'
+
+import type { CommandDefinition } from '../../command'
+import type { ListOpts, ListProjection } from '../../lib/output'
+
+import { readIdentities } from '../../lib/identity'
+import { isSessionExpired, listIdpSessions } from '../../lib/idp'
+import { log } from '../../lib/log'
+import { isMachine, presentList, RAW_OUTPUT_OPTIONS } from '../../lib/output'
+
+type AuthRow = {
+  name: string
+  default: boolean
+  idp?: string
+  issuer?: string
+  subject: string
+  session:
+    | {
+        cached: true
+        expired: boolean
+        expires_at?: string
+        scope?: string
+        has_refresh_token: boolean
+      }
+    | { cached: false }
+}
+
+function sessionState(s: AuthRow['session']): string {
+  if (!s.cached) return chalk.dim('no session')
+  return s.expired ? chalk.yellow('expired') : chalk.green('active')
+}
+
+function projection(items: AuthRow[]): ListProjection {
+  return {
+    columns: [
+      { key: 'name', header: 'NAME', color: chalk.bold },
+      { key: 'session', header: 'SESSION' },
+      { key: 'idp', header: 'IDP', color: chalk.dim },
+      { key: 'subject', header: 'SUBJECT', color: chalk.dim },
+    ],
+    rows: items.map((i) => ({
+      name: i.default ? `${i.name} ${chalk.green('*')}` : i.name,
+      session: sessionState(i.session),
+      idp: i.idp ?? '',
+      subject: i.subject,
+    })),
+    paths: items.map((i) => i.name),
+  }
+}
+
+export default {
+  name: 'status',
+  description: 'Show cached IdP authentication status',
+  options: [...RAW_OUTPUT_OPTIONS],
+  action: async (opts: ListOpts) => {
+    const [identityStore, sessions] = await Promise.all([readIdentities(), listIdpSessions()])
+    const byIdentity = new Map(sessions.map((session) => [session.identity, session]))
+    const items: AuthRow[] = Object.entries(identityStore.identities)
+      .filter(([, identity]) => identity.source === 'idp')
+      .map(([name, identity]) => {
+        const session = byIdentity.get(name)
+        return {
+          name,
+          default: identityStore.default === name,
+          idp: identity.idp,
+          issuer: identity.issuer,
+          subject: identity.subject,
+          session: session
+            ? {
+                cached: true,
+                expired: isSessionExpired(session),
+                expires_at: session.expires_at,
+                scope: session.scope,
+                has_refresh_token: !!session.refresh_token,
+              }
+            : { cached: false },
+        }
+      })
+
+    if (items.length === 0 && !isMachine(opts)) {
+      log.dim('  Not logged in to any IdP. Run: astrale auth login --idp <name>')
+      return
+    }
+    presentList(items, opts, projection)
+  },
+} satisfies CommandDefinition

package/src/commands/auth/token.ts

@@ -0,0 +1,162 @@
+import type { CommandDefinition } from '../../command'
+
+import { getDefault, getIdentity, readIdentities } from '../../lib/identity'
+import { isSessionExpired, readIdpSession, type IdpSession } from '../../lib/idp'
+import { ensureFreshSession } from '../../lib/idp-session'
+import { log } from '../../lib/log'
+import { output } from '../../lib/output'
+
+type AuthTokenType = 'access' | 'id'
+
+type AuthTokenOpts = {
+  name?: string
+  idp?: string
+  type?: AuthTokenType
+  refresh?: boolean
+  raw?: boolean
+  json?: boolean
+}
+
+type AuthTokenResult = {
+  identity: string
+  idp: string
+  issuer: string
+  subject: string
+  type: AuthTokenType
+  token: string
+  token_type?: string
+  scope?: string
+  expires_at?: string
+  expired: boolean
+  refreshed: boolean
+  updatedAt: string
+}
+
+export default {
+  name: 'token',
+  description: 'Print a cached IdP provider token for an IdP-backed identity',
+  options: [
+    {
+      flags: '--name <name>',
+      description: 'IdP-backed identity name (defaults to active identity)',
+    },
+    { flags: '--idp <name>', description: 'Select the IdP when identity name is omitted' },
+    {
+      flags: '--type <type>',
+      description: 'Token type to print',
+      choices: ['access', 'id'],
+      default: 'access',
+    },
+    {
+      flags: '--no-refresh',
+      description: 'Do not refresh an expired cached session before printing',
+    },
+    { flags: '--raw', description: 'Print only the token string' },
+    { flags: '--json', description: 'Print JSON metadata including the token' },
+  ],
+  afterHelpText: `
+Behavior:
+  Defaults to the active IdP-backed identity. If the cached session is expired,
+  the CLI refreshes it before printing unless --no-refresh is passed. --raw
+  prints only the token string for shell use.
+
+Examples:
+  $ astrale auth token --raw
+  $ astrale auth token --idp workos --raw
+  $ astrale auth token --name alice --type id --json
+`,
+  action: async (opts: AuthTokenOpts) => {
+    const result = await resolveAuthToken(opts)
+
+    if (opts.raw) {
+      process.stdout.write(result.token + '\n')
+      return
+    }
+
+    if (opts.json) {
+      output(result, { json: true })
+      return
+    }
+
+    log.dim(`  (${result.idp} ${result.type}_token for identity "${result.identity}" - secret)`)
+    process.stdout.write(result.token + '\n')
+  },
+} satisfies CommandDefinition
+
+export async function resolveAuthToken(opts: AuthTokenOpts): Promise<AuthTokenResult> {
+  const identityName = await resolveIdentityName(opts)
+  const session = await readIdpSession(identityName)
+  if (!session) {
+    throw new Error(
+      `No cached IdP session for "${identityName}". Run: astrale auth login --name ${identityName}`,
+    )
+  }
+
+  // ensureFreshSession serializes the (single-use) refresh-token exchange
+  // across concurrent CLI processes and is a no-op while the token is fresh.
+  const resolved = opts.refresh !== false ? await ensureFreshSession(identityName) : session
+  const type = opts.type ?? 'access'
+  const token = tokenFromSession(resolved, type)
+
+  return {
+    identity: resolved.identity,
+    idp: resolved.idp,
+    issuer: resolved.issuer,
+    subject: resolved.subject,
+    type,
+    token,
+    token_type: resolved.token_type,
+    scope: resolved.scope,
+    expires_at: resolved.expires_at,
+    expired: isSessionExpired(resolved),
+    refreshed: resolved.updatedAt !== session.updatedAt,
+    updatedAt: resolved.updatedAt,
+  }
+}
+
+async function resolveIdentityName(opts: AuthTokenOpts): Promise<string> {
+  if (opts.name) {
+    const identity = await getIdentity(opts.name)
+    if ((identity.source ?? 'key') !== 'idp') {
+      throw new Error(`Identity "${opts.name}" is not IdP-backed`)
+    }
+    if (opts.idp && identity.idp !== opts.idp) {
+      throw new Error(
+        `Identity "${opts.name}" is backed by IdP "${identity.idp ?? '?'}", not "${opts.idp}"`,
+      )
+    }
+    return opts.name
+  }
+
+  if (opts.idp) {
+    const store = await readIdentities()
+    const matches = Object.entries(store.identities)
+      .filter(([, identity]) => identity.source === 'idp' && identity.idp === opts.idp)
+      .map(([name]) => name)
+
+    if (matches.length === 0) {
+      throw new Error(
+        `No IdP-backed identities found for IdP "${opts.idp}". Run: astrale auth login --idp ${opts.idp}`,
+      )
+    }
+    if (matches.includes(store.default)) return store.default
+    if (matches.length === 1) return matches[0]
+    throw new Error(
+      `Multiple IdP-backed identities found for IdP "${opts.idp}": ${matches.join(', ')}. Pass --name.`,
+    )
+  }
+
+  const identity = await getDefault()
+  if ((identity.source ?? 'key') !== 'idp') {
+    throw new Error('Default identity is not IdP-backed. Pass --name or --idp.')
+  }
+  return identity.name
+}
+
+function tokenFromSession(session: IdpSession, type: AuthTokenType): string {
+  if (type === 'access') return session.access_token
+  if (session.id_token) return session.id_token
+  throw new Error(
+    `Cached IdP session for "${session.identity}" has no id_token. Use --type access.`,
+  )
+}