@synap-core/sdk 1.3.0 → 1.5.0

package/src/connect/auth.ts

@@ -8,23 +8,35 @@
  *
  * Handlers:
  *   GET  <metadata>    the app's client metadata document (its client_id URL)
- *   POST <connect>     form { pod, next?, space? } → 303 to the pod's /authorize
+ *   POST <connect>     form { pod, next?, space?, prompt? } → 303 to the pod's /authorize
  *   GET  <callback>    the pod's answer → sealed session cookie → 303 to `next`
  *   POST <disconnect>  revoke at the pod (best effort), clear the cookie → 303
+ *   POST <cloud>       form { next?, space?, prompt? } → 303 to the Synap Cloud pod chooser
+ *   GET  <cloud>       the chooser's return (?iss&state, state checked) → 303 to the pod's /authorize
+ *
+ * `prompt=consent` asks for the pod's consent screen again (widen or narrow
+ * what the app may touch); without it a person already connected to that pod
+ * goes straight to `next`. Either way a sign-in is a fresh PKCE + state flow.
  *
  * `connect` and `disconnect` change state, so they are POST and same-origin
  * only (Origin, else Sec-Fetch-Site): a third-party page cannot start a
  * sign-in into an attacker's pod for a visitor (login CSRF) or sign them out.
  * Failures redirect with `?error=<ConnectErrorCode>` and nothing else.
+ *
+ * Each successful sign-in or refresh also sets a marker cookie holding the
+ * pod's URL and no secret (`markerCookie`), so a connection that lapsed reads
+ * as "expired" (`readLapsed`, `RefreshOutcome.lapsed`), not "never connected".
  */
+import { acceptCloudReturn, cloudBaseUrl, CLOUD_TRANSACTION_TTL_MS, startCloudConnect } from "./cloud";
 import { safeNextPath, canonicalPodUrl } from "./discovery";
 import { ConnectError, isConnectError } from "./errors";
 import { serializeCookie, parseCookies } from "./encoding";
 import { createPodClient, type PodClient, type PodClientOptions } from "./client";
 import { assertPermissions, handleCallback, refreshConnection, revokeConnection, startConnect, TRANSACTION_TTL_MS } from "./flow";
 import { assertServerRuntime } from "./guard";
+import { isIpLiteral, LOOPBACK_HOSTS, SPACE_HINT_RE } from "./rules";
 import { assertAppSecret, type AppSecret } from "./seal";
-import { applySetCookies, cookieNames, createSealedCookieStore, type ConnectionStore } from "./store";
+import { applySetCookies, cookieNames, createSealedCookieStore, markerCookie, readMarker, type ConnectionStore } from "./store";
 import type { AppRequest, ClientMetadataDocument, PodConnection } from "./types";
 
 export interface PodAppPaths {
@@ -33,6 +45,8 @@ export interface PodAppPaths {
   connect: string;
   callback: string;
   disconnect: string;
+  /** Synap Cloud: POST starts it, GET is the pod chooser's return (forwarded from the connect page). */
+  cloud: string;
   /** The app's connect page (also the CIMD `initiate_login_uri`). */
   connectPage: string;
   /** Where a failed callback lands, with `?error=<code>`. */
@@ -46,6 +60,7 @@ export const DEFAULT_PATHS: PodAppPaths = {
   connect: "/api/synap/connect",
   callback: "/api/synap/callback",
   disconnect: "/api/synap/disconnect",
+  cloud: "/api/synap/cloud",
   connectPage: "/connect",
   resultPage: "/connect/result",
   afterConnect: "/",
@@ -55,7 +70,12 @@ export const DEFAULT_PATHS: PodAppPaths = {
 export const REFRESH_WINDOW_MS = 5 * 60 * 1000;
 
 export interface PodAppAuthConfig {
-  /** The app's origin, e.g. https://studio.example.com (http only on localhost). */
+  /**
+   * The app's origin, e.g. https://studio.example.com. `http://localhost` is
+   * accepted for the SDK's MOCK pod only: every real pod, a local one
+   * included, refuses an http client_id and redirect_uri, so an app that signs
+   * in to a real pod runs on https (a tunnel in development).
+   */
   appUrl: string;
   /** Shown on the pod's consent screen (at most 100 characters). */
   clientName: string;
@@ -70,7 +90,16 @@ export interface PodAppAuthConfig {
   store?: ConnectionStore;
   /** RFC 8707 resource asked for (default the Hub API). */
   resource?: "api/hub" | "mcp" | null;
-  /** Accept pods on http://localhost (development against a local pod). */
+  /**
+   * The Synap Control Plane's URL (e.g. https://api.synap.live): offers
+   * "Continue with Synap Cloud" (`cloudConnectAvailable`). Unset = address only.
+   */
+  cloudUrl?: string | null;
+  /**
+   * Accept a pod (and a Control Plane) on http://localhost: development
+   * against the SDK's mock pod (`@synap-core/sdk/testing`). A real local pod
+   * still refuses an app that is not on https (see `appUrl`).
+   */
   allowInsecureLoopback?: boolean;
   /** Developer log of every refused sign-in; messages never carry a token. Default: console.warn. */
   onError?: (error: ConnectError, where: "connect" | "callback" | "disconnect" | "refresh") => void;
@@ -89,9 +118,9 @@ export type RefreshStatus =
   | "refreshed"
   /** The refresh failed (a lost rotation race, the pod busy) but the access token still works: keep it, set nothing. */
   | "kept"
-  /** The access token is spent and cannot be renewed: connect again. */
+  /** The access token is spent and cannot be renewed (lapsed, or the pod moved: `error.code`): connect again. The session cookie is cleared (the marker stays). */
   | "expired"
-  /** The pod refused the refresh token (access removed): connect again. */
+  /** The pod refused the refresh token (access removed): connect again. The session cookie is cleared (the marker stays). */
   | "revoked"
   /** The pod could not be reached and the access token is spent: try later. */
   | "unavailable";
@@ -105,6 +134,36 @@ export interface RefreshOutcome {
   /** The request's Cookie header with the refreshed value, to forward to the render (null = unchanged). */
   cookieHeader: string | null;
   error?: ConnectError;
+  /**
+   * With `none`: this browser WAS connected to that pod and the connection
+   * lapsed (its sealed cookie is gone, idle past its life). Say "expired,
+   * connect again" with the pod pre-filled, not "connect your pod".
+   */
+  lapsed?: { podUrl: string };
+}
+
+export interface RefreshOptions {
+  /**
+   * Rotate now, whatever the access token's expiry says: the pod refused it
+   * (a Hub call answered `unauthorized` with `refreshable`). Needs a refresh
+   * token. If the pod refuses the refresh too, the outcome is `revoked` (or
+   * `expired`), never `kept`: the access token is known dead.
+   */
+  force?: boolean;
+}
+
+export interface PodAppClientOptions extends PodClientOptions {
+  /**
+   * Where the client may set cookies (a route handler, a server action): after
+   * a 401 it then renews the connection ONCE (rotate, seal, `persist` the
+   * Set-Cookie values, retry the request once). The rotation spends the old
+   * refresh token, so it is never done where its result cannot be stored: a
+   * server component passes no `persist`, and a 401 there answers
+   * `unauthorized` with `refreshable` (see `RefreshOptions.force`).
+   */
+  persist?: (setCookies: string[]) => void | Promise<void>;
+  /** The request (or its Cookie header) the connection came from: chunks a larger old cookie left are cleared. */
+  request?: Request | string | null;
 }
 
 export interface PodAppAuth {
@@ -112,11 +171,17 @@ export interface PodAppAuth {
   redirectUri: string;
   metadata: ClientMetadataDocument;
   paths: PodAppPaths;
+  /** Whether "Continue with Synap Cloud" can be offered (`cloudUrl` is configured). */
+  cloudConnectAvailable: boolean;
   handlers: {
     clientMetadata(request: Request): Promise<Response>;
     connect(request: Request): Promise<Response>;
     callback(request: Request): Promise<Response>;
     disconnect(request: Request): Promise<Response>;
+    /** POST: start a Synap Cloud sign-in (same-origin, form { next?, space?, prompt? }). */
+    cloudConnect(request: Request): Promise<Response>;
+    /** GET: the Synap Cloud pod chooser's return (`?iss&state`), checked against this browser's cookie. */
+    cloudReturn(request: Request): Promise<Response>;
   };
   /**
    * The stored connection (no refresh, no expiry check), or null. Takes the
@@ -124,15 +189,54 @@ export interface PodAppAuth {
    * pass `(await headers()).get("cookie")`).
    */
   readConnection(source: Request | string | null): Promise<PodConnection | null>;
-  /** For `proxy.ts` / a route handler: rotate near expiry, lost-race safe. */
-  refreshIfNeeded(request: Request): Promise<RefreshOutcome>;
-  /** A Hub REST client for the connection. */
-  client(connection: PodConnection, opts?: PodClientOptions): PodClient;
+  /**
+   * The pod this browser WAS connected to, when no connection is stored any
+   * more (it lapsed); null when one is stored or this browser never connected
+   * (or disconnected). Same sources as `readConnection`.
+   */
+  readLapsed(source: Request | string | null): Promise<{ podUrl: string } | null>;
+  /** For `proxy.ts` / a route handler: rotate near expiry (or now, `force`), lost-race safe. */
+  refreshIfNeeded(request: Request, opts?: RefreshOptions): Promise<RefreshOutcome>;
+  /** A Hub REST client for the connection (renewing it after a 401 when it can `persist`). */
+  client(connection: PodConnection, opts?: PodAppClientOptions): PodClient;
 }
 
-const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
 const TEMPLATE_SLUG_RE = /^[a-z0-9][a-z0-9._/-]{0,99}$/;
 const MAX_METADATA_BYTES = 5 * 1024;
+const MAX_REQUESTS = 32;
+/** How long a refused refresh is not asked again while the access token still works ("kept"). */
+const KEPT_RETRY_MS = 60_000;
+
+/** The pod's grant actions: the only verbs a pod app may ask for (client-metadata.ts `assertAppPermission`). */
+const GRANT_ACTIONS = ["read", "create", "update", "delete"];
+/** The review verbs only an official Synap app (`https://<id>.synap.live`) may ask for, spelled exactly. */
+const SYNAP_APP_REVIEW_PERMISSIONS = ["proposal.approve", "proposal.reject"];
+const PERMISSION_SEGMENT_RE = /^[a-z0-9][a-z0-9_-]*$/;
+
+function isSynapAppOrigin(origin: string): boolean {
+  return /^https:\/\/[a-z0-9]([a-z0-9-]*[a-z0-9])?\.synap\.live$/.test(origin);
+}
+
+/**
+ * One `synap_requests[].permission`, refused here exactly when the pod would
+ * refuse it: `<subject>[.<kind>].<action>`, lowercase, a kind only on
+ * `entity`, an action in the pod's grant actions (the review verbs only for a
+ * Synap app). Stricter on one point: no `*` at all (`can()` matches exactly).
+ */
+function assertAppPermission(permission: string, origin: string): void {
+  const segs = permission.split(".");
+  const fail = (why: string) => {
+    throw new ConnectError("misconfigured", `requests: "${permission}" ${why}`);
+  };
+  if (segs.length < 2 || segs.length > 3 || segs.some((seg) => !PERMISSION_SEGMENT_RE.test(seg))) {
+    fail("is not <subject>[.<kind>].<action> in lowercase (no *)");
+  }
+  if (segs.length === 3 && segs[0] !== "entity") fail(`names a kind, but "${segs[0]}" has none (only entity does)`);
+  if (SYNAP_APP_REVIEW_PERMISSIONS.includes(permission) && isSynapAppOrigin(origin)) return;
+  if (!GRANT_ACTIONS.includes(segs[segs.length - 1])) {
+    fail(`asks for "${segs[segs.length - 1]}", which an app cannot be granted (read, create, update, delete)`);
+  }
+}
 
 function appOriginOf(appUrl: string): { origin: string; secure: boolean } {
   let url: URL;
@@ -142,8 +246,11 @@ function appOriginOf(appUrl: string): { origin: string; secure: boolean } {
     throw new ConnectError("misconfigured", "appUrl is not a URL");
   }
   const secure = url.protocol === "https:";
-  if (!secure && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
-    throw new ConnectError("misconfigured", "appUrl must be https (http only on localhost)");
+  if (!secure && !(url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))) {
+    throw new ConnectError("misconfigured", "appUrl must be https (http only on localhost, for the SDK's mock pod)");
+  }
+  if (secure && isIpLiteral(url.hostname)) {
+    throw new ConnectError("misconfigured", "appUrl must use a domain name: the pod refuses an IP address client_id");
   }
   if (url.pathname !== "/" || url.search || url.hash || url.username || url.password) {
     throw new ConnectError("misconfigured", "appUrl is an origin: no path, query, fragment or credentials");
@@ -157,7 +264,12 @@ function assertPath(name: string, path: string): void {
   }
 }
 
-/** The CIMD document (spec 17 §6.1), validated the way the pod will validate it. */
+/**
+ * The app's client metadata document (its client_id URL serves it). Refuses,
+ * at setup, every document the pod would refuse at sign-in: the permissions
+ * (`assertAppPermission`), at most 32 requests counted as sent, duplicates
+ * included, an IP address origin, the 5 KB cap.
+ */
 export function buildClientMetadata(opts: {
   appUrl: string;
   clientName: string;
@@ -170,9 +282,13 @@ export function buildClientMetadata(opts: {
   for (const [name, path] of Object.entries(paths)) assertPath(name, path);
   const clientName = opts.clientName.trim();
   if (!clientName || clientName.length > 100) throw new ConnectError("misconfigured", "clientName must be 1-100 characters");
+  // The pod counts the entries as sent, before it drops duplicates.
+  if (opts.requests.length === 0 || opts.requests.length > MAX_REQUESTS) {
+    throw new ConnectError("misconfigured", `requests must hold 1-${MAX_REQUESTS} entries (duplicates count)`);
+  }
   assertPermissions(opts.requests.map((r) => r.permission));
   for (const r of opts.requests) {
-    if (r.permission.includes("*")) throw new ConnectError("misconfigured", "a permission cannot contain *");
+    assertAppPermission(r.permission, origin);
     if (typeof r.reason !== "string" || !r.reason.trim() || r.reason.length > 200) {
       throw new ConnectError("misconfigured", `the reason for ${r.permission} must be 1-200 characters`);
     }
@@ -231,9 +347,23 @@ async function readForm(request: Request): Promise<FormData | null> {
   }
 }
 
-function isPrefetchOrAsset(request: Request): boolean {
+/**
+ * A prefetch or a static asset: `refreshIfNeeded` answers `skipped` for these.
+ *
+ * LIMIT (Next.js 16 `proxy.ts` on the Node runtime): Next strips its router
+ * headers (`next-router-prefetch`, `rsc`, …, `FLIGHT_HEADERS` in
+ * next/dist/server/web/adapter.js) and the `_rsc` query BEFORE the proxy runs,
+ * so a router prefetch is invisible here. Skip prefetches in the proxy
+ * MATCHER, which still sees the raw headers:
+ *
+ *   export const config = { matcher: [{ source: "/((?!_next/static|_next/image|.*\\.\\w+$).*)",
+ *     missing: [{ type: "header", key: "next-router-prefetch" }, { type: "header", key: "purpose", value: "prefetch" }] }] };
+ *
+ * Route handlers and other frameworks see the headers, and this still checks them.
+ */
+export function isPrefetchOrAsset(request: Request): boolean {
   const h = request.headers;
-  if (h.get("next-router-prefetch") || h.get("x-middleware-prefetch")) return true;
+  if (h.get("next-router-prefetch") || h.get("next-router-segment-prefetch") || h.get("x-middleware-prefetch")) return true;
   if (/prefetch/i.test(h.get("purpose") ?? "") || /prefetch/i.test(h.get("sec-purpose") ?? "")) return true;
   const path = new URL(request.url).pathname;
   return path.startsWith("/_next/") || /\.[A-Za-z0-9]{1,8}$/.test(path);
@@ -245,6 +375,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
   const { origin, secure } = appOriginOf(config.appUrl);
   const paths: PodAppPaths = { ...DEFAULT_PATHS, ...config.paths };
   const metadata = buildClientMetadata({ ...config, paths });
+  const cloudUrl = config.cloudUrl?.trim() ? cloudBaseUrl(config.cloudUrl, config) : null;
   const clientId = metadata.client_id;
   const redirectUri = metadata.redirect_uris[0];
   const permissions = config.requests.map((r) => r.permission);
@@ -263,6 +394,42 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     return e;
   };
   const clearTx = serializeCookie(names.transaction, "", { maxAgeSec: 0, secure });
+  const clearCloud = serializeCookie(names.cloud, "", { maxAgeSec: 0, secure });
+  const clearMarker = serializeCookie(names.marker, "", { maxAgeSec: 0, secure });
+  const marker = (podUrl: string) => markerCookie(podUrl, { secure, name: names.marker });
+  const asRequest = (source: Request | string | null) =>
+    source instanceof Request ? source : new Request(origin, { headers: source ? { cookie: source } : {} });
+  const lapsedIn = (request: Request) => {
+    const podUrl = readMarker(request.headers.get("cookie"), { secure, name: names.marker, allowInsecureLoopback: config.allowInsecureLoopback });
+    return podUrl ? { podUrl } : null;
+  };
+
+  /** Off to the pod's consent: fresh PKCE + state, the transaction cookie set (extra cookies first). */
+  async function toPod(opts: { pod: string; next: string; space: string | null; prompt: "consent" | null }, extra: string[] = []) {
+    const started = await startConnect({
+      ...flow,
+      pod: opts.pod,
+      clientId,
+      redirectUri,
+      permissions,
+      secret: config.secret,
+      resource: config.resource,
+      spaceHint: opts.space && SPACE_HINT_RE.test(opts.space) ? opts.space : null,
+      next: opts.next,
+      prompt: opts.prompt,
+      allowInsecureLoopback: config.allowInsecureLoopback,
+    });
+    return redirect(started.authorizeUrl, [
+      ...extra,
+      serializeCookie(names.transaction, started.transaction, { maxAgeSec: TRANSACTION_TTL_MS / 1000, secure }),
+    ]);
+  }
+
+  /** A returning person already connected to this pod goes straight on (unless they asked to see the consent again). */
+  async function liveConnectionTo(request: Request, pod: string): Promise<boolean> {
+    const existing = await store.read(request);
+    return Boolean(existing && existing.accessExpiresAt > now() && existing.podUrl === canonicalPodUrl(pod, config));
+  }
 
   async function clientMetadata(): Promise<Response> {
     return new Response(JSON.stringify(metadata), {
@@ -278,27 +445,10 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     const pod = formField(form, "pod")?.slice(0, 512) ?? "";
     const next = safeNextPath(formField(form, "next"), origin) ?? paths.afterConnect;
     const space = formField(form, "space");
+    const prompt = formField(form, "prompt") === "consent" ? "consent" : null;
     try {
-      // A returning person already connected to this pod goes straight on.
-      const existing = await store.read(request);
-      if (existing && existing.accessExpiresAt > now() && existing.podUrl === canonicalPodUrl(pod, config)) {
-        return redirect(new URL(next, origin).href);
-      }
-      const started = await startConnect({
-        ...flow,
-        pod,
-        clientId,
-        redirectUri,
-        permissions,
-        secret: config.secret,
-        resource: config.resource,
-        spaceHint: space && /^[A-Za-z0-9_-]{1,64}$/.test(space) ? space : null,
-        next,
-        allowInsecureLoopback: config.allowInsecureLoopback,
-      });
-      return redirect(started.authorizeUrl, [
-        serializeCookie(names.transaction, started.transaction, { maxAgeSec: TRANSACTION_TTL_MS / 1000, secure }),
-      ]);
+      if (!prompt && (await liveConnectionTo(request, pod))) return redirect(new URL(next, origin).href);
+      return await toPod({ pod, next, space, prompt });
     } catch (err) {
       const e = fail(err, "connect");
       return redirect(withQuery(origin, paths.connectPage, { error: e.code, pod }));
@@ -318,7 +468,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
         secret: config.secret,
       });
       const cookies = await store.write(connection, request);
-      return redirect(new URL(next ?? paths.afterConnect, origin).href, [clearTx, ...cookies]);
+      return redirect(new URL(next ?? paths.afterConnect, origin).href, [clearTx, ...cookies, marker(connection.podUrl)]);
     } catch (err) {
       const e = fail(err, "callback");
       return redirect(withQuery(origin, paths.resultPage, { error: e.code }), [clearTx]);
@@ -334,10 +484,64 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       const { revoked } = await revokeConnection(connection, flow);
       if (!revoked) report(new ConnectError("pod_unreachable", "The pod did not confirm the revocation; the cookie is cleared anyway"), "disconnect");
     }
-    return redirect(new URL(next, origin).href, await store.clear(request));
+    // A sign-out is not a lapse: the marker goes too.
+    return redirect(new URL(next, origin).href, [...(await store.clear(request)), clearMarker]);
+  }
+
+  async function cloudConnect(request: Request): Promise<Response> {
+    if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "POST" } });
+    if (!sameOrigin(request, origin)) return new Response("Forbidden", { status: 403 });
+    const form = await readForm(request);
+    const next = safeNextPath(formField(form, "next"), origin) ?? paths.afterConnect;
+    const space = formField(form, "space");
+    try {
+      const started = await startCloudConnect({
+        cloudUrl,
+        allowInsecureLoopback: config.allowInsecureLoopback,
+        clientId,
+        secret: config.secret,
+        next,
+        spaceHint: space && SPACE_HINT_RE.test(space) ? space : null,
+        prompt: formField(form, "prompt") === "consent" ? "consent" : null,
+        now,
+      });
+      return redirect(started.url, [
+        serializeCookie(names.cloud, started.transaction, { maxAgeSec: CLOUD_TRANSACTION_TTL_MS / 1000, secure }),
+      ]);
+    } catch (err) {
+      const e = fail(err, "connect");
+      return redirect(withQuery(origin, paths.connectPage, { error: e.code }));
+    }
   }
 
-  async function refreshIfNeeded(request: Request): Promise<RefreshOutcome> {
+  async function cloudReturn(request: Request): Promise<Response> {
+    if (request.method !== "GET") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "GET" } });
+    let pod: string | null = null;
+    try {
+      // The state is checked against THIS browser's cookie before the pod is used.
+      const back = await acceptCloudReturn({
+        url: request.url,
+        transaction: parseCookies(request.headers.get("cookie")).get(names.cloud) ?? null,
+        clientId,
+        secret: config.secret,
+        allowInsecureLoopback: config.allowInsecureLoopback,
+        now,
+      });
+      pod = back.pod;
+      const next = back.next ?? paths.afterConnect;
+      if (!back.prompt && (await liveConnectionTo(request, back.pod))) return redirect(new URL(next, origin).href, [clearCloud]);
+      return await toPod({ pod: back.pod, next, space: back.spaceHint, prompt: back.prompt }, [clearCloud]);
+    } catch (err) {
+      const e = fail(err, "connect");
+      // The pod is echoed only once the state matched: a forged return pre-fills nothing.
+      return redirect(withQuery(origin, paths.connectPage, { error: e.code, pod: pod ? new URL(pod).host : null }), [clearCloud]);
+    }
+  }
+
+  /** Refresh tokens whose refresh failed while their access token still worked ("kept"): not asked again for a minute. */
+  const keptFailures = new Map<string, { error: ConnectError; at: number }>();
+
+  async function refreshIfNeeded(request: Request, opts: RefreshOptions = {}): Promise<RefreshOutcome> {
     const connection = await store.read(request);
     const unchanged = (status: RefreshStatus, conn: PodConnection | null, error?: ConnectError): RefreshOutcome => ({
       status,
@@ -346,15 +550,22 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       cookieHeader: null,
       ...(error ? { error } : {}),
     });
-    if (!connection) return unchanged("none", null);
+    if (!connection) {
+      const lapsed = lapsedIn(request);
+      return lapsed ? { ...unchanged("none", null), lapsed } : unchanged("none", null);
+    }
     if (isPrefetchOrAsset(request)) return unchanged("skipped", connection);
     const t = now();
-    const accessLives = connection.accessExpiresAt > t;
-    if (connection.accessExpiresAt - t > REFRESH_WINDOW_MS) return unchanged("fresh", connection);
+    // Forced: the pod already refused the access token, whatever its expiry says.
+    const accessLives = !opts.force && connection.accessExpiresAt > t;
+    if (!opts.force && connection.accessExpiresAt - t > REFRESH_WINDOW_MS) return unchanged("fresh", connection);
     if (!connection.refreshToken) {
-      // The pod issued none (before PB3): the connection ends with its access token.
+      // The pod issued none: the connection ends with its access token.
       return accessLives ? unchanged("fresh", connection) : unchanged("expired", null, new ConnectError("expired", "No refresh token; connect again"));
     }
+    for (const [token, f] of keptFailures) if (t - f.at >= KEPT_RETRY_MS) keptFailures.delete(token);
+    const keptFailure = accessLives ? keptFailures.get(connection.refreshToken) : undefined;
+    if (keptFailure) return unchanged("kept", connection, keptFailure.error);
     let next: PodConnection;
     try {
       next = await refreshConnection(connection, flow);
@@ -362,13 +573,24 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       const e = fail(err, "refresh");
       // LOST-RACE SAFE: another instance may have redeemed the token at the
       // same moment; the pod refuses the concurrent loser without a family
-      // revoke (PB3), and the access token we hold is still good. Keep it and
-      // set NOTHING, so the winner's cookie stands. (Within one process the
-      // race never reaches the pod: `refreshConnection` is single-flight.)
-      // Never clear the cookie here either: a clear racing the winner's
-      // Set-Cookie would sign the person out.
-      if (accessLives) return unchanged("kept", connection, e);
-      if (e.code === "revoked" || e.code === "expired") return unchanged(e.code, null, e);
+      // revoke, and the access token we hold is still good. Keep it and set
+      // NOTHING, so the winner's cookie stands. (Within one process the race
+      // never reaches the pod: `refreshConnection` is single-flight.) Never
+      // clear the cookie here either: a clear racing the winner's Set-Cookie
+      // would sign the person out. The failure is remembered for a minute, so
+      // each page view does not ask the pod again.
+      if (accessLives) {
+        keptFailures.set(connection.refreshToken, { error: e, at: t });
+        return unchanged("kept", connection, e);
+      }
+      // Spent and refused for good: clear the session cookie, so every later
+      // page view does not post the dead token to /token again (that budget is
+      // per caller IP: the app server, shared by all its visitors). The marker
+      // stays: the person still reads "expired, connect again to <pod>".
+      if (e.code === "revoked" || e.code === "expired" || e.code === "pod_moved") {
+        const cleared = await store.clear(request).catch(() => [] as string[]);
+        return { status: e.code === "revoked" ? "revoked" : "expired", connection: null, setCookies: cleared, cookieHeader: applySetCookies(request.headers.get("cookie"), cleared), error: e };
+      }
       return unchanged("unavailable", null, e);
     }
     // PERSIST BEFORE USE: the old refresh token is spent now; only a stored
@@ -383,6 +605,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       const cleared = await store.clear(request).catch(() => [] as string[]);
       return { status: "expired", connection: null, setCookies: cleared, cookieHeader: null, error: e };
     }
+    setCookies = [...setCookies, marker(next.podUrl)];
     return {
       status: "refreshed",
       connection: next,
@@ -391,15 +614,51 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     };
   }
 
+  /**
+   * The client's renewal after a 401: rotate (single-flight per
+   * process), PERSIST through `persist`, then hand the new connection over.
+   * A rotation that cannot be persisted is not used (persist before use).
+   */
+  function renewer(persist: NonNullable<PodAppClientOptions["persist"]>, source: Request | string | null | undefined) {
+    return async (connection: PodConnection): Promise<PodConnection> => {
+      let next: PodConnection;
+      try {
+        next = await refreshConnection(connection, flow);
+      } catch (err) {
+        throw fail(err, "refresh");
+      }
+      try {
+        const cookies = await store.write(next, asRequest(source ?? null));
+        await persist([...cookies, marker(next.podUrl)]);
+      } catch (err) {
+        fail(err, "refresh");
+        throw new ConnectError("expired", "The renewed connection could not be stored; connect again");
+      }
+      return next;
+    };
+  }
+
   return {
     clientId,
     redirectUri,
     metadata,
     paths,
-    handlers: { clientMetadata, connect, callback, disconnect },
-    readConnection: (source) =>
-      store.read(source instanceof Request ? source : new Request(origin, { headers: source ? { cookie: source } : {} })),
+    cloudConnectAvailable: cloudUrl !== null,
+    handlers: { clientMetadata, connect, callback, disconnect, cloudConnect, cloudReturn },
+    readConnection: (source) => store.read(asRequest(source)),
+    async readLapsed(source) {
+      const request = asRequest(source);
+      return (await store.read(request)) ? null : lapsedIn(request);
+    },
     refreshIfNeeded,
-    client: (connection, opts) => createPodClient(connection, { fetch: config.fetch, now: config.now, ...opts }),
+    client(connection, opts = {}) {
+      const { persist, request, ...clientOpts } = opts;
+      return createPodClient(connection, {
+        fetch: config.fetch,
+        now: config.now,
+        ...(persist ? { renew: renewer(persist, request) } : {}),
+        ...clientOpts,
+      });
+    },
   };
 }