@openparachute/vault 0.3.1 → 0.4.0

package/src/routing.ts

@@ -40,20 +40,24 @@ import {
   authenticateVaultRequest,
   authenticateGlobalRequest,
   extractApiKey,
-  requireScope,
 } from "./auth.ts";
-import { SCOPE_ADMIN, scopeForMethod } from "./scopes.ts";
+import { hasScopeForVault, SCOPE_ADMIN, scopeForMethod, verbForMethod } from "./scopes.ts";
 import { getVaultStore } from "./vault-store.ts";
 import { handleScopedMcp } from "./mcp-http.ts";
+import { defaultAdminSpaDistDir, isAdminSpaPath, serveAdminSpa } from "./admin-spa.ts";
 import {
   handleNotes,
   handleTags,
+  handleNoteSchemas,
   handleFindPath,
   handleVault,
   handleUnresolvedWikilinks,
   handleStorage,
   handleViewNote,
+  type TagScopeCtx,
 } from "./routes.ts";
+import { expandTokenTagScope } from "./tag-scope.ts";
+import { handleTokens } from "./tokens-routes.ts";
 import {
   handleProtectedResource,
   handleAuthorizationServer,
@@ -64,6 +68,8 @@ import {
   getBaseUrl,
 } from "./oauth.ts";
 import { handleConfigSchema, handleConfig } from "./module-config.ts";
+import { buildAuthStatus } from "./auth-status.ts";
+import { getAuthorizeRateLimiter } from "./owner-auth.ts";
 
 /**
  * Decorate a 401 response from the MCP endpoint with the RFC 9728 challenge
@@ -100,15 +106,15 @@ async function withMcpChallenge(
  * Returns true if authenticated, false if not. Never rejects — unauthenticated
  * requests still get public notes.
  */
-function isViewAuthenticated(
+async function isViewAuthenticated(
   req: Request,
   vaultConfig: VaultConfig | null,
   vaultDb?: import("bun:sqlite").Database,
-): boolean {
+): Promise<boolean> {
   if (!vaultConfig) return false;
   const key = extractApiKey(req);
   if (!key) return false;
-  const auth = authenticateVaultRequest(req, vaultConfig, vaultDb);
+  const auth = await authenticateVaultRequest(req, vaultConfig, vaultDb);
   return !("error" in auth);
 }
 
@@ -188,7 +194,7 @@ export async function route(
     /^\/\.well-known\/oauth-protected-resource\/vault\/([^/]+)(?:\/mcp)?$/,
   );
   if (protectedResourceInsert) {
-    const vaultName = protectedResourceInsert[1];
+    const vaultName = protectedResourceInsert[1]!;
     if (!readVaultConfig(vaultName)) {
       return Response.json({ error: "Vault not found", vault: vaultName }, { status: 404 });
     }
@@ -198,7 +204,7 @@ export async function route(
     /^\/\.well-known\/oauth-authorization-server\/vault\/([^/]+)(?:\/mcp)?$/,
   );
   if (authServerInsert) {
-    const vaultName = authServerInsert[1];
+    const vaultName = authServerInsert[1]!;
     if (!readVaultConfig(vaultName)) {
       return Response.json({ error: "Vault not found", vault: vaultName }, { status: 404 });
     }
@@ -210,7 +216,7 @@ export async function route(
   // ---------------------------------------------------------------------
 
   if (path === "/health") {
-    const auth = authenticateGlobalRequest(req);
+    const auth = await authenticateGlobalRequest(req);
     if ("error" in auth) {
       return Response.json({ status: "ok" });
     }
@@ -229,9 +235,43 @@ export async function route(
     return Response.json({ vaults: listVaults() });
   }
 
+  // Public auth-state probe. Tells a first-contact client whether the
+  // server has any vaults yet, which bearer formats it accepts, and
+  // whether owner-password / TOTP / tokens are configured. Replaces
+  // hub's out-of-process filesystem snoop (parachute-hub#86 follow-up).
+  // No auth, GET-only, no token counts — `hasTokens` is a yes/no signal
+  // only, with `null` for "DB read failed."
+  //
+  // Gated on `discovery: disabled` like /vaults/list — both leak vault
+  // existence (the `vaults` array names them), so an operator who hides
+  // one wants both hidden (#191).
+  if (path === "/auth/status" && req.method === "GET") {
+    if (readGlobalConfig().discovery === "disabled") {
+      return Response.json({ error: "Not found" }, { status: 404 });
+    }
+    return Response.json(buildAuthStatus(), {
+      headers: { "Access-Control-Allow-Origin": "*" },
+    });
+  }
+
+  // Admin SPA — per-vault at `/vault/<name>/admin/*` (vault#252). Static-
+  // file serving only (index.html + Vite asset bundle); no auth at this
+  // seam since the bundle reveals nothing privileged. The SPA's data
+  // fetches land on existing per-vault routes that enforce
+  // `vault:<name>:read` / `:admin`. GET-only — POSTs to `.../admin/*` aren't
+  // a thing the SPA bundle exposes; rejecting them here keeps surprises
+  // out. Must fire BEFORE the per-vault dispatch below or the auth wall
+  // there would short-circuit the static-asset response.
+  if (isAdminSpaPath(path)) {
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
+    return serveAdminSpa(defaultAdminSpaDistDir(), path);
+  }
+
   // Authenticated vault metadata list.
   if (path === "/vaults" && req.method === "GET") {
-    const auth = authenticateGlobalRequest(req);
+    const auth = await authenticateGlobalRequest(req);
     if ("error" in auth) return auth.error;
     const names = listVaults();
     const vaults = names.map((name) => {
@@ -254,7 +294,7 @@ export async function route(
     return Response.json({ error: "Not found" }, { status: 404 });
   }
 
-  const vaultName = vaultMatch[1];
+  const vaultName = vaultMatch[1]!;
   const subpath = vaultMatch[2] ?? "";
 
   const vaultConfig = readVaultConfig(vaultName);
@@ -266,7 +306,7 @@ export async function route(
   // convenience for published-note URLs that predate the /view/ path).
   const vaultPublicMatch = subpath.match(/^\/public\/([^/]+)$/);
   if (vaultPublicMatch && req.method === "GET") {
-    const dest = new URL(`/vault/${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);
   }
@@ -277,8 +317,8 @@ export async function route(
   const vaultViewMatch = subpath.match(/^\/view\/(.+)$/);
   if (vaultViewMatch && req.method === "GET") {
     const store = getVaultStore(vaultName);
-    const authenticated = isViewAuthenticated(req, vaultConfig, store.db);
-    return handleViewNote(store, decodeURIComponent(vaultViewMatch[1]), {
+    const authenticated = await isViewAuthenticated(req, vaultConfig, store.db);
+    return handleViewNote(store, decodeURIComponent(vaultViewMatch[1]!), {
       authenticated,
       publishedTag: vaultConfig.published_tag,
     });
@@ -308,6 +348,10 @@ export async function route(
           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 });
@@ -350,14 +394,14 @@ export async function route(
     // (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);
+    const configAuth = await authenticateVaultRequest(req, vaultConfig, getVaultStore(vaultName).db);
     if ("error" in configAuth) return configAuth.error;
-    if (!requireScope(configAuth, SCOPE_ADMIN)) {
+    if (!hasScopeForVault(configAuth.scopes, vaultName, "admin")) {
       return Response.json(
         {
           error: "Forbidden",
           error_type: "insufficient_scope",
-          message: `This endpoint requires the '${SCOPE_ADMIN}' scope.`,
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
           required_scope: SCOPE_ADMIN,
           granted_scopes: configAuth.scopes,
         },
@@ -385,7 +429,7 @@ export async function route(
   // ---------------------------------------------------------------------
 
   const store = getVaultStore(vaultName);
-  const auth = authenticateVaultRequest(req, vaultConfig, store.db);
+  const auth = await authenticateVaultRequest(req, vaultConfig, store.db);
   const isScopedMcp = subpath === "/mcp" || subpath.startsWith("/mcp/");
   if ("error" in auth) {
     return isScopedMcp ? withMcpChallenge(auth.error, req, vaultName) : auth.error;
@@ -411,6 +455,31 @@ export async function route(
     });
   }
 
+  // /tokens — admin-gated REST surface for minting/listing/revoking pvt_*
+  // tokens. Admin gate applies to every method (POST/GET/DELETE) since both
+  // the plaintext mint and the metadata listing are sensitive — knowing
+  // labels and scopes of issued tokens leaks the deployment's auth shape.
+  // The handler's POST path applies a strict subset check on requested
+  // scopes via `validateMintedScopes` (defense-in-depth: cross-vault and
+  // privilege-escalation rejections survive even if this gate is later
+  // relaxed).
+  const tokensMatch = subpath.match(/^\/tokens(\/.*)?$/);
+  if (tokensMatch) {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    return handleTokens(req, store, vaultName, auth.scopes, auth.scoped_tags, tokensMatch[1] ?? "");
+  }
+
   const apiMatch = subpath.match(/^\/api(\/.*)?$/);
   if (!apiMatch) {
     return Response.json({ error: "Not found" }, { status: 404 });
@@ -418,14 +487,17 @@ export async function route(
 
   // 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)) {
+  // and the broad-vs-narrowed shape (`vault:<verb>` from pvt_*, or
+  // `vault:<vaultName>:<verb>` from hub JWTs) are handled by
+  // `hasScopeForVault`.
+  const requiredVerb = verbForMethod(req.method);
+  if (!hasScopeForVault(auth.scopes, vaultName, requiredVerb)) {
+    const requiredApiScope = scopeForMethod(req.method);
     return Response.json(
       {
         error: "Forbidden",
         error_type: "insufficient_scope",
-        message: `This endpoint requires the '${requiredApiScope}' scope.`,
+        message: `This endpoint requires the '${requiredApiScope}' scope (or '${requiredApiScope.replace("vault:", `vault:${vaultName}:`)}').`,
         required_scope: requiredApiScope,
         granted_scopes: auth.scopes,
       },
@@ -435,9 +507,21 @@ export async function route(
 
   const apiPath = apiMatch[1] ?? "";
 
-  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);
+  // Tag-scoped tokens (patterns/tag-scoped-tokens.md): expand the token's
+  // root-tag allowlist into `{root} ∪ descendants(root)` once per request,
+  // so handlers can intersect against the note's tag set without re-walking
+  // the `_tags/<name>` hierarchy on every check. `tagScope.allowed` is null
+  // for unscoped tokens — the no-op fast path leaves the pre-tag-scope
+  // behavior identical.
+  const tagScope: TagScopeCtx = {
+    allowed: await expandTokenTagScope(store, auth.scoped_tags),
+    raw: auth.scoped_tags,
+  };
+
+  if (apiPath.startsWith("/notes")) return handleNotes(req, store, apiPath.slice(6), vaultName, tagScope);
+  if (apiPath.startsWith("/tags")) return handleTags(req, store, apiPath.slice(5), tagScope);
+  if (apiPath.startsWith("/note-schemas")) return handleNoteSchemas(req, store, apiPath.slice(13), tagScope);
+  if (apiPath === "/find-path") return handleFindPath(req, store, tagScope);
   if (apiPath === "/vault") {
     return handleVault(req, store, vaultConfig, () => {
       writeVaultConfig(vaultConfig);

package/src/scopes.test.ts

@@ -13,7 +13,10 @@ import {
   parseScopeFlags,
   resolveCreateTokenFlags,
   hasScope,
+  hasScopeForVault,
+  findBroadVaultScopes,
   scopeForMethod,
+  verbForMethod,
   legacyPermissionToScopes,
   serializeScopes,
 } from "./scopes.ts";
@@ -34,10 +37,10 @@ describe("parseScopes", () => {
     ]);
   });
 
-  test("collapses vault:<name>:<verb> synonym to vault:<verb>", () => {
-    expect(parseScopes("vault:journal:read")).toEqual([SCOPE_READ]);
+  test("preserves vault:<name>:<verb> narrowed shape verbatim", () => {
+    expect(parseScopes("vault:journal:read")).toEqual(["vault:journal:read"]);
     expect(parseScopes("vault:journal:write vault:work:admin")).toEqual([
-      SCOPE_WRITE, SCOPE_ADMIN,
+      "vault:journal:write", "vault:work:admin",
     ]);
   });
 
@@ -46,12 +49,13 @@ describe("parseScopes", () => {
     expect(parseScopes("vault:unknown:frob")).toEqual(["vault:unknown:frob"]);
   });
 
-  test("empty name segment does NOT collapse (vault::read stays literal)", () => {
+  test("empty name segment is treated as unrecognized (vault::read stays literal)", () => {
     // Guard against a hand-crafted DB row with `vault::read` satisfying a
     // `vault:read` check by accident. Only reachable via direct DB write,
     // not API input, but the parser stays honest.
     expect(parseScopes("vault::read")).toEqual(["vault::read"]);
     expect(hasScope(parseScopes("vault::read"), SCOPE_READ)).toBe(false);
+    expect(hasScopeForVault(parseScopes("vault::read"), "", "read")).toBe(false);
   });
 });
 
@@ -91,25 +95,79 @@ describe("hasScope — inheritance admin ⊇ write ⊇ read", () => {
     expect(hasScope(["profile"], "email")).toBe(false);
     expect(hasScope([SCOPE_ADMIN], "profile")).toBe(false);
   });
+
+  test("narrowed grant satisfies broad query (more-specific is at-least-as-strong)", () => {
+    expect(hasScope(["vault:work:write"], SCOPE_READ)).toBe(true);
+    expect(hasScope(["vault:work:write"], SCOPE_WRITE)).toBe(true);
+    expect(hasScope(["vault:work:write"], SCOPE_ADMIN)).toBe(false);
+    expect(hasScope(["vault:work:admin"], SCOPE_ADMIN)).toBe(true);
+  });
+
+  test("broad query against narrowed query returns false (use hasScopeForVault for that)", () => {
+    // hasScope refuses to answer narrowed queries — they need a vault context.
+    expect(hasScope([SCOPE_ADMIN], "vault:work:read")).toBe(false);
+    expect(hasScope(["vault:work:write"], "vault:work:read")).toBe(false);
+  });
+});
+
+describe("hasScopeForVault — per-vault matching with inheritance", () => {
+  test("broad grant satisfies any vault (caller pins via DB lookup / aud check)", () => {
+    expect(hasScopeForVault([SCOPE_READ], "work", "read")).toBe(true);
+    expect(hasScopeForVault([SCOPE_WRITE], "work", "read")).toBe(true);
+    expect(hasScopeForVault([SCOPE_WRITE], "work", "write")).toBe(true);
+    expect(hasScopeForVault([SCOPE_ADMIN], "anything", "admin")).toBe(true);
+  });
+
+  test("narrowed grant satisfies only the matching vault", () => {
+    expect(hasScopeForVault(["vault:work:read"], "work", "read")).toBe(true);
+    expect(hasScopeForVault(["vault:work:read"], "personal", "read")).toBe(false);
+    expect(hasScopeForVault(["vault:work:write"], "work", "read")).toBe(true);
+    expect(hasScopeForVault(["vault:work:admin"], "work", "write")).toBe(true);
+  });
+
+  test("narrowed grant does NOT satisfy a higher verb on its vault", () => {
+    expect(hasScopeForVault(["vault:work:read"], "work", "write")).toBe(false);
+    expect(hasScopeForVault(["vault:work:write"], "work", "admin")).toBe(false);
+  });
+
+  test("mixed grant — narrowed for one vault, broad fallback nowhere", () => {
+    expect(hasScopeForVault(["vault:work:write"], "personal", "read")).toBe(false);
+  });
+
+  test("empty grant fails everywhere", () => {
+    expect(hasScopeForVault([], "any", "read")).toBe(false);
+  });
+});
+
+describe("findBroadVaultScopes", () => {
+  test("returns broad vault scopes only", () => {
+    expect(findBroadVaultScopes([SCOPE_READ, SCOPE_WRITE])).toEqual([SCOPE_READ, SCOPE_WRITE]);
+    expect(findBroadVaultScopes(["vault:work:read"])).toEqual([]);
+    expect(findBroadVaultScopes([SCOPE_READ, "vault:work:write", "profile"])).toEqual([SCOPE_READ]);
+    expect(findBroadVaultScopes([])).toEqual([]);
+  });
 });
 
-describe("scopeForMethod", () => {
-  test("read methods → vault:read", () => {
+describe("scopeForMethod / verbForMethod", () => {
+  test("read methods → vault:read / read", () => {
     expect(scopeForMethod("GET")).toBe(SCOPE_READ);
     expect(scopeForMethod("HEAD")).toBe(SCOPE_READ);
     expect(scopeForMethod("OPTIONS")).toBe(SCOPE_READ);
     expect(scopeForMethod("get")).toBe(SCOPE_READ); // case-insensitive
+    expect(verbForMethod("GET")).toBe("read");
   });
 
-  test("write methods → vault:write", () => {
+  test("write methods → vault:write / write", () => {
     expect(scopeForMethod("POST")).toBe(SCOPE_WRITE);
     expect(scopeForMethod("PATCH")).toBe(SCOPE_WRITE);
     expect(scopeForMethod("PUT")).toBe(SCOPE_WRITE);
     expect(scopeForMethod("DELETE")).toBe(SCOPE_WRITE);
+    expect(verbForMethod("POST")).toBe("write");
   });
 
-  test("unknown method falls back to vault:write (default-deny)", () => {
+  test("unknown method falls back to write (default-deny)", () => {
     expect(scopeForMethod("TRACE")).toBe(SCOPE_WRITE);
+    expect(verbForMethod("TRACE")).toBe("write");
   });
 });
 

package/src/scopes.ts

@@ -1,11 +1,20 @@
 /**
- * Scope primitives for Phase 2 enforcement.
+ * Scope primitives for vault enforcement.
  *
- * Tokens carry OAuth-standard whitespace-separated scopes. This module parses,
- * normalizes, and matches them — including the `admin ⊇ write ⊇ read`
- * inheritance rule and the `vault:<name>:<verb>` future-shape synonym
- * (narrowed per-vault scopes are Phase 2+; today we treat them as equivalent
- * to `vault:<verb>`).
+ * Tokens carry OAuth-standard whitespace-separated scopes. Two shapes coexist:
+ *
+ *   - **Broad** `vault:<verb>` — used by `pvt_*` tokens, which are vault-pinned
+ *     by storage (each vault has its own tokens DB; a token only resolves
+ *     against the vault that minted it).
+ *   - **Narrowed** `vault:<name>:<verb>` — used by hub-issued JWTs, which are
+ *     not pinned by storage and so MUST name the resource they grant access
+ *     to. Hub JWTs carrying broad `vault:<verb>` are rejected at validation
+ *     (see `authenticateHubJwt`).
+ *
+ * Inheritance is `admin ⊇ write ⊇ read` for both shapes. `hasScopeForVault`
+ * resolves a (vault, verb) request: broad grants satisfy any vault (the
+ * caller has already pinned the vault via DB lookup), narrowed grants
+ * satisfy only the matching vault.
  *
  * Legacy back-compat: tokens without any `vault:*` scope — but with a
  * 0.2.x-era `permission = "full" | "read"` — are mapped to the appropriate
@@ -21,14 +30,40 @@ export const SCOPE_ADMIN = "vault:admin" as const;
 export const VAULT_SCOPES = [SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN] as const;
 export type VaultScope = (typeof VAULT_SCOPES)[number];
 
+/** The verb component of a vault scope — `read`, `write`, or `admin`. */
+export type VaultVerb = "read" | "write" | "admin";
+
+const VERB_RANK: Record<VaultVerb, number> = { read: 0, write: 1, admin: 2 };
+
+function isVerb(s: string): s is VaultVerb {
+  return s === "read" || s === "write" || s === "admin";
+}
+
 /**
- * Parse a whitespace-separated scope string into a normalized scope list.
+ * Decompose a scope string into `{ vault?, verb }` if it's a recognized vault
+ * scope; return `null` otherwise. Recognizes both broad (`vault:<verb>`) and
+ * narrowed (`vault:<name>:<verb>`) shapes. The empty-name case
+ * (`vault::read`) is rejected — a hand-crafted DB row with that shape must
+ * not satisfy any vault scope check.
+ */
+function decomposeVaultScope(scope: string): { vault: string | null; verb: VaultVerb } | null {
+  const parts = scope.split(":");
+  if (parts.length === 2 && parts[0] === "vault" && isVerb(parts[1]!)) {
+    return { vault: null, verb: parts[1]! as VaultVerb };
+  }
+  if (parts.length === 3 && parts[0] === "vault" && parts[1]!.length > 0 && isVerb(parts[2]!)) {
+    return { vault: parts[1]!, verb: parts[2]! as VaultVerb };
+  }
+  return null;
+}
+
+/**
+ * Parse a whitespace-separated scope string into a scope list.
  *
- * Normalization:
  *   - Empty / null → []
  *   - Trim + split on any whitespace
- *   - `vault:<name>:<verb>` collapses to `vault:<verb>` (per-vault narrowing
- *     is Phase 2+; today it's treated as a synonym)
+ *   - Both `vault:<verb>` and `vault:<name>:<verb>` shapes are preserved
+ *     verbatim; `hasScope` / `hasScopeForVault` decide what each satisfies.
  *   - Unrecognized scopes are preserved as-is (they just won't match anything)
  */
 export function parseScopes(raw: string | null | undefined): string[] {
@@ -36,38 +71,65 @@ export function parseScopes(raw: string | null | undefined): string[] {
   return raw
     .split(/\s+/)
     .map((s) => s.trim())
-    .filter(Boolean)
-    .map((s) => normalizeScope(s));
-}
-
-function normalizeScope(scope: string): string {
-  // `vault:<name>:<verb>` → `vault:<verb>` (synonym collapse). Reject an empty
-  // name segment (`vault::read`) — preserve it as-is so it can't accidentally
-  // satisfy a `vault:read` check. Only reachable via direct DB write, but the
-  // one-liner keeps the parser honest.
-  const parts = scope.split(":");
-  if (parts.length === 3 && parts[0] === "vault" && parts[1].length > 0) {
-    const verb = parts[2];
-    if (verb === "read" || verb === "write" || verb === "admin") {
-      return `vault:${verb}`;
-    }
-  }
-  return scope;
+    .filter(Boolean);
 }
 
 /**
- * Return true iff `granted` satisfies `required` under the inheritance rule
- * `admin ⊇ write ⊇ read`. Exact-match required for non-vault scopes.
+ * Broad-query check: does `granted` satisfy `required` (e.g. `vault:read`)?
+ *
+ * Used by code paths that don't have a specific vault in hand — JWT claim
+ * inspection, MCP tool list filtering inside a session that's already pinned
+ * to one vault, the legacy permission-derivation path. For per-request
+ * routing where the URL names a vault, prefer `hasScopeForVault`.
+ *
+ * A `vault:<name>:<verb>` grant DOES satisfy a broad `vault:<verb>` query —
+ * narrowed scopes are strictly more specific. The reverse is not true; broad
+ * grants do not satisfy narrowed queries via this function.
+ *
+ * Inheritance `admin ⊇ write ⊇ read` applies in both forms. Non-vault scopes
+ * require exact match.
  */
 export function hasScope(granted: string[], required: string): boolean {
   if (granted.includes(required)) return true;
 
-  // Inheritance: admin ⊇ write ⊇ read
-  if (required === SCOPE_READ) {
-    return granted.includes(SCOPE_WRITE) || granted.includes(SCOPE_ADMIN);
+  const requiredDecomposed = decomposeVaultScope(required);
+  if (!requiredDecomposed || requiredDecomposed.vault !== null) {
+    // Non-vault scope or narrowed query — exact match only via hasScope.
+    // (Narrowed queries belong on hasScopeForVault.)
+    return false;
   }
-  if (required === SCOPE_WRITE) {
-    return granted.includes(SCOPE_ADMIN);
+  const reqRank = VERB_RANK[requiredDecomposed.verb];
+  for (const s of granted) {
+    const d = decomposeVaultScope(s);
+    if (d && VERB_RANK[d.verb] >= reqRank) return true;
+  }
+  return false;
+}
+
+/**
+ * Per-vault check: does `granted` satisfy a (vault, verb) request? Use this
+ * at request-routing time — the URL names the vault and the method picks
+ * the verb.
+ *
+ * Match rules:
+ *   - Broad `vault:<verb>` in granted satisfies any vault (the broad scope
+ *     has no resource constraint; the caller pins the vault upstream — pvt_*
+ *     resolves only against its issuing vault's DB, hub JWTs reject broad
+ *     scopes at validation).
+ *   - Narrowed `vault:<name>:<verb>` satisfies only the matching `vaultName`.
+ *   - Verb inheritance `admin ⊇ write ⊇ read` applies in both forms.
+ */
+export function hasScopeForVault(
+  granted: string[],
+  vaultName: string,
+  requiredVerb: VaultVerb,
+): boolean {
+  const reqRank = VERB_RANK[requiredVerb];
+  for (const s of granted) {
+    const d = decomposeVaultScope(s);
+    if (!d) continue;
+    if (d.vault !== null && d.vault !== vaultName) continue;
+    if (VERB_RANK[d.verb] >= reqRank) return true;
   }
   return false;
 }
@@ -78,12 +140,76 @@ export function hasScope(granted: string[], required: string): boolean {
  *   - POST/PATCH/PUT/DELETE → write
  *
  * Admin-gated endpoints (like `/.parachute/config`) don't go through this
- * helper — they call `hasScope(auth.scopes, SCOPE_ADMIN)` directly.
+ * helper — they call `hasScopeForVault(auth.scopes, vaultName, "admin")`
+ * directly.
  */
 export function scopeForMethod(method: string): VaultScope {
+  return verbForMethod(method) === "read" ? SCOPE_READ : SCOPE_WRITE;
+}
+
+/** Verb-only variant of `scopeForMethod`, for use with `hasScopeForVault`. */
+export function verbForMethod(method: string): VaultVerb {
   const m = method.toUpperCase();
-  if (m === "GET" || m === "HEAD" || m === "OPTIONS") return SCOPE_READ;
-  return SCOPE_WRITE;
+  if (m === "GET" || m === "HEAD" || m === "OPTIONS") return "read";
+  return "write";
+}
+
+/**
+ * Validate scopes requested for token minting on a specific vault.
+ *
+ * Each requested scope must be (a) a recognized vault scope shape, (b) not
+ * naming a different vault (cross-vault rejected), and (c) within the
+ * caller's verb power on `vaultName`. The third check is defense-in-depth:
+ * the REST endpoint already gates on `vault:admin`, but enforcing subset
+ * here means a future loosening of the gate (or a partially-trusted caller)
+ * still cannot mint a token stronger than what they hold.
+ *
+ * Pass-through on success — we don't rewrite scopes, just decide yes/no.
+ */
+export function validateMintedScopes(
+  requested: string[],
+  vaultName: string,
+  callerScopes: string[],
+): { ok: true } | { ok: false; rejected: { scope: string; reason: string }[] } {
+  const rejected: { scope: string; reason: string }[] = [];
+  for (const s of requested) {
+    const d = decomposeVaultScope(s);
+    if (!d) {
+      rejected.push({ scope: s, reason: "unknown or unsupported scope" });
+      continue;
+    }
+    if (d.vault !== null && d.vault !== vaultName) {
+      rejected.push({
+        scope: s,
+        reason: `cross-vault scope not allowed (this endpoint mints for vault '${vaultName}')`,
+      });
+      continue;
+    }
+    if (!hasScopeForVault(callerScopes, vaultName, d.verb)) {
+      rejected.push({
+        scope: s,
+        reason: `caller lacks '${d.verb}' on vault '${vaultName}' — cannot grant a stronger scope than held`,
+      });
+      continue;
+    }
+  }
+  if (rejected.length > 0) return { ok: false, rejected };
+  return { ok: true };
+}
+
+/**
+ * Detect a broad `vault:<verb>` scope in a granted list. Hub-issued JWTs
+ * must NOT carry broad vault scopes — the hub mints `vault:<name>:<verb>` so
+ * the resource is named on the wire. `authenticateHubJwt` calls this to
+ * reject tokens that slipped through with the old shape.
+ */
+export function findBroadVaultScopes(granted: string[]): string[] {
+  const out: string[] = [];
+  for (const s of granted) {
+    const d = decomposeVaultScope(s);
+    if (d && d.vault === null) out.push(s);
+  }
+  return out;
 }
 
 /**