@openparachute/hub 0.5.1 → 0.5.7

package/src/commands/lifecycle.ts

@@ -136,6 +136,24 @@ export interface LifecycleOpts {
   killWaitMs?: number;
   /** Poll interval while waiting for SIGTERM to land. */
   pollIntervalMs?: number;
+  /**
+   * How long `start` sleeps before re-checking `alive(pid)` to catch the
+   * spawn-then-immediately-die failure shape (hub#194: notes-serve crashed
+   * 50ms in on Bun.resolveSync, but `start` reported success because the
+   * spawn returned a pid). 250ms is the default in production — long
+   * enough to catch real silent-crashes (resolve failures, port
+   * collisions, missing args) without making `parachute start` feel
+   * laggy.
+   *
+   * Defaulting policy: if `alive` is not overridden, the settle defaults
+   * to 0 (skipped). Stub spawners hand back fake pids that the real
+   * `defaultAlive` would mark as dead, which would make every existing
+   * stub-spawner test fail spuriously. Tests that want to exercise the
+   * settle path inject both `alive` and `startSettleMs` explicitly.
+   * Production paths use the real `defaultAlive` and get the real 250ms
+   * settle.
+   */
+  startSettleMs?: number;
   /**
    * Override the hub origin passed to services as PARACHUTE_HUB_ORIGIN. If
    * unset, `start` derives it from `expose-state.json` (when exposed) or
@@ -168,6 +186,7 @@ interface Resolved {
   log: (line: string) => void;
   killWaitMs: number;
   pollIntervalMs: number;
+  startSettleMs: number;
   hubOrigin: string | undefined;
   ensureHub: (opts: EnsureHubOpts) => Promise<EnsureHubResult>;
   stopHubFn: (opts: StopHubOpts) => Promise<boolean>;
@@ -186,6 +205,14 @@ function resolve(opts: LifecycleOpts): Resolved {
     log: opts.log ?? ((line) => console.log(line)),
     killWaitMs: opts.killWaitMs ?? 10_000,
     pollIntervalMs: opts.pollIntervalMs ?? 200,
+    // See `LifecycleOpts.startSettleMs` doc. Production (no spawner
+    // override, no alive override) gets the 250ms settle. Tests that
+    // inject a stub spawner without a stub alive get 0 — `defaultAlive`
+    // against a fake pid would always report dead and break unrelated
+    // tests. Tests that want to exercise the settle path explicitly
+    // override `alive`, which re-enables the default 250ms.
+    startSettleMs:
+      opts.startSettleMs ?? (opts.spawner === undefined || opts.alive !== undefined ? 250 : 0),
     hubOrigin: resolveHubOrigin(opts.hubOrigin, configDir),
     ensureHub: opts.hub?.ensureRunning ?? ensureHubRunning,
     stopHubFn: opts.hub?.stop ?? stopHub,
@@ -371,16 +398,38 @@ export async function start(svc: string | undefined, opts: LifecycleOpts = {}):
     if (entry.installDir) spawnerOpts.cwd = entry.installDir;
     const passOpts =
       spawnerOpts.env !== undefined || spawnerOpts.cwd !== undefined ? spawnerOpts : undefined;
+    let pid: number;
     try {
-      const pid = r.spawner.spawn(cmd, logFile, passOpts);
-      writePid(short, pid, r.configDir);
-      r.log(`✓ ${short} started (pid ${pid}); logs: ${logFile}`);
-      if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
+      pid = r.spawner.spawn(cmd, logFile, passOpts);
     } catch (err) {
       failures++;
       const msg = err instanceof Error ? err.message : String(err);
       r.log(`✗ ${short} failed to start: ${msg}`);
+      continue;
+    }
+    writePid(short, pid, r.configDir);
+
+    // Settle-poll for spawn-then-immediately-die (hub#194). A spawn returning
+    // a pid only proves the kernel forked the process; the child may exit
+    // microseconds later if its main code path throws before listening
+    // (e.g. notes-serve's Bun.resolveSync failing for bun-linked installs).
+    // Without this poll, we'd report success and the operator would chase
+    // a phantom 502.
+    if (r.startSettleMs > 0) {
+      await r.sleep(r.startSettleMs);
+      if (!r.alive(pid)) {
+        clearPid(short, r.configDir);
+        failures++;
+        r.log(
+          `✗ ${short} failed to start: spawned pid ${pid} but the process exited within ${r.startSettleMs}ms.`,
+        );
+        r.log(`  Tail the log for details: tail -50 ${logFile}`);
+        continue;
+      }
     }
+
+    r.log(`✓ ${short} started (pid ${pid}); logs: ${logFile}`);
+    if (r.hubOrigin) r.log(`  ${HUB_ORIGIN_ENV}=${r.hubOrigin}`);
   }
   return failures === 0 ? 0 : 1;
 }

package/src/commands/status.ts

@@ -1,7 +1,7 @@
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { HUB_SVC, readHubPort } from "../hub-control.ts";
 import { type AliveFn, defaultAlive, formatUptime, processState } from "../process-state.ts";
-import { getSpec, shortNameForManifest } from "../service-spec.ts";
+import { canonicalPortForManifest, getSpec, shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
 
 export type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
@@ -74,6 +74,14 @@ interface StatusRow {
   url: string | undefined;
   healthy: boolean;
   skipped: boolean;
+  /**
+   * Canonical-port drift warning. Set when the entry has a known canonical
+   * port (first-party / known short) AND the actual port differs. Surfaced
+   * as a continuation line under the row so operators see a silent miswire
+   * (e.g. parachute-hub#195: scribe + agent both at 1944) without us
+   * hard-erroring on a deliberate operator port change.
+   */
+  driftWarning?: string;
 }
 
 /**
@@ -157,6 +165,19 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
 
       const url = urlForEntry(entry, short);
 
+      // Canonical-port drift detection (hub#195). Only fires for known
+      // first-party services where we have a canonical assignment. Third-party
+      // rows have no canonical to compare against. Warning is informational —
+      // operators may have moved a service off canonical deliberately.
+      // Note: multi-vault instance rows (`parachute-vault-<instance>`) don't
+      // match a canonical manifest name, so drift warnings don't fire for
+      // them. Intentional — see `canonicalPortForManifest` for the rationale.
+      const canonical = canonicalPortForManifest(entry.name);
+      const driftWarning =
+        canonical !== undefined && canonical !== entry.port
+          ? `canonical port is ${canonical}`
+          : undefined;
+
       // Only skip probe when we know the process is dead (PID file was
       // present but kill(pid, 0) failed). "unknown" status (no PID file)
       // still probes — externally-managed services should report health.
@@ -173,6 +194,7 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
           url,
           healthy: false,
           skipped: true,
+          driftWarning,
         };
       }
 
@@ -194,6 +216,7 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
         url,
         healthy: p.healthy,
         skipped: false,
+        driftWarning,
       };
     }),
   );
@@ -228,6 +251,10 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     if (!cells || !row) continue;
     print(formatRow(cells, widths));
     if (row.url) print(`  → ${row.url}`);
+    // Drift warning rides as its own continuation line. Plain ASCII (no
+    // emoji / unicode glyphs) for terminal compatibility — the same
+    // surface that prints to scripts piping `parachute status`.
+    if (row.driftWarning) print(`  ! ${row.driftWarning}`);
   }
 
   /**

package/src/help.ts

@@ -44,9 +44,9 @@ Services:
 What it does:
   1. bun add -g @openparachute/<service>[@<tag>]
   2. run any service-specific init (e.g. \`parachute-vault init\`)
-  3. assign a canonical port (1939–1949) and write \`PORT=<port>\` into
-     \`~/.parachute/<service>/.env\`. Idempotent — an existing PORT wins, so
-     re-installs and operator-edited ports survive across upgrades.
+  3. assign a canonical port (1939–1949) and reflect it in
+     \`~/.parachute/services.json\` — the single source of truth at boot
+     (services follow a 4-tier resolvePort ladder; services.json wins).
   4. verify the service registered itself in ~/.parachute/services.json
   5. for scribe in a TTY: prompt for transcription provider + API key
      (or take \`--scribe-provider\` / \`--scribe-key\`)

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 };
         }
       }
     }
@@ -147,40 +161,98 @@ export function findVaultUpstream(
 }
 
 /**
- * Reverse-proxy a `/vault/<name>/*` request onto the vault backend's loopback
- * port. The path is preserved end-to-end (vault since paraclaw#18 expects
- * requests at `/vault/<name>/...` not stripped to `/...`), so the upstream URL
- * mirrors the incoming pathname exactly.
+ * 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.
  *
- * `manifestPath` is the services.json path from `HubFetchDeps`. Read on every
- * proxied request so a vault created seconds ago is reachable without a
- * re-expose — same dynamism as the well-known doc (#135).
+ *   "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
+ * rewrite the path (e.g. when the caller has stripped a mount prefix because
+ * the backend serves bare routes). Query string is always preserved from the
+ * incoming URL.
  *
- * Returns `undefined` when no vault is currently mounted at this pathname so
- * the caller falls through to the catch-all 404. Returns a 502 response when
- * the upstream connection fails (vault crashed, port shifted) — the upstream
- * URL was valid; we just couldn't reach it.
+ * Note: this is **not** equivalent to the tailscale convention. `tailscale
+ * serve <mount>=<target>` strips the mount before forwarding, so
+ * `serviceProxyTarget` in `commands/expose.ts` works by making mount and
+ * target byte-equal. The hub's fetch-based proxy does no stripping unless the
+ * caller asks; per-service preferences vary (scribe wants bare paths, notes
+ * / agent / vault want the prefix), so the decision lives one layer up in
+ * `proxyToService` / `proxyToVault`.
+ *
+ * Returns 502 when the loopback fetch fails — port valid, target unreachable
+ * (service crashed, port shifted, mid-restart). `serviceLabel` is folded into
+ * the error message so 502 bodies say `vault upstream unreachable` /
+ * `scribe upstream unreachable` etc.
  *
  * Hop-by-hop notes: WebSocket upgrades and HTTP/2 trailers don't traverse
- * fetch-based proxies cleanly. Vault uses neither today; if a future service
- * needs them, switch to a Node http.IncomingMessage / http.request pair.
+ * fetch-based proxies cleanly. No on-box service uses either today; if one
+ * eventually needs them, switch to a Node http.IncomingMessage / http.request
+ * pair.
  */
-async function proxyToVault(req: Request, manifestPath: string): Promise<Response | undefined> {
-  let services: readonly ServiceEntry[];
-  try {
-    services = readManifest(manifestPath).services;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return new Response(JSON.stringify({ error: `vault routing failed: ${msg}` }), {
-      status: 500,
-      headers: { "content-type": "application/json" },
-    });
-  }
+async function proxyRequest(
+  req: Request,
+  port: number,
+  serviceLabel: string,
+  targetPath?: string,
+): Promise<Response> {
   const url = new URL(req.url);
-  const match = findVaultUpstream(services, url.pathname);
-  if (!match) return undefined;
-
-  const upstream = `http://127.0.0.1:${match.port}${url.pathname}${url.search}`;
+  const path = targetPath ?? url.pathname;
+  const upstream = `http://127.0.0.1:${port}${path}${url.search}`;
   const headers = new Headers(req.headers);
   // Host comes from the requester (tailnet FQDN); the loopback target wants
   // its own. Bun's fetch fills it in when omitted.
@@ -199,13 +271,156 @@ async function proxyToVault(req: Request, manifestPath: string): Promise<Respons
     return await fetch(upstream, init);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return new Response(JSON.stringify({ error: `vault upstream unreachable: ${msg}` }), {
+    return new Response(JSON.stringify({ error: `${serviceLabel} upstream unreachable: ${msg}` }), {
       status: 502,
       headers: { "content-type": "application/json" },
     });
   }
 }
 
+/**
+ * Reverse-proxy a `/vault/<name>/*` request onto the vault backend.
+ * `manifestPath` is the services.json path from `HubFetchDeps`. Read on every
+ * proxied request so a vault created seconds ago is reachable without a
+ * re-expose — same dynamism as the well-known doc (#135).
+ *
+ * Returns `undefined` when no vault claims this pathname so the caller can
+ * fall through to the SPA shell fallback for unknown vault names (the seam
+ * #173 introduced).
+ */
+async function proxyToVault(req: Request, manifestPath: string): Promise<Response | undefined> {
+  let services: readonly ServiceEntry[];
+  try {
+    services = readManifest(manifestPath).services;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return new Response(JSON.stringify({ error: `vault routing failed: ${msg}` }), {
+      status: 500,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  const url = new URL(req.url);
+  const match = findVaultUpstream(services, url.pathname);
+  if (!match) return undefined;
+  // 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);
+}
+
+/**
+ * Resolve which (non-vault) ServiceEntry should handle a given request.
+ * Generic longest-prefix match across every service's `paths[]`. Vault
+ * entries are filtered out — they're routed by `findVaultUpstream` /
+ * `proxyToVault`, which encode the vault-specific SPA-fallback seam.
+ *
+ * Returns `undefined` when no service claims the pathname; the caller 404s.
+ */
+export function findServiceUpstream(
+  services: readonly ServiceEntry[],
+  pathname: string,
+): { port: number; mount: string; entry: ServiceEntry } | undefined {
+  let best: { port: number; mount: string; entry: ServiceEntry } | undefined;
+  for (const s of services) {
+    if (isVaultEntry(s)) continue;
+    for (const path of s.paths) {
+      // 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 };
+        }
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * Reverse-proxy a request onto whichever non-vault service registers a
+ * matching `paths[]` prefix in services.json. Wired after every specific
+ * handler in `hubFetch` so the exclusion list (`/`, `/admin/*`, `/oauth/*`,
+ * `/.well-known/*`, `/hub/*`, `/vault/*`, `/api/*`) is enforced by ordering:
+ * those specific handlers run first and never reach this dispatch.
+ *
+ * Read services.json on every request so a `parachute install <svc>` made
+ * seconds ago is reachable without a hub restart — same dynamism as the
+ * well-known doc and `proxyToVault`.
+ *
+ * Honors `entry.stripPrefix`: when `true` the matched mount prefix is
+ * removed from the forwarded path so the backend sees a bare route
+ * (`/scribe/health` becomes `/health`). Default (`false` / absent) forwards
+ * the full path — matches what notes / agent / vault expect.
+ *
+ * Returns `undefined` when no service claims the pathname; caller 404s.
+ */
+async function proxyToService(req: Request, manifestPath: string): Promise<Response | undefined> {
+  let services: readonly ServiceEntry[];
+  try {
+    services = readManifest(manifestPath).services;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return new Response(JSON.stringify({ error: `service routing failed: ${msg}` }), {
+      status: 500,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  const url = new URL(req.url);
+  const match = findServiceUpstream(services, url.pathname);
+  if (!match) return 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
@@ -539,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 });
@@ -690,6 +917,13 @@ export function hubFetch(
       return serveSpa(spaDistDir, pathname, "/vault");
     }
 
+    // Generic services.json-driven dispatch for non-vault modules. Reaches
+    // here only after every hub-owned prefix above has had its turn — so
+    // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,
+    // `/api/*` are excluded by ordering, not by an explicit denylist (#182).
+    const proxied = await proxyToService(req, manifestPath);
+    if (proxied) return proxied;
+
     return new Response("not found", { status: 404 });
   };
 }

package/src/module-manifest.ts

@@ -114,6 +114,15 @@ export interface ModuleManifest {
    * as `hasAuth` / `init` / `urlForEntry`.
    */
   readonly managementUrl?: string;
+  /**
+   * When `true`, the hub's `/<svc>/*` proxy strips the matched mount prefix
+   * before forwarding (so the backend sees `/health` rather than
+   * `/<name>/health`). Default `false` matches the prefix-aware convention
+   * notes / agent / vault already follow. Carried into services.json via
+   * `seedEntryFromManifest`. See `ServiceEntry.stripPrefix` for the full
+   * per-module rationale.
+   */
+  readonly stripPrefix?: boolean;
 }
 
 export class ModuleManifestError extends Error {
@@ -365,6 +374,13 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   const dependencies = asDependencies(m.dependencies, where);
   const configSchema = asConfigSchema(m.configSchema, where);
   const managementUrl = asManagementUrl(m.managementUrl, where);
+  let stripPrefix: boolean | undefined;
+  if (m.stripPrefix !== undefined) {
+    if (typeof m.stripPrefix !== "boolean") {
+      throw new ModuleManifestError(`${where}: "stripPrefix" must be a boolean if present`);
+    }
+    stripPrefix = m.stripPrefix;
+  }
 
   const out: ModuleManifest = { name, manifestName, kind, port, paths, health };
   if (displayName !== undefined) (out as { displayName?: string }).displayName = displayName;
@@ -380,6 +396,9 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   if (managementUrl !== undefined) {
     (out as { managementUrl?: string }).managementUrl = managementUrl;
   }
+  if (stripPrefix !== undefined) {
+    (out as { stripPrefix?: boolean }).stripPrefix = stripPrefix;
+  }
   return out;
 }