@synap-core/sdk 1.3.0 → 1.5.0

package/src/connect/cloud.ts

@@ -0,0 +1,210 @@
+/**
+ * Connecting through Synap Cloud: 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 { CLOUD_STATE_RE, LOOPBACK_HOSTS } from "./rules";
+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;
+
+
+/** 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. Required: without it the call throws `misconfigured`.
+   * Optional in the type only for 1.x semver; required in 2.0.
+   */
+  secret?: AppSecret;
+  /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
+  next?: string | null;
+  /** A space hint for the pod's consent (`synap_space_hint`); a pod may ignore it. */
+  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. Removed in 2.0. */
+  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, `misconfigured` without a secret: both SYNCHRONOUSLY, before
+ * a Promise exists, so wrap the call in try/catch rather than relying on
+ * `.catch` (kept from 1.3 for compatibility; 2.0 makes it a plain async
+ * function with a required 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 || !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,
+  };
+}

package/src/connect/discovery.ts

@@ -1,6 +1,6 @@
 /**
- * Pod discovery (spec 17 §6.3): a typed address or a launch `iss` → the pod's
- * authorization server metadata (RFC 8414), validated before any redirect.
+ * Pod discovery: a typed address or a launch `iss` → the pod's authorization
+ * server metadata (RFC 8414), validated before any redirect.
  *
  *  - the metadata's `issuer` must equal the address it was fetched for, byte
  *    for byte (RFC 8414 §3.3): a document naming another issuer is not used;
@@ -11,15 +11,17 @@
  * The fetch runs on the app's server with an address a visitor typed, so it is
  * fenced: https only (http only on loopback when `allowInsecureLoopback`), no
  * IP literal outside public space, no single-label or `.local`/`.internal`
- * host, no redirect followed, 5 s, 64 KB. Residual: a public DNS name that
- * resolves to a private address cannot be refused without a resolver; a
- * deployment that cares adds egress rules.
+ * host, no redirect followed, 5 s, 64 KB counted on the stream. At most three
+ * addresses are tried per call (`discoverPod`). Residual: a public DNS name
+ * that resolves to a private address cannot be refused without a resolver; a
+ * deployment that cares adds egress rules, and an app rate-limits the route
+ * that calls this (it fetches an address a visitor chose).
  *
- * Connecting through Synap Cloud (the CP pod chooser, wave C1) is not
- * available yet: `cloudConnectAvailable()` is false and `startCloudConnect`
- * throws `cp_unavailable`.
+ * Connecting through Synap Cloud (the Control Plane's pod chooser) is ./cloud.ts.
  */
 import { ConnectError, retryAfterSeconds } from "./errors";
+import { readCapped, timeoutSignal } from "./http";
+import { CLOUD_STATE_RE, LOOPBACK_HOSTS, SPACE_HINT_RE } from "./rules";
 import type { PodIssuer } from "./types";
 
 const METADATA_PATH = "/.well-known/oauth-authorization-server";
@@ -33,8 +35,6 @@ export interface DiscoverOptions {
   now?: () => number;
 }
 
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
-
 function isPrivateIpv4(host: string): boolean {
   const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
   if (!m) return false;
@@ -104,10 +104,14 @@ function sameOriginEndpoint(value: unknown, issuer: string): string | null {
 }
 
 async function readJsonCapped(res: Response): Promise<unknown> {
-  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");
   }
@@ -122,18 +126,25 @@ async function discoverIssuer(issuer: string, opts: DiscoverOptions): Promise<Po
       method: "GET",
       headers: { Accept: "application/json" },
       redirect: "manual",
-      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : undefined,
+      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 as Record<string, unknown>;
@@ -167,42 +178,53 @@ async function discoverIssuer(issuer: string, opts: DiscoverOptions): Promise<Po
   };
 }
 
+/** Synap Cloud's pod domain: pods are `<name>.pod.synap.live`; `<name>.synap.live` and `pod.<name>.synap.live` are older names. */
+const CLOUD_DOMAIN = "synap.live";
+const CLOUD_POD_ZONE = `pod.${CLOUD_DOMAIN}`;
+const POD_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$/;
+
+/** The addresses to try after the typed one fails, in order (at most two). */
+function fallbackIssuers(first: string): string[] {
+  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)) {
+    // A Synap Cloud name typed the old way: the pod's current name, then the old nested one.
+    return [`${url.protocol}//${label}.${CLOUD_POD_ZONE}`, `${url.protocol}//pod.${url.host}`];
+  }
+  return host.startsWith("pod.") ? [] : [`${url.protocol}//pod.${url.host}`];
+}
+
 /**
  * A typed pod address (or a launch `iss`) → its validated authorization server.
- * Tries the address, then `pod.<host>` (so "antoine.synap.live" finds
- * "pod.antoine.synap.live").
+ * Tries the address, then the pod names it may stand for: on Synap Cloud,
+ * "you.synap.live" finds "you.pod.synap.live" (and the older
+ * "pod.you.synap.live"); elsewhere, "example.com" finds "pod.example.com".
+ * A redirect is never followed: an old name that answers 308 counts as a
+ * miss (`pod_moved` when nothing else answers).
  */
 export async function discoverPod(input: string, opts: DiscoverOptions = {}): Promise<PodIssuer> {
   const first = canonicalPodUrl(input, opts);
+  let firstError: unknown;
   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: unknown) =>
+    err instanceof ConnectError && (err.code === "not_a_pod" || err.code === "pod_unreachable" || err.code === "pod_moved");
+  if (!retryable(firstError)) throw firstError;
+  let tooOld: ConnectError | null = null;
+  for (const candidate of fallbackIssuers(first)) {
     try {
-      return await discoverIssuer(second, opts);
-    } catch (err2) {
+      return await discoverIssuer(candidate, opts);
+    } catch (err) {
       // A pod that is there but too old says more than "nothing answered".
-      throw err2 instanceof ConnectError && err2.code === "pod_unsupported" ? err2 : err;
+      if (err instanceof ConnectError && err.code === "pod_unsupported") tooOld ??= err;
     }
   }
-}
-
-/** Whether "Continue with Synap Cloud" can be offered. False until the CP pod chooser (C1) ships. */
-export function cloudConnectAvailable(): boolean {
-  return false;
-}
-
-/** The Synap Cloud pod chooser (C1). Not available yet: always throws `cp_unavailable`. */
-export function startCloudConnect(_opts: { clientId: string; state?: string }): never {
-  throw new ConnectError("cp_unavailable", "cp: not available — connecting through Synap Cloud is not built yet; use a pod address");
+  throw tooOld ?? firstError;
 }
 
 /**
@@ -229,18 +251,27 @@ export function safeNextPath(value: string | null | undefined, appOrigin: string
 }
 
 export interface LaunchHint {
-  /** The pod issuer the launcher named (`iss`), to pre-fill and CONFIRM (T6), never to auto-connect. */
+  /** The pod issuer the launcher named (`iss`), to pre-fill and CONFIRM, never to auto-connect. */
   pod: string | null;
   /** Where to land after connecting (`target_link_uri`), same origin only. */
   next: string | null;
-  /** A space to preselect on consent (`synap_space_hint`). */
+  /** A space hint for the pod's consent (`synap_space_hint`); a pod may ignore it. */
   spaceHint: string | null;
+  /**
+   * The `state` of a Synap Cloud return (the CP pod chooser answers
+   * `initiate_login_uri?iss=…&state=…`, or `?state=…&error=access_denied` when
+   * the person cancelled), shape-checked only. NOT verified here:
+   * send the request's query to the cloud handler (GET `paths.cloud`), which
+   * checks it against this browser's sealed cookie. Never act on `pod` because
+   * a state is present.
+   */
+  cloudState: string | null;
 }
 
 /**
- * Read a third-party-initiated login (OIDC Core §4, spec 17 §7.2): the browser
+ * Read a third-party-initiated login (OIDC Core §4): the browser
  * opens the app's `initiate_login_uri?iss=…&target_link_uri=…`. One parser for
- * the browser launch and, later, the Synap Cloud chooser's return.
+ * the browser launch and the Synap Cloud chooser's return (`cloudState`).
  */
 export function acceptLaunch(url: string | URL, appOrigin: string, opts: { allowInsecureLoopback?: boolean } = {}): LaunchHint {
   const params = new URL(url).searchParams;
@@ -254,9 +285,13 @@ export function acceptLaunch(url: string | URL, appOrigin: string, opts: { allow
     }
   }
   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,
   };
 }

package/src/connect/encoding.ts

@@ -1,6 +1,6 @@
 /**
  * Web-standard primitives (WebCrypto, TextEncoder, btoa/atob): the same code
- * runs on Node 18+, edge runtimes and workers. No Node import.
+ * runs on Node 20+, edge runtimes and workers. No Node import.
  */
 
 const encoder = new TextEncoder();

package/src/connect/errors.ts

@@ -13,7 +13,7 @@ export type ConnectErrorCode =
   | "pod_unreachable"
   /** A Synap pod, but too old for app sign-in (no CIMD, no `iss`, no S256). */
   | "pod_unsupported"
-  /** Connecting through Synap Cloud is not available yet. */
+  /** Connecting through Synap Cloud is not configured for this app (no Control Plane URL). */
   | "cp_unavailable"
   /** The person said no on the consent screen. */
   | "denied"
@@ -29,6 +29,12 @@ export type ConnectErrorCode =
   | "expired"
   /** The pod refused the connection's refresh token while it should still live. */
   | "revoked"
+  /**
+   * The pod answered a redirect where it must answer itself (a moved pod
+   * answers 308 from its old name for a while): connect again with its new
+   * address. The new address is never taken from the redirect.
+   */
+  | "pod_moved"
   /** The pod answered something the SDK cannot use. */
   | "server_error";
 
@@ -69,6 +75,7 @@ export const CONNECT_ERROR_CODES: readonly ConnectErrorCode[] = [
   "rate_limited",
   "expired",
   "revoked",
+  "pod_moved",
   "server_error",
 ];
 

package/src/connect/flow.ts

@@ -1,5 +1,5 @@
 /**
- * The OAuth 2.1 authorization-code flow of a pod app (spec 17 §6.4-§6.7), as
+ * The OAuth 2.1 authorization-code flow of a pod app, as
  * plain functions over a SEALED transaction string. `createPodAppAuth` wires
  * them to cookies and route handlers; use these directly for another store.
  *
@@ -18,15 +18,19 @@
 import { ConnectError, fromOAuthError, retryAfterSeconds } from "./errors";
 import { constantTimeEqual, pkceChallenge, randomToken } from "./encoding";
 import { discoverPod, type DiscoverOptions } from "./discovery";
+import { readCapped, timeoutSignal } from "./http";
+import { LOOPBACK_HOSTS } from "./rules";
 import { seal, unseal, type AppSecret } from "./seal";
-import type { PodConnection, PodGrant, PodIssuer, PodUser } from "./types";
+import type { PodActsAs, PodConnection, PodGrant, PodIssuer, PodUser } from "./types";
 
 /** How long a started sign-in stays valid. */
 export const TRANSACTION_TTL_MS = 10 * 60 * 1000;
-/** The refresh token's idle life when the pod does not say (spec 17 F5: 30 days). */
+/** The refresh token's idle life when the pod does not say (the pod's: 30 days). */
 export const DEFAULT_REFRESH_IDLE_MS = 30 * 24 * 60 * 60 * 1000;
 const DEFAULT_ACCESS_TTL_SEC = 3600;
 const TIMEOUT_MS = 10_000;
+/** A token response is a few KB; more is not a token response. */
+const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
 
 /** A sealed `ConnectTransaction`: opaque, safe to put in an HttpOnly cookie. */
 export type SealedTransaction = string & { readonly __sealedTransaction: true };
@@ -66,6 +70,12 @@ export interface StartConnectOptions extends FlowOptions {
   spaceHint?: string | null;
   /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
   next?: string | null;
+  /**
+   * `"consent"`: the person asked to see the consent screen again (to widen or
+   * narrow what the app may touch). Sent as OIDC `prompt=consent`; the sign-in
+   * is otherwise the same (fresh PKCE verifier and state).
+   */
+  prompt?: "consent" | null;
   allowInsecureLoopback?: boolean;
 }
 
@@ -114,6 +124,7 @@ export async function startConnect(opts: StartConnectOptions): Promise<StartedCo
   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: ConnectTransaction = {
     v: 1,
@@ -233,20 +244,30 @@ async function tokenRequest(
       headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
       body: body.toString(),
       redirect: "manual",
-      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : undefined,
+      signal: timeoutSignal(TIMEOUT_MS),
     });
   } 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: unknown;
   try {
-    json = await res.json();
+    json = JSON.parse(read.text);
   } catch {
     throw new ConnectError("server_error", `The token endpoint answered ${res.status} without JSON`);
   }
@@ -263,9 +284,46 @@ function parseGrant(value: unknown): PodGrant[] | null {
   const out: PodGrant[] = [];
   for (const g of value) {
     if (!g || typeof g !== "object") return null;
-    const { permission, workspaceId, workspaceName } = g as Record<string, unknown>;
+    const { permission, workspaceId, workspaceName, templateSlug } = g as Record<string, unknown>;
     if (typeof permission !== "string" || typeof workspaceId !== "string") return null;
-    out.push({ permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" });
+    const row: PodGrant = { permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" };
+    // The space's template, omitted when it came from none.
+    if (typeof templateSlug === "string" && templateSlug.length > 0 && templateSlug.length <= 200) row.templateSlug = templateSlug;
+    out.push(row);
+  }
+  return out;
+}
+
+/**
+ * `synap_acts_as`: read from EVERY token response, never carried
+ * over from the previous one, so a pod that stops saying "person" (or never
+ * did) gives an agent connection.
+ */
+function parseActsAs(value: unknown): PodActsAs | undefined {
+  return value === "person" || value === "agent" ? value : undefined;
+}
+
+const APP_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+
+/**
+ * `synap_app` (Synap extension): the pod's id for this app connection and its
+ * page for it. The page is on the pod's console, which may be another host
+ * than the issuer, so it is kept when it is an absolute https URL (http only on
+ * loopback) without credentials; anything else is dropped.
+ */
+function parseApp(value: unknown): { appId?: string; manageUrl?: string } {
+  if (!value || typeof value !== "object") return {};
+  const { id, manageUrl } = value as Record<string, unknown>;
+  const out: { appId?: string; manageUrl?: string } = {};
+  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 {
+      // not a URL: no link
+    }
   }
   return out;
 }
@@ -278,7 +336,9 @@ function parseUser(value: unknown): PodUser | null {
 
 /**
  * A token response → a connection. On a refresh, `previous` supplies what the
- * response may omit (grant, user). A refresh response WITHOUT a new
+ * response may omit (grant, user, app; never `actsAs`). `expires_in` is read as sent: a refresh
+ * answered within the pod's reuse grace hands back the live key the
+ * first redeem got, with less than an hour left. A refresh response WITHOUT a new
  * refresh_token drops the old one: with single-use rotation, resending a
  * consumed token reads as theft and revokes the whole family.
  */
@@ -322,6 +382,13 @@ export function parseTokenResponse(
     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 !== undefined) connection.appId = appId;
+  if (manageUrl !== undefined) connection.manageUrl = manageUrl;
+  const actsAs = parseActsAs(body.synap_acts_as);
+  if (actsAs !== undefined) connection.actsAs = actsAs;
   if (typeof refresh_token === "string" && refresh_token !== "") {
     connection.refreshToken = refresh_token;
     const idle =
@@ -335,7 +402,7 @@ export function parseTokenResponse(
 
 /**
  * How long a rotation's result is remembered for its SPENT refresh token.
- * The pod (PB3) refuses a concurrent second redeem softly, but a token
+ * The pod refuses a concurrent second redeem softly, but a token
  * presented AGAIN after its use is a reuse: the whole family and the live
  * access key are revoked. A browser easily sends that replay: parallel
  * requests, a second tab, a response it had not stored yet, all still
@@ -361,7 +428,7 @@ function pruneRotations(now: number): void {
 
 /**
  * Exchange the refresh token for a new access token and the rotated refresh
- * token (PB3: single-use, 30 days from issue, reach re-derived by the pod).
+ * token (single-use, 30 days from issue, its reach re-derived by the pod).
  *
  * SINGLE-FLIGHT per connection within this process: concurrent callers share
  * one request, and for `ROTATION_MEMORY_MS` after it a caller still holding
@@ -375,7 +442,7 @@ function pruneRotations(now: number): void {
  * (invalid_grant while it should live: spent, revoked, the app removed or
  * narrowed to nothing, or a concurrent redeem lost), `misconfigured`
  * (invalid_client, unauthorized_client), `rate_limited`, `pod_unreachable`,
- * `server_error`.
+ * `pod_moved` (the token endpoint answered a redirect), `server_error`.
  */
 export function refreshConnection(connection: PodConnection, opts: FlowOptions = {}): Promise<PodConnection> {
   const clock = opts.now ?? Date.now;
@@ -438,8 +505,9 @@ export async function revokeConnection(connection: PodConnection, opts: FlowOpti
         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_MS) : undefined,
+        signal: timeoutSignal(TIMEOUT_MS),
       });
+      await res.body?.cancel().catch(() => {});
       if (res.status !== 200) revoked = false;
     } catch {
       revoked = false;