@openparachute/hub 0.7.3-rc.1 → 0.7.3-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.3-rc.1",
+  "version": "0.7.3-rc.3",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/admin-agent-grants.test.ts

@@ -1353,6 +1353,119 @@ describe("GET /oauth/agent-grant/callback", () => {
   });
 });
 
+// === returnTo: send the operator back to where they started ================
+//
+// The OAuth-consent round-trip used to dead-end on a "close this tab" page. A
+// same-origin (hub-relative) `returnTo` on the approve body is stashed on the
+// flow + 302'd to on success (with `?mcp_connected=1`). The open-redirect guard
+// (`isSafeHubReturnTo`, reused) is the load-bearing property: an off-origin /
+// scheme-relative value is dropped at stash time and never lands in Location.
+describe("approve(mcp) + callback — returnTo round-trip", () => {
+  async function startFlowWithBody(body: Record<string, unknown>): Promise<string> {
+    const bearer = await moduleBearer();
+    const cookie = await operatorCookie();
+    const created = await json(
+      await dispatch(
+        bearerReq("PUT", "/admin/grants", bearer, {
+          agent: "a",
+          connection: { kind: "mcp", target: "https://remote.test/mcp" },
+        }),
+      ),
+    );
+    const id = created.id as string;
+    await dispatch(cookieReq("POST", `/admin/grants/${id}/approve`, cookie, body));
+    return id;
+  }
+
+  test("approve stashes a valid same-origin returnTo on the flow", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "/admin/grants" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBe("/admin/grants");
+  });
+
+  test("approve drops an off-origin returnTo (absolute URL) — open-redirect guard", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "https://evil.example/steal" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBeUndefined();
+  });
+
+  test("approve drops a scheme-relative returnTo (//host) — open-redirect guard", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "//evil.example/steal" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBeUndefined();
+  });
+
+  test("approve drops a `..` path-traversal returnTo — open-redirect guard", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "/admin/../../etc/passwd" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBeUndefined();
+  });
+
+  test("approve drops a PERCENT-ENCODED `..` returnTo (%2e%2e) — open-redirect guard", async () => {
+    // `new URL()` decodes %2e%2e before emitting the redirect path, so the guard
+    // must reject the encoded form too, not just the literal `..`.
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "/%2e%2e/etc/passwd" });
+    const flow = getFlowByState(harness.flowsStorePath, "fixed-state");
+    expect(flow?.returnTo).toBeUndefined();
+  });
+
+  test("callback 302-redirects to a valid returnTo (with mcp_connected=1) on success", async () => {
+    currentOAuth = fakeOAuth();
+    const id = await startFlowWithBody({ returnTo: "/admin/grants?agent=a" });
+    const res = await callback("?code=ok&state=fixed-state");
+    expect(res.status).toBe(302);
+    const location = res.headers.get("location") ?? "";
+    expect(location).toContain("/admin/grants");
+    expect(location).toContain("agent=a");
+    expect(location).toContain("mcp_connected=1");
+    // Same-origin only — never a host/scheme in Location.
+    expect(location.startsWith("/")).toBe(true);
+    expect(location.startsWith("//")).toBe(false);
+    // The grant still flipped to approved (the success side-effects all ran).
+    expect(readGrants(harness.storePath).find((r) => r.id === id)?.status).toBe("approved");
+  });
+
+  test("callback overwrites a pre-existing mcp_connected param rather than duplicating it", async () => {
+    currentOAuth = fakeOAuth();
+    await startFlowWithBody({ returnTo: "/admin/grants?mcp_connected=0" });
+    const res = await callback("?code=ok&state=fixed-state");
+    expect(res.status).toBe(302);
+    const location = res.headers.get("location") ?? "";
+    expect(location).toContain("mcp_connected=1");
+    expect(location).not.toContain("mcp_connected=0");
+    // exactly one occurrence (searchParams.set semantics, not append)
+    expect(location.match(/mcp_connected=/g)?.length).toBe(1);
+  });
+
+  test("callback falls back to the close-tab HTML when no returnTo was stashed", async () => {
+    currentOAuth = fakeOAuth();
+    const id = await startFlowWithBody({}); // no returnTo
+    const res = await callback("?code=ok&state=fixed-state");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(await res.text()).toContain("Connected");
+    expect(readGrants(harness.storePath).find((r) => r.id === id)?.status).toBe("approved");
+  });
+
+  test("callback falls back to the close-tab HTML for an unsafe returnTo (never 302s off-origin)", async () => {
+    currentOAuth = fakeOAuth();
+    // The unsafe value was already dropped at stash time, so the callback has no
+    // returnTo to honor — it renders the back-compat page rather than redirecting.
+    const id = await startFlowWithBody({ returnTo: "https://evil.example/steal" });
+    const res = await callback("?code=ok&state=fixed-state");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(res.headers.get("location")).toBeNull();
+    expect(await res.text()).toContain("Connected");
+    expect(readGrants(harness.storePath).find((r) => r.id === id)?.status).toBe("approved");
+  });
+});
+
 describe("material(mcp) — auto-refresh", () => {
   // Drive a grant to approved-via-OAuth, with expiry in the (near) past/future.
   async function approvedViaOAuth(expiresAt: string): Promise<string> {

package/src/__tests__/jwt-sign.test.ts

@@ -10,7 +10,9 @@ import {
   RefreshTokenInsertError,
   findRefreshToken,
   findTokenRowByJti,
+  linkRotation,
   listActiveRevocations,
+  liveFamilyRefreshRows,
   recordTokenMint,
   revokeTokenByJti,
   signAccessToken,
@@ -623,3 +625,80 @@ describe("token registry (hub#212 Phase 1)", () => {
     }
   });
 });
+
+// hub#685 — rotation-grace primitives. The grace decision in
+// `handleTokenRefresh` is built on these two helpers; unit-cover them
+// directly so the security-load-bearing predecessor check has a tight test.
+describe("rotation grace primitives (hub#685)", () => {
+  test("rotatedTo is null on a freshly minted row, set by linkRotation", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      rotateSigningKey(db);
+      const u = await createUser(db, "owner", "pw");
+      signRefreshToken(db, {
+        jti: "pred",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-1",
+      });
+      expect(findTokenRowByJti(db, "pred")?.rotatedTo).toBeNull();
+
+      signRefreshToken(db, {
+        jti: "succ",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-1",
+      });
+      linkRotation(db, "pred", "succ");
+      expect(findTokenRowByJti(db, "pred")?.rotatedTo).toBe("succ");
+      // Successor itself has not rotated yet.
+      expect(findTokenRowByJti(db, "succ")?.rotatedTo).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("liveFamilyRefreshRows returns only un-revoked, un-expired refresh rows in the family", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      rotateSigningKey(db);
+      const u = await createUser(db, "owner", "pw");
+      const t0 = new Date("2026-06-24T00:00:00Z");
+      for (const jti of ["a", "b", "c"]) {
+        signRefreshToken(db, {
+          jti,
+          userId: u.id,
+          clientId: "parachute-hub",
+          scopes: ["vault:read"],
+          familyId: "fam-x",
+          now: () => t0,
+        });
+      }
+      // A different family — must never leak in.
+      signRefreshToken(db, {
+        jti: "other",
+        userId: u.id,
+        clientId: "parachute-hub",
+        scopes: ["vault:read"],
+        familyId: "fam-y",
+        now: () => t0,
+      });
+      // Revoke one of the three.
+      revokeTokenByJti(db, "b", t0);
+
+      const live = liveFamilyRefreshRows(db, "fam-x", t0)
+        .map((r) => r.jti)
+        .sort();
+      expect(live).toEqual(["a", "c"]);
+
+      // Evaluated PAST the 30-day TTL: every row in the family is expired,
+      // so none count as a live tip — the grace path can't rotate into one.
+      const afterExpiry = new Date(t0.getTime() + REFRESH_TOKEN_TTL_MS + 1);
+      expect(liveFamilyRefreshRows(db, "fam-x", afterExpiry)).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/__tests__/oauth-handlers.test.ts

@@ -14,7 +14,12 @@ import {
   openFirstClientAutoApproveWindow,
   setSetting,
 } from "../hub-settings.ts";
-import { findTokenRowByJti, validateAccessToken } from "../jwt-sign.ts";
+import {
+  REFRESH_GRACE_MS,
+  findTokenRowByJti,
+  signRefreshToken,
+  validateAccessToken,
+} from "../jwt-sign.ts";
 import {
   authorizationServerMetadata,
   buildServicesCatalog,
@@ -2262,6 +2267,7 @@ describe("handleToken — full OAuth dance", () => {
         refresh_token: initial.refresh_token,
         client_id: reg.client.clientId,
       });
+      const rotateAt = new Date("2026-06-24T00:00:00Z");
       const refreshRes = await handleToken(
         db,
         new Request(`${ISSUER}/oauth/token`, {
@@ -2269,13 +2275,16 @@ describe("handleToken — full OAuth dance", () => {
           body: refreshForm,
           headers: { "content-type": "application/x-www-form-urlencoded" },
         }),
-        { issuer: ISSUER },
+        { issuer: ISSUER, now: () => rotateAt },
       );
       expect(refreshRes.status).toBe(200);
       const rotated = (await refreshRes.json()) as { refresh_token: string };
       expect(rotated.refresh_token).not.toBe(initial.refresh_token);
 
-      // Old refresh token should now fail (revoked).
+      // Old refresh token replayed PAST the one-generation grace window
+      // should fail (revoked) — the immediate-predecessor grace (hub#685)
+      // only tolerates a replay within REFRESH_GRACE_MS. Replay an hour
+      // later: genuine zero-tolerance rejection.
       const replayRes = await handleToken(
         db,
         new Request(`${ISSUER}/oauth/token`, {
@@ -2283,7 +2292,7 @@ describe("handleToken — full OAuth dance", () => {
           body: refreshForm,
           headers: { "content-type": "application/x-www-form-urlencoded" },
         }),
-        { issuer: ISSUER },
+        { issuer: ISSUER, now: () => new Date(rotateAt.getTime() + 60 * 60 * 1000) },
       );
       expect(replayRes.status).toBe(400);
       const err = (await replayRes.json()) as Record<string, unknown>;
@@ -4125,6 +4134,284 @@ describe("refresh-token rotation + /oauth/revoke (#73)", () => {
     }
   });
 
+  // hub#685 — one-generation rotation grace window. A benign concurrent /
+  // retried refresh of the *immediately-previous* (just-rotated) token within
+  // REFRESH_GRACE_MS must NOT revoke the family (multi-tab SPA, bfcache/
+  // stale-tab resume, network retry). Genuine theft — an older ancestor, or
+  // any replay past the window — MUST still revoke the family.
+  describe("rotation grace window (hub#685)", () => {
+    function liveRefreshCount(
+      db: Awaited<ReturnType<typeof makeDb>>["db"],
+      familyId: string,
+    ): number {
+      const r = db
+        .query<{ n: number }, [string]>(
+          "SELECT COUNT(*) AS n FROM tokens WHERE family_id = ? AND revoked_at IS NULL AND refresh_token_hash IS NOT NULL",
+        )
+        .get(familyId);
+      return r?.n ?? -1;
+    }
+
+    async function refreshAt(
+      db: Awaited<ReturnType<typeof makeDb>>["db"],
+      clientId: string,
+      refreshToken: string,
+      at: Date,
+    ): Promise<Response> {
+      return handleToken(
+        db,
+        tokenRequest(
+          new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: clientId,
+          }),
+        ),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest, now: () => at },
+      );
+    }
+
+    test("benign concurrent refresh of the immediate predecessor within the window succeeds, no family revocation", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        // First (legitimate) rotation at t0 — `initial` becomes the immediate
+        // predecessor; rotated1 is the single live tip.
+        const r1 = await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+        expect(r1.status).toBe(200);
+        const rotated1 = (await r1.json()) as { refresh_token: string };
+        expect(liveRefreshCount(db, family)).toBe(1);
+
+        // A moment later (5s, well within REFRESH_GRACE_MS) a stale tab /
+        // retry replays `initial`. Benign: succeeds, and converges the client
+        // onto the lineage rather than revoking the family.
+        const replay = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 5_000),
+        );
+        expect(replay.status).toBe(200);
+        const replayed = (await replay.json()) as { refresh_token: string; access_token: string };
+        expect(replayed.refresh_token).toBeTruthy();
+        expect(replayed.access_token).toBeTruthy();
+
+        // No family-wide revocation: exactly one live refresh row remains
+        // (the grace path rotated the tip → its successor is the new tip).
+        expect(liveRefreshCount(db, family)).toBe(1);
+
+        // The token handed back is usable for a normal subsequent refresh.
+        const next = await refreshAt(
+          db,
+          reg.client.clientId,
+          replayed.refresh_token,
+          new Date(t0.getTime() + 10_000),
+        );
+        expect(next.status).toBe(200);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("genuine reuse of an OLDER ancestor (two generations back) revokes the family even within the window", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        // Two legitimate rotations: initial → rotated1 → rotated2. `initial`
+        // is now an ancestor (its successor rotated1 is itself revoked).
+        const r1 = await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+        const rotated1 = (await r1.json()) as { refresh_token: string };
+        const r2 = await refreshAt(
+          db,
+          reg.client.clientId,
+          rotated1.refresh_token,
+          new Date(t0.getTime() + 1_000),
+        );
+        expect(r2.status).toBe(200);
+
+        // Replay the ANCESTOR `initial` still within the window. Condition (b)
+        // fails — its successor (rotated1) is not the live tip — so this is
+        // treated as theft: family revoked.
+        const replay = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 2_000),
+        );
+        expect(replay.status).toBe(400);
+        expect(((await replay.json()) as Record<string, unknown>).error).toBe("invalid_grant");
+        expect(liveRefreshCount(db, family)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("replay of the immediate predecessor AFTER the window revokes the family", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        const r1 = await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+        expect(r1.status).toBe(200);
+
+        // Replay the immediate predecessor 1ms PAST the window. Condition (a)
+        // fails: zero-tolerance theft handling applies.
+        const replay = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + REFRESH_GRACE_MS + 1),
+        );
+        expect(replay.status).toBe(400);
+        expect(((await replay.json()) as Record<string, unknown>).error).toBe("invalid_grant");
+        expect(liveRefreshCount(db, family)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("window boundary: exactly at the edge succeeds, one ms past fails", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+
+        // Just inside (=== REFRESH_GRACE_MS): benign success, family intact.
+        const aPair = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const aFamily = familyIdFor(db, aPair.refresh_token);
+        const a0 = new Date("2026-06-24T00:00:00Z");
+        await refreshAt(db, reg.client.clientId, aPair.refresh_token, a0);
+        const inEdge = await refreshAt(
+          db,
+          reg.client.clientId,
+          aPair.refresh_token,
+          new Date(a0.getTime() + REFRESH_GRACE_MS),
+        );
+        expect(inEdge.status).toBe(200);
+        expect(liveRefreshCount(db, aFamily)).toBe(1);
+
+        // One ms past the edge: theft handling, family revoked.
+        const bPair = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const bFamily = familyIdFor(db, bPair.refresh_token);
+        const b0 = new Date("2026-06-24T01:00:00Z");
+        await refreshAt(db, reg.client.clientId, bPair.refresh_token, b0);
+        const outEdge = await refreshAt(
+          db,
+          reg.client.clientId,
+          bPair.refresh_token,
+          new Date(b0.getTime() + REFRESH_GRACE_MS + 1),
+        );
+        expect(outEdge.status).toBe(400);
+        expect(liveRefreshCount(db, bFamily)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("repeated benign replays of the same predecessor each converge on a live tip (idempotent-equivalent)", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+
+        // First benign replay of `initial`: succeeds, rotates the tip.
+        const replay1 = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 1_000),
+        );
+        expect(replay1.status).toBe(200);
+        expect(liveRefreshCount(db, family)).toBe(1);
+
+        // A SECOND replay of the SAME predecessor `initial`. Its successor is
+        // now revoked (the first replay rotated the tip), so `initial` is no
+        // longer the direct predecessor of the single live tip → theft. The
+        // grace window protects exactly ONE generation, not unbounded replay.
+        const replay2 = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 2_000),
+        );
+        expect(replay2.status).toBe(400);
+        expect(liveRefreshCount(db, family)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("already-forked family (multiple live tips) does NOT take the grace path — family revoked", async () => {
+      const { db, cleanup } = await makeDb();
+      try {
+        const user = await createUser(db, "owner", "pw");
+        const session = createSession(db, { userId: user.id });
+        const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+        const initial = await mintInitialPair(db, reg.client.clientId, user.id, session.id);
+        const family = familyIdFor(db, initial.refresh_token);
+
+        const t0 = new Date("2026-06-24T00:00:00Z");
+        // One legitimate rotation → `initial` is the immediate predecessor of
+        // the single live tip (live count == 1, the benign precondition).
+        const r1 = await refreshAt(db, reg.client.clientId, initial.refresh_token, t0);
+        expect(r1.status).toBe(200);
+        expect(liveRefreshCount(db, family)).toBe(1);
+
+        // Inject a SECOND live refresh row into the same family — simulating a
+        // family that has already forked into multiple live lineages (an
+        // already-compromised state). Now live count != 1, so `tip` is null.
+        signRefreshToken(db, {
+          jti: "injected-fork-jti",
+          userId: user.id,
+          clientId: reg.client.clientId,
+          scopes: ["vault:default:read"],
+          familyId: family,
+          now: () => t0,
+        });
+        expect(liveRefreshCount(db, family)).toBe(2);
+
+        // Replay the immediate predecessor WITHIN the window. Even though (a)
+        // holds and `initial.rotatedTo` is set, the single-live-tip check
+        // fails (2 live rows) → no grace → zero-tolerance family revocation.
+        const replay = await refreshAt(
+          db,
+          reg.client.clientId,
+          initial.refresh_token,
+          new Date(t0.getTime() + 1_000),
+        );
+        expect(replay.status).toBe(400);
+        expect(((await replay.json()) as Record<string, unknown>).error).toBe("invalid_grant");
+        expect(liveRefreshCount(db, family)).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
   test("/oauth/revoke refresh_token: revokes the row, second use rejected", async () => {
     const { db, cleanup } = await makeDb();
     try {

package/src/admin-agent-grants.ts

@@ -80,6 +80,7 @@ import {
 } from "./jwt-sign.ts";
 import { type OAuthClient, deriveVaultScopeFromMcpUrl, realOAuthClient } from "./oauth-client.ts";
 import { type PendingFlow, deleteFlow, getFlowByState, putFlow } from "./oauth-flows-store.ts";
+import { isSafeHubReturnTo } from "./oauth-handlers.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
 import { validateVaultName } from "./vault-name.ts";
@@ -630,10 +631,15 @@ async function approveGrant(req: Request, id: string, deps: AgentGrantsDeps): Pr
   const grant = getGrant(deps.storePath, id);
   if (!grant) return jsonError(404, "not_found", `no grant ${id}`);
 
-  let body: { token?: unknown } = {};
+  // `returnTo` is consumed ONLY by the mcp/OAuth path (approveMcpGrant), which
+  // is the one approve flow that hands the browser off to a remote consent
+  // screen and needs somewhere to land on return. vault/service approvals
+  // complete synchronously and return JSON — there's no redirect, so they
+  // ignore `returnTo` by design.
+  let body: { token?: unknown; returnTo?: unknown } = {};
   try {
     const raw = await req.text();
-    if (raw.trim().length > 0) body = JSON.parse(raw) as { token?: unknown };
+    if (raw.trim().length > 0) body = JSON.parse(raw) as { token?: unknown; returnTo?: unknown };
   } catch {
     return jsonError(400, "invalid_request", "body must be JSON when present");
   }
@@ -748,7 +754,7 @@ async function approveGrant(req: Request, id: string, deps: AgentGrantsDeps): Pr
  */
 async function approveMcpGrant(
   grant: GrantRecord,
-  body: { token?: unknown },
+  body: { token?: unknown; returnTo?: unknown },
   deps: AgentGrantsDeps,
   approvedAt: string,
 ): Promise<Response> {
@@ -850,6 +856,16 @@ async function approveMcpGrant(
       ? discovery.scopesSupported.join(" ")
       : undefined;
 
+  // OPTIONAL `returnTo` — the same-origin (hub-relative) page the operator
+  // started from (the agent ops surface / admin grants page). Stash it on the
+  // flow ONLY when it passes the shared open-redirect guard; absent/invalid →
+  // omit it (the callback then renders the back-compat close-tab page). This is
+  // the open-redirect-load-bearing check — reuse, don't reinvent.
+  const returnTo =
+    typeof body.returnTo === "string" && isSafeHubReturnTo(body.returnTo)
+      ? body.returnTo
+      : undefined;
+
   const flow: PendingFlow = {
     state,
     grantId: grant.id,
@@ -861,6 +877,7 @@ async function approveMcpGrant(
     mcpUrl,
     ...(scope ? { scope } : {}),
     redirectUri,
+    ...(returnTo ? { returnTo } : {}),
     createdAt: (deps.now?.() ?? new Date()).toISOString(),
   };
   putFlow(deps.flowsStorePath, flow, (deps.now?.() ?? new Date()).getTime());
@@ -1040,6 +1057,17 @@ export async function handleOAuthGrantCallback(
   // NEVER log a token.
   console.log(`agent grant approved: id=${grant.id} agent=${grant.agent} kind=mcp mode=oauth`);
 
+  // If the operator started from a hub page (agent ops surface / admin grants),
+  // send them back there instead of a dead-end "close this tab" screen. Re-run
+  // the open-redirect guard DEFENSIVELY at redirect time (the value was already
+  // gated at stash time; this is belt-and-suspenders against a tampered store).
+  // Append `?mcp_connected=1` (preserving any existing query) so the SPA can
+  // react (toast / refetch the grant). Absent/invalid returnTo → the
+  // back-compat close-tab page.
+  if (flow.returnTo && isSafeHubReturnTo(flow.returnTo)) {
+    return redirectToReturn(flow.returnTo);
+  }
+
   return htmlPage(
     200,
     "Connected",
@@ -1047,6 +1075,26 @@ export async function handleOAuthGrantCallback(
   );
 }
 
+/**
+ * 302 back to a same-origin (hub-relative) `returnTo`, appending
+ * `mcp_connected=1` so the SPA can show a success toast / refetch. The caller
+ * MUST have already passed `returnTo` through `isSafeHubReturnTo` — this builds
+ * the URL against a fixed dummy origin purely to merge the query param
+ * correctly, then emits only the path+query (never the origin), so a
+ * scheme-relative value can't leak through into the Location header.
+ */
+function redirectToReturn(returnTo: string): Response {
+  // Parse against a fixed base so query-string merging is correct even when
+  // returnTo already carries `?...`. Only `pathname + search + hash` is emitted.
+  const u = new URL(returnTo, "http://hub.invalid");
+  u.searchParams.set("mcp_connected", "1");
+  const location = `${u.pathname}${u.search}${u.hash}`;
+  return new Response(null, {
+    status: 302,
+    headers: { location, "cache-control": "no-store" },
+  });
+}
+
 /** Minimal server-rendered HTML — NEVER carries a token. */
 function htmlPage(status: number, heading: string, message: string): Response {
   const html = `<!doctype html>

package/src/hub-db.ts

@@ -451,6 +451,29 @@ const MIGRATIONS: readonly Migration[] = [
       ALTER TABLE invites ADD COLUMN username TEXT;
     `,
   },
+  {
+    version: 14,
+    sql: `
+      -- Refresh-token rotation grace window (hub#685). Records the successor
+      -- a refresh-token row rotated INTO, so the refresh handler can tell the
+      -- *immediately-previous* token (the single benign concurrent/retried
+      -- refresh a multi-tab / bfcache / network-retry client legitimately
+      -- presents) apart from a genuine replay of an older ancestor (theft).
+      --
+      -- \`rotated_to\` is the jti of the row minted when this row rotated. NULL
+      -- on every row that has not (yet) rotated: live tokens, revoked-by-
+      -- /oauth/revoke tokens, revoked-by-family-sweep tokens, and every
+      -- pre-v14 row (no backfill — pre-v14 rotations left no successor link,
+      -- so they fall through to the zero-tolerance theft path exactly as
+      -- before; the grace window only ever helps rows minted post-v14).
+      --
+      -- The successor link is the ONLY structural ordering signal we need:
+      -- created_at alone can't distinguish the direct predecessor from an
+      -- older ancestor under burst issuance (ties), and the grace decision is
+      -- security-load-bearing, so it must be exact, not heuristic.
+      ALTER TABLE tokens ADD COLUMN rotated_to TEXT;
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {

package/src/jwt-sign.ts

@@ -32,6 +32,18 @@ import { getActiveSigningKey, getAllPublicKeys } from "./signing-keys.ts";
 
 export const ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
 export const REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * One-generation rotation grace window (hub#685). When a presented refresh
+ * token has already been rotated (revoked), a refresh of the *immediately-
+ * previous* token within this window is treated as a benign concurrent /
+ * retried refresh (multi-tab SPA, bfcache/stale-tab resume, a network retry)
+ * rather than theft — it converges the client on the live tip instead of
+ * revoking the whole family. The window is deliberately short: it tolerates
+ * the brief overlap of a real client racing itself, NOT a delayed replay.
+ * Genuine theft (an OLDER ancestor, or ANY replay past the window) still
+ * revokes the family per RFC 6819 §5.2.2.3. See `handleTokenRefresh`.
+ */
+export const REFRESH_GRACE_MS = 30_000;
 export const SIGNING_ALGORITHM = "RS256";
 
 export interface SignAccessTokenOpts {
@@ -529,6 +541,14 @@ export interface RefreshTokenRow {
   createdVia: TokenCreatedVia;
   /** JSON-encoded fine-grained constraints (auth-architecture-shape.md §11.3). */
   permissions: string | null;
+  /**
+   * jti of the refresh-token row this row rotated INTO (set by
+   * `linkRotation` inside the rotation transaction). NULL until this row
+   * rotates, and NULL on every pre-v14 row. Powers the one-generation
+   * rotation grace window (hub#685): only the row whose `rotatedTo` is the
+   * family's single live tip is the benign immediate-predecessor.
+   */
+  rotatedTo: string | null;
 }
 
 /**
@@ -553,6 +573,7 @@ interface TokenRowDb {
   permissions: string | null;
   created_via: string;
   subject: string | null;
+  rotated_to: string | null;
 }
 
 function rowToRefreshToken(row: TokenRowDb): RefreshTokenRow {
@@ -568,6 +589,7 @@ function rowToRefreshToken(row: TokenRowDb): RefreshTokenRow {
     createdAt: row.created_at,
     createdVia: (row.created_via as TokenCreatedVia) ?? "oauth_refresh",
     permissions: row.permissions,
+    rotatedTo: row.rotated_to ?? null,
   };
 }
 
@@ -599,3 +621,39 @@ export function revokeFamily(db: Database, familyId: string, now: Date): number
     .run(now.toISOString(), familyId);
   return Number(res.changes);
 }
+
+/**
+ * Record that `predecessorJti` rotated INTO `successorJti`. Called INSIDE the
+ * rotation transaction (alongside the revoke-old + insert-new) so the
+ * successor link, the predecessor's `revoked_at`, and the new row commit or
+ * roll back as a unit. Powers the one-generation rotation grace window
+ * (hub#685): a benign concurrent/retried refresh of the immediate
+ * predecessor can be told apart from a genuine replay of an older ancestor.
+ */
+export function linkRotation(db: Database, predecessorJti: string, successorJti: string): void {
+  db.prepare("UPDATE tokens SET rotated_to = ? WHERE jti = ?").run(successorJti, predecessorJti);
+}
+
+/**
+ * The live (un-revoked AND un-expired) refresh-token rows in a family as of
+ * `now`. The grace window asks "is there exactly one live tip, and is the
+ * presented (revoked) row its direct predecessor?" — so callers inspect this
+ * set. Two filters matter:
+ *   - `refresh_token_hash IS NOT NULL` — the family can also contain
+ *     access-token rows sharing the jti/family, irrelevant to rotation lineage.
+ *   - `expires_at > now` — an expired-but-not-revoked tip is not a valid
+ *     rotation target, so the grace path must never rotate into it. Keeping
+ *     "live" exhaustive here means the single caller doesn't re-check expiry.
+ */
+export function liveFamilyRefreshRows(
+  db: Database,
+  familyId: string,
+  now: Date,
+): RefreshTokenRow[] {
+  const rows = db
+    .query<TokenRowDb, [string, string]>(
+      "SELECT * FROM tokens WHERE family_id = ? AND revoked_at IS NULL AND refresh_token_hash IS NOT NULL AND expires_at > ?",
+    )
+    .all(familyId, now.toISOString());
+  return rows.map(rowToRefreshToken);
+}

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,
@@ -1883,6 +1887,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 +1932,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 +2227,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 +2279,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 +2328,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 +2336,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