@asteroidai/cli 1.9.12 → 1.9.27

package/src/program.ts

@@ -1,4 +1,4 @@
-import { Command, CommanderError } from "commander";
+import { Command, CommanderError, Option as Flag } from "commander";
 
 import { type Parsed, UsageError } from "./args";
 import { type BuiltinCommand, GLOBAL_FLAGS } from "./reference";
@@ -146,6 +146,8 @@ export function defineCommands(
   for (const builtin of options.builtins ?? []) {
     const leaf = root.command(builtin.command).description(builtin.description);
     if (builtin.arg) leaf.argument(`[${builtin.arg}]`);
+    for (const [flags, text] of builtin.hiddenOptions ?? [])
+      leaf.addOption(new Flag(flags, text).hideHelp());
     leaf.action((...args: unknown[]) => {
       const cmd = args.at(-1) as Command;
       onInvocation({

package/src/reference.ts

@@ -6,6 +6,8 @@ export interface BuiltinCommand {
   description: string;
   args: number;
   arg?: string;
+  /** Flags left out of `--help` and the reference: staff only. */
+  hiddenOptions?: [string, string][];
 }
 
 export const BUILTINS: BuiltinCommand[] = [
@@ -36,6 +38,16 @@ export const BUILTINS: BuiltinCommand[] = [
     description:
       "Make an organization, by id or name, the default for later commands. Without one, pick from a list.",
     args: 1,
+    hiddenOptions: [
+      [
+        "--reason <why>",
+        "Staff only. Why you need access to an organization you are not a member of, such as a ticket id. It is audited. Asked for in a terminal.",
+      ],
+      [
+        "--exit",
+        "Staff only. Revoke every staff token now and go back to your own organization.",
+      ],
+    ],
   },
   {
     command: "complete",

package/src/run.test.ts

@@ -1,9 +1,10 @@
 import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import { CredentialStore } from "./auth/store";
+import { WorkosError } from "./auth/workos";
 import { ALL_COMMANDS } from "./commands";
 import { readEnv, saveConfig } from "./config";
 import { renderReference } from "./reference";
@@ -420,6 +421,225 @@ describe("workflow pull with a filter", () => {
   });
 });
 
+describe("staff access", () => {
+  const own = { workosId: "org_OWN", id: "uuid-own", name: "Asteroid" };
+  const signIn = jwt({ exp: Date.now() / 1000 + 300, org_id: "org_OWN" });
+  const minted = {
+    token: "staff-token-1",
+    grantId: "grant-1",
+    organizationId: "uuid-acme",
+    organizationName: "Acme",
+    workosOrganizationId: "org_ACME",
+    reason: "SUP-412",
+    expiresAt: new Date(Date.now() + 8 * 3600_000).toISOString(),
+  };
+
+  async function signedIn(
+    respond: (call: Call) => Response,
+    email = "ed@asteroid.ai",
+  ) {
+    const h = harness({}, respond);
+    h.deps.env.workosApiUrl = "https://workos.test";
+    const store = new CredentialStore(h.deps.env);
+    await store.writeLogin({ refreshToken: "r1", email });
+    store.cacheToken("org_OWN", {
+      accessToken: signIn,
+      expiresAt: Date.now() + 300_000,
+    });
+    saveConfig(h.deps.env, { org: own, orgs: [own] });
+    return { ...h, store };
+  }
+
+  const auth = (call: Call) =>
+    (call.init.headers as Record<string, string>).Authorization;
+  const config = (dir: string) =>
+    JSON.parse(readFileSync(join(dir, "config.json"), "utf8"));
+
+  it("mints a token with the sign-in, then acts in the org with it", async () => {
+    const h = await signedIn((call) => {
+      if (call.url.endsWith("/users/v2/staff-tokens")) return json(minted, 201);
+      return json({ id: "w1", name: "New" }, 201);
+    });
+
+    expect(await run(["use", "uuid-acme", "--reason", "SUP-412"], h.deps)).toBe(
+      0,
+    );
+    const mint = h.calls[0];
+    expect(mint.init.method).toBe("POST");
+    expect(auth(mint)).toBe(`Bearer ${signIn}`);
+    expect(JSON.parse(String(mint.init.body))).toEqual({
+      organization: "uuid-acme",
+      reason: "SUP-412",
+    });
+    expect(h.err.join("")).toContain("Staff access to Acme (uuid-acme)");
+    expect(h.err.join("")).toContain("audited");
+    expect(config(h.configDir).org).toEqual({
+      workosId: "org_ACME",
+      id: "uuid-acme",
+      name: "Acme",
+    });
+    expect(config(h.configDir).orgs).toEqual([own]);
+
+    expect(await run(["workflow", "create", "--name", "New"], h.deps)).toBe(0);
+    expect(auth(h.calls.at(-1)!)).toBe("Bearer staff-token-1");
+    expect(h.err.join("")).toContain(
+      "Acting in Acme (uuid-acme) with staff access (SUP-412).",
+    );
+  });
+
+  it("asks for a reason before it mints anything", async () => {
+    const h = await signedIn(() => json(minted, 201));
+    expect(await run(["use", "uuid-acme"], h.deps)).toBe(2);
+    expect(h.err.join("")).toContain("--reason <why>");
+    expect(h.calls).toHaveLength(0);
+  });
+
+  it("shows a customer no staff hint", async () => {
+    const h = await signedIn(
+      (call) =>
+        json(
+          {
+            error: "organization_membership_not_found",
+            error_description: "not a member",
+          },
+          400,
+        ),
+      "pat@customer.com",
+    );
+    expect(await run(["use", "uuid-acme"], h.deps)).toBe(2);
+    expect(await run(["use", "org_ACME"], h.deps)).toBe(2);
+    expect(await run(["workflow", "list", "--org", "nope"], h.deps)).toBe(1);
+    const err = h.err.join("");
+    expect(err).toContain("you are not a member of org_ACME.");
+    expect(err).toContain("unknown organization nope.");
+    expect(err).not.toMatch(/staff|--reason|audited/);
+    expect(h.calls.some((c) => c.url.includes("staff-tokens"))).toBe(false);
+  });
+
+  it("takes the staff path when the refresh says you are not a member", async () => {
+    const h = await signedIn((call) => {
+      if (call.url.includes("workos"))
+        return json(
+          {
+            error: "organization_membership_not_found",
+            error_description: "not a member",
+          },
+          400,
+        );
+      return json(minted, 201);
+    });
+    expect(await run(["use", "org_ACME"], h.deps)).toBe(2);
+    expect(h.err.join("")).toContain("you are not a member of org_ACME");
+
+    expect(await run(["use", "org_ACME", "--reason", "SUP-412"], h.deps)).toBe(
+      0,
+    );
+    expect(h.calls.at(-1)!.url).toContain("/users/v2/staff-tokens");
+  });
+
+  it("tells a non-staff person that staff access is for staff", async () => {
+    const h = await signedIn(() => json({ error: "forbidden" }, 403));
+    expect(await run(["use", "uuid-acme", "--reason", "x"], h.deps)).toBe(1);
+    expect(h.err.join("")).toContain("staff access is for Asteroid staff only");
+    expect(await h.store.staffTokens()).toEqual([]);
+  });
+
+  it("uses a held staff token for one command with --org", async () => {
+    const h = await signedIn(() => json({ items: [] }));
+    await h.store.saveStaffToken({
+      ...minted,
+      org: { workosId: "org_ACME", id: "uuid-acme", name: "Acme" },
+      expiresAt: Date.now() + 3600_000,
+    });
+    expect(await run(["workflow", "list", "--org", "Acme"], h.deps)).toBe(0);
+    expect(auth(h.calls[0])).toBe("Bearer staff-token-1");
+    expect(await run(["workflow", "list"], h.deps)).toBe(0);
+    expect(auth(h.calls[1])).toBe(`Bearer ${signIn}`);
+  });
+
+  // resolveAuth treats a token within 30 s of its expiry as expired.
+  it("refuses a staff token in its last 30 s and says how to renew it", async () => {
+    const h = await signedIn(() => json({ items: [] }));
+    await h.store.saveStaffToken({
+      ...minted,
+      org: { workosId: "org_ACME", id: "uuid-acme", name: "Acme" },
+      expiresAt: Date.now() + 10_000,
+    });
+    expect(await run(["workflow", "list", "--org", "org_ACME"], h.deps)).toBe(
+      1,
+    );
+    expect(h.err.join("")).toContain("has expired");
+    expect(h.calls).toHaveLength(0);
+  });
+
+  it("revokes every staff token on --exit and goes back to your org", async () => {
+    const h = await signedIn((call) => {
+      if (call.url.endsWith("/users/v2/staff-tokens")) return json(minted, 201);
+      return new Response(null, { status: 204 });
+    });
+    expect(await run(["use", "uuid-acme", "--reason", "SUP-412"], h.deps)).toBe(
+      0,
+    );
+
+    expect(await run(["use", "--exit"], h.deps)).toBe(0);
+    const revoke = h.calls.at(-1)!;
+    expect(revoke.init.method).toBe("DELETE");
+    expect(revoke.url).toBe(
+      "https://odyssey.asteroid.ai/users/v2/staff-tokens/grant-1",
+    );
+    expect(auth(revoke)).toBe(`Bearer ${signIn}`);
+    expect(await h.store.staffTokens()).toEqual([]);
+    expect(config(h.configDir).org).toEqual(own);
+    expect(h.err.join("")).toContain("Now using Asteroid (uuid-own)");
+  });
+
+  it("keeps a staff token on --exit when the revoke fails", async () => {
+    const h = await signedIn(() => json({ message: "down" }, 500));
+    await h.store.saveStaffToken({
+      ...minted,
+      org: { workosId: "org_ACME", id: "uuid-acme", name: "Acme" },
+      expiresAt: Date.now() + 3600_000,
+    });
+    expect(await run(["use", "--exit"], h.deps)).toBe(1);
+    expect(await h.store.staffTokens()).toHaveLength(1);
+    expect(h.err.join("")).toContain("Run `asteroid use --exit` again");
+  });
+
+  it("revokes a minted token it could not save", async () => {
+    const h = await signedIn((call) => {
+      if (call.url.endsWith("/users/v2/staff-tokens")) return json(minted, 201);
+      return new Response(null, { status: 204 });
+    });
+    const save = vi
+      .spyOn(CredentialStore.prototype, "saveStaffToken")
+      .mockRejectedValue(new WorkosError("keychain", "keychain locked"));
+    try {
+      expect(
+        await run(["use", "uuid-acme", "--reason", "SUP-412"], h.deps),
+      ).toBe(1);
+    } finally {
+      save.mockRestore();
+    }
+    const revoke = h.calls.at(-1)!;
+    expect(revoke.init.method).toBe("DELETE");
+    expect(revoke.url).toContain("/users/v2/staff-tokens/grant-1");
+  });
+
+  it("refuses an option as the reason", async () => {
+    const h = await signedIn(() => json(minted, 201));
+    expect(await run(["use", "uuid-acme", "--reason", "--exit"], h.deps)).toBe(
+      2,
+    );
+    expect(h.calls).toHaveLength(0);
+  });
+
+  it("rejects an org with --exit", async () => {
+    const h = await signedIn(() => json({}));
+    expect(await run(["use", "uuid-acme", "--exit"], h.deps)).toBe(2);
+    expect(h.calls).toHaveLength(0);
+  });
+});
+
 describe("reference", () => {
   it("matches the generated agent-docs page", () => {
     const page = readFileSync(

package/src/run.ts

@@ -62,7 +62,10 @@ async function runBuiltin(
         "run `asteroid complete <shell>` to print a completion script",
       );
     case "use":
-      return use(deps, parsed.positionals[0]);
+      return use(deps, parsed.positionals[0], {
+        reason: parsed.flags.get("reason")?.[0],
+        exit: parsed.flags.has("exit"),
+      });
     default:
       return whoami(deps, parsed.org, parsed.json);
   }
@@ -103,7 +106,10 @@ function announce(command: CliCommand, auth: Auth, deps: Deps) {
       : auth.org
         ? orgLabel(auth.org)
         : "your default organization";
-  deps.stderr(`Acting in ${org}.\n`);
+  const staff = auth.staff
+    ? ` with staff access (${clean(auth.staff.reason)})`
+    : "";
+  deps.stderr(`Acting in ${org}${staff}.\n`);
 }
 
 async function runCommand(

package/src/ui.ts

@@ -7,6 +7,7 @@ export interface Choice {
 
 export interface Ui {
   select(message: string, choices: Choice[]): Promise<string | undefined>;
+  text(message: string): Promise<string | undefined>;
   wait<T>(message: string, done: string, work: Promise<T>): Promise<T>;
 }
 
@@ -15,6 +16,10 @@ export const clackUi: Ui = {
     const value = await clack.select({ message, options: choices });
     return clack.isCancel(value) ? undefined : value;
   },
+  async text(message) {
+    const value = await clack.text({ message });
+    return clack.isCancel(value) ? undefined : value;
+  },
   async wait(message, done, work) {
     const spinner = clack.spinner();
     spinner.start(message);