@openparachute/vault 0.4.5 → 0.4.6

package/README.md

@@ -197,6 +197,9 @@ parachute-vault mcp-install --install-scope user      # write ~/.claude.json top
 parachute-vault mcp-install --install-scope local     # write ~/.claude.json projects[<cwd>] (this directory only — default)
 parachute-vault mcp-install --install-scope project   # write ./.mcp.json (checked into the repo)
 parachute-vault mcp-install --vault work   # target the "work" vault (keyed as parachute-vault-work)
+parachute-vault mcp-install --dry-run      # describe the write without touching disk or the hub
+parachute-vault mcp-config gitcoin         # emit JSON for `claude -p --mcp-config "$(...)"`
+parachute-vault mcp-config gitcoin --env-vars   # template form with ${PARACHUTE_HUB_URL}/${PARACHUTE_VAULT_TOKEN}
 
 # OAuth — owner password + 2FA
 parachute-vault set-password               # set/change the owner password (OAuth consent page)
@@ -619,8 +622,37 @@ parachute-vault mcp-install --legacy-pat
 
 **Multi-vault.** `--vault <name>` targets a specific vault and writes the entry under `parachute-vault-<name>` so multiple vaults coexist. Without `--vault`, the singular `parachute-vault` slot is used and one install clobbers another — that's intentional for the common single-vault case.
 
+**Dry-run.** `parachute-vault mcp-install --dry-run` prints the write that would happen — target file, install scope, entry key, URL, auth mode — without touching disk or hitting the hub. Useful for probing the command's effect; in particular, `--help` no longer creates an empty `projects[<cwd>]` entry as a side effect, but `--dry-run` is the deliberate "tell me what you'd do" path.
+
 **Doctor.** `parachute-vault doctor` checks `~/.claude.json` (both top-level and `projects[<cwd>]`) and `./.mcp.json`, and reports which one holds the entry, plus port-match and reachability of the MCP URL.
 
+#### Headless flows — `claude -p` runners (`mcp-config`)
+
+`mcp-install` writes a persistent entry into a Claude Code config file. That's the right shape for interactive sessions, but it has two sharp edges for headless runners that spawn `claude -p` against a vault:
+
+1. **Local-scope MCP entries don't propagate to `claude -p` subprocesses.** A project-scoped install under `projects[<cwd>].mcpServers` is visible to an *interactive* `claude` launched from that directory, but a `claude -p` invocation spawned by a Python script — even from the same directory, even with `--setting-sources user,project,local` — doesn't pick it up. Use `--install-scope user` for scripts, cron jobs, and runners; the local default is fine for interactive sessions.
+2. **`--mcp-config` JSON is per-runner boilerplate.** Some runners prefer to inline the MCP config rather than mutate the user's Claude Code state. `parachute-vault mcp-config <vault-name>` emits exactly the JSON shape `--mcp-config` consumes:
+
+```bash
+# Mint or fetch a vault-scoped token first, then:
+export PARACHUTE_VAULT_TOKEN=pvt_...
+claude -p --mcp-config "$(parachute-vault mcp-config gitcoin)" \
+          --strict-mcp-config \
+          "Summarize the latest notes under projects/gitcoin"
+
+# Or commit a template and expand at use-time:
+parachute-vault mcp-config gitcoin --env-vars > .claude/mcp-gitcoin.json
+# ...then later, when invoking claude:
+export PARACHUTE_HUB_URL=http://127.0.0.1:1940
+export PARACHUTE_VAULT_TOKEN=pvt_...
+claude -p --mcp-config "$(envsubst < .claude/mcp-gitcoin.json)" \
+          --strict-mcp-config ...
+```
+
+**Note on `--env-vars` expansion.** The file-save pattern requires the caller to expand `${...}` placeholders at use-time (e.g. via `envsubst`, available on most Linux distros and via `brew install gettext` on macOS). Bare `$(cat .claude/mcp-gitcoin.json)` feeds literal `${PARACHUTE_HUB_URL}` strings into `claude -p` — the shell only expands placeholders inside the command-substitution *source*, not inside the *captured output*. `claude -p` itself doesn't expand `${...}` either, so the substitution has to happen between the file and the command.
+
+Flags: `--token <bearer>` (alternative to `PARACHUTE_VAULT_TOKEN`); `--base-url <url>` (override the auto-detected origin, useful for tailnet-exposed hubs: `--base-url https://hub.tail.ts.net`); `--env-vars` (emit the template form with `${PARACHUTE_HUB_URL}` and `${PARACHUTE_VAULT_TOKEN}` placeholders, safe to commit). With no token and no `--env-vars`, the command exits 1 with a clear error — runners get a fail-fast.
+
 ## Data model
 
 ```
@@ -729,6 +761,15 @@ The checks, in the order they're emitted:
 - **Claude Code shows no vault tools.** Check in order: (1) is the daemon up (`parachute-vault status`)? (2) does `~/.claude.json` have a `parachute-vault` entry with both `url` and a valid `Authorization` header? (3) does the URL's vault name match an existing vault? `parachute-vault doctor` catches the first two. A missing or stale `Authorization` header after a bare `vault mcp-install` is the usual culprit for #2 — see the Claude Code section of [Connecting a client](#connecting-a-client) for how to rewrite it.
 - **Claude Desktop / Daily won't connect via OAuth.** If the owner-password prompt was skipped at `vault init`, the consent page falls back to requiring a vault token in place of the password (functional but clunky). Set one now with `parachute-vault set-password`. If 2FA is enrolled, have your authenticator app ready before starting the flow; lost TOTP access recovers via the backup codes printed at enrollment.
 - **Scheduled backups aren't running.** On macOS: `doctor` flags `backup agent: not loaded` when `schedule` isn't `manual` but the launchd agent is missing — rerun `parachute-vault backup --schedule <freq>` to reinstall it. On Linux: systemd-timer support for backup isn't shipped yet, so `--schedule daily` silently skips the scheduler. Run `parachute-vault backup` from cron (or similar) until that lands.
+- **Manual `curl` against `/vault/<name>/mcp` returns `406 Not Acceptable`.** The MCP HTTP transport requires both `application/json` and `text/event-stream` in the `Accept` header (it negotiates between the JSON response and the SSE streaming variant). Claude Code's `--mcp-config` http transport sets this automatically — the symptom only shows up when you probe the endpoint by hand. The fix:
+
+  ```bash
+  curl -H 'Accept: application/json, text/event-stream' \
+       -H "Authorization: Bearer $VAULT_TOKEN" \
+       http://127.0.0.1:1940/vault/default/mcp
+  ```
+
+  Both media types are needed; omitting either is what triggers the 406.
 
 ### Getting help
 
@@ -810,8 +851,37 @@ cp .env.example .env   # edit with your config
 docker compose up -d
 ```
 
+Optionally set `PARACHUTE_VAULT_NAME` to choose a name for your first vault (defaults to `default`). Lowercase alphanumeric + hyphens or underscores, 2–32 chars.
+
 ### Cloud platforms
 
+#### Render — recommended (hub-managed, v0.6)
+
+Most users deploy vault via parachute-hub's `/admin/modules` after the
+hub itself is on Render. See <https://parachute.computer/deploy/render/>
+for the primary v0.6 self-host story: one Render Blueprint provisions
+hub on a persistent disk, then you install vault (and the other
+Parachute modules) from the hub's admin UI. The hub container
+supervises vault's process, the shared persistent disk holds vault
+state, and module upgrades flow through the admin UI rather than
+separate Render redeploys.
+
+#### Render — standalone vault (advanced)
+
+The `render.yaml` Blueprint at the repo root deploys vault as its own
+Render web service, separate from hub. This is the **advanced path** —
+useful when you want vault on its own container (separate scaling,
+isolated logs, vault-only deploy without a hub) but not what the
+typical v0.6 self-host wants. If you're not sure, use the hub-managed
+path above. The standalone Blueprint stays in tree because some
+operators specifically want this shape (vault#341).
+
+Optionally set `PARACHUTE_VAULT_NAME` to choose a name for your first
+vault (defaults to `default`). Lowercase alphanumeric + hyphens or
+underscores, 2–32 chars.
+
+#### Other platforms
+
 **Railway** ($5/mo) — Deploy from GitHub, persistent volume, public URL.
 **Fly.io** ($3-5/mo) — `fly launch --copy-config && fly volumes create vault_data --size 1 && fly deploy`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@openparachute/scope-guard": "^0.2.0",
+    "@openparachute/scope-guard": "^0.3.0",
     "jose": "^6.2.2",
     "otpauth": "^9.5.0",
     "qrcode-terminal": "^0.12.0"

package/src/auth-hub-jwt.test.ts

@@ -98,12 +98,24 @@ interface SignOpts {
   ttlSeconds?: number;
   /** Override the random jti — needed when a test wants to revoke this exact token. */
   jti?: string;
+  /**
+   * `vault_scope` claim (multi-user Phase 1 PR 4 / scope-guard 0.3+).
+   * Undefined → omit the claim entirely (pre-PR-4 token shape; surfaces
+   * at scope-guard as `[]` = unrestricted). Provide `[]` explicitly for
+   * a hub-minted admin token; provide `["<name>"]` for a non-admin user.
+   */
+  vaultScope?: string[];
 }
 
 async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
   const iat = Math.floor(Date.now() / 1000);
   const exp = iat + (opts.ttlSeconds ?? 60);
-  return await new SignJWT({ scope: opts.scope, client_id: "test-client" })
+  const payload: Record<string, unknown> = {
+    scope: opts.scope,
+    client_id: "test-client",
+  };
+  if (opts.vaultScope !== undefined) payload.vault_scope = opts.vaultScope;
+  return await new SignJWT(payload)
     .setProtectedHeader({ alg: "RS256", kid: kp.kid })
     .setIssuer(opts.iss)
     .setSubject(opts.sub ?? "user-1")
@@ -319,6 +331,154 @@ describe("authenticateVaultRequest — hub JWT integration", () => {
     }
   });
 
+  test("vault_scope=[aaron] reaching /vault/aaron → success (matching pin)", async () => {
+    // Non-admin user assigned to vault "aaron" presenting their token
+    // at their own vault. The vault_scope claim names "aaron"; the
+    // request targets "aaron"; the defense-in-depth check passes.
+    seedVault("aaron");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.aaron",
+      scope: "vault:aaron:write",
+      vaultScope: ["aaron"],
+    });
+    const config = readVaultConfig("aaron")!;
+    const store = getVaultStore("aaron");
+
+    const result = await authenticateVaultRequest(bearer(token), config, store.db);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+      expect(result.scopes).toEqual(["vault:aaron:write"]);
+    }
+  });
+
+  test("vault_scope=[aaron] reaching /vault/bob (cross-vault) → 403 vault_scope_mismatch", async () => {
+    // The exact threat model multi-user Phase 1 PR 5 protects against.
+    // A non-admin user pinned to "aaron" somehow gets a token naming
+    // "bob" in its scope string (mint bug, edited token, third-party RS
+    // bug, replay attack). The audience strict-check inside
+    // validateHubJwt would catch the obvious shape (aud=vault.bob
+    // reaching journal endpoint), but the case below pre-fabricates a
+    // token whose aud + scope DO name bob — only the vault_scope claim
+    // pins the user to aaron. Without the new enforcement, the request
+    // would coast through.
+    seedVault("aaron");
+    seedVault("bob");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.bob", // audience matches bob (so the aud check passes)
+      scope: "vault:bob:write", // scope strings name bob too
+      vaultScope: ["aaron"], // but the user is pinned to aaron
+    });
+    const bobConfig = readVaultConfig("bob")!;
+    const bobStore = getVaultStore("bob");
+
+    const result = await authenticateVaultRequest(bearer(token), bobConfig, bobStore.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(403);
+      const body = (await result.error.json()) as {
+        error: string;
+        error_type: string;
+        message: string;
+        required_vault: string;
+        granted_vault_scope?: unknown;
+      };
+      expect(body.error).toBe("Forbidden");
+      expect(body.error_type).toBe("vault_scope_mismatch");
+      // Message names both the pinned vault (aaron) and the requested
+      // vault (bob) so operators reading 403 logs can correlate to
+      // user assignment without needing to decode the token.
+      expect(body.message).toContain("aaron");
+      expect(body.message).toContain("bob");
+      expect(body.required_vault).toBe("bob");
+      // Surface hygiene: the pinned vault is intentionally NOT echoed
+      // back in a dedicated body field. The message carries enough
+      // diagnostic for an operator reading logs; a dedicated field
+      // would only leak the pin to a passive observer (the attacker
+      // already has it via local decode, but pattern hygiene says
+      // don't volunteer it).
+      expect(body.granted_vault_scope).toBeUndefined();
+    }
+  });
+
+  test("vault_scope=[] (admin token) passes any-vault check", async () => {
+    // Admin tokens carry vault_scope: [] — the explicit "no per-user pin"
+    // sentinel. The defense-in-depth check skips, and the request is
+    // gated purely by audience + scope strings. Both name "work" here,
+    // so the request succeeds.
+    seedVault("work");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.work",
+      scope: "vault:work:admin",
+      vaultScope: [],
+    });
+    const config = readVaultConfig("work")!;
+    const store = getVaultStore("work");
+
+    const result = await authenticateVaultRequest(bearer(token), config, store.db);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+      expect(result.scopes).toEqual(["vault:work:admin"]);
+    }
+  });
+
+  test("pre-PR-4 token (vault_scope claim absent) → treated as admin (back-compat)", async () => {
+    // Every operator token + CLI-mint that existed before hub PR 4
+    // merged lacks the vault_scope claim entirely. scope-guard surfaces
+    // the absent claim as `[]`, which the helper treats as
+    // "unrestricted" — so the request goes through as long as audience
+    // + scope strings are correct. Without this back-compat, the entire
+    // pre-PR-4 fleet would 403 the moment this code shipped, which is
+    // the wrong tradeoff for a defense-in-depth check.
+    seedVault("legacy");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.legacy",
+      scope: "vault:legacy:write",
+      // vaultScope intentionally omitted — pre-PR-4 token shape
+    });
+    const config = readVaultConfig("legacy")!;
+    const store = getVaultStore("legacy");
+
+    const result = await authenticateVaultRequest(bearer(token), config, store.db);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+      expect(result.scopes).toEqual(["vault:legacy:write"]);
+    }
+  });
+
+  test("vault_scope check runs AFTER broad-scope check — broad scope still wins the failure mode", async () => {
+    // A token with a broad vault scope AND a vault_scope pin gets
+    // rejected for the broad scope (more diagnostic). Pinning the
+    // ordering matters because the 401 message tells the operator
+    // "your token shape is wrong" whereas 403 vault_scope_mismatch
+    // tells them "your user can't reach this vault" — those have
+    // different remediation paths.
+    seedVault("aaron");
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.aaron",
+      scope: "vault:write", // broad — should trigger 401 first
+      vaultScope: ["other-vault"], // would also fail vault_scope check
+    });
+    const config = readVaultConfig("aaron")!;
+    const store = getVaultStore("aaron");
+
+    const result = await authenticateVaultRequest(bearer(token), config, store.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      // 401, not 403 — broad-scope rejection takes precedence.
+      expect(result.error.status).toBe(401);
+      const body = (await result.error.json()) as { error: string; message: string };
+      expect(body.message).toContain("broad vault scope");
+    }
+  });
+
   test("revocation list unreachable on cold start → fail-closed 401 sanitized; full diagnostic routed to console.warn", async () => {
     seedVault("journal");
     // Hub is reachable for JWKS but the revocation endpoint 503s. Cold cache

package/src/auth.test.ts

@@ -398,3 +398,238 @@ describe("auth — legacy global YAML keys honor declared scope", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// VAULT_AUTH_TOKEN — server-wide operator bearer (vault#339)
+//
+// The container-shape auth gate. When the env var is set, a request whose
+// `Authorization: Bearer <value>` matches authenticates as full/admin
+// against any vault on the server — the operator-channel path for sibling
+// services on Render where vault and hub run as separate containers and
+// hub needs a stable shared bearer to call vault.
+//
+// Semantic confirmed for the loopback/non-loopback split (auth gate is
+// orthogonal to socket-level loopback): when VAULT_AUTH_TOKEN is unset,
+// vault's existing token surface (per-vault DB tokens + hub JWTs + legacy
+// YAML keys) is the ONLY auth surface. The bind socket defaults to
+// 127.0.0.1 (`VAULT_BIND` in bind.ts), but no implicit loopback trust
+// exists at the auth layer — a request from 127.0.0.1 still has to
+// present a valid bearer. This matches docs/auth-model.md §1.
+// ---------------------------------------------------------------------------
+
+describe("auth — VAULT_AUTH_TOKEN server-wide operator bearer", () => {
+  const TOKEN = "test-operator-token-deadbeef0123456789abcdef";
+  let prevToken: string | undefined;
+
+  beforeEach(() => {
+    prevToken = process.env.VAULT_AUTH_TOKEN;
+  });
+
+  afterEach(() => {
+    if (prevToken === undefined) delete process.env.VAULT_AUTH_TOKEN;
+    else process.env.VAULT_AUTH_TOKEN = prevToken;
+  });
+
+  test("env set + matching bearer → 200 on vault auth, full permission, admin scopes", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer(TOKEN),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+      expect(result.scopes).toContain("vault:admin");
+      expect(result.legacyDerived).toBe(false);
+      expect(result.scoped_tags).toBeNull();
+    }
+  });
+
+  test("env set + matching bearer authenticates against ANY vault on the server", async () => {
+    // Server-wide → not tied to any one vault's DB. Same bearer works
+    // for journal and work without minting a per-vault token in either.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    seedVault("work");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+    const workConfig = readVaultConfig("work")!;
+    const workStore = getVaultStore("work");
+
+    const j = await authenticateVaultRequest(bearer(TOKEN), journalConfig, journalStore.db);
+    const w = await authenticateVaultRequest(bearer(TOKEN), workConfig, workStore.db);
+
+    expect("error" in j).toBe(false);
+    expect("error" in w).toBe(false);
+  });
+
+  test("env set + missing bearer → 401 (no implicit auth)", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    // No Authorization header at all.
+    const noBearer = new Request("https://vault.test/x");
+    const result = await authenticateVaultRequest(noBearer, journalConfig, journalStore.db);
+
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set + wrong bearer → 401", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer("wrong-token-doesnotmatch"),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set + bearer that matches a vault token still resolves (server-wide first, but per-vault unchanged)", async () => {
+    // Per-vault tokens keep working even when the server-wide bearer is
+    // set. The server-wide check is a fast-path lookup before token DB
+    // resolution — a per-vault token doesn't match the env var so it
+    // falls through to the existing path.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const perVaultToken = mintTokenInVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer(perVaultToken),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(false);
+  });
+
+  test("env unset + valid per-vault bearer → 200 (existing behavior preserved)", async () => {
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const token = mintTokenInVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(bearer(token), journalConfig, journalStore.db);
+    expect("error" in result).toBe(false);
+  });
+
+  test("env unset + missing bearer → 401 (existing behavior preserved)", async () => {
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const noBearer = new Request("https://vault.test/x");
+    const result = await authenticateVaultRequest(noBearer, journalConfig, journalStore.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env unset + non-loopback simulated via X-Forwarded-For → still 401 without bearer", async () => {
+    // Doc note: vault has NO implicit loopback trust at the auth layer.
+    // The X-Forwarded-For shape (set by hub / Cloudflare Tunnel / etc.)
+    // doesn't affect the auth gate; tokens are required regardless of
+    // socket origin. The `bind.ts` 127.0.0.1 default is a socket-level
+    // listen-restriction, not a trust-asymmetric auth bypass.
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const remote = new Request("https://vault.test/x", {
+      headers: { "X-Forwarded-For": "203.0.113.7" },
+    });
+    const result = await authenticateVaultRequest(remote, journalConfig, journalStore.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set with whitespace-only value → treated as unset", async () => {
+    process.env.VAULT_AUTH_TOKEN = "   ";
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    // An empty/whitespace VAULT_AUTH_TOKEN must NOT allow any bearer to
+    // pass — the operator either commits to bearer auth or doesn't.
+    const result = await authenticateVaultRequest(
+      bearer(""),
+      journalConfig,
+      journalStore.db,
+    );
+    expect("error" in result).toBe(true);
+  });
+
+  test("env set + matching bearer also works on the global auth surface", async () => {
+    // /vaults metadata listing + /health vault names go through
+    // authenticateGlobalRequest. The server-wide bearer must work there
+    // too — otherwise hub couldn't enumerate vaults using the operator
+    // channel.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+
+    const result = await authenticateGlobalRequest(bearer(TOKEN));
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+    }
+  });
+
+  test("env set + wrong bearer on global auth surface → 401", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+
+    const result = await authenticateGlobalRequest(bearer("wrong-token"));
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("near-miss bearer (one-char difference, same length) → 401 (constant-time compare)", async () => {
+    // Defensive: the server-wide compare uses crypto.timingSafeEqual so
+    // a one-char-off bearer that matches length-wise still rejects.
+    // We can't measure timing in a unit test, but we can pin the
+    // correctness side: a same-length near-miss must still reject.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const nearMiss = TOKEN.slice(0, -1) + "x";
+    expect(nearMiss).not.toBe(TOKEN);
+    expect(nearMiss.length).toBe(TOKEN.length);
+
+    const result = await authenticateVaultRequest(
+      bearer(nearMiss),
+      journalConfig,
+      journalStore.db,
+    );
+    expect("error" in result).toBe(true);
+  });
+});