Context7 Platform -- Up-to-date docs for AI agents
CTX7-3308: fix(cli): lock the token refresh so concurrent commands keep the session (#3495)
Ramazan Onur Acarb6ad942ce06f
diff --git a/.changeset/cli-refresh-lock.md b/.changeset/cli-refresh-lock.mdnew file mode 100644index 00000000..57cb2201--- /dev/null+++ b/.changeset/cli-refresh-lock.md@@ -0,0 +1,5 @@+---+"ctx7": patch+---++Keep you signed in when several ctx7 commands run at once on an expired session. Each command used to refresh the token on its own, and two refreshes with the same token made the server revoke the whole session. Refreshes now take a lock file next to the credentials file: the first command refreshes and writes the new credentials, and the others wait for it and read them. A running command keeps its lock fresh, so a slow refresh is waited for, while a lock left behind by a crashed command is ignored after ten seconds and no command hangs on it. If the lock cannot be taken, for example on a read-only home directory, the command refreshes as before.diff --git a/packages/cli/src/__tests__/auth-utils.test.ts b/packages/cli/src/__tests__/auth-utils.test.tsindex b9b60756..a96df7a0 100644--- a/packages/cli/src/__tests__/auth-utils.test.ts+++ b/packages/cli/src/__tests__/auth-utils.test.ts@@ -9,6 +9,10 @@ vi.mock("fs", () => {unlinkSync: vi.fn(),renameSync: vi.fn(),chmodSync: vi.fn(),+ openSync: vi.fn(),+ closeSync: vi.fn(),+ statSync: vi.fn(),+ utimesSync: vi.fn(),};return { ...fns, default: fns };});@@ -31,6 +35,7 @@ import {clearTokens,isTokenExpired,getValidAccessToken,+ getRefreshLockPath,startDeviceAuthorization,pollDeviceToken,type TokenData,@@ -40,6 +45,7 @@ const mfs = vi.mocked(fs);const CREDENTIALS_PATH = "/fake-home/.config/context7/credentials.json";const LEGACY_CREDENTIALS_PATH = "/fake-home/.context7/credentials.json";const CONFIG_DIR_PATH = "/fake-home/.config/context7";+const REFRESH_LOCK_PATH = "/fake-home/.config/context7/credentials.json.lock";beforeEach(() => {vi.clearAllMocks();@@ -590,7 +596,7 @@ describe("getValidAccessToken when the refresh token is rejected", () => {expect(await getValidAccessToken()).toBeUndefined();expect(files.get(CREDENTIALS_PATH)).toBe(JSON.stringify(EXPIRED));- expect(mfs.unlinkSync).not.toHaveBeenCalled();+ expect(mfs.unlinkSync).not.toHaveBeenCalledWith(CREDENTIALS_PATH);expect(mockConfirm).not.toHaveBeenCalled();expect(errorSpy).not.toHaveBeenCalled();});@@ -613,6 +619,169 @@ describe("getValidAccessToken when the refresh token is rejected", () => {});});+// Agents run several ctx7 commands at once. Two refreshes with the same token+// make the authorization server revoke the whole grant, so refreshes are+// serialised across processes with a lock file next to the credentials.+describe("getValidAccessToken refresh lock", () => {+ const EXPIRED: TokenData = {+ access_token: "expired-tok",+ token_type: "bearer",+ expires_at: 1,+ refresh_token: "refresh-tok",+ };+ const REFRESHED = { access_token: "new-tok", token_type: "bearer", expires_in: 3600 };++ let files: Map<string, string>;+ let mtimes: Map<string, number>;++ function fsError(code: string): NodeJS.ErrnoException {+ return Object.assign(new Error(code), { code });+ }++ function sleep(ms: number): Promise<void> {+ return new Promise((resolve) => setTimeout(resolve, ms));+ }++ /** A refresh that takes long enough for the other commands to contend. */+ function stubSlowRefresh(ms: number): ReturnType<typeof vi.fn> {+ const fetchMock = vi.fn(async () => {+ await sleep(ms);+ return { ok: true, json: () => Promise.resolve(REFRESHED) };+ });+ vi.stubGlobal("fetch", fetchMock);+ return fetchMock;+ }++ function placeLock(ageMs: number): void {+ files.set(REFRESH_LOCK_PATH, "");+ mtimes.set(REFRESH_LOCK_PATH, Date.now() - ageMs);+ }++ beforeEach(() => {+ // Earlier tests may leave Date.now pinned; lock ages need a real clock.+ vi.restoreAllMocks();+ files = new Map([[CREDENTIALS_PATH, JSON.stringify(EXPIRED)]]);+ mtimes = new Map();++ mfs.existsSync.mockImplementation((p) => files.has(String(p)) || p === CONFIG_DIR_PATH);+ mfs.readFileSync.mockImplementation((p) => files.get(String(p)) ?? "");+ mfs.writeFileSync.mockImplementation((p, data) => void files.set(String(p), String(data)));+ mfs.unlinkSync.mockImplementation((p) => {+ if (!files.delete(String(p))) throw fsError("ENOENT");+ });+ // O_EXCL semantics: creating an existing file fails.+ mfs.openSync.mockImplementation((p, flags) => {+ if (String(flags).includes("x") && files.has(String(p))) throw fsError("EEXIST");+ files.set(String(p), "");+ mtimes.set(String(p), Date.now());+ return 3;+ });+ mfs.statSync.mockImplementation((p) => {+ if (!files.has(String(p))) throw fsError("ENOENT");+ return { mtimeMs: mtimes.get(String(p)) ?? Date.now() } as fs.Stats;+ });+ });++ test("lock file lives next to the credentials file", () => {+ expect(getRefreshLockPath()).toBe(REFRESH_LOCK_PATH);+ });++ test("5 parallel commands on an expired token make 1 refresh request and all sign in", async () => {+ const fetchMock = stubSlowRefresh(30);++ const results = await Promise.all(Array.from({ length: 5 }, () => getValidAccessToken()));++ expect(results).toEqual(Array(5).fill("new-tok"));+ expect(fetchMock).toHaveBeenCalledTimes(1);+ expect(JSON.parse(files.get(CREDENTIALS_PATH)!).access_token).toBe("new-tok");+ expect(files.has(REFRESH_LOCK_PATH)).toBe(false);+ });++ test("waits for another process's lock, then uses the credentials it wrote", async () => {+ const fetchMock = stubSlowRefresh(0);+ placeLock(0);+ // The holder finishes shortly: it writes fresh credentials and releases.+ setTimeout(() => {+ files.set(+ CREDENTIALS_PATH,+ JSON.stringify({ ...REFRESHED, expires_at: Date.now() + 3_600_000, refresh_token: "r2" })+ );+ files.delete(REFRESH_LOCK_PATH);+ }, 40);++ expect(await getValidAccessToken()).toBe("new-tok");+ expect(fetchMock).not.toHaveBeenCalled();+ expect(files.has(REFRESH_LOCK_PATH)).toBe(false);+ });++ test("a stale lock from a crashed process does not block the next command", async () => {+ const fetchMock = stubSlowRefresh(0);+ placeLock(60_000);++ const started = Date.now();+ expect(await getValidAccessToken()).toBe("new-tok");++ expect(fetchMock).toHaveBeenCalledTimes(1);+ expect(files.has(REFRESH_LOCK_PATH)).toBe(false);+ expect(Date.now() - started).toBeLessThan(1_000);+ });++ test.each(["EACCES", "EROFS", "EPERM", "ENOSYS"])(+ "refreshes as before when the lock cannot be taken (%s)",+ async (code) => {+ const fetchMock = stubSlowRefresh(0);+ mfs.openSync.mockImplementation(() => {+ throw fsError(code);+ });++ expect(await getValidAccessToken()).toBe("new-tok");++ expect(fetchMock).toHaveBeenCalledTimes(1);+ expect(JSON.parse(files.get(CREDENTIALS_PATH)!).access_token).toBe("new-tok");+ }+ );++ test("releases the lock when the refresh fails", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn().mockResolvedValue({+ ok: false,+ status: 503,+ url: "https://test.context7.com/api/oauth/token",+ text: () => Promise.resolve(""),+ })+ );++ expect(await getValidAccessToken()).toBeUndefined();+ expect(files.has(REFRESH_LOCK_PATH)).toBe(false);+ // Transient: credentials kept for the next command.+ expect(files.has(CREDENTIALS_PATH)).toBe(true);+ });++ test("a waiter does not prompt again after the holder's token was rejected", async () => {+ const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});+ Object.defineProperty(process.stdin, "isTTY", { value: false, configurable: true });+ const fetchMock = vi.fn(async () => {+ await sleep(30);+ return {+ ok: false,+ status: 400,+ url: "https://test.context7.com/api/oauth/token",+ text: () => Promise.resolve(JSON.stringify({ error: "invalid_grant" })),+ };+ });+ vi.stubGlobal("fetch", fetchMock);++ const results = await Promise.all([getValidAccessToken(), getValidAccessToken()]);++ expect(results).toEqual([undefined, undefined]);+ expect(fetchMock).toHaveBeenCalledTimes(1);+ expect(files.has(CREDENTIALS_PATH)).toBe(false);+ expect(errorSpy).toHaveBeenCalledTimes(1);+ expect(mockConfirm).not.toHaveBeenCalled();+ });+});+describe("startDeviceAuthorization", () => {test("returns parsed response on 200", async () => {const payload = {diff --git a/packages/cli/src/__tests__/file-lock.test.ts b/packages/cli/src/__tests__/file-lock.test.tsnew file mode 100644index 00000000..dad05420--- /dev/null+++ b/packages/cli/src/__tests__/file-lock.test.ts@@ -0,0 +1,140 @@+import { describe, test, expect, beforeEach, afterEach } from "vitest";+import * as fs from "fs";+import * as os from "os";+import * as path from "path";+import { acquireFileLock } from "../utils/file-lock.js";++// Real filesystem: the lock's whole point is cross-process atomicity, which a+// mocked fs cannot show.+let dir: string;+let lockPath: string;++function sleep(ms: number): Promise<void> {+ return new Promise((resolve) => setTimeout(resolve, ms));+}++function ageLock(ageMs: number): void {+ const then = new Date(Date.now() - ageMs);+ fs.utimesSync(lockPath, then, then);+}++beforeEach(() => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), "ctx7-lock-"));+ lockPath = path.join(dir, "credentials.json.lock");+});++afterEach(() => {+ fs.rmSync(dir, { recursive: true, force: true });+});++describe("acquireFileLock", () => {+ test("creates the lock file and release removes it", async () => {+ const release = await acquireFileLock(lockPath);+ expect(release).not.toBeNull();+ expect(fs.existsSync(lockPath)).toBe(true);+ release!();+ expect(fs.existsSync(lockPath)).toBe(false);+ });++ test("release is safe when the lock file is already gone", async () => {+ const release = await acquireFileLock(lockPath);+ fs.unlinkSync(lockPath);+ expect(() => release!()).not.toThrow();+ });++ test("concurrent acquirers take turns and never overlap", async () => {+ const held: Array<[number, number]> = [];+ await Promise.all(+ Array.from({ length: 5 }, async () => {+ const release = await acquireFileLock(lockPath, { pollMs: 5 });+ const from = Date.now();+ await sleep(15);+ held.push([from, Date.now()]);+ release!();+ })+ );++ held.sort((a, b) => a[0] - b[0]);+ for (let i = 1; i < held.length; i++) {+ expect(held[i][0]).toBeGreaterThanOrEqual(held[i - 1][1]);+ }+ expect(fs.existsSync(lockPath)).toBe(false);+ });++ test("a lock left by a crashed process is broken once it is stale", async () => {+ fs.writeFileSync(lockPath, "");+ ageLock(60_000);++ const started = Date.now();+ const release = await acquireFileLock(lockPath, { staleMs: 1_000, pollMs: 5 });++ expect(release).not.toBeNull();+ expect(Date.now() - started).toBeLessThan(500);+ release!();+ });++ test("a fresh lock is waited for, not broken", async () => {+ fs.writeFileSync(lockPath, "");+ setTimeout(() => fs.unlinkSync(lockPath), 60);++ const started = Date.now();+ const release = await acquireFileLock(lockPath, { staleMs: 1_000, pollMs: 5 });++ expect(Date.now() - started).toBeGreaterThanOrEqual(50);+ release!();+ });++ // A refresh through a slow proxy can outlast the stale window. If a waiter+ // broke the lock then, it would refresh with a token the holder has already+ // sent, which is the very reuse the lock exists to prevent.+ test("a slow holder keeps its lock past staleMs", async () => {+ const staleMs = 90;+ const holder = await acquireFileLock(lockPath, { staleMs });+ const holderInode = fs.statSync(lockPath).ino;++ let waiterGotLockAt: number | undefined;+ const waiter = acquireFileLock(lockPath, { staleMs, pollMs: 5 }).then((release) => {+ waiterGotLockAt = Date.now();+ return release;+ });++ // Hold for several stale windows.+ await sleep(staleMs * 4);+ expect(waiterGotLockAt).toBeUndefined();+ // Still our file: the waiter did not replace it with its own.+ expect(fs.statSync(lockPath).ino).toBe(holderInode);++ const releasedAt = Date.now();+ holder!();+ const release = await waiter;+ expect(waiterGotLockAt).toBeGreaterThanOrEqual(releasedAt);+ release!();+ });++ test("the heartbeat stops at release", async () => {+ const release = await acquireFileLock(lockPath, { staleMs: 30 });+ release!();+ fs.writeFileSync(lockPath, "");+ const then = new Date(Date.now() - 5_000);+ fs.utimesSync(lockPath, then, then);++ await sleep(60);+ // A live heartbeat would have touched the file we recreated.+ expect(fs.statSync(lockPath).mtimeMs).toBeLessThan(Date.now() - 4_000);+ });++ test("returns null when the lock cannot be created", async () => {+ const missingDir = path.join(dir, "missing", "credentials.json.lock");+ expect(await acquireFileLock(missingDir)).toBeNull();+ });++ test("returns null when the directory is not writable", async () => {+ if (process.platform === "win32" || process.getuid?.() === 0) return;+ fs.chmodSync(dir, 0o500);+ try {+ expect(await acquireFileLock(lockPath)).toBeNull();+ } finally {+ fs.chmodSync(dir, 0o700);+ }+ });+});diff --git a/packages/cli/src/utils/auth.ts b/packages/cli/src/utils/auth.tsindex d6cbf50b..b5345d4b 100644--- a/packages/cli/src/utils/auth.ts+++ b/packages/cli/src/utils/auth.ts@@ -4,6 +4,7 @@ import pc from "picocolors";import { confirm } from "@inquirer/prompts";import { CLI_CLIENT_ID } from "../constants.js";import { getBaseUrl } from "./api.js";+import { acquireFileLock, type ReleaseLock } from "./file-lock.js";import {CREDENTIALS_FILE_NAME,getConfigDir,@@ -195,12 +196,75 @@ interface GetValidAccessTokenOptions {recoverExpiredSession?: boolean;}+/**+ * Lock file taken around a token refresh so concurrent ctx7 processes do not+ * refresh with the same token. Lives next to the credentials file so it is+ * on the same filesystem and under the same permissions.+ */+export function getRefreshLockPath(): string {+ return `${getCredentialsFilePath()}.lock`;+}++/**+ * Best-effort: resolves to `null` when the lock cannot be taken (read-only+ * home directory, unsupported filesystem), and the caller refreshes unlocked+ * as the CLI always has.+ */+async function acquireRefreshLock(): Promise<ReleaseLock | null> {+ try {+ ensureConfigDir();+ return await acquireFileLock(getRefreshLockPath());+ } catch {+ return null;+ }+}++/** The server definitively rejected the refresh token; credentials cleared. */+const REFRESH_REJECTED = Symbol("refresh-rejected");++/**+ * Refreshes with `refreshToken` and stores the result. Resolves to the new+ * access token, `undefined` after a transient failure (credentials kept so+ * the next command retries), or REFRESH_REJECTED after a definitive rejection+ * (credentials cleared).+ */+async function refreshAndStore(+ refreshToken: string+): Promise<string | undefined | typeof REFRESH_REJECTED> {+ try {+ const newTokens = await refreshAccessToken(refreshToken);+ // RFC 6749 §6: the response MAY omit refresh_token, and the client then+ // keeps the one it already holds. Writing the response verbatim would+ // drop it and log the user out at the next expiry.+ saveTokens({ refresh_token: refreshToken, ...newTokens });+ return newTokens.access_token;+ } catch (error) {+ if (!(error instanceof RefreshTokenRejectedError)) return undefined;+ // Without the lock (see acquireRefreshLock), a concurrent ctx7 process may+ // have refreshed first, rotating the token we sent. Its credentials are+ // valid; clearing them would log the user out.+ const current = loadTokens();+ if (current && current.refresh_token !== refreshToken) {+ return isTokenExpired(current) ? undefined : current.access_token;+ }+ clearTokens();+ return REFRESH_REJECTED;+ }+}+/*** Returns a valid access token, refreshing if expired. Returns undefined if no* tokens are stored or refresh fails. Pre-0.5 installs may have OAuth tokens* with a `refresh_token`; new installs hold long-lived API keys that never* expire and skip the refresh path entirely.*+ * Agents often run several ctx7 commands at once. If two of them refresh with+ * the same token, the authorization server sees the old refresh token used+ * twice and revokes the whole grant, including the new token, so the user is+ * logged out. Refreshes are therefore serialised across processes with a file+ * lock: the first to take it refreshes and writes the credentials; the others+ * wait, then read what it wrote and do not refresh again.+ ** A transient refresh failure (network, 429, 5xx) keeps the credentials so the* next command retries. A definitive rejection clears them, so the user is* told at most once per expired session.@@ -219,29 +283,30 @@ export async function getValidAccessToken(return undefined;}+ let result: string | undefined | typeof REFRESH_REJECTED;+ const release = await acquireRefreshLock();try {- const newTokens = await refreshAccessToken(tokens.refresh_token);- // RFC 6749 §6: the response MAY omit refresh_token, and the client then- // keeps the one it already holds. Writing the response verbatim would- // drop it and log the user out at the next expiry.- saveTokens({ refresh_token: tokens.refresh_token, ...newTokens });- return newTokens.access_token;- } catch (error) {- if (!(error instanceof RefreshTokenRejectedError)) return undefined;- // A concurrent ctx7 process may have refreshed first, rotating the token we- // sent. Its credentials are valid; clearing them would log the user out.- const current = loadTokens();- if (current && current.refresh_token !== tokens.refresh_token) {- return isTokenExpired(current) ? undefined : current.access_token;- }- clearTokens();- // CONTEXT7_API_KEY takes precedence over stored tokens in every request- // (getAuthHeaders), so the user is still signed in; don't claim otherwise.- if (options.recoverExpiredSession === false || process.env.CONTEXT7_API_KEY) {- return undefined;- }- return recoverExpiredSession();+ // Another process may have refreshed (or been rejected and cleared the+ // credentials) in the meantime, whether or not we got the lock. Re-read+ // before deciding, so we never send a refresh token that is already used.+ const latest = loadTokens();+ if (!latest) return undefined;+ if (!isTokenExpired(latest)) return latest.access_token;+ if (!latest.refresh_token) return undefined;+ result = await refreshAndStore(latest.refresh_token);+ } finally {+ // Released before any sign-in prompt so waiting commands never block on+ // the user's answer.+ release?.();+ }++ if (result !== REFRESH_REJECTED) return result;+ // CONTEXT7_API_KEY takes precedence over stored tokens in every request+ // (getAuthHeaders), so the user is still signed in; don't claim otherwise.+ if (options.recoverExpiredSession === false || process.env.CONTEXT7_API_KEY) {+ return undefined;}+ return recoverExpiredSession();}interface TokenErrorResponse {diff --git a/packages/cli/src/utils/file-lock.ts b/packages/cli/src/utils/file-lock.tsnew file mode 100644index 00000000..637d4c03--- /dev/null+++ b/packages/cli/src/utils/file-lock.ts@@ -0,0 +1,108 @@+import * as fs from "fs";++/** Releases the lock. Safe to call if the lock file is already gone. */+export type ReleaseLock = () => void;++export interface FileLockOptions {+ /**+ * A lock file not touched for this long is treated as left behind by a+ * process that died without releasing it, and is removed so no command+ * hangs on it. A live holder touches its lock well within this window.+ */+ staleMs?: number;+ /** Delay between attempts while another process holds the lock. */+ pollMs?: number;+}++export const DEFAULT_LOCK_STALE_MS = 10_000;+const DEFAULT_LOCK_POLL_MS = 50;++function errorCode(error: unknown): string | undefined {+ if (typeof error !== "object" || error === null || !("code" in error)) return undefined;+ const code = (error as { code: unknown }).code;+ return typeof code === "string" ? code : undefined;+}++function sleep(ms: number): Promise<void> {+ return new Promise((resolve) => setTimeout(resolve, ms));+}++/**+ * Cross-process mutex backed by a lock file created with `O_EXCL`, which is+ * atomic on every filesystem Node supports. The file's existence is the lock;+ * the descriptor is closed right away so the holder's death leaves nothing+ * open and the stale check can clean up after it.+ *+ * While held, the lock's mtime is touched every `staleMs / 3` so that only a+ * dead holder's lock ever looks stale. A holder that is merely slow (a token+ * request through a proxy, a cold server) keeps the lock, and waiters keep+ * waiting; breaking it would let them repeat the work the holder is in the+ * middle of. The wait is therefore bounded by the holder's lifetime plus+ * `staleMs`, never by a fixed deadline.+ *+ * Resolves to a release function once the lock is held, or to `null` when the+ * lock cannot be taken at all (read-only directory, unsupported filesystem).+ * Callers fall back to running unlocked rather than failing.+ */+export async function acquireFileLock(+ lockPath: string,+ options: FileLockOptions = {}+): Promise<ReleaseLock | null> {+ const staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_MS;+ const pollMs = options.pollMs ?? DEFAULT_LOCK_POLL_MS;++ for (;;) {+ try {+ fs.closeSync(fs.openSync(lockPath, "wx", 0o600));+ return holdLock(lockPath, staleMs);+ } catch (error) {+ if (errorCode(error) !== "EEXIST") return null;+ }++ let mtimeMs: number;+ try {+ mtimeMs = fs.statSync(lockPath).mtimeMs;+ } catch (error) {+ // Released between our open and stat: try again at once.+ if (errorCode(error) === "ENOENT") continue;+ return null;+ }++ if (Date.now() - mtimeMs > staleMs) {+ try {+ fs.unlinkSync(lockPath);+ } catch (error) {+ if (errorCode(error) !== "ENOENT") return null;+ }+ continue;+ }++ await sleep(pollMs);+ }+}++function holdLock(lockPath: string, staleMs: number): ReleaseLock {+ const heartbeat = setInterval(+ () => {+ try {+ const now = new Date();+ fs.utimesSync(lockPath, now, now);+ } catch {+ // The lock is gone (broken as stale on a frozen machine, or the+ // directory was removed). Nothing to keep fresh; release copes.+ }+ },+ Math.max(1, Math.floor(staleMs / 3))+ );+ // Never keep the process alive just to touch the lock.+ heartbeat.unref();++ return () => {+ clearInterval(heartbeat);+ try {+ fs.unlinkSync(lockPath);+ } catch {+ // Already removed; nothing to do.+ }+ };+}