@openparachute/vault 0.4.6-rc.3 → 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.4.6-rc.3",
+  "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.ts

@@ -31,6 +31,7 @@ import {
   SCOPE_READ,
   SCOPE_WRITE,
 } from "./scopes.ts";
+import { enforceVaultScope } from "@openparachute/scope-guard";
 import { HubJwtError, looksLikeJwt, validateHubJwt } from "./hub-jwt.ts";
 
 /**
@@ -241,9 +242,15 @@ export async function authenticateVaultRequest(
   // JWT path: hub-issued tokens. Trust pinned to the hub origin via `iss`
   // verification inside validateHubJwt; signature checked against hub's JWKS.
   // Audience strict-checked against `vault.<name>` so a token stamped for
-  // one vault can't reach another.
+  // one vault can't reach another. `vault_scope` claim additionally checked
+  // against `vaultConfig.name` so a per-user vault pin refuses cross-vault
+  // access even if a scope-string somehow named the wrong vault (multi-user
+  // Phase 1 defense-in-depth — see hub#283 + scope-guard 0.3.0).
   if (looksLikeJwt(key)) {
-    return await authenticateHubJwt(key, { expectedAudience: `vault.${vaultConfig.name}` });
+    return await authenticateHubJwt(key, {
+      expectedAudience: `vault.${vaultConfig.name}`,
+      vaultName: vaultConfig.name,
+    });
   }
 
   // Try vault's token DB first
@@ -319,10 +326,20 @@ export async function authenticateVaultRequest(
  * here — Phase B2 settled that hub tokens always name the resource. Per-
  * vault audience enforcement happens inside `validateHubJwt` via
  * `opts.expectedAudience`.
+ *
+ * Per-user vault-pin enforcement (multi-user Phase 1 PR 5): when
+ * `opts.vaultName` is set, the token's `vault_scope` claim is checked
+ * against it via scope-guard's `enforceVaultScope`. Non-admin tokens
+ * (`vault_scope: [<assigned_vault>]`) refuse cross-vault access with a
+ * 403 + `vault_scope_mismatch` error code. Admin tokens (`vault_scope:
+ * []`) and pre-PR-4 tokens (claim absent → surfaced as `[]`) pass
+ * unchanged. The 403 (not 401) signals "your credential is valid but
+ * doesn't grant access to this vault" — distinct from authentication
+ * failures upstream. See hub#283 + scope-guard 0.3.0 for the mint side.
  */
 async function authenticateHubJwt(
   token: string,
-  opts: { expectedAudience: string | null },
+  opts: { expectedAudience: string | null; vaultName?: string },
 ): Promise<{ error: Response } | AuthResult> {
   try {
     const claims = await validateHubJwt(token, { expectedAudience: opts.expectedAudience });
@@ -338,6 +355,43 @@ async function authenticateHubJwt(
         ),
       };
     }
+    // Defense-in-depth vault-pin check (multi-user Phase 1 PR 5). Runs
+    // AFTER the broad-scope check — a malformed token gets the more-
+    // descriptive scope-shape error rather than a generic pin-mismatch.
+    // When `vaultName` is unset (no per-vault binding known at this
+    // call site), the check is skipped — the audience strict-check
+    // inside validateHubJwt is the primary pin in that case.
+    if (opts.vaultName !== undefined && !enforceVaultScope(claims, opts.vaultName)) {
+      // Invariant: by the contract of `enforceVaultScope`, the false
+      // branch requires `claims.vaultScope.length > 0` — an empty
+      // `vaultScope` always returns true. The defensive assertion
+      // pins that so a future refactor can't slip an empty-scope
+      // request into this branch (which would render an empty
+      // parenthesised list in the message and break the diagnostic).
+      // Body shape: client gets `required_vault` + a message naming
+      // the conflict. The token's pinned vault is intentionally NOT
+      // echoed back — the attacker holds the token (and can decode
+      // claims locally), so the message would only leak the pin to a
+      // legitimate operator looking at a 403 log line. They already
+      // know which user they assigned where; the required_vault is
+      // the actionable piece.
+      if (claims.vaultScope.length === 0) {
+        throw new Error(
+          "unreachable: enforceVaultScope returned false on an empty vaultScope",
+        );
+      }
+      return {
+        error: Response.json(
+          {
+            error: "Forbidden",
+            error_type: "vault_scope_mismatch",
+            message: `token's vault_scope (${claims.vaultScope.join(", ")}) does not include the requested vault '${opts.vaultName}'`,
+            required_vault: opts.vaultName,
+          },
+          { status: 403 },
+        ),
+      };
+    }
     const permission: TokenPermission =
       hasScope(claims.scopes, SCOPE_WRITE) || hasScope(claims.scopes, SCOPE_ADMIN)
         ? "full"