@juspay/neurolink 9.30.0 → 9.31.0

package/dist/lib/auth/accountPool.js

@@ -0,0 +1,179 @@
+/**
+ * AccountPool — manages a pool of proxy accounts with round-robin / fill-first
+ * selection and exponential-backoff cooldowns for quota-exceeded accounts.
+ *
+ * @module auth/accountPool
+ */
+import { tokenStore } from "./tokenStore.js";
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const DEFAULT_COOLDOWN_MS = 300_000;
+const DEFAULT_MAX_COOLDOWN_MS = 1_800_000;
+// =============================================================================
+// IMPLEMENTATION
+// =============================================================================
+export class AccountPool {
+    accounts = new Map();
+    cursor = 0;
+    config;
+    constructor(config = {}) {
+        this.config = {
+            strategy: config.strategy ?? "round-robin",
+            defaultCooldownMs: config.defaultCooldownMs ?? DEFAULT_COOLDOWN_MS,
+            maxCooldownMs: config.maxCooldownMs ?? DEFAULT_MAX_COOLDOWN_MS,
+            maxRetryAccounts: config.maxRetryAccounts ?? 0,
+        };
+    }
+    /** Add (or replace) an account in the pool. */
+    addAccount(account) {
+        // Clear any stale token refresher for a previously-registered account
+        // with the same id — wireTokenRefresh() captures the old account object
+        // in its closure, so leaving it behind would refresh the wrong tokens.
+        tokenStore.clearTokenRefresher(account.id);
+        this.accounts.set(account.id, { ...account });
+    }
+    /** Remove an account from the pool by id. */
+    removeAccount(id) {
+        tokenStore.clearTokenRefresher(id);
+        this.accounts.delete(id);
+    }
+    /**
+     * Return the next healthy account according to the configured strategy.
+     * Returns `null` when no healthy accounts are available.
+     */
+    getNextAccount() {
+        this._expireCooldowns();
+        const healthy = this._getHealthyAccounts();
+        if (healthy.length === 0) {
+            return null;
+        }
+        if (this.config.strategy === "fill-first") {
+            const account = healthy[0];
+            account.requestCount++;
+            account.lastUsed = Date.now();
+            return account;
+        }
+        // round-robin
+        const index = this.cursor % healthy.length;
+        this.cursor++;
+        const account = healthy[index];
+        account.requestCount++;
+        account.lastUsed = Date.now();
+        return account;
+    }
+    /**
+     * Mark an account as quota-exceeded.  The account enters a cooldown state
+     * with exponential backoff capped at `maxCooldownMs`.
+     *
+     * @deprecated Proxy routes now use `RuntimeAccountState` in `claudeProxyRoutes.ts`
+     * for runtime account state management. This method is retained for public API compatibility.
+     *
+     * @param id             Account id
+     * @param retryAfterMs   Optional explicit retry-after duration (from server header)
+     */
+    markQuotaExceeded(id, retryAfterMs) {
+        const account = this.accounts.get(id);
+        if (!account) {
+            return;
+        }
+        account.consecutiveFailures++;
+        const backoff = Math.min(this.config.defaultCooldownMs *
+            Math.pow(2, account.consecutiveFailures - 1), this.config.maxCooldownMs);
+        account.cooldownUntil = Date.now() + (retryAfterMs ?? backoff);
+        account.status = "cooling";
+    }
+    /**
+     * Manually mark an account as available (healthy), clearing its cooldown.
+     *
+     * @deprecated Proxy routes now use `RuntimeAccountState` in `claudeProxyRoutes.ts`
+     * for runtime account state management. This method is retained for public API compatibility.
+     */
+    markAvailable(id) {
+        const account = this.accounts.get(id);
+        if (!account) {
+            return;
+        }
+        account.status = "healthy";
+        account.cooldownUntil = undefined;
+    }
+    /**
+     * Mark an account as having completed a request successfully.
+     *
+     * @deprecated Proxy routes now use `RuntimeAccountState` in `claudeProxyRoutes.ts`
+     * for runtime account state management. This method is retained for public API compatibility.
+     */
+    markSuccess(id) {
+        const account = this.accounts.get(id);
+        if (!account) {
+            return;
+        }
+        account.status = "healthy";
+        account.cooldownUntil = undefined;
+        account.consecutiveFailures = 0;
+    }
+    /** Return the number of currently healthy (not cooling/disabled) accounts. */
+    getHealthyCount() {
+        this._expireCooldowns();
+        return this._getHealthyAccounts().length;
+    }
+    /** Return a snapshot of all accounts in the pool. */
+    getAllAccounts() {
+        return Array.from(this.accounts.values());
+    }
+    /** Return the configured selection strategy. */
+    getStrategy() {
+        return this.config.strategy;
+    }
+    /**
+     * Wire automatic token refresh for an OAuth account.
+     * Call after addAccount() for OAuth accounts that have a refresh token.
+     *
+     * @param accountId  The account id to wire refresh for
+     * @param refreshFn  Function that takes a refresh token and returns new token data
+     */
+    wireTokenRefresh(accountId, refreshFn) {
+        const account = this.accounts.get(accountId);
+        if (!account || account.type !== "oauth" || !account.tokens?.refreshToken) {
+            return;
+        }
+        tokenStore.setTokenRefresher(accountId, async (refreshToken) => {
+            const result = await refreshFn(refreshToken);
+            const newTokens = {
+                accessToken: result.accessToken,
+                refreshToken: result.refreshToken ?? refreshToken,
+                expiresAt: result.expiresAt instanceof Date
+                    ? result.expiresAt.getTime()
+                    : result.expiresAt,
+                tokenType: result.tokenType ?? "Bearer",
+            };
+            // Update in-memory account
+            if (account.tokens) {
+                account.tokens.accessToken = newTokens.accessToken;
+                account.tokens.expiresAt = newTokens.expiresAt;
+                if (newTokens.refreshToken) {
+                    account.tokens.refreshToken = newTokens.refreshToken;
+                }
+            }
+            return newTokens;
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    _getHealthyAccounts() {
+        return Array.from(this.accounts.values()).filter((a) => a.status === "healthy");
+    }
+    _expireCooldowns() {
+        const now = Date.now();
+        for (const account of this.accounts.values()) {
+            if (account.status === "cooling" &&
+                account.cooldownUntil &&
+                now >= account.cooldownUntil) {
+                account.status = "healthy";
+                account.cooldownUntil = undefined;
+            }
+        }
+    }
+}
+//# sourceMappingURL=accountPool.js.map

package/dist/lib/auth/anthropicOAuth.d.ts

@@ -15,7 +15,6 @@
  * @module auth/anthropicOAuth
  */
 import type { Server } from "http";
-export { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthTokenRefreshError, OAuthTokenValidationError, OAuthTokenRevocationError, OAuthCallbackServerError, } from "../types/errors.js";
 /**
  * Claude Code's official OAuth client ID
  * Used to authenticate with Anthropic's OAuth system
@@ -26,9 +25,13 @@ export declare const CLAUDE_CODE_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f
  */
 export declare const ANTHROPIC_AUTH_URL = "https://claude.ai/oauth/authorize";
 /**
- * Anthropic OAuth token endpoint
+ * Anthropic OAuth token endpoint (primary — lighter Cloudflare)
  */
-export declare const ANTHROPIC_TOKEN_URL = "https://console.anthropic.com/v1/oauth/token";
+export declare const ANTHROPIC_TOKEN_URL = "https://api.anthropic.com/v1/oauth/token";
+/**
+ * Anthropic OAuth token endpoint (fallback)
+ */
+export declare const ANTHROPIC_TOKEN_URL_FALLBACK = "https://console.anthropic.com/v1/oauth/token";
 /**
  * Anthropic OAuth redirect URI (official callback)
  */
@@ -63,8 +66,7 @@ export declare const DEFAULT_REDIRECT_URI = "https://console.anthropic.com/oauth
  * Default local callback server port (for local testing only)
  */
 export declare const DEFAULT_CALLBACK_PORT = 8787;
-import type { OAuthFlowTokens, TokenValidationResult, AnthropicOAuthConfig, PKCEParams, CallbackResult } from "../types/subscriptionTypes.js";
-export type { OAuthTokenResponse, OAuthFlowTokens, OAuthFlowTokens as OAuthTokens, TokenValidationResult, AnthropicOAuthConfig, PKCEParams, CallbackResult, } from "../types/subscriptionTypes.js";
+import type { OAuthFlowTokens, TokenValidationResult, AnthropicOAuthConfig, PKCEParams, CallbackResult } from "../types/index.js";
 /**
  * AnthropicOAuth - OAuth 2.0 authentication for Claude Pro/Max subscriptions
  *
@@ -251,6 +253,14 @@ export declare class AnthropicOAuth {
      * @throws OAuthTokenRevocationError if revocation fails
      */
     revokeToken(token: string, tokenType?: "access_token" | "refresh_token"): Promise<void>;
+    /**
+     * Build the list of token endpoint URLs to try, with optional fallback.
+     *
+     * When a custom tokenUrl was provided (via config param OR constructor), never
+     * fall back to the default Anthropic endpoint — leaking credentials to an
+     * unexpected endpoint is a security risk.
+     */
+    private getTokenUrls;
     /**
      * Parses a token response into structured OAuthFlowTokens
      */

package/dist/lib/auth/anthropicOAuth.js

@@ -38,8 +38,6 @@ function redactTokens(s) {
         .replace(/[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+/g, "[JWT]")
         .replace(/\b[A-Za-z0-9\-_]{32,}\b/g, "[TOKEN]");
 }
-// Re-export error classes for backward compatibility
-export { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthTokenRefreshError, OAuthTokenValidationError, OAuthTokenRevocationError, OAuthCallbackServerError, } from "../types/errors.js";
 // =============================================================================
 // OAUTH CONSTANTS (Claude Code Official)
 // =============================================================================
@@ -53,9 +51,13 @@ export const CLAUDE_CODE_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
  */
 export const ANTHROPIC_AUTH_URL = "https://claude.ai/oauth/authorize";
 /**
- * Anthropic OAuth token endpoint
+ * Anthropic OAuth token endpoint (primary — lighter Cloudflare)
  */
-export const ANTHROPIC_TOKEN_URL = "https://console.anthropic.com/v1/oauth/token";
+export const ANTHROPIC_TOKEN_URL = "https://api.anthropic.com/v1/oauth/token";
+/**
+ * Anthropic OAuth token endpoint (fallback)
+ */
+export const ANTHROPIC_TOKEN_URL_FALLBACK = "https://console.anthropic.com/v1/oauth/token";
 /**
  * Anthropic OAuth redirect URI (official callback)
  */
@@ -339,37 +341,54 @@ export class AnthropicOAuth {
         if (clientSecret) {
             body.client_secret = clientSecret;
         }
-        try {
-            const response = await fetch(config.tokenUrl || this.tokenUrl, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/x-www-form-urlencoded",
-                    Accept: "application/json",
-                },
-                body: new URLSearchParams(body).toString(),
-            });
-            if (!response.ok) {
-                const errorBody = await response.text();
-                logger.error("Token exchange failed", {
-                    status: response.status,
-                    error: redactTokens(errorBody).slice(0, 500),
+        const urls = this.getTokenUrls(config.tokenUrl);
+        let lastError;
+        for (const url of urls) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 10_000);
+            try {
+                const response = await fetch(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/x-www-form-urlencoded",
+                        Accept: "application/json",
+                    },
+                    body: new URLSearchParams(body).toString(),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    logger.error("Token exchange failed", {
+                        url,
+                        status: response.status,
+                        error: redactTokens(errorBody).slice(0, 500),
+                    });
+                    lastError = new OAuthTokenExchangeError(`Token exchange failed: ${response.status} - ${errorBody}`, response.status);
+                    continue;
+                }
+                const tokenResponse = await response.json();
+                const tokens = this.parseTokenResponse(tokenResponse);
+                logger.info("Token exchange successful", {
+                    expiresAt: tokens.expiresAt.toISOString(),
+                    hasRefreshToken: !!tokens.refreshToken,
                 });
-                throw new OAuthTokenExchangeError(`Token exchange failed: ${response.status} - ${errorBody}`, response.status);
+                return tokens;
             }
-            const tokenResponse = await response.json();
-            const tokens = this.parseTokenResponse(tokenResponse);
-            logger.info("Token exchange successful", {
-                expiresAt: tokens.expiresAt.toISOString(),
-                hasRefreshToken: !!tokens.refreshToken,
-            });
-            return tokens;
-        }
-        catch (error) {
-            if (error instanceof OAuthError) {
-                throw error;
+            catch (error) {
+                if (error instanceof OAuthError) {
+                    lastError = error;
+                    continue;
+                }
+                lastError = new OAuthTokenExchangeError(`Failed to exchange authorization code: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            finally {
+                clearTimeout(timeoutId);
             }
-            throw new OAuthTokenExchangeError(`Failed to exchange authorization code: ${error instanceof Error ? error.message : String(error)}`);
         }
+        throw lastError instanceof OAuthError
+            ? lastError
+            : new OAuthTokenExchangeError(`Failed to exchange authorization code: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
     }
     // =============================================================================
     // TOKEN REFRESH
@@ -405,36 +424,58 @@ export class AnthropicOAuth {
         if (clientSecret) {
             body.client_secret = clientSecret;
         }
-        try {
-            const response = await fetch(config.tokenUrl || this.tokenUrl, {
-                method: "POST",
-                headers: {
-                    "Content-Type": "application/x-www-form-urlencoded",
-                    Accept: "application/json",
-                },
-                body: new URLSearchParams(body).toString(),
-            });
-            if (!response.ok) {
-                const errorBody = await response.text();
-                logger.error("Token refresh failed", {
-                    status: response.status,
-                    error: redactTokens(errorBody).slice(0, 500),
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+            "User-Agent": CLAUDE_CLI_USER_AGENT,
+        };
+        const urls = this.getTokenUrls(config.tokenUrl);
+        let lastError;
+        for (const url of urls) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 10_000);
+            try {
+                const response = await fetch(url, {
+                    method: "POST",
+                    headers,
+                    body: new URLSearchParams(body).toString(),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    const errorBody = await response.text();
+                    logger.error("Token refresh failed", {
+                        url,
+                        status: response.status,
+                        error: redactTokens(errorBody).slice(0, 500),
+                    });
+                    lastError = new OAuthTokenRefreshError(`Token refresh failed: ${response.status} - ${errorBody}`, response.status);
+                    // Try fallback URL if available
+                    continue;
+                }
+                const tokenResponse = await response.json();
+                const tokens = this.parseTokenResponse(tokenResponse);
+                logger.info("Access token refreshed successfully", {
+                    expiresAt: tokens.expiresAt.toISOString(),
                 });
-                throw new OAuthTokenRefreshError(`Token refresh failed: ${response.status} - ${errorBody}`, response.status);
+                return tokens;
             }
-            const tokenResponse = await response.json();
-            const tokens = this.parseTokenResponse(tokenResponse);
-            logger.info("Access token refreshed successfully", {
-                expiresAt: tokens.expiresAt.toISOString(),
-            });
-            return tokens;
-        }
-        catch (error) {
-            if (error instanceof OAuthError) {
-                throw error;
+            catch (error) {
+                if (error instanceof OAuthError) {
+                    lastError = error;
+                    // Try fallback URL if available
+                    continue;
+                }
+                lastError = new OAuthTokenRefreshError(`Failed to refresh access token: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            finally {
+                clearTimeout(timeoutId);
             }
-            throw new OAuthTokenRefreshError(`Failed to refresh access token: ${error instanceof Error ? error.message : String(error)}`);
         }
+        // All URLs exhausted — throw the last error
+        throw lastError instanceof OAuthError
+            ? lastError
+            : new OAuthTokenRefreshError(`Failed to refresh access token: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
     }
     // =============================================================================
     // TOKEN VALIDATION
@@ -471,6 +512,7 @@ export class AnthropicOAuth {
                     "Content-Type": "application/x-www-form-urlencoded",
                     Accept: "application/json",
                     Authorization: `Bearer ${accessToken}`,
+                    "User-Agent": CLAUDE_CLI_USER_AGENT,
                 },
                 body: new URLSearchParams({
                     token: accessToken,
@@ -513,6 +555,7 @@ export class AnthropicOAuth {
                     "Content-Type": "application/x-www-form-urlencoded",
                     Accept: "application/json",
                     Authorization: `Bearer ${accessToken}`,
+                    "User-Agent": CLAUDE_CLI_USER_AGENT,
                 },
                 body: new URLSearchParams({
                     token: accessToken,
@@ -605,6 +648,23 @@ export class AnthropicOAuth {
     // =============================================================================
     // HELPER METHODS
     // =============================================================================
+    /**
+     * Build the list of token endpoint URLs to try, with optional fallback.
+     *
+     * When a custom tokenUrl was provided (via config param OR constructor), never
+     * fall back to the default Anthropic endpoint — leaking credentials to an
+     * unexpected endpoint is a security risk.
+     */
+    getTokenUrls(configTokenUrl) {
+        if (configTokenUrl) {
+            return [configTokenUrl];
+        }
+        const isCustomConstructorUrl = this.tokenUrl !== ANTHROPIC_TOKEN_URL;
+        if (isCustomConstructorUrl) {
+            return [this.tokenUrl];
+        }
+        return [this.tokenUrl, ANTHROPIC_TOKEN_URL_FALLBACK];
+    }
     /**
      * Parses a token response into structured OAuthFlowTokens
      */

package/dist/lib/auth/index.d.ts

@@ -11,10 +11,12 @@
  */
 export { ANTHROPIC_OAUTH_BASE_URL, DEFAULT_SCOPES, DEFAULT_REDIRECT_URI, DEFAULT_CALLBACK_PORT, } from "./anthropicOAuth.js";
 export { AnthropicOAuth } from "./anthropicOAuth.js";
-export { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthTokenRefreshError, OAuthTokenValidationError, OAuthTokenRevocationError, OAuthCallbackServerError, } from "./anthropicOAuth.js";
+export { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthTokenRefreshError, OAuthTokenValidationError, OAuthTokenRevocationError, OAuthCallbackServerError, } from "../types/errors.js";
 export { createAnthropicOAuth, createAnthropicOAuthConfig, hasAnthropicOAuthCredentials, startCallbackServer, stopCallbackServer, performOAuthFlow, } from "./anthropicOAuth.js";
-export type { OAuthTokenResponse, OAuthFlowTokens, OAuthFlowTokens as OAuthTokens, TokenValidationResult, AnthropicOAuthConfig, PKCEParams, CallbackResult, } from "./anthropicOAuth.js";
+export type { OAuthTokenResponse, OAuthFlowTokens, OAuthFlowTokens as OAuthTokens, TokenValidationResult, AnthropicOAuthConfig, PKCEParams, CallbackResult, } from "../types/index.js";
 export { TokenStore, tokenStore, defaultTokenStore } from "./tokenStore.js";
-export { TokenStoreError } from "./tokenStore.js";
-export type { StoredOAuthTokens, OAuthTokens as StoredOAuthTokensLegacy, TokenRefresher, } from "./tokenStore.js";
-export type { NeuroLinkAuthOptions, AuthStatus, } from "../types/subscriptionTypes.js";
+export { TokenStoreError } from "../types/errors.js";
+export type { StoredOAuthTokens, TokenRefresher } from "../types/authTypes.js";
+export type { NeuroLinkAuthOptions, AuthStatus } from "../types/index.js";
+export { AccountPool } from "./accountPool.js";
+export type { ProxyAccount, AccountPoolConfig } from "../types/index.js";

package/dist/lib/auth/index.js

@@ -17,7 +17,7 @@ export { ANTHROPIC_OAUTH_BASE_URL, DEFAULT_SCOPES, DEFAULT_REDIRECT_URI, DEFAULT
 // Main OAuth class
 export { AnthropicOAuth } from "./anthropicOAuth.js";
 // OAuth error classes (canonical definitions in types/errors.ts)
-export { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthTokenRefreshError, OAuthTokenValidationError, OAuthTokenRevocationError, OAuthCallbackServerError, } from "./anthropicOAuth.js";
+export { OAuthError, OAuthConfigurationError, OAuthTokenExchangeError, OAuthTokenRefreshError, OAuthTokenValidationError, OAuthTokenRevocationError, OAuthCallbackServerError, } from "../types/errors.js";
 // OAuth helper functions
 export { createAnthropicOAuth, createAnthropicOAuthConfig, hasAnthropicOAuthCredentials, startCallbackServer, stopCallbackServer, performOAuthFlow, } from "./anthropicOAuth.js";
 // =============================================================================
@@ -26,5 +26,9 @@ export { createAnthropicOAuth, createAnthropicOAuthConfig, hasAnthropicOAuthCred
 // Main TokenStore class and instances
 export { TokenStore, tokenStore, defaultTokenStore } from "./tokenStore.js";
 // Token store error class (canonical definition in types/errors.ts)
-export { TokenStoreError } from "./tokenStore.js";
+export { TokenStoreError } from "../types/errors.js";
+// =============================================================================
+// ACCOUNT POOL - Multi-account rotation with cooldowns
+// =============================================================================
+export { AccountPool } from "./accountPool.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/auth/tokenStore.d.ts

@@ -12,32 +12,8 @@
  * - Automatic token refresh via configurable refresher functions
  * - Cross-platform support (Unix/macOS/Windows)
  */
-export { TokenStoreError } from "../types/errors.js";
-/**
- * OAuth tokens structure for storage.
- * Stricter version of OAuthTokens from subscriptionTypes with required fields.
- */
-export interface StoredOAuthTokens {
-    /** The access token for API authentication */
-    accessToken: string;
-    /** The refresh token for obtaining new access tokens (optional for some OAuth flows) */
-    refreshToken?: string;
-    /** Unix timestamp (ms) when the access token expires */
-    expiresAt: number;
-    /** Token type, typically "Bearer" */
-    tokenType: string;
-    /** Optional OAuth scopes granted */
-    scope?: string;
-}
-/**
- * @deprecated Use StoredOAuthTokens instead
- */
-export type OAuthTokens = StoredOAuthTokens;
-/**
- * Token refresher function type
- * Takes a refresh token and returns new tokens
- */
-export type TokenRefresher = (refreshToken: string) => Promise<StoredOAuthTokens>;
+import type { StoredOAuthTokens, TokenRefresher } from "../types/authTypes.js";
+export type { StoredOAuthTokens, TokenRefresher };
 /**
  * Secure token storage for OAuth tokens with multi-provider support
  *
@@ -76,12 +52,14 @@ export declare class TokenStore {
     private static readonly TOKEN_FILE;
     private static readonly FILE_PERMISSIONS;
     private static readonly DIR_PERMISSIONS;
-    /** Default expiration buffer: 5 minutes */
+    /** Default expiration buffer: 1 hour (proactive refresh before actual expiry) */
     private static readonly DEFAULT_EXPIRY_BUFFER_MS;
     private readonly storagePath;
     private readonly encryptionEnabled;
     private readonly encryptionKey;
     private readonly tokenRefreshers;
+    private readonly inFlightRefreshes;
+    private readonly _mutex;
     /**
      * Creates a new TokenStore instance
      *
@@ -107,6 +85,10 @@ export declare class TokenStore {
      * @throws TokenStoreError if storage fails
      */
     saveTokens(provider: string, tokens: StoredOAuthTokens): Promise<void>;
+    /**
+     * Internal save without mutex — callers must already hold the mutex.
+     */
+    private _saveTokensInternal;
     /**
      * Loads stored OAuth tokens for a specific provider
      *
@@ -115,6 +97,10 @@ export declare class TokenStore {
      * @throws TokenStoreError if reading fails (other than file not found)
      */
     loadTokens(provider: string): Promise<StoredOAuthTokens | null>;
+    /**
+     * Internal load without mutex — callers must already hold the mutex.
+     */
+    private _loadTokensInternal;
     /**
      * Clears stored tokens for a specific provider
      *
@@ -170,6 +156,64 @@ export declare class TokenStore {
      * @returns Array of provider names
      */
     listProviders(): Promise<string[]>;
+    /**
+     * Lists all provider keys that start with the given prefix
+     *
+     * @param prefix - The prefix to filter by (e.g., "anthropic:")
+     * @returns Array of matching provider keys
+     */
+    listByPrefix(prefix: string): Promise<string[]>;
+    /**
+     * Marks a provider's tokens as permanently disabled (persisted to disk).
+     *
+     * Disabled accounts are skipped immediately by consumers — no wasted
+     * round-trips. The state survives proxy restarts because it is stored
+     * alongside the tokens in the JSON file.
+     *
+     * @param provider - The provider key (e.g., "anthropic:user@example.com")
+     * @param reason - Optional human-readable reason (e.g., "refresh_failed")
+     */
+    markDisabled(provider: string, reason?: string): Promise<void>;
+    /**
+     * Re-enables a previously disabled provider (persisted to disk).
+     *
+     * Clears the disabled flag, timestamp, and reason so the account can
+     * be used again by the proxy pool.
+     *
+     * @param provider - The provider key (e.g., "anthropic:user@example.com")
+     */
+    markEnabled(provider: string): Promise<void>;
+    /**
+     * Checks whether a provider's tokens are currently disabled.
+     *
+     * Returns false for providers that don't exist in the store (no tokens
+     * at all) and for entries that predate the disabled field (backward compat).
+     *
+     * @param provider - The provider key
+     * @returns true if the provider entry exists and is disabled
+     */
+    isDisabled(provider: string): Promise<boolean>;
+    /**
+     * Lists all provider keys that are currently disabled.
+     *
+     * @returns Array of disabled provider keys (empty if none or no storage file)
+     */
+    listDisabled(): Promise<string[]>;
+    /**
+     * Removes expired and unrefreshable token entries from disk.
+     *
+     * An entry is pruned when:
+     *   - Its access token is expired (with optional buffer) AND it has no
+     *     refresh token, AND it is NOT manually disabled.
+     *
+     * Manually disabled entries are preserved so that `auth enable` can
+     * re-enable them later. They are only removed via explicit `clearTokens`.
+     *
+     * @param bufferMs - Extra buffer in milliseconds to subtract from expiresAt
+     *                   when checking expiry (default: 0 — strict expiry check)
+     * @returns Array of provider keys that were removed
+     */
+    pruneExpired(bufferMs?: number): Promise<string[]>;
     /**
      * Clears all stored tokens for all providers
      *