Files
EJClaw/src/token-refresh.ts
Codex 1bb23a60db fix: park rooms during a transient Claude auth outage instead of failing
ff76d04 told the room about a transient refresh failure but still failed
the execution (completeImmediately 'failed'), which bumps
owner_failure_count and can hand the task to the arbiter after two blips.

- reportClaudeAuthRecovering now parks the turn like the usage-limit
  pause: releaseForClaudeUsagePause (lease released, no failure count, no
  follow-up) plus markRunPausedForClaudeUsage (messages stay unconsumed).
  The room is told once per incident; later blips park silently.
- token-refresh fires setOnClaudeAuthRecovered once a rejected token is
  replaced (deferred so the new token is in memory first); index.ts
  re-queues every parked room so the same turn runs without user input.
- Real-DB test: two parked owner runs leave owner_failure_count/status/
  arbiter_requested_at unchanged (control: a failed run does count).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 11:02:48 +09:00

966 lines
32 KiB
TypeScript

/**
* OAuth Token Auto-Refresh for Claude Code
*
* Periodically checks the service's credentials file (CLAUDE_CREDENTIALS_PATH,
* or ~/.claude/.credentials.json when the home fallback is enabled) and
* refreshes the access token before it expires.
*
* After refresh, updates both the in-memory token and the .env file so the
* new token survives restarts.
*/
import fs from 'fs';
import { getErrorMessage, readJsonFile } from './utils.js';
import path from 'path';
import { logger } from './logger.js';
import { DATA_DIR } from './config.js';
import {
getConfiguredClaudeToken,
setCurrentClaudeToken,
} from './claude-oauth-token.js';
import type { AgentType } from './types.js';
import {
getClaudeCredentialsPath,
hasExplicitClaudeCredentialsPath,
} from './claude-credentials-path.js';
const TOKEN_URL = 'https://api.anthropic.com/v1/oauth/token';
const PROFILE_URL = 'https://api.anthropic.com/api/oauth/profile';
const CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
const DEFAULT_SCOPES = [
'user:profile',
'user:inference',
'user:sessions:claude_code',
'user:mcp_servers',
];
// Check every 5 minutes.
const CHECK_INTERVAL_MS = 5 * 60 * 1000;
// Refresh when within 60 minutes of expiry. This is intentionally EARLIER than
// a spawned Claude Code agent's own internal refresh threshold: by refreshing
// first and syncing the fresh token into every session dir, the app becomes the
// consistent "winner" of the token-family rotation and agents rarely need to
// rotate on their own. That shrinks the cross-process refresh race that was
// revoking the whole token family (see loadFreshestCredentials below).
const REFRESH_BEFORE_EXPIRY_MS = 60 * 60 * 1000;
// Refreshing revokes the previous access token at once, and a running agent
// holds that token in CLAUDE_CODE_OAUTH_TOKEN (Claude Code will not swap an env
// token on a 401), so every agent running at refresh time dies with "401 OAuth
// access token has been revoked". Refresh early while no agent is running;
// only fall back to the hard REFRESH_BEFORE_EXPIRY_MS deadline when the
// service stays busy for the whole window.
const IDLE_REFRESH_BEFORE_EXPIRY_MS = 3 * 60 * 60 * 1000;
const REQUEST_TIMEOUT_MS = 15_000;
// After the refresh token itself has expired (or the endpoint keeps rejecting
// us), retrying every CHECK_INTERVAL_MS forever is pointless — only a manual
// browser re-login can recover. Keep trying for ~30 minutes, then give up and
// flag the account as needing manual re-login. Incoming requests can then be
// answered with a "please re-login" message instead of failing opaquely.
const GIVE_UP_AFTER_MS = 30 * 60 * 1000;
/** User-facing message shown when an account needs a manual re-login. */
export const RELOGIN_REQUIRED_MESSAGE =
'⚠️ 클로드 로그인이 풀려서 작업을 진행할 수 없습니다. ' +
'기본_codex 방에서 "클로드 로그인 주소 보내줘"라고 하시면 재로그인 링크를 받을 수 있습니다. ' +
'재로그인한 뒤 이 방에 "계속"이라고 보내 주시면 이어서 진행합니다.';
interface AuthFailureState {
firstFailureAt: number;
gaveUp: boolean;
/**
* Access token the API rejected outright (revoked). It still looks valid by
* its expiresAt, so the periodic check must not treat it as a recovery; only
* a different token (a re-login) clears the state.
*/
deadAccessToken?: string;
}
// Continuous-refresh-failure tracking. Cleared as soon as a valid token
// appears again (e.g. after a manual re-login rewrites the creds file).
let authFailure: AuthFailureState | null = null;
// Access token the API rejected (401) while refreshing it has only failed
// transiently so far (429/5xx/timeout). The periodic loop keeps retrying it
// every CHECK_INTERVAL_MS; after GIVE_UP_AFTER_MS it becomes re-login-required.
let rejectedAccessToken: string | null = null;
// Bumped for each newly rejected token, so rooms are told once per incident.
let authRecoveryIncident = 0;
// Called once a rejected token has been replaced by a working one.
let onAuthRecovered: (() => void) | null = null;
const AUTH_RECOVERED_RESUME_DELAY_MS = 1_000;
/** Register the hook that resumes rooms parked during an auth outage. */
export function setOnClaudeAuthRecovered(fn: (() => void) | null): void {
onAuthRecovered = fn;
}
/**
* The current token was rejected and refreshing failed for a transient reason;
* automatic retries are still running. Returns the incident number, or null.
*/
export function getClaudeAuthRecoveryIncident(): number | null {
return rejectedAccessToken !== null && !isReloginRequired()
? authRecoveryIncident
: null;
}
/**
* True when automatic refresh has been failing for longer than
* GIVE_UP_AFTER_MS and we have stopped retrying. Request handlers use this to
* reply with RELOGIN_REQUIRED_MESSAGE instead of running a doomed agent.
*/
export function isReloginRequired(): boolean {
return authFailure?.gaveUp === true;
}
/** Clear failure tracking once a valid token is observed again. */
function recordAuthSuccess(accessToken?: string): void {
if (
accessToken &&
rejectedAccessToken !== null &&
accessToken !== rejectedAccessToken
) {
rejectedAccessToken = null;
logger.info('Claude OAuth token replaced after a rejection — resuming');
// Deferred: the caller still has to write the new token to disk and into
// memory, and a resumed run must not start with the rejected one.
const hook = onAuthRecovered;
if (hook) {
setTimeout(() => {
try {
hook();
} catch (err) {
logger.warn(
{ err: getErrorMessage(err) },
'Resuming rooms after Claude auth recovery failed',
);
}
}, AUTH_RECOVERED_RESUME_DELAY_MS);
}
}
if (
authFailure?.deadAccessToken &&
(!accessToken || accessToken === authFailure.deadAccessToken)
) {
return;
}
if (authFailure) {
authFailure = null;
logger.info('Claude OAuth recovered — cleared re-login-required state');
}
}
/**
* Record a hard refresh failure. Returns true once we have given up (been
* failing for >= GIVE_UP_AFTER_MS), at which point the caller should stop
* hitting the network.
*/
function recordAuthFailure(): boolean {
const now = Date.now();
const state = authFailure;
if (!state) {
authFailure = { firstFailureAt: now, gaveUp: false };
return false;
}
if (!state.gaveUp && now - state.firstFailureAt >= GIVE_UP_AFTER_MS) {
state.gaveUp = true;
logger.error(
{
failingForMin: Math.round((now - state.firstFailureAt) / 60000),
},
'Claude OAuth refresh has failed for over 30 min — giving up automatic ' +
'retries. Manual re-login required (run claude_relogin.sh).',
);
}
return state.gaveUp;
}
/**
* The API rejected the current token and refreshing failed too: the login is
* gone, so stop retrying right away instead of after GIVE_UP_AFTER_MS.
*/
function markReloginRequired(deadAccessToken: string): void {
authFailure = {
firstFailureAt: authFailure?.firstFailureAt ?? Date.now(),
gaveUp: true,
deadAccessToken,
};
logger.error(
'Claude OAuth token was rejected and could not be refreshed — manual ' +
're-login required (run claude_relogin.sh)',
);
}
/** Test hook: reset the module-level failure state. */
export function resetAuthFailureStateForTests(): void {
authFailure = null;
rejectedAccessToken = null;
refreshRetryDelaysMs = DEFAULT_REFRESH_RETRY_DELAYS_MS;
}
/** Test hook: retry delays for a transient refresh failure. */
export function setRefreshRetryDelaysForTests(delaysMs: number[]): void {
refreshRetryDelaysMs = delaysMs;
}
// A forced refresh of a rejected token retries a transient failure a few
// times right away before falling back to the periodic loop.
const DEFAULT_REFRESH_RETRY_DELAYS_MS = [2_000, 5_000];
let refreshRetryDelaysMs = DEFAULT_REFRESH_RETRY_DELAYS_MS;
/**
* Why the token endpoint refused. `definitive` means the refresh token itself
* was refused (400/401, invalid_grant): only a re-login can help. Anything
* else (429, 5xx, network, timeout) is transient and worth retrying.
*/
export class TokenRefreshError extends Error {
constructor(
readonly definitive: boolean,
readonly status?: number,
) {
super(
`Token refresh failed${status ? ` (${status})` : ''}${definitive ? ': refresh token refused' : ''}`,
);
}
}
export function isDefinitiveRefreshFailure(
status: number,
body: string,
): boolean {
return status === 400 || status === 401 || /invalid_grant/.test(body);
}
export type AccessTokenProbe = 'valid' | 'rejected' | 'unknown';
/**
* Ask the API whether an access token is still accepted. A revoked token keeps
* its expiresAt, so the expiry alone cannot tell a dead token from a live one.
* Only a 401 counts as rejected; network errors and other statuses are unknown.
*/
export async function probeAccessToken(
token: string,
fetchImpl: typeof fetch = fetch,
): Promise<AccessTokenProbe> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
try {
const res = await fetchImpl(PROFILE_URL, {
method: 'GET',
headers: {
Authorization: `Bearer ${token}`,
'anthropic-beta': 'oauth-2025-04-20',
},
signal: controller.signal,
});
if (res.status === 401) return 'rejected';
return res.ok ? 'valid' : 'unknown';
} catch (err) {
logger.warn(
{ err: getErrorMessage(err) },
'Claude OAuth token probe failed',
);
return 'unknown';
} finally {
clearTimeout(timeout);
}
}
/** Pure refresh-timing decision for a token with `remainingMs` left. */
export function isRefreshDue(
remainingMs: number,
agentsActive: boolean,
): boolean {
if (remainingMs <= REFRESH_BEFORE_EXPIRY_MS) return true;
return !agentsActive && remainingMs <= IDLE_REFRESH_BEFORE_EXPIRY_MS;
}
let hasActiveAgents: () => boolean = () => false;
export function shouldStartTokenRefreshLoop(
serviceAgentType: AgentType,
): boolean {
return serviceAgentType === 'claude-code';
}
interface OAuthCredentials {
accessToken: string;
refreshToken: string;
expiresAt: number;
scopes: string[];
subscriptionType?: string;
rateLimitTier?: string;
}
interface CredentialsFile {
claudeAiOauth: OAuthCredentials;
}
interface TokenResponse {
access_token: string;
refresh_token?: string;
expires_in: number;
scope?: string;
}
/** Credentials file path (CLAUDE_CREDENTIALS_PATH or the home fallback). */
function getCredentialsPath(): string {
const credsPath = getClaudeCredentialsPath({
allowHomeFallback:
process.env.CLAUDE_TOKEN_REFRESH_USE_HOME_CREDENTIALS === 'true',
});
if (!credsPath) {
throw new Error('No Claude credentials path configured');
}
return credsPath;
}
function readCredentials(): CredentialsFile | null {
let credsPath: string;
try {
credsPath = getCredentialsPath();
} catch {
return null;
}
if (!fs.existsSync(credsPath)) return null;
const data = readJsonFile<CredentialsFile>(credsPath);
if (!data) {
logger.warn('Failed to read Claude credentials');
}
return data;
}
function writeCredentials(creds: CredentialsFile): void {
const credsPath = getCredentialsPath();
const dir = path.dirname(credsPath);
if (!fs.existsSync(dir)) {
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
}
const tempPath = `${credsPath}.tmp`;
fs.writeFileSync(tempPath, JSON.stringify(creds, null, 2), { mode: 0o600 });
fs.renameSync(tempPath, credsPath);
// Sync to all per-group session directories so running agents pick up the new token
syncToSessionDirs(credsPath);
}
/**
* Pure builder for the on-disk session credential paths. Spawned agents run with
* CLAUDE_CONFIG_DIR pointing at their session `.claude` dir and keep their own
* copy of the credentials, which Claude Code may refresh (rotate) on its own.
*
* The real layout is:
* <sessions>/<folder>/services/<serviceId>/.claude/.credentials.json (group session)
* <sessions>/<folder>/services/<serviceId>/tasks/<taskId>/.claude/.credentials.json (task session)
*
* (An earlier version scanned <sessions>/<folder>/.claude/... which never
* matched, so the fan-out and stale-copy scan silently missed every real
* session file.) `listDirs` is injected so this is unit-testable.
*/
export function collectSessionCredentialPaths(
sessionsDir: string,
listDirs: (dir: string) => string[],
): string[] {
const CRED = ['.claude', '.credentials.json'] as const;
const paths: string[] = [];
for (const folder of listDirs(sessionsDir)) {
const servicesDir = path.join(sessionsDir, folder, 'services');
for (const serviceId of listDirs(servicesDir)) {
const serviceDir = path.join(servicesDir, serviceId);
paths.push(path.join(serviceDir, ...CRED));
const tasksDir = path.join(serviceDir, 'tasks');
for (const taskId of listDirs(tasksDir)) {
paths.push(path.join(tasksDir, taskId, ...CRED));
}
}
}
return paths;
}
function listSubdirectories(dir: string): string[] {
try {
return fs
.readdirSync(dir, { withFileTypes: true })
.filter((entry) => entry.isDirectory())
.map((entry) => entry.name);
} catch {
return [];
}
}
function listSessionCredentialPaths(): string[] {
const sessionsDir = path.join(DATA_DIR, 'sessions');
try {
if (!fs.existsSync(sessionsDir)) return [];
return collectSessionCredentialPaths(sessionsDir, listSubdirectories);
} catch (err) {
logger.warn(
{ err: getErrorMessage(err) },
'Failed to enumerate session credential dirs',
);
return [];
}
}
function syncToSessionDirs(credsPath: string): void {
try {
let synced = 0;
for (const dest of listSessionCredentialPaths()) {
if (dest === credsPath) continue;
if (fs.existsSync(path.dirname(dest))) {
fs.copyFileSync(credsPath, dest);
synced++;
}
}
if (synced > 0) {
logger.info(
{ count: synced },
'Synced credentials to session directories',
);
}
} catch (err) {
logger.warn(
{ err: getErrorMessage(err) },
'Failed to sync credentials to sessions',
);
}
}
/**
* Pure decision for the session→canonical write-back: adopt the session token
* only when it is a valid credential that is strictly newer than canonical (the
* session refreshed mid-turn) and does not cross subscription types. Never
* regress canonical to an older/equal token.
*/
export function shouldAdoptSessionOAuth(
session: OAuthCredentials | undefined | null,
canonical: OAuthCredentials | undefined | null,
): boolean {
if (
!session?.accessToken ||
!session?.refreshToken ||
typeof session.expiresAt !== 'number'
) {
return false;
}
if (
canonical?.subscriptionType &&
session.subscriptionType &&
canonical.subscriptionType !== session.subscriptionType
) {
return false;
}
if (
canonical &&
typeof canonical.expiresAt === 'number' &&
session.expiresAt <= canonical.expiresAt
) {
return false;
}
return true;
}
/**
* Write-back (session → canonical). After a Claude agent turn, the child Claude
* CLI running with CLAUDE_CONFIG_DIR=<sessionClaudeDir> may have refreshed
* (rotated) the OAuth token in its own copy. If that copy is strictly newer than
* the canonical credentials, adopt it so the canonical file always holds the
* latest rotated token. Without this the main refresh loop can later refresh an
* already-rotated token, which Anthropic rejects with invalid_grant and revokes
* the whole token family (forcing a manual re-login). Mirrors the Codex
* syncCodexSessionAuthBack write-back. Returns true if canonical was updated.
*/
export function syncClaudeSessionAuthBack(sessionClaudeDir: string): boolean {
if (!sessionClaudeDir) return false;
const sessionPath = path.join(sessionClaudeDir, '.credentials.json');
let sessionCreds: CredentialsFile | null = null;
try {
if (!fs.existsSync(sessionPath)) return false;
sessionCreds = JSON.parse(
fs.readFileSync(sessionPath, 'utf-8'),
) as CredentialsFile;
} catch {
return false;
}
const sOauth = sessionCreds?.claudeAiOauth;
if (!sOauth) return false;
const canonical = readCredentials();
if (!shouldAdoptSessionOAuth(sOauth, canonical?.claudeAiOauth)) {
return false;
}
// writeCredentials also fans the adopted token out to every session dir, so
// stale copies (old refresh tokens that could trigger family revocation) are
// overwritten with the current one.
writeCredentials(sessionCreds);
recordAuthSuccess(sOauth.accessToken);
logger.info(
{
newExpiryMin: Math.round((sOauth.expiresAt - Date.now()) / 60000),
},
'Adopted refreshed Claude session token back into canonical credentials',
);
return true;
}
/**
* Pure selector: from a list of candidate credential files, pick the one whose
* access token expires latest (i.e. the most recently rotated, still-live
* member of the OAuth token family). Candidates without a refresh token or a
* numeric expiresAt are ignored. The first candidate should be the source file
* so that ties resolve in its favour (only a strictly-newer copy wins).
*/
export function pickFreshestOAuth(
candidates: Array<{ label: string; creds: CredentialsFile | null }>,
): { label: string; creds: CredentialsFile } | null {
let best: { label: string; creds: CredentialsFile } | null = null;
for (const candidate of candidates) {
const oauth = candidate.creds?.claudeAiOauth;
if (!oauth?.refreshToken || typeof oauth.expiresAt !== 'number') continue;
if (!best || oauth.expiresAt > best.creds.claudeAiOauth.expiresAt) {
best = {
label: candidate.label,
creds: candidate.creds as CredentialsFile,
};
}
}
return best;
}
interface FreshestCredentials {
creds: CredentialsFile;
/** True when the freshest copy came from a session dir, not the source file. */
adoptedFromSession: boolean;
label: string;
}
/**
* Read the source credentials plus every session-dir copy and return the
* freshest (latest-expiring) one. A spawned agent may have already rotated the
* token family in its own session copy; adopting that live token instead of
* re-POSTing our now-stale refresh token is what prevents reuse-detection from
* revoking the entire family.
*/
function loadFreshestCredentials(): FreshestCredentials | null {
const candidates: Array<{ label: string; creds: CredentialsFile | null }> = [
{ label: 'source', creds: readCredentials() },
];
for (const sessionPath of listSessionCredentialPaths()) {
candidates.push({
label: sessionPath,
creds: readJsonFile<CredentialsFile>(sessionPath),
});
}
const best = pickFreshestOAuth(candidates);
if (!best) return null;
return {
creds: best.creds,
adoptedFromSession: best.label !== 'source',
label: best.label,
};
}
/**
* Write the refreshed token into .env so it survives restarts. Both the
* CLAUDE_CODE_OAUTH_TOKEN line and the legacy CLAUDE_CODE_OAUTH_TOKENS line are
* rewritten when present; with neither present, CLAUDE_CODE_OAUTH_TOKEN is
* appended.
*/
export function applyUpdatedTokenToEnvContent(
content: string,
token: string,
): string {
const listLineRe = /^CLAUDE_CODE_OAUTH_TOKENS=.*/m;
const singleLineRe = /^CLAUDE_CODE_OAUTH_TOKEN=.*/m;
let next = content;
const hasList = listLineRe.test(next);
const hasSingle = singleLineRe.test(next);
if (hasList) {
next = next.replace(listLineRe, `CLAUDE_CODE_OAUTH_TOKENS=${token}`);
}
if (hasSingle) {
next = next.replace(singleLineRe, `CLAUDE_CODE_OAUTH_TOKEN=${token}`);
}
if (!hasList && !hasSingle) {
next = `${next.replace(/\s*$/, '')}\nCLAUDE_CODE_OAUTH_TOKEN=${token}\n`;
}
return next;
}
/**
* Adopt a refreshed access token: in memory, in process.env and in .env.
* Skipped when the service passes no OAuth token to agents (credentials-file
* only setups), matching the previous behaviour.
*/
function applyRefreshedAccessToken(accessToken: string): void {
if (!getConfiguredClaudeToken()) return;
setCurrentClaudeToken(accessToken);
process.env.CLAUDE_CODE_OAUTH_TOKEN = accessToken;
updateEnvToken(accessToken);
}
function updateEnvToken(token: string): void {
const envFile = path.join(process.cwd(), '.env');
try {
if (!fs.existsSync(envFile)) return;
const content = fs.readFileSync(envFile, 'utf-8');
const nextContent = applyUpdatedTokenToEnvContent(content, token);
const tempPath = `${envFile}.tmp`;
fs.writeFileSync(tempPath, nextContent, { mode: 0o600 });
fs.renameSync(tempPath, envFile);
logger.debug('Updated .env with refreshed tokens');
} catch (err) {
logger.warn(
{ err: getErrorMessage(err) },
'Failed to update .env with refreshed tokens',
);
}
}
async function refreshToken(
refreshTokenStr: string,
scopes: string[],
): Promise<TokenResponse> {
const body = JSON.stringify({
grant_type: 'refresh_token',
refresh_token: refreshTokenStr,
client_id: CLIENT_ID,
scope: (scopes.length > 0 ? scopes : DEFAULT_SCOPES).join(' '),
});
const headers = { 'Content-Type': 'application/json' };
try {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
const res = await fetch(TOKEN_URL, {
method: 'POST',
headers,
body,
signal: controller.signal,
});
clearTimeout(timeout);
if (res.status === 200) {
return (await res.json()) as TokenResponse;
}
const errText = await res.text().catch(() => '');
logger.warn(
{ url: TOKEN_URL, status: res.status, body: errText.slice(0, 200) },
'Token refresh failed at endpoint',
);
throw new TokenRefreshError(
isDefinitiveRefreshFailure(res.status, errText),
res.status,
);
} catch (err) {
if (err instanceof TokenRefreshError) throw err;
logger.warn(
{ url: TOKEN_URL, err: getErrorMessage(err) },
'Token refresh request error',
);
throw new TokenRefreshError(false);
}
}
/** refreshToken, retrying transient failures after each of `delaysMs`. */
async function refreshTokenWithRetry(
refreshTokenStr: string,
scopes: string[],
delaysMs: number[],
): Promise<TokenResponse> {
for (let attempt = 0; ; attempt += 1) {
try {
return await refreshToken(refreshTokenStr, scopes);
} catch (err) {
const delay = delaysMs[attempt];
if (
delay === undefined ||
(err instanceof TokenRefreshError && err.definitive)
) {
throw err;
}
logger.warn(
{ attempt: attempt + 1, retryInMs: delay },
'Claude OAuth refresh failed transiently — retrying',
);
await new Promise((resolve) => setTimeout(resolve, delay));
}
}
}
// Serialize all refreshes within this process so the 5-minute loop and an
// on-demand forceRefreshToken() (triggered by a 401) can never rotate the same
// token family concurrently — a self-inflicted reuse that revokes the family.
let refreshMutex: Promise<unknown> = Promise.resolve();
function serializeRefresh<T>(fn: () => Promise<T>): Promise<T> {
const next = refreshMutex.then(fn, fn);
// Keep the chain alive regardless of individual outcomes.
refreshMutex = next.then(
() => undefined,
() => undefined,
);
return next;
}
/**
* Check and refresh the credentials.
* Returns the (new or adopted) access token if it changed, null otherwise.
*/
async function checkAndRefreshCredentials(opts?: {
force?: boolean;
}): Promise<string | null> {
return serializeRefresh(() => doCheckAndRefreshCredentials(opts));
}
async function doCheckAndRefreshCredentials(opts?: {
force?: boolean;
}): Promise<string | null> {
const freshest = loadFreshestCredentials();
if (!freshest?.creds.claudeAiOauth) return null;
const creds = freshest.creds;
const oauth = creds.claudeAiOauth;
const rt = oauth.refreshToken;
if (!rt) {
logger.debug('No refresh token in credentials, skipping');
return null;
}
// A concurrent refresher (typically a spawned agent) may have already rotated
// the family in its session copy. Converge the source file onto that newer
// token so we never re-POST a superseded refresh token.
if (freshest.adoptedFromSession) {
writeCredentials(creds);
logger.info(
{
remainingMin: Math.round((oauth.expiresAt - Date.now()) / 60000),
},
'Adopted newer Claude token from a concurrent refresher (skipped duplicate refresh)',
);
}
const now = Date.now();
const remaining = oauth.expiresAt - now;
// A forced check comes from a 401. Expiry cannot reveal a revoked token, so
// ask the API; a rejected token must be refreshed even though it "looks"
// valid, otherwise every retry reuses the same dead token.
const knownRejected =
rejectedAccessToken !== null && rejectedAccessToken === oauth.accessToken;
const rejected =
knownRejected ||
(opts?.force === true &&
!isReloginRequired() &&
(await probeAccessToken(oauth.accessToken)) === 'rejected');
if (rejected && !knownRejected) {
rejectedAccessToken = oauth.accessToken;
authRecoveryIncident += 1;
logger.warn(
{ remainingMin: Math.round(remaining / 60000) },
'Claude OAuth token was rejected by the API before its expiry',
);
}
// A forced (401) check only refreshes a rejected or nearly expired token.
const due =
rejected || isRefreshDue(remaining, opts?.force ? true : hasActiveAgents());
if (!due) {
// A valid token is present again (typically after a manual re-login rewrote
// the credentials file) — drop any prior "re-login required" state.
recordAuthSuccess(oauth.accessToken);
if (!opts?.force && !freshest.adoptedFromSession) {
logger.debug(
{ remainingMin: Math.round(remaining / 60000) },
'Token still valid, no refresh needed',
);
}
// Still the token the API rejected: there is nothing usable to retry with.
if (isReloginRequired()) return null;
// Token is valid; only report a token when it actually changed (adopted) or
// a caller forced the check and wants a usable token back to retry with.
return freshest.adoptedFromSession || opts?.force
? oauth.accessToken
: null;
}
// Already gave up on this account (refresh token dead). Stop hammering the
// endpoint every 5 min — a manual re-login is required, which the
// healthy-token branch above will detect and clear automatically.
if (isReloginRequired()) {
logger.debug(
'Skipping refresh — re-login required until a manual re-login is performed',
);
return null;
}
const isExpired = remaining <= 0;
logger.info(
{
remainingMin: Math.round(remaining / 60000),
isExpired,
force: opts?.force === true,
},
'Refreshing Claude OAuth token',
);
try {
const response = await refreshTokenWithRetry(
rt,
oauth.scopes || DEFAULT_SCOPES,
rejected && opts?.force ? refreshRetryDelaysMs : [],
);
recordAuthSuccess(response.access_token);
oauth.accessToken = response.access_token;
oauth.refreshToken = response.refresh_token || rt;
oauth.expiresAt = Date.now() + response.expires_in * 1000;
if (response.scope) {
oauth.scopes = response.scope.split(' ');
}
writeCredentials(creds);
const newExpiryMin = Math.round(response.expires_in / 60);
logger.info(
{ expiresInMin: newExpiryMin },
'Claude OAuth token refreshed successfully',
);
return response.access_token;
} catch (err) {
// We may simply have lost the rotation race: another process refreshed the
// family a moment ago, so our token is now "expired". Re-scan every copy —
// if a valid token exists, adopt it instead of reporting a hard failure.
const recovered = loadFreshestCredentials();
const recoveredOauth = recovered?.creds.claudeAiOauth;
if (
recoveredOauth &&
recoveredOauth.expiresAt - Date.now() > REFRESH_BEFORE_EXPIRY_MS &&
// The token the API just rejected is no recovery, however long it has.
!(rejected && recoveredOauth.accessToken === oauth.accessToken)
) {
if (recovered.adoptedFromSession) {
writeCredentials(recovered.creds);
}
recordAuthSuccess(recoveredOauth.accessToken);
logger.warn(
{
remainingMin: Math.round(
(recoveredOauth.expiresAt - Date.now()) / 60000,
),
},
'Refresh failed but a concurrent refresher produced a valid token — adopted it',
);
return recoveredOauth.accessToken;
}
const definitive = err instanceof TokenRefreshError && err.definitive;
if (rejected && definitive) {
markReloginRequired(oauth.accessToken);
return null;
}
const gaveUp = recordAuthFailure();
if (rejected) {
// Transient (429/5xx/timeout): keep retrying from the periodic loop;
// only a failure that lasts GIVE_UP_AFTER_MS means the login is gone.
if (gaveUp) {
markReloginRequired(oauth.accessToken);
} else {
logger.warn(
{ err: getErrorMessage(err) },
'Rejected Claude OAuth token could not be refreshed yet (transient) — retrying every check',
);
}
return null;
}
logger.error(
{
gaveUp,
err: getErrorMessage(err),
},
gaveUp
? 'Failed to refresh Claude OAuth token — giving up until manual re-login'
: 'Failed to refresh Claude OAuth token — manual re-login may be required',
);
return null;
}
}
/** Periodic check: refresh when needed and adopt the new token. */
async function checkAndRefresh(): Promise<void> {
const newAccessToken = await checkAndRefreshCredentials();
if (newAccessToken) applyRefreshedAccessToken(newAccessToken);
}
let refreshInterval: ReturnType<typeof setInterval> | null = null;
export function startTokenRefreshLoop(options?: {
/** True while any agent run is in flight (see IDLE_REFRESH_BEFORE_EXPIRY_MS). */
hasActiveAgents?: () => boolean;
}): void {
if (options?.hasActiveAgents) hasActiveAgents = options.hasActiveAgents;
const refreshEnabled =
process.env.CLAUDE_TOKEN_REFRESH_USE_CREDENTIALS === 'true' ||
process.env.CLAUDE_TOKEN_REFRESH_USE_HOME_CREDENTIALS === 'true';
if (!refreshEnabled) {
logger.info(
'Claude token auto-refresh disabled; EJClaw is using its dedicated OAuth token',
);
return;
}
if (
process.env.CLAUDE_TOKEN_REFRESH_USE_HOME_CREDENTIALS !== 'true' &&
!hasExplicitClaudeCredentialsPath()
) {
logger.info('Claude token auto-refresh disabled; no credentials path set');
return;
}
if (!readCredentials()?.claudeAiOauth) {
logger.info('No OAuth credentials found, token refresh disabled');
return;
}
logger.info(
{ checkIntervalMin: CHECK_INTERVAL_MS / 60000 },
'Token auto-refresh started',
);
// Check immediately on startup
checkAndRefresh().catch((err) =>
logger.error({ err }, 'Initial token refresh check failed'),
);
refreshInterval = setInterval(() => {
checkAndRefresh().catch((err) =>
logger.error({ err }, 'Token refresh check failed'),
);
}, CHECK_INTERVAL_MS);
}
export function stopTokenRefreshLoop(): void {
if (refreshInterval) {
clearInterval(refreshInterval);
refreshInterval = null;
}
}
/**
* Force an immediate token refresh.
* Useful when a 401 is detected — attempt refresh before giving up.
* Returns the new access token if refresh succeeded, null otherwise.
*/
export async function forceRefreshToken(): Promise<string | null> {
logger.info('Force-refreshing token after 401');
const newAccessToken = await checkAndRefreshCredentials({ force: true });
if (newAccessToken) applyRefreshedAccessToken(newAccessToken);
return newAccessToken;
}