@synap-core/sdk 1.2.0 → 1.4.0

package/src/testing/auth-server.ts

@@ -0,0 +1,512 @@
+/**
+ * A mock pod for pod-app sign-in: its OAuth authorization server (RFC 8414
+ * metadata, /authorize as a function standing in for the consent screen,
+ * /token, /revoke) and a few Hub REST doors behind the Bearer token. Inject
+ * `fetch` into the REAL `@synap-core/sdk/connect` (`createPodAppAuth({ fetch })`)
+ * so everything above the wire is the production path. No network.
+ *
+ * Wire behaviour mirrors synap-backend `routers/oauth/routes.ts` for a CIMD
+ * client: `iss` on every authorization answer (RFC 9207), PKCE S256 checked at
+ * /token, single-use codes bound to client_id + redirect_uri + resource, the
+ * token response's `synap_grant` / `synap_user`. Refresh mirrors PB3
+ * (`routers/oauth/refresh.ts`): rotating and single-use, 30 days from issue;
+ * a token presented AGAIN after its use is a reuse that revokes its whole
+ * family AND the live access key; a new code ends the client's older
+ * families; /revoke with a refresh token kills its family and access key.
+ * The reuse grace (PB3b): within 30 s of its use, a spent token presented
+ * 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 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";
+import type { PodGrant, PodUser } from "../connect/types";
+
+/** A placeholder pod origin; never contacted. */
+export const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
+
+export const MOCK_GRANT: PodGrant[] = [
+  { permission: "entity.post.read", workspaceId: "ws_mock_studio", workspaceName: "Studio" },
+  { permission: "entity.post.create", workspaceId: "ws_mock_studio", workspaceName: "Studio" },
+];
+
+export const MOCK_USER: PodUser = { id: "user_mock_ada", name: "Ada Lovelace" };
+
+export type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
+
+export interface MockAuthServerOptions {
+  issuer?: string;
+  /** Issue rotating refresh tokens (PB3). Default true; false = a pod before PB3. */
+  refresh?: boolean;
+  /** Default 3600 (the pod's 1 h). */
+  accessTtlSec?: number;
+  /** Default 30 days. */
+  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. */
+  metadata?: Record<string, unknown>;
+  /** Hub writes: "proposed" (ask-first, the default for an app) or "applied". */
+  writeMode?: "proposed" | "applied";
+  /** Hub paths (after /api/hub) that answer one failure. */
+  failures?: Record<string, MockHubFailure>;
+  now?: () => number;
+}
+
+export interface MockAuthRequest {
+  method: string;
+  url: string;
+  /** Lower-cased header names. */
+  headers: Record<string, string>;
+  /** The form body of a /token or /revoke call. */
+  form: Record<string, string> | null;
+}
+
+export interface AuthorizeDecision {
+  /** The person said no. */
+  deny?: boolean;
+  /** Override `iss` on the answer (null = omit it): a mix-up attack. */
+  iss?: string | null;
+  /** Override `state` on the answer: a forged answer. */
+  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). */
+  consumeRefreshToken(token: string): void;
+  /** The next refresh redeem loses a concurrent race: invalid_grant, nothing revoked. */
+  loseNextRefreshRace(): void;
+  /** Refresh-token redeems that were reuses (each revoked a family). */
+  reuses: number;
+  /** The person revoked the app: every token stops working. */
+  revokeAll(): void;
+  /** Live (unrevoked) refresh tokens. */
+  liveRefreshTokens(): string[];
+  reset(): void;
+}
+
+interface CodeRow {
+  clientId: string;
+  redirectUri: string;
+  challenge: string;
+  resource: string | null;
+  scope: string[];
+}
+
+interface AccessRow {
+  expiresAt: number;
+  revoked: boolean;
+  family: string | null;
+  scope: string[];
+}
+
+interface RefreshRow {
+  clientId: string;
+  family: string;
+  idleUntil: number;
+  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 {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers },
+  });
+}
+
+function oauthError(error: string, description: string, status = 400): Response {
+  return json(status, { error, error_description: description });
+}
+
+export function createMockAuthServer(options: MockAuthServerOptions = {}): MockAuthServer {
+  const issuer = options.issuer ?? MOCK_AUTH_ISSUER;
+  const now = options.now ?? Date.now;
+  const refresh = options.refresh ?? true;
+  const accessTtl = options.accessTtlSec ?? 3600;
+  const refreshIdle = options.refreshIdleSec ?? 30 * 24 * 3600;
+  const grant = options.grant ?? MOCK_GRANT;
+  const user = options.user ?? MOCK_USER;
+  const codes = new Map<string, CodeRow>();
+  const access = new Map<string, AccessRow>();
+  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> = {
+      issuer,
+      authorization_endpoint: `${issuer}/authorize`,
+      token_endpoint: `${issuer}/token`,
+      registration_endpoint: `${issuer}/register`,
+      revocation_endpoint: `${issuer}/revoke`,
+      revocation_endpoint_auth_methods_supported: ["none"],
+      response_types_supported: ["code"],
+      grant_types_supported: refresh ? ["authorization_code", "refresh_token"] : ["authorization_code"],
+      code_challenge_methods_supported: ["S256"],
+      token_endpoint_auth_methods_supported: ["none"],
+      authorization_response_iss_parameter_supported: true,
+      client_id_metadata_document_supported: true,
+    };
+    for (const [k, v] of Object.entries(options.metadata ?? {})) {
+      if (v === undefined) delete base[k];
+      else base[k] = v;
+    }
+    return base;
+  };
+
+  let loseNextRace = false;
+  let reuses = 0;
+  const revokeFamily = (family: string) => {
+    for (const r of refreshTokens.values()) if (r.family === family) r.revoked = true;
+    for (const a of access.values()) if (a.family === family) a.revoked = true;
+  };
+
+  /** 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",
+      // 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 (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;
+      if (options.advertiseRefreshExpiry) body.refresh_token_expires_in = refreshIdle;
+    }
+    return body;
+  };
+
+  async function token(form: Record<string, string>): Promise<Response> {
+    if (form.grant_type === "authorization_code") {
+      const row = form.code ? codes.get(form.code) : undefined;
+      if (form.code) codes.delete(form.code); // claim first: a failed exchange burns the code
+      if (!row) return oauthError("invalid_grant", "Invalid, expired, or already-redeemed authorization code");
+      if (row.clientId !== form.client_id) return oauthError("invalid_grant", "client_id does not match the code");
+      if (row.redirectUri !== form.redirect_uri) return oauthError("invalid_grant", "redirect_uri mismatch");
+      if (!form.code_verifier || (await pkceChallenge(form.code_verifier)) !== row.challenge) {
+        return oauthError("invalid_grant", "PKCE verification failed");
+      }
+      if (form.resource !== undefined && row.resource && form.resource !== row.resource) {
+        return oauthError("invalid_target", "resource does not match the authorization request");
+      }
+      // The latest connect wins: a new code ends this client's older families.
+      for (const r of refreshTokens.values()) if (r.clientId === row.clientId) revokeFamily(r.family);
+      return json(200, tokenBody(row.scope, row.clientId, randomToken()));
+    }
+    if (form.grant_type === "refresh_token") {
+      if (!refresh) return oauthError("unsupported_grant_type", 'Only grant_type "authorization_code" is supported');
+      if (!form.refresh_token || !form.client_id) return oauthError("invalid_request", "refresh_token and client_id are required");
+      const row = refreshTokens.get(form.refresh_token);
+      if (!row || row.clientId !== form.client_id || row.revoked) {
+        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");
+      }
+      if (row.idleUntil <= now()) return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
+      if (loseNextRace) {
+        loseNextRace = false;
+        return oauthError("invalid_grant", "Invalid, expired, revoked or already-used refresh token");
+      }
+      row.used = true;
+      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, 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];
+    const row = bearer ? access.get(bearer) : undefined;
+    if (!row || row.revoked || row.expiresAt <= now()) return json(401, { error: "Unauthorized" });
+    switch (failure) {
+      case "rate_limited":
+        return json(429, { error: "Too many requests" }, { "Retry-After": "30" });
+      case "forbidden":
+        return json(403, { error: "Forbidden" });
+      case "door_unsupported":
+        return json(403, { error: "This door is not available to a space-scoped key", code: "GRANT_DOOR_UNSUPPORTED" });
+      case "server":
+        return json(500, { error: "Internal error" });
+      case "unavailable":
+        return json(503, { error: "Unavailable" });
+    }
+    // The grant fence (spec 17 §5): aggregate reads are refused to a scoped token.
+    if (path.startsWith("/knowledge/") || path === "/entities/retrieve" || path === "/memory/search") {
+      return json(403, { error: "This door is not available to a space-scoped key", code: "GRANT_DOOR_UNSUPPORTED" });
+    }
+    if (method === "GET" && path === "/users/me") return json(200, user);
+    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",
+          proposalId,
+          reviewUrl: `${issuer}/open/${proposalId}`,
+        });
+      }
+      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" });
+  }
+
+  const mockFetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const request = typeof input === "object" && "method" in input ? input : null;
+    const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+    const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+    const headers: Record<string, string> = {};
+    new Headers(init?.headers ?? request?.headers).forEach((value, name) => {
+      headers[name.toLowerCase()] = value;
+    });
+    const rawBody = typeof init?.body === "string" ? init.body : request ? await request.clone().text() : "";
+    const isForm = (headers["content-type"] ?? "").includes("application/x-www-form-urlencoded");
+    const form = isForm ? Object.fromEntries(new URLSearchParams(rawBody)) : null;
+    requests.push({ method, url: url.href, headers, form });
+
+    if (url.origin !== new URL(issuer).origin) throw new TypeError(`Failed to fetch: ${url.origin} is not the mock pod`);
+    const path = url.pathname;
+    if (method === "GET" && path === "/.well-known/oauth-authorization-server") return json(200, metadata());
+    if (method === "POST" && path === "/token") return token(form ?? {});
+    if (method === "POST" && path === "/revoke") {
+      const t = form?.token ?? "";
+      const r = refreshTokens.get(t);
+      if (r && form?.client_id && form.client_id !== r.clientId) {
+        return oauthError("unauthorized_client", "The token was not issued to this client");
+      }
+      if (r) revokeFamily(r.family);
+      const a = access.get(t);
+      if (a) a.revoked = true;
+      return new Response(null, { status: 200 });
+    }
+    const hubPath = /^\/api\/hub(\/.*)$/.exec(path)?.[1];
+    if (hubPath) {
+      let body: unknown = undefined;
+      try {
+        body = rawBody ? JSON.parse(rawBody) : undefined;
+      } catch {
+        body = rawBody;
+      }
+      const res = hub(method, hubPath, url.searchParams, headers, body);
+      if (res === "reject") throw new TypeError("Failed to fetch: mock pod unreachable");
+      return res;
+    }
+    return json(404, { error: "Not found" });
+  };
+
+  return {
+    issuer,
+    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}`);
+      const q = url.searchParams;
+      const redirectUri = q.get("redirect_uri");
+      const clientId = q.get("client_id");
+      // Phase 1 (shown, never redirected): no verified redirect yet.
+      if (!clientId || !redirectUri) throw new Error("Authorization request rejected: client_id and redirect_uri are required");
+      const answer = new URL(redirectUri);
+      const state = decision.state ?? q.get("state");
+      const finish = (fields: Record<string, string>) => {
+        for (const [k, v] of Object.entries(fields)) answer.searchParams.set(k, v);
+        if (state !== null) answer.searchParams.set("state", state);
+        const iss = decision.iss === undefined ? issuer : decision.iss;
+        if (iss !== null) answer.searchParams.set("iss", iss);
+        return answer.href;
+      };
+      if (q.get("response_type") !== "code") return finish({ error: "unsupported_response_type" });
+      if (q.get("code_challenge_method") !== "S256" || !q.get("code_challenge")) {
+        return finish({ error: "invalid_request", error_description: "PKCE S256 is required" });
+      }
+      const resource = q.get("resource");
+      if (resource !== null && resource !== `${issuer}/api/hub` && resource !== `${issuer}/mcp`) {
+        return finish({ error: "invalid_target" });
+      }
+      const scope = (q.get("scope") ?? "").split(/\s+/).filter(Boolean);
+      if (scope.length === 0) return finish({ error: "invalid_scope" });
+      if (decision.deny) return finish({ error: "access_denied" });
+      const code = randomToken();
+      codes.set(code, { clientId, redirectUri, challenge: q.get("code_challenge")!, resource, scope });
+      return finish({ code });
+    },
+    consumeRefreshToken(t) {
+      const row = refreshTokens.get(t);
+      if (row) row.used = true;
+    },
+    loseNextRefreshRace() {
+      loseNextRace = true;
+    },
+    get reuses() {
+      return reuses;
+    },
+    revokeAll() {
+      for (const row of access.values()) row.revoked = true;
+      for (const row of refreshTokens.values()) row.revoked = true;
+    },
+    liveRefreshTokens() {
+      return [...refreshTokens].filter(([, r]) => !r.used && !r.revoked).map(([t]) => t);
+    },
+    reset() {
+      requests.length = 0;
+      writes.length = 0;
+    },
+  };
+}

package/src/testing/cloud.ts

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

package/src/testing/index.ts

@@ -15,6 +15,9 @@
  *   tokens MOCK_TOKENS.form / .share / .site   the demo form, share and site
  *   tokens MOCK_FAILURE_TOKENS.*                one failure on every door
  *   anything else                               the uniform 404
+ *
+ * Pod-app sign-in (`@synap-core/sdk/connect`): `createMockAuthServer()`, see
+ * ./auth-server.ts; Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
  */
 import type {
   PublicCollectionPage,
@@ -28,6 +31,10 @@ import { MOCK_FORM, MOCK_SHARE, MOCK_SITE, type MockSite } from "./fixtures";
 
 export { MOCK_FORM, MOCK_SHARE, MOCK_SITE };
 export type { MockCollection, MockSite } from "./fixtures";
+// Pod-app sign-in: a mock authorization server + Hub REST doors.
+export * from "./auth-server";
+// Synap Cloud: a mock Control Plane pod chooser.
+export * from "./cloud";
 
 /** A placeholder origin; never contacted. */
 export const MOCK_POD_URL = "https://mock.synap.invalid";