axvault 1.6.0 → 1.7.1

package/README.md

@@ -2,6 +2,57 @@
 
 Remote credential storage server for a╳kit.
 
+## Quick start
+
+```bash
+export AXVAULT_ENCRYPTION_KEY="your-secret-key-minimum-32-chars!"
+axvault init
+axvault serve
+```
+
+In another shell, create an API key:
+
+```bash
+axvault key create --name "Admin" --read "*" --write "*" --grant "*"
+```
+
+Add `--verbose` to commands like `init`, `serve`, `key revoke`, `key update`, and
+`credential delete` to see status output.
+
+## Pipeline examples
+
+### Extract key IDs
+
+```bash
+axvault key list | tail -n +2 | cut -f1
+```
+
+### Count credentials by type
+
+```bash
+axvault credential list | tail -n +2 | cut -f3 | sort | uniq -c | sort -rn
+```
+
+### List credential paths for a single agent
+
+```bash
+axvault credential list | tail -n +2 | awk -F'\t' '$1 == "claude" {print $1 "/" $2}'
+```
+
+## Agent Rule
+
+Add to your `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+# Rule: `axvault` Usage
+
+Run `npx -y axvault --help` to learn available options.
+
+Use `axvault` when you need to initialize the vault database, manage API keys,
+or list/delete stored credentials. It outputs TSV tables for list commands, so
+you can pipe them into standard Unix tools.
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -100,9 +151,11 @@ axvault key update k_a1b2c3d4e5f6 --add-read "codex/ci" --remove-write "claude/d
 ### Revoke a Key
 
 ```bash
-axvault key revoke k_a1b2c3d4e5f6
+axvault key revoke k_a1b2c3d4e5f6 --force
 ```
 
+This command requires `--force` or `--yes` to confirm.
+
 ### Container Deployments
 
 #### Running the Container
@@ -222,13 +275,13 @@ curl -X DELETE https://vault.example.com/api/v1/credentials/claude/prod \
 
 ## Auto-Refresh
 
-axvault automatically refreshes `oauth-credentials` type credentials that are near expiration when they are retrieved. This behavior is controlled by the refresh threshold setting. Only credentials with a `refresh_token` in their data are eligible for auto-refresh.
+axvault automatically refreshes `oauth-credentials` type credentials that are near expiration when they are retrieved. This behavior is controlled by the refresh threshold setting. Only credentials containing a refresh token field are eligible for auto-refresh. Supported field names: `refresh_token` (standard OAuth), `refreshToken` (Claude), `refresh` (OpenCode).
 
 ### Access Control Note
 
 Auto-refresh is a server-side maintenance operation that occurs transparently during credential retrieval. Read-only API keys can trigger refresh because:
 
-- The refresh uses the credential's own `refresh_token` (already authorized by the token owner)
+- The refresh uses the credential's own refresh token (already authorized by the token owner)
 - The credential's identity and ownership remain unchanged
 - Only token values and expiry timestamps are updated
 - This prevents wasteful repeated refreshes and rate limit issues

package/dist/cli.js

@@ -40,21 +40,25 @@ Examples:
   # List all API keys
   axvault key list
 
+  # Extract key IDs for scripting (pipeline example)
+  axvault key list | tail -n +2 | cut -f1
+
   # Update an API key's permissions
   axvault key update k_abc123def456 --add-read "claude/new"
 
   # Revoke an API key
-  axvault key revoke k_abc123def456
+  axvault key revoke k_abc123def456 --force
 
   # List all stored credentials
   axvault credential list
 
   # Delete a credential
-  axvault credential delete claude/work`);
+  axvault credential delete claude/work --force`);
 program
     .command("init")
     .description("Initialize database and configuration")
     .option("--db-path <path>", "Database file path")
+    .option("-v, --verbose", "Enable verbose output")
     .action(handleInit);
 program
     .command("serve")
@@ -64,6 +68,7 @@ program
     .option("--db-path <path>", "Database file path")
     .option("--refresh-threshold <seconds>", "Refresh credentials expiring within this many seconds (0 to disable)")
     .option("--refresh-timeout <ms>", "Timeout for refresh operations in milliseconds")
+    .option("-v, --verbose", "Enable verbose output")
     .action(handleServe);
 // API key management commands
 const keyCommand = program
@@ -90,6 +95,9 @@ keyCommand
     .command("revoke")
     .description("Revoke an API key")
     .argument("<id>", "API key ID (e.g., k_abc123def456)")
+    .option("-f, --force", "Confirm destructive action")
+    .option("-y, --yes", "Alias for --force")
+    .option("-v, --verbose", "Enable verbose output")
     .option("--db-path <path>", "Database file path")
     .action(handleKeyRevoke);
 keyCommand
@@ -103,6 +111,7 @@ keyCommand
     .option("--remove-write <access>", "Remove write access entries")
     .option("--remove-grant <access>", "Remove grant access entries")
     .option("--json", "Output as JSON")
+    .option("-v, --verbose", "Enable verbose output")
     .option("--db-path <path>", "Database file path")
     .action(handleKeyUpdate);
 // Credential management commands
@@ -120,6 +129,9 @@ credentialCommand
     .command("delete")
     .description("Delete a credential")
     .argument("<path>", "Credential path (agent/name, e.g., claude/work)")
+    .option("-f, --force", "Confirm destructive action")
+    .option("-y, --yes", "Alias for --force")
+    .option("-v, --verbose", "Enable verbose output")
     .option("--db-path <path>", "Database file path")
     .action(handleCredentialDelete);
 await program.parseAsync(process.argv);

package/dist/commands/credential.d.ts

@@ -7,6 +7,9 @@ interface CredentialListOptions {
 }
 interface CredentialDeleteOptions {
     dbPath?: string;
+    force?: boolean;
+    yes?: boolean;
+    verbose?: boolean;
 }
 export declare function handleCredentialList(options: CredentialListOptions): void;
 export declare function handleCredentialDelete(path: string, options: CredentialDeleteOptions): void;

package/dist/commands/credential.js

@@ -91,6 +91,12 @@ export function handleCredentialDelete(path, options) {
         process.exitCode = 2;
         return;
     }
+    if (!options.force && !options.yes) {
+        console.error("Error: Deleting a credential is destructive. Re-run with --force or --yes to confirm.");
+        console.error("Try 'axvault credential delete --help' for more information.");
+        process.exitCode = 2;
+        return;
+    }
     const { agent, name } = parsed;
     try {
         const config = getServerConfig(options);
@@ -98,7 +104,9 @@ export function handleCredentialDelete(path, options) {
         runMigrations(database);
         const deleted = deleteCredential(database, agent, name);
         if (deleted) {
-            console.error(`Deleted credential: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);
+            if (options.verbose) {
+                console.error(`Deleted credential: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);
+            }
         }
         else {
             console.error(`Error: Credential not found: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);

package/dist/commands/init.d.ts

@@ -3,6 +3,7 @@
  */
 interface InitOptions {
     dbPath?: string;
+    verbose?: boolean;
 }
 export declare function handleInit(options: InitOptions): void;
 export {};

package/dist/commands/init.js

@@ -7,13 +7,15 @@ import { getServerConfig } from "../config.js";
 import { closeDatabase, getDatabase } from "../db/client.js";
 import { CURRENT_VERSION, getSchemaVersion, runMigrations, } from "../db/migrations.js";
 export function handleInit(options) {
-    const config = getServerConfig(options);
+    const config = getServerConfig({ dbPath: options.dbPath });
+    const verbose = options.verbose === true;
     // Ensure data directory exists
     const dataDirectory = path.dirname(config.databasePath);
     if (!existsSync(dataDirectory)) {
         try {
             mkdirSync(dataDirectory, { recursive: true });
-            console.error(`Created data directory: ${dataDirectory}`);
+            if (verbose)
+                console.error(`Created data directory: ${dataDirectory}`);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -28,15 +30,17 @@ export function handleInit(options) {
         const versionBefore = getSchemaVersion(database);
         runMigrations(database);
         const versionAfter = getSchemaVersion(database);
-        if (versionBefore === 0) {
-            console.error(`Database initialized at: ${config.databasePath}`);
-            console.error(`Schema version: ${versionAfter}`);
-        }
-        else if (versionBefore < versionAfter) {
-            console.error(`Database migrated from v${versionBefore} to v${versionAfter}`);
-        }
-        else {
-            console.error(`Database already at version ${versionAfter} (current: ${CURRENT_VERSION})`);
+        if (verbose) {
+            if (versionBefore === 0) {
+                console.error(`Database initialized at: ${config.databasePath}`);
+                console.error(`Schema version: ${versionAfter}`);
+            }
+            else if (versionBefore < versionAfter) {
+                console.error(`Database migrated from v${versionBefore} to v${versionAfter}`);
+            }
+            else {
+                console.error(`Database already at version ${versionAfter} (current: ${CURRENT_VERSION})`);
+            }
         }
     }
     catch (error) {

package/dist/commands/key-revoke.d.ts

@@ -3,6 +3,9 @@
  */
 interface KeyRevokeOptions {
     dbPath?: string;
+    force?: boolean;
+    yes?: boolean;
+    verbose?: boolean;
 }
 export declare function handleKeyRevoke(id: string, options: KeyRevokeOptions): void;
 export {};

package/dist/commands/key-revoke.js

@@ -24,13 +24,21 @@ export function handleKeyRevoke(id, options) {
         process.exitCode = 2;
         return;
     }
+    if (!options.force && !options.yes) {
+        console.error("Error: Revoking an API key is destructive. Re-run with --force or --yes to confirm.");
+        console.error("Try 'axvault key revoke --help' for more information.");
+        process.exitCode = 2;
+        return;
+    }
     try {
         const config = getServerConfig(options);
         const database = getDatabase(config.databasePath);
         runMigrations(database);
         const deleted = deleteApiKey(database, trimmedId);
         if (deleted) {
-            console.error(`Revoked API key: ${sanitizeForTsv(trimmedId)}`);
+            if (options.verbose) {
+                console.error(`Revoked API key: ${sanitizeForTsv(trimmedId)}`);
+            }
         }
         else {
             console.error(`Error: API key not found: ${sanitizeForTsv(trimmedId)}`);

package/dist/commands/key-update.d.ts

@@ -10,6 +10,7 @@ interface KeyUpdateOptions {
     removeWrite?: string;
     removeGrant?: string;
     json?: boolean;
+    verbose?: boolean;
 }
 export declare function handleKeyUpdate(id: string, options: KeyUpdateOptions): void;
 export {};

package/dist/commands/key-update.js

@@ -76,7 +76,7 @@ export function handleKeyUpdate(id, options) {
             process.exitCode = 1;
             return;
         }
-        outputKeyDetails(updatedKey, options.json ?? false);
+        outputKeyDetails(updatedKey, options.json ?? false, options.verbose ?? false);
     }
     catch (error) {
         console.error(`Error: Failed to update API key: ${getErrorMessage(error)}`);
@@ -87,7 +87,7 @@ export function handleKeyUpdate(id, options) {
     }
 }
 /** Output key details in JSON or human-readable format */
-function outputKeyDetails(key, json) {
+function outputKeyDetails(key, json, verbose) {
     if (json) {
         console.log(JSON.stringify({
             id: key.id,
@@ -99,7 +99,7 @@ function outputKeyDetails(key, json) {
             lastUsedAt: formatDateForJson(key.lastUsedAt),
         }, undefined, 2));
     }
-    else {
+    else if (verbose) {
         console.error(`Updated API key: ${sanitizeForTsv(key.name)}`);
         console.error(`ID: ${sanitizeForTsv(key.id)}`);
         console.error(`Read access: ${sanitizeForTsv(formatAccessList(key.readAccess))}`);

package/dist/commands/serve.d.ts

@@ -7,6 +7,7 @@ interface ServeOptions {
     dbPath?: string;
     refreshThreshold?: string;
     refreshTimeout?: string;
+    verbose?: boolean;
 }
 export declare function handleServe(options: ServeOptions): Promise<void>;
 export {};

package/dist/commands/serve.js

@@ -10,9 +10,12 @@ import { createHealthRouter, createCredentialRouter, } from "../server/routes.js
 import { createServer } from "../server/server.js";
 export async function handleServe(options) {
     let config;
+    const verbose = options.verbose === true;
     try {
         config = getServerConfig({
-            ...options,
+            port: options.port,
+            host: options.host,
+            dbPath: options.dbPath,
             refreshThresholdSeconds: options.refreshThreshold,
             refreshTimeoutMs: options.refreshTimeout,
         });
@@ -35,7 +38,8 @@ export async function handleServe(options) {
     if (!existsSync(dataDirectory)) {
         try {
             mkdirSync(dataDirectory, { recursive: true });
-            console.error(`Created data directory: ${dataDirectory}`);
+            if (verbose)
+                console.error(`Created data directory: ${dataDirectory}`);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -66,7 +70,8 @@ export async function handleServe(options) {
     ]);
     // Graceful shutdown handler
     const shutdown = () => {
-        console.error("Shutting down...");
+        if (verbose)
+            console.error("Shutting down...");
         server.stop().then(() => {
             closeDatabase();
             // eslint-disable-next-line unicorn/no-process-exit -- CLI graceful shutdown

package/dist/refresh/check-refresh.d.ts

@@ -4,26 +4,11 @@
  * Extracted from refresh-manager to reduce complexity.
  */
 import { type Credentials } from "axauth";
-/**
- * Check if credential is refreshable (has refresh_token or refresh).
- *
- * Detects credentials that have a refresh token field. This is a local
- * check only - the actual refresh is performed by axauth which spawns
- * the agent subprocess. The agent handles its own credential format
- * (e.g., OpenCode uses `refresh` instead of `refresh_token`).
- *
- * Returns false for non-object data to avoid TypeError from `in` operator.
- *
- * Supports both standard OAuth field names and OpenCode field names:
- * - `refresh_token`: Standard OAuth
- * - `refresh`: OpenCode format
- */
-declare function isRefreshable(data: unknown): data is Record<string, unknown>;
 /**
  * Check if credential needs refresh based on expiry.
  *
  * Only returns true if:
- * 1. Credential data is an object with refresh_token (required for axauth refresh)
+ * 1. Credential data is an object with refresh token (required for axauth refresh)
  * 2. Credential has expiry info that is within threshold
  *
  * @param data - Decrypted credential data (accepts unknown for safety)
@@ -35,17 +20,9 @@ declare function needsRefresh(data: unknown, thresholdSeconds: number): boolean;
  * Map vault credential data to axauth Credentials type.
  *
  * @param agent - Agent CLI name
- * @param data - Decrypted credential data from vault (must have refresh_token)
+ * @param data - Decrypted credential data from vault (must have refresh token)
  * @returns Credentials object for axauth, or undefined if not mappable
  */
 declare function toAxauthCredentials(agent: string, data: Record<string, unknown>): Credentials | undefined;
-/**
- * Extract expiry date from refreshed credentials.
- *
- * Looks for common expiry fields in order of preference:
- * - `expiry_date`: Google OAuth (milliseconds)
- * - `expires_at`: Generic OAuth (seconds or milliseconds)
- * - `expires`: OpenCode format (milliseconds)
- */
-declare function extractExpiryDate(data: Record<string, unknown>): Date | undefined;
-export { extractExpiryDate, isRefreshable, needsRefresh, toAxauthCredentials };
+export { extractExpiryDate, isRefreshable } from "axauth";
+export { needsRefresh, toAxauthCredentials };

package/dist/refresh/check-refresh.js

@@ -4,42 +4,14 @@
  * Extracted from refresh-manager to reduce complexity.
  */
 import { AGENT_CLIS } from "axshared";
-import { isCredentialExpired } from "axauth";
+import { isCredentialExpired, isRefreshable } from "axauth";
 /** Valid agent CLI names - sourced from axshared for consistency */
 const VALID_AGENTS = new Set(AGENT_CLIS);
-/**
- * Check if credential is refreshable (has refresh_token or refresh).
- *
- * Detects credentials that have a refresh token field. This is a local
- * check only - the actual refresh is performed by axauth which spawns
- * the agent subprocess. The agent handles its own credential format
- * (e.g., OpenCode uses `refresh` instead of `refresh_token`).
- *
- * Returns false for non-object data to avoid TypeError from `in` operator.
- *
- * Supports both standard OAuth field names and OpenCode field names:
- * - `refresh_token`: Standard OAuth
- * - `refresh`: OpenCode format
- */
-function isRefreshable(data) {
-    if (typeof data !== "object" || data === null)
-        return false;
-    const record = data;
-    // Check for standard OAuth field name
-    if ("refresh_token" in record && typeof record.refresh_token === "string") {
-        return true;
-    }
-    // Check for OpenCode field name
-    if ("refresh" in record && typeof record.refresh === "string") {
-        return true;
-    }
-    return false;
-}
 /**
  * Check if credential needs refresh based on expiry.
  *
  * Only returns true if:
- * 1. Credential data is an object with refresh_token (required for axauth refresh)
+ * 1. Credential data is an object with refresh token (required for axauth refresh)
  * 2. Credential has expiry info that is within threshold
  *
  * @param data - Decrypted credential data (accepts unknown for safety)
@@ -47,7 +19,7 @@ function isRefreshable(data) {
  * @returns true if refresh needed, false otherwise
  */
 function needsRefresh(data, thresholdSeconds) {
-    // Must be an object with refresh_token to be refreshable
+    // Must be an object with refresh token to be refreshable
     if (!isRefreshable(data))
         return false;
     const expired = isCredentialExpired(data, thresholdSeconds);
@@ -58,7 +30,7 @@ function needsRefresh(data, thresholdSeconds) {
  * Map vault credential data to axauth Credentials type.
  *
  * @param agent - Agent CLI name
- * @param data - Decrypted credential data from vault (must have refresh_token)
+ * @param data - Decrypted credential data from vault (must have refresh token)
  * @returns Credentials object for axauth, or undefined if not mappable
  */
 function toAxauthCredentials(agent, data) {
@@ -72,35 +44,6 @@ function toAxauthCredentials(agent, data) {
         data,
     };
 }
-/**
- * Timestamp threshold to distinguish seconds from milliseconds.
- * Values below this are assumed to be Unix timestamps in seconds.
- */
-const SECONDS_THRESHOLD = 10_000_000_000;
-/**
- * Extract expiry date from refreshed credentials.
- *
- * Looks for common expiry fields in order of preference:
- * - `expiry_date`: Google OAuth (milliseconds)
- * - `expires_at`: Generic OAuth (seconds or milliseconds)
- * - `expires`: OpenCode format (milliseconds)
- */
-function extractExpiryDate(data) {
-    // Google OAuth uses expiry_date (milliseconds)
-    if (typeof data.expiry_date === "number") {
-        return new Date(data.expiry_date);
-    }
-    // Generic OAuth uses expires_at (seconds or milliseconds)
-    if (typeof data.expires_at === "number") {
-        const ts = data.expires_at < SECONDS_THRESHOLD
-            ? data.expires_at * 1000
-            : data.expires_at;
-        return new Date(ts);
-    }
-    // OpenCode uses expires (milliseconds)
-    if (typeof data.expires === "number") {
-        return new Date(data.expires);
-    }
-    return undefined;
-}
-export { extractExpiryDate, isRefreshable, needsRefresh, toAxauthCredentials };
+// Re-export from axauth for convenience
+export { extractExpiryDate, isRefreshable } from "axauth";
+export { needsRefresh, toAxauthCredentials };

package/package.json

@@ -2,7 +2,7 @@
   "name": "axvault",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Remote credential storage server for axkit",
   "repository": {
     "type": "git",
@@ -49,9 +49,9 @@
   },
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
-    "axauth": "^1.11.2",
-    "axshared": "1.9.0",
-    "better-sqlite3": "^12.6.0",
+    "axauth": "^2.1.0",
+    "axshared": "2.0.0",
+    "better-sqlite3": "^12.6.2",
     "commander": "^14.0.2",
     "express": "^5.2.1"
   },
@@ -78,14 +78,14 @@
     "@total-typescript/ts-reset": "^0.6.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.0.8",
+    "@types/node": "^25.0.9",
     "@vitest/coverage-v8": "^4.0.17",
     "eslint": "^9.39.2",
-    "eslint-config-axkit": "^1.0.0",
+    "eslint-config-axkit": "^1.1.0",
     "fta-check": "^1.5.1",
     "fta-cli": "^3.0.0",
     "knip": "^5.81.0",
-    "prettier": "3.7.4",
+    "prettier": "3.8.0",
     "semantic-release": "^25.0.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"