@synap-core/sdk 1.4.0 → 1.5.1

package/dist/connect.js

@@ -1,15 +1,19 @@
 import {
+  CLOUD_STATE_RE,
+  LOOPBACK_HOSTS,
+  SPACE_HINT_RE,
   base64url,
   constantTimeEqual,
   fromBase64url,
   fromUtf8,
+  isIpLiteral,
   parseCookies,
   pkceChallenge,
   randomBytes,
   randomToken,
   serializeCookie,
   utf8
-} from "./chunk-J7XHAAFJ.js";
+} from "./chunk-UK2U6SMA.js";
 
 // src/connect/guard.ts
 var BROWSER_REFUSAL = "@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. Import it from route handlers, proxy.ts or server code, never from a client component.";
@@ -52,6 +56,7 @@ var CONNECT_ERROR_CODES = [
   "rate_limited",
   "expired",
   "revoked",
+  "pod_moved",
   "server_error"
 ];
 function parseConnectErrorCode(value) {
@@ -87,11 +92,44 @@ function retryAfterSeconds(header, now) {
   return Math.max(0, Math.ceil((at - now) / 1e3));
 }
 
+// src/connect/http.ts
+function timeoutSignal(ms) {
+  return typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(ms) : void 0;
+}
+async function readCapped(res, maxBytes) {
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    await res.body?.cancel().catch(() => {
+    });
+    return { ok: false, reason: "too_large" };
+  }
+  if (!res.body) return { ok: true, text: "" };
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let total = 0;
+  let text = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {
+        });
+        return { ok: false, reason: "too_large" };
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+  } catch {
+    return { ok: false, reason: "unreadable" };
+  }
+  return { ok: true, text: text + decoder.decode() };
+}
+
 // src/connect/discovery.ts
 var METADATA_PATH = "/.well-known/oauth-authorization-server";
 var TIMEOUT_MS = 5e3;
 var MAX_METADATA_BYTES = 64 * 1024;
-var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
 function isPrivateIpv4(host) {
   const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
   if (!m) return false;
@@ -144,10 +182,12 @@ function sameOriginEndpoint(value, issuer) {
   }
 }
 async function readJsonCapped(res) {
-  const text = await res.text();
-  if (text.length > MAX_METADATA_BYTES) throw new ConnectError("not_a_pod", "Metadata document too large");
+  const read = await readCapped(res, MAX_METADATA_BYTES);
+  if (!read.ok) {
+    throw read.reason === "too_large" ? new ConnectError("not_a_pod", "Metadata document too large") : new ConnectError("pod_unreachable", "The metadata answer broke off");
+  }
   try {
-    return JSON.parse(text);
+    return JSON.parse(read.text);
   } catch {
     throw new ConnectError("not_a_pod", "Metadata is not JSON");
   }
@@ -160,18 +200,27 @@ async function discoverIssuer(issuer, opts) {
       method: "GET",
       headers: { Accept: "application/json" },
       redirect: "manual",
-      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS) : void 0
+      signal: timeoutSignal(TIMEOUT_MS)
     });
   } catch {
     throw new ConnectError("pod_unreachable", "The pod did not answer");
   }
+  if (res.status >= 300 && res.status < 400) {
+    await res.body?.cancel().catch(() => {
+    });
+    throw new ConnectError("pod_moved", `The address answered ${res.status}: the pod moved (its new address is not followed)`);
+  }
   if (res.status === 429) {
     throw new ConnectError("rate_limited", "The pod asked to slow down", {
       retryAfterSec: retryAfterSeconds(res.headers.get("retry-after"), (opts.now ?? Date.now)())
     });
   }
   if (res.status >= 500) throw new ConnectError("pod_unreachable", `The pod answered ${res.status}`);
-  if (res.status !== 200) throw new ConnectError("not_a_pod", `No authorization server metadata (${res.status})`);
+  if (res.status !== 200) {
+    await res.body?.cancel().catch(() => {
+    });
+    throw new ConnectError("not_a_pod", `No authorization server metadata (${res.status})`);
+  }
   const doc = await readJsonCapped(res);
   if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new ConnectError("not_a_pod", "Metadata is not an object");
   const m = doc;
@@ -197,21 +246,38 @@ async function discoverIssuer(issuer, opts) {
     refreshSupported: list(m.grant_types_supported)?.includes("refresh_token") ?? false
   };
 }
+var CLOUD_DOMAIN = "synap.live";
+var CLOUD_POD_ZONE = `pod.${CLOUD_DOMAIN}`;
+var POD_NAME_RE = /^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$/;
+function fallbackIssuers(first) {
+  const url = new URL(first);
+  const host = url.hostname;
+  if (url.pathname !== "/" || !host.includes(".") || host.endsWith(`.${CLOUD_POD_ZONE}`)) return [];
+  const label = host.endsWith(`.${CLOUD_DOMAIN}`) ? host.slice(0, -CLOUD_DOMAIN.length - 1) : null;
+  if (label !== null && POD_NAME_RE.test(label)) {
+    return [`${url.protocol}//${label}.${CLOUD_POD_ZONE}`, `${url.protocol}//pod.${url.host}`];
+  }
+  return host.startsWith("pod.") ? [] : [`${url.protocol}//pod.${url.host}`];
+}
 async function discoverPod(input, opts = {}) {
   const first = canonicalPodUrl(input, opts);
+  let firstError;
   try {
     return await discoverIssuer(first, opts);
   } catch (err) {
-    const url = new URL(first);
-    const retry = err instanceof ConnectError && (err.code === "not_a_pod" || err.code === "pod_unreachable") && !url.hostname.startsWith("pod.") && url.pathname === "/" && url.hostname.includes(".");
-    if (!retry) throw err;
-    const second = `${url.protocol}//pod.${url.host}`;
+    firstError = err;
+  }
+  const retryable = (err) => err instanceof ConnectError && (err.code === "not_a_pod" || err.code === "pod_unreachable" || err.code === "pod_moved");
+  if (!retryable(firstError)) throw firstError;
+  let tooOld = null;
+  for (const candidate of fallbackIssuers(first)) {
     try {
-      return await discoverIssuer(second, opts);
-    } catch (err2) {
-      throw err2 instanceof ConnectError && err2.code === "pod_unsupported" ? err2 : err;
+      return await discoverIssuer(candidate, opts);
+    } catch (err) {
+      if (err instanceof ConnectError && err.code === "pod_unsupported") tooOld ??= err;
     }
   }
+  throw tooOld ?? firstError;
 }
 function safeNextPath(value, appOrigin) {
   if (!value || value.length > 2048) return null;
@@ -246,10 +312,10 @@ function acceptLaunch(url, appOrigin, opts = {}) {
   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
   };
 }
 
@@ -338,8 +404,6 @@ async function unseal(sealed, opts) {
 
 // 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 {
@@ -347,7 +411,7 @@ function cloudBaseUrl(cloudUrl, opts = {}) {
   } catch {
     throw new ConnectError("misconfigured", "cloudUrl is not a URL");
   }
-  const loopback = LOOPBACK_HOSTS2.has(url.hostname);
+  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)");
   }
@@ -415,7 +479,7 @@ async function acceptCloudReturn(opts) {
   }
   const params = new URL(opts.url).searchParams;
   const state = params.get("state");
-  if (state === null || !STATE_RE.test(state) || !constantTimeEqual(state, tx.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");
@@ -433,6 +497,12 @@ async function acceptCloudReturn(opts) {
 }
 
 // src/connect/client.ts
+function connectionActsAs(connection) {
+  return connection.actsAs === "person" ? "person" : "agent";
+}
+function humanSlots(session) {
+  return session.expectedOutputs.filter((slot) => slot.owner === "human" && slot.status !== "done" && !slot.retiredAt);
+}
 function can(connection, permission, workspaceId) {
   return connection.grant.some((g) => g.permission === permission && (workspaceId === void 0 || g.workspaceId === workspaceId));
 }
@@ -441,23 +511,50 @@ function spaces(connection) {
   for (const g of connection.grant) {
     const space = bySpace.get(g.workspaceId) ?? { workspaceId: g.workspaceId, workspaceName: g.workspaceName, permissions: [] };
     if (!space.workspaceName && g.workspaceName) space.workspaceName = g.workspaceName;
+    if (!space.templateSlug && g.templateSlug) space.templateSlug = g.templateSlug;
     if (!space.permissions.includes(g.permission)) space.permissions.push(g.permission);
     bySpace.set(g.workspaceId, space);
   }
   return [...bySpace.values()];
 }
+var ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+var PROPOSAL_IDS_MAX = 100;
 var SAFE_PATH = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/]*$/;
+var TIMEOUT_MS2 = 1e4;
+var MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 function hubUrl(podUrl, path, query) {
-  if (!SAFE_PATH.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) {
-    throw new TypeError(`Not a Hub API path: ${path}`);
+  if (!SAFE_PATH.test(path) || /%2e/i.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) return null;
+  let url;
+  try {
+    url = new URL(`${podUrl}/api/hub${path}`);
+  } catch {
+    return null;
   }
-  const url = new URL(`${podUrl}/api/hub${path}`);
+  if (url.origin !== new URL(podUrl).origin || !(url.pathname === "/api/hub" || url.pathname.startsWith("/api/hub/"))) return null;
   for (const [key, value] of Object.entries(query ?? {})) {
     if (value === void 0 || value === null) continue;
     for (const v of Array.isArray(value) ? value : [value]) url.searchParams.append(key, String(v));
   }
   return url;
 }
+function renewalError(err) {
+  const e = isConnectError(err) ? err : null;
+  const detail = e?.message ?? (err instanceof Error ? err.message : "The connection could not be renewed");
+  switch (e?.code) {
+    case "revoked":
+      return { code: "unauthorized", status: 401, detail };
+    case "expired":
+      return { code: "expired", status: null, detail };
+    case "rate_limited":
+      return { code: "rate_limited", status: null, detail, ...e.retryAfterSec !== void 0 ? { retryAfterSec: e.retryAfterSec } : {} };
+    case "pod_unreachable":
+      return { code: "pod_unreachable", status: null, detail };
+    case "pod_moved":
+      return { code: "pod_moved", status: null, detail };
+    default:
+      return { code: "server", status: null, detail };
+  }
+}
 function errorFor(status, body, retryAfter, now) {
   const obj = body && typeof body === "object" ? body : {};
   const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : void 0;
@@ -472,6 +569,7 @@ function errorFor(status, body, retryAfter, now) {
     return { code: "rate_limited", ...base, ...retryAfterSec !== void 0 ? { retryAfterSec } : {} };
   }
   if (status === 502 || status === 503 || status === 504) return { code: "pod_unreachable", ...base };
+  if (status >= 300 && status < 400) return { code: "pod_moved", ...base };
   return { code: "server", ...base };
 }
 function reviewUrlFor(podUrl, reviewUrl, proposalId) {
@@ -484,13 +582,37 @@ function reviewUrlFor(podUrl, reviewUrl, proposalId) {
   }
   return proposalId ? `${podUrl}/open/${encodeURIComponent(proposalId)}` : podUrl;
 }
+function refused(code, reason, detail) {
+  return { ok: false, error: { code, status: null, detail, reason } };
+}
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function hasId(value) {
+  return asObject(value) !== null && typeof value.id === "string";
+}
 function createPodClient(connection, opts = {}) {
   const now = opts.now ?? Date.now;
   const doFetch = () => opts.fetch ?? fetch;
-  async function request(method, path, body, query) {
-    const url = hubUrl(connection.podUrl, path, query);
-    if (connection.accessExpiresAt <= now()) return { ok: false, error: { code: "expired", status: null } };
-    const headers = { Accept: "application/json", Authorization: `Bearer ${connection.accessToken}` };
+  let current = connection;
+  let renewal = null;
+  function renewOnce(refused2) {
+    if (current !== refused2) return Promise.resolve({ ok: true, data: current });
+    renewal ??= opts.renew(refused2).then(
+      (next) => {
+        current = next;
+        return { ok: true, data: next };
+      },
+      (err) => ({ ok: false, error: renewalError(err) })
+    );
+    return renewal;
+  }
+  async function request(method, path, body, query, retried = false) {
+    const sent = current;
+    const url = hubUrl(sent.podUrl, path, query);
+    if (!url) return refused("invalid", "invalid_input", "Not a Hub API path: encode each path segment (encodeURIComponent)");
+    if (sent.accessExpiresAt <= now()) return { ok: false, error: { code: "expired", status: null } };
+    const headers = { Accept: "application/json", Authorization: `Bearer ${sent.accessToken}` };
     if (body !== void 0) headers["Content-Type"] = "application/json";
     let res;
     try {
@@ -498,21 +620,33 @@ function createPodClient(connection, opts = {}) {
         method,
         headers,
         body: body === void 0 ? void 0 : JSON.stringify(body),
-        redirect: "manual"
+        redirect: "manual",
+        signal: timeoutSignal(opts.timeoutMs ?? TIMEOUT_MS2)
       });
     } catch {
       return { ok: false, error: { code: "pod_unreachable", status: null } };
     }
+    const read2 = await readCapped(res, opts.maxResponseBytes ?? MAX_RESPONSE_BYTES);
+    if (!read2.ok) {
+      return read2.reason === "too_large" ? { ok: false, error: { code: "server", status: res.status, detail: "The pod's answer is larger than maxResponseBytes" } } : { ok: false, error: { code: "pod_unreachable", status: res.status, detail: "The pod's answer broke off" } };
+    }
     let data = null;
-    const text = await res.text().catch(() => "");
-    if (text) {
+    if (read2.text) {
       try {
-        data = JSON.parse(text);
+        data = JSON.parse(read2.text);
       } catch {
         data = null;
       }
     }
     if (res.status >= 200 && res.status < 300) return { ok: true, data };
+    if (res.status === 401 && sent.refreshToken) {
+      if (!opts.renew) return { ok: false, error: { ...errorFor(401, data, null, now()), refreshable: true } };
+      if (!retried) {
+        const renewed = await renewOnce(sent);
+        if (!renewed.ok) return renewed;
+        return request(method, path, body, query, true);
+      }
+    }
     return { ok: false, error: errorFor(res.status, data, res.headers.get("retry-after"), now()) };
   }
   async function write(method, path, body) {
@@ -525,18 +659,23 @@ function createPodClient(connection, opts = {}) {
         ok: true,
         status: "proposed",
         proposalId,
-        reviewUrl: reviewUrlFor(connection.podUrl, obj.reviewUrl, proposalId),
+        reviewUrl: reviewUrlFor(current.podUrl, obj.reviewUrl, proposalId),
         data: result.data
       };
     }
     return { ok: true, status: "applied", data: result.data };
   }
   async function listPendingProposals(opts2 = {}) {
-    if (!can(connection, "proposal.read", opts2.workspaceId)) {
-      return {
-        ok: false,
-        error: { code: "forbidden", status: null, detail: "The connection was not granted proposal.read in that space" }
-      };
+    if (!can(current, "proposal.read", opts2.workspaceId)) {
+      return refused("forbidden", "not_granted", "The connection was not granted proposal.read in that space");
+    }
+    let only = null;
+    if (opts2.proposalIds !== void 0) {
+      if (opts2.proposalIds.length > PROPOSAL_IDS_MAX || opts2.proposalIds.some((id) => !ID_RE.test(id))) {
+        return refused("invalid", "invalid_input", `proposalIds must be at most ${PROPOSAL_IDS_MAX} proposal ids`);
+      }
+      if (opts2.proposalIds.length === 0) return { ok: true, data: { total: 0, proposals: [], hasMore: false } };
+      only = new Set(opts2.proposalIds);
     }
     const limit = Math.min(Math.max(Math.floor(opts2.limit ?? 20), 1), 200);
     const offset = Math.max(Math.floor(opts2.offset ?? 0), 0);
@@ -545,7 +684,8 @@ function createPodClient(connection, opts = {}) {
       view: "basic",
       limit,
       offset,
-      workspaceId: opts2.workspaceId
+      workspaceId: opts2.workspaceId,
+      ...only ? { proposalIds: [...only].join(",") } : {}
     });
     if (!result.ok) return result;
     const obj = result.data && typeof result.data === "object" ? result.data : {};
@@ -558,7 +698,7 @@ function createPodClient(connection, opts = {}) {
       if (!row || typeof row !== "object") continue;
       const r = row;
       const id = str(r.id);
-      if (!id) continue;
+      if (!id || only && !only.has(id)) continue;
       proposals.push({
         id,
         proposalType: str(r.proposalType) ?? "",
@@ -569,7 +709,7 @@ function createPodClient(connection, opts = {}) {
         agentUserId: str(r.agentUserId),
         sessionId: str(r.sessionId),
         ...str(r.summary) ? { summary: str(r.summary) } : {},
-        reviewUrl: reviewUrlFor(connection.podUrl, null, id)
+        reviewUrl: reviewUrlFor(current.podUrl, null, id)
       });
     }
     return {
@@ -577,13 +717,134 @@ function createPodClient(connection, opts = {}) {
       data: { total: obj.total, proposals, hasMore: obj.hasMore === true || offset + proposals.length < obj.total }
     };
   }
+  async function read(path, query, shape) {
+    const result = await request("GET", path, void 0, query);
+    if (!result.ok) return result;
+    const data = shape(result.data);
+    if (data === null) return { ok: false, error: { code: "server", status: 200, detail: `The pod's ${path.split("/")[1]} answer is not the expected shape` } };
+    return { ok: true, data };
+  }
+  const badId = (what) => refused("invalid", "invalid_input", `Not a ${what} id`);
+  const clamp = (n, min, max) => n === void 0 ? void 0 : Math.min(Math.max(Math.floor(n), min), max);
+  function listEntities(opts2 = {}) {
+    return read("/entities", {
+      workspaceId: opts2.workspaceId,
+      profileSlug: opts2.profileSlug,
+      limit: clamp(opts2.limit, 1, 1e3),
+      offset: clamp(opts2.offset, 0, Number.MAX_SAFE_INTEGER),
+      sort: opts2.sort,
+      includePodWide: opts2.includePodWide,
+      facetSlug: opts2.facetSlug,
+      // Sent only when asked: the default request stays the 1.5.0 one.
+      includeFacets: opts2.includeFacets ? true : void 0
+    }, (data) => Array.isArray(data) ? data.filter(hasId) : null);
+  }
+  async function getEntity(id) {
+    if (!ID_RE.test(id)) return badId("entity");
+    return read(`/entities/${id}`, void 0, (data) => hasId(data) ? data : null);
+  }
+  async function getEntityConnections(id, opts2 = {}) {
+    if (!ID_RE.test(id)) return badId("entity");
+    return read(`/entities/${id}/connections`, { workspaceId: opts2.workspaceId, limit: clamp(opts2.limit, 1, 200) }, (data) => {
+      const obj = asObject(data);
+      if (!obj || !Array.isArray(obj.connections)) return null;
+      const connections = obj.connections.filter(
+        (c) => !!c && typeof c === "object" && typeof c.entityId === "string"
+      );
+      const counts = asObject(obj.counts) ?? {};
+      const count = (key, source) => typeof counts[key] === "number" ? counts[key] : connections.filter((c) => c.source === source).length;
+      return {
+        connections,
+        counts: {
+          total: typeof counts.total === "number" ? counts.total : connections.length,
+          graph: count("graph", "graph"),
+          structural: count("structural", "property"),
+          threads: count("threads", "thread"),
+          contextChannels: count("contextChannels", "context_channel"),
+          focusSessions: count("focusSessions", "focus_session")
+        }
+      };
+    });
+  }
+  async function getDocument(id, opts2 = {}) {
+    if (!ID_RE.test(id)) return badId("document");
+    return read(`/documents/${id}`, { format: opts2.format }, (data) => {
+      const doc = asObject(asObject(data)?.document);
+      if (!doc || typeof doc.id !== "string" || typeof doc.content !== "string") return null;
+      return { ...doc, sections: Array.isArray(doc.sections) ? doc.sections : [] };
+    });
+  }
+  async function listFocusSessions(opts2) {
+    if (!opts2?.workspaceId && !opts2?.projectId) return refused("invalid", "invalid_input", "workspaceId or projectId is required");
+    return read("/focus-sessions", {
+      workspaceId: opts2.workspaceId,
+      projectId: opts2.projectId,
+      status: opts2.status,
+      limit: clamp(opts2.limit, 1, 50),
+      lens: opts2.lens,
+      kind: opts2.kind,
+      subjectEntityId: opts2.subjectEntityId
+    }, (data) => {
+      if (!Array.isArray(data)) return null;
+      return data.filter(hasId).map((row) => ({
+        ...row,
+        expectedOutputs: Array.isArray(row.expectedOutputs) ? row.expectedOutputs.filter((s) => !!s && typeof s === "object" && typeof s.label === "string") : []
+      }));
+    });
+  }
+  async function getFileUrl(entityId) {
+    if (!ID_RE.test(entityId)) return badId("file");
+    return read(`/files/${entityId}/url`, void 0, (data) => {
+      const obj = asObject(data);
+      if (!obj || typeof obj.url !== "string" || typeof obj.expiresAt !== "string") return null;
+      return { url: obj.url, expiresAt: obj.expiresAt, mimeType: typeof obj.mimeType === "string" ? obj.mimeType : null };
+    });
+  }
+  async function approveProposal(id, opts2 = {}) {
+    if (connectionActsAs(current) !== "person") {
+      return refused("forbidden", "agent_cannot_approve", "An agent connection can never approve: approval is the person's");
+    }
+    if (!can(current, "proposal.approve", opts2.workspaceId)) {
+      return refused("forbidden", "not_granted", "The connection was not granted proposal.approve in that space");
+    }
+    if (!ID_RE.test(id)) return badId("proposal");
+    const result = await request("POST", `/proposals/${id}/approve`, {});
+    if (!result.ok) return result;
+    const obj = asObject(result.data);
+    if (!obj || typeof obj.proposalId !== "string") {
+      return { ok: false, error: { code: "server", status: 200, detail: "The pod's approve answer names no proposalId" } };
+    }
+    return {
+      ok: true,
+      data: {
+        proposalId: obj.proposalId,
+        ...typeof obj.primaryId === "string" ? { primaryId: obj.primaryId } : {},
+        ...typeof obj.linked === "number" ? { linked: obj.linked } : {},
+        proposal: asObject(obj.proposal)
+      }
+    };
+  }
   return {
     podUrl: connection.podUrl,
-    user: connection.user,
-    grant: connection.grant,
-    can: (permission, workspaceId) => can(connection, permission, workspaceId),
-    spaces: () => spaces(connection),
+    get user() {
+      return current.user;
+    },
+    get grant() {
+      return current.grant;
+    },
+    get actsAs() {
+      return connectionActsAs(current);
+    },
+    can: (permission, workspaceId) => can(current, permission, workspaceId),
+    spaces: () => spaces(current),
     listPendingProposals,
+    listEntities,
+    getEntity,
+    getEntityConnections,
+    getDocument,
+    listFocusSessions,
+    getFileUrl,
+    approveProposal,
     get(path, query) {
       return request("GET", path, void 0, query);
     },
@@ -606,7 +867,8 @@ function createPodClient(connection, opts = {}) {
 var TRANSACTION_TTL_MS = 10 * 60 * 1e3;
 var DEFAULT_REFRESH_IDLE_MS = 30 * 24 * 60 * 60 * 1e3;
 var DEFAULT_ACCESS_TTL_SEC = 3600;
-var TIMEOUT_MS2 = 1e4;
+var TIMEOUT_MS3 = 1e4;
+var MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
 var PERMISSION_RE = /^[a-z][a-z0-9_-]*(\.[a-z0-9_-]+)+$/i;
 function assertPermissions(permissions) {
   const unique = [...new Set(permissions)];
@@ -724,20 +986,29 @@ async function tokenRequest(endpoint, body, during, opts) {
       headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
       body: body.toString(),
       redirect: "manual",
-      signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS2) : void 0
+      signal: timeoutSignal(TIMEOUT_MS3)
     });
   } catch {
     throw new ConnectError("pod_unreachable", "The pod's token endpoint did not answer");
   }
+  if (res.status >= 300 && res.status < 400) {
+    await res.body?.cancel().catch(() => {
+    });
+    throw new ConnectError("pod_moved", `The token endpoint answered ${res.status}: the pod moved; connect again with its new address`);
+  }
   if (res.status === 429) {
     throw new ConnectError("rate_limited", "The pod asked to slow down", {
       retryAfterSec: retryAfterSeconds(res.headers.get("retry-after"), (opts.now ?? Date.now)())
     });
   }
   if (res.status >= 500) throw new ConnectError("pod_unreachable", `The token endpoint answered ${res.status}`);
+  const read = await readCapped(res, MAX_TOKEN_RESPONSE_BYTES);
+  if (!read.ok) {
+    throw read.reason === "too_large" ? new ConnectError("server_error", "The token endpoint's answer is too large") : new ConnectError("pod_unreachable", "The token endpoint's answer broke off");
+  }
   let json;
   try {
-    json = await res.json();
+    json = JSON.parse(read.text);
   } catch {
     throw new ConnectError("server_error", `The token endpoint answered ${res.status} without JSON`);
   }
@@ -753,14 +1024,18 @@ function parseGrant(value) {
   const out = [];
   for (const g of value) {
     if (!g || typeof g !== "object") return null;
-    const { permission, workspaceId, workspaceName } = g;
+    const { permission, workspaceId, workspaceName, templateSlug } = g;
     if (typeof permission !== "string" || typeof workspaceId !== "string") return null;
-    out.push({ permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" });
+    const row = { permission, workspaceId, workspaceName: typeof workspaceName === "string" ? workspaceName : "" };
+    if (typeof templateSlug === "string" && templateSlug.length > 0 && templateSlug.length <= 200) row.templateSlug = templateSlug;
+    out.push(row);
   }
   return out;
 }
+function parseActsAs(value) {
+  return value === "person" || value === "agent" ? value : void 0;
+}
 var APP_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
-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;
@@ -769,7 +1044,7 @@ function parseApp(value) {
   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);
+      const secure = url.protocol === "https:" || url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
       if (secure && !url.username && !url.password) out.manageUrl = url.href;
     } catch {
     }
@@ -815,6 +1090,8 @@ function parseTokenResponse(body, ctx) {
   const manageUrl = app.manageUrl ?? ctx.previous?.manageUrl;
   if (appId !== void 0) connection.appId = appId;
   if (manageUrl !== void 0) connection.manageUrl = manageUrl;
+  const actsAs = parseActsAs(body.synap_acts_as);
+  if (actsAs !== void 0) connection.actsAs = actsAs;
   if (typeof refresh_token === "string" && refresh_token !== "") {
     connection.refreshToken = refresh_token;
     const idle = typeof refresh_token_expires_in === "number" && Number.isFinite(refresh_token_expires_in) && refresh_token_expires_in > 0 ? refresh_token_expires_in * 1e3 : DEFAULT_REFRESH_IDLE_MS;
@@ -880,7 +1157,9 @@ async function revokeConnection(connection, opts = {}) {
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({ token, token_type_hint: hint, client_id: connection.clientId }).toString(),
         redirect: "manual",
-        signal: typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(TIMEOUT_MS2) : void 0
+        signal: timeoutSignal(TIMEOUT_MS3)
+      });
+      await res.body?.cancel().catch(() => {
       });
       if (res.status !== 200) revoked = false;
     } catch {
@@ -922,6 +1201,7 @@ function pack(c) {
   for (const g of c.grant) {
     const row = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
     row[2].push(g.permission);
+    if (g.templateSlug && row[3] === void 0) row[3] = g.templateSlug;
     bySpace.set(g.workspaceId, row);
   }
   const { grant: _grant, ...rest } = c;
@@ -931,7 +1211,7 @@ function unpack(s) {
   if (!s || typeof s.podUrl !== "string" || typeof s.accessToken !== "string" || !Array.isArray(s.g)) return null;
   const { g, ...rest } = s;
   const grant = g.flatMap(
-    ([workspaceId, workspaceName, permissions]) => permissions.map((permission) => ({ permission, workspaceId, workspaceName }))
+    ([workspaceId, workspaceName, permissions, templateSlug]) => permissions.map((permission) => ({ permission, workspaceId, workspaceName, ...typeof templateSlug === "string" ? { templateSlug } : {} }))
   );
   return { ...rest, grant };
 }
@@ -1010,9 +1290,34 @@ var DEFAULT_PATHS = {
   afterConnect: "/"
 };
 var REFRESH_WINDOW_MS = 5 * 60 * 1e3;
-var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
 var TEMPLATE_SLUG_RE = /^[a-z0-9][a-z0-9._/-]{0,99}$/;
 var MAX_METADATA_BYTES2 = 5 * 1024;
+var MAX_REQUESTS = 32;
+var KEPT_RETRY_MS = 6e4;
+var GRANT_ACTIONS = ["read", "create", "update", "delete"];
+var SYNAP_APP_REVIEW_PERMISSIONS = ["proposal.approve", "proposal.reject"];
+var PERMISSION_SEGMENT_RE = /^[a-z0-9][a-z0-9_-]*$/;
+function isSynapAppOrigin(origin) {
+  return /^https:\/\/[a-z0-9]([a-z0-9-]*[a-z0-9])?\.synap\.live$/.test(origin);
+}
+function isMockModeOrigin(origin) {
+  const url = new URL(origin);
+  return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+}
+function assertAppPermission(permission, origin) {
+  const segs = permission.split(".");
+  const fail = (why) => {
+    throw new ConnectError("misconfigured", `requests: "${permission}" ${why}`);
+  };
+  if (segs.length < 2 || segs.length > 3 || segs.some((seg) => !PERMISSION_SEGMENT_RE.test(seg))) {
+    fail("is not <subject>[.<kind>].<action> in lowercase (no *)");
+  }
+  if (segs.length === 3 && segs[0] !== "entity") fail(`names a kind, but "${segs[0]}" has none (only entity does)`);
+  if (SYNAP_APP_REVIEW_PERMISSIONS.includes(permission) && (isSynapAppOrigin(origin) || isMockModeOrigin(origin))) return;
+  if (!GRANT_ACTIONS.includes(segs[segs.length - 1])) {
+    fail(`asks for "${segs[segs.length - 1]}", which an app cannot be granted (read, create, update, delete)`);
+  }
+}
 function appOriginOf(appUrl) {
   let url;
   try {
@@ -1021,8 +1326,11 @@ function appOriginOf(appUrl) {
     throw new ConnectError("misconfigured", "appUrl is not a URL");
   }
   const secure = url.protocol === "https:";
-  if (!secure && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
-    throw new ConnectError("misconfigured", "appUrl must be https (http only on localhost)");
+  if (!secure && !(url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))) {
+    throw new ConnectError("misconfigured", "appUrl must be https (http only on localhost, for the SDK's mock pod)");
+  }
+  if (secure && isIpLiteral(url.hostname)) {
+    throw new ConnectError("misconfigured", "appUrl must use a domain name: the pod refuses an IP address client_id");
   }
   if (url.pathname !== "/" || url.search || url.hash || url.username || url.password) {
     throw new ConnectError("misconfigured", "appUrl is an origin: no path, query, fragment or credentials");
@@ -1040,9 +1348,12 @@ function buildClientMetadata(opts) {
   for (const [name, path] of Object.entries(paths)) assertPath(name, path);
   const clientName = opts.clientName.trim();
   if (!clientName || clientName.length > 100) throw new ConnectError("misconfigured", "clientName must be 1-100 characters");
+  if (opts.requests.length === 0 || opts.requests.length > MAX_REQUESTS) {
+    throw new ConnectError("misconfigured", `requests must hold 1-${MAX_REQUESTS} entries (duplicates count)`);
+  }
   assertPermissions(opts.requests.map((r) => r.permission));
   for (const r of opts.requests) {
-    if (r.permission.includes("*")) throw new ConnectError("misconfigured", "a permission cannot contain *");
+    assertAppPermission(r.permission, origin);
     if (typeof r.reason !== "string" || !r.reason.trim() || r.reason.length > 200) {
       throw new ConnectError("misconfigured", `the reason for ${r.permission} must be 1-200 characters`);
     }
@@ -1141,7 +1452,7 @@ function createPodAppAuth(config) {
       permissions,
       secret: config.secret,
       resource: config.resource,
-      spaceHint: opts.space && /^[A-Za-z0-9_-]{1,64}$/.test(opts.space) ? opts.space : null,
+      spaceHint: opts.space && SPACE_HINT_RE.test(opts.space) ? opts.space : null,
       next: opts.next,
       prompt: opts.prompt,
       allowInsecureLoopback: config.allowInsecureLoopback
@@ -1220,7 +1531,7 @@ function createPodAppAuth(config) {
         clientId,
         secret: config.secret,
         next,
-        spaceHint: space && /^[A-Za-z0-9_-]{1,64}$/.test(space) ? space : null,
+        spaceHint: space && SPACE_HINT_RE.test(space) ? space : null,
         prompt: formField(form, "prompt") === "consent" ? "consent" : null,
         now
       });
@@ -1253,7 +1564,8 @@ function createPodAppAuth(config) {
       return redirect(withQuery(origin, paths.connectPage, { error: e.code, pod: pod ? new URL(pod).host : null }), [clearCloud]);
     }
   }
-  async function refreshIfNeeded(request) {
+  const keptFailures = /* @__PURE__ */ new Map();
+  async function refreshIfNeeded(request, opts = {}) {
     const connection = await store.read(request);
     const unchanged = (status, conn, error) => ({
       status,
@@ -1268,18 +1580,27 @@ function createPodAppAuth(config) {
     }
     if (isPrefetchOrAsset(request)) return unchanged("skipped", connection);
     const t = now();
-    const accessLives = connection.accessExpiresAt > t;
-    if (connection.accessExpiresAt - t > REFRESH_WINDOW_MS) return unchanged("fresh", connection);
+    const accessLives = !opts.force && connection.accessExpiresAt > t;
+    if (!opts.force && connection.accessExpiresAt - t > REFRESH_WINDOW_MS) return unchanged("fresh", connection);
     if (!connection.refreshToken) {
       return accessLives ? unchanged("fresh", connection) : unchanged("expired", null, new ConnectError("expired", "No refresh token; connect again"));
     }
+    for (const [token, f] of keptFailures) if (t - f.at >= KEPT_RETRY_MS) keptFailures.delete(token);
+    const keptFailure = accessLives ? keptFailures.get(connection.refreshToken) : void 0;
+    if (keptFailure) return unchanged("kept", connection, keptFailure.error);
     let next;
     try {
       next = await refreshConnection(connection, flow);
     } catch (err) {
       const e = fail(err, "refresh");
-      if (accessLives) return unchanged("kept", connection, e);
-      if (e.code === "revoked" || e.code === "expired") return unchanged(e.code, null, e);
+      if (accessLives) {
+        keptFailures.set(connection.refreshToken, { error: e, at: t });
+        return unchanged("kept", connection, e);
+      }
+      if (e.code === "revoked" || e.code === "expired" || e.code === "pod_moved") {
+        const cleared = await store.clear(request).catch(() => []);
+        return { status: e.code === "revoked" ? "revoked" : "expired", connection: null, setCookies: cleared, cookieHeader: applySetCookies(request.headers.get("cookie"), cleared), error: e };
+      }
       return unchanged("unavailable", null, e);
     }
     let setCookies;
@@ -1298,6 +1619,24 @@ function createPodAppAuth(config) {
       cookieHeader: applySetCookies(request.headers.get("cookie"), setCookies)
     };
   }
+  function renewer(persist, source) {
+    return async (connection) => {
+      let next;
+      try {
+        next = await refreshConnection(connection, flow);
+      } catch (err) {
+        throw fail(err, "refresh");
+      }
+      try {
+        const cookies = await store.write(next, asRequest(source ?? null));
+        await persist([...cookies, marker(next.podUrl)]);
+      } catch (err) {
+        fail(err, "refresh");
+        throw new ConnectError("expired", "The renewed connection could not be stored; connect again");
+      }
+      return next;
+    };
+  }
   return {
     clientId,
     redirectUri,
@@ -1311,7 +1650,15 @@ function createPodAppAuth(config) {
       return await store.read(request) ? null : lapsedIn(request);
     },
     refreshIfNeeded,
-    client: (connection, opts) => createPodClient(connection, { fetch: config.fetch, now: config.now, ...opts })
+    client(connection, opts = {}) {
+      const { persist, request, ...clientOpts } = opts;
+      return createPodClient(connection, {
+        fetch: config.fetch,
+        now: config.now,
+        ...persist ? { renew: renewer(persist, request) } : {},
+        ...clientOpts
+      });
+    }
   };
 }
 
@@ -1336,6 +1683,7 @@ export {
   canonicalPodUrl,
   cloudBaseUrl,
   cloudConnectAvailable,
+  connectionActsAs,
   connectionExpiresAt,
   cookieNames,
   createPodAppAuth,
@@ -1343,6 +1691,7 @@ export {
   createSealedCookieStore,
   discoverPod,
   handleCallback,
+  humanSlots,
   isBrowserRuntime,
   isConnectError,
   isPrefetchOrAsset,