axvault 1.8.2 → 1.9.1

package/README.md

@@ -192,6 +192,8 @@ This command requires `--force` or `--yes` to confirm.
 
 ### Container Deployments
 
+Container images are published automatically to `registry.j4k.dev/axvault` on every release (multi-arch: amd64 + arm64). Use `workflow_dispatch` on the `publish-image` workflow to rebuild manually.
+
 #### Running the Container
 
 The image uses an external UID pattern—no user is baked into the image. **Always specify a non-root user** with `-u`/`--user` to limit container privileges:

package/dist/commands/credential.js

@@ -7,14 +7,16 @@ import { runMigrations } from "../db/migrations.js";
 import { deleteCredential, listCredentials, } from "../db/repositories/credentials.js";
 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) */
+/** Print credentials as TSV table */
 function printCredentialTable(credentials) {
-    console.log("NAME\tCREATED\tUPDATED");
+    console.log("NAME\tAGENT\tPROVIDER\tCREATED\tUPDATED");
     for (const cred of credentials) {
         const name = sanitizeForTsv(cred.name);
+        const agent = cred.agent || "";
+        const provider = cred.provider ?? "";
         const created = formatRelativeTime(cred.createdAt);
         const updated = formatRelativeTime(cred.updatedAt);
-        console.log(`${name}\t${created}\t${updated}`);
+        console.log(`${name}\t${agent}\t${provider}\t${created}\t${updated}`);
     }
 }
 /**
@@ -53,9 +55,10 @@ 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) => ({
                 name: cred.name,
+                ...(cred.agent !== "" && { agent: cred.agent }),
+                ...(cred.provider !== undefined && { provider: cred.provider }),
                 createdAt: cred.createdAt.toISOString(),
                 updatedAt: cred.updatedAt.toISOString(),
             }));

package/dist/commands/serve.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { getServerConfig } from "../config.js";
 import { getDatabase, closeDatabase } from "../db/client.js";
 import { runMigrations } from "../db/migrations.js";
-import { createHealthRouter, createCredentialRouter, } from "../server/routes.js";
+import { createHealthRouter, createCredentialRouter, createKeyRouter, } from "../server/routes.js";
 import { createServer } from "../server/server.js";
 export async function handleServe(options) {
     let config;
@@ -68,6 +68,7 @@ export async function handleServe(options) {
             refreshThresholdSeconds: config.refreshThresholdSeconds,
             refreshTimeoutMs: config.refreshTimeoutMs,
         }),
+        createKeyRouter(database),
     ]);
     // Graceful shutdown handler
     const shutdown = () => {

package/dist/db/migrations.d.ts

@@ -5,7 +5,7 @@
  * Credentials are identified by name only - the blob contains all metadata.
  */
 import type Database from "better-sqlite3";
-declare const CURRENT_VERSION = 1;
+declare const CURRENT_VERSION = 2;
 /** Run all pending migrations */
 declare function runMigrations(database: Database.Database): void;
 /** Get current schema version */

package/dist/db/migrations.js

@@ -4,7 +4,7 @@
  * Simple schema with opaque credential storage.
  * Credentials are identified by name only - the blob contains all metadata.
  */
-const CURRENT_VERSION = 1;
+const CURRENT_VERSION = 2;
 /** Run all pending migrations */
 function runMigrations(database) {
     let version = getSchemaVersion(database);
@@ -17,6 +17,11 @@ function runMigrations(database) {
             version = 1;
             continue;
         }
+        if (version === 1) {
+            migrateToV2(database);
+            version = 2;
+            continue;
+        }
         throw new Error(`Unsupported database schema version v${version} (expected v${CURRENT_VERSION}). Delete the database file to reinitialize.`);
     }
 }
@@ -88,4 +93,24 @@ function migrateToV1(database) {
         setSchemaVersion(database, 1);
     })();
 }
+/**
+ * Migration to version 2: Add agent and provider columns
+ *
+ * Moves routing metadata (agent, provider) from the encrypted blob to
+ * unencrypted columns. This enables refresh-on-read to pass agent/provider
+ * to axauth without parsing the blob, and allows future filtering by agent.
+ *
+ * Existing rows get empty agent (new PUTs populate the column).
+ */
+function migrateToV2(database) {
+    database.transaction(() => {
+        database.exec(`
+      ALTER TABLE credentials ADD COLUMN agent TEXT NOT NULL DEFAULT ''
+    `);
+        database.exec(`
+      ALTER TABLE credentials ADD COLUMN provider TEXT DEFAULT NULL
+    `);
+        setSchemaVersion(database, 2);
+    })();
+}
 export { CURRENT_VERSION, getSchemaVersion, runMigrations };

package/dist/db/repositories/credentials-queries.d.ts

@@ -1,12 +1,10 @@
 /**
  * SQL queries for credentials repository.
- *
- * Name-only primary key, opaque blob storage.
  */
-export declare const UPSERT_CREDENTIAL = "\n  INSERT INTO credentials (name, encrypted_data, salt, iv, auth_tag, created_at, updated_at)\n  VALUES (?, ?, ?, ?, ?, ?, ?)\n  ON CONFLICT(name) DO UPDATE SET\n    encrypted_data = excluded.encrypted_data, salt = excluded.salt, iv = excluded.iv, auth_tag = excluded.auth_tag,\n    updated_at = excluded.updated_at\n  RETURNING created_at, updated_at";
+export declare const UPSERT_CREDENTIAL = "\n  INSERT INTO credentials (name, agent, provider, encrypted_data, salt, iv, auth_tag, created_at, updated_at)\n  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)\n  ON CONFLICT(name) DO UPDATE SET\n    agent = excluded.agent, provider = excluded.provider,\n    encrypted_data = excluded.encrypted_data, salt = excluded.salt, iv = excluded.iv, auth_tag = excluded.auth_tag,\n    updated_at = excluded.updated_at\n  RETURNING created_at, updated_at";
 export declare const UPDATE_CREDENTIAL_IF_UPDATED_AT_MATCHES = "\n  UPDATE credentials\n  SET encrypted_data = ?, salt = ?, iv = ?, auth_tag = ?, updated_at = ?\n  WHERE name = ? AND updated_at = ?";
-export declare const SELECT_CREDENTIAL = "\n  SELECT name, encrypted_data, salt, iv, auth_tag, created_at, updated_at\n  FROM credentials WHERE name = ?";
-export declare const SELECT_ALL_METADATA = "\n  SELECT name, created_at, updated_at\n  FROM credentials ORDER BY name";
-export declare const SELECT_METADATA_PAGINATED = "\n  SELECT name, created_at, updated_at\n  FROM credentials\n  WHERE name > ?\n  ORDER BY name\n  LIMIT ?";
-export declare const SELECT_METADATA_FIRST_PAGE = "\n  SELECT name, created_at, updated_at\n  FROM credentials\n  ORDER BY name\n  LIMIT ?";
+export declare const SELECT_CREDENTIAL = "\n  SELECT name, agent, provider, encrypted_data, salt, iv, auth_tag, created_at, updated_at\n  FROM credentials WHERE name = ?";
+export declare const SELECT_ALL_METADATA = "\n  SELECT name, agent, provider, created_at, updated_at\n  FROM credentials ORDER BY name";
+export declare const SELECT_METADATA_PAGINATED = "\n  SELECT name, agent, provider, created_at, updated_at\n  FROM credentials\n  WHERE name > ?\n  ORDER BY name\n  LIMIT ?";
+export declare const SELECT_METADATA_FIRST_PAGE = "\n  SELECT name, agent, provider, created_at, updated_at\n  FROM credentials\n  ORDER BY name\n  LIMIT ?";
 export declare const DELETE_CREDENTIAL = "\n  DELETE FROM credentials WHERE name = ?";

package/dist/db/repositories/credentials-queries.js

@@ -1,12 +1,11 @@
 /**
  * SQL queries for credentials repository.
- *
- * Name-only primary key, opaque blob storage.
  */
 export const UPSERT_CREDENTIAL = `
-  INSERT INTO credentials (name, encrypted_data, salt, iv, auth_tag, created_at, updated_at)
-  VALUES (?, ?, ?, ?, ?, ?, ?)
+  INSERT INTO credentials (name, agent, provider, encrypted_data, salt, iv, auth_tag, created_at, updated_at)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
   ON CONFLICT(name) DO UPDATE SET
+    agent = excluded.agent, provider = excluded.provider,
     encrypted_data = excluded.encrypted_data, salt = excluded.salt, iv = excluded.iv, auth_tag = excluded.auth_tag,
     updated_at = excluded.updated_at
   RETURNING created_at, updated_at`;
@@ -15,19 +14,19 @@ export const UPDATE_CREDENTIAL_IF_UPDATED_AT_MATCHES = `
   SET encrypted_data = ?, salt = ?, iv = ?, auth_tag = ?, updated_at = ?
   WHERE name = ? AND updated_at = ?`;
 export const SELECT_CREDENTIAL = `
-  SELECT name, encrypted_data, salt, iv, auth_tag, created_at, updated_at
+  SELECT name, agent, provider, encrypted_data, salt, iv, auth_tag, created_at, updated_at
   FROM credentials WHERE name = ?`;
 export const SELECT_ALL_METADATA = `
-  SELECT name, created_at, updated_at
+  SELECT name, agent, provider, created_at, updated_at
   FROM credentials ORDER BY name`;
 export const SELECT_METADATA_PAGINATED = `
-  SELECT name, created_at, updated_at
+  SELECT name, agent, provider, created_at, updated_at
   FROM credentials
   WHERE name > ?
   ORDER BY name
   LIMIT ?`;
 export const SELECT_METADATA_FIRST_PAGE = `
-  SELECT name, created_at, updated_at
+  SELECT name, agent, provider, created_at, updated_at
   FROM credentials
   ORDER BY name
   LIMIT ?`;

package/dist/db/repositories/credentials.d.ts

@@ -14,6 +14,8 @@ interface UpsertTimestamps {
 /** Store or update a credential, returning the resulting timestamps */
 declare function upsertCredential(database: Database.Database, credential: {
     name: string;
+    agent: string;
+    provider: string | undefined;
     encryptedData: Buffer;
     salt: Buffer;
     iv: Buffer;

package/dist/db/repositories/credentials.js

@@ -11,7 +11,7 @@ function upsertCredential(database, credential) {
     const now = Date.now();
     const row = database
         .prepare(SQL.UPSERT_CREDENTIAL)
-        .get(credential.name, credential.encryptedData, credential.salt, credential.iv, credential.authTag, now, now);
+        .get(credential.name, credential.agent, credential.provider ?? undefined, credential.encryptedData, credential.salt, credential.iv, credential.authTag, now, now);
     return {
         createdAt: new Date(row.created_at),
         updatedAt: new Date(row.updated_at),

package/dist/db/repositories/list-credentials-paginated.js

@@ -16,7 +16,7 @@ function buildFilteredQuery(names, cursor, limit) {
     const placeholders = names.map(() => "?").join(", ");
     const cursorClause = cursor ? " AND name > ?" : "";
     const sql = `
-    SELECT name, created_at, updated_at
+    SELECT name, agent, provider, created_at, updated_at
     FROM credentials
     WHERE name IN (${placeholders})${cursorClause}
     ORDER BY name

package/dist/db/repositories/parse-credential-row.d.ts

@@ -7,6 +7,8 @@ import type { CredentialRow, MetadataRow } from "../types.js";
 /** Credential record stored in database */
 interface CredentialRecord {
     name: string;
+    agent: string;
+    provider: string | undefined;
     encryptedData: Buffer;
     salt: Buffer;
     iv: Buffer;
@@ -17,6 +19,8 @@ interface CredentialRecord {
 /** Credential metadata (without encrypted data) */
 interface CredentialMetadata {
     name: string;
+    agent: string;
+    provider: string | undefined;
     createdAt: Date;
     updatedAt: Date;
 }

package/dist/db/repositories/parse-credential-row.js

@@ -7,6 +7,8 @@
 function rowToRecord(row) {
     return {
         name: row.name,
+        agent: row.agent,
+        provider: row.provider ?? undefined,
         encryptedData: row.encrypted_data,
         salt: row.salt,
         iv: row.iv,
@@ -19,6 +21,8 @@ function rowToRecord(row) {
 function rowToMetadata(row) {
     return {
         name: row.name,
+        agent: row.agent,
+        provider: row.provider ?? undefined,
         createdAt: new Date(row.created_at),
         updatedAt: new Date(row.updated_at),
     };

package/dist/db/types.d.ts

@@ -23,9 +23,11 @@ export interface AuditLogRow {
     success: number;
     error_message: string | null;
 }
-/** Raw credential row from database (opaque blob storage) */
+/** Raw credential row from database */
 export interface CredentialRow {
     name: string;
+    agent: string;
+    provider: string | null;
     encrypted_data: Buffer;
     salt: Buffer;
     iv: Buffer;
@@ -36,6 +38,8 @@ export interface CredentialRow {
 /** Raw credential metadata row from database */
 export interface MetadataRow {
     name: string;
+    agent: string;
+    provider: string | null;
     created_at: number;
     updated_at: number;
 }

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

@@ -0,0 +1,10 @@
+/**
+ * POST /api/v1/keys handler.
+ *
+ * Creates a new API key and returns the one-time secret.
+ */
+import type { RequestHandler } from "express";
+import type Database from "better-sqlite3";
+/** Create a new API key */
+declare function createCreateKeyHandler(database: Database.Database): RequestHandler;
+export { createCreateKeyHandler };

package/dist/handlers/create-key.js

@@ -0,0 +1,63 @@
+/**
+ * POST /api/v1/keys handler.
+ *
+ * Creates a new API key and returns the one-time secret.
+ */
+import { createApiKey } from "../db/repositories/api-keys.js";
+import { serializeKeyForResponse } from "./serialize-key.js";
+/** Validate that the request body has valid access lists */
+function isValidAccessLists(body) {
+    const { readAccess, writeAccess, grantAccess } = body;
+    if (!Array.isArray(readAccess) ||
+        !readAccess.every((v) => typeof v === "string"))
+        return false;
+    if (!Array.isArray(writeAccess) ||
+        !writeAccess.every((v) => typeof v === "string"))
+        return false;
+    if (!Array.isArray(grantAccess) ||
+        !grantAccess.every((v) => typeof v === "string"))
+        return false;
+    // At least one access list must be non-empty
+    if (readAccess.length === 0 &&
+        writeAccess.length === 0 &&
+        grantAccess.length === 0)
+        return false;
+    return true;
+}
+/** Create a new API key */
+function createCreateKeyHandler(database) {
+    return (request, response) => {
+        const body = request.body;
+        if (typeof body !== "object" || body === null || Array.isArray(body)) {
+            response
+                .status(400)
+                .json({ error: "Request body must be a JSON object" });
+            return;
+        }
+        const record = body;
+        const { name } = record;
+        if (typeof name !== "string" || name.trim().length === 0) {
+            response
+                .status(400)
+                .json({ error: "name is required and must be a non-empty string" });
+            return;
+        }
+        if (!isValidAccessLists(record)) {
+            response.status(400).json({
+                error: "readAccess, writeAccess, and grantAccess must be string arrays; at least one must be non-empty",
+            });
+            return;
+        }
+        const keyWithSecret = createApiKey(database, {
+            name: name.trim(),
+            readAccess: record.readAccess,
+            writeAccess: record.writeAccess,
+            grantAccess: record.grantAccess,
+        });
+        response.status(201).json({
+            ...serializeKeyForResponse(keyWithSecret),
+            key: keyWithSecret.key,
+        });
+    };
+}
+export { createCreateKeyHandler };

package/dist/handlers/delete-key.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DELETE /api/v1/keys/:id handler.
+ *
+ * Revokes an API key.
+ */
+import type { RequestHandler } from "express";
+import type Database from "better-sqlite3";
+/** Handler type for key routes with id param */
+type KeyHandler = RequestHandler<{
+    id: string;
+}, unknown, unknown, unknown>;
+/** Revoke an API key */
+declare function createDeleteKeyHandler(database: Database.Database): KeyHandler;
+export { createDeleteKeyHandler };

package/dist/handlers/delete-key.js

@@ -0,0 +1,25 @@
+/**
+ * DELETE /api/v1/keys/:id handler.
+ *
+ * Revokes an API key.
+ */
+import { deleteApiKey } from "../db/repositories/api-keys.js";
+/** Revoke an API key */
+function createDeleteKeyHandler(database) {
+    return (request, response) => {
+        const { apiKey } = request;
+        const { id } = request.params;
+        // Prevent self-deletion
+        if (apiKey.id === id) {
+            response.status(403).json({ error: "Cannot revoke your own API key" });
+            return;
+        }
+        const deleted = deleteApiKey(database, id);
+        if (!deleted) {
+            response.status(404).json({ error: "API key not found" });
+            return;
+        }
+        response.status(204).end();
+    };
+}
+export { createDeleteKeyHandler };

package/dist/handlers/get-credential.js

@@ -67,6 +67,8 @@ function createGetCredentialHandler(database, config) {
             apiKeyId: apiKey.id,
             name,
             blob,
+            agent: credential.agent,
+            provider: credential.provider,
             expectedUpdatedAt: credential.updatedAt,
             refreshThresholdSeconds: config.refreshThresholdSeconds,
             refreshTimeoutMs: config.refreshTimeoutMs,
@@ -94,9 +96,13 @@ function createGetCredentialHandler(database, config) {
         if (refreshFailed) {
             response.setHeader("X-Axvault-Refresh-Failed", "true");
         }
-        // Return the blob as-is (opaque to axvault)
+        // Return the blob along with routing metadata from columns
         response.json({
             name,
+            ...(credential.agent !== "" && { agent: credential.agent }),
+            ...(credential.provider !== undefined && {
+                provider: credential.provider,
+            }),
             credential: finalBlob,
             updatedAt: finalUpdatedAt.toISOString(),
         });

package/dist/handlers/get-key.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GET /api/v1/keys/:id handler.
+ *
+ * Returns a single API key by ID.
+ */
+import type { RequestHandler } from "express";
+import type Database from "better-sqlite3";
+/** Handler type for key routes with id param */
+type KeyHandler = RequestHandler<{
+    id: string;
+}, unknown, unknown, unknown>;
+/** Get a single API key by ID */
+declare function createGetKeyHandler(database: Database.Database): KeyHandler;
+export { createGetKeyHandler };

package/dist/handlers/get-key.js

@@ -0,0 +1,20 @@
+/**
+ * GET /api/v1/keys/:id handler.
+ *
+ * Returns a single API key by ID.
+ */
+import { findApiKeyById } from "../db/repositories/api-keys.js";
+import { serializeKeyForResponse } from "./serialize-key.js";
+/** Get a single API key by ID */
+function createGetKeyHandler(database) {
+    return (request, response) => {
+        const { id } = request.params;
+        const key = findApiKeyById(database, id);
+        if (!key) {
+            response.status(404).json({ error: "API key not found" });
+            return;
+        }
+        response.json(serializeKeyForResponse(key));
+    };
+}
+export { createGetKeyHandler };

package/dist/handlers/list-credentials.js

@@ -10,6 +10,16 @@
  */
 import { listCredentialsForApiKey, listCredentialsPaginated, } from "../db/repositories/credentials.js";
 import { logAccess } from "../db/repositories/audit-log.js";
+/** Format credential metadata for API response */
+function formatCredentialMetadata(cred) {
+    return {
+        name: cred.name,
+        ...(cred.agent !== "" && { agent: cred.agent }),
+        ...(cred.provider !== undefined && { provider: cred.provider }),
+        createdAt: cred.createdAt.toISOString(),
+        updatedAt: cred.updatedAt.toISOString(),
+    };
+}
 /** Maximum page size when limit is specified */
 const MAX_LIMIT = 1000;
 /**
@@ -61,11 +71,7 @@ function createListCredentialsHandler(database) {
                 success: true,
             });
             response.json({
-                credentials: credentials.map((cred) => ({
-                    name: cred.name,
-                    createdAt: cred.createdAt.toISOString(),
-                    updatedAt: cred.updatedAt.toISOString(),
-                })),
+                credentials: credentials.map((cred) => formatCredentialMetadata(cred)),
             });
             return;
         }
@@ -92,11 +98,7 @@ function createListCredentialsHandler(database) {
             success: true,
         });
         response.json({
-            credentials: result.credentials.map((cred) => ({
-                name: cred.name,
-                createdAt: cred.createdAt.toISOString(),
-                updatedAt: cred.updatedAt.toISOString(),
-            })),
+            credentials: result.credentials.map((cred) => formatCredentialMetadata(cred)),
             ...(result.nextCursor !== undefined && {
                 nextCursor: result.nextCursor,
             }),

package/dist/handlers/list-keys.d.ts

@@ -0,0 +1,10 @@
+/**
+ * GET /api/v1/keys handler.
+ *
+ * Lists all API keys (metadata only, no secrets).
+ */
+import type { RequestHandler } from "express";
+import type Database from "better-sqlite3";
+/** List all API keys */
+declare function createListKeysHandler(database: Database.Database): RequestHandler;
+export { createListKeysHandler };

package/dist/handlers/list-keys.js

@@ -0,0 +1,15 @@
+/**
+ * GET /api/v1/keys handler.
+ *
+ * Lists all API keys (metadata only, no secrets).
+ */
+import { listApiKeys } from "../db/repositories/api-keys.js";
+import { serializeKeyForResponse } from "./serialize-key.js";
+/** List all API keys */
+function createListKeysHandler(database) {
+    return (_request, response) => {
+        const keys = listApiKeys(database);
+        response.json({ keys: keys.map((key) => serializeKeyForResponse(key)) });
+    };
+}
+export { createListKeysHandler };

package/dist/handlers/put-credential.js

@@ -48,10 +48,19 @@ function createPutCredentialHandler(database) {
             return;
         }
         try {
-            // Encrypt the blob as-is (opaque storage)
-            const encrypted = encryptCredential(body);
+            // Extract routing metadata from body before encrypting
+            const bodyRecord = body;
+            const agent = typeof bodyRecord.agent === "string" ? bodyRecord.agent : "";
+            const provider = typeof bodyRecord.provider === "string"
+                ? bodyRecord.provider
+                : undefined;
+            // Encrypt the credential blob (agent/provider stored as columns, not in blob)
+            const credentialBlob = Object.fromEntries(Object.entries(bodyRecord).filter(([key]) => key !== "agent" && key !== "provider"));
+            const encrypted = encryptCredential(credentialBlob);
             const timestamps = upsertCredential(database, {
                 name,
+                agent,
+                provider,
                 ...encrypted,
             });
             logAccess(database, {

package/dist/handlers/refresh-credential-on-read.d.ts

@@ -19,6 +19,8 @@ declare function refreshCredentialOnRead(options: {
     apiKeyId: string;
     name: string;
     blob: unknown;
+    agent: string;
+    provider: string | undefined;
     expectedUpdatedAt: Date;
     refreshThresholdSeconds: number;
     refreshTimeoutMs: number;

package/dist/handlers/refresh-credential-on-read.js

@@ -5,17 +5,17 @@
  * stays small enough for static complexity checks (FTA).
  */
 import { isCredentialExpired, isRefreshable, refreshBlob, } from "axauth";
-import { isRefreshableCredentialType, parseCredentials } from "axshared";
+import { isValidAgentCli, isRefreshableCredentialType, parseCredentials } from "axshared";
 import { getCredential, updateCredentialIfUnchanged, } from "../db/repositories/credentials.js";
 import { logAccess } from "../db/repositories/audit-log.js";
 import { decryptCredential, encryptCredential } from "../lib/encryption.js";
 /** Per-credential mutex to prevent concurrent refreshes */
 const pendingRefreshes = new Map();
-function getRefreshPromise(name, blob, refreshTimeoutMs) {
+function getRefreshPromise(name, blob, agent, provider, refreshTimeoutMs) {
     const existing = pendingRefreshes.get(name);
     if (existing)
         return existing;
-    const promise = refreshBlob(blob, { timeout: refreshTimeoutMs });
+    const promise = refreshBlob(blob, { agent, provider, timeout: refreshTimeoutMs });
     pendingRefreshes.set(name, promise);
     void promise.finally(() => {
         if (pendingRefreshes.get(name) === promise) {
@@ -34,6 +34,17 @@ async function refreshCredentialOnRead(options) {
             refreshFailed: false,
         };
     }
+    // Refresh requires a valid agent ID (empty means pre-v2 credential)
+    if (!isValidAgentCli(options.agent)) {
+        return {
+            status: "ok",
+            blob: options.blob,
+            updatedAt: options.expectedUpdatedAt,
+            wasRefreshed: false,
+            refreshFailed: false,
+        };
+    }
+    const agent = options.agent;
     const parsedCredentials = parseCredentials(options.blob);
     if (parsedCredentials === undefined ||
         !isRefreshableCredentialType(parsedCredentials.type) ||
@@ -48,7 +59,7 @@ async function refreshCredentialOnRead(options) {
         };
     }
     try {
-        const refreshResult = await getRefreshPromise(options.name, options.blob, options.refreshTimeoutMs);
+        const refreshResult = await getRefreshPromise(options.name, options.blob, agent, options.provider, options.refreshTimeoutMs);
         if (refreshResult.ok) {
             const encrypted = encryptCredential(refreshResult.blob);
             const updateResult = updateCredentialIfUnchanged(options.database, {

package/dist/handlers/serialize-key.d.ts

@@ -0,0 +1,20 @@
+/**
+ * API key serialization for HTTP responses.
+ *
+ * Converts ApiKeyRecord to a safe JSON shape (omits keyHash, converts dates).
+ */
+import type { ApiKeyRecord } from "../db/repositories/api-keys.js";
+/** JSON-safe API key response shape */
+interface SerializedKey {
+    id: string;
+    name: string;
+    keyPrefix: string | null;
+    readAccess: string[];
+    writeAccess: string[];
+    grantAccess: string[];
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+/** Convert an ApiKeyRecord to the JSON response shape */
+declare function serializeKeyForResponse(key: ApiKeyRecord): SerializedKey;
+export { serializeKeyForResponse };

package/dist/handlers/serialize-key.js

@@ -0,0 +1,21 @@
+/**
+ * API key serialization for HTTP responses.
+ *
+ * Converts ApiKeyRecord to a safe JSON shape (omits keyHash, converts dates).
+ */
+/** Convert an ApiKeyRecord to the JSON response shape */
+function serializeKeyForResponse(key) {
+    return {
+        id: key.id,
+        name: key.name,
+        // eslint-disable-next-line unicorn/no-null -- JSON API requires null for missing values
+        keyPrefix: key.keyPrefix ?? null,
+        readAccess: key.readAccess,
+        writeAccess: key.writeAccess,
+        grantAccess: key.grantAccess,
+        createdAt: key.createdAt.toISOString(),
+        // eslint-disable-next-line unicorn/no-null -- JSON API requires null for missing values
+        lastUsedAt: key.lastUsedAt?.toISOString() ?? null,
+    };
+}
+export { serializeKeyForResponse };

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

@@ -0,0 +1,14 @@
+/**
+ * PATCH /api/v1/keys/:id handler.
+ *
+ * Updates an API key's access permissions.
+ */
+import type { RequestHandler } from "express";
+import type Database from "better-sqlite3";
+/** Handler type for key routes with id param */
+type KeyHandler = RequestHandler<{
+    id: string;
+}, unknown, unknown, unknown>;
+/** Update an API key's permissions */
+declare function createUpdateKeyHandler(database: Database.Database): KeyHandler;
+export { createUpdateKeyHandler };

package/dist/handlers/update-key.js

@@ -0,0 +1,90 @@
+/**
+ * PATCH /api/v1/keys/:id handler.
+ *
+ * Updates an API key's access permissions.
+ */
+import { findApiKeyById, updateApiKeyAccess, } from "../db/repositories/api-keys.js";
+import { serializeKeyForResponse } from "./serialize-key.js";
+/** Check if value is a string array */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+/** Update an API key's permissions */
+function createUpdateKeyHandler(database) {
+    return (request, response) => {
+        const { apiKey } = request;
+        const { id } = request.params;
+        // Prevent self-modification
+        if (apiKey.id === id) {
+            response.status(403).json({ error: "Cannot modify your own API key" });
+            return;
+        }
+        const body = request.body;
+        if (typeof body !== "object" || body === null || Array.isArray(body)) {
+            response
+                .status(400)
+                .json({ error: "Request body must be a JSON object" });
+            return;
+        }
+        const record = body;
+        const { readAccess, writeAccess, grantAccess } = record;
+        // At least one field must be provided
+        if (readAccess === undefined &&
+            writeAccess === undefined &&
+            grantAccess === undefined) {
+            response.status(400).json({
+                error: "At least one of readAccess, writeAccess, or grantAccess is required",
+            });
+            return;
+        }
+        // Validate types of provided fields
+        if (readAccess !== undefined && !isStringArray(readAccess)) {
+            response
+                .status(400)
+                .json({ error: "readAccess must be an array of strings" });
+            return;
+        }
+        if (writeAccess !== undefined && !isStringArray(writeAccess)) {
+            response
+                .status(400)
+                .json({ error: "writeAccess must be an array of strings" });
+            return;
+        }
+        if (grantAccess !== undefined && !isStringArray(grantAccess)) {
+            response
+                .status(400)
+                .json({ error: "grantAccess must be an array of strings" });
+            return;
+        }
+        // Check target key exists before update
+        const existingKey = findApiKeyById(database, id);
+        if (!existingKey) {
+            response.status(404).json({ error: "API key not found" });
+            return;
+        }
+        // Compute resulting access lists to validate at least one is non-empty
+        const resultReadAccess = readAccess ?? existingKey.readAccess;
+        const resultWriteAccess = writeAccess ?? existingKey.writeAccess;
+        const resultGrantAccess = grantAccess ?? existingKey.grantAccess;
+        if (resultReadAccess.length === 0 &&
+            resultWriteAccess.length === 0 &&
+            resultGrantAccess.length === 0) {
+            response.status(400).json({
+                error: "Key must retain at least one non-empty access list",
+            });
+            return;
+        }
+        updateApiKeyAccess(database, id, {
+            readAccess,
+            writeAccess,
+            grantAccess,
+        });
+        const updatedKey = findApiKeyById(database, id);
+        if (!updatedKey) {
+            response.status(404).json({ error: "API key not found" });
+            return;
+        }
+        response.json(serializeKeyForResponse(updatedKey));
+    };
+}
+export { createUpdateKeyHandler };

package/dist/index.d.ts

@@ -7,11 +7,11 @@ export type { ServerConfig } from "./config.js";
 export { getServerConfig } from "./config.js";
 export type { AxvaultServer } from "./server/server.js";
 export { createServer } from "./server/server.js";
-export { createApiRouter } from "./server/routes.js";
+export { createApiRouter, createKeyRouter } from "./server/routes.js";
 export { closeDatabase, getDatabase, isDatabaseConnected, } from "./db/client.js";
 export { CURRENT_VERSION, getSchemaVersion, runMigrations, } from "./db/migrations.js";
 export type { ApiKeyRecord, ApiKeyWithSecret, } from "./db/repositories/api-keys.js";
-export { createApiKey, deleteApiKey, findApiKeyById, findApiKeyByKey, hasReadAccess, hasWriteAccess, listApiKeys, updateLastUsed, } from "./db/repositories/api-keys.js";
+export { createApiKey, deleteApiKey, findApiKeyById, findApiKeyByKey, hasGrantAccess, hasReadAccess, hasWriteAccess, listApiKeys, updateApiKeyAccess, updateLastUsed, } from "./db/repositories/api-keys.js";
 export type { AuditLogEntry } from "./db/repositories/audit-log.js";
 export { getLogsForCredential, getRecentLogs, logAccess, pruneOldLogs, } from "./db/repositories/audit-log.js";
 export type { CredentialMetadata, CredentialRecord, } from "./db/repositories/credentials.js";

package/dist/index.js

@@ -5,10 +5,10 @@
  */
 export { getServerConfig } from "./config.js";
 export { createServer } from "./server/server.js";
-export { createApiRouter } from "./server/routes.js";
+export { createApiRouter, createKeyRouter } from "./server/routes.js";
 // Database client
 export { closeDatabase, getDatabase, isDatabaseConnected, } from "./db/client.js";
 export { CURRENT_VERSION, getSchemaVersion, runMigrations, } from "./db/migrations.js";
-export { createApiKey, deleteApiKey, findApiKeyById, findApiKeyByKey, hasReadAccess, hasWriteAccess, listApiKeys, updateLastUsed, } from "./db/repositories/api-keys.js";
+export { createApiKey, deleteApiKey, findApiKeyById, findApiKeyByKey, hasGrantAccess, hasReadAccess, hasWriteAccess, listApiKeys, updateApiKeyAccess, updateLastUsed, } from "./db/repositories/api-keys.js";
 export { getLogsForCredential, getRecentLogs, logAccess, pruneOldLogs, } from "./db/repositories/audit-log.js";
 export { deleteCredential, getCredential, listCredentials, listCredentialsForApiKey, listCredentialsPaginated, upsertCredential, } from "./db/repositories/credentials.js";

package/dist/middleware/require-grant-access.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Grant access authorization middleware.
+ *
+ * Ensures the authenticated API key has grant access to all resources ("*").
+ */
+import type { NextFunction, Request, Response } from "express";
+/** Require the caller's API key to have full grant access ("*") */
+declare function requireGrantAccess(request: Request, response: Response, next: NextFunction): void;
+export { requireGrantAccess };

package/dist/middleware/require-grant-access.js

@@ -0,0 +1,16 @@
+/**
+ * Grant access authorization middleware.
+ *
+ * Ensures the authenticated API key has grant access to all resources ("*").
+ */
+import { hasGrantAccess } from "../db/repositories/api-keys.js";
+/** Require the caller's API key to have full grant access ("*") */
+function requireGrantAccess(request, response, next) {
+    const { apiKey } = request;
+    if (!hasGrantAccess(apiKey, "*")) {
+        response.status(403).json({ error: "Grant access required" });
+        return;
+    }
+    next();
+}
+export { requireGrantAccess };

package/dist/middleware/validate-key-id.d.ts

@@ -0,0 +1,9 @@
+/**
+ * API key ID parameter validation middleware.
+ *
+ * Validates that the :id path parameter matches the expected key ID format.
+ */
+import type { NextFunction, Request, Response } from "express";
+/** Validate API key ID path parameter */
+declare function validateKeyId(request: Request, response: Response, next: NextFunction): void;
+export { validateKeyId };

package/dist/middleware/validate-key-id.js

@@ -0,0 +1,19 @@
+/**
+ * API key ID parameter validation middleware.
+ *
+ * Validates that the :id path parameter matches the expected key ID format.
+ */
+/** Key ID format: "k_" followed by exactly 12 hex characters */
+const KEY_ID_PATTERN = /^k_[\da-f]{12}$/u;
+/** Validate API key ID path parameter */
+function validateKeyId(request, response, next) {
+    const { id } = request.params;
+    if (id !== undefined && !KEY_ID_PATTERN.test(id)) {
+        response.status(400).json({
+            error: "Invalid key ID format. Must be 'k_' followed by 12 hex characters.",
+        });
+        return;
+    }
+    next();
+}
+export { validateKeyId };

package/dist/server/routes.d.ts

@@ -8,5 +8,7 @@ import { type GetCredentialConfig } from "../handlers/get-credential.js";
 export declare function createHealthRouter(): Router;
 /** Create credential API router (auth required) */
 export declare function createCredentialRouter(database: Database.Database, config: GetCredentialConfig): Router;
+/** Create API key management router (auth + grant access required) */
+export declare function createKeyRouter(database: Database.Database): Router;
 /** Create all API routers (legacy compatibility) */
 export declare function createApiRouter(): Router;

package/dist/server/routes.js

@@ -3,11 +3,18 @@
  */
 import { Router } from "express";
 import packageJson from "../../package.json" with { type: "json" };
+import { createCreateKeyHandler } from "../handlers/create-key.js";
 import { createDeleteCredentialHandler } from "../handlers/delete-credential.js";
+import { createDeleteKeyHandler } from "../handlers/delete-key.js";
 import { createGetCredentialHandler, } from "../handlers/get-credential.js";
+import { createGetKeyHandler } from "../handlers/get-key.js";
 import { createListCredentialsHandler } from "../handlers/list-credentials.js";
+import { createListKeysHandler } from "../handlers/list-keys.js";
 import { createPutCredentialHandler } from "../handlers/put-credential.js";
+import { createUpdateKeyHandler } from "../handlers/update-key.js";
 import { createAuthMiddleware } from "../middleware/auth.js";
+import { requireGrantAccess } from "../middleware/require-grant-access.js";
+import { validateKeyId } from "../middleware/validate-key-id.js";
 import { validateParameters } from "../middleware/validate-parameters.js";
 /** Create health check router (no auth required) */
 export function createHealthRouter() {
@@ -36,6 +43,24 @@ export function createCredentialRouter(database, config) {
     router.delete("/api/v1/credentials/:name", validateParameters, createDeleteCredentialHandler(database));
     return router;
 }
+/** Create API key management router (auth + grant access required) */
+export function createKeyRouter(database) {
+    const router = Router();
+    const authMiddleware = createAuthMiddleware(database);
+    // All key routes require authentication and grant access
+    router.use("/api/v1/keys", authMiddleware, requireGrantAccess);
+    // List all keys
+    router.get("/api/v1/keys", createListKeysHandler(database));
+    // Create a new key
+    router.post("/api/v1/keys", createCreateKeyHandler(database));
+    // Get a single key
+    router.get("/api/v1/keys/:id", validateKeyId, createGetKeyHandler(database));
+    // Update key permissions
+    router.patch("/api/v1/keys/:id", validateKeyId, createUpdateKeyHandler(database));
+    // Revoke a key
+    router.delete("/api/v1/keys/:id", validateKeyId, createDeleteKeyHandler(database));
+    return router;
+}
 /** Create all API routers (legacy compatibility) */
 export function createApiRouter() {
     // For backward compatibility, returns just health router

package/package.json

@@ -2,7 +2,7 @@
   "name": "axvault",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.8.2",
+  "version": "1.9.1",
   "description": "Remote credential storage server for axkit",
   "repository": {
     "type": "git",
@@ -49,8 +49,8 @@
   },
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
-    "axauth": "^3.1.1",
-    "axshared": "4.0.0",
+    "axauth": "^3.1.4",
+    "axshared": "5.0.0",
     "better-sqlite3": "^12.6.2",
     "commander": "^14.0.2",
     "express": "^5.2.1"