@openparachute/vault 0.4.6 → 0.4.7-rc.2

package/src/mirror-routes.test.ts

@@ -0,0 +1,380 @@
+/**
+ * Tests for `/admin/mirror` route handlers — GET/PUT shapes, validation
+ * gates, atomic persist + restart (vault-sync Phase A1).
+ *
+ * Auth gating happens upstream in `routing.ts`; these tests cover the
+ * after-auth handler logic.
+ */
+
+import { describe, test, expect, beforeEach, afterEach, afterAll } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { defaultMirrorConfig, type MirrorConfig } from "./mirror-config.ts";
+import {
+  MirrorManager,
+  type MirrorDeps,
+} from "./mirror-manager.ts";
+import { handleMirrorGet, handleMirrorPut } from "./mirror-routes.ts";
+
+// Same env-restore pattern as mirror-manager.test.ts — keeps HOME +
+// PARACHUTE_HOME from leaking between test files.
+const ORIG_HOME = process.env.HOME;
+const ORIG_PARACHUTE_HOME = process.env.PARACHUTE_HOME;
+afterEach(() => {
+  if (ORIG_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIG_HOME;
+  if (ORIG_PARACHUTE_HOME === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = ORIG_PARACHUTE_HOME;
+});
+afterAll(() => {
+  if (ORIG_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIG_HOME;
+});
+
+function tmp(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function initRepo(dir: string): void {
+  Bun.spawnSync(["git", "init", "-q", "-b", "main"], { cwd: dir });
+  Bun.spawnSync(["git", "config", "user.email", "t@p.computer"], { cwd: dir });
+  Bun.spawnSync(["git", "config", "user.name", "T P"], { cwd: dir });
+  Bun.spawnSync(["git", "config", "commit.gpgsign", "false"], { cwd: dir });
+}
+
+function makeManager(home: string): {
+  manager: MirrorManager;
+  deps: MirrorDeps & { storedConfig: MirrorConfig | undefined };
+  exportCalls: () => Array<{ outDir: string }>;
+} {
+  process.env.PARACHUTE_HOME = home;
+  process.env.HOME = home;
+  fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+  const state: {
+    config: MirrorConfig | undefined;
+    calls: Array<{ outDir: string }>;
+  } = { config: undefined, calls: [] };
+  const deps: MirrorDeps = {
+    vaultName: "default",
+    runExport: async ({ outDir }) => {
+      state.calls.push({ outDir });
+      return { notes: 0 };
+    },
+    firstChangedNoteTitle: async () => "",
+    readMirrorConfig: () => state.config,
+    writeMirrorConfig: (c) => {
+      state.config = c;
+    },
+  };
+  Object.defineProperty(deps, "storedConfig", {
+    get: () => state.config,
+    enumerable: true,
+  });
+  const manager = new MirrorManager(deps);
+  return {
+    manager,
+    deps: deps as MirrorDeps & { storedConfig: MirrorConfig | undefined },
+    exportCalls: () => state.calls,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GET /admin/mirror
+// ---------------------------------------------------------------------------
+
+describe("handleMirrorGet", () => {
+  let home: string;
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  test("returns defaults + status when no config has been written", async () => {
+    home = tmp("mirror-get-defaults-");
+    const { manager } = makeManager(home);
+    const res = handleMirrorGet(manager);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { config: MirrorConfig; status: { enabled: boolean } };
+    expect(body.config).toEqual(defaultMirrorConfig());
+    expect(body.status.enabled).toBe(false);
+  });
+
+  test("after a successful start with enabled config, reports running status", async () => {
+    home = tmp("mirror-get-enabled-");
+    const { manager, deps } = makeManager(home);
+    deps.writeMirrorConfig({
+      ...defaultMirrorConfig(),
+      enabled: true,
+      location: "internal",
+      watch: false,
+      auto_commit: false,
+    });
+    await manager.start();
+    const res = handleMirrorGet(manager);
+    const body = (await res.json()) as {
+      config: MirrorConfig;
+      status: { enabled: boolean; mirror_path: string | null };
+    };
+    expect(body.config.enabled).toBe(true);
+    expect(body.status.enabled).toBe(true);
+    expect(body.status.mirror_path).toContain("mirror");
+    await manager.stop();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// PUT /admin/mirror
+// ---------------------------------------------------------------------------
+
+describe("handleMirrorPut", () => {
+  let home: string;
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  test("rejects invalid JSON body with 400", async () => {
+    home = tmp("mirror-put-badjson-");
+    const { manager } = makeManager(home);
+    const req = new Request("http://x/admin/mirror", {
+      method: "PUT",
+      body: "{not-json",
+      headers: { "Content-Type": "application/json" },
+    });
+    const res = await handleMirrorPut(req, manager);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain("Invalid JSON");
+  });
+
+  test("rejects shape errors with 400 + field localization", async () => {
+    home = tmp("mirror-put-shape-");
+    const { manager } = makeManager(home);
+    const req = new Request("http://x/admin/mirror", {
+      method: "PUT",
+      body: JSON.stringify({ location: "moon" }),
+    });
+    const res = await handleMirrorPut(req, manager);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field: string; message: string };
+    expect(body.field).toBe("location");
+    expect(body.message).toContain("location");
+  });
+
+  test("rejects external + missing external_path with 400", async () => {
+    home = tmp("mirror-put-noext-");
+    const { manager } = makeManager(home);
+    const req = new Request("http://x/admin/mirror", {
+      method: "PUT",
+      body: JSON.stringify({ enabled: true, location: "external" }),
+    });
+    const res = await handleMirrorPut(req, manager);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field: string };
+    expect(body.field).toBe("external_path");
+  });
+
+  test("rejects external + non-existent path with 400 + actionable error", async () => {
+    home = tmp("mirror-put-missing-");
+    const { manager } = makeManager(home);
+    const req = new Request("http://x/admin/mirror", {
+      method: "PUT",
+      body: JSON.stringify({
+        enabled: true,
+        location: "external",
+        external_path: "/definitely/not/here",
+      }),
+    });
+    const res = await handleMirrorPut(req, manager);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { message: string };
+    expect(body.message).toContain("doesn't exist");
+  });
+
+  test("rejects external + non-git directory with 400", async () => {
+    home = tmp("mirror-put-nogit-");
+    const { manager } = makeManager(home);
+    const external = tmp("mirror-put-plain-");
+    try {
+      const req = new Request("http://x/admin/mirror", {
+        method: "PUT",
+        body: JSON.stringify({
+          enabled: true,
+          location: "external",
+          external_path: external,
+        }),
+      });
+      const res = await handleMirrorPut(req, manager);
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { message: string };
+      expect(body.message).toContain("isn't a git repository");
+    } finally {
+      fs.rmSync(external, { recursive: true, force: true });
+    }
+  });
+
+  test("accepts a valid external config, persists, restarts watch", async () => {
+    home = tmp("mirror-put-happy-");
+    const external = tmp("mirror-put-ext-");
+    initRepo(external);
+    fs.writeFileSync(path.join(external, ".gitkeep"), "");
+    Bun.spawnSync(["git", "add", "-A"], { cwd: external });
+    Bun.spawnSync(["git", "commit", "-q", "-m", "i"], { cwd: external });
+    try {
+      const { manager, deps, exportCalls } = makeManager(home);
+      const req = new Request("http://x/admin/mirror", {
+        method: "PUT",
+        body: JSON.stringify({
+          enabled: true,
+          location: "external",
+          external_path: external,
+          watch: false,
+          auto_commit: false,
+        }),
+      });
+      const res = await handleMirrorPut(req, manager);
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as { config: MirrorConfig; status: { enabled: boolean; mirror_path: string } };
+      expect(body.config.enabled).toBe(true);
+      expect(body.status.enabled).toBe(true);
+      expect(body.status.mirror_path).toBe(external);
+      // Persisted via writeMirrorConfig.
+      expect(deps.storedConfig?.external_path).toBe(external);
+      // Initial export ran into the new path.
+      expect(exportCalls()).toHaveLength(1);
+      expect(exportCalls()[0]!.outDir).toBe(external);
+      await manager.stop();
+    } finally {
+      fs.rmSync(external, { recursive: true, force: true });
+    }
+  });
+
+  test("accepts disable-only PUT even when external_path no longer valid", async () => {
+    home = tmp("mirror-put-disable-");
+    const { manager } = makeManager(home);
+    const req = new Request("http://x/admin/mirror", {
+      method: "PUT",
+      body: JSON.stringify({
+        enabled: false,
+        location: "external",
+        external_path: "/this/path/is/gone",
+      }),
+    });
+    const res = await handleMirrorPut(req, manager);
+    // enabled:false skips the filesystem check.
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { config: MirrorConfig; status: { enabled: boolean } };
+    expect(body.status.enabled).toBe(false);
+    expect(body.config.external_path).toBe("/this/path/is/gone");
+    await manager.stop();
+  });
+
+  test("accepts disable-only PUT with external location and no external_path at all", async () => {
+    // Reviewer-flagged regression: previously `validateMirrorConfigShape`
+    // ran the cross-field "external requires external_path" rule
+    // unconditionally, so `{enabled: false, location: "external"}` (no
+    // path) returned 400. The rule now gates on `enabled`, matching
+    // the disable-should-never-fail-on-path-issues intent of the
+    // route-layer filesystem check skip.
+    home = tmp("mirror-put-disable-nopath-");
+    const { manager } = makeManager(home);
+    const req = new Request("http://x/admin/mirror", {
+      method: "PUT",
+      body: JSON.stringify({
+        enabled: false,
+        location: "external",
+        // no external_path
+      }),
+    });
+    const res = await handleMirrorPut(req, manager);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { config: MirrorConfig; status: { enabled: boolean } };
+    expect(body.status.enabled).toBe(false);
+    expect(body.config.external_path).toBeNull();
+    await manager.stop();
+  });
+
+  test("PUT restarts watch loop with new interval", async () => {
+    home = tmp("mirror-put-restart-");
+    const { manager } = makeManager(home);
+    // Enable with watch.
+    const req1 = new Request("http://x/admin/mirror", {
+      method: "PUT",
+      body: JSON.stringify({
+        enabled: true,
+        location: "internal",
+        watch: true,
+        auto_commit: false,
+        interval_seconds: 1,
+      }),
+    });
+    const res1 = await handleMirrorPut(req1, manager);
+    expect(res1.status).toBe(200);
+    expect(manager.getStatus().watch_running).toBe(true);
+
+    // Disable.
+    const req2 = new Request("http://x/admin/mirror", {
+      method: "PUT",
+      body: JSON.stringify({ enabled: false }),
+    });
+    const res2 = await handleMirrorPut(req2, manager);
+    expect(res2.status).toBe(200);
+    expect(manager.getStatus().watch_running).toBe(false);
+    await manager.stop();
+  });
+
+  test("two PUTs fired in quick succession both apply; manager ends in the second config's state", async () => {
+    // Reviewer concern: a second PUT entering `reload()` while the
+    // first PUT's `stop()` is still inside its 250ms in-flight settle
+    // window could theoretically race the `stopping` flag. JS's
+    // microtask-serialized awaits make this safe in practice — each
+    // PUT's reload→start chain runs to completion on its own tick
+    // before the next runs — but pinning the expected outcome with a
+    // test documents the behavior + catches a regression if the
+    // serialization ever relaxes.
+    //
+    // What we assert:
+    //   - Both PUTs return 200 (no crash, no stuck-in-flight).
+    //   - After both resolve, the manager is in the SECOND config's
+    //     shape (last-writer-wins; not a stale first-config state
+    //     leaking through).
+    home = tmp("mirror-put-concurrent-");
+    const { manager } = makeManager(home);
+    const put = (body: Record<string, unknown>) =>
+      handleMirrorPut(
+        new Request("http://x/admin/mirror", {
+          method: "PUT",
+          body: JSON.stringify(body),
+        }),
+        manager,
+      );
+    const [res1, res2] = await Promise.all([
+      put({
+        enabled: true,
+        location: "internal",
+        watch: true,
+        auto_commit: false,
+        interval_seconds: 1,
+      }),
+      put({
+        enabled: true,
+        location: "internal",
+        watch: true,
+        auto_commit: false,
+        interval_seconds: 2,
+      }),
+    ]);
+    expect(res1.status).toBe(200);
+    expect(res2.status).toBe(200);
+    // Both PUTs read the same config-storage seam (deps.writeMirrorConfig)
+    // and serialize through the manager's async start() under the
+    // microtask queue. Final config reflects whichever PUT entered
+    // `reload()` last — practically the second one — but the salient
+    // assertion is "the manager isn't stuck": enabled + watch_running.
+    const status = manager.getStatus();
+    expect(status.enabled).toBe(true);
+    expect(status.watch_running).toBe(true);
+    expect(manager.getConfig().interval_seconds).toBe(2);
+    await manager.stop();
+  });
+});

package/src/mirror-routes.ts

@@ -0,0 +1,152 @@
+/**
+ * HTTP surface for the mirror lifecycle.
+ *
+ *   GET  /vault/<name>/.parachute/mirror — read current config + runtime status
+ *   PUT  /vault/<name>/.parachute/mirror — update config + reload watch loop
+ *
+ * URL note: the design doc names this `/admin/mirror`, but vault's
+ * existing routing already mounts the admin SPA's static-file bundle at
+ * `/vault/<name>/admin/*` (vault#252). Putting the API endpoint there
+ * would collide with the SPA mount. We use the existing `.parachute/`
+ * namespace instead — sibling to `.parachute/config`, `.parachute/info`,
+ * `.parachute/icon.svg` — which matches the module-protocol convention
+ * for per-module API surfaces. The hub admin SPA (Phase A2) will call
+ * this URL; operators issuing `curl` calls use it directly.
+ *
+ * Both endpoints gate on `vault:admin` — see `routing.ts` for the
+ * upstream auth wiring. This module is the after-auth handler; the
+ * caller has already verified the scope.
+ *
+ * These two endpoints unblock the Phase A2 hub admin SPA from configuring
+ * vault-side mirrors. For Phase A1 the only consumers are direct API
+ * callers (curl, the future SPA) and operators editing config.yaml by
+ * hand + restarting the vault.
+ */
+
+import {
+  defaultMirrorConfig,
+  validateExternalPath,
+  validateMirrorConfigShape,
+  type MirrorConfig,
+} from "./mirror-config.ts";
+import type { MirrorManager } from "./mirror-manager.ts";
+
+/**
+ * `GET /vault/<name>/.parachute/mirror` — return the persisted config +
+ * the runtime status the manager is currently tracking.
+ *
+ * Always returns 200 (auth was already enforced upstream). When no
+ * mirror config has ever been written, returns the defaults — the
+ * operator + the hub SPA see a consistent shape regardless of whether
+ * any persistence has happened yet.
+ */
+export function handleMirrorGet(manager: MirrorManager): Response {
+  const config = manager.getConfig();
+  const status = manager.getStatus();
+  return Response.json(
+    {
+      config,
+      status,
+    },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
+/**
+ * `PUT /vault/<name>/.parachute/mirror` — accept a JSON body with the
+ * mirror config block, validate, persist, restart the in-process
+ * lifecycle.
+ *
+ * Request shape: same JSON as the MirrorConfig type — { enabled,
+ * location, external_path, watch, auto_commit, auto_push,
+ * commit_template, interval_seconds }. All fields optional; missing
+ * fields fall back to defaults.
+ *
+ * Validation surface:
+ *   - JSON shape: location ∈ {internal, external}, types match, etc.
+ *     Returns 400 with `field`-localized error on failure.
+ *   - For enabled=true + location=external: the supplied external_path
+ *     must exist on the filesystem AND be a git repo. Returns 400
+ *     with an actionable error message on failure.
+ *   - For enabled=false (any location): skip BOTH the cross-field
+ *     "external requires external_path" check AND the filesystem
+ *     check. Disable should never fail validation on path-related
+ *     issues — the operator's just trying to turn off a mirror whose
+ *     path may have gone away.
+ *
+ * Response: 200 with the new config + status snapshot.
+ */
+export async function handleMirrorPut(
+  req: Request,
+  manager: MirrorManager,
+): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch (err) {
+    return Response.json(
+      {
+        error: "Invalid JSON body",
+        message: (err as Error).message ?? String(err),
+      },
+      { status: 400 },
+    );
+  }
+
+  const shape = validateMirrorConfigShape(body);
+  if (!shape.ok) {
+    return Response.json(
+      {
+        error: "Invalid mirror config",
+        field: shape.field,
+        message: shape.error,
+      },
+      { status: 400 },
+    );
+  }
+
+  const config: MirrorConfig = shape.config;
+
+  // Filesystem-level validation runs only when the operator is asking us
+  // to *do* something with an external path. Disabling the mirror by-
+  // flipping enabled to false shouldn't fail because the path went away.
+  if (config.enabled && config.location === "external" && config.external_path) {
+    const pathCheck = await validateExternalPath(config.external_path);
+    if (!pathCheck.ok) {
+      return Response.json(
+        {
+          error: "Invalid external_path",
+          field: "external_path",
+          message: pathCheck.error,
+        },
+        { status: 400 },
+      );
+    }
+  }
+
+  // Persist + restart lifecycle. `reload` writes the config first and
+  // then calls `start()`, so a crash between the two leaves the operator-
+  // intended state on disk (next boot applies it).
+  const status = await manager.reload(config);
+  return Response.json(
+    {
+      config: manager.getConfig(),
+      status,
+    },
+    { headers: { "Access-Control-Allow-Origin": "*" } },
+  );
+}
+
+/**
+ * Convenience for tests + future callers: build the GET response from a
+ * known-good config without needing a real MirrorManager.
+ */
+export function buildMirrorGetResponse(
+  config: MirrorConfig | undefined,
+  status: ReturnType<MirrorManager["getStatus"]>,
+): { config: MirrorConfig; status: ReturnType<MirrorManager["getStatus"]> } {
+  return {
+    config: config ?? defaultMirrorConfig(),
+    status,
+  };
+}

package/src/routing.test.ts

@@ -1725,3 +1725,79 @@ describe("/health — always 200 (Render/Docker healthcheck contract)", () => {
     expect(body.vaults).toBeUndefined();
   });
 });
+
+// ---------------------------------------------------------------------------
+// /vault/<name>/admin/mirror — vault-sync Phase A1 admin surface.
+//
+// These tests pin the auth gate + the no-manager-bootstrapped fallback;
+// shape + lifecycle behaviour is covered in mirror-routes.test.ts /
+// mirror-manager.test.ts. We exercise the route here to make sure the
+// `vault:admin` enforcement matches the rest of the admin surface.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/mirror — auth + dispatch", () => {
+  test("unauthenticated → 401", async () => {
+    createVault("journal");
+    const p = "/vault/journal/.parachute/mirror";
+    const res = await route(new Request(`http://localhost:1940${p}`), p);
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token → 403 insufficient_scope", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    const { fullToken } = generateToken();
+    createToken(store.db, fullToken, {
+      label: "reader",
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+    const p = "/vault/journal/.parachute/mirror";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        headers: { authorization: `Bearer ${fullToken}` },
+      }),
+      p,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("admin token reaches the handler — returns 503 when manager hasn't been wired (no boot)", async () => {
+    // The routing-test harness boots `route()` without starting the
+    // server.ts wiring that constructs a MirrorManager. We expect the
+    // handler to surface 503 — distinct from an auth or shape error —
+    // so operators can tell "manager not initialized" apart from
+    // "you used the wrong creds".
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror";
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    // 200 if a previous test left a manager wired (test ordering varies),
+    // 503 otherwise. Both prove the auth gate passed.
+    expect([200, 503]).toContain(res.status);
+  });
+
+  test("non-GET/PUT methods return 405 when manager isn't wired", async () => {
+    createVault("journal");
+    const token = createAdminToken("journal");
+    const p = "/vault/journal/.parachute/mirror";
+    // 503 short-circuits the method check today — that's fine; what we
+    // want to assert is that we don't crash + the status is non-2xx.
+    const res = await route(
+      new Request(`http://localhost:1940${p}`, {
+        method: "DELETE",
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      p,
+    );
+    expect([405, 503]).toContain(res.status);
+  });
+});

package/src/routing.ts

@@ -69,6 +69,8 @@ import {
 import { handleConfigSchema, handleConfig } from "./module-config.ts";
 import { buildAuthStatus } from "./auth-status.ts";
 import { getAuthorizeRateLimiter } from "./owner-auth.ts";
+import { handleMirrorGet, handleMirrorPut } from "./mirror-routes.ts";
+import { getMirrorManager } from "./mirror-registry.ts";
 
 /**
  * Decorate a 401 response from the MCP endpoint with the RFC 9728 challenge
@@ -479,6 +481,50 @@ export async function route(
     return handleTokens(req, store, vaultName, auth.scopes, auth.scoped_tags, tokensMatch[1] ?? "");
   }
 
+  // /.parachute/mirror — vault-sync Phase A1. Admin-gated read+write of
+  // the persistent mirror config + runtime status. Lives under
+  // `.parachute/` (alongside info/icon/config) rather than `admin/`
+  // because `/vault/<name>/admin/*` is reserved for the admin SPA's
+  // static-file mount; the API surface goes under `.parachute/` by the
+  // module-protocol convention. Per the design doc, the hub admin SPA
+  // (Phase A2 — future PR) is the eventual primary consumer; for Phase
+  // A1 these endpoints unblock direct API callers and the by-hand
+  // config workflow.
+  if (subpath === "/.parachute/mirror") {
+    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 manager = getMirrorManager();
+    if (!manager) {
+      // The boot path constructs a manager when at least one vault
+      // exists; a missing manager here means either a startup error or
+      // a brand-new deploy that hasn't finished first-boot. Surface a
+      // clear 503 rather than a JSON null so the operator + the hub
+      // SPA know it's a service-state issue, not a misconfig on their
+      // end.
+      return Response.json(
+        {
+          error: "Mirror manager not initialized",
+          message:
+            "The vault server hasn't wired a mirror manager yet (no vaults exist, or boot failed). Check logs for [mirror] entries.",
+        },
+        { status: 503 },
+      );
+    }
+    if (req.method === "GET") return handleMirrorGet(manager);
+    if (req.method === "PUT") return handleMirrorPut(req, manager);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
   const apiMatch = subpath.match(/^\/api(\/.*)?$/);
   if (!apiMatch) {
     return Response.json({ error: "Not found" }, { status: 404 });