axvault 1.8.1 → 1.8.2

package/README.md

@@ -2,41 +2,70 @@
 
 Remote credential storage server for a╳kit.
 
+## Prerequisites
+
+- Node.js 22.14+
+- `pnpm` (for `pnpm dlx axvault`) or `npx` (for `npx -y axvault`)
+- `jq` for scripting against `--json` output
+
+If `axvault` is not installed globally, prefix commands with `npx -y axvault` (or `pnpm dlx axvault`).
+
 ## Quick start
 
 ```bash
-export AXVAULT_ENCRYPTION_KEY="your-secret-key-minimum-32-chars!"
-axvault init
-axvault serve
+umask 077
+printf 'AXVAULT_ENCRYPTION_KEY=' > .env
+openssl rand -base64 32 >> .env
+chmod 600 .env
+set -a
+. ./.env
+set +a
+mkdir -p ./data
+npx -y axvault init
+npx -y axvault serve
 ```
 
+Keep the `.env` file and reuse the same key between restarts to avoid losing access to existing credentials.
+
+In a new shell, you must re-export the variables from `.env` before running `axvault` commands (the server does not load `.env` automatically).
+
 In another shell, create an API key:
 
 ```bash
-axvault key create --name "Admin" --read "*" --write "*" --grant "*"
+npx -y 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.
 
+## Output formats
+
+List commands output TSV by default. Use `--json` on `key create`, `key list`,
+`key update`, and `credential list` for structured output (note: `key create
+--json` includes the secret key).
+
+```bash
+npx -y axvault key list --json | jq -r '.[].id'
+```
+
 ## Pipeline examples
 
 ### Extract key IDs
 
 ```bash
-axvault key list | tail -n +2 | cut -f1
+npx -y axvault key list | tail -n +2 | cut -f1
 ```
 
-### Count credentials by type
+### Count credentials by creation date
 
 ```bash
-axvault credential list | tail -n +2 | cut -f3 | sort | uniq -c | sort -rn
+npx -y axvault credential list --json | jq -r '.[].createdAt | split("T")[0]' | sort | uniq -c | sort -rn
 ```
 
-### List credential paths for a single agent
+### List credential names in the `claude` namespace
 
 ```bash
-axvault credential list | tail -n +2 | awk -F'\t' '$1 == "claude" {print $1 "/" $2}'
+npx -y axvault credential list | tail -n +2 | awk -F'\t' '$1 ~ /^claude\./ {print $1}'
 ```
 
 ## Agent Rule
@@ -49,8 +78,8 @@ Add to your `CLAUDE.md` or `AGENTS.md`:
 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.
+or list/delete stored credentials. List commands output TSV by default; add
+`--json` for structured output you can pipe into `jq`.
 ```
 
 ## Configuration
@@ -71,7 +100,7 @@ you can pipe them into standard Unix tools.
 The `serve` command accepts flags that override environment variables:
 
 ```bash
-axvault serve \
+npx -y axvault serve \
   --port 8080 \
   --host 0.0.0.0 \
   --db-path /data/vault.db \
@@ -81,6 +110,11 @@ axvault serve \
 
 Setting `--refresh-threshold 0` disables automatic credential refresh.
 
+## Confirmation flags
+
+Destructive commands require confirmation: `axvault key revoke` and `axvault
+credential delete` require `--force` (alias `--yes`).
+
 ## API Keys
 
 API keys control access to the credential API. Each key has configurable permissions:
@@ -93,17 +127,17 @@ API keys control access to the credential API. Each key has configurable permiss
 
 ```bash
 # Full access (read, write, and grant)
-axvault key create --name "Admin" --read "*" --write "*" --grant "*"
+npx -y axvault key create --name "Admin" --read "*" --write "*" --grant "*"
 
 # Read/write access only
-axvault key create --name "CI Pipeline" --read "*" --write "*"
+npx -y axvault key create --name "CI Pipeline" --read "*" --write "*"
 
 # Restricted access
-axvault key create --name "Claude Reader" --read "claude/work,claude/ci"
-axvault key create --name "Deploy Script" --write "claude/prod,codex/prod"
+npx -y axvault key create --name "Claude Reader" --read "claude.work,claude.ci"
+npx -y axvault key create --name "Deploy Script" --write "claude.prod,codex.prod"
 
 # Grant-only key (for delegation, does not allow direct read/write)
-axvault key create --name "Issuer" --grant "claude/work,claude/ci"
+npx -y axvault key create --name "Issuer" --grant "claude.work,claude.ci"
 ```
 
 The command outputs metadata to stderr and the secret key to stdout for easy piping:
@@ -122,12 +156,12 @@ Save this key securely - it cannot be retrieved later.
 axv_sk_0123456789abcdef0123456789abcdef
 ```
 
-To copy directly to clipboard: `axvault key create --name "My Key" --read "*" | pbcopy`
+To copy directly to clipboard: `npx -y axvault key create --name "My Key" --read "*" | pbcopy`
 
 ### List Keys
 
 ```bash
-axvault key list
+npx -y axvault key list
 ```
 
 ### Update a Key
@@ -136,22 +170,22 @@ Modify an existing key's permissions:
 
 ```bash
 # Add read access for new credentials
-axvault key update k_a1b2c3d4e5f6 --add-read "gemini/prod"
+npx -y axvault key update k_a1b2c3d4e5f6 --add-read "gemini.prod"
 
 # Remove write access
-axvault key update k_a1b2c3d4e5f6 --remove-write "claude/test"
+npx -y axvault key update k_a1b2c3d4e5f6 --remove-write "claude.test"
 
 # Add grant permissions
-axvault key update k_a1b2c3d4e5f6 --add-grant "claude/work"
+npx -y axvault key update k_a1b2c3d4e5f6 --add-grant "claude.work"
 
 # Multiple changes at once
-axvault key update k_a1b2c3d4e5f6 --add-read "codex/ci" --remove-write "claude/dev"
+npx -y axvault key update k_a1b2c3d4e5f6 --add-read "codex.ci" --remove-write "claude.dev"
 ```
 
 ### Revoke a Key
 
 ```bash
-axvault key revoke k_a1b2c3d4e5f6 --force
+npx -y axvault key revoke k_a1b2c3d4e5f6 --force
 ```
 
 This command requires `--force` or `--yes` to confirm.
@@ -243,7 +277,7 @@ docker exec axvault node /app/node_modules/axvault/bin/axvault key create --name
 ### Store a Credential
 
 ```bash
-curl -X PUT https://vault.example.com/api/v1/credentials/claude/prod \
+curl -X PUT https://vault.example.com/api/v1/credentials/claude.prod \
   -H "Authorization: Bearer <api_key>" \
   -H "Content-Type: application/json" \
   -d '{
@@ -254,25 +288,75 @@ curl -X PUT https://vault.example.com/api/v1/credentials/claude/prod \
   }'
 ```
 
+Returns 201 with the stored credential's metadata:
+
+```json
+{
+  "name": "claude.prod",
+  "createdAt": "2026-01-15T10:30:00.000Z",
+  "updatedAt": "2026-01-15T10:30:00.000Z"
+}
+```
+
 The `type` field is required and must be one of:
 
 - `"oauth-credentials"` — Full OAuth with refresh_token (eligible for auto-refresh)
 - `"oauth-token"` — Long-lived OAuth token like `CLAUDE_CODE_OAUTH_TOKEN` (static)
 - `"api-key"` — API key (static)
 
-The `provider` field is optional and stores the provider name for multi-provider agents. For example, OpenCode credentials can specify `"anthropic"`, `"openai"`, `"gemini"`, or `"opencode"` to distinguish which provider the credential is for.
+The `provider` field is optional for single-provider agents. For OpenCode (multi-provider), `provider` is required (e.g., `"anthropic"`, `"openai"`, `"gemini"`).
+
+### List Credentials
+
+```bash
+curl https://vault.example.com/api/v1/credentials \
+  -H "Authorization: Bearer <api_key>"
+```
+
+Returns metadata for all accessible credentials. Supports opt-in cursor-based pagination:
+
+| Parameter | Description                                              | Default     |
+| --------- | -------------------------------------------------------- | ----------- |
+| `limit`   | Results per page (1–1000; values above 1000 are clamped) | All results |
+| `cursor`  | Name from previous page's `nextCursor`                   | —           |
+
+Without `limit`, all accessible credentials are returned (backward-compatible). `cursor` requires `limit` — providing `cursor` without `limit` returns 400.
+
+```bash
+# First page
+curl 'https://vault.example.com/api/v1/credentials?limit=50' \
+  -H "Authorization: Bearer <api_key>"
+
+# Next page (cursor is the last name from the previous response)
+curl 'https://vault.example.com/api/v1/credentials?limit=50&cursor=claude.prod' \
+  -H "Authorization: Bearer <api_key>"
+```
+
+Response includes `nextCursor` when `limit` is set and more results are available:
+
+```json
+{
+  "credentials": [
+    { "name": "claude.staging", "createdAt": "...", "updatedAt": "..." },
+    { "name": "gemini.ci", "createdAt": "...", "updatedAt": "..." }
+  ],
+  "nextCursor": "gemini.ci"
+}
+```
 
 ### Retrieve a Credential
 
 ```bash
-curl https://vault.example.com/api/v1/credentials/claude/prod \
+curl https://vault.example.com/api/v1/credentials/claude.prod \
   -H "Authorization: Bearer <api_key>"
 ```
 
 ### Delete a Credential
 
+Returns 204 No Content on success.
+
 ```bash
-curl -X DELETE https://vault.example.com/api/v1/credentials/claude/prod \
+curl -X DELETE https://vault.example.com/api/v1/credentials/claude.prod \
   -H "Authorization: Bearer <api_key>"
 ```
 
@@ -352,13 +436,13 @@ Alternatively, use separate environment variables:
 
 ### Common Errors
 
-| Error            | Cause                                      | Solution                                                                         |
-| ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------- |
-| `not-configured` | Missing `AXVAULT_URL` or `AXVAULT_API_KEY` | Set both environment variables or use `AXVAULT` JSON                             |
-| `unauthorized`   | Invalid API key                            | Verify key with `axvault key list`, create new if needed                         |
-| `forbidden`      | No access to credential                    | Add credential to key's read access: `axvault key update <id> --add-read <path>` |
-| `not-found`      | Credential doesn't exist                   | Store credential first: `axauth vault push --agent <agent> --name <name>`        |
-| `unreachable`    | Network issue or server down               | Check vault URL, verify server is running                                        |
+| Error            | Cause                                      | Solution                                                                                |
+| ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `not-configured` | Missing `AXVAULT_URL` or `AXVAULT_API_KEY` | Set both environment variables or use `AXVAULT` JSON                                    |
+| `unauthorized`   | Invalid API key                            | Verify key with `npx -y axvault key list`, create new if needed                         |
+| `forbidden`      | No access to credential                    | Add credential to key's read access: `npx -y axvault key update <id> --add-read <path>` |
+| `not-found`      | Credential doesn't exist                   | Store credential first: `axauth vault push --agent <agent> --name <name>`               |
+| `unreachable`    | Network issue or server down               | Check vault URL, verify server is running                                               |
 
 ### Debugging
 
@@ -371,7 +455,7 @@ Alternatively, use separate environment variables:
 2. Verify API key permissions:
 
    ```bash
-   axvault key list  # on server
+   npx -y axvault key list  # on server
    ```
 
 3. Check credential exists:

package/dist/cli.js

@@ -29,10 +29,10 @@ Examples:
   axvault serve --port 8080
 
   # Create an API key with read access (at least one of --read/--write required)
-  axvault key create --name "CI Pipeline" --read "claude/work,codex/ci"
+  axvault key create --name "CI Pipeline" --read "claude.work,codex.ci"
 
   # Create a write-only API key
-  axvault key create --name "Uploader" --write "claude/backups"
+  axvault key create --name "Uploader" --write "claude.backups"
 
   # Create an admin API key with full access
   axvault key create --name "Admin" --read "*" --write "*" --grant "*"
@@ -44,7 +44,7 @@ Examples:
   axvault key list | tail -n +2 | cut -f1
 
   # Update an API key's permissions
-  axvault key update k_abc123def456 --add-read "claude/new"
+  axvault key update k_abc123def456 --add-read "claude.new"
 
   # Revoke an API key
   axvault key revoke k_abc123def456 --force
@@ -53,7 +53,7 @@ Examples:
   axvault credential list
 
   # Delete a credential
-  axvault credential delete claude/work --force`);
+  axvault credential delete claude.work --force`);
 program
     .command("init")
     .description("Initialize database and configuration")
@@ -79,8 +79,8 @@ keyCommand
     .command("create")
     .description("Create a new API key")
     .requiredOption("-n, --name <name>", "Name for the API key")
-    .option("-r, --read <access>", "Comma-separated read access list (e.g., 'claude/work,codex/ci' or '*')")
-    .option("-w, --write <access>", "Comma-separated write access list (e.g., 'claude/ci' or '*')")
+    .option("-r, --read <access>", "Comma-separated read access list (e.g., 'claude.work,codex.ci' or '*')")
+    .option("-w, --write <access>", "Comma-separated write access list (e.g., 'claude.ci' or '*')")
     .option("-g, --grant <access>", "Comma-separated grant access list (can delegate these to other keys)")
     .option("--json", "Output as JSON")
     .option("--db-path <path>", "Database file path")
@@ -128,7 +128,7 @@ credentialCommand
 credentialCommand
     .command("delete")
     .description("Delete a credential")
-    .argument("<path>", "Credential path (agent/name, e.g., claude/work)")
+    .argument("<name>", "Credential name (e.g., claude.work)")
     .option("-f, --force", "Confirm destructive action")
     .option("-y, --yes", "Alias for --force")
     .option("-v, --verbose", "Enable verbose output")

package/dist/commands/credential.d.ts

@@ -12,5 +12,5 @@ interface CredentialDeleteOptions {
     verbose?: boolean;
 }
 export declare function handleCredentialList(options: CredentialListOptions): void;
-export declare function handleCredentialDelete(path: string, options: CredentialDeleteOptions): void;
+export declare function handleCredentialDelete(credentialName: string, options: CredentialDeleteOptions): void;
 export {};

package/dist/commands/credential.js

@@ -5,50 +5,46 @@ import { getServerConfig } from "../config.js";
 import { closeDatabase, getDatabase } from "../db/client.js";
 import { runMigrations } from "../db/migrations.js";
 import { deleteCredential, listCredentials, } from "../db/repositories/credentials.js";
-import { containsControlChars, formatDateForJson, formatExpiresAt, formatRelativeTime, getErrorMessage, sanitizeForTsv, } from "../lib/format.js";
-/** Print credentials as TSV table */
+import { containsControlChars, formatRelativeTime, getErrorMessage, sanitizeForTsv, } from "../lib/format.js";
+import { CREDENTIAL_NAME_FORMAT_DESCRIPTION, isValidCredentialName, } from "../lib/credential-name.js";
+/** Print credentials as TSV table (opaque schema - no type/expires columns) */
 function printCredentialTable(credentials) {
-    console.log("AGENT\tNAME\tTYPE\tEXPIRES\tUPDATED");
+    console.log("NAME\tCREATED\tUPDATED");
     for (const cred of credentials) {
-        const agent = sanitizeForTsv(cred.agent);
         const name = sanitizeForTsv(cred.name);
-        const type = sanitizeForTsv(cred.type);
-        const expires = formatExpiresAt(cred.expiresAt);
+        const created = formatRelativeTime(cred.createdAt);
         const updated = formatRelativeTime(cred.updatedAt);
-        console.log(`${agent}\t${name}\t${type}\t${expires}\t${updated}`);
+        console.log(`${name}\t${created}\t${updated}`);
     }
 }
 /**
- * Parse credential path (agent/name).
+ * Parse and validate credential name.
  *
  * Control characters are checked BEFORE trimming to prevent silent bypass
- * (e.g., "\nclaude/work" would otherwise become "claude/work" after trim).
+ * (e.g., "\nwork" would otherwise become "work" after trim).
  */
-function parseCredentialPath(path) {
+function parseCredentialName(name) {
     // Reject inputs containing control characters BEFORE trimming
-    if (containsControlChars(path)) {
+    if (containsControlChars(name)) {
         return {
             ok: false,
-            message: `Invalid credential path: contains control characters.\nExpected format: agent/name (e.g., claude/work)`,
+            message: "Invalid credential name: contains control characters.",
         };
     }
-    const trimmed = path.trim();
-    const parts = trimmed.split("/");
-    if (parts.length !== 2) {
+    const trimmed = name.trim();
+    if (!trimmed) {
         return {
             ok: false,
-            message: `Invalid credential path: ${trimmed}\nExpected format: agent/name (e.g., claude/work)`,
+            message: "Invalid credential name: name is required.",
         };
     }
-    const agent = parts[0]?.trim();
-    const name = parts[1]?.trim();
-    if (!agent || !name) {
+    if (!isValidCredentialName(trimmed)) {
         return {
             ok: false,
-            message: `Invalid credential path: ${trimmed}\nBoth agent and name are required.`,
+            message: `Invalid credential name format. Must be ${CREDENTIAL_NAME_FORMAT_DESCRIPTION}.`,
         };
     }
-    return { ok: true, agent, name };
+    return { ok: true, name: trimmed };
 }
 export function handleCredentialList(options) {
     try {
@@ -57,19 +53,17 @@ export function handleCredentialList(options) {
         runMigrations(database);
         const credentials = listCredentials(database);
         if (options.json) {
+            // Opaque schema: type/provider/expiresAt not available without decrypting
             const output = credentials.map((cred) => ({
-                agent: cred.agent,
                 name: cred.name,
-                type: cred.type,
                 createdAt: cred.createdAt.toISOString(),
                 updatedAt: cred.updatedAt.toISOString(),
-                expiresAt: formatDateForJson(cred.expiresAt),
             }));
             console.log(JSON.stringify(output, undefined, 2));
         }
         else if (credentials.length === 0) {
             console.error("No credentials stored.");
-            console.error("Store credentials via the API: PUT /api/v1/credentials/:agent/:name");
+            console.error("Store credentials via the API: PUT /api/v1/credentials/:name");
         }
         else {
             printCredentialTable(credentials);
@@ -83,9 +77,9 @@ export function handleCredentialList(options) {
         closeDatabase();
     }
 }
-export function handleCredentialDelete(path, options) {
-    // Parse credential path first (before config parsing)
-    const parsed = parseCredentialPath(path);
+export function handleCredentialDelete(credentialName, options) {
+    // Validate credential name first (before config parsing)
+    const parsed = parseCredentialName(credentialName);
     if (!parsed.ok) {
         console.error(`Error: ${parsed.message}`);
         process.exitCode = 2;
@@ -97,19 +91,19 @@ export function handleCredentialDelete(path, options) {
         process.exitCode = 2;
         return;
     }
-    const { agent, name } = parsed;
+    const { name } = parsed;
     try {
         const config = getServerConfig(options);
         const database = getDatabase(config.databasePath);
         runMigrations(database);
-        const deleted = deleteCredential(database, agent, name);
+        const deleted = deleteCredential(database, name);
         if (deleted) {
             if (options.verbose) {
-                console.error(`Deleted credential: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);
+                console.error(`Deleted credential: ${sanitizeForTsv(name)}`);
             }
         }
         else {
-            console.error(`Error: Credential not found: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);
+            console.error(`Error: Credential not found: ${sanitizeForTsv(name)}`);
             process.exitCode = 1;
         }
     }

package/dist/commands/init.js

@@ -30,22 +30,23 @@ export function handleInit(options) {
         const versionBefore = getSchemaVersion(database);
         runMigrations(database);
         const versionAfter = getSchemaVersion(database);
-        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})`);
-            }
+        if (!verbose)
+            return;
+        if (versionBefore === 0) {
+            console.error(`Database initialized at: ${config.databasePath}`);
+            console.error(`Schema version: ${versionAfter}`);
+            return;
+        }
+        if (versionBefore === versionAfter) {
+            console.error(`Database already at version ${versionAfter} (current: ${CURRENT_VERSION})`);
+            return;
         }
+        console.error(`Database migrated from v${versionBefore} to v${versionAfter}`);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(`Failed to initialize database: ${message}`);
+        console.error("If this is a schema version mismatch, delete the database file and re-run `axvault init`.");
         process.exitCode = 1;
     }
     finally {

package/dist/commands/serve.js

@@ -57,6 +57,7 @@ export async function handleServe(options) {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(`Failed to initialize database: ${message}`);
+        console.error(`If this is a schema version mismatch, delete '${config.databasePath}' and restart.`);
         // eslint-disable-next-line unicorn/no-process-exit -- CLI startup failure
         process.exit(1);
     }

package/dist/db/migrations.d.ts

@@ -1,10 +1,11 @@
 /**
  * Database schema migrations.
  *
- * Uses a simple version-based migration system.
+ * Simple schema with opaque credential storage.
+ * Credentials are identified by name only - the blob contains all metadata.
  */
 import type Database from "better-sqlite3";
-declare const CURRENT_VERSION = 7;
+declare const CURRENT_VERSION = 1;
 /** Run all pending migrations */
 declare function runMigrations(database: Database.Database): void;
 /** Get current schema version */