@openparachute/hub 0.5.2 → 0.5.7

package/src/hub-server.ts

@@ -16,6 +16,7 @@
  *   /.well-known/jwks.json                    → JWKS from hub.db
  *   /.well-known/oauth-authorization-server   → RFC 8414 metadata (issuer, endpoints)
  *   /oauth/authorize  (GET + POST)            → login → consent → auth code
+ *   /oauth/authorize/approve (POST)           → inline DCR approve form (#208)
  *   /oauth/token      (POST)                  → authorization_code + refresh_token grants
  *   /oauth/register   (POST)                  → RFC 7591 dynamic client registration
  *   anything else                             → 404
@@ -60,6 +61,7 @@ import {
 } from "./module-manifest.ts";
 import {
   authorizationServerMetadata,
+  handleApproveClientPost,
   handleAuthorizeGet,
   handleAuthorizePost,
   handleRegister,
@@ -67,6 +69,11 @@ import {
   handleToken,
 } from "./oauth-handlers.ts";
 import { clearPid, writePid } from "./process-state.ts";
+import {
+  FIRST_PARTY_FALLBACKS,
+  effectivePublicExposure,
+  shortNameForManifest,
+} from "./service-spec.ts";
 import { type ServiceEntry, readManifest } from "./services-manifest.ts";
 import { getAllPublicKeys } from "./signing-keys.ts";
 import { buildWellKnown, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
@@ -136,9 +143,16 @@ export function findVaultUpstream(
   for (const s of services) {
     if (!isVaultEntry(s)) continue;
     for (const path of s.paths) {
-      if (pathname === path || pathname.startsWith(`${path}/`)) {
-        if (!best || path.length > best.mount.length) {
-          best = { port: s.port, mount: path, entry: s };
+      // Normalize trailing slashes before comparison (#197). A services.json
+      // entry written with `paths: ["/vault/default/"]` would otherwise only
+      // match the exact pathname `/vault/default/` and never any sub-path,
+      // because `pathname.startsWith("/vault/default//")` is always false.
+      // The "|| '/'" branch keeps a bare-root mount "/" stable rather than
+      // collapsing it to an empty string.
+      const norm = path.replace(/\/+$/, "") || "/";
+      if (pathname === norm || pathname.startsWith(`${norm}/`)) {
+        if (!best || norm.length > best.mount.length) {
+          best = { port: s.port, mount: norm, entry: s };
         }
       }
     }
@@ -146,6 +160,65 @@ export function findVaultUpstream(
   return best;
 }
 
+/**
+ * The trust layer a request arrived through. Hub binds `127.0.0.1:1939`, so
+ * every request reaches it via one of three trusted forwarders (or directly
+ * over loopback). The forwarder injects characteristic headers that we use to
+ * classify; nothing else can reach the listener, so spoofing isn't a concern.
+ *
+ *   "loopback" — direct localhost call (CLI, on-box service, dev shell).
+ *   "tailnet"  — `tailscale serve` forwarding an authed tailnet user.
+ *   "public"   — `tailscale funnel` (public-over-tailnet, unauthed) OR a
+ *                cloudflared tunnel forwarding from the public internet.
+ *
+ * Used to gate `publicExposure: "loopback"` services on the generic
+ * `/<svc>/*` dispatch (the hub's only layer-gate). Hub-owned paths (`/`,
+ * `/admin/*`, `/api/*`, `/hub/*`, `/oauth/*`, `/.well-known/*`, `/vault/*`,
+ * `/vaults`) reach all layers and rely on app-level auth (admin session
+ * cookie + 2FA, OAuth, per-service tokens) — they are NOT layer-blocked.
+ */
+export type RequestLayer = "loopback" | "tailnet" | "public";
+
+/**
+ * Classify the trust layer for an incoming request by inspecting proxy
+ * headers. Order matters: cloudflared headers come first because cloudflared
+ * could in principle be deployed alongside tailscale on the same node.
+ *
+ * Header reference (verified against tailscale serve.go on 2026-05-08):
+ *   - `Tailscale-User-Login` is set ONLY by `tailscale serve` for an authed
+ *     tailnet user. Tagged-source nodes don't get it. Funnel never sets it.
+ *   - `Tailscale-Funnel-Request: ?1` is set ONLY by Tailscale Funnel.
+ *     Mutually exclusive with `Tailscale-User-Login` (the serve.go path
+ *     returns early when funneled).
+ *   - `CF-Ray` and `CF-Connecting-IP` are set by Cloudflare's edge for
+ *     anything proxied through a cloudflared tunnel.
+ *
+ * Spoofing isn't a concern: hub binds `127.0.0.1:1939`, so external requests
+ * can't reach the listener except via these trusted forwarders. Tailscale
+ * specifically strips the same headers from incoming requests before
+ * re-injecting them, so even a malicious tailnet peer can't impersonate a
+ * different user. We could mirror that strip-on-arrival defense, but it's
+ * belt-and-braces given the bind shape.
+ *
+ * Default to "loopback" when no proxy headers are present — that's the
+ * direct-localhost case. Funnel without `Tailscale-Funnel-Request` would
+ * also fall here, but Tailscale always sets the header on funneled
+ * requests, so this branch only fires for true loopback callers.
+ */
+export function layerOf(req: Request): RequestLayer {
+  const h = req.headers;
+  if (h.get("cf-ray") !== null || h.get("cf-connecting-ip") !== null) return "public";
+  // Match the structured-header value (`?1`) rather than mere presence:
+  // serve.go only ever emits `?1`, so insisting on the canonical value keeps
+  // the classifier's intent obvious to a future reader (don't loosen this to
+  // `!== null` — Tailscale's contract is the value, not the header name).
+  // CF-Ray / CF-Connecting-IP are open-string identifiers with no canonical
+  // value to compare against, hence the presence-check above.
+  if (h.get("tailscale-funnel-request") === "?1") return "public";
+  if (h.get("tailscale-user-login") !== null) return "tailnet";
+  return "loopback";
+}
+
 /**
  * Forward a request to a loopback service on `127.0.0.1:<port>`. By default
  * the incoming pathname + query are preserved verbatim; pass `targetPath` to
@@ -229,7 +302,20 @@ async function proxyToVault(req: Request, manifestPath: string): Promise<Respons
   const url = new URL(req.url);
   const match = findVaultUpstream(services, url.pathname);
   if (!match) return undefined;
-  return proxyRequest(req, match.port, "vault");
+  // Layer-gate on `publicExposure: "loopback"` — hide the entry from non-
+  // loopback callers as if it doesn't exist. "allowed" / "auth-required"
+  // pass through; the service does its own auth.
+  if (effectivePublicExposure(match.entry) === "loopback" && layerOf(req) !== "loopback") {
+    return new Response("not found", { status: 404 });
+  }
+  // Symmetry with proxyToService (#196): honor `stripPrefix` with FIRST_-
+  // PARTY_FALLBACKS as a fallback source. No first-party vault fallback
+  // declares stripPrefix today (vault expects the full `/vault/<name>/*`
+  // path), so this is a no-op in practice — but reading the same shape in
+  // both proxies keeps the dispatch surface consistent for future readers.
+  const stripPrefix = stripPrefixFor(match.entry);
+  const targetPath = stripPrefix ? url.pathname.slice(match.mount.length) || "/" : undefined;
+  return proxyRequest(req, match.port, "vault", targetPath);
 }
 
 /**
@@ -248,9 +334,18 @@ export function findServiceUpstream(
   for (const s of services) {
     if (isVaultEntry(s)) continue;
     for (const path of s.paths) {
-      if (pathname === path || pathname.startsWith(`${path}/`)) {
-        if (!best || path.length > best.mount.length) {
-          best = { port: s.port, mount: path, entry: s };
+      // Normalize trailing slashes before comparison (#197). A services.json
+      // entry written with `paths: ["/notes/"]` would otherwise only match
+      // the exact pathname `/notes/` and never `/notes/assets/index.js` —
+      // `pathname.startsWith("/notes//")` is always false because URLs
+      // don't have double slashes. Result: SPA shell loads but every asset
+      // 404s (notes blank-screen on Aaron's box, 2026-05-08).
+      // The "|| '/'" branch keeps a bare-root mount "/" stable rather than
+      // collapsing it to an empty string.
+      const norm = path.replace(/\/+$/, "") || "/";
+      if (pathname === norm || pathname.startsWith(`${norm}/`)) {
+        if (!best || norm.length > best.mount.length) {
+          best = { port: s.port, mount: norm, entry: s };
         }
       }
     }
@@ -290,12 +385,42 @@ async function proxyToService(req: Request, manifestPath: string): Promise<Respo
   const url = new URL(req.url);
   const match = findServiceUpstream(services, url.pathname);
   if (!match) return undefined;
-  const targetPath = match.entry.stripPrefix
-    ? url.pathname.slice(match.mount.length) || "/"
-    : undefined;
+  // Layer-gate on `publicExposure: "loopback"`. From the perspective of a
+  // tailnet/public caller, a loopback-only service must be indistinguishable
+  // from "not installed" — 404, not 403, so we don't leak the existence of
+  // the route. "allowed" / "auth-required" pass through; the service does
+  // its own auth.
+  if (effectivePublicExposure(match.entry) === "loopback" && layerOf(req) !== "loopback") {
+    return new Response("not found", { status: 404 });
+  }
+  // Consult FIRST_PARTY_FALLBACKS as a fallback for `stripPrefix` (#196).
+  // Scribe v0.4.0 doesn't write `stripPrefix: true` to its services.json
+  // entry — the declaration only lives in hub's SCRIBE_FALLBACK manifest.
+  // Pre-#187 this didn't matter because the per-service tailscale serve
+  // plan baked the path into the target URL; post-#187 routing went through
+  // hub which wasn't consulting the fallback registry. Same shape as how
+  // `effectivePublicExposure` already handles fallback derivation in
+  // service-spec.ts. Explicit-on-entry still wins; absent → fallback →
+  // false (preserving existing keep-prefix default for unknown services).
+  const stripPrefix = stripPrefixFor(match.entry);
+  const targetPath = stripPrefix ? url.pathname.slice(match.mount.length) || "/" : undefined;
   return proxyRequest(req, match.port, match.entry.name, targetPath);
 }
 
+/**
+ * Resolve effective `stripPrefix` for a service entry. Explicit on-entry
+ * wins; otherwise consult `FIRST_PARTY_FALLBACKS` keyed by short name (so
+ * scribe's vendored fallback supplies `stripPrefix: true` even when scribe's
+ * own boot doesn't write it). Defaults to `false` — keep the prefix —
+ * matching the pre-#196 dispatch behavior for unknown / third-party services.
+ */
+function stripPrefixFor(entry: ServiceEntry): boolean {
+  if (entry.stripPrefix !== undefined) return entry.stripPrefix;
+  const short = shortNameForManifest(entry.name);
+  const fb = short !== undefined ? FIRST_PARTY_FALLBACKS[short] : undefined;
+  return fb?.manifest.stripPrefix ?? false;
+}
+
 export interface HubFetchDeps {
   /**
    * Lazily opens (or returns a cached handle to) the hub DB. Optional so
@@ -629,6 +754,18 @@ export function hubFetch(
       return new Response("method not allowed", { status: 405 });
     }
 
+    // Inline approve form for the operator-driven pending-client flow (#208).
+    // Receives `client_id` + `csrf_token` + `return_to` from the form rendered
+    // by handleAuthorizeGet when the operator hits a pending client. Three
+    // gates inside the handler: CSRF, active session, same-origin Origin.
+    if (pathname === "/oauth/authorize/approve") {
+      if (!getDb) {
+        return new Response("hub db not configured", { status: 503 });
+      }
+      if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+      return handleApproveClientPost(getDb(), req, oauthDeps(req));
+    }
+
     if (pathname === "/oauth/token") {
       if (!getDb) {
         return new Response("hub db not configured", { status: 503 });

package/src/notes-serve.ts

@@ -25,6 +25,7 @@
  */
 
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
 interface Args {
@@ -67,16 +68,76 @@ export function normalizeMount(raw: string): string {
   return raw.replace(/\/+$/, "");
 }
 
-function resolveNotesDist(): string {
-  const pkgPath = Bun.resolveSync("@openparachute/notes/package.json", process.cwd());
-  const root = dirname(pkgPath);
-  const dist = join(root, "dist");
-  if (!existsSync(dist)) {
-    throw new Error(
-      `@openparachute/notes is installed but has no dist/ directory at ${dist}. The package may not ship a prebuilt bundle — ask the notes maintainer to add a prepublishOnly build step.`,
-    );
+/**
+ * Candidate base directories that `Bun.resolveSync` walks from when looking
+ * for `@openparachute/notes/package.json`. Order matters:
+ *
+ *   1. `process.cwd()` — works when notes-serve is invoked from inside the
+ *      notes checkout (e.g. via `installDir` cwd in lifecycle.ts) or from
+ *      any project that depends on `@openparachute/notes`.
+ *   2. `~/.bun/install/global/node_modules` — modern Bun's global-install
+ *      layout. This is where `bun add -g @openparachute/notes` lands the
+ *      package, and where `bun link @openparachute/notes` symlinks it.
+ *   3. `~/.bun/install/global` — defensive fallback for older Bun layouts.
+ *
+ * Hub itself does NOT depend on `@openparachute/notes`, so when
+ * `parachute start notes` is run from the hub repo dir, the cwd-relative
+ * resolve walks ancestral node_modules and finds nothing. Bun does not
+ * auto-consult the global install dir, so bun-linked installs fail to
+ * resolve without (2)/(3). hub#194: Aaron hit silent 502 on tailnet
+ * `/notes/` because of this — fixed by trying the global install dirs.
+ *
+ * Exported (and parameterized via `cwd`/`home`) so tests can drive the
+ * resolution order against a real fixture install without monkey-patching
+ * `Bun.resolveSync`.
+ */
+export function notesDistCandidates(cwd: string, home: string): string[] {
+  return [cwd, join(home, ".bun/install/global/node_modules"), join(home, ".bun/install/global")];
+}
+
+export interface ResolveNotesDistDeps {
+  cwd?: string;
+  home?: string;
+  /** Override `Bun.resolveSync` for tests. */
+  resolveSync?: (specifier: string, base: string) => string;
+  existsSync?: (path: string) => boolean;
+}
+
+export function resolveNotesDistFrom(deps: ResolveNotesDistDeps = {}): string {
+  const cwd = deps.cwd ?? process.cwd();
+  const home = deps.home ?? homedir();
+  const resolveSync = deps.resolveSync ?? Bun.resolveSync;
+  const exists = deps.existsSync ?? existsSync;
+  const candidates = notesDistCandidates(cwd, home);
+  const resolveErrors: string[] = [];
+  for (const base of candidates) {
+    let pkgPath: string;
+    try {
+      pkgPath = resolveSync("@openparachute/notes/package.json", base);
+    } catch (err) {
+      resolveErrors.push(`  - ${base}: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    const root = dirname(pkgPath);
+    const dist = join(root, "dist");
+    if (!exists(dist)) {
+      // Found the package but it has no dist/. This is a hard error
+      // (package shipped without a prebuilt bundle); don't fall through to
+      // other candidates — they'd resolve to the same package and report
+      // the same problem.
+      throw new Error(
+        `@openparachute/notes resolved at ${root} has no dist/ directory at ${dist}. The package may not ship a prebuilt bundle — ask the notes maintainer to add a prepublishOnly build step.`,
+      );
+    }
+    return dist;
   }
-  return dist;
+  throw new Error(
+    `Could not resolve @openparachute/notes from any of:\n${resolveErrors.join("\n")}\nIs the package installed? Try \`bun add -g @openparachute/notes\` or \`parachute install notes\`.`,
+  );
+}
+
+function resolveNotesDist(): string {
+  return resolveNotesDistFrom();
 }
 
 function mimeFor(path: string): string | undefined {

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,13 @@ 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 { isNonRequestableScope, isRequestableScope } from "./scope-explanations.ts";
 import { findUnknownScopes, loadDeclaredScopes } from "./scope-registry.ts";
 import {
@@ -64,6 +72,7 @@ import {
   SESSION_TTL_MS,
   buildSessionCookie,
   createSession,
+  findActiveSession,
   findSession,
   parseSessionCookie,
 } from "./sessions.ts";
@@ -291,12 +300,63 @@ 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);
+  const session = findActiveSession(db, req, deps.now ?? (() => new Date()));
+  const sameOrigin = originMatchesIssuer(req, deps.issuer);
+  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,
+        approveForm: { csrfToken: csrf.token, returnTo },
+      }),
+      403,
+      extra,
+    );
+  }
+  return htmlResponse(
+    renderApprovePending({
+      clientName: client.clientName ?? client.clientId,
+      clientId: client.clientId,
+      redirectUris: client.redirectUris,
+      requestedScopes,
+    }),
     403,
+    extra,
   );
 }
 
@@ -345,7 +405,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 +598,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 +675,104 @@ 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 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.
+ *
+ * `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 (!originMatchesIssuer(req, deps.issuer)) {
+    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") ?? ""),
@@ -1064,20 +1235,72 @@ interface RegisterRequestBody {
   token_endpoint_auth_method?: string;
 }
 
+/**
+ * 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.
+ */
+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;
+}
+
 /**
  * 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 `originMatchesIssuer` + 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 +1347,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 && originMatchesIssuer(req, deps.issuer)) {
+      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;