iterate 0.2.7 → 0.4.0

package/dist/app-session.d.ts

@@ -0,0 +1,49 @@
+import { DurableObject } from "cloudflare:workers";
+export type BrowserHost = {
+    origin: string;
+    issuer: string;
+    resource: string;
+    scopes: string[];
+    client?: {
+        id?: string;
+        name: string;
+        logoUri: string;
+    };
+};
+/** 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. */
+export declare class BrowserSession extends DurableObject {
+    #private;
+    begin(host: BrowserHost, next: string): Promise<string>;
+    /** 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: string): Promise<{
+        error: string;
+        next?: undefined;
+    } | {
+        next: string;
+        error?: undefined;
+    }>;
+    bearer(): Promise<string | null>;
+    /** 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. */
+    host(): Promise<{
+        issuer: string;
+        resource: string;
+    } | null>;
+    scopes(): Promise<string[]>;
+    /** Public client metadata chosen by the app before consent; never a browser-supplied claim. */
+    client(): Promise<{
+        id?: string;
+        name: string;
+        logoUri: string;
+    } | undefined>;
+    /** A verified 401 means this local credential no longer grants access. */
+    discard(): Promise<void>;
+    end(): Promise<void>;
+    alarm(): Promise<void>;
+}

package/dist/app-session.mjs

@@ -0,0 +1,235 @@
+import { isLocalOrigin } from "./lib.mjs";
+import { OAuthScopes } from "./oauth-scopes.mjs";
+import { t as _usingCtx } from "./usingCtx-inzbY1Qz.mjs";
+import { authorizationCodeRequest, authorizationServer } from "./oauth.mjs";
+import { DurableObject } from "cloudflare:workers";
+import { z } from "zod";
+import { newHttpBatchRpcSession } from "capnweb";
+import * as oauth from "oauth4webapi";
+//#region src/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 = authorizationServer(data.issuer);
+			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: "bearer" })).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 = authorizationServer(data.issuer);
+		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.
+	*  A token endpoint that answered anything but its token — an OAuth error body, or a response
+	*  oauth4webapi could not read as one (an uncaught 500) — throws one message naming its status,
+	*  which reads the same on the far side of the Durable Object's RPC. */
+	async #endOnDeadGrant(error) {
+		if (error instanceof oauth.ResponseBodyError && error.error === "invalid_grant") {
+			await this.#clear();
+			return;
+		}
+		const status = error instanceof oauth.ResponseBodyError ? error.status : error instanceof oauth.OperationProcessingError && error.cause instanceof Response ? error.cause.status : null;
+		throw status === null ? error : /* @__PURE__ */ new Error(`Iterate token exchange failed (${status}). Try again.`);
+	}
+	/** 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/app-session.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-session.mjs","names":["#serial","#clear","#tokenOptions","#endOnDeadGrant","#activate","#bearer"],"sources":["../src/app-session.ts"],"sourcesContent":["import { DurableObject } from \"cloudflare:workers\";\nimport { newHttpBatchRpcSession } from \"capnweb\";\nimport * as oauth from \"oauth4webapi\";\nimport { z } from \"zod\";\nimport { authorizationCodeRequest, authorizationServer } 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 = authorizationServer(data.issuer);\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          // oxlint-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: \"bearer\" });\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 (which also ends one unused for a week: its\n    // refresh then answers `invalid_grant`). 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 = authorizationServer(data.issuer);\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   *  A token endpoint that answered anything but its token — an OAuth error body, or a response\n   *  oauth4webapi could not read as one (an uncaught 500) — throws one message naming its status,\n   *  which reads the same on the far side of the Durable Object's RPC. */\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    const status =\n      error instanceof oauth.ResponseBodyError\n        ? error.status\n        : error instanceof oauth.OperationProcessingError && error.cause instanceof Response\n          ? error.cause.status\n          : null;\n    throw status === null\n      ? error\n      : new Error(`Iterate token exchange failed (${status}). Try again.`);\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/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/app.mjs

@@ -0,0 +1,180 @@
+import { OAuthScopes } from "./oauth-scopes.mjs";
+import { newWebSocketRpcSession } from "capnweb";
+//#region src/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).
+*
+*  Every failed attempt is explained, never swallowed (docs/engineering-invariants.md): the error
+*  names the close code and reason the socket closed with before it opened, and each attempt that
+*  is tried again logs a `client.platform-failure-socket-open` warn first. The upgrade's HTTP status
+*  is not among them: the WebSocket API never exposes the handshake's response (a refused upgrade
+*  is a close 1006, by design — https://websockets.spec.whatwg.org/#feedback-from-the-protocol),
+*  so a non-standard `ErrorEvent.error` (Node's undici names "non-101 status code" there) is added
+*  when the runtime gives one. */
+const RETRY_DELAYS_MS = [
+	250,
+	500,
+	1e3,
+	2e3,
+	4e3,
+	8e3
+];
+/** How long one attempt may take to open. A handshake that neither opens nor closes is a failed
+*  attempt too, closed and tried again like any other: without a bound the page waits on it for as
+*  long as the browser does, behind a spinner that never ends (a Dash spec sat 30 s after its
+*  sign-in's `POST /api` answered, with no `/api` upgrade ever reaching the Worker, 2026-09-24).
+*  A healthy upgrade opens in well under a second. */
+const HANDSHAKE_TIMEOUT_MS = 1e4;
+function openSocketWithRetry(url, options = {}) {
+	const delays = options.delaysMs || RETRY_DELAYS_MS;
+	const handshakeTimeoutMs = options.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_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);
+		let cause = "";
+		const timeout = setTimeout(() => {
+			settle();
+			socket.close();
+			reject(/* @__PURE__ */ new Error(`WebSocket did not open in ${handshakeTimeoutMs} ms`));
+		}, handshakeTimeoutMs);
+		function settle() {
+			clearTimeout(timeout);
+			socket.removeEventListener("open", opened);
+			socket.removeEventListener("close", failed);
+			socket.removeEventListener("error", errored);
+		}
+		function errored(event) {
+			const error = event.error;
+			if (error instanceof Error) cause = ` (${error.message})`;
+		}
+		function opened() {
+			settle();
+			resolve(socket);
+		}
+		function failed(event) {
+			settle();
+			reject(/* @__PURE__ */ new Error(`WebSocket connection failed: closed ${event.code}${event.reason ? ` "${event.reason}"` : ""} before it opened${cause}`));
+		}
+		socket.addEventListener("open", opened, { once: true });
+		socket.addEventListener("error", errored);
+		socket.addEventListener("close", failed, { once: true });
+	});
+	return (async () => {
+		for (let attempt = 1;; attempt++) try {
+			return await once();
+		} catch (error) {
+			const delay = delays[attempt - 1];
+			if (delay === void 0) throw error;
+			console.warn({
+				event: "client.platform-failure-socket-open",
+				url: String(url),
+				attempt,
+				attempts: delays.length + 1,
+				retryInMs: delay,
+				message: error.message
+			});
+			await sleep(delay);
+		}
+	})();
+}
+//#endregion
+//#region src/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/app.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.mjs","names":[],"sources":["../src/client/socket.ts","../src/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).\n *\n *  Every failed attempt is explained, never swallowed (docs/engineering-invariants.md): the error\n *  names the close code and reason the socket closed with before it opened, and each attempt that\n *  is tried again logs a `client.platform-failure-socket-open` warn first. The upgrade's HTTP status\n *  is not among them: the WebSocket API never exposes the handshake's response (a refused upgrade\n *  is a close 1006, by design — https://websockets.spec.whatwg.org/#feedback-from-the-protocol),\n *  so a non-standard `ErrorEvent.error` (Node's undici names \"non-101 status code\" there) is added\n *  when the runtime gives one. */\nconst RETRY_DELAYS_MS: readonly number[] = [250, 500, 1_000, 2_000, 4_000, 8_000];\n\n/** How long one attempt may take to open. A handshake that neither opens nor closes is a failed\n *  attempt too, closed and tried again like any other: without a bound the page waits on it for as\n *  long as the browser does, behind a spinner that never ends (a Dash spec sat 30 s after its\n *  sign-in's `POST /api` answered, with no `/api` upgrade ever reaching the Worker, 2026-09-24).\n *  A healthy upgrade opens in well under a second. */\nconst HANDSHAKE_TIMEOUT_MS = 10_000;\n\nexport function openSocketWithRetry(\n  url: string | URL,\n  options: {\n    delaysMs?: readonly number[];\n    handshakeTimeoutMs?: 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 handshakeTimeoutMs = options.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_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      let cause = \"\";\n      const timeout = setTimeout(() => {\n        settle();\n        socket.close();\n        reject(new Error(`WebSocket did not open in ${handshakeTimeoutMs} ms`));\n      }, handshakeTimeoutMs);\n      function settle() {\n        clearTimeout(timeout);\n        socket.removeEventListener(\"open\", opened);\n        socket.removeEventListener(\"close\", failed);\n        socket.removeEventListener(\"error\", errored);\n      }\n      function errored(event: Event) {\n        const error = (event as Partial<ErrorEvent>).error;\n        if (error instanceof Error) cause = ` (${error.message})`;\n      }\n      function opened() {\n        settle();\n        resolve(socket);\n      }\n      function failed(event: CloseEvent) {\n        settle();\n        reject(\n          new Error(\n            `WebSocket connection failed: closed ${event.code}${event.reason ? ` \"${event.reason}\"` : \"\"} before it opened${cause}`,\n          ),\n        );\n      }\n      socket.addEventListener(\"open\", opened, { once: true });\n      socket.addEventListener(\"error\", errored);\n      socket.addEventListener(\"close\", failed, { once: true });\n    });\n  return (async () => {\n    for (let attempt = 1; ; attempt++) {\n      try {\n        return await once();\n      } catch (error) {\n        const delay = delays[attempt - 1];\n        if (delay === undefined) throw error;\n        console.warn({\n          event: \"client.platform-failure-socket-open\",\n          url: String(url),\n          attempt,\n          attempts: delays.length + 1,\n          retryInMs: delay,\n          message: (error as Error).message,\n        });\n        await sleep(delay);\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/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/itx/live-state-changed`
+ *  ephemeral event, delivered raw to the subscriber. `patch: null` = the change was too large to
+ *  send — the rev moved, re-read the seed. */
+export type LiveStateDelta = {
+    key: string;
+    from: number;
+    to: number;
+    patch: PatchOp[] | null;
+};
+/** What the producer's seed read 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 a seed read — 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. `readSeed` 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 seed re-read — never a lost update. Gap heals are SINGLE-FLIGHT (a burst of gapped
+ *  frames triggers one seed 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;
+    readSeed: () => Promise<LiveStateSeed<S>>;
+    /** Called after each gap heal attempt: "healed" on a fresh seed, the error when the seed 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 seed read that never answers leaves nothing lent. */
+    signal?: AbortSignal;
+}): Promise<LiveStateConnection<S>>;

package/dist/client/oauth.d.ts

@@ -0,0 +1,17 @@
+import * as oauth from "oauth4webapi";
+/** The platform's issuer as oauth4webapi's authorization server: its endpoints under `/oauth2`, and
+ *  the `iss` it adds to every authorization response (RFC 9207), which `validateAuthResponse` then
+ *  requires. The same description for an app's browser session and the CLI. */
+export declare function authorizationServer(issuer: string): oauth.AuthorizationServer;
+/** 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;
+}>;