@foir/sdk 0.27.1 → 0.29.0

package/CHANGELOG.md

@@ -108,6 +108,76 @@ nobody asking for `@foir/sdk` gets it early. The push that carries the commit to
 
 Changes on `dev` that have not been published to npm.
 
+## [0.29.0] — 2026-10-21
+
+### Added
+
+- **`AuthorizedApp` says whose app it is**: `clientLogoUrl`, `clientLogoAlt`
+  and `clientHomepageUrl`, where the app set them.
+- **`beginSignIn` and `completeSignIn`** (`@foir/sdk/auth`): the OpenID Connect
+  code flow for a server app with no OpenID Connect library. `beginSignIn`
+  finds the issuer's endpoints from its discovery document and returns the
+  authorization URL, with a PKCE S256 challenge, a state and a nonce, and what
+  to keep until the person comes back. `completeSignIn` checks the callback
+  against it, redeems the code at the token endpoint and returns the tokens,
+  with the ID token's issuer, audience, nonce and expiry checked. A refusal is
+  a `CodeFlowError` naming the OAuth error. It uses `fetch` and Web Crypto
+  only, so it runs in Workers, Oxygen and Node 18 or later.
+- **A link for somebody new** (`@foir/sdk/auth`): `hostedLoginUrl`,
+  `signInUrl` and `useFoir().hostedSignInUrl` take `{ signUp: true }`, which
+  opens the hosted sign-in at the login domain's `/signup`, on the project's
+  way in rather than the sign-in form: joining where sign-up is public, the
+  waitlist in waitlist mode, or the invitation-only or closed notice. For a
+  "Sign up" or "Join the waitlist" button. In the code flow,
+  `beginSignIn(config, { prompt: 'create' })` asks for the same.
+- **`<ProgressiveMedia>` video props** (`@foir/sdk/media`):
+  - `objectPosition` keeps a focal point in view when the image, the video or
+    its thumbnail is cropped to fit;
+  - `controls` shows the browser's controls, which default to `!autoplay` as
+    before. A video with controls shows from the start, its poster standing
+    until it plays;
+  - `preload` sets how much the browser fetches before a video plays;
+  - `videoRef` hands over the `<video>` element, for your own play and pause
+    controls;
+  - `onVideoError` is called when a video's source cannot play.
+
+### Fixed
+
+- **A video that cannot play leaves its thumbnail**, labelled with `alt`, where
+  it left a blank box.
+- **A video's `alt` labels the `<video>`**; it was dropped.
+- **A video of unknown size takes its own shape** once its metadata loads,
+  where it was cropped to 16:10.
+
+## [0.28.0] — 2026-10-20
+
+### Added
+
+- **`<FoirFeedback appearance>`** (`@foir/sdk/react`): the built-in styles'
+  colours, radius and type, as the new `FoirFeedbackAppearance`. Each token is
+  also a CSS custom property on the wrapper (`--foir-feedback-text`,
+  `--foir-feedback-radius`, …), so a stylesheet can set it from a design
+  system's own variables. Unset, the widget looks as it did.
+- **`<FoirFeedback layout="dialog">`**: the panel opens over the page in a
+  modal `<dialog>`, with a backdrop and a Close button, closed by Escape and
+  the backdrop too. `inline`, the default, is the panel under the button.
+- **`<FoirFeedback signIn={false}>`**: a site where nobody can sign in says so,
+  and a visitor the project takes no notes from reads "Feedback is not open
+  right now" rather than "Sign in to send feedback".
+
+### Changed
+
+- **Breaking: a visitor's thank-you shows no id.** Nothing opens a visitor's
+  note from its id, so `<FoirFeedback>` no longer renders the
+  `data-foir-feedback-receipt` line. The receipt, `{ id, createdAt }`, still
+  reaches `onVisitorSubmitted`.
+- **A visitor whose note is refused because the project stopped taking
+  visitors' notes is shown that**, as the panel would show it on opening,
+  rather than asked to try again. The widget asks `noteConfig` again after a
+  visitor's send fails for a reason it cannot name.
+- **The widget's smaller lines are sized relative to its font size**, so
+  `fontSize` scales them; they were fixed at 13 and 15px.
+
 ## [0.27.1] — 2026-10-20
 
 ### Fixed
@@ -123,6 +193,17 @@ Changes on `dev` that have not been published to npm.
 
 ### Added
 
+- **`createCollabSession({ orgId })`** (`@foir/sdk/realtime`): the
+  organization the signed-in user stands at in the room, sent as the
+  connection's `org`. The user joins there only as a member of it; omitted,
+  the join stands at the project.
+- **The subscription socket honours close codes 4402 and 4403.** On 4402,
+  the socket's credential is no longer honoured: the bearer is renewed through
+  `refreshBearer` and the socket reconnects at once, failing its subscriptions
+  with `FoirSessionExpiredError` when the session is over. On 4403, the
+  signed-in user is no member of the organization the client names: the
+  subscriptions fail rather than reconnecting into the same refusal.
+
 - **`organizations.startPool({ movePeople, dryRun })`** (`@foir/sdk/app`):
   starting the run's organization's own pool takes its people along when
   asked. Somebody who stands only there moves whole, and somebody who also
@@ -166,6 +247,15 @@ Changes on `dev` that have not been published to npm.
 
 ### Changed
 
+- **Breaking: signing up with a password proves the address first.**
+  `register()` answers `true` and `signUpWithPassword(env, vars)` answers
+  nothing, and neither signs anybody in: the address is mailed a code, and
+  `signInWithOTP` / `loginWithOTP` with it finishes the account and starts the
+  session, also where the project takes no code to sign in. The answer is the
+  same whether or not the address has an account already, or the project takes
+  nobody new; whoever holds the address is told by email. `signUpWithPassword`
+  no longer takes a session adapter, `useFoirAuth().register()` answers
+  nothing, and `foirRegisterWithPassword` takes no cookie store.
 - **`<FoirFeedback>` writes a signed-in user's note through `writeNote`**, the
   one note create, rather than `createMyNote`, its older name. The same note
   on the same data API. A client whose generated module predates `writeNote`

package/dist/auth/auth.d.ts

@@ -43,11 +43,16 @@ export declare function login(env: FoirEnv, vars: {
     email: string;
     password: string;
 }): Promise<AuthResult>;
-/** Register a new user with email + password. */
+/**
+ * Start an account with email + password. The address is mailed a code, and
+ * signing in with it ({@link loginWithOTP}) proves the address and finishes
+ * the account. Answered the same whether or not the address has an account
+ * already, or the project takes nobody new: its holder is told by email.
+ */
 export declare function register(env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<AuthResult>;
+}): Promise<boolean>;
 /** Request a one-time password be emailed to the user. */
 export declare function requestOTP(env: FoirEnv, email: string): Promise<boolean>;
 /** Complete an OTP login. */
@@ -444,11 +449,15 @@ export declare function signInWithPassword(adapter: SessionAdapter, env: FoirEnv
     email: string;
     password: string;
 }): Promise<FoirUser>;
-/** Register with email + password and persist the session. */
-export declare function signUpWithPassword(adapter: SessionAdapter, env: FoirEnv, vars: {
+/**
+ * Start a sign-up with email + password: the address is mailed a code, and
+ * {@link signInWithOTP} with it finishes the account and persists the
+ * session. Nobody is signed in until then.
+ */
+export declare function signUpWithPassword(env: FoirEnv, vars: {
     email: string;
     password: string;
-}): Promise<FoirUser>;
+}): Promise<void>;
 /** Complete an OTP login and persist the session. */
 export declare function signInWithOTP(adapter: SessionAdapter, env: FoirEnv, vars: {
     email: string;

package/dist/auth/code-flow.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Sign a person in through the OpenID Connect code flow, from a server app
+ * that has no OpenID Connect library of its own.
+ *
+ * `beginSignIn` finds the issuer's endpoints from its discovery document and
+ * builds the authorization URL, with a PKCE S256 challenge, a state and a
+ * nonce. It returns the URL to send the browser to and what the app keeps
+ * until the person comes back: keep it on the server, or in an http-only
+ * cookie scoped to the callback. `completeSignIn` checks the callback against
+ * it, redeems the code at the token endpoint and returns the tokens.
+ *
+ * These are the same endpoints any OpenID Connect library uses
+ * (`/oauth/authorize` and `/oauth/token`), so an app can move to a library
+ * later without changing anything in Foir. Only `fetch` and Web Crypto are
+ * used, so the helper runs in Workers, Oxygen and Node 18 or later.
+ *
+ * The ID token is checked for its issuer, audience, nonce and expiry. Its
+ * signature is not checked: it came straight from the issuer's token
+ * endpoint over TLS, which OpenID Connect accepts in place of the signature
+ * (Core 1.0, section 3.1.3.7).
+ */
+/** Where the app signs people in. */
+export interface CodeFlowConfig {
+    /**
+     * The issuer: Foir's own (`https://api.foir.io`) or a project's login
+     * domain (`https://login.example.com`), which is the issuer of the people
+     * who sign in through it.
+     */
+    issuer: string;
+    /** The auth client's id. */
+    clientId: string;
+    /** The callback, exactly as the auth client lists it. */
+    redirectUri: string;
+    /** A fetch to use in place of the global one. */
+    fetch?: typeof fetch;
+}
+/** What one sign-in asks for. */
+export interface BeginSignInOptions {
+    /**
+     * What the sign-in asks to carry. Default `openid profile email`. Add the
+     * permission names the app's list holds to ask for fewer than all of them.
+     */
+    scope?: string | string[];
+    /** The organization the person signs in to, when the app serves several. */
+    org?: string;
+    /** `login` asks the person to sign in again, `consent` to agree again. */
+    prompt?: string;
+    /** The address to start the sign-in with. */
+    loginHint?: string;
+}
+/** A sign-in begun: where to send the browser, and what to keep for the callback. */
+export interface PendingSignIn {
+    /** The authorization URL. */
+    url: string;
+    /** Kept to check the callback's `state`. */
+    state: string;
+    /** Kept, and sent with the code. Never put it in a URL. */
+    codeVerifier: string;
+    /** Kept to check the ID token's `nonce`. */
+    nonce: string;
+}
+/** What a completed sign-in hands back. */
+export interface CodeFlowTokens {
+    accessToken: string;
+    tokenType: string;
+    expiresIn?: number;
+    refreshToken?: string;
+    idToken?: string;
+    scope?: string;
+    /** The ID token's claims, checked as described above. */
+    claims?: Record<string, unknown>;
+}
+/**
+ * A sign-in that did not complete. `code` is the OAuth error the issuer
+ * answered (`access_denied`, `invalid_grant`, ...), or one of the checks the
+ * helper makes: `state_mismatch`, `issuer_mismatch`, `nonce_mismatch`,
+ * `audience_mismatch`, `id_token_expired`, `discovery_failed` (the issuer
+ * could not be reached or answered no discovery document),
+ * `token_request_failed` (the token endpoint could not be reached or answered
+ * no access token), `invalid_request` (the callback carries no code).
+ */
+export declare class CodeFlowError extends Error {
+    readonly code: string;
+    readonly description?: string;
+    constructor(code: string, description?: string);
+}
+/**
+ * Begin a sign-in: the URL to send the browser to, and what to keep until
+ * the person comes back to the callback.
+ */
+export declare function beginSignIn(config: CodeFlowConfig, options?: BeginSignInOptions): Promise<PendingSignIn>;
+/**
+ * Complete a sign-in from its callback: check it against what `beginSignIn`
+ * returned, redeem the code at the token endpoint, and return the tokens.
+ * `callback` is the URL the browser came back to, or its query.
+ */
+export declare function completeSignIn(config: CodeFlowConfig, callback: string | URL | URLSearchParams, pending: Pick<PendingSignIn, 'state' | 'codeVerifier' | 'nonce'>): Promise<CodeFlowTokens>;

package/dist/auth/hosted.d.ts

@@ -1,7 +1,7 @@
 /**
- * Hosted-login bridge — for storefronts that delegate sign-in to a Foir
- * white-label front door (the `loginWithFoir` flow) instead of
- * rendering their own login UI.
+ * The hosted session: for an app on the same registrable domain as its login
+ * domain, which trades the login domain's session cookie for a token instead
+ * of running the code flow itself (see code-flow.ts for that).
  *
  * The front door sets a first-party session cookie on the registrable domain;
  * because that domain is shared, the cookie reaches the storefront, which
@@ -37,6 +37,14 @@ export interface HostedLoginOptions {
      * of another project, and one that is not active.
      */
     org?: string;
+    /**
+     * Somebody new is expected: the page opens on the project's way in rather
+     * than the sign-in form, for a "Sign up" or "Join the waitlist" button. The
+     * project's sign-up still decides what that is: joining where it is public,
+     * the waitlist, or the invitation-only or closed notice. The URL is the
+     * login domain's `/signup`.
+     */
+    signUp?: boolean;
 }
 /**
  * Build the redirect URL to the hosted front door, forwarding an absolute

package/dist/auth/index.d.ts

@@ -18,6 +18,8 @@ export { FoirAuthDowngradedError, FoirSessionExpiredError } from '../graphql/foi
 export { AUTH_OPS } from './ops';
 export type { AuthOpName, AuthOpOptions } from './ops';
 export { hostedLoginUrl, hostedLogoutUrl, fetchHostedSession, hostedSignInNoticeOf } from './hosted';
+export { beginSignIn, completeSignIn, CodeFlowError } from './code-flow';
+export type { CodeFlowConfig, BeginSignInOptions, PendingSignIn, CodeFlowTokens } from './code-flow';
 export type { HostedLoginConfig, HostedLoginOptions, HostedSession, HostedSessionResult, HostedSignInNotice } from './hosted';
 export { createFoirSessionClient } from './session-client';
 export type { FoirSessionClient, FoirSessionConfig, FoirSessionUser, } from './session-client';

package/dist/auth/operations.d.ts

@@ -317,6 +317,11 @@ export interface AuthorizedApp {
     id: string;
     clientId: string;
     clientName: string;
+    /** The app's logo, where it has one, and what it shows. */
+    clientLogoUrl?: string | null;
+    clientLogoAlt?: string | null;
+    /** The app's homepage, where it has one. */
+    clientHomepageUrl?: string | null;
     /** What the app may carry for them, in the permission catalogue's names. */
     grants: string[];
     /** ISO-8601. */

package/dist/auth.js

@@ -1408,8 +1408,8 @@ async function getSessionUser(adapter) {
 async function signInWithPassword(adapter, env, vars) {
   return saveSession(adapter, await login(env, vars));
 }
-async function signUpWithPassword(adapter, env, vars) {
-  return saveSession(adapter, await register(env, vars));
+async function signUpWithPassword(env, vars) {
+  await register(env, vars);
 }
 async function signInWithOTP(adapter, env, vars) {
   return saveSession(adapter, await loginWithOTP(env, vars));
@@ -1602,6 +1602,7 @@ var GRANT_TABLE = [
   ["apikeys:write", "none", [], []],
   ["organizations:read", "none", [], []],
   ["organizations:write", "none", [], []],
+  ["orgsettings:write", "none", [], []],
   ["organizations:create", "none", [], []],
   ["organizations:delete", "none", [], []],
   ["organizations:reach", "none", [], []],
@@ -1612,7 +1613,7 @@ var GRANT_TABLE = [
   ["projects:read", "none", [], []],
   ["projects:write", "none", [], []],
   ["project:stand", "none", [], []],
-  ["project:manage", "none", [], ["project:stand", "records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:setup", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "auth:login_with_foir", "authclients:read", "authclients:write", "domains:read", "domains:write", "loginpages:read", "loginpages:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
+  ["project:manage", "none", [], ["project:stand", "records:read.all", "records:create", "records:write.all", "records:delete.all", "records:publish.all", "records:attribute", "search:read", "embeddings:read", "embeddings:write", "schemas:read", "drafts:read", "files:read.all", "files:write.all", "files:delete.all", "users:read.all", "identities:read", "users:create", "identities:delete", "users:write.all", "users:setup", "users:delete.all", "notifications:read.all", "notifications:write.all", "notifications:consent", "pushcredentials:read", "pushcredentials:write", "notes:read.all", "notes:write.all", "notes:create", "approvals:read", "approvals:write", "rooms:read", "rooms:write", "presence:read", "operations:read", "operations:execute", "operations:write", "appconfig:read", "schedules:read", "schedules:write", "hooks:read", "hooks:write", "authclients:read", "authclients:write", "domains:read", "domains:write", "loginpages:read", "loginpages:write", "secrets:read", "secrets:list", "secrets:put", "secrets:delete", "appsecrets:read", "appsecrets:list", "appsecrets:put", "appsecrets:delete", "usersecrets:read", "usersecrets:list", "usersecrets:put", "usersecrets:delete", "opsecrets:read", "opsecrets:write", "settings:read", "settings:write", "designtokens:read", "designtokens:write", "models:read", "models:write", "configs:read", "configs:write", "signinproviders:read", "signinproviders:write", "apps:read", "apps:write", "events:read", "targeting:debug", "visitors:forward", "apikeys:read", "apikeys:write", "organizations:read", "organizations:create", "organizations:delete", "organizations:write", "orgsettings:write", "organizations:reach", "members:read", "members:write", "roles:read", "roles:write", "projects:read", "projects:write", "audit:read"]],
   ["projects:create", "none", [], []],
   ["projects:delete", "none", [], []],
   ["tenants:read", "none", [], []],
@@ -1643,7 +1644,6 @@ var GRANT_TABLE = [
   ["usersecrets:list", "none", [], []],
   ["usersecrets:put", "none", [], []],
   ["usersecrets:delete", "none", [], []],
-  ["auth:login_with_foir", "none", [], []],
   ["signinproviders:read", "none", [], []],
   ["signinproviders:write", "none", [], []]
 ];
@@ -1807,6 +1807,9 @@ var DEFAULT_SESSION_PATH = "/session/token";
 var DEFAULT_END_SESSION_PATH = "/session/end-session";
 function hostedLoginUrl(config, returnTo, options = {}) {
   const dest = new URL(config.loginOrigin);
+  if (options.signUp) {
+    dest.pathname = `${dest.pathname.replace(/\/+$/, "")}/signup`;
+  }
   if (returnTo && returnTo !== "/") {
     dest.searchParams.set("returnTo", returnTo);
   }
@@ -1913,6 +1916,169 @@ function forApp(clientId) {
   return clientId ? `?client_id=${encodeURIComponent(clientId)}` : "";
 }
 
+// src/auth/code-flow.ts
+var CodeFlowError = class extends Error {
+  code;
+  description;
+  constructor(code, description) {
+    super(description ? `${code}: ${description}` : code);
+    this.name = "CodeFlowError";
+    this.code = code;
+    this.description = description;
+  }
+};
+var discoveries = /* @__PURE__ */ new Map();
+function trimSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+async function discover(config) {
+  const issuer = trimSlash(config.issuer);
+  let found = discoveries.get(issuer);
+  if (!found) {
+    found = (async () => {
+      let res;
+      try {
+        res = await (config.fetch ?? fetch)(`${issuer}/.well-known/openid-configuration`, {
+          headers: { accept: "application/json" }
+        });
+      } catch (e) {
+        throw new CodeFlowError("discovery_failed", `${issuer} could not be reached for its discovery document: ${String(e)}`);
+      }
+      if (!res.ok) {
+        throw new CodeFlowError("discovery_failed", `${issuer} answered ${res.status} for its discovery document`);
+      }
+      const doc = await res.json().catch(() => null);
+      if (!doc) {
+        throw new CodeFlowError("discovery_failed", `${issuer} answered no JSON for its discovery document`);
+      }
+      if (!doc.issuer || trimSlash(doc.issuer) !== issuer) {
+        throw new CodeFlowError("issuer_mismatch", `the discovery document at ${issuer} names ${doc.issuer ?? "no issuer"}`);
+      }
+      if (!doc.authorization_endpoint || !doc.token_endpoint) {
+        throw new CodeFlowError("discovery_failed", `the discovery document at ${issuer} names no authorization or token endpoint`);
+      }
+      return doc;
+    })();
+    discoveries.set(issuer, found);
+    found.catch(() => discoveries.delete(issuer));
+  }
+  return found;
+}
+function base64url(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomString(byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+async function s256(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}
+async function beginSignIn(config, options = {}) {
+  const endpoints = await discover(config);
+  const state = randomString(24);
+  const nonce = randomString(24);
+  const codeVerifier = randomString(48);
+  const url = new URL(endpoints.authorization_endpoint);
+  const scope = Array.isArray(options.scope) ? options.scope.join(" ") : options.scope ?? "openid profile email";
+  url.searchParams.set("client_id", config.clientId);
+  url.searchParams.set("redirect_uri", config.redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", scope);
+  url.searchParams.set("state", state);
+  url.searchParams.set("nonce", nonce);
+  url.searchParams.set("code_challenge", await s256(codeVerifier));
+  url.searchParams.set("code_challenge_method", "S256");
+  if (options.org) url.searchParams.set("org", options.org);
+  if (options.prompt) url.searchParams.set("prompt", options.prompt);
+  if (options.loginHint) url.searchParams.set("login_hint", options.loginHint);
+  return { url: url.toString(), state, codeVerifier, nonce };
+}
+function callbackParams(callback) {
+  if (callback instanceof URLSearchParams) return callback;
+  if (callback instanceof URL) return callback.searchParams;
+  const query = callback.indexOf("?");
+  return new URLSearchParams(query >= 0 ? callback.slice(query + 1).split("#")[0] : callback);
+}
+function claimsOf(idToken) {
+  const payload = idToken.split(".")[1];
+  if (!payload) throw new CodeFlowError("invalid_id_token", "the ID token is not a JWT");
+  const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+  const bytes = Uint8Array.from(json, (c) => c.charCodeAt(0));
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+async function completeSignIn(config, callback, pending) {
+  const endpoints = await discover(config);
+  const params = callbackParams(callback);
+  if (params.get("state") !== pending.state) {
+    throw new CodeFlowError("state_mismatch", "the callback is not for the sign-in this app began");
+  }
+  const refused = params.get("error");
+  if (refused) {
+    throw new CodeFlowError(refused, params.get("error_description") ?? void 0);
+  }
+  const code = params.get("code");
+  if (!code) {
+    throw new CodeFlowError("invalid_request", "the callback carries no code");
+  }
+  let res;
+  try {
+    res = await (config.fetch ?? fetch)(endpoints.token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: config.redirectUri,
+        client_id: config.clientId,
+        code_verifier: pending.codeVerifier
+      }).toString()
+    });
+  } catch (e) {
+    throw new CodeFlowError("token_request_failed", `the token endpoint could not be reached: ${String(e)}`);
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new CodeFlowError(
+      typeof body.error === "string" ? body.error : "token_request_failed",
+      typeof body.error_description === "string" ? body.error_description : `the token endpoint answered ${res.status}`
+    );
+  }
+  const tokens = {
+    accessToken: String(body.access_token ?? ""),
+    tokenType: String(body.token_type ?? "Bearer"),
+    expiresIn: typeof body.expires_in === "number" ? body.expires_in : void 0,
+    refreshToken: typeof body.refresh_token === "string" ? body.refresh_token : void 0,
+    idToken: typeof body.id_token === "string" ? body.id_token : void 0,
+    scope: typeof body.scope === "string" ? body.scope : void 0
+  };
+  if (!tokens.accessToken) {
+    throw new CodeFlowError("token_request_failed", "the token endpoint answered no access token");
+  }
+  if (tokens.idToken) {
+    const claims = claimsOf(tokens.idToken);
+    if (typeof claims.iss !== "string" || trimSlash(claims.iss) !== trimSlash(endpoints.issuer)) {
+      throw new CodeFlowError("issuer_mismatch", `the ID token's issuer is ${String(claims.iss)}`);
+    }
+    const audience = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+    if (!audience.includes(config.clientId)) {
+      throw new CodeFlowError("audience_mismatch", "the ID token is not for this app");
+    }
+    if (claims.nonce !== pending.nonce) {
+      throw new CodeFlowError("nonce_mismatch", "the ID token is not for the sign-in this app began");
+    }
+    if (typeof claims.exp === "number" && claims.exp * 1e3 < Date.now()) {
+      throw new CodeFlowError("id_token_expired", "the ID token has expired");
+    }
+    tokens.claims = claims;
+  }
+  return tokens;
+}
+
 // src/auth/session-client.ts
 var DEFAULT_SESSION_PATH2 = "/session/token";
 var DEFAULT_LOGOUT_PATH = "/session/logout";
@@ -1921,8 +2087,8 @@ var MIN_REFRESH_DELAY_MS = 5e3;
 var CSRF_HEADER = { "X-Foir-Session": "1" };
 function createFoirSessionClient(config) {
   const forApp2 = config.clientId ? `?client_id=${encodeURIComponent(config.clientId)}` : "";
-  const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH2}${forApp2}`;
-  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}${forApp2}`;
+  const sessionUrl = `${trimSlash2(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH2}${forApp2}`;
+  const logoutUrl = `${trimSlash2(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}${forApp2}`;
   const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
   let cached = null;
   let inflight = null;
@@ -2029,7 +2195,7 @@ function createFoirSessionClient(config) {
       config.onSignOut?.();
     },
     signInUrl(returnTo, options = {}) {
-      const dest = new URL(trimSlash(config.loginOrigin));
+      const dest = new URL(trimSlash2(config.loginOrigin));
       const target = returnTo ?? (typeof window !== "undefined" ? window.location.href : void 0);
       if (target && target !== "/") dest.searchParams.set("returnTo", target);
       if (options.org) dest.searchParams.set("org", options.org);
@@ -2046,11 +2212,12 @@ function createFoirSessionClient(config) {
     }
   };
 }
-function trimSlash(s) {
+function trimSlash2(s) {
   return s.replace(/\/+$/, "");
 }
 export {
   AUTH_OPS,
+  CodeFlowError,
   FoirAccessDeniedError,
   FoirAuthDowngradedError,
   FoirSessionExpiredError,
@@ -2058,9 +2225,11 @@ export {
   authedOp,
   authedRequest,
   beginFactorEnrollment,
+  beginSignIn,
   beginStepUp,
   clearSession,
   completeFactorEnrollment,
+  completeSignIn,
   completeStepUp,
   confirmProviderLink,
   connectSignInMethod,

package/dist/data/builtins.d.ts

@@ -554,8 +554,7 @@ export interface FoirNoteConfig {
  * and nothing else, because nobody is signed in to read the note back as. Ask
  * for more and the write is refused before anything is written.
  *
- * Show the `id` to the visitor so they can quote it. Nothing on the public
- * plane takes it to read the note.
+ * Nothing on the public plane takes the `id` to read the note.
  */
 export interface FoirNoteReceipt {
     id: string;

package/dist/data/transport.d.ts

@@ -725,4 +725,5 @@ export declare function executeFoirDocument<T>(config: FoirClientConfig, plan: F
 export declare function executeFoirRawDocument<T>(config: FoirClientConfig, document: string, mutation: boolean, variables?: Record<string, unknown>, options?: {
     strict?: boolean;
 }): Promise<T>;
+export declare function renewBearerOnce(refresh: () => Promise<string | null>): Promise<string | null>;
 export {};

package/dist/data/ws-transport.d.ts

@@ -149,6 +149,7 @@ export declare class FoirSocketTransport {
     private disposed;
     private keepAlive;
     private retryTimer;
+    private renewedBearer;
     constructor(config: FoirRequestConfig);
     /**
      * Start a subscription.
@@ -167,6 +168,14 @@ export declare class FoirSocketTransport {
     private ensureConnected;
     private sendConnectionInit;
     private handleClose;
+    /**
+     * Reconnect after the socket's credential lapsed: with the bearer renewed
+     * through the client's `refreshBearer` where it has one, failing every
+     * subscription with `FoirSessionExpiredError` when the session is over. A
+     * client without one reconnects at once, presenting what its bearer
+     * provider gives now.
+     */
+    private reconnectWithARenewedBearer;
     private scheduleReconnect;
     private teardownSocket;
     private receive;