axvault 1.8.0 → 1.8.2

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

@@ -1,41 +1,26 @@
 /**
  * Pure functions for parsing credential database rows.
+ *
+ * Credentials are fully opaque blobs - we don't inspect their structure.
  */
-import { CredentialType } from "axshared";
-/** Parse and validate credential type from database */
-function parseCredentialType(type) {
-    const result = CredentialType.safeParse(type);
-    if (!result.success) {
-        throw new Error(`Invalid credential type: ${type}`);
-    }
-    return result.data;
-}
 /** Convert database row to record */
 function rowToRecord(row) {
     return {
-        agent: row.agent,
         name: row.name,
-        type: parseCredentialType(row.type),
-        provider: row.provider ?? undefined,
         encryptedData: row.encrypted_data,
         salt: row.salt,
         iv: row.iv,
         authTag: row.auth_tag,
         createdAt: new Date(row.created_at),
         updatedAt: new Date(row.updated_at),
-        expiresAt: row.expires_at ? new Date(row.expires_at) : undefined,
     };
 }
 /** Convert metadata row to metadata */
 function rowToMetadata(row) {
     return {
-        agent: row.agent,
         name: row.name,
-        type: parseCredentialType(row.type),
-        provider: row.provider ?? undefined,
         createdAt: new Date(row.created_at),
         updatedAt: new Date(row.updated_at),
-        expiresAt: row.expires_at ? new Date(row.expires_at) : undefined,
     };
 }
 export { rowToMetadata, rowToRecord };

package/dist/db/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Database row types and conversion utilities.
+ * Database row types.
  */
 /** Raw API key row from database */
 export interface ApiKeyRow {
@@ -19,32 +19,23 @@ export interface AuditLogRow {
     timestamp: number;
     api_key_id: string | null;
     action: string;
-    agent: string | null;
-    name: string | null;
+    credential_name: string | null;
     success: number;
     error_message: string | null;
 }
-/** Raw credential row from database */
+/** Raw credential row from database (opaque blob storage) */
 export interface CredentialRow {
-    agent: string;
     name: string;
-    type: string;
-    provider: string | null;
     encrypted_data: Buffer;
     salt: Buffer;
     iv: Buffer;
     auth_tag: Buffer;
     created_at: number;
     updated_at: number;
-    expires_at: number | null;
 }
 /** Raw credential metadata row from database */
 export interface MetadataRow {
-    agent: string;
     name: string;
-    type: string;
-    provider: string | null;
     created_at: number;
     updated_at: number;
-    expires_at: number | null;
 }

package/dist/db/types.js

@@ -1,4 +1,4 @@
 /**
- * Database row types and conversion utilities.
+ * Database row types.
  */
 export {};

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

@@ -1,11 +1,10 @@
 /**
- * DELETE /api/v1/credentials/:agent/:name handler.
+ * DELETE /api/v1/credentials/:name handler.
  */
 import type { RequestHandler } from "express";
 import type Database from "better-sqlite3";
-/** Handler type for credential routes with agent/name params */
+/** Handler type for credential routes with name param */
 type CredentialHandler = RequestHandler<{
-    agent: string;
     name: string;
 }, unknown, unknown, unknown>;
 /**

package/dist/handlers/delete-credential.js

@@ -1,5 +1,5 @@
 /**
- * DELETE /api/v1/credentials/:agent/:name handler.
+ * DELETE /api/v1/credentials/:name handler.
  */
 import { hasWriteAccess } from "../db/repositories/api-keys.js";
 import { deleteCredential } from "../db/repositories/credentials.js";
@@ -10,27 +10,25 @@ import { logAccess } from "../db/repositories/audit-log.js";
 function createDeleteCredentialHandler(database) {
     return (request, response) => {
         const authenticatedRequest = request;
-        const { agent, name } = request.params;
+        const { name } = request.params;
         const { apiKey } = authenticatedRequest;
-        if (!hasWriteAccess(apiKey, agent, name)) {
+        if (!hasWriteAccess(apiKey, name)) {
             logAccess(database, {
                 apiKeyId: apiKey.id,
                 action: "delete",
-                agent,
-                name,
+                credentialName: name,
                 success: false,
                 errorMessage: "Access denied",
             });
             response.status(403).json({ error: "Access denied" });
             return;
         }
-        const deleted = deleteCredential(database, agent, name);
+        const deleted = deleteCredential(database, name);
         if (!deleted) {
             logAccess(database, {
                 apiKeyId: apiKey.id,
                 action: "delete",
-                agent,
-                name,
+                credentialName: name,
                 success: false,
                 errorMessage: "Not found",
             });
@@ -40,11 +38,10 @@ function createDeleteCredentialHandler(database) {
         logAccess(database, {
             apiKeyId: apiKey.id,
             action: "delete",
-            agent,
-            name,
+            credentialName: name,
             success: true,
         });
-        response.json({ message: "Credential deleted", agent, name });
+        response.status(204).end();
     };
 }
 export { createDeleteCredentialHandler };

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

@@ -1,5 +1,9 @@
 /**
- * GET /api/v1/credentials/:agent/:name handler.
+ * GET /api/v1/credentials/:name handler.
+ *
+ * Fully opaque: The stored blob is decrypted and returned as-is. axvault does
+ * not inspect the blob's structure - all introspection (refresh checks, expiry
+ * detection) is delegated to axauth functions that accept opaque blobs.
  */
 import type { Request, Response } from "express";
 import type Database from "better-sqlite3";
@@ -9,12 +13,11 @@ interface GetCredentialConfig {
     refreshTimeoutMs: number;
 }
 /**
- * Retrieve a credential by agent and name.
+ * Retrieve a credential by name.
  *
  * Automatically refreshes credentials that are near expiration.
  */
 declare function createGetCredentialHandler(database: Database.Database, config: GetCredentialConfig): (request: Request<{
-    agent: string;
     name: string;
 }>, response: Response) => Promise<void>;
 export { createGetCredentialHandler };

package/dist/handlers/get-credential.js

@@ -1,29 +1,31 @@
 /**
- * GET /api/v1/credentials/:agent/:name handler.
+ * GET /api/v1/credentials/:name handler.
+ *
+ * Fully opaque: The stored blob is decrypted and returned as-is. axvault does
+ * not inspect the blob's structure - all introspection (refresh checks, expiry
+ * detection) is delegated to axauth functions that accept opaque blobs.
  */
-import { isRefreshableCredentialType } from "axshared";
 import { hasReadAccess } from "../db/repositories/api-keys.js";
 import { getCredential } from "../db/repositories/credentials.js";
 import { logAccess } from "../db/repositories/audit-log.js";
 import { decryptCredential } from "../lib/encryption.js";
-import { isRefreshable, needsRefresh, refreshWithMutex, } from "../refresh/refresh-manager.js";
+import { refreshCredentialOnRead } from "./refresh-credential-on-read.js";
 /**
- * Retrieve a credential by agent and name.
+ * Retrieve a credential by name.
  *
  * Automatically refreshes credentials that are near expiration.
  */
 function createGetCredentialHandler(database, config) {
     return async (request, response) => {
         const authenticatedRequest = request;
-        const { agent, name } = request.params;
+        const { name } = request.params;
         const { apiKey } = authenticatedRequest;
         // Access control check
-        if (!hasReadAccess(apiKey, agent, name)) {
+        if (!hasReadAccess(apiKey, name)) {
             logAccess(database, {
                 apiKeyId: apiKey.id,
                 action: "read",
-                agent,
-                name,
+                credentialName: name,
                 success: false,
                 errorMessage: "Access denied",
             });
@@ -31,98 +33,57 @@ function createGetCredentialHandler(database, config) {
             return;
         }
         // Fetch credential from database
-        const credential = getCredential(database, agent, name);
+        const credential = getCredential(database, name);
         if (!credential) {
             logAccess(database, {
                 apiKeyId: apiKey.id,
                 action: "read",
-                agent,
-                name,
+                credentialName: name,
                 success: false,
                 errorMessage: "Not found",
             });
             response.status(404).json({ error: "Credential not found" });
             return;
         }
-        // Decrypt credential data
-        let data;
+        // Decrypt credential blob (opaque - we don't inspect its structure)
+        let blob;
         try {
-            data = decryptCredential(credential);
+            blob = decryptCredential(credential);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             logAccess(database, {
                 apiKeyId: apiKey.id,
                 action: "read",
-                agent,
-                name,
+                credentialName: name,
                 success: false,
                 errorMessage: `Decryption failed: ${message}`,
             });
             response.status(500).json({ error: "Failed to decrypt credential" });
             return;
         }
-        // Check if refresh is needed (isRefreshable is a type guard)
-        // When refreshThresholdSeconds is 0, auto-refresh is disabled
-        let finalData = data;
-        let finalExpiresAt = credential.expiresAt;
-        let finalUpdatedAt = credential.updatedAt;
-        let wasRefreshed = false;
-        let refreshFailed = false;
-        if (config.refreshThresholdSeconds > 0 &&
-            isRefreshableCredentialType(credential.type) &&
-            isRefreshable(data) &&
-            needsRefresh(data, config.refreshThresholdSeconds)) {
-            try {
-                const refreshResult = await refreshWithMutex(database, agent, name, credential.type, credential.provider, data, apiKey.id, credential.updatedAt, { timeoutMs: config.refreshTimeoutMs });
-                if (refreshResult.ok) {
-                    finalData = refreshResult.data;
-                    finalExpiresAt = refreshResult.expiresAt;
-                    finalUpdatedAt = refreshResult.updatedAt;
-                    wasRefreshed = true;
-                }
-                else {
-                    // Refresh failed - re-fetch to check if credential was deleted/modified
-                    const currentCredential = getCredential(database, agent, name);
-                    if (!currentCredential) {
-                        // Credential was deleted during refresh - don't leak old data
-                        logAccess(database, {
-                            apiKeyId: apiKey.id,
-                            action: "read",
-                            agent,
-                            name,
-                            success: false,
-                            errorMessage: "Credential deleted during refresh",
-                        });
-                        response.status(404).json({ error: "Credential not found" });
-                        return;
-                    }
-                    if (currentCredential.updatedAt.getTime() !==
-                        credential.updatedAt.getTime()) {
-                        // Credential was modified during refresh - return fresh data
-                        const freshData = decryptCredential(currentCredential);
-                        finalData = freshData;
-                        finalExpiresAt = currentCredential.expiresAt;
-                        finalUpdatedAt = currentCredential.updatedAt;
-                    }
-                    // Otherwise credential unchanged, return original with warning
-                    refreshFailed = true;
-                }
-            }
-            catch (error) {
-                // Programming error safety net - refreshWithMutex handles all expected
-                // errors internally and returns { ok: false }. This catch is for bugs
-                // in our code, not provider errors. Only log message, not stack/object.
-                console.error(`Unexpected refresh error for ${agent}/${name}:`, error instanceof Error ? error.message : error);
-                refreshFailed = true;
-            }
+        const refreshResult = await refreshCredentialOnRead({
+            database,
+            apiKeyId: apiKey.id,
+            name,
+            blob,
+            expectedUpdatedAt: credential.updatedAt,
+            refreshThresholdSeconds: config.refreshThresholdSeconds,
+            refreshTimeoutMs: config.refreshTimeoutMs,
+        });
+        if (refreshResult.status === "not-found") {
+            response.status(404).json({ error: "Credential not found" });
+            return;
         }
+        const finalBlob = refreshResult.blob;
+        const finalUpdatedAt = refreshResult.updatedAt;
+        const wasRefreshed = refreshResult.wasRefreshed;
+        const refreshFailed = refreshResult.refreshFailed;
         // Log successful read
         logAccess(database, {
             apiKeyId: apiKey.id,
             action: "read",
-            agent,
-            name,
+            credentialName: name,
             success: true,
         });
         // Set refresh header if token was refreshed
@@ -130,17 +91,13 @@ function createGetCredentialHandler(database, config) {
             response.setHeader("X-Axvault-Refreshed", "true");
         }
         // Set warning header if refresh failed (still return 200 with stale data)
-        // Error details are logged to audit log; header is boolean to avoid invalid chars
         if (refreshFailed) {
             response.setHeader("X-Axvault-Refresh-Failed", "true");
         }
+        // Return the blob as-is (opaque to axvault)
         response.json({
-            agent,
             name,
-            type: credential.type,
-            ...(credential.provider && { provider: credential.provider }),
-            data: finalData,
-            expiresAt: finalExpiresAt?.toISOString(),
+            credential: finalBlob,
             updatedAt: finalUpdatedAt.toISOString(),
         });
     };

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

@@ -1,12 +1,28 @@
 /**
  * GET /api/v1/credentials handler.
+ *
+ * Lists all credentials accessible by the API key (metadata only).
+ * With opaque schema, only name and timestamps are available without decrypting.
+ *
+ * Supports opt-in cursor-based pagination via `limit` and `cursor` query
+ * parameters. Without `limit`, all accessible credentials are returned
+ * (backward-compatible with pre-pagination behavior).
  */
 import type { RequestHandler } from "express";
 import type Database from "better-sqlite3";
-/** Handler type for list route (no params) */
-type ListHandler = RequestHandler<Record<string, never>, unknown, unknown, unknown>;
+/** Handler type for list route with pagination query params */
+type ListHandler = RequestHandler<Record<string, never>, unknown, unknown, {
+    limit?: string;
+    cursor?: string;
+}>;
 /**
- * List all credentials accessible by the API key (metadata only).
+ * List credentials accessible by the API key (metadata only).
+ *
+ * Query parameters:
+ * - `limit` — Results per page (1–1000). Omit for all results.
+ * - `cursor` — Name of the last credential from the previous page (requires `limit`)
+ *
+ * Returns `nextCursor` when more results are available.
  */
 declare function createListCredentialsHandler(database: Database.Database): ListHandler;
 export { createListCredentialsHandler };

package/dist/handlers/list-credentials.js

@@ -1,30 +1,105 @@
 /**
  * GET /api/v1/credentials handler.
+ *
+ * Lists all credentials accessible by the API key (metadata only).
+ * With opaque schema, only name and timestamps are available without decrypting.
+ *
+ * Supports opt-in cursor-based pagination via `limit` and `cursor` query
+ * parameters. Without `limit`, all accessible credentials are returned
+ * (backward-compatible with pre-pagination behavior).
  */
-import { listCredentialsForApiKey } from "../db/repositories/credentials.js";
+import { listCredentialsForApiKey, listCredentialsPaginated, } from "../db/repositories/credentials.js";
 import { logAccess } from "../db/repositories/audit-log.js";
+/** Maximum page size when limit is specified */
+const MAX_LIMIT = 1000;
 /**
- * List all credentials accessible by the API key (metadata only).
+ * List credentials accessible by the API key (metadata only).
+ *
+ * Query parameters:
+ * - `limit` — Results per page (1–1000). Omit for all results.
+ * - `cursor` — Name of the last credential from the previous page (requires `limit`)
+ *
+ * Returns `nextCursor` when more results are available.
  */
 function createListCredentialsHandler(database) {
     return (request, response) => {
         const authenticatedRequest = request;
         const { apiKey } = authenticatedRequest;
-        const credentials = listCredentialsForApiKey(database, apiKey.readAccess);
+        const rawLimit = request.query.limit;
+        const rawCursor = request.query.cursor;
+        // Validate query param types (repeated params produce arrays)
+        if ((rawLimit !== undefined && typeof rawLimit !== "string") ||
+            (rawCursor !== undefined && typeof rawCursor !== "string")) {
+            logAccess(database, {
+                apiKeyId: apiKey.id,
+                action: "list",
+                success: false,
+                errorMessage: "Repeated query parameters",
+            });
+            response
+                .status(400)
+                .json({ error: "Repeated query parameters are not supported" });
+            return;
+        }
+        // cursor without limit is invalid — pagination requires an explicit page size
+        if (rawCursor && rawLimit === undefined) {
+            logAccess(database, {
+                apiKeyId: apiKey.id,
+                action: "list",
+                success: false,
+                errorMessage: "cursor requires limit",
+            });
+            response.status(400).json({ error: "cursor requires limit" });
+            return;
+        }
+        // No limit specified: return all accessible credentials (backward-compatible)
+        if (rawLimit === undefined) {
+            const credentials = listCredentialsForApiKey(database, apiKey.readAccess);
+            logAccess(database, {
+                apiKeyId: apiKey.id,
+                action: "list",
+                success: true,
+            });
+            response.json({
+                credentials: credentials.map((cred) => ({
+                    name: cred.name,
+                    createdAt: cred.createdAt.toISOString(),
+                    updatedAt: cred.updatedAt.toISOString(),
+                })),
+            });
+            return;
+        }
+        // Paginated path (rawLimit is guaranteed to be defined here)
+        const parsedLimit = Number(rawLimit);
+        if (!Number.isInteger(parsedLimit) || parsedLimit < 1) {
+            logAccess(database, {
+                apiKeyId: apiKey.id,
+                action: "list",
+                success: false,
+                errorMessage: "Invalid limit parameter",
+            });
+            response.status(400).json({ error: "limit must be a positive integer" });
+            return;
+        }
+        const limit = Math.min(parsedLimit, MAX_LIMIT);
+        const result = listCredentialsPaginated(database, apiKey.readAccess, {
+            cursor: rawCursor || undefined,
+            limit,
+        });
         logAccess(database, {
             apiKeyId: apiKey.id,
             action: "list",
             success: true,
         });
         response.json({
-            credentials: credentials.map((cred) => ({
-                agent: cred.agent,
+            credentials: result.credentials.map((cred) => ({
                 name: cred.name,
-                type: cred.type,
-                ...(cred.provider && { provider: cred.provider }),
-                expiresAt: cred.expiresAt?.toISOString(),
+                createdAt: cred.createdAt.toISOString(),
                 updatedAt: cred.updatedAt.toISOString(),
             })),
+            ...(result.nextCursor !== undefined && {
+                nextCursor: result.nextCursor,
+            }),
         });
     };
 }

package/dist/handlers/put-credential.d.ts

@@ -1,15 +1,22 @@
 /**
- * PUT /api/v1/credentials/:agent/:name handler.
+ * PUT /api/v1/credentials/:name handler.
+ *
+ * Fully opaque: The request body is treated as an opaque blob. axvault does not
+ * validate or inspect its structure - that responsibility belongs to axauth.
+ * The blob is encrypted and stored as-is.
  */
 import type { RequestHandler } from "express";
 import type Database from "better-sqlite3";
-/** Handler type for credential routes with agent/name params */
+/** Handler type for credential routes with name param */
 type CredentialHandler = RequestHandler<{
-    agent: string;
     name: string;
 }, unknown, unknown, unknown>;
 /**
  * Store or update a credential.
+ *
+ * Request body is treated as an opaque blob. axvault does not validate its
+ * structure - the client (via axauth) is responsible for providing a valid
+ * Credentials object. The blob is encrypted and stored as-is.
  */
 declare function createPutCredentialHandler(database: Database.Database): CredentialHandler;
 export { createPutCredentialHandler };