fix(oauth): durable generation-bound refresh intent prevents Anthropic stale-lock token replay (#209)

Author: lidge-jun

devlog/_plan/260722_issue_bug_sweep/040_merge_readiness_review.md

@@ -37,6 +37,8 @@
 
 ### B2 — #209 Anthropic: stale-lock이 소모된 회전 토큰 재전송 (High)
 
+> **해결됨 (2026-07-22, WP-fix-2)**: `store.ts`에 generation-bound durable refresh-intent 사이드카(`auth.refresh.<provider>.<hash>.lock.json`, 토큰 미저장, atomicWrite 0600) 도입. `refreshAnthropicAccountWithLock`이 `def.refresh` 전에 intent를 durable 기록하고, 진입 시 동일 generation intent가 있으면 재전송하지 않고 신규 Claude 자격 채택 또는 recovery(needsReauth, 소스 무관)로 해소. recovery 시 intent 유지(재진입 replay 차단), ENOENT만 부재로 처리(그 외 read/parse 실패는 uncertain=fail-closed). 회귀: 연속 2회 same-generation refreshCalls=0, corrupt-sidecar refreshCalls=0(둘 다 수정 전 RED). 리뷰어 2라운드(FAIL 2건→PASS). xAI 비회귀. oauth 45 pass, tsc 0.
+
 - 위치: `src/oauth/index.ts:320` 인접 + 락 프리미티브 `src/oauth/store.ts:79-85`.
 - 트리거: Anthropic이 회전 토큰을 소모한 뒤 `mergeAccountCredential` persist 전에 프로세스 종료/120s 락 stale.
 - 영향: 이후 프로세스가 stale 락 제거 후 옛 토큰 재제출 → invalid_grant로 영구 needsReauth, 이슈 재현·no-blind-replay 위반.

src/oauth/index.ts

@@ -3,7 +3,7 @@ import { parseCallbackInput } from "./callback-server";
 import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
 import { loadConfig, resolveEnvValue, saveConfig } from "../config";
 import { maskEmail } from "../lib/privacy";
-import { getAccountCredential, getAccountSet, saveAccountCredential, saveCredential, markAccountNeedsReauth, getCredential, credentialGeneration, createOAuthRefreshIntentLock, mergeAccountCredential, markAccountNeedsReauthIfGeneration } from "./store";
+import { getAccountCredential, getAccountSet, saveAccountCredential, saveCredential, markAccountNeedsReauth, getCredential, credentialGeneration, createOAuthRefreshIntentLock, mergeAccountCredential, markAccountNeedsReauthIfGeneration, readOAuthRefreshIntent, writeOAuthRefreshIntent, clearOAuthRefreshIntent } from "./store";
 import { loginXai, refreshXaiToken, XAI_LOCAL_CLI_DETACH_WARNING, XaiTokenRequestError } from "./xai";
 import { ANTHROPIC_OAUTH_BETA, AnthropicTokenError, loginAnthropic, refreshAnthropicToken } from "./anthropic";
 import { loginKimi, refreshKimiToken } from "./kimi";
@@ -296,40 +296,52 @@ export async function refreshAnthropicAccountWithLock(
     const stored = getAccountCredential(provider, accountId);
     if (!stored) throw new OAuthLoginRequiredError(provider);
     const account = getAccountSet(provider)?.accounts.find(candidate => candidate.id === accountId);
+    const generation = credentialGeneration(stored);
+    const pendingIntent = readOAuthRefreshIntent(provider, accountId);
     const disk = newerClaudeCredential(stored, now());
     if (disk) {
       const outcome = await mergeAccountCredential(provider, accountId, disk, {
         expectedGeneration: credentialGeneration(stored),
         afterPrePersistRead: deps.afterPrePersistRead,
       });
       if (outcome.superseded) {
+        if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
         if (outcome.stored.expires > now() + REFRESH_SKEW_MS) return outcome.stored.access;
         throw new OAuthLoginRequiredError(provider);
       }
+      if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
       return disk.access;
     }
-    if (account?.needsReauth && stored.source === "local-cli") {
+    if (pendingIntent?.uncertain || pendingIntent?.generation === generation) {
+      await markAccountNeedsReauthIfGeneration(provider, accountId, generation);
+      throw new OAuthLoginRequiredError(provider);
+    }
+    if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
+    if (account?.needsReauth) {
       throw new OAuthLoginRequiredError(provider);
     }
     if (credentialGeneration(stored) !== credentialGeneration(callerCredential) && stored.expires > now() + REFRESH_SKEW_MS) {
       return stored.access;
     }
 
-    const generation = credentialGeneration(stored);
     try {
+      writeOAuthRefreshIntent(provider, accountId, generation, now());
       const fresh = merged(await def.refresh(stored.refresh), stored);
       const outcome = await mergeAccountCredential(provider, accountId, fresh, {
         expectedGeneration: generation,
         afterPrePersistRead: deps.afterPrePersistRead,
       });
       if (outcome.superseded) {
+        clearOAuthRefreshIntent(provider, accountId, generation);
         if (outcome.stored.expires > now() + REFRESH_SKEW_MS) return outcome.stored.access;
         throw new OAuthLoginRequiredError(provider);
       }
+      clearOAuthRefreshIntent(provider, accountId, generation);
       return fresh.access;
     } catch (error) {
       if (!terminal(error)) throw error;
       await markAccountNeedsReauthIfGeneration(provider, accountId, generation);
+      clearOAuthRefreshIntent(provider, accountId, generation);
       throw new OAuthLoginRequiredError(provider);
     }
   } finally {

src/oauth/store.ts

@@ -36,6 +36,38 @@ export function getAuthRefreshIntentLockPath(provider: string, accountId: string
   const accountHash = createHash("sha256").update(accountId).digest("hex").slice(0, 24);
   return join(getConfigDir(), `auth.refresh.${safeProvider}.${accountHash}.lock`);
 }
+export function getAuthRefreshIntentPath(provider: string, accountId: string): string {
+  return `${getAuthRefreshIntentLockPath(provider, accountId)}.json`;
+}
+export interface OAuthRefreshIntent { version: 1; provider: string; accountId: string; generation: string; createdAt: number; uncertain?: true }
+export function readOAuthRefreshIntent(provider: string, accountId: string): OAuthRefreshIntent | undefined {
+  const path = getAuthRefreshIntentPath(provider, accountId);
+  try {
+    hardenConfigDir();
+    hardenExistingSecret(path);
+    const value = JSON.parse(readFileSync(path, "utf8")) as Partial<OAuthRefreshIntent>;
+    if (value.version !== 1 || value.provider !== provider || value.accountId !== accountId || typeof value.generation !== "string" || typeof value.createdAt !== "number") {
+      return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
+    }
+    return value as OAuthRefreshIntent;
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    return { version: 1, provider, accountId, generation: "", createdAt: 0, uncertain: true };
+  }
+}
+export function writeOAuthRefreshIntent(provider: string, accountId: string, generation: string, createdAt = Date.now()): void {
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  hardenConfigDir();
+  const intent: OAuthRefreshIntent = { version: 1, provider, accountId, generation, createdAt };
+  atomicWriteFile(getAuthRefreshIntentPath(provider, accountId), `${JSON.stringify(intent)}\n`);
+}
+export function clearOAuthRefreshIntent(provider: string, accountId: string, generation: string): boolean {
+  const current = readOAuthRefreshIntent(provider, accountId);
+  if (!current || current.generation !== generation) return false;
+  try { unlinkSync(getAuthRefreshIntentPath(provider, accountId)); return true; }
+  catch (error) { if (errorCode(error) === "ENOENT") return false; throw error; }
+}
 export function credentialGeneration(cred: OAuthCredentials): string {
   return createHash("sha256").update(JSON.stringify([cred.refresh, cred.access, cred.expires])).digest("hex");
 }

tests/oauth-refresh.test.ts

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { getValidAccessToken, OAuthLoginRequiredError, OAUTH_PROVIDERS, refreshAnthropicAccountWithLock } from "../src/oauth";
 import { AnthropicTokenError } from "../src/oauth/anthropic";
-import { getAccountCredential, getAccountSet, getCredential, markAccountNeedsReauth, saveCredential } from "../src/oauth/store";
+import { credentialGeneration, getAccountCredential, getAccountSet, getAuthRefreshIntentPath, getCredential, markAccountNeedsReauth, readOAuthRefreshIntent, saveCredential, writeOAuthRefreshIntent } from "../src/oauth/store";
 
 const origHome = process.env.HOME;
 const origOcxHome = process.env.OPENCODEX_HOME;
@@ -271,14 +271,14 @@ describe("oauth refresh hardening", () => {
   });
 
   test("Anthropic transient failures do not mark needsReauth", async () => {
-    await saveCredential("anthropic", { access: "old", refresh: "rt-old", expires: 1, accountId: "acct" });
-    const id = getAccountSet("anthropic")!.activeAccountId;
-    for (const error of [
+    for (const [index, error] of [
       new AnthropicTokenError("server", 503, undefined),
       new AnthropicTokenError("timeout", undefined, undefined),
-    ]) {
+    ].entries()) {
+      await saveCredential("anthropic", { access: `old-${index}`, refresh: `rt-old-${index}`, expires: 1, accountId: `acct-${index}` });
+      const id = getAccountSet("anthropic")!.activeAccountId;
       await expect(refreshAnthropicAccountWithLock("anthropic", id, { ...OAUTH_PROVIDERS.anthropic!, refresh: async () => { throw error; } }, getAccountCredential("anthropic", id)!)).rejects.toBe(error);
-      expect(getAccountSet("anthropic")!.accounts[0]!.needsReauth).toBeUndefined();
+      expect(getAccountSet("anthropic")!.accounts.find(account => account.id === id)!.needsReauth).toBeUndefined();
     }
   });
 
@@ -290,6 +290,83 @@ describe("oauth refresh hardening", () => {
     expect(getAccountSet("anthropic")!.accounts[0]!.needsReauth).toBe(true);
   });
 
+  test("Anthropic never replays an outstanding oauth-source generation across re-entry", async () => {
+    await saveCredential("anthropic", { access: "old", refresh: "rt-consumed", expires: 1, accountId: "acct" });
+    const id = getAccountSet("anthropic")!.activeAccountId;
+    const credential = getAccountCredential("anthropic", id)!;
+    writeOAuthRefreshIntent("anthropic", id, credentialGeneration(credential), Date.now() - 120_001);
+    let refreshCalls = 0;
+
+    const attempt = () => refreshAnthropicAccountWithLock("anthropic", id, {
+      ...OAUTH_PROVIDERS.anthropic!,
+      refresh: async () => { refreshCalls++; throw new Error("must not replay"); },
+    }, credential);
+
+    await expect(attempt()).rejects.toBeInstanceOf(OAuthLoginRequiredError);
+    await expect(attempt()).rejects.toBeInstanceOf(OAuthLoginRequiredError);
+
+    expect(refreshCalls).toBe(0);
+    expect(getAccountSet("anthropic")!.accounts[0]!.needsReauth).toBe(true);
+    expect(readOAuthRefreshIntent("anthropic", id)?.generation).toBe(credentialGeneration(credential));
+  });
+
+  test("Anthropic treats a corrupt durable intent as outstanding and never refreshes", async () => {
+    await saveCredential("anthropic", { access: "old", refresh: "rt-consumed", expires: 1, accountId: "acct" });
+    const id = getAccountSet("anthropic")!.activeAccountId;
+    const credential = getAccountCredential("anthropic", id)!;
+    writeFileSync(getAuthRefreshIntentPath("anthropic", id), "not-json");
+    let refreshCalls = 0;
+
+    await expect(refreshAnthropicAccountWithLock("anthropic", id, {
+      ...OAUTH_PROVIDERS.anthropic!,
+      refresh: async () => { refreshCalls++; throw new Error("must not replay"); },
+    }, credential)).rejects.toBeInstanceOf(OAuthLoginRequiredError);
+
+    expect(refreshCalls).toBe(0);
+    expect(readOAuthRefreshIntent("anthropic", id)?.uncertain).toBe(true);
+  });
+
+  test("Anthropic outstanding intent adopts a newer Claude credential without replay", async () => {
+    await saveCredential("anthropic", { access: "old", refresh: "rt-consumed", expires: 1, source: "local-cli" });
+    const id = getAccountSet("anthropic")!.activeAccountId;
+    const credential = getAccountCredential("anthropic", id)!;
+    writeOAuthRefreshIntent("anthropic", id, credentialGeneration(credential));
+    seedClaudeCredentials("disk", "rt-new", Date.now() + 3600_000);
+    let refreshCalls = 0;
+
+    await expect(refreshAnthropicAccountWithLock("anthropic", id, {
+      ...OAUTH_PROVIDERS.anthropic!,
+      refresh: async () => { refreshCalls++; throw new Error("must not replay"); },
+    }, credential)).resolves.toBe("disk");
+
+    expect(refreshCalls).toBe(0);
+    expect(getAccountCredential("anthropic", id)?.refresh).toBe("rt-new");
+    expect(readOAuthRefreshIntent("anthropic", id)).toBeUndefined();
+  });
+
+  test("Anthropic successful refresh clears its intent and the new generation can refresh", async () => {
+    await saveCredential("anthropic", { access: "old", refresh: "rt-old", expires: 1, accountId: "acct" });
+    const id = getAccountSet("anthropic")!.activeAccountId;
+    const calls: string[] = [];
+    const def = {
+      ...OAUTH_PROVIDERS.anthropic!,
+      refresh: async (refresh: string) => {
+        calls.push(refresh);
+        return calls.length === 1
+          ? { access: "fresh-1", refresh: "rt-new-1", expires: 1 }
+          : { access: "fresh-2", refresh: "rt-new-2", expires: Date.now() + 3600_000 };
+      },
+    };
+
+    await expect(refreshAnthropicAccountWithLock("anthropic", id, def, getAccountCredential("anthropic", id)!)).resolves.toBe("fresh-1");
+    expect(readOAuthRefreshIntent("anthropic", id)).toBeUndefined();
+    await expect(refreshAnthropicAccountWithLock("anthropic", id, def, getAccountCredential("anthropic", id)!)).resolves.toBe("fresh-2");
+
+    expect(calls).toEqual(["rt-old", "rt-new-1"]);
+    expect(getAccountCredential("anthropic", id)?.refresh).toBe("rt-new-2");
+    expect(readOAuthRefreshIntent("anthropic", id)).toBeUndefined();
+  });
+
   test("Anthropic late terminal failure does not mark a superseding generation", async () => {
     await saveCredential("anthropic", { access: "old", refresh: "rt-old", expires: 1, accountId: "acct" });
     const id = getAccountSet("anthropic")!.activeAccountId;