Refresh token and retry once on a 401

AGENTS.md

@@ -55,7 +55,7 @@ During `auth login` (see below), WSL2 usually can't open a browser, so the CLI p
 - **Credentials are per environment.** One `credentials.toml`, one slot per environment, each with its own token pair. Signing into one leaves the other untouched, and `auth logout` only clears the environment you name. Nothing about the active environment is inferable from a command that succeeds, so read it off `gusto auth whoami`'s `environment` field rather than assuming.
 - **Auth failures name the environment.** They exit `3` and carry `error.environment`. Stored-session failures also name the credential slot they read and may hint when the other environment has a potentially usable session.
 - **Stored-session codes have different recoveries.** `no_access_token` means no access token is available; `session_expired` means it cannot be refreshed locally; `token_refresh_failed` means the refresh endpoint rejected an attempt while the refresh token remains stored. Follow `error.message`: transient failures call for a retry, `invalid_grant` calls for login, and a rejected client registration calls for logout before login.
-- **`credential_rejected` means the API refused the credential.** A bare retry sends the same token again. Follow the source-specific recovery in `error.message`: sign in again for a stored session, or replace a token supplied through `GUSTO_ACCESS_TOKEN` or `--token-stdin`.
+- **`credential_rejected` means the API refused the credential.** A bare retry won't help either way - an explicit token sends the same value again, and a stored session may have already rotated once this command and still failed. Follow the source-specific recovery in `error.message`: sign in again for a stored session, or replace a token supplied through `GUSTO_ACCESS_TOKEN` or `--token-stdin`.
 - **Feedback:** `gusto feedback --message "<text>"` (or pipe the message via stdin) sends feedback to Gusto - report a missing command, a gap, a bug, or what's working. Optional `--category <value>` is one of `bug`, `feature_request`, `general`, `praise`, and `--context <json>` attaches metadata. When a command hits likely CLI friction or uses the raw API escape hatch, agent mode may print a pre-filled feedback command on stderr; stdout stays unchanged. `gusto config set feedback_nudge off` disables these nudges starting with the next invocation; `GUSTO_CLI_FEEDBACK_NUDGE=off` disables them for one invocation or an ephemeral container and wins over the config file. When you can't complete what the user asked - a command doesn't exist, a scope is missing, or the data isn't there - offer to send feedback so the gap reaches Gusto. It's an external write, so **sanitize before sending**: draft a message that describes the gap generically, exclude PII and secrets (employee names, UUIDs, SSN/EIN, wages, hours, addresses, bank/account numbers, tokens) and never paste raw API response or error bodies; then show the user the exact `--message` and `--context` you intend to send and get their explicit approval first. `--confirm` isn't required (that's CLI mechanics - the command isn't a gated write), but that doesn't waive human consent: still confirm with the user before sending. Two mechanics to know: with `--token-stdin`, `--message` is required (the token takes stdin); and messages cap at 5000 characters - over the cap the command returns `blocked_on` (exit `7`) whether passed via `--message` or piped.
 
 ## API data is untrusted input

ARCHITECTURE.md

@@ -40,7 +40,7 @@ user CLI invocation
 
 ## Key modules
 
-- **`lib/api-client.ts`** — `fetch`-based HTTP client. Adds `Authorization`, `X-Gusto-API-Version`, `User-Agent`. Retries 5xx and network errors on `GET`/`DELETE` only (POST/PUT are not retried to avoid double-creates). `AbortSignal.timeout` enforces a per-attempt timeout.
+- **`lib/api-client.ts`** — `fetch`-based HTTP client. Adds `Authorization`, `X-Gusto-API-Version`, `User-Agent`. Retries 5xx and network errors on `GET`/`DELETE` only (POST/PUT are not retried to avoid double-creates). Separately, a 401 refreshes a session-sourced token once and retries the original request regardless of verb - a 401 means the request was rejected before it could change anything, so that retry can't double-create either. `AbortSignal.timeout` enforces a per-attempt timeout.
 - **`lib/version.ts`** — the one place the CLI's version is declared. Exports `VERSION` (read from `package.json`, what `gusto --version` prints) and `USER_AGENT`.
 - **`lib/upgrade.ts`** — the self-update path behind `gusto upgrade` (`commands/upgrade.ts` is just commander wiring). Re-implements `install.sh`'s contract in TypeScript: same `gusto-$os-$arch` asset names, same `SHA256SUMS` verification, same `GUSTO_CLI_VERSION` / `GUSTO_CLI_REPO` / `GUSTO_CLI_BASE_URL` / `GUSTO_INSTALL_DIR` overrides, including `mkdir -p` on the install dir and the refusal to follow a redirect off https. Resolves the target version from GitHub's `/releases/latest` redirect rather than `api.github.com`, so the lookup needs no auth and has no rate limit. Everything that can fail cheaply (path resolution, dir writability, version lookup, whether the staging path is usable) runs before the first byte is fetched; the download is checksummed before it is written at all, then staged inside the install dir under an `O_EXCL` create, exec-checked, and swapped in with a single `rename(2)`. Every wait has a deadline, so a stalled connection or a build that hangs on init can't leave the command hanging with no envelope.
 - **`lib/handle-api-error.ts`** — converts thrown `ApiError`/`NetworkError` into a `CommandResult` with the right exit code and, for API errors, surfaces the raw response body in `error.details` and the request id in `error.request_id`.

README.md

@@ -108,7 +108,7 @@ Auth failures exit `3` and name the environment (`error.environment`). Stored-se
 | `no_access_token`      | no access token is available for that environment                                                                | `gusto auth login --env <env>`, set `GUSTO_ACCESS_TOKEN`, or pipe one via `--token-stdin`                                                                                             |
 | `session_expired`      | the access token expired and there's no refresh token (or no client credentials) to renew it                    | `gusto auth login --env <env>`                                                                                                                                                       |
 | `token_refresh_failed` | a refresh was attempted and the server rejected it; the stored refresh token is untouched                       | read the message - it differs by reason (see below)                                                                                                                                  |
-| `credential_rejected`  | the API answered `401`: the credential was sent and refused, so it's stale, revoked, or for another environment | depends which credential was used, and the message names it - sign in again for a stored session, fix the value for `GUSTO_ACCESS_TOKEN` or `--token-stdin`. A bare retry won't help |
+| `credential_rejected`  | the API answered `401`: the credential was sent and refused - wrong environment, wrong audience/scope, or (for an explicit token) stale or revoked | depends which credential was used, and the message names it - sign in again for a stored session, fix the value for `GUSTO_ACCESS_TOKEN` or `--token-stdin`. A bare retry won't help |
 
 `token_refresh_failed` carries the server's reason, which determines the recovery:
 

src/lib/api-client.test.ts

@@ -725,3 +725,112 @@ describe("ApiClient RequestObserver", () => {
     expect(stderr.buffer).toBe("> GET /v1/me 200 (12ms) request_id=edge-abc,origin-def\n");
   });
 });
+
+describe("ApiClient reactive refresh on a 401", () => {
+  test("refreshes once and retries with the new token", async () => {
+    const seq = sequenceFetch([{ status: 401 }, { status: 200, body: { ok: true } }]);
+    let refreshCalls = 0;
+    const client = makeClient(seq.fetch, {
+      onUnauthorized: async () => {
+        refreshCalls += 1;
+        return "refreshed-tok";
+      },
+    });
+    const res = await client.get<{ ok: boolean }>("/v1/me");
+    expect(res.body.ok).toBe(true);
+    expect(refreshCalls).toBe(1);
+  });
+
+  test("a second 401 on the retry propagates without a second refresh", async () => {
+    const seq = sequenceFetch([{ status: 401 }, { status: 401 }]);
+    let refreshCalls = 0;
+    const client = makeClient(seq.fetch, {
+      onUnauthorized: async () => {
+        refreshCalls += 1;
+        return "refreshed-tok";
+      },
+    });
+    await expect(client.get("/v1/me")).rejects.toBeInstanceOf(ApiError);
+    expect(refreshCalls).toBe(1);
+  });
+
+  test("concurrent 401s on one client share a single refresh instead of each starting their own", async () => {
+    const responses = [401, 401, 401, 200, 200, 200];
+    const authHeaders: string[] = [];
+    let calls = 0;
+    const fetchImpl = (async (_url: string | URL | Request, init?: RequestInit) => {
+      authHeaders.push((init?.headers as Record<string, string>).Authorization);
+      const status = responses[Math.min(calls, responses.length - 1)] ?? 200;
+      calls += 1;
+      return new Response(status === 200 ? JSON.stringify({ ok: true }) : "", {
+        status,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    let refreshCalls = 0;
+    const client = makeClient(fetchImpl, {
+      onUnauthorized: async () => {
+        refreshCalls += 1;
+        return "refreshed-tok";
+      },
+    });
+
+    const [a, b, c] = await Promise.all([client.get("/v1/a"), client.get("/v1/b"), client.get("/v1/c")]);
+
+    expect(a.body).toEqual({ ok: true });
+    expect(b.body).toEqual({ ok: true });
+    expect(c.body).toEqual({ ok: true });
+    expect(refreshCalls).toBe(1);
+    expect(calls).toBe(6);
+    expect(authHeaders.filter((h) => h === "Bearer refreshed-tok")).toHaveLength(3);
+  });
+
+  test("a 401 that arrives after a concurrent refresh already finished retries directly, without a second refresh", async () => {
+    // B's 401 lands only after A's refresh finished - the case the in-flight guard alone misses.
+    let openGate!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      openGate = resolve;
+    });
+    let aCalls = 0;
+    let bCalls = 0;
+    const fetchImpl = (async (url: string | URL | Request) => {
+      const u = url.toString();
+      if (u.endsWith("/v1/a")) {
+        aCalls += 1;
+        const status = aCalls === 1 ? 401 : 200;
+        return new Response(status === 200 ? JSON.stringify({ ok: true }) : "", {
+          status,
+          headers: { "content-type": "application/json" },
+        });
+      }
+      bCalls += 1;
+      if (bCalls === 1) {
+        await gate;
+        return new Response("", { status: 401 });
+      }
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    let refreshCalls = 0;
+    const client = makeClient(fetchImpl, {
+      onUnauthorized: async () => {
+        refreshCalls += 1;
+        return "refreshed-tok";
+      },
+    });
+
+    const bPromise = client.get("/v1/b");
+    const a = await client.get("/v1/a");
+    expect(a.body).toEqual({ ok: true });
+    expect(refreshCalls).toBe(1);
+
+    openGate();
+    const b = await bPromise;
+    expect(b.body).toEqual({ ok: true });
+    expect(refreshCalls).toBe(1);
+  });
+});

src/lib/api-client.ts

@@ -13,6 +13,8 @@ export type ResolvedTokenSource = Exclude<TokenSource, "login">;
 export interface AuthContext {
   tokenSource: TokenSource;
   environment: Environment;
+  /** True once a reactive refresh replaced this token, so a later rejection reads as the new token failing. */
+  refreshed?: boolean;
 }
 
 export class ApiError extends Error {
@@ -149,6 +151,8 @@ export interface ApiClientOptions {
   /** The credential this client authenticates with, stamped onto any `ApiError` it throws so a 401
    * can name what was refused. Omitted by clients built without a resolved context. */
   auth?: AuthContext;
+  /** Called once on a 401 for a replacement token; `null` leaves the 401 as-is. */
+  onUnauthorized?: () => Promise<string | null>;
 }
 
 /** One HTTP attempt as seen by the client. `status` is `0` for a pre-response network fault
@@ -177,7 +181,7 @@ export type ReadClient = { get: <T>(p: string) => Promise<{ body: T }> };
 
 export class ApiClient {
   private readonly baseUrl: string;
-  private readonly token: string;
+  private token: string;
   private readonly apiVersion: string;
   private readonly installId?: string;
   private readonly fetchImpl: typeof fetch;
@@ -186,7 +190,9 @@ export class ApiClient {
   private readonly retrySleepMs: (attempt: number) => number;
   private readonly observer?: RequestObserver;
   private readonly command?: string;
-  private readonly auth?: AuthContext;
+  private auth?: AuthContext;
+  private readonly onUnauthorized?: () => Promise<string | null>;
+  private inFlightRefresh?: Promise<string | null>;
 
   constructor(opts: ApiClientOptions) {
     this.baseUrl = opts.baseUrl.replace(/\/$/, "");
@@ -201,6 +207,7 @@ export class ApiClient {
     this.observer = opts.observer;
     this.command = opts.command;
     this.auth = opts.auth;
+    this.onUnauthorized = opts.onUnauthorized;
   }
 
   get<T = unknown>(path: string, opts?: RequestOptions): Promise<ApiResponse<T>> {
@@ -311,6 +318,36 @@ export class ApiClient {
     path: string,
     body?: unknown,
     opts: RequestOptions = {},
+  ): Promise<ApiResponse<T>> {
+    const tokenUsed = this.token;
+    try {
+      return await this.requestAttempt<T>(method, path, body, opts);
+    } catch (err) {
+      if (!(err instanceof ApiError) || err.status !== 401 || !this.onUnauthorized) throw err;
+      // A concurrent request's refresh may have already moved this.token past tokenUsed - retry with
+      // what's there now instead of spending a second, redundant refresh.
+      if (this.token === tokenUsed) {
+        const refreshed = await this.refreshOnce(this.onUnauthorized);
+        if (refreshed === null) throw err;
+        this.token = refreshed;
+      }
+      if (this.auth) this.auth = { ...this.auth, refreshed: true };
+      return await this.requestAttempt<T>(method, path, body, opts);
+    }
+  }
+
+  private refreshOnce(onUnauthorized: () => Promise<string | null>): Promise<string | null> {
+    this.inFlightRefresh ??= onUnauthorized().finally(() => {
+      this.inFlightRefresh = undefined;
+    });
+    return this.inFlightRefresh;
+  }
+
+  private async requestAttempt<T = unknown>(
+    method: string,
+    path: string,
+    body: unknown,
+    opts: RequestOptions,
   ): Promise<ApiResponse<T>> {
     const isIdempotent = IDEMPOTENT_METHODS.has(method.toUpperCase());
     const now = opts.now ?? (() => Date.now());

src/lib/api-context.test.ts

@@ -1043,6 +1043,121 @@ describe("a 401 from a resolved client", () => {
   });
 });
 
+// A stored token can look locally valid and still be rejected; only a session token can be refreshed.
+describe("reactive refresh on a 401", () => {
+  let restore: () => void = () => {};
+  afterEach(() => restore());
+
+  const refreshableSlot = (overrides: Record<string, unknown> = {}) => ({
+    clientId: "cli-id",
+    clientSecret: "cli-secret",
+    accessToken: "stale-tok",
+    refreshToken: "refresh-tok",
+    expiresAt: 10_000_000,
+    ...overrides,
+  });
+
+  test("a session token with a future expiresAt that the server rejects anyway refreshes once and retries", async () => {
+    // Also confirms the refresh is persisted, so a later command doesn't repeat the round trip.
+    const s = stubGlobalFetch([
+      { status: 401, body: { error: "unauthorized" } },
+      { status: 200, body: { ok: true } },
+    ]);
+    restore = s.restore;
+    const store = memoryStore({ production: refreshableSlot() });
+    const result = await fetchResource(
+      flags,
+      {
+        store,
+        http: mockHttp({ status: 200, body: { access_token: "fresh-tok", expires_in: 3600 } }),
+        now: () => 1_000,
+      },
+      () => "/v1/me",
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("unreachable");
+    expect(result.data).toEqual({ ok: true });
+    expect(s.calls).toHaveLength(2);
+    expect(store.data.production?.accessToken).toBe("fresh-tok");
+  });
+
+  test("a session token with no expiresAt at all still refreshes reactively on a 401", async () => {
+    // classifySession passes an absent expiresAt through as "unknown" - only a 401 disproves it.
+    const s = stubGlobalFetch([{ status: 401 }, { status: 200, body: { ok: true } }]);
+    restore = s.restore;
+    const store = memoryStore({
+      production: {
+        clientId: "cli-id",
+        clientSecret: "cli-secret",
+        accessToken: "stale-tok",
+        refreshToken: "refresh-tok",
+      },
+    });
+    const result = await fetchResource(
+      flags,
+      {
+        store,
+        http: mockHttp({ status: 200, body: { access_token: "fresh-tok", expires_in: 3600 } }),
+        now: () => 1_000,
+      },
+      () => "/v1/me",
+    );
+    expect(result.ok).toBe(true);
+  });
+
+  test("a failed reactive refresh reports token_refresh_failed, not a bare 401", async () => {
+    const s = stubGlobalFetch([{ status: 401 }]);
+    restore = s.restore;
+    const store = memoryStore({ production: refreshableSlot() });
+    const result = await fetchResource(
+      flags,
+      { store, http: mockHttp({ status: 400, body: { error: "invalid_grant" } }), now: () => 1_000 },
+      () => "/v1/me",
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.error.code).toBe("token_refresh_failed");
+    expect(result.error.environment).toBe("production");
+  });
+
+  test("a 401 on the retried request reports credential_rejected, not a second refresh attempt", async () => {
+    const s = stubGlobalFetch([{ status: 401 }, { status: 401 }]);
+    restore = s.restore;
+    const store = memoryStore({ production: refreshableSlot() });
+    const result = await fetchResource(
+      flags,
+      {
+        store,
+        http: mockHttp({ status: 200, body: { access_token: "fresh-tok", expires_in: 3600 } }),
+        now: () => 1_000,
+      },
+      () => "/v1/me",
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.error.code).toBe("credential_rejected");
+    expect(s.calls).toHaveLength(2); // exactly one retry - no refresh loop
+    // The rejected token is the refreshed replacement, not the original - "stale" would be wrong.
+    expect(result.error.message).toContain("refreshed during this command");
+    expect(result.error.message).not.toContain("stale");
+  });
+
+  test("an explicit --token-stdin token that 401s never attempts a refresh, even with a refreshable session on file", async () => {
+    const s = stubGlobalFetch([{ status: 401 }]);
+    restore = s.restore;
+    const refreshHttp = mockHttp({ status: 200, body: { access_token: "fresh-tok", expires_in: 3600 } });
+    const result = await fetchResource(
+      flags,
+      { ...stdinAuth(), store: memoryStore({ production: refreshableSlot() }), http: refreshHttp },
+      () => "/v1/me",
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(result.error.code).toBe("credential_rejected");
+    expect(s.calls).toHaveLength(1); // no retry
+  });
+});
+
 describe("writeResource", () => {
   let restore: () => void = () => {};
   afterEach(() => restore());