@openparachute/vault 0.5.3-rc.3 → 0.6.0

package/src/triggers-api.ts

@@ -0,0 +1,295 @@
+/**
+ * Runtime trigger-registration REST API (frictionless-channel-setup PR 1).
+ *
+ * Mounts under `/vault/<v>/api/triggers`, ADMIN-scoped. Registering a webhook
+ * trigger exfiltrates note data to an arbitrary URL — that's an admin
+ * capability, not `write` — so every method here gates on `vault:admin`
+ * (or the narrowed `vault:<v>:admin`). The gate is enforced in `handleTriggers`
+ * itself rather than the method-based verb gate in routing.ts, because a GET
+ * here must still require admin (read is too weak).
+ *
+ *   POST   /api/triggers        — upsert {name, events, when, action};
+ *                                 validate webhook URL; persist; (re-)register
+ *                                 live on the shared hook registry, vault-scoped.
+ *   GET    /api/triggers        — list this vault's persisted triggers.
+ *   DELETE /api/triggers/:name  — unregister the live hook + delete the row.
+ *
+ * A process-wide registry of unregister-fns keyed by (vault, name) lets
+ * POST-replace and DELETE unwind the prior live hook before re-registering.
+ */
+
+import type { SqliteStore } from "../core/src/store.ts";
+import { defaultHookRegistry } from "../core/src/hooks.ts";
+import {
+  upsertTrigger,
+  listTriggers,
+  getTrigger,
+  deleteTrigger,
+  loadAllTriggers,
+  type StoredTrigger,
+  type TriggerInput,
+} from "../core/src/triggers-store.ts";
+import { registerVaultTrigger } from "./triggers.ts";
+import { hasScopeForVault, SCOPE_ADMIN } from "./scopes.ts";
+import type { AuthResult } from "./auth.ts";
+
+// ---------------------------------------------------------------------------
+// Live registry of unregister-fns, keyed by `${vault}${name}` (SPACE
+// separator). Neither vault names (validated on create) nor trigger names
+// (NAME_RE below — [A-Za-z0-9][A-Za-z0-9_-]*) admit a space, so the composite
+// key can't collide. Survives across requests in the long-lived server
+// process; on boot it's repopulated by `loadVaultTriggers`.
+// ---------------------------------------------------------------------------
+
+const liveTriggers = new Map<string, () => void>();
+
+function liveKey(vaultName: string, triggerName: string): string {
+  return `${vaultName}${triggerName}`;
+}
+
+/** Unregister + forget any live hook for (vault, name). No-op if absent. */
+function unwindLiveTrigger(vaultName: string, triggerName: string): void {
+  const key = liveKey(vaultName, triggerName);
+  const fn = liveTriggers.get(key);
+  if (fn) {
+    try {
+      fn();
+    } catch {
+      // unregister is a pure array splice — failures shouldn't happen, but a
+      // throw here must not block delete/replace. Swallow + drop the entry.
+    }
+    liveTriggers.delete(key);
+  }
+}
+
+/**
+ * Register a stored trigger live on the shared hook registry, vault-scoped,
+ * replacing any prior same-(vault,name) hook. Exported for the boot path.
+ */
+export function registerLiveTrigger(vaultName: string, trigger: StoredTrigger): void {
+  unwindLiveTrigger(vaultName, trigger.name);
+  const unregister = registerVaultTrigger(defaultHookRegistry, trigger, vaultName);
+  liveTriggers.set(liveKey(vaultName, trigger.name), unregister);
+}
+
+/**
+ * Boot loader: register every persisted trigger for a vault, scoped to it.
+ * Idempotent — replaces any existing live registration per (vault, name).
+ * Called for each vault at server start (alongside config.yaml triggers).
+ */
+export function loadVaultTriggers(vaultName: string, store: SqliteStore): number {
+  const triggers = loadAllTriggers(store.db);
+  for (const t of triggers) {
+    registerLiveTrigger(vaultName, t);
+  }
+  return triggers.length;
+}
+
+/** Test-only: clear the live registry (unregistering each hook). */
+export function clearLiveTriggers(): void {
+  for (const [, fn] of liveTriggers) {
+    try {
+      fn();
+    } catch {
+      /* swallow */
+    }
+  }
+  liveTriggers.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+function validateInput(body: unknown):
+  | { ok: true; input: TriggerInput }
+  | { ok: false; message: string } {
+  if (typeof body !== "object" || body === null) {
+    return { ok: false, message: "request body must be a JSON object" };
+  }
+  const b = body as Record<string, unknown>;
+
+  if (typeof b.name !== "string" || !NAME_RE.test(b.name)) {
+    return {
+      ok: false,
+      message:
+        "`name` is required and must match [A-Za-z0-9][A-Za-z0-9_-]* (no whitespace, NUL, or leading punctuation)",
+    };
+  }
+
+  // events — optional; default applied at the store. When present, must be a
+  // subset of {created, updated}.
+  let events: Array<"created" | "updated"> | undefined;
+  if (b.events !== undefined) {
+    if (
+      !Array.isArray(b.events) ||
+      !b.events.every((e) => e === "created" || e === "updated")
+    ) {
+      return { ok: false, message: "`events` must be an array of 'created'/'updated'" };
+    }
+    events = b.events as Array<"created" | "updated">;
+  }
+
+  if (typeof b.when !== "object" || b.when === null || Array.isArray(b.when)) {
+    return { ok: false, message: "`when` is required and must be an object" };
+  }
+
+  if (typeof b.action !== "object" || b.action === null || Array.isArray(b.action)) {
+    return { ok: false, message: "`action` is required and must be an object" };
+  }
+  const action = b.action as Record<string, unknown>;
+  if (typeof action.webhook !== "string" || action.webhook.length === 0) {
+    return { ok: false, message: "`action.webhook` is required and must be a string URL" };
+  }
+  // Reuse the same http/https validation registerTriggers does, but fail the
+  // request here (400) rather than silently skipping at registration time.
+  try {
+    const url = new URL(action.webhook);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      return {
+        ok: false,
+        message: `\`action.webhook\` must use http or https (got ${url.protocol})`,
+      };
+    }
+  } catch {
+    return { ok: false, message: `\`action.webhook\` is not a valid URL: ${action.webhook}` };
+  }
+  if (action.auth !== undefined) {
+    if (typeof action.auth !== "object" || action.auth === null || Array.isArray(action.auth)) {
+      return { ok: false, message: "`action.auth` must be an object when present" };
+    }
+    // `bearer` is the only auth field today. When present it MUST be a
+    // non-empty string — a non-string (number/object/false/null) would either
+    // silently no-op or serialize as `[object Object]` into the Authorization
+    // header at fire time. Reject at the door.
+    const auth = action.auth as Record<string, unknown>;
+    if (auth.bearer !== undefined && (typeof auth.bearer !== "string" || auth.bearer.length === 0)) {
+      return {
+        ok: false,
+        message: "`action.auth.bearer` must be a non-empty string when present",
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    input: {
+      name: b.name,
+      events,
+      when: b.when as TriggerInput["when"],
+      action: b.action as TriggerInput["action"],
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Response shaping
+// ---------------------------------------------------------------------------
+
+/**
+ * Redact the webhook auth secret before serializing a trigger into ANY HTTP
+ * response. A registration credential (`action.auth.bearer`, typically a hub
+ * JWT) is a one-way input: the caller supplies it, but it must never be
+ * readable back over GET (or echoed by POST). We keep the `bearer` KEY present
+ * — set to the sentinel `"[REDACTED]"` — so clients can still see that auth IS
+ * configured, just not its value.
+ *
+ * Response-only: the DB row and the live webhook-fire path keep the real
+ * bearer (verified by the per-vault firing test, which asserts the fired
+ * request still carries the real `Authorization: Bearer <token>`).
+ */
+const REDACTED = "[REDACTED]";
+
+export function redactTrigger(t: StoredTrigger): StoredTrigger {
+  const bearer = t.action.auth?.bearer;
+  if (bearer === undefined) return t;
+  return {
+    ...t,
+    action: {
+      ...t.action,
+      auth: { ...t.action.auth, bearer: REDACTED },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// HTTP handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle `/api/triggers` and `/api/triggers/:name`. `subPath` is the portion
+ * AFTER `/triggers` (e.g. "" for the collection, "/my-trigger" for an item).
+ * Admin-scoped — the gate lives here (not the routing.ts verb gate) so GET
+ * also requires admin.
+ */
+export async function handleTriggers(
+  req: Request,
+  store: SqliteStore,
+  subPath: string,
+  vaultName: string,
+  auth: AuthResult,
+): Promise<Response> {
+  // Admin gate — every method. A webhook trigger exfiltrates note data, so
+  // even listing/reading is an admin capability here.
+  if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+    return Response.json(
+      {
+        error: "Forbidden",
+        error_type: "insufficient_scope",
+        message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace(
+          "vault:",
+          `vault:${vaultName}:`,
+        )}').`,
+        required_scope: SCOPE_ADMIN,
+        granted_scopes: auth.scopes,
+      },
+      { status: 403 },
+    );
+  }
+
+  const itemName = subPath.startsWith("/") ? decodeURIComponent(subPath.slice(1)) : "";
+
+  // Collection: /api/triggers
+  if (itemName === "") {
+    if (req.method === "GET") {
+      return Response.json({ triggers: listTriggers(store.db).map(redactTrigger) });
+    }
+    if (req.method === "POST") {
+      let body: unknown;
+      try {
+        body = await req.json();
+      } catch {
+        return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+      }
+      const validated = validateInput(body);
+      if (!validated.ok) {
+        return Response.json({ error: validated.message }, { status: 400 });
+      }
+      // Persist (upsert by name) then (re-)register live, vault-scoped. The
+      // live registration replaces any prior same-name hook for this vault.
+      const stored = upsertTrigger(store.db, validated.input);
+      registerLiveTrigger(vaultName, stored);
+      return Response.json({ trigger: redactTrigger(stored) }, { status: 200 });
+    }
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
+  // Item: /api/triggers/:name
+  if (req.method === "DELETE") {
+    const existed = getTrigger(store.db, itemName) !== null;
+    unwindLiveTrigger(vaultName, itemName);
+    const removed = deleteTrigger(store.db, itemName);
+    if (!existed && !removed) {
+      return Response.json({ error: "Not found", name: itemName }, { status: 404 });
+    }
+    return Response.json({ deleted: itemName });
+  }
+  if (req.method === "GET") {
+    const t = getTrigger(store.db, itemName);
+    if (!t) return Response.json({ error: "Not found", name: itemName }, { status: 404 });
+    return Response.json({ trigger: redactTrigger(t) });
+  }
+  return Response.json({ error: "Method not allowed" }, { status: 405 });
+}

package/src/triggers.ts

@@ -31,12 +31,25 @@ import crypto from "node:crypto";
 import type { Note, Store, Attachment } from "../core/src/types.ts";
 import type { HookRegistry, HookEvent, NoteHookPayload } from "../core/src/hooks.ts";
 import type { TriggerConfig, TriggerWhen } from "./config.ts";
+import type { StoredTrigger } from "../core/src/triggers-store.ts";
 import { getVaultNameForStore } from "./vault-store.ts";
 import { assetsDir } from "./routes.ts";
 import { appendContextPart, fetchContextEntries, type ContextPayload } from "./context.ts";
 
 const DEFAULT_TIMEOUT = 60_000;
 
+/**
+ * Build the optional auth headers for a trigger's webhook POST. When
+ * `action.auth.bearer` is set we send `Authorization: Bearer <bearer>` (the
+ * JWT webhook-auth path, frictionless-channel-setup PR 1). Returns an empty
+ * object otherwise — back-compat with webhook URLs carrying a `?secret=`
+ * query param, which is unaffected by this.
+ */
+function buildAuthHeaders(action: TriggerConfig["action"]): Record<string, string> {
+  const bearer = action.auth?.bearer;
+  return bearer ? { Authorization: `Bearer ${bearer}` } : {};
+}
+
 export interface WebhookResponse {
   content?: string;
   metadata?: Record<string, unknown>;
@@ -163,11 +176,12 @@ async function dispatchJson(
   existingMeta: Record<string, unknown>,
   hookEvent: HookEvent | undefined,
   context: ContextPayload | null,
+  authHeaders: Record<string, string>,
   signal: AbortSignal,
 ): Promise<DispatchResult> {
   const resp = await fetch(url, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...authHeaders },
     body: JSON.stringify({
       trigger: trigger.name,
       event: hookEvent ?? "updated",
@@ -207,6 +221,7 @@ async function dispatchAttachment(
   attachments: Attachment[],
   store: Store,
   context: ContextPayload | null,
+  authHeaders: Record<string, string>,
   signal: AbortSignal,
 ): Promise<DispatchResult> {
   const assetsRoot = resolveAssetsDir(store);
@@ -223,7 +238,9 @@ async function dispatchAttachment(
   form.append("file", file);
   if (context) appendContextPart(form, context);
 
-  const resp = await fetch(url, { method: "POST", body: form, signal });
+  // multipart boundary is set by fetch from the FormData body; only the auth
+  // header is added here (no Content-Type — that would clobber the boundary).
+  const resp = await fetch(url, { method: "POST", body: form, headers: authHeaders, signal });
   if (!resp.ok) {
     throw new Error(`webhook returned ${resp.status}: ${await resp.text().catch(() => "")}`);
   }
@@ -244,6 +261,7 @@ async function dispatchContent(
   url: string,
   note: Note,
   store: Store,
+  authHeaders: Record<string, string>,
   signal: AbortSignal,
 ): Promise<DispatchResult> {
   if (!note.content || !note.content.trim()) {
@@ -252,7 +270,7 @@ async function dispatchContent(
 
   const resp = await fetch(url, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...authHeaders },
     body: JSON.stringify({ input: note.content }),
     signal,
   });
@@ -280,15 +298,40 @@ async function dispatchContent(
 // Registration
 // ---------------------------------------------------------------------------
 
+export interface RegisterTriggersOptions {
+  logger?: { error: (...args: unknown[]) => void; info?: (...args: unknown[]) => void };
+  /**
+   * When set, the registered handler early-returns unless the firing event's
+   * vault (resolved via `getVaultNameForStore(store)`) equals this value.
+   * Used by the runtime per-vault trigger system: a trigger registered for
+   * vault A never acts on a vault-B note event. `config.yaml` triggers omit
+   * this and stay global (fire for every vault). See `registerVaultTrigger`.
+   */
+  vaultName?: string;
+}
+
 /**
  * Register all triggers from config onto a HookRegistry.
  * Returns a cleanup function that unregisters all hooks.
+ *
+ * `opts.logger` defaults to console. `opts.vaultName`, when set, scopes every
+ * registered handler to that vault (early-return on mismatch) — the
+ * load-bearing isolation for runtime per-vault triggers. A plain logger object
+ * is still accepted as the third arg for back-compat with existing callers.
  */
 export function registerTriggers(
   hooks: HookRegistry,
   triggers: TriggerConfig[],
-  logger: { error: (...args: unknown[]) => void; info?: (...args: unknown[]) => void } = console,
+  optsOrLogger: RegisterTriggersOptions | { error: (...args: unknown[]) => void; info?: (...args: unknown[]) => void } = {},
 ): () => void {
+  // Back-compat: callers historically passed a bare logger as the 3rd arg.
+  // Distinguish it from the new options object by the presence of `error`.
+  const opts: RegisterTriggersOptions =
+    optsOrLogger && typeof (optsOrLogger as { error?: unknown }).error === "function"
+      ? { logger: optsOrLogger as RegisterTriggersOptions["logger"] }
+      : (optsOrLogger as RegisterTriggersOptions);
+  const logger = opts.logger ?? console;
+  const scopedVault = opts.vaultName;
   const unregisters: Array<() => void> = [];
 
   for (const trigger of triggers) {
@@ -310,6 +353,7 @@ export function registerTriggers(
     const renderedKey = `${trigger.name}_rendered_at`;
     const timeout = trigger.action.timeout ?? DEFAULT_TIMEOUT;
     const sendMode = trigger.action.send ?? "json";
+    const authHeaders = buildAuthHeaders(trigger.action);
 
     const unregister = hooks.onNote({
       name: trigger.name,
@@ -322,6 +366,16 @@ export function registerTriggers(
         return predicate(payload as Note);
       },
       handler: async (payload: NoteHookPayload, store: Store, hookEvent?: HookEvent) => {
+        // Per-vault scoping (runtime triggers): the process-wide hook registry
+        // is shared across every vault, so a trigger registered for vault A
+        // would otherwise fire on vault-B note events too. Resolve the firing
+        // store's vault and early-return on mismatch. `config.yaml` triggers
+        // leave `scopedVault` undefined and stay global. This is the
+        // load-bearing isolation check — see the per-vault firing test.
+        if (scopedVault !== undefined && getVaultNameForStore(store) !== scopedVault) {
+          return;
+        }
+
         // Same shape contract as the predicate — triggers don't
         // subscribe to deleted events, so narrow back to Note.
         const note = payload as Note;
@@ -357,16 +411,16 @@ export function registerTriggers(
           let result: DispatchResult;
           switch (sendMode) {
             case "attachment":
-              result = await dispatchAttachment(trigger.action.webhook, note, attachments, store, context, controller.signal);
+              result = await dispatchAttachment(trigger.action.webhook, note, attachments, store, context, authHeaders, controller.signal);
               break;
             case "content":
               // send=content is pure TTS (audio out); vault context makes no
               // sense here and would confuse the server contract.
-              result = await dispatchContent(trigger.action.webhook, note, store, controller.signal);
+              result = await dispatchContent(trigger.action.webhook, note, store, authHeaders, controller.signal);
               break;
             case "json":
             default:
-              result = await dispatchJson(trigger.action.webhook, trigger, note, attachments, existingMeta, hookEvent, context, controller.signal);
+              result = await dispatchJson(trigger.action.webhook, trigger, note, attachments, existingMeta, hookEvent, context, authHeaders, controller.signal);
               break;
           }
           webhookResult = result.webhookResult;
@@ -438,3 +492,35 @@ export function registerTriggers(
 
   return () => unregisters.forEach((fn) => fn());
 }
+
+/**
+ * Convert a persisted `StoredTrigger` (core/src/triggers-store.ts) into the
+ * `TriggerConfig` shape `registerTriggers` consumes. The two are structurally
+ * compatible — this is a thin, explicit bridge so the type boundary between
+ * core (storage) and src (config types) stays visible.
+ */
+export function storedTriggerToConfig(t: StoredTrigger): TriggerConfig {
+  return {
+    name: t.name,
+    events: t.events,
+    when: t.when as TriggerWhen,
+    action: t.action as unknown as TriggerConfig["action"],
+  };
+}
+
+/**
+ * Register a single runtime trigger scoped to `vaultName`. The handler
+ * early-returns unless the firing store resolves to `vaultName` (see the
+ * scoping check in `registerTriggers`), so a trigger registered for vault A
+ * never acts on a vault-B event. Otherwise identical to a config.yaml trigger
+ * — same two-phase claim + webhook fire. Returns an unregister function the
+ * caller keys by (vault, name) so POST-replace and DELETE can unwind it.
+ */
+export function registerVaultTrigger(
+  hooks: HookRegistry,
+  trigger: StoredTrigger,
+  vaultName: string,
+  logger: { error: (...args: unknown[]) => void; info?: (...args: unknown[]) => void } = console,
+): () => void {
+  return registerTriggers(hooks, [storedTriggerToConfig(trigger)], { logger, vaultName });
+}

package/src/vault-create.test.ts

@@ -28,11 +28,18 @@ function runCli(
   args: string[],
   env: Record<string, string>,
 ): { exitCode: number; stdout: string; stderr: string } {
+  // Hermetic: don't inherit the dev/CI box's PARACHUTE_HUB_ORIGIN. A leaked
+  // origin makes `detectHubPresence`'s rule-1 (configured-origin) short-circuit
+  // to "hub present" with no probe, flipping the no-hub guidance copy to the
+  // "admin wizard" variant — a CI flake when the runner env has it set. Tests
+  // that genuinely want a hub origin pass it explicitly via `env`.
+  const baseEnv: Record<string, string | undefined> = { ...process.env };
+  delete baseEnv.PARACHUTE_HUB_ORIGIN;
   const proc = Bun.spawnSync({
     cmd: ["bun", CLI, ...args],
     stdout: "pipe",
     stderr: "pipe",
-    env: { ...process.env, ...env },
+    env: { ...baseEnv, ...env },
   });
   return {
     exitCode: proc.exitCode ?? -1,
@@ -150,6 +157,33 @@ describe("vault create --json", () => {
     expect(stderr).toContain("lowercase");
   });
 
+  test("reserved names (list/new/assets/admin) are rejected at create", () => {
+    // Consolidated reserved set (2026-06-09 hub-module-boundary B2). Before
+    // the consolidation cmdCreate hardcoded only "list" — `admin` could enter
+    // through `create` and capture the daemon-level /vault/admin mount.
+    for (const reserved of ["list", "new", "assets", "admin"]) {
+      const { exitCode, stdout, stderr } = runCli(
+        ["create", reserved, "--json"],
+        { PARACHUTE_HOME: home },
+      );
+      expect(exitCode).not.toBe(0);
+      expect(stdout).toBe("");
+      expect(stderr).toContain("reserved");
+      // The vault must not have been created.
+      expect(existsSync(join(home, "vault", "data", reserved))).toBe(false);
+    }
+  });
+
+  test("near-misses of reserved names (adminx, admin2) create fine", () => {
+    for (const name of ["adminx", "admin2"]) {
+      const { exitCode, stdout } = runCli(["create", name, "--json"], {
+        PARACHUTE_HOME: home,
+      });
+      expect(exitCode).toBe(0);
+      expect(JSON.parse(stdout.trim()).name).toBe(name);
+    }
+  });
+
   test("duplicate name in --json mode errors on stderr and exits non-zero", () => {
     runCli(["create", "dup", "--json"], { PARACHUTE_HOME: home });
     const { exitCode, stdout, stderr } = runCli(

package/src/vault-name.test.ts

@@ -7,7 +7,13 @@
  */
 
 import { describe, test, expect } from "bun:test";
-import { validateVaultName, decideInitVaultName, resolveFirstBootVaultName } from "./vault-name.ts";
+import {
+  RESERVED_VAULT_NAMES,
+  decideInitVaultName,
+  reservedNameSquatWarnings,
+  resolveFirstBootVaultName,
+  validateVaultName,
+} from "./vault-name.ts";
 
 describe("validateVaultName", () => {
   describe("accepts", () => {
@@ -69,12 +75,29 @@ describe("validateVaultName", () => {
       }
     });
 
-    test("reserved name 'list'", () => {
-      const result = validateVaultName("list");
+    // The consolidated reserved set (2026-06-09 hub-module-boundary B2):
+    // `list` (legacy), `new` + `assets` (hub SPA route collisions), `admin`
+    // (the daemon-level /vault/admin multi-vault mount). Kept in lockstep
+    // with hub's RESERVED_VAULT_NAMES.
+    test.each(["list", "new", "assets", "admin"])("reserved name '%s'", (name) => {
+      const result = validateVaultName(name);
       expect(result.ok).toBe(false);
       if (!result.ok) expect(result.error).toContain("reserved");
     });
 
+    test("the exported set carries exactly the four consolidated names", () => {
+      expect([...RESERVED_VAULT_NAMES].sort()).toEqual(["admin", "assets", "list", "new"]);
+    });
+
+    test.each(["adminx", "admin2", "newer", "asset", "listing"])(
+      "near-miss '%s' is NOT reserved",
+      (name) => {
+        const result = validateVaultName(name);
+        expect(result.ok).toBe(true);
+        if (result.ok) expect(result.name).toBe(name);
+      },
+    );
+
     test("single character (below 2-char min)", () => {
       const result = validateVaultName("a");
       expect(result.ok).toBe(false);
@@ -95,6 +118,41 @@ describe("validateVaultName", () => {
   });
 });
 
+describe("reservedNameSquatWarnings", () => {
+  test("fires for a squatted 'admin' vault, naming the shadowing + recovery", () => {
+    const warnings = reservedNameSquatWarnings(["default", "admin"]);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('vault "admin"');
+    expect(warnings[0]).toContain("shadowed");
+    expect(warnings[0]).toContain("/vault/admin/*");
+    // Recovery procedure (no rename command exists): export → create →
+    // import → remove.
+    expect(warnings[0]).toContain("export");
+    expect(warnings[0]).toContain("create <newname>");
+    expect(warnings[0]).toContain("import");
+    expect(warnings[0]).toContain("remove admin --yes");
+  });
+
+  test("fires once per squatted name — admin + new + assets all warned", () => {
+    const warnings = reservedNameSquatWarnings(["admin", "new", "assets", "ok"]);
+    expect(warnings).toHaveLength(3);
+    expect(warnings.join("\n")).toContain('vault "admin"');
+    expect(warnings.join("\n")).toContain('vault "new"');
+    expect(warnings.join("\n")).toContain('vault "assets"');
+  });
+
+  test("silent for clean vault lists and near-misses", () => {
+    expect(reservedNameSquatWarnings([])).toEqual([]);
+    expect(reservedNameSquatWarnings(["default", "work", "adminx", "admin2"])).toEqual([]);
+  });
+
+  test("silent for 'list' (reserved for consistency, but not shadowed)", () => {
+    // `/vault/list/*` still routes per-vault — list is reserved at create
+    // time but a legacy squatter keeps working, so no scary boot warning.
+    expect(reservedNameSquatWarnings(["list"])).toEqual([]);
+  });
+});
+
 describe("decideInitVaultName", () => {
   test("--vault-name=aaron resolves to name 'aaron'", () => {
     const d = decideInitVaultName(["--vault-name", "aaron"], { isTTY: true });