axvault 1.8.2 → 1.9.0

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/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/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-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-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/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.0",
   "description": "Remote credential storage server for axkit",
   "repository": {
     "type": "git",