@openparachute/vault 0.4.7-rc.2 → 0.4.8-rc.10

package/src/routing.test.ts

@@ -455,19 +455,21 @@ describe("per-vault routing under /vault/<name>/", () => {
     expect(res.status).toBe(401);
   });
 
-  test("/vault/<name>/oauth/register reaches the OAuth handler", async () => {
+  test("/vault/<name>/oauth/* returns 410 Gone (standalone issuer retired — workstream E)", async () => {
+    // The standalone OAuth issuer on vault was removed in vault#366 once hub
+    // became required. The 410 carries a pointer to the protected-resource
+    // metadata so a confused client can rediscover the new issuer (the hub).
     createVault("journal");
-    const path = "/vault/journal/oauth/register";
-    const res = await route(
-      new Request(`http://localhost:1940${path}`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ client_name: "test", redirect_uris: ["https://x.example/cb"] }),
-      }),
-      path,
-    );
-    expect(res.status).not.toBe(500);
-    expect([201, 400]).toContain(res.status);
+    for (const subpath of ["/oauth/register", "/oauth/authorize", "/oauth/token"]) {
+      const path = `/vault/journal${subpath}`;
+      const res = await route(new Request(`http://localhost:1940${path}`), path);
+      expect(res.status).toBe(410);
+      const body = (await res.json()) as { error: string; protected_resource_metadata: string };
+      expect(body.error).toBe("oauth_endpoint_removed");
+      expect(body.protected_resource_metadata).toBe(
+        "http://localhost:1940/vault/journal/.well-known/oauth-protected-resource",
+      );
+    }
   });
 
   test("unknown vault returns 404 before hitting auth", async () => {
@@ -475,7 +477,6 @@ describe("per-vault routing under /vault/<name>/", () => {
     for (const path of [
       "/vault/nonexistent/mcp",
       "/vault/nonexistent/api/notes",
-      "/vault/nonexistent/oauth/register",
     ]) {
       const res = await route(new Request(`http://localhost:1940${path}`), path);
       expect(res.status).toBe(404);
@@ -591,15 +592,22 @@ describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
 // ---------------------------------------------------------------------------
 // Per-vault OAuth discovery (RFC 8414 / RFC 9728, path-append form).
 //
-// For a resource at `/vault/<name>/mcp`, clients fetch metadata from
+// After workstream E (2026-05-25), vault is resource-server-only — hub is
+// the OAuth issuer. The discovery endpoints stay served at
 //   /vault/<name>/.well-known/oauth-protected-resource
 //   /vault/<name>/.well-known/oauth-authorization-server
-// All endpoints in the AS metadata are vault-scoped so a client that
-// discovers the AS at that URL can drive the full authorization flow.
+// but the metadata they return forwards every authorization-server endpoint
+// to the hub origin. The `resource` URL still names the vault's MCP path
+// (that's the resource being protected); the AS pointer is the hub.
+//
+// `PARACHUTE_HUB_ORIGIN` defaults to `http://127.0.0.1:1939` when unset
+// (canonical hub loopback). Tests below assert against that default.
 // ---------------------------------------------------------------------------
 
-describe("per-vault OAuth discovery", () => {
-  test("/vault/<name>/.well-known/oauth-authorization-server returns vault-scoped AS metadata", async () => {
+const HUB_ORIGIN = "http://127.0.0.1:1939";
+
+describe("per-vault OAuth discovery (hub-rooted after workstream E)", () => {
+  test("AS metadata names the hub as issuer + endpoints", async () => {
     createVault("journal");
     const path = "/vault/journal/.well-known/oauth-authorization-server";
     const res = await route(new Request(`http://localhost:1940${path}`), path);
@@ -609,21 +617,23 @@ describe("per-vault OAuth discovery", () => {
       authorization_endpoint: string;
       token_endpoint: string;
       registration_endpoint: string;
+      jwks_uri: string;
     };
-    expect(body.issuer).toBe("http://localhost:1940/vault/journal");
-    expect(body.authorization_endpoint).toBe("http://localhost:1940/vault/journal/oauth/authorize");
-    expect(body.token_endpoint).toBe("http://localhost:1940/vault/journal/oauth/token");
-    expect(body.registration_endpoint).toBe("http://localhost:1940/vault/journal/oauth/register");
+    expect(body.issuer).toBe(HUB_ORIGIN);
+    expect(body.authorization_endpoint).toBe(`${HUB_ORIGIN}/oauth/authorize`);
+    expect(body.token_endpoint).toBe(`${HUB_ORIGIN}/oauth/token`);
+    expect(body.registration_endpoint).toBe(`${HUB_ORIGIN}/oauth/register`);
+    expect(body.jwks_uri).toBe(`${HUB_ORIGIN}/.well-known/jwks.json`);
   });
 
-  test("/vault/<name>/.well-known/oauth-protected-resource returns vault-scoped PRM", async () => {
+  test("PRM names the vault's MCP endpoint and points at the hub as AS", async () => {
     createVault("journal");
     const path = "/vault/journal/.well-known/oauth-protected-resource";
     const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(200);
     const body = (await res.json()) as { resource: string; authorization_servers: string[] };
     expect(body.resource).toBe("http://localhost:1940/vault/journal/mcp");
-    expect(body.authorization_servers).toEqual(["http://localhost:1940/vault/journal"]);
+    expect(body.authorization_servers).toEqual([HUB_ORIGIN]);
   });
 
   test("unknown vault returns 404 rather than boilerplate metadata", async () => {
@@ -637,7 +647,28 @@ describe("per-vault OAuth discovery", () => {
     }
   });
 
-  test("x-forwarded-* headers propagate into the generated metadata URLs", async () => {
+  test("x-forwarded-* headers propagate into the PRM `resource` URL", async () => {
+    // The resource URL still tracks the vault's external origin (it's the
+    // protected resource the client just hit); the AS pointer is always the
+    // hub, independent of the inbound request's origin.
+    createVault("journal");
+    const path = "/vault/journal/.well-known/oauth-protected-resource";
+    const res = await route(
+      new Request(`http://127.0.0.1:1940${path}`, {
+        headers: {
+          "x-forwarded-host": "vault.example.com",
+          "x-forwarded-proto": "https",
+        },
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { resource: string; authorization_servers: string[] };
+    expect(body.resource).toBe("https://vault.example.com/vault/journal/mcp");
+    expect(body.authorization_servers).toEqual([HUB_ORIGIN]);
+  });
+
+  test("AS metadata ignores x-forwarded-* (hub origin is config, not request-derived)", async () => {
     createVault("journal");
     const path = "/vault/journal/.well-known/oauth-authorization-server";
     const res = await route(
@@ -651,16 +682,16 @@ describe("per-vault OAuth discovery", () => {
     );
     expect(res.status).toBe(200);
     const body = (await res.json()) as { issuer: string; registration_endpoint: string };
-    expect(body.issuer).toBe("https://vault.example.com/vault/journal");
-    expect(body.registration_endpoint).toBe(
-      "https://vault.example.com/vault/journal/oauth/register",
-    );
+    expect(body.issuer).toBe(HUB_ORIGIN);
+    expect(body.registration_endpoint).toBe(`${HUB_ORIGIN}/oauth/register`);
   });
 
-  test("end-to-end flow: WWW-Authenticate → PRM → AS metadata → registration_endpoint is live", async () => {
-    // On 401, follow the challenge to the PRM, then follow
-    // PRM.authorization_servers[0] to the AS metadata, then hit the
-    // `registration_endpoint`. Every hop must resolve.
+  test("end-to-end flow: WWW-Authenticate → PRM → hub AS metadata pointer", async () => {
+    // On 401, follow the challenge to the PRM, then read
+    // PRM.authorization_servers[0] — it must point at the hub origin. The
+    // hub side of the test (fetching the AS metadata at the hub itself)
+    // lives in hub's test suite; here we just verify vault stops at the
+    // right pointer.
     createVault("journal");
 
     // Step 1: unauthenticated MCP → 401 + WWW-Authenticate.
@@ -675,29 +706,9 @@ describe("per-vault OAuth discovery", () => {
     const prmRes = await route(new Request(`http://localhost:1940${prmPath}`), prmPath);
     expect(prmRes.status).toBe(200);
     const prm = (await prmRes.json()) as { authorization_servers: string[] };
-    const asBase = prm.authorization_servers[0]; // "http://localhost:1940/vault/journal"
 
-    // Step 3: AS metadata lives at `{asBase}/.well-known/oauth-authorization-server`.
-    const asBasePath = new URL(asBase).pathname; // "/vault/journal"
-    const asMetaPath = `${asBasePath}/.well-known/oauth-authorization-server`;
-    const asRes = await route(new Request(`http://localhost:1940${asMetaPath}`), asMetaPath);
-    expect(asRes.status).toBe(200);
-    const asMeta = (await asRes.json()) as { registration_endpoint: string };
-
-    // Step 4: the advertised registration_endpoint must be live.
-    const regPath = new URL(asMeta.registration_endpoint).pathname;
-    const regRes = await route(
-      new Request(`http://localhost:1940${regPath}`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          client_name: "Test",
-          redirect_uris: ["https://example.com/cb"],
-        }),
-      }),
-      regPath,
-    );
-    expect(regRes.status).toBe(201);
+    // Step 3: the AS pointer is the hub. Clients drive the flow from there.
+    expect(prm.authorization_servers).toEqual([HUB_ORIGIN]);
   });
 });
 
@@ -716,7 +727,7 @@ describe("per-vault OAuth discovery", () => {
 // ---------------------------------------------------------------------------
 
 describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
-  test("AS metadata at path-insertion short form returns vault-scoped endpoints", async () => {
+  test("AS metadata at path-insertion short form names the hub", async () => {
     createVault("journal");
     const path = "/.well-known/oauth-authorization-server/vault/journal";
     const res = await route(new Request(`http://localhost:1940${path}`), path);
@@ -727,10 +738,10 @@ describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
       token_endpoint: string;
       registration_endpoint: string;
     };
-    expect(body.issuer).toBe("http://localhost:1940/vault/journal");
-    expect(body.authorization_endpoint).toBe("http://localhost:1940/vault/journal/oauth/authorize");
-    expect(body.token_endpoint).toBe("http://localhost:1940/vault/journal/oauth/token");
-    expect(body.registration_endpoint).toBe("http://localhost:1940/vault/journal/oauth/register");
+    expect(body.issuer).toBe(HUB_ORIGIN);
+    expect(body.authorization_endpoint).toBe(`${HUB_ORIGIN}/oauth/authorize`);
+    expect(body.token_endpoint).toBe(`${HUB_ORIGIN}/oauth/token`);
+    expect(body.registration_endpoint).toBe(`${HUB_ORIGIN}/oauth/register`);
   });
 
   test("AS metadata at path-insertion long form (/mcp suffix) also works", async () => {
@@ -741,7 +752,7 @@ describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
     const res = await route(new Request(`http://localhost:1940${path}`), path);
     expect(res.status).toBe(200);
     const body = (await res.json()) as { issuer: string };
-    expect(body.issuer).toBe("http://localhost:1940/vault/journal");
+    expect(body.issuer).toBe(HUB_ORIGIN);
   });
 
   test("PRM at path-insertion short form returns vault-scoped resource", async () => {
@@ -751,7 +762,7 @@ describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
     expect(res.status).toBe(200);
     const body = (await res.json()) as { resource: string; authorization_servers: string[] };
     expect(body.resource).toBe("http://localhost:1940/vault/journal/mcp");
-    expect(body.authorization_servers).toEqual(["http://localhost:1940/vault/journal"]);
+    expect(body.authorization_servers).toEqual([HUB_ORIGIN]);
   });
 
   test("PRM at path-insertion long form (/mcp suffix) also works", async () => {
@@ -808,7 +819,9 @@ describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
     }
   });
 
-  test("x-forwarded-* headers propagate through path-insertion URLs", async () => {
+  test("AS metadata at path-insertion is hub-rooted regardless of x-forwarded-*", async () => {
+    // Hub origin is configuration, not request-derived. Proxies forwarding
+    // x-forwarded-host don't override the issuer.
     createVault("journal");
     const path = "/.well-known/oauth-authorization-server/vault/journal";
     const res = await route(
@@ -822,16 +835,17 @@ describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
     );
     expect(res.status).toBe(200);
     const body = (await res.json()) as { issuer: string; registration_endpoint: string };
-    expect(body.issuer).toBe("https://vault.example.com/vault/journal");
-    expect(body.registration_endpoint).toBe(
-      "https://vault.example.com/vault/journal/oauth/register",
-    );
+    expect(body.issuer).toBe(HUB_ORIGIN);
+    expect(body.registration_endpoint).toBe(`${HUB_ORIGIN}/oauth/register`);
   });
 
-  test("end-to-end: 401 → PRM (path-insertion) → AS (path-insertion) → DCR lands", async () => {
-    // Exact handshake Claude Code's MCP OAuth SDK performs. If any hop
-    // 404s, auth cascade-fails — this is the launch-blocker regression
-    // we're fixing.
+  test("end-to-end: 401 → PRM (path-insertion) → AS pointer is the hub", async () => {
+    // Exact handshake Claude Code's MCP OAuth SDK performs. After
+    // workstream E the chain stops at "AS = hub origin"; the live
+    // registration_endpoint lives on the hub (covered by hub's tests).
+    // Both the path-append PRM (named by the WWW-Authenticate challenge)
+    // and the path-insertion PRM (what strict clients probe) must
+    // return the same hub pointer.
     createVault("journal");
 
     // Step 1: unauth MCP → 401 + WWW-Authenticate with PRM pointer.
@@ -841,9 +855,7 @@ describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
     const challenge = mcpRes.headers.get("WWW-Authenticate")!;
     const prmUrl = challenge.match(/resource_metadata="([^"]+)"/)![1];
 
-    // The challenge still points at the path-append PRM (we emit one URL
-    // in the header). Strict clients ignore the hint and probe the
-    // path-insertion form regardless — that's the path we care about here.
+    // Step 2: path-insertion PRM also resolves and names the hub.
     const prmInsertPath = "/.well-known/oauth-protected-resource/vault/journal";
     const prmRes = await route(
       new Request(`http://localhost:1940${prmInsertPath}`),
@@ -851,41 +863,30 @@ describe("OAuth discovery (RFC 8414/9728 path-insertion form)", () => {
     );
     expect(prmRes.status).toBe(200);
     const prm = (await prmRes.json()) as { authorization_servers: string[] };
-    const asBase = prm.authorization_servers[0]; // http://localhost:1940/vault/journal
+    expect(prm.authorization_servers).toEqual([HUB_ORIGIN]);
 
-    // Step 2: fetch AS metadata via path-insertion. The issuer path is
-    // everything after the host — here, `/vault/journal`.
-    const asBasePath = new URL(asBase).pathname;
-    const asInsertPath = `/.well-known/oauth-authorization-server${asBasePath}`;
+    // Step 3: AS metadata via path-insertion on the vault path returns
+    // hub-rooted endpoints — strict clients that probe AS via the vault
+    // path (rather than following the PRM pointer) still land at the hub.
+    const asInsertPath = `/.well-known/oauth-authorization-server/vault/journal`;
     const asRes = await route(
       new Request(`http://localhost:1940${asInsertPath}`),
       asInsertPath,
     );
     expect(asRes.status).toBe(200);
-    const asMeta = (await asRes.json()) as { registration_endpoint: string };
-
-    // Step 3: registration_endpoint must be live.
-    const regPath = new URL(asMeta.registration_endpoint).pathname;
-    const regRes = await route(
-      new Request(`http://localhost:1940${regPath}`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          client_name: "Test",
-          redirect_uris: ["https://example.com/cb"],
-        }),
-      }),
-      regPath,
-    );
-    expect(regRes.status).toBe(201);
+    const asMeta = (await asRes.json()) as { issuer: string; registration_endpoint: string };
+    expect(asMeta.issuer).toBe(HUB_ORIGIN);
+    expect(asMeta.registration_endpoint).toBe(`${HUB_ORIGIN}/oauth/register`);
 
-    // Path-append PRM URL in the challenge header must still resolve —
-    // we haven't broken the back-compat path.
+    // Step 4: path-append PRM URL in the challenge header still resolves
+    // and agrees with the path-insertion answer.
     const prmAppendRes = await route(
       new Request(prmUrl),
       new URL(prmUrl).pathname,
     );
     expect(prmAppendRes.status).toBe(200);
+    const prmAppend = (await prmAppendRes.json()) as { authorization_servers: string[] };
+    expect(prmAppend.authorization_servers).toEqual([HUB_ORIGIN]);
   });
 });
 
@@ -911,7 +912,6 @@ describe("/.parachute/info + /.parachute/icon.svg", () => {
       tagline: string;
       version: string;
       iconUrl: string;
-      kind: string;
     };
     expect(body).toEqual({
       name: "parachute-vault",
@@ -919,8 +919,11 @@ describe("/.parachute/info + /.parachute/icon.svg", () => {
       tagline: expect.stringContaining("knowledge graph"),
       version: pkg.version,
       iconUrl: "/vault/journal/.parachute/icon.svg",
-      kind: "api",
     });
+    // `kind` retired from the info-endpoint response per hub#330 (companion
+    // to vault#359's module.json drop). Pin its absence so regressions are
+    // surfaced — the shape is a locked contract with the hub.
+    expect(body).not.toHaveProperty("kind");
   });
 
   test("info iconUrl is vault-scoped and points at a live icon handler", async () => {

package/src/routing.ts

@@ -15,8 +15,9 @@
  *   /vaults/list                       — public vault-name discovery (can be
  *                                        disabled globally via config)
  *   /vaults                            — authenticated vault metadata list
- *   /vault/<name>/.well-known/*        — per-vault OAuth discovery
- *   /vault/<name>/oauth/{register,authorize,token}
+ *   /vault/<name>/.well-known/oauth-*  — discovery forwarder; metadata names
+ *                                        the hub as the authorization server
+ *                                        (vault is resource-server only)
  *   /vault/<name>/mcp[/*]              — MCP endpoint (Bearer auth)
  *   /vault/<name>/view/<idOrPath>      — auth-aware HTML view
  *   /vault/<name>/public/<noteId>      — legacy alias → /view redirect
@@ -26,6 +27,13 @@
  * There is deliberately no compat for the old `/api/*`, `/mcp`, `/oauth/*`,
  * `/view/*`, or `/vaults/<name>/*` prefixes. Clients must re-authenticate
  * after the upgrade and point at the new URLs.
+ *
+ * **No standalone OAuth issuer.** vault does not mint OAuth tokens or
+ * render a consent UI. Hub is the issuer; vault validates hub-signed
+ * JWTs (see `auth.ts` + `hub-jwt.ts`). The discovery endpoints above are
+ * forwarders that point clients at the hub. The standalone surface that
+ * lived in `src/oauth.ts` was retired in vault#366 (workstream E of the
+ * UX audit, 2026-05-25).
  */
 
 import pkg from "../package.json" with { type: "json" };
@@ -60,15 +68,10 @@ import { handleTokens } from "./tokens-routes.ts";
 import {
   handleProtectedResource,
   handleAuthorizationServer,
-  handleRegister,
-  handleAuthorizeGet,
-  handleAuthorizePost,
-  handleToken,
   getBaseUrl,
-} from "./oauth.ts";
+} from "./oauth-discovery.ts";
 import { handleConfigSchema, handleConfig } from "./module-config.ts";
 import { buildAuthStatus } from "./auth-status.ts";
-import { getAuthorizeRateLimiter } from "./owner-auth.ts";
 import { handleMirrorGet, handleMirrorPut } from "./mirror-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 
@@ -132,11 +135,11 @@ function handleParachuteInfo(vaultName: string): Response {
     tagline: "Agent-native knowledge graph — notes, tags, links, attachments over REST + MCP",
     version: pkg.version,
     iconUrl: `/vault/${vaultName}/.parachute/icon.svg`,
-    // Hub renders `kind: "api"` cards as an expandable detail panel (MCP URL,
-    // OAuth link, version) rather than navigating to the API's root. Vault
-    // has no browser UI, so navigating to it shows raw JSON — not useful.
-    kind: "api",
   };
+  // `kind` was previously emitted here (and matched module.json) to let the
+  // hub branch its card rendering on api vs ui. Retired per hub#330 — the hub
+  // now infers presentation from the response shape itself. Companion to
+  // vault#359 (manifest drop); closes part of hub#340.
   return Response.json(body, {
     headers: { "Access-Control-Allow-Origin": "*" },
   });
@@ -167,7 +170,6 @@ function handleParachuteIcon(): Response {
 export async function route(
   req: Request,
   path: string,
-  clientIp?: string,
 ): Promise<Response> {
   // ---------------------------------------------------------------------
   // OAuth discovery — RFC 8414 §3.1 / RFC 9728 §3 path-insertion form.
@@ -325,41 +327,25 @@ export async function route(
     });
   }
 
-  // OAuth flow endpoints (no auth — these ARE the auth).
+  // The legacy `/oauth/{register,authorize,token}` flow on vault was retired
+  // when the standalone OAuth issuer was removed (vault#366, workstream E of
+  // the UX audit). Hub is the issuer now; vault is resource-server only. A
+  // request landing here is from a client that hasn't been re-pointed at the
+  // hub yet — surface a clear 410 Gone with a discovery pointer so the client
+  // (or its operator) knows where the authorization server moved.
   if (subpath === "/oauth/register" || subpath === "/oauth/authorize" || subpath === "/oauth/token") {
-    const store = getVaultStore(vaultName);
-    if (subpath === "/oauth/register") return handleRegister(req, store.db);
-    if (subpath === "/oauth/authorize") {
-      const gc = readGlobalConfig();
-      const ownerPasswordHash = gc.owner_password_hash ?? null;
-      const totpSecret = gc.totp_secret ?? null;
-      const totpEnrolled = typeof totpSecret === "string" && totpSecret.length > 0;
-      if (req.method === "GET") {
-        return handleAuthorizeGet(
-          req,
-          store.db,
-          vaultConfig.name,
-          ownerPasswordHash,
-          totpEnrolled,
-        );
-      }
-      if (req.method === "POST") {
-        return handleAuthorizePost(req, store.db, {
-          vaultName: vaultConfig.name,
-          clientIp,
-          ownerPasswordHash,
-          totpSecret,
-          // Per-vault rate-limit instance — prevents brute-force traffic on
-          // one vault's consent flow from locking out IPs trying to authorize
-          // against an unrelated vault (#93).
-          rateLimiter: getAuthorizeRateLimiter(vaultConfig.name),
-        });
-      }
-      return Response.json({ error: "method_not_allowed" }, { status: 405 });
-    }
-    // handleToken pins the OAuth code to the issuing vault (prevents
-    // cross-vault code replay) and echoes `vault: <name>` in the response.
-    if (subpath === "/oauth/token") return handleToken(req, store.db, vaultName);
+    const base = getBaseUrl(req);
+    return Response.json(
+      {
+        error: "oauth_endpoint_removed",
+        error_description:
+          "Vault no longer hosts an OAuth issuer. The hub is the authorization server. " +
+          "Discover its endpoints via the protected-resource metadata.",
+        protected_resource_metadata:
+          `${base}/vault/${vaultName}/.well-known/oauth-protected-resource`,
+      },
+      { status: 410 },
+    );
   }
 
   // Parachute service-info + icon (no auth, CORS *). The CLI hub page at

package/src/scribe-discovery.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Tests for vault's scribe service-discovery (vault#353).
+ *
+ * Single decision site for "where does scribe live": env override, then
+ * `~/.parachute/services.json`. The cache layer is exercised separately
+ * so the resolution rule stays unit-testable without filesystem state.
+ */
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import { resolveScribeUrl, clearScribeUrlCache } from "./scribe-discovery.ts";
+
+function mkManifest(services: Array<{ name: string; port: number; origin?: string }>): typeof import("./services-manifest.ts").readManifest {
+  return () => ({
+    services: services.map((s) => ({
+      name: s.name,
+      port: s.port,
+      paths: [`/${s.name}`],
+      health: "/health",
+      version: "0.0.0-test",
+      ...(s.origin ? { origin: s.origin } : {}),
+    })) as any,
+  });
+}
+
+beforeEach(() => {
+  clearScribeUrlCache();
+});
+
+describe("resolveScribeUrl", () => {
+  test("returns SCRIBE_URL env var (overrides services.json)", () => {
+    const env = { SCRIBE_URL: "http://example.test:9999" } as NodeJS.ProcessEnv;
+    const manifest = mkManifest([{ name: "parachute-scribe", port: 1943 }]);
+    expect(resolveScribeUrl(env, manifest)).toBe("http://example.test:9999");
+  });
+
+  test("strips trailing slash from SCRIBE_URL env var", () => {
+    const env = { SCRIBE_URL: "http://example.test:9999/" } as NodeJS.ProcessEnv;
+    const manifest = mkManifest([]);
+    expect(resolveScribeUrl(env, manifest)).toBe("http://example.test:9999");
+  });
+
+  test("falls back to services.json parachute-scribe entry", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    const manifest = mkManifest([{ name: "parachute-scribe", port: 1943 }]);
+    expect(resolveScribeUrl(env, manifest)).toBe("http://127.0.0.1:1943");
+  });
+
+  test("honors explicit `origin` on the service entry (v0.7 shape)", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    const manifest = mkManifest([
+      { name: "parachute-scribe", port: 1943, origin: "https://scribe.cloud.example.com" },
+    ]);
+    expect(resolveScribeUrl(env, manifest)).toBe("https://scribe.cloud.example.com");
+  });
+
+  test("returns undefined when no env override AND no scribe entry", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    const manifest = mkManifest([{ name: "parachute-vault", port: 1940 }]);
+    expect(resolveScribeUrl(env, manifest)).toBeUndefined();
+  });
+
+  test("returns undefined when manifest read throws", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    const calls: unknown[][] = [];
+    const logger = { warn: (...args: unknown[]) => calls.push(args) };
+    const manifest = (() => { throw new Error("boom"); }) as unknown as Parameters<typeof resolveScribeUrl>[1];
+    expect(resolveScribeUrl(env, manifest, logger)).toBeUndefined();
+    expect(calls.length).toBe(1);
+  });
+
+  test("trims whitespace-only SCRIBE_URL as unset", () => {
+    const env = { SCRIBE_URL: "   " } as NodeJS.ProcessEnv;
+    const manifest = mkManifest([{ name: "parachute-scribe", port: 1943 }]);
+    // Whitespace-only env falls through to services.json.
+    expect(resolveScribeUrl(env, manifest)).toBe("http://127.0.0.1:1943");
+  });
+});

package/src/scribe-discovery.ts

@@ -0,0 +1,91 @@
+/**
+ * Service discovery for the scribe transcription module.
+ *
+ * Per the 2026-05-21 vault↔scribe design (Part 2, design question 2), vault
+ * locates scribe via `~/.parachute/services.json` — the canonical hub-
+ * maintained registry. This module is the single read site so the
+ * resolution rule lives in one place.
+ *
+ * Resolution order (first hit wins):
+ *
+ *   1. `SCRIBE_URL` env var (operator override; useful for tests, Docker
+ *      compose, and any deploy where scribe runs at a non-loopback host).
+ *   2. Entry `name === "parachute-scribe"` in `~/.parachute/services.json`
+ *      → construct `http://127.0.0.1:<port>`.
+ *   3. `undefined` (auto-transcribe stays a no-op).
+ *
+ * The bearer token resolution stays in `./scribe-env.ts:resolveScribeAuthToken`.
+ * Service discovery is just about WHERE scribe lives; AUTH is a separate
+ * concern with its own env-var precedence (SCRIBE_AUTH_TOKEN over the legacy
+ * SCRIBE_TOKEN). When the v0.7 hub-issued-JWT path lands, the bearer source
+ * changes but the URL source stays the same — one file, one concern.
+ *
+ * v0.6 deploy is single-container (hub-as-supervisor) so loopback is fine.
+ * v0.7 cloud-multi-container will grow an `origin` field on the services.json
+ * entry; this resolver will honor it without API changes — `port` becomes
+ * a fallback when `origin` isn't set, no breaking change for v0.6 callers.
+ */
+
+import { readManifest, ServicesManifestError } from "./services-manifest.ts";
+
+/**
+ * Resolve the scribe base URL (no trailing slash) by consulting the env-var
+ * override first, then services.json. Returns `undefined` when scribe isn't
+ * configured — callers MUST treat that as "auto-transcribe disabled."
+ *
+ * The `env` + `readManifestImpl` parameters are injection seams for tests;
+ * production callers omit them and pick up `process.env` + the real
+ * `~/.parachute/services.json`.
+ */
+export function resolveScribeUrl(
+  env: NodeJS.ProcessEnv = process.env,
+  readManifestImpl: typeof readManifest = readManifest,
+  logger: { warn?: (...args: unknown[]) => void } = console,
+): string | undefined {
+  const override = env.SCRIBE_URL?.trim();
+  if (override) return override.replace(/\/$/, "");
+
+  let manifest;
+  try {
+    manifest = readManifestImpl();
+  } catch (err) {
+    if (err instanceof ServicesManifestError) {
+      logger.warn?.(`[scribe-discovery] services.json unreadable: ${err.message}`);
+    } else {
+      logger.warn?.(`[scribe-discovery] services.json read failed: ${err}`);
+    }
+    return undefined;
+  }
+  const entry = manifest.services.find((s) => s.name === "parachute-scribe");
+  if (!entry) return undefined;
+  // v0.6 loopback shape; v0.7 will add an explicit `origin` field on the
+  // service entry which wins over loopback when present.
+  const origin = (entry as { origin?: string }).origin;
+  if (typeof origin === "string" && origin.trim()) {
+    return origin.trim().replace(/\/$/, "");
+  }
+  return `http://127.0.0.1:${entry.port}`;
+}
+
+/**
+ * Process-lifetime cache. Computed at first call (typically during server
+ * boot), reused for every subsequent transcription request. Operators who
+ * change the scribe URL via `services.json` (re-install of scribe with a
+ * different port) need to restart vault; we deliberately don't watch the
+ * file because the v0.6 deploy model has a single restart-on-change story.
+ *
+ * Tests should pass an explicit `env` + `readManifestImpl` to `resolveScribeUrl`
+ * directly to bypass the cache.
+ */
+let cachedScribeUrl: string | undefined | null = null;
+
+export function getCachedScribeUrl(): string | undefined {
+  if (cachedScribeUrl === null) {
+    cachedScribeUrl = resolveScribeUrl();
+  }
+  return cachedScribeUrl;
+}
+
+export function clearScribeUrlCache(): void {
+  cachedScribeUrl = null;
+}