@synap-core/sdk 1.4.0 → 1.5.0

package/src/testing/auth-server.ts

@@ -8,21 +8,34 @@
  * Wire behaviour mirrors synap-backend `routers/oauth/routes.ts` for a CIMD
  * client: `iss` on every authorization answer (RFC 9207), PKCE S256 checked at
  * /token, single-use codes bound to client_id + redirect_uri + resource, the
- * token response's `synap_grant` / `synap_user`. Refresh mirrors PB3
+ * token response's `synap_grant` / `synap_user`. Refresh mirrors the pod's
  * (`routers/oauth/refresh.ts`): rotating and single-use, 30 days from issue;
  * a token presented AGAIN after its use is a reuse that revokes its whole
  * family AND the live access key; a new code ends the client's older
  * families; /revoke with a refresh token kills its family and access key.
- * The reuse grace (PB3b): within 30 s of its use, a spent token presented
+ * The reuse grace: within 30 s of its use, a spent token presented
  * again with its own client_id gets the SAME pair its first use got (the
  * successor refresh token and the live key, `expires_in` = what that key has
  * left), as long as the successor is unused; past it, a reuse.
- * `refresh: false` is a pod before PB3 (no refresh_token at all).
+ * `refresh: false` is a pod without refresh tokens (no refresh_token at all).
  *
  * Hub REST: `GET /users/me`, `GET /entities` (an ARRAY of entities, as the pod
  * answers; the seeds plus what applied writes created), `GET /proposals`
  * (`{ proposals, limit, offset, total, hasMore }`, rows only in spaces where
- * the token holds `proposal.read`, as the pod's grant clause), governed writes.
+ * the token holds `proposal.read`, as the pod's grant clause; `proposalIds`),
+ * governed writes. 1.5, from `seed` (one JSON shape, ./seed.ts):
+ * `GET /entities/:id` (404 with an empty body, as the pod), `GET
+ * /entities/:id/connections` (`{ connections, counts }`: seeded relations and
+ * the sessions about it), `GET /documents/:id` (`{ document }`), `GET
+ * /focus-sessions` (an ARRAY; `workspaceId` or `projectId` required; status,
+ * limit 1-50, lens, kind, subjectEntityId), `POST /proposals/:id/approve`.
+ *
+ * Who the token acts as: `actsAs: "person"` answers
+ * `synap_acts_as: "person"`, applies writes directly (unless `writeMode`
+ * says otherwise) and lets the token approve where it holds
+ * `proposal.approve`; `"agent"` answers `"agent"`; omitted, the field is not
+ * sent (a pod that does not name it) and the token is an agent's. An agent's approve is
+ * refused 403, as the pod's `rejectAgentReviewer`.
  *
  *   mock.authorize(authorizeUrl)                  → the callback URL (approved)
  *   mock.authorize(authorizeUrl, { deny: true })  → error=access_denied
@@ -31,9 +44,11 @@
  *   mock.redeemElsewhere(t)                       → another app instance rotated t (presenting it within 30 s gets that pair)
  *   mock.consumeRefreshToken(t)                   → the token was used elsewhere with no successor (presenting it is a reuse)
  *   mock.revokeAll()                              → the person removed the app in their pod
+ *   mock.revokeAccessKeys()                       → a narrow or a pod-side "Revoke key": the live keys stop, the connection (its refresh token) lives
  */
 import { pkceChallenge, randomToken } from "../connect/encoding";
-import type { PodGrant, PodUser } from "../connect/types";
+import type { PodActsAs, PodGrant, PodUser } from "../connect/types";
+import type { MockPodSeed, MockSeedDocument, MockSeedRelation, MockSeedSession } from "./seed";
 
 /** A placeholder pod origin; never contacted. */
 export const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
@@ -49,7 +64,7 @@ export type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" |
 
 export interface MockAuthServerOptions {
   issuer?: string;
-  /** Issue rotating refresh tokens (PB3). Default true; false = a pod before PB3. */
+  /** Issue rotating refresh tokens. Default true; false = a pod without refresh tokens. */
   refresh?: boolean;
   /** Default 3600 (the pod's 1 h). */
   accessTtlSec?: number;
@@ -57,7 +72,7 @@ export interface MockAuthServerOptions {
   refreshIdleSec?: number;
   /** Send `refresh_token_expires_in` with each refresh token. Default false (the pod does not say). */
   advertiseRefreshExpiry?: boolean;
-  /** The reuse grace, seconds (PB3b). Default 30 (the pod's); 0 = off (a pod before PB3b). */
+  /** The reuse grace, seconds. Default 30 (the pod's); 0 = off (a pod without the grace). */
   refreshGraceSec?: number;
   /**
    * `synap_app` on token responses: the connection's id and its page on the
@@ -70,8 +85,22 @@ export interface MockAuthServerOptions {
   user?: PodUser;
   /** Override or remove (undefined) metadata fields: a pod too old, a lying issuer. */
   metadata?: Record<string, unknown>;
-  /** Hub writes: "proposed" (ask-first, the default for an app) or "applied". */
+  /**
+   * Hub writes: "proposed" (ask-first, the default for an agent token) or
+   * "applied" (the default for `actsAs: "person"`).
+   */
   writeMode?: "proposed" | "applied";
+  /**
+   * `synap_acts_as` on token responses. Omitted = not sent (a pod that does
+   * not name it; the SDK reads an agent connection).
+   */
+  actsAs?: PodActsAs;
+  /**
+   * The pod's data as one JSON shape (`parseMockPodSeed`). `seed.entities` come
+   * before `entities`; `seed.spaces` put a `templateSlug` on the grant rows of
+   * those spaces.
+   */
+  seed?: MockPodSeed;
   /** Hub paths (after /api/hub) that answer one failure. */
   failures?: Record<string, MockHubFailure>;
   now?: () => number;
@@ -122,8 +151,10 @@ export interface MockAuthServer {
   requests: MockAuthRequest[];
   /** Hub writes seen, in order. */
   writes: Array<{ method: string; path: string; body: unknown }>;
-  /** Proposals filed by proposed writes, in order. */
+  /** Proposals: the seeded ones, then those filed by proposed writes, in order. */
   proposals: MockProposal[];
+  /** Proposals approved through `POST /proposals/:id/approve`, in order. */
+  approvals: string[];
   /** The person approved or rejected one: it leaves the pending list. */
   settleProposal(id: string, status: "approved" | "rejected"): void;
   /** Another instance of the app rotated `token` (its own refresh): returns the pair the pod answered it. */
@@ -140,6 +171,12 @@ export interface MockAuthServer {
   reuses: number;
   /** The person revoked the app: every token stops working. */
   revokeAll(): void;
+  /**
+   * The live access keys stop working, the refresh tokens do not: what a
+   * narrow (the slot's key is revoked at once) or a pod-side "Revoke key"
+   * does. The next refresh mints a new key.
+   */
+  revokeAccessKeys(): void;
   /** Live (unrevoked) refresh tokens. */
   liveRefreshTokens(): string[];
   reset(): void;
@@ -198,7 +235,29 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
   const requests: MockAuthRequest[] = [];
   const writes: Array<{ method: string; path: string; body: unknown }> = [];
   const proposals: MockProposal[] = [];
-  const entities: Array<Record<string, unknown>> = [...(options.entities ?? [])];
+  const seed = options.seed ?? {};
+  const entities: Array<Record<string, unknown>> = [...(seed.entities ?? []), ...(options.entities ?? [])];
+  const sessions: MockSeedSession[] = [...(seed.sessions ?? [])];
+  const documents: MockSeedDocument[] = [...(seed.documents ?? [])];
+  const relations: MockSeedRelation[] = [...(seed.relations ?? [])];
+  const templateOf = new Map((seed.spaces ?? []).filter((sp) => sp.templateSlug).map((sp) => [sp.id, sp.templateSlug!]));
+  const approvals: string[] = [];
+  const seededAt = new Date(now()).toISOString();
+  for (const p of seed.proposals ?? []) {
+    proposals.push({
+      proposalType: "create",
+      targetType: "entity",
+      targetId: null,
+      status: "pending",
+      workspaceId: null,
+      createdAt: seededAt,
+      correlationId: null,
+      sessionId: null,
+      agentUserId: null,
+      ...p,
+    });
+  }
+  const writeMode = options.writeMode ?? (options.actsAs === "person" ? "applied" : "proposed");
   const graceMs = (options.refreshGraceSec ?? 30) * 1000;
   const app = options.app === undefined ? MOCK_APP : options.app;
   let proposalSeq = 0;
@@ -244,9 +303,13 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       // As the pod: what the key has left, never an assumed hour.
       expires_in: Math.max(0, Math.floor((row.expiresAt - now()) / 1000)),
       scope: scope.join(" "),
-      synap_grant: grant.filter((g) => scope.includes(g.permission)),
+      // Each grant row names its space's template when it came from one.
+      synap_grant: grant
+        .filter((g) => scope.includes(g.permission))
+        .map((g) => (g.templateSlug || !templateOf.has(g.workspaceId) ? g : { ...g, templateSlug: templateOf.get(g.workspaceId)! })),
       synap_user: user,
       ...(app ? { synap_app: app } : {}),
+      ...(options.actsAs ? { synap_acts_as: options.actsAs } : {}),
     };
     if (pair) {
       body.refresh_token = pair.refreshToken;
@@ -285,7 +348,7 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
         return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
       }
       if (row.used) {
-        // PB3b: the same pair again, inside the grace, while the successor is unused and its key lives.
+        // The same pair again, inside the grace, while the successor is unused and its key lives.
         const successor = row.successor ? refreshTokens.get(row.successor) : undefined;
         const key = row.pairAccess ? access.get(row.pairAccess) : undefined;
         const inGrace = graceMs > 0 && row.usedAt !== undefined && now() - row.usedAt < graceMs;
@@ -314,6 +377,139 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     return oauthError("unsupported_grant_type", "Unsupported grant_type");
   }
 
+  /** A focus-session row as the list door answers it: the table's columns (defaults filled), `triage`, `kind`. */
+  const sessionRow = (s: MockSeedSession): Record<string, unknown> => ({
+    workspaceId: null,
+    projectId: null,
+    userId: user.id,
+    correlationId: null,
+    title: null,
+    goal: "",
+    status: "active",
+    templateId: null,
+    expectedOutputs: [],
+    channelId: null,
+    progress: null,
+    currentStage: null,
+    agentIds: [],
+    closedAt: null,
+    verificationReport: null,
+    metadata: {},
+    startedAt: seededAt,
+    createdAt: seededAt,
+    updatedAt: seededAt,
+    kind: "work",
+    triage: { pending: false, acceptedAt: null, acceptedBy: null },
+    ...s,
+  });
+
+  /** The seeded read doors (1.5); null when `path` is none of them. */
+  function readSeeded(path: string, query: URLSearchParams): Response | null {
+    const conn = /^\/entities\/([^/]+)\/connections$/.exec(path);
+    if (conn) {
+      const id = decodeURIComponent(conn[1]);
+      const ws = query.get("workspaceId");
+      const limit = Math.min(Math.max(Number(query.get("limit") ?? 50) || 50, 1), 200);
+      const inLens = (e: Record<string, unknown>) => !ws || e.workspaceId === ws || e.workspaceId == null;
+      const connections: Array<Record<string, unknown>> = [];
+      const graph = relations
+        .filter((r) => r.sourceEntityId === id || r.targetEntityId === id)
+        .sort((a, b) => String(b.createdAt ?? "").localeCompare(String(a.createdAt ?? "")))
+        .slice(0, limit);
+      for (const r of graph) {
+        const outgoing = r.sourceEntityId === id;
+        const otherId = outgoing ? r.targetEntityId : r.sourceEntityId;
+        const other = entities.find((e) => e.id === otherId);
+        // As the pod: an edge whose far end is gone or out of the lens is not a neighbour.
+        if (!other || !inLens(other)) continue;
+        connections.push({
+          entityId: otherId,
+          entity: { ...other, type: other.profileSlug ?? other.type ?? null, facetSlugs: other.facetSlugs ?? [] },
+          label: r.type,
+          direction: outgoing ? "outgoing" : "incoming",
+          source: "graph",
+          relationId: r.id,
+          relationType: r.type,
+          createdAt: r.createdAt ?? null,
+        });
+      }
+      for (const s of sessions.filter((x) => x.subjectEntityId === id).slice(0, limit)) {
+        const row = sessionRow(s);
+        connections.push({
+          entityId: s.id,
+          entity: null,
+          label: (row.title as string | null) || (row.goal as string),
+          direction: "incoming",
+          source: "focus_session",
+          focusSessionId: s.id,
+          focusSessionGoal: row.goal,
+          focusSessionStatus: row.status,
+          focusSessionWorkspaceId: row.workspaceId,
+          createdAt: row.createdAt,
+        });
+      }
+      const n = (source: string) => connections.filter((c) => c.source === source).length;
+      return json(200, {
+        connections,
+        counts: { total: connections.length, graph: n("graph"), structural: n("property"), threads: n("thread"), contextChannels: n("context_channel"), focusSessions: n("focus_session") },
+      });
+    }
+    const entity = /^\/entities\/([^/]+)$/.exec(path);
+    if (entity) {
+      const found = entities.find((e) => e.id === decodeURIComponent(entity[1]));
+      // The pod answers a miss with an EMPTY 404 body (rest/entities.ts `c.body(null, 404)`).
+      return found ? json(200, found) : new Response(null, { status: 404 });
+    }
+    const doc = /^\/documents\/([^/]+)$/.exec(path);
+    if (doc) {
+      const format = query.get("format") ?? "raw";
+      if (format !== "raw" && format !== "readable") return json(400, { error: "format must be raw or readable" });
+      const d = documents.find((x) => x.id === decodeURIComponent(doc[1]));
+      if (!d) return json(404, { error: "Document not found" });
+      // projectAgentDocument; the mock has no embeds, so `readable` = `raw`, and no sections are parsed.
+      return json(200, {
+        document: {
+          id: d.id,
+          title: d.title,
+          type: d.type ?? "markdown",
+          language: d.language ?? null,
+          workspaceId: d.workspaceId ?? null,
+          format,
+          content: d.content,
+          revision: d.revision ?? 1,
+          version: d.version ?? 1,
+          sections: [],
+          diagnostics: [],
+          updatedAt: d.updatedAt ?? seededAt,
+          createdAt: d.createdAt ?? seededAt,
+        },
+      });
+    }
+    if (path === "/focus-sessions") {
+      const ws = query.get("workspaceId");
+      const project = query.get("projectId");
+      if (!ws && !project) return json(400, { error: "workspaceId or projectId is required" });
+      const status = query.get("status") ?? "all";
+      const lens = query.get("lens") ?? "all";
+      const kind = query.get("kind") ?? "all";
+      const subject = query.get("subjectEntityId");
+      const limit = Math.min(Math.max(Number(query.get("limit") ?? 20) || 20, 1), 50);
+      const rows = sessions
+        .map(sessionRow)
+        .filter((r) => (!ws || r.workspaceId === ws) && (!project || r.projectId === project))
+        .filter((r) => status === "all" || r.status === status)
+        .filter((r) => {
+          const pending = (r.triage as { pending?: boolean } | undefined)?.pending === true;
+          return lens === "triage" ? pending : lens === "default" ? !pending : true;
+        })
+        .filter((r) => kind === "all" || r.kind === kind)
+        .filter((r) => !subject || r.subjectEntityId === subject)
+        .sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)));
+      return json(200, rows.slice(0, limit));
+    }
+    return null;
+  }
+
   function hub(method: string, path: string, query: URLSearchParams, headers: Record<string, string>, body: unknown): Response | "reject" {
     const failure = options.failures?.[path];
     if (failure === "unreachable") return "reject";
@@ -332,7 +528,7 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       case "unavailable":
         return json(503, { error: "Unavailable" });
     }
-    // The grant fence (spec 17 §5): aggregate reads are refused to a scoped token.
+    // The grant fence: aggregate reads are refused to a space-scoped token.
     if (path.startsWith("/knowledge/") || path === "/entities/retrieve" || path === "/memory/search") {
       return json(403, { error: "This door is not available to a space-scoped key", code: "GRANT_DOOR_UNSUPPORTED" });
     }
@@ -353,18 +549,43 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       const ws = query.get("workspaceId");
       const limit = Math.min(Math.max(Number(query.get("limit") ?? 50) || 50, 1), 200);
       const offset = Number(query.get("offset") ?? 0) || 0;
+      // proposalIds: comma-separated and/or repeated; present but empty matches nothing.
+      const idsRaw = query.getAll("proposalIds");
+      const ids = idsRaw.length > 0 ? new Set(idsRaw.flatMap((v) => v.split(",").map((x) => x.trim()).filter(Boolean))) : null;
       const rows = proposals
         .filter((p) => p.workspaceId !== null && readable.has(p.workspaceId))
         .filter((p) => (status === "all" || p.status === status) && (!ws || p.workspaceId === ws))
+        .filter((p) => !ids || ids.has(p.id))
         .reverse(); // newest first
       const page = rows.slice(offset, offset + limit);
       return json(200, { proposals: page, limit, offset, total: rows.length, hasMore: offset + page.length < rows.length });
     }
+    if (method === "GET") {
+      const read = readSeeded(path, query);
+      if (read) return read;
+    }
+    const approve = method === "POST" ? /^\/proposals\/([^/]+)\/approve$/.exec(path) : null;
+    if (approve) {
+      // rejectAgentReviewer: an agent credential never approves, before anything is read.
+      if (options.actsAs !== "person") {
+        return json(403, { error: "An agent credential cannot approve proposals — approve is human review. Approve from a human session." });
+      }
+      const p = proposals.find((x) => x.id === decodeURIComponent(approve[1]));
+      if (!p) return json(404, { error: "Proposal not found" });
+      // Only where the person granted proposal.approve, for the proposal's own space.
+      if (!grant.some((g) => g.permission === "proposal.approve" && row.scope.includes(g.permission) && g.workspaceId === p.workspaceId)) {
+        return json(403, { error: "You may not approve changes here" });
+      }
+      if (p.status !== "pending") return json(409, { error: `The proposal is ${p.status}, not pending` });
+      p.status = "approved";
+      approvals.push(p.id);
+      return json(200, { success: true, proposalId: p.id, proposal: { ...p } });
+    }
     if (method !== "GET") {
       writes.push({ method, path, body });
       const fields = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
       const workspaceId = typeof fields.workspaceId === "string" ? fields.workspaceId : null;
-      if ((options.writeMode ?? "proposed") === "proposed") {
+      if (writeMode === "proposed") {
         const proposalId = `prop_mock_${++proposalSeq}`;
         proposals.push({
           id: proposalId,
@@ -442,6 +663,7 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     requests,
     writes,
     proposals,
+    approvals,
     settleProposal(id, status) {
       const p = proposals.find((x) => x.id === id);
       if (p) p.status = status;
@@ -501,6 +723,9 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       for (const row of access.values()) row.revoked = true;
       for (const row of refreshTokens.values()) row.revoked = true;
     },
+    revokeAccessKeys() {
+      for (const row of access.values()) row.revoked = true;
+    },
     liveRefreshTokens() {
       return [...refreshTokens].filter(([, r]) => !r.used && !r.revoked).map(([t]) => t);
     },

package/src/testing/cloud.ts

@@ -1,9 +1,9 @@
 /**
- * A mock Synap Cloud pod chooser (Control Plane `GET /connect/pod`, wave C1)
+ * 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 (doc 18 §1.1): it accepts only
+ * 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}$`),
@@ -15,13 +15,12 @@
  *   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";
 
-const STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
 
 export interface MockCloud {
   url: string;

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; Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
+ * ./auth-server.ts, seeded from one JSON shape (`parseMockPodSeed`, ./seed.ts); Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
  */
 import type {
   PublicCollectionPage,
@@ -27,19 +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;
@@ -289,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":[]}