@openparachute/hub 0.7.2 → 0.7.3-rc.10

package/src/module-manifest.ts

@@ -66,16 +66,26 @@ export interface ConfigSchema {
 }
 
 /**
- * Discovery tier (2026-06-09 modular-UI architecture). `core` modules are the
- * product surface (vault / scribe / hub / surface); `experimental` modules
- * (channel / runner / others) render in a de-emphasized group on the Modules
- * screen. **Show all; never hide** — `focus` only sorts + labels.
+ * Discovery tier (2026-06-09 modular-UI architecture). Three tiers today:
+ *   - `core` — the product surface (vault / scribe / hub / surface).
+ *   - `experimental` — legit previews (agent) that render in a de-emphasized
+ *     group but ARE offered on a fresh install.
+ *   - `deprecated` — modules retained for back-compat (notes-daemon, runner)
+ *     that stay resolvable + shown-if-installed (so an existing operator can
+ *     still manage / uninstall them) but are NOT offered on a fresh setup
+ *     (2026-06-25). Distinct from a fully retired module (`RETIRED_MODULES`),
+ *     whose services.json row is GC'd on load.
+ *
+ * **Show all installed; never hide** — `focus` only sorts + labels for an
+ * installed/known module. The one behavioral lever it pulls is the fresh-install
+ * OFFER: `deprecated` shorts are dropped from the setup wizard + the admin SPA's
+ * "available to install" set.
  *
  * Absent in a `module.json` ⇒ the hub falls back to its default map (see
  * `service-spec.focusForShort`), which defaults unlisted modules to
  * `experimental`.
  */
-export type ModuleFocus = "core" | "experimental";
+export type ModuleFocus = "core" | "experimental" | "deprecated";
 
 /**
  * An event a module EMITS — the left-hand side of a Connection (2026-06-09
@@ -324,8 +334,10 @@ export interface ModuleManifest {
    * Discovery tier (2026-06-09 modular-UI architecture). When a module
    * declares `focus`, the hub's Modules screen uses it verbatim; otherwise it
    * falls back to `service-spec.focusForShort` (vault/scribe/hub/surface →
-   * `core`, everything else → `experimental`). **Show all; never hide** —
-   * `focus` only groups + de-emphasizes. Additive + back-compatible.
+   * `core`, notes/runner → `deprecated`, everything else → `experimental`).
+   * **Show all installed; never hide** — `focus` groups + de-emphasizes; the
+   * one behavioral lever is the fresh-install OFFER, which excludes
+   * `deprecated`. Additive + back-compatible.
    */
   readonly focus?: ModuleFocus;
   /**
@@ -711,12 +723,14 @@ function asCredentials(v: unknown, where: string): readonly ModuleCredential[] |
   });
 }
 
-const MODULE_FOCUS_VALUES = new Set<ModuleFocus>(["core", "experimental"]);
+const MODULE_FOCUS_VALUES = new Set<ModuleFocus>(["core", "experimental", "deprecated"]);
 
 function asFocus(v: unknown, where: string): ModuleFocus | undefined {
   if (v === undefined) return undefined;
   if (typeof v !== "string" || !MODULE_FOCUS_VALUES.has(v as ModuleFocus)) {
-    throw new ModuleManifestError(`${where}: "focus" must be "core" | "experimental" if present`);
+    throw new ModuleManifestError(
+      `${where}: "focus" must be "core" | "experimental" | "deprecated" if present`,
+    );
   }
   return v as ModuleFocus;
 }

package/src/oauth-client.ts

@@ -28,6 +28,15 @@ export type FetchFn = typeof fetch;
 /** Default outbound timeout for every OAuth-client request. */
 const DEFAULT_TIMEOUT_MS = 15_000;
 
+/**
+ * Shorter timeout for best-effort DISCOVERY probes. Discovery tries several
+ * well-known candidates in priority order (path-inserted, host-root, OIDC), so a
+ * full 15s per probe could stack into a long wall-clock wait on a slow/firewalled
+ * remote. These metadata GETs are quick when they exist; a tight ceiling bounds
+ * the worst case while still tolerating a sluggish responder.
+ */
+const DISCOVERY_PROBE_TIMEOUT_MS = 6_000;
+
 /**
  * `fetch` with an AbortController timeout. The hub has no shared fetch wrapper,
  * so this lives here for all outbound OAuth-client calls — a slow/hung remote
@@ -93,10 +102,15 @@ async function fetchJson(
   url: string,
   fetchFn: FetchFn,
   what: string,
+  timeoutMs?: number,
 ): Promise<Record<string, unknown>> {
   let res: Response;
   try {
-    res = await fetchWithTimeout(url, { headers: { accept: "application/json" } }, fetchFn);
+    res = await fetchWithTimeout(
+      url,
+      { headers: { accept: "application/json" }, ...(timeoutMs ? { timeout: timeoutMs } : {}) },
+      fetchFn,
+    );
   } catch (err) {
     throw new OAuthClientError(`${what}: request to ${url} failed`, err);
   }
@@ -125,44 +139,120 @@ function asStringArray(v: unknown): string[] | undefined {
   return out.length > 0 ? out : undefined;
 }
 
+/**
+ * RFC 9728 §3.1 / RFC 8414 §3.1 well-known URL candidates for a resource or
+ * issuer URL. The spec INSERTS the well-known segment after the host while
+ * PRESERVING the URL's path: `https://h/p` → `https://h/.well-known/<seg>/p`.
+ * We try the path-inserted form FIRST (correct when the resource/issuer carries
+ * a path — e.g. an MCP served at `/mcp`, or a multi-tenant issuer at `/tenant`),
+ * then the host-root form (`https://h/.well-known/<seg>`) as a fallback for
+ * path-less deployments + older servers. De-duplicated, in priority order.
+ */
+function wellKnownCandidates(url: string, segment: string): string[] {
+  const u = new URL(url);
+  // The query string is intentionally excluded (u.pathname omits it) — RFC 9728
+  // §3.1 builds the well-known URL from the resource PATH only.
+  const path = u.pathname.replace(/\/+$/, ""); // drop trailing slash(es)
+  const root = `${u.origin}/.well-known/${segment}`;
+  const out = path ? [`${u.origin}/.well-known/${segment}${path}`, root] : [root];
+  return [...new Set(out)];
+}
+
+/**
+ * Fetch the first candidate URL (in priority order) that returns a valid JSON
+ * object. Lets discovery probe the path-inserted well-known location first, then
+ * fall back to the host root. If EVERY candidate fails, throws an
+ * OAuthClientError naming all tried locations (so a failure points at every
+ * probe, not just the last).
+ */
+async function fetchJsonFirst(
+  urls: string[],
+  fetchFn: FetchFn,
+  what: string,
+  timeoutMs?: number,
+): Promise<Record<string, unknown>> {
+  const errors: string[] = [];
+  for (const url of urls) {
+    try {
+      return await fetchJson(url, fetchFn, what, timeoutMs);
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  throw new OAuthClientError(
+    `${what}: no metadata found — tried ${urls.length} location(s): ${errors.join(" | ")}`,
+  );
+}
+
 /**
  * Discover the issuer + endpoints for a remote MCP URL.
  *
- *   1. RFC 9728: GET <mcp-origin>/.well-known/oauth-protected-resource →
- *      authorization_servers[0] = issuer (+ scopes_supported).
- *   2. RFC 8414: GET <issuer>/.well-known/oauth-authorization-server →
+ *   1. RFC 9728: GET <mcp>/.well-known/oauth-protected-resource[/<path>] →
+ *      authorization_servers[0] = issuer (+ scopes_supported). The path-inserted
+ *      location is tried first (the modern MCP shape: an MCP at `/mcp` advertises
+ *      at `/.well-known/oauth-protected-resource/mcp`, and its auth server often
+ *      lives on a SEPARATE host), then the host root.
+ *   2. RFC 8414 / OIDC: GET <issuer>/.well-known/oauth-authorization-server then
+ *      /.well-known/openid-configuration (each path-inserted then host-root) →
  *      authorization_endpoint, token_endpoint, registration_endpoint,
  *      revocation_endpoint (+ scopes_supported fallback).
  *
  * If the resource has no 9728 doc, falls back to treating the MCP origin itself
- * as the issuer and reading its 8414 doc directly (8414-only resources).
+ * as the issuer and reading its 8414/OIDC doc directly (8414-only resources).
  */
 export async function discover(mcpUrl: string, fetchFn: FetchFn = fetch): Promise<DiscoveryResult> {
   const origin = originOf(mcpUrl);
 
-  // Step 1 — RFC 9728 (best-effort; some resources only expose 8414).
+  // Step 1 — RFC 9728 protected-resource metadata (best-effort; some resources
+  // only expose 8414). Probe the PATH-INSERTED location first (an MCP served at
+  // `/mcp` advertises at `/.well-known/oauth-protected-resource/mcp`), then the
+  // host root — this is what lets a resource whose auth server lives on a
+  // SEPARATE host be discovered at all.
   let issuer: string | undefined;
   let prScopes: string[] | undefined;
   try {
-    const pr = await fetchJson(
-      `${origin}/.well-known/oauth-protected-resource`,
+    const pr = await fetchJsonFirst(
+      wellKnownCandidates(mcpUrl, "oauth-protected-resource"),
       fetchFn,
       "protected-resource discovery",
+      DISCOVERY_PROBE_TIMEOUT_MS,
     );
     const servers = asStringArray(pr.authorization_servers);
     issuer = servers?.[0];
     prScopes = asStringArray(pr.scopes_supported);
   } catch {
-    // No 9728 doc — fall back to the MCP origin as issuer.
+    // No 9728 doc anywhere — fall back to the MCP origin as issuer.
     issuer = undefined;
   }
   if (!issuer) issuer = origin;
 
-  // Step 2 — RFC 8414 on the issuer.
-  const as = await fetchJson(
-    `${issuer.replace(/\/+$/, "")}/.well-known/oauth-authorization-server`,
+  // The issuer comes from the (attacker-influenceable) PRM doc — validate it
+  // parses as a URL so a malformed value surfaces as an OAuthClientError rather
+  // than a raw TypeError out of the candidate construction below.
+  let issuerUrl: URL;
+  try {
+    issuerUrl = new URL(issuer);
+  } catch {
+    throw new OAuthClientError(`authorization_servers[0] is not a valid URL: ${issuer}`);
+  }
+
+  // Step 2 — RFC 8414 / OIDC metadata on the issuer. Path-inserted before host
+  // root, and `oauth-authorization-server` before `openid-configuration`, so an
+  // issuer that sits at a path or only serves OIDC discovery still resolves. Plus
+  // the OIDC Discovery 1.0 §4.1 APPEND form (`<issuer-with-path>/.well-known/
+  // openid-configuration`) for a path-ful issuer — distinct from the 8414 INSERT.
+  const asCandidates = [
+    ...wellKnownCandidates(issuer, "oauth-authorization-server"),
+    ...wellKnownCandidates(issuer, "openid-configuration"),
+  ];
+  if (issuerUrl.pathname.replace(/\/+$/, "")) {
+    asCandidates.push(`${issuer.replace(/\/+$/, "")}/.well-known/openid-configuration`);
+  }
+  const as = await fetchJsonFirst(
+    [...new Set(asCandidates)],
     fetchFn,
     "authorization-server discovery",
+    DISCOVERY_PROBE_TIMEOUT_MS,
   );
 
   const authorizationEndpoint = asString(as.authorization_endpoint);

package/src/oauth-flows-store.ts

@@ -52,6 +52,14 @@ export interface PendingFlow {
   readonly scope?: string;
   /** The hub's callback URL registered for this flow. */
   readonly redirectUri: string;
+  /**
+   * OPTIONAL same-origin (hub-relative) page the operator should be sent back
+   * to after a SUCCESSFUL consent — the agent ops surface / admin grants page
+   * they started from. Validated with `isSafeHubReturnTo` at stash time and
+   * (defensively) again at redirect time. Absent for flows started without one
+   * (and for all pre-existing on-disk flows — additive + back-compat).
+   */
+  readonly returnTo?: string;
   readonly createdAt: string;
 }
 
@@ -62,6 +70,10 @@ interface FlowsFile {
 function isPendingFlow(v: unknown): v is PendingFlow {
   if (!v || typeof v !== "object") return false;
   const f = v as Record<string, unknown>;
+  // `returnTo` is OPTIONAL + additive — absent on every pre-existing on-disk
+  // flow. Accept undefined; if present it must be a string (validated for
+  // open-redirect safety at the call sites, not here).
+  if (f.returnTo !== undefined && typeof f.returnTo !== "string") return false;
   return (
     typeof f.state === "string" &&
     typeof f.grantId === "string" &&

package/src/oauth-handlers.ts

@@ -51,9 +51,13 @@ import { consumeFirstClientAutoApproveWindow } from "./hub-settings.ts";
 import { VAULT_VERBS, inferAudience } from "./jwt-audience.ts";
 import {
   ACCESS_TOKEN_TTL_SECONDS,
+  REFRESH_GRACE_MS,
   RefreshTokenInsertError,
+  type RefreshTokenRow,
   findRefreshToken,
   findTokenRowByJti,
+  linkRotation,
+  liveFamilyRefreshRows,
   revokeFamily,
   signAccessToken,
   signRefreshToken,
@@ -68,6 +72,12 @@ import {
 } from "./oauth-ui.ts";
 import { isSameOriginRequest } from "./origin-check.ts";
 import { buildPendingLoginCookie, createPendingLogin } from "./pending-login.ts";
+import {
+  authIpCeilingRateLimiter,
+  clientIpFromRequest,
+  compositeKey,
+  loginRateLimiter,
+} from "./rate-limit.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import { narrowResourceVaultScopes, resolveResourceVault } from "./resource-binding.ts";
 import { isNonRequestableScope, isRequestableScope, scopeIsAdmin } from "./scope-explanations.ts";
@@ -1382,12 +1392,40 @@ async function handleLoginSubmit(
   db: Database,
   req: Request,
   form: Awaited<ReturnType<Request["formData"]>>,
-  _deps: OAuthDeps,
+  deps: OAuthDeps,
   csrfToken: string,
 ): Promise<Response> {
   const username = String(form.get("username") ?? "");
   const password = String(form.get("password") ?? "");
   const params = paramsFromForm(form);
+  // Rate-limit gate — AFTER CSRF (verified by the `handleAuthorizePost` caller)
+  // and BEFORE the credential check. This `/oauth/authorize` password door had
+  // NO rate-limit before; without it an attacker got an unbounded brute-force
+  // channel that bypassed `/login`'s floor entirely. Two tiers, reusing the
+  // SAME `loginRateLimiter` instance + the SAME `compositeKey(ip, username)`
+  // scheme as `/login`, so the two password doors share ONE per-account bucket
+  // (an attacker can't get 5 tries at `/login` PLUS another 5 here). The coarse
+  // per-IP CEILING backstops username-rotation; the per-(ip,username) FLOOR is
+  // the brute-force floor.
+  const clientIp = clientIpFromRequest(req);
+  const now = deps.now ? deps.now() : new Date();
+  const ceiling = authIpCeilingRateLimiter.checkAndRecord(clientIp, now);
+  const floor = loginRateLimiter.checkAndRecord(compositeKey(clientIp, username), now);
+  if (!ceiling.allowed || !floor.allowed) {
+    const retryAfterSeconds = Math.max(
+      ceiling.allowed ? 0 : (ceiling.retryAfterSeconds ?? 1),
+      floor.allowed ? 0 : (floor.retryAfterSeconds ?? 1),
+    );
+    return htmlResponse(
+      renderLogin({
+        params,
+        csrfToken,
+        errorMessage: `Too many login attempts. Try again in ${retryAfterSeconds} seconds.`,
+      }),
+      429,
+      { "retry-after": String(retryAfterSeconds) },
+    );
+  }
   if (!username || !password) {
     return htmlResponse(
       renderLogin({ params, csrfToken, errorMessage: "Username and password are required." }),
@@ -1883,6 +1921,39 @@ export async function handleApproveClientPost(
   return redirectResponse(returnTo);
 }
 
+/**
+ * The load-bearing open-redirect guard, shared by every hub `return_to` gate.
+ * A safe hub-relative target is a SINGLE-slash root-relative path: same-origin
+ * to the hub, no scheme, no `//host` scheme-relative escape. Empty string is
+ * rejected.
+ *
+ * This is the same-origin core that `isSafeAuthorizeReturnTo` (OAuth-resume)
+ * builds on, and that broader same-origin gates (the agent-grant OAuth
+ * callback's `returnTo`) reuse directly — they need to return the operator to
+ * a `/admin/...` page, not specifically `/oauth/authorize`. Single source of
+ * truth for "is this an open redirect?" — do NOT reimplement the
+ * `startsWith("/") && !startsWith("//")` check elsewhere.
+ */
+export function isSafeHubReturnTo(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;
+  // Reject `..` traversal sequences — literal AND percent-encoded (`%2e%2e`),
+  // since redirectToReturn's `new URL()` parse decodes them before emitting the
+  // path. They stay same-origin but a target that walks the path tree is never a
+  // legitimate return-to and lets a crafted value reach an unexpected hub path.
+  // (`/oauth/authorize?…` callers never carry `..`, so this is free for them.)
+  if (value.includes("..")) return false;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return false; // malformed percent-encoding → reject rather than guess
+  }
+  return !decoded.includes("..");
+}
+
 /**
  * Validate a form-submitted `return_to` value. Must be a hub-relative URL
  * (no scheme, no double-slash) targeting `/oauth/authorize` with a query
@@ -1895,13 +1966,10 @@ export async function handleApproveClientPost(
  * valid OAuth-resume target?" for the whole hub.
  */
 export 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.
+  // Same-origin open-redirect guard first (shared single source of truth)…
+  if (!isSafeHubReturnTo(value)) return false;
+  // …then the authorize-specific path constraint: the OAuth flow re-enters
+  // via GET /oauth/authorize?<original-params>; anything off-path is a misuse.
   return value.startsWith("/oauth/authorize?");
 }
 
@@ -2193,10 +2261,46 @@ async function handleTokenRefresh(
     // Replay of an already-rotated refresh token. Per RFC 6819 §5.2.2.3 the
     // working assumption is theft — the legitimate client received a new
     // refresh token at the prior rotation, so anyone presenting the old one
-    // either lost a race (rare) or stole it (the case we must defend
-    // against). Either way: revoke every descendant in the family so the
-    // attacker can't keep refreshing, and force the legitimate client to
-    // re-authorize. Cheaper than tracking which call was first.
+    // either lost a race or stole it (the case we must defend against).
+    //
+    // ONE-GENERATION GRACE WINDOW (hub#685). Benign concurrent/retried
+    // refreshes — a multi-tab SPA, a bfcache/stale-tab resume, a network
+    // retry — legitimately present the *just-rotated* token a moment after
+    // it rotated. To avoid forcing those real clients to re-login, we let
+    // through the SINGLE immediately-previous token, and ONLY it, for
+    // ~REFRESH_GRACE_MS. The grace case rotates the live tip and converges
+    // the replaying client onto the current token; it does NOT mint a
+    // second live token into a forked lineage.
+    //
+    // The window is narrow ON PURPOSE — both conditions must hold:
+    //   (a) WINDOW: this row was revoked within the last REFRESH_GRACE_MS.
+    //   (b) IMMEDIATE-PREDECESSOR: this row's recorded successor (rotated_to)
+    //       IS the family's single live refresh row. That proves it's the
+    //       direct parent of the current tip — not an older ancestor (whose
+    //       successor is itself revoked) and not a sibling fork.
+    //
+    // HARD SECURITY INVARIANT: anything outside (a)∧(b) — an OLDER/ancestor
+    // token, any replay past the window, a family with zero or multiple live
+    // tips (already a theft-revoked or forked family) — falls through to the
+    // unchanged zero-tolerance path: revokeFamily + invalid_grant. The grace
+    // window NEVER tolerates more than the one immediate predecessor, and
+    // never beyond REFRESH_GRACE_MS.
+    const live = liveFamilyRefreshRows(db, row.familyId, now);
+    const revokedAtMs = new Date(row.revokedAt).getTime();
+    const withinWindow =
+      now.getTime() - revokedAtMs <= REFRESH_GRACE_MS && now.getTime() >= revokedAtMs;
+    const tip = live.length === 1 ? live[0]! : null;
+    const isImmediatePredecessor =
+      tip !== null && row.rotatedTo !== null && row.rotatedTo === tip.jti;
+    if (withinWindow && isImmediatePredecessor && tip) {
+      // Benign replay of the immediate predecessor. Rotate the live tip and
+      // hand the client the new pair — it converges on the current lineage
+      // (single live token preserved), no family revocation. Equivalent to
+      // what the client would have received had it presented the tip itself.
+      return await rotateAndRespond(db, tip, deps, now);
+    }
+    // Genuine theft (or a too-late replay): revoke every descendant so the
+    // attacker can't keep refreshing, and force re-authorization.
     revokeFamily(db, row.familyId, now);
     return jsonResponse(
       { error: "invalid_grant", error_description: "refresh_token revoked" },
@@ -2209,17 +2313,34 @@ async function handleTokenRefresh(
       400,
     );
   }
-  // Rotate: revoke the old refresh row, mint a new access + refresh pair
-  // bound to the same family so a future replay of *any* descendant can
-  // walk the chain.
-  //
+  return await rotateAndRespond(db, row, deps, now);
+}
+
+/**
+ * Rotate a single live refresh-token row: revoke it, mint + insert a new
+ * access + refresh pair bound to the same family, and link old→new
+ * (`rotated_to`) so a future grace-window check can identify the direct
+ * predecessor (hub#685). Returns the spec-shaped token response.
+ *
+ * Both call sites pass a row that is live at the moment of the call: the
+ * normal path passes the presented (non-revoked) token; the grace path
+ * passes the family's single live tip. Used for both so the benign-replay
+ * client receives exactly what a direct refresh of the tip would yield.
+ */
+async function rotateAndRespond(
+  db: Database,
+  row: RefreshTokenRow,
+  deps: OAuthDeps,
+  now: Date,
+): Promise<Response> {
+  const refreshUserId = row.userId ?? "";
   // Mint the access token *before* opening the rotation transaction. JWT
   // signing is async (jose returns a Promise) and bun:sqlite's
   // `db.transaction()` is sync — running async work inside the closure
   // would silently break atomicity. Once we have the JWT, the UPDATE
-  // (revoke old) + INSERT (mint new refresh row) commit or roll back as
-  // a unit, so a mid-rotation crash can't dead-old-without-replacement
-  // (#107).
+  // (revoke old) + INSERT (mint new refresh row) + link (rotated_to) commit
+  // or roll back as a unit, so a mid-rotation crash can't
+  // dead-old-without-replacement (#107).
   const audience = inferAudience(row.scopes);
   const access = await signAccessToken(db, {
     sub: refreshUserId,
@@ -2241,7 +2362,7 @@ async function handleTokenRefresh(
   try {
     refresh = db.transaction(() => {
       db.prepare("UPDATE tokens SET revoked_at = ? WHERE jti = ?").run(now.toISOString(), row.jti);
-      return signRefreshToken(db, {
+      const minted = signRefreshToken(db, {
         jti: access.jti,
         userId: refreshUserId,
         clientId: row.clientId,
@@ -2249,6 +2370,10 @@ async function handleTokenRefresh(
         familyId: row.familyId,
         now: deps.now,
       });
+      // Link old→new so the grace-window check (hub#685) can tell the
+      // immediate predecessor apart from an older ancestor on replay.
+      linkRotation(db, row.jti, access.jti);
+      return minted;
     })();
   } catch (err) {
     // Concurrent rotation: a sibling refresh of the same row already