axauth 1.2.0 → 1.4.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,14 @@
+/**
+ * JWT token expiry check utility.
+ */
+/**
+ * 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;
+export { isTokenExpired };

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

@@ -0,0 +1,35 @@
+/**
+ * JWT token expiry check utility.
+ */
+/**
+ * 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
+    }
+}
+export { 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: 10000) */
+    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,140 @@
+/**
+ * Token refresh via agent subprocess.
+ *
+ * Refreshes credentials by running the agent in an isolated temp config,
+ * triggering its internal auth refresh mechanism.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { buildAgentRuntimeEnvironment, getAgent, } from "axshared";
+import { spawnAgent } from "./spawn-agent.js";
+/** Default timeout for refresh operations in milliseconds */
+const DEFAULT_REFRESH_TIMEOUT_MS = 10_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: handled via GEMINI_FORCE_FILE_STORAGE env var in spawn
+        // 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. Write agent-specific config to force file storage
+        writeForceFileConfig(creds.agent, temporaryDirectory);
+        // 3. Install credentials to temp directory
+        // Import dynamically to avoid circular dependency
+        const { installCredentials } = await import("./registry.js");
+        const installResult = installCredentials(creds, {
+            configDir: temporaryDirectory,
+            dataDir: temporaryDirectory,
+        });
+        if (!installResult.ok) {
+            return {
+                ok: false,
+                error: `Failed to install credentials: ${installResult.message}`,
+            };
+        }
+        // 4. Build runtime environment pointing to temp directory
+        const runtimeEnvironment = buildAgentRuntimeEnvironment(creds.agent, temporaryDirectory);
+        // 5. Add force-file env vars where needed
+        const forceFileEnvironment = creds.agent === "gemini" ? { GEMINI_FORCE_FILE_STORAGE: "true" } : {};
+        const fullEnvironment = {
+            ...process.env,
+            ...runtimeEnvironment,
+            ...forceFileEnvironment,
+        };
+        // 6. Build CLI arguments using simplePromptArguments from agent
+        const cliArguments = agent.simplePromptArguments("ping", {
+            provider: options?.provider,
+        });
+        // 7. Spawn agent with minimal prompt
+        const { timedOut } = await spawnAgent(agent.cli, cliArguments, fullEnvironment, timeout);
+        if (timedOut) {
+            return { ok: false, error: "Refresh timed out" };
+        }
+        // 8. Read refreshed credentials from temp directory
+        const { extractRawCredentialsFromDirectory } = await import("./registry.js");
+        const refreshedCredentials = extractRawCredentialsFromDirectory(creds.agent, temporaryDirectory);
+        if (!refreshedCredentials) {
+            return { ok: false, error: "No credentials found after refresh" };
+        }
+        return { ok: true, credentials: refreshedCredentials };
+    }
+    finally {
+        // 9. 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.
  *
@@ -119,6 +126,13 @@ declare function credentialsToEnvironment(creds: Credentials): Record<string, st
  * Pattern: AX_<AGENT>_CREDENTIALS (e.g., AX_GEMINI_CREDENTIALS)
  */
 declare function getCredentialsEnvironmentVariableName(agent: AgentCli): string;
+/** Options for installing credentials from environment variable */
+interface InstallFromEnvironmentOptions {
+    /** Custom config directory */
+    configDir?: string;
+    /** Custom data directory */
+    dataDir?: string;
+}
 /**
  * Install credentials from environment variable.
  *
@@ -132,15 +146,18 @@ declare function getCredentialsEnvironmentVariableName(agent: AgentCli): string;
  *
  * @example
  * // In CI/CD, set: AX_GEMINI_CREDENTIALS=$(cat creds.json)
- * const result = await installCredentialsFromEnvironmentVariable("gemini", "/tmp/.gemini");
+ * const result = await installCredentialsFromEnvironmentVariable("gemini", {
+ *   configDir: "/tmp/.gemini",
+ * });
  * if (!result.ok) {
  *   console.error(result.error);
  * }
  */
-declare function installCredentialsFromEnvironmentVariable(agent: AgentCli, configDirectory: string): Promise<{
+declare function installCredentialsFromEnvironmentVariable(agent: AgentCli, options?: InstallFromEnvironmentOptions): Promise<{
     ok: true;
 } | {
     ok: false;
     error: string;
 }>;
-export { checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, getAccessToken, getAdapter, getAgentAccessToken, getAllAdapters, getCapabilities, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, };
+export type { InstallFromEnvironmentOptions };
+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 { 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,52 @@ 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
+    const expired = isTokenExpired(token);
+    if (expired !== true)
+        return token; // Valid or not a JWT
+    // 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.
@@ -171,12 +203,14 @@ function getCredentialsEnvironmentVariableName(agent) {
  *
  * @example
  * // In CI/CD, set: AX_GEMINI_CREDENTIALS=$(cat creds.json)
- * const result = await installCredentialsFromEnvironmentVariable("gemini", "/tmp/.gemini");
+ * const result = await installCredentialsFromEnvironmentVariable("gemini", {
+ *   configDir: "/tmp/.gemini",
+ * });
  * if (!result.ok) {
  *   console.error(result.error);
  * }
  */
-async function installCredentialsFromEnvironmentVariable(agent, configDirectory) {
+async function installCredentialsFromEnvironmentVariable(agent, options) {
     const environmentVariableName = getCredentialsEnvironmentVariableName(agent);
     const environmentValue = process.env[environmentVariableName];
     if (!environmentValue) {
@@ -218,11 +252,12 @@ async function installCredentialsFromEnvironmentVariable(agent, configDirectory)
     }
     // Install credentials to config directory
     const result = installCredentials(credentials, {
-        configDir: configDirectory,
+        configDir: options?.configDir,
+        dataDir: options?.dataDir,
     });
     if (!result.ok) {
         return { ok: false, error: result.message };
     }
     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

@@ -34,4 +34,6 @@ export type { AgentCli } from "axshared";
 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, } from "./auth/registry.js";
+export { checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, getAccessToken, getAgentAccessToken, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, getAdapter, getAllAdapters, getCapabilities, type InstallFromEnvironmentOptions, } from "./auth/registry.js";
+export { 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 { 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.2.0",
+  "version": "1.4.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.6.0",
     "commander": "^14.0.2",
     "zod": "^4.3.4"
   },