@modelprofile.com/authswitch 3.3.0 → 4.0.0

package/ts/classes.claudecodeharness.ts

@@ -1,8 +1,11 @@
 import * as plugins from './plugins.js';
 import { FileHarness, type IFileAccount, type IFileHarnessSnapshot } from './classes.fileharness.js';
-import { CredentialStore, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw } from './classes.credentialstore.js';
+import { CredentialStore, credentialHash, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw } from './classes.credentialstore.js';
 import { HarnessProcesses } from './classes.harnessprocesses.js';
 import { ClaudeAccountStatus } from './classes.claudestatus.js';
+import { ClaudeCodeLocks } from './classes.claudecodelocks.js';
+import { ClaudeTokenRefresh, type IClaudeTokens } from './classes.claudetokenrefresh.js';
+import { CLAUDE_LOGIN_REJECTED, ClaudeLoginRejectedError, ClaudeRateLimitError } from './claudehttp.js';
 import { writeSecretFileAtomically } from './helpers.js';
 import type { IHarnessAccountStatus, IHarnessProcessControl, IHarnessStatusOptions } from './interfaces.harness.js';
 
@@ -17,15 +20,31 @@ export interface IClaudeCodeHarnessOptions {
   processes?: IHarnessProcessControl;
   /** Local settings sources to inspect for credential overrides, in increasing precedence. */
   settingsFiles?: string[];
+  /** How long a credential change waits for a lock Claude Code holds; 15 seconds by default. */
+  lockTimeoutMs?: number;
+  /** The clock that decides when a saved login's access token is due for a refresh; `Date.now` by default. */
+  now?: () => number;
 }
 
 const accountCaches = ['additionalModelOptionsCache', 'additionalModelOptionsAnsweredAt', 'additionalModelCostsCache', 'modelAccessCache', 'orgModelDefaultCache', 'lastSeenOrgDefaultUpdatedAt', 'clientDataCache', 'clientDataCacheSlots', 'autoCompactWindowsCache', 'cachedUsageUtilization'];
 
-/** File-backed Claude Code subscriber login and its matching global oauthAccount metadata. */
+/**
+ * File-backed Claude Code subscriber login and its matching global oauthAccount metadata.
+ *
+ * A running Claude Code (verified against 2.1.273) re-reads its credential file whenever the file's mtime changes,
+ * before every request, and watches `.claude.json`, so a swap is picked up live without a restart. Every native read
+ * and write therefore runs under Claude Code's own locks instead of asking for it to be stopped.
+ *
+ * Nothing else refreshes a saved login, so its access token expires a few hours after it was saved. Reading such a
+ * login's status refreshes it first, the way Claude Code would; the active login's tokens belong to Claude Code.
+ */
 export class ClaudeCodeHarness extends FileHarness {
   public readonly id = 'claude';
   public readonly label = 'Claude Code';
   public readonly loginHint = 'Log in using claude auth login, then authswitch claude stash --keep; Claude Code may stay running.';
+  public readonly liveSwap = true;
+  public readonly autoSwitch = true;
+  public readonly renewalUnavailableReason = "renewal dates are not exposed by Claude's account API.";
   protected readonly store: CredentialStore;
   private readonly file: string;
   private readonly configFile: string;
@@ -34,6 +53,16 @@ export class ClaudeCodeHarness extends FileHarness {
   private readonly status: ClaudeAccountStatus;
   public readonly processes: IHarnessProcessControl;
   private readonly settingsFiles: string[];
+  private readonly locks: ClaudeCodeLocks;
+  private readonly tokens: ClaudeTokenRefresh;
+  /**
+   * The refresh token the service rejected, per account: a hash, never the token itself.
+   *
+   * A rejected grant stays rejected until a new Claude Code login replaces the saved record, so replaying it would
+   * only add traffic to an auth endpoint -- once every tick of a watch, for as long as it runs. The entry is
+   * superseded as soon as the record holds a different refresh token.
+   */
+  private readonly rejectedGrants = new Map<string, string>();
 
   constructor(options: IClaudeCodeHarnessOptions = {}) {
     super();
@@ -44,10 +73,16 @@ export class ClaudeCodeHarness extends FileHarness {
     this.configFile = options.globalConfigFile ?? plugins.path.join(custom || plugins.os.homedir(), '.claude.json');
     this.store = new CredentialStore(this.id, options.stashRoot);
     this.platform = options.platform ?? process.platform;
-    this.status = new ClaudeAccountStatus(options.fetch);
+    this.status = new ClaudeAccountStatus(options.fetch, options.now);
+    this.tokens = new ClaudeTokenRefresh(options.fetch, options.now);
     this.processes = options.processes ?? new HarnessProcesses('claude', { platform: this.platform });
     this.settingsFiles = options.settingsFiles ?? [plugins.path.join(dir, 'settings.json'),
       plugins.path.join(process.cwd(), '.claude/settings.json'), plugins.path.join(process.cwd(), '.claude/settings.local.json')];
+    this.locks = new ClaudeCodeLocks(dir, this.configFile, { timeoutMs: options.lockTimeoutMs });
+  }
+  /** A login this adapter cannot manage has no Claude Code file to lock; the action itself reports why. */
+  protected nativeTransaction(actionArg: () => string[]): Promise<string[]> {
+    return this.unavailableReason() === null ? this.locks.hold(actionArg) : super.nativeTransaction(actionArg);
   }
   /** One record holds the credential and its matching metadata, so both files must be proven stable. */
   protected nativeSources(): (string | null)[] { return [readCredentialRaw(this.file), readCredentialRaw(this.configFile)]; }
@@ -59,8 +94,9 @@ export class ClaudeCodeHarness extends FileHarness {
       || !credentialText(account.accountUuid) || !credentialText(account.organizationUuid) || !credentialText(account.emailAddress)) throw new Error('Claude Code login or its matching account metadata is incomplete. Log in again with Claude Code before saving.');
     return { slotId, identity: JSON.stringify([account.accountUuid, account.organizationUuid]), label: String(account.emailAddress).toLowerCase(), credential };
   }
-  protected snapshot(): IFileHarnessSnapshot {
-    if (this.platform === 'darwin') return { accounts: [], unavailable: 'Claude Code uses the macOS Keychain. This adapter supports file credentials on Linux and Windows; Keychain switching is unavailable.' };
+  /** Why this installation's login is not a subscriber file login this adapter can manage; null when it is. */
+  private unavailableReason(): string | null {
+    if (this.platform === 'darwin') return 'Claude Code uses the macOS Keychain. This adapter supports file credentials on Linux and Windows; Keychain switching is unavailable.';
     const overrides = ['CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_PROFILE', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'ANTHROPIC_BASE_URL'];
     const settings: Record<string, unknown> = {};
     const environment: Record<string, unknown> = { ...this.env };
@@ -69,7 +105,12 @@ export class ClaudeCodeHarness extends FileHarness {
       Object.assign(settings, data);
       if (data.env != null) Object.assign(environment, credentialRecord(data.env));
     }
-    if (overrides.some(key => environment[key]) || credentialText(settings.apiKeyHelper)) return { accounts: [], unavailable: 'Claude Code has a settings or environment credential/provider override. Remove it before managing subscriber file logins.' };
+    return overrides.some(key => environment[key]) || credentialText(settings.apiKeyHelper)
+      ? 'Claude Code has a settings or environment credential/provider override. Remove it before managing subscriber file logins.' : null;
+  }
+  protected snapshot(): IFileHarnessSnapshot {
+    const unavailable = this.unavailableReason();
+    if (unavailable !== null) return { accounts: [], unavailable };
     const data = readCredentialDocument(this.file).data;
     if (data.claudeAiOauth == null) return { accounts: [], unavailable: null };
     const config = readCredentialDocument(this.configFile).data;
@@ -90,7 +131,7 @@ export class ClaudeCodeHarness extends FileHarness {
     for (const key of accountCaches) delete nextConfig[key];
     const raw = JSON.stringify(next, null, 2) + '\n';
     const configRaw = JSON.stringify(nextConfig, null, 2) + '\n';
-    if (readCredentialDocument(this.file).raw !== original.raw || readCredentialDocument(this.configFile).raw !== config.raw) throw new Error('Claude Code files changed during the operation; try again after Claude Code exits.');
+    if (readCredentialDocument(this.file).raw !== original.raw || readCredentialDocument(this.configFile).raw !== config.raw) throw new Error('Claude Code files changed during the operation; no credential was replaced. Try again.');
     plugins.fs.mkdirSync(plugins.path.dirname(this.file), { recursive: true, mode: 0o700 });
     plugins.fs.mkdirSync(plugins.path.dirname(this.configFile), { recursive: true, mode: 0o700 });
     try {
@@ -103,12 +144,84 @@ export class ClaudeCodeHarness extends FileHarness {
       try {
         if (readCredentialDocument(this.file).raw === raw) writeSecretFileAtomically(this.file, original.raw ?? '{}\n');
         if (readCredentialDocument(this.configFile).raw === configRaw) writeSecretFileAtomically(this.configFile, config.raw ?? '{}\n');
-      } catch { throw new Error('Claude Code switch and rollback were incomplete. Keep Claude Code stopped and restore a verified saved account.'); }
-      throw new Error('Claude Code switch failed while updating account metadata. The outgoing login remains saved; check doctor before restarting.');
+      } catch { throw new Error('Claude Code switch and rollback were incomplete, so its login and account metadata may not match. Activate a verified saved account with authswitch claude use, then check authswitch claude active.'); }
+      throw new Error('Claude Code switch failed while updating account metadata and was rolled back. The outgoing login remains saved; check authswitch claude doctor.');
     }
   }
-  public async readAccountStatus(id: string, optionsArg?: IHarnessStatusOptions): Promise<IHarnessAccountStatus> {
-    const account = this.readCredential(id);
-    return this.status.read(credentialRecord(account.credential.claudeAiOauth), credentialRecord(account.credential.oauthAccount), optionsArg);
+  /** The hash that identifies a saved login's refresh token, so a rejected grant is remembered without keeping it. */
+  private grantKey(oauthArg: Record<string, unknown>): string { return credentialHash(credentialText(oauthArg.refreshToken) ?? ''); }
+
+  /**
+   * What the native files say about this account: its active login, and why they could not be read at all.
+   *
+   * Both answers come from one snapshot, because only their combination proves that a login is *not* the active one.
+   * An installation this adapter cannot read reports no accounts, so the login Claude Code is actually running on
+   * reads as inactive there; anything that would renew a saved login has to refuse instead.
+   */
+  private nativeView(idArg: string): { active: IFileAccount | null; unavailable: string | null } {
+    const snapshot = this.snapshot();
+    return { active: snapshot.accounts.find(account => this.store.id(account.slotId, account.identity) === idArg) ?? null, unavailable: snapshot.unavailable };
+  }
+
+  /**
+   * The account's status. The active login is read as it is: Claude Code refreshes it. A saved login whose access token
+   * is due is refreshed first; when that fails, the status says why and keeps the stored plan, and the saved login is
+   * left exactly as it was.
+   *
+   * A refresh is only ever sent for a login the native files prove is not the active one (`nativeView`), and a grant
+   * the service already rejected is not sent again while the saved record still holds it.
+   */
+  public async readAccountStatus(id: string, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
+    const read = (accountArg: IFileAccount) =>
+      this.status.read(credentialRecord(accountArg.credential.claudeAiOauth), credentialRecord(accountArg.credential.oauthAccount), optionsArg);
+    const view = this.nativeView(id);
+    if (view.active) return read(view.active);
+    const saved = this.savedCredential(id);
+    const oauth = credentialRecord(saved.credential.claudeAiOauth);
+    if (!this.tokens.due(oauth)) return read(saved);
+    if (view.unavailable !== null) {
+      return this.status.unavailable(oauth, `Login refresh: this saved login's access token has expired and cannot be renewed for this installation. ${view.unavailable}`);
+    }
+    if (this.rejectedGrants.get(id) === this.grantKey(oauth)) return this.status.unavailable(oauth, `Login refresh: ${CLAUDE_LOGIN_REJECTED}`);
+    let refreshed: IFileAccount;
+    try { refreshed = await this.refreshSaved(id, optionsArg.signal); }
+    catch (error) {
+      if (optionsArg.signal?.aborted) throw error;
+      return this.status.unavailable(oauth, `Login refresh: ${error instanceof Error ? error.message : 'the saved login could not be refreshed.'}`,
+        error instanceof ClaudeRateLimitError ? { retryAt: error.retryAt } : undefined);
+    }
+    return read(refreshed);
+  }
+
+  /**
+   * A saved login with fresh tokens, refreshed as the only operation on the store: a switch, a save or another refresh
+   * waits for it, so none of them can read or activate a refresh token the service is replacing. Under the lock the
+   * native files are read again, so the decision that this is not the active login is taken where it holds: one that
+   * became active meanwhile belongs to Claude Code and is returned as it is, one in an installation that can no
+   * longer be read is returned unrefreshed, and one another refresh already renewed is not refreshed twice. The new
+   * tokens replace the saved ones only while the record still holds the refresh token that was sent, the
+   * compare-and-swap Claude Code 2.1.273 applies to its own store (`$fn`, @15410824).
+   */
+  private refreshSaved(id: string, signal?: AbortSignal): Promise<IFileAccount> {
+    return this.store.locked(async () => {
+      const view = this.nativeView(id);
+      if (view.active) return view.active;
+      const saved = this.savedCredential(id);
+      const oauth = credentialRecord(saved.credential.claudeAiOauth);
+      if (view.unavailable !== null || !this.tokens.due(oauth)) return saved;
+      signal?.throwIfAborted();
+      let tokens: IClaudeTokens;
+      try { tokens = await this.tokens.refresh(oauth); }
+      catch (error) {
+        // Only this token was rejected; a login saved again replaces it and is tried like any other.
+        if (error instanceof ClaudeLoginRejectedError) this.rejectedGrants.set(id, this.grantKey(oauth));
+        throw error;
+      }
+      const latest = this.savedCredential(id);
+      const latestOauth = credentialRecord(latest.credential.claudeAiOauth);
+      if (latestOauth.refreshToken !== oauth.refreshToken) return latest;
+      this.store.replaceCredential(id, { ...latest.credential, claudeAiOauth: { ...latestOauth, ...tokens } });
+      return this.savedCredential(id);
+    }, { signal });
   }
 }

package/ts/classes.claudecodelocks.ts

@@ -0,0 +1,132 @@
+import * as plugins from './plugins.js';
+import { errorCode } from './helpers.js';
+
+/** One lock Claude Code takes, with the options it takes it with. */
+interface IClaudeCodeLock {
+  /** The path proper-lockfile keys the lock by. */
+  file: string;
+  /** The lock directory. */
+  lockfilePath: string;
+  stale: number;
+  /** Omitted where Claude Code leaves it to proper-lockfile's default of half the stale time. */
+  update?: number;
+  /** Claude Code proceeds without this lock when it fails for any reason other than being held. */
+  bestEffort: boolean;
+}
+
+interface IHeldLock {
+  lockfilePath: string;
+  release: () => Promise<void>;
+}
+
+export interface IClaudeCodeLocksOptions {
+  /** How long an operation waits for a lock that Claude Code holds. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const RETRY_MS = 250;
+
+/**
+ * Claude Code's own locks around its login and global config, taken with its own library and options.
+ *
+ * A running Claude Code picks a swapped credential up on its next request, so a switch no longer waits for it to
+ * stop. What it must not do is interleave with that session's own writes: a token refresh that is in flight when
+ * the credential is swapped leaves the outgoing account's saved copy with a refresh token the server may already
+ * have replaced, and a config save that read `.claude.json` before the swap writes the previous account's
+ * metadata back. Claude Code 2.1.273 serialises those writers with proper-lockfile (see hints.md); this class
+ * takes the same locks, in the order a refresh nests them, waits a bounded time for a held one, and releases them
+ * in reverse order on every path. A lock left behind by a Claude Code that died is stale after its own threshold
+ * and is taken over, exactly as Claude Code itself would.
+ */
+export class ClaudeCodeLocks {
+  private readonly timeoutMs: number;
+
+  constructor(private readonly configDir: string, private readonly configFile: string, optionsArg: IClaudeCodeLocksOptions = {}) {
+    this.timeoutMs = optionsArg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  /** The locks of Claude Code 2.1.273, in acquisition order. */
+  private async locks(): Promise<IClaudeCodeLock[]> {
+    // The OAuth refresh lock's legacy twin is keyed by the resolved directory; Claude Code falls back to the path as given.
+    const resolved = await plugins.fs.promises.realpath(this.configDir).catch(() => this.configDir);
+    const storageWrite = plugins.path.join(this.configDir, '.storage-write');
+    return [
+      { file: this.configDir, lockfilePath: plugins.path.join(this.configDir, '.oauth_refresh.lock'), stale: 60_000, update: 5_000, bestEffort: false },
+      { file: `${resolved}.lock`, lockfilePath: `${resolved}.lock`, stale: 60_000, update: 5_000, bestEffort: true },
+      { file: storageWrite, lockfilePath: `${storageWrite}.lock`, stale: 15_000, bestEffort: false },
+      { file: this.configFile, lockfilePath: `${this.configFile}.lock`, stale: 10_000, bestEffort: false },
+    ];
+  }
+
+  /**
+   * Runs a synchronous read-and-write of the native login while every lock is held.
+   *
+   * A held lock never makes authswitch sit on the others: like Claude Code, it releases what it holds, waits and
+   * starts again, so a live session is never blocked by a switch that is still waiting. A lock that could not be
+   * released afterwards is reported as an outcome line, because the write it guarded has completed and the lock
+   * expires on its own.
+   */
+  public async hold(actionArg: () => string[]): Promise<string[]> {
+    const lockfile = await plugins.loadProperLockfile();
+    const deadline = Date.now() + this.timeoutMs;
+    const held: IHeldLock[] = [];
+    const unreleased: string[] = [];
+    const releaseAll = async (): Promise<void> => {
+      for (const lock of held.splice(0).reverse()) {
+        // A compromised lock is no longer ours to release; the operation already failed for it.
+        try { await lock.release(); } catch (error) { if (errorCode(error) !== 'ERELEASED') unreleased.push(lock.lockfilePath); }
+      }
+    };
+    let outcome: { lines: string[] } | { error: unknown };
+    try {
+      for (const directory of new Set([this.configDir, plugins.path.dirname(this.configFile)])) {
+        plugins.fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+      }
+      const locks = await this.locks();
+      for (;;) {
+        // Each attempt owns its flag, so a late report about a lock released in an earlier attempt changes nothing.
+        const attempt = { compromised: false };
+        const busy = await this.acquireAll(lockfile, locks, held, () => { attempt.compromised = true; });
+        if (busy === null) {
+          if (attempt.compromised) throw new Error('A Claude Code lock was taken over while authswitch took the others; nothing was changed. Try again.');
+          break;
+        }
+        await releaseAll();
+        if (Date.now() >= deadline) {
+          throw new Error(`Claude Code is refreshing or saving its login (${busy.lockfilePath} is held); nothing was changed. Try again in a moment.`);
+        }
+        await new Promise<void>(resolve => { setTimeout(resolve, Math.min(RETRY_MS, Math.max(1, deadline - Date.now()))); });
+      }
+      outcome = { lines: actionArg() };
+    } catch (error) { outcome = { error }; }
+    await releaseAll();
+    const note = unreleased.length ? `Claude Code's lock ${unreleased.join(', ')} could not be released; it expires on its own within a minute.` : null;
+    if ('error' in outcome) {
+      if (note === null) throw outcome.error;
+      throw new Error(`${outcome.error instanceof Error ? outcome.error.message : 'Credential operation failed.'} ${note}`);
+    }
+    return note === null ? outcome.lines : [...outcome.lines, note];
+  }
+
+  /** Takes the locks in order into `heldArg` and returns the first one another process holds, or null once all are held. */
+  private async acquireAll(
+    lockfileArg: plugins.TProperLockfile,
+    locksArg: readonly IClaudeCodeLock[],
+    heldArg: IHeldLock[],
+    onCompromisedArg: (errorArg: Error) => void,
+  ): Promise<IClaudeCodeLock | null> {
+    for (const lock of locksArg) {
+      try {
+        const release = await lockfileArg.lock(lock.file, {
+          lockfilePath: lock.lockfilePath, realpath: false, stale: lock.stale, update: lock.update, onCompromised: onCompromisedArg,
+        });
+        heldArg.push({ lockfilePath: lock.lockfilePath, release });
+      } catch (error) {
+        if (errorCode(error) === 'ELOCKED') return lock;
+        if (!lock.bestEffort) throw new Error(`Claude Code's lock ${lock.lockfilePath} could not be taken (${errorCode(error) ?? 'unknown error'}); nothing was changed.`);
+      }
+    }
+    return null;
+  }
+}

package/ts/classes.claudestatus.ts

@@ -1,8 +1,8 @@
-import { credentialRecord, credentialText } from './classes.credentialstore.js';
+import { credentialHash, credentialRecord, credentialText } from './classes.credentialstore.js';
+import { claudeRequest, ClaudeLoginRejectedError, ClaudeRateLimitError, ClaudeRequestError } from './claudehttp.js';
+import { latestRetryAt } from './ratelimit.js';
 import { plainText } from './formatting.js';
-import type { IHarnessAccountStatus, IHarnessStatusOptions, IHarnessUsageWindow, TUsageSeverity } from './interfaces.harness.js';
-
-class ClaudeStatusError extends Error {}
+import type { IHarnessAccountStatus, IHarnessStatusFact, IHarnessStatusOptions, IHarnessUsageWindow, TUsageSeverity } from './interfaces.harness.js';
 
 interface IClaudeUsageWindows {
   windows: IHarnessUsageWindow[];
@@ -102,66 +102,96 @@ const claudeUsageWindows = (usage: Record<string, unknown>): IClaudeUsageWindows
   return Array.isArray(limits) && limits.length ? limitWindows(limits) : { windows: keyedWindows(usage), unsupported: [] };
 };
 
-/** Read-only Claude Code OAuth account endpoints. No refresh, inference, or browser session is used. */
+/** A profile lookup's answer. Only a lookup that could not be completed is thrown, and so never reused. */
+type TClaudeProfile =
+  | { kind: 'found'; plan: string | undefined; facts: IHarnessStatusFact[] }
+  | { kind: 'mismatch' }
+  | { kind: 'unavailable'; problem: string };
+
+/**
+ * How long a session reuses an account's profile. The watch polls every few minutes, and the profile (plan,
+ * organization, billing type) changes far more rarely, so it is read at most hourly there.
+ */
+const PROFILE_REUSE_MS = 3_600_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+const MISMATCH = 'Claude returned a different account or organization; no account data was displayed.';
+
+/**
+ * Claude Code's read-only OAuth account endpoints: the profile and usage of one login, with the access token it
+ * carries. It never refreshes that token; `ClaudeCodeHarness` refreshes a saved login first, and leaves the active
+ * login's tokens to Claude Code. No inference or browser session is used.
+ */
 export class ClaudeAccountStatus {
-  constructor(private readonly fetcher: typeof fetch = globalThis.fetch) {}
-  private async get(route: 'usage' | 'profile', accessToken: string, cancelArg?: AbortSignal): Promise<Record<string, unknown>> {
-    const timeout = AbortSignal.timeout(10_000);
-    const signal = cancelArg ? AbortSignal.any([cancelArg, timeout]) : timeout;
+  constructor(private readonly fetcher: typeof fetch = globalThis.fetch, private readonly now: () => number = Date.now) {}
+
+  private async get(route: 'usage' | 'profile', accessToken: string, signal?: AbortSignal): Promise<Record<string, unknown>> {
+    const { status, body } = await claudeRequest(this.fetcher, {
+      url: `https://api.anthropic.com/api/oauth/${route}`, method: 'GET', subject: 'Claude account', timeoutMs: REQUEST_TIMEOUT_MS, signal, now: this.now,
+      headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json',
+        ...(route === 'usage' ? { 'anthropic-beta': 'oauth-2025-04-20' } : { 'Cache-Control': 'no-cache' }) },
+    });
+    if (status === 401) throw new ClaudeLoginRejectedError();
+    if (status < 200 || status > 299) throw new ClaudeRequestError(`Claude account service returned HTTP ${status}.`);
+    if (body === null) throw new ClaudeRequestError('The Claude account service returned invalid data.');
+    return body;
+  }
+
+  /** The profile, from the session while it is younger than an hour; the session key is a hash of the token, never the token. */
+  private profile(token: string, account: Record<string, unknown>, optionsArg: IHarnessStatusOptions): Promise<TClaudeProfile> {
+    const lookup = () => this.lookupProfile(token, account, optionsArg.signal);
+    return optionsArg.session ? optionsArg.session.reuse(`claude:profile:${credentialHash(token)}`, PROFILE_REUSE_MS, lookup) : lookup();
+  }
+
+  /** A rejected login and an unsupported or foreign profile are answers; a rate limit or a failed request is thrown. */
+  private async lookupProfile(token: string, account: Record<string, unknown>, signal?: AbortSignal): Promise<TClaudeProfile> {
+    let body: Record<string, unknown>;
+    try { body = await this.get('profile', token, signal); }
+    catch (error) {
+      if (error instanceof ClaudeLoginRejectedError) return { kind: 'unavailable', problem: `Profile: ${error.message}` };
+      throw error;
+    }
     try {
-      const response = await this.fetcher(`https://api.anthropic.com/api/oauth/${route}`, {
-        method: 'GET', redirect: 'error', signal,
-        headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json',
-          ...(route === 'usage' ? { 'anthropic-beta': 'oauth-2025-04-20' } : { 'Cache-Control': 'no-cache' }) },
-      });
-      if (!response.ok) {
-        await response.body?.cancel();
-        throw new ClaudeStatusError(response.status === 401 ? 'Login expired or was rejected. Log in again with Claude Code and save it.' : `Claude account service returned HTTP ${response.status}.`);
+      const user = credentialRecord(body.account);
+      const organization = credentialRecord(body.organization);
+      if (user.uuid !== account.accountUuid || organization.uuid !== account.organizationUuid) return { kind: 'mismatch' };
+      const facts: IHarnessStatusFact[] = [];
+      for (const [label, value] of [['Email', user.email], ['Organization', organization.name], ['Billing type', organization.billing_type], ['Seat tier', organization.seat_tier]]) {
+        if (credentialText(value)) facts.push({ section: 'Account', label: String(label), value: String(value) });
       }
-      const reader = response.body?.getReader();
-      if (!reader) throw new ClaudeStatusError('The Claude account service returned an empty response.');
-      const chunks: Uint8Array[] = [];
-      let size = 0;
-      try {
-        while (true) {
-          const part = await reader.read();
-          if (part.done) break;
-          size += part.value.byteLength;
-          if (size > 1024 * 1024) { await reader.cancel(); throw new ClaudeStatusError('The Claude account response is too large.'); }
-          chunks.push(part.value);
-        }
-      } finally { reader.releaseLock(); }
-      try { return credentialRecord(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
-      catch { throw new ClaudeStatusError('The Claude account service returned invalid data.'); }
-    } catch (error) {
-      if (signal.aborted) throw new ClaudeStatusError(timeout.aborted ? 'The Claude account request timed out.' : 'The Claude account request was cancelled.');
-      if (error instanceof ClaudeStatusError) throw error;
-      throw new ClaudeStatusError('The Claude account service could not be reached.');
-    }
+      return { kind: 'found', plan: credentialText(organization.organization_type)?.replace(/^claude_/, ''), facts };
+    } catch { return { kind: 'unavailable', problem: 'Claude profile response is unsupported; no profile values were inferred.' }; }
+  }
+
+  /** The plan the login was saved with, the only one known while the service cannot be asked. */
+  private storedSummary(oauth: Record<string, unknown>): Pick<IHarnessAccountStatus, 'summary'> {
+    const plan = credentialText(oauth.subscriptionType);
+    return plan ? { summary: { subscription: { plan, source: 'stored' } } } : {};
   }
+
+  /** A login that could not be made usable for a lookup: its stored plan and why, with the service's retry time for a rate limit. */
+  public unavailable(oauth: Record<string, unknown>, problem: string, rateLimit?: IHarnessAccountStatus['rateLimit']): IHarnessAccountStatus {
+    return { facts: [], problems: [problem], ...this.storedSummary(oauth), ...(rateLimit ? { rateLimit } : {}) };
+  }
+
   public async read(oauth: Record<string, unknown>, account: Record<string, unknown>, optionsArg: IHarnessStatusOptions = {}): Promise<IHarnessAccountStatus> {
-    const result: IHarnessAccountStatus = { facts: [], problems: [] };
-    const storedPlan = credentialText(oauth.subscriptionType);
-    if (storedPlan) result.summary = { subscription: { plan: storedPlan, source: 'stored' } };
+    const result: IHarnessAccountStatus = { facts: [], problems: [], ...this.storedSummary(oauth) };
     if (!Array.isArray(oauth.scopes) || !oauth.scopes.includes('user:profile')) {
       result.facts.push({ section: 'Availability', label: 'Live account status', value: 'This login lacks the user:profile scope. Log in through Claude Code to obtain subscriber status.' });
       return result;
     }
     const token = credentialText(oauth.accessToken);
     if (!token) return { facts: [], problems: ['No usable Claude Code access token is available.'] };
-    const [profile, usage] = await Promise.allSettled([this.get('profile', token, optionsArg.signal), this.get('usage', token, optionsArg.signal)]);
+    const [profile, usage] = await Promise.allSettled([this.profile(token, account, optionsArg), this.get('usage', token, optionsArg.signal)]);
+    const failure = (reason: unknown): string => reason instanceof ClaudeRequestError ? reason.message : 'Lookup failed.';
     if (profile.status === 'fulfilled') {
-      try {
-        const user = credentialRecord(profile.value.account);
-        const organization = credentialRecord(profile.value.organization);
-        if (user.uuid !== account.accountUuid || organization.uuid !== account.organizationUuid) return { facts: [], problems: ['Claude returned a different account or organization; no account data was displayed.'] };
-        const plan = credentialText(organization.organization_type)?.replace(/^claude_/, '');
-        if (plan) result.summary = { ...result.summary, subscription: { plan, source: 'live' } };
-        for (const [label, value] of [['Email', user.email], ['Organization', organization.name], ['Billing type', organization.billing_type], ['Seat tier', organization.seat_tier]]) {
-          if (credentialText(value)) result.facts.push({ section: 'Account', label: String(label), value: String(value) });
-        }
-      } catch { result.problems.push('Claude profile response is unsupported; no profile values were inferred.'); }
-    } else result.problems.push(`Profile: ${profile.reason instanceof ClaudeStatusError ? profile.reason.message : 'Lookup failed.'}`);
+      const found = profile.value;
+      if (found.kind === 'mismatch') return { facts: [], problems: [MISMATCH] };
+      if (found.kind === 'unavailable') result.problems.push(found.problem);
+      else {
+        if (found.plan) result.summary = { ...result.summary, subscription: { plan: found.plan, source: 'live' } };
+        result.facts.push(...found.facts.map(fact => ({ ...fact })));
+      }
+    } else result.problems.push(`Profile: ${failure(profile.reason)}`);
     if (usage.status === 'fulfilled') {
       try {
         const { windows, unsupported } = claudeUsageWindows(usage.value);
@@ -181,8 +211,11 @@ export class ClaudeAccountStatus {
         }
         if (unsupported.length) result.facts.push({ section: 'Availability', label: 'Unsupported limits', value: `The service returned limits without a supported reset window, which are not shown: ${unsupported.join(', ')}.` });
       } catch { result.problems.push('Claude usage response is unsupported; missing values were not inferred.'); }
-    } else result.problems.push(`Usage: ${usage.reason instanceof ClaudeStatusError ? usage.reason.message : 'Lookup failed.'}`);
-    result.facts.push({ section: 'Availability', label: 'Billing dates and earned resets', value: 'Renewal dates, cancellation dates and earned reset credits are not exposed by these Claude Code endpoints.' });
+    } else result.problems.push(`Usage: ${failure(usage.reason)}`);
+    const limited = [profile, usage].flatMap(item => item.status === 'rejected' && item.reason instanceof ClaudeRateLimitError ? [item.reason] : []);
+    if (limited.length) result.rateLimit = { retryAt: latestRetryAt(limited.map(error => error.retryAt)) };
+    // The missing renewal dates are the harness's `renewalUnavailableReason`, stated once by the views that show them.
+    result.facts.push({ section: 'Availability', label: 'Earned resets', value: 'authswitch does not read earned reset credits for Claude Code logins.' });
     return result;
   }
 }

package/ts/classes.claudetokenrefresh.ts

@@ -0,0 +1,85 @@
+import { credentialText } from './classes.credentialstore.js';
+import { claudeRequest, ClaudeLoginRejectedError, ClaudeRequestError } from './claudehttp.js';
+
+/** Claude Code 2.1.273's token endpoint (`TOKEN_URL`, bundle offset @12733057; see hints.md). */
+const TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
+/** Claude Code 2.1.273's public OAuth client (`CLIENT_ID`, @12733057), used when a login does not name its own. */
+export const CLAUDE_CODE_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
+/** Claude Code 2.1.273 refreshes an access token that expires within five minutes (`cF`, @15359182). */
+const REFRESH_MARGIN_MS = 300_000;
+/**
+ * Claude Code 2.1.273 allows a refresh 30 seconds. A refresh is never cut shorter than that, nor cancelled once sent:
+ * the service may already have replaced the refresh token the request carries.
+ */
+const REFRESH_TIMEOUT_MS = 30_000;
+
+/** The token fields a refresh replaces in a stored `claudeAiOauth`; every other field is kept. */
+export interface IClaudeTokens {
+  accessToken: string;
+  refreshToken: string;
+  /** Milliseconds since the epoch, as Claude Code stores them. */
+  expiresAt: number;
+  refreshTokenExpiresAt?: number;
+  scopes?: string[];
+}
+
+const seconds = (valueArg: unknown): number | undefined =>
+  typeof valueArg === 'number' && Number.isFinite(valueArg) && valueArg >= 0 ? valueArg : undefined;
+
+/**
+ * Refreshes a saved Claude Code login with the refresh-token grant Claude Code 2.1.273 uses (`RQ`, @15355055).
+ *
+ * It only talks to the token endpoint; which login is refreshed, and how the result is stored, belongs to the harness.
+ */
+export class ClaudeTokenRefresh {
+  constructor(private readonly fetcher: typeof fetch = globalThis.fetch, private readonly now: () => number = Date.now) {}
+
+  /**
+   * Whether Claude Code would refresh this login before using it: its access token expires within five minutes. A
+   * login without a numeric expiry or without a refresh token is used as it is, exactly as Claude Code does.
+   */
+  public due(oauthArg: Record<string, unknown>): boolean {
+    const expiresAt = oauthArg.expiresAt;
+    return typeof expiresAt === 'number' && Number.isFinite(expiresAt) && credentialText(oauthArg.refreshToken) !== undefined
+      && this.now() + REFRESH_MARGIN_MS >= expiresAt;
+  }
+
+  /**
+   * New tokens for the login. A response without a refresh token keeps the one sent, and one without a scope keeps the
+   * stored scopes, as Claude Code merges them. Throws `ClaudeRequestError` with a fixed diagnostic; a grant the service
+   * rejects is `ClaudeLoginRejectedError`, and a rate limit is `ClaudeRateLimitError`.
+   */
+  public async refresh(oauthArg: Record<string, unknown>): Promise<IClaudeTokens> {
+    const refreshToken = credentialText(oauthArg.refreshToken);
+    const scopes = oauthArg.scopes;
+    if (!refreshToken || !Array.isArray(scopes) || !scopes.every(scope => typeof scope === 'string')) {
+      throw new ClaudeRequestError('This saved login has no refresh token or scopes to refresh with. Log in again with Claude Code and save it.');
+    }
+    const { status, body } = await claudeRequest(this.fetcher, {
+      url: TOKEN_URL, method: 'POST', headers: { 'Content-Type': 'application/json' }, subject: 'Claude sign-in',
+      body: JSON.stringify({
+        grant_type: 'refresh_token', refresh_token: refreshToken,
+        client_id: credentialText(oauthArg.clientId) ?? CLAUDE_CODE_CLIENT_ID, scope: scopes.join(' '),
+      }),
+      timeoutMs: REFRESH_TIMEOUT_MS, readErrorBody: true, now: this.now,
+    });
+    if ((status === 400 || status === 401) && body?.error === 'invalid_grant') throw new ClaudeLoginRejectedError();
+    if (status < 200 || status > 299) throw new ClaudeRequestError(`The Claude sign-in service returned HTTP ${status}.`);
+    const receivedAt = this.now();
+    const accessToken = credentialText(body?.access_token);
+    const tokenType = body?.token_type;
+    const expiresIn = seconds(body?.expires_in);
+    const refreshExpiresIn = body?.refresh_token_expires_in == null ? null : seconds(body.refresh_token_expires_in);
+    const rotated = body?.refresh_token == null ? null : credentialText(body.refresh_token);
+    const scope = body?.scope == null ? null : typeof body.scope === 'string' ? body.scope.split(/\s+/).filter(Boolean) : undefined;
+    if (!accessToken || (tokenType != null && (typeof tokenType !== 'string' || tokenType.toLowerCase() !== 'bearer'))
+      || expiresIn === undefined || refreshExpiresIn === undefined || rotated === undefined || scope === undefined) {
+      throw new ClaudeRequestError('The Claude sign-in service returned an unsupported token response; the saved login was not changed.');
+    }
+    return {
+      accessToken, refreshToken: rotated ?? refreshToken, expiresAt: receivedAt + expiresIn * 1000,
+      ...(refreshExpiresIn === null ? {} : { refreshTokenExpiresAt: receivedAt + refreshExpiresIn * 1000 }),
+      ...(scope === null || !scope.length ? {} : { scopes: scope }),
+    };
+  }
+}