axvault 1.1.0 → 1.3.0

package/README.md

@@ -32,17 +32,27 @@ Setting `--refresh-threshold 0` disables automatic credential refresh.
 
 ## API Keys
 
-API keys control access to the credential API. Each key has configurable read and write permissions.
+API keys control access to the credential API. Each key has configurable permissions:
+
+- **Read**: retrieve credentials
+- **Write**: store and delete credentials
+- **Grant**: delegate access to other keys (enforcement coming in future release)
 
 ### Create an API Key
 
 ```bash
-# Full access
+# Full access (read, write, and grant)
+axvault key create --name "Admin" --read "*" --write "*" --grant "*"
+
+# Read/write access only
 axvault key create --name "CI Pipeline" --read "*" --write "*"
 
 # Restricted access
-axvault key create --name "Claude Reader" --read "claude/*"
+axvault key create --name "Claude Reader" --read "claude/work,claude/ci"
 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"
 ```
 
 The command outputs metadata to stderr and the secret key to stdout for easy piping:
@@ -53,6 +63,7 @@ Created API key: CI Pipeline
 ID: k_a1b2c3d4e5f6
 Read access: *
 Write access: *
+Grant access: (none)
 
 Save this key securely - it cannot be retrieved later.
 
@@ -68,6 +79,24 @@ To copy directly to clipboard: `axvault key create --name "My Key" --read "*" |
 axvault key list
 ```
 
+### Update a Key
+
+Modify an existing key's permissions:
+
+```bash
+# Add read access for new credentials
+axvault key update k_a1b2c3d4e5f6 --add-read "gemini/prod"
+
+# Remove write access
+axvault key update k_a1b2c3d4e5f6 --remove-write "claude/test"
+
+# Add grant permissions
+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"
+```
+
 ### Revoke a Key
 
 ```bash
@@ -148,10 +177,10 @@ Exec into the container to manage API keys:
 
 ```bash
 # Podman
-sudo podman exec axvault /nodejs/bin/node node_modules/axvault/bin/axvault key create --name "My Key" --write "*"
+sudo podman exec axvault /nodejs/bin/node node_modules/axvault/bin/axvault key create --name "My Key" --read "*" --write "*"
 
 # Docker
-docker exec axvault /nodejs/bin/node node_modules/axvault/bin/axvault key create --name "My Key" --write "*"
+docker exec axvault /nodejs/bin/node node_modules/axvault/bin/axvault key create --name "My Key" --read "*" --write "*"
 ```
 
 ## Credentials API
@@ -163,13 +192,17 @@ curl -X PUT https://vault.example.com/api/v1/credentials/claude/prod \
   -H "Authorization: Bearer <api_key>" \
   -H "Content-Type: application/json" \
   -d '{
-    "type": "oauth",
+    "type": "oauth-credentials",
     "data": {"access_token": "...", "refresh_token": "..."},
     "expiresAt": "2025-12-31T23:59:59Z"
   }'
 ```
 
-The `type` field is required and must be either `"oauth"` (for refreshable tokens) or `"api-key"` (for static keys). Only `oauth` credentials are eligible for auto-refresh.
+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)
 
 ### Retrieve a Credential
 
@@ -187,7 +220,7 @@ curl -X DELETE https://vault.example.com/api/v1/credentials/claude/prod \
 
 ## Auto-Refresh
 
-axvault automatically refreshes OAuth credentials that are near expiration when they are retrieved. This behavior is controlled by the refresh threshold setting.
+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.
 
 ### Access Control Note
 

package/dist/cli.js

@@ -8,7 +8,7 @@ import { Command } from "@commander-js/extra-typings";
 import packageJson from "../package.json" with { type: "json" };
 import { handleCredentialDelete, handleCredentialList, } from "./commands/credential.js";
 import { handleInit } from "./commands/init.js";
-import { handleKeyCreate, handleKeyList, handleKeyRevoke, } from "./commands/key.js";
+import { handleKeyCreate, handleKeyList, handleKeyRevoke, handleKeyUpdate, } from "./commands/key.js";
 import { handleServe } from "./commands/serve.js";
 const program = new Command()
     .name(packageJson.name)
@@ -35,11 +35,14 @@ Examples:
   axvault key create --name "Uploader" --write "claude/backups"
 
   # Create an admin API key with full access
-  axvault key create --name "Admin" --read "*" --write "*"
+  axvault key create --name "Admin" --read "*" --write "*" --grant "*"
 
   # List all API keys
   axvault key list
 
+  # Update an API key's permissions
+  axvault key update k_abc123def456 --add-read "claude/new"
+
   # Revoke an API key
   axvault key revoke k_abc123def456
 
@@ -73,6 +76,7 @@ keyCommand
     .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("-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")
     .action(handleKeyCreate);
@@ -88,6 +92,19 @@ keyCommand
     .argument("<id>", "API key ID (e.g., k_abc123def456)")
     .option("--db-path <path>", "Database file path")
     .action(handleKeyRevoke);
+keyCommand
+    .command("update")
+    .description("Update an API key's permissions")
+    .argument("<id>", "API key ID (e.g., k_abc123def456)")
+    .option("--add-read <access>", "Add read access entries")
+    .option("--add-write <access>", "Add write access entries")
+    .option("--add-grant <access>", "Add grant access entries")
+    .option("--remove-read <access>", "Remove read access entries")
+    .option("--remove-write <access>", "Remove write access entries")
+    .option("--remove-grant <access>", "Remove grant access entries")
+    .option("--json", "Output as JSON")
+    .option("--db-path <path>", "Database file path")
+    .action(handleKeyUpdate);
 // Credential management commands
 const credentialCommand = program
     .command("credential")

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

@@ -0,0 +1,13 @@
+/**
+ * API key create command handler.
+ */
+interface KeyCreateOptions {
+    dbPath?: string;
+    name: string;
+    read?: string;
+    write?: string;
+    grant?: string;
+    json?: boolean;
+}
+export declare function handleKeyCreate(options: KeyCreateOptions): void;
+export {};

package/dist/commands/key-create.js

@@ -0,0 +1,99 @@
+/**
+ * API key create command handler.
+ */
+import { getServerConfig } from "../config.js";
+import { closeDatabase, getDatabase } from "../db/client.js";
+import { runMigrations } from "../db/migrations.js";
+import { createApiKey } from "../db/repositories/api-keys.js";
+import { containsControlChars, formatAccessList, getAccessListErrorMessage, getErrorMessage, normalizeAccessList, parseAccessList, sanitizeForTsv, } from "../lib/format.js";
+export function handleKeyCreate(options) {
+    // Validate key name (reject control characters)
+    if (containsControlChars(options.name)) {
+        console.error("Error: Key name contains control characters.");
+        process.exitCode = 2;
+        return;
+    }
+    // Parse and validate access lists
+    const readResult = parseAccessList(options.read);
+    const writeResult = parseAccessList(options.write);
+    const grantResult = parseAccessList(options.grant);
+    if (readResult.error) {
+        console.error(`Error: ${getAccessListErrorMessage(readResult.error)}`);
+        process.exitCode = 2;
+        return;
+    }
+    if (writeResult.error) {
+        console.error(`Error: ${getAccessListErrorMessage(writeResult.error)}`);
+        process.exitCode = 2;
+        return;
+    }
+    if (grantResult.error) {
+        console.error(`Error: ${getAccessListErrorMessage(grantResult.error)}`);
+        process.exitCode = 2;
+        return;
+    }
+    // Normalize wildcards (warn if mixed with specific entries)
+    const readNorm = normalizeAccessList(readResult.entries, "read");
+    const writeNorm = normalizeAccessList(writeResult.entries, "write");
+    const grantNorm = normalizeAccessList(grantResult.entries, "grant");
+    if (readNorm.warning)
+        console.warn(`Warning: ${readNorm.warning}`);
+    if (writeNorm.warning)
+        console.warn(`Warning: ${writeNorm.warning}`);
+    if (grantNorm.warning)
+        console.warn(`Warning: ${grantNorm.warning}`);
+    const readAccess = readNorm.normalized;
+    const writeAccess = writeNorm.normalized;
+    const grantAccess = grantNorm.normalized;
+    // Validate: at least one access must be specified
+    if (readAccess.length === 0 &&
+        writeAccess.length === 0 &&
+        grantAccess.length === 0) {
+        console.error("Error: At least one of --read, --write, or --grant must be specified.");
+        console.error("Try 'axvault key create --help' for more information.");
+        process.exitCode = 2;
+        return;
+    }
+    try {
+        const config = getServerConfig(options);
+        const database = getDatabase(config.databasePath);
+        runMigrations(database);
+        const apiKey = createApiKey(database, {
+            name: options.name,
+            readAccess,
+            writeAccess,
+            grantAccess,
+        });
+        if (options.json) {
+            console.warn("Warning: JSON output contains the secret key. Avoid logging in CI.");
+            console.log(JSON.stringify({
+                id: apiKey.id,
+                name: apiKey.name,
+                key: apiKey.key,
+                readAccess: apiKey.readAccess,
+                writeAccess: apiKey.writeAccess,
+                grantAccess: apiKey.grantAccess,
+                createdAt: apiKey.createdAt.toISOString(),
+            }, undefined, 2));
+        }
+        else {
+            console.error(`Created API key: ${sanitizeForTsv(apiKey.name)}`);
+            console.error(`ID: ${sanitizeForTsv(apiKey.id)}`);
+            console.error(`Read access: ${sanitizeForTsv(formatAccessList(apiKey.readAccess))}`);
+            console.error(`Write access: ${sanitizeForTsv(formatAccessList(apiKey.writeAccess))}`);
+            console.error(`Grant access: ${sanitizeForTsv(formatAccessList(apiKey.grantAccess))}`);
+            console.error("");
+            // Output the secret key to stdout for piping
+            console.log(apiKey.key);
+            console.error("");
+            console.error("Save this key securely - it cannot be retrieved later.");
+        }
+    }
+    catch (error) {
+        console.error(`Error: Failed to create API key: ${getErrorMessage(error)}`);
+        process.exitCode = 1;
+    }
+    finally {
+        closeDatabase();
+    }
+}

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

@@ -0,0 +1,9 @@
+/**
+ * API key list command handler.
+ */
+interface KeyListOptions {
+    dbPath?: string;
+    json?: boolean;
+}
+export declare function handleKeyList(options: KeyListOptions): void;
+export {};

package/dist/commands/key-list.js

@@ -0,0 +1,43 @@
+/**
+ * API key list command handler.
+ */
+import { getServerConfig } from "../config.js";
+import { closeDatabase, getDatabase } from "../db/client.js";
+import { runMigrations } from "../db/migrations.js";
+import { listApiKeys } from "../db/repositories/api-keys.js";
+import { formatDateForJson, formatKeyRow, getErrorMessage, } from "../lib/format.js";
+export function handleKeyList(options) {
+    try {
+        const config = getServerConfig(options);
+        const database = getDatabase(config.databasePath);
+        runMigrations(database);
+        const keys = listApiKeys(database);
+        if (options.json) {
+            const output = keys.map((key) => ({
+                id: key.id,
+                name: key.name,
+                readAccess: key.readAccess,
+                writeAccess: key.writeAccess,
+                grantAccess: key.grantAccess,
+                createdAt: key.createdAt.toISOString(),
+                lastUsedAt: formatDateForJson(key.lastUsedAt),
+            }));
+            console.log(JSON.stringify(output, undefined, 2));
+        }
+        else if (keys.length === 0) {
+            console.error("No API keys found.\nCreate one with: axvault key create --name <name> [--read <access>] [--write <access>] [--grant <access>]");
+        }
+        else {
+            console.log("ID\tNAME\tREAD ACCESS\tWRITE ACCESS\tGRANT ACCESS\tLAST USED");
+            for (const key of keys)
+                console.log(formatKeyRow(key));
+        }
+    }
+    catch (error) {
+        console.error(`Error: Failed to list API keys: ${getErrorMessage(error)}`);
+        process.exitCode = 1;
+    }
+    finally {
+        closeDatabase();
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * API key revoke command handler.
+ */
+interface KeyRevokeOptions {
+    dbPath?: string;
+}
+export declare function handleKeyRevoke(id: string, options: KeyRevokeOptions): void;
+export {};

package/dist/commands/key-revoke.js

@@ -0,0 +1,47 @@
+/**
+ * API key revoke command handler.
+ */
+import { getServerConfig } from "../config.js";
+import { closeDatabase, getDatabase } from "../db/client.js";
+import { runMigrations } from "../db/migrations.js";
+import { deleteApiKey } from "../db/repositories/api-keys.js";
+import { containsControlChars, getErrorMessage, isValidKeyId, sanitizeForTsv, } from "../lib/format.js";
+export function handleKeyRevoke(id, options) {
+    // Reject inputs containing control characters BEFORE trimming
+    // (prevents silent bypass where \n or \t would be removed by trim)
+    if (containsControlChars(id)) {
+        console.error("Error: Invalid API key ID: contains control characters.");
+        console.error("API key IDs have format: k_<12 hex chars> (e.g., k_abc123def456)");
+        process.exitCode = 2;
+        return;
+    }
+    // Trim whitespace from ID (common copy-paste issue)
+    const trimmedId = id.trim();
+    // Validate ID format (k_ + 12 hex chars)
+    if (!isValidKeyId(trimmedId)) {
+        console.error(`Error: Invalid API key ID format: ${trimmedId}`);
+        console.error("API key IDs have format: k_<12 hex chars> (e.g., k_abc123def456)");
+        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)}`);
+        }
+        else {
+            console.error(`Error: API key not found: ${sanitizeForTsv(trimmedId)}`);
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        console.error(`Error: Failed to revoke API key: ${getErrorMessage(error)}`);
+        process.exitCode = 1;
+    }
+    finally {
+        closeDatabase();
+    }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * API key update command handler.
+ */
+interface KeyUpdateOptions {
+    dbPath?: string;
+    addRead?: string;
+    addWrite?: string;
+    addGrant?: string;
+    removeRead?: string;
+    removeWrite?: string;
+    removeGrant?: string;
+    json?: boolean;
+}
+export declare function handleKeyUpdate(id: string, options: KeyUpdateOptions): void;
+export {};

package/dist/commands/key-update.js

@@ -0,0 +1,109 @@
+/**
+ * API key update command handler.
+ */
+import { getServerConfig } from "../config.js";
+import { closeDatabase, getDatabase } from "../db/client.js";
+import { runMigrations } from "../db/migrations.js";
+import { findApiKeyById, updateApiKeyAccess, } from "../db/repositories/api-keys.js";
+import { containsControlChars, formatAccessList, formatDateForJson, getErrorMessage, isValidKeyId, sanitizeForTsv, } from "../lib/format.js";
+import { computeUpdatedAccess, normalizeAllAccess, parseAccessOptions, } from "../lib/parse-access-options.js";
+export function handleKeyUpdate(id, options) {
+    // Validate key ID
+    if (containsControlChars(id)) {
+        console.error("Error: Invalid API key ID: contains control characters.");
+        console.error("API key IDs have format: k_<12 hex chars> (e.g., k_abc123def456)");
+        process.exitCode = 2;
+        return;
+    }
+    const trimmedId = id.trim();
+    if (!isValidKeyId(trimmedId)) {
+        console.error(`Error: Invalid API key ID format: ${trimmedId}`);
+        console.error("API key IDs have format: k_<12 hex chars> (e.g., k_abc123def456)");
+        process.exitCode = 2;
+        return;
+    }
+    // Parse and validate access options
+    const parsed = parseAccessOptions(options);
+    if (!parsed)
+        return; // Error already logged
+    // Check if any updates were requested
+    const hasUpdates = parsed.addRead.length > 0 ||
+        parsed.addWrite.length > 0 ||
+        parsed.addGrant.length > 0 ||
+        parsed.removeRead.length > 0 ||
+        parsed.removeWrite.length > 0 ||
+        parsed.removeGrant.length > 0;
+    if (!hasUpdates) {
+        console.error("Error: No updates specified.");
+        console.error("Try 'axvault key update --help' for more information.");
+        process.exitCode = 2;
+        return;
+    }
+    try {
+        const config = getServerConfig(options);
+        const database = getDatabase(config.databasePath);
+        runMigrations(database);
+        // Find existing key
+        const existingKey = findApiKeyById(database, trimmedId);
+        if (!existingKey) {
+            console.error(`Error: API key not found: ${sanitizeForTsv(trimmedId)}`);
+            process.exitCode = 1;
+            return;
+        }
+        // Compute new access lists
+        const newReadAccess = computeUpdatedAccess(existingKey.readAccess, parsed.addRead, parsed.removeRead);
+        const newWriteAccess = computeUpdatedAccess(existingKey.writeAccess, parsed.addWrite, parsed.removeWrite);
+        const newGrantAccess = computeUpdatedAccess(existingKey.grantAccess, parsed.addGrant, parsed.removeGrant);
+        // Normalize and update
+        const normalized = normalizeAllAccess(newReadAccess, newWriteAccess, newGrantAccess);
+        // Validate: at least one access must remain after update
+        if (normalized.read.length === 0 &&
+            normalized.write.length === 0 &&
+            normalized.grant.length === 0) {
+            console.error("Error: Update would leave the key with no permissions. At least one of read, write, or grant access must remain.");
+            process.exitCode = 2;
+            return;
+        }
+        updateApiKeyAccess(database, trimmedId, {
+            readAccess: normalized.read,
+            writeAccess: normalized.write,
+            grantAccess: normalized.grant,
+        });
+        // Fetch updated key for output
+        const updatedKey = findApiKeyById(database, trimmedId);
+        if (!updatedKey) {
+            console.error("Error: Failed to fetch updated key.");
+            process.exitCode = 1;
+            return;
+        }
+        outputKeyDetails(updatedKey, options.json ?? false);
+    }
+    catch (error) {
+        console.error(`Error: Failed to update API key: ${getErrorMessage(error)}`);
+        process.exitCode = 1;
+    }
+    finally {
+        closeDatabase();
+    }
+}
+/** Output key details in JSON or human-readable format */
+function outputKeyDetails(key, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            id: key.id,
+            name: key.name,
+            readAccess: key.readAccess,
+            writeAccess: key.writeAccess,
+            grantAccess: key.grantAccess,
+            createdAt: key.createdAt.toISOString(),
+            lastUsedAt: formatDateForJson(key.lastUsedAt),
+        }, undefined, 2));
+    }
+    else {
+        console.error(`Updated API key: ${sanitizeForTsv(key.name)}`);
+        console.error(`ID: ${sanitizeForTsv(key.id)}`);
+        console.error(`Read access: ${sanitizeForTsv(formatAccessList(key.readAccess))}`);
+        console.error(`Write access: ${sanitizeForTsv(formatAccessList(key.writeAccess))}`);
+        console.error(`Grant access: ${sanitizeForTsv(formatAccessList(key.grantAccess))}`);
+    }
+}

package/dist/commands/key.d.ts

@@ -1,21 +1,9 @@
 /**
  * API key management command handlers.
+ *
+ * Re-exports handlers from separate modules for better maintainability.
  */
-interface KeyCreateOptions {
-    dbPath?: string;
-    name: string;
-    read?: string;
-    write?: string;
-    json?: boolean;
-}
-interface KeyListOptions {
-    dbPath?: string;
-    json?: boolean;
-}
-interface KeyRevokeOptions {
-    dbPath?: string;
-}
-export declare function handleKeyCreate(options: KeyCreateOptions): void;
-export declare function handleKeyList(options: KeyListOptions): void;
-export declare function handleKeyRevoke(id: string, options: KeyRevokeOptions): void;
-export {};
+export { handleKeyCreate } from "./key-create.js";
+export { handleKeyList } from "./key-list.js";
+export { handleKeyRevoke } from "./key-revoke.js";
+export { handleKeyUpdate } from "./key-update.js";