axvault 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Łukasz Jerciński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# axvault
+
+Remote credential storage server for a╳point.
+
+## Configuration
+
+### Environment Variables
+
+| Variable                     | Description                                                          | Default             |
+| ---------------------------- | -------------------------------------------------------------------- | ------------------- |
+| `AXVAULT_PORT`               | Port to listen on                                                    | `3847`              |
+| `AXVAULT_HOST`               | Host to bind to                                                      | `127.0.0.1`         |
+| `AXVAULT_DB_PATH`            | Database file path                                                   | `./data/axvault.db` |
+| `AXVAULT_ENCRYPTION_KEY`     | Encryption key (min 32 chars, required)                              | —                   |
+| `AXVAULT_REFRESH_THRESHOLD`  | Refresh credentials expiring within this many seconds (0 to disable) | `3600`              |
+| `AXVAULT_REFRESH_TIMEOUT_MS` | Timeout for refresh operations in milliseconds                       | `30000`             |
+
+### CLI Flags
+
+The `serve` command accepts flags that override environment variables:
+
+```bash
+axvault serve \
+  --port 8080 \
+  --host 0.0.0.0 \
+  --db-path /data/vault.db \
+  --refresh-threshold 7200 \
+  --refresh-timeout 60000
+```
+
+Setting `--refresh-threshold 0` disables automatic credential refresh.
+
+## API Keys
+
+API keys control access to the credential API. Each key has configurable read and write permissions.
+
+### Create an API Key
+
+```bash
+# Full access
+axvault key create --name "CI Pipeline" --read "*" --write "*"
+
+# Restricted access
+axvault key create --name "Claude Reader" --read "claude/*"
+axvault key create --name "Deploy Script" --write "claude/prod,codex/prod"
+```
+
+The command outputs metadata to stderr and the secret key to stdout for easy piping:
+
+```
+# stderr (visible in terminal):
+Created API key: CI Pipeline
+ID: k_a1b2c3d4e5f6
+Read access: *
+Write access: *
+
+Save this key securely - it cannot be retrieved later.
+
+# stdout (can be piped):
+axv_sk_0123456789abcdef0123456789abcdef
+```
+
+To copy directly to clipboard: `axvault key create --name "My Key" --read "*" | pbcopy`
+
+### List Keys
+
+```bash
+axvault key list
+```
+
+### Revoke a Key
+
+```bash
+axvault key revoke k_a1b2c3d4e5f6
+```
+
+### Container Deployments
+
+#### Running the Container
+
+The image uses an external UID pattern - no user is baked into the image. Specify the runtime user with `-u`/`--user`:
+
+```bash
+# Docker
+docker run -d \
+  --name axvault \
+  -p 3847:3847 \
+  -u 1000:1000 \
+  -e AXVAULT_ENCRYPTION_KEY="your-secret-key-minimum-32-chars!" \
+  -v /srv/axvault/data:/data \
+  ghcr.io/jercik/axvault:latest
+
+# Podman
+podman run -d \
+  --name axvault \
+  -p 3847:3847 \
+  --user 1000:1000 \
+  -e AXVAULT_ENCRYPTION_KEY="your-secret-key-minimum-32-chars!" \
+  -v /srv/axvault/data:/data:Z \
+  ghcr.io/jercik/axvault:latest
+```
+
+#### Volume Ownership
+
+The data volume must be owned by the UID/GID the container runs as:
+
+```bash
+# Create directory and set ownership before first run
+sudo mkdir -p /srv/axvault/data
+sudo chown 1000:1000 /srv/axvault/data
+```
+
+For rootless Podman, use your user's UID or let Podman handle mapping automatically.
+
+#### Quadlet (systemd)
+
+Create `/etc/containers/systemd/axvault.container`:
+
+```ini
+[Unit]
+Description=axvault credential server
+
+[Container]
+Image=ghcr.io/jercik/axvault:latest
+PublishPort=3847:3847
+User=1000
+Group=1000
+Environment=AXVAULT_ENCRYPTION_KEY=your-secret-key-minimum-32-chars!
+Volume=/srv/axvault/data:/data:Z
+
+[Service]
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then reload and start:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl start axvault
+```
+
+#### Managing Keys in Containers
+
+Exec into the container to manage API keys:
+
+```bash
+# Podman
+sudo podman exec axvault /nodejs/bin/node node_modules/axvault/bin/axvault key create --name "My Key" --write "*"
+
+# Docker
+docker exec axvault /nodejs/bin/node node_modules/axvault/bin/axvault key create --name "My Key" --write "*"
+```
+
+## Credentials API
+
+### Store a Credential
+
+```bash
+curl -X PUT https://vault.example.com/api/v1/credentials/claude/prod \
+  -H "Authorization: Bearer <api_key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": {"accessToken": "...", "refreshToken": "..."},
+    "expiresAt": "2025-12-31T23:59:59Z"
+  }'
+```
+
+### Retrieve a Credential
+
+```bash
+curl https://vault.example.com/api/v1/credentials/claude/prod \
+  -H "Authorization: Bearer <api_key>"
+```
+
+### Delete a Credential
+
+```bash
+curl -X DELETE https://vault.example.com/api/v1/credentials/claude/prod \
+  -H "Authorization: Bearer <api_key>"
+```
+
+## Auto-Refresh
+
+axvault automatically refreshes OAuth credentials that are near expiration when they are retrieved. This behavior is controlled by the refresh threshold setting.
+
+### Access Control Note
+
+Auto-refresh is a server-side maintenance operation that occurs transparently during credential retrieval. Read-only API keys can trigger refresh because:
+
+- The refresh uses the credential's own `refresh_token` (already authorized by the token owner)
+- The credential's identity and ownership remain unchanged
+- Only token values and expiry timestamps are updated
+- This prevents wasteful repeated refreshes and rate limit issues
+
+This follows the pattern used by credential vaults like HashiCorp Vault, where credential maintenance is handled transparently on reads.
+
+### Response Headers
+
+When retrieving credentials, the response may include these headers:
+
+| Header                     | Value  | Description                                                  |
+| -------------------------- | ------ | ------------------------------------------------------------ |
+| `X-Axvault-Refreshed`      | `true` | Credential was successfully refreshed during this request    |
+| `X-Axvault-Refresh-Failed` | `true` | Refresh was attempted but failed; stale credentials returned |
+
+When `X-Axvault-Refresh-Failed` is present, the response still returns HTTP 200 with the existing (potentially expired) credentials. Error details are logged to the audit log.
+
+## License
+
+MIT

package/bin/axvault

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * axvault - Remote credential storage server for axpoint.
+ *
+ * Stores agent credentials and serves them via API.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * axvault - Remote credential storage server for axpoint.
+ *
+ * Stores agent credentials and serves them via API.
+ */
+import { Command } from "@commander-js/extra-typings";
+import packageJson from "../package.json" with { type: "json" };
+import { handleCredentialDelete, handleCredentialList, } from "./commands/credential.js";
+import { handleInit } from "./commands/init.js";
+import { handleKeyCreate, handleKeyList, handleKeyRevoke, } from "./commands/key.js";
+import { handleServe } from "./commands/serve.js";
+const program = new Command()
+    .name(packageJson.name)
+    .description(packageJson.description)
+    .version(packageJson.version, "-V, --version")
+    .showHelpAfterError("(add --help for additional information)")
+    .showSuggestionAfterError()
+    .helpCommand(false)
+    .addHelpText("after", String.raw `
+Examples:
+  # Initialize database
+  axvault init
+
+  # Start server
+  axvault serve
+
+  # Start server on custom port
+  axvault serve --port 8080
+
+  # Create an API key with read access (at least one of --read/--write required)
+  axvault key create --name "CI Pipeline" --read "claude/work,codex/ci"
+
+  # Create a write-only API key
+  axvault key create --name "Uploader" --write "claude/backups"
+
+  # Create an admin API key with full access
+  axvault key create --name "Admin" --read "*" --write "*"
+
+  # List all API keys
+  axvault key list
+
+  # Revoke an API key
+  axvault key revoke k_abc123def456
+
+  # List all stored credentials
+  axvault credential list
+
+  # Delete a credential
+  axvault credential delete claude/work`);
+program
+    .command("init")
+    .description("Initialize database and configuration")
+    .option("--db-path <path>", "Database file path")
+    .action(handleInit);
+program
+    .command("serve")
+    .description("Start the vault server")
+    .option("-p, --port <port>", "Port to listen on")
+    .option("-H, --host <host>", "Host to bind to")
+    .option("--db-path <path>", "Database file path")
+    .option("--refresh-threshold <seconds>", "Refresh credentials expiring within this many seconds (0 to disable)")
+    .option("--refresh-timeout <ms>", "Timeout for refresh operations in milliseconds")
+    .action(handleServe);
+// API key management commands
+const keyCommand = program
+    .command("key")
+    .description("Manage API keys")
+    .helpCommand(false);
+keyCommand
+    .command("create")
+    .description("Create a new API key")
+    .requiredOption("-n, --name <name>", "Name for the API key")
+    .option("-r, --read <access>", "Comma-separated read access list (e.g., 'claude/work,codex/ci' or '*')")
+    .option("-w, --write <access>", "Comma-separated write access list (e.g., 'claude/ci' or '*')")
+    .option("--json", "Output as JSON")
+    .option("--db-path <path>", "Database file path")
+    .action(handleKeyCreate);
+keyCommand
+    .command("list")
+    .description("List all API keys")
+    .option("--json", "Output as JSON")
+    .option("--db-path <path>", "Database file path")
+    .action(handleKeyList);
+keyCommand
+    .command("revoke")
+    .description("Revoke an API key")
+    .argument("<id>", "API key ID (e.g., k_abc123def456)")
+    .option("--db-path <path>", "Database file path")
+    .action(handleKeyRevoke);
+// Credential management commands
+const credentialCommand = program
+    .command("credential")
+    .description("Manage stored credentials")
+    .helpCommand(false);
+credentialCommand
+    .command("list")
+    .description("List all stored credentials")
+    .option("--json", "Output as JSON")
+    .option("--db-path <path>", "Database file path")
+    .action(handleCredentialList);
+credentialCommand
+    .command("delete")
+    .description("Delete a credential")
+    .argument("<path>", "Credential path (agent/name, e.g., claude/work)")
+    .option("--db-path <path>", "Database file path")
+    .action(handleCredentialDelete);
+await program.parseAsync(process.argv);

package/dist/commands/credential.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Credential management command handlers.
+ */
+interface CredentialListOptions {
+    dbPath?: string;
+    json?: boolean;
+}
+interface CredentialDeleteOptions {
+    dbPath?: string;
+}
+export declare function handleCredentialList(options: CredentialListOptions): void;
+export declare function handleCredentialDelete(path: string, options: CredentialDeleteOptions): void;
+export {};

package/dist/commands/credential.js

@@ -0,0 +1,113 @@
+/**
+ * Credential management command handlers.
+ */
+import { getServerConfig } from "../config.js";
+import { closeDatabase, getDatabase } from "../db/client.js";
+import { runMigrations } from "../db/migrations.js";
+import { deleteCredential, listCredentials, } from "../db/repositories/credentials.js";
+import { containsControlChars, formatDateForJson, formatExpiresAt, formatRelativeTime, getErrorMessage, sanitizeForTsv, } from "../lib/format.js";
+/** Print credentials as TSV table */
+function printCredentialTable(credentials) {
+    console.log("AGENT\tNAME\tEXPIRES\tUPDATED");
+    for (const cred of credentials) {
+        const agent = sanitizeForTsv(cred.agent);
+        const name = sanitizeForTsv(cred.name);
+        const expires = formatExpiresAt(cred.expiresAt);
+        const updated = formatRelativeTime(cred.updatedAt);
+        console.log(`${agent}\t${name}\t${expires}\t${updated}`);
+    }
+}
+/**
+ * Parse credential path (agent/name).
+ *
+ * Control characters are checked BEFORE trimming to prevent silent bypass
+ * (e.g., "\nclaude/work" would otherwise become "claude/work" after trim).
+ */
+function parseCredentialPath(path) {
+    // Reject inputs containing control characters BEFORE trimming
+    if (containsControlChars(path)) {
+        return {
+            ok: false,
+            message: `Invalid credential path: contains control characters.\nExpected format: agent/name (e.g., claude/work)`,
+        };
+    }
+    const trimmed = path.trim();
+    const parts = trimmed.split("/");
+    if (parts.length !== 2) {
+        return {
+            ok: false,
+            message: `Invalid credential path: ${trimmed}\nExpected format: agent/name (e.g., claude/work)`,
+        };
+    }
+    const agent = parts[0]?.trim();
+    const name = parts[1]?.trim();
+    if (!agent || !name) {
+        return {
+            ok: false,
+            message: `Invalid credential path: ${trimmed}\nBoth agent and name are required.`,
+        };
+    }
+    return { ok: true, agent, name };
+}
+export function handleCredentialList(options) {
+    try {
+        const config = getServerConfig(options);
+        const database = getDatabase(config.databasePath);
+        runMigrations(database);
+        const credentials = listCredentials(database);
+        if (options.json) {
+            const output = credentials.map((cred) => ({
+                agent: cred.agent,
+                name: cred.name,
+                createdAt: cred.createdAt.toISOString(),
+                updatedAt: cred.updatedAt.toISOString(),
+                expiresAt: formatDateForJson(cred.expiresAt),
+            }));
+            console.log(JSON.stringify(output, undefined, 2));
+        }
+        else if (credentials.length === 0) {
+            console.error("No credentials stored.");
+            console.error("Store credentials via the API: PUT /api/v1/credentials/:agent/:name");
+        }
+        else {
+            printCredentialTable(credentials);
+        }
+    }
+    catch (error) {
+        console.error(`Error: Failed to list credentials: ${getErrorMessage(error)}`);
+        process.exitCode = 1;
+    }
+    finally {
+        closeDatabase();
+    }
+}
+export function handleCredentialDelete(path, options) {
+    // Parse credential path first (before config parsing)
+    const parsed = parseCredentialPath(path);
+    if (!parsed.ok) {
+        console.error(`Error: ${parsed.message}`);
+        process.exitCode = 2;
+        return;
+    }
+    const { agent, name } = parsed;
+    try {
+        const config = getServerConfig(options);
+        const database = getDatabase(config.databasePath);
+        runMigrations(database);
+        const deleted = deleteCredential(database, agent, name);
+        if (deleted) {
+            console.error(`Deleted credential: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);
+        }
+        else {
+            console.error(`Error: Credential not found: ${sanitizeForTsv(agent)}/${sanitizeForTsv(name)}`);
+            process.exitCode = 1;
+        }
+    }
+    catch (error) {
+        console.error(`Error: Failed to delete credential: ${getErrorMessage(error)}`);
+        process.exitCode = 1;
+    }
+    finally {
+        closeDatabase();
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Initialize database command handler.
+ */
+interface InitOptions {
+    dbPath?: string;
+}
+export declare function handleInit(options: InitOptions): void;
+export {};

package/dist/commands/init.js

@@ -0,0 +1,50 @@
+/**
+ * Initialize database command handler.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { getServerConfig } from "../config.js";
+import { closeDatabase, getDatabase } from "../db/client.js";
+import { CURRENT_VERSION, getSchemaVersion, runMigrations, } from "../db/migrations.js";
+export function handleInit(options) {
+    const config = getServerConfig(options);
+    // Ensure data directory exists
+    const dataDirectory = path.dirname(config.databasePath);
+    if (!existsSync(dataDirectory)) {
+        try {
+            mkdirSync(dataDirectory, { recursive: true });
+            console.error(`Created data directory: ${dataDirectory}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Failed to create data directory '${dataDirectory}': ${message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Initialize database
+    try {
+        const database = getDatabase(config.databasePath);
+        const versionBefore = getSchemaVersion(database);
+        runMigrations(database);
+        const versionAfter = getSchemaVersion(database);
+        if (versionBefore === 0) {
+            console.error(`Database initialized at: ${config.databasePath}`);
+            console.error(`Schema version: ${versionAfter}`);
+        }
+        else if (versionBefore < versionAfter) {
+            console.error(`Database migrated from v${versionBefore} to v${versionAfter}`);
+        }
+        else {
+            console.error(`Database already at version ${versionAfter} (current: ${CURRENT_VERSION})`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to initialize database: ${message}`);
+        process.exitCode = 1;
+    }
+    finally {
+        closeDatabase();
+    }
+}

package/dist/commands/key.d.ts

@@ -0,0 +1,21 @@
+/**
+ * API key management command handlers.
+ */
+interface KeyCreateOptions {
+    dbPath?: string;
+    name: string;
+    read?: string;
+    write?: string;
+    json?: boolean;
+}
+interface KeyListOptions {
+    dbPath?: string;
+    json?: boolean;
+}
+interface KeyRevokeOptions {
+    dbPath?: string;
+}
+export declare function handleKeyCreate(options: KeyCreateOptions): void;
+export declare function handleKeyList(options: KeyListOptions): void;
+export declare function handleKeyRevoke(id: string, options: KeyRevokeOptions): void;
+export {};