axauth 3.1.1 → 3.1.4

package/README.md

@@ -24,13 +24,27 @@ axauth provides a consistent interface for managing credentials across multiple
 ## Installation
 
 ```bash
-npm install axauth
+# CLI (global)
+npm install -g axauth
 # or
-pnpm add axauth
+pnpm add -g axauth
+
+# Library usage (non-global)
+npm install axauth
 ```
 
+## Prerequisites
+
+- Node.js 22+
+- pnpm or npm
+- jq for JSON examples
+- Agent CLIs installed (as needed): `claude`, `codex`, `gemini`, `opencode`, `copilot`
+- POSIX shell assumed in examples (bash/zsh); PowerShell needs syntax adjustments
+
 ## CLI Usage
 
+Examples use long-form flags; short flags exist but prefer long for clarity.
+
 ```bash
 # List agents and their auth status
 axauth list
@@ -53,18 +67,34 @@ axauth remove-credentials --agent claude
 axauth remove-credentials --agent claude --config-dir /tmp/config
 ```
 
+## Output Formats
+
+- `axauth list` outputs TSV by default; `--json` returns a JSON array
+- `axauth vault fetch` outputs JSON by default; `--json` pretty-prints JSON
+- `axauth token` outputs the raw token for piping
+
 ### Pipeline Examples
 
-The CLI outputs TSV format for easy processing with standard Unix tools:
+The `axauth list` command outputs TSV with a header row:
+
+- Columns: `AGENT`, `STATUS`, `METHOD`
+- `STATUS` values: `authenticated` | `not_configured`
 
 ```bash
 # List all agents and their auth status
 axauth list
-# AGENT    STATUS          METHOD
-# claude   authenticated   OAuth (max)
-# codex    authenticated   ChatGPT OAuth
-# ...
+```
 
+Output (TSV):
+
+```
+AGENT	STATUS	METHOD
+claude	authenticated	OAuth (max)
+codex	authenticated	ChatGPT OAuth
+...
+```
+
+```bash
 # Filter to show only authenticated agents
 axauth list | tail -n +2 | awk -F'\t' '$2 == "authenticated"'
 
@@ -80,6 +110,10 @@ curl -s -H "Authorization: Bearer $(axauth token --agent claude)" \
   https://api.anthropic.com/api/oauth/usage | jq .
 ```
 
+## Security Note: `--no-password`
+
+`--no-password` uses a deterministic “default password” derived from the source code. This is intended for CI/CD convenience (e.g., storing the exported file as a secret), not for protecting credentials at rest.
+
 ## Library API
 
 ```typescript
@@ -170,9 +204,9 @@ Each agent adapter declares its storage capabilities:
 | Agent    | Keychain | File | Environment | Install API Key |
 | -------- | :------: | :--: | :---------: | :-------------: |
 | claude   |  macOS   | Yes  |     Yes     |  No (env-only)  |
-| codex    |  macOS   | Yes  |     Yes     |  No (env-only)  |
+| codex    |  macOS   | Yes  |     Yes     |       Yes       |
 | gemini   |  macOS   | Yes  |     Yes     |  No (env-only)  |
-| opencode |    No    | Yes  |     Yes     |       No        |
+| opencode |    No    | Yes  |     No      |       Yes       |
 | copilot  |  macOS   | Yes  |     Yes     |  No (env-only)  |
 
 **Notes:**
@@ -215,47 +249,24 @@ For CI/CD workflows, credentials can be passed via environment variables:
 
 Use `installCredentialsFromEnvironmentVariable()` to install credentials from these variables programmatically.
 
-## Config Directory Requirements
+## Custom Directory Behavior
 
-Some agents require specific directory name suffixes:
+Directory handling depends on whether the agent separates config and data:
 
-| Agent    | Directory Requirement    | Example              |
-| -------- | ------------------------ | -------------------- |
-| claude   | Any name                 | `/tmp/my-config`     |
-| codex    | Any name                 | `/tmp/my-config`     |
-| gemini   | Must end with `.gemini`  | `/tmp/home/.gemini`  |
-| copilot  | Must end with `.copilot` | `/tmp/home/.copilot` |
-| opencode | Must end with `opencode` | `/tmp/data/opencode` |
+- **Shared config/data agents** (`claude`, `codex`, `gemini`, `copilot`): `--config-dir` and `--data-dir` are interchangeable and point to the same location.
+- **Separate config/data agent** (`opencode`): `--config-dir` and `--data-dir` are independent.
+  If only one is provided, the other uses the default location and axauth emits a warning.
 
 ## Architecture
 
-axauth follows the adapter pattern with a functional core:
+axauth follows an adapter architecture with a functional core:
 
-```
-src/
-├── index.ts              # Public API exports
-├── cli.ts                # CLI entry point
-├── crypto.ts             # AES-256-GCM encryption
-├── commands/
-│   └── auth.ts           # CLI command handlers
-└── auth/
-    ├── adapter.ts        # AuthAdapter interface
-    ├── types.ts          # AuthStatus, Credentials types
-    ├── registry.ts       # Adapter registry and unified operations
-    └── agents/           # Agent-specific adapters
-        ├── claude-code.ts
-        ├── claude-code-storage.ts
-        ├── codex.ts
-        ├── codex-storage.ts
-        ├── codex-config.ts
-        ├── gemini.ts
-        ├── gemini-storage.ts
-        ├── gemini-auth-check.ts
-        ├── copilot.ts
-        ├── copilot-storage.ts
-        ├── copilot-auth-check.ts
-        └── opencode.ts
-```
+- `src/auth/` — core auth domain logic, adapter interfaces, registry, shared utilities
+- `src/auth/agents/` — agent-specific adapter implementations and storage/install/remove flows
+- `src/commands/` — CLI command handlers (`list`, `token`, `export`, `install-credentials`, `vault`, etc.)
+- `src/vault/` — axvault client/config integration for fetch/push workflows
+- `src/crypto.ts` — credential encryption/decryption primitives (AES-256-GCM + PBKDF2)
+- `src/index.ts` / `src/cli.ts` — library exports and CLI entrypoint
 
 ## Related Packages
 

package/dist/auth/adapter.d.ts

@@ -51,6 +51,8 @@ interface InstallOptions {
     configDir?: string;
     /** Custom data directory for credentials */
     dataDir?: string;
+    /** Provider ID for multi-provider agents (required for OpenCode) */
+    provider?: string;
 }
 /**
  * Options for credential removal.

package/dist/auth/agents/claude.js

@@ -24,14 +24,14 @@ const claudeCodeAdapter = {
         const result = getEnvironmentCredentialsInternal();
         if (!result)
             return undefined;
-        return { agent: AGENT_ID, type: result.type, data: result.data };
+        return { type: result.type, data: result.data };
     },
     findStoredCredentials() {
         const result = findStoredCredentialsInternal();
         if (!result)
             return undefined;
         return {
-            credentials: { agent: AGENT_ID, type: result.type, data: result.data },
+            credentials: { type: result.type, data: result.data },
             source: result.source,
         };
     },

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

@@ -51,7 +51,6 @@ function getEnvironmentCredentials() {
     const environmentKey = getEnvironmentApiKey();
     if (environmentKey) {
         return {
-            agent: AGENT_ID,
             type: "api-key",
             data: { apiKey: environmentKey },
         };
@@ -64,7 +63,6 @@ function extractKeychainCredentials() {
     if (keychainAuth?.OPENAI_API_KEY) {
         return {
             credentials: {
-                agent: AGENT_ID,
                 type: "api-key",
                 data: { apiKey: keychainAuth.OPENAI_API_KEY },
             },
@@ -74,7 +72,6 @@ function extractKeychainCredentials() {
     if (keychainAuth?.tokens) {
         return {
             credentials: {
-                agent: AGENT_ID,
                 type: "oauth-credentials",
                 data: keychainAuth,
             },
@@ -89,7 +86,6 @@ function extractFileCredentials() {
     if (fileAuth?.OPENAI_API_KEY) {
         return {
             credentials: {
-                agent: AGENT_ID,
                 type: "api-key",
                 data: { apiKey: fileAuth.OPENAI_API_KEY },
             },
@@ -99,7 +95,6 @@ function extractFileCredentials() {
     if (fileAuth?.tokens) {
         return {
             credentials: {
-                agent: AGENT_ID,
                 type: "oauth-credentials",
                 data: fileAuth,
             },

package/dist/auth/agents/codex.js

@@ -35,7 +35,7 @@ const codexAdapter = {
             const data = parsed;
             // Determine type from data structure
             const type = data.api_key ? "api-key" : "oauth-credentials";
-            return { agent: AGENT_ID, type, data };
+            return { type, data };
         }
         catch {
             return undefined;

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

@@ -9,13 +9,24 @@
 declare function getConfigDirectory(): string;
 /** Get the default config file path */
 declare function getConfigFilePath(): string;
-/** Load token from keychain */
-declare function loadKeychainToken(host?: string): string | undefined;
+/**
+ * Load token from keychain.
+ *
+ * Searches by service only — the Copilot CLI stores credentials under the
+ * GitHub username (from the OAuth response), which may differ in case from
+ * the OS username ($USER). Service-only search avoids that mismatch.
+ */
+declare function loadKeychainToken(): string | undefined;
 /** Save token to keychain */
 declare function saveKeychainToken(token: string, host?: string): boolean;
 /** Delete token from keychain */
-declare function deleteKeychainToken(host?: string): boolean;
-/** Load token from config file */
+declare function deleteKeychainToken(): boolean;
+/**
+ * Load token from config file.
+ *
+ * Matches by host prefix — the Copilot CLI stores tokens under the GitHub
+ * username (from OAuth), which may differ in case from $USER.
+ */
 declare function loadFileToken(host?: string): string | undefined;
 /** Save token to config file */
 declare function saveFileToken(token: string, host?: string): boolean;

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

@@ -8,7 +8,7 @@
 import { existsSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { ensureDirectory, loadJsonFile, saveJsonFile, } from "../file-storage.js";
-import { deleteFromKeychain, isMacOS, loadFromKeychain, saveToKeychain, } from "../keychain.js";
+import { deleteFromKeychainByService, isMacOS, loadFromKeychainByService, saveToKeychain, } from "../keychain.js";
 import { getResolvedConfigDirectory } from "../resolve-config-directory.js";
 const KEYCHAIN_SERVICE = "copilot-cli";
 const DEFAULT_HOST = "https://github.com";
@@ -24,30 +24,28 @@ function getConfigFilePath() {
 function getUsername() {
     return process.env.USER ?? process.env.USERNAME ?? "user";
 }
-/** Build keychain account key */
-function getKeychainAccount(host = DEFAULT_HOST) {
-    return `${host}:${getUsername()}`;
-}
-/** Load token from keychain */
-function loadKeychainToken(host = DEFAULT_HOST) {
-    if (!isMacOS())
-        return undefined;
-    const account = getKeychainAccount(host);
-    return loadFromKeychain(KEYCHAIN_SERVICE, account);
+/**
+ * Load token from keychain.
+ *
+ * Searches by service only — the Copilot CLI stores credentials under the
+ * GitHub username (from the OAuth response), which may differ in case from
+ * the OS username ($USER). Service-only search avoids that mismatch.
+ */
+function loadKeychainToken() {
+    return loadFromKeychainByService(KEYCHAIN_SERVICE);
 }
 /** Save token to keychain */
 function saveKeychainToken(token, host = DEFAULT_HOST) {
     if (!isMacOS())
         return false;
-    const account = getKeychainAccount(host);
+    // Remove any existing entry first (handles username case mismatches)
+    deleteFromKeychainByService(KEYCHAIN_SERVICE);
+    const account = `${host}:${getUsername()}`;
     return saveToKeychain(KEYCHAIN_SERVICE, account, token);
 }
 /** Delete token from keychain */
-function deleteKeychainToken(host = DEFAULT_HOST) {
-    if (!isMacOS())
-        return false;
-    const account = getKeychainAccount(host);
-    return deleteFromKeychain(KEYCHAIN_SERVICE, account);
+function deleteKeychainToken() {
+    return deleteFromKeychainByService(KEYCHAIN_SERVICE);
 }
 /** Load config file */
 function loadConfig() {
@@ -57,17 +55,36 @@ function loadConfig() {
 function saveConfig(config) {
     return saveJsonFile(getConfigFilePath(), config, { mode: 0o600 });
 }
-/** Load token from config file */
+/** Find the first token key matching a host prefix */
+function findTokenKeyForHost(tokens, host) {
+    const prefix = `${host}:`;
+    return Object.keys(tokens).find((key) => key.startsWith(prefix));
+}
+/**
+ * Load token from config file.
+ *
+ * Matches by host prefix — the Copilot CLI stores tokens under the GitHub
+ * username (from OAuth), which may differ in case from $USER.
+ */
 function loadFileToken(host = DEFAULT_HOST) {
     const config = loadConfig();
-    return config?.copilot_tokens?.[`${host}:${getUsername()}`];
+    if (!config?.copilot_tokens)
+        return undefined;
+    const key = findTokenKeyForHost(config.copilot_tokens, host);
+    return key ? config.copilot_tokens[key] : undefined;
 }
 /** Save token to config file */
 function saveFileToken(token, host = DEFAULT_HOST) {
     const config = loadConfig() ?? {};
     const key = `${host}:${getUsername()}`;
+    // Rebuild tokens without any stale entry for this host (handles username case mismatches)
+    const existing = config.copilot_tokens ?? {};
+    const staleKey = findTokenKeyForHost(existing, host);
+    const filtered = staleKey && staleKey !== key
+        ? Object.fromEntries(Object.entries(existing).filter(([k]) => k !== staleKey))
+        : existing;
     config.copilot_tokens = {
-        ...config.copilot_tokens,
+        ...filtered,
         [key]: token,
     };
     config.store_token_plaintext = true;
@@ -78,12 +95,10 @@ function deleteFileToken(host = DEFAULT_HOST) {
     const config = loadConfig();
     if (!config?.copilot_tokens)
         return false;
-    const key = `${host}:${getUsername()}`;
-    if (!(key in config.copilot_tokens))
+    const key = findTokenKeyForHost(config.copilot_tokens, host);
+    if (!key)
         return false;
-    // Remove the token by filtering out the key
     const remainingTokens = Object.fromEntries(Object.entries(config.copilot_tokens).filter(([k]) => k !== key));
-    // If no tokens left, remove the whole section
     if (Object.keys(remainingTokens).length === 0) {
         const rest = Object.fromEntries(Object.entries(config).filter(([k]) => k !== "copilot_tokens" && k !== "store_token_plaintext"));
         return saveConfig(rest);

package/dist/auth/agents/copilot.js

@@ -27,8 +27,8 @@ const copilotAdapter = {
         }
         const methodMap = {
             environment: `Token (${result.environmentVariable})`,
-            keychain: "Token (keychain)",
-            file: "Token (file)",
+            keychain: "OAuth (keychain)",
+            file: "OAuth (file)",
             "gh-cli": "GitHub CLI",
         };
         return {
@@ -42,7 +42,6 @@ const copilotAdapter = {
         if (!token)
             return undefined;
         return {
-            agent: AGENT_ID,
             type: "oauth-token",
             data: { accessToken: token },
         };
@@ -55,7 +54,6 @@ const copilotAdapter = {
         const source = result.source === "keychain" ? "keychain" : "file";
         return {
             credentials: {
-                agent: AGENT_ID,
                 type: "oauth-token",
                 data: { accessToken: result.token },
             },

package/dist/auth/agents/gemini.js

@@ -34,7 +34,6 @@ const geminiAdapter = {
         if (!result?.data)
             return undefined;
         return {
-            agent: AGENT_ID,
             type: "api-key",
             data: result.data,
         };
@@ -47,7 +46,6 @@ const geminiAdapter = {
         if (result.source === "api-key" || result.source === "vertex-ai") {
             return {
                 credentials: {
-                    agent: AGENT_ID,
                     type: "api-key",
                     data: result.data,
                 },
@@ -57,7 +55,6 @@ const geminiAdapter = {
         // OAuth credentials from keychain or file - return source separately
         return {
             credentials: {
-                agent: AGENT_ID,
                 type: "oauth-credentials",
                 data: result.data,
             },

package/dist/auth/agents/opencode-credentials.js

@@ -44,8 +44,6 @@ function buildCredentials(provider, entry) {
     if (!parsed.success)
         return undefined;
     return {
-        agent: AGENT_ID,
-        provider,
         type: mapToCredentialType(parsed.data),
         data: entry,
     };

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

@@ -21,15 +21,16 @@ function installCredentials(creds, options) {
         if (!existsSync(targetDirectory)) {
             mkdirSync(targetDirectory, { recursive: true, mode: 0o700 });
         }
-        // OpenCode requires per-provider credentials
-        if (creds.agent !== "opencode" || !creds.provider) {
+        // OpenCode requires per-provider credentials via options
+        const rawProvider = options?.provider;
+        if (!rawProvider) {
             return {
                 ok: false,
-                message: "Bundled credential format is no longer supported for OpenCode; please provide per-provider credentials.",
+                message: "OpenCode requires provider option for credential installation.",
             };
         }
         // Validate provider key is non-empty (defensive check for programmatic use)
-        const provider = creds.provider.trim();
+        const provider = rawProvider.trim();
         if (provider.length === 0) {
             return { ok: false, message: "Provider name cannot be empty" };
         }

package/dist/auth/agents/opencode.js

@@ -76,9 +76,7 @@ const opencodeAdapter = {
         }
         return {
             credentials: {
-                agent: AGENT_ID,
                 type: mapToCredentialType(parsed.data),
-                provider: normalizedProvider,
                 data: entry,
             },
             source: "file",
@@ -108,9 +106,7 @@ const opencodeAdapter = {
             if (!parsed.success)
                 return undefined;
             return {
-                agent: AGENT_ID,
                 type: mapToCredentialType(parsed.data),
-                provider: targetProvider,
                 data: entry,
             };
         }

package/dist/auth/build-refreshed-credentials.d.ts

@@ -1,18 +1,18 @@
 /**
- * Build refreshed credentials with provider context preserved.
+ * Build refreshed credentials from refresh operation output.
  */
 import type { Credentials } from "./types.js";
 /**
- * Build refreshed credentials, preserving provider context.
+ * Build refreshed credentials from the refresh operation.
  *
- * For OpenCode (per-provider), extracts the specific provider's refreshed data.
- * For other agents, uses the refreshed data directly.
+ * Returns the refreshed type and data. Provider context is handled
+ * by the caller, not embedded in credentials.
  *
- * @param originalCreds - Original credentials
+ * @param _originalCreds - Original credentials (reserved for future validation)
  * @param refreshedCreds - Credentials returned from refresh operation
  * @returns Built credentials or error message
  */
-declare function buildRefreshedCredentials(originalCreds: Credentials, refreshedCreds: Credentials): {
+declare function buildRefreshedCredentials(_originalCreds: Credentials, refreshedCreds: Credentials): {
     ok: true;
     credentials: Credentials;
 } | {

package/dist/auth/build-refreshed-credentials.js

@@ -1,60 +1,20 @@
 /**
- * Build refreshed credentials with provider context preserved.
+ * Build refreshed credentials from refresh operation output.
  */
 /**
- * Build refreshed credentials, preserving provider context.
+ * Build refreshed credentials from the refresh operation.
  *
- * For OpenCode (per-provider), extracts the specific provider's refreshed data.
- * For other agents, uses the refreshed data directly.
+ * Returns the refreshed type and data. Provider context is handled
+ * by the caller, not embedded in credentials.
  *
- * @param originalCreds - Original credentials
+ * @param _originalCreds - Original credentials (reserved for future validation)
  * @param refreshedCreds - Credentials returned from refresh operation
  * @returns Built credentials or error message
  */
-function buildRefreshedCredentials(originalCreds, refreshedCreds) {
-    // OpenCode per-provider refresh: verify provider matches and use data directly
-    if (originalCreds.agent === "opencode" && originalCreds.provider) {
-        const normalizedProvider = originalCreds.provider.trim();
-        // refreshedCreds from loadCredentialsFromDirectory is now per-provider format:
-        // - refreshedCreds.provider = the provider name
-        // - refreshedCreds.data = the provider's auth entry directly
-        if (refreshedCreds.agent !== "opencode") {
-            return {
-                ok: false,
-                error: `Provider '${normalizedProvider}' not found in refreshed credentials`,
-            };
-        }
-        // TypeScript narrows to OpenCodeCredentials which has provider as required
-        // (z.string().trim().min(1) in axshared) - NOT optional despite Credentials union
-        if (refreshedCreds.provider.trim() !== normalizedProvider) {
-            return {
-                ok: false,
-                error: `Provider '${normalizedProvider}' not found in refreshed credentials`,
-            };
-        }
-        return {
-            ok: true,
-            credentials: {
-                agent: originalCreds.agent,
-                type: refreshedCreds.type,
-                provider: normalizedProvider,
-                data: refreshedCreds.data,
-            },
-        };
-    }
-    // Standard agent refresh: use refreshed data
-    // Both originalCreds and refreshedCreds are standard agents here (not OpenCode)
-    if (originalCreds.agent === "opencode") {
-        // TypeScript narrowing: unreachable, but satisfies type checker
-        return {
-            ok: false,
-            error: "Unexpected OpenCode credential without provider",
-        };
-    }
+function buildRefreshedCredentials(_originalCreds, refreshedCreds) {
     return {
         ok: true,
         credentials: {
-            agent: originalCreds.agent,
             type: refreshedCreds.type,
             data: refreshedCreds.data,
         },

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

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

package/dist/auth/install-from-environment.js

@@ -63,13 +63,6 @@ async function installCredentialsFromEnvironmentCore(parameters) {
     }
     // Install all credentials
     for (const credentials of credentialsList.credentials) {
-        // Defense-in-depth: verify each credential matches the target agent
-        if (credentials.agent !== parameters.agent) {
-            return {
-                ok: false,
-                error: `Credential agent mismatch: expected '${parameters.agent}', got '${credentials.agent}'`,
-            };
-        }
         const result = parameters.installCredentials(credentials, {
             configDir: parameters.configDir,
             dataDir: parameters.dataDir,

package/dist/auth/keychain.d.ts

@@ -9,4 +9,8 @@ declare function loadFromKeychain(service: string, account: string): string | un
 declare function saveToKeychain(service: string, account: string, data: string): boolean;
 /** Delete entry from macOS Keychain */
 declare function deleteFromKeychain(service: string, account: string): boolean;
-export { deleteFromKeychain, isMacOS, loadFromKeychain, saveToKeychain };
+/** Load data from macOS Keychain by service only (any account) */
+declare function loadFromKeychainByService(service: string): string | undefined;
+/** Delete entry from macOS Keychain by service only (first match) */
+declare function deleteFromKeychainByService(service: string): boolean;
+export { deleteFromKeychain, deleteFromKeychainByService, isMacOS, loadFromKeychain, loadFromKeychainByService, saveToKeychain, };

package/dist/auth/keychain.js

@@ -53,4 +53,32 @@ function deleteFromKeychain(service, account) {
         return false;
     }
 }
-export { deleteFromKeychain, isMacOS, loadFromKeychain, saveToKeychain };
+/** Load data from macOS Keychain by service only (any account) */
+function loadFromKeychainByService(service) {
+    if (!isMacOS()) {
+        return undefined;
+    }
+    try {
+        const result = execFileSync("security", ["find-generic-password", "-s", service, "-w"], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+        return result.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Delete entry from macOS Keychain by service only (first match) */
+function deleteFromKeychainByService(service) {
+    if (!isMacOS()) {
+        return false;
+    }
+    try {
+        execFileSync("security", ["delete-generic-password", "-s", service], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export { deleteFromKeychain, deleteFromKeychainByService, isMacOS, loadFromKeychain, loadFromKeychainByService, saveToKeychain, };