npm - @openparachute/hub - Versions diffs - 0.5.14-rc.2 → 0.5.14-rc.21 - Mend

@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (106) hide show

package/README.md +109 -15
package/package.json +7 -3
package/src/__tests__/account-home-ui.test.ts +251 -15
package/src/__tests__/account-vault-token.test.ts +355 -0
package/src/__tests__/admin-vaults.test.ts +70 -4
package/src/__tests__/api-mint-token.test.ts +693 -5
package/src/__tests__/api-modules-config.test.ts +16 -10
package/src/__tests__/api-modules-ops.test.ts +45 -0
package/src/__tests__/api-modules.test.ts +92 -75
package/src/__tests__/api-ready.test.ts +135 -0
package/src/__tests__/api-revoke-token.test.ts +384 -0
package/src/__tests__/api-users.test.ts +7 -2
package/src/__tests__/auth.test.ts +157 -30
package/src/__tests__/cli.test.ts +44 -5
package/src/__tests__/cloudflare-detect.test.ts +60 -5
package/src/__tests__/expose-2fa-warning.test.ts +31 -17
package/src/__tests__/expose-auth-preflight.test.ts +71 -72
package/src/__tests__/expose-cloudflare.test.ts +582 -11
package/src/__tests__/expose-interactive.test.ts +10 -4
package/src/__tests__/expose-public-auto.test.ts +5 -1
package/src/__tests__/expose.test.ts +52 -2
package/src/__tests__/hub-server.test.ts +396 -10
package/src/__tests__/hub.test.ts +85 -6
package/src/__tests__/init.test.ts +928 -0
package/src/__tests__/lifecycle.test.ts +464 -2
package/src/__tests__/migrate.test.ts +433 -51
package/src/__tests__/oauth-handlers.test.ts +1252 -83
package/src/__tests__/oauth-ui.test.ts +12 -1
package/src/__tests__/operator-token-issuer-self-heal.test.ts +412 -0
package/src/__tests__/proxy-error-ui.test.ts +212 -0
package/src/__tests__/proxy-state.test.ts +192 -0
package/src/__tests__/resource-binding.test.ts +97 -0
package/src/__tests__/scope-explanations.test.ts +77 -12
package/src/__tests__/services-manifest.test.ts +122 -4
package/src/__tests__/setup-wizard.test.ts +633 -53
package/src/__tests__/status.test.ts +36 -0
package/src/__tests__/two-factor-flow.test.ts +602 -0
package/src/__tests__/two-factor.test.ts +183 -0
package/src/__tests__/upgrade.test.ts +78 -1
package/src/__tests__/users.test.ts +68 -0
package/src/__tests__/vault-auth-status.test.ts +312 -11
package/src/__tests__/vault-hub-origin-env.test.ts +263 -0
package/src/__tests__/wizard.test.ts +372 -0
package/src/account-home-ui.ts +488 -38
package/src/account-vault-token.ts +282 -0
package/src/admin-handlers.ts +159 -4
package/src/admin-login-ui.ts +49 -5
package/src/admin-vaults.ts +48 -15
package/src/api-account.ts +14 -0
package/src/api-mint-token.ts +132 -24
package/src/api-modules-ops.ts +49 -11
package/src/api-modules.ts +29 -12
package/src/api-ready.ts +102 -0
package/src/api-revoke-token.ts +107 -21
package/src/api-users.ts +29 -3
package/src/cli.ts +112 -25
package/src/clients.ts +18 -6
package/src/cloudflare/config.ts +10 -4
package/src/cloudflare/detect.ts +82 -20
package/src/commands/auth.ts +165 -24
package/src/commands/expose-2fa-warning.ts +34 -32
package/src/commands/expose-auth-preflight.ts +89 -78
package/src/commands/expose-cloudflare.ts +471 -16
package/src/commands/expose-interactive.ts +10 -11
package/src/commands/expose-public-auto.ts +6 -4
package/src/commands/expose.ts +8 -0
package/src/commands/init.ts +594 -0
package/src/commands/install.ts +33 -2
package/src/commands/lifecycle.ts +386 -17
package/src/commands/migrate.ts +293 -41
package/src/commands/status.ts +22 -0
package/src/commands/upgrade.ts +55 -11
package/src/commands/wizard.ts +847 -0
package/src/env-file.ts +10 -0
package/src/help.ts +157 -15
package/src/hub-db.ts +39 -1
package/src/hub-server.ts +119 -13
package/src/hub-settings.ts +11 -0
package/src/hub.ts +82 -14
package/src/oauth-handlers.ts +298 -21
package/src/oauth-ui.ts +10 -0
package/src/operator-token.ts +151 -0
package/src/pending-login.ts +116 -0
package/src/proxy-error-ui.ts +506 -0
package/src/proxy-state.ts +131 -0
package/src/rate-limit.ts +51 -0
package/src/resource-binding.ts +134 -0
package/src/scope-attenuation.ts +85 -0
package/src/scope-explanations.ts +131 -14
package/src/services-manifest.ts +112 -0
package/src/setup-wizard.ts +738 -125
package/src/tailscale/run.ts +28 -11
package/src/totp.ts +201 -0
package/src/two-factor-handlers.ts +287 -0
package/src/two-factor-store.ts +181 -0
package/src/two-factor-ui.ts +462 -0
package/src/users.ts +58 -0
package/src/vault/auth-status.ts +200 -25
package/src/vault-hub-origin-env.ts +163 -0
package/web/ui/dist/assets/index-BiBlvEaj.css +1 -0
package/web/ui/dist/assets/index-CIN3mnmf.js +61 -0
package/web/ui/dist/index.html +2 -2
package/src/__tests__/vault-tokens-create-interactive.test.ts +0 -183
package/src/commands/vault-tokens-create-interactive.ts +0 -143
package/web/ui/dist/assets/index-7DtAXz7y.css +0 -1
package/web/ui/dist/assets/index-tRmPbbC7.js +0 -61

package/src/hub.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { brandMarkSvg, CANONICAL_TAGLINE, WORDMARK_TEXT } from "./brand.ts";
+import { CANONICAL_TAGLINE, WORDMARK_TEXT, brandMarkSvg } from "./brand.ts";
 import { CONFIG_DIR } from "./config.ts";
 import { CSRF_FIELD_NAME } from "./csrf.ts";
@@ -84,15 +84,34 @@ function buildHtml({ session }: RenderHubOpts): string {
   const authBlock = session
     ? renderSignedIn(session.displayName, session.csrfToken)
     : renderSignedOut();
-  return HTML_TEMPLATE.replace("<!--AUTH-INDICATOR-->", authBlock);
+  // Gate the verbose discovery sections (Get started / Services / Admin)
+  // and their data-loading script on auth state. A signed-out visitor sees
+  // a clean, minimal landing — brand + tagline + a clear "Sign in" call —
+  // not the hub's service catalog, vault listings, or admin links. The
+  // detail un-gates the moment they sign in (the server already knows auth
+  // state from the session cookie, so this stays a no-JS-required,
+  // session-aware render). Operator feedback from a live multi-user deploy:
+  // the signed-out page exposed too much to anonymous visitors.
+  const body = session ? SIGNED_IN_BODY : SIGNED_OUT_BODY;
+  const script = session ? DISCOVERY_SCRIPT : "";
+  return HTML_TEMPLATE.replace("<!--AUTH-INDICATOR-->", authBlock)
+    .replace("<!--DISCOVERY-BODY-->", body)
+    .replace("<!--DISCOVERY-SCRIPT-->", script);
 }
 function renderSignedIn(displayName: string, csrfToken: string): string {
   // Inline POST form so sign-out works without JS. Submit button is
   // styled as a text link via `.auth-signout` so the visual weight
   // matches the surrounding "Signed in as <name>" text.
+  //
+  // The "Account" link is the single breadcrumb to `/account/` — the
+  // self-service home where any signed-in user (admin or invited
+  // member) can change their password, see their vault, and sign out.
+  // Without it, a friend who's been handed credentials has no way to
+  // discover the change-password surface after the first-login prompt.
   return `<div class="auth-indicator">
       <span class="muted">Signed in as <strong>${escapeHtml(displayName)}</strong></span>
+      <a href="/account/" class="auth-account">Account</a>
       <form method="POST" action="/logout" class="auth-signout-form">
         <input type="hidden" name="${CSRF_FIELD_NAME}" value="${escapeAttr(csrfToken)}" />
         <button type="submit" class="auth-signout">Sign out</button>
@@ -203,7 +222,7 @@ const HTML_TEMPLATE = `<!doctype html>
     margin: 0;
     display: inline;
   }
-  .auth-signout, .auth-signin {
+  .auth-signout, .auth-signin, .auth-account {
     background: none;
     border: none;
     padding: 0;
@@ -214,10 +233,10 @@ const HTML_TEMPLATE = `<!doctype html>
     text-decoration-thickness: 1px;
     text-underline-offset: 2px;
   }
-  .auth-signout:hover, .auth-signin:hover {
+  .auth-signout:hover, .auth-signin:hover, .auth-account:hover {
     color: var(--accent-hover);
   }
-  a.auth-signin {
+  a.auth-signin, a.auth-account {
     /* Anchor needs explicit reset since the a element has its own
        color/decoration. */
     border-bottom: none;
@@ -262,6 +281,34 @@ const HTML_TEMPLATE = `<!doctype html>
     font-size: 0.92rem;
     margin: 0 0 1.25rem;
   }
+  /* Signed-out landing: a single centered "Sign in" call under the brand.
+     Minimal by design — the service catalog + admin surfaces stay hidden
+     until the visitor authenticates. */
+  .signed-out-cta {
+    text-align: center;
+    margin-bottom: 0;
+  }
+  .signed-out-lede {
+    color: var(--fg-muted);
+    font-size: 1.05rem;
+    margin: 0 0 1.5rem;
+  }
+  .btn-signin {
+    display: inline-block;
+    background: var(--accent);
+    color: var(--card-bg);
+    font-family: var(--sans);
+    font-size: 1rem;
+    font-weight: 500;
+    text-decoration: none;
+    padding: 0.65rem 1.6rem;
+    border-radius: 8px;
+    transition: background 0.15s ease, transform 0.15s ease;
+  }
+  .btn-signin:hover {
+    background: var(--accent-hover);
+    transform: translateY(-1px);
+  }
   .grid {
     display: grid;
     gap: 1.25rem;
@@ -371,7 +418,22 @@ const HTML_TEMPLATE = `<!doctype html>
     <h1>${WORDMARK_TEXT}</h1>
     <p class="tagline">${CANONICAL_TAGLINE}</p>
   </header>
+<!--DISCOVERY-BODY-->
+  <footer>
+    <a href="/.well-known/parachute.json">discovery</a>
+  </footer>
+</main>
+<!--DISCOVERY-SCRIPT-->
+</body>
+</html>
+`;
+// The verbose discovery body — the service catalog, admin surfaces, and the
+// "Get started" CTA. Rendered ONLY for a signed-in visitor (`buildHtml`
+// selects this vs SIGNED_OUT_BODY on `session`). Anonymous visitors get the
+// slim landing below instead, so the hub's internal surface isn't exposed
+// pre-auth.
+const SIGNED_IN_BODY = `
   <section class="section" id="get-started-section" hidden>
     <h2>Get started</h2>
     <p class="section-sub">Jump straight into what you came here for.</p>
@@ -391,12 +453,21 @@ const HTML_TEMPLATE = `<!doctype html>
     <p class="section-sub">Manage this hub — vaults, permissions, tokens.</p>
     <div class="grid" id="admin-grid"></div>
   </section>
+`;
-  <footer>
-    <a href="/.well-known/parachute.json">discovery</a>
-  </footer>
-</main>
-<script>
+// The slim signed-out landing. Brand + tagline (in the header above) plus a
+// single clear "Sign in" call — no service catalog, no vault listings, no
+// admin links. Keep it tasteful and minimal; the detail un-gates on sign-in.
+const SIGNED_OUT_BODY = `
+  <section class="section signed-out-cta" id="signed-out-cta">
+    <p class="signed-out-lede">Sign in to reach your vault and the services on this hub.</p>
+    <a href="/login?next=/" class="btn-signin" data-testid="signed-out-signin">Sign in →</a>
+  </section>
+`;
+// The data-loading script for the signed-in discovery body. Emitted only
+// when signed in (the signed-out body has nothing for it to populate).
+const DISCOVERY_SCRIPT = `<script>
 (async () => {
   const servicesGrid = document.getElementById('services-grid');
   const adminGrid = document.getElementById('admin-grid');
@@ -607,7 +678,4 @@ const HTML_TEMPLATE = `<!doctype html>
   void loadServices();
 })();
-</script>
-</body>
-</html>
-`;
+</script>`;

package/src/oauth-handlers.ts CHANGED Viewed

@@ -23,6 +23,7 @@
  */
 import type { Database } from "bun:sqlite";
 import { AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
+import { renderTotpChallenge } from "./admin-login-ui.ts";
 import {
   AuthCodeExpiredError,
   AuthCodeNotFoundError,
@@ -65,7 +66,9 @@ import {
   renderUnknownClient,
 } from "./oauth-ui.ts";
 import { isSameOriginRequest } from "./origin-check.ts";
+import { buildPendingLoginCookie, createPendingLogin } from "./pending-login.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
+import { narrowResourceVaultScopes, resolveResourceVault } from "./resource-binding.ts";
 import { isNonRequestableScope, isRequestableScope, scopeIsAdmin } from "./scope-explanations.ts";
 import { findUnknownScopes, loadDeclaredScopes } from "./scope-registry.ts";
 import {
@@ -83,7 +86,14 @@ import {
   findSession,
   parseSessionCookie,
 } from "./sessions.ts";
-import { getUserById, getUserByUsername, isFirstAdmin, verifyPassword } from "./users.ts";
+import { isTotpEnrolled } from "./two-factor-store.ts";
+import {
+  getUserById,
+  getUserByUsername,
+  isFirstAdmin,
+  vaultVerbsForUserVault,
+  verifyPassword,
+} from "./users.ts";
 import { listVaultNames } from "./vault-names.ts";
 import { isVaultEntry, shortName, vaultInstanceNameFor } from "./well-known.ts";
@@ -460,6 +470,9 @@ function parseAuthorizeFormParams(url: URL): AuthorizeFormParams | { error: stri
     codeChallenge,
     codeChallengeMethod,
     state: url.searchParams.get("state"),
+    // RFC 8707 resource indicator (optional). When present and resolvable to
+    // a per-vault MCP resource, drives the narrow-consent + named-scope path.
+    resource: url.searchParams.get("resource"),
   };
 }
@@ -821,7 +834,7 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
       parsed.state,
     );
   }
-  const client = getClient(db, parsed.clientId);
+  let client = getClient(db, parsed.clientId);
   if (!client) {
     // Can't safely redirect — we don't trust the redirect_uri until we've
     // matched it against a registered client. Render an HTML error that
@@ -832,7 +845,71 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     return unknownClientResponse(parsed.clientId, parsed.redirectUri, deps);
   }
   if (client.status !== "approved") {
-    return pendingClientResponse(db, req, client, url, deps);
+    // Single-consent change (2026-05-29): the separate operator "approve this
+    // client" gate is retired — the user's OAuth consent IS the authorization.
+    // A request carrying a valid session auto-approves the pending client and
+    // FALLS THROUGH into the normal consent path below (resource-narrow →
+    // non-requestable gate → skip-consent / same-hub → consent render). A
+    // session-less request still renders the unauth "App not yet approved"
+    // page (`pendingClientResponse`), whose sign-in CTA (`loginNextUrl`)
+    // round-trips back to this authorize URL; after login the user re-enters
+    // WITH a session → hits this auto-approve branch → consent.
+    //
+    // We resolve the session via the same `parseSessionCookie` + `findSession`
+    // pair the consent path uses below (not `findActiveSession`) so the
+    // auto-approve predicate and the consent render agree on session identity.
+    const earlySessionId = parseSessionCookie(req.headers.get("cookie"));
+    const earlySession = earlySessionId ? findSession(db, earlySessionId) : null;
+    if (!earlySession) {
+      return pendingClientResponse(db, req, client, url, deps);
+    }
+    console.log(
+      `[oauth] auto-approved client on user consent (single-consent) client_id=${client.clientId} user_id=${earlySession.userId} (2026-05-29)`,
+    );
+    approveClient(db, client.clientId);
+    // Trust-by-client_name carry-over (hub#409, preserved through the
+    // single-consent change). Notes/Claude DCR a fresh client_id per session;
+    // when the user has a prior grant under the SAME client_name that covers
+    // the requested scopes, re-link must stay SILENT. The skip-consent gate
+    // below keys on (user, client_id) and the fresh client_id has no grant
+    // yet — so we re-record that prior coverage onto the fresh client_id here.
+    // The mint downstream goes through `issueAuthCodeRedirect`, which caps to
+    // held authority, so this carry-over can never silently re-grant an
+    // un-held verb. Guarded identically to the in-`pendingClientResponse`
+    // block: same-origin + non-empty client_name + non-admin requested scopes
+    // (`scopeIsAdmin` recognizes the named admin form now — load-bearing) +
+    // prior-grant coverage. When it doesn't apply, fall through to the consent
+    // render (the single-consent payoff: one consent screen, then silent).
+    const earlyRequested = parsed.scope.split(" ").filter((s) => s.length > 0);
+    if (
+      isSameOriginRequest(req, resolveBoundOrigins(deps)) &&
+      client.clientName &&
+      earlyRequested.length > 0 &&
+      !earlyRequested.some(scopeIsAdmin) &&
+      isCoveredByGrantForClientName(db, earlySession.userId, client.clientName, earlyRequested)
+    ) {
+      console.log(
+        `[oauth] carried prior client_name trust onto fresh client_id=${client.clientId} client_name=${JSON.stringify(client.clientName)} user_id=${earlySession.userId} scopes=${earlyRequested.join(" ")} (hub#409)`,
+      );
+      recordGrant(
+        db,
+        earlySession.userId,
+        client.clientId,
+        earlyRequested,
+        deps.now?.() ?? new Date(),
+      );
+    }
+    // Re-fetch so `client.status` reflects `approved` for the rest of this
+    // function (the same-hub gate and consent props read `client`). Fall
+    // through on success; if the refresh somehow failed, render the unauth
+    // pending page defensively (should never happen given approveClient).
+    const refreshed = getClient(db, client.clientId);
+    if (!refreshed || refreshed.status !== "approved") {
+      return pendingClientResponse(db, req, client, url, deps);
+    }
+    client = refreshed;
   }
   try {
     requireRegisteredRedirectUri(client, parsed.redirectUri);
@@ -844,6 +921,41 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     );
   }
+  // RFC 8707 resource binding. When the client named a per-vault MCP
+  // resource (`<origin>/vault/<name>/mcp` or its PRM URL), narrow the
+  // requested vault verbs to the named `vault:<name>:<verb>` form BEFORE any
+  // downstream processing. Two effects:
+  //
+  //   1. The consent screen shows ONLY that vault's scopes (the picker locks
+  //      to <name>) instead of the whole-hub catalog — a friend connecting to
+  //      one vault no longer sees `hub:admin`, `scribe:admin`, or every other
+  //      vault's verbs.
+  //   2. The minted token carries the named scope, so `inferAudience` stamps
+  //      `aud=vault.<name>` and a current-line vault accepts it (an unnamed
+  //      `vault:read` token is rejected by `findBroadVaultScopes`).
+  //
+  // Narrowing happens before the non-requestable gate (below) on purpose: if
+  // a resource-bound client somehow asked for `vault:admin`, narrowing makes
+  // it `vault:<name>:admin`, which IS non-requestable — so the gate correctly
+  // blocks it. Read/write narrow to the requestable named form. Non-vault
+  // scopes and already-named scopes for other vaults pass through unchanged.
+  //
+  // No resource, or a resource that isn't one of our per-vault MCP resources
+  // (off-origin, malformed, non-vault path) → `boundVault` is null and the
+  // flow is byte-for-byte the pre-#461 behavior (manual picker, etc.).
+  const boundVault = resolveResourceVault(parsed.resource, resolveBoundOrigins(deps));
+  if (boundVault) {
+    const narrowed = narrowResourceVaultScopes(
+      parsed.scope.split(" ").filter((s) => s.length > 0),
+      boundVault,
+    );
+    // Rewrite `parsed.scope` so the narrowed named scopes flow through every
+    // downstream consumer: the login-redirect query round-trip, the consent
+    // props + hidden inputs, the skip-consent grant lookup, and the
+    // auth-code mint.
+    parsed.scope = narrowed.join(" ");
+  }
   // Operator-only scope gate (#96). Reject any request that names a scope
   // we'll never mint via this flow — `parachute:host:admin` and friends.
   // Per RFC 6749 §4.1.2.1, errors that aren't redirect-uri-related are
@@ -991,10 +1103,13 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     console.log(
       `[oauth] auto-approved same-hub client client_id=${client.clientId} user_id=${session.userId} scopes=${requestedScopes.join(" ")} (hub#312)`,
     );
-    // Record the grant so the next /authorize for this (user, client, scopes)
-    // hits the standard skip-consent path (#75) — keeps the audit story
-    // consistent between same-hub and externally-approved flows.
-    recordGrant(db, session.userId, client.clientId, requestedScopes);
+    // The grant is recorded INSIDE issueAuthCodeRedirect with the CAPPED
+    // scopes (single choke-point, single source of truth) so the next
+    // /authorize for this (user, client, scopes) hits the standard
+    // skip-consent path (#75) — and can never replay an un-held verb. The
+    // `!hasAdminScope` guard above already keeps admin scopes off this path
+    // (they fall through to consent), so the cap is a no-op here for the
+    // common case, but it still runs unconditionally for defense in depth.
     return issueAuthCodeRedirect(db, parsed, requestedScopes, session.userId, deps);
   }
@@ -1008,10 +1123,89 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
 }
 /**
- * Mint an auth code and redirect to the client's redirect_uri. Shared by
- * the consent-submit path (`handleConsentSubmit`) and the skip-consent path
- * in `handleAuthorizeGet` (#75). Caller is responsible for having already
- * validated the client + redirect_uri + scopes.
+ * Anti-privilege-escalation cap (THE security crux of the single-consent
+ * change, 2026-05-29). A user may only delegate authority they themselves
+ * hold: the OAuth consent that authorizes a client must never grant a named
+ * vault verb the consenting user doesn't actually hold on that vault.
+ *
+ * For each scope shaped `vault:<name>:<verb>` (verb ∈ VAULT_VERBS) when the
+ * user is NOT the hub owner, the verb is admitted only if it appears in
+ * `vaultVerbsForUserVault(db, userId, name)` (the verbs the user holds on
+ * that vault, derived from their `user_vaults` role). Otherwise the scope is
+ * DROPPED. Non-vault scopes and unnamed `vault:<verb>` (which never reach
+ * mint without picker-narrowing) pass through untouched.
+ *
+ * The owner (`isFirstAdmin`) bypasses the cap entirely — they hold admin on
+ * every vault by construction (admin posture is the unrestricted sentinel;
+ * see `vaultScopeForUser`). Owner=isFirstAdmin is the Phase-1 definition of
+ * "holds admin everywhere"; revisit when multi-admin lands.
+ *
+ * Security argument (documented at the call site too):
+ *   - The authority source of truth today is `isFirstAdmin` for owner-wide
+ *     authority and `user_vaults.role` (via `vaultVerbsForRole`) for assigned
+ *     users.
+ *   - `vaultVerbsForRole` provably never returns `admin` for an assigned user
+ *     (it maps write→[read,write], read→[read], unknown→[]), so this helper
+ *     drops `vault:<name>:admin` for every non-owner BY CONSTRUCTION — without
+ *     hardcoding "drop admin". It reads the held verb set and admits only
+ *     held verbs, so it's forward-compatible: if a future role ever granted
+ *     admin, the cap would admit it automatically.
+ *   - Applied inside `issueAuthCodeRedirect` (the single choke-point ALL mint
+ *     paths funnel through: consent-submit, skip-consent, and same-hub
+ *     auto-trust), the CAPPED set is what gets both recorded (`recordGrant`)
+ *     and minted (`issueAuthCode`). No mint path can bypass it, and a later
+ *     skip-consent flow can never replay an un-held admin verb because it was
+ *     never recorded.
+ */
+function capScopesToUserAuthority(
+  db: Database,
+  userId: string,
+  scopes: readonly string[],
+  opts: { userIsAdmin: boolean },
+): string[] {
+  if (opts.userIsAdmin) return [...scopes];
+  return scopes.filter((s) => {
+    const parts = s.split(":");
+    if (parts.length !== 3 || parts[0] !== "vault") return true; // non-named — pass through
+    const name = parts[1];
+    const verb = parts[2];
+    if (name === undefined || verb === undefined || !VAULT_VERBS.has(verb)) return true;
+    // Named vault verb requested by a non-owner: admit only if the user holds
+    // it. `vaultVerbsForUserVault` returns null for an unassigned vault (drop)
+    // or the held verb list (today read/write only — never admin).
+    const held = vaultVerbsForUserVault(db, userId, name);
+    return held !== null && (held as readonly string[]).includes(verb);
+  });
+}
+/**
+ * Mint an auth code and redirect to the client's redirect_uri. The SINGLE
+ * mint choke-point — shared by the consent-submit path (`handleConsentSubmit`),
+ * the skip-consent path (#75), and the same-hub auto-trust path (hub#312) in
+ * `handleAuthorizeGet`. Caller is responsible for having already validated the
+ * client + redirect_uri and for having narrowed unnamed `vault:<verb>` scopes
+ * to their named form (so the cap below sees final shapes).
+ *
+ * This is the single choke-point for two responsibilities, so NO mint path can
+ * bypass them:
+ *   1. Anti-privilege-escalation cap (`capScopesToUserAuthority`): a non-owner
+ *      can only delegate vault verbs they hold; un-held verbs (notably admin)
+ *      are dropped. An admin-only request from a non-owner caps to EMPTY → we
+ *      refuse with `invalid_scope` rather than mint a zero-scope token. EVERY
+ *      auth code is minted through here, so the cap runs before every mint —
+ *      even when a stale `grants` row already lists an un-held admin verb (the
+ *      cap, not the grant lookup, is what blocks the mint).
+ *   2. Grant recording (`recordGrant`) with the CAPPED scopes for THIS mint —
+ *      so a later skip-consent flow re-entering with the same (user, client)
+ *      can never replay an un-held verb. UNION semantics make this idempotent.
+ *
+ * Not the ONLY `recordGrant` call in this module, though: two other guarded
+ * fast-path records exist — the trust-by-client_name auto-promote in
+ * `pendingClientResponse` (~L585) and the auto-approve carry-over in
+ * `handleAuthorizeGet` (~L895). Both are gated by `!some(scopeIsAdmin)`, so
+ * neither can ever record an admin verb, and any mint they unlock still flows
+ * back through this function's cap. So the invariant "no minted token, and no
+ * grant row, ever carries an un-held admin verb" holds across all paths.
  */
 function issueAuthCodeRedirect(
   db: Database,
@@ -1020,11 +1214,37 @@ function issueAuthCodeRedirect(
   userId: string,
   deps: OAuthDeps,
 ): Response {
+  // Anti-privesc cap at the single choke-point. Runs AFTER any narrowing the
+  // callers did (unnamed `vault:admin` → `vault:<picked>:admin`), so it sees
+  // the final named shapes. Owner (isFirstAdmin) bypasses — holds admin
+  // everywhere by construction.
+  const userIsAdmin = isFirstAdmin(db, userId);
+  const cappedScopes = capScopesToUserAuthority(db, userId, scopes, { userIsAdmin });
+  // Drop-not-refuse UX, with one hard floor: if capping leaves an EMPTY set
+  // (e.g. a non-owner requested ONLY `vault:<name>:admin`, which they don't
+  // hold), never mint a zero-scope token — refuse with a clear invalid_scope.
+  // A request that started empty (no scopes at all) is a separate, legitimate
+  // "session token only" case the consent UI supports, so we only refuse when
+  // the cap itself removed every scope.
+  if (cappedScopes.length === 0 && scopes.length > 0) {
+    return oauthErrorRedirect(
+      params.redirectUri,
+      "invalid_scope",
+      "You can grant only the access you hold on this vault; an admin grant requires hub-owner authority.",
+      params.state,
+    );
+  }
+  // Record the grant with the CAPPED scopes (single source of truth) so
+  // skip-consent re-entry can never widen back to an un-held verb.
+  recordGrant(db, userId, params.clientId, cappedScopes, deps.now?.() ?? new Date());
   const code = issueAuthCode(db, {
     clientId: params.clientId,
     userId,
     redirectUri: params.redirectUri,
-    scopes,
+    scopes: cappedScopes,
     codeChallenge: params.codeChallenge,
     codeChallengeMethod: params.codeChallengeMethod,
     now: deps.now,
@@ -1100,17 +1320,49 @@ async function handleLoginSubmit(
       401,
     );
   }
+  // Where to land after a successful sign-in: back at GET /oauth/authorize
+  // with the original query string so the user resumes the OAuth flow on the
+  // consent screen with full params re-validated.
+  const authorizeReturnUrl = buildAuthorizeReturnUrl(params);
+  // 2FA gate (hub#473 — security fix). The OAuth login POST is the MORE-common
+  // sign-in path (every OAuth client: vault, notes-ui, `parachute auth login`).
+  // It must enforce the second factor exactly like `/login` does: after the
+  // password verifies, if the user has TOTP enrolled, do NOT mint a session.
+  // Stash a pending-login whose `next` is the FULL /oauth/authorize return URL
+  // (so the post-TOTP redirect resumes the OAuth flow), and render the TOTP
+  // challenge. The challenge form posts to `/login/2fa` — the shared
+  // completion path (`handleAdminLoginTotpPost`) — which verifies the factor,
+  // mints the session, and 302s to the stored `next`. The pending-login cookie
+  // is scoped `Path=/login`, so it rides the `/login/2fa` POST. Without this
+  // gate a 2FA-enrolled user could obtain a full session with password ONLY.
+  if (isTotpEnrolled(db, user.id)) {
+    const pendingToken = createPendingLogin(user.id, authorizeReturnUrl);
+    return htmlResponse(renderTotpChallenge({ next: authorizeReturnUrl, csrfToken }), 200, {
+      "set-cookie": buildPendingLoginCookie(pendingToken, req),
+    });
+  }
   const session = createSession(db, { userId: user.id });
   const cookie = buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000), {
     secure: isHttpsRequest(req),
   });
-  // Redirect back to GET /oauth/authorize with the original query string so
-  // the user lands on the consent screen with full params re-validated.
+  return redirectResponse(authorizeReturnUrl, { "set-cookie": cookie });
+}
+/**
+ * Build the `/oauth/authorize?...` return URL (path + query, same-origin) that
+ * a successful sign-in redirects back to so the OAuth flow resumes on the
+ * consent screen. Shared by the password-only path and the post-TOTP path
+ * (the latter via the pending-login's `next`).
+ */
+function buildAuthorizeReturnUrl(params: AuthorizeFormParams): string {
   const u = new URL("/oauth/authorize", "http://placeholder");
   for (const [k, v] of Object.entries(authorizeParamsToQuery(params))) {
     u.searchParams.set(k, v);
   }
-  return redirectResponse(`${u.pathname}${u.search}`, { "set-cookie": cookie });
+  return `${u.pathname}${u.search}`;
 }
 async function handleConsentSubmit(
@@ -1121,6 +1373,21 @@ async function handleConsentSubmit(
   csrfToken: string,
 ): Promise<Response> {
   const params = paramsFromForm(form);
+  // RFC 8707 resource binding — defense-in-depth (mirror of the GET handler).
+  // The consent form's hidden inputs already carry the narrowed named scopes
+  // (the GET handler rewrote `parsed.scope` before rendering), but a hand-
+  // crafted POST could re-supply an unnamed `vault:read` alongside the
+  // `resource` field. Re-narrow here so the minted token is always named +
+  // correctly-audienced regardless of what the form body claims. Same
+  // semantics as the GET path: only when `resource` resolves to one of our
+  // per-vault MCP resources; no-op otherwise (manual-pick path unchanged).
+  const boundVault = resolveResourceVault(params.resource, resolveBoundOrigins(deps));
+  if (boundVault) {
+    params.scope = narrowResourceVaultScopes(
+      params.scope.split(" ").filter((s) => s.length > 0),
+      boundVault,
+    ).join(" ");
+  }
   const approve = String(form.get("approve") ?? "") === "yes";
   const sessionId = parseSessionCookie(req.headers.get("cookie"));
   const session = sessionId ? findSession(db, sessionId) : null;
@@ -1201,6 +1468,11 @@ async function handleConsentSubmit(
   const sessionUser = getUserById(db, session.userId);
   const assignedVaults: string[] = userIsAdmin ? [] : (sessionUser?.assignedVaults ?? []);
   const isPinned = assignedVaults.length > 0;
+  // By design: the resource-bound re-narrow above does NOT check the bound
+  // vault exists in services.json for the admin path — admin (isPinned=false)
+  // can already consent to any vault via the manual picker, so the asymmetry
+  // (named-scope mint against a possibly-missing vault) is deliberate, not an
+  // oversight. Non-admins still hit the assignment + stale-vault defenses below.
   // Zero-vault non-admin gate (Phase 2 PR 2 reviewer fold). A non-admin
   // user with no `user_vaults` rows is a known-but-not-yet-assigned
@@ -1362,12 +1634,12 @@ async function handleConsentSubmit(
     }
   }
-  // Record (or extend) the grant so the next /oauth/authorize for this
-  // (user, client) with these scopes — or any subset — can skip the consent
-  // screen (#75). UNION semantics: if the user previously granted [a, b, c]
-  // and now grants [a, d], the row becomes [a, b, c, d]. Subset re-flows
-  // still match.
-  recordGrant(db, session.userId, client.clientId, scopes, deps.now?.() ?? new Date());
+  // The grant is recorded (or extended) INSIDE issueAuthCodeRedirect with the
+  // CAPPED scopes — the single mint choke-point owns both the anti-privesc cap
+  // and the recordGrant so no path can record an un-held verb. UNION semantics
+  // there mean a subset re-flow still matches a prior grant, and an admin-only
+  // request from a non-owner caps to empty → refused (no zero-scope token).
+  // (#75 skip-consent depends on this recording.)
   return issueAuthCodeRedirect(db, params, scopes, session.userId, deps);
 }
@@ -1554,6 +1826,7 @@ function paramsFromForm(form: Awaited<ReturnType<Request["formData"]>>): Authori
     codeChallenge: String(form.get("code_challenge") ?? ""),
     codeChallengeMethod: String(form.get("code_challenge_method") ?? "S256"),
     state: (form.get("state") as string | null) ?? null,
+    resource: (form.get("resource") as string | null) ?? null,
   };
 }
@@ -1567,6 +1840,10 @@ function authorizeParamsToQuery(p: AuthorizeFormParams): Record<string, string>
     code_challenge_method: p.codeChallengeMethod,
   };
   if (p.state) q.state = p.state;
+  // Round-trip the RFC 8707 resource indicator through the login redirect so
+  // the resource-bound narrowing survives a sign-in (it re-enters GET
+  // /oauth/authorize with the original params).
+  if (p.resource) q.resource = p.resource;
   return q;
 }

package/src/oauth-ui.ts CHANGED Viewed

@@ -62,6 +62,12 @@ export interface AuthorizeFormParams {
   codeChallenge: string;
   codeChallengeMethod: string;
   state: string | null;
+  /**
+   * RFC 8707 resource indicator. Carried through the login → consent →
+   * form-post round-trip so the resource-bound vault narrowing survives a
+   * sign-in redirect. Null when the client sent no `resource` param.
+   */
+  resource: string | null;
 }
 export interface LoginViewProps {
@@ -932,6 +938,10 @@ export function renderHiddenInputs(p: AuthorizeFormParams): string {
     ["code_challenge_method", p.codeChallengeMethod],
   ];
   if (p.state) fields.push(["state", p.state]);
+  // RFC 8707 resource indicator — round-tripped through the consent form so
+  // the resource-bound vault narrowing survives the POST (the consent submit
+  // path re-derives the bound vault from it).
+  if (p.resource) fields.push(["resource", p.resource]);
   return fields
     .map(([k, v]) => `<input type="hidden" name="${k}" value="${escapeHtml(v)}" />`)
     .join("\n        ");