@openparachute/vault 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to Parachute Vault are documented here.
 
 This project loosely follows [Keep a Changelog](https://keepachangelog.com) and [Semantic Versioning](https://semver.org).
 
+## [0.2.1] — 2026-04-17
+
+### Fixed
+
+- OAuth discovery now works against Claude Code's MCP SDK (and any other strict RFC 9728 client): 401 responses from the MCP endpoint carry a `WWW-Authenticate: Bearer resource_metadata="…"` header pointing at the scoped or unscoped protected-resource metadata document, matching the URL the client actually hit. Previously, clients with no pointer fell back to probing the root `/.well-known/oauth-protected-resource`, got `resource: <base>/mcp`, and rejected any connection to `/vaults/<name>/mcp` as a resource mismatch.
+
 ## [0.2.0] — 2026-04-17
 
 First tagged public release. Ships the auth, backup, and onboarding surface the project needs for first-wave users.
@@ -77,4 +83,5 @@ First tagged public release. Ships the auth, backup, and onboarding surface the
 - **`core/src/test-preload.ts`** isolates `PARACHUTE_HOME` for tests so `bun test` never touches a user's real `~/.parachute/`.
 - Test suite at release cut: **538 passing / 0 failing / 3 skipped** across 22 files (541 tests total).
 
+[0.2.1]: https://github.com/ParachuteComputer/parachute-vault/releases/tag/v0.2.1
 [0.2.0]: https://github.com/ParachuteComputer/parachute-vault/releases/tag/v0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/oauth.ts

@@ -44,7 +44,15 @@ export interface AuthorizePostOptions {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function getBaseUrl(req: Request): string {
+/**
+ * Public-facing base URL of the server. Honors `x-forwarded-*` headers so a
+ * Cloudflare Tunnel / Tailscale Funnel / reverse-proxied deployment advertises
+ * the right external origin in discovery documents (RFC 8414, RFC 9728).
+ *
+ * Exported so the router can build `WWW-Authenticate` challenge headers that
+ * point at the same origin as the `/.well-known/*` metadata documents.
+ */
+export function getBaseUrl(req: Request): string {
   const forwardedHost = req.headers.get("x-forwarded-host");
   const forwardedProto = req.headers.get("x-forwarded-proto");
   if (forwardedHost) {

package/src/routing.test.ts

@@ -345,3 +345,134 @@ describe("single-vault auto-default", () => {
     expect(res.status).toBe(401); // reached per-vault auth
   });
 });
+
+// ---------------------------------------------------------------------------
+// RFC 9728 WWW-Authenticate challenge on MCP 401.
+//
+// Claude Code's MCP SDK (and any other strict RFC 9728 client) requires the
+// server to emit `WWW-Authenticate: Bearer resource_metadata="..."` on 401
+// so the client knows which protected-resource metadata document applies to
+// the endpoint it just hit. Without it, clients fall back to probing the
+// root `/.well-known/oauth-protected-resource`, get `resource: <base>/mcp`,
+// and reject any connection to `/vaults/<name>/mcp` as a resource mismatch.
+// ---------------------------------------------------------------------------
+
+describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
+  test("unscoped /mcp 401 carries the root protected-resource pointer", async () => {
+    createVault("journal");
+    const req = new Request("http://localhost:1940/mcp");
+    const res = await route(req, "/mcp");
+    expect(res.status).toBe(401);
+    const header = res.headers.get("WWW-Authenticate");
+    expect(header).toBe(
+      'Bearer resource_metadata="http://localhost:1940/.well-known/oauth-protected-resource"',
+    );
+  });
+
+  test("scoped /vaults/{name}/mcp 401 carries the vault-scoped pointer", async () => {
+    createVault("journal");
+    const req = new Request("http://localhost:1940/vaults/journal/mcp");
+    const res = await route(req, "/vaults/journal/mcp");
+    expect(res.status).toBe(401);
+    const header = res.headers.get("WWW-Authenticate");
+    expect(header).toBe(
+      'Bearer resource_metadata="http://localhost:1940/vaults/journal/.well-known/oauth-protected-resource"',
+    );
+  });
+
+  test("challenge points at the same PRM document the server actually serves", async () => {
+    // Belt-and-braces: whatever we advertise in the header MUST line up with
+    // what `/.well-known/oauth-protected-resource` actually returns. If these
+    // drift, a conforming client will chase the pointer, fetch the PRM, then
+    // reject on resource mismatch anyway. Test both directions.
+    createVault("journal");
+
+    // Scoped: header points at /vaults/journal/.well-known/...
+    const scopedReq = new Request("http://localhost:1940/vaults/journal/mcp");
+    const scopedRes = await route(scopedReq, "/vaults/journal/mcp");
+    const scopedHeader = scopedRes.headers.get("WWW-Authenticate")!;
+    const scopedPrmUrl = scopedHeader.match(/resource_metadata="([^"]+)"/)![1];
+    // Fetch that PRM. Bypass the full URL by extracting the path.
+    const prmPath = new URL(scopedPrmUrl).pathname;
+    const prmRes = await route(new Request(`http://localhost:1940${prmPath}`), prmPath);
+    expect(prmRes.status).toBe(200);
+    const prm = (await prmRes.json()) as { resource: string };
+    expect(prm.resource).toBe("http://localhost:1940/vaults/journal/mcp");
+
+    // Unscoped: header points at root /.well-known/...
+    const unscopedReq = new Request("http://localhost:1940/mcp");
+    const unscopedRes = await route(unscopedReq, "/mcp");
+    const unscopedHeader = unscopedRes.headers.get("WWW-Authenticate")!;
+    const unscopedPrmUrl = unscopedHeader.match(/resource_metadata="([^"]+)"/)![1];
+    const unscopedPrmPath = new URL(unscopedPrmUrl).pathname;
+    const unscopedPrmRes = await route(
+      new Request(`http://localhost:1940${unscopedPrmPath}`),
+      unscopedPrmPath,
+    );
+    expect(unscopedPrmRes.status).toBe(200);
+    const unscopedPrm = (await unscopedPrmRes.json()) as { resource: string };
+    expect(unscopedPrm.resource).toBe("http://localhost:1940/mcp");
+  });
+
+  test("MCP 401 with invalid token still carries the challenge", async () => {
+    // The no-token case is one 401 code path (extractApiKey returns null);
+    // the invalid-token case is another (extractApiKey returns a string but
+    // resolveToken / validateKey all fail). Both must emit the header.
+    createVault("journal");
+    const req = new Request("http://localhost:1940/vaults/journal/mcp", {
+      headers: { Authorization: "Bearer pvt_not-a-real-token" },
+    });
+    const res = await route(req, "/vaults/journal/mcp");
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toBe(
+      'Bearer resource_metadata="http://localhost:1940/vaults/journal/.well-known/oauth-protected-resource"',
+    );
+  });
+
+  test("non-MCP 401s do NOT carry the challenge (spec is MCP-only)", async () => {
+    // The RFC 9728 challenge header is specific to the MCP resource; plain
+    // REST endpoints are not OAuth resources in the same sense. A spurious
+    // challenge here could confuse non-MCP clients and makes the /api
+    // surface look OAuth-gated when it is not.
+    createVault("journal");
+
+    // /api/notes (unscoped) — 401, no challenge.
+    const unscopedApi = await route(new Request("http://localhost:1940/api/notes"), "/api/notes");
+    expect(unscopedApi.status).toBe(401);
+    expect(unscopedApi.headers.get("WWW-Authenticate")).toBeNull();
+
+    // /vaults/journal/api/notes (scoped) — 401, no challenge. This is the
+    // code path that shares the auth check with the scoped MCP branch, so
+    // if we leak the header here the isScopedMcp gate has regressed.
+    const scopedApi = await route(
+      new Request("http://localhost:1940/vaults/journal/api/notes"),
+      "/vaults/journal/api/notes",
+    );
+    expect(scopedApi.status).toBe(401);
+    expect(scopedApi.headers.get("WWW-Authenticate")).toBeNull();
+
+    // /vaults (authenticated listing) — 401, no challenge.
+    const vaultsList = await route(new Request("http://localhost:1940/vaults"), "/vaults");
+    expect(vaultsList.status).toBe(401);
+    expect(vaultsList.headers.get("WWW-Authenticate")).toBeNull();
+  });
+
+  test("x-forwarded-host and x-forwarded-proto shape the challenge URL", async () => {
+    // Remote deployments behind Cloudflare Tunnel / Tailscale Funnel / any
+    // reverse proxy need the challenge URL to match the external origin,
+    // not the 127.0.0.1:1940 the server actually binds. Parallels how the
+    // /.well-known/* endpoints already honor these headers.
+    createVault("journal");
+    const req = new Request("http://127.0.0.1:1940/vaults/journal/mcp", {
+      headers: {
+        "x-forwarded-host": "vault.example.com",
+        "x-forwarded-proto": "https",
+      },
+    });
+    const res = await route(req, "/vaults/journal/mcp");
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toBe(
+      'Bearer resource_metadata="https://vault.example.com/vaults/journal/.well-known/oauth-protected-resource"',
+    );
+  });
+});

package/src/routing.ts

@@ -49,8 +49,49 @@ import {
   handleAuthorizeGet,
   handleAuthorizePost,
   handleToken,
+  getBaseUrl,
 } from "./oauth.ts";
 
+/**
+ * Decorate a 401 response from the MCP endpoint with the RFC 9728 challenge
+ * header pointing at the matching protected-resource metadata document.
+ *
+ * An MCP-capable OAuth client that receives a plain 401 has no structured way
+ * to discover which authorization server to use, and SDKs that follow RFC 9728
+ * (including Claude Code's) default to probing the *root* `/.well-known/oauth-
+ * protected-resource`. That document advertises `resource: <base>/mcp` — which
+ * then fails the SDK's strict resource-URL match when the client is actually
+ * connecting to `/vaults/{name}/mcp`. The `WWW-Authenticate` header tells the
+ * client exactly which metadata document applies to the endpoint it just hit,
+ * closing the mismatch.
+ *
+ * Scoped calls pass `vaultName`; unscoped omits it. Other 401-emitting
+ * endpoints (`/api/*`, `/vaults`, `/health` when authenticated) are not MCP
+ * resources and intentionally do not carry this header.
+ */
+function mcpWwwAuthenticate(req: Request, vaultName?: string): string {
+  const base = getBaseUrl(req);
+  const prefix = vaultName ? `/vaults/${vaultName}` : "";
+  return `Bearer resource_metadata="${base}${prefix}/.well-known/oauth-protected-resource"`;
+}
+
+/**
+ * Clone a 401 Response and attach the `WWW-Authenticate` challenge header.
+ * The auth module returns a fully-baked `Response`, and headers on a consumed
+ * `Response` can't be mutated in place; cloning is the cheap path.
+ */
+async function withMcpChallenge(
+  res: Response,
+  req: Request,
+  vaultName?: string,
+): Promise<Response> {
+  if (res.status !== 401) return res;
+  const body = await res.text();
+  const headers = new Headers(res.headers);
+  headers.set("WWW-Authenticate", mcpWwwAuthenticate(req, vaultName));
+  return new Response(body, { status: 401, headers });
+}
+
 /**
  * Check if a /view request has a valid API key (header or ?key= query param).
  * Returns true if authenticated, false if not. Never rejects — unauthenticated
@@ -134,7 +175,7 @@ export async function route(
   // Unified MCP (all vaults, global auth)
   if (path === "/mcp" || path.startsWith("/mcp/")) {
     const auth = authenticateGlobalRequest(req);
-    if ("error" in auth) return auth.error;
+    if ("error" in auth) return withMcpChallenge(auth.error, req);
     return handleUnifiedMcp(req, auth);
   }
 
@@ -308,13 +349,20 @@ export async function route(
     return handleAuthorizationServer(req, vaultName);
   }
 
-  // Auth: per-vault key OR global key
+  // Auth: per-vault key OR global key.
+  // The auth check is shared between the scoped MCP branch and the scoped
+  // /api/* branches, so we can't unconditionally attach the MCP-only
+  // WWW-Authenticate challenge here — we pass the challenge back only when
+  // the failing request was actually targeting /vaults/{name}/mcp.
   const store = getVaultStore(vaultName);
   const auth = authenticateVaultRequest(req, vaultConfig, store.db);
-  if ("error" in auth) return auth.error;
+  const isScopedMcp = subpath === "/mcp" || subpath.startsWith("/mcp/");
+  if ("error" in auth) {
+    return isScopedMcp ? withMcpChallenge(auth.error, req, vaultName) : auth.error;
+  }
 
   // Per-vault scoped MCP
-  if (subpath === "/mcp" || subpath.startsWith("/mcp/")) {
+  if (isScopedMcp) {
     return handleScopedMcp(req, vaultName, auth);
   }