axvault 1.0.0

package/dist/refresh/refresh-manager.js

@@ -0,0 +1,132 @@
+/**
+ * Refresh manager with per-credential mutex locking.
+ *
+ * Prevents concurrent refreshes of the same credential and coordinates
+ * with axauth's refresh functionality.
+ */
+import { refreshCredentials } from "axauth";
+import { getCredential, upsertCredential, } from "../db/repositories/credentials.js";
+import { encryptCredential } from "../lib/encryption.js";
+import { extractExpiryDate, toAxauthCredentials } from "./check-refresh.js";
+import { getErrorMessage, logRefreshError, logRefreshSuccess, } from "./log-refresh.js";
+/** Map of in-progress refreshes to prevent concurrent operations */
+const pendingRefreshes = new Map();
+/** Build credential key for mutex */
+function buildKey(agent, name) {
+    return `${agent}/${name}`;
+}
+/**
+ * Execute the full refresh operation: call axauth, validate, persist.
+ * This is the inner operation that gets stored in the mutex.
+ */
+async function executeRefresh(database, agent, name, data, apiKeyId, originalUpdatedAt, refreshStartedAt, options) {
+    const logContext = { database, apiKeyId, agent, name };
+    // Map to axauth format
+    const creds = toAxauthCredentials(agent, data);
+    if (!creds) {
+        return { ok: false, error: `Unknown agent: ${agent}` };
+    }
+    try {
+        const result = await refreshCredentials(creds, {
+            timeout: options.timeoutMs,
+        });
+        if (!result.ok) {
+            logRefreshError(logContext, result.error);
+            return { ok: false, error: result.error };
+        }
+        // Check if credential still exists and wasn't modified during refresh
+        const existingCredential = getCredential(database, agent, name);
+        if (!existingCredential) {
+            logRefreshError(logContext, "Credential was deleted during refresh");
+            return { ok: false, error: "Credential was deleted during refresh" };
+        }
+        // Optimistic locking: abort if credential was modified during refresh
+        if (existingCredential.updatedAt.getTime() !== originalUpdatedAt.getTime()) {
+            logRefreshError(logContext, "Credential was modified during refresh");
+            return { ok: false, error: "Credential was modified during refresh" };
+        }
+        // Persist newly refreshed credentials to database
+        // Merge original data with refreshed data to preserve fields like refresh_token
+        const newData = { ...data, ...result.credentials.data };
+        const encrypted = encryptCredential(newData);
+        const expiresAt = extractExpiryDate(newData);
+        try {
+            upsertCredential(database, {
+                agent,
+                name,
+                ...encrypted,
+                expiresAt,
+            });
+            logRefreshSuccess(logContext);
+            return {
+                ok: true,
+                data: newData,
+                expiresAt,
+                updatedAt: refreshStartedAt,
+            };
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            logRefreshError(logContext, `Persistence failed: ${message}`);
+            return {
+                ok: false,
+                error: `Failed to persist refreshed credentials: ${message}`,
+            };
+        }
+    }
+    catch (error) {
+        // Handle unexpected errors (e.g., refreshCredentials promise rejection)
+        const message = getErrorMessage(error);
+        logRefreshError(logContext, `Refresh error: ${message}`);
+        return { ok: false, error: `Refresh failed: ${message}` };
+    }
+}
+/**
+ * Perform refresh with mutex locking.
+ *
+ * If a refresh is already in progress for this credential, waits for it
+ * rather than starting a new one. The mutex covers the FULL operation
+ * (refresh + validate + persist), ensuring all callers see the same result.
+ *
+ * Note: There is a small race window where a request that loaded stale
+ * credential data could start a duplicate refresh if it checks the mutex
+ * right after the previous refresh completes. This is rare (requires precise
+ * timing), harmless (produces correct results), and self-limiting (OAuth
+ * providers handle duplicate refreshes). The complexity of cooldown timers
+ * or reference counting isn't justified for this edge case.
+ *
+ * @param database - Database connection
+ * @param agent - Agent name
+ * @param name - Credential name
+ * @param data - Current decrypted credential data
+ * @param apiKeyId - API key ID for audit logging
+ * @param originalUpdatedAt - Original updatedAt for optimistic locking
+ * @param options - Refresh options
+ * @returns Refresh result with new data, expiresAt, updatedAt or error
+ */
+async function refreshWithMutex(database, agent, name, data, apiKeyId, originalUpdatedAt, options) {
+    const key = buildKey(agent, name);
+    // Check if refresh already in progress
+    const existing = pendingRefreshes.get(key);
+    if (existing) {
+        // Wait for existing FULL operation to complete
+        // All callers observe the same final success/failure result
+        return existing.promise;
+    }
+    // Start new refresh - store promise for the FULL operation
+    const refreshStartedAt = new Date();
+    const fullOperationPromise = executeRefresh(database, agent, name, data, apiKeyId, originalUpdatedAt, refreshStartedAt, options);
+    pendingRefreshes.set(key, {
+        promise: fullOperationPromise,
+        startedAt: refreshStartedAt,
+    });
+    try {
+        return await fullOperationPromise;
+    }
+    finally {
+        // Always clean up mutex
+        pendingRefreshes.delete(key);
+    }
+}
+export { extractExpiryDate, isRefreshable, needsRefresh, toAxauthCredentials, } from "./check-refresh.js";
+export { buildKey, refreshWithMutex };

package/dist/server/routes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * API route definitions using Express Router.
+ */
+import type Database from "better-sqlite3";
+import { Router } from "express";
+import { type GetCredentialConfig } from "../handlers/get-credential.js";
+/** Create health check router (no auth required) */
+export declare function createHealthRouter(): Router;
+/** Create credential API router (auth required) */
+export declare function createCredentialRouter(database: Database.Database, config: GetCredentialConfig): Router;
+/** Create all API routers (legacy compatibility) */
+export declare function createApiRouter(): Router;

package/dist/server/routes.js

@@ -0,0 +1,44 @@
+/**
+ * API route definitions using Express Router.
+ */
+import { Router } from "express";
+import packageJson from "../../package.json" with { type: "json" };
+import { createDeleteCredentialHandler } from "../handlers/delete-credential.js";
+import { createGetCredentialHandler, } from "../handlers/get-credential.js";
+import { createListCredentialsHandler } from "../handlers/list-credentials.js";
+import { createPutCredentialHandler } from "../handlers/put-credential.js";
+import { createAuthMiddleware } from "../middleware/auth.js";
+import { validateParameters } from "../middleware/validate-parameters.js";
+/** Create health check router (no auth required) */
+export function createHealthRouter() {
+    const router = Router();
+    router.get("/api/v1/health", (_request, response) => {
+        response.json({
+            status: "ok",
+            version: packageJson.version,
+        });
+    });
+    return router;
+}
+/** Create credential API router (auth required) */
+export function createCredentialRouter(database, config) {
+    const router = Router();
+    const authMiddleware = createAuthMiddleware(database);
+    // All credential routes require authentication
+    router.use("/api/v1/credentials", authMiddleware);
+    // List all accessible credentials
+    router.get("/api/v1/credentials", createListCredentialsHandler(database));
+    // Get a specific credential (with automatic refresh)
+    router.get("/api/v1/credentials/:agent/:name", validateParameters, createGetCredentialHandler(database, config));
+    // Store/update a credential
+    router.put("/api/v1/credentials/:agent/:name", validateParameters, createPutCredentialHandler(database));
+    // Delete a credential
+    router.delete("/api/v1/credentials/:agent/:name", validateParameters, createDeleteCredentialHandler(database));
+    return router;
+}
+/** Create all API routers (legacy compatibility) */
+export function createApiRouter() {
+    // For backward compatibility, returns just health router
+    // Use createHealthRouter() and createCredentialRouter(db, config) directly for full API
+    return createHealthRouter();
+}

package/dist/server/server.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Express HTTP server for axvault API.
+ *
+ * Designed for both CLI and library usage via factory pattern.
+ */
+import { type Express, type Router } from "express";
+import type { ServerConfig } from "../config.js";
+/** Server instance with lifecycle methods */
+export interface AxvaultServer {
+    /** The Express application instance */
+    readonly app: Express;
+    /** Start listening on the configured host:port */
+    start(): Promise<void>;
+    /** Stop the server gracefully */
+    stop(): Promise<void>;
+}
+/** Create an axvault server instance */
+export declare function createServer(config: ServerConfig, routers: Router[]): AxvaultServer;

package/dist/server/server.js

@@ -0,0 +1,106 @@
+/**
+ * Express HTTP server for axvault API.
+ *
+ * Designed for both CLI and library usage via factory pattern.
+ */
+import express, {} from "express";
+/** Create and configure Express application */
+function createApp(routers) {
+    const app = express();
+    // Security: disable X-Powered-By header
+    app.disable("x-powered-by");
+    // JSON body parsing middleware with size limit
+    app.use(express.json({ limit: "1mb" }));
+    // Register all routers
+    for (const router of routers) {
+        app.use(router);
+    }
+    // 404 handler for unmatched routes
+    app.use((_request, response) => {
+        response.status(404).json({ error: "Not found" });
+    });
+    // Error handling middleware - must be last and have 4 parameters
+    app.use((error, _request, response, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- Express requires 4 params
+    _next) => {
+        // Don't double-respond if headers already sent
+        if (response.headersSent) {
+            return;
+        }
+        // Handle JSON parse errors
+        if (error instanceof SyntaxError && "body" in error) {
+            response.status(400).json({ error: "Invalid JSON" });
+            return;
+        }
+        // Extract status from middleware errors (e.g., body-parser 413)
+        // Guard against null/primitive errors
+        const isErrorObject = error !== null && typeof error === "object";
+        const errorWithStatus = error;
+        const status = isErrorObject
+            ? (errorWithStatus.status ?? errorWithStatus.statusCode ?? 500)
+            : 500;
+        // Log server errors
+        if (status >= 500) {
+            console.error("Server error:", error);
+        }
+        // Use generic message for 5xx, actual message for 4xx
+        const message = status >= 500
+            ? "Internal server error"
+            : ((isErrorObject ? errorWithStatus.message : undefined) ??
+                "Request error");
+        response.status(status).json({ error: message });
+    });
+    return app;
+}
+/** Create an axvault server instance */
+export function createServer(config, routers) {
+    const app = createApp(routers);
+    let server;
+    let stopPromise;
+    return {
+        app,
+        start() {
+            // Reset state for restart support
+            stopPromise = undefined;
+            return new Promise((resolve, reject) => {
+                // Startup error handler - removed after successful listen
+                const onStartupError = (error) => {
+                    reject(error);
+                };
+                server = app.listen(config.port, config.host, () => {
+                    server?.removeListener("error", onStartupError);
+                    // Add persistent error handler only after startup succeeds
+                    server?.on("error", (error) => {
+                        console.error("Server error:", error);
+                    });
+                    console.error(`axvault listening on http://${config.host}:${config.port}`);
+                    resolve();
+                });
+                server.once("error", onStartupError);
+            });
+        },
+        stop() {
+            // Return memoized promise for idempotency
+            if (stopPromise) {
+                return stopPromise;
+            }
+            if (!server) {
+                return Promise.resolve();
+            }
+            // Capture reference before async operation
+            const serverToClose = server;
+            server = undefined;
+            stopPromise = new Promise((resolve, reject) => {
+                serverToClose.close((error) => {
+                    if (error) {
+                        reject(error);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            });
+            return stopPromise;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "axvault",
+  "author": "Łukasz Jerciński",
+  "license": "MIT",
+  "version": "1.0.0",
+  "description": "Remote credential storage server for axpoint",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jercik/axvault.git"
+  },
+  "homepage": "https://github.com/Jercik/axvault#readme",
+  "bugs": {
+    "url": "https://github.com/Jercik/axvault/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "axvault": "bin/axvault"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepare": "git config core.hooksPath .githooks",
+    "prepublishOnly": "pnpm run rebuild",
+    "build": "tsc -p tsconfig.app.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "fta": "fta-check",
+    "knip": "knip",
+    "lint": "eslint",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "start": "pnpm -s run rebuild && node bin/axvault",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc -b --noEmit"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "^14.0.0",
+    "axauth": "^1.7.2",
+    "axshared": "^1.8.0",
+    "better-sqlite3": "^12.5.0",
+    "commander": "^14.0.2",
+    "express": "^5.2.1"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "auth",
+    "authentication",
+    "credentials",
+    "claude-code",
+    "codex",
+    "gemini",
+    "opencode",
+    "llm",
+    "automation",
+    "coding-assistant"
+  ],
+  "packageManager": "pnpm@10.27.0",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "devDependencies": {
+    "@total-typescript/ts-reset": "^0.6.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.39.2",
+    "eslint-config-axpoint": "^1.0.0",
+    "fta-check": "^1.5.1",
+    "fta-cli": "^3.0.0",
+    "knip": "^5.80.0",
+    "prettier": "3.7.4",
+    "semantic-release": "^25.0.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}