axauth 3.1.1 → 3.1.2

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/commands/auth.js

@@ -23,7 +23,7 @@ async function handleAuthToken(options) {
     // OpenCode requires --provider
     if (agentId === "opencode" && !options.provider) {
         console.error("Error: --provider is required for opencode");
-        console.error("Hint: Use 'axauth auth list' to see available providers");
+        console.error("Hint: Use 'axauth list --json' to see available providers");
         process.exitCode = 1;
         return;
     }

package/dist/commands/vault.js

@@ -141,7 +141,7 @@ async function handleVaultPush(options) {
     }
     if (agentId === "opencode" && !options.provider) {
         console.error("Error: --provider is required for opencode");
-        console.error("Hint: Use 'axauth auth list' to see available providers");
+        console.error("Hint: Use 'axauth list --json' to see available providers");
         process.exitCode = 1;
         return;
     }
@@ -159,7 +159,7 @@ async function handleVaultPush(options) {
     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 auth list' to check status`;
+            : `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;

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

@@ -5,7 +5,7 @@
  * a remote axvault server. It handles authentication, error responses,
  * and returns a typed result.
  */
-import { type AgentCli } from "axshared";
+import type { AgentCli } from "axshared";
 import type { Credentials } from "../auth/types.js";
 /** Reason why vault operation failed */
 type VaultFailureReason = "not-configured" | "unreachable" | "unauthorized" | "forbidden" | "not-found" | "legacy-credential" | "client-error" | "server-error";

package/dist/vault/vault-client.js

@@ -5,17 +5,12 @@
  * a remote axvault server. It handles authentication, error responses,
  * and returns a typed result.
  */
-import { CredentialType } from "axshared";
 import { z } from "zod";
 import { getVaultConfig } from "./vault-config.js";
-/** Zod schema for vault API response */
+/** Zod schema for vault API response envelope */
 const VaultCredentialResponse = z.object({
-    agent: z.string(),
     name: z.string(),
-    type: CredentialType,
-    data: z.record(z.string(), z.unknown()),
-    provider: z.string().trim().min(1).optional(), // OpenCode provider support
-    expiresAt: z.string().nullish(), // optional for oauth-token type
+    credential: z.record(z.string(), z.unknown()),
     updatedAt: z.string(),
 });
 /**
@@ -41,7 +36,7 @@ async function fetchVaultCredentials(options) {
     if (!config) {
         return { ok: false, reason: "not-configured" };
     }
-    const url = `${config.url}/api/v1/credentials/${encodeURIComponent(options.agentId)}/${encodeURIComponent(options.name)}`;
+    const url = `${config.url}/api/v1/credentials/${encodeURIComponent(options.name)}`;
     try {
         const response = await fetch(url, {
             method: "GET",
@@ -83,33 +78,11 @@ async function fetchVaultCredentials(options) {
         const refreshFailed = response.headers.get("X-Axvault-Refresh-Failed") === "true";
         // Log warning if refresh failed (stale credentials returned)
         if (refreshFailed) {
-            console.error(`[axauth] Vault returned stale credentials for ${options.agentId}/${options.name} (refresh failed)`);
+            console.error(`[axauth] Vault returned stale credentials for ${options.name} (refresh failed)`);
         }
-        // Build credentials based on agent type
-        // OpenCode requires provider field - treat missing provider as server error
-        if (options.agentId === "opencode") {
-            if (!body.provider) {
-                return { ok: false, reason: "server-error" };
-            }
-            return {
-                ok: true,
-                credentials: {
-                    agent: options.agentId,
-                    type: body.type,
-                    provider: body.provider,
-                    data: body.data,
-                },
-                refreshed: wasRefreshed,
-            };
-        }
-        const credentials = {
-            agent: options.agentId,
-            type: body.type,
-            data: body.data,
-        };
         return {
             ok: true,
-            credentials,
+            credentials: body.credential,
             refreshed: wasRefreshed,
         };
     }
@@ -145,7 +118,7 @@ async function pushVaultCredentials(options) {
     if (!config) {
         return { ok: false, reason: "not-configured" };
     }
-    const url = `${config.url}/api/v1/credentials/${encodeURIComponent(options.agentId)}/${encodeURIComponent(options.name)}`;
+    const url = `${config.url}/api/v1/credentials/${encodeURIComponent(options.name)}`;
     try {
         const response = await fetch(url, {
             method: "PUT",

package/package.json

@@ -2,7 +2,7 @@
   "name": "axauth",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "description": "Authentication management library and CLI for AI coding agents",
   "repository": {
     "type": "git",
@@ -62,7 +62,7 @@
     "automation",
     "coding-assistant"
   ],
-  "packageManager": "pnpm@10.28.0",
+  "packageManager": "pnpm@10.28.1",
   "engines": {
     "node": ">=22.14.0"
   },
@@ -70,21 +70,21 @@
     "@commander-js/extra-typings": "^14.0.0",
     "@inquirer/password": "^5.0.4",
     "axconfig": "^3.6.3",
-    "axexec": "^1.6.1",
+    "axexec": "^1.7.0",
     "axshared": "^4.0.0",
     "commander": "^14.0.2",
     "zod": "^4.3.5"
   },
   "devDependencies": {
     "@total-typescript/ts-reset": "^0.6.1",
-    "@types/node": "^25.0.9",
+    "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
     "eslint": "^9.39.2",
     "eslint-config-axkit": "^1.1.0",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.0",
-    "knip": "^5.82.0",
-    "prettier": "3.8.0",
+    "knip": "^5.82.1",
+    "prettier": "3.8.1",
     "semantic-release": "^25.0.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"