@synap-core/sdk 1.3.0 → 1.4.0

package/src/connect/auth.ts

@@ -8,15 +8,26 @@
  *
  * Handlers:
  *   GET  <metadata>    the app's client metadata document (its client_id URL)
- *   POST <connect>     form { pod, next?, space? } → 303 to the pod's /authorize
+ *   POST <connect>     form { pod, next?, space?, prompt? } → 303 to the pod's /authorize
  *   GET  <callback>    the pod's answer → sealed session cookie → 303 to `next`
  *   POST <disconnect>  revoke at the pod (best effort), clear the cookie → 303
+ *   POST <cloud>       form { next?, space?, prompt? } → 303 to the Synap Cloud pod chooser
+ *   GET  <cloud>       the chooser's return (?iss&state, state checked) → 303 to the pod's /authorize
+ *
+ * `prompt=consent` asks for the pod's consent screen again (widen or narrow
+ * what the app may touch); without it a person already connected to that pod
+ * goes straight to `next`. Either way a sign-in is a fresh PKCE + state flow.
  *
  * `connect` and `disconnect` change state, so they are POST and same-origin
  * only (Origin, else Sec-Fetch-Site): a third-party page cannot start a
  * sign-in into an attacker's pod for a visitor (login CSRF) or sign them out.
  * Failures redirect with `?error=<ConnectErrorCode>` and nothing else.
+ *
+ * Each successful sign-in or refresh also sets a marker cookie holding the
+ * pod's URL and no secret (`markerCookie`), so a connection that lapsed reads
+ * as "expired" (`readLapsed`, `RefreshOutcome.lapsed`), not "never connected".
  */
+import { acceptCloudReturn, cloudBaseUrl, CLOUD_TRANSACTION_TTL_MS, startCloudConnect } from "./cloud";
 import { safeNextPath, canonicalPodUrl } from "./discovery";
 import { ConnectError, isConnectError } from "./errors";
 import { serializeCookie, parseCookies } from "./encoding";
@@ -24,7 +35,7 @@ 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, type ConnectionStore } from "./store";
+import { applySetCookies, cookieNames, createSealedCookieStore, markerCookie, readMarker, type ConnectionStore } from "./store";
 import type { AppRequest, ClientMetadataDocument, PodConnection } from "./types";
 
 export interface PodAppPaths {
@@ -33,6 +44,8 @@ export interface PodAppPaths {
   connect: string;
   callback: string;
   disconnect: string;
+  /** Synap Cloud: POST starts it, GET is the pod chooser's return (forwarded from the connect page). */
+  cloud: string;
   /** The app's connect page (also the CIMD `initiate_login_uri`). */
   connectPage: string;
   /** Where a failed callback lands, with `?error=<code>`. */
@@ -46,6 +59,7 @@ export const DEFAULT_PATHS: PodAppPaths = {
   connect: "/api/synap/connect",
   callback: "/api/synap/callback",
   disconnect: "/api/synap/disconnect",
+  cloud: "/api/synap/cloud",
   connectPage: "/connect",
   resultPage: "/connect/result",
   afterConnect: "/",
@@ -70,7 +84,12 @@ export interface PodAppAuthConfig {
   store?: ConnectionStore;
   /** RFC 8707 resource asked for (default the Hub API). */
   resource?: "api/hub" | "mcp" | null;
-  /** Accept pods on http://localhost (development against a local pod). */
+  /**
+   * The Synap Control Plane's URL (e.g. https://api.synap.live): offers
+   * "Continue with Synap Cloud" (`cloudConnectAvailable`). Unset = address only.
+   */
+  cloudUrl?: string | null;
+  /** Accept 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;
@@ -105,6 +124,12 @@ export interface RefreshOutcome {
   /** The request's Cookie header with the refreshed value, to forward to the render (null = unchanged). */
   cookieHeader: string | null;
   error?: ConnectError;
+  /**
+   * With `none`: this browser WAS connected to that pod and the connection
+   * lapsed (its sealed cookie is gone, idle past its life). Say "expired,
+   * connect again" with the pod pre-filled, not "connect your pod".
+   */
+  lapsed?: { podUrl: string };
 }
 
 export interface PodAppAuth {
@@ -112,11 +137,17 @@ export interface PodAppAuth {
   redirectUri: string;
   metadata: ClientMetadataDocument;
   paths: PodAppPaths;
+  /** Whether "Continue with Synap Cloud" can be offered (`cloudUrl` is configured). */
+  cloudConnectAvailable: boolean;
   handlers: {
     clientMetadata(request: Request): Promise<Response>;
     connect(request: Request): Promise<Response>;
     callback(request: Request): Promise<Response>;
     disconnect(request: Request): Promise<Response>;
+    /** POST: start a Synap Cloud sign-in (same-origin, form { next?, space?, prompt? }). */
+    cloudConnect(request: Request): Promise<Response>;
+    /** GET: the Synap Cloud pod chooser's return (`?iss&state`), checked against this browser's cookie. */
+    cloudReturn(request: Request): Promise<Response>;
   };
   /**
    * The stored connection (no refresh, no expiry check), or null. Takes the
@@ -124,6 +155,12 @@ export interface PodAppAuth {
    * 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. */
@@ -231,9 +268,23 @@ async function readForm(request: Request): Promise<FormData | null> {
   }
 }
 
-function isPrefetchOrAsset(request: Request): boolean {
+/**
+ * A prefetch or a static asset: `refreshIfNeeded` answers `skipped` for these.
+ *
+ * LIMIT (Next.js 16 `proxy.ts` on the Node runtime): Next strips its router
+ * headers (`next-router-prefetch`, `rsc`, …, `FLIGHT_HEADERS` in
+ * next/dist/server/web/adapter.js) and the `_rsc` query BEFORE the proxy runs,
+ * so a router prefetch is invisible here. Skip prefetches in the proxy
+ * MATCHER, which still sees the raw headers:
+ *
+ *   export const config = { matcher: [{ source: "/((?!_next/static|_next/image|.*\\.\\w+$).*)",
+ *     missing: [{ type: "header", key: "next-router-prefetch" }, { type: "header", key: "purpose", value: "prefetch" }] }] };
+ *
+ * Route handlers and other frameworks see the headers, and this still checks them.
+ */
+export function isPrefetchOrAsset(request: Request): boolean {
   const h = request.headers;
-  if (h.get("next-router-prefetch") || h.get("x-middleware-prefetch")) return true;
+  if (h.get("next-router-prefetch") || h.get("next-router-segment-prefetch") || h.get("x-middleware-prefetch")) return true;
   if (/prefetch/i.test(h.get("purpose") ?? "") || /prefetch/i.test(h.get("sec-purpose") ?? "")) return true;
   const path = new URL(request.url).pathname;
   return path.startsWith("/_next/") || /\.[A-Za-z0-9]{1,8}$/.test(path);
@@ -245,6 +296,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
   const { origin, secure } = appOriginOf(config.appUrl);
   const paths: PodAppPaths = { ...DEFAULT_PATHS, ...config.paths };
   const metadata = buildClientMetadata({ ...config, paths });
+  const cloudUrl = config.cloudUrl?.trim() ? cloudBaseUrl(config.cloudUrl, config) : null;
   const clientId = metadata.client_id;
   const redirectUri = metadata.redirect_uris[0];
   const permissions = config.requests.map((r) => r.permission);
@@ -263,6 +315,42 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     return e;
   };
   const clearTx = serializeCookie(names.transaction, "", { maxAgeSec: 0, secure });
+  const clearCloud = serializeCookie(names.cloud, "", { maxAgeSec: 0, secure });
+  const clearMarker = serializeCookie(names.marker, "", { maxAgeSec: 0, secure });
+  const marker = (podUrl: string) => markerCookie(podUrl, { secure, name: names.marker });
+  const asRequest = (source: Request | string | null) =>
+    source instanceof Request ? source : new Request(origin, { headers: source ? { cookie: source } : {} });
+  const lapsedIn = (request: Request) => {
+    const podUrl = readMarker(request.headers.get("cookie"), { secure, name: names.marker, allowInsecureLoopback: config.allowInsecureLoopback });
+    return podUrl ? { podUrl } : null;
+  };
+
+  /** Off to the pod's consent: fresh PKCE + state, the transaction cookie set (extra cookies first). */
+  async function toPod(opts: { pod: string; next: string; space: string | null; prompt: "consent" | null }, extra: string[] = []) {
+    const started = await startConnect({
+      ...flow,
+      pod: opts.pod,
+      clientId,
+      redirectUri,
+      permissions,
+      secret: config.secret,
+      resource: config.resource,
+      spaceHint: opts.space && /^[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), {
@@ -278,27 +366,10 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     const pod = formField(form, "pod")?.slice(0, 512) ?? "";
     const next = safeNextPath(formField(form, "next"), origin) ?? paths.afterConnect;
     const space = formField(form, "space");
+    const prompt = formField(form, "prompt") === "consent" ? "consent" : null;
     try {
-      // A returning person already connected to this pod goes straight on.
-      const existing = await store.read(request);
-      if (existing && existing.accessExpiresAt > now() && existing.podUrl === canonicalPodUrl(pod, config)) {
-        return redirect(new URL(next, origin).href);
-      }
-      const started = await startConnect({
-        ...flow,
-        pod,
-        clientId,
-        redirectUri,
-        permissions,
-        secret: config.secret,
-        resource: config.resource,
-        spaceHint: space && /^[A-Za-z0-9_-]{1,64}$/.test(space) ? space : null,
-        next,
-        allowInsecureLoopback: config.allowInsecureLoopback,
-      });
-      return redirect(started.authorizeUrl, [
-        serializeCookie(names.transaction, started.transaction, { maxAgeSec: TRANSACTION_TTL_MS / 1000, secure }),
-      ]);
+      if (!prompt && (await liveConnectionTo(request, pod))) return redirect(new URL(next, origin).href);
+      return await toPod({ pod, next, space, prompt });
     } catch (err) {
       const e = fail(err, "connect");
       return redirect(withQuery(origin, paths.connectPage, { error: e.code, pod }));
@@ -318,7 +389,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
         secret: config.secret,
       });
       const cookies = await store.write(connection, request);
-      return redirect(new URL(next ?? paths.afterConnect, origin).href, [clearTx, ...cookies]);
+      return redirect(new URL(next ?? paths.afterConnect, origin).href, [clearTx, ...cookies, marker(connection.podUrl)]);
     } catch (err) {
       const e = fail(err, "callback");
       return redirect(withQuery(origin, paths.resultPage, { error: e.code }), [clearTx]);
@@ -334,7 +405,58 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       const { revoked } = await revokeConnection(connection, flow);
       if (!revoked) report(new ConnectError("pod_unreachable", "The pod did not confirm the revocation; the cookie is cleared anyway"), "disconnect");
     }
-    return redirect(new URL(next, origin).href, await store.clear(request));
+    // A sign-out is not a lapse: the marker goes too.
+    return redirect(new URL(next, origin).href, [...(await store.clear(request)), clearMarker]);
+  }
+
+  async function cloudConnect(request: Request): Promise<Response> {
+    if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "POST" } });
+    if (!sameOrigin(request, origin)) return new Response("Forbidden", { status: 403 });
+    const form = await readForm(request);
+    const next = safeNextPath(formField(form, "next"), origin) ?? paths.afterConnect;
+    const space = formField(form, "space");
+    try {
+      const started = await startCloudConnect({
+        cloudUrl,
+        allowInsecureLoopback: config.allowInsecureLoopback,
+        clientId,
+        secret: config.secret,
+        next,
+        spaceHint: space && /^[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> {
@@ -346,7 +468,10 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       cookieHeader: null,
       ...(error ? { error } : {}),
     });
-    if (!connection) return unchanged("none", null);
+    if (!connection) {
+      const lapsed = lapsedIn(request);
+      return lapsed ? { ...unchanged("none", null), lapsed } : unchanged("none", null);
+    }
     if (isPrefetchOrAsset(request)) return unchanged("skipped", connection);
     const t = now();
     const accessLives = connection.accessExpiresAt > t;
@@ -383,6 +508,7 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
       const cleared = await store.clear(request).catch(() => [] as string[]);
       return { status: "expired", connection: null, setCookies: cleared, cookieHeader: null, error: e };
     }
+    setCookies = [...setCookies, marker(next.podUrl)];
     return {
       status: "refreshed",
       connection: next,
@@ -396,9 +522,13 @@ export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
     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 }),
   };

package/src/connect/client.ts

@@ -17,7 +17,7 @@
  * redirect is followed.
  */
 import { retryAfterSeconds } from "./errors";
-import type { PodConnection, PodGrant } from "./types";
+import type { PodConnection, PodGrant, PodSpace } from "./types";
 
 export type PodErrorCode =
   | "expired"
@@ -49,6 +49,38 @@ export type PodWriteResult<T> =
 
 export type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
 
+/** One pending proposal, the pod's summary row (`GET /proposals?view=basic`). */
+export interface PendingProposal {
+  id: string;
+  proposalType: string;
+  targetType: string;
+  targetId: string | null;
+  workspaceId: string | null;
+  /** ISO 8601, as the pod sent it. */
+  createdAt: string;
+  /** The agent that filed it (this app's agent, or another one), when known. */
+  agentUserId: string | null;
+  sessionId: string | null;
+  summary?: string;
+  /** Where the person reviews it: the pod's deep link. */
+  reviewUrl: string;
+}
+
+export interface PendingProposals {
+  /** Every pending proposal the connection can see, not only this page (the pod COUNTs it). */
+  total: number;
+  proposals: PendingProposal[];
+  hasMore: boolean;
+}
+
+export interface ListPendingProposalsOptions {
+  /** One granted space only. */
+  workspaceId?: string;
+  /** 1-200, default 20. */
+  limit?: number;
+  offset?: number;
+}
+
 export interface PodClientOptions {
   fetch?: typeof fetch;
   now?: () => number;
@@ -60,6 +92,16 @@ export interface PodClient {
   grant: PodGrant[];
   /** Whether the connection was granted `permission` (in `workspaceId` when given). */
   can(permission: string, workspaceId?: string): boolean;
+  /** The granted spaces, each with its permissions (`spaces(connection)`). */
+  spaces(): PodSpace[];
+  /**
+   * "Waiting for review: N". The person's pending proposals in the spaces this
+   * connection may read proposals in (any agent's, not only this app's), from
+   * the pod's seamed `GET /proposals` door. Needs the `proposal.read`
+   * permission (ask for it in `requests`): without it the pod would answer an
+   * empty list, so this answers `forbidden` instead, without a request.
+   */
+  listPendingProposals(opts?: ListPendingProposalsOptions): Promise<PodResult<PendingProposals>>;
   get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<PodResult<T>>;
   post<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
   patch<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
@@ -72,6 +114,21 @@ export function can(connection: Pick<PodConnection, "grant">, permission: string
   return connection.grant.some((g) => g.permission === permission && (workspaceId === undefined || g.workspaceId === workspaceId));
 }
 
+/**
+ * The grant by space, in the grant's order, each permission once. The pod
+ * sends one row per permission per space; a space switcher wants one per space.
+ */
+export function spaces(connection: Pick<PodConnection, "grant">): PodSpace[] {
+  const bySpace = new Map<string, PodSpace>();
+  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()];
+}
+
 const SAFE_PATH = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/]*$/;
 
 function hubUrl(podUrl: string, path: string, query?: Record<string, QueryValue>): URL {
@@ -169,11 +226,60 @@ export function createPodClient(connection: PodConnection, opts: PodClientOption
     return { ok: true, status: "applied", data: result.data as T };
   }
 
+  async function listPendingProposals(opts: ListPendingProposalsOptions = {}): Promise<PodResult<PendingProposals>> {
+    if (!can(connection, "proposal.read", opts.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(opts.limit ?? 20), 1), 200);
+    const offset = Math.max(Math.floor(opts.offset ?? 0), 0);
+    const result = await request("GET", "/proposals", undefined, {
+      status: "pending",
+      view: "basic",
+      limit,
+      offset,
+      workspaceId: opts.workspaceId,
+    });
+    if (!result.ok) return result;
+    const obj = result.data && typeof result.data === "object" ? (result.data as Record<string, unknown>) : {};
+    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: unknown): string | null => (typeof v === "string" && v ? v : null);
+    const proposals: PendingProposal[] = [];
+    for (const row of obj.proposals as unknown[]) {
+      if (!row || typeof row !== "object") continue;
+      const r = row as Record<string, unknown>;
+      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<T>(path: string, query?: Record<string, QueryValue>) {
       return request("GET", path, undefined, query) as Promise<PodResult<T>>;
     },

package/src/connect/cloud.ts

@@ -0,0 +1,206 @@
+/**
+ * Connecting through Synap Cloud (wave C1, doc 18 §1.1): the person picks
+ * their pod on the Control Plane instead of typing its address.
+ *
+ *   app  POST <cloud handler>            → 303 <cp>/connect/pod?client_id=<CIMD url>&state=<nonce>
+ *   CP   the person signs in, picks a pod → 302 <initiate_login_uri>?iss=<pod issuer>&state=<nonce>
+ *   app  GET  <cloud handler>?iss&state  → state checked against this browser's sealed
+ *                                          cookie → the SAME sign-in as a typed address
+ *                                          (discovery, fresh PKCE + state, `iss` on the answer)
+ *
+ * The CP never sees a code or a token, and takes the return URL from the
+ * app's client metadata, never from the query. `state` is what makes the
+ * return trustworthy: it is drawn here, kept sealed in an HttpOnly cookie of
+ * this browser, and compared in constant time, so an `iss` link that another
+ * site sends a visitor to (login CSRF into an attacker's pod) is refused. A
+ * return without a matching `state` never starts a sign-in.
+ *
+ * The CP's answer only names a pod. The pod itself is then validated exactly
+ * like a typed address (`discoverPod`), and its answer like any other.
+ */
+import { canonicalPodUrl } from "./discovery";
+import { constantTimeEqual, randomToken } from "./encoding";
+import { ConnectError, fromOAuthError } from "./errors";
+import { seal, unseal, type AppSecret } from "./seal";
+
+/** How long a Synap Cloud sign-in may take, from the click to the pod chooser's return. */
+export const CLOUD_TRANSACTION_TTL_MS = 10 * 60 * 1000;
+
+/** The state the CP accepts (`^[A-Za-z0-9._~-]{16,256}$`); ours is 43 base64url characters. */
+const STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** A sealed `CloudTransaction`: opaque, safe to put in an HttpOnly cookie. */
+export type SealedCloudTransaction = string & { readonly __sealedCloudTransaction: true };
+
+/** What a started Synap Cloud sign-in remembers (sealed; never sent to the CP). */
+export interface CloudTransaction {
+  v: 1;
+  state: string;
+  clientId: string;
+  /** The CP base it was sent to. */
+  cloudUrl: string;
+  next: string | null;
+  spaceHint: string | null;
+  prompt: "consent" | null;
+  createdAt: number;
+}
+
+export interface CloudConnectConfig {
+  /** The Control Plane's base URL, e.g. https://api.synap.live. Unset = no Synap Cloud option. */
+  cloudUrl?: string | null;
+  /** Accept a CP on http://localhost (development). */
+  allowInsecureLoopback?: boolean;
+}
+
+/** The CP base (no trailing slash), or a ConnectError (`misconfigured`). */
+export function cloudBaseUrl(cloudUrl: string, opts: { allowInsecureLoopback?: boolean } = {}): string {
+  let url: 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(/\/+$/, "")}`;
+}
+
+/** Whether "Continue with Synap Cloud" can be offered: a valid Control Plane URL is configured. */
+export function cloudConnectAvailable(config?: CloudConnectConfig | null): boolean {
+  if (!config?.cloudUrl) return false;
+  try {
+    cloudBaseUrl(config.cloudUrl, config);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface StartCloudConnectOptions extends CloudConnectConfig {
+  /** The app's client_id (its CIMD URL): the CP reads `initiate_login_uri` from it. */
+  clientId: string;
+  /** SERVER-ONLY app secret that seals the transaction. */
+  secret?: AppSecret;
+  /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
+  next?: string | null;
+  /** A space to preselect on the pod's consent. */
+  spaceHint?: string | null;
+  /** Show the pod's consent again even if this browser is already connected to the pod the person picks. */
+  prompt?: "consent" | null;
+  /** @deprecated Ignored: the SDK always draws its own 32-byte state. */
+  state?: string;
+  now?: () => number;
+}
+
+export interface StartedCloudConnect {
+  /** Redirect the browser here (303): the CP's pod chooser. */
+  url: string;
+  /** Store in an HttpOnly cookie until the CP returns. */
+  transaction: SealedCloudTransaction;
+  /** ms since epoch. */
+  expiresAt: number;
+}
+
+/**
+ * Start a Synap Cloud sign-in. Throws `cp_unavailable` at once when no CP URL
+ * is configured (as 1.3 always did), `misconfigured` without a secret.
+ */
+export function startCloudConnect(opts: StartCloudConnectOptions): Promise<StartedCloudConnect> {
+  if (!cloudConnectAvailable(opts)) {
+    throw new ConnectError("cp_unavailable", "cp: not configured — 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: CloudTransaction = {
+      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 })) as SealedCloudTransaction;
+    return { url: url.href, transaction, expiresAt };
+  })();
+}
+
+export interface AcceptCloudReturnOptions {
+  /** The URL the CP sent the browser back to (`?iss=…&state=…`). */
+  url: string | URL;
+  transaction: string | null | undefined;
+  clientId: string;
+  secret: AppSecret;
+  allowInsecureLoopback?: boolean;
+  now?: () => number;
+}
+
+export interface CloudReturn {
+  /** The pod the person picked (canonical issuer), still to be discovered and validated. */
+  pod: string;
+  next: string | null;
+  spaceHint: string | null;
+  prompt: "consent" | null;
+}
+
+/**
+ * Check the CP's return against the sealed transaction of THIS browser.
+ * Throws `expired_transaction` (none, foreign, tampered or older than 10
+ * minutes), `mismatch` (the state is not this browser's, or no pod is named),
+ * `denied` (the person cancelled on the chooser: `error=access_denied`, no
+ * `iss`; nothing is started), `invalid_pod_address`.
+ * `state` is compared BEFORE anything else in the query is used.
+ */
+export async function acceptCloudReturn(opts: AcceptCloudReturnOptions): Promise<CloudReturn> {
+  if (!opts.transaction) throw new ConnectError("expired_transaction", "No Synap Cloud sign-in in progress in this browser");
+  const opened = await unseal<CloudTransaction>(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,
+  };
+}