@openparachute/vault 0.2.4 → 0.3.0

package/src/routing.ts

@@ -1,38 +1,50 @@
 /**
  * HTTP request router for the multi-vault server.
  *
- * Extracted from server.ts so routes are unit-testable without spinning up
- * Bun.serve(). server.ts imports this and wires it into the listener.
+ * All per-vault resources live under `/vault/<name>/...`. There is no
+ * unscoped fallback — a request must name the vault it targets. A fresh
+ * install creates a vault named `default`, so `/vault/default/...` is the
+ * baseline URL for single-vault deployments.
  *
- * Path dispatch order (skim):
- *   - /.well-known/oauth-*           — public OAuth discovery
- *   - /oauth/*                       — unscoped OAuth (targets default vault)
- *   - /health                        — lightweight ping
- *   - /mcp, /mcp/*                   — unified MCP (global auth)
- *   - /view/:id                      — default-vault HTML view
- *   - /public/:id                    — backward-compat redirect → /view
- *   - /vaults/list                   — PUBLIC vault names (no auth, no metadata)
- *   - /vaults                        — authenticated vault metadata listing
- *   - /api/*                         — default-vault REST API
- *   - /vaults/:name/*                — vault-scoped: view, oauth, mcp, api
+ * Dispatch shape:
+ *
+ *   /.well-known/parachute.json        — NOT served here (CLI owns it at
+ *                                        origin root; vault never handles it)
+ *   /health                            — liveness ping, vault names leaked
+ *                                        only to authenticated callers
+ *   /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>/mcp[/*]              — MCP endpoint (Bearer auth)
+ *   /vault/<name>/view/<idOrPath>      — auth-aware HTML view
+ *   /vault/<name>/public/<noteId>      — legacy alias → /view redirect
+ *   /vault/<name>                      — vault metadata + stats (auth)
+ *   /vault/<name>/api/...              — REST surface (auth)
+ *
+ * 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.
  */
 
+import pkg from "../package.json" with { type: "json" };
 import type { VaultConfig } from "./config.ts";
 import {
   readVaultConfig,
   readGlobalConfig,
   writeVaultConfig,
   listVaults,
-  resolveDefaultVault,
 } from "./config.ts";
 import {
   authenticateVaultRequest,
   authenticateGlobalRequest,
-  isMethodAllowed,
   extractApiKey,
+  requireScope,
 } from "./auth.ts";
+import { SCOPE_ADMIN, scopeForMethod } from "./scopes.ts";
 import { getVaultStore } from "./vault-store.ts";
-import { handleUnifiedMcp, handleScopedMcp } from "./mcp-http.ts";
+import { handleScopedMcp } from "./mcp-http.ts";
 import {
   handleNotes,
   handleTags,
@@ -51,28 +63,19 @@ import {
   handleToken,
   getBaseUrl,
 } from "./oauth.ts";
+import { handleConfigSchema, handleConfig } from "./module-config.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.
+ * to discover which authorization server to use; the `WWW-Authenticate`
+ * header names the metadata document for the exact endpoint they hit.
  */
-function mcpWwwAuthenticate(req: Request, vaultName?: string): string {
+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"`;
+  return `Bearer resource_metadata="${base}/vault/${vaultName}/.well-known/oauth-protected-resource"`;
 }
 
 /**
@@ -83,7 +86,7 @@ function mcpWwwAuthenticate(req: Request, vaultName?: string): string {
 async function withMcpChallenge(
   res: Response,
   req: Request,
-  vaultName?: string,
+  vaultName: string,
 ): Promise<Response> {
   if (res.status !== 401) return res;
   const body = await res.text();
@@ -103,46 +106,96 @@ function isViewAuthenticated(
   vaultDb?: import("bun:sqlite").Database,
 ): boolean {
   if (!vaultConfig) return false;
-  // extractApiKey now checks headers AND ?key= query param
   const key = extractApiKey(req);
   if (!key) return false;
   const auth = authenticateVaultRequest(req, vaultConfig, vaultDb);
   return !("error" in auth);
 }
 
+/**
+ * Public service-info card for the CLI hub page. The CLI fetches this from
+ * every service registered in `~/.parachute/well-known/parachute.json` and
+ * renders each as a tile — services own their display story, CLI is a dumb
+ * aggregator. No auth, no PII, CORS `*` so the hub can call us cross-origin.
+ */
+function handleParachuteInfo(vaultName: string): Response {
+  const body = {
+    name: "parachute-vault",
+    displayName: "Vault",
+    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",
+  };
+  return Response.json(body, {
+    headers: { "Access-Control-Allow-Origin": "*" },
+  });
+}
+
+/**
+ * Placeholder monogram icon for the hub tile. Kept inline so the endpoint
+ * has zero filesystem dependency — the CLI can render a card even on a
+ * pristine install where no assets have been written out yet.
+ */
+const PARACHUTE_ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><circle cx="32" cy="32" r="30" fill="#879B7E"/><text x="32" y="43" text-anchor="middle" font-family="system-ui,sans-serif" font-size="32" font-weight="600" fill="#FAFAF7">V</text></svg>`;
+
+function handleParachuteIcon(): Response {
+  return new Response(PARACHUTE_ICON_SVG, {
+    headers: {
+      "Content-Type": "image/svg+xml",
+      // Defense-in-depth: the payload is a static inline SVG with no
+      // script/foreignObject, but older Edge/IE have been known to sniff
+      // image/svg+xml as HTML under certain conditions. nosniff pins the
+      // declared type and takes the sniff path off the table entirely.
+      "X-Content-Type-Options": "nosniff",
+      "Access-Control-Allow-Origin": "*",
+      "Cache-Control": "public, max-age=3600",
+    },
+  });
+}
+
 export async function route(
   req: Request,
   path: string,
   clientIp?: string,
 ): Promise<Response> {
-  // OAuth discovery endpoints (no auth required).
+  // ---------------------------------------------------------------------
+  // OAuth discovery — RFC 8414 §3.1 / RFC 9728 §3 path-insertion form.
   //
-  // RFC 8414 §3.1 and RFC 9728 §3 specify the discovery URL shape when an
-  // authorization server (or protected resource) has a path component `/p`:
+  // For a resource at `/vault/<name>/mcp`, the spec-mandated metadata URLs
+  // are
   //
-  //   Path-insertion (spec-mandated):
-  //     <host>/.well-known/<metadata-type>/p
-  //   Path-append (widespread in the wild, shipped in PR #111):
-  //     <host>/p/.well-known/<metadata-type>
+  //   /.well-known/oauth-authorization-server/vault/<name>[/mcp]
+  //   /.well-known/oauth-protected-resource/vault/<name>[/mcp]
   //
-  // Strict clients — including Claude Code's MCP OAuth SDK — probe only the
-  // path-insertion form. Lax clients try path-append. We serve both so any
-  // conformant probe hits a live endpoint. Unscoped root forms
-  // (`/.well-known/oauth-*`) are the third accepted shape, and the
-  // path-append branch for scoped discovery lives further down alongside the
-  // other `/vaults/{name}/*` routing.
+  // (path-insertion — `.well-known` goes ABOVE the issuer path), not the
+  // path-append shape `/vault/<name>/.well-known/<type>` served further
+  // down. Strict clients — Claude Code's MCP SDK, and any RFC 8414-
+  // conformant MCP client — only probe the path-insertion form; without
+  // these routes they 404 on discovery and can't authenticate.
+  //
+  // Both shapes return byte-identical JSON via the shared handlers. The
+  // path-append branch lives inside the per-vault block alongside the
+  // rest of `/vault/<name>/*` routing. PR #124 originally shipped this
+  // for the `/vaults/<name>/` URL shape; PR #138 migrated URLs to
+  // `/vault/<name>/` and dropped the insertion routes — this restores
+  // them for the new URL shape.
+  // ---------------------------------------------------------------------
   const protectedResourceInsert = path.match(
-    /^\/\.well-known\/oauth-protected-resource\/vaults\/([^/]+)(?:\/mcp)?$/,
+    /^\/\.well-known\/oauth-protected-resource\/vault\/([^/]+)(?:\/mcp)?$/,
   );
   if (protectedResourceInsert) {
     const vaultName = protectedResourceInsert[1];
     if (!readVaultConfig(vaultName)) {
       return Response.json({ error: "Vault not found", vault: vaultName }, { status: 404 });
     }
-    return handleProtectedResource(req, `/vaults/${vaultName}/mcp`, `/vaults/${vaultName}`);
+    return handleProtectedResource(req, vaultName);
   }
   const authServerInsert = path.match(
-    /^\/\.well-known\/oauth-authorization-server\/vaults\/([^/]+)(?:\/mcp)?$/,
+    /^\/\.well-known\/oauth-authorization-server\/vault\/([^/]+)(?:\/mcp)?$/,
   );
   if (authServerInsert) {
     const vaultName = authServerInsert[1];
@@ -152,54 +205,10 @@ export async function route(
     return handleAuthorizationServer(req, vaultName);
   }
 
-  if (path === "/.well-known/oauth-protected-resource") {
-    return handleProtectedResource(req);
-  }
-  if (path === "/.well-known/oauth-authorization-server") {
-    return handleAuthorizationServer(req);
-  }
-
-  // OAuth flow endpoints (no auth — these ARE the auth)
-  if (path === "/oauth/register" || path === "/oauth/authorize" || path === "/oauth/token") {
-    const defaultVault = resolveDefaultVault();
-    const vaultConfig = defaultVault ? readVaultConfig(defaultVault) : null;
-    if (!defaultVault || !vaultConfig) {
-      return Response.json(
-        { error: "server_error", error_description: "Default vault not configured" },
-        { status: 500 },
-      );
-    }
-    const store = getVaultStore(defaultVault);
+  // ---------------------------------------------------------------------
+  // Cross-vault / origin-root endpoints
+  // ---------------------------------------------------------------------
 
-    if (path === "/oauth/register") {
-      return handleRegister(req, store.db);
-    }
-    if (path === "/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,
-        });
-      }
-      return Response.json({ error: "method_not_allowed" }, { status: 405 });
-    }
-    if (path === "/oauth/token") {
-      // PR #111: handleToken echoes the vault name back to the client so it
-      // knows which vault it just connected to.
-      return handleToken(req, store.db, defaultVault);
-    }
-  }
-
-  // Health check — vault names only for authenticated requests
   if (path === "/health") {
     const auth = authenticateGlobalRequest(req);
     if ("error" in auth) {
@@ -208,45 +217,10 @@ export async function route(
     return Response.json({ status: "ok", vaults: listVaults() });
   }
 
-  // Unified MCP (all vaults, global auth)
-  if (path === "/mcp" || path.startsWith("/mcp/")) {
-    const auth = authenticateGlobalRequest(req);
-    if ("error" in auth) return withMcpChallenge(auth.error, req);
-    return handleUnifiedMcp(req, auth);
-  }
-
-  // View endpoint — serves notes as HTML (auth-aware, supports ID or path)
-  const viewMatch = path.match(/^\/view\/(.+)$/);
-  if (viewMatch && req.method === "GET") {
-    const defaultVault = resolveDefaultVault();
-    const vaultConfig = defaultVault ? readVaultConfig(defaultVault) : null;
-    if (!defaultVault || !vaultConfig) {
-      return Response.json({ error: "Default vault not found" }, { status: 404 });
-    }
-    const store = getVaultStore(defaultVault);
-    const authenticated = isViewAuthenticated(req, vaultConfig, store.db);
-    return handleViewNote(store, decodeURIComponent(viewMatch[1]), {
-      authenticated,
-      publishedTag: vaultConfig.published_tag,
-    });
-  }
-
-  // Backward compat: /public/:noteId → /view/:noteId (preserving query params)
-  const publicMatch = path.match(/^\/public\/([^/]+)$/);
-  if (publicMatch && req.method === "GET") {
-    const dest = new URL(`/view/${publicMatch[1]}`, req.url);
-    dest.search = new URL(req.url).search;
-    return Response.redirect(dest.toString(), 301);
-  }
-
-  // Public vault names — no auth, no metadata. Lets unauthenticated clients
-  // (e.g. the Daily vault-picker dropdown before OAuth) know which vault to
-  // target. Only vault names are exposed; descriptions, counts, timestamps,
-  // and API keys are never returned from this endpoint.
-  //
-  // Operators who want to hide vault existence from anonymous callers can set
-  // `discovery: disabled` in ~/.parachute/config.yaml — the endpoint then
-  // returns 404 as if it didn't exist.
+  // Public vault-name discovery. Lets unauthenticated clients (e.g. the
+  // Daily vault-picker dropdown before OAuth) know which vault to target.
+  // Operators who want to hide vault existence can set `discovery: disabled`
+  // in ~/.parachute/vault/config.yaml — the endpoint then returns 404.
   if (path === "/vaults/list" && req.method === "GET") {
     const globalConfig = readGlobalConfig();
     if (globalConfig.discovery === "disabled") {
@@ -255,7 +229,7 @@ export async function route(
     return Response.json({ vaults: listVaults() });
   }
 
-  // List vaults — requires auth
+  // Authenticated vault metadata list.
   if (path === "/vaults" && req.method === "GET") {
     const auth = authenticateGlobalRequest(req);
     if ("error" in auth) return auth.error;
@@ -271,39 +245,11 @@ export async function route(
     return Response.json({ vaults });
   }
 
-  // Backward-compatible: /api/* routes to default vault
-  if (path.startsWith("/api/")) {
-    const defaultVault = resolveDefaultVault();
-    const vaultConfig = defaultVault ? readVaultConfig(defaultVault) : null;
-    if (!defaultVault || !vaultConfig) {
-      return Response.json({ error: "Default vault not found" }, { status: 404 });
-    }
-    const store = getVaultStore(defaultVault);
-    const auth = authenticateVaultRequest(req, vaultConfig, store.db);
-    if ("error" in auth) return auth.error;
-    if (!isMethodAllowed(req.method, auth.permission)) {
-      return Response.json(
-        { error: "Forbidden", message: "Insufficient permissions" },
-        { status: 403 },
-      );
-    }
-    const apiPath = path.slice(4); // strip "/api"
-    if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6));
-    if (apiPath.startsWith("/tags")) return handleTags(req, store, apiPath.slice(5));
-    if (apiPath === "/find-path") return handleFindPath(req, store);
-    if (apiPath === "/vault") {
-      return handleVault(req, store, vaultConfig, (desc) => {
-        vaultConfig.description = desc;
-        writeVaultConfig(vaultConfig);
-      });
-    }
-    if (apiPath === "/unresolved-wikilinks") return handleUnresolvedWikilinks(req, store);
-    if (apiPath.startsWith("/storage")) return handleStorage(req, apiPath.slice(8), defaultVault);
-    if (apiPath === "/health") return Response.json({ status: "ok", vault: defaultVault });
-  }
+  // ---------------------------------------------------------------------
+  // Per-vault routing: /vault/<name>/...
+  // ---------------------------------------------------------------------
 
-  // Vault-scoped routes: /vaults/{name}/...
-  const vaultMatch = path.match(/^\/vaults\/([^/]+)(\/.*)?$/);
+  const vaultMatch = path.match(/^\/vault\/([^/]+)(\/.*)?$/);
   if (!vaultMatch) {
     return Response.json({ error: "Not found" }, { status: 404 });
   }
@@ -316,15 +262,18 @@ export async function route(
     return Response.json({ error: "Vault not found", vault: vaultName }, { status: 404 });
   }
 
-  // Backward compat: /vaults/{name}/public/:noteId → /view/:noteId
+  // Legacy-style /public/:noteId → /view/:noteId redirect (kept as a
+  // convenience for published-note URLs that predate the /view/ path).
   const vaultPublicMatch = subpath.match(/^\/public\/([^/]+)$/);
   if (vaultPublicMatch && req.method === "GET") {
-    const dest = new URL(`/vaults/${vaultName}/view/${vaultPublicMatch[1]}`, req.url);
+    const dest = new URL(`/vault/${vaultName}/view/${vaultPublicMatch[1]}`, req.url);
     dest.search = new URL(req.url).search;
     return Response.redirect(dest.toString(), 301);
   }
 
-  // View endpoint — serves notes as HTML (auth-aware, vault-scoped, supports ID or path)
+  // View endpoint — auth-aware HTML renderer. Unauthenticated requests
+  // still serve public notes; a valid API key via header or ?key= query
+  // parameter unlocks private notes.
   const vaultViewMatch = subpath.match(/^\/view\/(.+)$/);
   if (vaultViewMatch && req.method === "GET") {
     const store = getVaultStore(vaultName);
@@ -335,7 +284,7 @@ export async function route(
     });
   }
 
-  // Vault-scoped OAuth endpoints (no auth — these ARE the auth)
+  // OAuth flow endpoints (no auth — these ARE the auth).
   if (subpath === "/oauth/register" || subpath === "/oauth/authorize" || subpath === "/oauth/token") {
     const store = getVaultStore(vaultName);
     if (subpath === "/oauth/register") return handleRegister(req, store.db);
@@ -363,33 +312,78 @@ export async function route(
       }
       return Response.json({ error: "method_not_allowed" }, { status: 405 });
     }
-    // PR #111: handleToken now requires the vault name so it can (a) pin the
-    // OAuth code to the issuing vault (prevents cross-vault code replay) and
-    // (b) echo `vault: <name>` back to the client in the token response.
+    // 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);
   }
 
-  // Vault-scoped discovery endpoints. PR #111: the protected-resource
-  // advertises a vault-scoped authorization server (`${base}/vaults/${name}`),
-  // and the vault-scoped authorization-server metadata returns endpoints
-  // scoped to `/vaults/${name}/oauth/*` so tokens mint against this vault's
-  // DB. Keeps the RFC 9728 → RFC 8414 chain coherent end-to-end.
+  // Parachute service-info + icon (no auth, CORS *). The CLI hub page at
+  // the ecosystem root reads `~/.parachute/well-known/parachute.json`,
+  // fans out to each service's `/.parachute/info`, and renders a card per
+  // response. Keeping display copy here means the hub never needs a vault
+  // release to pick up wording changes.
+  if (subpath === "/.parachute/info" || subpath === "/.parachute/icon.svg") {
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return subpath === "/.parachute/info"
+      ? handleParachuteInfo(vaultName)
+      : handleParachuteIcon();
+  }
+
+  // Module configuration endpoints (Phase 2 of the module architecture).
+  // Schema is always public — hub reads it to render the config form, no
+  // secrets involved. Current values require `vault:admin` as of Phase 3.
+  if (subpath === "/.parachute/config/schema") {
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return handleConfigSchema();
+  }
+  if (subpath === "/.parachute/config") {
+    if (req.method !== "GET") {
+      // PUT lands in a future phase — return 405 so clients that already speak
+      // the full contract discover the gap rather than silently succeeding.
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    // Admin-gated: the current config includes things that aren't user data
+    // (worker intervals, TTLs, retention policy) but are still configuration
+    // an attacker could use to map the deployment. `vault:admin` keeps the
+    // hub's loopback workflow intact while locking out read-only tokens.
+    const configAuth = authenticateVaultRequest(req, vaultConfig, getVaultStore(vaultName).db);
+    if ("error" in configAuth) return configAuth.error;
+    if (!requireScope(configAuth, SCOPE_ADMIN)) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope.`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: configAuth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const globalConfig = readGlobalConfig();
+    return handleConfig(vaultConfig, globalConfig);
+  }
+
+  // OAuth discovery (no auth). The protected-resource metadata advertises
+  // this vault's MCP endpoint and names the vault's authorization server;
+  // the authorization-server metadata returns endpoints scoped to
+  // `/vault/<name>/oauth/*`. Together they keep RFC 9728 → RFC 8414
+  // discovery coherent for a single vault.
   if (subpath === "/.well-known/oauth-protected-resource") {
-    return handleProtectedResource(
-      req,
-      `/vaults/${vaultName}/mcp`,
-      `/vaults/${vaultName}`,
-    );
+    return handleProtectedResource(req, vaultName);
   }
   if (subpath === "/.well-known/oauth-authorization-server") {
     return handleAuthorizationServer(req, vaultName);
   }
 
-  // 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.
+  // ---------------------------------------------------------------------
+  // Authenticated surface
+  // ---------------------------------------------------------------------
+
   const store = getVaultStore(vaultName);
   const auth = authenticateVaultRequest(req, vaultConfig, store.db);
   const isScopedMcp = subpath === "/mcp" || subpath.startsWith("/mcp/");
@@ -397,12 +391,12 @@ export async function route(
     return isScopedMcp ? withMcpChallenge(auth.error, req, vaultName) : auth.error;
   }
 
-  // Per-vault scoped MCP
+  // MCP (per-vault, single-vault session).
   if (isScopedMcp) {
     return handleScopedMcp(req, vaultName, auth);
   }
 
-  // Bare /vaults/{name} — single-vault root. Returns name, description,
+  // Bare `/vault/<name>` — single-vault root. Returns name, description,
   // createdAt, and stats. One round trip for a viz landing page.
   if (subpath === "" || subpath === "/") {
     if (req.method !== "GET") {
@@ -417,27 +411,35 @@ export async function route(
     });
   }
 
-  // REST API — enforce permission level
-  if (!isMethodAllowed(req.method, auth.permission)) {
-    return Response.json(
-      { error: "Forbidden", message: "Insufficient permissions" },
-      { status: 403 },
-    );
-  }
-
   const apiMatch = subpath.match(/^\/api(\/.*)?$/);
   if (!apiMatch) {
     return Response.json({ error: "Not found" }, { status: 404 });
   }
 
+  // REST API — scope gate. GET/HEAD/OPTIONS → vault:read,
+  // POST/PATCH/PUT/DELETE → vault:write. Inheritance (admin ⊇ write ⊇ read)
+  // is handled inside `requireScope`.
+  const requiredApiScope = scopeForMethod(req.method);
+  if (!requireScope(auth, requiredApiScope)) {
+    return Response.json(
+      {
+        error: "Forbidden",
+        error_type: "insufficient_scope",
+        message: `This endpoint requires the '${requiredApiScope}' scope.`,
+        required_scope: requiredApiScope,
+        granted_scopes: auth.scopes,
+      },
+      { status: 403 },
+    );
+  }
+
   const apiPath = apiMatch[1] ?? "";
 
-  if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6));
+  if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName);
   if (apiPath.startsWith("/tags")) return handleTags(req, store, apiPath.slice(5));
   if (apiPath === "/find-path") return handleFindPath(req, store);
   if (apiPath === "/vault") {
-    return handleVault(req, store, vaultConfig, (desc) => {
-      vaultConfig.description = desc;
+    return handleVault(req, store, vaultConfig, () => {
       writeVaultConfig(vaultConfig);
     });
   }