@synap-core/sdk 1.2.0 → 1.3.0

package/src/connect/store.ts

@@ -0,0 +1,151 @@
+/**
+ * Where a PodConnection lives between requests. The default keeps it in the
+ * browser as a SEALED cookie (AES-GCM under the app secret, HttpOnly, Secure
+ * on https, SameSite=Lax, Path=/, `__Host-` prefix on https): the browser holds
+ * ciphertext it cannot read or forge, the pod token never reaches JS.
+ *
+ * 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 { ConnectError } from "./errors";
+import { seal, unseal, type AppSecret } from "./seal";
+import type { PodConnection, PodGrant } from "./types";
+
+export interface ConnectionStore {
+  /** The request's connection, or null (absent, tampered, foreign, expired). */
+  read(request: Request): Promise<PodConnection | null>;
+  /** Persist; returns the Set-Cookie header values to send. */
+  write(connection: PodConnection, request: Request): Promise<string[]>;
+  /** Forget; returns the Set-Cookie header values to send. */
+  clear(request: Request): Promise<string[]>;
+}
+
+export interface CookieNames {
+  session: string;
+  transaction: 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" };
+}
+
+/** Browsers cap a cookie near 4096 bytes; a big grant spans several. */
+const CHUNK_SIZE = 3800;
+const MAX_CHUNKS = 4;
+
+function chunkName(name: string, i: number): string {
+  return i === 0 ? name : `${name}.${i}`;
+}
+
+/** The sealed form: the grant grouped per space (it repeats the space otherwise). */
+interface StoredConnection extends Omit<PodConnection, "grant"> {
+  g: Array<[workspaceId: string, workspaceName: string, permissions: string[]]>;
+}
+
+function pack(c: PodConnection): StoredConnection {
+  const bySpace = new Map<string, [string, string, string[]]>();
+  for (const g of c.grant) {
+    const row = bySpace.get(g.workspaceId) ?? [g.workspaceId, g.workspaceName, []];
+    row[2].push(g.permission);
+    bySpace.set(g.workspaceId, row);
+  }
+  const { grant: _grant, ...rest } = c;
+  return { ...rest, g: [...bySpace.values()] };
+}
+
+function unpack(s: StoredConnection): PodConnection | null {
+  if (!s || typeof s.podUrl !== "string" || typeof s.accessToken !== "string" || !Array.isArray(s.g)) return null;
+  const { g, ...rest } = s;
+  const grant: PodGrant[] = g.flatMap(([workspaceId, workspaceName, permissions]) =>
+    permissions.map((permission) => ({ permission, workspaceId, workspaceName })),
+  );
+  return { ...rest, grant };
+}
+
+/** When the stored value stops being useful. */
+export function connectionExpiresAt(c: PodConnection): number {
+  return c.refreshToken && c.refreshExpiresAt !== undefined ? Math.max(c.refreshExpiresAt, c.accessExpiresAt) : c.accessExpiresAt;
+}
+
+export interface SealedCookieStoreOptions {
+  secret: AppSecret;
+  /** True on https (the default when the app URL is https). */
+  secure: boolean;
+  name?: string;
+  now?: () => number;
+}
+
+export function createSealedCookieStore(opts: SealedCookieStoreOptions): ConnectionStore {
+  const name = opts.name ?? cookieNames(opts.secure).session;
+  const now = opts.now ?? Date.now;
+
+  const presentChunks = (request: Request) => {
+    const cookies = parseCookies(request.headers.get("cookie"));
+    const names: string[] = [];
+    for (let i = 0; i < MAX_CHUNKS; i++) if (cookies.has(chunkName(name, i))) names.push(chunkName(name, i));
+    return { cookies, names };
+  };
+
+  return {
+    async read(request) {
+      const { cookies } = presentChunks(request);
+      let sealed = "";
+      for (let i = 0; i < MAX_CHUNKS; i++) {
+        const part = cookies.get(chunkName(name, i));
+        if (part === undefined) break;
+        sealed += part;
+      }
+      if (!sealed) return null;
+      const opened = await unseal<StoredConnection>(sealed, { secret: opts.secret, purpose: "synap-connect/session", now: now() });
+      return opened.ok ? unpack(opened.value) : null;
+    },
+
+    async write(connection, request) {
+      const expiresAt = connectionExpiresAt(connection);
+      const sealed = await seal(pack(connection), { secret: opts.secret, purpose: "synap-connect/session", expiresAt });
+      const parts: string[] = [];
+      for (let i = 0; i < sealed.length; i += CHUNK_SIZE) parts.push(sealed.slice(i, i + CHUNK_SIZE));
+      if (parts.length > MAX_CHUNKS) {
+        throw new ConnectError(
+          "misconfigured",
+          "The connection is too large for a cookie (a very wide grant); pass a server-side ConnectionStore",
+        );
+      }
+      const maxAgeSec = (expiresAt - now()) / 1000;
+      const out = parts.map((value, i) => serializeCookie(chunkName(name, i), value, { maxAgeSec, secure: opts.secure }));
+      // Drop chunks a previous, larger value left behind.
+      for (const stale of presentChunks(request).names.slice(parts.length)) {
+        out.push(serializeCookie(stale, "", { maxAgeSec: 0, secure: opts.secure }));
+      }
+      return out;
+    },
+
+    async clear(request) {
+      const { names } = presentChunks(request);
+      return (names.length > 0 ? names : [name]).map((n) => serializeCookie(n, "", { maxAgeSec: 0, secure: opts.secure }));
+    },
+  };
+}
+
+/**
+ * Apply Set-Cookie values to a request's Cookie header, so code that runs
+ * later IN THE SAME REQUEST (a server component after `proxy.ts`) reads the
+ * refreshed value. A `Max-Age=0` removes the cookie.
+ */
+export function applySetCookies(cookieHeader: string | null, setCookies: readonly string[]): string {
+  const cookies = parseCookies(cookieHeader);
+  for (const sc of setCookies) {
+    const [pair, ...attrs] = sc.split(";");
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    const name = pair.slice(0, eq).trim();
+    const removed = attrs.some((a) => /^\s*max-age\s*=\s*0\s*$/i.test(a));
+    if (removed) cookies.delete(name);
+    else cookies.set(name, pair.slice(eq + 1).trim());
+  }
+  return [...cookies].map(([k, v]) => `${k}=${v}`).join("; ");
+}

package/src/connect/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Wire and session shapes of pod-app sign-in.
+ *
+ * DRIFT RISK: hand-written from the pod's OAuth AS (synap-backend
+ * `routers/oauth/routes.ts` /token for a CIMD client, `protocol.ts`
+ * `buildAuthorizationServerMetadata`, spec 17 §6.6). The contract fixture
+ * `src/__tests__/connect.contract.test.ts` copies the token response; when the
+ * backend changes, update both.
+ */
+
+/** One permission the app asks for, with the sentence the consent screen shows. */
+export interface AppRequest {
+  /** Grant grammar, e.g. `entity.post.read`, `document.update`. No `*`. */
+  permission: string;
+  /** Why the app needs it (at most 200 characters). */
+  reason: string;
+}
+
+/** What the person approved: one row per permission per space. */
+export interface PodGrant {
+  permission: string;
+  workspaceId: string;
+  workspaceName: string;
+}
+
+export interface PodUser {
+  id: string;
+  name: string;
+}
+
+/** A pod's authorization server, as `discoverPod` validated it. */
+export interface PodIssuer {
+  /** The canonical issuer, which is also the pod's base URL. */
+  issuer: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  revocationEndpoint: string | null;
+  /** The AS advertises `grant_types_supported: [..., "refresh_token"]`. */
+  refreshSupported: boolean;
+}
+
+/**
+ * A live connection of this app to one person's pod. Server-only: it holds the
+ * bearer token. Serialisable, so a custom store can keep it anywhere.
+ */
+export interface PodConnection {
+  /** The pod's canonical issuer = its base URL (no trailing slash). */
+  podUrl: string;
+  /** The app's client_id (its CIMD URL) the tokens were issued to. */
+  clientId: string;
+  tokenEndpoint: string;
+  revocationEndpoint: string | null;
+  accessToken: string;
+  /** ms since epoch. */
+  accessExpiresAt: number;
+  /** Absent when the pod issued none (then the connection ends at `accessExpiresAt`). */
+  refreshToken?: string;
+  /** ms since epoch; the refresh token's idle life, renewed by each rotation. */
+  refreshExpiresAt?: number;
+  /** The approved permissions (the token response's `scope`). */
+  scope: string[];
+  grant: PodGrant[];
+  user: PodUser;
+  /** ms since epoch. */
+  connectedAt: number;
+}
+
+/** The CIMD document an app serves at its client_id URL (spec 17 §6.1). */
+export interface ClientMetadataDocument {
+  client_id: string;
+  client_name: string;
+  client_uri: string;
+  redirect_uris: string[];
+  grant_types: string[];
+  response_types: string[];
+  token_endpoint_auth_method: "none";
+  initiate_login_uri: string;
+  synap_requests: AppRequest[];
+  synap_templates?: string[];
+}

package/src/testing/auth-server.ts

@@ -0,0 +1,380 @@
+/**
+ * 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.
+ * `refresh: false` is a pod before PB3 (no refresh_token at all).
+ *
+ *   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.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;
+  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;
+}
+
+export interface MockAuthServer {
+  issuer: string;
+  fetch: typeof fetch;
+  requests: MockAuthRequest[];
+  /** Hub writes seen, in order. */
+  writes: Array<{ method: string; path: string; body: unknown }>;
+  /** 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;
+}
+
+interface RefreshRow {
+  clientId: string;
+  family: string;
+  idleUntil: number;
+  used: boolean;
+  revoked: boolean;
+  scope: 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 }> = [];
+  let proposalSeq = 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;
+  };
+
+  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 });
+    const body: Record<string, unknown> = {
+      access_token: accessToken,
+      token_type: "Bearer",
+      expires_in: accessTtl,
+      scope: scope.join(" "),
+      synap_grant: grant.filter((g) => scope.includes(g.permission)),
+      synap_user: user,
+    };
+    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) {
+        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;
+      return json(200, tokenBody(row.scope, row.clientId, row.family));
+    }
+    return oauthError("unsupported_grant_type", "Unsupported grant_type");
+  }
+
+  function hub(method: string, path: string, 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") return json(200, { entities: [], total: 0 });
+    if (method !== "GET") {
+      writes.push({ method, path, body });
+      if ((options.writeMode ?? "proposed") === "proposed") {
+        const proposalId = `prop_mock_${++proposalSeq}`;
+        return json(200, {
+          status: "proposed",
+          message: "Sent for review",
+          proposalId,
+          reviewUrl: `${issuer}/open/${proposalId}`,
+        });
+      }
+      return json(200, { status: "created", id: `ent_mock_${writes.length}` });
+    }
+    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, 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,
+    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/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.
  */
 import type {
   PublicCollectionPage,
@@ -28,6 +31,8 @@ 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";
 
 /** A placeholder origin; never contacted. */
 export const MOCK_POD_URL = "https://mock.synap.invalid";