@synap-core/sdk 1.3.0 → 1.5.0

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() };
+}

package/src/connect/hub-types.ts

@@ -0,0 +1,254 @@
+/**
+ * Wire shapes of the Hub REST doors `createPodClient`'s typed methods read.
+ *
+ * DRIFT RISK: hand-written from synap-backend main (2026-10-22), each from the
+ * route itself, never from `@synap-core/hub-rest-client` alone:
+ *  - entities: `routers/hub-protocol/rest/entities.ts` (`GET /entities`,
+ *    `GET /entities/:id` → `entityToWire`, `_codecs/entity.ts`
+ *    `WireEntitySchema`; `GET /entities/:id/connections` → `relations.ts`
+ *    `getConnections`, `services/object-graph/entity-connections.ts`);
+ *  - documents: `rest/documents.ts` `GET /documents/:id` →
+ *    `services/document-patch/read-document.ts` `projectAgentDocument`;
+ *  - focus sessions: `rest/focus-sessions.ts` `GET /focus-sessions` (raw rows +
+ *    `triage` + `kind`), slots `services/focus-sessions/update-session.ts`
+ *    `expectedOutputWireSchema`;
+ *  - files: `rest/entities.ts` `GET /files/:id/url` → `file-upload.ts`
+ *    `signFileEntityUrl`;
+ *  - approve: `rest/proposals.ts` `POST /proposals/:id/approve`.
+ * Fields the SDK does not read stay on the objects (index signatures): the pod
+ * sends more than is typed here. The mock pod (`@synap-core/sdk/testing`)
+ * answers these shapes; `src/__tests__/connect.typed.test.ts` drives both.
+ */
+
+/** One entity, as `GET /entities` and `GET /entities/:id` answer it (`WireEntitySchema`). */
+export interface PodEntity {
+  id: string;
+  profileSlug: string;
+  /** Deprecated alias of `profileSlug`, still sent. */
+  type?: string;
+  title?: string | null;
+  preview?: string | null;
+  description?: string | null;
+  properties: Record<string, unknown>;
+  systemData?: Record<string, unknown>;
+  userId: string;
+  workspaceId?: string | null;
+  documentId?: string | null;
+  version?: number;
+  /** ISO 8601. */
+  createdAt?: string;
+  updatedAt?: string;
+  [key: string]: unknown;
+}
+
+export interface ListEntitiesOptions {
+  /** One granted space. Omitted: every space the connection can read. */
+  workspaceId?: string;
+  /** One kind, e.g. `post`. */
+  profileSlug?: string;
+  /** 1-1000 (the pod's bounds); the pod's default is 20. */
+  limit?: number;
+  offset?: number;
+  /** e.g. `updatedAt:desc`. */
+  sort?: string;
+  /** With `workspaceId`: also the person's pod-wide rows (the pod's default: true). */
+  includePodWide?: boolean;
+}
+
+export type PodConnectionSource = "graph" | "property" | "thread" | "context_channel" | "focus_session";
+
+/** One edge of `GET /entities/:id/connections` (`EntityConnection`). */
+export interface PodEntityConnection {
+  /** The other end: an entity, or the channel / session for those sources. */
+  entityId: string;
+  /** The other entity's row (title, `type` = its kind, workspaceId, facetSlugs, …); null for channels and sessions. */
+  entity: {
+    title?: string | null;
+    type?: string | null;
+    workspaceId?: string | null;
+    facetSlugs?: string[] | null;
+    [key: string]: unknown;
+  } | null;
+  label: string;
+  direction: "outgoing" | "incoming" | "structural";
+  source: PodConnectionSource;
+  relationId?: string;
+  relationType?: string;
+  storedAs?: "link";
+  propertySlug?: string;
+  propertyLabel?: string;
+  channelId?: string;
+  channelRelationshipType?: string;
+  channelTitle?: string | null;
+  channelWorkspaceId?: string | null;
+  focusSessionId?: string;
+  focusSessionGoal?: string;
+  focusSessionStatus?: string;
+  focusSessionWorkspaceId?: string | null;
+  /** ISO 8601, or null (a property link has no date). */
+  createdAt?: string | null;
+  [key: string]: unknown;
+}
+
+export interface PodEntityConnections {
+  connections: PodEntityConnection[];
+  counts: {
+    total: number;
+    graph: number;
+    structural: number;
+    threads: number;
+    contextChannels: number;
+    focusSessions: number;
+  };
+}
+
+export interface GetEntityConnectionsOptions {
+  /** A space lens; omitted = everything the connection can read. */
+  workspaceId?: string;
+  /** Per source, 1-200 (the pod's default: 50). */
+  limit?: number;
+}
+
+/** A document's top-level section (`listDocumentSections`). */
+export interface PodDocumentSection {
+  id: string;
+  /** Who owns it (a person's section is not an agent's to change). */
+  owner: string;
+  title: string | null;
+  author: string | null;
+}
+
+/** `GET /documents/:id` → `document` (`projectAgentDocument`). */
+export interface PodDocument {
+  id: string;
+  title: string;
+  /** `markdown`, `text`, `html`, … */
+  type: string;
+  language: string | null;
+  workspaceId: string | null;
+  format: "raw" | "readable";
+  /** Markdown; `readable` replaces embeds by their fallback text. */
+  content: string;
+  /** Pass back as `baseRevision` on a guarded edit. */
+  revision: number;
+  version: number;
+  sections: PodDocumentSection[];
+  /** What will not render; null when the check could not run (`diagnosticsError`). */
+  diagnostics: unknown[] | null;
+  diagnosticsError?: string;
+  updatedAt: string;
+  createdAt: string;
+  [key: string]: unknown;
+}
+
+export interface GetDocumentOptions {
+  /** `raw` (the stored markdown, the pod's default) or `readable`. */
+  format?: "raw" | "readable";
+}
+
+/** `focus_sessions.status` (`@synap-core/types/focus-sessions` SESSION_STATUSES). */
+export type PodSessionStatus = "active" | "paused" | "forming" | "scheduled" | "closed" | "failed" | "cancelled" | "stale";
+
+/**
+ * One declared deliverable of a session (`expectedOutputWireSchema`). A slot
+ * with `owner: "human"` is waiting on the person: `blockedReason` and `why` say
+ * for what, `ask` how they can answer (confirm, choose, form, act, provide).
+ */
+export interface PodSessionSlot {
+  kind: string;
+  label: string;
+  key?: string;
+  optional?: boolean;
+  status?: "pending" | "done";
+  /** Absent = `agent`. */
+  owner?: "human" | "agent";
+  blockedReason?: string;
+  why?: string;
+  /** ISO 8601, stamped by the pod with `owner: "human"`. */
+  owedSince?: string;
+  /** How the person can answer (`@synap-core/types/ask`), or null. */
+  ask?: unknown;
+  answer?: {
+    text: string;
+    messageId: string | null;
+    answeredBy: string;
+    answeredAt: string;
+    question?: string;
+    value?: unknown;
+    [key: string]: unknown;
+  };
+  retiredAt?: string;
+  [key: string]: unknown;
+}
+
+/** One row of `GET /focus-sessions`. `expectedOutputs` is always an array here (the SDK drops anything else). */
+export interface PodFocusSession {
+  id: string;
+  workspaceId: string | null;
+  projectId: string | null;
+  userId: string;
+  title: string | null;
+  goal: string;
+  status: PodSessionStatus | (string & {});
+  templateId: string | null;
+  expectedOutputs: PodSessionSlot[];
+  channelId: string | null;
+  progress: number | null;
+  currentStage: string | null;
+  agentIds: string[];
+  closedAt: string | null;
+  metadata: unknown;
+  startedAt: string;
+  createdAt: string;
+  updatedAt: string;
+  /** Projected by the list door: `work`, `run` (a playbook or automation ran it) or `receipt`. */
+  kind?: "work" | "run" | "receipt";
+  /** Projected by the list door: an agent-started session the person has not accepted yet. */
+  triage?: { pending: boolean; acceptedAt: string | null; acceptedBy: string | null };
+  [key: string]: unknown;
+}
+
+export interface ListFocusSessionsOptions {
+  /** A space; `workspaceId` or `projectId` is required (the pod's rule). */
+  workspaceId?: string;
+  projectId?: string;
+  /** Default `all` (the pod's default on this door). */
+  status?: PodSessionStatus | "all";
+  /** 1-50 (the pod's bounds); the pod's default is 20. */
+  limit?: number;
+  /** Triage lens: `all` (default here), `default` (hides unaccepted agent sessions), `triage`. */
+  lens?: "all" | "default" | "triage";
+  /** Population lens: `all` (default here), `work`, `run`, `receipt`. */
+  kind?: "all" | "work" | "run" | "receipt";
+  /** Sessions about one thing. */
+  subjectEntityId?: string;
+}
+
+/** `GET /files/:id/url`: a signed GET for a file entity's blob. */
+export interface PodFileUrl {
+  /** Served as an `attachment`, with the stored type. */
+  url: string;
+  /** ISO 8601; the signature's end (about an hour). */
+  expiresAt: string;
+  /** Decide drawability on this, never on the URL; null when unknown. */
+  mimeType: string | null;
+}
+
+/** `POST /proposals/:id/approve`. */
+export interface PodApproval {
+  proposalId: string;
+  /** The row the approval produced or linked, when it names one. */
+  primaryId?: string;
+  linked?: number;
+  /** The proposal after the approval (status, execution result), when the pod could read it back. */
+  proposal: Record<string, unknown> | null;
+}
+
+export interface ApproveProposalOptions {
+  /**
+   * The proposal's space, when known: refused locally unless the connection
+   * holds `proposal.approve` there. Omitted: needs it in some space, and the
+   * pod checks the proposal's own space.
+   */
+  workspaceId?: string;
+}

package/src/connect/index.ts

@@ -1,11 +1,10 @@
 /**
- * `@synap-core/sdk/connect` — pod-app sign-in, SERVER-ONLY (spec 17 §10.1,
- * doc 18 § SDK): an app connects to a person's own pod as an OAuth 2.1 public
+ * `@synap-core/sdk/connect` — pod-app sign-in, SERVER-ONLY: an app connects to a person's own pod as an OAuth 2.1 public
  * client (CIMD client_id, PKCE S256, `iss`-checked answers), keeps the pod
  * token on its server in a sealed HttpOnly cookie, refreshes it in `proxy.ts`,
  * and reads/writes the pod's Hub API with typed results.
  *
- * Framework-free and Web-standard (Request/Response, WebCrypto): Node 18+,
+ * Framework-free and Web-standard (Request/Response, WebCrypto): Node 20+,
  * edge runtimes, workers. Throws when loaded in a browser (./guard.ts).
  *
  * Invariant (pinned by src/__tests__/connect.guard.test.ts): every file of
@@ -15,17 +14,70 @@ import { assertServerRuntime } from "./guard";
 
 assertServerRuntime();
 
-export { createPodAppAuth, buildClientMetadata, DEFAULT_PATHS, REFRESH_WINDOW_MS } from "./auth";
-export type { PodAppAuth, PodAppAuthConfig, PodAppPaths, RefreshOutcome, RefreshStatus } from "./auth";
-export {
-  discoverPod,
-  canonicalPodUrl,
-  acceptLaunch,
-  safeNextPath,
-  cloudConnectAvailable,
-  startCloudConnect,
-} from "./discovery";
-export type { DiscoverOptions, LaunchHint } from "./discovery";
+// What an app on createPodAppAuth uses.
+export { createPodAppAuth, buildClientMetadata, isPrefetchOrAsset, DEFAULT_PATHS, REFRESH_WINDOW_MS } from "./auth";
+export type { PodAppAuth, PodAppAuthConfig, PodAppClientOptions, PodAppPaths, RefreshOptions, RefreshOutcome, RefreshStatus } from "./auth";
+export { acceptLaunch, safeNextPath } from "./discovery";
+export type { LaunchHint } from "./discovery";
+export { cloudConnectAvailable } from "./cloud";
+export type { CloudConnectConfig } from "./cloud";
+export { createPodClient, can, spaces, reviewUrlFor, connectionActsAs, humanSlots } from "./client";
+export type {
+  ListPendingProposalsOptions,
+  PendingProposal,
+  PendingProposals,
+  PodClient,
+  PodClientOptions,
+  PodError,
+  PodErrorCode,
+  PodRefusalReason,
+  PodResult,
+  PodWriteResult,
+  QueryValue,
+} from "./client";
+export type {
+  ApproveProposalOptions,
+  GetDocumentOptions,
+  GetEntityConnectionsOptions,
+  ListEntitiesOptions,
+  ListFocusSessionsOptions,
+  PodApproval,
+  PodConnectionSource,
+  PodDocument,
+  PodDocumentSection,
+  PodEntity,
+  PodEntityConnection,
+  PodEntityConnections,
+  PodFileUrl,
+  PodFocusSession,
+  PodSessionSlot,
+  PodSessionStatus,
+} from "./hub-types";
+export { ConnectError, isConnectError, parseConnectErrorCode, CONNECT_ERROR_CODES } from "./errors";
+export type { ConnectErrorCode } from "./errors";
+export { isBrowserRuntime } from "./guard";
+export type { AppRequest, ClientMetadataDocument, PodActsAs, PodConnection, PodGrant, PodIssuer, PodSpace, PodUser } from "./types";
+export type { ConnectionStore } from "./store";
+export { createSealedCookieStore } from "./store";
+export type { SealedCookieStoreOptions } from "./store";
+export type { AppSecret } from "./seal";
+
+// Building blocks: what createPodAppAuth is made of, for another framework or
+// store. INTERNAL, not the supported surface: an app on createPodAppAuth needs
+// none of them, and no new export is added here. They stay exported only for
+// 1.x semver; 2.0 moves them to their own entry. (ConnectionStore and
+// createSealedCookieStore above are the supported custom-store seam.)
+export { discoverPod, canonicalPodUrl } from "./discovery";
+export type { DiscoverOptions } from "./discovery";
+export { startCloudConnect, acceptCloudReturn, cloudBaseUrl, CLOUD_TRANSACTION_TTL_MS } from "./cloud";
+export type {
+  AcceptCloudReturnOptions,
+  CloudReturn,
+  CloudTransaction,
+  SealedCloudTransaction,
+  StartCloudConnectOptions,
+  StartedCloudConnect,
+} from "./cloud";
 export {
   startConnect,
   openTransaction,
@@ -46,14 +98,8 @@ export type {
   StartConnectOptions,
   StartedConnect,
 } from "./flow";
-export { createPodClient, can, reviewUrlFor } from "./client";
-export type { PodClient, PodClientOptions, PodError, PodErrorCode, PodResult, PodWriteResult, QueryValue } from "./client";
-export { createSealedCookieStore, cookieNames, applySetCookies, connectionExpiresAt } from "./store";
-export type { ConnectionStore, CookieNames, SealedCookieStoreOptions } from "./store";
+export { cookieNames, applySetCookies, connectionExpiresAt, markerCookie, readMarker, MARKER_TTL_SEC } from "./store";
+export type { CookieNames } from "./store";
 export { seal, unseal, MIN_SECRET_LENGTH } from "./seal";
-export type { AppSecret, Opened, SealPurpose } from "./seal";
+export type { Opened, SealPurpose } from "./seal";
 export { pkceChallenge } from "./encoding";
-export { ConnectError, isConnectError, parseConnectErrorCode, CONNECT_ERROR_CODES } from "./errors";
-export type { ConnectErrorCode } from "./errors";
-export { isBrowserRuntime } from "./guard";
-export type { AppRequest, ClientMetadataDocument, PodConnection, PodGrant, PodIssuer, PodUser } from "./types";

package/src/connect/rules.ts

@@ -0,0 +1,18 @@
+/**
+ * The shape rules several files of this entry (and the mock pod) apply, in
+ * one place, so a hint or a state accepted in one door is accepted in all.
+ */
+
+/** Hosts that count as this machine (WHATWG keeps IPv6 brackets: "[::1]"). */
+export const LOOPBACK_HOSTS: ReadonlySet<string> = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/** A `synap_space_hint`: a space id (uuid, short id), never a path or a query. */
+export const SPACE_HINT_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** The `state` the Synap Cloud pod chooser accepts and echoes; ours is 43 base64url characters. */
+export const CLOUD_STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;
+
+/** An IP literal host (dotted IPv4 or bracketed IPv6), as WHATWG URL normalises them. */
+export function isIpLiteral(hostname: string): boolean {
+  return hostname.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname);
+}

package/src/connect/seal.ts

@@ -13,7 +13,7 @@
 import { ConnectError } from "./errors";
 import { base64url, fromBase64url, fromUtf8, randomBytes, utf8 } from "./encoding";
 
-export type SealPurpose = "synap-connect/transaction" | "synap-connect/session";
+export type SealPurpose = "synap-connect/transaction" | "synap-connect/session" | "synap-connect/cloud";
 
 /** The app secret: one value, or several to rotate (the first seals, all open). */
 export type AppSecret = string | readonly string[];

package/src/connect/store.ts

@@ -7,7 +7,8 @@
  * Bring your own (a database, a KV) by implementing `ConnectionStore`; it
  * answers with the Set-Cookie values to send (e.g. its own session id).
  */
-import { parseCookies, serializeCookie } from "./encoding";
+import { canonicalPodUrl } from "./discovery";
+import { base64url, fromBase64url, fromUtf8, parseCookies, serializeCookie, utf8 } from "./encoding";
 import { ConnectError } from "./errors";
 import { seal, unseal, type AppSecret } from "./seal";
 import type { PodConnection, PodGrant } from "./types";
@@ -24,13 +25,50 @@ export interface ConnectionStore {
 export interface CookieNames {
   session: string;
   transaction: string;
+  /** A Synap Cloud sign-in in progress (sealed state, 10 minutes). */
+  cloud: string;
+  /** "This browser was connected to <pod>": the pod's URL only, no secret (`markerCookie`). */
+  marker: string;
 }
 
 /** `__Host-` names on https (Secure, Path=/, no Domain: bound to this exact host). */
 export function cookieNames(secure: boolean): CookieNames {
   return secure
-    ? { session: "__Host-synap_session", transaction: "__Host-synap_tx" }
-    : { session: "synap_session", transaction: "synap_tx" };
+    ? { session: "__Host-synap_session", transaction: "__Host-synap_tx", cloud: "__Host-synap_cloud", marker: "__Host-synap_seen" }
+    : { session: "synap_session", transaction: "synap_tx", cloud: "synap_cloud", marker: "synap_seen" };
+}
+
+/** The marker outlives the connection: as long as browsers keep a cookie (400 days). */
+export const MARKER_TTL_SEC = 400 * 24 * 60 * 60;
+
+/**
+ * The marker cookie: which pod this browser was connected to, so a connection
+ * that lapsed (idle past the refresh token's life, its sealed cookie gone)
+ * reads as "expired, connect again to <pod>" rather than "never connected".
+ * It holds the pod's public URL and NOTHING else: no token, no user, nothing
+ * sealed. A forged value can only pre-fill the address the person confirms.
+ */
+export function markerCookie(podUrl: string, opts: { secure: boolean; name?: string }): string {
+  return serializeCookie(opts.name ?? cookieNames(opts.secure).marker, base64url(utf8(podUrl)), {
+    maxAgeSec: MARKER_TTL_SEC,
+    secure: opts.secure,
+  });
+}
+
+/** The marker's pod URL, or null (absent, or not a canonical pod address). */
+export function readMarker(
+  cookieHeader: string | null,
+  opts: { secure: boolean; name?: string; allowInsecureLoopback?: boolean },
+): string | null {
+  const raw = parseCookies(cookieHeader).get(opts.name ?? cookieNames(opts.secure).marker);
+  const bytes = raw ? fromBase64url(raw) : null;
+  if (!bytes || bytes.length > 512) return null;
+  const podUrl = fromUtf8(bytes);
+  try {
+    return canonicalPodUrl(podUrl, opts) === podUrl ? podUrl : null;
+  } catch {
+    return null;
+  }
 }
 
 /** Browsers cap a cookie near 4096 bytes; a big grant spans several. */
@@ -41,16 +79,20 @@ function chunkName(name: string, i: number): string {
   return i === 0 ? name : `${name}.${i}`;
 }
 
+/** One space of the sealed grant; the template slug only when the pod named one (cookies written by 1.4 have none). */
+type StoredSpace = [workspaceId: string, workspaceName: string, permissions: string[], templateSlug?: string];
+
 /** The sealed form: the grant grouped per space (it repeats the space otherwise). */
 interface StoredConnection extends Omit<PodConnection, "grant"> {
-  g: Array<[workspaceId: string, workspaceName: string, permissions: string[]]>;
+  g: StoredSpace[];
 }
 
 function pack(c: PodConnection): StoredConnection {
-  const bySpace = new Map<string, [string, string, string[]]>();
+  const bySpace = new Map<string, StoredSpace>();
   for (const g of c.grant) {
-    const row = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
+    const row: StoredSpace = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
     row[2].push(g.permission);
+    if (g.templateSlug && row[3] === undefined) row[3] = g.templateSlug;
     bySpace.set(g.workspaceId, row);
   }
   const { grant: _grant, ...rest } = c;
@@ -60,8 +102,8 @@ function pack(c: PodConnection): StoredConnection {
 function unpack(s: StoredConnection): PodConnection | null {
   if (!s || typeof s.podUrl !== "string" || typeof s.accessToken !== "string" || !Array.isArray(s.g)) return null;
   const { g, ...rest } = s;
-  const grant: PodGrant[] = g.flatMap(([workspaceId, workspaceName, permissions]) =>
-    permissions.map((permission) => ({ permission, workspaceId, workspaceName })),
+  const grant: PodGrant[] = g.flatMap(([workspaceId, workspaceName, permissions, templateSlug]) =>
+    permissions.map((permission) => ({ permission, workspaceId, workspaceName, ...(typeof templateSlug === "string" ? { templateSlug } : {}) })),
   );
   return { ...rest, grant };
 }

package/src/connect/types.ts

@@ -3,9 +3,9 @@
  *
  * DRIFT RISK: hand-written from the pod's OAuth AS (synap-backend
  * `routers/oauth/routes.ts` /token for a CIMD client, `protocol.ts`
- * `buildAuthorizationServerMetadata`, spec 17 §6.6). The contract fixture
- * `src/__tests__/connect.contract.test.ts` copies the token response; when the
- * backend changes, update both.
+ * `buildAuthorizationServerMetadata`). The contract test
+ * `src/__tests__/connect.contract.test.ts` holds copies of the pod's token and
+ * metadata answers; when the backend changes them, update both.
  */
 
 /** One permission the app asks for, with the sentence the consent screen shows. */
@@ -21,8 +21,25 @@ export interface PodGrant {
   permission: string;
   workspaceId: string;
   workspaceName: string;
+  /**
+   * The template the space was made from (`synap_grant[].templateSlug`, e.g.
+   * `content-os`), when the pod names one: absent for a space made by hand
+   * and from pods that do not send it.
+   */
+  templateSlug?: string;
 }
 
+/**
+ * Who the connection's token acts as (`synap_acts_as` of the token response):
+ *  - `"person"`: an official Synap app; the token is held by the person who
+ *    consented, so their clicks write as them, directly, approvals included
+ *    (where they granted `proposal.approve`);
+ *  - `"agent"`: every other app; the token is the app's own ask-first agent's,
+ *    its writes become proposals the person reviews, and it can never approve.
+ * A pod that does not say is `"agent"`.
+ */
+export type PodActsAs = "person" | "agent";
+
 export interface PodUser {
   id: string;
   name: string;
@@ -63,9 +80,36 @@ export interface PodConnection {
   user: PodUser;
   /** ms since epoch. */
   connectedAt: number;
+  /**
+   * The pod's id for this app connection (`app_…`, the grant's client id), when
+   * the token response names it (`synap_app.id`). Absent from pods that do not.
+   */
+  appId?: string;
+  /**
+   * The pod's own page for this app connection (pod-admin `/apps/<appId>`:
+   * what it may touch, narrow it, apply automatically, revoke), when the token
+   * response names it (`synap_app.manageUrl`). Absent otherwise: hide the link,
+   * never guess one.
+   */
+  manageUrl?: string;
+  /**
+   * Who the token acts as, as the latest token response said
+   * (`synap_acts_as`). Absent = `"agent"` (read it with `connectionActsAs`).
+   */
+  actsAs?: PodActsAs;
+}
+
+/** One space of the grant, its permissions together (`spaces(connection)`). */
+export interface PodSpace {
+  workspaceId: string;
+  /** "" when the pod sent no name. */
+  workspaceName: string;
+  permissions: string[];
+  /** The template the space was made from, when the pod names one (`PodGrant.templateSlug`). */
+  templateSlug?: string;
 }
 
-/** The CIMD document an app serves at its client_id URL (spec 17 §6.1). */
+/** The client metadata document (CIMD) an app serves at its client_id URL. */
 export interface ClientMetadataDocument {
   client_id: string;
   client_name: string;

package/src/public/client.ts

@@ -34,12 +34,24 @@
 
 // ── Wire types (hand-written; see DRIFT RISK) ────────────────────────────────
 
+/**
+ * A published body, in the format the pod serves it (backend
+ * `PublicBodyFormatSchema`): `markdown` is text to parse with
+ * `parseSafeMarkdown`; `html` is a whole HTML document (an estimate, a report)
+ * that a page renders ONLY inside `<iframe sandbox="" srcdoc>`, never in its
+ * own DOM. `null`: nothing pinned, or a body that is not text (pdf, docx).
+ */
+export interface PublicBody {
+  format: "markdown" | "html";
+  content: string;
+}
+
 export interface PublicShare {
   resourceType: "entity";
   /** Present only when the publisher allowlisted `title`. */
   title?: string;
   properties: Record<string, string | number | boolean>;
-  body: { format: "markdown"; content: string } | null;
+  body: PublicBody | null;
   /** Publication day, YYYY-MM-DD. */
   publishedOn: string;
 }
@@ -136,7 +148,7 @@ export interface PublicCollectionPage {
 
 /** One published record, with its pinned body. */
 export interface PublicRecord extends PublicRecordSummary {
-  body: { format: "markdown"; content: string } | null;
+  body: PublicBody | null;
 }
 
 /** The collection door's query bounds (backend `parseCollectionQuery`). */

package/src/public/safe-markdown.ts

@@ -12,6 +12,8 @@
  * Everything else is plain text. Extend here — never by rendering HTML.
  */
 
+import type { PublicBody } from "./client";
+
 export type Inline =
   | { type: "text"; text: string }
   | { type: "strong"; text: string }
@@ -112,3 +114,14 @@ export function parseSafeMarkdown(source: string): Block[] {
   flush();
   return blocks;
 }
+
+/**
+ * A published body as a page renders it: markdown -> safe blocks; html -> the
+ * document for a sandboxed frame, never parsed as markdown (its tags would show
+ * as text). One rule for the share page and the site record page.
+ */
+export function bodyOf(body: PublicBody | null | undefined): { blocks: Block[]; html: string | null } {
+  if (!body) return { blocks: [], html: null };
+  if (body.format === "html") return { blocks: [], html: body.content };
+  return { blocks: parseSafeMarkdown(body.content), html: null };
+}