@openparachute/vault 0.4.4-rc.14 → 0.4.6-rc.3

package/src/published.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
 import { handleViewNote } from "./routes.ts";
+import { SqliteStore } from "../core/src/store.ts";
 
 // Redirect URL builder — mirrors the logic in server.ts
 function buildRedirectUrl(reqUrl: string, noteId: string, prefix = ""): string {
@@ -211,4 +213,19 @@ describe("handleViewNote", async () => {
     const resp = await handleViewNote(store, "n1", { publishedTag: "public" });
     expect(resp.status).toBe(404);
   });
+
+  it("returns 409 ambiguous_path when bare path resolves to multiple notes (vault#331 N1)", async () => {
+    // Real SqliteStore so the v18 composite (path, extension) uniqueness
+    // index lets two notes coexist at the same path with different
+    // extensions — the scenario AmbiguousPathError is built for.
+    const store = new SqliteStore(new Database(":memory:"));
+    await store.createNote("# md", { id: "vn-md", path: "Foo", tags: ["publish"] });
+    await store.createNote("a,b\n1,2", { id: "vn-csv", path: "Foo", extension: "csv", tags: ["publish"] });
+    const resp = await handleViewNote(store, "Foo", { authenticated: true });
+    expect(resp.status).toBe(409);
+    const body = await resp.json() as any;
+    expect(body.error_type).toBe("ambiguous_path");
+    expect(body.path).toBe("Foo");
+    expect(body.candidates).toHaveLength(2);
+  });
 });

package/src/routes.ts

@@ -13,7 +13,7 @@
 
 import type { Store, Note } from "../core/src/types.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
-import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE } from "../core/src/notes.ts";
+import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import { attachValidationStatus } from "../core/src/mcp.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
@@ -75,6 +75,25 @@ function parseQueryList(url: URL, key: string): string[] | undefined {
   return val ? val.split(",") : undefined;
 }
 
+/**
+ * Parse the extension query parameter (vault#328). Two accepted shapes:
+ *   - `?extension=csv` (single value → string)
+ *   - `?extension=csv&extension=yaml` OR `?extension=csv,yaml`
+ *     (repeated or comma-list → array)
+ * Returns undefined when absent so the queryNotes filter is skipped.
+ * Validation lives at the engine layer — bad strings result in zero
+ * matches rather than 400, mirroring how `path` works.
+ */
+function parseExtensionFilter(url: URL): string | string[] | undefined {
+  const all = url.searchParams.getAll("extension");
+  if (all.length === 0) return undefined;
+  // Flatten comma-lists inside each param.
+  const flat = all.flatMap((v) => v.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
+  if (flat.length === 0) return undefined;
+  if (flat.length === 1) return flat[0]!;
+  return flat;
+}
+
 function parseInt10(val: string | null): number | undefined {
   if (!val) return undefined;
   const n = parseInt(val, 10);
@@ -373,11 +392,21 @@ function parseExpandParams(
 
 
 /**
- * Resolve a note by ID or path. Tries ID first, then case-insensitive path.
+ * Resolve a note by ID or path. Tries ID first, then case-insensitive
+ * path. A trailing `.<ext>` matching the extension pattern is parsed
+ * as `(path, extension)` to disambiguate notes sharing a path
+ * differing only by extension (vault#330 S1). When the path is
+ * ambiguous and no extension hint is supplied, `getNoteByPath` throws
+ * `AmbiguousPathError` — REST handlers catch it and return 409.
  */
 async function resolveNote(store: Store, idOrPath: string): Promise<Note | null> {
   const byId = await store.getNote(idOrPath);
   if (byId) return byId;
+  const extMatch = idOrPath.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const explicit = await store.getNoteByPath(extMatch[1]!, extMatch[2]!);
+    if (explicit) return explicit;
+  }
   return await store.getNoteByPath(idOrPath);
 }
 
@@ -398,12 +427,49 @@ class NotFoundError extends Error {
 // Notes — GET/POST/PATCH/DELETE /api/notes[/:idOrPath]
 // ---------------------------------------------------------------------------
 
+/**
+ * Convert a thrown `AmbiguousPathError` (vault#330 S1) into a structured
+ * 409 JSON response. Shared by every handler that calls `resolveNote`
+ * with a user-supplied path — handleNotes, handleFindPath,
+ * handleViewNote. Returns null when the error isn't an
+ * AmbiguousPathError so the caller can re-throw / fall through.
+ */
+function ambiguousPathResponse(e: any): Response | null {
+  if (!e || e.code !== "AMBIGUOUS_PATH") return null;
+  return json(
+    {
+      error_type: "ambiguous_path",
+      error: "ambiguous_path",
+      path: e.path,
+      candidates: e.candidates,
+      message: e.message,
+    },
+    409,
+  );
+}
+
 export async function handleNotes(
   req: Request,
   store: Store,
   subpath: string,
   vault?: string,
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Promise<Response> {
+  try {
+    return await handleNotesInner(req, store, subpath, vault, tagScope);
+  } catch (e: any) {
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
+    throw e;
+  }
+}
+
+async function handleNotesInner(
+  req: Request,
+  store: Store,
+  subpath: string,
+  vault?: string,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
 ): Promise<Response> {
   const url = new URL(req.url);
   const method = req.method;
@@ -508,6 +574,12 @@ export async function handleNotes(
           hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
           path: parseQuery(url, "path") ?? undefined,
           pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
+          // Extension filter (vault#328). Accepts repeated `extension=`
+          // params for the array form: `?extension=csv&extension=yaml`.
+          // `parseQueryList` already returns undefined when no params
+          // are present, so the filter is silently skipped on a plain
+          // GET without the extension query.
+          extension: parseExtensionFilter(url),
           metadata: bracket.metadata,
           // Date-range precedence chain (highest to lowest):
           //   1. Bracket-style `meta[created_at][gte]=…` (canonical).
@@ -660,12 +732,19 @@ export async function handleNotes(
       if (batched) db.exec("BEGIN");
       try {
         for (const item of items) {
+          // Validate extension before reaching the Store (vault#328).
+          // Thrown inside the BEGIN block — outer catch rolls the batch
+          // back, same shape as the path-conflict path.
+          const extension = item.extension !== undefined
+            ? validateExtension(item.extension)
+            : undefined;
           const note = await store.createNote(item.content ?? "", {
             id: item.id,
             path: item.path,
             tags: item.tags,
             metadata: item.metadata,
             created_at: item.createdAt ?? item.created_at,
+            ...(extension !== undefined ? { extension } : {}),
           });
 
           // Create explicit links
@@ -688,6 +767,12 @@ export async function handleNotes(
             409,
           );
         }
+        if (e && e.code === "INVALID_EXTENSION") {
+          return json(
+            { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
+            400,
+          );
+        }
         throw e;
       }
 
@@ -845,12 +930,17 @@ export async function handleNotes(
           }
           const idLooksLikePath = idOrPathStr.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPathStr);
           const explicitPath = typeof body.path === "string" ? body.path as string : undefined;
+          // Validate extension before reaching the Store (vault#328).
+          const createExt = body.extension !== undefined
+            ? validateExtension(body.extension)
+            : undefined;
           const createOpts: Parameters<Store["createNote"]>[1] = {
             ...(idLooksLikePath ? { path: explicitPath ?? idOrPathStr } : { id: idOrPathStr, ...(explicitPath !== undefined ? { path: explicitPath } : {}) }),
             ...(tagsArr.length > 0 ? { tags: tagsArr } : {}),
             ...(body.metadata !== undefined ? { metadata: body.metadata as Record<string, unknown> } : {}),
             ...(body.created_at !== undefined ? { created_at: body.created_at as string } : {}),
             ...(body.createdAt !== undefined ? { created_at: body.createdAt as string } : {}),
+            ...(createExt !== undefined ? { extension: createExt } : {}),
           };
           const content = (body.content as string | undefined) ?? "";
           const created = await store.createNote(content, createOpts);
@@ -1019,6 +1109,11 @@ export async function handleNotes(
         if (body.prepend !== undefined) updates.prepend = body.prepend;
       }
       if (body.path !== undefined) updates.path = body.path;
+      if (body.extension !== undefined) {
+        // Validate up front (vault#328). Throws ExtensionValidationError
+        // which the outer catch converts to a 400.
+        updates.extension = validateExtension(body.extension);
+      }
       if (body.metadata !== undefined) {
         const existing = (note.metadata as Record<string, unknown>) ?? {};
         updates.metadata = { ...existing, ...body.metadata };
@@ -1108,6 +1203,12 @@ export async function handleNotes(
           409,
         );
       }
+      if (e && e.code === "INVALID_EXTENSION") {
+        return json(
+          { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
+          400,
+        );
+      }
       throw e;
     }
   }
@@ -1448,6 +1549,11 @@ export async function handleFindPath(
     return json(result);
   } catch (e: any) {
     if (e instanceof NotFoundError) return json({ error: e.message }, 404);
+    // vault#331 N1 — surface AmbiguousPathError from resolveNote as 409
+    // mirroring the handleNotes path. Without this, an ambiguous source/
+    // target path on /api/find-path bubbled to a server-level 500.
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
     throw e;
   }
 }
@@ -1640,7 +1746,19 @@ export async function handleViewNote(
   options: { authenticated?: boolean; publishedTag?: string } = {},
 ): Promise<Response> {
   const { authenticated = false, publishedTag = "publish" } = options;
-  const note = await resolveNote(store, idOrPath);
+  let note: Note | null;
+  try {
+    note = await resolveNote(store, idOrPath);
+  } catch (e: any) {
+    // vault#331 N1 — surface AmbiguousPathError as 409. The HTML view
+    // route doesn't otherwise return JSON, but the structured body is
+    // the right shape for the API contract; a human reader hitting
+    // this URL gets the JSON inline (rare — the bare path form is
+    // mostly an API consumer's mistake).
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
+    throw e;
+  }
   if (!note) {
     return new Response("Not Found", { status: 404, headers: { "Content-Type": "text/plain" } });
   }

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,
+  };
+}