@synap-core/sdk 1.2.0 → 1.4.0

package/src/connect/auth.ts

@@ -0,0 +1,535 @@
+/**
+ * `createPodAppAuth(config)`: pod-app sign-in as Web-standard route handlers
+ * (`Request → Response`, so Next route handlers, Hono, Remix, workers) plus
+ * the `proxy.ts` refresh helper. The route files stay two lines:
+ *
+ *   // app/api/synap/connect/route.ts
+ *   export const POST = synap.handlers.connect;
+ *
+ * Handlers:
+ *   GET  <metadata>    the app's client metadata document (its client_id URL)
+ *   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 { assertAppSecret, type AppSecret } from "./seal";
+import { applySetCookies, cookieNames, createSealedCookieStore, markerCookie, readMarker, type ConnectionStore } from "./store";
+import type { AppRequest, ClientMetadataDocument, PodConnection } from "./types";
+
+export interface PodAppPaths {
+  /** The client metadata document; its absolute URL is the client_id. */
+  metadata: string;
+  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>`. */
+  resultPage: string;
+  /** Where a sign-in lands when it named no `next`. */
+  afterConnect: string;
+}
+
+export const DEFAULT_PATHS: PodAppPaths = {
+  metadata: "/.well-known/synap-client.json",
+  connect: "/api/synap/connect",
+  callback: "/api/synap/callback",
+  disconnect: "/api/synap/disconnect",
+  cloud: "/api/synap/cloud",
+  connectPage: "/connect",
+  resultPage: "/connect/result",
+  afterConnect: "/",
+};
+
+/** Refresh only inside the last 5 minutes of the access token's life. */
+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). */
+  appUrl: string;
+  /** Shown on the pod's consent screen (at most 100 characters). */
+  clientName: string;
+  /** What the app asks for, each with the reason the consent screen shows. */
+  requests: readonly AppRequest[];
+  /** Workspace-template slugs the consent may offer to create (`synap_templates`). */
+  templates?: readonly string[];
+  /** SERVER-ONLY secret, at least 32 characters (SYNAP_APP_SESSION_SECRET). Several to rotate. */
+  secret: AppSecret;
+  paths?: Partial<PodAppPaths>;
+  /** Defaults to the sealed session cookie. */
+  store?: ConnectionStore;
+  /** RFC 8707 resource asked for (default the Hub API). */
+  resource?: "api/hub" | "mcp" | null;
+  /**
+   * 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 pods (and a Control Plane) on http://localhost (development against a local pod). */
+  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;
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+export type RefreshStatus =
+  /** No connection in this request. */
+  | "none"
+  /** Prefetch or static asset: nothing refreshed (the connection is read as is). */
+  | "skipped"
+  /** Valid beyond the refresh window, or no refresh token to use. */
+  | "fresh"
+  /** Rotated: send `setCookies`, forward `cookieHeader`. */
+  | "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. */
+  | "expired"
+  /** The pod refused the refresh token (access removed): connect again. */
+  | "revoked"
+  /** The pod could not be reached and the access token is spent: try later. */
+  | "unavailable";
+
+export interface RefreshOutcome {
+  status: RefreshStatus;
+  /** A usable connection, or null. */
+  connection: PodConnection | null;
+  /** Set-Cookie values to append to the response. */
+  setCookies: string[];
+  /** 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 PodAppAuth {
+  clientId: string;
+  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
+   * request, or just its Cookie header (a server component has no Request:
+   * pass `(await headers()).get("cookie")`).
+   */
+  readConnection(source: Request | string | null): Promise<PodConnection | null>;
+  /**
+   * 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, lost-race safe. */
+  refreshIfNeeded(request: Request): Promise<RefreshOutcome>;
+  /** A Hub REST client for the connection. */
+  client(connection: PodConnection, opts?: PodClientOptions): 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;
+
+function appOriginOf(appUrl: string): { origin: string; secure: boolean } {
+  let url: URL;
+  try {
+    url = new URL(appUrl);
+  } catch {
+    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 (url.pathname !== "/" || url.search || url.hash || url.username || url.password) {
+    throw new ConnectError("misconfigured", "appUrl is an origin: no path, query, fragment or credentials");
+  }
+  return { origin: url.origin, secure };
+}
+
+function assertPath(name: string, path: string): void {
+  if (!path.startsWith("/") || path.startsWith("//") || /[?#\\]/.test(path)) {
+    throw new ConnectError("misconfigured", `paths.${name} must be an absolute path on the app`);
+  }
+}
+
+/** The CIMD document (spec 17 §6.1), validated the way the pod will validate it. */
+export function buildClientMetadata(opts: {
+  appUrl: string;
+  clientName: string;
+  requests: readonly AppRequest[];
+  templates?: readonly string[];
+  paths?: Partial<PodAppPaths>;
+}): ClientMetadataDocument {
+  const { origin } = appOriginOf(opts.appUrl);
+  const paths = { ...DEFAULT_PATHS, ...opts.paths };
+  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");
+  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 *");
+    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`);
+    }
+  }
+  const templates = [...new Set(opts.templates ?? [])];
+  if (templates.length > 8 || templates.some((t) => !TEMPLATE_SLUG_RE.test(t))) {
+    throw new ConnectError("misconfigured", "at most 8 template slugs (lowercase letters, digits, . _ / -)");
+  }
+  const doc: ClientMetadataDocument = {
+    client_id: `${origin}${paths.metadata}`,
+    client_name: clientName,
+    client_uri: origin,
+    redirect_uris: [`${origin}${paths.callback}`],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+    initiate_login_uri: `${origin}${paths.connectPage}`,
+    synap_requests: opts.requests.map((r) => ({ permission: r.permission, reason: r.reason.trim() })),
+    ...(templates.length > 0 ? { synap_templates: templates } : {}),
+  };
+  if (new TextEncoder().encode(JSON.stringify(doc)).length > MAX_METADATA_BYTES) {
+    throw new ConnectError("misconfigured", "the client metadata document exceeds the pod's 5 KB limit");
+  }
+  return doc;
+}
+
+function redirect(location: string, setCookies: readonly string[] = []): Response {
+  const headers = new Headers({ Location: location, "Cache-Control": "no-store" });
+  for (const c of setCookies) headers.append("Set-Cookie", c);
+  return new Response(null, { status: 303, headers });
+}
+
+function withQuery(origin: string, path: string, params: Record<string, string | null | undefined>): string {
+  const url = new URL(path, origin);
+  for (const [k, v] of Object.entries(params)) if (v) url.searchParams.set(k, v);
+  return url.href;
+}
+
+/** A state-changing request must come from the app's own pages. */
+function sameOrigin(request: Request, origin: string): boolean {
+  const from = request.headers.get("origin");
+  if (from !== null) return from === origin;
+  return request.headers.get("sec-fetch-site") === "same-origin";
+}
+
+function formField(form: FormData | null, name: string): string | null {
+  const v = form?.get(name);
+  return typeof v === "string" ? v : null;
+}
+
+async function readForm(request: Request): Promise<FormData | null> {
+  try {
+    return await request.formData();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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("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);
+}
+
+export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
+  assertServerRuntime();
+  assertAppSecret(config.secret);
+  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);
+  const names = cookieNames(secure);
+  const now = config.now ?? Date.now;
+  const store = config.store ?? createSealedCookieStore({ secret: config.secret, secure, now });
+  const flow = { fetch: config.fetch, now: config.now };
+  const report =
+    config.onError ??
+    ((err: ConnectError, where: string) => {
+      console.warn(`[synap/connect] ${where}: ${err.code}: ${err.message}`);
+    });
+  const fail = (err: unknown, where: "connect" | "callback" | "disconnect" | "refresh"): ConnectError => {
+    const e = isConnectError(err) ? err : new ConnectError("server_error", err instanceof Error ? err.message : "Unexpected failure");
+    report(e, where);
+    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 && /^[A-Za-z0-9_-]{1,64}$/.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), {
+      status: 200,
+      headers: { "Content-Type": "application/json", "Cache-Control": "public, max-age=300" },
+    });
+  }
+
+  async function connect(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 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 {
+      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 }));
+    }
+  }
+
+  async function callback(request: Request): Promise<Response> {
+    if (request.method !== "GET") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "GET" } });
+    const transaction = parseCookies(request.headers.get("cookie")).get(names.transaction) ?? null;
+    try {
+      const { connection, next } = await handleCallback({
+        ...flow,
+        callbackUrl: request.url,
+        transaction,
+        clientId,
+        redirectUri,
+        secret: config.secret,
+      });
+      const cookies = await store.write(connection, request);
+      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]);
+    }
+  }
+
+  async function disconnect(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 next = safeNextPath(formField(await readForm(request), "next"), origin) ?? paths.connectPage;
+    const connection = await store.read(request);
+    if (connection) {
+      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");
+    }
+    // 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 && /^[A-Za-z0-9_-]{1,64}$/.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 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]);
+    }
+  }
+
+  async function refreshIfNeeded(request: Request): Promise<RefreshOutcome> {
+    const connection = await store.read(request);
+    const unchanged = (status: RefreshStatus, conn: PodConnection | null, error?: ConnectError): RefreshOutcome => ({
+      status,
+      connection: conn,
+      setCookies: [],
+      cookieHeader: null,
+      ...(error ? { error } : {}),
+    });
+    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);
+    if (!connection.refreshToken) {
+      // The pod issued none (before PB3): the connection ends with its access token.
+      return accessLives ? unchanged("fresh", connection) : unchanged("expired", null, new ConnectError("expired", "No refresh token; connect again"));
+    }
+    let next: PodConnection;
+    try {
+      next = await refreshConnection(connection, flow);
+    } catch (err) {
+      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);
+      return unchanged("unavailable", null, e);
+    }
+    // PERSIST BEFORE USE: the old refresh token is spent now; only a stored
+    // successor keeps the connection. If it cannot be stored, the new tokens
+    // are not handed out, and the stored (spent) one is cleared so no later
+    // request replays it (a replay revokes the family and the live key).
+    let setCookies: string[];
+    try {
+      setCookies = await store.write(next, request);
+    } catch (err) {
+      const e = fail(err, "refresh");
+      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,
+      setCookies,
+      cookieHeader: applySetCookies(request.headers.get("cookie"), setCookies),
+    };
+  }
+
+  return {
+    clientId,
+    redirectUri,
+    metadata,
+    paths,
+    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 }),
+  };
+}

package/src/connect/browser.ts

@@ -0,0 +1,10 @@
+/**
+ * What a BROWSER bundle gets for `@synap-core/sdk/connect` (the `browser`
+ * export condition): no exports, and a throw on load. See ./guard.ts.
+ */
+throw new Error(
+  "@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. " +
+    "Import it from route handlers, proxy.ts or server code, never from a client component.",
+);
+
+export {};