@openparachute/vault 0.3.3 → 0.4.0

package/src/hub-jwt.ts

@@ -0,0 +1,79 @@
+/**
+ * Hub-issued JWT validation. Vault as resource server: trusts tokens that the
+ * hub signs against keys we fetch from the hub's `/.well-known/jwks.json`.
+ *
+ * The trust kernel — JWKS fetch + verify, issuer pin, audience strict-check,
+ * RFC 7519 string-or-array `aud` handling — lives in the shared
+ * `@openparachute/scope-guard` library so vault, scribe, and paraclaw can't
+ * silently drift on the worst place to drift. This file is the vault-side
+ * adapter: hub-origin resolution (env-var precedence + loopback fallback),
+ * a process-wide guard instance, and re-exports preserving the public
+ * surface every existing call site already imports.
+ *
+ * Vault#169 / hub-as-issuer Phase B2; vault#TBD / scope-guard adoption.
+ */
+import {
+  createScopeGuard,
+  HubJwtError,
+  type HubJwtClaims,
+  looksLikeJwt,
+  type ValidateHubJwtOptions,
+} from "@openparachute/scope-guard";
+
+const DEFAULT_HUB_LOOPBACK = "http://127.0.0.1:1939";
+
+/**
+ * Resolve the hub origin used to fetch JWKS and validate `iss`. Strips a
+ * trailing slash so we get a single canonical form.
+ *
+ * Order: env var → loopback fallback. We deliberately don't read
+ * `~/.parachute/services.json` — the hub is the dispatcher, not a registered
+ * service in that file. If a deployment exposes the hub on a non-default
+ * origin, the env var is the contract.
+ */
+export function getHubOrigin(): string {
+  const env = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
+  if (env && env.length > 0) return env;
+  return DEFAULT_HUB_LOOPBACK;
+}
+
+// Process-wide guard. The resolver form lets tests flip
+// `PARACHUTE_HUB_ORIGIN` between cases — the lib re-resolves on every
+// `validateHubJwt` and `resetJwksCache` call so the env-var change picks up
+// without a server restart. JWKS cache (5min/30s defaults) lives inside the
+// guard, shared across requests.
+const guard = createScopeGuard({ hubOrigin: () => getHubOrigin() });
+
+/**
+ * Verify a presented JWT against the hub's JWKS. Throws `HubJwtError` on any
+ * failure (bad signature, wrong issuer, expired, missing kid, JWKS
+ * unreachable, audience mismatch). On success returns the surfaced claims
+ * plus the parsed scope list.
+ *
+ * Trust model:
+ *   - `iss` MUST equal the configured hub origin. Without this, anyone could
+ *     mint a token against any RSA key and pass verification.
+ *   - `aud` is strict-checked against `opts.expectedAudience` when provided
+ *     — the resource-server backstop for per-vault binding.
+ *
+ * Scope-shape policy (e.g. "hub-issued tokens may not carry broad
+ * `vault:<verb>` scopes") is enforced one layer up in `authenticateHubJwt`,
+ * not here — this function stays focused on JWT-level concerns.
+ */
+export async function validateHubJwt(
+  token: string,
+  opts: ValidateHubJwtOptions = {},
+): Promise<HubJwtClaims> {
+  return guard.validateHubJwt(token, opts);
+}
+
+/**
+ * Reset the cached JWKS getter. Tests use this to switch origins between
+ * cases; production callers shouldn't need it (origin is process-stable).
+ */
+export function resetJwksCache(): void {
+  guard.resetJwksCache();
+}
+
+export { HubJwtError, looksLikeJwt };
+export type { HubJwtClaims, ValidateHubJwtOptions };

package/src/init.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Integration tests for `parachute-vault init` flag plumbing — the cases
+ * where init exits early without touching the daemon, ~/.claude.json, or
+ * the vault filesystem. The full happy-path of init isn't run here because
+ * it would install a launchd agent on macOS and write into the developer's
+ * real ~/Library/LaunchAgents — out of scope for unit tests. The vault-name
+ * decision logic is fully covered by `vault-name.test.ts`.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
+
+const CLI = resolve(import.meta.dir, "cli.ts");
+
+function runCli(args: string[], env: Record<string, string> = {}): {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+} {
+  const proc = Bun.spawnSync({
+    cmd: ["bun", CLI, ...args],
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, ...env },
+  });
+  return {
+    exitCode: proc.exitCode ?? -1,
+    stdout: new TextDecoder().decode(proc.stdout),
+    stderr: new TextDecoder().decode(proc.stderr),
+  };
+}
+
+describe("vault init — --vault-name validation", () => {
+  test("rejects --vault-name with uppercase + space and exits non-zero", () => {
+    const { exitCode, stderr } = runCli(["init", "--vault-name", "My Vault"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("--vault-name:");
+    expect(stderr).toContain("lowercase alphanumeric");
+  });
+
+  test("rejects --vault-name with a slash and exits non-zero", () => {
+    const { exitCode, stderr } = runCli(["init", "--vault-name", "team/work"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("lowercase alphanumeric");
+  });
+
+  test("rejects --vault-name with no value and exits non-zero", () => {
+    // `--vault-name` is the last arg → no value follows.
+    const { exitCode, stderr } = runCli(["init", "--vault-name"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("requires a value");
+  });
+
+  test("rejects reserved name 'list' and exits non-zero", () => {
+    const { exitCode, stderr } = runCli(["init", "--vault-name", "list"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("reserved");
+  });
+});
+
+describe("vault init — --help mentions --vault-name", () => {
+  test("usage text documents the new flag", () => {
+    const { exitCode, stdout } = runCli(["--help"]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("--vault-name");
+  });
+
+  test("usage text documents --no-autostart (#113)", () => {
+    const { exitCode, stdout } = runCli(["--help"]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("--no-autostart");
+  });
+});
+
+/**
+ * End-to-end init under an isolated $HOME / $PARACHUTE_HOME so we never touch
+ * the developer's real ~/.parachute or ~/Library/LaunchAgents. With
+ * --no-autostart, init must:
+ *   1. Persist `autostart: false` in config.yaml.
+ *   2. NOT write the daemon wrapper (start.sh / server-path).
+ *
+ * --no-mcp / --no-token avoid the ~/.claude.json side effect; HOME=tmpdir
+ * makes the launchd-uninstall-prior-registration call land inside the
+ * sandbox even on macOS (where uninstallAgent operates on
+ * `homedir()/Library/LaunchAgents/...`).
+ */
+describe("vault init — --no-autostart (#113)", () => {
+  test("persists autostart=false and skips the daemon wrapper", () => {
+    const sandbox = mkdtempSync(join(tmpdir(), "vault-init-autostart-"));
+    try {
+      const parachuteHome = join(sandbox, ".parachute");
+      const { exitCode, stdout } = runCli(
+        [
+          "init",
+          "--no-autostart",
+          "--no-mcp",
+          "--no-token",
+          "--vault-name",
+          "autostarttest",
+        ],
+        { HOME: sandbox, PARACHUTE_HOME: parachuteHome },
+      );
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain("Autostart disabled");
+
+      const configPath = join(parachuteHome, "vault", "config.yaml");
+      expect(existsSync(configPath)).toBe(true);
+      expect(readFileSync(configPath, "utf-8")).toContain("autostart: false");
+
+      // Daemon wrapper / pointer are written by installAgent /
+      // installSystemdService — neither should run when autostart is off.
+      expect(existsSync(join(parachuteHome, "vault", "start.sh"))).toBe(false);
+      expect(existsSync(join(parachuteHome, "vault", "server-path"))).toBe(false);
+    } finally {
+      rmSync(sandbox, { recursive: true, force: true });
+    }
+  });
+
+  test("re-running init without a flag preserves persisted autostart=false", () => {
+    // We can't drive the --autostart re-run end-to-end here: it calls
+    // installAgent() / installSystemdService() which write to launchd /
+    // systemd state outside the PARACHUTE_HOME sandbox, breaking test
+    // hermeticity. Instead verify the inverse property — that a no-flag
+    // re-run honors the persisted opt-out and does NOT fall back to the
+    // default-on. This is the actual user-facing risk (forgetting to pass
+    // --no-autostart on every re-run shouldn't re-enable the daemon).
+    const sandbox = mkdtempSync(join(tmpdir(), "vault-init-autostart-"));
+    try {
+      const parachuteHome = join(sandbox, ".parachute");
+      const env = { HOME: sandbox, PARACHUTE_HOME: parachuteHome };
+
+      const first = runCli(
+        [
+          "init",
+          "--no-autostart",
+          "--no-mcp",
+          "--no-token",
+          "--vault-name",
+          "autostarttest",
+        ],
+        env,
+      );
+      expect(first.exitCode).toBe(0);
+
+      const configPath = join(parachuteHome, "vault", "config.yaml");
+      expect(readFileSync(configPath, "utf-8")).toContain("autostart: false");
+
+      // No --autostart / --no-autostart on this run; init should read the
+      // persisted false and skip daemon install again.
+      const second = runCli(["init", "--no-mcp", "--no-token"], env);
+      expect(second.exitCode).toBe(0);
+      expect(second.stdout).toContain("Autostart disabled");
+      expect(readFileSync(configPath, "utf-8")).toContain("autostart: false");
+      expect(existsSync(join(parachuteHome, "vault", "start.sh"))).toBe(false);
+    } finally {
+      rmSync(sandbox, { recursive: true, force: true });
+    }
+  });
+});
+
+/**
+ * #210: re-running `parachute-vault init` is the documented recovery path
+ * for installs whose `services.json` is stale (#208 left some vaults out of
+ * the manifest). The recovery is implicit — init re-registers the full
+ * vault list every run via `buildVaultServicePaths` — so this test pins it
+ * down with an explicit fixture: corrupt the manifest to drop one vault,
+ * re-run init, expect the manifest to grow back.
+ */
+describe("vault init — repairs stale services.json (#210)", () => {
+  test("re-running init rewrites services.json to include every vault on disk", () => {
+    const sandbox = mkdtempSync(join(tmpdir(), "vault-init-repair-"));
+    try {
+      const parachuteHome = join(sandbox, ".parachute");
+      const env = { HOME: sandbox, PARACHUTE_HOME: parachuteHome };
+
+      // Use `create` to bootstrap two vaults into a real, healthy state —
+      // this also writes the initial services.json with both vaults so we
+      // have a known-good baseline to corrupt.
+      expect(runCli(["create", "alpha", "--json"], env).exitCode).toBe(0);
+      expect(runCli(["create", "beta", "--json"], env).exitCode).toBe(0);
+
+      const servicesPath = join(parachuteHome, "services.json");
+      const baseline = JSON.parse(readFileSync(servicesPath, "utf-8"));
+      const baselineEntry = baseline.services.find(
+        (s: { name: string }) => s.name === "parachute-vault",
+      );
+      expect(baselineEntry.paths).toEqual(["/vault/alpha", "/vault/beta"]);
+
+      // Corrupt: drop beta from the manifest, mimicking the #208 state where
+      // an older `create` ran without the upsert.
+      baselineEntry.paths = ["/vault/alpha"];
+      writeFileSync(servicesPath, JSON.stringify(baseline, null, 2));
+
+      // Re-run init with no flags that would change vault topology. The
+      // sandbox env keeps launchd / ~/.claude.json side effects out of the
+      // dev environment.
+      const repair = runCli(
+        ["init", "--no-autostart", "--no-mcp", "--no-token"],
+        env,
+      );
+      expect(repair.exitCode).toBe(0);
+
+      const repaired = JSON.parse(readFileSync(servicesPath, "utf-8"));
+      const repairedEntry = repaired.services.find(
+        (s: { name: string }) => s.name === "parachute-vault",
+      );
+      // alpha is still default (created first), so it leads. beta is back.
+      expect(repairedEntry.paths).toEqual(["/vault/alpha", "/vault/beta"]);
+    } finally {
+      rmSync(sandbox, { recursive: true, force: true });
+    }
+  });
+});

package/src/mcp-http.ts

@@ -24,47 +24,49 @@ import {
   McpError,
 } from "@modelcontextprotocol/sdk/types.js";
 import { generateScopedMcpTools, getServerInstruction } from "./mcp-tools.ts";
-import { requireScope } from "./auth.ts";
 import type { AuthResult } from "./auth.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
-import { SCOPE_READ, SCOPE_WRITE } from "./scopes.ts";
+import { hasScopeForVault } from "./scopes.ts";
+import type { VaultVerb } from "./scopes.ts";
 
 /**
- * Required scope for each MCP tool. Tools that mutate note/tag state require
- * `vault:write`; pure query tools need `vault:read`. `vault-info` is listed as
- * read because read-only callers can fetch stats — the description-update
- * branch inside vault-info performs its own secondary `vault:write` check
- * (see `overrideVaultInfo` in mcp-tools.ts). Do not assume the outer gate
- * alone protects the inner branch.
+ * Required verb for each MCP tool. Tools that mutate note/tag state require
+ * write; pure query tools need read. `vault-info` is listed as read because
+ * read-only callers can fetch stats — the description-update branch inside
+ * vault-info performs its own secondary write check (see `overrideVaultInfo`
+ * in mcp-tools.ts). Do not assume the outer gate alone protects the inner
+ * branch.
  */
-const TOOL_REQUIRED_SCOPE: Record<string, string> = {
-  "query-notes": SCOPE_READ,
-  "list-tags": SCOPE_READ,
-  "find-path": SCOPE_READ,
-  "vault-info": SCOPE_READ,
-  "create-note": SCOPE_WRITE,
-  "update-note": SCOPE_WRITE,
-  "delete-note": SCOPE_WRITE,
-  "update-tag": SCOPE_WRITE,
-  "delete-tag": SCOPE_WRITE,
+const TOOL_REQUIRED_VERB: Record<string, VaultVerb> = {
+  "query-notes": "read",
+  "list-tags": "read",
+  "find-path": "read",
+  "synthesize-notes": "read",
+  "vault-info": "read",
+  "create-note": "write",
+  "update-note": "write",
+  "delete-note": "write",
+  "update-tag": "write",
+  "delete-tag": "write",
 };
 
-function requiredScopeForTool(toolName: string): string {
+function requiredVerbForTool(toolName: string): VaultVerb {
   // Default-deny: unknown tools require write. Keeps accidental reads of
   // a not-yet-mapped mutation tool from slipping past.
-  return TOOL_REQUIRED_SCOPE[toolName] ?? SCOPE_WRITE;
+  return TOOL_REQUIRED_VERB[toolName] ?? "write";
 }
 
 /** Handle scoped MCP at /vault/{name}/mcp (single vault). */
 export async function handleScopedMcp(req: Request, vaultName: string, auth: AuthResult): Promise<Response> {
   const instruction = getServerInstruction(vaultName);
-  return handleMcp(req, () => generateScopedMcpTools(vaultName, auth), `parachute-vault/${vaultName}`, auth, instruction);
+  return handleMcp(req, () => generateScopedMcpTools(vaultName, auth), `parachute-vault/${vaultName}`, vaultName, auth, instruction);
 }
 
 async function handleMcp(
   req: Request,
   getTools: () => McpToolDef[],
   serverName: string,
+  vaultName: string,
   auth: AuthResult,
   instruction: string,
 ): Promise<Response> {
@@ -84,11 +86,11 @@ async function handleMcp(
   const mcpTools = getTools();
 
   // Filter the advertised tool list to what the caller's scopes actually
-  // permit. Callers without `vault:write` don't see mutation tools at all —
-  // matches the prior behavior of the read/full permission model but is now
-  // driven by scope inheritance.
+  // permit for THIS vault. Callers without write don't see mutation tools at
+  // all — matches the prior behavior of the read/full permission model but
+  // now driven by per-vault scope inheritance.
   const visibleTools = mcpTools.filter((t) =>
-    requireScope(auth, requiredScopeForTool(t.name)),
+    hasScopeForVault(auth.scopes, vaultName, requiredVerbForTool(t.name)),
   );
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -102,12 +104,12 @@ async function handleMcp(
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
 
-    const neededScope = requiredScopeForTool(name);
-    if (!requireScope(auth, neededScope)) {
+    const neededVerb = requiredVerbForTool(name);
+    if (!hasScopeForVault(auth.scopes, vaultName, neededVerb)) {
       return {
         content: [{
           type: "text" as const,
-          text: `Forbidden: tool '${name}' requires the '${neededScope}' scope. Granted scopes: ${auth.scopes.join(" ") || "(none)"}.`,
+          text: `Forbidden: tool '${name}' requires the 'vault:${neededVerb}' scope (or 'vault:${vaultName}:${neededVerb}'). Granted scopes: ${auth.scopes.join(" ") || "(none)"}.`,
         }],
         isError: true,
       };

package/src/mcp-install.ts

@@ -20,7 +20,7 @@ export type McpUrlSource = "hub-origin" | "expose-state" | "loopback";
 export function chooseMcpUrl(
   vaultName: string,
   port: number,
-  env: { PARACHUTE_HUB_ORIGIN?: string } = process.env,
+  env: { PARACHUTE_HUB_ORIGIN?: string | undefined } = process.env as { PARACHUTE_HUB_ORIGIN?: string },
 ): { url: string; source: McpUrlSource } {
   const hub = env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
   if (hub) {