axvault 1.12.0 → 1.13.0

package/README.md

@@ -7,7 +7,7 @@ Remote credential storage server for a╳kit.
 - Node.js 22.19+
 - PostgreSQL 14+ (local install or via Docker: `docker run -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:17-alpine`)
 - `pnpm` (for `pnpm dlx axvault`) or `npx` (for `npx -y axvault`)
-- `jq` for scripting against `--json` output
+- `jq` for scripting against JSON API responses
 
 If `axvault` is not installed globally, prefix commands with `npx -y axvault` (or `pnpm dlx axvault`).
 
@@ -29,53 +29,29 @@ set -a
 . ./.env
 set +a
 
-# Initialize database and start server
-npx -y axvault init
+# Start server (runs migrations and creates bootstrap admin key on first startup)
 npx -y axvault serve
 ```
 
-Keep the `.env` file and reuse the same key between restarts to avoid losing access to existing credentials.
+On first startup, axvault runs database migrations and creates a bootstrap admin API key with full access. The secret is printed to stderr — **save it immediately**, it cannot be retrieved later.
 
-In a new shell, you must re-export the variables from `.env` before running `axvault` commands (the server does not load `.env` automatically).
+Keep the `.env` file and reuse the same encryption key between restarts to avoid losing access to existing credentials.
 
-In another shell, create an API key:
+## Architecture
 
-```bash
-npx -y axvault key create --name "Admin" --read "*" --write "*" --grant "*"
-```
-
-Add `--verbose` to commands like `init`, `serve`, `key revoke`, `key update`, and
-`credential delete` to see status output.
-
-## Output formats
+axvault is a server-only tool. The CLI has a single command (`serve`) that starts the HTTP server. All key and credential management is done through the HTTP API.
 
-List commands output TSV by default. Use `--json` on `key create`, `key list`,
-`key update`, and `credential list` for structured output (note: `key create
---json` includes the secret key).
-
-```bash
-npx -y axvault key list --json | jq -r '.[].id'
-```
+On startup, the server:
 
-## Pipeline examples
+1. Runs database migrations (idempotent, so they are safe to re-run on every startup)
+2. Creates a bootstrap admin API key if no keys exist (serialized with an advisory lock, prints secret to stderr)
+3. Starts listening for HTTP requests
 
-### Extract key IDs
-
-```bash
-npx -y axvault key list | tail -n +2 | cut -f1
-```
-
-### Count credentials by creation date
-
-```bash
-npx -y axvault credential list --json | jq -r '.[].createdAt | split("T")[0]' | sort | uniq -c | sort -rn
-```
-
-### List credential names in the `claude` namespace
-
-```bash
-npx -y axvault credential list | tail -n +2 | awk -F'\t' '$1 ~ /^claude\./ {print $1}'
-```
+Migration files must remain replay-safe because axvault re-runs them on every
+startup instead of tracking applied versions. Use guarded SQL such as
+`CREATE ... IF NOT EXISTS` or `ALTER ... ADD COLUMN IF NOT EXISTS`. If a future
+schema change cannot be written safely that way, switch back to tracked
+migrations rather than adding a one-shot file to this runner.
 
 ## Agent Rule
 
@@ -86,9 +62,9 @@ Add to your `CLAUDE.md` or `AGENTS.md`:
 
 Run `npx -y axvault --help` to learn available options.
 
-Use `axvault` when you need to initialize the vault database, manage API keys,
-or list/delete stored credentials. List commands output TSV by default; add
-`--json` for structured output you can pipe into `jq`.
+Use `axvault serve` to start the credential vault server. All key and credential
+management is done via the HTTP API. On first startup, a bootstrap admin API key
+is created and printed to stderr.
 ```
 
 ## Configuration
@@ -121,86 +97,60 @@ npx -y axvault serve \
 
 Setting `--refresh-threshold 0` disables automatic credential refresh.
 
-## Confirmation flags
-
-Destructive commands require confirmation: `axvault key revoke` and `axvault
-credential delete` require `--force` (alias `--yes`).
-
 ## API Keys
 
 API keys control access to the credential API. Each key has configurable permissions:
 
 - **Read**: retrieve credentials
 - **Write**: store and delete credentials
-- **Grant**: delegate access to other keys (enforcement coming in future release)
-
-### Create an API Key
-
-```bash
-# Full access (read, write, and grant)
-npx -y axvault key create --name "Admin" --read "*" --write "*" --grant "*"
+- **Grant**: manage other API keys
 
-# Read/write access only
-npx -y axvault key create --name "CI Pipeline" --read "*" --write "*"
+### Bootstrap Key
 
-# Restricted access
-npx -y axvault key create --name "Claude Reader" --read "claude.work,claude.ci"
-npx -y axvault key create --name "Deploy Script" --write "claude.prod,codex.prod"
+On first startup (when no keys exist), axvault creates a "Bootstrap Admin" key with full access (`*` for read, write, and grant). The secret is printed to stderr.
 
-# Grant-only key (for delegation, does not allow direct read/write)
-npx -y axvault key create --name "Issuer" --grant "claude.work,claude.ci"
-```
+### Managing Keys via API
 
-The command outputs metadata to stderr and the secret key to stdout for easy piping:
+All key management is done through the HTTP API:
 
-```
-# stderr (visible in terminal):
-Created API key: CI Pipeline
-ID: k_a1b2c3d4e5f6
-Read access: *
-Write access: *
-Grant access: (none)
-
-Save this key securely - it cannot be retrieved later.
-
-# stdout (can be piped):
-axv_sk_0123456789abcdef0123456789abcdef
-```
-
-To copy directly to clipboard: `npx -y axvault key create --name "My Key" --read "*" | pbcopy`
-
-### List Keys
-
-```bash
-npx -y axvault key list
-```
-
-### Update a Key
-
-Modify an existing key's permissions:
+- `POST /api/v1/keys` accepts either a bootstrap/admin key or a scoped grant
+  key, as long as every requested read/write/grant entry stays within the
+  caller's `grantAccess` list.
+- `PATCH /api/v1/keys/:id` only works when the target key's current and resulting
+  permissions both stay within the caller's `grantAccess` list. In practice,
+  scoped grant keys can only update keys that are already fully inside their
+  scope.
+- `GET /api/v1/keys`, `GET /api/v1/keys/:id`, and `DELETE /api/v1/keys/:id`
+  require full grant access (`grantAccess: ["*"]`).
 
 ```bash
-# Add read access for new credentials
-npx -y axvault key update k_a1b2c3d4e5f6 --add-read "gemini.prod"
+API_KEY="axv_sk_..."  # Bootstrap/admin key with grantAccess ["*"]
 
-# Remove write access
-npx -y axvault key update k_a1b2c3d4e5f6 --remove-write "claude.test"
+# Create a new key
+curl -X POST https://vault.example.com/api/v1/keys \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "CI Pipeline", "readAccess": ["*"], "writeAccess": ["*"], "grantAccess": []}'
 
-# Add grant permissions
-npx -y axvault key update k_a1b2c3d4e5f6 --add-grant "claude.work"
+# List all keys
+curl https://vault.example.com/api/v1/keys \
+  -H "Authorization: Bearer $API_KEY"
 
-# Multiple changes at once
-npx -y axvault key update k_a1b2c3d4e5f6 --add-read "codex.ci" --remove-write "claude.dev"
-```
+# Get a single key
+curl https://vault.example.com/api/v1/keys/k_a1b2c3d4e5f6 \
+  -H "Authorization: Bearer $API_KEY"
 
-### Revoke a Key
+# Update key permissions
+curl -X PATCH https://vault.example.com/api/v1/keys/k_a1b2c3d4e5f6 \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"readAccess": ["claude.work", "codex.ci"]}'
 
-```bash
-npx -y axvault key revoke k_a1b2c3d4e5f6 --force
+# Revoke a key
+curl -X DELETE https://vault.example.com/api/v1/keys/k_a1b2c3d4e5f6 \
+  -H "Authorization: Bearer $API_KEY"
 ```
 
-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). To rebuild manually, run `workflow_dispatch` on `publish-image` and provide the required `version` input (for example `1.7.0`).
@@ -233,6 +183,8 @@ podman run -d \
 
 **Note:** `AXVAULT_DATABASE_URL` must point to an accessible PostgreSQL instance. The Containerfile default (`postgresql://localhost:5432/axvault`) refers to the container itself, so standalone `docker run` users must provide this variable. For a batteries-included setup, use `docker-compose.yml` which includes a PostgreSQL service.
 
+The bootstrap admin key is created on first startup and printed to the container logs. Retrieve it with `docker logs axvault` or `podman logs axvault`.
+
 #### Quadlet (systemd)
 
 This example references `axvault-db.service`, which is a PostgreSQL container you must provide separately as a companion Quadlet (`axvault-db.container`). Alternatively, point `AXVAULT_DATABASE_URL` at an existing PostgreSQL instance and remove the `Requires`/`After` lines.
@@ -267,18 +219,6 @@ 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 node /app/node_modules/axvault/bin/axvault key create --name "My Key" --read "*" --write "*"
-
-# Docker
-docker exec axvault node /app/node_modules/axvault/bin/axvault key create --name "My Key" --read "*" --write "*"
-```
-
 ## Credentials API
 
 ### Store a Credential
@@ -457,13 +397,13 @@ Alternatively, use separate environment variables:
 
 ### Common Errors
 
-| Error            | Cause                                      | Solution                                                                                |
-| ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- |
-| `not-configured` | Missing `AXVAULT_URL` or `AXVAULT_API_KEY` | Set both environment variables or use `AXVAULT` JSON                                    |
-| `unauthorized`   | Invalid API key                            | Verify key with `npx -y axvault key list`, create new if needed                         |
-| `forbidden`      | No access to credential                    | Add credential to key's read access: `npx -y axvault key update <id> --add-read <path>` |
-| `not-found`      | Credential doesn't exist                   | Store credential first: `axauth vault push --agent <agent> --name <name>`               |
-| `unreachable`    | Network issue or server down               | Check vault URL, verify server is running                                               |
+| Error            | Cause                                      | Solution                                                                  |
+| ---------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
+| `not-configured` | Missing `AXVAULT_URL` or `AXVAULT_API_KEY` | Set both environment variables or use `AXVAULT` JSON                      |
+| `unauthorized`   | Invalid API key                            | Check the key via the keys API, create a new one if needed                |
+| `forbidden`      | No access to credential                    | Update key permissions via `PATCH /api/v1/keys/:id`                       |
+| `not-found`      | Credential doesn't exist                   | Store credential first: `axauth vault push --agent <agent> --name <name>` |
+| `unreachable`    | Network issue or server down               | Check vault URL, verify server is running                                 |
 
 ### Debugging
 
@@ -473,10 +413,11 @@ Alternatively, use separate environment variables:
    curl -I $AXVAULT_URL/api/v1/health
    ```
 
-2. Verify API key permissions:
+2. List API keys (requires grant access):
 
    ```bash
-   npx -y axvault key list  # on server
+   curl -H "Authorization: Bearer $AXVAULT_API_KEY" \
+     $AXVAULT_URL/api/v1/keys
    ```
 
 3. Check credential exists:

package/dist/cli.d.ts

@@ -2,7 +2,8 @@
 /**
  * axvault - Remote credential storage server for axkit.
  *
- * Stores agent credentials and serves them via API.
+ * Starts the vault server. All key and credential management is done
+ * via the HTTP API once the server is running.
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;GAIG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/cli.js

@@ -2,13 +2,11 @@
 /**
  * axvault - Remote credential storage server for axkit.
  *
- * Stores agent credentials and serves them via API.
+ * Starts the vault server. All key and credential management is done
+ * via the HTTP API once the server is running.
  */
 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, handleKeyUpdate, } from "./commands/key.js";
 import { handleServe } from "./commands/serve.js";
 const program = new Command()
     .name(packageJson.name)
@@ -19,47 +17,14 @@ const program = new Command()
     .helpCommand(false)
     .addHelpText("after", String.raw `
 Examples:
-  # Initialize database
-  axvault init
-
-  # Start server
+  # Start server (runs migrations and creates bootstrap key on first run)
   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 "*" --grant "*"
-
-  # List all API keys
-  axvault key list
-
-  # Extract key IDs for scripting (pipeline example)
-  axvault key list | tail -n +2 | cut -f1
-
-  # Update an API key's permissions
-  axvault key update k_abc123def456 --add-read "claude.new"
-
-  # Revoke an API key
-  axvault key revoke k_abc123def456 --force
-
-  # List all stored credentials
-  axvault credential list
-
-  # Delete a credential
-  axvault credential delete claude.work --force`);
-program
-    .command("init")
-    .description("Initialize database and configuration")
-    .option("--database-url <url>", "PostgreSQL connection URL")
-    .option("-v, --verbose", "Enable verbose output")
-    .action(handleInit);
+  # Start with debug logging
+  axvault serve --log-level debug`);
 program
     .command("serve")
     .description("Start the vault server")
@@ -71,69 +36,5 @@ program
     .option("--log-level <level>", "Log level (trace, debug, info, warn, error, fatal, silent)")
     .option("-v, --verbose", "Enable verbose output")
     .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("-g, --grant <access>", "Comma-separated grant access list (can delegate these to other keys)")
-    .option("--json", "Output as JSON")
-    .option("--database-url <url>", "PostgreSQL connection URL")
-    .action(handleKeyCreate);
-keyCommand
-    .command("list")
-    .description("List all API keys")
-    .option("--json", "Output as JSON")
-    .option("--database-url <url>", "PostgreSQL connection URL")
-    .action(handleKeyList);
-keyCommand
-    .command("revoke")
-    .description("Revoke an API key")
-    .argument("<id>", "API key ID (e.g., k_abc123def456)")
-    .option("-f, --force", "Confirm destructive action")
-    .option("-y, --yes", "Alias for --force")
-    .option("-v, --verbose", "Enable verbose output")
-    .option("--database-url <url>", "PostgreSQL connection URL")
-    .action(handleKeyRevoke);
-keyCommand
-    .command("update")
-    .description("Update an API key's permissions")
-    .argument("<id>", "API key ID (e.g., k_abc123def456)")
-    .option("--add-read <access>", "Add read access entries")
-    .option("--add-write <access>", "Add write access entries")
-    .option("--add-grant <access>", "Add grant access entries")
-    .option("--remove-read <access>", "Remove read access entries")
-    .option("--remove-write <access>", "Remove write access entries")
-    .option("--remove-grant <access>", "Remove grant access entries")
-    .option("--json", "Output as JSON")
-    .option("-v, --verbose", "Enable verbose output")
-    .option("--database-url <url>", "PostgreSQL connection URL")
-    .action(handleKeyUpdate);
-// 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("--database-url <url>", "PostgreSQL connection URL")
-    .action(handleCredentialList);
-credentialCommand
-    .command("delete")
-    .description("Delete a credential")
-    .argument("<name>", "Credential name (e.g., claude.work)")
-    .option("-f, --force", "Confirm destructive action")
-    .option("-y, --yes", "Alias for --force")
-    .option("-v, --verbose", "Enable verbose output")
-    .option("--database-url <url>", "PostgreSQL connection URL")
-    .action(handleCredentialDelete);
 await program.parseAsync(process.argv);
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAEtD,OAAO,WAAW,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE;KAC1B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;KACtB,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC;KACpC,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,eAAe,CAAC;KAC7C,kBAAkB,CAAC,yCAAyC,CAAC;KAC7D,wBAAwB,EAAE;KAC1B,WAAW,CAAC,KAAK,CAAC;KAClB,WAAW,CACV,OAAO,EACP,MAAM,CAAC,GAAG,CAAA;;;;;;;;;kCASoB,CAC/B,CAAC;AAEJ,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,wBAAwB,CAAC;KACrC,MAAM,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;KAChD,MAAM,CAAC,mBAAmB,EAAE,iBAAiB,CAAC;KAC9C,MAAM,CAAC,sBAAsB,EAAE,2BAA2B,CAAC;KAC3D,MAAM,CACL,+BAA+B,EAC/B,sEAAsE,CACvE;KACA,MAAM,CACL,wBAAwB,EACxB,gDAAgD,CACjD;KACA,MAAM,CACL,qBAAqB,EACrB,4DAA4D,CAC7D;KACA,MAAM,CAAC,eAAe,EAAE,uBAAuB,CAAC;KAChD,MAAM,CAAC,WAAW,CAAC,CAAC;AAEvB,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/commands/serve.d.ts

@@ -1,5 +1,9 @@
 /**
  * Start server command handler.
+ *
+ * Builds the Fastify app, registers plugins in dependency order
+ * (database → auth → routes), runs migrations, creates a bootstrap
+ * API key on first startup, and starts listening.
  */
 interface ServeOptions {
     port?: string;

package/dist/commands/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiBH,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA+FtE"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH,UAAU,YAAY;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA2GtE"}

package/dist/commands/serve.js

@@ -1,25 +1,28 @@
 /**
  * Start server command handler.
+ *
+ * Builds the Fastify app, registers plugins in dependency order
+ * (database → auth → routes), runs migrations, creates a bootstrap
+ * API key on first startup, and starts listening.
  */
 import { fileURLToPath } from "node:url";
 import closeWithGrace from "close-with-grace";
-import { getServerConfig } from "../config.js";
-import { closePool, createPool } from "../db/create-pool.js";
-import { runMigrations } from "../db/run-migrations.js";
 import { formatErrorMessage } from "../format-error-message.js";
-import { createHealthPlugin, createCredentialPlugin, createKeyPlugin, } from "../server/routes.js";
-import { createServer } from "../server/server.js";
+import { resolveBuildAppConfig } from "../config.js";
+import { bootstrapApiKey } from "../db/bootstrap-api-key.js";
+import { runMigrations } from "../db/run-migrations.js";
+import configPlugin from "../server/plugins/config.js";
+import databasePlugin from "../server/plugins/database.js";
+import authPlugin from "../server/plugins/auth.js";
+import credentialRoutes from "../server/routes/credentials.js";
+import healthRoutes from "../server/routes/health.js";
+import keyRoutes from "../server/routes/keys.js";
+import { buildApp } from "../server/server.js";
 const migrationsDirectory = fileURLToPath(new URL("../db/migrations", import.meta.url));
 export async function handleServe(options) {
-    let config;
-    const verbose = options.verbose === true;
+    let buildConfig;
     try {
-        config = getServerConfig({
-            port: options.port,
-            host: options.host,
-            databaseUrl: options.databaseUrl,
-            refreshThresholdSeconds: options.refreshThreshold,
-            refreshTimeoutMs: options.refreshTimeout,
+        buildConfig = resolveBuildAppConfig({
             logLevel: options.logLevel,
         });
     }
@@ -29,72 +32,89 @@ export async function handleServe(options) {
         // eslint-disable-next-line unicorn/no-process-exit -- CLI config error
         process.exit(1);
     }
-    // Check encryption key is set
-    const encryptionKey = process.env["AXVAULT_ENCRYPTION_KEY"];
-    if (!encryptionKey || encryptionKey.length < 32) {
-        console.error("Error: AXVAULT_ENCRYPTION_KEY must be set to at least 32 characters");
-        // eslint-disable-next-line unicorn/no-process-exit -- CLI config error
+    // Build core app with security middleware and error handling
+    const app = buildApp(buildConfig);
+    try {
+        // Register plugins in dependency order: config → database → auth → routes
+        await app.register(configPlugin, {
+            overrides: {
+                port: options.port,
+                host: options.host,
+                databaseUrl: options.databaseUrl,
+                refreshThresholdSeconds: options.refreshThreshold,
+                refreshTimeoutMs: options.refreshTimeout,
+                logLevel: options.logLevel,
+            },
+        });
+        await app.register(databasePlugin, (parent) => ({
+            connectionString: parent.config.databaseUrl,
+        }));
+        await app.register(authPlugin);
+        await app.register(healthRoutes);
+        await app.register(credentialRoutes, (parent) => ({
+            refreshThresholdSeconds: parent.config.refreshThresholdSeconds,
+            refreshTimeoutMs: parent.config.refreshTimeoutMs,
+        }));
+        await app.register(keyRoutes);
+        // Initialize plugins (creates pool, decorators, validated config)
+        await app.ready();
+    }
+    catch (error) {
+        const message = formatErrorMessage(error);
+        console.error(`Error: ${message}`);
+        await app.close();
+        // eslint-disable-next-line unicorn/no-process-exit -- CLI config/startup error
         process.exit(1);
     }
-    // Create pool and run migrations
-    const pool = createPool(config.databaseUrl);
+    // Run migrations using the pool created by @fastify/postgres
     try {
-        await runMigrations(pool, migrationsDirectory);
+        await runMigrations(app.pg.pool, migrationsDirectory);
     }
     catch (error) {
         const message = formatErrorMessage(error);
-        console.error(`Failed to initialize database: ${message}`);
-        await closePool(pool);
+        app.log.error(`Failed to initialize database: ${message}`);
+        await app.close();
         // eslint-disable-next-line unicorn/no-process-exit -- CLI startup failure
         process.exit(1);
     }
-    // Create server with plugins using the pool for DB access
-    const server = createServer(config, [
-        createHealthPlugin(),
-        createCredentialPlugin(pool, {
-            refreshThresholdSeconds: config.refreshThresholdSeconds,
-            refreshTimeoutMs: config.refreshTimeoutMs,
-        }),
-        createKeyPlugin(pool),
-    ]);
-    // Graceful shutdown with close-with-grace.
-    // The composition root owns both the server and the pool, so it is
-    // responsible for closing both in the correct order.
-    closeWithGrace({
-        delay: 5000,
-        logger: false,
-    }, async ({ signal, err }) => {
-        try {
-            if (err) {
-                server.app.log.error({ err, signal }, "Shutting down due to error");
-            }
-            else if (verbose) {
-                server.app.log.info({ signal }, "Shutting down...");
-            }
-        }
-        catch {
-            // Server not started yet; use console.error as fallback
-            if (err) {
-                console.error("Shutting down due to error:", err);
-            }
-            else if (verbose) {
-                console.error(`Shutting down (signal: ${signal})...`);
-            }
+    // Create bootstrap admin key on first startup (no keys exist)
+    try {
+        const bootstrapKey = await bootstrapApiKey(app.pg);
+        if (bootstrapKey) {
+            app.log.info({ keyId: bootstrapKey.id }, "Created bootstrap admin API key — save this secret, it cannot be retrieved later:");
+            // Print the secret to stderr so it's visible but not mixed with structured logs
+            console.error(`\n  ${bootstrapKey.key}\n`);
         }
-        try {
-            await server.stop();
+    }
+    catch (error) {
+        const message = formatErrorMessage(error);
+        app.log.error(`Failed to create bootstrap key: ${message}`);
+        await app.close();
+        // eslint-disable-next-line unicorn/no-process-exit -- CLI startup failure
+        process.exit(1);
+    }
+    // Graceful shutdown
+    closeWithGrace({ delay: 5000, logger: false }, async ({ signal, err }) => {
+        if (err) {
+            app.log.error({ err, signal }, "Shutting down due to error");
         }
-        finally {
-            await closePool(pool);
+        else if (options.verbose) {
+            app.log.info({ signal }, "Shutting down...");
         }
+        await app.close();
     });
+    // Start listening
     try {
-        await server.start();
+        const address = await app.listen({
+            port: app.config.port,
+            host: app.config.host,
+        });
+        app.log.info({ address }, "axvault listening");
     }
     catch (error) {
         const message = formatErrorMessage(error);
-        console.error(`Failed to start server on http://${config.host}:${config.port}:`, message);
-        await closePool(pool);
+        console.error(`Failed to start server on http://${app.config.host}:${app.config.port}:`, message);
+        await app.close();
         // eslint-disable-next-line unicorn/no-process-exit -- CLI startup failure
         process.exit(1);
     }