@synap-core/sdk 1.4.0 → 1.5.0

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,20 +14,64 @@ import { assertServerRuntime } from "./guard";
 
 assertServerRuntime();
 
+// What an app on createPodAppAuth uses.
 export { createPodAppAuth, buildClientMetadata, isPrefetchOrAsset, DEFAULT_PATHS, REFRESH_WINDOW_MS } from "./auth";
-export type { PodAppAuth, PodAppAuthConfig, PodAppPaths, RefreshOutcome, RefreshStatus } from "./auth";
-export { discoverPod, canonicalPodUrl, acceptLaunch, safeNextPath } from "./discovery";
-export type { DiscoverOptions, LaunchHint } from "./discovery";
-export {
-  cloudConnectAvailable,
-  startCloudConnect,
-  acceptCloudReturn,
-  cloudBaseUrl,
-  CLOUD_TRANSACTION_TTL_MS,
-} from "./cloud";
+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,
-  CloudConnectConfig,
   CloudReturn,
   CloudTransaction,
   SealedCloudTransaction,
@@ -55,33 +98,8 @@ export type {
   StartConnectOptions,
   StartedConnect,
 } from "./flow";
-export { createPodClient, can, spaces, reviewUrlFor } from "./client";
-export type {
-  ListPendingProposalsOptions,
-  PendingProposal,
-  PendingProposals,
-  PodClient,
-  PodClientOptions,
-  PodError,
-  PodErrorCode,
-  PodResult,
-  PodWriteResult,
-  QueryValue,
-} from "./client";
-export {
-  createSealedCookieStore,
-  cookieNames,
-  applySetCookies,
-  connectionExpiresAt,
-  markerCookie,
-  readMarker,
-  MARKER_TTL_SEC,
-} 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, PodSpace, 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/store.ts

@@ -79,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;
@@ -98,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;
@@ -75,6 +92,11 @@ export interface PodConnection {
    * 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)`). */
@@ -83,9 +105,11 @@ export interface PodSpace {
   /** "" 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 };
+}

package/src/public/share-model.ts

@@ -8,7 +8,7 @@
  * is honest (a network blip) — it never says anything about the token.
  */
 import type { PublicReadError, PublicResult, PublicShare } from "./client";
-import { parseSafeMarkdown, type Block } from "./safe-markdown";
+import { bodyOf, type Block } from "./safe-markdown";
 import { formatPublicValue, type FormatOptions } from "./site-model";
 
 export const UNAVAILABLE_TITLE = "This link isn't available";
@@ -20,7 +20,10 @@ export type SharePageModel =
       title: string | null;
       /** Property rows exactly as the publisher allowlisted them. */
       properties: Array<{ key: string; value: string }>;
+      /** A markdown body as safe blocks (`[]` for an html body or none). */
       blocks: Block[];
+      /** An html body: render ONLY as `<iframe sandbox="" srcdoc>`. `null` otherwise. */
+      html: string | null;
       publishedOn: string;
     };
 
@@ -41,7 +44,8 @@ export function toSharePageModel(
       key,
       value: formatPublicValue(value, opts),
     })),
-    blocks: share.body ? parseSafeMarkdown(share.body.content) : [],
+    ...bodyOf(share.body),
     publishedOn: share.publishedOn,
   };
 }
+

package/src/public/site-model.ts

@@ -14,7 +14,7 @@ import {
   type PublicRecordSummary,
   type PublicValue,
 } from "./client";
-import { parseSafeMarkdown, type Block } from "./safe-markdown";
+import { bodyOf, type Block } from "./safe-markdown";
 
 export interface FormatOptions {
   /** BCP 47 locale (default `en`). */
@@ -197,8 +197,10 @@ export interface RecordViewModel {
   slug: string | null;
   /** Rows exactly as the publisher allowlisted them, formatted. */
   properties: Array<{ key: string; value: string }>;
-  /** The body as safe blocks (never HTML). */
+  /** A markdown body as safe blocks (`[]` for an html body or none). */
   blocks: Block[];
+  /** An html body: render ONLY as `<iframe sandbox="" srcdoc>`. `null` otherwise. */
+  html: string | null;
   publishedOn: string;
 }
 
@@ -211,7 +213,7 @@ export function toRecordViewModel(record: PublicRecord, opts: FormatOptions = {}
       key,
       value: formatPublicValue(value, opts),
     })),
-    blocks: record.body ? parseSafeMarkdown(record.body.content) : [],
+    ...bodyOf(record.body),
     publishedOn: record.publishedOn,
   };
 }