axauth 1.3.0 → 1.5.0

package/dist/auth/adapter.d.ts

@@ -73,6 +73,10 @@ interface RemoveOptions {
 interface TokenOptions {
     /** Provider ID for multi-provider agents (e.g., "anthropic", "openai") */
     provider?: string;
+    /** Skip auto-refresh even for expired tokens (default: false) */
+    skipRefresh?: boolean;
+    /** Timeout for refresh operation in ms (default: 10000) */
+    refreshTimeout?: number;
 }
 /** Capabilities that an adapter supports */
 interface AdapterCapabilities {
@@ -113,6 +117,13 @@ interface AuthAdapter {
      * Use {@link getAccessToken} to extract the token in a uniform way.
      */
     extractRawCredentials(): Credentials | undefined;
+    /**
+     * Extract raw credentials from a specific directory.
+     *
+     * Used by token refresh to read credentials from a temp directory.
+     * Returns undefined if no credentials found at that location.
+     */
+    extractRawCredentialsFromDirectory?(directory: string): Credentials | undefined;
     /**
      * Install credentials to storage.
      *

package/dist/auth/agents/claude.js

@@ -4,6 +4,7 @@
  * Supports OAuth via keychain (macOS) or file, and API key via env var.
  */
 import path from "node:path";
+import { extractCredsFromDirectory } from "../extract-creds-from-directory.js";
 import { isMacOS } from "../keychain.js";
 import { resolveCustomDirectory } from "../validate-directories.js";
 import { AGENT_ID, checkAuth, deleteFileCreds, deleteKeychainCreds, extractRawCredentials, getDefaultCredsFilePath, saveFileCreds, saveKeychainCreds, } from "./claude-storage.js";
@@ -27,6 +28,15 @@ const claudeCodeAdapter = {
             return undefined;
         return { agent: AGENT_ID, ...result };
     },
+    extractRawCredentialsFromDirectory(directory) {
+        // Unwrap claudeAiOauth wrapper (matches loadFileCreds behavior)
+        return extractCredsFromDirectory(AGENT_ID, directory, CREDS_FILE_NAME, (file) => {
+            const data = file.claudeAiOauth;
+            return typeof data === "object" && data !== null
+                ? data
+                : undefined;
+        });
+    },
     installCredentials(creds, options) {
         // Resolve custom directory with validation
         const resolved = resolveCustomDirectory(AGENT_ID, options?.configDir, options?.dataDir);

package/dist/auth/agents/codex.js

@@ -3,6 +3,7 @@
  *
  * Supports API key and OAuth via keychain (macOS) or file.
  */
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { ensureDirectory } from "../file-storage.js";
 import { isMacOS } from "../keychain.js";
@@ -23,6 +24,23 @@ const codexAdapter = {
     },
     checkAuth,
     extractRawCredentials,
+    extractRawCredentialsFromDirectory(directory) {
+        const credentialsPath = path.join(directory, CREDS_FILE_NAME);
+        try {
+            if (!existsSync(credentialsPath))
+                return undefined;
+            const parsed = JSON.parse(readFileSync(credentialsPath, "utf8"));
+            if (typeof parsed !== "object" || parsed === null)
+                return undefined;
+            const data = parsed;
+            // Determine type from data structure
+            const type = data.api_key ? "api-key" : "oauth";
+            return { agent: AGENT_ID, type, data };
+        }
+        catch {
+            return undefined;
+        }
+    },
     installCredentials(creds, options) {
         // Resolve custom directory with validation
         const resolved = resolveCustomDirectory(AGENT_ID, options?.configDir, options?.dataDir);

package/dist/auth/agents/copilot.js

@@ -5,6 +5,7 @@
  * Also supports GitHub CLI (`gh auth login`) as a fallback.
  */
 import path from "node:path";
+import { extractCredsFromDirectory } from "../extract-creds-from-directory.js";
 import { ensureDirectory } from "../file-storage.js";
 import { isMacOS } from "../keychain.js";
 import { resolveCustomDirectory } from "../validate-directories.js";
@@ -48,6 +49,9 @@ const copilotAdapter = {
             data: { accessToken: result.token, _source: result.source },
         };
     },
+    extractRawCredentialsFromDirectory(directory) {
+        return extractCredsFromDirectory(AGENT_ID, directory, CREDS_FILE_NAME);
+    },
     installCredentials(creds, options) {
         // Resolve custom directory with validation
         const resolved = resolveCustomDirectory(AGENT_ID, options?.configDir, options?.dataDir);

package/dist/auth/agents/gemini.js

@@ -3,6 +3,7 @@
  *
  * Supports OAuth via keychain (macOS) or file. API key auth is env-var only.
  */
+import { extractCredsFromDirectory } from "../extract-creds-from-directory.js";
 import { findCredentials } from "./gemini-auth-check.js";
 import { installOAuthCredentials, removeGeminiCredentials, } from "./gemini-install.js";
 const AGENT_ID = "gemini";
@@ -48,6 +49,9 @@ const geminiAdapter = {
             },
         };
     },
+    extractRawCredentialsFromDirectory(directory) {
+        return extractCredsFromDirectory(AGENT_ID, directory, "oauth_creds.json");
+    },
     installCredentials(creds, options) {
         if (creds.type === "api-key") {
             return {

package/dist/auth/agents/opencode.js

@@ -9,6 +9,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import path from "node:path";
+import { extractCredsFromDirectory } from "../extract-creds-from-directory.js";
 import { resolveAgentDataDirectory } from "axshared";
 import { resolveCustomDirectory } from "../validate-directories.js";
 import { extractTokenFromEntry, OpenCodeAuth } from "./opencode-schema.js";
@@ -82,6 +83,10 @@ const opencodeAdapter = {
         }
         return undefined;
     },
+    extractRawCredentialsFromDirectory(directory) {
+        // Only return if there's at least one provider
+        return extractCredsFromDirectory(AGENT_ID, directory, CREDS_FILE_NAME, (data) => (Object.keys(data).length > 0 ? data : undefined));
+    },
     installCredentials(creds, options) {
         // Resolve custom directory with validation (OpenCode supports separation)
         const resolved = resolveCustomDirectory(AGENT_ID, options?.configDir, options?.dataDir);

package/dist/auth/extract-creds-from-directory.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Common utility for extracting credentials from a directory.
+ */
+import type { AgentCli } from "axshared";
+import type { Credentials } from "./types.js";
+/**
+ * Extract credentials from a JSON file in a directory.
+ *
+ * @param agentId - The agent ID
+ * @param directory - Directory to read from
+ * @param fileName - Name of the credentials file
+ * @param transform - Optional transform to apply to file contents
+ * @returns Credentials or undefined if not found
+ */
+declare function extractCredsFromDirectory(agentId: AgentCli, directory: string, fileName: string, transform?: (data: Record<string, unknown>) => Record<string, unknown> | undefined): Credentials | undefined;
+export { extractCredsFromDirectory };

package/dist/auth/extract-creds-from-directory.js

@@ -0,0 +1,37 @@
+/**
+ * Common utility for extracting credentials from a directory.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Extract credentials from a JSON file in a directory.
+ *
+ * @param agentId - The agent ID
+ * @param directory - Directory to read from
+ * @param fileName - Name of the credentials file
+ * @param transform - Optional transform to apply to file contents
+ * @returns Credentials or undefined if not found
+ */
+function extractCredsFromDirectory(agentId, directory, fileName, transform) {
+    const credentialsPath = path.join(directory, fileName);
+    try {
+        if (!existsSync(credentialsPath))
+            return undefined;
+        const fileContent = JSON.parse(readFileSync(credentialsPath, "utf8"));
+        // JSON.parse can return null, primitives, or arrays - we need an object
+        if (typeof fileContent !== "object" ||
+            fileContent === null ||
+            Array.isArray(fileContent)) {
+            return undefined;
+        }
+        const record = fileContent;
+        const data = transform ? transform(record) : record;
+        if (!data)
+            return undefined;
+        return { agent: agentId, type: "oauth", data };
+    }
+    catch {
+        return undefined;
+    }
+}
+export { extractCredsFromDirectory };

package/dist/auth/is-token-expired.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Token and credential expiry check utilities.
+ */
+/**
+ * Check if a JWT token is expired.
+ *
+ * Decodes the JWT payload and checks the `exp` claim against current time.
+ *
+ * @param token - The JWT token string
+ * @param bufferSeconds - Buffer before actual expiry (default: 60s)
+ * @returns true if expired, false if valid, undefined if not a valid JWT
+ */
+declare function isTokenExpired(token: string, bufferSeconds?: number): boolean | undefined;
+/**
+ * Check if credentials have expired using explicit timestamp fields.
+ *
+ * Checks common OAuth credential expiry fields like `expiry_date` (Google)
+ * or `expires_at` (generic). Useful for opaque tokens that aren't JWTs.
+ *
+ * @param data - The credential data object
+ * @param bufferSeconds - Buffer before actual expiry (default: 60s)
+ * @returns true if expired, false if valid, undefined if no expiry field found
+ */
+declare function isCredentialExpired(data: Record<string, unknown>, bufferSeconds?: number): boolean | undefined;
+export { isCredentialExpired, isTokenExpired };

package/dist/auth/is-token-expired.js

@@ -0,0 +1,77 @@
+/**
+ * Token and credential expiry check utilities.
+ */
+/**
+ * Timestamp threshold to distinguish seconds from milliseconds.
+ *
+ * Values below this are assumed to be Unix timestamps in seconds,
+ * values above are assumed to be milliseconds.
+ *
+ * 10 billion seconds ≈ year 2286, so any current timestamp in
+ * seconds will be below this threshold.
+ */
+const SECONDS_THRESHOLD = 10_000_000_000;
+/**
+ * Check if a JWT token is expired.
+ *
+ * Decodes the JWT payload and checks the `exp` claim against current time.
+ *
+ * @param token - The JWT token string
+ * @param bufferSeconds - Buffer before actual expiry (default: 60s)
+ * @returns true if expired, false if valid, undefined if not a valid JWT
+ */
+function isTokenExpired(token, bufferSeconds = 60) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return undefined; // Not a JWT
+    const payloadPart = parts[1];
+    if (!payloadPart)
+        return undefined;
+    try {
+        // Convert base64url to standard base64 (JWTs use base64url encoding)
+        const base64 = payloadPart.replaceAll("-", "+").replaceAll("_", "/");
+        const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
+        const payload = JSON.parse(atob(padded));
+        const exp = payload.exp;
+        if (typeof exp !== "number")
+            return undefined; // No exp claim
+        const nowSeconds = Date.now() / 1000;
+        return nowSeconds > exp - bufferSeconds;
+    }
+    catch {
+        return undefined; // Invalid JWT
+    }
+}
+/**
+ * Check if credentials have expired using explicit timestamp fields.
+ *
+ * Checks common OAuth credential expiry fields like `expiry_date` (Google)
+ * or `expires_at` (generic). Useful for opaque tokens that aren't JWTs.
+ *
+ * @param data - The credential data object
+ * @param bufferSeconds - Buffer before actual expiry (default: 60s)
+ * @returns true if expired, false if valid, undefined if no expiry field found
+ */
+function isCredentialExpired(data, bufferSeconds = 60) {
+    // Check common expiry field names (in order of preference)
+    // expiry_date: Google OAuth (milliseconds)
+    // expires_at: Generic OAuth (seconds or milliseconds)
+    const expiryDate = data.expiry_date;
+    const expiresAt = data.expires_at;
+    let expiryTimestampMs;
+    if (typeof expiryDate === "number") {
+        // Google uses milliseconds
+        expiryTimestampMs = expiryDate;
+    }
+    else if (typeof expiresAt === "number") {
+        // Could be seconds or milliseconds - heuristic based on SECONDS_THRESHOLD
+        expiryTimestampMs =
+            expiresAt < SECONDS_THRESHOLD ? expiresAt * 1000 : expiresAt;
+    }
+    if (expiryTimestampMs === undefined)
+        return undefined;
+    const nowMs = Date.now();
+    const bufferMs = bufferSeconds * 1000;
+    return nowMs > expiryTimestampMs - bufferMs;
+}
+export { isCredentialExpired, isTokenExpired };

package/dist/auth/refresh-credentials.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Token refresh via agent subprocess.
+ *
+ * Refreshes credentials by running the agent in an isolated temp config,
+ * triggering its internal auth refresh mechanism.
+ */
+import type { Credentials } from "./types.js";
+/** Options for credential refresh */
+interface RefreshOptions {
+    /** Timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Provider for multi-provider agents (OpenCode) */
+    provider?: string;
+}
+/** Result of a credential refresh attempt */
+type RefreshResult = {
+    ok: true;
+    credentials: Credentials;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Refresh credentials by spawning the agent briefly.
+ *
+ * Creates an isolated temp config directory, installs credentials there,
+ * and runs the agent with a minimal prompt to trigger its internal refresh.
+ *
+ * @param creds - The credentials to refresh (must contain refresh_token for OAuth)
+ * @param options - Refresh options (timeout, provider for multi-provider agents)
+ * @returns RefreshResult with new credentials or error
+ */
+declare function refreshCredentials(creds: Credentials, options?: RefreshOptions): Promise<RefreshResult>;
+/** Result of refresh and persist operation */
+type RefreshAndPersistResult = {
+    ok: true;
+    credentials: Credentials;
+} | {
+    ok: false;
+    staleCredentials: Credentials;
+};
+/**
+ * Refresh credentials and persist to original storage.
+ *
+ * Higher-level function that:
+ * 1. Refreshes credentials via agent subprocess
+ * 2. Preserves _source marker from original credentials
+ * 3. Persists refreshed credentials to original storage location
+ *
+ * @param creds - Original credentials with _source marker
+ * @param installFunction - Function to install credentials (avoids circular import)
+ * @param options - Refresh options
+ * @returns Refreshed credentials or original credentials on failure
+ */
+declare function refreshAndPersist(creds: Credentials, installFunction: (c: Credentials) => {
+    ok: boolean;
+    message: string;
+}, options?: RefreshOptions): Promise<RefreshAndPersistResult>;
+export { refreshAndPersist, refreshCredentials };
+export type { RefreshAndPersistResult, RefreshOptions, RefreshResult };

package/dist/auth/refresh-credentials.js

@@ -0,0 +1,150 @@
+/**
+ * Token refresh via agent subprocess.
+ *
+ * Refreshes credentials by running the agent in an isolated temp config,
+ * triggering its internal auth refresh mechanism.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { buildAgentRuntimeEnvironment, getAgent, getAgentConfigSubdirectory, } from "axshared";
+import { spawnAgent } from "./spawn-agent.js";
+/** Default timeout for refresh operations in milliseconds */
+const DEFAULT_REFRESH_TIMEOUT_MS = 30_000;
+/**
+ * Write agent-specific config to force file-based storage.
+ *
+ * This prevents the agent from using keychain credentials,
+ * ensuring it reads/writes from our temp directory.
+ */
+function writeForceFileConfig(agentId, temporaryDirectory) {
+    switch (agentId) {
+        case "codex": {
+            // Codex uses config.toml with cli_auth_credentials_store setting
+            writeFileSync(path.join(temporaryDirectory, "config.toml"), 'cli_auth_credentials_store = "file"\nmcp_oauth_credentials_store = "file"\n');
+            break;
+        }
+        case "copilot": {
+            // Copilot uses JSON config with store_token_plaintext flag
+            writeFileSync(path.join(temporaryDirectory, "config.json"), JSON.stringify({ store_token_plaintext: true }, undefined, 2));
+            break;
+        }
+        // Claude: keychain service name includes hash of CLAUDE_CONFIG_DIR,
+        //         so unique temp dir = unique keychain entry that won't exist
+        // Gemini: file storage behavior is controlled via the GEMINI_FORCE_FILE_STORAGE
+        //         environment variable, which is set by buildAgentRuntimeEnvironment and
+        //         later included in fullEnvironment when spawning the agent.
+        // OpenCode: file-only by design, no action needed
+    }
+}
+/**
+ * Refresh credentials by spawning the agent briefly.
+ *
+ * Creates an isolated temp config directory, installs credentials there,
+ * and runs the agent with a minimal prompt to trigger its internal refresh.
+ *
+ * @param creds - The credentials to refresh (must contain refresh_token for OAuth)
+ * @param options - Refresh options (timeout, provider for multi-provider agents)
+ * @returns RefreshResult with new credentials or error
+ */
+async function refreshCredentials(creds, options) {
+    const timeout = options?.timeout ?? DEFAULT_REFRESH_TIMEOUT_MS;
+    const agent = getAgent(creds.agent);
+    // 1. Create temp config directory
+    const temporaryDirectory = mkdtempSync(path.join(tmpdir(), `axauth-refresh-${creds.agent}-`));
+    try {
+        // 2. Determine where credentials should be installed
+        // Some agents (Gemini, Copilot, OpenCode) require a subdirectory structure
+        const subdirectory = getAgentConfigSubdirectory(creds.agent);
+        const credentialsDirectory = subdirectory
+            ? path.join(temporaryDirectory, subdirectory)
+            : temporaryDirectory;
+        // 3. Ensure credentials directory exists before writing config
+        mkdirSync(credentialsDirectory, { recursive: true });
+        // 4. Write agent-specific config to force file storage
+        writeForceFileConfig(creds.agent, credentialsDirectory);
+        // 5. Install credentials to the appropriate directory
+        // Import dynamically to avoid circular dependency
+        const { installCredentials } = await import("./registry.js");
+        const installResult = installCredentials(creds, {
+            configDir: credentialsDirectory,
+            dataDir: credentialsDirectory,
+        });
+        if (!installResult.ok) {
+            return {
+                ok: false,
+                error: `Failed to install credentials: ${installResult.message}`,
+            };
+        }
+        // 6. Build runtime environment
+        // Pass the full credentialsDirectory (which may include an agent-specific
+        // subdirectory, e.g. "~/.gemini/"); buildAgentRuntimeEnvironment will
+        // derive the parent directory internally for agents that use subdirectories.
+        const runtimeEnvironment = buildAgentRuntimeEnvironment(creds.agent, credentialsDirectory);
+        const fullEnvironment = {
+            ...process.env,
+            ...runtimeEnvironment,
+        };
+        // 7. Build CLI arguments using simplePromptArguments from agent
+        const cliArguments = agent.simplePromptArguments("ping", {
+            provider: options?.provider,
+        });
+        // 8. Spawn agent with minimal prompt
+        const { timedOut } = await spawnAgent(agent.cli, cliArguments, fullEnvironment, timeout);
+        if (timedOut) {
+            return { ok: false, error: "Refresh timed out" };
+        }
+        // 9. Read refreshed credentials from temp directory
+        const { extractRawCredentialsFromDirectory } = await import("./registry.js");
+        const refreshedCredentials = extractRawCredentialsFromDirectory(creds.agent, credentialsDirectory);
+        if (!refreshedCredentials) {
+            return { ok: false, error: "No credentials found after refresh" };
+        }
+        return { ok: true, credentials: refreshedCredentials };
+    }
+    finally {
+        // 10. Clean up temp directory
+        try {
+            rmSync(temporaryDirectory, { recursive: true, force: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Warning: Failed to clean up temp directory '${temporaryDirectory}': ${message}`);
+        }
+    }
+}
+/**
+ * Refresh credentials and persist to original storage.
+ *
+ * Higher-level function that:
+ * 1. Refreshes credentials via agent subprocess
+ * 2. Preserves _source marker from original credentials
+ * 3. Persists refreshed credentials to original storage location
+ *
+ * @param creds - Original credentials with _source marker
+ * @param installFunction - Function to install credentials (avoids circular import)
+ * @param options - Refresh options
+ * @returns Refreshed credentials or original credentials on failure
+ */
+async function refreshAndPersist(creds, installFunction, options) {
+    const result = await refreshCredentials(creds, options);
+    if (!result.ok) {
+        console.error(`Warning: Token refresh failed: ${result.error}`);
+        return { ok: false, staleCredentials: creds };
+    }
+    // Preserve _source marker so credentials are saved to the same location
+    const refreshedCreds = {
+        ...result.credentials,
+        data: {
+            ...result.credentials.data,
+            _source: creds.data._source,
+        },
+    };
+    // Persist refreshed credentials back to storage
+    const installResult = installFunction(refreshedCreds);
+    if (!installResult.ok) {
+        console.error(`Warning: Failed to save refreshed credentials: ${installResult.message}`);
+    }
+    return { ok: true, credentials: refreshedCreds };
+}
+export { refreshAndPersist, refreshCredentials };

package/dist/auth/registry.d.ts

@@ -59,6 +59,16 @@ declare function checkAllAuth(): AuthStatus[];
  * if (creds) { await exportCredentials(creds); }
  */
 declare function extractRawCredentials(agentId: AgentCli): Credentials | undefined;
+/**
+ * Extract raw credentials from a specific directory.
+ *
+ * Used by token refresh to read credentials from a temp directory.
+ * Returns undefined if no credentials found or adapter doesn't support it.
+ *
+ * @example
+ * const creds = extractRawCredentialsFromDirectory("claude", "/tmp/refresh-123");
+ */
+declare function extractRawCredentialsFromDirectory(agentId: AgentCli, directory: string): Credentials | undefined;
 /**
  * Install credentials for an agent.
  *
@@ -82,29 +92,26 @@ declare function installCredentials(creds: Credentials, options?: InstallOptions
  */
 declare function removeCredentials(agentId: AgentCli, options?: RemoveOptions): OperationResult;
 /**
- * Get access token from credentials.
+ * Extract access token from credentials.
  *
- * For multi-provider agents (like opencode), use `options.provider`
- * to specify which provider's token to extract.
+ * For OAuth tokens, automatically refreshes if expired.
+ * For API keys, returns immediately (no expiry).
  *
  * @example
- * const token = getAccessToken(creds);
- * if (token) { headers.Authorization = `Bearer ${token}`; }
- *
- * // For multi-provider agents
- * const token = getAccessToken(creds, { provider: "anthropic" });
+ * const token = await getAccessToken(creds);
+ * const token = await getAccessToken(creds, { skipRefresh: true });
  */
-declare function getAccessToken(creds: Credentials, options?: TokenOptions): string | undefined;
+declare function getAccessToken(creds: Credentials, options?: TokenOptions): Promise<string | undefined>;
 /**
- * Get access token for an agent (convenience function).
+ * Get access token for an agent by ID.
  *
- * Extracts credentials and returns the access token in one call.
+ * Convenience function that extracts credentials and gets the token.
+ * Automatically refreshes expired OAuth tokens.
  *
  * @example
- * const token = getAgentAccessToken("claude");
- * if (token) { ... }
+ * const token = await getAgentAccessToken("claude");
  */
-declare function getAgentAccessToken(agentId: AgentCli): string | undefined;
+declare function getAgentAccessToken(agentId: AgentCli, options?: TokenOptions): Promise<string | undefined>;
 /**
  * Convert credentials to environment variables.
  *
@@ -153,4 +160,4 @@ declare function installCredentialsFromEnvironmentVariable(agent: AgentCli, opti
     error: string;
 }>;
 export type { InstallFromEnvironmentOptions };
-export { checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, getAccessToken, getAdapter, getAgentAccessToken, getAllAdapters, getCapabilities, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, };
+export { checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, extractRawCredentialsFromDirectory, getAccessToken, getAdapter, getAgentAccessToken, getAllAdapters, getCapabilities, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, };

package/dist/auth/registry.js

@@ -10,6 +10,8 @@ import { codexAdapter } from "./agents/codex.js";
 import { copilotAdapter } from "./agents/copilot.js";
 import { geminiAdapter } from "./agents/gemini.js";
 import { opencodeAdapter } from "./agents/opencode.js";
+import { isCredentialExpired, isTokenExpired } from "./is-token-expired.js";
+import { refreshAndPersist } from "./refresh-credentials.js";
 import { parseCredentials } from "./types.js";
 /** Registry of all adapters by agent ID */
 const ADAPTERS = {
@@ -83,6 +85,19 @@ function checkAllAuth() {
 function extractRawCredentials(agentId) {
     return ADAPTERS[agentId].extractRawCredentials();
 }
+/**
+ * Extract raw credentials from a specific directory.
+ *
+ * Used by token refresh to read credentials from a temp directory.
+ * Returns undefined if no credentials found or adapter doesn't support it.
+ *
+ * @example
+ * const creds = extractRawCredentialsFromDirectory("claude", "/tmp/refresh-123");
+ */
+function extractRawCredentialsFromDirectory(agentId, directory) {
+    const adapter = ADAPTERS[agentId];
+    return adapter.extractRawCredentialsFromDirectory?.(directory);
+}
 /**
  * Install credentials for an agent.
  *
@@ -110,35 +125,56 @@ function removeCredentials(agentId, options) {
     return ADAPTERS[agentId].removeCredentials(options);
 }
 /**
- * Get access token from credentials.
+ * Extract access token from credentials.
  *
- * For multi-provider agents (like opencode), use `options.provider`
- * to specify which provider's token to extract.
+ * For OAuth tokens, automatically refreshes if expired.
+ * For API keys, returns immediately (no expiry).
  *
  * @example
- * const token = getAccessToken(creds);
- * if (token) { headers.Authorization = `Bearer ${token}`; }
- *
- * // For multi-provider agents
- * const token = getAccessToken(creds, { provider: "anthropic" });
+ * const token = await getAccessToken(creds);
+ * const token = await getAccessToken(creds, { skipRefresh: true });
  */
-function getAccessToken(creds, options) {
-    return ADAPTERS[creds.agent].getAccessToken(creds, options);
+async function getAccessToken(creds, options) {
+    const token = ADAPTERS[creds.agent].getAccessToken(creds, options);
+    // No token found
+    if (!token)
+        return undefined;
+    // API keys don't expire
+    if (creds.type === "api-key")
+        return token;
+    // Skip refresh if requested
+    if (options?.skipRefresh)
+        return token;
+    // Check if token is expired (try JWT first, then credential fields)
+    let expired = isTokenExpired(token);
+    if (expired === undefined) {
+        // Token isn't a JWT - check credential's explicit expiry fields
+        expired = isCredentialExpired(creds.data);
+    }
+    if (expired !== true)
+        return token; // Valid or no expiry info
+    // Refresh and persist
+    const result = await refreshAndPersist(creds, installCredentials, {
+        timeout: options?.refreshTimeout,
+        provider: options?.provider,
+    });
+    const finalCreds = result.ok ? result.credentials : result.staleCredentials;
+    return ADAPTERS[creds.agent].getAccessToken(finalCreds, options);
 }
 /**
- * Get access token for an agent (convenience function).
+ * Get access token for an agent by ID.
  *
- * Extracts credentials and returns the access token in one call.
+ * Convenience function that extracts credentials and gets the token.
+ * Automatically refreshes expired OAuth tokens.
  *
  * @example
- * const token = getAgentAccessToken("claude");
- * if (token) { ... }
+ * const token = await getAgentAccessToken("claude");
  */
-function getAgentAccessToken(agentId) {
+async function getAgentAccessToken(agentId, options) {
     const creds = extractRawCredentials(agentId);
     if (!creds)
         return undefined;
-    return getAccessToken(creds);
+    return getAccessToken(creds, options);
 }
 /**
  * Convert credentials to environment variables.
@@ -228,4 +264,4 @@ async function installCredentialsFromEnvironmentVariable(agent, options) {
     }
     return { ok: true };
 }
-export { checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, getAccessToken, getAdapter, getAgentAccessToken, getAllAdapters, getCapabilities, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, };
+export { checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, extractRawCredentialsFromDirectory, getAccessToken, getAdapter, getAgentAccessToken, getAllAdapters, getCapabilities, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, };

package/dist/auth/spawn-agent.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Agent subprocess spawning utility.
+ */
+/**
+ * Spawn agent and wait for completion.
+ *
+ * @returns Object with timedOut flag and exit code
+ */
+declare function spawnAgent(binary: string, arguments_: string[], environment: NodeJS.ProcessEnv, timeout: number): Promise<{
+    timedOut: boolean;
+    exitCode: number | null;
+}>;
+export { spawnAgent };

package/dist/auth/spawn-agent.js

@@ -0,0 +1,40 @@
+/**
+ * Agent subprocess spawning utility.
+ */
+import { spawn } from "node:child_process";
+/**
+ * Spawn agent and wait for completion.
+ *
+ * @returns Object with timedOut flag and exit code
+ */
+async function spawnAgent(binary, arguments_, environment, timeout) {
+    return new Promise((resolve) => {
+        const child = spawn(binary, arguments_, {
+            env: environment,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let timedOut = false;
+        let resolved = false;
+        const timer = setTimeout(() => {
+            if (!resolved) {
+                timedOut = true;
+                child.kill("SIGTERM");
+            }
+        }, timeout);
+        child.on("error", () => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(timer);
+                resolve({ timedOut: false, exitCode: 1 });
+            }
+        });
+        child.on("close", (code) => {
+            if (!resolved) {
+                resolved = true;
+                clearTimeout(timer);
+                resolve({ timedOut, exitCode: code });
+            }
+        });
+    });
+}
+export { spawnAgent };

package/dist/commands/auth.d.ts

@@ -10,7 +10,7 @@ declare function handleAuthList(options: {
 declare function handleAuthToken(options: {
     agent: string;
     provider?: string;
-}): void;
+}): Promise<void>;
 interface AuthExportOptions {
     agent: string;
     output: string;

package/dist/commands/auth.js

@@ -18,7 +18,7 @@ function handleAuthList(options) {
     }
 }
 /** Handle auth token command */
-function handleAuthToken(options) {
+async function handleAuthToken(options) {
     const agentId = validateAgent(options.agent);
     if (!agentId)
         return;
@@ -29,7 +29,7 @@ function handleAuthToken(options) {
         return;
     }
     // Extract the token based on credential type
-    const token = getAccessToken(creds, { provider: options.provider });
+    const token = await getAccessToken(creds, { provider: options.provider });
     if (!token) {
         const providerHint = options.provider
             ? ` for provider '${options.provider}'`

package/dist/index.d.ts

@@ -35,3 +35,5 @@ export { AGENT_CLIS } from "axshared";
 export type { AdapterCapabilities, AuthAdapter, InstallOptions, OperationResult, RemoveOptions, } from "./auth/adapter.js";
 export type { AuthStatus, Credentials } from "./auth/types.js";
 export { checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, getAccessToken, getAgentAccessToken, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, getAdapter, getAllAdapters, getCapabilities, type InstallFromEnvironmentOptions, } from "./auth/registry.js";
+export { isCredentialExpired, isTokenExpired, } from "./auth/is-token-expired.js";
+export { refreshAndPersist, refreshCredentials, type RefreshAndPersistResult, type RefreshOptions, type RefreshResult, } from "./auth/refresh-credentials.js";

package/dist/index.js

@@ -37,3 +37,6 @@ export {
 checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, getAccessToken, getAgentAccessToken, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, 
 // Adapter access
 getAdapter, getAllAdapters, getCapabilities, } from "./auth/registry.js";
+// Token refresh utilities
+export { isCredentialExpired, isTokenExpired, } from "./auth/is-token-expired.js";
+export { refreshAndPersist, refreshCredentials, } from "./auth/refresh-credentials.js";

package/package.json

@@ -2,7 +2,7 @@
   "name": "axauth",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Authentication management library and CLI for AI coding agents",
   "repository": {
     "type": "git",
@@ -70,7 +70,7 @@
     "@commander-js/extra-typings": "^14.0.0",
     "@inquirer/password": "^5.0.3",
     "axconfig": "^3.2.0",
-    "axshared": "^1.5.0",
+    "axshared": "^1.7.0",
     "commander": "^14.0.2",
     "zod": "^4.3.4"
   },