@synap-core/sdk 1.3.0 → 1.5.0

package/src/testing/cloud.ts

@@ -0,0 +1,83 @@
+/**
+ * A mock Synap Cloud pod chooser (Control Plane `GET /connect/pod`)
+ * for "Continue with Synap Cloud" tests and a kit's mock mode. No network:
+ * `choose()` stands in for the person signing in to the CP and picking a pod.
+ *
+ * Wire behaviour mirrors the CP route: it accepts only
+ * `client_id` (an https CIMD URL; http on loopback only with
+ * `allowInsecureLoopback`, for a kit's mock mode on http://localhost) and
+ * `state` (`^[A-Za-z0-9._~-]{16,256}$`),
+ * takes the return URL from the app's client metadata (`initiate_login_uri`),
+ * never from the query, and answers `<initiate_login_uri>?iss=<pod issuer>&state=<state>`.
+ * It never sees a code or a token.
+ *
+ *   const cloud = createMockCloud();
+ *   createPodAppAuth({ ...config, cloudUrl: cloud.url });
+ *   cloud.choose(location, { pod: mockPod.issuer, metadata: auth.metadata })  → the app's return URL
+ */
+import { CLOUD_STATE_RE as STATE_RE, LOOPBACK_HOSTS } from "../connect/rules";
+import type { ClientMetadataDocument } from "../connect/types";
+
+/** A placeholder Control Plane origin; never contacted. */
+export const MOCK_CLOUD_URL = "https://cp.mock-synap.test";
+
+
+export interface MockCloud {
+  url: string;
+  /** The chooser URLs the app sent browsers to. */
+  requests: string[];
+  /**
+   * The person picks `pod` on the chooser: validates the request like the CP,
+   * returns where the CP redirects the browser. Throws on a request the CP
+   * refuses (shown as a page there, never redirected).
+   */
+  choose(location: string, opts: { pod: string; metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri"> }): string;
+  /** The person cancels on the chooser: `<initiate_login_uri>?state=…&error=access_denied`, no `iss`. */
+  cancel(location: string, opts: { metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri"> }): string;
+}
+
+export function createMockCloud(options: { url?: string; allowInsecureLoopback?: boolean } = {}): MockCloud {
+  const base = (options.url ?? MOCK_CLOUD_URL).replace(/\/+$/, "");
+  const requests: string[] = [];
+  return {
+    url: base,
+    requests,
+    choose(location, { pod, metadata }) {
+      const back = check(location, metadata);
+      back.searchParams.set("iss", pod);
+      back.searchParams.set("state", new URL(location).searchParams.get("state")!);
+      return back.href;
+    },
+    cancel(location, { metadata }) {
+      const back = check(location, metadata);
+      back.searchParams.set("state", new URL(location).searchParams.get("state")!);
+      back.searchParams.set("error", "access_denied");
+      return back.href;
+    },
+  };
+
+  /** Validates like the CP (an HTML error there, never a redirect); returns the app's initiate_login_uri. */
+  function check(location: string, metadata: Pick<ClientMetadataDocument, "client_id" | "initiate_login_uri">): URL {
+    requests.push(location);
+    const url = new URL(location);
+    if (`${url.origin}${url.pathname}` !== `${base}/connect/pod`) throw new Error(`Not this CP's /connect/pod: ${location}`);
+    const clientId = url.searchParams.get("client_id");
+    const state = url.searchParams.get("state");
+    if (!clientId || !cimdUrlAccepted(clientId)) throw new Error("Chooser refused: client_id must be an https CIMD URL");
+    if (!state || !STATE_RE.test(state)) throw new Error("Chooser refused: state is missing or malformed");
+    if (clientId !== metadata.client_id) throw new Error("Chooser refused: the client metadata is not this client_id's");
+    return new URL(metadata.initiate_login_uri);
+  }
+
+  /** https; http only on a loopback host, and only with `allowInsecureLoopback`. */
+  function cimdUrlAccepted(clientId: string): boolean {
+    let url: URL;
+    try {
+      url = new URL(clientId);
+    } catch {
+      return false;
+    }
+    if (url.protocol === "https:") return true;
+    return url.protocol === "http:" && options.allowInsecureLoopback === true && LOOPBACK_HOSTS.has(url.hostname);
+  }
+}

package/src/testing/fixtures.ts

@@ -44,6 +44,32 @@ export const MOCK_SHARE: PublicShare = {
   publishedOn: "2026-09-27",
 };
 
+/**
+ * A published HTML document (an estimate), as the pod serves an `html` body: a
+ * page renders it only inside `<iframe sandbox="" srcdoc>`, so the script below
+ * never runs.
+ */
+export const MOCK_HTML_SHARE: PublicShare = {
+  resourceType: "entity",
+  title: "Estimate for Northwind",
+  properties: { total: "4 800 €", validUntil: "2026-11-30" },
+  body: {
+    format: "html",
+    content: [
+      "<!doctype html>",
+      '<html lang="en"><head><meta charset="utf-8"><title>Estimate</title>',
+      "<style>body{font-family:Georgia,serif;max-width:40rem;margin:2rem auto;line-height:1.5}td{padding:.25rem .75rem}</style>",
+      "</head><body>",
+      "<h1>Estimate for Northwind</h1>",
+      "<table><tr><td>Discovery workshop</td><td>1 200 €</td></tr><tr><td>Build</td><td>3 600 €</td></tr></table>",
+      "<p><strong>Total: 4 800 €</strong></p>",
+      "<script>document.body.textContent = 'scripts never run in a sandboxed frame'</script>",
+      "</body></html>",
+    ].join(""),
+  },
+  publishedOn: "2026-10-22",
+};
+
 /** One collection of a mock site: its door config and its live records. */
 export interface MockCollection {
   /** Default sort keys (`-` = descending); also the sort keys the door accepts. */

package/src/testing/index.ts

@@ -12,12 +12,12 @@
  * `credentials: "include"` request is refused (it rejects, as a CORS failure
  * does); with `{ browser: true }` a non-safelisted request header is too.
  *
- *   tokens MOCK_TOKENS.form / .share / .site   the demo form, share and site
+ *   tokens MOCK_TOKENS.form / .share / .htmlShare / .site   the demo form, shares (markdown, html) and site
  *   tokens MOCK_FAILURE_TOKENS.*                one failure on every door
  *   anything else                               the uniform 404
  *
  * Pod-app sign-in (`@synap-core/sdk/connect`): `createMockAuthServer()`, see
- * ./auth-server.ts.
+ * ./auth-server.ts, seeded from one JSON shape (`parseMockPodSeed`, ./seed.ts); Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
  */
 import type {
   PublicCollectionPage,
@@ -27,17 +27,21 @@ import type {
   PublicShare,
   PublicSite,
 } from "../public/client";
-import { MOCK_FORM, MOCK_SHARE, MOCK_SITE, type MockSite } from "./fixtures";
+import { MOCK_FORM, MOCK_HTML_SHARE, MOCK_SHARE, MOCK_SITE, type MockSite } from "./fixtures";
 
-export { MOCK_FORM, MOCK_SHARE, MOCK_SITE };
+export { MOCK_FORM, MOCK_HTML_SHARE, MOCK_SHARE, MOCK_SITE };
 export type { MockCollection, MockSite } from "./fixtures";
 // Pod-app sign-in: a mock authorization server + Hub REST doors.
 export * from "./auth-server";
+// The mock pod's data as one JSON shape (1.5).
+export * from "./seed";
+// Synap Cloud: a mock Control Plane pod chooser.
+export * from "./cloud";
 
 /** A placeholder origin; never contacted. */
 export const MOCK_POD_URL = "https://mock.synap.invalid";
 
-export const MOCK_TOKENS = { form: "demo-form", share: "demo", site: "demo-site" } as const;
+export const MOCK_TOKENS = { form: "demo-form", share: "demo", htmlShare: "demo-html", site: "demo-site" } as const;
 
 /** The `Retry-After` the `rateLimitedRetryAfter` token sends. */
 export const MOCK_RETRY_AFTER_SEC = 30;
@@ -287,7 +291,7 @@ function invalidKeys(form: PublicForm, body: unknown): string[] {
 
 export function createMockPod(options: MockPodOptions = {}): MockPod {
   const forms = options.forms ?? { [MOCK_TOKENS.form]: MOCK_FORM };
-  const shares = options.shares ?? { [MOCK_TOKENS.share]: MOCK_SHARE };
+  const shares = options.shares ?? { [MOCK_TOKENS.share]: MOCK_SHARE, [MOCK_TOKENS.htmlShare]: MOCK_HTML_SHARE };
   const sites = options.sites ?? { [MOCK_TOKENS.site]: MOCK_SITE };
   const requests: MockRequest[] = [];
   const submissions: MockSubmission[] = [];

package/src/testing/seed.ts

@@ -0,0 +1,120 @@
+/**
+ * The mock pod's data as ONE JSON-serialisable shape, so an app's mock mode,
+ * smoke and screenshots replay a recorded snapshot (one file) instead of
+ * fixtures built in app code:
+ *
+ *   import { readFileSync } from "node:fs";
+ *   const seed = parseMockPodSeed(readFileSync("mock/pod-seed.json", "utf8"));
+ *   const pod = createMockAuthServer({ seed });
+ *
+ * Rows are the pod's wire shapes (see `@synap-core/sdk/connect` hub-types):
+ * `entities` as `GET /entities` answers them, `sessions` as `GET
+ * /focus-sessions` rows (missing columns get the pod's defaults), `documents`
+ * as `GET /documents/:id` (`sections` and `diagnostics` answered empty),
+ * `relations` as graph edges for `GET /entities/:id/connections`, `proposals`
+ * as `GET /proposals?view=basic` rows, `spaces` name each granted space's
+ * template (`synap_grant[].templateSlug` on the token response).
+ */
+import type { MockProposal } from "./auth-server";
+
+export interface MockSeedEntity {
+  id: string;
+  profileSlug?: string;
+  workspaceId?: string | null;
+  title?: string | null;
+  properties?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface MockSeedSession {
+  id: string;
+  workspaceId?: string | null;
+  projectId?: string | null;
+  goal?: string;
+  status?: string;
+  /** Slots; `owner: "human"` ones are what waits on the person. */
+  expectedOutputs?: Array<Record<string, unknown>>;
+  /** The entity it is about: listed among that entity's connections. */
+  subjectEntityId?: string | null;
+  /** ISO 8601; the list is newest first by it. */
+  startedAt?: string;
+  [key: string]: unknown;
+}
+
+export interface MockSeedDocument {
+  id: string;
+  title: string;
+  content: string;
+  type?: string;
+  language?: string | null;
+  workspaceId?: string | null;
+  revision?: number;
+  version?: number;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface MockSeedRelation {
+  id: string;
+  sourceEntityId: string;
+  targetEntityId: string;
+  type: string;
+  createdAt?: string;
+}
+
+export interface MockSeedSpace {
+  id: string;
+  name: string;
+  /** The template it came from (e.g. `content-os`); absent = made by hand. */
+  templateSlug?: string;
+}
+
+export interface MockPodSeed {
+  entities?: MockSeedEntity[];
+  sessions?: MockSeedSession[];
+  documents?: MockSeedDocument[];
+  relations?: MockSeedRelation[];
+  /** Missing fields default to a pending `create` of an `entity`, with null ids and the seed's load time. */
+  proposals?: Array<Partial<MockProposal> & { id: string }>;
+  spaces?: MockSeedSpace[];
+}
+
+const KEYS = ["entities", "sessions", "documents", "relations", "proposals", "spaces"] as const;
+
+/** Required string fields per collection (the rest is free-form, as the pod's rows). */
+const REQUIRED: Record<(typeof KEYS)[number], readonly string[]> = {
+  entities: ["id"],
+  sessions: ["id"],
+  documents: ["id", "title", "content"],
+  relations: ["id", "sourceEntityId", "targetEntityId", "type"],
+  proposals: ["id"],
+  spaces: ["id", "name"],
+};
+
+/**
+ * Read a seed (JSON text or an already-parsed value) and check its shape:
+ * every collection optional, each an array of objects carrying its required
+ * string fields; unknown top-level keys are refused (a typo would otherwise
+ * seed nothing). Throws `TypeError` naming the first bad path.
+ */
+export function parseMockPodSeed(input: string | unknown): MockPodSeed {
+  const value: unknown = typeof input === "string" ? JSON.parse(input) : input;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("seed: expected an object");
+  const obj = value as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    if (!(KEYS as readonly string[]).includes(key)) throw new TypeError(`seed.${key}: unknown collection (expected ${KEYS.join(", ")})`);
+  }
+  for (const key of KEYS) {
+    const rows = obj[key];
+    if (rows === undefined) continue;
+    if (!Array.isArray(rows)) throw new TypeError(`seed.${key}: expected an array`);
+    rows.forEach((row, i) => {
+      if (!row || typeof row !== "object" || Array.isArray(row)) throw new TypeError(`seed.${key}[${i}]: expected an object`);
+      for (const field of REQUIRED[key]) {
+        if (typeof (row as Record<string, unknown>)[field] !== "string") throw new TypeError(`seed.${key}[${i}].${field}: expected a string`);
+      }
+    });
+  }
+  // A JSON round trip: what the mock serves is what a file could hold.
+  return JSON.parse(JSON.stringify(obj)) as MockPodSeed;
+}

package/dist/chunk-J7XHAAFJ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/connect/encoding.ts"],"sourcesContent":["/**\n * Web-standard primitives (WebCrypto, TextEncoder, btoa/atob): the same code\n * runs on Node 18+, edge runtimes and workers. No Node import.\n */\n\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\n\n/** `Uint8Array<ArrayBuffer>`: what WebCrypto's `BufferSource` takes under TS 5.7+ lib types. */\nexport type Bytes = Uint8Array<ArrayBuffer>;\n\nexport function utf8(text: string): Bytes {\n  return encoder.encode(text);\n}\n\nexport function fromUtf8(bytes: Uint8Array): string {\n  return decoder.decode(bytes);\n}\n\nexport function base64url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/** Null when `text` is not base64url. */\nexport function fromBase64url(text: string): Bytes | null {\n  if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;\n  const padded = text.replace(/-/g, \"+\").replace(/_/g, \"/\") + \"===\".slice((text.length + 3) % 4);\n  let binary: string;\n  try {\n    binary = atob(padded);\n  } catch {\n    return null;\n  }\n  const out = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n  return out;\n}\n\nexport function randomBytes(length: number): Bytes {\n  const out = new Uint8Array(length);\n  crypto.getRandomValues(out);\n  return out;\n}\n\n/** 32 random bytes, base64url (43 chars): a state value or a PKCE verifier. */\nexport function randomToken(): string {\n  return base64url(randomBytes(32));\n}\n\n/** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */\nexport async function pkceChallenge(verifier: string): Promise<string> {\n  const digest = await crypto.subtle.digest(\"SHA-256\", utf8(verifier));\n  return base64url(new Uint8Array(digest));\n}\n\n/** Compare two strings without an early exit on the first differing byte. */\nexport function constantTimeEqual(a: string, b: string): boolean {\n  const x = utf8(a);\n  const y = utf8(b);\n  let diff = x.length ^ y.length;\n  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);\n  return diff === 0;\n}\n\n/** The request's cookies by name (the first value wins, as browsers order the most specific first). */\nexport function parseCookies(header: string | null): Map<string, string> {\n  const out = new Map<string, string>();\n  if (!header) return out;\n  for (const part of header.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq < 0) continue;\n    const name = part.slice(0, eq).trim();\n    if (!name || out.has(name)) continue;\n    let value = part.slice(eq + 1).trim();\n    if (value.startsWith('\"') && value.endsWith('\"')) value = value.slice(1, -1);\n    out.set(name, value);\n  }\n  return out;\n}\n\nexport interface CookieAttributes {\n  maxAgeSec: number;\n  secure: boolean;\n}\n\n/** `HttpOnly; SameSite=Lax; Path=/` always; `Secure` on https. Never a `Domain`. */\nexport function serializeCookie(name: string, value: string, attrs: CookieAttributes): string {\n  const parts = [`${name}=${value}`, \"Path=/\", \"HttpOnly\", \"SameSite=Lax\", `Max-Age=${Math.max(0, Math.floor(attrs.maxAgeSec))}`];\n  if (attrs.secure) parts.push(\"Secure\");\n  return parts.join(\"; \");\n}\n"],"mappings":";AAKA,IAAM,UAAU,IAAI,YAAY;AAChC,IAAM,UAAU,IAAI,YAAY;AAKzB,SAAS,KAAK,MAAqB;AACxC,SAAO,QAAQ,OAAO,IAAI;AAC5B;AAEO,SAAS,SAAS,OAA2B;AAClD,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAEO,SAAS,UAAU,OAA2B;AACnD,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,IAAK,WAAU,OAAO,aAAa,MAAM,CAAC,CAAC;AAC7E,SAAO,KAAK,MAAM,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE;AAC/E;AAGO,SAAS,cAAc,MAA4B;AACxD,MAAI,CAAC,mBAAmB,KAAK,IAAI,EAAG,QAAO;AAC3C,QAAM,SAAS,KAAK,QAAQ,MAAM,GAAG,EAAE,QAAQ,MAAM,GAAG,IAAI,MAAM,OAAO,KAAK,SAAS,KAAK,CAAC;AAC7F,MAAI;AACJ,MAAI;AACF,aAAS,KAAK,MAAM;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,MAAM,IAAI,WAAW,OAAO,MAAM;AACxC,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,KAAI,CAAC,IAAI,OAAO,WAAW,CAAC;AACpE,SAAO;AACT;AAEO,SAAS,YAAY,QAAuB;AACjD,QAAM,MAAM,IAAI,WAAW,MAAM;AACjC,SAAO,gBAAgB,GAAG;AAC1B,SAAO;AACT;AAGO,SAAS,cAAsB;AACpC,SAAO,UAAU,YAAY,EAAE,CAAC;AAClC;AAGA,eAAsB,cAAc,UAAmC;AACrE,QAAM,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,KAAK,QAAQ,CAAC;AACnE,SAAO,UAAU,IAAI,WAAW,MAAM,CAAC;AACzC;AAGO,SAAS,kBAAkB,GAAW,GAAoB;AAC/D,QAAM,IAAI,KAAK,CAAC;AAChB,QAAM,IAAI,KAAK,CAAC;AAChB,MAAI,OAAO,EAAE,SAAS,EAAE;AACxB,WAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAK,UAAS,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,KAAK;AACtF,SAAO,SAAS;AAClB;AAGO,SAAS,aAAa,QAA4C;AACvE,QAAM,MAAM,oBAAI,IAAoB;AACpC,MAAI,CAAC,OAAQ,QAAO;AACpB,aAAW,QAAQ,OAAO,MAAM,GAAG,GAAG;AACpC,UAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,QAAI,KAAK,EAAG;AACZ,UAAM,OAAO,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK;AACpC,QAAI,CAAC,QAAQ,IAAI,IAAI,IAAI,EAAG;AAC5B,QAAI,QAAQ,KAAK,MAAM,KAAK,CAAC,EAAE,KAAK;AACpC,QAAI,MAAM,WAAW,GAAG,KAAK,MAAM,SAAS,GAAG,EAAG,SAAQ,MAAM,MAAM,GAAG,EAAE;AAC3E,QAAI,IAAI,MAAM,KAAK;AAAA,EACrB;AACA,SAAO;AACT;AAQO,SAAS,gBAAgB,MAAc,OAAe,OAAiC;AAC5F,QAAM,QAAQ,CAAC,GAAG,IAAI,IAAI,KAAK,IAAI,UAAU,YAAY,gBAAgB,WAAW,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE;AAC9H,MAAI,MAAM,OAAQ,OAAM,KAAK,QAAQ;AACrC,SAAO,MAAM,KAAK,IAAI;AACxB;","names":[]}