axauth 3.1.5 → 3.2.0

package/dist/auth/get-access-token-with-refresh.d.ts

@@ -0,0 +1,12 @@
+import type { AgentCli } from "axshared";
+import type { AuthAdapter, FindStoredCredentialsOptions, InstallOptions, OperationResult, TokenOptions } from "./adapter.js";
+import type { Credentials } from "./types.js";
+interface AccessTokenDependencies {
+    adapter: AuthAdapter;
+    installCredentials: (agentId: AgentCli, creds: Credentials, options?: InstallOptions) => OperationResult;
+}
+declare function findCredentialsWithEnvironmentPriority(adapter: AuthAdapter, options?: FindStoredCredentialsOptions): Credentials | undefined;
+type AccessTokenGetter = (agentId: AgentCli, creds: Credentials, options?: TokenOptions) => Promise<string | undefined>;
+declare function getAgentAccessTokenFromStoredCredentials(agentId: AgentCli, adapter: AuthAdapter, options: TokenOptions | undefined, getAccessToken: AccessTokenGetter): Promise<string | undefined>;
+declare function getAccessTokenWithRefresh(agentId: AgentCli, creds: Credentials, options: TokenOptions | undefined, dependencies: AccessTokenDependencies): Promise<string | undefined>;
+export { findCredentialsWithEnvironmentPriority, getAccessTokenWithRefresh, getAgentAccessTokenFromStoredCredentials, };

package/dist/auth/get-access-token-with-refresh.js

@@ -0,0 +1,47 @@
+import { isCredentialExpired, isTokenExpired } from "./is-token-expired.js";
+import { refreshAndPersist } from "./refresh-credentials.js";
+function findCredentialsWithEnvironmentPriority(adapter, options) {
+    const environmentCredentials = adapter.getEnvironmentCredentials?.();
+    if (environmentCredentials)
+        return environmentCredentials;
+    const stored = adapter.findStoredCredentials(options);
+    return stored?.credentials;
+}
+function shouldRefreshToken(token, creds, options) {
+    if (creds.type === "api-key")
+        return false;
+    if (options?.skipRefresh)
+        return false;
+    let expired = isTokenExpired(token);
+    if (expired === undefined) {
+        expired = isCredentialExpired(creds.data);
+    }
+    return expired === true;
+}
+async function getAgentAccessTokenFromStoredCredentials(agentId, adapter, options, getAccessToken) {
+    const stored = adapter.findStoredCredentials({
+        provider: options?.provider,
+    });
+    if (!stored)
+        return undefined;
+    return getAccessToken(agentId, stored.credentials, {
+        ...options,
+        storage: options?.storage ?? stored.source,
+    });
+}
+async function getAccessTokenWithRefresh(agentId, creds, options, dependencies) {
+    const token = dependencies.adapter.getAccessToken(creds, options);
+    if (!token)
+        return undefined;
+    if (!shouldRefreshToken(token, creds, options)) {
+        return token;
+    }
+    const result = await refreshAndPersist(agentId, creds, (resolvedAgentId, refreshedCreds, installOptions) => dependencies.installCredentials(resolvedAgentId, refreshedCreds, installOptions), {
+        timeout: options?.refreshTimeout,
+        provider: options?.provider,
+        storage: options?.storage,
+    });
+    const finalCreds = result.ok ? result.credentials : result.staleCredentials;
+    return dependencies.adapter.getAccessToken(finalCreds, options);
+}
+export { findCredentialsWithEnvironmentPriority, getAccessTokenWithRefresh, getAgentAccessTokenFromStoredCredentials, };

package/dist/auth/registry.js

@@ -9,9 +9,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 { findCredentialsWithEnvironmentPriority, getAccessTokenWithRefresh, getAgentAccessTokenFromStoredCredentials, } from "./get-access-token-with-refresh.js";
 import { installCredentialsFromEnvironmentCore } from "./install-from-environment.js";
-import { isCredentialExpired, isTokenExpired } from "./is-token-expired.js";
-import { refreshAndPersist } from "./refresh-credentials.js";
 /** Registry of all adapters by agent ID */
 const ADAPTERS = {
     claude: claudeCodeAdapter,
@@ -92,14 +91,7 @@ function checkAllAuth() {
  * const creds = findCredentials("opencode", { provider: "anthropic" });
  */
 function findCredentials(agentId, options) {
-    const adapter = ADAPTERS[agentId];
-    // Check environment credentials first (allows easy overrides in CI/CD)
-    const environmentCredentials = adapter.getEnvironmentCredentials?.();
-    if (environmentCredentials)
-        return environmentCredentials;
-    // Fall back to stored credentials (keychain/file)
-    const stored = adapter.findStoredCredentials(options);
-    return stored?.credentials;
+    return findCredentialsWithEnvironmentPriority(ADAPTERS[agentId], options);
 }
 /**
  * Extract raw credentials from custom directories.
@@ -158,32 +150,10 @@ function removeCredentials(agentId, options) {
  * const token = await getAccessToken(creds, { skipRefresh: true });
  */
 async function getAccessToken(agentId, creds, options) {
-    const token = ADAPTERS[agentId].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(agentId, creds, (aid, c, installOptions) => installCredentials(aid, c, installOptions), {
-        timeout: options?.refreshTimeout,
-        provider: options?.provider,
-        storage: options?.storage,
+    return getAccessTokenWithRefresh(agentId, creds, options, {
+        adapter: ADAPTERS[agentId],
+        installCredentials,
     });
-    const finalCreds = result.ok ? result.credentials : result.staleCredentials;
-    return ADAPTERS[agentId].getAccessToken(finalCreds, options);
 }
 /**
  * Get access token for an agent by ID.
@@ -196,16 +166,7 @@ async function getAccessToken(agentId, creds, options) {
  * const token = await getAgentAccessToken("claude");
  */
 async function getAgentAccessToken(agentId, options) {
-    const stored = ADAPTERS[agentId].findStoredCredentials({
-        provider: options?.provider,
-    });
-    if (!stored)
-        return undefined;
-    // Pass the source to getAccessToken so refresh preserves storage location
-    return getAccessToken(agentId, stored.credentials, {
-        ...options,
-        storage: options?.storage ?? stored.source,
-    });
+    return getAgentAccessTokenFromStoredCredentials(agentId, ADAPTERS[agentId], options, getAccessToken);
 }
 /**
  * Convert credentials to environment variables.

package/dist/cli.js

@@ -9,7 +9,8 @@ import packageJson from "../package.json" with { type: "json" };
 import { handleAuthExport, handleAuthInstall, handleAuthList, handleAuthRemove, handleAuthToken, } from "./commands/auth.js";
 import { handleDecrypt } from "./commands/decrypt.js";
 import { handleEncrypt } from "./commands/encrypt.js";
-import { handleVaultFetch, handleVaultPush } from "./commands/vault.js";
+import { handleVaultFetch } from "./commands/vault-fetch.js";
+import { handleVaultPush } from "./commands/vault-push.js";
 import { AGENT_CLIS } from "axshared";
 // Handle SIGINT gracefully
 process.on("SIGINT", () => {
@@ -198,6 +199,8 @@ vault
     .requiredOption("-a, --agent <agent>", `Agent to push credentials from (${AGENT_CLIS.join(", ")})`)
     .requiredOption("-n, --name <name>", "Credential name in vault (e.g., ci, prod)")
     .option("-p, --provider <provider>", "Provider to push (opencode only; pushes single provider instead of all)")
+    .option("--display-name <name>", "Human-readable display name for this credential (e.g., 'Claude (Work)')")
+    .option("--notes <text>", "Additional notes about this credential")
     .addHelpText("after", String.raw `
 Environment variables (option 1 - single JSON):
   AXVAULT           JSON config: {"url":"...","apiKey":"..."}
@@ -210,6 +213,9 @@ Examples:
   # Push local Claude credentials to vault as "ci"
   axauth vault push --agent claude --name ci
 
+  # Push with a display name for multi-instance identification
+  axauth vault push --agent claude --name work-claude --display-name "Claude (Work)"
+
   # Push a single OpenCode provider to vault
   axauth vault push --agent opencode --provider anthropic --name ci-anthropic
 

package/dist/commands/auth.js

@@ -37,7 +37,9 @@ async function handleAuthToken(options) {
         return;
     }
     // Extract the token based on credential type
-    const token = await getAccessToken(agentId, creds, { provider: options.provider });
+    const token = await getAccessToken(agentId, creds, {
+        provider: options.provider,
+    });
     if (!token) {
         const providerHint = options.provider
             ? ` for provider '${options.provider}'`

package/dist/commands/vault-failure-messages.d.ts

@@ -0,0 +1,4 @@
+import type { VaultFailureReason } from "../vault/vault-client.js";
+/** Human-readable error messages for vault failures */
+declare const FAILURE_MESSAGES: Record<VaultFailureReason, string>;
+export { FAILURE_MESSAGES };

package/dist/commands/vault-failure-messages.js

@@ -0,0 +1,12 @@
+/** 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 required 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.",
+};
+export { FAILURE_MESSAGES };

package/dist/commands/{vault.d.ts → vault-fetch.d.ts}

@@ -1,5 +1,5 @@
 /**
- * Vault commands - fetch and push credentials to axvault server.
+ * Vault fetch command - download credentials from axvault server.
  */
 interface VaultFetchOptions {
     agent: string;
@@ -19,17 +19,4 @@ interface VaultFetchOptions {
  * - Outputs shell export commands with --env flag (for eval/source)
  */
 declare function handleVaultFetch(options: VaultFetchOptions): Promise<void>;
-interface VaultPushOptions {
-    agent: string;
-    name: string;
-    provider?: string;
-}
-/**
- * Handle vault push command.
- *
- * Reads local credentials for an agent and pushes them to the vault server
- * in raw (unencrypted) format. This allows the vault to handle encryption
- * and automatic token refresh.
- */
-declare function handleVaultPush(options: VaultPushOptions): Promise<void>;
-export { handleVaultFetch, handleVaultPush };
+export { handleVaultFetch };

package/dist/commands/{vault.js → vault-fetch.js}

@@ -1,22 +1,11 @@
 /**
- * Vault commands - fetch and push credentials to axvault server.
+ * Vault fetch command - download credentials from axvault server.
  */
-import { credentialsToEnvironment, findCredentials, installCredentials, } from "../auth/registry.js";
-import { getStoredCredentialsForProvider } from "../auth/agents/opencode.js";
-import { fetchVaultCredentials, pushVaultCredentials, } from "../vault/vault-client.js";
+import { credentialsToEnvironment, installCredentials, } from "../auth/registry.js";
+import { fetchVaultCredentials } from "../vault/vault-client.js";
 import { getVaultConfig } from "../vault/vault-config.js";
+import { FAILURE_MESSAGES } from "./vault-failure-messages.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.
@@ -66,7 +55,7 @@ async function handleVaultFetch(options) {
         process.exitCode = 1;
         return;
     }
-    const { credentials, refreshed } = result;
+    const { credentials, refreshed, displayName, notes } = result;
     // Log refresh status to stderr (not stdout, to allow piping)
     if (refreshed) {
         console.error("Note: Credentials were auto-refreshed by vault");
@@ -112,71 +101,18 @@ async function handleVaultFetch(options) {
     }
     else {
         // Output credentials as JSON (default)
+        const output = {
+            ...credentials,
+            ...(displayName !== undefined && { displayName }),
+            ...(notes !== undefined && { notes }),
+        };
         if (options.json) {
-            console.log(JSON.stringify(credentials, undefined, 2));
+            console.log(JSON.stringify(output, undefined, 2));
         }
         else {
             // Compact JSON for piping
-            console.log(JSON.stringify(credentials));
+            console.log(JSON.stringify(output));
         }
     }
 }
-/**
- * Handle vault push command.
- *
- * Reads local credentials for an agent and pushes them to the vault server
- * in raw (unencrypted) format. This allows the vault to handle encryption
- * and automatic token refresh.
- */
-async function handleVaultPush(options) {
-    // Validate agent
-    const agentId = validateAgent(options.agent);
-    if (!agentId)
-        return;
-    // Validate provider flag usage
-    if (options.provider && agentId !== "opencode") {
-        console.error("Error: --provider flag is only supported for opencode agent");
-        process.exitCode = 2;
-        return;
-    }
-    if (agentId === "opencode" && !options.provider) {
-        console.error("Error: --provider is required for opencode");
-        console.error("Hint: Use 'axauth list --json' to see available providers");
-        process.exitCode = 1;
-        return;
-    }
-    // Check vault is configured
-    const vaultConfig = getVaultConfig();
-    if (!vaultConfig) {
-        console.error(`Error: ${FAILURE_MESSAGES["not-configured"]}`);
-        process.exitCode = 1;
-        return;
-    }
-    // Extract local credentials
-    const credentials = agentId === "opencode" && options.provider
-        ? getStoredCredentialsForProvider(options.provider)
-        : findCredentials(agentId);
-    if (!credentials) {
-        const hint = agentId === "opencode"
-            ? `No credentials found for provider '${options.provider}'`
-            : `No credentials found for ${agentId}\nHint: Authenticate with the agent first, or use 'axauth list' to check status`;
-        console.error(`Error: ${hint}`);
-        process.exitCode = 1;
-        return;
-    }
-    // Push to vault
-    const result = await pushVaultCredentials({
-        agentId,
-        name: options.name,
-        credentials,
-        provider: options.provider,
-    });
-    if (!result.ok) {
-        console.error(`Error: ${FAILURE_MESSAGES[result.reason]}`);
-        process.exitCode = 1;
-        return;
-    }
-    const label = options.provider ? `${agentId}/${options.provider}` : agentId;
-    console.error(`Credentials pushed to vault: ${label} → ${options.name}`);
-}
-export { handleVaultFetch, handleVaultPush };
+export { handleVaultFetch };

package/dist/commands/vault-push.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Vault push command - upload local credentials to axvault server.
+ */
+interface VaultPushOptions {
+    agent: string;
+    name: string;
+    provider?: string;
+    displayName?: string;
+    notes?: string;
+}
+/**
+ * Handle vault push command.
+ *
+ * Reads local credentials for an agent and pushes them to the vault server
+ * in raw (unencrypted) format. This allows the vault to handle encryption
+ * and automatic token refresh.
+ */
+declare function handleVaultPush(options: VaultPushOptions): Promise<void>;
+export { handleVaultPush };

package/dist/commands/vault-push.js

@@ -0,0 +1,70 @@
+/**
+ * Vault push command - upload local credentials to axvault server.
+ */
+import { findCredentials } from "../auth/registry.js";
+import { getStoredCredentialsForProvider } from "../auth/agents/opencode.js";
+import { pushVaultCredentials } from "../vault/vault-client.js";
+import { getVaultConfig } from "../vault/vault-config.js";
+import { FAILURE_MESSAGES } from "./vault-failure-messages.js";
+import { validateAgent } from "./validate-agent.js";
+/**
+ * Handle vault push command.
+ *
+ * Reads local credentials for an agent and pushes them to the vault server
+ * in raw (unencrypted) format. This allows the vault to handle encryption
+ * and automatic token refresh.
+ */
+async function handleVaultPush(options) {
+    // Validate agent
+    const agentId = validateAgent(options.agent);
+    if (!agentId)
+        return;
+    // Validate provider flag usage
+    if (options.provider && agentId !== "opencode") {
+        console.error("Error: --provider flag is only supported for opencode agent");
+        process.exitCode = 2;
+        return;
+    }
+    if (agentId === "opencode" && !options.provider) {
+        console.error("Error: --provider is required for opencode");
+        console.error("Hint: Use 'axauth list --json' to see available providers");
+        process.exitCode = 1;
+        return;
+    }
+    // Check vault is configured
+    const vaultConfig = getVaultConfig();
+    if (!vaultConfig) {
+        console.error(`Error: ${FAILURE_MESSAGES["not-configured"]}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Extract local credentials
+    const credentials = agentId === "opencode" && options.provider
+        ? getStoredCredentialsForProvider(options.provider)
+        : findCredentials(agentId);
+    if (!credentials) {
+        const hint = agentId === "opencode"
+            ? `No credentials found for provider '${options.provider}'`
+            : `No credentials found for ${agentId}\nHint: Authenticate with the agent first, or use 'axauth list' to check status`;
+        console.error(`Error: ${hint}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Push to vault
+    const result = await pushVaultCredentials({
+        agentId,
+        name: options.name,
+        credentials,
+        provider: options.provider,
+        displayName: options.displayName,
+        notes: options.notes,
+    });
+    if (!result.ok) {
+        console.error(`Error: ${FAILURE_MESSAGES[result.reason]}`);
+        process.exitCode = 1;
+        return;
+    }
+    const label = options.provider ? `${agentId}/${options.provider}` : agentId;
+    console.error(`Credentials pushed to vault: ${label} → ${options.name}`);
+}
+export { handleVaultPush };

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

@@ -14,6 +14,8 @@ type VaultResult = {
     ok: true;
     credentials: Credentials;
     refreshed: boolean;
+    displayName: string | undefined;
+    notes: string | undefined;
 } | {
     ok: false;
     reason: VaultFailureReason;
@@ -61,6 +63,10 @@ interface VaultPushOptions {
     credentials: Credentials;
     /** Provider for multi-provider agents (e.g., "anthropic" for OpenCode) */
     provider?: string;
+    /** Human-readable display name for this credential */
+    displayName?: string;
+    /** Additional notes about this credential */
+    notes?: string;
 }
 /**
  * Push credentials to the axvault server.

package/dist/vault/vault-client.js

@@ -11,6 +11,14 @@ import { getVaultConfig } from "./vault-config.js";
 const VaultCredentialResponse = z.object({
     name: z.string(),
     credential: z.record(z.string(), z.unknown()),
+    displayName: z
+        .string()
+        .nullish()
+        .transform((value) => value ?? undefined),
+    notes: z
+        .string()
+        .nullish()
+        .transform((value) => value ?? undefined),
     updatedAt: z.string(),
 });
 /**
@@ -84,6 +92,8 @@ async function fetchVaultCredentials(options) {
             ok: true,
             credentials: body.credential,
             refreshed: wasRefreshed,
+            displayName: body.displayName,
+            notes: body.notes,
         };
     }
     catch {
@@ -133,6 +143,10 @@ async function pushVaultCredentials(options) {
                 type: options.credentials.type,
                 data: options.credentials.data,
                 ...(options.provider !== undefined && { provider: options.provider }),
+                ...(options.displayName !== undefined && {
+                    displayName: options.displayName,
+                }),
+                ...(options.notes !== undefined && { notes: options.notes }),
             }),
         });
         // Handle error responses

package/package.json

@@ -2,7 +2,7 @@
   "name": "axauth",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "3.1.5",
+  "version": "3.2.0",
   "description": "Authentication management library and CLI for AI coding agents",
   "repository": {
     "type": "git",
@@ -62,31 +62,31 @@
     "automation",
     "coding-assistant"
   ],
-  "packageManager": "pnpm@10.28.1",
+  "packageManager": "pnpm@10.30.1",
   "engines": {
     "node": ">=22.14.0"
   },
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
-    "@inquirer/password": "^5.0.4",
+    "@inquirer/password": "^5.0.7",
     "axconfig": "^3.6.3",
-    "axexec": "^2.0.0",
+    "axexec": "^2.0.1",
     "axshared": "^5.0.0",
-    "commander": "^14.0.2",
-    "zod": "^4.3.5"
+    "commander": "^14.0.3",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@total-typescript/ts-reset": "^0.6.1",
-    "@types/node": "^25.0.10",
-    "@vitest/coverage-v8": "^4.0.17",
-    "eslint": "^9.39.2",
-    "eslint-config-axkit": "^1.1.0",
+    "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.1",
+    "eslint-config-axkit": "^1.2.1",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.0",
-    "knip": "^5.82.1",
+    "knip": "^5.85.0",
     "prettier": "3.8.1",
-    "semantic-release": "^25.0.2",
+    "semantic-release": "^25.0.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   }
 }