@synap-core/sdk 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,133 @@
+# @synap-core/sdk changelog
+
+## 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,7 @@ 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)
+## 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
@@ -142,34 +145,58 @@ export const synap = createPodAppAuth({
     { permission: "entity.post.create", reason: "Save drafts to your pod" },
   ],
   secret: process.env.SYNAP_APP_SESSION_SECRET!, // ≥ 32 chars, never NEXT_PUBLIC_
+  cloudUrl: process.env.SYNAP_CLOUD_URL, // optional (1.4): https://api.synap.live offers "Continue with Synap Cloud"
 });
 
 // app/.well-known/synap-client.json/route.ts  export const GET = synap.handlers.clientMetadata;
-// app/api/synap/connect/route.ts               export const POST = synap.handlers.connect;    // form { pod, next?, space? }
+// app/api/synap/connect/route.ts               export const POST = synap.handlers.connect;    // form { pod, next?, space?, prompt? }
 // app/api/synap/callback/route.ts              export const GET = synap.handlers.callback;
 // app/api/synap/disconnect/route.ts            export const POST = synap.handlers.disconnect; // form { next? }
+// app/api/synap/cloud/route.ts (1.4)           export const POST = synap.handlers.cloudConnect; // form { next?, space?, prompt? }
+//                                              export const GET = synap.handlers.cloudReturn;
 ```
 
 ```typescript
 // proxy.ts: refresh before render (server components cannot set cookies)
 const out = await synap.refreshIfNeeded(request);
 // out.status: none | skipped | fresh | refreshed | kept | expired | revoked | unavailable
+// out.lapsed (with none, 1.4): { podUrl } when this browser WAS connected and the connection lapsed
 // send out.setCookies on the response; forward out.cookieHeader (when set) as the request's Cookie
 
+// Next 16 strips its router headers before proxy code runs, so skip prefetches in the MATCHER
+// (it still sees them; matcher values must be literals):
+export const config = {
+  matcher: [{
+    source: "/((?!_next/static|_next/image|api/synap/|\\.well-known/|.*\\.\\w+$).*)",
+    missing: [{ type: "header", key: "next-router-prefetch" }, { type: "header", key: "purpose", value: "prefetch" }],
+  }],
+};
+
 // 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. Synap Cloud discovery is not available yet:
-  `cloudConnectAvailable()` is `false`.
+  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
@@ -184,19 +211,192 @@ 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 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`,
   returning Set-Cookie values) and pass it as `store`.
 - Lower level: `startConnect`, `handleCallback`, `refreshConnection`,
-  `revokeConnection`, `buildClientMetadata`, `seal`/`unseal`.
+  `revokeConnection`, `buildClientMetadata`, `seal`/`unseal`,
+  `startCloudConnect`, `acceptCloudReturn`.
+
+### 1.4.0 (additive)
+
+- **Re-consent**: the connect form's `prompt=consent` (or `startConnect({ prompt: "consent" })`)
+  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**: 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
+  the CIMD `initiate_login_uri?iss=<pod>&state=<nonce>` (your connect page):
+  `acceptLaunch(url).cloudState` is set, so forward the request's query to GET
+  `handlers.cloudReturn`, which checks the state against the cookie (constant time,
+  single use) BEFORE the pod is used, then runs the same sign-in as a typed address.
+  `acceptLaunch` itself never verifies anything; a return without a matching state
+  starts no sign-in (`mismatch`, `expired_transaction`). A cancel on the chooser
+  (`?state=…&error=access_denied`, no `iss`) also carries `cloudState`: forwarded the
+  same way, it lands on the connect page with `?error=denied` once the state matched.
+  Security notes: after the state matches, the named pod goes through the same
+  discovery as a typed address (metadata, `issuer` equality, CIMD, `iss`, S256)
+  before the browser is sent anywhere. The cloud cookie is single-use and cleared on
+  every outcome (success, cancel, mismatch). Accepted trade-off: a third-party page
+  that sends a visitor's browser to a forged return can cancel that visitor's Cloud
+  sign-in in progress (they click again); nothing leaks and nothing is bound, the
+  same nuisance any OAuth `state` check allows.
+
+  ```typescript
+  // app/connect/page.tsx (server component)
+  const launch = acceptLaunch(url, origin);
+  if (launch.cloudState) redirect(`${synap.paths.cloud}${new URL(url).search}`);
+  ```
+- **`connection.manageUrl` / `connection.appId`**: the pod's page for this app
+  connection (pod-admin `/apps/<appId>`), read from the token response's
+  `synap_app: { id, manageUrl }` (https only). Absent when the pod does not send it:
+  hide the link, never build one.
+- **`client.listPendingProposals({ workspaceId?, limit?, offset? })`**: "Waiting for
+  review: N" (`data.total`, plus summary rows with `reviewUrl`) from the pod's seamed
+  `GET /proposals` door. Ask for `proposal.read` in `requests`: without it the answer
+  is `forbidden` and nothing is sent (the pod would answer an empty list). It counts
+  the person's pending proposals in those spaces, from any agent.
+- **`spaces(connection)` / `client.spaces()`**: the grant by space
+  (`{ workspaceId, workspaceName, permissions }`), each permission once.
+- **Expired vs never connected**: each sign-in and refresh also sets a marker cookie
+  (`__Host-synap_seen`, 400 days) holding the pod's URL and nothing else.
+  `synap.readLapsed(cookieHeader)` and `RefreshOutcome.lapsed` say "this browser was
+  connected to <pod>" once the sealed session is gone; a disconnect clears it.
+- **`isPrefetchOrAsset(request)`** is exported, and its limit documented: inside
+  Next 16's proxy a router prefetch is invisible (see the matcher above).
+- Not added: `ensureTemplate` on the pod-app client. A pod-app key's grant is pinned
+  to the approved spaces, so creating a space is refused by the pod's grant check
+  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.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, `/revoke`, Hub REST doors; `writeMode`, `failures`, `refresh: false`):
+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.
+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" });
+```
+
 
 ```typescript
 const pod = createMockAuthServer();
-const synap = createPodAppAuth({ ...config, fetch: pod.fetch });
+const cloud = createMockCloud();
+const synap = createPodAppAuth({ ...config, fetch: pod.fetch, cloudUrl: cloud.url });
 // POST connect → Location → pod.authorize(location) → GET callback with that URL
+// POST cloud → Location → cloud.choose(location, { pod: pod.issuer, metadata: synap.metadata }) → forward to GET cloud
 ```
 
 ## Mock pod: `@synap-core/sdk/testing`

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":"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","names":[]}

package/dist/{client-CVUT1Mcf.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 PublicShare as a, type PublicRecord as b, type PublicReadError as c, type PublicRecordSummary as d, type PublicValue as e, type PublicCollectionPage as f, type PublicResult 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-CVUT1Mcf.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 PublicShare as a, type PublicRecord as b, type PublicReadError as c, type PublicRecordSummary as d, type PublicValue as e, type PublicCollectionPage as f, type PublicResult 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 };