@synap-core/sdk 1.3.0 → 1.5.0

package/dist/connect.js

@@ -1,15 +1,19 @@
 import {
+  CLOUD_STATE_RE,
+  LOOPBACK_HOSTS,
+  SPACE_HINT_RE,
   base64url,
   constantTimeEqual,
   fromBase64url,
   fromUtf8,
+  isIpLiteral,
   parseCookies,
   pkceChallenge,
   randomBytes,
   randomToken,
   serializeCookie,
   utf8
-} from "./chunk-J7XHAAFJ.js";
+} from "./chunk-UK2U6SMA.js";
 
 // src/connect/guard.ts
 var BROWSER_REFUSAL = "@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.";
@@ -52,6 +56,7 @@ var CONNECT_ERROR_CODES = [
   "rate_limited",
   "expired",
   "revoked",
+  "pod_moved",
   "server_error"
 ];
 function parseConnectErrorCode(value) {
@@ -87,11 +92,44 @@ function retryAfterSeconds(header, now) {
   return Math.max(0, Math.ceil((at - now) / 1e3));
 }
 
+// src/connect/http.ts
+function timeoutSignal(ms) {
+  return typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(ms) : void 0;
+}
+async function readCapped(res, maxBytes) {
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    await res.body?.cancel().catch(() => {
+    });
+    return { ok: false, reason: "too_large" };
+  }
+  if (!res.body) return { ok: true, text: "" };
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let total = 0;
+  let text = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {
+        });
+        return { ok: false, reason: "too_large" };
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+  } catch {
+    return { ok: false, reason: "unreadable" };
+  }
+  return { ok: true, text: text + decoder.decode() };
+}
+
 // src/connect/discovery.ts
 var METADATA_PATH = "/.well-known/oauth-authorization-server";
 var TIMEOUT_MS = 5e3;
 var MAX_METADATA_BYTES = 64 * 1024;
-var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
 function isPrivateIpv4(host) {
   const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
   if (!m) return false;
@@ -144,10 +182,12 @@ function sameOriginEndpoint(value, issuer) {
   }
 }
 async function readJsonCapped(res) {
-  const text = await res.text();
-  if (text.length > MAX_METADATA_BYTES) throw new ConnectError("not_a_pod", "Metadata document too large");
+  const read = await readCapped(res, MAX_METADATA_BYTES);
+  if (!read.ok) {
+    throw read.reason === "too_large" ? new ConnectError("not_a_pod", "Metadata document too large") : new ConnectError("pod_unreachable", "The metadata answer broke off");
+  }
   try {
-    return JSON.parse(text);
+    return JSON.parse(read.text);
   } catch {
     throw new ConnectError("not_a_pod", "Metadata is not JSON");
   }
@@ -160,18 +200,27 @@ async function discoverIssuer(issuer, opts) {
       method: "GET",
       headers: { Accept: "application/json" },
       redirect: "manual",
-      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : void 0
+      signal: timeoutSignal(TIMEOUT_MS)
     });
   } catch {
     throw new ConnectError("pod_unreachable", "The pod did not answer");
   }
+  if (res.status >= 300 && res.status < 400) {
+    await res.body?.cancel().catch(() => {
+    });
+    throw new ConnectError("pod_moved", `The address answered ${res.status}: the pod moved (its new address is not followed)`);
+  }
   if (res.status === 429) {
     throw new ConnectError("rate_limited", "The pod asked to slow down", {
       retryAfterSec: retryAfterSeconds(res.headers.get("retry-after"), (opts.now ?? Date.now)())
     });
   }
   if (res.status >= 500) throw new ConnectError("pod_unreachable", `The pod answered ${res.status}`);
-  if (res.status !== 200) throw new ConnectError("not_a_pod", `No authorization server metadata (${res.status})`);
+  if (res.status !== 200) {
+    await res.body?.cancel().catch(() => {
+    });
+    throw new ConnectError("not_a_pod", `No authorization server metadata (${res.status})`);
+  }
   const doc = await readJsonCapped(res);
   if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new ConnectError("not_a_pod", "Metadata is not an object");
   const m = doc;
@@ -197,27 +246,38 @@ async function discoverIssuer(issuer, opts) {
     refreshSupported: list(m.grant_types_supported)?.includes("refresh_token") ?? false
   };
 }
+var CLOUD_DOMAIN = "synap.live";
+var CLOUD_POD_ZONE = `pod.${CLOUD_DOMAIN}`;
+var POD_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$/;
+function fallbackIssuers(first) {
+  const url = new URL(first);
+  const host = url.hostname;
+  if (url.pathname !== "/" || !host.includes(".") || host.endsWith(`.${CLOUD_POD_ZONE}`)) return [];
+  const label = host.endsWith(`.${CLOUD_DOMAIN}`) ? host.slice(0, -CLOUD_DOMAIN.length - 1) : null;
+  if (label !== null && POD_NAME_RE.test(label)) {
+    return [`${url.protocol}//${label}.${CLOUD_POD_ZONE}`, `${url.protocol}//pod.${url.host}`];
+  }
+  return host.startsWith("pod.") ? [] : [`${url.protocol}//pod.${url.host}`];
+}
 async function discoverPod(input, opts = {}) {
   const first = canonicalPodUrl(input, opts);
+  let firstError;
   try {
     return await discoverIssuer(first, opts);
   } catch (err) {
-    const url = new URL(first);
-    const retry = err instanceof ConnectError && (err.code === "not_a_pod" || err.code === "pod_unreachable") && !url.hostname.startsWith("pod.") && url.pathname === "/" && url.hostname.includes(".");
-    if (!retry) throw err;
-    const second = `${url.protocol}//pod.${url.host}`;
+    firstError = err;
+  }
+  const retryable = (err) => err instanceof ConnectError && (err.code === "not_a_pod" || err.code === "pod_unreachable" || err.code === "pod_moved");
+  if (!retryable(firstError)) throw firstError;
+  let tooOld = null;
+  for (const candidate of fallbackIssuers(first)) {
     try {
-      return await discoverIssuer(second, opts);
-    } catch (err2) {
-      throw err2 instanceof ConnectError && err2.code === "pod_unsupported" ? err2 : err;
+      return await discoverIssuer(candidate, opts);
+    } catch (err) {
+      if (err instanceof ConnectError && err.code === "pod_unsupported") tooOld ??= err;
     }
   }
-}
-function cloudConnectAvailable() {
-  return false;
-}
-function startCloudConnect(_opts) {
-  throw new ConnectError("cp_unavailable", "cp: not available \u2014 connecting through Synap Cloud is not built yet; use a pod address");
+  throw tooOld ?? firstError;
 }
 function safeNextPath(value, appOrigin) {
   if (!value || value.length > 2048) return null;
@@ -248,29 +308,253 @@ function acceptLaunch(url, appOrigin, opts = {}) {
     }
   }
   const hint = params.get("synap_space_hint");
+  const state = params.get("state");
   return {
     pod,
     next: safeNextPath(params.get("target_link_uri"), appOrigin),
-    spaceHint: hint && /^[A-Za-z0-9_-]{1,64}$/.test(hint) ? hint : null
+    spaceHint: hint && SPACE_HINT_RE.test(hint) ? hint : null,
+    // A browser launch never carries a state: any well-formed one is a Synap Cloud return
+    // (a pick: iss + state; a cancel: state + error=access_denied, no iss).
+    cloudState: state && CLOUD_STATE_RE.test(state) ? state : null
+  };
+}
+
+// src/connect/seal.ts
+var VERSION = "v1";
+var IV_BYTES = 12;
+var TAG_BYTES = 16;
+var MIN_SECRET_LENGTH = 32;
+var SALT = utf8("synap-connect/v1");
+var keyCache = /* @__PURE__ */ new Map();
+function secretsOf(secret) {
+  const list = typeof secret === "string" ? [secret] : secret;
+  if (list.length === 0 || list.some((s) => typeof s !== "string" || s.length < MIN_SECRET_LENGTH)) {
+    throw new ConnectError(
+      "misconfigured",
+      `The app session secret must be at least ${MIN_SECRET_LENGTH} characters (set SYNAP_APP_SESSION_SECRET on the server).`
+    );
+  }
+  return list;
+}
+function assertAppSecret(secret) {
+  secretsOf(secret);
+}
+function keyFor(secret, purpose) {
+  const cacheKey = `${purpose}\0${secret}`;
+  let key = keyCache.get(cacheKey);
+  if (!key) {
+    key = crypto.subtle.importKey("raw", utf8(secret), "HKDF", false, ["deriveKey"]).then(
+      (base) => crypto.subtle.deriveKey(
+        { name: "HKDF", hash: "SHA-256", salt: SALT, info: utf8(purpose) },
+        base,
+        { name: "AES-GCM", length: 256 },
+        false,
+        ["encrypt", "decrypt"]
+      )
+    );
+    keyCache.set(cacheKey, key);
+  }
+  return key;
+}
+async function seal(value, opts) {
+  const [current] = secretsOf(opts.secret);
+  const iv = randomBytes(IV_BYTES);
+  const plaintext = utf8(JSON.stringify({ exp: opts.expiresAt, data: value }));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: utf8(opts.purpose) },
+    await keyFor(current, opts.purpose),
+    plaintext
+  );
+  const out = new Uint8Array(IV_BYTES + ciphertext.byteLength);
+  out.set(iv, 0);
+  out.set(new Uint8Array(ciphertext), IV_BYTES);
+  return `${VERSION}.${base64url(out)}`;
+}
+async function unseal(sealed, opts) {
+  const secrets = secretsOf(opts.secret);
+  const dot = sealed.indexOf(".");
+  if (dot < 0 || sealed.slice(0, dot) !== VERSION) return { ok: false, reason: "invalid" };
+  const bytes = fromBase64url(sealed.slice(dot + 1));
+  if (!bytes || bytes.length < IV_BYTES + TAG_BYTES) return { ok: false, reason: "invalid" };
+  const iv = bytes.slice(0, IV_BYTES);
+  const ciphertext = bytes.slice(IV_BYTES);
+  for (const secret of secrets) {
+    let plaintext;
+    try {
+      plaintext = await crypto.subtle.decrypt(
+        { name: "AES-GCM", iv, additionalData: utf8(opts.purpose) },
+        await keyFor(secret, opts.purpose),
+        ciphertext
+      );
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(fromUtf8(new Uint8Array(plaintext)));
+    } catch {
+      return { ok: false, reason: "invalid" };
+    }
+    if (typeof parsed.exp !== "number") return { ok: false, reason: "invalid" };
+    if (parsed.exp <= opts.now) return { ok: false, reason: "expired" };
+    return { ok: true, value: parsed.data, expiresAt: parsed.exp };
+  }
+  return { ok: false, reason: "invalid" };
+}
+
+// src/connect/cloud.ts
+var CLOUD_TRANSACTION_TTL_MS = 10 * 60 * 1e3;
+function cloudBaseUrl(cloudUrl, opts = {}) {
+  let url;
+  try {
+    url = new URL(cloudUrl.trim());
+  } catch {
+    throw new ConnectError("misconfigured", "cloudUrl is not a URL");
+  }
+  const loopback = LOOPBACK_HOSTS.has(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback && opts.allowInsecureLoopback)) {
+    throw new ConnectError("misconfigured", "cloudUrl must be https (http only on localhost in development)");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new ConnectError("misconfigured", "cloudUrl has no credentials, query or fragment");
+  }
+  return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+}
+function cloudConnectAvailable(config) {
+  if (!config?.cloudUrl) return false;
+  try {
+    cloudBaseUrl(config.cloudUrl, config);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function startCloudConnect(opts) {
+  if (!cloudConnectAvailable(opts)) {
+    throw new ConnectError("cp_unavailable", "cp: not configured \u2014 pass cloudUrl (the Control Plane URL) to offer Synap Cloud");
+  }
+  if (!opts.secret) throw new ConnectError("misconfigured", "startCloudConnect needs the app secret to seal its state");
+  const base = cloudBaseUrl(opts.cloudUrl, opts);
+  const secret = opts.secret;
+  return (async () => {
+    const now = (opts.now ?? Date.now)();
+    const state = randomToken();
+    const url = new URL(`${base}/connect/pod`);
+    url.searchParams.set("client_id", opts.clientId);
+    url.searchParams.set("state", state);
+    const tx = {
+      v: 1,
+      state,
+      clientId: opts.clientId,
+      cloudUrl: base,
+      next: opts.next ?? null,
+      spaceHint: opts.spaceHint ?? null,
+      prompt: opts.prompt === "consent" ? "consent" : null,
+      createdAt: now
+    };
+    const expiresAt = now + CLOUD_TRANSACTION_TTL_MS;
+    const transaction = await seal(tx, { secret, purpose: "synap-connect/cloud", expiresAt });
+    return { url: url.href, transaction, expiresAt };
+  })();
+}
+async function acceptCloudReturn(opts) {
+  if (!opts.transaction) throw new ConnectError("expired_transaction", "No Synap Cloud sign-in in progress in this browser");
+  const opened = await unseal(opts.transaction, {
+    secret: opts.secret,
+    purpose: "synap-connect/cloud",
+    now: (opts.now ?? Date.now)()
+  });
+  if (!opened.ok) {
+    throw new ConnectError(
+      "expired_transaction",
+      opened.reason === "expired" ? "The Synap Cloud sign-in is older than 10 minutes" : "The Synap Cloud cookie is not one this app sealed"
+    );
+  }
+  const tx = opened.value;
+  if (!tx || tx.v !== 1 || typeof tx.state !== "string") {
+    throw new ConnectError("expired_transaction", "The Synap Cloud cookie is not one this app sealed");
+  }
+  if (tx.clientId !== opts.clientId) {
+    throw new ConnectError("misconfigured", "The Synap Cloud sign-in was started for another client_id");
+  }
+  const params = new URL(opts.url).searchParams;
+  const state = params.get("state");
+  if (state === null || !CLOUD_STATE_RE.test(state) || !constantTimeEqual(state, tx.state)) {
+    throw new ConnectError("mismatch", "The Synap Cloud answer does not belong to the sign-in this browser started");
+  }
+  const error = params.get("error");
+  if (error !== null) {
+    throw new ConnectError(fromOAuthError(error, "authorize"), `Synap Cloud answered ${error}`, { oauthError: error });
+  }
+  const iss = params.get("iss");
+  if (!iss) throw new ConnectError("mismatch", "The Synap Cloud answer names no pod");
+  return {
+    pod: canonicalPodUrl(iss, opts),
+    next: tx.next,
+    spaceHint: tx.spaceHint,
+    prompt: tx.prompt === "consent" ? "consent" : null
   };
 }
 
 // src/connect/client.ts
+function connectionActsAs(connection) {
+  return connection.actsAs === "person" ? "person" : "agent";
+}
+function humanSlots(session) {
+  return session.expectedOutputs.filter((slot) => slot.owner === "human" && slot.status !== "done" && !slot.retiredAt);
+}
 function can(connection, permission, workspaceId) {
   return connection.grant.some((g) => g.permission === permission && (workspaceId === void 0 || g.workspaceId === workspaceId));
 }
+function spaces(connection) {
+  const bySpace = /* @__PURE__ */ new Map();
+  for (const g of connection.grant) {
+    const space = bySpace.get(g.workspaceId) ?? { workspaceId: g.workspaceId, workspaceName: g.workspaceName, permissions: [] };
+    if (!space.workspaceName && g.workspaceName) space.workspaceName = g.workspaceName;
+    if (!space.templateSlug && g.templateSlug) space.templateSlug = g.templateSlug;
+    if (!space.permissions.includes(g.permission)) space.permissions.push(g.permission);
+    bySpace.set(g.workspaceId, space);
+  }
+  return [...bySpace.values()];
+}
+var ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+var PROPOSAL_IDS_MAX = 100;
 var SAFE_PATH = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/]*$/;
+var TIMEOUT_MS2 = 1e4;
+var MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 function hubUrl(podUrl, path, query) {
-  if (!SAFE_PATH.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) {
-    throw new TypeError(`Not a Hub API path: ${path}`);
+  if (!SAFE_PATH.test(path) || /%2e/i.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) return null;
+  let url;
+  try {
+    url = new URL(`${podUrl}/api/hub${path}`);
+  } catch {
+    return null;
   }
-  const url = new URL(`${podUrl}/api/hub${path}`);
+  if (url.origin !== new URL(podUrl).origin || !(url.pathname === "/api/hub" || url.pathname.startsWith("/api/hub/"))) return null;
   for (const [key, value] of Object.entries(query ?? {})) {
     if (value === void 0 || value === null) continue;
     for (const v of Array.isArray(value) ? value : [value]) url.searchParams.append(key, String(v));
   }
   return url;
 }
+function renewalError(err) {
+  const e = isConnectError(err) ? err : null;
+  const detail = e?.message ?? (err instanceof Error ? err.message : "The connection could not be renewed");
+  switch (e?.code) {
+    case "revoked":
+      return { code: "unauthorized", status: 401, detail };
+    case "expired":
+      return { code: "expired", status: null, detail };
+    case "rate_limited":
+      return { code: "rate_limited", status: null, detail, ...e.retryAfterSec !== void 0 ? { retryAfterSec: e.retryAfterSec } : {} };
+    case "pod_unreachable":
+      return { code: "pod_unreachable", status: null, detail };
+    case "pod_moved":
+      return { code: "pod_moved", status: null, detail };
+    default:
+      return { code: "server", status: null, detail };
+  }
+}
 function errorFor(status, body, retryAfter, now) {
   const obj = body && typeof body === "object" ? body : {};
   const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : void 0;
@@ -285,6 +569,7 @@ function errorFor(status, body, retryAfter, now) {
     return { code: "rate_limited", ...base, ...retryAfterSec !== void 0 ? { retryAfterSec } : {} };
   }
   if (status === 502 || status === 503 || status === 504) return { code: "pod_unreachable", ...base };
+  if (status >= 300 && status < 400) return { code: "pod_moved", ...base };
   return { code: "server", ...base };
 }
 function reviewUrlFor(podUrl, reviewUrl, proposalId) {
@@ -297,13 +582,37 @@ function reviewUrlFor(podUrl, reviewUrl, proposalId) {
   }
   return proposalId ? `${podUrl}/open/${encodeURIComponent(proposalId)}` : podUrl;
 }
+function refused(code, reason, detail) {
+  return { ok: false, error: { code, status: null, detail, reason } };
+}
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function hasId(value) {
+  return asObject(value) !== null && typeof value.id === "string";
+}
 function createPodClient(connection, opts = {}) {
   const now = opts.now ?? Date.now;
   const doFetch = () => opts.fetch ?? fetch;
-  async function request(method, path, body, query) {
-    const url = hubUrl(connection.podUrl, path, query);
-    if (connection.accessExpiresAt <= now()) return { ok: false, error: { code: "expired", status: null } };
-    const headers = { Accept: "application/json", Authorization: `Bearer ${connection.accessToken}` };
+  let current = connection;
+  let renewal = null;
+  function renewOnce(refused2) {
+    if (current !== refused2) return Promise.resolve({ ok: true, data: current });
+    renewal ??= opts.renew(refused2).then(
+      (next) => {
+        current = next;
+        return { ok: true, data: next };
+      },
+      (err) => ({ ok: false, error: renewalError(err) })
+    );
+    return renewal;
+  }
+  async function request(method, path, body, query, retried = false) {
+    const sent = current;
+    const url = hubUrl(sent.podUrl, path, query);
+    if (!url) return refused("invalid", "invalid_input", "Not a Hub API path: encode each path segment (encodeURIComponent)");
+    if (sent.accessExpiresAt <= now()) return { ok: false, error: { code: "expired", status: null } };
+    const headers = { Accept: "application/json", Authorization: `Bearer ${sent.accessToken}` };
     if (body !== void 0) headers["Content-Type"] = "application/json";
     let res;
     try {
@@ -311,21 +620,33 @@ function createPodClient(connection, opts = {}) {
         method,
         headers,
         body: body === void 0 ? void 0 : JSON.stringify(body),
-        redirect: "manual"
+        redirect: "manual",
+        signal: timeoutSignal(opts.timeoutMs ?? TIMEOUT_MS2)
       });
     } catch {
       return { ok: false, error: { code: "pod_unreachable", status: null } };
     }
+    const read2 = await readCapped(res, opts.maxResponseBytes ?? MAX_RESPONSE_BYTES);
+    if (!read2.ok) {
+      return read2.reason === "too_large" ? { ok: false, error: { code: "server", status: res.status, detail: "The pod's answer is larger than maxResponseBytes" } } : { ok: false, error: { code: "pod_unreachable", status: res.status, detail: "The pod's answer broke off" } };
+    }
     let data = null;
-    const text = await res.text().catch(() => "");
-    if (text) {
+    if (read2.text) {
       try {
-        data = JSON.parse(text);
+        data = JSON.parse(read2.text);
       } catch {
         data = null;
       }
     }
     if (res.status >= 200 && res.status < 300) return { ok: true, data };
+    if (res.status === 401 && sent.refreshToken) {
+      if (!opts.renew) return { ok: false, error: { ...errorFor(401, data, null, now()), refreshable: true } };
+      if (!retried) {
+        const renewed = await renewOnce(sent);
+        if (!renewed.ok) return renewed;
+        return request(method, path, body, query, true);
+      }
+    }
     return { ok: false, error: errorFor(res.status, data, res.headers.get("retry-after"), now()) };
   }
   async function write(method, path, body) {
@@ -338,17 +659,189 @@ function createPodClient(connection, opts = {}) {
         ok: true,
         status: "proposed",
         proposalId,
-        reviewUrl: reviewUrlFor(connection.podUrl, obj.reviewUrl, proposalId),
+        reviewUrl: reviewUrlFor(current.podUrl, obj.reviewUrl, proposalId),
         data: result.data
       };
     }
     return { ok: true, status: "applied", data: result.data };
   }
+  async function listPendingProposals(opts2 = {}) {
+    if (!can(current, "proposal.read", opts2.workspaceId)) {
+      return refused("forbidden", "not_granted", "The connection was not granted proposal.read in that space");
+    }
+    let only = null;
+    if (opts2.proposalIds !== void 0) {
+      if (opts2.proposalIds.length > PROPOSAL_IDS_MAX || opts2.proposalIds.some((id) => !ID_RE.test(id))) {
+        return refused("invalid", "invalid_input", `proposalIds must be at most ${PROPOSAL_IDS_MAX} proposal ids`);
+      }
+      if (opts2.proposalIds.length === 0) return { ok: true, data: { total: 0, proposals: [], hasMore: false } };
+      only = new Set(opts2.proposalIds);
+    }
+    const limit = Math.min(Math.max(Math.floor(opts2.limit ?? 20), 1), 200);
+    const offset = Math.max(Math.floor(opts2.offset ?? 0), 0);
+    const result = await request("GET", "/proposals", void 0, {
+      status: "pending",
+      view: "basic",
+      limit,
+      offset,
+      workspaceId: opts2.workspaceId,
+      ...only ? { proposalIds: [...only].join(",") } : {}
+    });
+    if (!result.ok) return result;
+    const obj = result.data && typeof result.data === "object" ? result.data : {};
+    if (!Array.isArray(obj.proposals) || typeof obj.total !== "number") {
+      return { ok: false, error: { code: "server", status: 200, detail: "The pod's /proposals answer has no proposals or total" } };
+    }
+    const str = (v) => typeof v === "string" && v ? v : null;
+    const proposals = [];
+    for (const row of obj.proposals) {
+      if (!row || typeof row !== "object") continue;
+      const r = row;
+      const id = str(r.id);
+      if (!id || only && !only.has(id)) continue;
+      proposals.push({
+        id,
+        proposalType: str(r.proposalType) ?? "",
+        targetType: str(r.targetType) ?? "",
+        targetId: str(r.targetId),
+        workspaceId: str(r.workspaceId),
+        createdAt: str(r.createdAt) ?? "",
+        agentUserId: str(r.agentUserId),
+        sessionId: str(r.sessionId),
+        ...str(r.summary) ? { summary: str(r.summary) } : {},
+        reviewUrl: reviewUrlFor(current.podUrl, null, id)
+      });
+    }
+    return {
+      ok: true,
+      data: { total: obj.total, proposals, hasMore: obj.hasMore === true || offset + proposals.length < obj.total }
+    };
+  }
+  async function read(path, query, shape) {
+    const result = await request("GET", path, void 0, query);
+    if (!result.ok) return result;
+    const data = shape(result.data);
+    if (data === null) return { ok: false, error: { code: "server", status: 200, detail: `The pod's ${path.split("/")[1]} answer is not the expected shape` } };
+    return { ok: true, data };
+  }
+  const badId = (what) => refused("invalid", "invalid_input", `Not a ${what} id`);
+  const clamp = (n, min, max) => n === void 0 ? void 0 : Math.min(Math.max(Math.floor(n), min), max);
+  function listEntities(opts2 = {}) {
+    return read("/entities", {
+      workspaceId: opts2.workspaceId,
+      profileSlug: opts2.profileSlug,
+      limit: clamp(opts2.limit, 1, 1e3),
+      offset: clamp(opts2.offset, 0, Number.MAX_SAFE_INTEGER),
+      sort: opts2.sort,
+      includePodWide: opts2.includePodWide
+    }, (data) => Array.isArray(data) ? data.filter(hasId) : null);
+  }
+  async function getEntity(id) {
+    if (!ID_RE.test(id)) return badId("entity");
+    return read(`/entities/${id}`, void 0, (data) => hasId(data) ? data : null);
+  }
+  async function getEntityConnections(id, opts2 = {}) {
+    if (!ID_RE.test(id)) return badId("entity");
+    return read(`/entities/${id}/connections`, { workspaceId: opts2.workspaceId, limit: clamp(opts2.limit, 1, 200) }, (data) => {
+      const obj = asObject(data);
+      if (!obj || !Array.isArray(obj.connections)) return null;
+      const connections = obj.connections.filter(
+        (c) => !!c && typeof c === "object" && typeof c.entityId === "string"
+      );
+      const counts = asObject(obj.counts) ?? {};
+      const count = (key, source) => typeof counts[key] === "number" ? counts[key] : connections.filter((c) => c.source === source).length;
+      return {
+        connections,
+        counts: {
+          total: typeof counts.total === "number" ? counts.total : connections.length,
+          graph: count("graph", "graph"),
+          structural: count("structural", "property"),
+          threads: count("threads", "thread"),
+          contextChannels: count("contextChannels", "context_channel"),
+          focusSessions: count("focusSessions", "focus_session")
+        }
+      };
+    });
+  }
+  async function getDocument(id, opts2 = {}) {
+    if (!ID_RE.test(id)) return badId("document");
+    return read(`/documents/${id}`, { format: opts2.format }, (data) => {
+      const doc = asObject(asObject(data)?.document);
+      if (!doc || typeof doc.id !== "string" || typeof doc.content !== "string") return null;
+      return { ...doc, sections: Array.isArray(doc.sections) ? doc.sections : [] };
+    });
+  }
+  async function listFocusSessions(opts2) {
+    if (!opts2?.workspaceId && !opts2?.projectId) return refused("invalid", "invalid_input", "workspaceId or projectId is required");
+    return read("/focus-sessions", {
+      workspaceId: opts2.workspaceId,
+      projectId: opts2.projectId,
+      status: opts2.status,
+      limit: clamp(opts2.limit, 1, 50),
+      lens: opts2.lens,
+      kind: opts2.kind,
+      subjectEntityId: opts2.subjectEntityId
+    }, (data) => {
+      if (!Array.isArray(data)) return null;
+      return data.filter(hasId).map((row) => ({
+        ...row,
+        expectedOutputs: Array.isArray(row.expectedOutputs) ? row.expectedOutputs.filter((s) => !!s && typeof s === "object" && typeof s.label === "string") : []
+      }));
+    });
+  }
+  async function getFileUrl(entityId) {
+    if (!ID_RE.test(entityId)) return badId("file");
+    return read(`/files/${entityId}/url`, void 0, (data) => {
+      const obj = asObject(data);
+      if (!obj || typeof obj.url !== "string" || typeof obj.expiresAt !== "string") return null;
+      return { url: obj.url, expiresAt: obj.expiresAt, mimeType: typeof obj.mimeType === "string" ? obj.mimeType : null };
+    });
+  }
+  async function approveProposal(id, opts2 = {}) {
+    if (connectionActsAs(current) !== "person") {
+      return refused("forbidden", "agent_cannot_approve", "An agent connection can never approve: approval is the person's");
+    }
+    if (!can(current, "proposal.approve", opts2.workspaceId)) {
+      return refused("forbidden", "not_granted", "The connection was not granted proposal.approve in that space");
+    }
+    if (!ID_RE.test(id)) return badId("proposal");
+    const result = await request("POST", `/proposals/${id}/approve`, {});
+    if (!result.ok) return result;
+    const obj = asObject(result.data);
+    if (!obj || typeof obj.proposalId !== "string") {
+      return { ok: false, error: { code: "server", status: 200, detail: "The pod's approve answer names no proposalId" } };
+    }
+    return {
+      ok: true,
+      data: {
+        proposalId: obj.proposalId,
+        ...typeof obj.primaryId === "string" ? { primaryId: obj.primaryId } : {},
+        ...typeof obj.linked === "number" ? { linked: obj.linked } : {},
+        proposal: asObject(obj.proposal)
+      }
+    };
+  }
   return {
     podUrl: connection.podUrl,
-    user: connection.user,
-    grant: connection.grant,
-    can: (permission, workspaceId) => can(connection, permission, workspaceId),
+    get user() {
+      return current.user;
+    },
+    get grant() {
+      return current.grant;
+    },
+    get actsAs() {
+      return connectionActsAs(current);
+    },
+    can: (permission, workspaceId) => can(current, permission, workspaceId),
+    spaces: () => spaces(current),
+    listPendingProposals,
+    listEntities,
+    getEntity,
+    getEntityConnections,
+    getDocument,
+    listFocusSessions,
+    getFileUrl,
+    approveProposal,
     get(path, query) {
       return request("GET", path, void 0, query);
     },
@@ -367,94 +860,12 @@ function createPodClient(connection, opts = {}) {
   };
 }
 
-// src/connect/seal.ts
-var VERSION = "v1";
-var IV_BYTES = 12;
-var TAG_BYTES = 16;
-var MIN_SECRET_LENGTH = 32;
-var SALT = utf8("synap-connect/v1");
-var keyCache = /* @__PURE__ */ new Map();
-function secretsOf(secret) {
-  const list = typeof secret === "string" ? [secret] : secret;
-  if (list.length === 0 || list.some((s) => typeof s !== "string" || s.length < MIN_SECRET_LENGTH)) {
-    throw new ConnectError(
-      "misconfigured",
-      `The app session secret must be at least ${MIN_SECRET_LENGTH} characters (set SYNAP_APP_SESSION_SECRET on the server).`
-    );
-  }
-  return list;
-}
-function assertAppSecret(secret) {
-  secretsOf(secret);
-}
-function keyFor(secret, purpose) {
-  const cacheKey = `${purpose}\0${secret}`;
-  let key = keyCache.get(cacheKey);
-  if (!key) {
-    key = crypto.subtle.importKey("raw", utf8(secret), "HKDF", false, ["deriveKey"]).then(
-      (base) => crypto.subtle.deriveKey(
-        { name: "HKDF", hash: "SHA-256", salt: SALT, info: utf8(purpose) },
-        base,
-        { name: "AES-GCM", length: 256 },
-        false,
-        ["encrypt", "decrypt"]
-      )
-    );
-    keyCache.set(cacheKey, key);
-  }
-  return key;
-}
-async function seal(value, opts) {
-  const [current] = secretsOf(opts.secret);
-  const iv = randomBytes(IV_BYTES);
-  const plaintext = utf8(JSON.stringify({ exp: opts.expiresAt, data: value }));
-  const ciphertext = await crypto.subtle.encrypt(
-    { name: "AES-GCM", iv, additionalData: utf8(opts.purpose) },
-    await keyFor(current, opts.purpose),
-    plaintext
-  );
-  const out = new Uint8Array(IV_BYTES + ciphertext.byteLength);
-  out.set(iv, 0);
-  out.set(new Uint8Array(ciphertext), IV_BYTES);
-  return `${VERSION}.${base64url(out)}`;
-}
-async function unseal(sealed, opts) {
-  const secrets = secretsOf(opts.secret);
-  const dot = sealed.indexOf(".");
-  if (dot < 0 || sealed.slice(0, dot) !== VERSION) return { ok: false, reason: "invalid" };
-  const bytes = fromBase64url(sealed.slice(dot + 1));
-  if (!bytes || bytes.length < IV_BYTES + TAG_BYTES) return { ok: false, reason: "invalid" };
-  const iv = bytes.slice(0, IV_BYTES);
-  const ciphertext = bytes.slice(IV_BYTES);
-  for (const secret of secrets) {
-    let plaintext;
-    try {
-      plaintext = await crypto.subtle.decrypt(
-        { name: "AES-GCM", iv, additionalData: utf8(opts.purpose) },
-        await keyFor(secret, opts.purpose),
-        ciphertext
-      );
-    } catch {
-      continue;
-    }
-    let parsed;
-    try {
-      parsed = JSON.parse(fromUtf8(new Uint8Array(plaintext)));
-    } catch {
-      return { ok: false, reason: "invalid" };
-    }
-    if (typeof parsed.exp !== "number") return { ok: false, reason: "invalid" };
-    if (parsed.exp <= opts.now) return { ok: false, reason: "expired" };
-    return { ok: true, value: parsed.data, expiresAt: parsed.exp };
-  }
-  return { ok: false, reason: "invalid" };
-}
-
 // src/connect/flow.ts
 var TRANSACTION_TTL_MS = 10 * 60 * 1e3;
 var DEFAULT_REFRESH_IDLE_MS = 30 * 24 * 60 * 60 * 1e3;
 var DEFAULT_ACCESS_TTL_SEC = 3600;
-var TIMEOUT_MS2 = 1e4;
+var TIMEOUT_MS3 = 1e4;
+var MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
 var PERMISSION_RE = /^[a-z][a-z0-9_-]*(\.[a-z0-9_-]+)+$/i;
 function assertPermissions(permissions) {
   const unique = [...new Set(permissions)];
@@ -484,6 +895,7 @@ async function startConnect(opts) {
   url.searchParams.set("code_challenge_method", "S256");
   if (resource) url.searchParams.set("resource", resource);
   if (opts.spaceHint) url.searchParams.set("synap_space_hint", opts.spaceHint);
+  if (opts.prompt === "consent") url.searchParams.set("prompt", "consent");
   const tx = {
     v: 1,
     issuer: issuer.issuer,
@@ -571,20 +983,29 @@ async function tokenRequest(endpoint, body, during, opts) {
       headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
       body: body.toString(),
       redirect: "manual",
-      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS2) : void 0
+      signal: timeoutSignal(TIMEOUT_MS3)
     });
   } catch {
     throw new ConnectError("pod_unreachable", "The pod's token endpoint did not answer");
   }
+  if (res.status >= 300 && res.status < 400) {
+    await res.body?.cancel().catch(() => {
+    });
+    throw new ConnectError("pod_moved", `The token endpoint answered ${res.status}: the pod moved; connect again with its new address`);
+  }
   if (res.status === 429) {
     throw new ConnectError("rate_limited", "The pod asked to slow down", {
       retryAfterSec: retryAfterSeconds(res.headers.get("retry-after"), (opts.now ?? Date.now)())
     });
   }
   if (res.status >= 500) throw new ConnectError("pod_unreachable", `The token endpoint answered ${res.status}`);
+  const read = await readCapped(res, MAX_TOKEN_RESPONSE_BYTES);
+  if (!read.ok) {
+    throw read.reason === "too_large" ? new ConnectError("server_error", "The token endpoint's answer is too large") : new ConnectError("pod_unreachable", "The token endpoint's answer broke off");
+  }
   let json;
   try {
-    json = await res.json();
+    json = JSON.parse(read.text);
   } catch {
     throw new ConnectError("server_error", `The token endpoint answered ${res.status} without JSON`);
   }
@@ -600,9 +1021,30 @@ function parseGrant(value) {
   const out = [];
   for (const g of value) {
     if (!g || typeof g !== "object") return null;
-    const { permission, workspaceId, workspaceName } = g;
+    const { permission, workspaceId, workspaceName, templateSlug } = g;
     if (typeof permission !== "string" || typeof workspaceId !== "string") return null;
-    out.push({ permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" });
+    const row = { permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" };
+    if (typeof templateSlug === "string" && templateSlug.length > 0 && templateSlug.length <= 200) row.templateSlug = templateSlug;
+    out.push(row);
+  }
+  return out;
+}
+function parseActsAs(value) {
+  return value === "person" || value === "agent" ? value : void 0;
+}
+var APP_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+function parseApp(value) {
+  if (!value || typeof value !== "object") return {};
+  const { id, manageUrl } = value;
+  const out = {};
+  if (typeof id === "string" && APP_ID_RE.test(id)) out.appId = id;
+  if (typeof manageUrl === "string" && manageUrl.length <= 2048) {
+    try {
+      const url = new URL(manageUrl);
+      const secure = url.protocol === "https:" || url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+      if (secure && !url.username && !url.password) out.manageUrl = url.href;
+    } catch {
+    }
   }
   return out;
 }
@@ -640,6 +1082,13 @@ function parseTokenResponse(body, ctx) {
     user,
     connectedAt: ctx.previous?.connectedAt ?? ctx.now
   };
+  const app = parseApp(body.synap_app);
+  const appId = app.appId ?? ctx.previous?.appId;
+  const manageUrl = app.manageUrl ?? ctx.previous?.manageUrl;
+  if (appId !== void 0) connection.appId = appId;
+  if (manageUrl !== void 0) connection.manageUrl = manageUrl;
+  const actsAs = parseActsAs(body.synap_acts_as);
+  if (actsAs !== void 0) connection.actsAs = actsAs;
   if (typeof refresh_token === "string" && refresh_token !== "") {
     connection.refreshToken = refresh_token;
     const idle = typeof refresh_token_expires_in === "number" && Number.isFinite(refresh_token_expires_in) && refresh_token_expires_in > 0 ? refresh_token_expires_in * 1e3 : DEFAULT_REFRESH_IDLE_MS;
@@ -705,7 +1154,9 @@ async function revokeConnection(connection, opts = {}) {
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({ token, token_type_hint: hint, client_id: connection.clientId }).toString(),
         redirect: "manual",
-        signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS2) : void 0
+        signal: timeoutSignal(TIMEOUT_MS3)
+      });
+      await res.body?.cancel().catch(() => {
       });
       if (res.status !== 200) revoked = false;
     } catch {
@@ -717,7 +1168,25 @@ async function revokeConnection(connection, opts = {}) {
 
 // src/connect/store.ts
 function cookieNames(secure) {
-  return secure ? { session: "__Host-synap_session", transaction: "__Host-synap_tx" } : { session: "synap_session", transaction: "synap_tx" };
+  return secure ? { session: "__Host-synap_session", transaction: "__Host-synap_tx", cloud: "__Host-synap_cloud", marker: "__Host-synap_seen" } : { session: "synap_session", transaction: "synap_tx", cloud: "synap_cloud", marker: "synap_seen" };
+}
+var MARKER_TTL_SEC = 400 * 24 * 60 * 60;
+function markerCookie(podUrl, opts) {
+  return serializeCookie(opts.name ?? cookieNames(opts.secure).marker, base64url(utf8(podUrl)), {
+    maxAgeSec: MARKER_TTL_SEC,
+    secure: opts.secure
+  });
+}
+function readMarker(cookieHeader, opts) {
+  const raw = parseCookies(cookieHeader).get(opts.name ?? cookieNames(opts.secure).marker);
+  const bytes = raw ? fromBase64url(raw) : null;
+  if (!bytes || bytes.length > 512) return null;
+  const podUrl = fromUtf8(bytes);
+  try {
+    return canonicalPodUrl(podUrl, opts) === podUrl ? podUrl : null;
+  } catch {
+    return null;
+  }
 }
 var CHUNK_SIZE = 3800;
 var MAX_CHUNKS = 4;
@@ -729,6 +1198,7 @@ function pack(c) {
   for (const g of c.grant) {
     const row = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
     row[2].push(g.permission);
+    if (g.templateSlug && row[3] === void 0) row[3] = g.templateSlug;
     bySpace.set(g.workspaceId, row);
   }
   const { grant: _grant, ...rest } = c;
@@ -738,7 +1208,7 @@ function unpack(s) {
   if (!s || typeof s.podUrl !== "string" || typeof s.accessToken !== "string" || !Array.isArray(s.g)) return null;
   const { g, ...rest } = s;
   const grant = g.flatMap(
-    ([workspaceId, workspaceName, permissions]) => permissions.map((permission) => ({ permission, workspaceId, workspaceName }))
+    ([workspaceId, workspaceName, permissions, templateSlug]) => permissions.map((permission) => ({ permission, workspaceId, workspaceName, ...typeof templateSlug === "string" ? { templateSlug } : {} }))
   );
   return { ...rest, grant };
 }
@@ -811,14 +1281,36 @@ var DEFAULT_PATHS = {
   connect: "/api/synap/connect",
   callback: "/api/synap/callback",
   disconnect: "/api/synap/disconnect",
+  cloud: "/api/synap/cloud",
   connectPage: "/connect",
   resultPage: "/connect/result",
   afterConnect: "/"
 };
 var REFRESH_WINDOW_MS = 5 * 60 * 1e3;
-var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
 var TEMPLATE_SLUG_RE = /^[a-z0-9][a-z0-9._/-]{0,99}$/;
 var MAX_METADATA_BYTES2 = 5 * 1024;
+var MAX_REQUESTS = 32;
+var KEPT_RETRY_MS = 6e4;
+var GRANT_ACTIONS = ["read", "create", "update", "delete"];
+var SYNAP_APP_REVIEW_PERMISSIONS = ["proposal.approve", "proposal.reject"];
+var PERMISSION_SEGMENT_RE = /^[a-z0-9][a-z0-9_-]*$/;
+function isSynapAppOrigin(origin) {
+  return /^https:\/\/[a-z0-9]([a-z0-9-]*[a-z0-9])?\.synap\.live$/.test(origin);
+}
+function assertAppPermission(permission, origin) {
+  const segs = permission.split(".");
+  const fail = (why) => {
+    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) {
   let url;
   try {
@@ -827,8 +1319,11 @@ function appOriginOf(appUrl) {
     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");
@@ -846,9 +1341,12 @@ 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");
+  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`);
     }
@@ -902,7 +1400,7 @@ async function readForm(request) {
 }
 function isPrefetchOrAsset(request) {
   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);
@@ -913,6 +1411,7 @@ function createPodAppAuth(config) {
   const { origin, secure } = appOriginOf(config.appUrl);
   const paths = { ...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);
@@ -929,6 +1428,37 @@ function createPodAppAuth(config) {
     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) => markerCookie(podUrl, { secure, name: names.marker });
+  const asRequest = (source) => source instanceof Request ? source : new Request(origin, { headers: source ? { cookie: source } : {} });
+  const lapsedIn = (request) => {
+    const podUrl = readMarker(request.headers.get("cookie"), { secure, name: names.marker, allowInsecureLoopback: config.allowInsecureLoopback });
+    return podUrl ? { podUrl } : null;
+  };
+  async function toPod(opts, extra = []) {
+    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 / 1e3, secure })
+    ]);
+  }
+  async function liveConnectionTo(request, pod) {
+    const existing = await store.read(request);
+    return Boolean(existing && existing.accessExpiresAt > now() && existing.podUrl === canonicalPodUrl(pod, config));
+  }
   async function clientMetadata() {
     return new Response(JSON.stringify(metadata), {
       status: 200,
@@ -942,26 +1472,10 @@ function createPodAppAuth(config) {
     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 {
-      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 / 1e3, 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 }));
@@ -980,7 +1494,7 @@ function createPodAppAuth(config) {
         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]);
@@ -995,9 +1509,56 @@ function createPodAppAuth(config) {
       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));
+    return redirect(new URL(next, origin).href, [...await store.clear(request), clearMarker]);
+  }
+  async function cloudConnect(request) {
+    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 / 1e3, secure })
+      ]);
+    } catch (err) {
+      const e = fail(err, "connect");
+      return redirect(withQuery(origin, paths.connectPage, { error: e.code }));
+    }
   }
-  async function refreshIfNeeded(request) {
+  async function cloudReturn(request) {
+    if (request.method !== "GET") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "GET" } });
+    let pod = null;
+    try {
+      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");
+      return redirect(withQuery(origin, paths.connectPage, { error: e.code, pod: pod ? new URL(pod).host : null }), [clearCloud]);
+    }
+  }
+  const keptFailures = /* @__PURE__ */ new Map();
+  async function refreshIfNeeded(request, opts = {}) {
     const connection = await store.read(request);
     const unchanged = (status, conn, error) => ({
       status,
@@ -1006,21 +1567,33 @@ function createPodAppAuth(config) {
       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);
+    const accessLives = !opts.force && connection.accessExpiresAt > t;
+    if (!opts.force && connection.accessExpiresAt - t > REFRESH_WINDOW_MS) return unchanged("fresh", connection);
     if (!connection.refreshToken) {
       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) : void 0;
+    if (keptFailure) return unchanged("kept", connection, keptFailure.error);
     let next;
     try {
       next = await refreshConnection(connection, flow);
     } catch (err) {
       const e = fail(err, "refresh");
-      if (accessLives) return unchanged("kept", connection, e);
-      if (e.code === "revoked" || e.code === "expired") return unchanged(e.code, null, e);
+      if (accessLives) {
+        keptFailures.set(connection.refreshToken, { error: e, at: t });
+        return unchanged("kept", connection, e);
+      }
+      if (e.code === "revoked" || e.code === "expired" || e.code === "pod_moved") {
+        const cleared = await store.clear(request).catch(() => []);
+        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);
     }
     let setCookies;
@@ -1031,6 +1604,7 @@ function createPodAppAuth(config) {
       const cleared = await store.clear(request).catch(() => []);
       return { status: "expired", connection: null, setCookies: cleared, cookieHeader: null, error: e };
     }
+    setCookies = [...setCookies, marker(next.podUrl)];
     return {
       status: "refreshed",
       connection: next,
@@ -1038,35 +1612,71 @@ function createPodAppAuth(config) {
       cookieHeader: applySetCookies(request.headers.get("cookie"), setCookies)
     };
   }
+  function renewer(persist, source) {
+    return async (connection) => {
+      let next;
+      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
+      });
+    }
   };
 }
 
 // src/connect/index.ts
 assertServerRuntime();
 export {
+  CLOUD_TRANSACTION_TTL_MS,
   CONNECT_ERROR_CODES,
   ConnectError,
   DEFAULT_PATHS,
   DEFAULT_REFRESH_IDLE_MS,
+  MARKER_TTL_SEC,
   MIN_SECRET_LENGTH,
   REFRESH_WINDOW_MS,
   ROTATION_MEMORY_MS,
   TRANSACTION_TTL_MS,
+  acceptCloudReturn,
   acceptLaunch,
   applySetCookies,
   buildClientMetadata,
   can,
   canonicalPodUrl,
+  cloudBaseUrl,
   cloudConnectAvailable,
+  connectionActsAs,
   connectionExpiresAt,
   cookieNames,
   createPodAppAuth,
@@ -1074,17 +1684,22 @@ export {
   createSealedCookieStore,
   discoverPod,
   handleCallback,
+  humanSlots,
   isBrowserRuntime,
   isConnectError,
+  isPrefetchOrAsset,
+  markerCookie,
   openTransaction,
   parseConnectErrorCode,
   parseTokenResponse,
   pkceChallenge,
+  readMarker,
   refreshConnection,
   reviewUrlFor,
   revokeConnection,
   safeNextPath,
   seal,
+  spaces,
   startCloudConnect,
   startConnect,
   unseal