@synap-core/sdk 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -0,0 +1,215 @@
+# @synap-core/sdk changelog
+
+## 1.5.1
+
+What a pod app sees of a person's pod, and the roles (Kind + Facets) on it: the
+mock pod models the reach rule and answers roles as the pod does, so an app
+that lists by role (a CRM's leads) shows its pages on mock data; the typed
+client asks for roles; mock mode may ask for the review verbs. Additive, except
+the mock behaviours under "Behaviour changes (mock)".
+
+### `@synap-core/sdk/connect`
+
+- **`listEntities({ facetSlug?, includeFacets? })`**: only the entities wearing
+  a role, and each row's roles on it (`PodEntity.facetSlugs`, `PodEntity.facets:
+  PodEntityFacet[]` = `{ facetId, slug, properties, status }`, present only on a
+  row that wears one). `includeFacets` is sent only when true. It needs a pod
+  with the backend release that adds it to `GET /entities` (synap-backend
+  `feat/hub-entities-include-facets`); until that pod runs, the pod ignores it
+  and the rows come back without roles.
+- **Mock mode may ask for the review verbs**: `buildClientMetadata` (and so
+  `createPodAppAuth`) accepts `proposal.approve` / `proposal.reject` on an http
+  loopback `appUrl` (`localhost`, `127.0.0.1`, `[::1]`), so an app that requests
+  them starts mock mode, smoke and shots. A real pod refuses an http client_id
+  outright (synap-backend `client-id-url.ts`); every other origin is refused
+  as in 1.5.0.
+
+### `@synap-core/sdk/testing`
+
+- **The mock models the pod's reach rule**: `GET /entities`, `GET /entities/:id`
+  and connection neighbours answer rows of a granted space plus pod-wide
+  entities (`workspaceId` null) with a role in a granted space. A pod-wide
+  entity with no role in a granted space, and any row of an ungranted space, is
+  never answered (a miss is the pod's empty 404). Reads need an
+  `entity.*.read` grant in the token's scope.
+- **Seeded roles, one field: `MockSeedEntity.facets`** (`MockSeedFacet`:
+  `facetId`, `slug`, `properties?`, `status?`, and seed-only `workspaceId`: the
+  space whose members see the role, stamped there or a pod-wide facet of a role
+  granted to it). Seed input only: no answer carries them unless `includeFacets`
+  asks. Validated by `parseMockPodSeed`.
+- **`seedRoles`** (`[{ profileSlug, workspaceId }]`), **deprecated: use
+  `facets`; removed in 2.0.** A shorthand desugared into `facets` when the seed
+  is read (a generated `facetId`, no overlay); a role stated in both on one
+  entity is a parse error naming the entity.
+- **`facets[].sharedRole`** (seed only, never served, validated): the role is
+  stored pod-wide and granted to `workspaceId` (default: stamped in it). It
+  differs from a stamped role in `includePodWide=false` on a space lens, and in
+  `GET /entities/:id/facets` (its facet answers `workspaceId` null).
+- **`PATCH /entities/:id` of a pod-wide row** is refused (the mock answers 403;
+  the pod's 403 or 404 is not yet pinned): nothing written, no proposal.
+- **A row of another space T with a role stamped in S** is visible to an app
+  granted S (list and by id), as to a member of S; a shared role does not
+  reach a row of another space.
+- **`GET /entities`** as the pod (`rest/entities.ts`): `includePodWide=false`
+  on a workspace lens drops only the pod-wide rows reached through a SHARED role
+  (the pod keeps those with a role stamped in the space); `facetSlug` filters by a role
+  the read sees: what a member of a granted space sees (a workspace lens, that
+  space's roles only; never a role of a space outside the grant); a
+  `profileSlug` naming a role
+  matches its wearers too; `includeFacets=true` adds `facetSlugs` + `facets` to
+  the rows wearing one.
+- **`GET /entities/:id/facets`**: `{ facets: [{ facet, profile, effectiveProperties }] }`
+  (`getEffectiveFacets` under the token's floor; the mock knows a role by its
+  slug only, so `profile` is `{ id: "profile_<slug>", slug, profileKind: "role" }`
+  and `effectiveProperties` is empty). A miss, or an entity out of reach, is the
+  pod's empty 404.
+- **`GET /entities/:id/connections`**: the far end's `facetSlugs` come from its
+  seeded roles, under the read's `workspaceId` lens.
+- Not mirrored: the mock knows no profile catalog (an undeclared `facetSlug`
+  answers `[]` where the pod answers 404; `facetProfileId` is not read), and it
+  serves neither `q` (the pod refuses it to a space-scoped key, and answers 400
+  to `q` with `includeFacets`) nor `scope=all`.
+- Docs: AGENTS.md, "What a pod app can see and do". Needs a pod with the reach
+  rule (rolling out from 2026-10-23; an older pod returns no pod-wide rows to an app).
+
+### Behaviour changes (mock)
+
+- An entity list without `workspaceId` no longer returns rows of spaces the
+  token was not granted; a pod-wide row is listed only when it has a role in a
+  granted space.
+- `includePodWide=false` on a space lens keeps the pod-wide rows with a role
+  stamped in the space (it dropped every pod-wide row).
+- `GET /entities` and `GET /entities/:id` no longer echo a seed row's
+  `facets` / `facetSlugs` (the pod's `entityToWire` never sends them).
+
+## 1.5.0
+
+For Content Studio, the first pod app on `@synap-core/sdk/connect`, plus a
+hardening pass. Additive, except three behaviours that were bugs (see
+"Behaviour changes").
+
+### `@synap-core/sdk/connect`
+
+- **Typed Hub reads on `createPodClient(connection)`**, each a `PodResult` with
+  the 1.4 error codes: `listEntities({ workspaceId?, profileSlug?, limit? (≤ 1000),
+  offset?, sort?, includePodWide? })`, `getEntity(id)`,
+  `getEntityConnections(id, { workspaceId?, limit? })`, `getDocument(id, { format? })`,
+  `listFocusSessions({ workspaceId | projectId, status?, limit? (≤ 50), lens?, kind?,
+  subjectEntityId? })`, `getFileUrl(entityId)`. Each shape is read from the
+  backend route (see `src/connect/hub-types.ts`); a 2xx answer of another shape
+  is `server`, never empty data.
+- **`humanSlots(session)`**: the slots of a focus session that wait on the person
+  (`owner: "human"`, not done, not retired), for a "needs you" list.
+- **`listPendingProposals({ proposalIds })`**: only those proposals (≤ 100; the
+  pod's filter from backend #28). An empty list answers without a request. A pod
+  that ignores the filter never hands back a proposal that was not asked for.
+- **Who the connection acts as**: `connection.actsAs` / `client.actsAs` /
+  `connectionActsAs(connection)` read the token response's `synap_acts_as`. `"person"`: an official Synap app, the token is the person's,
+  writes apply directly. `"agent"`: every other app, writes are proposals. A pod
+  that does not send it is `"agent"`; the field is read from every token
+  response, never carried over from the previous one.
+- **`approveProposal(id, { workspaceId? })`**: `POST /proposals/:id/approve` as
+  the person. An agent connection gets `forbidden` with `reason:
+  "agent_cannot_approve"` and nothing is sent; without `proposal.approve`,
+  `forbidden` / `not_granted`, also without a request.
+- **`PodError.reason`** (`agent_cannot_approve | not_granted | invalid_input`):
+  set when the SDK refused locally (`status: null`). `listPendingProposals`
+  without `proposal.read` now carries `reason: "not_granted"`. A typed method
+  given an id that could leave its path segment answers `invalid`, never throws.
+- **Spaces carry their template**: `PodGrant.templateSlug` and
+  `PodSpace.templateSlug` (from `synap_grant[].templateSlug`), so
+  `client.spaces().find((s) => s.templateSlug === "content-os")` finds the space.
+  Absent when the space came from no template or the pod does not send it. The
+  sealed cookie keeps it (cookies sealed by 1.4 still open).
+- **A 401 renews once**: `synap.client(connection, { persist, request })` (a
+  route handler or a server action) renews a connection whose access key the
+  pod refused (a narrow, a pod-side "Revoke key") with ONE single-flight
+  rotation, persisted before use, and retries the request once. Lower level:
+  `createPodClient(connection, { renew })`. Without `persist` (a server
+  component) nothing is rotated and the 401 carries `PodError.refreshable`;
+  `refreshIfNeeded(request, { force: true })` rotates regardless of expiry.
+- **`pod_moved`** (`ConnectErrorCode`, `PodErrorCode`): `/token`, the metadata
+  or the Hub answered a redirect (a moved pod answers 308 from its old name).
+- **Discovery finds Synap Cloud pods by their current name**: `you.synap.live`
+  also tries `you.pod.synap.live`, then `pod.you.synap.live` (at most three
+  addresses).
+- **Bounded answers**: discovery, `/token` (64 KB each) and the Hub client
+  (`maxResponseBytes`, 8 MiB) count bytes on the stream and stop past the cap;
+  Hub requests time out (`timeoutMs`, 10 s) as `pod_unreachable`.
+- **`buildClientMetadata` refuses what the pod refuses**: actions other than
+  read/create/update/delete (the review verbs `proposal.approve` /
+  `proposal.reject` only for an official Synap app origin), a kind on a subject
+  other than `entity`, uppercase, more than 32 requests counted with
+  duplicates, an IP address `appUrl`.
+- **Packaging**: `engines.node >=20`, `types` per `import` / `require`
+  (`.d.ts` / `.d.cts`), `sideEffects`, this changelog. Shipped source no longer
+  cites internal spec, wave or PR tags.
+
+### `@synap-core/sdk/public`
+
+- **An HTML body arrives as HTML** (backend `body.format: "markdown" | "html"`):
+  `PublicShare` and `PublicRecord` carry `body: { format, content }`, and
+  `SharePageModel` / `RecordViewModel` gain `html: string | null`. Render it
+  ONLY inside `<iframe sandbox="" srcdoc>`, never in the page's own DOM;
+  markdown still goes through `parseSafeMarkdown`. `@synap-core/sdk/testing`
+  adds `MOCK_HTML_SHARE` (`MOCK_TOKENS.htmlShare`) for the mock-mode path.
+
+### Known issue
+
+- A **CommonJS** consumer that type-checks declaration files
+  (`skipLibCheck: false`) gets `TS1479` on the root entry `@synap-core/sdk`:
+  its `.d.cts` imports `@synap-core/api-types`, which ships ESM types only.
+  `skipLibCheck: true` (the default for Next.js and most apps), every ESM or
+  bundler consumer, and the `/public`, `/connect` and `/testing` entries are
+  unaffected. Fixed when api-types ships CJS declarations.
+
+### Behaviour changes
+
+- A Hub path that could leave `/api/hub` answers `{ ok: false, error: { code:
+  "invalid", reason: "invalid_input" } }` instead of throwing a `TypeError`, and
+  percent-encoded dot segments (`%2e%2e`) are refused too (WHATWG URL resolves
+  them like `..`, which sent the Bearer token to other pod routes).
+- `refreshIfNeeded` answering `revoked` or `expired` with the access token
+  spent now clears the session cookie (the marker stays), instead of leaving it
+  for 30 days and posting the dead token to `/token` on every page view.
+- A Hub answer with a 3xx status is `pod_moved` (was `server`); a `/token`
+  redirect is `pod_moved` (was `server_error`).
+
+### Kept for 1.x, changing in 2.0
+
+- The low-level building blocks of `@synap-core/sdk/connect` (`seal`/`unseal`,
+  `startConnect`/`handleCallback`/`refreshConnection`/`revokeConnection`,
+  `openTransaction`, `parseTokenResponse`, `startCloudConnect`/`acceptCloudReturn`,
+  the cookie helpers, `pkceChallenge`, the `*_MS` constants) are internal: an app on
+  `createPodAppAuth` needs none of them and nothing new is added to them. 2.0 moves
+  them to their own entry. `ConnectionStore` / `createSealedCookieStore` stay the
+  supported custom-store seam.
+- `startCloudConnect`: `secret` becomes required, `state` (ignored since 1.4) is
+  removed, and the call becomes a plain async function in 2.0.
+
+### `@synap-core/sdk/testing`
+
+- **`parseMockPodSeed(jsonOrValue)`** and `createMockAuthServer({ seed })`: the
+  mock pod's data as ONE JSON shape, `{ entities, sessions, documents, relations,
+  proposals, spaces }`, so a mock mode, a smoke run and screenshots replay one
+  recorded file.
+- New mock doors, answered from the seed in the backend's shapes:
+  `GET /entities/:id`, `GET /entities/:id/connections`, `GET /documents/:id`,
+  `GET /focus-sessions`, `POST /proposals/:id/approve`; `GET /proposals` honours
+  `proposalIds`.
+- `createMockAuthServer({ actsAs: "person" | "agent" })` answers
+  `synap_acts_as`; a person token's writes apply (unless `writeMode`) and it may
+  approve where it holds `proposal.approve`; an agent's approve is refused 403.
+  `mock.approvals` lists what was approved. Seeded `spaces` put `templateSlug`
+  on the token response's grant rows.
+
+## 1.4.0
+
+Re-consent (`prompt=consent`), Synap Cloud connect, `connection.manageUrl` /
+`appId`, `listPendingProposals`, `spaces()`, the lapse marker (`readLapsed`),
+`isPrefetchOrAsset`, `createMockCloud`. See the README.
+
+## 1.3.0
+
+`@synap-core/sdk/connect`: pod-app sign-in (CIMD, PKCE S256, `iss` checks,
+sealed cookie, rotating refresh) and `createMockAuthServer`.

package/README.md

@@ -79,6 +79,9 @@ is safe in a public site. The same entry ships the framework-free view-models a
 site renders (no React): `toFieldModels` / `validate` / `submitFailure` (forms),
 `toSharePageModel`, `parseSafeMarkdown` (data, never HTML), `formatPublicValue`,
 `toCollectionPageModel` / `pageQuery` / `parsePageParam`, `toRecordViewModel`.
+A published body is `format: "markdown"` (the models parse it into safe blocks) or
+`format: "html"` (a whole HTML document such as an estimate: the models hand it
+over as `html`; render it only in `<iframe sandbox="" srcdoc={html}>`).
 
 ```typescript
 import { createPublicClient } from "@synap-core/sdk/public";
@@ -119,7 +122,9 @@ SDK refuses out-of-bounds `offset`/`limit`/`sort` locally, without a request),
 pass `ifNoneMatch` from a browser: the doors allow no cross-origin request header
 but `Content-Type`, so the preflight fails (browsers revalidate on their own).
 
-## Pod-app sign-in (server-only): `@synap-core/sdk/connect` (1.3.0, 1.4.0)
+What a pod app can see and do (spaces, pod-wide people and companies, roles): see [AGENTS.md, "What a pod app can see and do"](./AGENTS.md#what-a-pod-app-can-see-and-do).
+
+## Pod-app sign-in (server-only): `@synap-core/sdk/connect` (1.3.0, 1.4.0, 1.5.0)
 
 An app that reads and writes a person's OWN pod connects as an OAuth 2.1 public
 client of that pod: its `client_id` is the https URL of its client metadata
@@ -171,17 +176,29 @@ export const config = {
 
 // a server component / action (no Request there: pass the Cookie header)
 const connection = await synap.readConnection((await headers()).get("cookie"));
-const pod = synap.client(connection!);
+if (!connection) redirect("/connect");
+const pod = synap.client(connection);
 const res = await pod.post("/entities", { profileSlug: "post", title: "Hello" });
 if (res.ok && res.status === "proposed") showPending(res.reviewUrl); // success: queued for review, never retry
-if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupported | rate_limited (retryAfterSec) | pod_unreachable | …
+if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupported | rate_limited (retryAfterSec) | pod_unreachable | pod_moved | …
 ```
 
-- **Discovery**: `discoverPod("pod.example.com")` fetches the pod's RFC 8414
+- **Discovery**: `discoverPod("you.pod.synap.live")` fetches the pod's RFC 8414
   metadata and requires `issuer` equal to the address, CIMD, `iss` on answers and
-  S256 (`not_a_pod`, `pod_unsupported`, `pod_unreachable`). A browser launch
-  (`?iss=…&target_link_uri=…`) is read with `acceptLaunch` and only pre-fills the
-  connect page.
+  S256 (`not_a_pod`, `pod_unsupported`, `pod_unreachable`). A Synap Cloud name
+  typed the old way (`you.synap.live`) also tries `you.pod.synap.live`, then
+  `pod.you.synap.live`; another address also tries `pod.<address>`. A redirect is
+  never followed (`pod_moved` when only an old, moved name answers). A browser
+  launch (`?iss=…&target_link_uri=…`) is read with `acceptLaunch` and only
+  pre-fills the connect page. The connect route fetches an address a visitor
+  typed: rate-limit it per visitor.
+- **Local development**: an app on `http://localhost` can sign in to the SDK's
+  mock pod only (`@synap-core/sdk/testing`, `allowInsecureLoopback`). Every real
+  pod, a local one included, refuses an http `client_id` and `redirect_uri`: run
+  the app on https (a tunnel) to sign in to a real pod.
+- **`space`** (the connect form, `startConnect({ spaceHint })`) is sent to the pod
+  as `synap_space_hint`, a hint its consent screen may use. A pod may ignore it:
+  never rely on a space being preselected.
 - **Failures** redirect with `?error=<ConnectErrorCode>`: `denied`,
   `expired_transaction`, `mismatch`, `misconfigured`, `rate_limited`,
   `pod_unreachable`, … (`parseConnectErrorCode` reads it back). `connect` and
@@ -196,7 +213,7 @@ if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupp
   rotation's result instead of reaching the pod. Across server instances only
   a shared server-side `ConnectionStore` rules that replay out. A concurrent
   loser (refused softly by the pod) keeps the still-valid access token.
-  The pod's reuse grace (PB3b) answers a spent token presented again within
+  The pod's reuse grace answers a spent token presented again within
   30 s with the same pair the first use got; its `expires_in` may be under an
   hour, and the SDK reads it as sent.
 - **Your own store**: implement `ConnectionStore` (`read`, `write`, `clear`,
@@ -211,7 +228,7 @@ if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupp
   goes to the pod's consent screen even when this browser is already connected to
   that pod (to widen or narrow access). It is a normal sign-in: fresh PKCE verifier
   and state, `iss` checked; a denied or forged answer leaves the live connection as it is.
-- **Synap Cloud** (wave C1): with `cloudUrl` set, `synap.cloudConnectAvailable` is
+- **Synap Cloud**: with `cloudUrl` set, `synap.cloudConnectAvailable` is
   true and `cloudConnectAvailable({ cloudUrl })` too. POST `handlers.cloudConnect`
   sends the browser to `<cp>/connect/pod?client_id=<client id>&state=<nonce>`, the
   state sealed in an HttpOnly cookie of that browser (10 minutes). The CP returns to
@@ -258,12 +275,137 @@ if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupp
   every time; ask for templates with `templates` (CIMD `synap_templates`) instead:
   the pod's consent offers to create the space.
 
+### 1.5.0 (additive): typed reads, who the app acts as, approvals
+
+**Which client for what.** A pod app (a website or service a person connects to
+their OWN pod, with a token from this sign-in) reads and writes through
+`synap.client(connection)` / `createPodClient(connection)`: it carries the
+connection's token, refuses expired tokens locally, and answers the typed codes
+below. `@synap-core/hub-rest-client` stays the client for scripts, CLIs and
+agents holding a static pod key (`apiKey`): it retries, throws `HubApiError` and
+knows far more doors. The two are separate on purpose; this SDK does not depend
+on it (CLIENTS.md).
+
+```typescript
+const pod = synap.client(connection);
+
+// Typed reads: PodResult<T>, the same codes as get/post (expired | unauthorized | forbidden |
+// door_unsupported | not_found | invalid | rate_limited | pod_unreachable | server | …)
+await pod.listEntities({ workspaceId, profileSlug: "post", limit: 1000 }); // PodEntity[]
+await pod.listEntities({ workspaceId, facetSlug: "lead", includeFacets: true }); // the wearers of a role, each with facets
+await pod.getEntity(id);                                                 // PodEntity, not_found on a miss
+await pod.getEntityConnections(id);                                      // { connections, counts }
+await pod.getDocument(documentId);                                       // { content, revision, sections, … }
+const sessions = await pod.listFocusSessions({ workspaceId, status: "active" });
+if (sessions.ok) sessions.data.flatMap(humanSlots);                      // what waits on the person (owner: "human")
+await pod.getFileUrl(fileEntityId);                                      // { url, expiresAt, mimeType }
+await pod.listPendingProposals({ proposalIds: [id1, id2] });             // only those (≤ 100)
+
+// Who the token acts as: "person" for an official Synap app, else "agent".
+pod.actsAs; // also connection.actsAs (absent = agent) and connectionActsAs(connection)
+const space = pod.spaces().find((s) => s.templateSlug === "content-os"); // the space made from that template
+
+// Approve, as the person (needs proposal.approve in requests, which only an official Synap app
+// on https://<id>.synap.live may ask for; any other appUrl is refused at setup). An agent connection is refused
+// before any request: { ok: false, error: { code: "forbidden", status: null, reason: "agent_cannot_approve" } }
+const res = await pod.approveProposal(proposalId, { workspaceId });
+```
+
+- **Writes**: an agent connection's writes are proposals (`proposed` is
+  success: show `reviewUrl`, never retry). A person connection's writes apply
+  directly, as the person, with no review step (`applied`). The result reports what the pod did either way, so a
+  `proposed` answer to a person (a space that reviews its members' changes) is
+  still success.
+- **`actsAs`** is read from every token response (code exchange, refresh, the
+  reuse grace), never carried over: a pod that stops saying `"person"`, or never
+  did, gives an agent connection. It drives the SDK's own
+  refusals and your UI's words; the pod enforces the rule itself.
+- **Local refusals** answer `status: null` with a `reason`
+  (`agent_cannot_approve`, `not_granted`, `invalid_input`) and send nothing: an
+  agent approving, a missing `proposal.read` / `proposal.approve`, an id that
+  could leave its path segment, `listFocusSessions` without a space or project.
+- **Shapes** are read from the backend routes (`src/connect/hub-types.ts` names
+  each one). A 2xx answer of another shape is `server` (status 200), never empty
+  data. Fields the SDK does not type stay on the objects.
+- **`templateSlug`** (`PodGrant`, `PodSpace`): the template the space was made
+  from, when the pod names one; absent for a space made by hand and from pods
+  that do not send it (keep a fallback, such as `ensure-template`, for those).
+  It survives the sealed cookie (`readConnection`).
+
+### 1.5.0: hardening
+
+- **A 401 renews once.** A narrow, or a pod-side "Revoke key", ends the access
+  key, not the connection. A client that can set cookies renews it ONCE (one
+  single-flight rotation, persisted before use) and retries the request once:
+
+  ```typescript
+  // a route handler: send the renewed cookie on its own response, as with refreshIfNeeded
+  const setCookies: string[] = [];
+  const pod = synap.client(connection, { request, persist: (c) => void setCookies.push(...c) });
+  const entities = await pod.listEntities({ workspaceId });
+  const response = Response.json(entities);
+  for (const c of setCookies) response.headers.append("Set-Cookie", c);
+  return response;
+  ```
+
+  `unauthorized` then means the pod refused the connection itself. A server
+  component cannot set cookies, so it passes no `persist`: nothing is rotated
+  there (the old refresh token would be spent and lost), and a 401 answers
+  `unauthorized` with `refreshable: true`. Send that visitor through the proxy
+  once with `refreshIfNeeded(request, { force: true })` (it rotates whatever the
+  expiry says; refused, it is `revoked`, never `kept`).
+- **A revoked connection's cookie is cleared** (`revoked` / `expired` with the
+  access token spent; the marker stays, so the visitor reads "expired"), so each
+  page view no longer posts the dead token to `/token`. A refresh that fails
+  while the access token still works (`kept`) is not asked again for a minute.
+- **A moved pod is `pod_moved`** (`ConnectErrorCode` and `PodErrorCode`): a
+  redirect from `/token`, the metadata or the Hub. Connect again with the pod's
+  new address; the SDK never takes it from the redirect.
+- **Bounded answers**: discovery (64 KB), the token endpoint (64 KB) and the Hub
+  (`maxResponseBytes`, 8 MiB) count bytes on the stream and stop there; Hub
+  requests time out (`timeoutMs`, 10 s) as `pod_unreachable`.
+- **Paths**: a Hub path that could leave `/api/hub` (a dot segment, plain or
+  percent-encoded, `//`, `\`, a query) answers `invalid` / `invalid_input`
+  instead of throwing. Encode each path segment (`encodeURIComponent`).
+- **`buildClientMetadata` refuses what the pod refuses**, at setup: an action
+  other than read/create/update/delete (`proposal.approve` and
+  `proposal.reject` only for an official Synap app on `https://<id>.synap.live`),
+  a kind on a subject other than `entity`, more than 32 requests counted with
+  duplicates, an IP address `appUrl`.
+- **Packaging**: `engines.node >=20` (WebCrypto global), `types` per
+  `import`/`require` (`.d.ts` / `.d.cts`), `sideEffects` (only the `connect`
+  entry runs code on load), this package's `CHANGELOG.md`.
+
 Test without a pod: `createMockAuthServer()` from `@synap-core/sdk/testing`
 (metadata, `authorize()` as the consent screen, `/token` with PKCE, rotating
 refresh with the 30 s reuse grace, `/revoke`, Hub REST doors: `GET /entities`
 answers an array as the pod does, `GET /proposals` lists what proposed writes
 filed; `synap_app` is `MOCK_APP` unless `app: null`; `writeMode`, `failures`, `refresh: false`, `entities`,
-`refreshGraceSec`), and `createMockCloud()` for the Synap Cloud pod chooser:
+`refreshGraceSec`), and `createMockCloud()` for the Synap Cloud pod chooser.
+1.5: `seed` (one JSON shape, `parseMockPodSeed`) feeds `GET /entities/:id`,
+`GET /entities/:id/connections`, `GET /documents/:id`, `GET /focus-sessions` and
+`proposalIds`; `actsAs: "person" | "agent"` answers `synap_acts_as` (a person's
+writes apply, it may approve where granted; an agent's approve is refused 403):
+
+```typescript
+import { readFileSync } from "node:fs";
+const seed = parseMockPodSeed(readFileSync("mock/pod-seed.json", "utf8")); // { entities, sessions, documents, relations, proposals, spaces }
+const pod = createMockAuthServer({ seed, actsAs: "person" });
+```
+
+1.5.1: an entity's roles ride on its seed row as `facets`, the shape
+`includeFacets=true` answers, plus the space whose members see it
+(`workspaceId`, seed only). A role in a granted space puts a pod-wide row in the app's reach
+(AGENTS.md, "What a pod app can see and do"). `GET /entities` then filters by
+`facetSlug`, drops a lens's pod-wide rows on `includePodWide: false`, and puts
+`facetSlugs` + `facets` on a row only when asked; `GET /entities/:id/facets` is
+served:
+
+```json
+{ "id": "ent_ada", "profileSlug": "person", "title": "Ada", "workspaceId": null,
+  "facets": [{ "facetId": "fct_1", "slug": "lead", "properties": { "leadStage": "prospect" }, "status": "new", "workspaceId": "ws_crm" }] }
+```
+
 
 ```typescript
 const pod = createMockAuthServer();

package/dist/{chunk-J7XHAAFJ.js → chunk-UK2U6SMA.js}

@@ -64,6 +64,14 @@ function serializeCookie(name, value, attrs) {
   return parts.join("; ");
 }
 
+// src/connect/rules.ts
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+var SPACE_HINT_RE = /^[A-Za-z0-9_-]{1,64}$/;
+var CLOUD_STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;
+function isIpLiteral(hostname) {
+  return hostname.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname);
+}
+
 export {
   utf8,
   fromUtf8,
@@ -74,6 +82,10 @@ export {
   pkceChallenge,
   constantTimeEqual,
   parseCookies,
-  serializeCookie
+  serializeCookie,
+  LOOPBACK_HOSTS,
+  SPACE_HINT_RE,
+  CLOUD_STATE_RE,
+  isIpLiteral
 };
-//# sourceMappingURL=chunk-J7XHAAFJ.js.map
+//# sourceMappingURL=chunk-UK2U6SMA.js.map

package/dist/chunk-UK2U6SMA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connect/encoding.ts","../src/connect/rules.ts"],"sourcesContent":["/**\n * Web-standard primitives (WebCrypto, TextEncoder, btoa/atob): the same code\n * runs on Node 20+, 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","/**\n * The shape rules several files of this entry (and the mock pod) apply, in\n * one place, so a hint or a state accepted in one door is accepted in all.\n */\n\n/** Hosts that count as this machine (WHATWG keeps IPv6 brackets: \"[::1]\"). */\nexport const LOOPBACK_HOSTS: ReadonlySet<string> = new Set([\"localhost\", \"127.0.0.1\", \"[::1]\"]);\n\n/** A `synap_space_hint`: a space id (uuid, short id), never a path or a query. */\nexport const SPACE_HINT_RE = /^[A-Za-z0-9_-]{1,64}$/;\n\n/** The `state` the Synap Cloud pod chooser accepts and echoes; ours is 43 base64url characters. */\nexport const CLOUD_STATE_RE = /^[A-Za-z0-9._~-]{16,256}$/;\n\n/** An IP literal host (dotted IPv4 or bracketed IPv6), as WHATWG URL normalises them. */\nexport function isIpLiteral(hostname: string): boolean {\n  return hostname.startsWith(\"[\") || /^\\d{1,3}(\\.\\d{1,3}){3}$/.test(hostname);\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;;;ACtFO,IAAM,iBAAsC,oBAAI,IAAI,CAAC,aAAa,aAAa,OAAO,CAAC;AAGvF,IAAM,gBAAgB;AAGtB,IAAM,iBAAiB;AAGvB,SAAS,YAAY,UAA2B;AACrD,SAAO,SAAS,WAAW,GAAG,KAAK,0BAA0B,KAAK,QAAQ;AAC5E;","names":[]}

package/dist/{client-C5sF20f1.d.cts → client-B50KC2aJ.d.cts}

@@ -31,15 +31,23 @@
  * `src/__tests__/fixtures.ts` copies those shapes; when the backend changes,
  * update both.
  */
+/**
+ * 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).
+ */
+interface PublicBody {
+    format: "markdown" | "html";
+    content: string;
+}
 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;
 }
@@ -123,10 +131,7 @@ interface PublicCollectionPage {
 }
 /** One published record, with its pinned body. */
 interface PublicRecord extends PublicRecordSummary {
-    body: {
-        format: "markdown";
-        content: string;
-    } | null;
+    body: PublicBody | null;
 }
 /** The collection door's query bounds (backend `parseCollectionQuery`). */
 declare const SITE_MAX_OFFSET = 10000;
@@ -250,4 +255,4 @@ interface PublicClient {
 }
 declare function createPublicClient(opts: PublicClientOptions): PublicClient;
 
-export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicReadError as a, type PublicRecordSummary as b, type PublicValue as c, type PublicCollectionPage as d, type PublicRecord as e, type PublicResult as f, type PublicShare as g, type PublicClient as h, type PublicClientOptions as i, type PublicFailure as j, type PublicFormField as k, type PublicFormFieldType as l, type PublicNotModified as m, type PublicSite as n, type PublicSiteCollection as o, type PublicSiteError as p, type PublicSiteResult as q, type PublicSubmitError as r, SITE_MAX_LIMIT as s, SITE_MAX_OFFSET as t, SITE_MAX_SORT_KEYS as u, SITE_PUBLISHED_AT_SORT as v, type SubmitFormInput as w, createPublicClient as x };
+export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicReadError as a, type PublicBody as b, type PublicRecordSummary as c, type PublicValue as d, type PublicCollectionPage as e, type PublicRecord as f, type PublicResult as g, type PublicShare as h, type PublicClient as i, type PublicClientOptions as j, type PublicFailure as k, type PublicFormField as l, type PublicFormFieldType as m, type PublicNotModified as n, type PublicSite as o, type PublicSiteCollection as p, type PublicSiteError as q, type PublicSiteResult as r, type PublicSubmitError as s, SITE_MAX_LIMIT as t, SITE_MAX_OFFSET as u, SITE_MAX_SORT_KEYS as v, SITE_PUBLISHED_AT_SORT as w, type SubmitFormInput as x, createPublicClient as y };

package/dist/{client-C5sF20f1.d.ts → client-B50KC2aJ.d.ts}

@@ -31,15 +31,23 @@
  * `src/__tests__/fixtures.ts` copies those shapes; when the backend changes,
  * update both.
  */
+/**
+ * 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).
+ */
+interface PublicBody {
+    format: "markdown" | "html";
+    content: string;
+}
 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;
 }
@@ -123,10 +131,7 @@ interface PublicCollectionPage {
 }
 /** One published record, with its pinned body. */
 interface PublicRecord extends PublicRecordSummary {
-    body: {
-        format: "markdown";
-        content: string;
-    } | null;
+    body: PublicBody | null;
 }
 /** The collection door's query bounds (backend `parseCollectionQuery`). */
 declare const SITE_MAX_OFFSET = 10000;
@@ -250,4 +255,4 @@ interface PublicClient {
 }
 declare function createPublicClient(opts: PublicClientOptions): PublicClient;
 
-export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicReadError as a, type PublicRecordSummary as b, type PublicValue as c, type PublicCollectionPage as d, type PublicRecord as e, type PublicResult as f, type PublicShare as g, type PublicClient as h, type PublicClientOptions as i, type PublicFailure as j, type PublicFormField as k, type PublicFormFieldType as l, type PublicNotModified as m, type PublicSite as n, type PublicSiteCollection as o, type PublicSiteError as p, type PublicSiteResult as q, type PublicSubmitError as r, SITE_MAX_LIMIT as s, SITE_MAX_OFFSET as t, SITE_MAX_SORT_KEYS as u, SITE_PUBLISHED_AT_SORT as v, type SubmitFormInput as w, createPublicClient as x };
+export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicReadError as a, type PublicBody as b, type PublicRecordSummary as c, type PublicValue as d, type PublicCollectionPage as e, type PublicRecord as f, type PublicResult as g, type PublicShare as h, type PublicClient as i, type PublicClientOptions as j, type PublicFailure as k, type PublicFormField as l, type PublicFormFieldType as m, type PublicNotModified as n, type PublicSite as o, type PublicSiteCollection as p, type PublicSiteError as q, type PublicSiteResult as r, type PublicSubmitError as s, SITE_MAX_LIMIT as t, SITE_MAX_OFFSET as u, SITE_MAX_SORT_KEYS as v, SITE_PUBLISHED_AT_SORT as w, type SubmitFormInput as x, createPublicClient as y };