@openparachute/vault 0.4.5 → 0.4.6-rc.3

package/README.md

@@ -810,8 +810,37 @@ cp .env.example .env   # edit with your config
 docker compose up -d
 ```
 
+Optionally set `PARACHUTE_VAULT_NAME` to choose a name for your first vault (defaults to `default`). Lowercase alphanumeric + hyphens or underscores, 2–32 chars.
+
 ### Cloud platforms
 
+#### Render — recommended (hub-managed, v0.6)
+
+Most users deploy vault via parachute-hub's `/admin/modules` after the
+hub itself is on Render. See <https://parachute.computer/deploy/render/>
+for the primary v0.6 self-host story: one Render Blueprint provisions
+hub on a persistent disk, then you install vault (and the other
+Parachute modules) from the hub's admin UI. The hub container
+supervises vault's process, the shared persistent disk holds vault
+state, and module upgrades flow through the admin UI rather than
+separate Render redeploys.
+
+#### Render — standalone vault (advanced)
+
+The `render.yaml` Blueprint at the repo root deploys vault as its own
+Render web service, separate from hub. This is the **advanced path** —
+useful when you want vault on its own container (separate scaling,
+isolated logs, vault-only deploy without a hub) but not what the
+typical v0.6 self-host wants. If you're not sure, use the hub-managed
+path above. The standalone Blueprint stays in tree because some
+operators specifically want this shape (vault#341).
+
+Optionally set `PARACHUTE_VAULT_NAME` to choose a name for your first
+vault (defaults to `default`). Lowercase alphanumeric + hyphens or
+underscores, 2–32 chars.
+
+#### Other platforms
+
 **Railway** ($5/mo) — Deploy from GitHub, persistent volume, public URL.
 **Fly.io** ($3-5/mo) — `fly launch --copy-config && fly volumes create vault_data --size 1 && fly deploy`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.4.5",
+  "version": "0.4.6-rc.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/auth.test.ts

@@ -398,3 +398,238 @@ describe("auth — legacy global YAML keys honor declared scope", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// VAULT_AUTH_TOKEN — server-wide operator bearer (vault#339)
+//
+// The container-shape auth gate. When the env var is set, a request whose
+// `Authorization: Bearer <value>` matches authenticates as full/admin
+// against any vault on the server — the operator-channel path for sibling
+// services on Render where vault and hub run as separate containers and
+// hub needs a stable shared bearer to call vault.
+//
+// Semantic confirmed for the loopback/non-loopback split (auth gate is
+// orthogonal to socket-level loopback): when VAULT_AUTH_TOKEN is unset,
+// vault's existing token surface (per-vault DB tokens + hub JWTs + legacy
+// YAML keys) is the ONLY auth surface. The bind socket defaults to
+// 127.0.0.1 (`VAULT_BIND` in bind.ts), but no implicit loopback trust
+// exists at the auth layer — a request from 127.0.0.1 still has to
+// present a valid bearer. This matches docs/auth-model.md §1.
+// ---------------------------------------------------------------------------
+
+describe("auth — VAULT_AUTH_TOKEN server-wide operator bearer", () => {
+  const TOKEN = "test-operator-token-deadbeef0123456789abcdef";
+  let prevToken: string | undefined;
+
+  beforeEach(() => {
+    prevToken = process.env.VAULT_AUTH_TOKEN;
+  });
+
+  afterEach(() => {
+    if (prevToken === undefined) delete process.env.VAULT_AUTH_TOKEN;
+    else process.env.VAULT_AUTH_TOKEN = prevToken;
+  });
+
+  test("env set + matching bearer → 200 on vault auth, full permission, admin scopes", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer(TOKEN),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+      expect(result.scopes).toContain("vault:admin");
+      expect(result.legacyDerived).toBe(false);
+      expect(result.scoped_tags).toBeNull();
+    }
+  });
+
+  test("env set + matching bearer authenticates against ANY vault on the server", async () => {
+    // Server-wide → not tied to any one vault's DB. Same bearer works
+    // for journal and work without minting a per-vault token in either.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    seedVault("work");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+    const workConfig = readVaultConfig("work")!;
+    const workStore = getVaultStore("work");
+
+    const j = await authenticateVaultRequest(bearer(TOKEN), journalConfig, journalStore.db);
+    const w = await authenticateVaultRequest(bearer(TOKEN), workConfig, workStore.db);
+
+    expect("error" in j).toBe(false);
+    expect("error" in w).toBe(false);
+  });
+
+  test("env set + missing bearer → 401 (no implicit auth)", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    // No Authorization header at all.
+    const noBearer = new Request("https://vault.test/x");
+    const result = await authenticateVaultRequest(noBearer, journalConfig, journalStore.db);
+
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set + wrong bearer → 401", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer("wrong-token-doesnotmatch"),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set + bearer that matches a vault token still resolves (server-wide first, but per-vault unchanged)", async () => {
+    // Per-vault tokens keep working even when the server-wide bearer is
+    // set. The server-wide check is a fast-path lookup before token DB
+    // resolution — a per-vault token doesn't match the env var so it
+    // falls through to the existing path.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const perVaultToken = mintTokenInVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer(perVaultToken),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(false);
+  });
+
+  test("env unset + valid per-vault bearer → 200 (existing behavior preserved)", async () => {
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const token = mintTokenInVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(bearer(token), journalConfig, journalStore.db);
+    expect("error" in result).toBe(false);
+  });
+
+  test("env unset + missing bearer → 401 (existing behavior preserved)", async () => {
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const noBearer = new Request("https://vault.test/x");
+    const result = await authenticateVaultRequest(noBearer, journalConfig, journalStore.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env unset + non-loopback simulated via X-Forwarded-For → still 401 without bearer", async () => {
+    // Doc note: vault has NO implicit loopback trust at the auth layer.
+    // The X-Forwarded-For shape (set by hub / Cloudflare Tunnel / etc.)
+    // doesn't affect the auth gate; tokens are required regardless of
+    // socket origin. The `bind.ts` 127.0.0.1 default is a socket-level
+    // listen-restriction, not a trust-asymmetric auth bypass.
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const remote = new Request("https://vault.test/x", {
+      headers: { "X-Forwarded-For": "203.0.113.7" },
+    });
+    const result = await authenticateVaultRequest(remote, journalConfig, journalStore.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set with whitespace-only value → treated as unset", async () => {
+    process.env.VAULT_AUTH_TOKEN = "   ";
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    // An empty/whitespace VAULT_AUTH_TOKEN must NOT allow any bearer to
+    // pass — the operator either commits to bearer auth or doesn't.
+    const result = await authenticateVaultRequest(
+      bearer(""),
+      journalConfig,
+      journalStore.db,
+    );
+    expect("error" in result).toBe(true);
+  });
+
+  test("env set + matching bearer also works on the global auth surface", async () => {
+    // /vaults metadata listing + /health vault names go through
+    // authenticateGlobalRequest. The server-wide bearer must work there
+    // too — otherwise hub couldn't enumerate vaults using the operator
+    // channel.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+
+    const result = await authenticateGlobalRequest(bearer(TOKEN));
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+    }
+  });
+
+  test("env set + wrong bearer on global auth surface → 401", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+
+    const result = await authenticateGlobalRequest(bearer("wrong-token"));
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("near-miss bearer (one-char difference, same length) → 401 (constant-time compare)", async () => {
+    // Defensive: the server-wide compare uses crypto.timingSafeEqual so
+    // a one-char-off bearer that matches length-wise still rejects.
+    // We can't measure timing in a unit test, but we can pin the
+    // correctness side: a same-length near-miss must still reject.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const nearMiss = TOKEN.slice(0, -1) + "x";
+    expect(nearMiss).not.toBe(TOKEN);
+    expect(nearMiss.length).toBe(TOKEN.length);
+
+    const result = await authenticateVaultRequest(
+      bearer(nearMiss),
+      journalConfig,
+      journalStore.db,
+    );
+    expect("error" in result).toBe(true);
+  });
+});

package/src/auth.ts

@@ -20,6 +20,7 @@ import type { VaultConfig, StoredKey } from "./config.ts";
 import { resolveToken } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
 import type { Database } from "bun:sqlite";
+import crypto from "node:crypto";
 import { getVaultStore } from "./vault-store.ts";
 import {
   findBroadVaultScopes,
@@ -32,6 +33,66 @@ import {
 } from "./scopes.ts";
 import { HubJwtError, looksLikeJwt, validateHubJwt } from "./hub-jwt.ts";
 
+/**
+ * Server-wide operator bearer token, sourced from the `VAULT_AUTH_TOKEN`
+ * environment variable.
+ *
+ * Read dynamically per request (not cached at import time) so test seams
+ * that mutate `process.env.VAULT_AUTH_TOKEN` work without re-importing.
+ * In production the env var is set at container start and doesn't change.
+ *
+ * Empty / whitespace-only values are treated as unset — the operator
+ * either commits to bearer auth or doesn't, no degraded "empty token
+ * always matches" failure mode.
+ */
+function getServerWideAuthToken(env: NodeJS.ProcessEnv = process.env): string | null {
+  const raw = env.VAULT_AUTH_TOKEN;
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+
+/**
+ * Constant-time string equality. Returns false when lengths differ
+ * (timingSafeEqual throws on length mismatch; we want a quiet false).
+ */
+function constantTimeEquals(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a, "utf8");
+  const bBuf = Buffer.from(b, "utf8");
+  if (aBuf.length !== bBuf.length) return false;
+  return crypto.timingSafeEqual(aBuf, bBuf);
+}
+
+/**
+ * If `VAULT_AUTH_TOKEN` is set and the provided bearer matches it
+ * (constant-time), return a full-admin AuthResult that's accepted by
+ * every vault on the server.
+ *
+ * The operator-channel auth shape for non-loopback deploys (Render,
+ * sibling-container setups, vault#339). Hub uses this to call vault
+ * across a container boundary; end-user OAuth tokens still take the
+ * per-vault hub-JWT / pvt_* paths below. See `docs/auth-model.md` §2.
+ *
+ * Scope set is broad (`vault:admin`) — the env-var bearer is an
+ * operator credential, not a user credential. Tag-scoping doesn't
+ * apply; we represent it as unscoped (`scoped_tags: null`).
+ */
+function tryServerWideAuth(
+  providedKey: string,
+  env: NodeJS.ProcessEnv = process.env,
+): AuthResult | null {
+  const configured = getServerWideAuthToken(env);
+  if (configured === null) return null;
+  if (!constantTimeEquals(providedKey, configured)) return null;
+  return {
+    permission: "full",
+    scopes: [SCOPE_ADMIN, SCOPE_WRITE, SCOPE_READ],
+    legacyDerived: false,
+    scoped_tags: null,
+    vault_name: null,
+  };
+}
+
 /** Result of a successful auth check. */
 export interface AuthResult {
   permission: TokenPermission;
@@ -168,6 +229,15 @@ export async function authenticateVaultRequest(
     return { error: Response.json({ error: "Unauthorized", message: "API key required" }, { status: 401 }) };
   }
 
+  // Server-wide operator token (vault#339). When VAULT_AUTH_TOKEN is set,
+  // a matching bearer authenticates as full/admin against any vault. This
+  // is the cross-container path for Render / sibling-service deployments
+  // where hub talks to vault over HTTP. Checked first so it short-circuits
+  // both JWT validation and per-vault DB lookups — the operator token is
+  // a credential the operator opts into, not one we'd ever fall through.
+  const serverWide = tryServerWideAuth(key);
+  if (serverWide !== null) return serverWide;
+
   // JWT path: hub-issued tokens. Trust pinned to the hub origin via `iss`
   // verification inside validateHubJwt; signature checked against hub's JWKS.
   // Audience strict-checked against `vault.<name>` so a token stamped for
@@ -326,6 +396,14 @@ export async function authenticateGlobalRequest(
     return { error: Response.json({ error: "Unauthorized", message: "API key required" }, { status: 401 }) };
   }
 
+  // Server-wide operator token (vault#339). When VAULT_AUTH_TOKEN is set,
+  // a matching bearer authenticates as full/admin on cross-vault routes
+  // (/vaults metadata listing, /health detail). Checked first so a
+  // container-host operator-channel call doesn't depend on any per-vault
+  // DB lookup.
+  const serverWide = tryServerWideAuth(key);
+  if (serverWide !== null) return serverWide;
+
   // Hub-issued JWTs are always vault-bound (aud=vault.<name>). The unified
   // /vaults / /health surface spans every vault and has no single audience to
   // strict-check against, so JWTs aren't accepted here. Cross-vault listing

package/src/routing.test.ts

@@ -17,7 +17,7 @@
  * never touch ~/.parachute.
  */
 
-import { describe, test, expect, beforeEach, afterAll } from "bun:test";
+import { describe, test, expect, beforeEach, afterEach, afterAll } from "bun:test";
 import { rmSync, existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
@@ -1641,3 +1641,87 @@ describe("scope enforcement on /api/*", () => {
     expect(writeRes.status).toBe(403);
   });
 });
+
+// ---------------------------------------------------------------------------
+// /health — smoke tests for the unauthenticated liveness probe (vault#339).
+//
+// /health must ALWAYS return 200 regardless of VAULT_AUTH_TOKEN config so
+// Render's health probe + Docker HEALTHCHECK can poll the container even
+// before the operator has configured a bearer. The response shape changes
+// (vault names are leaked only to authed callers) but the status code is
+// invariant.
+// ---------------------------------------------------------------------------
+
+describe("/health — always 200 (Render/Docker healthcheck contract)", () => {
+  let prevToken: string | undefined;
+
+  beforeEach(() => {
+    prevToken = process.env.VAULT_AUTH_TOKEN;
+  });
+
+  afterEach(() => {
+    if (prevToken === undefined) delete process.env.VAULT_AUTH_TOKEN;
+    else process.env.VAULT_AUTH_TOKEN = prevToken;
+  });
+
+  test("env unset + no bearer → 200 (anonymous probe)", async () => {
+    delete process.env.VAULT_AUTH_TOKEN;
+    createVault("journal");
+
+    const res = await route(new Request("http://localhost:1940/health"), "/health");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+    // No bearer → no vault names leaked.
+    expect(body.vaults).toBeUndefined();
+  });
+
+  test("env set + no bearer → 200 (Render's health probe doesn't have the secret)", async () => {
+    process.env.VAULT_AUTH_TOKEN = "operator-token-xyz";
+    createVault("journal");
+
+    const res = await route(new Request("http://localhost:1940/health"), "/health");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+    expect(body.vaults).toBeUndefined();
+  });
+
+  test("env set + matching bearer → 200 + vault names leaked", async () => {
+    process.env.VAULT_AUTH_TOKEN = "operator-token-xyz";
+    createVault("journal");
+    createVault("work");
+
+    const res = await route(
+      new Request("http://localhost:1940/health", {
+        headers: { Authorization: "Bearer operator-token-xyz" },
+      }),
+      "/health",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+    expect(Array.isArray(body.vaults)).toBe(true);
+    expect(body.vaults).toContain("journal");
+    expect(body.vaults).toContain("work");
+  });
+
+  test("env set + wrong bearer → 200 (still healthy, just no vault detail)", async () => {
+    // /health doesn't 401 on a wrong bearer — it just falls back to the
+    // anonymous response. The operator's probe stays green even if the
+    // bearer is mid-rotation.
+    process.env.VAULT_AUTH_TOKEN = "operator-token-xyz";
+    createVault("journal");
+
+    const res = await route(
+      new Request("http://localhost:1940/health", {
+        headers: { Authorization: "Bearer wrong-token" },
+      }),
+      "/health",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("ok");
+    expect(body.vaults).toBeUndefined();
+  });
+});

package/src/server.ts

@@ -18,6 +18,7 @@
 import { readVaultConfig, readGlobalConfig, writeGlobalConfig, writeVaultConfig, listVaults, DEFAULT_PORT, ensureConfigDirSync, loadEnvFile, generateApiKey, hashKey, stopSignalPath } from "./config.ts";
 import { existsSync, rmSync } from "fs";
 import { migrateVaultKeys } from "./token-store.ts";
+import { resolveFirstBootVaultName } from "./vault-name.ts";
 import { getVaultStore, getVaultNameForStore } from "./vault-store.ts";
 import { defaultHookRegistry } from "../core/src/hooks.ts";
 import { registerTriggers } from "./triggers.ts";
@@ -98,13 +99,31 @@ if (process.env.SCRIBE_URL) {
   console.log("[transcribe] worker disabled (set SCRIBE_URL to enable)");
 }
 
-// Auto-init: create a default vault if none exist (first run in Docker)
+if (process.env.VAULT_AUTH_TOKEN?.trim()) {
+  console.log("[auth] VAULT_AUTH_TOKEN set — server-wide operator bearer active");
+}
+
+// Auto-init: create a default vault if none exist (first run in Docker).
+// The vault name comes from PARACHUTE_VAULT_NAME when set + valid; otherwise
+// falls back to "default". Hub's first-boot wizard (hub#267) passes through
+// an operator-chosen name via this env var.
 if (listVaults().length === 0) {
   const globalConfig = readGlobalConfig();
   if (!globalConfig.default_vault) {
+    const firstBoot = resolveFirstBootVaultName(process.env.PARACHUTE_VAULT_NAME);
+    if (firstBoot.source === "env") {
+      console.log(`[vault first-boot] using PARACHUTE_VAULT_NAME=${firstBoot.name}`);
+    } else if (firstBoot.source === "env-invalid") {
+      console.warn(
+        `[vault first-boot] PARACHUTE_VAULT_NAME=${JSON.stringify(firstBoot.rawValue)} is invalid (${firstBoot.reason}); falling back to "default"`,
+      );
+    } else {
+      console.log("[vault first-boot] using default name (no PARACHUTE_VAULT_NAME set)");
+    }
+    const vaultName = firstBoot.name;
     const { fullKey, keyId } = generateApiKey();
     writeVaultConfig({
-      name: "default",
+      name: vaultName,
       api_keys: [{
         id: keyId,
         label: "default",
@@ -114,7 +133,7 @@ if (listVaults().length === 0) {
       }],
       created_at: new Date().toISOString(),
     });
-    globalConfig.default_vault = "default";
+    globalConfig.default_vault = vaultName;
     if (!globalConfig.api_keys?.length) {
       globalConfig.api_keys = [{
         id: keyId,
@@ -125,7 +144,7 @@ if (listVaults().length === 0) {
       }];
     }
     writeGlobalConfig(globalConfig);
-    console.log(`Auto-created default vault (API key: ${fullKey})`);
+    console.log(`Auto-created vault "${vaultName}" (API key: ${fullKey})`);
   }
 }
 

package/src/vault-name.test.ts

@@ -1,11 +1,13 @@
 /**
  * Unit tests for `validateVaultName` — the rule enforced by the `init`
- * prompt and the `--vault-name` flag. Covers each rejection branch plus
- * the happy paths the prompt has to accept (default, hyphens, underscores).
+ * prompt, the `--vault-name` flag, and the `PARACHUTE_VAULT_NAME` env var
+ * at server first-boot. Covers each rejection branch (empty, length,
+ * regex, reserved) plus the happy paths the prompt has to accept (default,
+ * hyphens, underscores, length boundaries).
  */
 
 import { describe, test, expect } from "bun:test";
-import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
+import { validateVaultName, decideInitVaultName, resolveFirstBootVaultName } from "./vault-name.ts";
 
 describe("validateVaultName", () => {
   describe("accepts", () => {
@@ -14,11 +16,12 @@ describe("validateVaultName", () => {
       "aaron",
       "personal",
       "work",
-      "a",
+      "ab", // 2-char boundary (min length)
       "vault-1",
       "my_vault",
       "a-b_c-1",
       "abc123",
+      "a".repeat(32), // 32-char boundary (max length)
     ])("%s", (name) => {
       const result = validateVaultName(name);
       expect(result.ok).toBe(true);
@@ -71,6 +74,24 @@ describe("validateVaultName", () => {
       expect(result.ok).toBe(false);
       if (!result.ok) expect(result.error).toContain("reserved");
     });
+
+    test("single character (below 2-char min)", () => {
+      const result = validateVaultName("a");
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error).toContain("2");
+    });
+
+    test("33 characters (above 32-char max)", () => {
+      const result = validateVaultName("a".repeat(33));
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error).toContain("32");
+    });
+
+    test("200 characters (well above max)", () => {
+      const result = validateVaultName("a".repeat(200));
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error).toContain("32");
+    });
   });
 });
 
@@ -121,3 +142,78 @@ describe("decideInitVaultName", () => {
     expect(d).toEqual({ kind: "name", name: "aaron" });
   });
 });
+
+describe("resolveFirstBootVaultName", () => {
+  test("env var unset → fallback to default", () => {
+    const r = resolveFirstBootVaultName(undefined);
+    expect(r).toEqual({ source: "default", name: "default" });
+  });
+
+  test("env var empty string → fallback to default", () => {
+    const r = resolveFirstBootVaultName("");
+    expect(r).toEqual({ source: "default", name: "default" });
+  });
+
+  test("env var whitespace-only → fallback to default", () => {
+    const r = resolveFirstBootVaultName("   ");
+    expect(r).toEqual({ source: "default", name: "default" });
+  });
+
+  test("env var set to a valid name → that name (positive path)", () => {
+    const r = resolveFirstBootVaultName("smoke-1939");
+    expect(r).toEqual({ source: "env", name: "smoke-1939" });
+  });
+
+  test("env var set to a valid name with underscores → that name", () => {
+    const r = resolveFirstBootVaultName("my_vault");
+    expect(r).toEqual({ source: "env", name: "my_vault" });
+  });
+
+  test("env var set with surrounding whitespace → trimmed + accepted", () => {
+    const r = resolveFirstBootVaultName("  aaron  ");
+    expect(r).toEqual({ source: "env", name: "aaron" });
+  });
+
+  test("env var set to invalid (uppercase + spaces + special) → fallback to default + record raw + reason", () => {
+    const r = resolveFirstBootVaultName("Bad Name!!");
+    expect(r.source).toBe("env-invalid");
+    expect(r.name).toBe("default");
+    if (r.source === "env-invalid") {
+      expect(r.rawValue).toBe("Bad Name!!");
+      expect(r.reason).toContain("lowercase alphanumeric");
+    }
+  });
+
+  test("env var set to reserved name 'list' → fallback to default", () => {
+    const r = resolveFirstBootVaultName("list");
+    expect(r.source).toBe("env-invalid");
+    expect(r.name).toBe("default");
+    if (r.source === "env-invalid") {
+      expect(r.reason).toContain("reserved");
+    }
+  });
+
+  test("env var set to slash-containing name → fallback to default", () => {
+    const r = resolveFirstBootVaultName("team/work");
+    expect(r.source).toBe("env-invalid");
+    expect(r.name).toBe("default");
+  });
+
+  test("env var set to a 200-char name → fallback to default (over max-length)", () => {
+    const r = resolveFirstBootVaultName("a".repeat(200));
+    expect(r.source).toBe("env-invalid");
+    expect(r.name).toBe("default");
+    if (r.source === "env-invalid") {
+      expect(r.reason).toContain("32");
+    }
+  });
+
+  test("env var set to a single character → fallback to default (under min-length)", () => {
+    const r = resolveFirstBootVaultName("a");
+    expect(r.source).toBe("env-invalid");
+    expect(r.name).toBe("default");
+    if (r.source === "env-invalid") {
+      expect(r.reason).toContain("2");
+    }
+  });
+});

package/src/vault-name.ts

@@ -5,12 +5,17 @@
  * the SQLite filename, and the OAuth consent page — anything that breaks
  * URL routing or filesystem assumptions has to be rejected up front.
  *
- * Used by the `init` prompt and the `--vault-name` flag. `cmdCreate` keeps
- * its own (slightly more permissive, legacy) regex for backward compat —
- * tightening it would reject names existing users may already have minted.
+ * Rule: lowercase alphanumeric + hyphens or underscores, 2–32 chars, with
+ * `list` reserved. Used by the `init` prompt, the `--vault-name` flag, and
+ * the `PARACHUTE_VAULT_NAME` env var at server first-boot. `cmdCreate`
+ * keeps its own (slightly more permissive, legacy) regex for backward
+ * compat — tightening it would reject names existing users may already
+ * have minted.
  */
 
 const VAULT_NAME_RE = /^[a-z0-9_-]+$/;
+const VAULT_NAME_MIN_LEN = 2;
+const VAULT_NAME_MAX_LEN = 32;
 
 const RESERVED_NAMES = new Set([
   // Collides with the `/vaults/list` discovery endpoint historically; the
@@ -23,11 +28,24 @@ export type VaultNameValidation =
   | { ok: true; name: string }
   | { ok: false; error: string };
 
+/**
+ * Validate a vault name. Accepts lowercase alphanumeric + hyphens or
+ * underscores, 2–32 chars. Trims surrounding whitespace before checking.
+ * `cmdCreate` keeps its own (legacy-permissive) regex; this validator is
+ * the strict gate used by the env var, the `--vault-name` flag, and
+ * hub's first-boot wizard.
+ */
 export function validateVaultName(raw: string): VaultNameValidation {
   const name = raw.trim();
   if (!name) {
     return { ok: false, error: "vault name cannot be empty." };
   }
+  if (name.length < VAULT_NAME_MIN_LEN || name.length > VAULT_NAME_MAX_LEN) {
+    return {
+      ok: false,
+      error: `vault names must be ${VAULT_NAME_MIN_LEN}–${VAULT_NAME_MAX_LEN} characters long.`,
+    };
+  }
   if (!VAULT_NAME_RE.test(name)) {
     return {
       ok: false,
@@ -78,3 +96,43 @@ export function decideInitVaultName(
   }
   return { kind: "prompt" };
 }
+
+/**
+ * Pick the first-boot vault name based on `PARACHUTE_VAULT_NAME`. Used by
+ * `server.ts` when the server starts with zero vaults on disk (Docker
+ * first-boot, hub-driven self-host install).
+ *
+ *   - env var unset / empty / whitespace-only → `{ source: "default", name: "default" }`
+ *   - env var present + valid → `{ source: "env", name: <validated> }`
+ *   - env var present + invalid → `{ source: "env-invalid", name: "default",
+ *     rawValue: <original>, reason: <validator message> }` (caller logs a
+ *     warning and proceeds with the default name; we never abort first-boot
+ *     over a misconfigured env var)
+ *
+ * Validation uses the same `validateVaultName` rule as the `--vault-name`
+ * flag — lowercase alphanumeric + hyphens or underscores, 2–32 chars, with
+ * the `list` reserved-name carveout — so hub's wizard, the CLI flag, and
+ * the env var all share one truth.
+ */
+export type FirstBootVaultName =
+  | { source: "default"; name: "default" }
+  | { source: "env"; name: string }
+  | { source: "env-invalid"; name: "default"; rawValue: string; reason: string };
+
+export function resolveFirstBootVaultName(
+  rawEnvValue: string | undefined,
+): FirstBootVaultName {
+  if (rawEnvValue === undefined || rawEnvValue.trim() === "") {
+    return { source: "default", name: "default" };
+  }
+  const v = validateVaultName(rawEnvValue);
+  if (v.ok) {
+    return { source: "env", name: v.name };
+  }
+  return {
+    source: "env-invalid",
+    name: "default",
+    rawValue: rawEnvValue,
+    reason: v.error,
+  };
+}