axauth 1.8.0 → 1.9.0

package/README.md

@@ -253,7 +253,7 @@ src/
 
 ## Related Packages
 
-axauth is part of the [a╳point](https://axpoint.dev) ecosystem:
+axauth is part of the [a╳kit](https://axkit.dev) ecosystem:
 
 - **axshared** - Shared types and agent metadata
 - **axconfig** - Permission and configuration management

package/dist/auth/adapter.d.ts

@@ -111,6 +111,18 @@ interface AdapterCapabilities {
  *
  * Encapsulates all auth operations for a single agent, hiding the
  * complexity of different storage mechanisms and credential formats.
+ *
+ * ## Credential Source Priority
+ *
+ * When resolving credentials, sources are checked in this order:
+ *
+ * 1. **Environment variables** (via `extractFromEnvironment`)
+ * 2. **Vault** (external, via axvault server when configured)
+ * 3. **Local storage** (keychain/file via `extractRawCredentials`)
+ *
+ * Environment variables always take precedence to allow easy overrides
+ * in CI/CD and development. Vault provides centralized credential
+ * management. Local storage is the fallback for interactive use.
  */
 interface AuthAdapter {
     /** Agent identifier */
@@ -124,6 +136,19 @@ interface AuthAdapter {
      * and returns the status without making API calls.
      */
     checkAuth(): AuthStatus;
+    /**
+     * Extract credentials from environment variables only.
+     *
+     * This is called before checking vault or local storage to ensure
+     * environment variables have highest priority. Returns undefined if
+     * no credentials are set via environment variables.
+     *
+     * @example
+     * // For Claude, checks CLAUDE_CODE_OAUTH_TOKEN and ANTHROPIC_API_KEY
+     * const envCreds = adapter.extractFromEnvironment?.();
+     * if (envCreds) return envCreds; // Env vars win over vault
+     */
+    extractFromEnvironment?(): Credentials | undefined;
     /**
      * Extract raw credentials for export.
      *

package/dist/auth/agents/claude-storage.d.ts

@@ -18,9 +18,19 @@ declare function checkAuth(): {
     method?: string;
     details?: Record<string, unknown>;
 };
+/**
+ * Extract credentials from environment variables only.
+ *
+ * This is called before checking vault or local storage to ensure
+ * environment variables have highest priority.
+ */
+declare function extractFromEnvironment(): {
+    type: "oauth-credentials" | "oauth-token" | "api-key";
+    data: Record<string, unknown>;
+} | undefined;
 /** Extract raw credentials from available sources */
 declare function extractRawCredentials(): {
-    type: "oauth" | "api-key";
+    type: "oauth-credentials" | "oauth-token" | "api-key";
     data: Record<string, unknown>;
 } | undefined;
-export { AGENT_ID, checkAuth, deleteFileCreds, deleteKeychainCreds, extractRawCredentials, getDefaultCredsFilePath, saveFileCreds, saveKeychainCreds, };
+export { AGENT_ID, checkAuth, deleteFileCreds, deleteKeychainCreds, extractFromEnvironment, extractRawCredentials, getDefaultCredsFilePath, saveFileCreds, saveKeychainCreds, };

package/dist/auth/agents/claude-storage.js

@@ -81,34 +81,57 @@ function checkAuth() {
     }
     return { authenticated: false };
 }
-/** Extract raw credentials from available sources */
-function extractRawCredentials() {
+/**
+ * Extract credentials from environment variables only.
+ *
+ * This is called before checking vault or local storage to ensure
+ * environment variables have highest priority.
+ */
+function extractFromEnvironment() {
     if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
         return {
-            type: "oauth",
+            type: "oauth-token",
             data: { accessToken: process.env.CLAUDE_CODE_OAUTH_TOKEN },
         };
     }
+    if (process.env.ANTHROPIC_API_KEY) {
+        return {
+            type: "api-key",
+            data: { apiKey: process.env.ANTHROPIC_API_KEY },
+        };
+    }
+    return undefined;
+}
+/**
+ * Extract credentials from local storage only (keychain + file).
+ *
+ * This skips environment variable checks and only looks at local storage.
+ * Used as fallback after vault fetch fails.
+ */
+function extractFromLocalStorage() {
     const keychainCreds = loadKeychainCreds();
     if (keychainCreds) {
         return {
-            type: "oauth",
+            type: "oauth-credentials",
             data: { ...keychainCreds, _source: "keychain" },
         };
     }
     const fileCreds = loadFileCreds();
     if (fileCreds) {
         return {
-            type: "oauth",
+            type: "oauth-credentials",
             data: { ...fileCreds, _source: "file" },
         };
     }
-    if (process.env.ANTHROPIC_API_KEY) {
-        return {
-            type: "api-key",
-            data: { apiKey: process.env.ANTHROPIC_API_KEY },
-        };
-    }
     return undefined;
 }
-export { AGENT_ID, checkAuth, deleteFileCreds, deleteKeychainCreds, extractRawCredentials, getDefaultCredsFilePath, saveFileCreds, saveKeychainCreds, };
+/** Extract raw credentials from available sources */
+function extractRawCredentials() {
+    // Check env vars first
+    const environmentCreds = extractFromEnvironment();
+    if (environmentCreds)
+        return environmentCreds;
+    // Fall back to local storage
+    return extractFromLocalStorage();
+}
+export { AGENT_ID, checkAuth, deleteFileCreds, deleteKeychainCreds, extractFromEnvironment, extractRawCredentials, getDefaultCredsFilePath, saveFileCreds, saveKeychainCreds, };

package/dist/auth/agents/claude.js

@@ -7,7 +7,7 @@ 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";
+import { AGENT_ID, checkAuth, deleteFileCreds, deleteKeychainCreds, extractFromEnvironment, extractRawCredentials, getDefaultCredsFilePath, saveFileCreds, saveKeychainCreds, } from "./claude-storage.js";
 const CREDS_FILE_NAME = ".credentials.json";
 /** Claude Code authentication adapter */
 const claudeCodeAdapter = {
@@ -22,6 +22,12 @@ const claudeCodeAdapter = {
         const result = checkAuth();
         return { agentId: AGENT_ID, ...result };
     },
+    extractFromEnvironment() {
+        const result = extractFromEnvironment();
+        if (!result)
+            return undefined;
+        return { agent: AGENT_ID, ...result };
+    },
     extractRawCredentials() {
         const result = extractRawCredentials();
         if (!result)
@@ -121,7 +127,8 @@ const claudeCodeAdapter = {
     },
     getAccessToken(creds) {
         const data = creds.data;
-        if (creds.type === "oauth" && typeof data.accessToken === "string") {
+        if ((creds.type === "oauth-credentials" || creds.type === "oauth-token") &&
+            typeof data.accessToken === "string") {
             return data.accessToken;
         }
         if (creds.type === "api-key" && typeof data.apiKey === "string") {
@@ -132,7 +139,8 @@ const claudeCodeAdapter = {
     credentialsToEnvironment(creds) {
         const environment = {};
         const data = creds.data;
-        if (creds.type === "oauth" && typeof data.accessToken === "string") {
+        if ((creds.type === "oauth-credentials" || creds.type === "oauth-token") &&
+            typeof data.accessToken === "string") {
             environment.CLAUDE_CODE_OAUTH_TOKEN = data.accessToken;
         }
         else if (creds.type === "api-key" && typeof data.apiKey === "string") {

package/dist/auth/agents/codex-auth-check.d.ts

@@ -4,6 +4,8 @@
 import type { AuthStatus, Credentials } from "../types.js";
 /** Check auth status across all sources */
 declare function checkAuth(): AuthStatus;
+/** Extract credentials from environment */
+declare function extractEnvironmentCredentials(): Credentials | undefined;
 /** Extract raw credentials from first available source */
 declare function extractRawCredentials(): Credentials | undefined;
-export { checkAuth, extractRawCredentials };
+export { checkAuth, extractEnvironmentCredentials, extractRawCredentials };

package/dist/auth/agents/codex-auth-check.js

@@ -71,7 +71,7 @@ function extractKeychainCredentials() {
     if (keychainAuth?.tokens) {
         return {
             agent: AGENT_ID,
-            type: "oauth",
+            type: "oauth-credentials",
             data: { ...keychainAuth, _source: "keychain" },
         };
     }
@@ -88,7 +88,7 @@ function extractFileCredentials() {
         };
     }
     if (fileAuth?.tokens) {
-        return { agent: AGENT_ID, type: "oauth", data: fileAuth };
+        return { agent: AGENT_ID, type: "oauth-credentials", data: fileAuth };
     }
     return undefined;
 }
@@ -98,4 +98,4 @@ function extractRawCredentials() {
         extractKeychainCredentials() ??
         extractFileCredentials());
 }
-export { checkAuth, extractRawCredentials };
+export { checkAuth, extractEnvironmentCredentials, extractRawCredentials };

package/dist/auth/agents/codex-storage.d.ts

@@ -39,5 +39,5 @@ interface CredentialsData {
     [key: string]: unknown;
 }
 /** Build auth content from credentials data */
-declare function buildAuthContent(type: "oauth" | "api-key", data: CredentialsData): CodexAuthJson;
+declare function buildAuthContent(type: "oauth-credentials" | "oauth-token" | "api-key", data: CredentialsData): CodexAuthJson;
 export { buildAuthContent, deleteFileCreds, deleteKeychainCreds, getEnvironmentApiKey, hasFileApiKey, hasFileOAuth, hasKeychainApiKey, hasKeychainOAuth, loadFileCreds, loadKeychainCreds, saveFileCreds, saveKeychainCreds, };

package/dist/auth/agents/codex.js

@@ -8,7 +8,7 @@ import path from "node:path";
 import { ensureDirectory } from "../file-storage.js";
 import { isMacOS } from "../keychain.js";
 import { resolveCustomDirectory } from "../validate-directories.js";
-import { checkAuth, extractRawCredentials } from "./codex-auth-check.js";
+import { checkAuth, extractEnvironmentCredentials, extractRawCredentials, } from "./codex-auth-check.js";
 import { getAuthFilePath, getCodexHome, updateConfigStorage, } from "./codex-config.js";
 import { buildAuthContent, deleteFileCreds, deleteKeychainCreds, saveFileCreds, saveKeychainCreds, } from "./codex-storage.js";
 const AGENT_ID = "codex";
@@ -23,6 +23,7 @@ const codexAdapter = {
         installApiKey: true,
     },
     checkAuth,
+    extractFromEnvironment: extractEnvironmentCredentials,
     extractRawCredentials,
     extractRawCredentialsFromDirectory(options) {
         // Codex doesn't separate config/data - use either directory
@@ -38,7 +39,7 @@ const codexAdapter = {
                 return undefined;
             const data = parsed;
             // Determine type from data structure
-            const type = data.api_key ? "api-key" : "oauth";
+            const type = data.api_key ? "api-key" : "oauth-credentials";
             return { agent: AGENT_ID, type, data };
         }
         catch {
@@ -133,7 +134,7 @@ const codexAdapter = {
         if (creds.type === "api-key" && typeof data.apiKey === "string") {
             return data.apiKey;
         }
-        if (creds.type === "oauth") {
+        if (creds.type === "oauth-credentials") {
             // Direct access_token
             if (typeof data.access_token === "string") {
                 return data.access_token;

package/dist/auth/agents/copilot-install.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copilot credential installation helpers.
+ *
+ * Extracted from copilot.ts to reduce file complexity.
+ */
+import type { InstallOptions, OperationResult } from "../adapter.js";
+import type { Credentials } from "../types.js";
+import type { ResolveResult } from "../validate-directories.js";
+declare const CREDS_FILE_NAME = "token.json";
+/**
+ * Install Copilot credentials.
+ *
+ * Handles keychain vs file storage and custom directories.
+ */
+declare function installCopilotCredentials(creds: Credentials, resolved: Extract<ResolveResult, {
+    ok: true;
+}>, options?: InstallOptions): OperationResult;
+export { CREDS_FILE_NAME, installCopilotCredentials };

package/dist/auth/agents/copilot-install.js

@@ -0,0 +1,73 @@
+/**
+ * Copilot credential installation helpers.
+ *
+ * Extracted from copilot.ts to reduce file complexity.
+ */
+import path from "node:path";
+import { ensureDirectory } from "../file-storage.js";
+import { isMacOS } from "../keychain.js";
+import { getConfigDirectory, getConfigFilePath, saveFileToken, saveKeychainToken, saveTokenToPath, } from "./copilot-storage.js";
+const CREDS_FILE_NAME = "token.json";
+/**
+ * Install Copilot credentials.
+ *
+ * Handles keychain vs file storage and custom directories.
+ */
+function installCopilotCredentials(creds, resolved, options) {
+    if (creds.type === "api-key") {
+        return {
+            ok: false,
+            message: "API key credentials cannot be installed (use COPILOT_GITHUB_TOKEN env var)",
+        };
+    }
+    const token = typeof creds.data.accessToken === "string"
+        ? creds.data.accessToken
+        : undefined;
+    if (!token) {
+        return { ok: false, message: "No access token found in credentials" };
+    }
+    // Custom directory forces file storage
+    if (resolved.customDir) {
+        const targetPath = path.join(resolved.customDir, CREDS_FILE_NAME);
+        if (saveTokenToPath(token, targetPath)) {
+            return {
+                ok: true,
+                message: `Installed credentials to ${targetPath}`,
+            };
+        }
+        return {
+            ok: false,
+            message: `Failed to install credentials to ${targetPath}`,
+        };
+    }
+    // Default location: use storage option or _source marker
+    const sourceMarker = creds.data._source;
+    const targetStorage = options?.storage ?? (sourceMarker === "keychain" ? "keychain" : "file");
+    if (targetStorage === "keychain") {
+        if (!isMacOS()) {
+            return {
+                ok: false,
+                message: "Keychain storage is only available on macOS",
+            };
+        }
+        if (saveKeychainToken(token)) {
+            return { ok: true, message: "Installed credentials to macOS Keychain" };
+        }
+        return { ok: false, message: "Failed to save to macOS Keychain" };
+    }
+    // File storage
+    if (!ensureDirectory(getConfigDirectory())) {
+        return {
+            ok: false,
+            message: "Failed to create copilot config directory",
+        };
+    }
+    if (saveFileToken(token)) {
+        return {
+            ok: true,
+            message: `Installed credentials to ${getConfigFilePath()}`,
+        };
+    }
+    return { ok: false, message: "Failed to install credentials to file" };
+}
+export { CREDS_FILE_NAME, installCopilotCredentials };

package/dist/auth/agents/copilot.js

@@ -6,13 +6,11 @@
  */
 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";
 import { findFirstAvailableToken } from "./copilot-auth-check.js";
-import { deleteFileToken, deleteKeychainToken, deleteTokenFromPath, getConfigDirectory, getConfigFilePath, saveFileToken, saveKeychainToken, saveTokenToPath, } from "./copilot-storage.js";
+import { CREDS_FILE_NAME, installCopilotCredentials, } from "./copilot-install.js";
+import { deleteFileToken, deleteKeychainToken, deleteTokenFromPath, getConfigFilePath, getEnvironmentToken, } from "./copilot-storage.js";
 const AGENT_ID = "copilot";
-const CREDS_FILE_NAME = "token.json";
 /** Copilot CLI authentication adapter */
 const copilotAdapter = {
     agentId: AGENT_ID,
@@ -39,13 +37,23 @@ const copilotAdapter = {
             method: methodMap[result.source],
         };
     },
+    extractFromEnvironment() {
+        const token = getEnvironmentToken();
+        if (!token)
+            return undefined;
+        return {
+            agent: AGENT_ID,
+            type: "oauth-token",
+            data: { accessToken: token },
+        };
+    },
     extractRawCredentials() {
         const result = findFirstAvailableToken();
         if (!result)
             return undefined;
         return {
             agent: AGENT_ID,
-            type: "oauth",
+            type: "oauth-token",
             data: { accessToken: result.token, _source: result.source },
         };
     },
@@ -57,65 +65,10 @@ const copilotAdapter = {
         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);
         if (!resolved.ok)
             return resolved.error;
-        if (creds.type === "api-key") {
-            return {
-                ok: false,
-                message: "API key credentials cannot be installed (use COPILOT_GITHUB_TOKEN env var)",
-            };
-        }
-        const token = typeof creds.data.accessToken === "string"
-            ? creds.data.accessToken
-            : undefined;
-        if (!token) {
-            return { ok: false, message: "No access token found in credentials" };
-        }
-        // Custom directory forces file storage
-        if (resolved.customDir) {
-            const targetPath = path.join(resolved.customDir, CREDS_FILE_NAME);
-            if (saveTokenToPath(token, targetPath)) {
-                return {
-                    ok: true,
-                    message: `Installed credentials to ${targetPath}`,
-                };
-            }
-            return {
-                ok: false,
-                message: `Failed to install credentials to ${targetPath}`,
-            };
-        }
-        // Default location: use storage option or _source marker
-        const sourceMarker = creds.data._source;
-        const targetStorage = options?.storage ?? (sourceMarker === "keychain" ? "keychain" : "file");
-        if (targetStorage === "keychain") {
-            if (!isMacOS()) {
-                return {
-                    ok: false,
-                    message: "Keychain storage is only available on macOS",
-                };
-            }
-            if (saveKeychainToken(token)) {
-                return { ok: true, message: "Installed credentials to macOS Keychain" };
-            }
-            return { ok: false, message: "Failed to save to macOS Keychain" };
-        }
-        // File storage
-        if (!ensureDirectory(getConfigDirectory())) {
-            return {
-                ok: false,
-                message: "Failed to create copilot config directory",
-            };
-        }
-        if (saveFileToken(token)) {
-            return {
-                ok: true,
-                message: `Installed credentials to ${getConfigFilePath()}`,
-            };
-        }
-        return { ok: false, message: "Failed to install credentials to file" };
+        return installCopilotCredentials(creds, resolved, options);
     },
     removeCredentials(options) {
         // Resolve custom directory with validation

package/dist/auth/agents/gemini-auth-check.d.ts

@@ -11,6 +11,8 @@ interface CredentialResult {
     method: string;
     data?: Record<string, unknown>;
 }
+/** Check environment variable credentials (API key and Vertex AI) */
+declare function checkEnvironmentAuth(): CredentialResult | undefined;
 /** Find credentials using priority-ordered discovery: env → keychain → file */
 declare function findCredentials(): CredentialResult | undefined;
-export { findCredentials };
+export { checkEnvironmentAuth, findCredentials };

package/dist/auth/agents/gemini-auth-check.js

@@ -57,4 +57,4 @@ function checkFileAuth() {
 function findCredentials() {
     return checkEnvironmentAuth() ?? checkKeychainAuth() ?? checkFileAuth();
 }
-export { findCredentials };
+export { checkEnvironmentAuth, findCredentials };

package/dist/auth/agents/gemini.js

@@ -4,7 +4,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 { checkEnvironmentAuth, findCredentials } from "./gemini-auth-check.js";
 import { installOAuthCredentials, removeGeminiCredentials, } from "./gemini-install.js";
 const AGENT_ID = "gemini";
 /** Gemini authentication adapter */
@@ -27,6 +27,16 @@ const geminiAdapter = {
             method: result.method,
         };
     },
+    extractFromEnvironment() {
+        const result = checkEnvironmentAuth();
+        if (!result || !result.data)
+            return undefined;
+        return {
+            agent: AGENT_ID,
+            type: "api-key",
+            data: result.data,
+        };
+    },
     extractRawCredentials() {
         const result = findCredentials();
         if (!result || !result.data)
@@ -42,7 +52,7 @@ const geminiAdapter = {
         // OAuth credentials from keychain or file include _source for round-tripping
         return {
             agent: AGENT_ID,
-            type: "oauth",
+            type: "oauth-credentials",
             data: {
                 ...result.data,
                 _source: result.source === "keychain" ? "keychain" : "file",
@@ -74,7 +84,8 @@ const geminiAdapter = {
         if (creds.type === "api-key" && typeof data.apiKey === "string") {
             return data.apiKey;
         }
-        if (creds.type === "oauth" && typeof data.access_token === "string") {
+        if (creds.type === "oauth-credentials" &&
+            typeof data.access_token === "string") {
             return data.access_token;
         }
         return undefined;

package/dist/auth/agents/opencode.js

@@ -77,7 +77,7 @@ const opencodeAdapter = {
         const auth = readAuthFile(getDefaultAuthFilePath());
         if (!auth || Object.keys(auth).length === 0)
             return undefined;
-        return { agent: AGENT_ID, type: "oauth", data: auth };
+        return { agent: AGENT_ID, type: "oauth-credentials", data: auth };
     },
     extractRawCredentialsFromDirectory(options) {
         // OpenCode stores credentials in dataDir only - configDir is for settings

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

@@ -28,7 +28,7 @@ function extractCredsFromDirectory(agentId, directory, fileName, transform) {
         const data = transform ? transform(record) : record;
         if (!data)
             return undefined;
-        return { agent: agentId, type: "oauth", data };
+        return { agent: agentId, type: "oauth-credentials", data };
     }
     catch {
         return undefined;

package/dist/auth/registry.d.ts

@@ -51,9 +51,17 @@ declare function checkAllAuth(): AuthStatus[];
 /**
  * Extract raw credentials for an agent.
  *
+ * Checks credentials from all available sources:
+ * - Environment variables
+ * - Keychain (macOS)
+ * - File storage
+ *
  * Note: The `data` field format is agent-specific and not standardized.
  * Use {@link getAccessToken} to extract the token in a uniform way.
  *
+ * For vault credentials, use {@link fetchVaultCredentials} from the vault module
+ * or the `axauth vault fetch` CLI command.
+ *
  * @example
  * const creds = extractRawCredentials("codex");
  * if (creds) { await exportCredentials(creds); }

package/dist/auth/registry.js

@@ -75,9 +75,17 @@ function checkAllAuth() {
 /**
  * Extract raw credentials for an agent.
  *
+ * Checks credentials from all available sources:
+ * - Environment variables
+ * - Keychain (macOS)
+ * - File storage
+ *
  * Note: The `data` field format is agent-specific and not standardized.
  * Use {@link getAccessToken} to extract the token in a uniform way.
  *
+ * For vault credentials, use {@link fetchVaultCredentials} from the vault module
+ * or the `axauth vault fetch` CLI command.
+ *
  * @example
  * const creds = extractRawCredentials("codex");
  * if (creds) { await exportCredentials(creds); }

package/dist/auth/types.d.ts

@@ -21,8 +21,9 @@ declare const Credentials: z.ZodObject<{
         copilot: "copilot";
     }>;
     type: z.ZodEnum<{
-        oauth: "oauth";
         "api-key": "api-key";
+        "oauth-token": "oauth-token";
+        "oauth-credentials": "oauth-credentials";
     }>;
     data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;

package/dist/auth/types.js

@@ -1,14 +1,14 @@
 /**
  * Shared types for auth module.
  */
-import { AGENT_CLIS } from "axshared";
+import { AGENT_CLIS, CredentialType } from "axshared";
 import { z } from "zod";
 /** Zod schema for AgentCli */
 const AgentCliSchema = z.enum(AGENT_CLIS);
 /** Extracted credential data schema */
 const Credentials = z.object({
     agent: AgentCliSchema,
-    type: z.enum(["oauth", "api-key"]),
+    type: CredentialType,
     data: z.record(z.string(), z.unknown()),
 });
 /**

package/dist/auth/validate-directories.d.ts

@@ -22,4 +22,5 @@ type ResolveResult = {
  * @see resolveCustomDirectories in axshared for behavior details
  */
 declare function resolveCustomDirectory(agentId: AgentCli, configDirectory: string | undefined, dataDirectory: string | undefined): ResolveResult;
+export type { ResolveResult };
 export { resolveCustomDirectory };

package/dist/cli.js

@@ -7,6 +7,7 @@
 import { Command } from "@commander-js/extra-typings";
 import packageJson from "../package.json" with { type: "json" };
 import { handleAuthExport, handleAuthInstall, handleAuthList, handleAuthRemove, handleAuthToken, } from "./commands/auth.js";
+import { handleVaultFetch } from "./commands/vault.js";
 import { AGENT_CLIS } from "axshared";
 // Handle SIGINT gracefully
 process.on("SIGINT", () => {
@@ -38,7 +39,11 @@ Examples:
   axauth remove-credentials --agent claude
 
   # Install credentials from exported file
-  axauth install-credentials --agent claude --input creds.json`);
+  axauth install-credentials --agent claude --input creds.json
+
+  # Fetch credentials from vault (JSON config)
+  AXVAULT='{"url":"https://vault.example.com","apiKey":"axv_sk_xxx"}' \
+    axauth vault fetch --agent claude --name ci --install`);
 program
     .command("list")
     .description("List agents and their auth status")
@@ -87,4 +92,51 @@ program
         dataDir: options.dataDir,
     });
 });
+// Vault subcommand
+const vault = program
+    .command("vault")
+    .description("Manage credentials stored in axvault server");
+vault
+    .command("fetch")
+    .description("Fetch credentials from vault server")
+    .requiredOption("-a, --agent <agent>", `Agent to fetch credentials for (${AGENT_CLIS.join(", ")})`)
+    .requiredOption("-n, --name <name>", "Credential name in vault (e.g., ci, prod)")
+    .option("-i, --install", "Install fetched credentials to local storage")
+    .option("-e, --env", "Output shell export commands for environment variables")
+    .option("--config-dir <dir>", "Custom config directory (for agents without separation)")
+    .option("--data-dir <dir>", "Custom data directory for credentials")
+    .option("--json", "Pretty-print JSON output")
+    .addHelpText("after", `
+Environment variables (option 1 - single JSON):
+  AXVAULT           JSON config: {"url":"...","apiKey":"...","credentialName":"..."}
+
+Environment variables (option 2 - individual):
+  AXVAULT_URL       Vault server URL (required)
+  AXVAULT_API_KEY   API key for authentication (required)
+  AXVAULT_CREDENTIAL  Default credential name (optional)
+
+Output modes:
+  (default)   Output credentials as JSON
+  --install   Write credentials to local storage (file/keychain)
+  --env       Output shell export commands for environment variables
+
+Examples:
+  # Fetch and output credentials as JSON
+  axauth vault fetch --agent claude --name ci
+
+  # Fetch and install OAuth credentials locally
+  axauth vault fetch --agent claude --name ci --install
+
+  # Fetch and set environment variables (works for all credential types)
+  eval "$(axauth vault fetch --agent claude --name ci --env)"
+
+  # GitHub Actions: append to $GITHUB_ENV
+  axauth vault fetch --agent claude --name ci --env | sed 's/^export //' >> $GITHUB_ENV`)
+    .action((options) => {
+    void handleVaultFetch({
+        ...options,
+        configDir: options.configDir,
+        dataDir: options.dataDir,
+    });
+});
 await program.parseAsync(process.argv);

package/dist/commands/vault.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Vault commands - fetch credentials from axvault server.
+ */
+interface VaultFetchOptions {
+    agent: string;
+    name: string;
+    install?: boolean;
+    env?: boolean;
+    configDir?: string;
+    dataDir?: string;
+    json?: boolean;
+}
+/**
+ * Handle vault fetch command.
+ *
+ * Fetches credentials from the vault server and either:
+ * - Outputs them as JSON (default) for piping to other commands
+ * - Installs them locally with --install flag (writes to file)
+ * - Outputs shell export commands with --env flag (for eval/source)
+ */
+declare function handleVaultFetch(options: VaultFetchOptions): Promise<void>;
+export { handleVaultFetch };

package/dist/commands/vault.js

@@ -0,0 +1,123 @@
+/**
+ * Vault commands - fetch credentials from axvault server.
+ */
+import { credentialsToEnvironment, installCredentials, } from "../auth/registry.js";
+import { fetchVaultCredentials, } from "../vault/vault-client.js";
+import { getVaultConfig } from "../vault/vault-config.js";
+import { validateAgent } from "./validate-agent.js";
+/** Human-readable error messages for vault failures */
+const FAILURE_MESSAGES = {
+    "not-configured": "Vault not configured. Set AXVAULT (JSON) or AXVAULT_URL + AXVAULT_API_KEY.",
+    unreachable: "Vault server is unreachable. Check vault URL and network.",
+    unauthorized: "Invalid API key. Check apiKey in vault config.",
+    forbidden: "Access denied. API key doesn't have read access to this credential.",
+    "not-found": "Credential not found in vault.",
+    "legacy-credential": "Credential uses legacy encryption. Re-upload it to vault.",
+    "client-error": "Invalid request. Check credential name and try again.",
+    "server-error": "Vault server error. Check server logs.",
+};
+/**
+ * Escape a value for safe use in shell export statement.
+ * Uses single quotes and escapes any single quotes in the value.
+ *
+ * @throws Error if value contains newlines or null bytes (cannot be safely exported)
+ */
+function shellEscape(value) {
+    if (value.includes("\n") || value.includes("\0")) {
+        throw new Error("Credential values cannot contain newlines or null bytes");
+    }
+    // Replace single quotes with '\'' (end quote, escaped quote, start quote)
+    return `'${value.replaceAll("'", String.raw `'\''`)}'`;
+}
+/**
+ * Handle vault fetch command.
+ *
+ * Fetches credentials from the vault server and either:
+ * - Outputs them as JSON (default) for piping to other commands
+ * - Installs them locally with --install flag (writes to file)
+ * - Outputs shell export commands with --env flag (for eval/source)
+ */
+async function handleVaultFetch(options) {
+    // Validate agent
+    const agentId = validateAgent(options.agent);
+    if (!agentId)
+        return;
+    // Validate mutually exclusive options
+    if (options.install && options.env) {
+        console.error("Error: --install and --env are mutually exclusive");
+        process.exitCode = 2;
+        return;
+    }
+    // Check vault is configured
+    const vaultConfig = getVaultConfig();
+    if (!vaultConfig) {
+        console.error(`Error: ${FAILURE_MESSAGES["not-configured"]}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Fetch from vault
+    const result = await fetchVaultCredentials({
+        agentId,
+        name: options.name,
+    });
+    if (!result.ok) {
+        console.error(`Error: ${FAILURE_MESSAGES[result.reason]}`);
+        process.exitCode = 1;
+        return;
+    }
+    const { credentials, refreshed } = result;
+    // Log refresh status to stderr (not stdout, to allow piping)
+    if (refreshed) {
+        console.error("Note: Credentials were auto-refreshed by vault");
+    }
+    if (options.env) {
+        // Output shell export commands (for eval/source)
+        const environmentVariables = credentialsToEnvironment(credentials);
+        const environmentEntries = Object.entries(environmentVariables);
+        if (environmentEntries.length === 0) {
+            console.error("Warning: No environment variables to export for this credential type");
+            return;
+        }
+        try {
+            for (const [key, value] of environmentEntries) {
+                console.log(`export ${key}=${shellEscape(value)}`);
+            }
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : "Failed to escape credential value"}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else if (options.install) {
+        // Install credentials locally (writes to file)
+        const installResult = installCredentials(credentials, {
+            configDir: options.configDir,
+            dataDir: options.dataDir,
+        });
+        if (!installResult.ok) {
+            // For env-only credentials, suggest using --env instead
+            if (installResult.message.includes("cannot be installed")) {
+                console.error(`Error: ${installResult.message}`);
+                console.error("Hint: Use --env to get shell export commands instead");
+            }
+            else {
+                console.error(`Error: ${installResult.message}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        console.error(installResult.message);
+    }
+    else {
+        // Output credentials as JSON (default)
+        if (options.json) {
+            console.log(JSON.stringify(credentials, undefined, 2));
+        }
+        else {
+            // Compact JSON for piping
+            console.log(JSON.stringify(credentials));
+        }
+    }
+}
+export { handleVaultFetch };

package/dist/index.d.ts

@@ -35,5 +35,7 @@ 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, extractRawCredentialsFromDirectory, getAccessToken, getAgentAccessToken, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, getAdapter, getAllAdapters, getCapabilities, type ExtractOptions, type InstallFromEnvironmentOptions, } from "./auth/registry.js";
+export { getVaultConfig, isVaultConfigured, type VaultConfig, } from "./vault/vault-config.js";
+export { fetchVaultCredentials, type VaultFailureReason, type VaultFetchOptions, type VaultResult, } from "./vault/vault-client.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,6 +37,9 @@ export {
 checkAllAuth, checkAuth, credentialsToEnvironment, extractRawCredentials, extractRawCredentialsFromDirectory, getAccessToken, getAgentAccessToken, getCredentialsEnvironmentVariableName, installCredentials, installCredentialsFromEnvironmentVariable, removeCredentials, 
 // Adapter access
 getAdapter, getAllAdapters, getCapabilities, } from "./auth/registry.js";
+// Vault utilities
+export { getVaultConfig, isVaultConfigured, } from "./vault/vault-config.js";
+export { fetchVaultCredentials, } from "./vault/vault-client.js";
 // Token refresh utilities
 export { isCredentialExpired, isTokenExpired, } from "./auth/is-token-expired.js";
 export { refreshAndPersist, refreshCredentials, } from "./auth/refresh-credentials.js";

package/dist/vault/vault-client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HTTP client for fetching credentials from axvault server.
+ *
+ * The vault client provides a simple interface to fetch credentials from
+ * a remote axvault server. It handles authentication, error responses,
+ * and returns a typed result.
+ */
+import type { AgentCli } from "axshared";
+import type { Credentials } from "../auth/types.js";
+/** Reason why vault fetch failed */
+type VaultFailureReason = "not-configured" | "unreachable" | "unauthorized" | "forbidden" | "not-found" | "legacy-credential" | "client-error" | "server-error";
+/** Result of a vault fetch operation */
+type VaultResult = {
+    ok: true;
+    credentials: Credentials;
+    refreshed: boolean;
+} | {
+    ok: false;
+    reason: VaultFailureReason;
+};
+/** Options for fetching from vault */
+interface VaultFetchOptions {
+    /** Agent ID (e.g., "claude", "codex") */
+    agentId: AgentCli;
+    /** Credential name in vault (e.g., "ci", "prod") */
+    name: string;
+}
+/**
+ * Fetch credentials from the axvault server.
+ *
+ * This function attempts to fetch credentials for a specific agent and name
+ * from the configured vault server. If the vault is not configured, it returns
+ * a "not-configured" result without making any network requests.
+ *
+ * @example
+ * const result = await fetchVaultCredentials({ agentId: "claude", name: "ci" });
+ * if (result.ok) {
+ *   console.log("Got credentials:", result.credentials);
+ *   if (result.refreshed) {
+ *     console.log("Credentials were auto-refreshed by vault");
+ *   }
+ * } else {
+ *   console.log("Failed:", result.reason);
+ * }
+ */
+declare function fetchVaultCredentials(options: VaultFetchOptions): Promise<VaultResult>;
+export type { VaultFailureReason, VaultFetchOptions, VaultResult };
+export { fetchVaultCredentials };

package/dist/vault/vault-client.js

@@ -0,0 +1,102 @@
+/**
+ * HTTP client for fetching credentials from axvault server.
+ *
+ * The vault client provides a simple interface to fetch credentials from
+ * a remote axvault server. It handles authentication, error responses,
+ * and returns a typed result.
+ */
+import { z } from "zod";
+import { getVaultConfig } from "./vault-config.js";
+/** Zod schema for vault API response */
+const VaultCredentialResponse = z.object({
+    agent: z.string(),
+    name: z.string(),
+    type: z.enum(["oauth-credentials", "oauth-token", "api-key"]),
+    data: z.record(z.string(), z.unknown()),
+    expiresAt: z.string().nullable(),
+    updatedAt: z.string(),
+});
+/**
+ * Fetch credentials from the axvault server.
+ *
+ * This function attempts to fetch credentials for a specific agent and name
+ * from the configured vault server. If the vault is not configured, it returns
+ * a "not-configured" result without making any network requests.
+ *
+ * @example
+ * const result = await fetchVaultCredentials({ agentId: "claude", name: "ci" });
+ * if (result.ok) {
+ *   console.log("Got credentials:", result.credentials);
+ *   if (result.refreshed) {
+ *     console.log("Credentials were auto-refreshed by vault");
+ *   }
+ * } else {
+ *   console.log("Failed:", result.reason);
+ * }
+ */
+async function fetchVaultCredentials(options) {
+    const config = getVaultConfig();
+    if (!config) {
+        return { ok: false, reason: "not-configured" };
+    }
+    const url = `${config.url}/api/v1/credentials/${encodeURIComponent(options.agentId)}/${encodeURIComponent(options.name)}`;
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${config.apiKey}`,
+                Accept: "application/json",
+                "User-Agent": "axauth-vault-client",
+            },
+        });
+        // Handle error responses
+        if (response.status === 401) {
+            return { ok: false, reason: "unauthorized" };
+        }
+        if (response.status === 403) {
+            return { ok: false, reason: "forbidden" };
+        }
+        if (response.status === 404) {
+            return { ok: false, reason: "not-found" };
+        }
+        if (response.status === 410) {
+            return { ok: false, reason: "legacy-credential" };
+        }
+        if (response.status >= 500) {
+            return { ok: false, reason: "server-error" };
+        }
+        if (!response.ok) {
+            // Other 4xx errors (400 Bad Request, 429 Rate Limited, etc.)
+            return { ok: false, reason: "client-error" };
+        }
+        // Parse and validate response body
+        const json = await response.json();
+        const parsed = VaultCredentialResponse.safeParse(json);
+        if (!parsed.success) {
+            return { ok: false, reason: "server-error" };
+        }
+        const body = parsed.data;
+        // Check refresh headers
+        const wasRefreshed = response.headers.get("X-Axvault-Refreshed") === "true";
+        const refreshFailed = response.headers.get("X-Axvault-Refresh-Failed") === "true";
+        // Log warning if refresh failed (stale credentials returned)
+        if (refreshFailed) {
+            console.error(`[axauth] Vault returned stale credentials for ${options.agentId}/${options.name} (refresh failed)`);
+        }
+        const credentials = {
+            agent: options.agentId,
+            type: body.type,
+            data: body.data,
+        };
+        return {
+            ok: true,
+            credentials,
+            refreshed: wasRefreshed,
+        };
+    }
+    catch {
+        // Network errors (DNS failure, connection refused, timeout, etc.)
+        return { ok: false, reason: "unreachable" };
+    }
+}
+export { fetchVaultCredentials };

package/dist/vault/vault-config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Vault configuration from environment variables.
+ *
+ * Vault is an optional credential source. When configured via environment
+ * variables, axauth will attempt to fetch credentials from the vault server
+ * before falling back to local storage.
+ */
+/** Vault configuration parsed from environment */
+interface VaultConfig {
+    /** Vault server URL (e.g., "https://vault.example.com") */
+    url: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Default credential name to fetch (e.g., "ci", "prod") */
+    credentialName?: string;
+}
+/**
+ * Get vault configuration from environment variables.
+ *
+ * Supports two configuration methods (checked in order):
+ *
+ * 1. Single JSON env var:
+ *    - `AXVAULT`: JSON object with url, apiKey, and optional credentialName
+ *
+ * 2. Individual env vars:
+ *    - `AXVAULT_URL`: Vault server URL (required)
+ *    - `AXVAULT_API_KEY`: API key for authentication (required)
+ *    - `AXVAULT_CREDENTIAL`: Default credential name (optional)
+ *
+ * @returns Vault configuration if configured, undefined otherwise
+ *
+ * @example
+ * // Option 1: Single JSON env var
+ * // AXVAULT='{"url":"https://vault.axkit.dev","apiKey":"axv_sk_xxx","credentialName":"ci"}'
+ *
+ * // Option 2: Individual env vars
+ * // AXVAULT_URL=https://vault.axkit.dev
+ * // AXVAULT_API_KEY=axv_sk_xxx
+ * // AXVAULT_CREDENTIAL=ci
+ *
+ * const config = getVaultConfig();
+ * if (config) {
+ *   // Vault is configured, can fetch credentials
+ * }
+ */
+declare function getVaultConfig(): VaultConfig | undefined;
+/**
+ * Check if vault is configured.
+ *
+ * @returns true if AXVAULT_URL and AXVAULT_API_KEY are both set
+ */
+declare function isVaultConfigured(): boolean;
+export type { VaultConfig };
+export { getVaultConfig, isVaultConfigured };

package/dist/vault/vault-config.js

@@ -0,0 +1,112 @@
+/**
+ * Vault configuration from environment variables.
+ *
+ * Vault is an optional credential source. When configured via environment
+ * variables, axauth will attempt to fetch credentials from the vault server
+ * before falling back to local storage.
+ */
+import { z } from "zod";
+/** Zod schema for vault config JSON */
+const VaultConfigJson = z.object({
+    url: z.string(),
+    apiKey: z.string(),
+    credentialName: z.string().optional(),
+});
+/**
+ * Validate and normalize a vault URL.
+ *
+ * @returns Normalized URL (trailing slashes removed) or undefined if invalid
+ */
+function validateVaultUrl(url) {
+    try {
+        new URL(url);
+        return url.replaceAll(/\/+$/gu, "");
+    }
+    catch {
+        console.error(`Warning: Invalid vault URL "${url}", ignoring`);
+        return undefined;
+    }
+}
+/**
+ * Parse vault config from JSON environment variable.
+ *
+ * @returns Parsed config or undefined if invalid/not set
+ */
+function parseVaultConfigJson() {
+    const json = process.env.AXVAULT;
+    if (!json)
+        return undefined;
+    try {
+        const parsed = VaultConfigJson.parse(JSON.parse(json));
+        const url = validateVaultUrl(parsed.url);
+        if (!url)
+            return undefined;
+        return {
+            url,
+            apiKey: parsed.apiKey,
+            credentialName: parsed.credentialName,
+        };
+    }
+    catch {
+        console.error("Warning: AXVAULT env var contains invalid JSON, ignoring");
+        return undefined;
+    }
+}
+/**
+ * Get vault configuration from environment variables.
+ *
+ * Supports two configuration methods (checked in order):
+ *
+ * 1. Single JSON env var:
+ *    - `AXVAULT`: JSON object with url, apiKey, and optional credentialName
+ *
+ * 2. Individual env vars:
+ *    - `AXVAULT_URL`: Vault server URL (required)
+ *    - `AXVAULT_API_KEY`: API key for authentication (required)
+ *    - `AXVAULT_CREDENTIAL`: Default credential name (optional)
+ *
+ * @returns Vault configuration if configured, undefined otherwise
+ *
+ * @example
+ * // Option 1: Single JSON env var
+ * // AXVAULT='{"url":"https://vault.axkit.dev","apiKey":"axv_sk_xxx","credentialName":"ci"}'
+ *
+ * // Option 2: Individual env vars
+ * // AXVAULT_URL=https://vault.axkit.dev
+ * // AXVAULT_API_KEY=axv_sk_xxx
+ * // AXVAULT_CREDENTIAL=ci
+ *
+ * const config = getVaultConfig();
+ * if (config) {
+ *   // Vault is configured, can fetch credentials
+ * }
+ */
+function getVaultConfig() {
+    // Try JSON config first
+    const jsonConfig = parseVaultConfigJson();
+    if (jsonConfig)
+        return jsonConfig;
+    // Fall back to individual env vars
+    const rawUrl = process.env.AXVAULT_URL;
+    const apiKey = process.env.AXVAULT_API_KEY;
+    if (!rawUrl || !apiKey) {
+        return undefined;
+    }
+    const url = validateVaultUrl(rawUrl);
+    if (!url)
+        return undefined;
+    return {
+        url,
+        apiKey,
+        credentialName: process.env.AXVAULT_CREDENTIAL,
+    };
+}
+/**
+ * Check if vault is configured.
+ *
+ * @returns true if AXVAULT_URL and AXVAULT_API_KEY are both set
+ */
+function isVaultConfigured() {
+    return getVaultConfig() !== undefined;
+}
+export { getVaultConfig, isVaultConfigured };

package/package.json

@@ -2,7 +2,7 @@
   "name": "axauth",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Authentication management library and CLI for AI coding agents",
   "repository": {
     "type": "git",
@@ -62,7 +62,7 @@
     "automation",
     "coding-assistant"
   ],
-  "packageManager": "pnpm@10.26.1",
+  "packageManager": "pnpm@10.28.0",
   "engines": {
     "node": ">=22.14.0"
   },
@@ -70,19 +70,19 @@
     "@commander-js/extra-typings": "^14.0.0",
     "@inquirer/password": "^5.0.3",
     "axconfig": "^3.6.0",
-    "axshared": "^1.8.0",
+    "axshared": "^1.9.0",
     "commander": "^14.0.2",
     "zod": "^4.3.5"
   },
   "devDependencies": {
     "@total-typescript/ts-reset": "^0.6.1",
-    "@types/node": "^25.0.3",
+    "@types/node": "^25.0.5",
     "@vitest/coverage-v8": "^4.0.16",
     "eslint": "^9.39.2",
-    "eslint-config-axpoint": "^1.0.0",
+    "eslint-config-axkit": "^1.0.0",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.0",
-    "knip": "^5.80.0",
+    "knip": "^5.80.2",
     "prettier": "3.7.4",
     "semantic-release": "^25.0.2",
     "typescript": "^5.9.3",