axauth 1.11.1 → 1.12.0

package/dist/auth/refresh-credentials.js

@@ -9,8 +9,8 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { buildAgentRuntimeEnvironment, getAgent, getAgentConfigSubdirectory, } from "axshared";
 import { buildRefreshedCredentials } from "./build-refreshed-credentials.js";
-import { spawnAgent } from "./spawn-agent.js";
-import { getFileStats, waitForFileUpdate } from "./wait-for-file-update.js";
+import { spawnAgentWithFileMonitor } from "./spawn-agent-with-file-monitor.js";
+import { getFileStats } from "./wait-for-file-update.js";
 /** Default timeout for refresh operations in milliseconds */
 const DEFAULT_REFRESH_TIMEOUT_MS = 30_000;
 /**
@@ -95,30 +95,19 @@ async function refreshCredentials(creds, options) {
         const cliArguments = agent.simplePromptArguments("ping", {
             provider: options?.provider,
         });
-        // 8. Spawn agent with minimal prompt
-        const { timedOut, exitCode } = await spawnAgent(agent.cli, cliArguments, fullEnvironment, timeout);
+        // 8. Spawn agent with file monitoring
+        // File monitoring starts before agent spawn to catch async writes that may
+        // occur during process execution (e.g., Gemini's async event handlers).
+        const { timedOut, exitCode, fileUpdated } = await spawnAgentWithFileMonitor(agent.cli, cliArguments, fullEnvironment, timeout, credentialFilePath, beforeStats);
         if (timedOut) {
             return { ok: false, error: "Refresh timed out" };
         }
-        if (exitCode !== 0 && exitCode !== null) {
+        if (exitCode !== 0 && exitCode !== undefined) {
             return { ok: false, error: `Agent exited with code ${exitCode}` };
         }
-        // 8b. Wait for credential file to be written
-        // Some agents (like Gemini) use async event handlers that may not complete
-        // before the process exits. Wait for the file to be created or modified.
-        //
-        // If the wait times out or errors, we still proceed to read credentials.
-        // This is intentional: even if monitoring failed, the agent may have written
-        // the file by now. Failing here would be worse than attempting to read.
-        const waitResult = await waitForFileUpdate(credentialFilePath, beforeStats, {
-            timeout: 5000,
-        });
-        if (!waitResult.ok) {
-            const errorDetail = waitResult.reason === "error" && waitResult.error
-                ? ` - ${waitResult.error}`
-                : "";
+        if (!fileUpdated) {
             console.error(`Warning: Credential file "${credentialFilePath}" was not observed ` +
-                `to be updated (${waitResult.reason}${errorDetail}). Proceeding may read stale credentials.`);
+                `to be updated. Proceeding may read stale credentials.`);
         }
         // 9. Read refreshed credentials from temp directory
         const { extractRawCredentialsFromDirectory } = await import("./registry.js");

package/dist/auth/spawn-agent-with-file-monitor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent subprocess spawning with file monitoring.
+ *
+ * Starts file monitoring before agent spawn to catch async writes that may
+ * occur during process execution (e.g., Gemini's async event handlers).
+ */
+import { type SpawnResult } from "./spawn-agent.js";
+import { type FileStats } from "./wait-for-file-update.js";
+/**
+ * Spawn agent and monitor a file for updates.
+ *
+ * File monitoring starts before agent spawn to catch writes that occur during
+ * process execution, not just after exit.
+ *
+ * @returns Object with spawn result and whether file was updated
+ */
+declare function spawnAgentWithFileMonitor(cli: string, arguments_: string[], environment: NodeJS.ProcessEnv, timeout: number, filePath: string, beforeStats: FileStats | undefined): Promise<SpawnResult & {
+    fileUpdated: boolean;
+}>;
+export { spawnAgentWithFileMonitor };

package/dist/auth/spawn-agent-with-file-monitor.js

@@ -0,0 +1,57 @@
+/**
+ * Agent subprocess spawning with file monitoring.
+ *
+ * Starts file monitoring before agent spawn to catch async writes that may
+ * occur during process execution (e.g., Gemini's async event handlers).
+ */
+import { spawnAgent } from "./spawn-agent.js";
+import { getFileStats, waitForFileUpdate, } from "./wait-for-file-update.js";
+/**
+ * Spawn agent and monitor a file for updates.
+ *
+ * File monitoring starts before agent spawn to catch writes that occur during
+ * process execution, not just after exit.
+ *
+ * @returns Object with spawn result and whether file was updated
+ */
+async function spawnAgentWithFileMonitor(cli, arguments_, environment, timeout, filePath, beforeStats) {
+    const fileMonitorAbort = new AbortController();
+    // Start file monitoring BEFORE spawning agent
+    const fileMonitorPromise = waitForFileUpdate(filePath, beforeStats, {
+        timeout: timeout + 5000,
+        signal: fileMonitorAbort.signal,
+    });
+    try {
+        // Spawn agent
+        const spawnResult = await spawnAgent(cli, arguments_, environment, timeout);
+        // On early exit, abort file monitor
+        if (spawnResult.timedOut ||
+            (spawnResult.exitCode !== 0 && spawnResult.exitCode !== undefined)) {
+            return { ...spawnResult, fileUpdated: false };
+        }
+        // Agent exited successfully - wait for in-flight writes
+        // Use 5s grace period to match previous behavior (some agents like Gemini
+        // may write credentials several seconds after process exit)
+        const gracePeriodMs = 5000;
+        const fileResult = await Promise.race([
+            fileMonitorPromise,
+            new Promise((resolve) => {
+                setTimeout(() => {
+                    resolve({ ok: false });
+                }, gracePeriodMs).unref();
+            }),
+        ]);
+        // Final check in case write completed after race
+        const finalStats = getFileStats(filePath);
+        const fileUpdated = fileResult.ok ||
+            (finalStats !== undefined &&
+                (beforeStats === undefined ||
+                    finalStats.mtimeMs !== beforeStats.mtimeMs ||
+                    finalStats.size !== beforeStats.size));
+        return { ...spawnResult, fileUpdated };
+    }
+    finally {
+        fileMonitorAbort.abort();
+    }
+}
+export { spawnAgentWithFileMonitor };

package/dist/auth/spawn-agent.d.ts

@@ -1,13 +1,19 @@
 /**
  * Agent subprocess spawning utility.
  */
+/** Result of spawning an agent process */
+interface SpawnResult {
+    timedOut: boolean;
+    exitCode: number | undefined;
+}
 /**
  * Spawn agent and wait for completion.
  *
+ * Enforces a hard timeout - if the process doesn't exit after SIGTERM,
+ * escalates to SIGKILL after a grace period and resolves anyway.
+ *
  * @returns Object with timedOut flag and exit code
  */
-declare function spawnAgent(binary: string, arguments_: string[], environment: NodeJS.ProcessEnv, timeout: number): Promise<{
-    timedOut: boolean;
-    exitCode: number | null;
-}>;
+declare function spawnAgent(binary: string, arguments_: string[], environment: NodeJS.ProcessEnv, timeout: number): Promise<SpawnResult>;
 export { spawnAgent };
+export type { SpawnResult };

package/dist/auth/spawn-agent.js

@@ -2,37 +2,60 @@
  * Agent subprocess spawning utility.
  */
 import { spawn } from "node:child_process";
+/** Grace period before escalating SIGTERM to SIGKILL */
+const SIGKILL_GRACE_MS = 5000;
 /**
  * Spawn agent and wait for completion.
  *
+ * Enforces a hard timeout - if the process doesn't exit after SIGTERM,
+ * escalates to SIGKILL after a grace period and resolves anyway.
+ *
  * @returns Object with timedOut flag and exit code
  */
 async function spawnAgent(binary, arguments_, environment, timeout) {
     return new Promise((resolve) => {
         const child = spawn(binary, arguments_, {
             env: environment,
-            stdio: ["ignore", "pipe", "pipe"],
+            // Ignore stdin/stdout to prevent pipe buffer deadlocks, but inherit
+            // stderr so agent error messages are visible for debugging
+            stdio: ["ignore", "ignore", "inherit"],
         });
         let timedOut = false;
         let resolved = false;
+        let killTimer;
+        const cleanup = () => {
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+        };
         const timer = setTimeout(() => {
             if (!resolved) {
                 timedOut = true;
                 child.kill("SIGTERM");
+                // If process doesn't exit after SIGTERM, escalate to SIGKILL
+                // and resolve anyway to prevent indefinite hangs
+                killTimer = setTimeout(() => {
+                    if (!resolved) {
+                        child.kill("SIGKILL");
+                        resolved = true;
+                        cleanup();
+                        resolve({ timedOut: true, exitCode: undefined });
+                    }
+                }, SIGKILL_GRACE_MS);
             }
         }, timeout);
         child.on("error", () => {
             if (!resolved) {
                 resolved = true;
-                clearTimeout(timer);
+                cleanup();
                 resolve({ timedOut: false, exitCode: 1 });
             }
         });
         child.on("close", (code) => {
             if (!resolved) {
                 resolved = true;
-                clearTimeout(timer);
-                resolve({ timedOut, exitCode: code });
+                cleanup();
+                resolve({ timedOut, exitCode: code ?? undefined });
             }
         });
     });

package/dist/auth/wait-for-file-update.d.ts

@@ -5,10 +5,14 @@
  * used by token refresh to wait for credential files to be written.
  */
 import { type Stats } from "node:fs";
+/** File stats type for external use */
+type FileStats = Stats;
 /** Options for waiting on file changes */
 interface WaitOptions {
     /** Maximum time to wait in milliseconds (default: 5000) */
     timeout?: number;
+    /** AbortSignal to cancel waiting early */
+    signal?: AbortSignal;
 }
 /** Result of waiting for file change */
 type WaitResult = {
@@ -16,7 +20,7 @@ type WaitResult = {
     reason: "created" | "modified";
 } | {
     ok: false;
-    reason: "timeout" | "error";
+    reason: "timeout" | "error" | "aborted";
     error?: string;
 };
 /**
@@ -35,3 +39,4 @@ declare function getFileStats(filePath: string): Stats | undefined;
  */
 declare function waitForFileUpdate(filePath: string, beforeStats: Stats | undefined, options?: WaitOptions): Promise<WaitResult>;
 export { getFileStats, waitForFileUpdate };
+export type { FileStats };

package/dist/auth/wait-for-file-update.js

@@ -47,8 +47,13 @@ function checkFileChange(filePath, beforeStats) {
  */
 async function waitForFileUpdate(filePath, beforeStats, options) {
     const timeout = options?.timeout ?? 5000;
+    const signal = options?.signal;
     const parentDirectory = path.dirname(filePath);
     const fileName = path.basename(filePath);
+    // Check if already aborted
+    if (signal?.aborted) {
+        return { ok: false, reason: "aborted" };
+    }
     // Check immediately (file might already be written)
     const immediate = checkFileChange(filePath, beforeStats);
     if (immediate) {
@@ -57,6 +62,7 @@ async function waitForFileUpdate(filePath, beforeStats, options) {
     return new Promise((resolve) => {
         let watcher;
         let resolved = false;
+        let abortHandler;
         const cleanup = (timeoutId, pollId) => {
             if (resolved)
                 return;
@@ -64,6 +70,9 @@ async function waitForFileUpdate(filePath, beforeStats, options) {
             watcher?.close();
             clearTimeout(timeoutId);
             clearInterval(pollId);
+            if (abortHandler && signal) {
+                signal.removeEventListener("abort", abortHandler);
+            }
         };
         // Set timeout
         const timeoutId = setTimeout(() => {
@@ -79,6 +88,14 @@ async function waitForFileUpdate(filePath, beforeStats, options) {
                 resolve(result);
             }
         }, 100);
+        // Handle abort signal
+        if (signal) {
+            abortHandler = () => {
+                cleanup(timeoutId, pollIntervalId);
+                resolve({ ok: false, reason: "aborted" });
+            };
+            signal.addEventListener("abort", abortHandler);
+        }
         // Watch parent directory for changes (for faster responsiveness)
         try {
             watcher = watch(parentDirectory, (_eventType, changedFile) => {

package/dist/cli.js

@@ -28,24 +28,29 @@ Examples:
   # List authenticated agents
   axauth list
 
-  # Filter to show only authenticated agents
-  axauth list | tail -n +2 | awk -F'\t' '$2 == "authenticated"'
-
   # Get access token for an agent
   axauth token --agent claude
 
-  # Export credentials for CI/CD
-  axauth export --agent claude --output creds.json --no-password
+  # Export/import credentials (file-based)
+  axauth export --agent claude --output creds.json
+  axauth install-credentials --agent claude --input creds.json
+
+  # For vault operations: export raw format (--no-encrypt)
+  # Note: install-credentials cannot consume raw exports
+  axauth export --agent claude --output creds.json --no-encrypt
 
   # Remove credentials (agent will prompt for login)
   axauth remove-credentials --agent claude
 
-  # Install credentials from exported file
-  axauth install-credentials --agent claude --input creds.json
+CI/CD with axvault (recommended):
+  # One-time: push local credentials to vault
+  axauth vault push --agent claude --name ci
+
+  # In CI/CD: fetch and install credentials
+  AXVAULT_URL=https://vault.example.com AXVAULT_API_KEY=axv_sk_xxx \
+    axauth vault fetch --agent claude --name ci --install
 
-  # Fetch credentials from vault (JSON config)
-  AXVAULT='{"url":"https://vault.example.com","apiKey":"axv_sk_xxx"}' \
-    axauth vault fetch --agent claude --name ci --install`);
+  # See "axauth vault --help" for full workflow documentation`);
 program
     .command("list")
     .description("List agents and their auth status")
@@ -118,7 +123,32 @@ program
 // Vault subcommand
 const vault = program
     .command("vault")
-    .description("Manage credentials stored in axvault server");
+    .description("Manage credentials stored in axvault server")
+    .addHelpText("after", String.raw `
+Workflow:
+  1. Push local credentials to vault (one-time setup from authenticated machine):
+     axauth vault push --agent claude --name ci
+
+  2. Fetch credentials in CI/CD (set AXVAULT_URL and AXVAULT_API_KEY):
+     axauth vault fetch --agent claude --name ci --install
+
+Environment variables:
+  AXVAULT           JSON config: {"url":"...","apiKey":"..."}
+  AXVAULT_URL       Vault server URL
+  AXVAULT_API_KEY   API key for authentication
+
+OpenCode multi-provider support:
+  OpenCode stores credentials for multiple providers (anthropic, openai, google).
+  Use --provider to push a single provider (fetch uses the stored name):
+
+    axauth vault push --agent opencode --provider anthropic --name ci-anthropic
+    axauth vault fetch --agent opencode --name ci-anthropic --install
+
+Quick reference:
+  vault push   Upload local credentials to vault (requires write access)
+  vault fetch  Download credentials from vault (requires read access)
+
+Use "axauth vault <command> --help" for detailed options.`);
 vault
     .command("fetch")
     .description("Fetch credentials from vault server")
@@ -167,6 +197,7 @@ vault
     .description("Push local credentials to vault server")
     .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)")
     .addHelpText("after", String.raw `
 Environment variables (option 1 - single JSON):
   AXVAULT           JSON config: {"url":"...","apiKey":"..."}
@@ -179,6 +210,9 @@ Examples:
   # Push local Claude credentials to vault as "ci"
   axauth vault push --agent claude --name ci
 
+  # Push a single OpenCode provider to vault
+  axauth vault push --agent opencode --provider anthropic --name ci-anthropic
+
   # Push to a different vault instance
   AXVAULT_URL=https://vault.example.com AXVAULT_API_KEY=axv_sk_xxx \
     axauth vault push --agent gemini --name prod`)

package/dist/commands/vault.d.ts

@@ -22,6 +22,7 @@ declare function handleVaultFetch(options: VaultFetchOptions): Promise<void>;
 interface VaultPushOptions {
     agent: string;
     name: string;
+    provider?: string;
 }
 /**
  * Handle vault push command.

package/dist/commands/vault.js

@@ -2,6 +2,7 @@
  * Vault commands - fetch and push credentials to axvault server.
  */
 import { credentialsToEnvironment, extractRawCredentials, installCredentials, } from "../auth/registry.js";
+import { extractProviderCredentials } from "../auth/agents/opencode.js";
 import { fetchVaultCredentials, pushVaultCredentials, } from "../vault/vault-client.js";
 import { getVaultConfig } from "../vault/vault-config.js";
 import { validateAgent } from "./validate-agent.js";
@@ -132,6 +133,12 @@ async function handleVaultPush(options) {
     const agentId = validateAgent(options.agent);
     if (!agentId)
         return;
+    // Validate --provider is only used with opencode
+    if (options.provider && agentId !== "opencode") {
+        console.error("Error: --provider flag is only supported for opencode agent");
+        process.exitCode = 2;
+        return;
+    }
     // Check vault is configured
     const vaultConfig = getVaultConfig();
     if (!vaultConfig) {
@@ -140,13 +147,22 @@ async function handleVaultPush(options) {
         return;
     }
     // Extract local credentials
-    const credentials = extractRawCredentials(agentId);
-    if (!credentials) {
+    const rawCredentials = extractRawCredentials(agentId);
+    if (!rawCredentials) {
         console.error(`Error: No credentials found for ${agentId}`);
         console.error("Hint: Authenticate with the agent first, or use 'axauth list' to check status");
         process.exitCode = 1;
         return;
     }
+    // Handle per-provider extraction for OpenCode
+    const credentials = options.provider
+        ? extractProviderCredentials(rawCredentials, options.provider)
+        : rawCredentials;
+    if (!credentials) {
+        console.error(`Error: No credentials found for provider '${options.provider}'`);
+        process.exitCode = 1;
+        return;
+    }
     // Push to vault
     const result = await pushVaultCredentials({
         agentId,
@@ -158,6 +174,7 @@ async function handleVaultPush(options) {
         process.exitCode = 1;
         return;
     }
-    console.error(`Credentials pushed to vault: ${agentId}/${options.name}`);
+    const label = options.provider ? `${agentId}/${options.provider}` : agentId;
+    console.error(`Credentials pushed to vault: ${label} → ${options.name}`);
 }
 export { handleVaultFetch, handleVaultPush };

package/dist/vault/vault-client.js

@@ -14,6 +14,7 @@ const VaultCredentialResponse = z.object({
     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
     updatedAt: z.string(),
 });
@@ -88,6 +89,7 @@ async function fetchVaultCredentials(options) {
             agent: options.agentId,
             type: body.type,
             data: body.data,
+            provider: body.provider,
         };
         return {
             ok: true,
@@ -142,6 +144,7 @@ async function pushVaultCredentials(options) {
             body: JSON.stringify({
                 type: options.credentials.type,
                 data: options.credentials.data,
+                provider: options.credentials.provider,
             }),
         });
         // Handle error responses

package/package.json

@@ -2,7 +2,7 @@
   "name": "axauth",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Authentication management library and CLI for AI coding agents",
   "repository": {
     "type": "git",