@asteroidai/cli 1.9.11 → 1.9.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteroidai/cli",
-  "version": "1.9.11",
+  "version": "1.9.27",
   "description": "The asteroid command-line interface for the Asteroid platform.",
   "type": "module",
   "license": "MIT",

package/src/account.ts

@@ -1,13 +1,17 @@
 import { UsageError } from "./args";
 import {
   API_KEY_OVERRIDES,
+  type Auth,
   AuthError,
+  isStaffLogin,
+  NotMemberError,
   orgFromToken,
   rememberOrg,
   resolveAuth,
+  staffHint,
   UNSET_API_KEY,
 } from "./auth/credentials";
-import { CredentialStore } from "./auth/store";
+import { CredentialStore, type StaffToken } from "./auth/store";
 import {
   authorizeDevice,
   pollDevice,
@@ -15,14 +19,16 @@ import {
   type WorkosOrg,
 } from "./auth/workos";
 import {
+  type Config,
   findOrg,
   loadConfig,
   mergeOrgs,
+  type Org,
   orgLabel,
   requestedOrg,
   saveConfig,
 } from "./config";
-import { send } from "./http";
+import { ApiError, send } from "./http";
 import { clean, render } from "./output";
 import type { Deps } from "./run";
 
@@ -128,11 +134,21 @@ export async function orgs(
     deps.fetch,
   );
   const list = loadConfig(deps.env).orgs ?? [];
+  const staff = (await new CredentialStore(deps.env).staffTokens()).filter(
+    (held) => held.expiresAt > Date.now(),
+  );
   const active = auth.org?.workosId;
   if (json) {
     deps.stdout(
       `${JSON.stringify(
-        list.map((org) => ({ ...org, active: org.workosId === active })),
+        [
+          ...list.map((org) => ({ ...org, active: org.workosId === active })),
+          ...staff.map((held) => ({
+            ...held.org,
+            active: held.org.workosId === active,
+            staff: { reason: held.reason, expiresAt: held.expiresAt },
+          })),
+        ],
         null,
         2,
       )}\n`,
@@ -141,17 +157,259 @@ export async function orgs(
   }
   for (const org of list)
     deps.stdout(`${org.workosId === active ? "*" : " "} ${orgLabel(org)}\n`);
+  for (const held of staff)
+    deps.stdout(
+      `${held.org.workosId === active ? "*" : " "} ${orgLabel(held.org)}  staff access, ${timeLeft(held.expiresAt)} left\n`,
+    );
+  return 0;
+}
+
+function timeLeft(expiresAt: number): string {
+  const minutes = Math.max(0, Math.round((expiresAt - Date.now()) / 60_000));
+  return minutes >= 60
+    ? `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`
+    : `${minutes}m`;
+}
+
+function isMember(config: Config, org: Org): boolean {
+  return (config.orgs ?? []).some((o) => o.workosId === org.workosId);
+}
+
+/** The org whose sign-in calls the mint: the default, or else any of yours. */
+function homeOrg(config: Config): Org {
+  const org =
+    config.org && isMember(config, config.org) ? config.org : config.orgs?.[0];
+  if (!org)
+    throw new AuthError(
+      "staff access needs a sign-in to one of your own organizations. Run `asteroid login`.",
+    );
+  return org;
+}
+
+const STAFF_TOKEN_PATH = "/users/v2/staff-tokens";
+
+interface MintedStaffToken {
+  token: string;
+  grantId: string;
+  organizationId: string;
+  organizationName: string;
+  workosOrganizationId?: string;
+  reason: string;
+  expiresAt: string;
+}
+
+async function mintStaffToken(
+  deps: Deps,
+  config: Config,
+  ref: string,
+  reason: string,
+): Promise<StaffToken> {
+  const home = await resolveAuth(
+    deps.env,
+    config,
+    homeOrg(config).workosId,
+    deps.fetch,
+  );
+  let minted: MintedStaffToken;
+  try {
+    const response = await send(
+      deps.env.apiUrl,
+      home,
+      {
+        method: "POST",
+        path: STAFF_TOKEN_PATH,
+        query: new URLSearchParams(),
+        json: { organization: ref, reason },
+      },
+      false,
+      deps.fetch,
+    );
+    minted = response.json as MintedStaffToken;
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 403)
+      throw new AuthError(
+        `you are not a member of ${clean(ref)}, and staff access is for Asteroid staff only.`,
+      );
+    if (error instanceof ApiError && error.status === 404)
+      throw new UsageError(
+        `unknown organization ${clean(ref)}. Pass its id or its WorkOS id (org_...).`,
+      );
+    throw error;
+  }
+  return {
+    token: minted.token,
+    grantId: minted.grantId,
+    org: {
+      workosId: minted.workosOrganizationId ?? minted.organizationId,
+      id: minted.organizationId,
+      name: minted.organizationName,
+    },
+    reason: minted.reason,
+    expiresAt: Date.parse(minted.expiresAt),
+  };
+}
+
+async function revokeStaffToken(
+  deps: Deps,
+  home: Auth,
+  held: StaffToken,
+): Promise<boolean> {
+  try {
+    await send(
+      deps.env.apiUrl,
+      home,
+      {
+        method: "DELETE",
+        path: `${STAFF_TOKEN_PATH}/${encodeURIComponent(held.grantId)}`,
+        query: new URLSearchParams(),
+      },
+      false,
+      deps.fetch,
+    );
+    return true;
+  } catch (error) {
+    // Gone already: revoked, or never recorded. Either way it no longer works.
+    if (error instanceof ApiError && error.status === 404) return true;
+    deps.stderr(
+      `Could not revoke staff access to ${orgLabel(held.org)}: ${clean(error instanceof Error ? error.message : String(error))}. It ends at ${new Date(held.expiresAt).toISOString()}.\n`,
+    );
+    return false;
+  }
+}
+
+/** `use --exit`: revoke every staff token now and go back to your own org. */
+async function exitStaff(deps: Deps): Promise<number> {
+  const store = new CredentialStore(deps.env);
+  const held = await store.staffTokens();
+  const config = loadConfig(deps.env);
+  if (held.length === 0) {
+    deps.stderr("No staff access to leave.\n");
+    return 0;
+  }
+  const home = await resolveAuth(
+    deps.env,
+    config,
+    homeOrg(config).workosId,
+    deps.fetch,
+  );
+  const left: StaffToken[] = [];
+  const kept: StaffToken[] = [];
+  for (const token of held) {
+    // Keep a token whose grant is still live, so a retry can revoke it.
+    const ended =
+      token.expiresAt <= Date.now() ||
+      (await revokeStaffToken(deps, home, token));
+    if (!ended) {
+      kept.push(token);
+      continue;
+    }
+    await store.dropStaffToken(token.grantId);
+    left.push(token);
+  }
+  const back = held.find((t) => t.from)?.from ?? homeOrg(config);
+  saveConfig(deps.env, { ...loadConfig(deps.env), org: back });
+  if (left.length > 0)
+    deps.stderr(
+      `Left staff access to ${left.map((t) => orgLabel(t.org)).join(", ")}.\n`,
+    );
+  if (kept.length > 0)
+    deps.stderr(
+      `Still holding staff access to ${kept.map((t) => orgLabel(t.org)).join(", ")}. Run \`asteroid use --exit\` again to retry.\n`,
+    );
+  deps.stderr(`Now using ${orgLabel(back)}.\n`);
+  return kept.length === 0 ? 0 : 1;
+}
+
+async function askReason(deps: Deps, org: string): Promise<string | undefined> {
+  if (!deps.ui) return undefined;
+  const reason = await deps.ui.text(
+    `You are not a member of ${clean(org)}. Why do you need staff access? This is audited.`,
+  );
+  return reason?.trim() || undefined;
+}
+
+/** The staff path of `use`: mint a token for an org you are not a member of. */
+async function useAsStaff(
+  deps: Deps,
+  config: Config,
+  ref: string,
+  reason: string | undefined,
+  staff: boolean,
+): Promise<number> {
+  const store = new CredentialStore(deps.env);
+  const held = await store.staffToken(ref);
+  if (held && held.expiresAt - 30_000 > Date.now() && !reason) {
+    saveConfig(deps.env, { ...config, org: held.org });
+    deps.stderr(
+      `Now using ${orgLabel(held.org)} with staff access, ${timeLeft(held.expiresAt)} left.\n`,
+    );
+    return 0;
+  }
+  if (!reason && staff) reason = await askReason(deps, ref);
+  if (!reason)
+    throw new UsageError(
+      `you are not a member of ${clean(ref)}.${staffHint(ref, staff)}${staff ? " The reason is audited." : ""}`,
+    );
+  // The mint takes an id, not a name. A held token knows the id.
+  const minted = await mintStaffToken(
+    deps,
+    config,
+    held?.org.id ?? ref,
+    reason,
+  );
+  const previous = config.org
+    ? isMember(config, config.org)
+      ? config.org
+      : (await store.staffToken(config.org.workosId))?.from
+    : undefined;
+  try {
+    await store.saveStaffToken(
+      { ...minted, from: previous ?? held?.from },
+      held?.grantId,
+    );
+  } catch (error) {
+    // Nothing holds the token, so nothing could revoke it later. End it now.
+    const home = await resolveAuth(
+      deps.env,
+      config,
+      homeOrg(config).workosId,
+      deps.fetch,
+    );
+    await revokeStaffToken(deps, home, minted);
+    throw error;
+  }
+  saveConfig(deps.env, { ...loadConfig(deps.env), org: minted.org });
+  deps.stderr(
+    `Staff access to ${orgLabel(minted.org)} for ${timeLeft(minted.expiresAt)}, until ${new Date(minted.expiresAt).toLocaleTimeString()}. ` +
+      `Reason: ${clean(minted.reason)}. This is audited. Run \`asteroid use --exit\` to leave.\n`,
+  );
   return 0;
 }
 
+export interface UseOptions {
+  reason?: string;
+  exit?: boolean;
+}
+
 export async function use(
   deps: Deps,
   ref: string | undefined,
+  options: UseOptions = {},
 ): Promise<number> {
   if (deps.env.apiKey)
     throw new UsageError(
       `${API_KEY_OVERRIDES} \`use\` only switches the login's organization. ${UNSET_API_KEY}`,
     );
+  if (options.exit) {
+    if (ref || options.reason)
+      throw new UsageError("usage: asteroid use --exit");
+    return exitStaff(deps);
+  }
+  // `--reason --exit` must not mint a grant whose reason is "--exit".
+  if (options.reason?.startsWith("-"))
+    throw new UsageError(
+      `--reason needs a value, not ${clean(options.reason)}. Give the reason without a leading -.`,
+    );
   const config = loadConfig(deps.env);
   if (!ref && deps.ui && (config.orgs?.length ?? 0) > 0) {
     ref = await deps.ui.select(
@@ -164,12 +422,22 @@ export async function use(
     if (!ref) return 1;
   }
   if (!ref) throw new UsageError("usage: asteroid use <org>");
+  const login = await new CredentialStore(deps.env).readLogin();
+  if (!login) throw new AuthError("not signed in. Run `asteroid login`.");
+  const staff = isStaffLogin(login);
   const org = findOrg(ref, config.orgs ?? []);
-  if (!org)
-    throw new UsageError(
-      `unknown organization ${ref}. Run \`asteroid orgs\` to list yours.`,
-    );
-  const auth = await resolveAuth(deps.env, config, org.workosId, deps.fetch);
+  // Not one of yours: an id or name the sign-in does not list. A bare WorkOS id
+  // may still be yours, so the refresh decides.
+  if (!org || (!isMember(config, org) && options.reason))
+    return useAsStaff(deps, config, ref, options.reason, staff);
+  let auth: Auth;
+  try {
+    auth = await resolveAuth(deps.env, config, org.workosId, deps.fetch);
+  } catch (error) {
+    if (error instanceof NotMemberError)
+      return useAsStaff(deps, config, ref, options.reason, staff);
+    throw error;
+  }
   const updated = loadConfig(deps.env);
   updated.org =
     updated.orgs?.find((o) => o.workosId === org.workosId) ?? auth.org ?? org;
@@ -207,6 +475,7 @@ export async function whoami(
     );
     return 0;
   }
+  const grant = body.staffGrant as { reason?: string } | undefined;
   const person = body.person as { email?: string } | undefined;
   const orgId = body.organizationId as string | undefined;
   const organization = auth.org ? orgLabel(auth.org) : (orgId ?? "none");
@@ -215,9 +484,17 @@ export async function whoami(
       as: person?.email ?? body.id,
       kind: body.kind,
       credential: body.credential,
-      source: auth.kind === "api-key" ? "ASTEROID_API_KEY" : "asteroid login",
+      source:
+        auth.kind === "api-key"
+          ? "ASTEROID_API_KEY"
+          : auth.staff
+            ? "asteroid use (staff access)"
+            : "asteroid login",
       organization,
-      ...(minutes === undefined ? {} : { tokenExpiresIn: `${minutes}m` }),
+      ...(grant ? { staffReason: grant.reason } : {}),
+      ...(auth.expiresAt === undefined
+        ? {}
+        : { tokenExpiresIn: timeLeft(auth.expiresAt) }),
     })}\n`,
   );
   return 0;

package/src/auth/credentials.ts

@@ -7,11 +7,15 @@ import {
   orgLabel,
   saveConfig,
 } from "../config";
-import { CredentialStore } from "./store";
+import { clean } from "../output";
+import { CredentialStore, type Login, type StaffToken } from "./store";
 import { refresh, tokenClaims, WorkosError } from "./workos";
 
 export class AuthError extends Error {}
 
+/** The sign-in is fine, but the person is not a member of the org. */
+export class NotMemberError extends AuthError {}
+
 export const API_KEY_OVERRIDES =
   "ASTEROID_API_KEY is set, so the CLI uses that key and ignores `asteroid login`.";
 export const UNSET_API_KEY =
@@ -22,6 +26,30 @@ export interface Auth {
   headers: Record<string, string>;
   org?: Org;
   expiresAt?: number;
+  /** Set when the token is a staff token from `asteroid use <org> --reason`. */
+  staff?: { grantId: string; reason: string };
+}
+
+/** An Asteroid sign-in. It only decides which hints to show: the server checks the admin list. */
+export function isStaffLogin(login: Login | undefined): boolean {
+  return login?.email?.toLowerCase().endsWith("@asteroid.ai") ?? false;
+}
+
+/** The `--reason` hint, for staff only. Empty for everyone else. */
+export function staffHint(ref: string, staff: boolean): string {
+  return staff
+    ? ` Asteroid staff: run \`asteroid use ${clean(ref)} --reason <why>\`.`
+    : "";
+}
+
+function staffAuth(held: StaffToken): Auth {
+  return {
+    kind: "bearer",
+    headers: { Authorization: `Bearer ${held.token}` },
+    org: held.org,
+    expiresAt: held.expiresAt,
+    staff: { grantId: held.grantId, reason: held.reason },
+  };
 }
 
 export function orgFromToken(token: string): Org | undefined {
@@ -55,7 +83,7 @@ function bearer(token: string, expiresAt: number): Auth {
 const SSO_OR_MFA =
   /^(sso_required|mfa_.*|organization_authentication_methods_required)$/;
 
-function refreshError(error: WorkosError, org: Org): AuthError {
+function refreshError(error: WorkosError, org: Org, login: Login): AuthError {
   if (error.code === "invalid_grant") {
     return new AuthError("your sign-in has expired. Run `asteroid login`.");
   }
@@ -65,8 +93,8 @@ function refreshError(error: WorkosError, org: Org): AuthError {
     );
   }
   if (error.code === "organization_membership_not_found") {
-    return new AuthError(
-      `you are not a member of ${orgLabel(org)}. Staff access to other organizations is not available yet.`,
+    return new NotMemberError(
+      `you are not a member of ${orgLabel(org)}.${staffHint(org.id ?? org.workosId, isStaffLogin(login))}`,
     );
   }
   return new AuthError(
@@ -84,16 +112,26 @@ export async function resolveAuth(
     return { kind: "api-key", headers: { "X-Api-Key": env.apiKey } };
 
   const store = new CredentialStore(env);
-  if (!(await store.readLogin())) {
+  const login = await store.readLogin();
+  if (!login) {
     throw new AuthError(
       "not signed in. Run `asteroid login`, or set ASTEROID_API_KEY.",
     );
   }
 
+  const target = orgRef ?? config.org?.workosId;
+  const held = target ? await store.staffToken(target) : undefined;
+  if (held) {
+    if (held.expiresAt - 30_000 > Date.now()) return staffAuth(held);
+    throw new AuthError(
+      `your staff access to ${orgLabel(held.org)} has expired.${staffHint(held.org.id ?? held.org.workosId, true)}`,
+    );
+  }
+
   const org = orgRef ? findOrg(orgRef, config.orgs ?? []) : config.org;
   if (orgRef && !org) {
     throw new AuthError(
-      `unknown organization ${orgRef}. Run \`asteroid orgs\` to list yours.`,
+      `unknown organization ${clean(orgRef)}. Run \`asteroid orgs\` to list yours.${staffHint(orgRef, isStaffLogin(login))}`,
     );
   }
   if (!org) {
@@ -134,7 +172,7 @@ export async function resolveAuth(
       rememberOrg(env, config, auth.org);
       return auth;
     } catch (error) {
-      if (error instanceof WorkosError) throw refreshError(error, org);
+      if (error instanceof WorkosError) throw refreshError(error, org, login);
       throw error;
     }
   });

package/src/auth/store.ts

@@ -2,12 +2,13 @@ import { mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import lockfile from "proper-lockfile";
 
-import { type Env, readJson, writePrivateJson } from "../config";
+import { type Env, type Org, readJson, writePrivateJson } from "../config";
 import { WorkosError } from "./workos";
 
 const SERVICE = "asteroid-cli";
 const LOCK_STALE_MS = 30_000;
 const ACCOUNT = "refresh-token";
+const STAFF_ACCOUNT = "staff-tokens";
 
 export interface Login {
   refreshToken: string;
@@ -19,17 +20,30 @@ export interface CachedToken {
   expiresAt: number;
 }
 
+/** A staff token for one org that is not yours. It lasts 8 h and is audited. */
+export interface StaffToken {
+  token: string;
+  grantId: string;
+  org: Org;
+  reason: string;
+  expiresAt: number;
+  /** The default org before `asteroid use` took staff access. */
+  from?: Org;
+}
+
+type StaffTokens = Record<string, StaffToken>;
+
 interface Keyring {
   get(): string | null;
   set(value: string): void;
   delete(): void;
 }
 
-async function keyring(): Promise<Keyring | undefined> {
+async function keyring(account = ACCOUNT): Promise<Keyring | undefined> {
   if (process.env.ASTEROID_NO_KEYCHAIN) return undefined;
   try {
     const { Entry } = await import("@napi-rs/keyring");
-    const entry = new Entry(SERVICE, ACCOUNT);
+    const entry = new Entry(SERVICE, account);
     entry.getPassword();
     return {
       get: () => entry.getPassword() ?? null,
@@ -72,6 +86,10 @@ export class CredentialStore {
     return join(this.env.configDir, "tokens.json");
   }
 
+  private get staffFile() {
+    return join(this.env.configDir, "staff-tokens.json");
+  }
+
   async readLogin(): Promise<Login | undefined> {
     const ring = await keyring();
     const raw = ring ? tryGet(ring).value : null;
@@ -102,23 +120,113 @@ export class CredentialStore {
     const cleared = current.ok && (!current.value || trySet(ring!, null));
     rmSync(this.loginFile, { force: true });
     rmSync(this.tokenFile, { force: true });
-    return cleared;
+    const staffCleared = await this.withStaffLock(() =>
+      this.writeStaffTokens({}),
+    );
+    return staffCleared && cleared;
+  }
+
+  /** Every staff token held, expired ones included. */
+  async staffTokens(): Promise<StaffToken[]> {
+    const ring = await keyring(STAFF_ACCOUNT);
+    const raw = ring ? tryGet(ring).value : null;
+    const tokens = raw
+      ? (JSON.parse(raw) as StaffTokens)
+      : readJson<StaffTokens>(this.staffFile, {});
+    return Object.values(tokens);
+  }
+
+  /** The staff token for an org, matched by WorkOS id, id or name. */
+  async staffToken(ref: string): Promise<StaffToken | undefined> {
+    const lower = ref.toLowerCase();
+    return (await this.staffTokens()).find(
+      ({ org }) =>
+        org.workosId.toLowerCase() === lower ||
+        org.id?.toLowerCase() === lower ||
+        org.name?.toLowerCase() === lower,
+    );
+  }
+
+  /** Saves a staff token and drops expired ones. `replaces` is dropped too. */
+  async saveStaffToken(token: StaffToken, replaces?: string) {
+    await this.withStaffLock(async () => {
+      const tokens: StaffTokens = {};
+      for (const held of await this.staffTokens())
+        if (held.expiresAt > Date.now() && held.grantId !== replaces)
+          tokens[held.org.workosId] = held;
+      tokens[token.org.workosId] = token;
+      if (!(await this.writeStaffTokens(tokens)))
+        throw new WorkosError(
+          "keychain",
+          "could not save the staff token in the OS keychain. Unlock it and try again.",
+        );
+    });
+  }
+
+  async dropStaffToken(grantId: string) {
+    await this.withStaffLock(async () => {
+      const tokens: StaffTokens = {};
+      for (const held of await this.staffTokens())
+        if (held.grantId !== grantId) tokens[held.org.workosId] = held;
+      if (!(await this.writeStaffTokens(tokens)))
+        throw new WorkosError(
+          "keychain",
+          "could not remove the staff token from the OS keychain. Unlock it and try again.",
+        );
+    });
+  }
+
+  private async writeStaffTokens(tokens: StaffTokens): Promise<boolean> {
+    const empty = Object.keys(tokens).length === 0;
+    const ring = await keyring(STAFF_ACCOUNT);
+    if (ring && trySet(ring, empty ? null : JSON.stringify(tokens))) {
+      rmSync(this.staffFile, { force: true });
+      return true;
+    }
+    const stale = ring ? tryGet(ring) : { ok: true, value: null };
+    if (!stale.ok || (stale.value && !trySet(ring!, null))) return false;
+    if (empty) rmSync(this.staffFile, { force: true });
+    else writePrivateJson(this.staffFile, tokens);
+    return true;
   }
 
   async withRefreshLock<T>(work: () => Promise<T>): Promise<T> {
+    return this.withLock(
+      "refresh",
+      "another asteroid command is refreshing the sign-in.",
+      work,
+    );
+  }
+
+  /** Two commands at once must not lose a grant they could still revoke. */
+  private async withStaffLock<T>(work: () => Promise<T>): Promise<T> {
+    return this.withLock(
+      "staff",
+      "another asteroid command is saving staff access.",
+      work,
+    );
+  }
+
+  private async withLock<T>(
+    name: string,
+    busy: string,
+    work: () => Promise<T>,
+  ): Promise<T> {
     mkdirSync(this.env.configDir, { recursive: true, mode: 0o700 });
-    const lockfilePath = join(this.env.configDir, "refresh.lock");
+    const lockfilePath = join(this.env.configDir, `${name}.lock`);
     let release: () => Promise<void>;
     try {
-      release = await lockfile.lock(this.env.configDir, {
+      // Each lock names its own target: proper-lockfile tracks locks by target.
+      release = await lockfile.lock(join(this.env.configDir, name), {
         lockfilePath,
+        realpath: false,
         stale: LOCK_STALE_MS,
         retries: { retries: 60, minTimeout: 100, maxTimeout: 500 },
       });
     } catch {
       throw new WorkosError(
         "locked",
-        `another asteroid command is refreshing the sign-in. Try again, or delete ${lockfilePath} if none is running.`,
+        `${busy} Try again, or delete ${lockfilePath} if none is running.`,
       );
     }
     try {