@openparachute/hub 0.5.2 → 0.5.9-rc.6

package/src/oauth-handlers.ts

@@ -8,6 +8,7 @@
  *   - GET  /.well-known/oauth-authorization-server  (RFC 8414 metadata)
  *   - GET  /oauth/authorize                          (login → consent → code)
  *   - POST /oauth/authorize                          (form posts: login + consent)
+ *   - POST /oauth/authorize/approve                  (operator-driven inline DCR approval, #208)
  *   - POST /oauth/token                              (grant_type=authorization_code | refresh_token)
  *   - POST /oauth/register                           (RFC 7591 DCR)
  *   - POST /oauth/revoke                             (RFC 7009 token revocation)
@@ -35,6 +36,7 @@ import {
   type ClientStatus,
   type OAuthClient,
   type RegisteredClient,
+  approveClient,
   getClient,
   isValidRedirectUri,
   registerClient,
@@ -53,7 +55,14 @@ import {
   signAccessToken,
   signRefreshToken,
 } from "./jwt-sign.ts";
-import { type AuthorizeFormParams, renderConsent, renderError, renderLogin } from "./oauth-ui.ts";
+import {
+  type AuthorizeFormParams,
+  renderApprovePending,
+  renderConsent,
+  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 {
@@ -64,6 +73,7 @@ import {
   SESSION_TTL_MS,
   buildSessionCookie,
   createSession,
+  findActiveSession,
   findSession,
   parseSessionCookie,
 } from "./sessions.ts";
@@ -134,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 {
@@ -149,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;
@@ -291,21 +401,100 @@ function parseAuthorizeFormParams(url: URL): AuthorizeFormParams | { error: stri
   };
 }
 
-/** HTML response for pending clients hitting /oauth/authorize. */
-function pendingClientHtml(): Response {
-  return htmlError(
-    "App not yet approved",
-    "This client_id is registered but has not been approved by the hub operator. Ask the operator to run `parachute auth approve-client` for this app, then try again.",
+/**
+ * "App not yet approved" page (#74) for /oauth/authorize. When the request
+ * carries a valid operator session AND a same-origin Origin/Referer, render
+ * the inline approve form (#208) so one click flips the client to `approved`
+ * and the OAuth flow re-enters at consent. Otherwise fall back to the
+ * pre-#208 CLI-only message ("ask operator to run `parachute auth
+ * approve-client <id>`").
+ *
+ * The session-bound approve gate mirrors the same-origin DCR auto-approve
+ * gate on `/oauth/register` (#199, #200): valid session cookie + matching
+ * Origin/Referer = trusted operator action. Cross-origin or session-less
+ * GETs see the CLI-fallback message; the button never renders for them, so
+ * the POST handler can't be tricked into approving via a hand-crafted form
+ * either (CSRF token won't match).
+ *
+ * The form's `return_to` carries the original `/oauth/authorize?...` URL so
+ * the post-approve redirect lands the operator back on the same flow with
+ * the now-approved client. The POST handler validates `return_to` is a
+ * hub-relative path before following it (open-redirect defense).
+ */
+function pendingClientResponse(
+  db: Database,
+  req: Request,
+  client: OAuthClient,
+  authorizeUrl: URL,
+  deps: OAuthDeps,
+): Response {
+  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 = isSameOriginRequest(req, resolveBoundOrigins(deps));
+  const csrf = ensureCsrfToken(req);
+  const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  if (session && sameOrigin) {
+    const returnTo = `${authorizeUrl.pathname}${authorizeUrl.search}`;
+    return htmlResponse(
+      renderApprovePending({
+        clientName: client.clientName ?? client.clientId,
+        clientId: client.clientId,
+        redirectUris: client.redirectUris,
+        requestedScopes,
+        ...(requestedVault !== undefined && { requestedVault }),
+        approveForm: { csrfToken: csrf.token, returnTo },
+      }),
+      403,
+      extra,
+    );
+  }
+  return htmlResponse(
+    renderApprovePending({
+      clientName: client.clientName ?? client.clientId,
+      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,
   );
@@ -345,7 +534,9 @@ export function handleAuthorizeGet(db: Database, req: Request, deps: OAuthDeps):
     // matched it against a registered client. Render an HTML error.
     return htmlError("Unknown application", "This client_id is not registered with this hub.", 400);
   }
-  if (client.status !== "approved") return pendingClientHtml();
+  if (client.status !== "approved") {
+    return pendingClientResponse(db, req, client, url, deps);
+  }
   try {
     requireRegisteredRedirectUri(client, parsed.redirectUri);
   } catch {
@@ -536,7 +727,18 @@ async function handleConsentSubmit(
   if (!client) {
     return htmlError("Unknown application", "This client_id is not registered with this hub.", 400);
   }
-  if (client.status !== "approved") return pendingClientHtml();
+  if (client.status !== "approved") {
+    // Defensive: consent only renders for approved clients, so a non-approved
+    // status here means the row was unapproved between render and submit (or
+    // the form was hand-crafted). The approve UI requires a known authorize
+    // URL to round-trip via `return_to`, which we don't reconstruct here —
+    // surface the static error and let the operator restart from the SPA.
+    return htmlError(
+      "App not yet approved",
+      `This client_id is registered but has not been approved. Run \`parachute auth approve-client ${client.clientId}\` from a terminal, then try again.`,
+      403,
+    );
+  }
   try {
     requireRegisteredRedirectUri(client, params.redirectUri);
   } catch {
@@ -602,6 +804,107 @@ async function handleConsentSubmit(
   return issueAuthCodeRedirect(db, params, scopes, session.userId, deps);
 }
 
+/**
+ * POST /oauth/authorize/approve — operator-driven inline approval of a
+ * pending DCR client (closes #208). The cross-origin SPA case the
+ * same-origin DCR auto-approve (#199, #200) doesn't cover: an SPA on a
+ * different origin can't ride the cookie path during DCR, so its
+ * freshly-registered client_id lands `pending` and the operator hits
+ * "App not yet approved" on /oauth/authorize. This endpoint flips that
+ * client to `approved` in one click and redirects back into the OAuth flow.
+ *
+ * Three-belt security model. All three must pass:
+ *
+ *   1. Valid CSRF token (double-submit cookie). Defends against a malicious
+ *      cross-origin POST that rides the session cookie's SameSite=Lax.
+ *      Token was minted at GET render time and embedded in the form.
+ *   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 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`
+ * with the now-approved client. We refuse anything that doesn't start with
+ * `/oauth/authorize?` — open-redirect defense, plus a hand-crafted form
+ * trying to use this endpoint as a generic redirect-after-approve gadget
+ * shouldn't succeed at smuggling an off-path target.
+ */
+export async function handleApproveClientPost(
+  db: Database,
+  req: Request,
+  deps: OAuthDeps,
+): Promise<Response> {
+  const form = await req.formData();
+  const formCsrf = form.get(CSRF_FIELD_NAME);
+  if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
+    return htmlError(
+      "Invalid form submission",
+      "The form's CSRF token did not match. Reload the page and try again.",
+      403,
+    );
+  }
+  const session = findActiveSession(db, req, deps.now ?? (() => new Date()));
+  if (!session) {
+    return htmlError(
+      "Sign in required",
+      "You must be signed in to this hub to approve an app. Sign in and try again.",
+      401,
+    );
+  }
+  if (!isSameOriginRequest(req, resolveBoundOrigins(deps))) {
+    return htmlError(
+      "Cross-origin request rejected",
+      "The approve form must be submitted from this hub's own origin.",
+      403,
+    );
+  }
+  const clientId = String(form.get("client_id") ?? "");
+  if (!clientId) {
+    return htmlError("Invalid form submission", "Missing client_id.", 400);
+  }
+  const client = getClient(db, clientId);
+  if (!client) {
+    return htmlError("Unknown application", "This client_id is not registered with this hub.", 404);
+  }
+  // Validate return_to BEFORE the DB mutation: if an authenticated operator
+  // submits a hand-crafted form with a bad return_to, we refuse without
+  // committing the client to `approved`. Practical risk is low (all three
+  // belts already passed), but ordering matters — validate, then mutate.
+  const returnTo = String(form.get("return_to") ?? "");
+  if (!isSafeAuthorizeReturnTo(returnTo)) {
+    return htmlError(
+      "Invalid form submission",
+      "The return_to value is not a hub-relative /oauth/authorize URL.",
+      400,
+    );
+  }
+  approveClient(db, clientId);
+  return redirectResponse(returnTo);
+}
+
+/**
+ * Validate a form-submitted `return_to` value. Must be a hub-relative URL
+ * (no scheme, no double-slash) targeting `/oauth/authorize` with a query
+ * string — anything else is either an open-redirect attempt or a misuse of
+ * the endpoint. Empty string is rejected (the form always supplies one).
+ */
+function isSafeAuthorizeReturnTo(value: string): boolean {
+  if (!value) return false;
+  // Reject scheme-relative ("//evil.example/foo") and absolute URLs. Only
+  // single-slash root-relative paths are allowed.
+  if (!value.startsWith("/") || value.startsWith("//")) return false;
+  // Must target the authorize endpoint with a query string. The OAuth flow
+  // re-enters via GET /oauth/authorize?<original-params>; anything off-path
+  // is a misuse.
+  return value.startsWith("/oauth/authorize?");
+}
+
 function paramsFromForm(form: Awaited<ReturnType<Request["formData"]>>): AuthorizeFormParams {
   return {
     clientId: String(form.get("client_id") ?? ""),
@@ -760,7 +1063,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>;
@@ -795,6 +1098,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,
@@ -835,7 +1145,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);
@@ -848,6 +1158,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
@@ -882,7 +1204,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,
@@ -895,7 +1217,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,
@@ -1064,20 +1386,50 @@ interface RegisterRequestBody {
   token_endpoint_auth_method?: string;
 }
 
+/**
+ * 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 resolveBoundOrigins(deps: OAuthDeps): readonly string[] {
+  if (deps.hubBoundOrigins) return deps.hubBoundOrigins();
+  return [deps.issuer];
+}
+
 /**
  * POST /oauth/register — RFC 7591 Dynamic Client Registration.
  *
  * Approval gate (closes #74). New rows land as `pending` by default and
  * cannot participate in OAuth flows until an operator runs
- * `parachute auth approve-client <id>`. The single bypass is presenting an
- * `Authorization: Bearer <operator-token>` whose token carries the
- * `hub:admin` scope — the install-time path used by first-party modules so
- * `parachute install vault` can self-register without a human follow-up.
+ * `parachute auth approve-client <id>`. Two bypass paths:
+ *
+ * 1. **Operator-bearer** (#74). `Authorization: Bearer <operator-token>` whose
+ *    token carries the `hub:admin` scope — the install-time path used by
+ *    first-party modules so `parachute install vault` can self-register
+ *    without a human follow-up.
+ * 2. **Operator-session** (#199). A valid `parachute_hub_session` cookie
+ *    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 `isSameOriginRequest` + the cookie's
+ *    `SameSite=Lax` attribute.
  *
  * If a bearer is presented but invalid or insufficient, we reject with the
  * RFC 6750 shape rather than silently downgrading to the public path: a
  * caller who tried to authenticate but failed wants to know why, not get
  * `pending` back and wonder why their module can't OAuth.
+ *
+ * Access-control matrix:
+ *   no auth                       → pending
+ *   bearer (hub:admin)            → approved (#74)
+ *   bearer (other scope)          → 403 insufficient_scope
+ *   bearer (malformed)            → 401 invalid_token
+ *   session cookie + same-origin  → approved (#199)
+ *   session cookie + cross-origin → pending (CSRF defense)
+ *   session cookie + no Origin/Referer → pending
+ *   expired/unknown session       → pending
  */
 export async function handleRegister(
   db: Database,
@@ -1124,6 +1476,20 @@ export async function handleRegister(
       throw err;
     }
   }
+  // Operator-session auto-approve (closes #199). The browser path:
+  // operator-authenticated SPA on the hub's own origin can self-register a
+  // client without dropping to a terminal. Two gates: (1) a live (un-expired)
+  // session row keyed by the cookie, (2) Origin/Referer matches the issuer
+  // origin so a cross-site forgery can't ride the cookie. Quietly stays
+  // `pending` on any failure — unlike the bearer path, we don't surface an
+  // error, because absence of session/origin is the *normal* unauthenticated
+  // public-DCR shape.
+  if (status === "pending") {
+    const session = findActiveSession(db, req, deps.now ?? (() => new Date()));
+    if (session && isSameOriginRequest(req, resolveBoundOrigins(deps))) {
+      status = "approved";
+    }
+  }
   const confidential = body.token_endpoint_auth_method === "client_secret_post";
   const scopes = (body.scope ?? "").split(" ").filter((s) => s.length > 0);
   let registered: RegisteredClient;