@synap-core/sdk 1.1.0 → 1.3.0

package/src/connect/auth.ts

@@ -0,0 +1,405 @@
+/**
+ * `createPodAppAuth(config)`: pod-app sign-in as Web-standard route handlers
+ * (`Request → Response`, so Next route handlers, Hono, Remix, workers) plus
+ * the `proxy.ts` refresh helper. The route files stay two lines:
+ *
+ *   // app/api/synap/connect/route.ts
+ *   export const POST = synap.handlers.connect;
+ *
+ * Handlers:
+ *   GET  <metadata>    the app's client metadata document (its client_id URL)
+ *   POST <connect>     form { pod, next?, space? } → 303 to the pod's /authorize
+ *   GET  <callback>    the pod's answer → sealed session cookie → 303 to `next`
+ *   POST <disconnect>  revoke at the pod (best effort), clear the cookie → 303
+ *
+ * `connect` and `disconnect` change state, so they are POST and same-origin
+ * only (Origin, else Sec-Fetch-Site): a third-party page cannot start a
+ * sign-in into an attacker's pod for a visitor (login CSRF) or sign them out.
+ * Failures redirect with `?error=<ConnectErrorCode>` and nothing else.
+ */
+import { safeNextPath, canonicalPodUrl } from "./discovery";
+import { ConnectError, isConnectError } from "./errors";
+import { serializeCookie, parseCookies } from "./encoding";
+import { createPodClient, type PodClient, type PodClientOptions } from "./client";
+import { assertPermissions, handleCallback, refreshConnection, revokeConnection, startConnect, TRANSACTION_TTL_MS } from "./flow";
+import { assertServerRuntime } from "./guard";
+import { assertAppSecret, type AppSecret } from "./seal";
+import { applySetCookies, cookieNames, createSealedCookieStore, type ConnectionStore } from "./store";
+import type { AppRequest, ClientMetadataDocument, PodConnection } from "./types";
+
+export interface PodAppPaths {
+  /** The client metadata document; its absolute URL is the client_id. */
+  metadata: string;
+  connect: string;
+  callback: string;
+  disconnect: string;
+  /** The app's connect page (also the CIMD `initiate_login_uri`). */
+  connectPage: string;
+  /** Where a failed callback lands, with `?error=<code>`. */
+  resultPage: string;
+  /** Where a sign-in lands when it named no `next`. */
+  afterConnect: string;
+}
+
+export const DEFAULT_PATHS: PodAppPaths = {
+  metadata: "/.well-known/synap-client.json",
+  connect: "/api/synap/connect",
+  callback: "/api/synap/callback",
+  disconnect: "/api/synap/disconnect",
+  connectPage: "/connect",
+  resultPage: "/connect/result",
+  afterConnect: "/",
+};
+
+/** Refresh only inside the last 5 minutes of the access token's life. */
+export const REFRESH_WINDOW_MS = 5 * 60 * 1000;
+
+export interface PodAppAuthConfig {
+  /** The app's origin, e.g. https://studio.example.com (http only on localhost). */
+  appUrl: string;
+  /** Shown on the pod's consent screen (at most 100 characters). */
+  clientName: string;
+  /** What the app asks for, each with the reason the consent screen shows. */
+  requests: readonly AppRequest[];
+  /** Workspace-template slugs the consent may offer to create (`synap_templates`). */
+  templates?: readonly string[];
+  /** SERVER-ONLY secret, at least 32 characters (SYNAP_APP_SESSION_SECRET). Several to rotate. */
+  secret: AppSecret;
+  paths?: Partial<PodAppPaths>;
+  /** Defaults to the sealed session cookie. */
+  store?: ConnectionStore;
+  /** RFC 8707 resource asked for (default the Hub API). */
+  resource?: "api/hub" | "mcp" | null;
+  /** Accept pods on http://localhost (development against a local pod). */
+  allowInsecureLoopback?: boolean;
+  /** Developer log of every refused sign-in; messages never carry a token. Default: console.warn. */
+  onError?: (error: ConnectError, where: "connect" | "callback" | "disconnect" | "refresh") => void;
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+export type RefreshStatus =
+  /** No connection in this request. */
+  | "none"
+  /** Prefetch or static asset: nothing refreshed (the connection is read as is). */
+  | "skipped"
+  /** Valid beyond the refresh window, or no refresh token to use. */
+  | "fresh"
+  /** Rotated: send `setCookies`, forward `cookieHeader`. */
+  | "refreshed"
+  /** The refresh failed (a lost rotation race, the pod busy) but the access token still works: keep it, set nothing. */
+  | "kept"
+  /** The access token is spent and cannot be renewed: connect again. */
+  | "expired"
+  /** The pod refused the refresh token (access removed): connect again. */
+  | "revoked"
+  /** The pod could not be reached and the access token is spent: try later. */
+  | "unavailable";
+
+export interface RefreshOutcome {
+  status: RefreshStatus;
+  /** A usable connection, or null. */
+  connection: PodConnection | null;
+  /** Set-Cookie values to append to the response. */
+  setCookies: string[];
+  /** The request's Cookie header with the refreshed value, to forward to the render (null = unchanged). */
+  cookieHeader: string | null;
+  error?: ConnectError;
+}
+
+export interface PodAppAuth {
+  clientId: string;
+  redirectUri: string;
+  metadata: ClientMetadataDocument;
+  paths: PodAppPaths;
+  handlers: {
+    clientMetadata(request: Request): Promise<Response>;
+    connect(request: Request): Promise<Response>;
+    callback(request: Request): Promise<Response>;
+    disconnect(request: Request): Promise<Response>;
+  };
+  /**
+   * The stored connection (no refresh, no expiry check), or null. Takes the
+   * request, or just its Cookie header (a server component has no Request:
+   * pass `(await headers()).get("cookie")`).
+   */
+  readConnection(source: Request | string | null): Promise<PodConnection | null>;
+  /** For `proxy.ts` / a route handler: rotate near expiry, lost-race safe. */
+  refreshIfNeeded(request: Request): Promise<RefreshOutcome>;
+  /** A Hub REST client for the connection. */
+  client(connection: PodConnection, opts?: PodClientOptions): PodClient;
+}
+
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+const TEMPLATE_SLUG_RE = /^[a-z0-9][a-z0-9._/-]{0,99}$/;
+const MAX_METADATA_BYTES = 5 * 1024;
+
+function appOriginOf(appUrl: string): { origin: string; secure: boolean } {
+  let url: URL;
+  try {
+    url = new URL(appUrl);
+  } catch {
+    throw new ConnectError("misconfigured", "appUrl is not a URL");
+  }
+  const secure = url.protocol === "https:";
+  if (!secure && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
+    throw new ConnectError("misconfigured", "appUrl must be https (http only on localhost)");
+  }
+  if (url.pathname !== "/" || url.search || url.hash || url.username || url.password) {
+    throw new ConnectError("misconfigured", "appUrl is an origin: no path, query, fragment or credentials");
+  }
+  return { origin: url.origin, secure };
+}
+
+function assertPath(name: string, path: string): void {
+  if (!path.startsWith("/") || path.startsWith("//") || /[?#\\]/.test(path)) {
+    throw new ConnectError("misconfigured", `paths.${name} must be an absolute path on the app`);
+  }
+}
+
+/** The CIMD document (spec 17 §6.1), validated the way the pod will validate it. */
+export function buildClientMetadata(opts: {
+  appUrl: string;
+  clientName: string;
+  requests: readonly AppRequest[];
+  templates?: readonly string[];
+  paths?: Partial<PodAppPaths>;
+}): ClientMetadataDocument {
+  const { origin } = appOriginOf(opts.appUrl);
+  const paths = { ...DEFAULT_PATHS, ...opts.paths };
+  for (const [name, path] of Object.entries(paths)) assertPath(name, path);
+  const clientName = opts.clientName.trim();
+  if (!clientName || clientName.length > 100) throw new ConnectError("misconfigured", "clientName must be 1-100 characters");
+  assertPermissions(opts.requests.map((r) => r.permission));
+  for (const r of opts.requests) {
+    if (r.permission.includes("*")) throw new ConnectError("misconfigured", "a permission cannot contain *");
+    if (typeof r.reason !== "string" || !r.reason.trim() || r.reason.length > 200) {
+      throw new ConnectError("misconfigured", `the reason for ${r.permission} must be 1-200 characters`);
+    }
+  }
+  const templates = [...new Set(opts.templates ?? [])];
+  if (templates.length > 8 || templates.some((t) => !TEMPLATE_SLUG_RE.test(t))) {
+    throw new ConnectError("misconfigured", "at most 8 template slugs (lowercase letters, digits, . _ / -)");
+  }
+  const doc: ClientMetadataDocument = {
+    client_id: `${origin}${paths.metadata}`,
+    client_name: clientName,
+    client_uri: origin,
+    redirect_uris: [`${origin}${paths.callback}`],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+    initiate_login_uri: `${origin}${paths.connectPage}`,
+    synap_requests: opts.requests.map((r) => ({ permission: r.permission, reason: r.reason.trim() })),
+    ...(templates.length > 0 ? { synap_templates: templates } : {}),
+  };
+  if (new TextEncoder().encode(JSON.stringify(doc)).length > MAX_METADATA_BYTES) {
+    throw new ConnectError("misconfigured", "the client metadata document exceeds the pod's 5 KB limit");
+  }
+  return doc;
+}
+
+function redirect(location: string, setCookies: readonly string[] = []): Response {
+  const headers = new Headers({ Location: location, "Cache-Control": "no-store" });
+  for (const c of setCookies) headers.append("Set-Cookie", c);
+  return new Response(null, { status: 303, headers });
+}
+
+function withQuery(origin: string, path: string, params: Record<string, string | null | undefined>): string {
+  const url = new URL(path, origin);
+  for (const [k, v] of Object.entries(params)) if (v) url.searchParams.set(k, v);
+  return url.href;
+}
+
+/** A state-changing request must come from the app's own pages. */
+function sameOrigin(request: Request, origin: string): boolean {
+  const from = request.headers.get("origin");
+  if (from !== null) return from === origin;
+  return request.headers.get("sec-fetch-site") === "same-origin";
+}
+
+function formField(form: FormData | null, name: string): string | null {
+  const v = form?.get(name);
+  return typeof v === "string" ? v : null;
+}
+
+async function readForm(request: Request): Promise<FormData | null> {
+  try {
+    return await request.formData();
+  } catch {
+    return null;
+  }
+}
+
+function isPrefetchOrAsset(request: Request): boolean {
+  const h = request.headers;
+  if (h.get("next-router-prefetch") || h.get("x-middleware-prefetch")) return true;
+  if (/prefetch/i.test(h.get("purpose") ?? "") || /prefetch/i.test(h.get("sec-purpose") ?? "")) return true;
+  const path = new URL(request.url).pathname;
+  return path.startsWith("/_next/") || /\.[A-Za-z0-9]{1,8}$/.test(path);
+}
+
+export function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth {
+  assertServerRuntime();
+  assertAppSecret(config.secret);
+  const { origin, secure } = appOriginOf(config.appUrl);
+  const paths: PodAppPaths = { ...DEFAULT_PATHS, ...config.paths };
+  const metadata = buildClientMetadata({ ...config, paths });
+  const clientId = metadata.client_id;
+  const redirectUri = metadata.redirect_uris[0];
+  const permissions = config.requests.map((r) => r.permission);
+  const names = cookieNames(secure);
+  const now = config.now ?? Date.now;
+  const store = config.store ?? createSealedCookieStore({ secret: config.secret, secure, now });
+  const flow = { fetch: config.fetch, now: config.now };
+  const report =
+    config.onError ??
+    ((err: ConnectError, where: string) => {
+      console.warn(`[synap/connect] ${where}: ${err.code}: ${err.message}`);
+    });
+  const fail = (err: unknown, where: "connect" | "callback" | "disconnect" | "refresh"): ConnectError => {
+    const e = isConnectError(err) ? err : new ConnectError("server_error", err instanceof Error ? err.message : "Unexpected failure");
+    report(e, where);
+    return e;
+  };
+  const clearTx = serializeCookie(names.transaction, "", { maxAgeSec: 0, secure });
+
+  async function clientMetadata(): Promise<Response> {
+    return new Response(JSON.stringify(metadata), {
+      status: 200,
+      headers: { "Content-Type": "application/json", "Cache-Control": "public, max-age=300" },
+    });
+  }
+
+  async function connect(request: Request): Promise<Response> {
+    if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "POST" } });
+    if (!sameOrigin(request, origin)) return new Response("Forbidden", { status: 403 });
+    const form = await readForm(request);
+    const pod = formField(form, "pod")?.slice(0, 512) ?? "";
+    const next = safeNextPath(formField(form, "next"), origin) ?? paths.afterConnect;
+    const space = formField(form, "space");
+    try {
+      // A returning person already connected to this pod goes straight on.
+      const existing = await store.read(request);
+      if (existing && existing.accessExpiresAt > now() && existing.podUrl === canonicalPodUrl(pod, config)) {
+        return redirect(new URL(next, origin).href);
+      }
+      const started = await startConnect({
+        ...flow,
+        pod,
+        clientId,
+        redirectUri,
+        permissions,
+        secret: config.secret,
+        resource: config.resource,
+        spaceHint: space && /^[A-Za-z0-9_-]{1,64}$/.test(space) ? space : null,
+        next,
+        allowInsecureLoopback: config.allowInsecureLoopback,
+      });
+      return redirect(started.authorizeUrl, [
+        serializeCookie(names.transaction, started.transaction, { maxAgeSec: TRANSACTION_TTL_MS / 1000, secure }),
+      ]);
+    } catch (err) {
+      const e = fail(err, "connect");
+      return redirect(withQuery(origin, paths.connectPage, { error: e.code, pod }));
+    }
+  }
+
+  async function callback(request: Request): Promise<Response> {
+    if (request.method !== "GET") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "GET" } });
+    const transaction = parseCookies(request.headers.get("cookie")).get(names.transaction) ?? null;
+    try {
+      const { connection, next } = await handleCallback({
+        ...flow,
+        callbackUrl: request.url,
+        transaction,
+        clientId,
+        redirectUri,
+        secret: config.secret,
+      });
+      const cookies = await store.write(connection, request);
+      return redirect(new URL(next ?? paths.afterConnect, origin).href, [clearTx, ...cookies]);
+    } catch (err) {
+      const e = fail(err, "callback");
+      return redirect(withQuery(origin, paths.resultPage, { error: e.code }), [clearTx]);
+    }
+  }
+
+  async function disconnect(request: Request): Promise<Response> {
+    if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "POST" } });
+    if (!sameOrigin(request, origin)) return new Response("Forbidden", { status: 403 });
+    const next = safeNextPath(formField(await readForm(request), "next"), origin) ?? paths.connectPage;
+    const connection = await store.read(request);
+    if (connection) {
+      const { revoked } = await revokeConnection(connection, flow);
+      if (!revoked) report(new ConnectError("pod_unreachable", "The pod did not confirm the revocation; the cookie is cleared anyway"), "disconnect");
+    }
+    return redirect(new URL(next, origin).href, await store.clear(request));
+  }
+
+  async function refreshIfNeeded(request: Request): Promise<RefreshOutcome> {
+    const connection = await store.read(request);
+    const unchanged = (status: RefreshStatus, conn: PodConnection | null, error?: ConnectError): RefreshOutcome => ({
+      status,
+      connection: conn,
+      setCookies: [],
+      cookieHeader: null,
+      ...(error ? { error } : {}),
+    });
+    if (!connection) return unchanged("none", null);
+    if (isPrefetchOrAsset(request)) return unchanged("skipped", connection);
+    const t = now();
+    const accessLives = connection.accessExpiresAt > t;
+    if (connection.accessExpiresAt - t > REFRESH_WINDOW_MS) return unchanged("fresh", connection);
+    if (!connection.refreshToken) {
+      // The pod issued none (before PB3): the connection ends with its access token.
+      return accessLives ? unchanged("fresh", connection) : unchanged("expired", null, new ConnectError("expired", "No refresh token; connect again"));
+    }
+    let next: PodConnection;
+    try {
+      next = await refreshConnection(connection, flow);
+    } catch (err) {
+      const e = fail(err, "refresh");
+      // LOST-RACE SAFE: another instance may have redeemed the token at the
+      // same moment; the pod refuses the concurrent loser without a family
+      // revoke (PB3), and the access token we hold is still good. Keep it and
+      // set NOTHING, so the winner's cookie stands. (Within one process the
+      // race never reaches the pod: `refreshConnection` is single-flight.)
+      // Never clear the cookie here either: a clear racing the winner's
+      // Set-Cookie would sign the person out.
+      if (accessLives) return unchanged("kept", connection, e);
+      if (e.code === "revoked" || e.code === "expired") return unchanged(e.code, null, e);
+      return unchanged("unavailable", null, e);
+    }
+    // PERSIST BEFORE USE: the old refresh token is spent now; only a stored
+    // successor keeps the connection. If it cannot be stored, the new tokens
+    // are not handed out, and the stored (spent) one is cleared so no later
+    // request replays it (a replay revokes the family and the live key).
+    let setCookies: string[];
+    try {
+      setCookies = await store.write(next, request);
+    } catch (err) {
+      const e = fail(err, "refresh");
+      const cleared = await store.clear(request).catch(() => [] as string[]);
+      return { status: "expired", connection: null, setCookies: cleared, cookieHeader: null, error: e };
+    }
+    return {
+      status: "refreshed",
+      connection: next,
+      setCookies,
+      cookieHeader: applySetCookies(request.headers.get("cookie"), setCookies),
+    };
+  }
+
+  return {
+    clientId,
+    redirectUri,
+    metadata,
+    paths,
+    handlers: { clientMetadata, connect, callback, disconnect },
+    readConnection: (source) =>
+      store.read(source instanceof Request ? source : new Request(origin, { headers: source ? { cookie: source } : {} })),
+    refreshIfNeeded,
+    client: (connection, opts) => createPodClient(connection, { fetch: config.fetch, now: config.now, ...opts }),
+  };
+}

package/src/connect/browser.ts

@@ -0,0 +1,10 @@
+/**
+ * What a BROWSER bundle gets for `@synap-core/sdk/connect` (the `browser`
+ * export condition): no exports, and a throw on load. See ./guard.ts.
+ */
+throw new Error(
+  "@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. " +
+    "Import it from route handlers, proxy.ts or server code, never from a client component.",
+);
+
+export {};

package/src/connect/client.ts

@@ -0,0 +1,193 @@
+/**
+ * A server-side Hub REST client for one PodConnection: `<pod>/api/hub/*` with
+ * the connection's Bearer token. Results, not throws: `{ ok: true, … }` or
+ * `{ ok: false, error }` with a typed `code`.
+ *
+ *  - `expired`: the access token is past its expiry here; nothing was sent
+ *    (refresh in `proxy.ts` / a route handler, or connect again);
+ *  - `unauthorized`: the pod refused the token (revoked, or expired there);
+ *  - `forbidden`: not granted; `door_unsupported`: a door a space-scoped app
+ *    token can never use (403 GRANT_DOOR_UNSUPPORTED, spec 17 §5);
+ *  - `rate_limited` with `retryAfterSec`; `pod_unreachable` (network, 502-504).
+ *
+ * Writes are governed: `proposed` is SUCCESS (queued for the person's review,
+ * never retry it), with `reviewUrl` on the pod.
+ *
+ * The token goes to the pod's own origin only: paths are pod-relative, no
+ * redirect is followed.
+ */
+import { retryAfterSeconds } from "./errors";
+import type { PodConnection, PodGrant } from "./types";
+
+export type PodErrorCode =
+  | "expired"
+  | "unauthorized"
+  | "forbidden"
+  | "door_unsupported"
+  | "not_found"
+  | "invalid"
+  | "conflict"
+  | "rate_limited"
+  | "pod_unreachable"
+  | "server";
+
+export interface PodError {
+  code: PodErrorCode;
+  /** The HTTP status, or null when nothing was answered. */
+  status: number | null;
+  retryAfterSec?: number;
+  /** The pod's own error text, for logs only. */
+  detail?: string;
+}
+
+export type PodResult<T> = { ok: true; data: T } | { ok: false; error: PodError };
+
+export type PodWriteResult<T> =
+  | { ok: true; status: "applied"; data: T }
+  | { ok: true; status: "proposed"; proposalId: string | null; reviewUrl: string; data: T }
+  | { ok: false; error: PodError };
+
+export type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+
+export interface PodClientOptions {
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+export interface PodClient {
+  podUrl: string;
+  user: PodConnection["user"];
+  grant: PodGrant[];
+  /** Whether the connection was granted `permission` (in `workspaceId` when given). */
+  can(permission: string, workspaceId?: string): boolean;
+  get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<PodResult<T>>;
+  post<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+  patch<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+  put<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+  delete<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
+}
+
+/** Whether `connection` was granted `permission` (in `workspaceId` when given). Exact match: grants carry no wildcard. */
+export function can(connection: Pick<PodConnection, "grant">, permission: string, workspaceId?: string): boolean {
+  return connection.grant.some((g) => g.permission === permission && (workspaceId === undefined || g.workspaceId === workspaceId));
+}
+
+const SAFE_PATH = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/]*$/;
+
+function hubUrl(podUrl: string, path: string, query?: Record<string, QueryValue>): URL {
+  if (!SAFE_PATH.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) {
+    throw new TypeError(`Not a Hub API path: ${path}`);
+  }
+  const url = new URL(`${podUrl}/api/hub${path}`);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value === undefined || value === null) continue;
+    for (const v of Array.isArray(value) ? value : [value]) url.searchParams.append(key, String(v));
+  }
+  return url;
+}
+
+function errorFor(status: number, body: unknown, retryAfter: string | null, now: number): PodError {
+  const obj = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
+  const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : undefined;
+  const base = { status, ...(detail !== undefined ? { detail } : {}) };
+  if (status === 401) return { code: "unauthorized", ...base };
+  if (status === 403) return { code: obj.code === "GRANT_DOOR_UNSUPPORTED" ? "door_unsupported" : "forbidden", ...base };
+  if (status === 404) return { code: "not_found", ...base };
+  if (status === 409) return { code: "conflict", ...base };
+  if (status === 400 || status === 422) return { code: "invalid", ...base };
+  if (status === 429) {
+    const retryAfterSec = retryAfterSeconds(retryAfter, now);
+    return { code: "rate_limited", ...base, ...(retryAfterSec !== undefined ? { retryAfterSec } : {}) };
+  }
+  if (status === 502 || status === 503 || status === 504) return { code: "pod_unreachable", ...base };
+  return { code: "server", ...base };
+}
+
+/**
+ * Where to review a proposal: the pod's answer, resolved against the pod and
+ * kept only on the pod's own origin; else the pod's deep link `/open/<id>`.
+ */
+export function reviewUrlFor(podUrl: string, reviewUrl: unknown, proposalId: string | null): string {
+  if (typeof reviewUrl === "string" && reviewUrl) {
+    try {
+      const url = new URL(reviewUrl, `${podUrl}/`);
+      if (url.origin === new URL(podUrl).origin) return url.href;
+    } catch {
+      // fall through to the deep link
+    }
+  }
+  return proposalId ? `${podUrl}/open/${encodeURIComponent(proposalId)}` : podUrl;
+}
+
+export function createPodClient(connection: PodConnection, opts: PodClientOptions = {}): PodClient {
+  const now = opts.now ?? Date.now;
+  const doFetch = () => opts.fetch ?? fetch;
+
+  async function request(method: string, path: string, body: unknown, query?: Record<string, QueryValue>): Promise<PodResult<unknown>> {
+    const url = hubUrl(connection.podUrl, path, query);
+    if (connection.accessExpiresAt <= now()) return { ok: false, error: { code: "expired", status: null } };
+    const headers: Record<string, string> = { Accept: "application/json", Authorization: `Bearer ${connection.accessToken}` };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    let res: Response;
+    try {
+      res = await doFetch()(url.href, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: "manual",
+      });
+    } catch {
+      return { ok: false, error: { code: "pod_unreachable", status: null } };
+    }
+    let data: unknown = null;
+    const text = await res.text().catch(() => "");
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = null;
+      }
+    }
+    if (res.status >= 200 && res.status < 300) return { ok: true, data };
+    return { ok: false, error: errorFor(res.status, data, res.headers.get("retry-after"), now()) };
+  }
+
+  async function write<T>(method: string, path: string, body: unknown): Promise<PodWriteResult<T>> {
+    const result = await request(method, path, body);
+    if (!result.ok) return result;
+    const obj = result.data && typeof result.data === "object" ? (result.data as Record<string, unknown>) : {};
+    const proposalId = typeof obj.proposalId === "string" && obj.proposalId ? obj.proposalId : null;
+    if (obj.status === "proposed" || (obj.status === "pending" && proposalId)) {
+      return {
+        ok: true,
+        status: "proposed",
+        proposalId,
+        reviewUrl: reviewUrlFor(connection.podUrl, obj.reviewUrl, proposalId),
+        data: result.data as T,
+      };
+    }
+    return { ok: true, status: "applied", data: result.data as T };
+  }
+
+  return {
+    podUrl: connection.podUrl,
+    user: connection.user,
+    grant: connection.grant,
+    can: (permission, workspaceId) => can(connection, permission, workspaceId),
+    get<T>(path: string, query?: Record<string, QueryValue>) {
+      return request("GET", path, undefined, query) as Promise<PodResult<T>>;
+    },
+    post<T>(path: string, body?: unknown) {
+      return write<T>("POST", path, body);
+    },
+    patch<T>(path: string, body?: unknown) {
+      return write<T>("PATCH", path, body);
+    },
+    put<T>(path: string, body?: unknown) {
+      return write<T>("PUT", path, body);
+    },
+    delete<T>(path: string, body?: unknown) {
+      return write<T>("DELETE", path, body);
+    },
+  };
+}