@openparachute/vault 0.2.4 → 0.3.0

package/src/auth.test.ts

@@ -1,11 +1,10 @@
 /**
- * Auth invariants — routing coherence between unscoped and scoped paths.
+ * Auth invariants — per-vault routing with strict isolation.
  *
- * See Fix 2 in the OAuth-to-Daily launch work: a vault token minted by one
- * path (unscoped `/oauth/token` or scoped `/vaults/X/oauth/token`) must
- * authenticate identically at every endpoint that addresses the same vault,
- * regardless of whether the URL uses `/api/*` (default-vault shortcut) or
- * `/vaults/X/api/*` (explicit). Same for `/mcp` vs `/vaults/X/mcp`.
+ * Every HTTP path that touches a vault lives under `/vault/<name>/...`, so
+ * a token minted for vault A must authenticate at vault A endpoints and
+ * must not authenticate at vault B endpoints. The global auth path still
+ * exists for cross-vault listings (`/vaults`) and scans every vault's DB.
  *
  * These tests isolate `PARACHUTE_HOME` so they don't touch the user's real
  * config. Each test builds 1-2 vaults from scratch.
@@ -34,7 +33,7 @@ let prevHome: string | undefined;
 
 beforeEach(() => {
   tmpHome = join(tmpdir(), `vault-auth-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-  mkdirSync(join(tmpHome, "vaults"), { recursive: true });
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
   prevHome = process.env.PARACHUTE_HOME;
   process.env.PARACHUTE_HOME = tmpHome;
   clearVaultStoreCache();
@@ -83,51 +82,35 @@ function bearer(token: string): Request {
   });
 }
 
-describe("auth — default-vault routing coherence", () => {
-  test("token minted in default vault authenticates at both unscoped and scoped paths", () => {
-    seedVault("default", { isDefault: true });
-    const token = mintTokenInVault("default");
-    const defaultConfig = readVaultConfig("default")!;
-    const defaultStore = getVaultStore("default");
-
-    // Unscoped `/api/*` flow: server resolves default vault, calls
-    // authenticateVaultRequest with default's config + DB. Token must resolve.
-    const unscoped = authenticateVaultRequest(bearer(token), defaultConfig, defaultStore.db);
-    expect("error" in unscoped).toBe(false);
-    if (!("error" in unscoped)) expect(unscoped.permission).toBe("full");
-
-    // Scoped `/vaults/default/api/*` flow: same defaultConfig + DB. Must also
-    // resolve — this is the invariant Aaron's complaint hinges on.
-    const scoped = authenticateVaultRequest(bearer(token), defaultConfig, defaultStore.db);
-    expect("error" in scoped).toBe(false);
-
-    // Unified `/mcp` flow: authenticateGlobalRequest scans every vault's DB.
-    // Since the token is in default's DB, this must also resolve.
+describe("auth — per-vault routing", () => {
+  test("token minted in a vault authenticates at its own /vault/<name>/* endpoints", () => {
+    seedVault("journal");
+    const token = mintTokenInVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    // /vault/journal/api/* and /vault/journal/mcp both funnel into
+    // authenticateVaultRequest with journal's config + DB.
+    const vaultAuth = authenticateVaultRequest(bearer(token), journalConfig, journalStore.db);
+    expect("error" in vaultAuth).toBe(false);
+    if (!("error" in vaultAuth)) expect(vaultAuth.permission).toBe("full");
+
+    // /vaults (global metadata listing) uses authenticateGlobalRequest which
+    // scans every vault's DB. Since the token is in journal's DB, it must resolve.
     const global = authenticateGlobalRequest(bearer(token));
     expect("error" in global).toBe(false);
   });
 
-  // HTTP-level routing stand-in. Mirrors server.ts's vault-resolution step:
-  // unscoped `/api/*` resolves to the default vault; scoped `/vaults/X/api/*`
-  // extracts the name from the URL. After resolution both paths funnel into
-  // `authenticateVaultRequest` with that vault's config + DB. The earlier
-  // version of this test called `authenticateVaultRequest` twice with the same
-  // args and labelled the calls "scoped"/"unscoped" — tautological, because
-  // routing was never exercised. This variant drives the resolver from the
-  // URL, so the routing step is the thing under test.
+  // HTTP-level routing stand-in. Mirrors routing.ts: every vault-scoped path
+  // matches `/vault/<name>/...`, we look the vault up, then authenticate the
+  // request against that vault's DB.
   function dispatchAuthFromPath(path: string, req: Request): {
     status: number;
     permission?: string;
   } {
-    let vaultName: string;
-    if (path.startsWith("/vaults/")) {
-      vaultName = path.split("/")[2];
-    } else if (path.startsWith("/api/")) {
-      const gc = readGlobalConfig();
-      vaultName = gc.default_vault ?? "default";
-    } else {
-      return { status: 404 };
-    }
+    const match = path.match(/^\/vault\/([^/]+)(\/.*)?$/);
+    if (!match) return { status: 404 };
+    const vaultName = match[1];
     const vaultConfig = readVaultConfig(vaultName);
     if (!vaultConfig) return { status: 404 };
     const store = getVaultStore(vaultName);
@@ -136,77 +119,71 @@ describe("auth — default-vault routing coherence", () => {
     return { status: 200, permission: res.permission };
   }
 
-  test("routing coherence: unscoped and scoped /api/health accept a default-vault token identically", () => {
-    seedVault("default", { isDefault: true });
-    const token = mintTokenInVault("default");
-
-    // (a) unscoped /api/health with default-vault token
-    const unscoped = dispatchAuthFromPath("/api/health", bearer(token));
-    expect(unscoped.status).toBe(200);
-
-    // (b) scoped /vaults/default/api/health with the same token
-    const scoped = dispatchAuthFromPath("/vaults/default/api/health", bearer(token));
-    expect(scoped.status).toBe(200);
+  test("routing: /vault/<name>/api/health accepts a token minted in that vault", () => {
+    seedVault("journal");
+    const token = mintTokenInVault("journal");
 
-    // Both paths resolve the same vault → same permission level comes back.
-    expect(unscoped.permission).toBe(scoped.permission);
+    const result = dispatchAuthFromPath("/vault/journal/api/health", bearer(token));
+    expect(result.status).toBe(200);
+    expect(result.permission).toBe("full");
   });
 
-  test("routing coherence: scoped /vaults/X/api/health rejects a token issued for vault Y", () => {
+  test("routing: /vault/A/api/* rejects a token issued for vault B", () => {
     // The privilege-escalation barrier: a valid token for vault A must not
-    // authenticate at vault B's scoped endpoint, even though the URL is
-    // well-formed and the token itself is valid for *some* vault.
-    seedVault("default", { isDefault: true });
+    // authenticate at vault B's endpoint, even though the token is valid
+    // for some vault. This is the point of per-vault DBs.
+    seedVault("journal");
     seedVault("work");
     const workToken = mintTokenInVault("work");
 
-    const crossVault = dispatchAuthFromPath("/vaults/default/api/health", bearer(workToken));
+    const crossVault = dispatchAuthFromPath("/vault/journal/api/health", bearer(workToken));
     expect(crossVault.status).toBe(401);
   });
+
+  test("routing: /vault/<unknown> returns 404 (not 401)", () => {
+    seedVault("journal");
+    const token = mintTokenInVault("journal");
+    const result = dispatchAuthFromPath("/vault/nonexistent/api/health", bearer(token));
+    expect(result.status).toBe(404);
+  });
 });
 
-describe("auth — named-vault routing coherence", () => {
+describe("auth — cross-vault isolation", () => {
   test("token minted in a non-default vault authenticates via scoped and global paths", () => {
-    seedVault("default", { isDefault: true });
+    seedVault("journal", { isDefault: true });
     seedVault("work");
     const workToken = mintTokenInVault("work");
     const workConfig = readVaultConfig("work")!;
     const workStore = getVaultStore("work");
 
-    // Scoped `/vaults/work/api/*` — must resolve against work's DB.
     const scoped = authenticateVaultRequest(bearer(workToken), workConfig, workStore.db);
     expect("error" in scoped).toBe(false);
 
-    // Unified `/mcp` — global auth scans all vaults, must find it.
+    // Global auth scans every vault, must find the token in work's DB.
     const global = authenticateGlobalRequest(bearer(workToken));
     expect("error" in global).toBe(false);
   });
 
-  test("a work-vault token does NOT authenticate against the default vault's /api/*", () => {
-    // This is the correct isolation behavior: a token scoped to vault X has no
-    // business being accepted at endpoints that address vault Y. If this ever
-    // regressed, we'd have a privilege-escalation bug (read a different vault
-    // by just sending a valid token at the wrong URL).
-    seedVault("default", { isDefault: true });
+  test("a work-vault token does NOT authenticate against the journal vault", () => {
+    seedVault("journal", { isDefault: true });
     seedVault("work");
     const workToken = mintTokenInVault("work");
-    const defaultConfig = readVaultConfig("default")!;
-    const defaultStore = getVaultStore("default");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
 
-    const res = authenticateVaultRequest(bearer(workToken), defaultConfig, defaultStore.db);
+    const res = authenticateVaultRequest(bearer(workToken), journalConfig, journalStore.db);
     expect("error" in res).toBe(true);
   });
 });
 
 // ---------------------------------------------------------------------------
-// End-to-end: OAuth flow → resulting token authenticates at expected paths
+// End-to-end: OAuth flow → resulting token authenticates against its vault
 // ---------------------------------------------------------------------------
 
-describe("OAuth-minted tokens — cross-endpoint coherence", () => {
+describe("OAuth-minted tokens — per-vault coherence", () => {
   // These tests drive the OAuth handlers directly (no HTTP), then take the
-  // resulting access_token and verify it resolves at every endpoint that
-  // addresses its issuing vault. This is the key coherence invariant for
-  // Aaron's launch complaint.
+  // resulting access_token and verify it resolves at endpoints addressing
+  // its issuing vault — and only its issuing vault.
 
   async function runOAuthFlow(vaultName: string): Promise<string> {
     const store = getVaultStore(vaultName);
@@ -218,7 +195,7 @@ describe("OAuth-minted tokens — cross-endpoint coherence", () => {
 
     // 1. Register client
     const regRes = await handleRegister(
-      new Request("https://vault.test/oauth/register", {
+      new Request(`https://vault.test/vault/${vaultName}/oauth/register`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -234,7 +211,7 @@ describe("OAuth-minted tokens — cross-endpoint coherence", () => {
     const codeVerifier = crypto.randomBytes(32).toString("base64url");
     const codeChallenge = crypto.createHash("sha256").update(codeVerifier).digest("base64url");
     const authRes = await handleAuthorizePost(
-      new Request("https://vault.test/oauth/authorize", {
+      new Request(`https://vault.test/vault/${vaultName}/oauth/authorize`, {
         method: "POST",
         body: new URLSearchParams({
           action: "authorize",
@@ -253,7 +230,7 @@ describe("OAuth-minted tokens — cross-endpoint coherence", () => {
 
     // 3. Token exchange
     const tokRes = await handleToken(
-      new Request("https://vault.test/oauth/token", {
+      new Request(`https://vault.test/vault/${vaultName}/oauth/token`, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({
@@ -272,48 +249,40 @@ describe("OAuth-minted tokens — cross-endpoint coherence", () => {
     return tokBody.access_token;
   }
 
-  test("default-vault OAuth: token works at /api/*, /mcp, /vaults/default/api/*, /vaults/default/mcp", async () => {
-    seedVault("default", { isDefault: true });
-    const token = await runOAuthFlow("default");
-    const cfg = readVaultConfig("default")!;
-    const store = getVaultStore("default");
-
-    // `/api/*` — unscoped path resolves default vault, calls authenticateVaultRequest.
-    const apiUnscoped = authenticateVaultRequest(bearer(token), cfg, store.db);
-    expect("error" in apiUnscoped).toBe(false);
+  test("OAuth-minted token works at /vault/<name>/api/* and /vault/<name>/mcp", async () => {
+    seedVault("journal", { isDefault: true });
+    const token = await runOAuthFlow("journal");
+    const cfg = readVaultConfig("journal")!;
+    const store = getVaultStore("journal");
 
-    // `/vaults/default/api/*` — scoped path resolves same default, same DB, same call.
-    const apiScoped = authenticateVaultRequest(bearer(token), cfg, store.db);
-    expect("error" in apiScoped).toBe(false);
+    // /vault/journal/api/* and /vault/journal/mcp both reach this auth call.
+    const vaultAuth = authenticateVaultRequest(bearer(token), cfg, store.db);
+    expect("error" in vaultAuth).toBe(false);
 
-    // `/mcp` — unified endpoint uses authenticateGlobalRequest which scans all DBs.
-    const mcpUnscoped = authenticateGlobalRequest(bearer(token));
-    expect("error" in mcpUnscoped).toBe(false);
-
-    // `/vaults/default/mcp` — scoped MCP uses authenticateVaultRequest (same as api).
-    const mcpScoped = authenticateVaultRequest(bearer(token), cfg, store.db);
-    expect("error" in mcpScoped).toBe(false);
+    // /vaults (authenticated listing) uses authenticateGlobalRequest.
+    const global = authenticateGlobalRequest(bearer(token));
+    expect("error" in global).toBe(false);
   });
 
-  test("named-vault OAuth: token works at /vaults/X/api/*, /vaults/X/mcp, /mcp", async () => {
-    seedVault("default", { isDefault: true });
+  test("named-vault OAuth: token works for its vault, rejected by others", async () => {
+    seedVault("journal", { isDefault: true });
     seedVault("work");
     const token = await runOAuthFlow("work");
     const workCfg = readVaultConfig("work")!;
     const workStore = getVaultStore("work");
 
-    // Scoped endpoints addressing vault work — must resolve.
-    const apiScoped = authenticateVaultRequest(bearer(token), workCfg, workStore.db);
-    expect("error" in apiScoped).toBe(false);
+    // Valid at work's own endpoints.
+    const scoped = authenticateVaultRequest(bearer(token), workCfg, workStore.db);
+    expect("error" in scoped).toBe(false);
 
-    // Unified /mcp scans all vaults, must find the token in work's DB.
-    const mcpUnified = authenticateGlobalRequest(bearer(token));
-    expect("error" in mcpUnified).toBe(false);
+    // Global auth finds the token in work's DB.
+    const global = authenticateGlobalRequest(bearer(token));
+    expect("error" in global).toBe(false);
 
-    // Defensive: the same token is NOT usable against the default vault's /api/*.
-    const defaultCfg = readVaultConfig("default")!;
-    const defaultStore = getVaultStore("default");
-    const crossCheck = authenticateVaultRequest(bearer(token), defaultCfg, defaultStore.db);
+    // Isolation: the token is NOT usable against the journal vault.
+    const journalCfg = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+    const crossCheck = authenticateVaultRequest(bearer(token), journalCfg, journalStore.db);
     expect("error" in crossCheck).toBe(true);
   });
 });

package/src/auth.ts

@@ -21,10 +21,56 @@ import { resolveToken } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
 import type { Database } from "bun:sqlite";
 import { getVaultStore } from "./vault-store.ts";
+import { hasScope, legacyPermissionToScopes, SCOPE_ADMIN, SCOPE_READ, SCOPE_WRITE } from "./scopes.ts";
 
 /** Result of a successful auth check. */
 export interface AuthResult {
   permission: TokenPermission;
+  /** OAuth-standard scopes granted to this token. */
+  scopes: string[];
+  /**
+   * True iff scopes were derived from a legacy permission value (no `vault:*`
+   * scopes stored on the token row or legacy YAML key). Callers should log a
+   * one-time deprecation warning when they encounter `legacyDerived: true`.
+   */
+  legacyDerived: boolean;
+}
+
+/**
+ * Convert a legacy "read" | "full" permission into scopes + the legacyDerived
+ * flag. Used for legacy YAML key authentication paths and for tokens whose
+ * `scopes` column is still NULL.
+ */
+function legacyAuthResult(permission: TokenPermission): AuthResult {
+  return {
+    permission,
+    scopes: legacyPermissionToScopes(permission),
+    legacyDerived: true,
+  };
+}
+
+/**
+ * Guard: does the authenticated request carry the required scope?
+ * Uses `hasScope` inheritance: admin ⊇ write ⊇ read.
+ */
+export function requireScope(auth: AuthResult, required: string): boolean {
+  return hasScope(auth.scopes, required);
+}
+
+// One-shot deprecation warning tracker, keyed by token hash / legacy label so
+// we don't spam the log on every request.
+const warnedLegacyTokens = new Set<string>();
+
+/**
+ * Log a one-time deprecation warning for legacy-derived auth results.
+ * Safe to call on every request — dedupes internally by cache key.
+ */
+export function warnLegacyOnce(cacheKey: string, context: string): void {
+  if (warnedLegacyTokens.has(cacheKey)) return;
+  warnedLegacyTokens.add(cacheKey);
+  console.warn(
+    `[scopes] legacy permission-based auth used (${context}); migrate to vault:read / vault:write / vault:admin scopes. This compat shim will be removed after the next release.`,
+  );
 }
 
 /** Read-only tools (the only tools allowed for "read" permission). */
@@ -33,7 +79,6 @@ const READ_TOOLS = new Set([
   "list-tags",
   "find-path",
   "vault-info",
-  "list-vaults",
 ]);
 
 /** Check if a tool call is allowed for a given permission level. */
@@ -100,7 +145,14 @@ export function authenticateVaultRequest(
     try {
       const resolved = resolveToken(vaultDb, key);
       if (resolved) {
-        return { permission: resolved.permission };
+        if (resolved.legacyDerived) {
+          warnLegacyOnce(`vault-token:${vaultConfig.name ?? ""}`, "vault token without scopes column");
+        }
+        return {
+          permission: resolved.permission,
+          scopes: resolved.scopes,
+          legacyDerived: resolved.legacyDerived,
+        };
       }
     } catch {
       // Token table might not exist yet — fall through to legacy auth
@@ -111,7 +163,8 @@ export function authenticateVaultRequest(
   const vaultKey = validateKey(vaultConfig.api_keys, key);
   if (vaultKey) {
     try { writeVaultConfig(vaultConfig); } catch {}
-    return { permission: vaultKey.scope === "read" ? "read" : "full" };
+    warnLegacyOnce(`yaml-vault:${vaultKey.key_hash}`, "vault.yaml api_keys");
+    return legacyAuthResult(vaultKey.scope === "read" ? "read" : "full");
   }
 
   // Legacy: check global keys from config.yaml
@@ -120,7 +173,8 @@ export function authenticateVaultRequest(
     const globalKey = validateKey(globalConfig.api_keys, key);
     if (globalKey) {
       try { writeGlobalConfig(globalConfig); } catch {}
-      return { permission: globalKey.scope === "read" ? "read" : "full" };
+      warnLegacyOnce(`yaml-global:${globalKey.key_hash}`, "config.yaml api_keys");
+      return legacyAuthResult(globalKey.scope === "read" ? "read" : "full");
     }
   }
 
@@ -147,7 +201,8 @@ export function authenticateGlobalRequest(
     const matched = validateKey(globalConfig.api_keys, key);
     if (matched) {
       try { writeGlobalConfig(globalConfig); } catch {}
-      return { permission: matched.scope === "read" ? "read" : "full" };
+      warnLegacyOnce(`yaml-global:${matched.key_hash}`, "config.yaml api_keys");
+      return legacyAuthResult(matched.scope === "read" ? "read" : "full");
     }
   }
 
@@ -159,7 +214,14 @@ export function authenticateGlobalRequest(
       const store = getVaultStore(vaultName);
       const resolved = resolveToken(store.db, key);
       if (resolved) {
-        return { permission: resolved.permission };
+        if (resolved.legacyDerived) {
+          warnLegacyOnce(`vault-token:${vaultName}`, "vault token without scopes column");
+        }
+        return {
+          permission: resolved.permission,
+          scopes: resolved.scopes,
+          legacyDerived: resolved.legacyDerived,
+        };
       }
     } catch {
       // Skip vaults that can't be opened

package/src/backup-launchd.ts

@@ -35,7 +35,7 @@ export const BACKUP_PLIST_PATH = join(homedir(), "Library", "LaunchAgents", `${B
  * Resolve the CLI path the backup job should invoke. Sibling-to-server.ts
  * — we reuse `resolveServerPath()`'s dirname-of-module approach so a move
  * of the repo updates both the daemon and the backup agent on the next
- * `parachute vault backup --schedule <f>` run.
+ * `parachute-vault backup --schedule <f>` run.
  */
 export function resolveCliPath(): string {
   const serverPath = resolveServerPath(); // <repo>/src/server.ts

package/src/backup.test.ts

@@ -604,7 +604,7 @@ describe("backup — checkDestinationWritable", () => {
 });
 
 // ---------------------------------------------------------------------------
-// CLI integration — `parachute vault backup` + `backup status`
+// CLI integration — `parachute-vault backup` + `backup status`
 // ---------------------------------------------------------------------------
 
 describe("CLI — vault backup", () => {

package/src/backup.ts

@@ -24,8 +24,8 @@ import { tmpdir } from "os";
 import { Database } from "bun:sqlite";
 import { $ } from "bun";
 import {
-  CONFIG_DIR,
-  VAULTS_DIR,
+  VAULT_HOME,
+  DATA_DIR,
   GLOBAL_CONFIG_PATH,
   listVaults,
   vaultDir,
@@ -105,33 +105,34 @@ export function parseBackupFilename(name: string): { timestamp: string } | null
 // ---------------------------------------------------------------------------
 
 /**
- * Take a `VACUUM INTO` snapshot of every `.db` file we can find in
- * `CONFIG_DIR`:
+ * Take a `VACUUM INTO` snapshot of every `.db` file we can find under
+ * `VAULT_HOME`:
  *
- *   1. Top-level `~/.parachute/*.db` — covers legacy pre-multi-vault installs
- *      (e.g. `daily.db`) and any user-placed sidecar DBs. Hits include `.bak`
- *      copies, which we intentionally skip since they're already static
- *      snapshots that `cp` would duplicate faster than VACUUM.
+ *   1. Top-level `~/.parachute/vault/*.db` — covers legacy pre-multi-vault
+ *      installs (e.g. `daily.db`) and any user-placed sidecar DBs. Hits
+ *      include `.bak` copies, which we intentionally skip since they're
+ *      already static snapshots that `cp` would duplicate faster than
+ *      VACUUM.
  *   2. Per-vault `vaults/<name>/vault.db` via `listVaults()`.
  *
  * Returns the staging directory so the next stage can tar it up.
  */
 export async function stageSnapshot(opts?: {
-  /** Override config dir. Tests point this at a tempdir. */
+  /** Override vault-home dir. Tests point this at a tempdir. */
   configDir?: string;
   /** Override vaults dir. Tests point this at a tempdir's vaults/. */
   vaultsDir?: string;
   /** Override staging dir. Tests pass a tempdir to inspect contents. */
   stagingDir?: string;
 }): Promise<{ stagingDir: string; contents: TarballContents }> {
-  const configDir = opts?.configDir ?? CONFIG_DIR;
-  const vaultsDir = opts?.vaultsDir ?? VAULTS_DIR;
+  const configDir = opts?.configDir ?? VAULT_HOME;
+  const vaultsDir = opts?.vaultsDir ?? DATA_DIR;
   const stagingDir = opts?.stagingDir ?? mkdtempSync(join(tmpdir(), "parachute-backup-"));
 
   const dbSnapshots: string[] = [];
   const configFiles: string[] = [];
 
-  // 1. Top-level *.db files in CONFIG_DIR. Skip .bak and other non-live files.
+  // 1. Top-level *.db files in VAULT_HOME. Skip .bak and other non-live files.
   if (existsSync(configDir)) {
     for (const entry of readdirSync(configDir)) {
       if (!entry.endsWith(".db")) continue;
@@ -210,7 +211,7 @@ function vacuumInto(srcDbPath: string, destPath: string): void {
 
 /**
  * Small internal helper so tests can point us at a vaults dir that isn't
- * the global VAULTS_DIR without plumbing the override through `listVaults()`.
+ * the global DATA_DIR without plumbing the override through `listVaults()`.
  */
 function listVaultsIn(dir: string): string[] {
   if (!existsSync(dir)) return [];
@@ -552,7 +553,7 @@ export function pruneRetention(dir: string, policy: RetentionPolicy): number {
 
 /**
  * Run a single backup end-to-end: stage, tar, ship to destinations. This is
- * what `parachute vault backup` and the launchd-scheduled job both invoke.
+ * what `parachute-vault backup` and the launchd-scheduled job both invoke.
  *
  * The staging dir is cleaned up on exit; the tarball itself is kept (copied
  * to each destination) and also left behind in the staging dir's parent —
@@ -583,7 +584,7 @@ export async function runBackup(opts?: {
     const results = await writeToDestinations(tarballPath, backup.destinations, backup.retention);
 
     // Record last-backup metadata for `status`. Stored in a small JSON file
-    // inside CONFIG_DIR so it survives across daemons and doesn't require
+    // inside VAULT_HOME so it survives across daemons and doesn't require
     // plumbing through config.yaml (which is hand-edited by users).
     recordLastBackup({
       timestamp,
@@ -613,12 +614,12 @@ export interface LastBackupMeta {
 }
 
 export function lastBackupPath(configDir?: string): string {
-  return join(configDir ?? CONFIG_DIR, "backup-last.json");
+  return join(configDir ?? VAULT_HOME, "backup-last.json");
 }
 
 function recordLastBackup(meta: LastBackupMeta, configDir?: string): void {
   try {
-    mkdirSync(configDir ?? CONFIG_DIR, { recursive: true });
+    mkdirSync(configDir ?? VAULT_HOME, { recursive: true });
     Bun.write(lastBackupPath(configDir), JSON.stringify(meta, null, 2) + "\n");
   } catch {
     // Non-fatal — losing last-run metadata is a UX regression, not a data loss.

package/src/bind.test.ts

@@ -0,0 +1,28 @@
+import { describe, test, expect } from "bun:test";
+import { resolveBindHostname } from "./bind.ts";
+
+describe("resolveBindHostname", () => {
+  test("defaults to 127.0.0.1 when VAULT_BIND is unset", () => {
+    expect(resolveBindHostname({})).toBe("127.0.0.1");
+  });
+
+  test("honors VAULT_BIND=0.0.0.0 for Docker / LAN", () => {
+    expect(resolveBindHostname({ VAULT_BIND: "0.0.0.0" })).toBe("0.0.0.0");
+  });
+
+  test("honors a specific interface IP in VAULT_BIND", () => {
+    expect(resolveBindHostname({ VAULT_BIND: "10.0.0.5" })).toBe("10.0.0.5");
+  });
+
+  test("treats empty VAULT_BIND as unset", () => {
+    expect(resolveBindHostname({ VAULT_BIND: "" })).toBe("127.0.0.1");
+  });
+
+  test("treats whitespace-only VAULT_BIND as unset", () => {
+    expect(resolveBindHostname({ VAULT_BIND: "   " })).toBe("127.0.0.1");
+  });
+
+  test("trims surrounding whitespace", () => {
+    expect(resolveBindHostname({ VAULT_BIND: "  127.0.0.1  " })).toBe("127.0.0.1");
+  });
+});

package/src/bind.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve the hostname the HTTP server binds to.
+ *
+ * Default is `127.0.0.1` — loopback-only at the socket level. The auth gate
+ * protects vault data regardless, but listening only on loopback is a
+ * defense-in-depth default that matches the threat model in
+ * `docs/auth-model.md` §4. Supported remote-access paths (Tailscale Serve,
+ * Cloudflare Tunnel) proxy from loopback, so the default does not break any
+ * documented exposure path.
+ *
+ * Escape hatch: `VAULT_BIND`. Set to `0.0.0.0` for Docker bridge networking
+ * or an intentional LAN setup; set to a specific interface IP for
+ * multi-homed hosts. Empty/whitespace values are treated as unset.
+ */
+export function resolveBindHostname(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.VAULT_BIND?.trim();
+  if (override) return override;
+  return "127.0.0.1";
+}