@openparachute/vault 0.2.3 → 0.3.0-rc.1

package/src/mcp-install.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Tests for the MCP URL picker used by `mcp-install`. The picker must match
+ * vault's advertised OAuth issuer for the origin a client will reach it on —
+ * otherwise Claude Code (and any strict RFC 8414 client) rejects the
+ * discovery response on issuer/origin mismatch.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { chooseMcpUrl } from "./mcp-install.ts";
+
+describe("chooseMcpUrl", () => {
+  let tmpHome: string;
+  let origHome: string | undefined;
+
+  beforeEach(() => {
+    origHome = process.env.PARACHUTE_HOME;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "vault-mcp-install-"));
+    process.env.PARACHUTE_HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (origHome === undefined) delete process.env.PARACHUTE_HOME;
+    else process.env.PARACHUTE_HOME = origHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  test("prefers PARACHUTE_HUB_ORIGIN when set", () => {
+    const res = chooseMcpUrl("default", 1940, {
+      PARACHUTE_HUB_ORIGIN: "https://hub.example",
+    });
+    expect(res).toEqual({
+      url: "https://hub.example/vault/default/mcp",
+      source: "hub-origin",
+    });
+  });
+
+  test("strips trailing slash on PARACHUTE_HUB_ORIGIN", () => {
+    const res = chooseMcpUrl("default", 1940, {
+      PARACHUTE_HUB_ORIGIN: "https://hub.example/",
+    });
+    expect(res.url).toBe("https://hub.example/vault/default/mcp");
+  });
+
+  test("falls back to tailnet/public FQDN from expose-state.json when hub env unset", () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "expose-state.json"),
+      JSON.stringify({
+        version: 1,
+        layer: "tailnet",
+        mode: "path",
+        canonicalFqdn: "parachute.taildf9ce2.ts.net",
+        port: 1940,
+        funnel: false,
+        entries: [],
+      }),
+    );
+    const res = chooseMcpUrl("default", 1940, {});
+    expect(res).toEqual({
+      url: "https://parachute.taildf9ce2.ts.net/vault/default/mcp",
+      source: "expose-state",
+    });
+  });
+
+  test("uses public FQDN from expose-state.json when layer is public", () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "expose-state.json"),
+      JSON.stringify({
+        version: 1,
+        layer: "public",
+        mode: "subdomain",
+        canonicalFqdn: "vault.parachute.computer",
+        port: 1940,
+        funnel: true,
+        entries: [],
+      }),
+    );
+    const res = chooseMcpUrl("default", 1940, {});
+    expect(res.url).toBe("https://vault.parachute.computer/vault/default/mcp");
+    expect(res.source).toBe("expose-state");
+  });
+
+  test("falls back to loopback when no hub env and no expose-state", () => {
+    const res = chooseMcpUrl("default", 1940, {});
+    expect(res).toEqual({
+      url: "http://127.0.0.1:1940/vault/default/mcp",
+      source: "loopback",
+    });
+  });
+
+  test("hub env wins over an active exposure", () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "expose-state.json"),
+      JSON.stringify({
+        version: 1,
+        layer: "tailnet",
+        mode: "path",
+        canonicalFqdn: "parachute.taildf9ce2.ts.net",
+        port: 1940,
+        funnel: false,
+        entries: [],
+      }),
+    );
+    const res = chooseMcpUrl("default", 1940, {
+      PARACHUTE_HUB_ORIGIN: "https://hub.example",
+    });
+    expect(res.source).toBe("hub-origin");
+    expect(res.url).toBe("https://hub.example/vault/default/mcp");
+  });
+
+  test("falls back to loopback on a malformed expose-state.json", () => {
+    fs.writeFileSync(path.join(tmpHome, "expose-state.json"), "{ not json");
+    const res = chooseMcpUrl("default", 1940, {});
+    expect(res.source).toBe("loopback");
+  });
+
+  test("honors the passed-in vault name in the URL path", () => {
+    const res = chooseMcpUrl("work", 1940, {
+      PARACHUTE_HUB_ORIGIN: "https://hub.example",
+    });
+    expect(res.url).toBe("https://hub.example/vault/work/mcp");
+  });
+});

package/src/mcp-install.ts

@@ -0,0 +1,60 @@
+/**
+ * URL picker for `parachute-vault mcp-install`. The URL written into
+ * `~/.claude.json` must match vault's advertised OAuth issuer for the origin
+ * the client will reach the server on — otherwise strict clients (Claude
+ * Code's MCP SDK) reject discovery on origin/issuer mismatch (RFC 8414 §3.1).
+ *
+ * Selection order:
+ *   1. `PARACHUTE_HUB_ORIGIN` env (vault is advertising the hub as issuer).
+ *   2. `~/.parachute/expose-state.json` canonical FQDN (active tailnet /
+ *      public exposure the CLI brought up).
+ *   3. Loopback on the configured port.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+export type McpUrlSource = "hub-origin" | "expose-state" | "loopback";
+
+export function chooseMcpUrl(
+  vaultName: string,
+  port: number,
+  env: { PARACHUTE_HUB_ORIGIN?: string } = process.env,
+): { url: string; source: McpUrlSource } {
+  const hub = env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
+  if (hub) {
+    return { url: `${hub}/vault/${vaultName}/mcp`, source: "hub-origin" };
+  }
+  const fqdn = readExposedFqdn();
+  if (fqdn) {
+    return { url: `https://${fqdn}/vault/${vaultName}/mcp`, source: "expose-state" };
+  }
+  return { url: `http://127.0.0.1:${port}/vault/${vaultName}/mcp`, source: "loopback" };
+}
+
+/**
+ * Best-effort read of `~/.parachute/expose-state.json` (CLI-owned). Returns
+ * the canonical FQDN when an active tailnet/public exposure is configured;
+ * returns undefined on any error or when absent — this is advisory, not
+ * load-bearing.
+ *
+ * Re-derives the ecosystem root per-call so tests that flip `PARACHUTE_HOME`
+ * see the override — the top-level `CONFIG_DIR` const in config.ts is frozen
+ * at module import.
+ */
+function readExposedFqdn(): string | undefined {
+  try {
+    const root = process.env.PARACHUTE_HOME ?? resolve(homedir(), ".parachute");
+    const p = resolve(root, "expose-state.json");
+    if (!existsSync(p)) return undefined;
+    const raw = JSON.parse(readFileSync(p, "utf-8")) as {
+      layer?: string;
+      canonicalFqdn?: string;
+    };
+    if ((raw.layer === "tailnet" || raw.layer === "public") && raw.canonicalFqdn) {
+      return raw.canonicalFqdn;
+    }
+  } catch {}
+  return undefined;
+}

package/src/mcp-tools.ts

@@ -1,25 +1,26 @@
 /**
- * MCP tool generation for multi-vault.
+ * MCP tool generation for the scoped (per-vault) MCP endpoint.
  *
- * Wraps core tools with vault resolution (optional `vault` param) and
- * overrides vault-info with actual vault config access.
+ * Every MCP session is now bound to one vault via `/vault/<name>/mcp`, so
+ * tools operate on that vault and vault-info picks up its config directly.
  */
 
 import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
-import { readVaultConfig, writeVaultConfig, listVaults as getVaultNames, resolveDefaultVault } from "./config.ts";
+import { readVaultConfig, writeVaultConfig } from "./config.ts";
 import { getVaultStore } from "./vault-store.ts";
+import { hasScope, SCOPE_WRITE } from "./scopes.ts";
+import type { AuthResult } from "./auth.ts";
 
 /**
- * Get the MCP server instruction for a vault (or the default vault).
+ * Get the MCP server instruction for a vault.
  * Sent once at session init — not per tool.
  */
-export function getServerInstruction(vaultName?: string): string {
-  const name = vaultName ?? resolveDefaultVault() ?? "default";
-  const config = readVaultConfig(name);
+export function getServerInstruction(vaultName: string): string {
+  const config = readVaultConfig(vaultName);
 
   const parts: string[] = [
-    `You are connected to Parachute Vault "${name}".`,
+    `You are connected to Parachute Vault "${vaultName}".`,
   ];
 
   if (config?.description) {
@@ -29,111 +30,48 @@ export function getServerInstruction(vaultName?: string): string {
   return parts.join("\n");
 }
 
-/**
- * Generate the unified MCP tool set.
- * Each tool has an optional `vault` param that defaults to the default vault.
- */
-export function generateUnifiedMcpTools(): McpToolDef[] {
-  const vaultNames = getVaultNames();
-  const defaultVault = resolveDefaultVault() ?? "default";
-  const multiVault = vaultNames.length > 1;
-
-  // Get tool definitions from core (using default vault for schema)
-  const defaultStore = getVaultStore(defaultVault);
-  const coreTools = generateMcpTools(defaultStore);
-
-  // Wrap each core tool with vault resolution
-  const tools: McpToolDef[] = coreTools.map((coreTool) => {
-    let description = coreTool.description;
-    if (multiVault) {
-      description += `\n\nMulti-vault: pass 'vault' to target a specific vault. Default: "${defaultVault}". Available: ${vaultNames.join(", ")}`;
-    }
-
-    const inputSchema = {
-      ...coreTool.inputSchema,
-      properties: {
-        vault: {
-          type: "string",
-          description: `Vault name (default: "${defaultVault}")`,
-        },
-        ...(coreTool.inputSchema as any).properties,
-      },
-    };
-
-    return {
-      name: coreTool.name,
-      description,
-      inputSchema,
-      execute: async (params) => {
-        const vaultName = (params.vault as string) ?? defaultVault;
-        const config = readVaultConfig(vaultName);
-        if (!config) {
-          throw new Error(`Vault "${vaultName}" not found. Available: ${getVaultNames().join(", ")}`);
-        }
-        const store = getVaultStore(vaultName);
-        const vaultTools = generateMcpTools(store);
-        const tool = vaultTools.find((t) => t.name === coreTool.name)!;
-        const { vault: _, ...rest } = params;
-        return await tool.execute(rest);
-      },
-    };
-  });
-
-  // Override vault-info with actual vault config access
-  overrideVaultInfo(tools, defaultVault);
-
-  // Add list-vaults (multi-vault only, not in core)
-  if (multiVault) {
-    tools.push({
-      name: "list-vaults",
-      description: "List all available vaults with their descriptions.",
-      inputSchema: { type: "object", properties: {} },
-      execute: () => {
-        const names = getVaultNames();
-        return names.map((name) => {
-          const config = readVaultConfig(name);
-          return {
-            name,
-            description: config?.description,
-            created_at: config?.created_at,
-            is_default: name === defaultVault,
-          };
-        });
-      },
-    });
-  }
-
-  return tools;
-}
-
 /**
  * Generate MCP tools scoped to a single vault.
- * No vault param — tools operate on that vault only.
+ *
+ * `auth` is the resolved token for the caller and is captured by vault-info's
+ * execute closure so the description-update branch can perform a secondary
+ * scope check: the tool itself is gated at vault:read (so read-only callers
+ * can fetch stats), but writing a new description requires vault:write.
+ *
+ * When omitted (internal callers that only inspect the tool list — no execute
+ * path exercised), the description-update branch is disabled entirely.
  */
-export function generateScopedMcpTools(vaultName: string): McpToolDef[] {
+export function generateScopedMcpTools(vaultName: string, auth?: AuthResult): McpToolDef[] {
   const store = getVaultStore(vaultName);
   const tools = generateMcpTools(store);
 
-  // Override vault-info with actual vault config access
-  overrideVaultInfo(tools, vaultName);
+  overrideVaultInfo(tools, vaultName, auth);
 
   return tools;
 }
 
-/**
- * Override vault-info's placeholder execute with real vault config access.
- */
-function overrideVaultInfo(tools: McpToolDef[], defaultVault: string): void {
+function overrideVaultInfo(
+  tools: McpToolDef[],
+  vaultName: string,
+  auth: AuthResult | undefined,
+): void {
   const vaultInfo = tools.find((t) => t.name === "vault-info");
   if (!vaultInfo) return;
 
   vaultInfo.execute = async (params) => {
-    const vaultName = (params.vault as string) ?? defaultVault;
     const config = readVaultConfig(vaultName);
     if (!config) throw new Error(`Vault "${vaultName}" not found`);
 
-    // Update description if provided
     if (params.description !== undefined) {
+      // Secondary scope check: vault-info is read-gated so read-only callers
+      // can fetch stats, but mutating the vault description requires write.
+      // Without this, a vault:read token could bypass the outer gate by
+      // passing `description` to a tool the outer gate considers read-only.
+      if (!auth || !hasScope(auth.scopes, SCOPE_WRITE)) {
+        throw new Error(
+          `Forbidden: updating the vault description requires the '${SCOPE_WRITE}' scope. Granted scopes: ${auth?.scopes.join(" ") || "(none)"}.`,
+        );
+      }
       config.description = params.description as string;
       writeVaultConfig(config);
     }

package/src/module-config.ts

@@ -0,0 +1,109 @@
+/**
+ * Module configuration endpoints (Phase 2 of the module architecture).
+ *
+ * Every Parachute module exposes two paired endpoints:
+ *
+ *   GET /.parachute/config/schema  — JSON Schema (draft-07) describing the
+ *                                    module's configurable shape. Hub renders
+ *                                    a form from this schema. No auth.
+ *   GET /.parachute/config         — current effective values, with
+ *                                    `writeOnly` fields excluded. No auth for
+ *                                    now (hub is loopback-only through
+ *                                    Phase 0–2); gated by `vault:admin` scope
+ *                                    once scope enforcement lands in Phase 3.
+ *
+ * PUT /.parachute/config is Phase 3 — not implemented here.
+ *
+ * Fields currently described:
+ *   - audio_retention: per-vault enum, backed by VaultConfig.audio_retention.
+ *   - scribe_url:      env var SCRIBE_URL (read-only for now — there is no
+ *                      yaml slot yet, so PUT won't come online until Phase 3).
+ *   - scribe_token:    env var SCRIBE_TOKEN, writeOnly (never returned).
+ *   - port:            GlobalConfig.port, exposed read-only so the hub can
+ *                      display it without round-tripping through /health.
+ */
+
+import type { VaultConfig, GlobalConfig } from "./config.ts";
+
+export interface ModuleConfigSchema {
+  $schema: string;
+  type: "object";
+  title: string;
+  description: string;
+  properties: Record<string, unknown>;
+}
+
+export function buildConfigSchema(): ModuleConfigSchema {
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    type: "object",
+    title: "Vault configuration",
+    description:
+      "Settings that control vault's runtime behavior. Hub renders this schema into a configuration form.",
+    properties: {
+      audio_retention: {
+        type: "string",
+        enum: ["keep", "until_transcribed", "never"],
+        default: "keep",
+        title: "Audio retention",
+        description:
+          "What to do with audio attachments after transcription. `keep` leaves the file on disk; `until_transcribed` unlinks on successful transcribe (keeps on failure for retry); `never` unlinks on any terminal state (including failure — no retries).",
+      },
+      scribe_url: {
+        type: "string",
+        format: "uri",
+        title: "Scribe URL",
+        description:
+          "URL of the Scribe service for transcription. Empty disables the background worker. Currently sourced from the SCRIBE_URL env var; a PUT slot lands in Phase 3.",
+        readOnly: true,
+      },
+      scribe_token: {
+        type: "string",
+        title: "Scribe auth token",
+        description:
+          "Optional bearer token for Scribe. Stored in the SCRIBE_TOKEN env var today. Write-only — never returned by GET.",
+        writeOnly: true,
+      },
+      port: {
+        type: "integer",
+        minimum: 1,
+        maximum: 65535,
+        title: "HTTP port",
+        description: "Port the vault server listens on. Set at init time; changing requires a restart.",
+        readOnly: true,
+      },
+    },
+  };
+}
+
+/**
+ * Effective config values, with `writeOnly` fields stripped. `scribe_token` is
+ * declared `writeOnly` and is never returned here, even when SCRIBE_TOKEN is
+ * set in the environment.
+ */
+export function buildConfigValues(
+  vaultConfig: VaultConfig,
+  globalConfig: GlobalConfig,
+  env: { SCRIBE_URL?: string } = process.env,
+): Record<string, unknown> {
+  return {
+    audio_retention: vaultConfig.audio_retention ?? "keep",
+    scribe_url: env.SCRIBE_URL ?? "",
+    port: globalConfig.port,
+  };
+}
+
+export function handleConfigSchema(): Response {
+  return Response.json(buildConfigSchema(), {
+    headers: { "Access-Control-Allow-Origin": "*" },
+  });
+}
+
+export function handleConfig(
+  vaultConfig: VaultConfig,
+  globalConfig: GlobalConfig,
+): Response {
+  return Response.json(buildConfigValues(vaultConfig, globalConfig), {
+    headers: { "Access-Control-Allow-Origin": "*" },
+  });
+}