axauth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Łukasz Jerciński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# axauth
+
+Authentication management library and CLI for AI coding agents.
+
+## Overview
+
+axauth manages credentials for AI coding agents. It can be used:
+
+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
+
+## Supported Agents
+
+- **claude-code** - Claude Code (Anthropic)
+- **codex** - Codex CLI (OpenAI)
+- **gemini** - Gemini CLI (Google)
+- **opencode** - OpenCode
+
+## 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}`);
+}
+
+// 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.
+}
+```
+
+## CLI Commands
+
+```bash
+# List agents and their auth status
+axauth list
+axauth list --json
+
+# Get access token for an agent (outputs raw token for piping)
+axauth token --agent claude-code
+
+# 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
+
+# Install credentials from exported file
+axauth install-credentials --agent claude-code --input creds.json
+```
+
+## 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
+# ...
+
+# Filter to show only authenticated agents
+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'
+
+# Check Claude Code usage via OAuth endpoint
+curl -s -H "Authorization: Bearer $(axauth token --agent claude-code)" \
+  -H "anthropic-beta: oauth-2025-04-20" \
+  https://api.anthropic.com/api/oauth/usage | jq .
+```
+
+## Module Structure
+
+```
+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
+```
+
+## Authentication Methods
+
+| 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                       |
+
+## Agent Rule
+
+Add to your `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+# Rule: `axauth` Usage
+
+Run `npx -y axauth --help` to learn available options.
+
+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.
+```
+
+## Development Status
+
+🚧 **Work in Progress**
+
+## License
+
+MIT

package/bin/axauth

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point that dynamically imports the compiled TypeScript.
+ *
+ * Uses top-level await to ensure module evaluation errors are handled
+ * properly. Without await, errors during import would surface as unhandled
+ * rejections instead of clean CLI failures with appropriate exit codes.
+ */
+try {
+  await import("../dist/cli.js");
+} catch (error) {
+  console.error(
+    "Failed to start axauth:",
+    error instanceof Error ? error.message : error,
+  );
+  process.exitCode = 1;
+}

package/dist/auth/adapter.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Unified authentication adapter interface.
+ *
+ * All agents implement this interface, providing a consistent API
+ * for auth operations regardless of underlying storage mechanism.
+ */
+import type { AgentCli } from "axshared";
+import type { AuthStatus, Credentials } from "./types.js";
+/** Storage type preference for credential installation */
+type StorageType = "keychain" | "file";
+/** Result of an auth operation (install, remove) */
+interface OperationResult {
+    ok: boolean;
+    message: string;
+}
+/**
+ * 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 `path` is not 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
+ */
+interface InstallOptions {
+    /** Storage type for default location (ignored if path is set) */
+    storage?: StorageType;
+    /** Custom file path (forces file storage, keychain not available) */
+    path?: 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 `path` is not provided, credentials are removed from all default
+ * locations (keychain and/or default file path).
+ */
+interface RemoveOptions {
+    /** Custom file path to remove (only removes this file, not keychain) */
+    path?: string;
+}
+/** Capabilities that an adapter supports */
+interface AdapterCapabilities {
+    /** Whether keychain storage is supported (macOS only) */
+    keychain: boolean;
+    /** Whether file storage is supported */
+    file: boolean;
+    /** Whether environment variable auth is supported */
+    environment: boolean;
+    /** Whether API key credentials can be installed (vs env-only) */
+    installApiKey: boolean;
+}
+/**
+ * Authentication adapter for an agent.
+ *
+ * Encapsulates all auth operations for a single agent, hiding the
+ * complexity of different storage mechanisms and credential formats.
+ */
+interface AuthAdapter {
+    /** Agent identifier */
+    readonly agentId: AgentCli;
+    /** Capabilities of this adapter */
+    readonly capabilities: AdapterCapabilities;
+    /**
+     * Check authentication status.
+     *
+     * Checks all supported auth methods (env vars, keychain, files)
+     * and returns the status without making API calls.
+     */
+    checkAuth(): AuthStatus;
+    /**
+     * Extract raw credentials for export.
+     *
+     * Returns the full credential data from the first available source,
+     * suitable for encrypted export. Returns undefined if not authenticated.
+     *
+     * Note: The `data` field format is agent-specific and not standardized.
+     * Use {@link getAccessToken} to extract the token in a uniform way.
+     */
+    extractRawCredentials(): Credentials | undefined;
+    /**
+     * Install credentials to storage.
+     *
+     * When `options.path` is provided, credentials are written as a file to that
+     * path. Keychain storage is not available for custom paths.
+     *
+     * When `options.path` is not provided, credentials are written to the default
+     * location. The `storage` option or `_source` marker controls keychain vs file.
+     */
+    installCredentials(creds: Credentials, options?: InstallOptions): OperationResult;
+    /**
+     * Remove credentials from storage.
+     *
+     * When `options.path` is provided, only the file at that path is removed.
+     * Keychain credentials are not affected.
+     *
+     * When `options.path` is not provided, credentials are removed from all
+     * default locations (keychain and/or default file path).
+     */
+    removeCredentials(options?: RemoveOptions): OperationResult;
+    /**
+     * Extract access token from credentials.
+     *
+     * Returns the primary access token (OAuth token or API key) from
+     * the credential data. Returns undefined if no token found.
+     */
+    getAccessToken(creds: Credentials): string | undefined;
+    /**
+     * Convert credentials to environment variables.
+     *
+     * Returns a record of environment variable names to values that can
+     * be used to authenticate the agent. Returns empty object if the
+     * credential type doesn't support env var authentication.
+     */
+    credentialsToEnvironment(creds: Credentials): Record<string, string>;
+}
+export type { AdapterCapabilities, AuthAdapter, InstallOptions, OperationResult, RemoveOptions, };

package/dist/auth/adapter.js

@@ -0,0 +1,7 @@
+/**
+ * Unified authentication adapter interface.
+ *
+ * All agents implement this interface, providing a consistent API
+ * for auth operations regardless of underlying storage mechanism.
+ */
+export {};

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

@@ -0,0 +1,18 @@
+/**
+ * Claude Code credential storage operations.
+ */
+/** 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 */
+declare function saveFileCreds(oauthData: Record<string, unknown>, filePath: string): boolean;
+/** Delete credentials from keychain */
+declare function deleteKeychainCreds(): boolean;
+/** Delete credentials from file */
+declare function deleteFileCreds(filePath?: string): boolean;
+export { deleteFileCreds, deleteKeychainCreds, getDefaultCredsFilePath, loadFileCreds, loadKeychainCreds, saveFileCreds, saveKeychainCreds, };

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

@@ -0,0 +1,66 @@
+/**
+ * Claude Code credential storage operations.
+ */
+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";
+const KEYCHAIN_SERVICE = "Claude Code-credentials";
+/** Get the current username for keychain operations */
+function getUsername() {
+    return userInfo().username;
+}
+/** Get default credentials file path */
+function getDefaultCredsFilePath() {
+    return path.join(getResolvedConfigDirectory(claudeCodeConfigReader), ".credentials.json");
+}
+/** Load OAuth credentials from keychain */
+function loadKeychainCreds() {
+    const raw = loadFromKeychain(KEYCHAIN_SERVICE, getUsername());
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed.claudeAiOauth;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Load OAuth credentials from file */
+function loadFileCreds() {
+    const creds = loadJsonFile(getDefaultCredsFilePath());
+    return creds?.claudeAiOauth;
+}
+/** Save credentials to keychain */
+function saveKeychainCreds(oauthData) {
+    const data = JSON.stringify({ claudeAiOauth: oauthData });
+    return saveToKeychain(KEYCHAIN_SERVICE, getUsername(), data);
+}
+/** Save credentials to file */
+function saveFileCreds(oauthData, filePath) {
+    // Merge with existing credentials if file exists
+    let existingCreds = {};
+    if (existsSync(filePath)) {
+        try {
+            existingCreds = JSON.parse(readFileSync(filePath, "utf8"));
+        }
+        catch {
+            // Start fresh if invalid
+        }
+    }
+    const newCreds = { ...existingCreds, claudeAiOauth: oauthData };
+    return saveJsonFile(filePath, newCreds, { mode: 0o600 });
+}
+/** Delete credentials from keychain */
+function deleteKeychainCreds() {
+    return deleteFromKeychain(KEYCHAIN_SERVICE, getUsername());
+}
+/** Delete credentials from file */
+function deleteFileCreds(filePath) {
+    return deleteFile(filePath ?? getDefaultCredsFilePath());
+}
+export { deleteFileCreds, deleteKeychainCreds, getDefaultCredsFilePath, loadFileCreds, loadKeychainCreds, saveFileCreds, saveKeychainCreds, };

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

@@ -0,0 +1,9 @@
+/**
+ * Claude Code auth adapter.
+ *
+ * Supports OAuth via keychain (macOS) or file, and API key via env var.
+ */
+import type { AuthAdapter } from "../adapter.js";
+/** Claude Code authentication adapter */
+declare const claudeCodeAdapter: AuthAdapter;
+export { claudeCodeAdapter };

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

@@ -0,0 +1,162 @@
+/**
+ * Claude Code auth adapter.
+ *
+ * Supports OAuth via keychain (macOS) or file, and API key via env var.
+ */
+import { isMacOS } from "../keychain.js";
+import { deleteFileCreds, deleteKeychainCreds, getDefaultCredsFilePath, loadFileCreds, loadKeychainCreds, saveFileCreds, saveKeychainCreds, } from "./claude-code-storage.js";
+const AGENT_ID = "claude";
+/** Claude Code authentication adapter */
+const claudeCodeAdapter = {
+    agentId: AGENT_ID,
+    capabilities: {
+        keychain: true,
+        file: true,
+        environment: true,
+        installApiKey: false,
+    },
+    checkAuth() {
+        if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+            return { agentId: AGENT_ID, authenticated: true, method: "OAuth (env)" };
+        }
+        const keychainCreds = loadKeychainCreds();
+        if (keychainCreds) {
+            const subType = keychainCreds.subscriptionType;
+            return {
+                agentId: AGENT_ID,
+                authenticated: true,
+                method: `OAuth (${subType ?? "keychain"})`,
+            };
+        }
+        if (loadFileCreds()) {
+            return { agentId: AGENT_ID, authenticated: true, method: "OAuth (file)" };
+        }
+        if (process.env.ANTHROPIC_API_KEY) {
+            return { agentId: AGENT_ID, authenticated: true, method: "API key" };
+        }
+        return { agentId: AGENT_ID, authenticated: false };
+    },
+    extractRawCredentials() {
+        if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+            return {
+                agent: AGENT_ID,
+                type: "oauth",
+                data: { accessToken: process.env.CLAUDE_CODE_OAUTH_TOKEN },
+            };
+        }
+        const keychainCreds = loadKeychainCreds();
+        if (keychainCreds) {
+            return {
+                agent: AGENT_ID,
+                type: "oauth",
+                data: { ...keychainCreds, _source: "keychain" },
+            };
+        }
+        const fileCreds = loadFileCreds();
+        if (fileCreds) {
+            return {
+                agent: AGENT_ID,
+                type: "oauth",
+                data: { ...fileCreds, _source: "file" },
+            };
+        }
+        if (process.env.ANTHROPIC_API_KEY) {
+            return {
+                agent: AGENT_ID,
+                type: "api-key",
+                data: { apiKey: process.env.ANTHROPIC_API_KEY },
+            };
+        }
+        return undefined;
+    },
+    installCredentials(creds, options) {
+        if (creds.type === "api-key") {
+            return {
+                ok: false,
+                message: "API key credentials cannot be installed (use ANTHROPIC_API_KEY env var)",
+            };
+        }
+        const { _source, ...oauthData } = creds.data;
+        // Custom path forces file storage (keychain only for default location)
+        if (options?.path) {
+            if (saveFileCreds(oauthData, options.path)) {
+                return {
+                    ok: true,
+                    message: `Installed credentials to ${options.path}`,
+                };
+            }
+            return {
+                ok: false,
+                message: `Failed to install credentials to ${options.path}`,
+            };
+        }
+        // Default location: use storage option or _source marker
+        const targetStorage = options?.storage ?? (_source === "keychain" ? "keychain" : "file");
+        if (targetStorage === "keychain") {
+            if (!isMacOS()) {
+                return {
+                    ok: false,
+                    message: "Keychain storage is only available on macOS",
+                };
+            }
+            if (saveKeychainCreds(oauthData)) {
+                return { ok: true, message: "Installed credentials to macOS Keychain" };
+            }
+            return { ok: false, message: "Failed to save to macOS Keychain" };
+        }
+        const defaultPath = getDefaultCredsFilePath();
+        if (saveFileCreds(oauthData, defaultPath)) {
+            return { ok: true, message: `Installed credentials to ${defaultPath}` };
+        }
+        return {
+            ok: false,
+            message: `Failed to install credentials to ${defaultPath}`,
+        };
+    },
+    removeCredentials(options) {
+        // Custom path: only remove that specific file (no keychain)
+        if (options?.path) {
+            if (deleteFileCreds(options.path)) {
+                return { ok: true, message: `Removed ${options.path}` };
+            }
+            return {
+                ok: true,
+                message: "No credentials file found at specified path",
+            };
+        }
+        // Default location: remove from both keychain and default file
+        const removedFrom = [];
+        if (deleteKeychainCreds()) {
+            removedFrom.push("macOS Keychain");
+        }
+        if (deleteFileCreds()) {
+            removedFrom.push(getDefaultCredsFilePath());
+        }
+        if (removedFrom.length === 0) {
+            return { ok: true, message: "No credentials found" };
+        }
+        return { ok: true, message: `Removed from ${removedFrom.join(" and ")}` };
+    },
+    getAccessToken(creds) {
+        const data = creds.data;
+        if (creds.type === "oauth" && typeof data.accessToken === "string") {
+            return data.accessToken;
+        }
+        if (creds.type === "api-key" && typeof data.apiKey === "string") {
+            return data.apiKey;
+        }
+        return undefined;
+    },
+    credentialsToEnvironment(creds) {
+        const environment = {};
+        const data = creds.data;
+        if (creds.type === "oauth" && typeof data.accessToken === "string") {
+            environment.CLAUDE_CODE_OAUTH_TOKEN = data.accessToken;
+        }
+        else if (creds.type === "api-key" && typeof data.apiKey === "string") {
+            environment.ANTHROPIC_API_KEY = data.apiKey;
+        }
+        return environment;
+    },
+};
+export { claudeCodeAdapter };

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

@@ -0,0 +1,9 @@
+/**
+ * Codex auth status checking and credential extraction.
+ */
+import type { AuthStatus, Credentials } from "../types.js";
+/** Check auth status across all sources */
+declare function checkAuth(): AuthStatus;
+/** Extract raw credentials from first available source */
+declare function extractRawCredentials(): Credentials | undefined;
+export { checkAuth, extractRawCredentials };

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

@@ -0,0 +1,101 @@
+/**
+ * Codex auth status checking and credential extraction.
+ */
+import { getEnvironmentApiKey, hasFileApiKey, hasFileOAuth, hasKeychainApiKey, hasKeychainOAuth, loadFileCreds, loadKeychainCreds, } from "./codex-storage.js";
+const AGENT_ID = "codex";
+/** Check if authenticated via environment variables */
+function checkEnvironmentAuth() {
+    if (getEnvironmentApiKey()) {
+        return { agentId: AGENT_ID, authenticated: true, method: "API key (env)" };
+    }
+    return undefined;
+}
+/** Check if authenticated via keychain */
+function checkKeychainAuth() {
+    const keychainAuth = loadKeychainCreds();
+    if (hasKeychainApiKey(keychainAuth)) {
+        return {
+            agentId: AGENT_ID,
+            authenticated: true,
+            method: "API key (keychain)",
+        };
+    }
+    if (hasKeychainOAuth(keychainAuth)) {
+        return {
+            agentId: AGENT_ID,
+            authenticated: true,
+            method: "ChatGPT OAuth (keychain)",
+        };
+    }
+    return undefined;
+}
+/** Check if authenticated via file */
+function checkFileAuth() {
+    const fileAuth = loadFileCreds();
+    if (hasFileApiKey(fileAuth)) {
+        return { agentId: AGENT_ID, authenticated: true, method: "API key" };
+    }
+    if (hasFileOAuth(fileAuth)) {
+        return { agentId: AGENT_ID, authenticated: true, method: "ChatGPT OAuth" };
+    }
+    return undefined;
+}
+/** Check auth status across all sources */
+function checkAuth() {
+    return (checkEnvironmentAuth() ??
+        checkKeychainAuth() ??
+        checkFileAuth() ?? { agentId: AGENT_ID, authenticated: false });
+}
+/** Extract credentials from environment */
+function extractEnvironmentCredentials() {
+    const environmentKey = getEnvironmentApiKey();
+    if (environmentKey) {
+        return {
+            agent: AGENT_ID,
+            type: "api-key",
+            data: { apiKey: environmentKey },
+        };
+    }
+    return undefined;
+}
+/** Extract credentials from keychain */
+function extractKeychainCredentials() {
+    const keychainAuth = loadKeychainCreds();
+    if (keychainAuth?.OPENAI_API_KEY) {
+        return {
+            agent: AGENT_ID,
+            type: "api-key",
+            data: { apiKey: keychainAuth.OPENAI_API_KEY, _source: "keychain" },
+        };
+    }
+    if (keychainAuth?.tokens) {
+        return {
+            agent: AGENT_ID,
+            type: "oauth",
+            data: { ...keychainAuth, _source: "keychain" },
+        };
+    }
+    return undefined;
+}
+/** Extract credentials from file */
+function extractFileCredentials() {
+    const fileAuth = loadFileCreds();
+    if (fileAuth?.OPENAI_API_KEY) {
+        return {
+            agent: AGENT_ID,
+            type: "api-key",
+            data: { apiKey: fileAuth.OPENAI_API_KEY },
+        };
+    }
+    if (fileAuth?.tokens) {
+        return { agent: AGENT_ID, type: "oauth", data: fileAuth };
+    }
+    return undefined;
+}
+/** Extract raw credentials from first available source */
+function extractRawCredentials() {
+    return (extractEnvironmentCredentials() ??
+        extractKeychainCredentials() ??
+        extractFileCredentials());
+}
+export { checkAuth, extractRawCredentials };