@synap-core/sdk 1.3.0 → 1.4.0

package/dist/connect.js

@@ -213,12 +213,6 @@ async function discoverPod(input, opts = {}) {
     }
   }
 }
-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");
-}
 function safeNextPath(value, appOrigin) {
   if (!value || value.length > 2048) return null;
   if (value.startsWith("/") && !value.startsWith("//") && !value.startsWith("/\\")) {
@@ -248,10 +242,193 @@ 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 && /^[A-Za-z0-9_-]{1,64}$/.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 && /^[A-Za-z0-9._~-]{16,256}$/.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;
+var STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;
+var LOOPBACK_HOSTS2 = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+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_HOSTS2.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 || !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
   };
 }
 
@@ -259,6 +436,16 @@ function acceptLaunch(url, appOrigin, opts = {}) {
 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.permissions.includes(g.permission)) space.permissions.push(g.permission);
+    bySpace.set(g.workspaceId, space);
+  }
+  return [...bySpace.values()];
+}
 var SAFE_PATH = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/]*$/;
 function hubUrl(podUrl, path, query) {
   if (!SAFE_PATH.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) {
@@ -344,11 +531,59 @@ function createPodClient(connection, opts = {}) {
     }
     return { ok: true, status: "applied", data: result.data };
   }
+  async function listPendingProposals(opts2 = {}) {
+    if (!can(connection, "proposal.read", opts2.workspaceId)) {
+      return {
+        ok: false,
+        error: { code: "forbidden", status: null, detail: "The connection was not granted proposal.read in that space" }
+      };
+    }
+    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
+    });
+    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) 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(connection.podUrl, null, id)
+      });
+    }
+    return {
+      ok: true,
+      data: { total: obj.total, proposals, hasMore: obj.hasMore === true || offset + proposals.length < obj.total }
+    };
+  }
   return {
     podUrl: connection.podUrl,
     user: connection.user,
     grant: connection.grant,
     can: (permission, workspaceId) => can(connection, permission, workspaceId),
+    spaces: () => spaces(connection),
+    listPendingProposals,
     get(path, query) {
       return request("GET", path, void 0, query);
     },
@@ -367,89 +602,6 @@ 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;
@@ -484,6 +636,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,
@@ -606,6 +759,23 @@ function parseGrant(value) {
   }
   return out;
 }
+var APP_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+var LOOPBACK_HOSTS3 = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+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_HOSTS3.has(url.hostname);
+      if (secure && !url.username && !url.password) out.manageUrl = url.href;
+    } catch {
+    }
+  }
+  return out;
+}
 function parseUser(value) {
   if (!value || typeof value !== "object") return null;
   const { id, name } = value;
@@ -640,6 +810,11 @@ 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;
   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;
@@ -717,7 +892,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;
@@ -811,6 +1004,7 @@ 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: "/"
@@ -902,7 +1096,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 +1107,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 +1124,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 && /^[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 / 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 +1168,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 +1190,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,7 +1205,53 @@ 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 && /^[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 / 1e3, secure })
+      ]);
+    } catch (err) {
+      const e = fail(err, "connect");
+      return redirect(withQuery(origin, paths.connectPage, { error: e.code }));
+    }
+  }
+  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]);
+    }
   }
   async function refreshIfNeeded(request) {
     const connection = await store.read(request);
@@ -1006,7 +1262,10 @@ 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;
@@ -1031,6 +1290,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,
@@ -1043,8 +1303,13 @@ function createPodAppAuth(config) {
     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 })
   };
@@ -1053,19 +1318,23 @@ function createPodAppAuth(config) {
 // 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,
   connectionExpiresAt,
   cookieNames,
@@ -1076,15 +1345,19 @@ export {
   handleCallback,
   isBrowserRuntime,
   isConnectError,
+  isPrefetchOrAsset,
+  markerCookie,
   openTransaction,
   parseConnectErrorCode,
   parseTokenResponse,
   pkceChallenge,
+  readMarker,
   refreshConnection,
   reviewUrlFor,
   revokeConnection,
   safeNextPath,
   seal,
+  spaces,
   startCloudConnect,
   startConnect,
   unseal