axauth 1.0.0 → 1.2.0

package/README.md

@@ -1,46 +1,35 @@
 # axauth
 
-Authentication management library and CLI for AI coding agents.
+Unified authentication management for AI coding agents.
 
 ## Overview
 
-axauth manages credentials for AI coding agents. It can be used:
+axauth provides a consistent interface for managing credentials across multiple AI coding agent CLIs. It abstracts away the differences between agent-specific credential storage mechanisms (macOS Keychain, file-based storage, environment variables) and provides:
 
-1. **As a library** - imported to check auth status, extract tokens, and manage credentials programmatically
-2. **As a CLI** - standalone tool for managing agent credentials
+- **Auth status detection** - Check which agents are authenticated and via which method
+- **Credential extraction** - Extract tokens for API calls or export/import workflows
+- **Portable credential export** - Encrypted credential files for CI/CD and backup
+- **Multi-storage support** - Keychain (macOS), file storage, and environment variables
 
 ## Supported Agents
 
-- **claude-code** - Claude Code (Anthropic)
-- **codex** - Codex CLI (OpenAI)
-- **gemini** - Gemini CLI (Google)
-- **opencode** - OpenCode
+| Agent       | CLI        | Provider  | Auth Methods                               |
+| ----------- | ---------- | --------- | ------------------------------------------ |
+| Claude Code | `claude`   | Anthropic | OAuth (keychain/file), `ANTHROPIC_API_KEY` |
+| Codex CLI   | `codex`    | OpenAI    | ChatGPT OAuth, `OPENAI_API_KEY`            |
+| Gemini CLI  | `gemini`   | Google    | OAuth, `GEMINI_API_KEY`                    |
+| OpenCode    | `opencode` | Sst       | Multi-provider OAuth                       |
+| Copilot CLI | `copilot`  | GitHub    | OAuth, `GH_TOKEN`/`GITHUB_TOKEN`           |
 
-## Library API
-
-```typescript
-import { checkAuth, getAgentAccessToken, extractCredentials } from "axauth";
-
-// Check auth status for an agent
-const status = checkAuth("claude-code");
-if (status.authenticated) {
-  console.log(`Authenticated via ${status.method}`);
-}
+## Installation
 
-// Get access token for API calls
-const token = getAgentAccessToken("claude-code");
-if (token) {
-  // Use token for API calls
-}
-
-// Extract full credentials for export
-const creds = extractCredentials("claude-code");
-if (creds) {
-  // creds.accessToken, creds.refreshToken, etc.
-}
+```bash
+npm install axauth
+# or
+pnpm add axauth
 ```
 
-## CLI Commands
+## CLI Usage
 
 ```bash
 # List agents and their auth status
@@ -48,29 +37,31 @@ axauth list
 axauth list --json
 
 # Get access token for an agent (outputs raw token for piping)
-axauth token --agent claude-code
+axauth token --agent claude
 
 # Export credentials to encrypted file
-axauth export --agent claude-code --output creds.json
-axauth export --agent claude-code --output creds.json --no-password
-
-# Remove credentials (agent will prompt for login)
-axauth remove-credentials --agent claude-code
+axauth export --agent claude --output creds.json
+axauth export --agent claude --output creds.json --no-password
 
 # Install credentials from exported file
-axauth install-credentials --agent claude-code --input creds.json
+axauth install-credentials --agent claude --input creds.json
+axauth install-credentials --agent claude --input creds.json --config-dir /tmp/config
+
+# Remove credentials (agent will prompt for login on next use)
+axauth remove-credentials --agent claude
+axauth remove-credentials --agent claude --config-dir /tmp/config
 ```
 
-## Pipeline Examples
+### Pipeline Examples
 
 The CLI outputs TSV format for easy processing with standard Unix tools:
 
 ```bash
 # List all agents and their auth status
 axauth list
-# AGENT         STATUS          METHOD
-# claude-code   authenticated   OAuth (max)
-# codex         authenticated   ChatGPT OAuth
+# AGENT    STATUS          METHOD
+# claude   authenticated   OAuth (max)
+# codex    authenticated   ChatGPT OAuth
 # ...
 
 # Filter to show only authenticated agents
@@ -79,68 +70,194 @@ axauth list | tail -n +2 | awk -F'\t' '$2 == "authenticated"'
 # Count agents by status
 axauth list | tail -n +2 | cut -f2 | sort | uniq -c
 
-# Extract agent names as a list
-axauth list | tail -n +2 | cut -f1
-
 # Check if a specific agent is authenticated
-axauth list --json | jq -e '.[] | select(.agentId == "claude-code") | .authenticated'
+axauth list --json | jq -e '.[] | select(.agentId == "claude") | .authenticated'
 
-# Check Claude Code usage via OAuth endpoint
-curl -s -H "Authorization: Bearer $(axauth token --agent claude-code)" \
+# Use token with curl
+curl -s -H "Authorization: Bearer $(axauth token --agent claude)" \
   -H "anthropic-beta: oauth-2025-04-20" \
   https://api.anthropic.com/api/oauth/usage | jq .
 ```
 
-## Module Structure
+## Library API
 
+```typescript
+import {
+  // Core operations
+  checkAuth, // Check single agent auth status
+  checkAllAuth, // Check all agents' auth status
+  getAgentAccessToken, // Get access token for an agent
+  extractRawCredentials, // Extract full credentials for export
+  installCredentials, // Install credentials to storage
+  removeCredentials, // Remove credentials from storage
+
+  // Credential utilities
+  getAccessToken, // Extract token from credential object
+  credentialsToEnvironment, // Convert credentials to env vars
+  getCredentialsEnvironmentVariableName, // Get AX_*_CREDENTIALS var name
+  installCredentialsFromEnvironmentVariable, // Install from env var (CI/CD)
+
+  // Adapter access
+  getAdapter, // Get adapter for an agent
+  getAllAdapters, // Get all adapters
+  getCapabilities, // Check adapter capabilities
+} from "axauth";
+
+// Types
+import type {
+  AgentCli, // "claude" | "codex" | "gemini" | "opencode" | "copilot"
+  AuthStatus, // { agentId, authenticated, method?, details? }
+  Credentials, // { agent, type, data }
+  AuthAdapter, // Adapter interface
+  AdapterCapabilities, // { keychain, file, environment, installApiKey }
+} from "axauth";
 ```
-src/
-├── types.ts                # AgentId type definition
-├── crypto.ts               # AES-256-GCM encryption for credentials
-├── cli.ts                  # CLI entry point
-├── commands/
-│   └── auth.ts             # CLI command handlers
-└── auth/
-    ├── check-auth.ts       # Auth status detection
-    ├── extract-credentials.ts  # Credential extraction
-    ├── get-access-token.ts     # Token retrieval
-    ├── install-credentials.ts  # Credential installation
-    ├── remove-credentials.ts   # Credential removal
-    ├── keychain.ts         # macOS Keychain utilities
-    ├── file-storage.ts     # File I/O utilities
-    ├── types.ts            # Auth types
-    └── agents/             # Agent-specific implementations
-        ├── claude-code.ts
-        ├── codex.ts
-        ├── gemini.ts
-        └── opencode.ts
+
+### Examples
+
+```typescript
+import { checkAuth, getAgentAccessToken, getCapabilities } from "axauth";
+
+// Check auth status for an agent
+const status = checkAuth("claude");
+if (status.authenticated) {
+  console.log(`Authenticated via ${status.method}`);
+}
+
+// Get access token for API calls
+const token = getAgentAccessToken("claude");
+if (token) {
+  // Use token for API calls
+}
+
+// Check adapter capabilities
+const caps = getCapabilities("gemini");
+if (!caps.keychain) {
+  console.log("Gemini requires file storage on this platform");
+}
+```
+
+### Adapter Pattern
+
+Each agent implements the `AuthAdapter` interface, hiding storage complexity:
+
+```typescript
+import { getAdapter } from "axauth";
+
+const adapter = getAdapter("claude");
+
+// All adapters have the same interface
+const status = adapter.checkAuth();
+const creds = adapter.extractRawCredentials();
+const token = adapter.getAccessToken(creds);
+const envVars = adapter.credentialsToEnvironment(creds);
+
+// Check what the adapter supports
+console.log(adapter.capabilities);
+// { keychain: true, file: true, environment: true, installApiKey: false }
+```
+
+## Adapter Capabilities
+
+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)  |
+| gemini   |  macOS   | Yes  |     Yes     |  No (env-only)  |
+| opencode |    No    | Yes  |     Yes     |       No        |
+| copilot  |  macOS   | Yes  |     Yes     |  No (env-only)  |
+
+**Notes:**
+
+- **Keychain**: macOS Keychain support (not available on Linux/Windows)
+- **File**: File-based credential storage
+- **Environment**: Can read credentials from environment variables
+- **Install API Key**: Whether API keys can be installed (vs. read from env only)
+
+## Credential Export Format
+
+Exported credentials are encrypted with AES-256-GCM:
+
+```json
+{
+  "version": 1,
+  "agent": "claude",
+  "ciphertext": "<base64>",
+  "salt": "<base64>",
+  "iv": "<base64>",
+  "tag": "<base64>"
+}
 ```
 
-## Authentication Methods
+- Key derivation: PBKDF2 with SHA-256, 100,000 iterations
+- Use `--no-password` for CI/CD (uses a default password)
+- Files are written with `0o600` permissions
+
+## Environment Variables
+
+For CI/CD workflows, credentials can be passed via environment variables:
+
+| Agent    | Credential Env Var        |
+| -------- | ------------------------- |
+| claude   | `AX_CLAUDE_CREDENTIALS`   |
+| codex    | `AX_CODEX_CREDENTIALS`    |
+| gemini   | `AX_GEMINI_CREDENTIALS`   |
+| copilot  | `AX_COPILOT_CREDENTIALS`  |
+| opencode | `AX_OPENCODE_CREDENTIALS` |
+
+Use `installCredentialsFromEnvironmentVariable()` to install credentials from these variables programmatically.
 
-| Agent       | Methods                                    |
-| ----------- | ------------------------------------------ |
-| claude-code | OAuth (keychain/file) or ANTHROPIC_API_KEY |
-| codex       | ChatGPT OAuth or OPENAI_API_KEY            |
-| gemini      | OAuth or GEMINI_API_KEY                    |
-| opencode    | Multi-provider OAuth                       |
+## Config Directory Requirements
 
-## Agent Rule
+Some agents require specific directory name suffixes:
 
-Add to your `CLAUDE.md` or `AGENTS.md`:
+| 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` |
 
-```markdown
-# Rule: `axauth` Usage
+## Architecture
 
-Run `npx -y axauth --help` to learn available options.
+axauth follows the adapter pattern with a functional core:
 
-Use `axauth` to manage AI agent credentials. Check auth status with `axauth list`,
-get tokens with `axauth token`, and export/import credentials for CI/CD workflows.
 ```
+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
+```
+
+## Related Packages
 
-## Development Status
+axauth is part of the [a╳point](https://axpoint.dev) ecosystem:
 
-🚧 **Work in Progress**
+- **axshared** - Shared types and agent metadata
+- **axconfig** - Permission and configuration management
+- **axrun** - Agent execution and output normalization
 
 ## License
 

package/dist/auth/adapter.d.ts

@@ -16,32 +16,63 @@ interface OperationResult {
 /**
  * Options for credential installation.
  *
- * When `path` is provided, credentials are always written as a file to that
- * path (keychain is only for default location). The `storage` option is ignored.
+ * When custom directories are provided, credentials are always written as files
+ * (keychain is only for default location). The `storage` option is ignored.
  *
- * When `path` is not provided, `storage` controls where credentials go:
+ * When no directories are provided, `storage` controls where credentials go:
  * - `"keychain"`: Store in macOS Keychain (if supported)
  * - `"file"`: Store in agent's default file location
  * - `undefined`: Use the `_source` marker in credentials, or default to file
+ *
+ * **Agents without separation** (Claude, Codex, Gemini, Copilot):
+ * - Config and data are stored in the same directory
+ * - `configDir` and `dataDir` are interchangeable (either works)
+ * - Providing different values for both will result in an error
+ *
+ * **Agents with separation** (OpenCode):
+ * - Config and data are stored in separate directories
+ * - `dataDir` controls where credentials go; `configDir` is for settings
+ * - If only `configDir` provided, credentials use default data location
+ * - If only `dataDir` provided, config uses default location
  */
 interface InstallOptions {
-    /** Storage type for default location (ignored if path is set) */
+    /** Storage type for default location (ignored if configDir/dataDir is set) */
     storage?: StorageType;
-    /** Custom file path (forces file storage, keychain not available) */
-    path?: string;
+    /** Custom config directory for settings/preferences */
+    configDir?: string;
+    /** Custom data directory for credentials */
+    dataDir?: string;
 }
 /**
  * Options for credential removal.
  *
- * When `path` is provided, only the file at that path is removed.
- * Keychain credentials are not affected (keychain is only for default location).
+ * When `dataDir` is provided, only the credentials file in that directory
+ * is removed. Keychain credentials are not affected (keychain is only for
+ * default location).
  *
- * When `path` is not provided, credentials are removed from all default
- * locations (keychain and/or default file path).
+ * **Agents without separation** (Claude, Codex, Gemini, Copilot):
+ * - `configDir` and `dataDir` are interchangeable
+ * - Either option specifies where to remove credentials from
+ *
+ * **Agents with separation** (OpenCode):
+ * - `dataDir` specifies where to remove credentials from
+ * - If only `configDir` provided, credentials are removed from default location
  */
 interface RemoveOptions {
-    /** Custom file path to remove (only removes this file, not keychain) */
-    path?: string;
+    /** Custom config directory for settings/preferences */
+    configDir?: string;
+    /** Custom data directory for credentials */
+    dataDir?: string;
+}
+/**
+ * Options for token extraction.
+ *
+ * Some agents (like opencode) support multiple providers. Use the `provider`
+ * option to specify which provider's token to extract.
+ */
+interface TokenOptions {
+    /** Provider ID for multi-provider agents (e.g., "anthropic", "openai") */
+    provider?: string;
 }
 /** Capabilities that an adapter supports */
 interface AdapterCapabilities {
@@ -95,10 +126,10 @@ interface AuthAdapter {
     /**
      * Remove credentials from storage.
      *
-     * When `options.path` is provided, only the file at that path is removed.
-     * Keychain credentials are not affected.
+     * When `options.configDir` is provided, only the credentials file in that
+     * directory is removed. Keychain credentials are not affected.
      *
-     * When `options.path` is not provided, credentials are removed from all
+     * When `options.configDir` is not provided, credentials are removed from all
      * default locations (keychain and/or default file path).
      */
     removeCredentials(options?: RemoveOptions): OperationResult;
@@ -107,8 +138,11 @@ interface AuthAdapter {
      *
      * Returns the primary access token (OAuth token or API key) from
      * the credential data. Returns undefined if no token found.
+     *
+     * For multi-provider agents (like opencode), use `options.provider`
+     * to specify which provider's token to extract.
      */
-    getAccessToken(creds: Credentials): string | undefined;
+    getAccessToken(creds: Credentials, options?: TokenOptions): string | undefined;
     /**
      * Convert credentials to environment variables.
      *
@@ -118,4 +152,4 @@ interface AuthAdapter {
      */
     credentialsToEnvironment(creds: Credentials): Record<string, string>;
 }
-export type { AdapterCapabilities, AuthAdapter, InstallOptions, OperationResult, RemoveOptions, };
+export type { AdapterCapabilities, AuthAdapter, InstallOptions, OperationResult, RemoveOptions, TokenOptions, };

package/dist/auth/agents/{claude-code-storage.d.ts → claude-storage.d.ts}

@@ -3,10 +3,6 @@
  */
 /** Get default credentials file path */
 declare function getDefaultCredsFilePath(): string;
-/** Load OAuth credentials from keychain */
-declare function loadKeychainCreds(): Record<string, unknown> | undefined;
-/** Load OAuth credentials from file */
-declare function loadFileCreds(): Record<string, unknown> | undefined;
 /** Save credentials to keychain */
 declare function saveKeychainCreds(oauthData: Record<string, unknown>): boolean;
 /** Save credentials to file */
@@ -15,4 +11,16 @@ declare function saveFileCreds(oauthData: Record<string, unknown>, filePath: str
 declare function deleteKeychainCreds(): boolean;
 /** Delete credentials from file */
 declare function deleteFileCreds(filePath?: string): boolean;
-export { deleteFileCreds, deleteKeychainCreds, getDefaultCredsFilePath, loadFileCreds, loadKeychainCreds, saveFileCreds, saveKeychainCreds, };
+declare const AGENT_ID: "claude";
+/** Check if Claude is authenticated and return status */
+declare function checkAuth(): {
+    authenticated: boolean;
+    method?: string;
+    details?: Record<string, unknown>;
+};
+/** Extract raw credentials from available sources */
+declare function extractRawCredentials(): {
+    type: "oauth" | "api-key";
+    data: Record<string, unknown>;
+} | undefined;
+export { AGENT_ID, checkAuth, deleteFileCreds, deleteKeychainCreds, extractRawCredentials, getDefaultCredsFilePath, saveFileCreds, saveKeychainCreds, };

package/dist/auth/agents/{claude-code-storage.js → claude-storage.js}

@@ -4,7 +4,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { userInfo } from "node:os";
 import path from "node:path";
-import { claudeCodeConfigReader } from "axconfig";
 import { deleteFile, loadJsonFile, saveJsonFile } from "../file-storage.js";
 import { getResolvedConfigDirectory } from "../resolve-config-directory.js";
 import { deleteFromKeychain, loadFromKeychain, saveToKeychain, } from "../keychain.js";
@@ -15,7 +14,7 @@ function getUsername() {
 }
 /** Get default credentials file path */
 function getDefaultCredsFilePath() {
-    return path.join(getResolvedConfigDirectory(claudeCodeConfigReader), ".credentials.json");
+    return path.join(getResolvedConfigDirectory("claude"), ".credentials.json");
 }
 /** Load OAuth credentials from keychain */
 function loadKeychainCreds() {
@@ -63,4 +62,53 @@ function deleteKeychainCreds() {
 function deleteFileCreds(filePath) {
     return deleteFile(filePath ?? getDefaultCredsFilePath());
 }
-export { deleteFileCreds, deleteKeychainCreds, getDefaultCredsFilePath, loadFileCreds, loadKeychainCreds, saveFileCreds, saveKeychainCreds, };
+const AGENT_ID = "claude";
+/** Check if Claude is authenticated and return status */
+function checkAuth() {
+    if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+        return { authenticated: true, method: "OAuth (env)" };
+    }
+    const keychainCreds = loadKeychainCreds();
+    if (keychainCreds) {
+        const subType = keychainCreds.subscriptionType;
+        return { authenticated: true, method: `OAuth (${subType ?? "keychain"})` };
+    }
+    if (loadFileCreds()) {
+        return { authenticated: true, method: "OAuth (file)" };
+    }
+    if (process.env.ANTHROPIC_API_KEY) {
+        return { authenticated: true, method: "API key" };
+    }
+    return { authenticated: false };
+}
+/** Extract raw credentials from available sources */
+function extractRawCredentials() {
+    if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+        return {
+            type: "oauth",
+            data: { accessToken: process.env.CLAUDE_CODE_OAUTH_TOKEN },
+        };
+    }
+    const keychainCreds = loadKeychainCreds();
+    if (keychainCreds) {
+        return {
+            type: "oauth",
+            data: { ...keychainCreds, _source: "keychain" },
+        };
+    }
+    const fileCreds = loadFileCreds();
+    if (fileCreds) {
+        return {
+            type: "oauth",
+            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, };