@synap-core/sdk 1.4.0 → 1.5.1

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,13 +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 ./cloud.ts.
+ * 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";
@@ -31,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;
@@ -102,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");
   }
@@ -120,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>;
@@ -165,32 +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;
     }
   }
+  throw tooOld ?? firstError;
 }
 
 /**
@@ -217,11 +251,11 @@ 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
@@ -235,7 +269,7 @@ export interface LaunchHint {
 }
 
 /**
- * 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 the Synap Cloud chooser's return (`cloudState`).
  */
@@ -255,9 +289,9 @@ export function acceptLaunch(url: string | URL, appOrigin: string, opts: { allow
   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 && /^[A-Za-z0-9._~-]{16,256}$/.test(state) ? state : null,
+    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

@@ -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 };
@@ -240,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`);
   }
@@ -270,15 +284,26 @@ 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}$/;
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 
 /**
  * `synap_app` (Synap extension): the pod's id for this app connection and its
@@ -311,8 +336,8 @@ function parseUser(value: unknown): PodUser | null {
 
 /**
  * A token response → a connection. On a refresh, `previous` supplies what the
- * response may omit (grant, user, app). `expires_in` is read as sent: a refresh
- * answered within the pod's reuse grace (PB3b) hands back the live key the
+ * 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.
@@ -362,6 +387,8 @@ export function parseTokenResponse(
   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 =
@@ -375,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
@@ -401,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
@@ -415,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;
@@ -478,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;

package/src/connect/http.ts

@@ -0,0 +1,42 @@
+/**
+ * Reading answers from hosts the SDK does not control: a pod a visitor typed,
+ * its token endpoint, its Hub API. Bounded in time (`timeoutSignal`) and in
+ * bytes (`readCapped`): the bytes are counted on the stream, so an answer past
+ * the cap is cancelled there, never buffered whole first.
+ */
+
+/** An abort signal after `ms`, where the runtime has `AbortSignal.timeout` (workers and edge runtimes may not). */
+export function timeoutSignal(ms: number): AbortSignal | undefined {
+  return typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(ms) : undefined;
+}
+
+export type CappedRead = { ok: true; text: string } | { ok: false; reason: "too_large" | "unreadable" };
+
+/** The body as UTF-8 text, at most `maxBytes` bytes. */
+export async function readCapped(res: Response, maxBytes: number): Promise<CappedRead> {
+  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() };
+}