@foir/sdk 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -108,6 +108,47 @@ 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
@@ -152,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
@@ -195,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/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;

package/dist/data.js

@@ -1380,6 +1380,8 @@ function printSubscriptionDocument(input) {
 }
 
 // src/data/ws-transport.ts
+var CLOSE_CREDENTIAL_ENDED = 4402;
+var CLOSE_FORBIDDEN = 4403;
 var GQL = {
   connectionInit: "connection_init",
   connectionAck: "connection_ack",
@@ -1414,6 +1416,9 @@ var FoirSocketTransport = class {
   disposed = false;
   keepAlive = null;
   retryTimer = null;
+  // A bearer renewed after the socket's lapsed (4402), presented from the next
+  // connect on in place of the client's own.
+  renewedBearer = null;
   constructor(config) {
     if (config.dispatch !== void 0) {
       throw new FoirRequestError(
@@ -1486,12 +1491,14 @@ var FoirSocketTransport = class {
     socket.onmessage = (event) => this.receive(event.data);
     socket.onerror = () => {
     };
-    socket.onclose = () => this.handleClose();
+    socket.onclose = (event) => this.handleClose(event);
   }
   async sendConnectionInit(socket) {
     this.connecting = false;
     try {
-      const { headers } = await resolveFoirAuth(this.config);
+      const { headers } = await resolveFoirAuth(
+        this.renewedBearer ? { ...this.config, bearerToken: this.renewedBearer } : this.config
+      );
       const { "Content-Type": _contentType, ...params } = headers;
       const extra = await this.config.connectionParams?.() ?? {};
       this.send(socket, {
@@ -1505,19 +1512,53 @@ var FoirSocketTransport = class {
       this.teardownSocket(true);
     }
   }
-  handleClose() {
+  handleClose(event) {
+    const code = event?.code;
     const wasAcknowledged = this.acknowledged;
     this.teardownSocket(false);
     if (this.disposed || this.registrations.size === 0) return;
     for (const registration of this.registrations.values()) {
       registration.sent = false;
     }
+    if (code === CLOSE_FORBIDDEN) {
+      this.failAll(
+        new FoirRequestError(
+          "[foir] the subscription socket was refused where it asked to stand: the signed-in user is no member of the organization this client names"
+        )
+      );
+      return;
+    }
+    if (code === CLOSE_CREDENTIAL_ENDED) {
+      void this.reconnectWithARenewedBearer();
+      return;
+    }
     this.scheduleReconnect(
       new FoirRequestError(
         wasAcknowledged ? "[foir] the subscription socket closed and could not be re-established" : "[foir] the subscription socket closed before the credential was accepted"
       )
     );
   }
+  /**
+   * 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.
+   */
+  async reconnectWithARenewedBearer() {
+    const refresh = this.config.refreshBearer;
+    if (refresh) {
+      const token = await renewBearerOnce(refresh).catch(() => null);
+      if (this.disposed) return;
+      if (!token) {
+        this.failAll(new FoirSessionExpiredError());
+        return;
+      }
+      this.renewedBearer = token;
+    }
+    this.attempt = 0;
+    this.ensureConnected();
+  }
   scheduleReconnect(error) {
     if (this.disposed || this.registrations.size === 0) return;
     if (this.attempt >= this.policy.maxAttempts) {

package/dist/media/ProgressiveMedia.d.ts

@@ -1,3 +1,4 @@
+import type { Ref } from 'react';
 import type { ProgressiveImageSource, ProgressiveVideoSource, VariantTierKey } from './media';
 export interface ProgressiveMediaProps {
     image?: ProgressiveImageSource;
@@ -25,6 +26,31 @@ export interface ProgressiveMediaProps {
     muted?: boolean;
     /** Video playback — loop on end. Default true. */
     loop?: boolean;
+    /**
+     * Video playback: show the browser's controls. Defaults to `!autoplay`. A
+     * video with controls shows from the start, its poster standing until it
+     * plays, so the controls can always be reached.
+     */
+    controls?: boolean;
+    /** Video: how much the browser fetches before it plays (`<video preload>`). */
+    preload?: 'none' | 'metadata' | 'auto';
+    /**
+     * Where the media sits in its box when it is cropped to fit, as CSS
+     * `object-position` (`'30% 60%'`), for a focal point. Applies to the image,
+     * the video and its thumbnail. Default centre.
+     */
+    objectPosition?: string;
+    /**
+     * The `<video>` element, once it mounts: for a caller's own play and pause
+     * controls, and the events that keep them in step.
+     */
+    videoRef?: Ref<HTMLVideoElement>;
+    /**
+     * Called once when a video's source cannot be played. The video is then
+     * removed, and its thumbnail, labelled with `alt`, stands in for it over
+     * the colour and blurhash layers.
+     */
+    onVideoError?: () => void;
     /**
      * When false, skip loading the full media layer (no `<video>`/full `<img>`
      * mount, no HLS attach, no full-image preload). The lower layers — colour,
@@ -53,4 +79,4 @@ export interface ProgressiveMediaProps {
      */
     variantTiers?: readonly VariantTierKey[];
 }
-export declare function ProgressiveMedia({ image, video, alt, className, fill, fit, placeholder, autoplay, muted, loop, active, sizes, priority, variantTiers, }: ProgressiveMediaProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ProgressiveMedia({ image, video, alt, className, fill, fit, placeholder, autoplay, muted, loop, controls, preload, objectPosition, videoRef: externalVideoRef, onVideoError, active, sizes, priority, variantTiers, }: ProgressiveMediaProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/media.js

@@ -213,6 +213,11 @@ function ProgressiveMedia({
   autoplay = true,
   muted = true,
   loop = true,
+  controls,
+  preload,
+  objectPosition,
+  videoRef: externalVideoRef,
+  onVideoError,
   active = true,
   sizes = "100vw",
   priority = false,
@@ -225,7 +230,13 @@ function ProgressiveMedia({
   const source = video ?? image;
   const isVideo = !!video;
   const [wrapperRef, inViewport] = useInViewport("300px", priority);
-  const videoActive = isVideo && active && (priority || inViewport);
+  const [failedUrl, setFailedUrl] = useState2(void 0);
+  const videoFailed = isVideo && failedUrl !== void 0 && failedUrl === video?.url;
+  const [videoSize, setVideoSize] = useState2(
+    null
+  );
+  const videoActive = isVideo && active && !videoFailed && (priority || inViewport);
+  const showControls = controls ?? !autoplay;
   const imageActive = !isVideo && active;
   const hlsUrl = video?.hlsUrl;
   const useHls = isVideo && !!hlsUrl;
@@ -282,6 +293,8 @@ function ProgressiveMedia({
         cleanupRef.current = null;
       }
       videoRef.current = el;
+      if (typeof externalVideoRef === "function") externalVideoRef(el);
+      else if (externalVideoRef) externalVideoRef.current = el;
       if (!el) return;
       if (el.readyState >= 3) {
         onFullReady();
@@ -299,7 +312,7 @@ function ProgressiveMedia({
         el.removeEventListener("playing", handler);
       };
     },
-    [onFullReady]
+    [onFullReady, externalVideoRef]
   );
   if (!source) {
     if (!placeholder) return null;
@@ -314,8 +327,9 @@ function ProgressiveMedia({
     );
   }
   const effective = !isVideo ? effectiveImageDimensions(image) : null;
-  const w = effective?.width ?? source.width;
-  const h = effective?.height ?? source.height;
+  const w = effective?.width ?? source.width ?? videoSize?.w;
+  const h = effective?.height ?? source.height ?? videoSize?.h;
+  const positioned = objectPosition ? { objectPosition } : void 0;
   const aspect = w && h ? w / h : 16 / 10;
   return /* @__PURE__ */ jsxs(
     "div",
@@ -342,13 +356,14 @@ function ProgressiveMedia({
           "img",
           {
             src: thumbnailUrl,
-            alt: "",
-            "aria-hidden": true,
+            alt: videoFailed ? alt ?? "" : "",
+            "aria-hidden": videoFailed ? void 0 : true,
             width: w,
             height: h,
             loading: priority ? "eager" : "lazy",
             fetchPriority: priority ? "high" : void 0,
-            className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-400 ease-in-out ${stage === "thumbnail" || stage === "full" ? "opacity-100" : "opacity-0"}`
+            className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-400 ease-in-out ${stage === "thumbnail" || stage === "full" ? "opacity-100" : "opacity-0"}`,
+            style: positioned
           }
         ),
         videoActive ? /* @__PURE__ */ jsx2(
@@ -363,8 +378,21 @@ function ProgressiveMedia({
             muted,
             loop,
             playsInline: true,
-            controls: !autoplay,
-            className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-500 ease-in-out ${stage === "full" ? "opacity-100" : "opacity-0"}`
+            controls: showControls,
+            preload,
+            "aria-label": alt || void 0,
+            onLoadedMetadata: (e) => {
+              const v = e.currentTarget;
+              if (!source.width && v.videoWidth && v.videoHeight) {
+                setVideoSize({ w: v.videoWidth, h: v.videoHeight });
+              }
+            },
+            onError: () => {
+              setFailedUrl(video?.url);
+              onVideoError?.();
+            },
+            className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-500 ease-in-out ${stage === "full" || showControls ? "opacity-100" : "opacity-0"}`,
+            style: positioned
           }
         ) : imageActive ? (
           // <picture>: browser picks AVIF when it can decode it, else WebP. The
@@ -383,7 +411,8 @@ function ProgressiveMedia({
                 height: h,
                 loading: priority ? "eager" : "lazy",
                 fetchPriority: priority ? "high" : void 0,
-                className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-500 ease-in-out ${stage === "full" ? "opacity-100" : "opacity-0"}`
+                className: `absolute inset-0 h-full w-full ${fitClass} transition-opacity duration-500 ease-in-out ${stage === "full" ? "opacity-100" : "opacity-0"}`,
+                style: positioned
               }
             )
           ] })

package/dist/next/session.d.ts

@@ -27,8 +27,12 @@ interface PasswordArgs {
 }
 /** Password sign-in in a route handler; persists the session to cookies. */
 export declare function foirSignInWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirUser>;
-/** Register a user in a route handler; persists the session to cookies. */
-export declare function foirRegisterWithPassword({ env, store, email, password, cookieOptions, }: PasswordArgs): Promise<FoirUser>;
+/**
+ * Start a sign-up in a route handler: the address is mailed a code, and
+ * {@link foirSignInWithOtp} with it finishes the account and persists the
+ * session to cookies.
+ */
+export declare function foirRegisterWithPassword({ env, email, password, }: Pick<PasswordArgs, 'env' | 'email' | 'password'>): Promise<void>;
 /** Complete an OTP sign-in in a route handler; persists the session to cookies. */
 export declare function foirSignInWithOtp({ env, store, email, otp, cookieOptions, }: {
     env: FoirEnv;

package/dist/next.js

@@ -1127,8 +1127,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));
@@ -1158,15 +1158,10 @@ function foirSignInWithPassword({
 }
 function foirRegisterWithPassword({
   env,
-  store,
   email,
-  password,
-  cookieOptions
+  password
 }) {
-  return signUpWithPassword(createFoirCookieAdapter(store, { cookieOptions }), env, {
-    email,
-    password
-  });
+  return signUpWithPassword(env, { email, password });
 }
 function foirSignInWithOtp({
   env,

package/dist/placement.js

@@ -70,6 +70,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", [], []],
@@ -80,7 +81,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", [], []],
@@ -111,7 +112,6 @@ var GRANT_TABLE = [
   ["usersecrets:list", "none", [], []],
   ["usersecrets:put", "none", [], []],
   ["usersecrets:delete", "none", [], []],
-  ["auth:login_with_foir", "none", [], []],
   ["signinproviders:read", "none", [], []],
   ["signinproviders:write", "none", [], []]
 ];

package/dist/react/FoirProvider.d.ts

@@ -28,10 +28,14 @@ export interface FoirContextValue {
         email: string;
         password: string;
     }): Promise<FoirUser>;
+    /**
+     * Start a sign-up: the address is mailed a code, and `signInWithOtp` with it
+     * finishes the account and signs them in.
+     */
     register(vars: {
         email: string;
         password: string;
-    }): Promise<FoirUser>;
+    }): Promise<void>;
     requestOtp(email: string): Promise<boolean>;
     signInWithOtp(vars: {
         email: string;
@@ -138,7 +142,7 @@ export declare function useFoirAuth(): {
     register: (vars: {
         email: string;
         password: string;
-    }) => Promise<FoirUser>;
+    }) => Promise<void>;
     requestOtp: (email: string) => Promise<boolean>;
     signInWithOtp: (vars: {
         email: string;

package/dist/react.js

@@ -1133,8 +1133,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));
@@ -1280,6 +1280,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", [], []],
@@ -1290,7 +1291,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", [], []],
@@ -1321,7 +1322,6 @@ var GRANT_TABLE = [
   ["usersecrets:list", "none", [], []],
   ["usersecrets:put", "none", [], []],
   ["usersecrets:delete", "none", [], []],
-  ["auth:login_with_foir", "none", [], []],
   ["signinproviders:read", "none", [], []],
   ["signinproviders:write", "none", [], []]
 ];
@@ -1680,13 +1680,11 @@ function FoirProvider({
     [apply, assertTokenMode]
   );
   const register2 = useCallback(
-    async (vars) => {
+    (vars) => {
       assertTokenMode("register");
-      const c = await signUpWithPassword(adapterRef.current, envRef.current, vars);
-      apply(c);
-      return c;
+      return signUpWithPassword(envRef.current, vars);
     },
-    [apply, assertTokenMode]
+    [assertTokenMode]
   );
   const requestOtp = useCallback(
     (email) => {

package/dist/realtime/index.d.ts

@@ -71,6 +71,12 @@ export interface CreateCollabSessionOptions {
     room: RoomAddress | string;
     /** Async token source. Invoked before the first connect and on each refresh tick. */
     getToken: () => string | Promise<string>;
+    /**
+     * The organization the signed-in user stands at in the room, as a request
+     * names it. Omit for the project. The platform admits the join only where
+     * the user is a member.
+     */
+    orgId?: string;
     /** Caller-owned `Y.Doc` carrying the app-defined shared types. */
     doc: Y.Doc;
     /** Local presence. Sets awareness under the `user` field (contract shape). Omit for no presence. */

package/dist/realtime.js

@@ -39,12 +39,13 @@ function createCollabSession(options) {
     refreshMs = 4 * 60 * 1e3,
     connect = true,
     params: extraParams,
+    orgId,
     WebSocketPolyfill
   } = options;
   const room = roomPath(options.room);
   const provider = new WebsocketProvider(url, room, doc, {
     connect: false,
-    params: { ...extraParams },
+    params: { ...extraParams, ...orgId ? { org: orgId } : {} },
     ...WebSocketPolyfill ? { WebSocketPolyfill } : {}
   });
   const awareness = provider.awareness;

package/dist/server.js

@@ -144,6 +144,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", [], []],
@@ -154,7 +155,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", [], []],
@@ -185,7 +186,6 @@ var GRANT_TABLE = [
   ["usersecrets:list", "none", [], []],
   ["usersecrets:put", "none", [], []],
   ["usersecrets:delete", "none", [], []],
-  ["auth:login_with_foir", "none", [], []],
   ["signinproviders:read", "none", [], []],
   ["signinproviders:write", "none", [], []]
 ];
@@ -1107,8 +1107,18 @@ async function resolveFoirAuth(config) {
     key: { apiKey: config.apiKey, bearerToken }
   };
 }
+var renewing = /* @__PURE__ */ new WeakMap();
+function renewBearerOnce(refresh) {
+  const running = renewing.get(refresh);
+  if (running) return running;
+  const next = refresh().finally(() => renewing.delete(refresh));
+  renewing.set(refresh, next);
+  return next;
+}
 
 // src/data/ws-transport.ts
+var CLOSE_CREDENTIAL_ENDED = 4402;
+var CLOSE_FORBIDDEN = 4403;
 var GQL = {
   connectionInit: "connection_init",
   connectionAck: "connection_ack",
@@ -1143,6 +1153,9 @@ var FoirSocketTransport = class {
   disposed = false;
   keepAlive = null;
   retryTimer = null;
+  // A bearer renewed after the socket's lapsed (4402), presented from the next
+  // connect on in place of the client's own.
+  renewedBearer = null;
   constructor(config) {
     if (config.dispatch !== void 0) {
       throw new FoirRequestError(
@@ -1215,12 +1228,14 @@ var FoirSocketTransport = class {
     socket.onmessage = (event) => this.receive(event.data);
     socket.onerror = () => {
     };
-    socket.onclose = () => this.handleClose();
+    socket.onclose = (event) => this.handleClose(event);
   }
   async sendConnectionInit(socket) {
     this.connecting = false;
     try {
-      const { headers } = await resolveFoirAuth(this.config);
+      const { headers } = await resolveFoirAuth(
+        this.renewedBearer ? { ...this.config, bearerToken: this.renewedBearer } : this.config
+      );
       const { "Content-Type": _contentType, ...params } = headers;
       const extra = await this.config.connectionParams?.() ?? {};
       this.send(socket, {
@@ -1234,19 +1249,53 @@ var FoirSocketTransport = class {
       this.teardownSocket(true);
     }
   }
-  handleClose() {
+  handleClose(event) {
+    const code = event?.code;
     const wasAcknowledged = this.acknowledged;
     this.teardownSocket(false);
     if (this.disposed || this.registrations.size === 0) return;
     for (const registration of this.registrations.values()) {
       registration.sent = false;
     }
+    if (code === CLOSE_FORBIDDEN) {
+      this.failAll(
+        new FoirRequestError(
+          "[foir] the subscription socket was refused where it asked to stand: the signed-in user is no member of the organization this client names"
+        )
+      );
+      return;
+    }
+    if (code === CLOSE_CREDENTIAL_ENDED) {
+      void this.reconnectWithARenewedBearer();
+      return;
+    }
     this.scheduleReconnect(
       new FoirRequestError(
         wasAcknowledged ? "[foir] the subscription socket closed and could not be re-established" : "[foir] the subscription socket closed before the credential was accepted"
       )
     );
   }
+  /**
+   * 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.
+   */
+  async reconnectWithARenewedBearer() {
+    const refresh = this.config.refreshBearer;
+    if (refresh) {
+      const token = await renewBearerOnce(refresh).catch(() => null);
+      if (this.disposed) return;
+      if (!token) {
+        this.failAll(new FoirSessionExpiredError());
+        return;
+      }
+      this.renewedBearer = token;
+    }
+    this.attempt = 0;
+    this.ensureConnected();
+  }
   scheduleReconnect(error) {
     if (this.disposed || this.registrations.size === 0) return;
     if (this.attempt >= this.policy.maxAttempts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -173,12 +173,12 @@
     "react-dom": "^19.2.0",
     "tsup": "^8.5.1",
     "typescript": "5.9.2",
-    "vitest": "^3.2.4",
+    "vitest": "^5.0.5",
     "ws": "^8.18.0",
     "y-websocket": "^3.0.0",
     "yjs": "^13.6.30",
-    "@foir/proto-ts": "0.109.0",
-    "@foir/access-vocab": "0.0.0"
+    "@foir/access-vocab": "0.0.0",
+    "@foir/proto-ts": "0.109.0"
   },
   "engines": {
     "node": ">=18.0.0"