iterate 0.2.6 → 0.3.0

package/dist/next/app-session.mjs

@@ -0,0 +1,238 @@
+import { isLocalOrigin } from "./lib.mjs";
+import { OAuthScopes } from "./oauth-scopes.mjs";
+import { t as _usingCtx } from "../usingCtx-inzbY1Qz.mjs";
+import { authorizationCodeRequest } from "./oauth.mjs";
+import { DurableObject } from "cloudflare:workers";
+import { z } from "zod";
+import { newHttpBatchRpcSession } from "capnweb";
+import * as oauth from "oauth4webapi";
+//#region src/next/app-session.ts
+/** Each app binds this same class. Token exchange and logout use the issuer's
+* public protocol, so separately deployed apps need no platform bindings.
+* The input gate serializes refresh and logout across tabs. */
+var BrowserSession = class extends DurableObject {
+	begin(host, next) {
+		return this.#serial(async () => {
+			if (await this.ctx.storage.get("session")) throw new Error("Browser session already exists");
+			const origin = new URL(host.origin);
+			const local = isLocalOrigin(host.origin);
+			if (origin.protocol !== "https:" && !local) throw new Error("Browser login requires HTTPS");
+			let clientId = host.client?.id || `${host.origin}/.auth/client.json`;
+			if (local) {
+				const response = await fetch(`${host.issuer}/oauth2/register`, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({
+						client_name: host.client?.name || origin.host,
+						client_uri: host.origin,
+						logo_uri: host.client?.logoUri,
+						redirect_uris: [`${host.origin}/.auth/callback`],
+						token_endpoint_auth_method: "none",
+						grant_types: ["authorization_code", "refresh_token"],
+						response_types: ["code"]
+					}),
+					signal: AbortSignal.timeout(1e4)
+				});
+				if (!response.ok) throw new Error(`Local client registration failed (${response.status})`);
+				clientId = z.object({ client_id: z.string().min(1) }).parse(await response.json()).client_id;
+			}
+			const { url, state, verifier } = await authorizationCodeRequest({
+				issuer: host.issuer,
+				clientId,
+				redirectUri: `${host.origin}/.auth/callback`,
+				resources: [host.resource],
+				scopes: host.scopes
+			});
+			const data = {
+				...host,
+				next,
+				clientId,
+				phase: "pending",
+				state,
+				verifier,
+				until: Date.now() + 10 * 6e4
+			};
+			await this.ctx.storage.put("session", data);
+			await this.ctx.storage.setAlarm(data.until);
+			return url.href;
+		});
+	}
+	/** The issuer's redirect back to `/.auth/callback`, its query string. oauth4webapi validates it
+	*  (the state matches this browser's pending flow, the `iss` matches the issuer, no `error`), then
+	*  exchanges the code for tokens. */
+	complete(callbackQuery) {
+		return this.#serial(async () => {
+			const data = await this.ctx.storage.get("session");
+			if (!data || data.phase !== "pending" || data.until <= Date.now()) return { error: "This sign-in expired or does not match this browser. Start sign-in again." };
+			const as = {
+				issuer: data.issuer,
+				token_endpoint: `${data.issuer}/oauth2/token`,
+				authorization_response_iss_parameter_supported: true
+			};
+			const client = { client_id: data.clientId };
+			let callback;
+			try {
+				callback = oauth.validateAuthResponse(as, client, new URLSearchParams(callbackQuery), data.state);
+			} catch (error) {
+				if (error instanceof oauth.AuthorizationResponseError) {
+					await this.#clear();
+					return { error: "Authorization was declined." };
+				}
+				return { error: "This sign-in expired or does not match this browser. Start sign-in again." };
+			}
+			const started = Date.now();
+			let tokens;
+			try {
+				const response = await oauth.authorizationCodeGrantRequest(as, client, oauth.None(), callback, `${data.origin}/.auth/callback`, data.verifier, this.#tokenOptions(data));
+				tokens = await oauth.processAuthorizationCodeResponse(as, client, response);
+			} catch (error) {
+				await this.#endOnDeadGrant(error);
+				return { error: "Sign-in could not complete. Start sign-in again." };
+			}
+			await this.#activate(data, tokens, started);
+			return { next: data.next };
+		});
+	}
+	bearer() {
+		return this.#serial(() => this.#bearer());
+	}
+	/** THE ISSUER THIS SESSION IS BOUND TO and the resource its tokens are for — written once at
+	*  `begin`, never steered by a request: the app's `/api` proxy, its login probe and its logout read
+	*  them from here, so a browser connected to one issuer can only ever spend its credential there.
+	*  Null when no session was begun. */
+	async host() {
+		const data = await this.ctx.storage.get("session");
+		return data ? {
+			issuer: data.issuer,
+			resource: data.resource
+		} : null;
+	}
+	async scopes() {
+		const data = await this.ctx.storage.get("session");
+		return data?.phase === "active" ? data.scopes : [];
+	}
+	/** Public client metadata chosen by the app before consent; never a browser-supplied claim. */
+	async client() {
+		const data = await this.ctx.storage.get("session");
+		return data?.phase === "active" ? data.client : void 0;
+	}
+	/** A verified 401 means this local credential no longer grants access. */
+	discard() {
+		return this.#serial(() => this.#clear());
+	}
+	end() {
+		return this.#serial(async () => {
+			const token = await this.#bearer();
+			const data = await this.ctx.storage.get("session");
+			if (token && data) {
+				const probe = await fetch(new Request(data.resource, {
+					method: "POST",
+					headers: { Authorization: `Bearer ${token}` },
+					body: "",
+					signal: AbortSignal.timeout(1e4)
+				}));
+				await probe.body?.cancel();
+				if (probe.status !== 401) try {
+					var _usingCtx$1 = _usingCtx();
+					if (!probe.ok) throw new Error(`Sign-out could not reach Iterate (${probe.status}). Try again.`);
+					const api = _usingCtx$1.u(newHttpBatchRpcSession(new Request(data.resource, {
+						headers: { Authorization: `Bearer ${token}` },
+						signal: AbortSignal.timeout(1e4)
+					})));
+					await _usingCtx$1.u(api.authenticate({ type: "from-server-cookie" })).logout();
+				} catch (_) {
+					_usingCtx$1.e = _;
+				} finally {
+					_usingCtx$1.d();
+				}
+			}
+			await this.#clear();
+		});
+	}
+	async alarm() {
+		await this.#clear();
+	}
+	async #bearer() {
+		const data = await this.ctx.storage.get("session");
+		if (!data || data.phase !== "active") return null;
+		if (data.until <= Date.now()) {
+			await this.#clear();
+			return null;
+		}
+		if (data.expiresAt > Date.now() + 3e4) return data.accessToken;
+		const as = {
+			issuer: data.issuer,
+			token_endpoint: `${data.issuer}/oauth2/token`
+		};
+		const client = { client_id: data.clientId };
+		const started = Date.now();
+		let tokens;
+		try {
+			const response = await oauth.refreshTokenGrantRequest(as, client, oauth.None(), data.refreshToken, this.#tokenOptions(data));
+			tokens = await oauth.processRefreshTokenResponse(as, client, response);
+		} catch (error) {
+			await this.#endOnDeadGrant(error);
+			return null;
+		}
+		return (await this.#activate(data, tokens, started)).accessToken;
+	}
+	/** The token request's shared options: the audience (RFC 8707 resource), a bounded timeout, and —
+	*  only for a LOCAL APP (`begin` already admits http there) — oauth4webapi's opt-out of its
+	*  HTTPS-only default. Keyed on the app's origin, never the issuer's: an issuer a person typed can
+	*  not talk a deployed app into sending its codes in the clear. */
+	#tokenOptions(data) {
+		const options = {
+			additionalParameters: { resource: data.resource },
+			signal: AbortSignal.timeout(1e4)
+		};
+		if (isLocalOrigin(data.origin)) options[oauth.allowInsecureRequests] = true;
+		return options;
+	}
+	/** Write the active session from a token response. A refresh reuses the prior refresh token when
+	*  the issuer does not rotate it. */
+	async #activate(data, tokens, started) {
+		const refreshToken = tokens.refresh_token || (data.phase === "active" ? data.refreshToken : void 0);
+		if (!refreshToken) throw new Error("Iterate returned no refresh token.");
+		const { origin, issuer, resource, clientId, next } = data;
+		const stored = {
+			origin,
+			issuer,
+			resource,
+			clientId,
+			client: data.client,
+			next,
+			phase: "active",
+			scopes: tokens.scope ? OAuthScopes.parse(tokens.scope.split(" ").filter(Boolean)) : data.scopes,
+			accessToken: tokens.access_token,
+			refreshToken,
+			expiresAt: started + (tokens.expires_in ?? 0) * 1e3,
+			until: data.phase === "pending" ? started + 720 * 36e5 : data.until
+		};
+		await this.ctx.storage.put("session", stored);
+		await this.ctx.storage.setAlarm(stored.until);
+		return stored;
+	}
+	/** A dead code or refresh token (`invalid_grant`) ends the session; other failures are transient. */
+	async #endOnDeadGrant(error) {
+		if (error instanceof oauth.ResponseBodyError && error.error === "invalid_grant") {
+			await this.#clear();
+			return;
+		}
+		throw error instanceof oauth.ResponseBodyError ? /* @__PURE__ */ new Error(`Iterate token exchange failed (${error.status}). Try again.`) : error;
+	}
+	/** An operation failure must not reset the DO or fail other tabs' requests. */
+	#serial(work) {
+		return this.ctx.blockConcurrencyWhile(() => work().then((value) => ({ value }), (error) => ({ error }))).then((result) => {
+			if ("error" in result) throw result.error;
+			return result.value;
+		});
+	}
+	async #clear() {
+		await this.ctx.storage.deleteAll();
+		await this.ctx.storage.deleteAlarm();
+	}
+};
+//#endregion
+export { BrowserSession };
+
+//# sourceMappingURL=app-session.mjs.map

package/dist/next/app-session.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-session.mjs","names":["#serial","#clear","#tokenOptions","#endOnDeadGrant","#activate","#bearer"],"sources":["../../src/next/app-session.ts"],"sourcesContent":["import { DurableObject } from \"cloudflare:workers\";\n// eslint-disable-next-line iterate/no-capnweb-http-batch -- One bounded logout request, no live capabilities.\nimport { newHttpBatchRpcSession } from \"capnweb\";\nimport * as oauth from \"oauth4webapi\";\nimport { z } from \"zod\";\nimport { authorizationCodeRequest } from \"./client/oauth.ts\";\nimport { OAuthScopes } from \"./oauth-scopes.ts\";\nimport { isLocalOrigin } from \"./lib.ts\";\nimport type { IterateApi } from \"./api.ts\";\n\nexport type BrowserHost = {\n  origin: string;\n  issuer: string;\n  resource: string;\n  scopes: string[];\n  client?: { id?: string; name: string; logoUri: string };\n};\ntype Base = BrowserHost & { clientId: string; next: string; until: number };\ntype Pending = Base & { phase: \"pending\"; state: string; verifier: string };\ntype Active = Base & {\n  phase: \"active\";\n  accessToken: string;\n  refreshToken: string;\n  expiresAt: number;\n};\ntype StoredSession = Pending | Active;\n\n/** Each app binds this same class. Token exchange and logout use the issuer's\n * public protocol, so separately deployed apps need no platform bindings.\n * The input gate serializes refresh and logout across tabs. */\nexport class BrowserSession extends DurableObject {\n  begin(host: BrowserHost, next: string) {\n    return this.#serial(async () => {\n      if (await this.ctx.storage.get(\"session\")) throw new Error(\"Browser session already exists\");\n      const origin = new URL(host.origin);\n      const local = isLocalOrigin(host.origin);\n      if (origin.protocol !== \"https:\" && !local) throw new Error(\"Browser login requires HTTPS\");\n      let clientId = host.client?.id || `${host.origin}/.auth/client.json`;\n      if (local) {\n        const response = await fetch(`${host.issuer}/oauth2/register`, {\n          method: \"POST\",\n          headers: { \"content-type\": \"application/json\" },\n          body: JSON.stringify({\n            client_name: host.client?.name || origin.host,\n            client_uri: host.origin,\n            logo_uri: host.client?.logoUri,\n            redirect_uris: [`${host.origin}/.auth/callback`],\n            token_endpoint_auth_method: \"none\",\n            grant_types: [\"authorization_code\", \"refresh_token\"],\n            response_types: [\"code\"],\n          }),\n          signal: AbortSignal.timeout(10_000),\n        });\n        if (!response.ok) throw new Error(`Local client registration failed (${response.status})`);\n        clientId = z\n          .object({ client_id: z.string().min(1) })\n          .parse(await response.json()).client_id;\n      }\n      const { url, state, verifier } = await authorizationCodeRequest({\n        issuer: host.issuer,\n        clientId,\n        redirectUri: `${host.origin}/.auth/callback`,\n        resources: [host.resource],\n        scopes: host.scopes,\n      });\n      const data: Pending = {\n        ...host,\n        next,\n        clientId,\n        phase: \"pending\",\n        state,\n        verifier,\n        until: Date.now() + 10 * 60_000,\n      };\n      await this.ctx.storage.put(\"session\", data);\n      await this.ctx.storage.setAlarm(data.until);\n      return url.href;\n    });\n  }\n\n  /** The issuer's redirect back to `/.auth/callback`, its query string. oauth4webapi validates it\n   *  (the state matches this browser's pending flow, the `iss` matches the issuer, no `error`), then\n   *  exchanges the code for tokens. */\n  complete(callbackQuery: string) {\n    return this.#serial(async () => {\n      const data = await this.ctx.storage.get<StoredSession>(\"session\");\n      if (!data || data.phase !== \"pending\" || data.until <= Date.now())\n        return {\n          error: \"This sign-in expired or does not match this browser. Start sign-in again.\",\n        };\n      const as: oauth.AuthorizationServer = {\n        issuer: data.issuer,\n        token_endpoint: `${data.issuer}/oauth2/token`,\n        authorization_response_iss_parameter_supported: true,\n      };\n      const client: oauth.Client = { client_id: data.clientId };\n      let callback: URLSearchParams;\n      try {\n        callback = oauth.validateAuthResponse(\n          as,\n          client,\n          new URLSearchParams(callbackQuery),\n          data.state,\n        );\n      } catch (error) {\n        // A provider `error=` (the person declined) ends the flow; a state/iss mismatch leaves the\n        // pending flow to be retried from a genuine browser.\n        if (error instanceof oauth.AuthorizationResponseError) {\n          await this.#clear();\n          return { error: \"Authorization was declined.\" };\n        }\n        return {\n          error: \"This sign-in expired or does not match this browser. Start sign-in again.\",\n        };\n      }\n      const started = Date.now();\n      let tokens: oauth.TokenEndpointResponse;\n      try {\n        const response = await oauth.authorizationCodeGrantRequest(\n          as,\n          client,\n          oauth.None(),\n          callback,\n          `${data.origin}/.auth/callback`,\n          data.verifier,\n          this.#tokenOptions(data),\n        );\n        tokens = await oauth.processAuthorizationCodeResponse(as, client, response);\n      } catch (error) {\n        await this.#endOnDeadGrant(error);\n        return { error: \"Sign-in could not complete. Start sign-in again.\" };\n      }\n      await this.#activate(data, tokens, started);\n      return { next: data.next };\n    });\n  }\n\n  bearer() {\n    return this.#serial(() => this.#bearer());\n  }\n  /** THE ISSUER THIS SESSION IS BOUND TO and the resource its tokens are for — written once at\n   *  `begin`, never steered by a request: the app's `/api` proxy, its login probe and its logout read\n   *  them from here, so a browser connected to one issuer can only ever spend its credential there.\n   *  Null when no session was begun. */\n  async host(): Promise<{ issuer: string; resource: string } | null> {\n    const data = await this.ctx.storage.get<StoredSession>(\"session\");\n    return data ? { issuer: data.issuer, resource: data.resource } : null;\n  }\n  async scopes() {\n    const data = await this.ctx.storage.get<StoredSession>(\"session\");\n    return data?.phase === \"active\" ? data.scopes : [];\n  }\n  /** Public client metadata chosen by the app before consent; never a browser-supplied claim. */\n  async client() {\n    const data = await this.ctx.storage.get<StoredSession>(\"session\");\n    return data?.phase === \"active\" ? data.client : undefined;\n  }\n  /** A verified 401 means this local credential no longer grants access. */\n  discard() {\n    return this.#serial(() => this.#clear());\n  }\n\n  end() {\n    return this.#serial(async () => {\n      const token = await this.#bearer();\n      const data = await this.ctx.storage.get<StoredSession>(\"session\");\n      if (token && data) {\n        // Probe classifies a revoked/expired credential without interpreting RPC error text.\n        const probe = await fetch(\n          new Request(data.resource, {\n            method: \"POST\",\n            headers: { Authorization: `Bearer ${token}` },\n            body: \"\",\n            signal: AbortSignal.timeout(10_000),\n          }),\n        );\n        await probe.body?.cancel();\n        if (probe.status !== 401) {\n          if (!probe.ok)\n            throw new Error(`Sign-out could not reach Iterate (${probe.status}). Try again.`);\n          // eslint-disable-next-line iterate/no-capnweb-http-batch -- A bounded logout command returns no live capabilities.\n          using api = newHttpBatchRpcSession<IterateApi>(\n            new Request(data.resource, {\n              headers: { Authorization: `Bearer ${token}` },\n              signal: AbortSignal.timeout(10_000),\n            }),\n          );\n          // `authenticate(...)` returns a SessionRpcTarget STUB — its own RPC result to dispose (the\n          // capnweb README's `using authedApi = api.authenticate(...)`); disposing only `api` leaves\n          // it dangling and workerd warns the result was never disposed.\n          using session = api.authenticate({ type: \"from-server-cookie\" });\n          await session.logout();\n        }\n      }\n      // Network failures preserve the session and are shown to the caller.\n      // Successful logout has written the issuer's durable revocation marker.\n      await this.#clear();\n    });\n  }\n\n  async alarm() {\n    // Pending flows expire in ten minutes; active grants have the same absolute\n    // thirty-day lifetime at the issuer. No refresh token survives this bound.\n    await this.#clear();\n  }\n  async #bearer() {\n    const data = await this.ctx.storage.get<StoredSession>(\"session\");\n    if (!data || data.phase !== \"active\") return null;\n    if (data.until <= Date.now()) {\n      await this.#clear();\n      return null;\n    }\n    if (data.expiresAt > Date.now() + 30_000) return data.accessToken;\n    const as: oauth.AuthorizationServer = {\n      issuer: data.issuer,\n      token_endpoint: `${data.issuer}/oauth2/token`,\n    };\n    const client: oauth.Client = { client_id: data.clientId };\n    const started = Date.now();\n    let tokens: oauth.TokenEndpointResponse;\n    try {\n      const response = await oauth.refreshTokenGrantRequest(\n        as,\n        client,\n        oauth.None(),\n        data.refreshToken,\n        this.#tokenOptions(data),\n      );\n      tokens = await oauth.processRefreshTokenResponse(as, client, response);\n    } catch (error) {\n      await this.#endOnDeadGrant(error);\n      return null;\n    }\n    return (await this.#activate(data, tokens, started)).accessToken;\n  }\n\n  /** The token request's shared options: the audience (RFC 8707 resource), a bounded timeout, and —\n   *  only for a LOCAL APP (`begin` already admits http there) — oauth4webapi's opt-out of its\n   *  HTTPS-only default. Keyed on the app's origin, never the issuer's: an issuer a person typed can\n   *  not talk a deployed app into sending its codes in the clear. */\n  #tokenOptions(data: StoredSession): oauth.TokenEndpointRequestOptions {\n    const options: oauth.TokenEndpointRequestOptions = {\n      additionalParameters: { resource: data.resource },\n      signal: AbortSignal.timeout(10_000),\n    };\n    if (isLocalOrigin(data.origin)) options[oauth.allowInsecureRequests] = true;\n    return options;\n  }\n\n  /** Write the active session from a token response. A refresh reuses the prior refresh token when\n   *  the issuer does not rotate it. */\n  async #activate(\n    data: StoredSession,\n    tokens: oauth.TokenEndpointResponse,\n    started: number,\n  ): Promise<Active> {\n    const refreshToken =\n      tokens.refresh_token || (data.phase === \"active\" ? data.refreshToken : undefined);\n    if (!refreshToken) throw new Error(\"Iterate returned no refresh token.\");\n    const { origin, issuer, resource, clientId, next } = data;\n    const stored: Active = {\n      origin,\n      issuer,\n      resource,\n      clientId,\n      client: data.client,\n      next,\n      phase: \"active\",\n      // An omitted (or empty) `scope` means unchanged (RFC 6749 §5.1) — keep what the grant already\n      // holds rather than silently narrow to `iterate`.\n      scopes: tokens.scope\n        ? OAuthScopes.parse(tokens.scope.split(\" \").filter(Boolean))\n        : data.scopes,\n      accessToken: tokens.access_token,\n      refreshToken,\n      expiresAt: started + (tokens.expires_in ?? 0) * 1000,\n      until: data.phase === \"pending\" ? started + 30 * 24 * 3600_000 : data.until,\n    };\n    await this.ctx.storage.put(\"session\", stored);\n    await this.ctx.storage.setAlarm(stored.until);\n    return stored;\n  }\n\n  /** A dead code or refresh token (`invalid_grant`) ends the session; other failures are transient. */\n  async #endOnDeadGrant(error: unknown): Promise<void> {\n    if (error instanceof oauth.ResponseBodyError && error.error === \"invalid_grant\") {\n      await this.#clear();\n      return;\n    }\n    throw error instanceof oauth.ResponseBodyError\n      ? new Error(`Iterate token exchange failed (${error.status}). Try again.`)\n      : error;\n  }\n  /** An operation failure must not reset the DO or fail other tabs' requests. */\n  #serial<T>(work: () => Promise<T>): Promise<T> {\n    return this.ctx\n      .blockConcurrencyWhile(() =>\n        work().then(\n          (value) => ({ value }),\n          (error: unknown) => ({ error }),\n        ),\n      )\n      .then((result) => {\n        if (\"error\" in result) throw result.error;\n        return result.value;\n      });\n  }\n\n  async #clear() {\n    await this.ctx.storage.deleteAll();\n    await this.ctx.storage.deleteAlarm();\n  }\n}\n"],"mappings":"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"}

package/dist/next/app.d.ts

@@ -0,0 +1,29 @@
+import { type RpcStub } from "capnweb";
+import type { IterateSessionApi } from "./api.ts";
+/** What `authenticate` resolves to: the session as a capnweb stub (pipelined; disposable) and the
+ *  bootstrap info it answered with. Declared, so the package's declarations stay serializable. */
+export type AuthenticatedApp = {
+    api: RpcStub<IterateSessionApi>;
+    info: ReturnType<IterateSessionApi["info"]>;
+    /** The page names a project this sign-in does not include — its `/projects/<ref>` is absent from
+     *  `api.projects.list()`: leave for `/.auth/login`, whose page offers to sign in again (the
+     *  project ticked at consent, or another account) and returns to this very URL. Never settles,
+     *  like `authenticate`'s own leave for login. */
+    signInFor(project: string): Promise<never>;
+};
+export type IterateClient = {
+    authenticate(next?: string): Promise<AuthenticatedApp>;
+};
+/** Create once per app — a TanStack route's client-only `beforeLoad`, or a plain page's entry.
+ *  Every loader and action of the page shares the returned public RPC session.
+ *
+ *  Connecting tries for a while (client/socket.ts: ≈16 s of attempts) before an error reaches the
+ *  page — a phone waking up or a flapping tunnel is not a reason to show "connection failed". And
+ *  the `api` the page holds is a proxy to the CURRENT connection: when the socket closes, the next
+ *  call opens a fresh one and pipelines onto it, so a dropped connection costs a reconnect, not the
+ *  page. A reconnect the platform refuses (the session ended elsewhere) rejects that call; the
+ *  page's retry runs `authenticate` again — a fresh one, the socket's close forgot the last — whose
+ *  probe sends the browser to log in. */
+export declare function createIterateClient(options?: {
+    scopes?: string[];
+}): IterateClient;

package/dist/next/app.mjs

@@ -0,0 +1,141 @@
+import { OAuthScopes } from "./oauth-scopes.mjs";
+import { newWebSocketRpcSession } from "capnweb";
+//#region src/next/client/socket.ts
+/** Open a WebSocket, trying again for a while when the connection fails: a phone waking up, a
+*  tunnel flapping, a cold edge — the things a first attempt trips over. Resolves with the socket
+*  once it is OPEN; rejects with the last failure after the last attempt. The delays are the
+*  waits BETWEEN attempts (the first is immediate). */
+const RETRY_DELAYS_MS = [
+	250,
+	500,
+	1e3,
+	2e3,
+	4e3,
+	8e3
+];
+function openSocketWithRetry(url, options = {}) {
+	const delays = options.delaysMs || RETRY_DELAYS_MS;
+	const Socket = options.WebSocket || WebSocket;
+	const sleep = options.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const once = () => new Promise((resolve, reject) => {
+		const socket = new Socket(url);
+		const opened = () => {
+			socket.removeEventListener("close", failed);
+			resolve(socket);
+		};
+		const failed = () => {
+			socket.removeEventListener("open", opened);
+			reject(/* @__PURE__ */ new Error("WebSocket connection failed."));
+		};
+		socket.addEventListener("open", opened, { once: true });
+		socket.addEventListener("close", failed, { once: true });
+	});
+	return (async () => {
+		let attempt = 0;
+		for (;;) try {
+			return await once();
+		} catch (error) {
+			if (attempt >= delays.length) throw error;
+			await sleep(delays[attempt]);
+			attempt += 1;
+		}
+	})();
+}
+//#endregion
+//#region src/next/app.ts
+/** The browser leaves for the issuer's login (a document navigation) and this never settles — no
+*  framework in the loop: a TanStack `beforeLoad` awaiting it ends the way a thrown
+*  `redirect({ reloadDocument: true })` did, a plain page simply navigates. */
+function leaveForLogin(login) {
+	window.location.assign(login);
+	return new Promise(() => {});
+}
+function connectionOn(socket) {
+	const iterate = newWebSocketRpcSession(socket);
+	return {
+		api: iterate.authenticate({ type: "from-server-cookie" }),
+		socket,
+		dispose: () => iterate[Symbol.dispose]()
+	};
+}
+/** Create once per app — a TanStack route's client-only `beforeLoad`, or a plain page's entry.
+*  Every loader and action of the page shares the returned public RPC session.
+*
+*  Connecting tries for a while (client/socket.ts: ≈16 s of attempts) before an error reaches the
+*  page — a phone waking up or a flapping tunnel is not a reason to show "connection failed". And
+*  the `api` the page holds is a proxy to the CURRENT connection: when the socket closes, the next
+*  call opens a fresh one and pipelines onto it, so a dropped connection costs a reconnect, not the
+*  page. A reconnect the platform refuses (the session ended elsewhere) rejects that call; the
+*  page's retry runs `authenticate` again — a fresh one, the socket's close forgot the last — whose
+*  probe sends the browser to log in. */
+function createIterateClient(options = {}) {
+	const scopes = OAuthScopes.parse(options.scopes || []);
+	let live = null;
+	let connecting;
+	const socketUrl = () => {
+		const url = new URL("/api", window.location.href);
+		url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+		return url;
+	};
+	/** Adopt a connection as the live one until its socket closes. A close also forgets the settled
+	*  `authenticate` — the next one probes `/api` again, so a session that ended elsewhere sends the
+	*  browser to log in instead of a retry that can only fail. */
+	function adopt(socket) {
+		const connection = connectionOn(socket);
+		live = connection;
+		const forget = () => {
+			if (live !== connection) return;
+			live = null;
+			connecting = void 0;
+		};
+		const dispose = () => {
+			forget();
+			connection.dispose();
+		};
+		socket.addEventListener("close", () => {
+			forget();
+			window.removeEventListener("pagehide", dispose);
+		}, { once: true });
+		window.addEventListener("pagehide", dispose, { once: true });
+		return connection;
+	}
+	const api = new Proxy({}, { get(_target, property) {
+		const connection = live || adopt(new WebSocket(socketUrl()));
+		return Reflect.get(connection.api, property);
+	} });
+	const loginUrl = (params) => `/.auth/login?${new URLSearchParams({
+		scope: scopes.join(" "),
+		...params
+	})}`;
+	async function connect(next) {
+		const login = loginUrl({ next });
+		const probe = await fetch("/api", {
+			method: "POST",
+			body: "",
+			signal: AbortSignal.timeout(1e4)
+		});
+		await probe.body?.cancel();
+		if (probe.status === 401) return leaveForLogin(login);
+		if (!probe.ok) throw new Error(`iterate is unavailable (${probe.status}). Please retry.`);
+		if (!live) adopt(await openSocketWithRetry(socketUrl()));
+		return {
+			api,
+			info: await api.info(),
+			signInFor: (project) => leaveForLogin(loginUrl({
+				next: window.location.href,
+				project
+			}))
+		};
+	}
+	return { authenticate(next = "/") {
+		connecting ||= connect(next).catch((error) => {
+			connecting = void 0;
+			throw error;
+		});
+		return connecting;
+	} };
+}
+//#endregion
+export { createIterateClient };
+
+//# sourceMappingURL=app.mjs.map

package/dist/next/app.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.mjs","names":[],"sources":["../../src/next/client/socket.ts","../../src/next/app.ts"],"sourcesContent":["/** Open a WebSocket, trying again for a while when the connection fails: a phone waking up, a\n *  tunnel flapping, a cold edge — the things a first attempt trips over. Resolves with the socket\n *  once it is OPEN; rejects with the last failure after the last attempt. The delays are the\n *  waits BETWEEN attempts (the first is immediate). */\nconst RETRY_DELAYS_MS: readonly number[] = [250, 500, 1_000, 2_000, 4_000, 8_000];\n\nexport function openSocketWithRetry(\n  url: string | URL,\n  options: {\n    delaysMs?: readonly number[];\n    /** the constructor to use — a test's fake, `WebSocket` otherwise */\n    WebSocket?: typeof WebSocket;\n    sleep?: (ms: number) => Promise<void>;\n  } = {},\n): Promise<WebSocket> {\n  const delays = options.delaysMs || RETRY_DELAYS_MS;\n  const Socket = options.WebSocket || WebSocket;\n  const sleep = options.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));\n  const once = () =>\n    new Promise<WebSocket>((resolve, reject) => {\n      const socket = new Socket(url);\n      const opened = () => {\n        socket.removeEventListener(\"close\", failed);\n        resolve(socket);\n      };\n      const failed = () => {\n        socket.removeEventListener(\"open\", opened);\n        reject(new Error(\"WebSocket connection failed.\"));\n      };\n      socket.addEventListener(\"open\", opened, { once: true });\n      socket.addEventListener(\"close\", failed, { once: true });\n    });\n  return (async () => {\n    let attempt = 0;\n    for (;;) {\n      try {\n        return await once();\n      } catch (error) {\n        if (attempt >= delays.length) throw error;\n        await sleep(delays[attempt]!);\n        attempt += 1;\n      }\n    }\n  })();\n}\n","import { newWebSocketRpcSession, type RpcStub } from \"capnweb\";\nimport type { IterateApi, IterateSessionApi } from \"./api.ts\";\nimport { openSocketWithRetry } from \"./client/socket.ts\";\nimport { OAuthScopes } from \"./oauth-scopes.ts\";\n\n/** What `authenticate` resolves to: the session as a capnweb stub (pipelined; disposable) and the\n *  bootstrap info it answered with. Declared, so the package's declarations stay serializable. */\nexport type AuthenticatedApp = {\n  api: RpcStub<IterateSessionApi>;\n  info: ReturnType<IterateSessionApi[\"info\"]>;\n  /** The page names a project this sign-in does not include — its `/projects/<ref>` is absent from\n   *  `api.projects.list()`: leave for `/.auth/login`, whose page offers to sign in again (the\n   *  project ticked at consent, or another account) and returns to this very URL. Never settles,\n   *  like `authenticate`'s own leave for login. */\n  signInFor(project: string): Promise<never>;\n};\nexport type IterateClient = { authenticate(next?: string): Promise<AuthenticatedApp> };\n\n/** The browser leaves for the issuer's login (a document navigation) and this never settles — no\n *  framework in the loop: a TanStack `beforeLoad` awaiting it ends the way a thrown\n *  `redirect({ reloadDocument: true })` did, a plain page simply navigates. */\nfunction leaveForLogin(login: string): Promise<never> {\n  window.location.assign(login);\n  return new Promise<never>(() => {});\n}\n\n/** One socket to `/api` with the session the OAuth gate resolved from the cookie. The `api` is\n *  capnweb's pipelined `authenticate(...)` answer: usable before the socket has even opened, calls\n *  queue until it has. */\ntype Connection = { api: RpcStub<IterateSessionApi>; socket: WebSocket; dispose(): void };\nfunction connectionOn(socket: WebSocket): Connection {\n  const iterate = newWebSocketRpcSession<IterateApi>(socket);\n  const api = iterate.authenticate({\n    type: \"from-server-cookie\",\n  }) as unknown as RpcStub<IterateSessionApi>;\n  return { api, socket, dispose: () => iterate[Symbol.dispose]() };\n}\n\n/** Create once per app — a TanStack route's client-only `beforeLoad`, or a plain page's entry.\n *  Every loader and action of the page shares the returned public RPC session.\n *\n *  Connecting tries for a while (client/socket.ts: ≈16 s of attempts) before an error reaches the\n *  page — a phone waking up or a flapping tunnel is not a reason to show \"connection failed\". And\n *  the `api` the page holds is a proxy to the CURRENT connection: when the socket closes, the next\n *  call opens a fresh one and pipelines onto it, so a dropped connection costs a reconnect, not the\n *  page. A reconnect the platform refuses (the session ended elsewhere) rejects that call; the\n *  page's retry runs `authenticate` again — a fresh one, the socket's close forgot the last — whose\n *  probe sends the browser to log in. */\nexport function createIterateClient(options: { scopes?: string[] } = {}): IterateClient {\n  const scopes = OAuthScopes.parse(options.scopes || []);\n  let live: Connection | null = null;\n  let connecting: Promise<AuthenticatedApp> | undefined;\n  const socketUrl = () => {\n    const url = new URL(\"/api\", window.location.href);\n    url.protocol = url.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n    return url;\n  };\n  /** Adopt a connection as the live one until its socket closes. A close also forgets the settled\n   *  `authenticate` — the next one probes `/api` again, so a session that ended elsewhere sends the\n   *  browser to log in instead of a retry that can only fail. */\n  function adopt(socket: WebSocket): Connection {\n    const connection = connectionOn(socket);\n    live = connection;\n    const forget = () => {\n      if (live !== connection) return;\n      live = null;\n      connecting = undefined;\n    };\n    const dispose = () => {\n      forget();\n      connection.dispose();\n    };\n    socket.addEventListener(\n      \"close\",\n      () => {\n        forget();\n        window.removeEventListener(\"pagehide\", dispose);\n      },\n      { once: true },\n    );\n    window.addEventListener(\"pagehide\", dispose, { once: true });\n    return connection;\n  }\n  // Every property read goes to the live connection — or to a fresh one when the last socket\n  // closed (a new WebSocket, no wait: capnweb queues the call until it opens). What comes back is\n  // capnweb's own stub for that property — a method stub carries its path, so it is returned as\n  // is, never bound or otherwise touched (a capnweb stub answers `.bind` with another stub).\n  const api = new Proxy({} as RpcStub<IterateSessionApi>, {\n    get(_target, property) {\n      const connection = live || adopt(new WebSocket(socketUrl()));\n      return Reflect.get(connection.api as object, property);\n    },\n  });\n  const loginUrl = (params: Record<string, string>) =>\n    `/.auth/login?${new URLSearchParams({ scope: scopes.join(\" \"), ...params })}`;\n  async function connect(next: string): Promise<AuthenticatedApp> {\n    const login = loginUrl({ next });\n    // HTTP distinguishes 401 from outages; a failed WebSocket is not evidence\n    // that the visitor needs to log in. Errors reach the route's error boundary.\n    const probe = await fetch(\"/api\", {\n      method: \"POST\",\n      body: \"\",\n      signal: AbortSignal.timeout(10_000),\n    });\n    await probe.body?.cancel();\n    if (probe.status === 401) return leaveForLogin(login);\n    if (!probe.ok) throw new Error(`iterate is unavailable (${probe.status}). Please retry.`);\n    if (!live) adopt(await openSocketWithRetry(socketUrl()));\n    // Consent is task-based: the person may have granted fewer scopes than the app asked for\n    // (every scope but `iterate` is optional on the consent page). The granted set is\n    // `info.scopes` — an app reads it and offers a step-up link (`/.auth/login?scope=…`) for what\n    // it lacks; it is never bounced back to consent for a permission the person declined.\n    const info = await api.info();\n    return {\n      api,\n      info,\n      signInFor: (project) => leaveForLogin(loginUrl({ next: window.location.href, project })),\n    };\n  }\n  return {\n    authenticate(next = \"/\") {\n      connecting ||= connect(next).catch((error) => {\n        connecting = undefined;\n        throw error;\n      });\n      return connecting;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/next/client/live-state.d.ts

@@ -0,0 +1,63 @@
+import { type PatchOp } from "../lib.ts";
+/** One live-state delta off the wire — the payload of an `events.iterate.com/live-state/changed`
+ *  ephemeral event, delivered raw to the subscriber. */
+/** `patch: null` = the change was too large to send — the rev moved, re-seed through the door. */
+export type LiveStateDelta = {
+    key: string;
+    from: number;
+    to: number;
+    patch: PatchOp[] | null;
+};
+/** What the producer's seed door returns: the current revision paired with the current value. */
+export type LiveStateSeed<S> = {
+    rev: number;
+    state: S;
+};
+export type LiveStateStore<S> = {
+    /** The current value, or undefined until the first seed lands. */
+    get(): S | undefined;
+    /** The held revision, or null before the first seed. */
+    rev(): number | null;
+    /** Subscribe to changes (for React's useSyncExternalStore, or a test's await-loop). */
+    subscribe(listener: () => void): () => void;
+    /** Seed (or re-seed) from the door — the first paint, and the heal after a gap. */
+    seed(seed: LiveStateSeed<S>): void;
+    /** Reduce one delta in; on a revision gap call `resync` and hold the value until a fresh seed. */
+    apply(delta: LiveStateDelta, resync: () => void): void;
+};
+export declare function createLiveStateStore<S>(): LiveStateStore<S>;
+/** The slice of an itx session this needs — a capnweb `IterateContextRpcTarget` proxy satisfies it structurally:
+ *  `subscribe` hands back a DISPOSABLE handle (disposing it removes the subscription server-side). */
+export type LiveStateItx = {
+    subscribe(input: {
+        name?: string;
+        consumes?: string[];
+        target: (events: unknown[], range: unknown) => void;
+    }): Promise<{
+        [Symbol.dispose](): void;
+    }>;
+};
+/** A connected live-state subscription: the store rendering it, and the dispose that removes the
+ *  server-side subscription (the handle's disposer; the session's end does the same). */
+export type LiveStateConnection<S> = {
+    store: LiveStateStore<S>;
+    /** Unsubscribe on the server and stop reducing deltas. Safe to call more than once. */
+    dispose(): Promise<void>;
+};
+/** Subscribe to a producer's live state and reduce it into a store. `door` reads the seed
+ *  (`itx.invoke("itx.facets.get('slug').liveSnapshot()")` for a processor, or a mini-app's
+ *  own `state()` method). Subscribe happens BEFORE the first seed, so a delta racing the seed just
+ *  triggers one door re-read — never a lost update. Gap heals are SINGLE-FLIGHT (a burst of gapped
+ *  frames triggers one door read, not one per frame); a failed heal is reported through `onResync`
+ *  and retried by the next delivered delta (its `from` still mismatches, so it re-triggers). */
+export declare function connectLiveState<S>(itx: LiveStateItx, opts: {
+    key: string;
+    name?: string;
+    door: () => Promise<LiveStateSeed<S>>;
+    /** Called after each gap heal attempt: "healed" on a fresh seed, the error when the door read
+     *  failed (the store keeps its last value; the next delta retries). */
+    onResync?: (result: "healed" | Error) => void;
+    /** Abort while the FIRST seed is still pending (a component unmounting): the row just configured
+     *  is recalled and the connect rejects — a door that never answers leaves nothing lent. */
+    signal?: AbortSignal;
+}): Promise<LiveStateConnection<S>>;

package/dist/next/client/oauth.d.ts

@@ -0,0 +1,12 @@
+/** The same code/PKCE parameters for browser login and a console-minted token. */
+export declare function authorizationCodeRequest(input: {
+    issuer: string;
+    clientId: string;
+    redirectUri: string;
+    resources: string[];
+    scopes?: string[];
+}): Promise<{
+    url: URL;
+    state: string;
+    verifier: string;
+}>;

package/dist/next/client/react.d.ts

@@ -0,0 +1,109 @@
+import { type LiveStateItx, type LiveStateSeed } from "./live-state.ts";
+export type LiveStateStatus = "connecting" | "live" | "error";
+/** One live state as a component reads it: the latest value (undefined until the first seed lands),
+ *  the revision it is at, whether its subscription is connecting, live or failed, and the failure. */
+export type LiveStateResult<S = unknown> = {
+    value: S | undefined;
+    rev: number | null;
+    status: LiveStateStatus;
+    error?: string;
+};
+/** Subscribe to a producer's live state and render its latest value. Pass a ready `itx` (a capnweb
+ *  `api.authenticate(credentials).user` or `.projects.get(id)`), the producer's `key`, and a `door`
+ *  thunk that reads `{rev, state}` (`() => itx.invoke("itx.facets.get('slug').liveSnapshot()")`).
+ *  Re-subscribes when the session, `key`, or `name` changes; unmount (and every re-subscribe)
+ *  disposes the previous server-side subscription. */
+export declare function useLiveState<S>(itx: LiveStateItx | undefined, opts: {
+    key: string;
+    name?: string;
+    door: () => Promise<LiveStateSeed<S>>;
+}): LiveStateResult<S>;
+/** One committed event as the hook hands it out: the itx envelope, structurally. */
+export type IterateContextEvent = {
+    offset: number;
+    type: string;
+    createdAt: string;
+    payload?: unknown;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+    source?: {
+        principal?: {
+            actor: string;
+            email?: string;
+        };
+        grant?: string;
+        processor?: {
+            slug: string;
+            version: string;
+        };
+    };
+};
+/** One row of a context's processors table (`itx.processors.list()`), structurally. */
+export type IterateContextProcessorRow = {
+    name: string;
+    target: string;
+    consumes?: string[];
+    configuredAtOffset: number;
+    hostedFacet?: {
+        name: string;
+        className: string;
+        cacheKey?: string;
+        restarts: number;
+    };
+};
+/** One presence: who acted on the context and when last, from the log's stamps. */
+export type IterateContextPresence = {
+    actor: string;
+    email?: string;
+    grant?: string;
+    lastSeenAt: string;
+};
+/** The slice of a context handle `useIterateContext` reads — a capnweb `IterateContextApi` stub
+ *  satisfies it structurally. `rpcStubs` is optional: a handle typed without the census (a project
+ *  context's client type) still gets the log, the table and the actors. `invoke` seeds a named
+ *  facet's live state (`itx.facets.get('<name>').liveSnapshot()`, as an expression). */
+export type IterateContextHandle = LiveStateItx & {
+    readEvents(afterOffset?: number, limit?: number): Promise<{
+        events: unknown[];
+        atHead: boolean;
+        scannedThroughOffset: number;
+    }>;
+    processors: {
+        list(): Promise<IterateContextProcessorRow[]> | IterateContextProcessorRow[];
+    };
+    rpcStubs?: {
+        list(): Promise<string[]> | string[];
+    };
+    invoke(call: string): Promise<unknown>;
+};
+/** THE ITERATE CONTEXT, live — one hook, one stream subscription. THE LOG: subscribe to every
+ *  committed event (or `consumes`) BEFORE the catch-up read, so nothing lands between the two;
+ *  pushes and pages both dedupe into one map by offset; `caughtUp` once the read reached the head;
+ *  `error` when the connect failed. Off that same log, THE PROCESSORS TABLE, re-read whenever the
+ *  log grows a row-changing event (a subscription configured, halted or resumed — the table is core
+ *  state, one call away, no push of its own), and WHO IS HERE: the rpc stubs lent right now
+ *  (`itx.rpcStubs.list()` — physical, re-read at every new head, since presence changes are
+ *  ephemeral facts) and, from the log, every principal that acted, newest first. And named facets'
+ *  LIVE STATE, each seeded through `itx.facets.get('<name>').liveSnapshot()` — one entry per name,
+ *  always. `liveState` OMITTED opens `core` (the core reduce answers under that name) plus every
+ *  hosted facet in the processors table the hook holds, following the table as it loads and changes;
+ *  `liveState` GIVEN is exactly the names to open, no implicit `core`. Re-connects when `itx`
+ *  changes; unmount disposes every server-side subscription. */
+export declare function useIterateContext(itx: IterateContextHandle | undefined, opts?: {
+    consumes?: string[];
+    liveState?: string[];
+}): {
+    events: IterateContextEvent[];
+    caughtUp: boolean;
+    error?: string;
+    processors: {
+        rows: IterateContextProcessorRow[];
+        loaded: boolean;
+        error?: string;
+    };
+    presence: {
+        actors: IterateContextPresence[];
+        rpcStubs: string[];
+    };
+    liveState: Record<string, LiveStateResult>;
+};