@openparachute/hub 0.5.7 → 0.5.10-rc.2

package/src/module-manifest.ts

@@ -114,6 +114,27 @@ export interface ModuleManifest {
    * as `hasAuth` / `init` / `urlForEntry`.
    */
   readonly managementUrl?: string;
+  /**
+   * Where the module's primary user-facing UI lives. Hub renders a tile on
+   * the discovery page (`/`) Services section when set (see
+   * `parachute-patterns/patterns/module-json-extensibility.md` and the
+   * `loadUiUrls` resolver in `hub-server.ts`).
+   *
+   * Two shapes — same rules as `managementUrl`:
+   *   - A relative path (e.g. `"/notes"`, `"/agent"`) — hub resolves
+   *     against the canonical hub origin.
+   *   - A full absolute URL — hub uses verbatim.
+   *
+   * Absent = no Services tile rendered (the module is API-only or surfaces
+   * its UI via a sibling module — e.g. vault content browses through Notes,
+   * so vault has no `uiUrl`).
+   *
+   * Read at every discovery render via `installDir/.parachute/module.json`
+   * (mirrors how `managementUrl` is sourced for vaults). Not persisted in
+   * services.json — that file's "services own the write side" semantics
+   * would clobber any install-time copy on the next service boot.
+   */
+  readonly uiUrl?: string;
   /**
    * When `true`, the hub's `/<svc>/*` proxy strips the matched mount prefix
    * before forwarding (so the backend sees `/health` rather than
@@ -374,6 +395,7 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   const dependencies = asDependencies(m.dependencies, where);
   const configSchema = asConfigSchema(m.configSchema, where);
   const managementUrl = asManagementUrl(m.managementUrl, where);
+  const uiUrl = asUiUrl(m.uiUrl, where);
   let stripPrefix: boolean | undefined;
   if (m.stripPrefix !== undefined) {
     if (typeof m.stripPrefix !== "boolean") {
@@ -396,6 +418,9 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   if (managementUrl !== undefined) {
     (out as { managementUrl?: string }).managementUrl = managementUrl;
   }
+  if (uiUrl !== undefined) {
+    (out as { uiUrl?: string }).uiUrl = uiUrl;
+  }
   if (stripPrefix !== undefined) {
     (out as { stripPrefix?: boolean }).stripPrefix = stripPrefix;
   }
@@ -403,26 +428,39 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
 }
 
 function asManagementUrl(v: unknown, where: string): string | undefined {
+  return asPathOrUrl(v, where, "managementUrl");
+}
+
+function asUiUrl(v: unknown, where: string): string | undefined {
+  return asPathOrUrl(v, where, "uiUrl");
+}
+
+/**
+ * Validate a "path or http(s) URL" field. Both `managementUrl` and `uiUrl`
+ * follow the same shape per the module-json-extensibility pattern doc;
+ * factored so the next URL-shaped field doesn't have to copy-paste.
+ */
+function asPathOrUrl(v: unknown, where: string, field: string): string | undefined {
   if (v === undefined) return undefined;
   if (typeof v !== "string" || v.length === 0) {
-    throw new ModuleManifestError(
-      `${where}: "managementUrl" must be a non-empty string if present`,
-    );
-  }
-  // Two valid shapes: a path starting with "/" or a full http(s) URL.
-  if (v.startsWith("/")) return v;
+    throw new ModuleManifestError(`${where}: "${field}" must be a non-empty string if present`);
+  }
+  // Two valid shapes: an absolute path starting with a single "/" or a full
+  // http(s) URL. Reject protocol-relative forms like "//evil.com" — they
+  // start with "/" but `new URL("//evil.com", base)` resolves to the foreign
+  // origin, which would let a malicious module render an off-origin tile and
+  // turn the discovery page into an open-redirect surface.
+  if (v.startsWith("/") && !v.startsWith("//")) return v;
   try {
     const u = new URL(v);
     if (u.protocol !== "http:" && u.protocol !== "https:") {
-      throw new ModuleManifestError(
-        `${where}: "managementUrl" absolute form must use http: or https:`,
-      );
+      throw new ModuleManifestError(`${where}: "${field}" absolute form must use http: or https:`);
     }
     return v;
   } catch (err) {
     if (err instanceof ModuleManifestError) throw err;
     throw new ModuleManifestError(
-      `${where}: "managementUrl" must be a path starting with "/" or a full http(s) URL`,
+      `${where}: "${field}" must be a path starting with "/" or a full http(s) URL`,
     );
   }
 }

package/src/oauth-handlers.ts

@@ -62,6 +62,7 @@ import {
   renderError,
   renderLogin,
 } from "./oauth-ui.ts";
+import { isSameOriginRequest } from "./origin-check.ts";
 import { isNonRequestableScope, isRequestableScope } from "./scope-explanations.ts";
 import { findUnknownScopes, loadDeclaredScopes } from "./scope-registry.ts";
 import {
@@ -143,6 +144,18 @@ export interface OAuthDeps {
    * `~/.parachute/services.json`; tests inject a fixture.
    */
   loadServicesManifest?: () => ServicesManifest;
+  /**
+   * Set of origins (`scheme://host:port`) the hub considers itself bound to.
+   * Drives the same-origin defense on cookie-based POST endpoints: a request
+   * whose Origin/Referer matches any bound origin is accepted; everything
+   * else is rejected as cross-origin. Production wires this from
+   * `buildHubBoundOrigins` with the hub's port + expose-state hostname so
+   * loopback + tailnet + funnel access all work without restarting hub
+   * after `parachute expose`. Tests inject deterministic sets. When absent,
+   * the gate falls back to `[issuer]` — pre-#245 behavior — so callers that
+   * don't yet thread this through stay correct on a single-origin hub.
+   */
+  hubBoundOrigins?: () => readonly string[];
 }
 
 export interface ServicesCatalogEntry {
@@ -158,41 +171,129 @@ export type ServicesCatalog = Record<string, ServicesCatalogEntry>;
  * version, so OAuth clients don't have to re-probe `/.well-known/parachute.json`
  * to know where vault lives.
  *
- * URL source: `entry.paths[0]` from services.json verbatim — never hardcode
+ * URL source: `entry.paths[*]` from services.json verbatim — never hardcode
  * `/vault/default`. Users who installed with `parachute install vault
  * --vault-name work` have `paths: ["/vault/work"]` in their manifest, and the
  * catalog URL must follow that. The custom-vault-name regression test in
- * oauth-handlers.test.ts pins this.
+ * oauth-handlers.test.ts pins this for single-vault.
  *
  * Filtering: only services for which the token has at least one scope are
  * included. A scope `vault:read` admits the `vault` service; a token with only
  * `scribe:transcribe` gets a catalog with no vault entry. The check is on the
  * audience prefix (`<aud>:<verb>`) — same shape `inferAudience` uses.
  *
- * Multi-vault: Phase 1 collapses every vault entry under the single key
- * `vault`, first matching `parachute-vault*` row wins. Per-vault keys
- * (`services.vault.work.url` or `services["vault:work"].url`) are deferred
- * to a future design once notes ships its vault picker; multi-vault clients
- * need to probe `/.well-known/parachute.json` for the full vaults array
- * until then.
+ * Multi-vault (closes #247): emits per-vault keys `vault:<name>` alongside
+ * the collapsed `vault` key. A scope `vault:boulder:write` admits only
+ * boulder → emits `vault:boulder` (and the legacy `vault` key, pointing at
+ * boulder so it resolves consistently). A broad scope `vault:read` admits
+ * every vault on the hub → emits `vault:<name>` for each vault path plus
+ * the legacy `vault` key (pointing at `entry.paths[0]` of the first vault,
+ * unchanged from Phase 1). Notes' OAuthCallback (notes#115 ships the
+ * picker; per-vault consumer change is the post-#247 Notes-side PR) reads
+ * `services["vault:<name>"]` so it stops collapsing multi-vault grants
+ * onto a single VaultRecord URL.
+ *
+ * Pre-popover clients still see `services.vault` and behave unchanged —
+ * that key never goes away. Per-vault keys are additive.
  */
 export function buildServicesCatalog(
   manifest: ServicesManifest,
   issuer: string,
   scopes: readonly string[],
 ): ServicesCatalog {
+  // Two scope-derived sets:
+  //   - audiences: bare service prefix (`vault`, `scribe`) → admits the
+  //     collapsed key + every per-vault key.
+  //   - namedVaults: per-vault narrowed scopes (`vault:<name>:<verb>`) →
+  //     admits only `vault:<name>` and the collapsed `vault`.
+  //
+  // A token with both `vault:read` and `vault:boulder:write` should land in
+  // the "any vault" bucket — the bare scope is permissive, the named one
+  // is informational. Detect this via the bare-prefix presence; the named
+  // scope's per-vault narrowing still works for clients that prefer it.
   const audiences = new Set<string>();
+  const namedVaults = new Set<string>();
   for (const s of scopes) {
+    const parts = s.split(":");
+    if (
+      parts.length === 3 &&
+      parts[0] === "vault" &&
+      parts[1] &&
+      parts[2] &&
+      VAULT_VERBS.has(parts[2])
+    ) {
+      namedVaults.add(parts[1]);
+      audiences.add("vault");
+      continue;
+    }
     const colon = s.indexOf(":");
     if (colon > 0) audiences.add(s.slice(0, colon));
   }
+  const broadVaultScope =
+    audiences.has("vault") &&
+    scopes.some((s) => {
+      const parts = s.split(":");
+      return (
+        parts.length === 2 &&
+        parts[0] === "vault" &&
+        parts[1] !== undefined &&
+        VAULT_VERBS.has(parts[1])
+      );
+    });
+
+  // Count total admitted vault paths across the manifest. Per-vault keys
+  // are only worth emitting when there are >1 admitted vaults to
+  // disambiguate (or when the token's own scopes are per-vault narrowed —
+  // a per-vault scope is an explicit consumer signal that the per-vault
+  // key matters even on a single-vault hub). The check is on admitted
+  // paths, not raw vault rows: a broad token on a multi-path vault row
+  // sees N paths; a per-vault token sees only its own.
+  let admittedVaultPathCount = 0;
+  if (audiences.has("vault")) {
+    for (const entry of manifest.services) {
+      if (!isVaultEntry(entry)) continue;
+      const paths = entry.paths.length > 0 ? entry.paths : ["/"];
+      for (const path of paths) {
+        const instance = vaultInstanceNameFor(entry.name, path);
+        if (broadVaultScope || namedVaults.has(instance)) admittedVaultPathCount++;
+      }
+    }
+  }
+  const emitPerVaultKeys = admittedVaultPathCount > 1 || namedVaults.size > 0;
+
   const base = issuer.replace(/\/$/, "");
   const catalog: ServicesCatalog = {};
   for (const entry of manifest.services) {
-    const path = entry.paths[0] ?? "/";
-    const key = isVaultEntry(entry) ? "vault" : shortName(entry.name);
+    if (isVaultEntry(entry)) {
+      if (!audiences.has("vault")) continue;
+      // Walk every path the row exposes. Real multi-vault on the hub is a
+      // single `parachute-vault` row with N paths (one per vault instance);
+      // legacy per-vault rows (`parachute-vault-<name>`) are handled by the
+      // same loop because each contributes one path.
+      const paths = entry.paths.length > 0 ? entry.paths : ["/"];
+      for (const path of paths) {
+        const instance = vaultInstanceNameFor(entry.name, path);
+        const admit = broadVaultScope || namedVaults.has(instance);
+        if (!admit) continue;
+        if (emitPerVaultKeys) {
+          const perVaultKey = `vault:${instance}`;
+          if (!catalog[perVaultKey]) {
+            catalog[perVaultKey] = { url: `${base}${path}`, version: entry.version };
+          }
+        }
+        // Collapsed `vault` key stays for backwards compat. First admitted
+        // vault wins (deterministic — `entry.paths[0]` for a broad scope,
+        // or the only admitted instance for a per-vault scope).
+        if (!catalog.vault) {
+          catalog.vault = { url: `${base}${path}`, version: entry.version };
+        }
+      }
+      continue;
+    }
+    const key = shortName(entry.name);
     if (!audiences.has(key)) continue;
-    if (catalog[key]) continue; // first vault wins; deterministic for clients
+    if (catalog[key]) continue;
+    const path = entry.paths[0] ?? "/";
     catalog[key] = { url: `${base}${path}`, version: entry.version };
   }
   return catalog;
@@ -330,8 +431,14 @@ function pendingClientResponse(
   const requestedScopes = (authorizeUrl.searchParams.get("scope") ?? "")
     .split(" ")
     .filter((s) => s.length > 0);
+  // Vault hint (closes #244): Notes' VaultPopover (notes#115) sets this on
+  // the authorize URL when kicking OAuth for a specific vault. Empty-string
+  // values normalize to undefined so the approve UI omits the row rather
+  // than rendering a blank vault label.
+  const vaultParam = authorizeUrl.searchParams.get("vault");
+  const requestedVault = vaultParam && vaultParam.length > 0 ? vaultParam : undefined;
   const session = findActiveSession(db, req, deps.now ?? (() => new Date()));
-  const sameOrigin = originMatchesIssuer(req, deps.issuer);
+  const sameOrigin = isSameOriginRequest(req, resolveBoundOrigins(deps));
   const csrf = ensureCsrfToken(req);
   const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
   if (session && sameOrigin) {
@@ -342,6 +449,7 @@ function pendingClientResponse(
         clientId: client.clientId,
         redirectUris: client.redirectUris,
         requestedScopes,
+        ...(requestedVault !== undefined && { requestedVault }),
         approveForm: { csrfToken: csrf.token, returnTo },
       }),
       403,
@@ -354,18 +462,39 @@ function pendingClientResponse(
       clientId: client.clientId,
       redirectUris: client.redirectUris,
       requestedScopes,
+      ...(requestedVault !== undefined && { requestedVault }),
     }),
     403,
     extra,
   );
 }
 
-/** JSON response for pending clients hitting /oauth/token. */
-function pendingClientJson(): Response {
+/**
+ * JSON response for pending clients hitting /oauth/token. Carries two
+ * actionability hints alongside the OAuth error so consumers (Notes, future
+ * cross-origin SPAs) can surface an inline approval path instead of dead-
+ * ending on a CLI message:
+ *
+ *   - `approve_url` — hub-served SPA route the operator can open in a
+ *     browser to approve the client in one click. Same-origin to the hub.
+ *   - `cli_alternative` — the `parachute auth approve-client <id>` shell
+ *     command, retained for terminal-first operators or scripted flows.
+ *
+ * Spec note: the OAuth error class stays `invalid_client` per RFC 6749 §5.2
+ * — "this client cannot use this endpoint right now" is the semantic match.
+ * `access_denied` is reserved for /authorize "user said no" flows; using it
+ * here would conflate two distinct error families and break clients doing
+ * strict spec-shaped handling. The extra fields are spec-permitted
+ * extensions ("other parameters").
+ */
+function pendingClientJson(clientId: string, issuer: string): Response {
+  const base = issuer.replace(/\/$/, "");
   return jsonResponse(
     {
       error: "invalid_client",
       error_description: "client is registered but has not been approved by the hub operator (#74)",
+      approve_url: `${base}/admin/approve-client/${encodeURIComponent(clientId)}`,
+      cli_alternative: `parachute auth approve-client ${clientId}`,
     },
     401,
   );
@@ -376,6 +505,61 @@ function pendingClientJson(): Response {
  * either renders the login form (no session) or the consent screen (session
  * present). All authorize-time params are echoed back via hidden inputs so
  * the form POST keeps the binding intact.
+ *
+ * ## Silent-approve flow (skip-consent gate, hub#75, hub#236)
+ *
+ * Cross-surface session smoothness ("first Notes use prompts for consent;
+ * subsequent uses are seamless") rides on a single gate further down in
+ * this function. The end-to-end flow:
+ *
+ *   1. **First use.** A client lands on `/oauth/authorize` with scope `S`.
+ *      The user has a session but no prior `grants` row for this
+ *      (user, client) pair. `isCoveredByGrant` returns false; the gate
+ *      falls through; the consent screen renders. User clicks approve →
+ *      `handleAuthorizePost` records a `grants` row keyed on
+ *      (user_id, client_id) with the approved scopes, then mints the
+ *      auth code.
+ *   2. **Subsequent use, same scopes.** Same client lands on
+ *      `/oauth/authorize` with scope `S` again. `isCoveredByGrant` finds
+ *      the row and returns true. The gate fires: auth code minted
+ *      directly via `issueAuthCodeRedirect`; no consent screen renders;
+ *      operator sees a silent redirect. This is the seamless second-use
+ *      experience.
+ *   3. **Subsequent use, subset.** Client asks for scope `S' ⊂ S`. The
+ *      grant covers every requested scope; gate fires.
+ *   4. **Subsequent use, novel scope.** Client asks for scope `S''`
+ *      where `S'' ⊄ S` (a strict superset, or any new scope). The grant
+ *      doesn't cover the new ask; gate falls through; consent re-renders
+ *      with the new scope explicit. User must approve to extend the grant.
+ *   5. **Grant revoked.** Operator revokes via `/admin/permissions` or
+ *      `parachute auth revoke-grant`. The next /authorize re-renders
+ *      consent — already-minted refresh tokens keep working until they
+ *      expire (or are revoked separately via `/oauth/revoke`).
+ *
+ * Two important constraints on the gate itself:
+ *
+ *   - **Unnamed vault verbs (`vault:read`) always render consent.** The
+ *     vault-picker UI is the only path that binds an unnamed scope to a
+ *     specific vault (grants store narrowed `vault:<name>:<verb>`, so
+ *     `vault:read` never matches a stored grant literally). Re-flowing
+ *     with `vault:read` must always show the picker even if any prior
+ *     grant exists.
+ *   - **Client re-registration breaks the grant link.** Dynamic Client
+ *     Registration mints a fresh `client_id` each time; grants are keyed
+ *     on `(user_id, client_id)` so a re-registered client looks brand-
+ *     new and re-prompts for consent. (Intentional: the operator should
+ *     re-consent to an app whose registration was destroyed and re-made
+ *     — that's a stronger signal of "this is the same app I trusted"
+ *     than the redirect URI alone.)
+ *
+ * The full grant-scope subset semantics live in `grants.ts`
+ * `isCoveredByGrant`; the gate itself is the if-block below the
+ * "Skip-consent gate" comment in this function.
+ *
+ * Pinned by the regression test "first-use consent → silent-approve →
+ * novel scope re-prompts" in `oauth-handlers.test.ts` (hub#236), plus
+ * the per-branch tests in the same describe block (subset / superset /
+ * revoke / unnamed-vault / re-registered-client).
  */
 export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps): Response {
   const url = new URL(req.url);
@@ -692,9 +876,12 @@ async function handleConsentSubmit(
  *   2. Active operator session (`findActiveSession`). The operator must be
  *      logged into this hub from the browser submitting the form — no
  *      session means no operator authority to approve anything.
- *   3. Origin/Referer matches the issuer (`originMatchesIssuer`). Same
- *      shape as the DCR auto-approve gate (#199, #200): a same-origin POST
- *      proves the form was rendered by *this hub*, not a forged page.
+ *   3. Origin/Referer matches a hub-bound origin (`isSameOriginRequest`).
+ *      Same shape as the DCR auto-approve gate (#199, #200, #245): a same-
+ *      origin POST proves the form was rendered by *this hub*, not a forged
+ *      page. Bound origins include issuer + loopback + tailnet hostname
+ *      (#245); pre-#245 was issuer-only and rejected legitimate operator
+ *      paths from loopback / tailnet.
  *
  * `return_to` validation: the form embeds the original authorize URL so
  * the post-approve redirect lands the operator back on `/oauth/authorize`
@@ -725,7 +912,7 @@ export async function handleApproveClientPost(
       401,
     );
   }
-  if (!originMatchesIssuer(req, deps.issuer)) {
+  if (!isSameOriginRequest(req, resolveBoundOrigins(deps))) {
     return htmlError(
       "Cross-origin request rejected",
       "The approve form must be submitted from this hub's own origin.",
@@ -931,7 +1118,7 @@ async function handleTokenAuthorizationCode(
   if (!client) {
     return jsonResponse({ error: "invalid_client", error_description: "unknown client_id" }, 401);
   }
-  if (client.status !== "approved") return pendingClientJson();
+  if (client.status !== "approved") return pendingClientJson(client.clientId, deps.issuer);
   const authFailure = authenticateClient(client, req, form, clientId);
   if (authFailure) return authFailure;
   let redeemed: ReturnType<typeof redeemAuthCode>;
@@ -966,6 +1153,13 @@ async function handleTokenAuthorizationCode(
     issuer: deps.issuer,
     now: deps.now,
   });
+  // Phase 1 (#212) registry exemption: code-grant access tokens piggyback
+  // on the paired refresh token's `tokens` row (they share `jti` by
+  // design). We don't write a separate access-token row — revocation acts
+  // on the shared jti / family, and the 15-min access TTL bounds the
+  // window before per-jti re-validation is needed. A separate per-jti
+  // access-token row would double registry write volume on every OAuth
+  // grant + every refresh rotation; not worth the trade today.
   const refresh = signRefreshToken(db, {
     jti: access.jti,
     userId: redeemed.userId,
@@ -1006,7 +1200,7 @@ async function handleTokenRefresh(
   if (!client) {
     return jsonResponse({ error: "invalid_client", error_description: "unknown client_id" }, 401);
   }
-  if (client.status !== "approved") return pendingClientJson();
+  if (client.status !== "approved") return pendingClientJson(client.clientId, deps.issuer);
   const authFailure = authenticateClient(client, req, form, clientId);
   if (authFailure) return authFailure;
   const row = findRefreshToken(db, refreshToken);
@@ -1019,6 +1213,18 @@ async function handleTokenRefresh(
   if (row.clientId !== clientId) {
     return jsonResponse({ error: "invalid_grant", error_description: "client_id mismatch" }, 400);
   }
+  // Refresh-token rows always have a non-null user_id (the caller's hub
+  // user). Post-v6 the column is nullable to accommodate non-OAuth mints
+  // (operator/cli mints), but those rows have no `refresh_token_hash` so
+  // `findRefreshToken` can't return them. Defensive: surface a clean
+  // invalid_grant if a hand-crafted row shows up here without a user.
+  if (!row.userId) {
+    return jsonResponse(
+      { error: "invalid_grant", error_description: "refresh_token has no associated user" },
+      400,
+    );
+  }
+  const refreshUserId: string = row.userId;
   const now = deps.now?.() ?? new Date();
   if (row.revokedAt) {
     // Replay of an already-rotated refresh token. Per RFC 6819 §5.2.2.3 the
@@ -1053,7 +1259,7 @@ async function handleTokenRefresh(
   // (#107).
   const audience = inferAudience(row.scopes);
   const access = await signAccessToken(db, {
-    sub: row.userId,
+    sub: refreshUserId,
     scopes: row.scopes,
     audience,
     clientId: row.clientId,
@@ -1066,7 +1272,7 @@ async function handleTokenRefresh(
       db.prepare("UPDATE tokens SET revoked_at = ? WHERE jti = ?").run(now.toISOString(), row.jti);
       return signRefreshToken(db, {
         jti: access.jti,
-        userId: row.userId,
+        userId: refreshUserId,
         clientId: row.clientId,
         scopes: row.scopes,
         familyId: row.familyId,
@@ -1236,37 +1442,15 @@ interface RegisterRequestBody {
 }
 
 /**
- * CSRF defense for the cookie-based DCR auto-approve path (closes #199).
- *
- * Compares the request's `Origin` (or `Referer` as fallback) against the
- * configured issuer origin. URL.origin compares scheme + host + port —
- * port-only mismatches reject. A request with neither header is treated as
- * suspicious and rejected: cookie-bearing POSTs from same-origin browsers
- * always send Origin (per Fetch standard) and almost always send Referer,
- * so a header-stripped request is more likely a curl probe or a privacy
- * extension on a third-party site than a legitimate same-origin caller.
- *
- * SameSite=Lax on the session cookie (sessions.ts:buildSessionCookie) is the
- * browser-side defense layer; this function is the server-side belt.
+ * Resolve the hub-bound origin set for a given `OAuthDeps`. Pre-#245 this
+ * was implicit (just `deps.issuer`); post-#245 callers can thread a richer
+ * set through `deps.hubBoundOrigins` so loopback + tailnet + funnel access
+ * all match. Fallback to `[issuer]` keeps callers that haven't migrated
+ * correct on single-origin hubs.
  */
-function originMatchesIssuer(req: Request, issuer: string): boolean {
-  const origin = req.headers.get("origin");
-  if (origin) {
-    try {
-      return new URL(origin).origin === new URL(issuer).origin;
-    } catch {
-      return false;
-    }
-  }
-  const referer = req.headers.get("referer");
-  if (referer) {
-    try {
-      return new URL(referer).origin === new URL(issuer).origin;
-    } catch {
-      return false;
-    }
-  }
-  return false;
+function resolveBoundOrigins(deps: OAuthDeps): readonly string[] {
+  if (deps.hubBoundOrigins) return deps.hubBoundOrigins();
+  return [deps.issuer];
 }
 
 /**
@@ -1284,7 +1468,7 @@ function originMatchesIssuer(req: Request, issuer: string): boolean {
  *    plus a same-origin `Origin`/`Referer` header. The browser path: an
  *    operator hitting their own SPA from their own browser is by definition
  *    operator-authenticated, so re-requiring approval is friction without
- *    benefit. CSRF defense is `originMatchesIssuer` + the cookie's
+ *    benefit. CSRF defense is `isSameOriginRequest` + the cookie's
  *    `SameSite=Lax` attribute.
  *
  * If a bearer is presented but invalid or insufficient, we reject with the
@@ -1357,7 +1541,7 @@ export async function handleRegister(
   // public-DCR shape.
   if (status === "pending") {
     const session = findActiveSession(db, req, deps.now ?? (() => new Date()));
-    if (session && originMatchesIssuer(req, deps.issuer)) {
+    if (session && isSameOriginRequest(req, resolveBoundOrigins(deps))) {
       status = "approved";
     }
   }

package/src/oauth-ui.ts

@@ -111,6 +111,14 @@ export interface ApprovePendingViewProps {
   redirectUris: string[];
   /** Scopes parsed from the original `/oauth/authorize?scope=` query param. */
   requestedScopes: string[];
+  /**
+   * Vault hint from the original `/oauth/authorize?vault=<name>` query param,
+   * passed by Notes' VaultPopover (notes#115) when kicking the OAuth flow for
+   * a specific vault. Rendered alongside scopes so the operator can tell
+   * which vault they're approving access for on a multi-vault hub (closes
+   * #244). Single-vault hubs leave this absent and the section omits.
+   */
+  requestedVault?: string;
   /**
    * When set, render the inline approve form. The form posts to
    * `/oauth/authorize/approve` with the CSRF token + a `return_to` URL the
@@ -245,12 +253,25 @@ function renderVaultPicker(picker: VaultPicker): string {
  * context). The button is the easy path; the CLI is always-available.
  */
 export function renderApprovePending(props: ApprovePendingViewProps): string {
-  const { clientName, clientId, redirectUris, requestedScopes, approveForm } = props;
+  const { clientName, clientId, redirectUris, requestedScopes, requestedVault, approveForm } =
+    props;
   const redirectList = redirectUris.map((u) => `<li><code>${escapeHtml(u)}</code></li>`).join("");
   const scopeRows =
     requestedScopes.length === 0
       ? `<li class="scope scope-empty">No scopes requested — the app gets a session token only.</li>`
       : requestedScopes.map(renderScopeRow).join("\n");
+  // Vault hint (closes #244): Notes' VaultPopover (notes#115) passes
+  // `vault=<name>` on `/oauth/authorize` for per-vault grants. Surface it
+  // alongside scopes so a multi-vault operator can tell which vault they're
+  // approving for. Missing on single-vault hubs / pre-vault-popover clients —
+  // section omits when absent.
+  const vaultRow = requestedVault
+    ? `
+        <p class="approve-meta-row">
+          <span class="approve-meta-label">vault</span>
+          <code class="approve-meta-value">${escapeHtml(requestedVault)}</code>
+        </p>`
+    : "";
   const formSection = approveForm
     ? `
       <form method="POST" action="/oauth/authorize/approve" class="auth-form approve-form">
@@ -289,7 +310,7 @@ export function renderApprovePending(props: ApprovePendingViewProps): string {
         <p class="approve-meta-row">
           <span class="approve-meta-label">client_id</span>
           <code class="approve-meta-value">${escapeHtml(clientId)}</code>
-        </p>
+        </p>${vaultRow}
         <div class="approve-meta-row approve-meta-row-block">
           <span class="approve-meta-label">redirect_uris</span>
           <ul class="approve-redirect-list">${redirectList}</ul>