@synap-core/sdk 1.3.0 → 1.4.0

package/src/connect/discovery.ts

@@ -15,9 +15,7 @@
  * resolves to a private address cannot be refused without a resolver; a
  * deployment that cares adds egress rules.
  *
- * Connecting through Synap Cloud (the CP pod chooser, wave C1) is not
- * available yet: `cloudConnectAvailable()` is false and `startCloudConnect`
- * throws `cp_unavailable`.
+ * Connecting through Synap Cloud (the CP pod chooser, wave C1) is ./cloud.ts.
  */
 import { ConnectError, retryAfterSeconds } from "./errors";
 import type { PodIssuer } from "./types";
@@ -195,16 +193,6 @@ export async function discoverPod(input: string, opts: DiscoverOptions = {}): Pr
   }
 }
 
-/** Whether "Continue with Synap Cloud" can be offered. False until the CP pod chooser (C1) ships. */
-export function cloudConnectAvailable(): boolean {
-  return false;
-}
-
-/** The Synap Cloud pod chooser (C1). Not available yet: always throws `cp_unavailable`. */
-export function startCloudConnect(_opts: { clientId: string; state?: string }): never {
-  throw new ConnectError("cp_unavailable", "cp: not available — connecting through Synap Cloud is not built yet; use a pod address");
-}
-
 /**
  * A same-origin path to return to after connecting, or null. Accepts a
  * relative path (never `//host` or `/\host`) or an absolute URL on the app's
@@ -235,12 +223,21 @@ export interface LaunchHint {
   next: string | null;
   /** A space to preselect on consent (`synap_space_hint`). */
   spaceHint: string | null;
+  /**
+   * The `state` of a Synap Cloud return (the CP pod chooser answers
+   * `initiate_login_uri?iss=…&state=…`, or `?state=…&error=access_denied` when
+   * the person cancelled), shape-checked only. NOT verified here:
+   * send the request's query to the cloud handler (GET `paths.cloud`), which
+   * checks it against this browser's sealed cookie. Never act on `pod` because
+   * a state is present.
+   */
+  cloudState: string | null;
 }
 
 /**
  * Read a third-party-initiated login (OIDC Core §4, spec 17 §7.2): the browser
  * opens the app's `initiate_login_uri?iss=…&target_link_uri=…`. One parser for
- * the browser launch and, later, the Synap Cloud chooser's return.
+ * the browser launch and the Synap Cloud chooser's return (`cloudState`).
  */
 export function acceptLaunch(url: string | URL, appOrigin: string, opts: { allowInsecureLoopback?: boolean } = {}): LaunchHint {
   const params = new URL(url).searchParams;
@@ -254,9 +251,13 @@ export function acceptLaunch(url: string | URL, appOrigin: string, opts: { allow
     }
   }
   const hint = params.get("synap_space_hint");
+  const state = params.get("state");
   return {
     pod,
     next: safeNextPath(params.get("target_link_uri"), appOrigin),
     spaceHint: hint && /^[A-Za-z0-9_-]{1,64}$/.test(hint) ? hint : null,
+    // A browser launch never carries a state: any well-formed one is a Synap Cloud return
+    // (a pick: iss + state; a cancel: state + error=access_denied, no iss).
+    cloudState: state && /^[A-Za-z0-9._~-]{16,256}$/.test(state) ? state : null,
   };
 }

package/src/connect/errors.ts

@@ -13,7 +13,7 @@ export type ConnectErrorCode =
   | "pod_unreachable"
   /** A Synap pod, but too old for app sign-in (no CIMD, no `iss`, no S256). */
   | "pod_unsupported"
-  /** Connecting through Synap Cloud is not available yet. */
+  /** Connecting through Synap Cloud is not configured for this app (no Control Plane URL). */
   | "cp_unavailable"
   /** The person said no on the consent screen. */
   | "denied"

package/src/connect/flow.ts

@@ -66,6 +66,12 @@ export interface StartConnectOptions extends FlowOptions {
   spaceHint?: string | null;
   /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
   next?: string | null;
+  /**
+   * `"consent"`: the person asked to see the consent screen again (to widen or
+   * narrow what the app may touch). Sent as OIDC `prompt=consent`; the sign-in
+   * is otherwise the same (fresh PKCE verifier and state).
+   */
+  prompt?: "consent" | null;
   allowInsecureLoopback?: boolean;
 }
 
@@ -114,6 +120,7 @@ export async function startConnect(opts: StartConnectOptions): Promise<StartedCo
   url.searchParams.set("code_challenge_method", "S256");
   if (resource) url.searchParams.set("resource", resource);
   if (opts.spaceHint) url.searchParams.set("synap_space_hint", opts.spaceHint);
+  if (opts.prompt === "consent") url.searchParams.set("prompt", "consent");
 
   const tx: ConnectTransaction = {
     v: 1,
@@ -270,6 +277,32 @@ function parseGrant(value: unknown): PodGrant[] | null {
   return out;
 }
 
+const APP_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+/**
+ * `synap_app` (Synap extension): the pod's id for this app connection and its
+ * page for it. The page is on the pod's console, which may be another host
+ * than the issuer, so it is kept when it is an absolute https URL (http only on
+ * loopback) without credentials; anything else is dropped.
+ */
+function parseApp(value: unknown): { appId?: string; manageUrl?: string } {
+  if (!value || typeof value !== "object") return {};
+  const { id, manageUrl } = value as Record<string, unknown>;
+  const out: { appId?: string; manageUrl?: string } = {};
+  if (typeof id === "string" && APP_ID_RE.test(id)) out.appId = id;
+  if (typeof manageUrl === "string" && manageUrl.length <= 2048) {
+    try {
+      const url = new URL(manageUrl);
+      const secure = url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname));
+      if (secure && !url.username && !url.password) out.manageUrl = url.href;
+    } catch {
+      // not a URL: no link
+    }
+  }
+  return out;
+}
+
 function parseUser(value: unknown): PodUser | null {
   if (!value || typeof value !== "object") return null;
   const { id, name } = value as Record<string, unknown>;
@@ -278,7 +311,9 @@ function parseUser(value: unknown): PodUser | null {
 
 /**
  * A token response → a connection. On a refresh, `previous` supplies what the
- * response may omit (grant, user). A refresh response WITHOUT a new
+ * response may omit (grant, user, app). `expires_in` is read as sent: a refresh
+ * answered within the pod's reuse grace (PB3b) hands back the live key the
+ * first redeem got, with less than an hour left. A refresh response WITHOUT a new
  * refresh_token drops the old one: with single-use rotation, resending a
  * consumed token reads as theft and revokes the whole family.
  */
@@ -322,6 +357,11 @@ export function parseTokenResponse(
     user,
     connectedAt: ctx.previous?.connectedAt ?? ctx.now,
   };
+  const app = parseApp(body.synap_app);
+  const appId = app.appId ?? ctx.previous?.appId;
+  const manageUrl = app.manageUrl ?? ctx.previous?.manageUrl;
+  if (appId !== undefined) connection.appId = appId;
+  if (manageUrl !== undefined) connection.manageUrl = manageUrl;
   if (typeof refresh_token === "string" && refresh_token !== "") {
     connection.refreshToken = refresh_token;
     const idle =

package/src/connect/index.ts

@@ -15,17 +15,26 @@ import { assertServerRuntime } from "./guard";
 
 assertServerRuntime();
 
-export { createPodAppAuth, buildClientMetadata, DEFAULT_PATHS, REFRESH_WINDOW_MS } from "./auth";
+export { createPodAppAuth, buildClientMetadata, isPrefetchOrAsset, DEFAULT_PATHS, REFRESH_WINDOW_MS } from "./auth";
 export type { PodAppAuth, PodAppAuthConfig, PodAppPaths, RefreshOutcome, RefreshStatus } from "./auth";
+export { discoverPod, canonicalPodUrl, acceptLaunch, safeNextPath } from "./discovery";
+export type { DiscoverOptions, LaunchHint } from "./discovery";
 export {
-  discoverPod,
-  canonicalPodUrl,
-  acceptLaunch,
-  safeNextPath,
   cloudConnectAvailable,
   startCloudConnect,
-} from "./discovery";
-export type { DiscoverOptions, LaunchHint } from "./discovery";
+  acceptCloudReturn,
+  cloudBaseUrl,
+  CLOUD_TRANSACTION_TTL_MS,
+} from "./cloud";
+export type {
+  AcceptCloudReturnOptions,
+  CloudConnectConfig,
+  CloudReturn,
+  CloudTransaction,
+  SealedCloudTransaction,
+  StartCloudConnectOptions,
+  StartedCloudConnect,
+} from "./cloud";
 export {
   startConnect,
   openTransaction,
@@ -46,9 +55,28 @@ export type {
   StartConnectOptions,
   StartedConnect,
 } from "./flow";
-export { createPodClient, can, reviewUrlFor } from "./client";
-export type { PodClient, PodClientOptions, PodError, PodErrorCode, PodResult, PodWriteResult, QueryValue } from "./client";
-export { createSealedCookieStore, cookieNames, applySetCookies, connectionExpiresAt } from "./store";
+export { createPodClient, can, spaces, reviewUrlFor } from "./client";
+export type {
+  ListPendingProposalsOptions,
+  PendingProposal,
+  PendingProposals,
+  PodClient,
+  PodClientOptions,
+  PodError,
+  PodErrorCode,
+  PodResult,
+  PodWriteResult,
+  QueryValue,
+} from "./client";
+export {
+  createSealedCookieStore,
+  cookieNames,
+  applySetCookies,
+  connectionExpiresAt,
+  markerCookie,
+  readMarker,
+  MARKER_TTL_SEC,
+} from "./store";
 export type { ConnectionStore, CookieNames, SealedCookieStoreOptions } from "./store";
 export { seal, unseal, MIN_SECRET_LENGTH } from "./seal";
 export type { AppSecret, Opened, SealPurpose } from "./seal";
@@ -56,4 +84,4 @@ export { pkceChallenge } from "./encoding";
 export { ConnectError, isConnectError, parseConnectErrorCode, CONNECT_ERROR_CODES } from "./errors";
 export type { ConnectErrorCode } from "./errors";
 export { isBrowserRuntime } from "./guard";
-export type { AppRequest, ClientMetadataDocument, PodConnection, PodGrant, PodIssuer, PodUser } from "./types";
+export type { AppRequest, ClientMetadataDocument, PodConnection, PodGrant, PodIssuer, PodSpace, PodUser } from "./types";

package/src/connect/seal.ts

@@ -13,7 +13,7 @@
 import { ConnectError } from "./errors";
 import { base64url, fromBase64url, fromUtf8, randomBytes, utf8 } from "./encoding";
 
-export type SealPurpose = "synap-connect/transaction" | "synap-connect/session";
+export type SealPurpose = "synap-connect/transaction" | "synap-connect/session" | "synap-connect/cloud";
 
 /** The app secret: one value, or several to rotate (the first seals, all open). */
 export type AppSecret = string | readonly string[];

package/src/connect/store.ts

@@ -7,7 +7,8 @@
  * Bring your own (a database, a KV) by implementing `ConnectionStore`; it
  * answers with the Set-Cookie values to send (e.g. its own session id).
  */
-import { parseCookies, serializeCookie } from "./encoding";
+import { canonicalPodUrl } from "./discovery";
+import { base64url, fromBase64url, fromUtf8, parseCookies, serializeCookie, utf8 } from "./encoding";
 import { ConnectError } from "./errors";
 import { seal, unseal, type AppSecret } from "./seal";
 import type { PodConnection, PodGrant } from "./types";
@@ -24,13 +25,50 @@ export interface ConnectionStore {
 export interface CookieNames {
   session: string;
   transaction: string;
+  /** A Synap Cloud sign-in in progress (sealed state, 10 minutes). */
+  cloud: string;
+  /** "This browser was connected to <pod>": the pod's URL only, no secret (`markerCookie`). */
+  marker: string;
 }
 
 /** `__Host-` names on https (Secure, Path=/, no Domain: bound to this exact host). */
 export function cookieNames(secure: boolean): CookieNames {
   return secure
-    ? { session: "__Host-synap_session", transaction: "__Host-synap_tx" }
-    : { session: "synap_session", transaction: "synap_tx" };
+    ? { session: "__Host-synap_session", transaction: "__Host-synap_tx", cloud: "__Host-synap_cloud", marker: "__Host-synap_seen" }
+    : { session: "synap_session", transaction: "synap_tx", cloud: "synap_cloud", marker: "synap_seen" };
+}
+
+/** The marker outlives the connection: as long as browsers keep a cookie (400 days). */
+export const MARKER_TTL_SEC = 400 * 24 * 60 * 60;
+
+/**
+ * The marker cookie: which pod this browser was connected to, so a connection
+ * that lapsed (idle past the refresh token's life, its sealed cookie gone)
+ * reads as "expired, connect again to <pod>" rather than "never connected".
+ * It holds the pod's public URL and NOTHING else: no token, no user, nothing
+ * sealed. A forged value can only pre-fill the address the person confirms.
+ */
+export function markerCookie(podUrl: string, opts: { secure: boolean; name?: string }): string {
+  return serializeCookie(opts.name ?? cookieNames(opts.secure).marker, base64url(utf8(podUrl)), {
+    maxAgeSec: MARKER_TTL_SEC,
+    secure: opts.secure,
+  });
+}
+
+/** The marker's pod URL, or null (absent, or not a canonical pod address). */
+export function readMarker(
+  cookieHeader: string | null,
+  opts: { secure: boolean; name?: string; allowInsecureLoopback?: boolean },
+): string | null {
+  const raw = parseCookies(cookieHeader).get(opts.name ?? cookieNames(opts.secure).marker);
+  const bytes = raw ? fromBase64url(raw) : null;
+  if (!bytes || bytes.length > 512) return null;
+  const podUrl = fromUtf8(bytes);
+  try {
+    return canonicalPodUrl(podUrl, opts) === podUrl ? podUrl : null;
+  } catch {
+    return null;
+  }
 }
 
 /** Browsers cap a cookie near 4096 bytes; a big grant spans several. */

package/src/connect/types.ts

@@ -63,6 +63,26 @@ export interface PodConnection {
   user: PodUser;
   /** ms since epoch. */
   connectedAt: number;
+  /**
+   * The pod's id for this app connection (`app_…`, the grant's client id), when
+   * the token response names it (`synap_app.id`). Absent from pods that do not.
+   */
+  appId?: string;
+  /**
+   * The pod's own page for this app connection (pod-admin `/apps/<appId>`:
+   * what it may touch, narrow it, apply automatically, revoke), when the token
+   * response names it (`synap_app.manageUrl`). Absent otherwise: hide the link,
+   * never guess one.
+   */
+  manageUrl?: string;
+}
+
+/** One space of the grant, its permissions together (`spaces(connection)`). */
+export interface PodSpace {
+  workspaceId: string;
+  /** "" when the pod sent no name. */
+  workspaceName: string;
+  permissions: string[];
 }
 
 /** The CIMD document an app serves at its client_id URL (spec 17 §6.1). */

package/src/testing/auth-server.ts

@@ -13,13 +13,23 @@
  * 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
+ * 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).
  *
+ * 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.
+ *
  *   mock.authorize(authorizeUrl)                  → the callback URL (approved)
  *   mock.authorize(authorizeUrl, { deny: true })  → error=access_denied
  *   mock.authorize(authorizeUrl, { iss: "https://evil.example" })  → a mix-up attempt
- *   mock.loseNextRefreshRace()                    → the next redeem is a concurrent loser (refused, no revoke)
- *   mock.consumeRefreshToken(t)                   → the token was used elsewhere (presenting it is a reuse)
+ *   mock.loseNextRefreshRace()                    → the next redeem is a concurrent loser that found no successor (refused, no revoke)
+ *   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
  */
 import { pkceChallenge, randomToken } from "../connect/encoding";
@@ -47,6 +57,15 @@ 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). */
+  refreshGraceSec?: number;
+  /**
+   * `synap_app` on token responses: the connection's id and its page on the
+   * pod console. Default `MOCK_APP`; null = a pod that does not send it.
+   */
+  app?: { id: string; manageUrl: string | null } | null;
+  /** Entities `GET /entities` answers (with `workspaceId` / `profileSlug` filters). */
+  entities?: Array<Record<string, unknown>>;
   grant?: PodGrant[];
   user?: PodUser;
   /** Override or remove (undefined) metadata fields: a pod too old, a lying issuer. */
@@ -76,12 +95,41 @@ export interface AuthorizeDecision {
   state?: string;
 }
 
+/** A proposal a governed write filed (`GET /proposals` lists the pending ones). */
+export interface MockProposal {
+  id: string;
+  proposalType: string;
+  targetType: string;
+  targetId: string | null;
+  status: "pending" | "approved" | "rejected";
+  workspaceId: string | null;
+  createdAt: string;
+  correlationId: string | null;
+  sessionId: string | null;
+  agentUserId: string | null;
+  summary?: string;
+}
+
+/** The connection's `synap_app` the mock pod answers by default (backend `appTokenResponse`). */
+export const MOCK_APP = { id: "app_mock_studio", manageUrl: "https://pod-admin.mock-synap.test/apps/app_mock_studio" };
+
+/** The app's agent on the mock pod: who files its proposals. */
+export const MOCK_APP_AGENT_ID = "agent_mock_app";
+
 export interface MockAuthServer {
   issuer: string;
   fetch: typeof fetch;
   requests: MockAuthRequest[];
   /** Hub writes seen, in order. */
   writes: Array<{ method: string; path: string; body: unknown }>;
+  /** Proposals filed by proposed writes, in order. */
+  proposals: MockProposal[];
+  /** 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. */
+  redeemElsewhere(token: string): Promise<{ access_token: string; refresh_token: string; expires_in: number }>;
+  /** Refresh redeems answered within the reuse grace (the same pair again). */
+  graceAnswers: number;
   /** Stand-in for the consent screen: validates the request like /authorize, returns where the pod redirects. */
   authorize(authorizeUrl: string, decision?: AuthorizeDecision): string;
   /** Mark a refresh token used elsewhere: presenting it now is a REUSE (family + live key revoked). */
@@ -109,6 +157,7 @@ interface AccessRow {
   expiresAt: number;
   revoked: boolean;
   family: string | null;
+  scope: string[];
 }
 
 interface RefreshRow {
@@ -118,6 +167,10 @@ interface RefreshRow {
   used: boolean;
   revoked: boolean;
   scope: string[];
+  /** When it was spent, and the pair that use was answered (the grace re-answers it). */
+  usedAt?: number;
+  successor?: string;
+  pairAccess?: string;
 }
 
 function json(status: number, body: unknown, headers: Record<string, string> = {}): Response {
@@ -144,7 +197,12 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
   const refreshTokens = new Map<string, RefreshRow>();
   const requests: MockAuthRequest[] = [];
   const writes: Array<{ method: string; path: string; body: unknown }> = [];
+  const proposals: MockProposal[] = [];
+  const entities: Array<Record<string, unknown>> = [...(options.entities ?? [])];
+  const graceMs = (options.refreshGraceSec ?? 30) * 1000;
+  const app = options.app === undefined ? MOCK_APP : options.app;
   let proposalSeq = 0;
+  let graceAnswers = 0;
 
   const metadata = (): Record<string, unknown> => {
     const base: Record<string, unknown> = {
@@ -175,18 +233,25 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     for (const a of access.values()) if (a.family === family) a.revoked = true;
   };
 
-  const tokenBody = (scope: string[], clientId: string, family: string) => {
-    const accessToken = `synap_hub_mock_${randomToken()}`;
-    access.set(accessToken, { expiresAt: now() + accessTtl * 1000, revoked: false, family: refresh ? family : null });
+  /** The token response; `pair` re-answers an existing access key + refresh token (the grace). */
+  const tokenBody = (scope: string[], clientId: string, family: string, pair?: { accessToken: string; refreshToken: string }) => {
+    const accessToken = pair?.accessToken ?? `synap_hub_mock_${randomToken()}`;
+    if (!pair) access.set(accessToken, { expiresAt: now() + accessTtl * 1000, revoked: false, family: refresh ? family : null, scope });
+    const row = access.get(accessToken)!;
     const body: Record<string, unknown> = {
       access_token: accessToken,
       token_type: "Bearer",
-      expires_in: accessTtl,
+      // 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)),
       synap_user: user,
+      ...(app ? { synap_app: app } : {}),
     };
-    if (refresh) {
+    if (pair) {
+      body.refresh_token = pair.refreshToken;
+      if (options.advertiseRefreshExpiry) body.refresh_token_expires_in = Math.floor((refreshTokens.get(pair.refreshToken)!.idleUntil - now()) / 1000);
+    } else if (refresh) {
       const refreshToken = randomToken();
       refreshTokens.set(refreshToken, { clientId, family, idleUntil: now() + refreshIdle * 1000, used: false, revoked: false, scope });
       body.refresh_token = refreshToken;
@@ -220,6 +285,14 @@ 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.
+        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;
+        if (inGrace && successor && !successor.used && !successor.revoked && key && !key.revoked && key.expiresAt > now()) {
+          graceAnswers++;
+          return json(200, tokenBody(row.scope, row.clientId, row.family, { accessToken: row.pairAccess!, refreshToken: row.successor! }));
+        }
         reuses++;
         revokeFamily(row.family);
         return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
@@ -230,12 +303,18 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
         return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
       }
       row.used = true;
-      return json(200, tokenBody(row.scope, row.clientId, row.family));
+      row.usedAt = now();
+      // One live key per connection: the rotation retires the family's older keys.
+      for (const a of access.values()) if (a.family === row.family) a.revoked = true;
+      const body = tokenBody(row.scope, row.clientId, row.family);
+      row.successor = body.refresh_token as string;
+      row.pairAccess = body.access_token as string;
+      return json(200, body);
     }
     return oauthError("unsupported_grant_type", "Unsupported grant_type");
   }
 
-  function hub(method: string, path: string, headers: Record<string, string>, body: unknown): Response | "reject" {
+  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";
     const bearer = /^Bearer (.+)$/.exec(headers.authorization ?? "")?.[1];
@@ -258,11 +337,48 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       return json(403, { error: "This door is not available to a space-scoped key", code: "GRANT_DOOR_UNSUPPORTED" });
     }
     if (method === "GET" && path === "/users/me") return json(200, user);
-    if (method === "GET" && path === "/entities") return json(200, { entities: [], total: 0 });
+    if (method === "GET" && path === "/entities") {
+      // The pod answers an ARRAY (rest/entities.ts), not a page object.
+      const ws = query.get("workspaceId");
+      const kind = query.get("profileSlug");
+      const offset = Number(query.get("offset") ?? 0) || 0;
+      const limit = Number(query.get("limit") ?? 50) || 50;
+      const rows = entities.filter((e) => (!ws || e.workspaceId === ws) && (!kind || e.profileSlug === kind));
+      return json(200, rows.slice(offset, offset + limit));
+    }
+    if (method === "GET" && path === "/proposals") {
+      // The grant clause: proposals are read only where the token holds proposal.read (else none, not a 403).
+      const readable = new Set(grant.filter((g) => g.permission === "proposal.read" && row.scope.includes(g.permission)).map((g) => g.workspaceId));
+      const status = query.get("status") ?? "pending";
+      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;
+      const rows = proposals
+        .filter((p) => p.workspaceId !== null && readable.has(p.workspaceId))
+        .filter((p) => (status === "all" || p.status === status) && (!ws || p.workspaceId === ws))
+        .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") {
       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") {
         const proposalId = `prop_mock_${++proposalSeq}`;
+        proposals.push({
+          id: proposalId,
+          proposalType: method === "POST" ? "create" : method === "DELETE" ? "delete" : "update",
+          targetType: path.split("/")[1]?.replace(/s$/, "") ?? "entity",
+          targetId: null,
+          status: "pending",
+          workspaceId,
+          createdAt: new Date(now()).toISOString(),
+          correlationId: null,
+          sessionId: null,
+          agentUserId: MOCK_APP_AGENT_ID,
+          ...(typeof fields.title === "string" ? { summary: `Create "${fields.title}"` } : {}),
+        });
         return json(200, {
           status: "proposed",
           message: "Sent for review",
@@ -270,7 +386,9 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
           reviewUrl: `${issuer}/open/${proposalId}`,
         });
       }
-      return json(200, { status: "created", id: `ent_mock_${writes.length}` });
+      const id = `ent_mock_${writes.length}`;
+      if (method === "POST" && path === "/entities") entities.push({ id, ...fields });
+      return json(200, { status: "created", id });
     }
     return json(404, { error: "Not found" });
   }
@@ -311,7 +429,7 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
       } catch {
         body = rawBody;
       }
-      const res = hub(method, hubPath, headers, body);
+      const res = hub(method, hubPath, url.searchParams, headers, body);
       if (res === "reject") throw new TypeError("Failed to fetch: mock pod unreachable");
       return res;
     }
@@ -323,6 +441,20 @@ export function createMockAuthServer(options: MockAuthServerOptions = {}): MockA
     fetch: mockFetch as typeof fetch,
     requests,
     writes,
+    proposals,
+    settleProposal(id, status) {
+      const p = proposals.find((x) => x.id === id);
+      if (p) p.status = status;
+    },
+    async redeemElsewhere(t) {
+      const row = refreshTokens.get(t);
+      const res = await token({ grant_type: "refresh_token", refresh_token: t, client_id: row?.clientId ?? "" });
+      if (res.status !== 200) throw new Error(`redeemElsewhere: the pod answered ${res.status}`);
+      return (await res.json()) as { access_token: string; refresh_token: string; expires_in: number };
+    },
+    get graceAnswers() {
+      return graceAnswers;
+    },
     authorize(authorizeUrl, decision = {}) {
       const url = new URL(authorizeUrl);
       if (`${url.origin}${url.pathname}` !== `${issuer}/authorize`) throw new Error(`Not this pod's /authorize: ${authorizeUrl}`);