@openparachute/vault 0.1.0 → 0.2.0

package/src/config.test.ts

@@ -2,6 +2,8 @@ import { describe, test, expect } from "bun:test";
 import {
   writeVaultConfig,
   readVaultConfig,
+  writeGlobalConfig,
+  readGlobalConfig,
   generateApiKey,
   hashKey,
   verifyKey,
@@ -122,4 +124,175 @@ describe("config", () => {
     expect(loaded).not.toBeNull();
     expect(loaded!.tag_schemas).toBeUndefined();
   });
+
+  test("round-trips discovery: enabled|disabled", () => {
+    // Default: absent means enabled (endpoint serves names).
+    writeGlobalConfig({ port: 1940 });
+    expect(readGlobalConfig().discovery).toBeUndefined();
+
+    // Explicit enabled.
+    writeGlobalConfig({ port: 1940, discovery: "enabled" });
+    expect(readGlobalConfig().discovery).toBe("enabled");
+
+    // Explicit disabled — this is the opt-out flag operators set when they
+    // don't want /vaults/list to reveal vault names publicly.
+    writeGlobalConfig({ port: 1940, discovery: "disabled" });
+    expect(readGlobalConfig().discovery).toBe("disabled");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Backup config — round-trip through writeGlobalConfig + readGlobalConfig
+// ---------------------------------------------------------------------------
+
+import { describe as describe2, test as test2, expect as expect2, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+describe2("backup config round-trip", () => {
+  // We can't just call writeGlobalConfig / readGlobalConfig like above: they
+  // write into CONFIG_DIR, which is derived from PARACHUTE_HOME at import
+  // time. So we spawn a child process with an isolated PARACHUTE_HOME to
+  // test the full read/write cycle, matching the pattern in doctor.test.ts.
+  let dir: string;
+  beforeEach(() => { dir = mkdtempSync(join(tmpdir(), "backup-cfg-")); });
+  afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+  test2("writes and reads a backup section with tiered retention + local dest", async () => {
+    // Child script writes a config, re-reads it, and prints the normalized
+    // result. This exercises the full YAML round-trip without mocking.
+    const script = `
+      process.env.PARACHUTE_HOME = ${JSON.stringify(dir)};
+      const { writeGlobalConfig, readGlobalConfig } = await import(${JSON.stringify(join(import.meta.dir, "config.ts"))});
+      writeGlobalConfig({
+        port: 1940,
+        default_vault: "default",
+        backup: {
+          schedule: "daily",
+          retention: { daily: 7, weekly: 4, monthly: 12, yearly: null },
+          destinations: [{ kind: "local", path: "~/parachute-backups" }],
+        },
+      });
+      const read = readGlobalConfig();
+      console.log(JSON.stringify(read.backup));
+    `;
+    const proc = Bun.spawnSync({
+      cmd: ["bun", "-e", script],
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const stdout = new TextDecoder().decode(proc.stdout);
+    const stderr = new TextDecoder().decode(proc.stderr);
+    expect2(proc.exitCode, stderr).toBe(0);
+
+    const parsed = JSON.parse(stdout.trim());
+    expect2(parsed.schedule).toBe("daily");
+    expect2(parsed.retention).toEqual({ daily: 7, weekly: 4, monthly: 12, yearly: null });
+    expect2(parsed.destinations.length).toBe(1);
+    expect2(parsed.destinations[0].kind).toBe("local");
+    expect2(parsed.destinations[0].path).toBe("~/parachute-backups");
+  });
+
+  test2("retention defaults when the user omits the retention block entirely", async () => {
+    // A backup: with schedule only (no retention block) should pick up the
+    // shipped defaults: 7/4/12/null.
+    const script = `
+      process.env.PARACHUTE_HOME = ${JSON.stringify(dir)};
+      const fs = await import("fs");
+      const path = await import("path");
+      fs.writeFileSync(path.join(${JSON.stringify(dir)}, "config.yaml"),
+        "port: 1940\\nbackup:\\n  schedule: daily\\n  destinations: []\\n");
+      const { readGlobalConfig } = await import(${JSON.stringify(join(import.meta.dir, "config.ts"))});
+      console.log(JSON.stringify(readGlobalConfig().backup));
+    `;
+    const proc = Bun.spawnSync({ cmd: ["bun", "-e", script], stdout: "pipe", stderr: "pipe" });
+    const out = new TextDecoder().decode(proc.stdout);
+    expect2(proc.exitCode, new TextDecoder().decode(proc.stderr)).toBe(0);
+    const parsed = JSON.parse(out.trim());
+    expect2(parsed.retention).toEqual({ daily: 7, weekly: 4, monthly: 12, yearly: null });
+  });
+
+  test2("partial retention block: unspecified tiers default to 0 (explicit > merged)", async () => {
+    // If the user supplies a retention block with only `daily: 3`, the
+    // remaining tiers read as 0 rather than merging with shipped defaults.
+    // Predictable: what you write is what you get.
+    const script = `
+      process.env.PARACHUTE_HOME = ${JSON.stringify(dir)};
+      const fs = await import("fs");
+      const path = await import("path");
+      fs.writeFileSync(path.join(${JSON.stringify(dir)}, "config.yaml"),
+        "port: 1940\\nbackup:\\n  schedule: daily\\n  retention:\\n    daily: 3\\n  destinations: []\\n");
+      const { readGlobalConfig } = await import(${JSON.stringify(join(import.meta.dir, "config.ts"))});
+      console.log(JSON.stringify(readGlobalConfig().backup));
+    `;
+    const proc = Bun.spawnSync({ cmd: ["bun", "-e", script], stdout: "pipe", stderr: "pipe" });
+    const out = new TextDecoder().decode(proc.stdout);
+    expect2(proc.exitCode, new TextDecoder().decode(proc.stderr)).toBe(0);
+    const parsed = JSON.parse(out.trim());
+    expect2(parsed.retention.daily).toBe(3);
+    expect2(parsed.retention.weekly).toBe(0);
+    expect2(parsed.retention.monthly).toBe(0);
+    // yearly stays at 0 because the user didn't say null.
+    expect2(parsed.retention.yearly).toBe(0);
+  });
+
+  test2("yearly: null round-trips through write/read as JSON null", async () => {
+    const script = `
+      process.env.PARACHUTE_HOME = ${JSON.stringify(dir)};
+      const { writeGlobalConfig, readGlobalConfig } = await import(${JSON.stringify(join(import.meta.dir, "config.ts"))});
+      writeGlobalConfig({
+        port: 1940,
+        backup: {
+          schedule: "manual",
+          retention: { daily: 0, weekly: 0, monthly: 0, yearly: null },
+          destinations: [],
+        },
+      });
+      console.log(JSON.stringify(readGlobalConfig().backup));
+    `;
+    const proc = Bun.spawnSync({ cmd: ["bun", "-e", script], stdout: "pipe", stderr: "pipe" });
+    const out = new TextDecoder().decode(proc.stdout);
+    expect2(proc.exitCode).toBe(0);
+    const parsed = JSON.parse(out.trim());
+    expect2(parsed.retention.yearly).toBeNull();
+  });
+
+  test2("config without a backup section reads back with backup === undefined", async () => {
+    const script = `
+      process.env.PARACHUTE_HOME = ${JSON.stringify(dir)};
+      const { writeGlobalConfig, readGlobalConfig } = await import(${JSON.stringify(join(import.meta.dir, "config.ts"))});
+      writeGlobalConfig({ port: 1940, default_vault: "default" });
+      const read = readGlobalConfig();
+      console.log(JSON.stringify({ backup: read.backup ?? null }));
+    `;
+    const proc = Bun.spawnSync({ cmd: ["bun", "-e", script], stdout: "pipe", stderr: "pipe" });
+    const out = new TextDecoder().decode(proc.stdout);
+    expect2(proc.exitCode).toBe(0);
+    const parsed = JSON.parse(out.trim());
+    expect2(parsed.backup).toBeNull();
+  });
+
+  test2("empty destinations round-trips as empty list (not missing key)", async () => {
+    const script = `
+      process.env.PARACHUTE_HOME = ${JSON.stringify(dir)};
+      const { writeGlobalConfig, readGlobalConfig } = await import(${JSON.stringify(join(import.meta.dir, "config.ts"))});
+      writeGlobalConfig({
+        port: 1940,
+        backup: {
+          schedule: "manual",
+          retention: { daily: 7, weekly: 4, monthly: 12, yearly: null },
+          destinations: [],
+        },
+      });
+      const read = readGlobalConfig();
+      console.log(JSON.stringify(read.backup));
+    `;
+    const proc = Bun.spawnSync({ cmd: ["bun", "-e", script], stdout: "pipe", stderr: "pipe" });
+    const out = new TextDecoder().decode(proc.stdout);
+    expect2(proc.exitCode).toBe(0);
+    const parsed = JSON.parse(out.trim());
+    expect2(parsed.schedule).toBe("manual");
+    expect2(parsed.destinations).toEqual([]);
+  });
 });

package/src/config.ts

@@ -19,9 +19,34 @@ import crypto from "node:crypto";
 
 // ---------------------------------------------------------------------------
 // Paths
+//
+// Historical note: the exported `CONFIG_DIR`, `VAULTS_DIR`, etc. used to be
+// `const` captured at module load. That made tests flaky: anything setting
+// `process.env.PARACHUTE_HOME` after import would be ignored, and when `bun
+// test` shares one process across files, whichever test loaded first froze
+// the path for the rest. Internal read/write now go through the `*Path()`
+// getters so `PARACHUTE_HOME` is re-read per call. The top-level constants
+// are kept for backward-compat (other modules import them) and reflect the
+// value at load time.
 // ---------------------------------------------------------------------------
 
-export const CONFIG_DIR = process.env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
+function configDirPath(): string {
+  return process.env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
+}
+
+function vaultsDirPath(): string {
+  return join(configDirPath(), "vaults");
+}
+
+function globalConfigPath(): string {
+  return join(configDirPath(), "config.yaml");
+}
+
+function envFilePath(): string {
+  return join(configDirPath(), ".env");
+}
+
+export const CONFIG_DIR = configDirPath();
 export const VAULTS_DIR = join(CONFIG_DIR, "vaults");
 export const GLOBAL_CONFIG_PATH = join(CONFIG_DIR, "config.yaml");
 export const ENV_PATH = join(CONFIG_DIR, ".env");
@@ -31,7 +56,7 @@ export const DEFAULT_PORT = 1940;
 export const ASSETS_DIR = join(CONFIG_DIR, "assets");
 
 export function vaultDir(name: string): string {
-  return join(VAULTS_DIR, name);
+  return join(vaultsDirPath(), name);
 }
 
 export function vaultDbPath(name: string): string {
@@ -137,6 +162,90 @@ export interface GlobalConfig {
   totp_secret?: string;
   /** Bcrypt hashes of single-use backup codes for 2FA recovery. */
   backup_codes?: string[];
+  /**
+   * Controls the public `GET /vaults/list` endpoint.
+   * - `"enabled"` (default): returns vault names (no other metadata).
+   * - `"disabled"`: returns 404, hiding vault existence from unauthenticated
+   *   callers.
+   */
+  discovery?: "enabled" | "disabled";
+  /** Backup configuration: schedule, retention, destinations. */
+  backup?: BackupConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Backup configuration
+// ---------------------------------------------------------------------------
+
+export type BackupSchedule = "hourly" | "daily" | "weekly" | "manual";
+
+/**
+ * Discriminated union over destination kinds. For the MVP we ship `local`
+ * only; `s3`, `rsync`, and `cloud` kinds will be added as additional variants
+ * without breaking existing configs. Unknown kinds are preserved verbatim so
+ * a forward-rolled config edited by a newer CLI isn't silently downgraded by
+ * an older CLI rewriting the file.
+ */
+export interface LocalBackupDestination {
+  kind: "local";
+  /** Absolute or `~/`-prefixed path. `~/` is expanded at use-time. */
+  path: string;
+}
+
+export type BackupDestination = LocalBackupDestination;
+
+/**
+ * Tiered (grandfather-father-son) retention policy. After each backup we keep
+ * the union of four tier queries:
+ *
+ *   daily   — the N most recent snapshots (unconditionally).
+ *   weekly  — one snapshot per ISO week, for the N most recent such weeks.
+ *   monthly — one snapshot per calendar month, for the N most recent months.
+ *   yearly  — one snapshot per calendar year; `null` means keep every year
+ *             (never prune by age — the long-tail archive).
+ *
+ * A tier set to 0 is disabled (it contributes no keepers, but the other tiers
+ * still apply). All bucketing uses the local timezone so calendar alignment
+ * matches the user's expectations, not UTC.
+ */
+export interface RetentionPolicy {
+  /** Keep the last N daily snapshots. 0 disables the daily tier. */
+  daily: number;
+  /** Keep the last snapshot from each of the last N ISO weeks. 0 disables. */
+  weekly: number;
+  /** Keep the last snapshot from each of the last N months. 0 disables. */
+  monthly: number;
+  /**
+   * Keep the last snapshot from each of the last N years. `null` or `undefined`
+   * means unbounded — keep one snapshot per year, forever, across the full
+   * history. 0 disables the yearly tier entirely.
+   */
+  yearly: number | null;
+}
+
+export interface BackupConfig {
+  /** How often the scheduler fires. "manual" = scheduler is not registered. */
+  schedule: BackupSchedule;
+  /** Tiered retention policy — grandfather/father/son. */
+  retention: RetentionPolicy;
+  /** Pluggable destinations. Runs in order; a destination error logs + continues. */
+  destinations: BackupDestination[];
+}
+
+export function defaultRetentionPolicy(): RetentionPolicy {
+  // Defaults balance "I want to roll back yesterday's accidental delete"
+  // against "my iCloud folder shouldn't blow up in a year." The yearly tier
+  // is unbounded by default — the whole point of the tiered policy is that
+  // one-per-year is cheap forever.
+  return { daily: 7, weekly: 4, monthly: 12, yearly: null };
+}
+
+export function defaultBackupConfig(): BackupConfig {
+  return {
+    schedule: "manual",
+    retention: defaultRetentionPolicy(),
+    destinations: [],
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -426,18 +535,192 @@ function parseTriggers(yaml: string): TriggerConfig[] | undefined {
   return triggers.length > 0 ? triggers : undefined;
 }
 
+// ---------------------------------------------------------------------------
+// Backup YAML parsing / serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the `backup:` section. Returns undefined if no section is present so
+ * callers can tell "user hasn't configured backups" apart from "user asked
+ * for the default (schedule: manual, empty destinations)."
+ *
+ * Shape:
+ *   backup:
+ *     schedule: daily
+ *     retention:
+ *       daily: 7
+ *       weekly: 4
+ *       monthly: 12
+ *       yearly: null       # or omit for unbounded; 0 disables the tier
+ *     destinations:
+ *       - kind: local
+ *         path: ~/Library/Mobile Documents/com~apple~CloudDocs/parachute-backups
+ */
+function parseBackup(yaml: string): BackupConfig | undefined {
+  const startMatch = yaml.match(/^backup:\s*$/m);
+  if (!startMatch) return undefined;
+
+  const startIdx = (startMatch.index ?? 0) + startMatch[0].length;
+  const lines = yaml.slice(startIdx).split("\n");
+
+  const backup: BackupConfig = defaultBackupConfig();
+  let section: "top" | "retention" | "destinations" = "top";
+  let currentDest: Partial<BackupDestination> & { kind?: string } = {};
+  let hasDest = false;
+  // Track whether the user supplied a retention block at all. If they did,
+  // we start from a clean slate (all tiers default 0, yearly null) so that
+  // an explicit partial policy overrides defaults rather than merging with
+  // them — predictable semantics beat magical merging.
+  let retentionSeen = false;
+
+  const pushDest = () => {
+    if (!hasDest) return;
+    // For the MVP we only ship `local`. Unknown/malformed destination kinds
+    // are skipped rather than rejected: a forward-rolled config authored by
+    // a newer CLI mustn't break backup for the features this CLI does
+    // understand. The backup command itself warns about skipped kinds.
+    if (currentDest.kind === "local" && typeof currentDest.path === "string") {
+      backup.destinations.push({ kind: "local", path: currentDest.path });
+    }
+    currentDest = {};
+    hasDest = false;
+  };
+
+  for (const line of lines) {
+    // Stop at next top-level key.
+    if (line.match(/^\S/) && line.trim().length > 0) break;
+    if (line.trim().length === 0) continue;
+
+    const trimmed = line.trim();
+
+    // A 2-space-indented line starting a new sub-section closes the previous
+    // section. The only 2-space keys under `backup:` today are `schedule`,
+    // `retention`, and `destinations`, so we key off indent depth here.
+    const indent = line.match(/^ */)?.[0].length ?? 0;
+
+    if (indent === 2) {
+      if (/^retention:\s*$/.test(trimmed)) {
+        section = "retention";
+        retentionSeen = true;
+        // Zero-out tiers so partially specified blocks don't silently merge
+        // with defaults in surprising ways.
+        backup.retention = { daily: 0, weekly: 0, monthly: 0, yearly: 0 };
+        continue;
+      }
+      if (/^destinations:\s*$/.test(trimmed)) {
+        pushDest();
+        section = "destinations";
+        continue;
+      }
+      // Any other 2-space top field terminates the current sub-section.
+      if (section !== "top") {
+        pushDest();
+        section = "top";
+      }
+    }
+
+    if (section === "top" && indent === 2) {
+      const schedMatch = trimmed.match(/^schedule:\s*(\S+)/);
+      if (schedMatch) {
+        const v = schedMatch[1];
+        if (v === "hourly" || v === "daily" || v === "weekly" || v === "manual") {
+          backup.schedule = v;
+        }
+        continue;
+      }
+    }
+
+    if (section === "retention" && indent === 4) {
+      const tierMatch = trimmed.match(/^(daily|weekly|monthly|yearly):\s*(\S+)/);
+      if (tierMatch) {
+        const tier = tierMatch[1] as keyof RetentionPolicy;
+        const raw = tierMatch[2].trim();
+        // "null" / "~" / "unbounded" all mean "keep every year" for the
+        // yearly tier. For the other tiers they'd be meaningless; we
+        // silently treat them as disabled (0) rather than erroring.
+        if (raw === "null" || raw === "~" || raw === "unbounded") {
+          if (tier === "yearly") backup.retention.yearly = null;
+          // Other tiers stay at 0.
+          continue;
+        }
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 0) {
+          backup.retention[tier] = n as never;
+        }
+        continue;
+      }
+    }
+
+    if (section === "destinations") {
+      // Start of a new list item: "- kind: local" or just "- kind:"
+      const itemMatch = trimmed.match(/^-\s+(\w+):\s*(.*)$/);
+      if (itemMatch) {
+        pushDest();
+        hasDest = true;
+        currentDest = {};
+        (currentDest as Record<string, string>)[itemMatch[1]] = itemMatch[2].trim();
+        continue;
+      }
+      // Continuation line inside the current list item.
+      const fieldMatch = trimmed.match(/^(\w+):\s*(.*)$/);
+      if (fieldMatch && hasDest) {
+        (currentDest as Record<string, string>)[fieldMatch[1]] = fieldMatch[2].trim();
+        continue;
+      }
+    }
+  }
+  pushDest();
+
+  // If the user left retention out entirely, fall back to the shipped default.
+  if (!retentionSeen) {
+    backup.retention = defaultRetentionPolicy();
+  }
+
+  return backup;
+}
+
+function serializeBackup(backup: BackupConfig): string[] {
+  const lines: string[] = [];
+  lines.push("backup:");
+  lines.push(`  schedule: ${backup.schedule}`);
+  lines.push("  retention:");
+  lines.push(`    daily: ${backup.retention.daily}`);
+  lines.push(`    weekly: ${backup.retention.weekly}`);
+  lines.push(`    monthly: ${backup.retention.monthly}`);
+  // `null` is serialized as the YAML literal `null` so round-trips preserve
+  // "unbounded." Numbers render as-is, including 0 (disabled).
+  lines.push(`    yearly: ${backup.retention.yearly === null ? "null" : backup.retention.yearly}`);
+  if (backup.destinations.length > 0) {
+    lines.push("  destinations:");
+    for (const dest of backup.destinations) {
+      lines.push(`    - kind: ${dest.kind}`);
+      // Paths may contain ~, spaces, and `.` — the whole line being on its
+      // own key line means we don't need to quote unless the value begins
+      // with a YAML-special character. Quoting defensively keeps the
+      // hand-rolled parser happy under future path-with-colons pressure.
+      if ("path" in dest) {
+        const needsQuote = /[:#]/.test(dest.path);
+        lines.push(`      path: ${needsQuote ? `"${dest.path}"` : dest.path}`);
+      }
+    }
+  } else {
+    lines.push("  destinations: []");
+  }
+  return lines;
+}
+
 // ---------------------------------------------------------------------------
 // Directory management
 // ---------------------------------------------------------------------------
 
 export async function ensureConfigDir(): Promise<void> {
-  await mkdir(CONFIG_DIR, { recursive: true });
-  await mkdir(VAULTS_DIR, { recursive: true });
+  await mkdir(configDirPath(), { recursive: true });
+  await mkdir(vaultsDirPath(), { recursive: true });
 }
 
 export function ensureConfigDirSync(): void {
-  mkdirSync(CONFIG_DIR, { recursive: true });
-  mkdirSync(VAULTS_DIR, { recursive: true });
+  mkdirSync(configDirPath(), { recursive: true });
+  mkdirSync(vaultsDirPath(), { recursive: true });
 }
 
 // ---------------------------------------------------------------------------
@@ -446,18 +729,23 @@ export function ensureConfigDirSync(): void {
 
 export function readGlobalConfig(): GlobalConfig {
   try {
-    if (existsSync(GLOBAL_CONFIG_PATH)) {
-      const yaml = readFileSync(GLOBAL_CONFIG_PATH, "utf-8");
+    const gcPath = globalConfigPath();
+    if (existsSync(gcPath)) {
+      const yaml = readFileSync(gcPath, "utf-8");
       const portMatch = yaml.match(/^port:\s*(\d+)/m);
       const defaultVaultMatch = yaml.match(/^default_vault:\s*(\S+)/m);
       const passwordHashMatch = yaml.match(/^owner_password_hash:\s*"([^"]+)"/m);
       const totpSecretMatch = yaml.match(/^totp_secret:\s*"([^"]+)"/m);
+      const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const config: GlobalConfig = {
         port: portMatch ? parseInt(portMatch[1], 10) : DEFAULT_PORT,
         default_vault: defaultVaultMatch?.[1],
         owner_password_hash: passwordHashMatch?.[1],
         totp_secret: totpSecretMatch?.[1],
       };
+      if (discoveryMatch) {
+        config.discovery = discoveryMatch[1] as "enabled" | "disabled";
+      }
 
       // Parse backup_codes: a YAML list of quoted bcrypt hashes under
       //   backup_codes:
@@ -501,6 +789,9 @@ export function readGlobalConfig(): GlobalConfig {
       // Parse triggers
       config.triggers = parseTriggers(yaml);
 
+      // Parse backup section
+      config.backup = parseBackup(yaml);
+
       return config;
     }
   } catch {}
@@ -511,6 +802,7 @@ export function writeGlobalConfig(config: GlobalConfig): void {
   ensureConfigDirSync();
   const lines = [`port: ${config.port}`];
   if (config.default_vault) lines.push(`default_vault: ${config.default_vault}`);
+  if (config.discovery) lines.push(`discovery: ${config.discovery}`);
   if (config.owner_password_hash) {
     lines.push(`owner_password_hash: "${config.owner_password_hash}"`);
   }
@@ -568,12 +860,16 @@ export function writeGlobalConfig(config: GlobalConfig): void {
     }
   }
 
+  if (config.backup) {
+    lines.push(...serializeBackup(config.backup));
+  }
+
   // 0600 — owner read/write only. This file may contain the bcrypt password
   // hash and plaintext TOTP secret; it must not be world- or group-readable.
-  writeFileSync(GLOBAL_CONFIG_PATH, lines.join("\n") + "\n", { mode: 0o600 });
+  writeFileSync(globalConfigPath(), lines.join("\n") + "\n", { mode: 0o600 });
   // writeFileSync's `mode` only applies on file creation, so chmod an existing
   // file explicitly in case it was written by an older version at 0644.
-  try { chmodSync(GLOBAL_CONFIG_PATH, 0o600); } catch {}
+  try { chmodSync(globalConfigPath(), 0o600); } catch {}
 }
 
 // ---------------------------------------------------------------------------
@@ -629,8 +925,9 @@ export function generateApiKey(): { fullKey: string; keyId: string } {
 export function readEnvFile(): Record<string, string> {
   const env: Record<string, string> = {};
   try {
-    if (!existsSync(ENV_PATH)) return env;
-    const content = readFileSync(ENV_PATH, "utf-8");
+    const p = envFilePath();
+    if (!existsSync(p)) return env;
+    const content = readFileSync(p, "utf-8");
     for (const line of content.split("\n")) {
       const trimmed = line.trim();
       if (!trimmed || trimmed.startsWith("#")) continue;
@@ -665,7 +962,7 @@ export function writeEnvFile(env: Record<string, string>): void {
       lines.push(`${key}=${val}`);
     }
   }
-  writeFileSync(ENV_PATH, lines.join("\n") + "\n");
+  writeFileSync(envFilePath(), lines.join("\n") + "\n");
 }
 
 /**
@@ -704,8 +1001,9 @@ export function loadEnvFile(): void {
 
 export function listVaults(): string[] {
   try {
-    if (!existsSync(VAULTS_DIR)) return [];
-    const entries = Bun.spawnSync(["ls", VAULTS_DIR]).stdout.toString().trim();
+    const dir = vaultsDirPath();
+    if (!existsSync(dir)) return [];
+    const entries = Bun.spawnSync(["ls", dir]).stdout.toString().trim();
     if (!entries) return [];
     return entries.split("\n").filter((name) => {
       return existsSync(vaultConfigPath(name));
@@ -714,3 +1012,35 @@ export function listVaults(): string[] {
     return [];
   }
 }
+
+/**
+ * Resolve the vault that unscoped routes (`/mcp`, `/api/*`, `/oauth/*`,
+ * `/view/*`) should target.
+ *
+ * Resolution order:
+ *  1. If `default_vault` is set in config.yaml AND that vault exists → use it.
+ *  2. Else if exactly one vault exists → use that vault regardless of its name.
+ *     This is the "single-vault auto-default": if you only have `journal`,
+ *     `/mcp` transparently targets `journal` without requiring you to visit
+ *     `/vaults/journal/mcp`.
+ *  3. Otherwise → return `null` (multi-vault deployment with no/bad default;
+ *     the caller should surface an explicit error rather than guess).
+ *
+ * Notes:
+ *  - If `default_vault` points to a deleted vault, step 2 still kicks in so
+ *    operators aren't stranded after `vault remove`.
+ *  - The name "default" has no special meaning here; it's just whatever
+ *    `vault init` happens to create on first run. A single vault named
+ *    "journal" behaves identically.
+ */
+export function resolveDefaultVault(): string | null {
+  const globalConfig = readGlobalConfig();
+  const vaults = listVaults();
+  if (globalConfig.default_vault && vaults.includes(globalConfig.default_vault)) {
+    return globalConfig.default_vault;
+  }
+  if (vaults.length === 1) {
+    return vaults[0];
+  }
+  return null;
+}