@foir/sdk 0.3.0 → 0.5.0

package/README.md

@@ -24,8 +24,8 @@ pnpm add yjs y-websocket    # for @foir/sdk/realtime
 | --- | --- | --- |
 | `@foir/sdk` | Editor iframe client — `EditorProvider`, `useEditor`, `useAutoResize`, `createPlatformClient`, host↔editor message protocol | `react` |
 | `@foir/sdk/client` | Client-agnostic GraphQL transport for SSR/edge loaders — `foirRequest`, `isFoirPreview`, `absolutiseFoirMediaUrl` | `graphql` |
-| `@foir/sdk/auth` | Framework-agnostic customer auth — login/register/OTP/provider flows, token lifecycle (`SessionAdapter`), `authedRequest`, guards | `graphql` |
-| `@foir/sdk/react` | Drop-in React auth — `<FoirProvider>`, `useFoirSession`/`useFoirUser`/`useFoirAuth`, `<SignIn>`, `<OAuthButtons>`, `<UserButton>` | `react`, `graphql` |
+| `@foir/sdk/auth` | Framework-agnostic customer auth — login/register/OTP/provider flows, token lifecycle (`SessionAdapter`), `createFoirSessionClient` (Foir-hosted cookie sessions), `authedRequest`, guards | `graphql` |
+| `@foir/sdk/react` | Drop-in React auth — `<FoirProvider>` (token or `hostedSession` mode), `useFoirSession`/`useFoirUser`/`useFoirAuth`, `<SignIn>`, `<OAuthButtons>`, `<UserButton>` | `react`, `graphql` |
 | `@foir/sdk/next` | Next.js App Router BFF auth — `createFoirCookieAdapter`, `getFoirSession`, `foirSignIn*`, `completeFoirProviderLogin`, `createFoirMiddleware` | `graphql` |
 | `@foir/sdk/server` | Server-side helpers for extension/config API backends — `createServerClient`, `verifyWebhookSignature`, `verifyScopedToken`, callback client | — |
 | `@foir/sdk/media` | Progressive media — `ProgressiveMedia`, `BlurhashCanvas`, `useProgressiveLoad`, variant-tier adapters | `react` (`hls.js`, `blurhash` optional) |
@@ -108,6 +108,40 @@ function Header() {
 For a custom form, use `useFoirAuth()` (`signIn`, `register`, `signInWithOtp`,
 `requestOtp`, `signInWithProvider`, `signOut`, `getToken`) and `useFoirUser()`.
 
+### Backend-less SPA (Foir-hosted sessions)
+
+By default `<FoirProvider>` stores tokens in `localStorage`. If your SPA has no
+backend but you have a **verified custom login domain** on the same registrable
+domain (`app.acme.com` + `login.acme.com`), prefer `hostedSession`: the durable
+credential becomes an HttpOnly cookie Foir sets on your domain, and the 15-minute
+access token lives only in memory. Nothing authentication-related is reachable
+from JS, so XSS has nothing to exfiltrate — the BFF security posture without a
+backend.
+
+```tsx
+<FoirProvider
+  env={{ PLATFORM_API_URL: 'https://api.foir.dev/graphql', PLATFORM_API_KEY: 'pk_…' }}
+  hostedSession={{ loginOrigin: 'https://login.acme.com' }}
+>
+  <App />
+</FoirProvider>
+```
+
+Sign-in is a redirect, not a form — `useFoirAuth().hostedSignInUrl()` gives you
+the URL (the password/OTP actions throw in this mode). `getToken()` exchanges the
+cookie and re-exchanges it silently before expiry; `signOut()` revokes the session
+server-side. Everything else — `useFoirSession`, `useFoirUser`, `<UserButton>` —
+behaves the same.
+
+Framework-agnostic equivalent:
+
+```ts
+import { createFoirSessionClient } from '@foir/sdk/auth';
+
+const session = createFoirSessionClient({ loginOrigin: 'https://login.acme.com' });
+const token = await session.getToken(); // null when signed out
+```
+
 ### Next.js (App Router, BFF)
 
 `@foir/sdk/next` keeps the tokens in HttpOnly cookies server-side. Protect

package/dist/auth.d.ts

@@ -302,4 +302,81 @@ interface HostedSession {
  */
 declare function fetchHostedSession(request: Request, config: HostedLoginConfig): Promise<HostedSession | null>;
 
-export { type AuthProviderPublic, AuthProvidersDocument, type CustomerAuthResult, CustomerLoginDocument, CustomerLoginOTPDocument, CustomerLoginWithProviderDocument, CustomerProviderCallbackDocument, CustomerProviderVerifyOTPDocument, CustomerRefreshTokenDocument, CustomerRegisterDocument, CustomerRequestOTPDocument, type FoirAuthTokens, type FoirCustomer, type FoirUser, type HostedLoginConfig, type HostedSession, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type RequireAdminOptions, type RequireAuthOptions, type SessionAdapter, authedRequest, clearSession, customerLogin, customerLoginOTP, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, customerRefreshToken, customerRegister, customerRequestOTP, fetchHostedSession, getAuthProviders, getSessionCustomer, getSessionToken, hostedLoginUrl, loginWithOTP, loginWithPassword, refreshSession, registerWithPassword, requireAdmin, requireAuth, saveSession };
+/**
+ * Foir-hosted first-party sessions, from the browser — the model for a
+ * backend-less SPA (Vite, CRA, a static site) that wants no tokens in JS.
+ *
+ * The sibling `fetchHostedSession` in ./hosted does the same exchange from a
+ * SERVER: it reads the cookie off an incoming request and forwards it by hand.
+ * A browser cannot set a `Cookie` header, so that function is unusable from an
+ * SPA by construction. This one lets the browser send the cookie the only way it
+ * can — `credentials: 'include'` — and keeps the resulting bearer in memory.
+ *
+ * How the pieces divide:
+ *
+ *   cookie  — long-lived (30d), HttpOnly, first-party on your registrable
+ *             domain, set by Foir when hosted login finalizes. JS cannot read
+ *             it, so XSS cannot exfiltrate it.
+ *   bearer  — 15 minutes, held in a closure here. Never written to
+ *             localStorage/sessionStorage/IndexedDB, never in a cookie of ours.
+ *
+ * There is no refresh token in this flow. Re-exchanging the cookie IS the
+ * refresh, which is why nothing here needs rotation or reuse-detection: the
+ * durable credential is an opaque server-side session handle, revocable at any
+ * time from the admin panel or `signOut()`.
+ *
+ * REQUIRES a verified custom login domain that shares a registrable domain with
+ * your app (app.acme.com + login.acme.com). That is what makes the cookie
+ * first-party and lets `SameSite=Lax` send it. The same endpoints exist on
+ * api.foir.dev but a browser cannot reach them there — the cookie would be
+ * cross-site, and that CORS surface deliberately refuses credentials.
+ */
+interface FoirSessionConfig {
+    /**
+     * Your verified custom login domain, e.g. `https://login.acme.com`. Must share
+     * a registrable domain with the app calling it.
+     */
+    loginOrigin: string;
+    /** Session-exchange path. Default `/session/token`. */
+    sessionPath?: string;
+    /** Logout path. Default `/session/logout`. */
+    logoutPath?: string;
+    /** Seconds before expiry to re-exchange. Default 60. */
+    refreshSkewSeconds?: number;
+    /**
+     * Called when the session goes away — the cookie expired, was revoked, or
+     * `signOut()` ran. Use it to redirect to `signInUrl()`.
+     */
+    onSignOut?: () => void;
+}
+/** The identity behind the current session. */
+interface FoirSessionUser {
+    customerId: string;
+    email: string;
+}
+interface FoirSessionClient {
+    /**
+     * The current access token, exchanging or re-exchanging the cookie as needed.
+     * Null when there is no session. Concurrent callers share one in-flight
+     * exchange. Call this before each API request — do not cache the result.
+     */
+    getToken(): Promise<string | null>;
+    /** The signed-in customer, or null. Exchanges if the session isn't loaded yet. */
+    getUser(): Promise<FoirSessionUser | null>;
+    /** Revoke the session server-side and clear the cookie. Idempotent. */
+    signOut(): Promise<void>;
+    /** Where to send the browser to sign in. */
+    signInUrl(returnTo?: string): string;
+    /** Observe session changes. Returns an unsubscribe function. */
+    subscribe(listener: (user: FoirSessionUser | null) => void): () => void;
+    /** Cancel the refresh timer. Call on unmount. */
+    destroy(): void;
+}
+/**
+ * Create a session client. Safe to call during SSR — it does nothing until a
+ * method is invoked, and `getToken()` on the server returns null rather than
+ * throwing (there is no cookie jar to draw on).
+ */
+declare function createFoirSessionClient(config: FoirSessionConfig): FoirSessionClient;
+
+export { type AuthProviderPublic, AuthProvidersDocument, type CustomerAuthResult, CustomerLoginDocument, CustomerLoginOTPDocument, CustomerLoginWithProviderDocument, CustomerProviderCallbackDocument, CustomerProviderVerifyOTPDocument, CustomerRefreshTokenDocument, CustomerRegisterDocument, CustomerRequestOTPDocument, type FoirAuthTokens, type FoirCustomer, type FoirSessionClient, type FoirSessionConfig, type FoirSessionUser, type FoirUser, type HostedLoginConfig, type HostedSession, type ProviderCallbackInput, type ProviderLoginInput, type ProviderLoginResult, type ProviderOTPVerifyInput, type RequireAdminOptions, type RequireAuthOptions, type SessionAdapter, authedRequest, clearSession, createFoirSessionClient, customerLogin, customerLoginOTP, customerLoginWithProvider, customerProviderCallback, customerProviderVerifyOTP, customerRefreshToken, customerRegister, customerRequestOTP, fetchHostedSession, getAuthProviders, getSessionCustomer, getSessionToken, hostedLoginUrl, loginWithOTP, loginWithPassword, refreshSession, registerWithPassword, requireAdmin, requireAuth, saveSession };

package/dist/auth.js

@@ -274,6 +274,141 @@ async function fetchHostedSession(request, config) {
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+
+// src/auth/session-client.ts
+var DEFAULT_SESSION_PATH2 = "/session/token";
+var DEFAULT_LOGOUT_PATH = "/session/logout";
+var DEFAULT_REFRESH_SKEW_SECONDS = 60;
+var MIN_REFRESH_DELAY_MS = 5e3;
+var CSRF_HEADER = { "X-Foir-Session": "1" };
+function createFoirSessionClient(config) {
+  const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH2}`;
+  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
+  const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
+  let cached = null;
+  let inflight = null;
+  let timer = null;
+  let destroyed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  function emit(user) {
+    for (const l of listeners) l(user);
+  }
+  function clearTimer() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  function scheduleRefresh(expiresAt) {
+    clearTimer();
+    if (destroyed || typeof setTimeout === "undefined") return;
+    const delay = Math.max(expiresAt - Date.now() - skewMs, MIN_REFRESH_DELAY_MS);
+    timer = setTimeout(() => {
+      void exchange();
+    }, delay);
+    timer.unref?.();
+  }
+  function forget() {
+    const had = cached !== null;
+    cached = null;
+    clearTimer();
+    if (had) emit(null);
+  }
+  function exchange() {
+    if (inflight) return inflight;
+    const pending = (async () => {
+      let res;
+      try {
+        res = await fetch(sessionUrl, {
+          method: "GET",
+          // The whole point: send the first-party cookie cross-origin (but
+          // same-site) to the login domain. Without this the cookie is not sent.
+          credentials: "include",
+          headers: { ...CSRF_HEADER }
+        });
+      } catch {
+        return cached;
+      }
+      if (res.status === 401) {
+        forget();
+        config.onSignOut?.();
+        return null;
+      }
+      if (!res.ok) return cached;
+      let json;
+      try {
+        json = await res.json();
+      } catch {
+        return cached;
+      }
+      if (!json.access_token || !json.customer_id) return cached;
+      const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 0;
+      const next = {
+        token: json.access_token,
+        expiresAt: Date.now() + expiresIn * 1e3,
+        user: { customerId: json.customer_id, email: json.email ?? "" }
+      };
+      const changed = cached?.user.customerId !== next.user.customerId;
+      cached = next;
+      scheduleRefresh(next.expiresAt);
+      if (changed) emit(next.user);
+      return next;
+    })();
+    inflight = pending;
+    void pending.finally(() => {
+      if (inflight === pending) inflight = null;
+    });
+    return pending;
+  }
+  function fresh() {
+    if (!cached) return null;
+    return Date.now() < cached.expiresAt - skewMs ? cached : null;
+  }
+  return {
+    async getToken() {
+      const hit = fresh();
+      if (hit) return hit.token;
+      const got = await exchange();
+      return got?.token ?? null;
+    },
+    async getUser() {
+      const hit = fresh();
+      if (hit) return hit.user;
+      const got = await exchange();
+      return got?.user ?? null;
+    },
+    async signOut() {
+      try {
+        await fetch(logoutUrl, {
+          method: "POST",
+          credentials: "include",
+          headers: { ...CSRF_HEADER }
+        });
+      } catch {
+      }
+      forget();
+      config.onSignOut?.();
+    },
+    signInUrl(returnTo) {
+      const dest = new URL(trimSlash(config.loginOrigin));
+      const target = returnTo ?? (typeof window !== "undefined" ? window.location.href : void 0);
+      if (target && target !== "/") dest.searchParams.set("returnTo", target);
+      return dest.toString();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    destroy() {
+      destroyed = true;
+      clearTimer();
+      listeners.clear();
+    }
+  };
+}
+function trimSlash(s) {
+  return s.replace(/\/+$/, "");
+}
 export {
   AuthProvidersDocument,
   CustomerLoginDocument,
@@ -286,6 +421,7 @@ export {
   CustomerRequestOTPDocument,
   authedRequest,
   clearSession,
+  createFoirSessionClient,
   customerLogin,
   customerLoginOTP,
   customerLoginWithProvider,

package/dist/client.d.ts

@@ -80,4 +80,56 @@ interface FoirRequestOptions {
 }
 declare function foirRequest<TData, TVariables>(env: FoirEnv, document: TypedDocumentNode<TData, TVariables>, variables?: TVariables, options?: FoirRequestOptions): Promise<TData>;
 
-export { FOIR_CDN_BASE, type FoirEnv, FoirRequestError, type FoirRequestOptions, absolutiseFoirMediaUrl, foirRequest, isFoirPreview };
+/**
+ * Session-bound content client — forwards the customer bearer on every read
+ * when one is available, so auth/segment-targeted variants and customer-scoped
+ * records resolve out of the box, with no per-query wiring to forget.
+ *
+ * Resolution keys off the request's principal (see the platform's two-gate
+ * model): the `x-api-key` alone resolves the *anonymous baseline*
+ * (`context.authStatus = ""`); adding the customer bearer resolves the request
+ * as that customer (`context.authStatus = "authenticated"`, `customer_id` set).
+ *
+ * Caching: an api-key-only read is identical for every anonymous visitor and is
+ * shared-cacheable; a bearer-bearing read resolves per-customer and is not.
+ * Because the bearer only exists once a customer signs in, anonymous traffic
+ * keeps hitting the shared-cacheable baseline — only signed-in reads become
+ * per-customer. Bind this client wherever content is personalized (for most
+ * apps, everywhere the customer may be signed in) and use plain `foirRequest`
+ * for reads that must stay anonymous regardless of session.
+ */
+
+/**
+ * Supplies the current customer bearer. Sync or async so consumers can read a
+ * cookie session (Hydrogen/Remix), a KV store, an in-memory value, etc. Returns
+ * the token when signed in, or `null`/`undefined` when signed out.
+ */
+type FoirTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
+interface FoirContentClientConfig {
+    env: FoirEnv;
+    /**
+     * Resolves the current customer bearer before every request. When it yields a
+     * token the token is forwarded, so `authStatus`/segment targeting and
+     * customer-scoped records resolve as that customer; when it yields
+     * null/undefined the read hits the anonymous baseline. Omit for a client that
+     * is always anonymous (equivalent to calling `foirRequest` directly).
+     */
+    getToken?: FoirTokenProvider;
+}
+interface FoirContentClient {
+    /**
+     * Run a typed document, forwarding the bound customer bearer when available.
+     * An explicit `options.bearerToken` still wins, so a single call can override
+     * the bound token (or force anonymous by passing `undefined` — the bound
+     * token only fills in when `options.bearerToken` is not supplied).
+     */
+    request<TData, TVariables>(document: TypedDocumentNode<TData, TVariables>, variables?: TVariables, options?: FoirRequestOptions): Promise<TData>;
+}
+/**
+ * Create a {@link FoirContentClient} bound to an env + token source. Every
+ * `request` forwards the customer bearer when `getToken` yields one, upgrading
+ * that read from the anonymous baseline to the signed-in customer.
+ */
+declare function createFoirContentClient(config: FoirContentClientConfig): FoirContentClient;
+
+export { FOIR_CDN_BASE, type FoirContentClient, type FoirContentClientConfig, type FoirEnv, FoirRequestError, type FoirRequestOptions, type FoirTokenProvider, absolutiseFoirMediaUrl, createFoirContentClient, foirRequest, isFoirPreview };

package/dist/client.js

@@ -72,10 +72,24 @@ async function foirRequest(env, document, variables, options) {
   }
   return json.data;
 }
+
+// src/graphql/content-client.ts
+function createFoirContentClient(config) {
+  return {
+    async request(document, variables, options) {
+      const bound = config.getToken ? await config.getToken() : null;
+      return foirRequest(config.env, document, variables, {
+        ...options,
+        bearerToken: options?.bearerToken ?? bound ?? void 0
+      });
+    }
+  };
+}
 export {
   FOIR_CDN_BASE,
   FoirRequestError,
   absolutiseFoirMediaUrl,
+  createFoirContentClient,
   foirRequest,
   isFoirPreview
 };

package/dist/react.d.ts

@@ -90,6 +90,54 @@ interface SessionAdapter {
     unset(key: string): void | Promise<void>;
 }
 
+/**
+ * Foir-hosted first-party sessions, from the browser — the model for a
+ * backend-less SPA (Vite, CRA, a static site) that wants no tokens in JS.
+ *
+ * The sibling `fetchHostedSession` in ./hosted does the same exchange from a
+ * SERVER: it reads the cookie off an incoming request and forwards it by hand.
+ * A browser cannot set a `Cookie` header, so that function is unusable from an
+ * SPA by construction. This one lets the browser send the cookie the only way it
+ * can — `credentials: 'include'` — and keeps the resulting bearer in memory.
+ *
+ * How the pieces divide:
+ *
+ *   cookie  — long-lived (30d), HttpOnly, first-party on your registrable
+ *             domain, set by Foir when hosted login finalizes. JS cannot read
+ *             it, so XSS cannot exfiltrate it.
+ *   bearer  — 15 minutes, held in a closure here. Never written to
+ *             localStorage/sessionStorage/IndexedDB, never in a cookie of ours.
+ *
+ * There is no refresh token in this flow. Re-exchanging the cookie IS the
+ * refresh, which is why nothing here needs rotation or reuse-detection: the
+ * durable credential is an opaque server-side session handle, revocable at any
+ * time from the admin panel or `signOut()`.
+ *
+ * REQUIRES a verified custom login domain that shares a registrable domain with
+ * your app (app.acme.com + login.acme.com). That is what makes the cookie
+ * first-party and lets `SameSite=Lax` send it. The same endpoints exist on
+ * api.foir.dev but a browser cannot reach them there — the cookie would be
+ * cross-site, and that CORS surface deliberately refuses credentials.
+ */
+interface FoirSessionConfig {
+    /**
+     * Your verified custom login domain, e.g. `https://login.acme.com`. Must share
+     * a registrable domain with the app calling it.
+     */
+    loginOrigin: string;
+    /** Session-exchange path. Default `/session/token`. */
+    sessionPath?: string;
+    /** Logout path. Default `/session/logout`. */
+    logoutPath?: string;
+    /** Seconds before expiry to re-exchange. Default 60. */
+    refreshSkewSeconds?: number;
+    /**
+     * Called when the session goes away — the cookie expired, was revoked, or
+     * `signOut()` ran. Use it to redirect to `signInUrl()`.
+     */
+    onSignOut?: () => void;
+}
+
 /** Where the session hydration stands. */
 type FoirStatus = 'loading' | 'authenticated' | 'unauthenticated';
 /** The full context value. Read it through the hooks below, not directly. */
@@ -126,20 +174,46 @@ interface FoirContextValue {
     getToken(): Promise<string | null>;
     /** The project's configured auth providers (for OAuth buttons). */
     getProviders(): Promise<AuthProviderPublic[]>;
+    /**
+     * In `hostedSession` mode, where to send the browser to sign in — sign-in is a
+     * redirect to your Foir login domain, not an in-page form. Null in token mode,
+     * where you call {@link FoirContextValue.signIn} instead.
+     */
+    hostedSignInUrl: ((returnTo?: string) => string) | null;
 }
 interface FoirProviderProps {
     /** API config: `{ PLATFORM_API_URL, PLATFORM_API_KEY }` (a publishable `pk_` key). */
     env: FoirEnv;
-    /** Session store. Defaults to a browser localStorage adapter. */
+    /** Session store for token mode. Defaults to a browser localStorage adapter. */
     adapter?: SessionAdapter;
+    /**
+     * Opt into Foir-hosted first-party sessions: the durable credential is an
+     * HttpOnly cookie on your own domain and the access token lives only in
+     * memory, so nothing authentication-related is reachable from JS. This is the
+     * secure default for a backend-less SPA, and it REPLACES `adapter` — pass one
+     * or the other, not both.
+     *
+     * Requires a verified custom login domain sharing a registrable domain with
+     * your app (`app.acme.com` + `login.acme.com`). Sign-in becomes a redirect to
+     * {@link FoirContextValue.hostedSignInUrl}; the password/OTP/provider actions
+     * do not apply and will throw.
+     */
+    hostedSession?: Omit<FoirSessionConfig, 'onSignOut'>;
     children: ReactNode;
 }
 /**
- * Provides Foir customer auth to a React tree. Hydrates the stored session on
- * mount, then exposes the current customer and sign-in/out actions through
+ * Provides Foir customer auth to a React tree. Hydrates the session on mount,
+ * then exposes the current customer and sign-in/out actions through
  * {@link useFoirSession}, {@link useFoirUser}, and {@link useFoirAuth}.
+ *
+ * Two session models:
+ *
+ *   default          tokens in a `SessionAdapter` (localStorage unless you pass
+ *                    your own). Simple, but a refresh token sits in JS.
+ *   `hostedSession`  Foir-hosted first-party cookie; the bearer never leaves
+ *                    memory. Needs a custom login domain. Prefer this.
  */
-declare function FoirProvider({ env, adapter, children }: FoirProviderProps): react_jsx_runtime.JSX.Element;
+declare function FoirProvider({ env, adapter, hostedSession, children, }: FoirProviderProps): react_jsx_runtime.JSX.Element;
 /** The current session state. */
 interface FoirSession {
     status: FoirStatus;
@@ -174,6 +248,7 @@ declare function useFoirAuth(): {
     refresh: () => Promise<boolean>;
     getToken: () => Promise<string | null>;
     getProviders: () => Promise<AuthProviderPublic[]>;
+    hostedSignInUrl: ((returnTo?: string) => string) | null;
 };
 
 interface SignInProps {

package/dist/react.js

@@ -202,6 +202,141 @@ async function refreshSession(adapter, env) {
   }
 }
 
+// src/auth/session-client.ts
+var DEFAULT_SESSION_PATH = "/session/token";
+var DEFAULT_LOGOUT_PATH = "/session/logout";
+var DEFAULT_REFRESH_SKEW_SECONDS = 60;
+var MIN_REFRESH_DELAY_MS = 5e3;
+var CSRF_HEADER = { "X-Foir-Session": "1" };
+function createFoirSessionClient(config) {
+  const sessionUrl = `${trimSlash(config.loginOrigin)}${config.sessionPath ?? DEFAULT_SESSION_PATH}`;
+  const logoutUrl = `${trimSlash(config.loginOrigin)}${config.logoutPath ?? DEFAULT_LOGOUT_PATH}`;
+  const skewMs = (config.refreshSkewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS) * 1e3;
+  let cached = null;
+  let inflight = null;
+  let timer = null;
+  let destroyed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  function emit(user) {
+    for (const l of listeners) l(user);
+  }
+  function clearTimer() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  function scheduleRefresh(expiresAt) {
+    clearTimer();
+    if (destroyed || typeof setTimeout === "undefined") return;
+    const delay = Math.max(expiresAt - Date.now() - skewMs, MIN_REFRESH_DELAY_MS);
+    timer = setTimeout(() => {
+      void exchange();
+    }, delay);
+    timer.unref?.();
+  }
+  function forget() {
+    const had = cached !== null;
+    cached = null;
+    clearTimer();
+    if (had) emit(null);
+  }
+  function exchange() {
+    if (inflight) return inflight;
+    const pending = (async () => {
+      let res;
+      try {
+        res = await fetch(sessionUrl, {
+          method: "GET",
+          // The whole point: send the first-party cookie cross-origin (but
+          // same-site) to the login domain. Without this the cookie is not sent.
+          credentials: "include",
+          headers: { ...CSRF_HEADER }
+        });
+      } catch {
+        return cached;
+      }
+      if (res.status === 401) {
+        forget();
+        config.onSignOut?.();
+        return null;
+      }
+      if (!res.ok) return cached;
+      let json;
+      try {
+        json = await res.json();
+      } catch {
+        return cached;
+      }
+      if (!json.access_token || !json.customer_id) return cached;
+      const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 0;
+      const next = {
+        token: json.access_token,
+        expiresAt: Date.now() + expiresIn * 1e3,
+        user: { customerId: json.customer_id, email: json.email ?? "" }
+      };
+      const changed = cached?.user.customerId !== next.user.customerId;
+      cached = next;
+      scheduleRefresh(next.expiresAt);
+      if (changed) emit(next.user);
+      return next;
+    })();
+    inflight = pending;
+    void pending.finally(() => {
+      if (inflight === pending) inflight = null;
+    });
+    return pending;
+  }
+  function fresh() {
+    if (!cached) return null;
+    return Date.now() < cached.expiresAt - skewMs ? cached : null;
+  }
+  return {
+    async getToken() {
+      const hit = fresh();
+      if (hit) return hit.token;
+      const got = await exchange();
+      return got?.token ?? null;
+    },
+    async getUser() {
+      const hit = fresh();
+      if (hit) return hit.user;
+      const got = await exchange();
+      return got?.user ?? null;
+    },
+    async signOut() {
+      try {
+        await fetch(logoutUrl, {
+          method: "POST",
+          credentials: "include",
+          headers: { ...CSRF_HEADER }
+        });
+      } catch {
+      }
+      forget();
+      config.onSignOut?.();
+    },
+    signInUrl(returnTo) {
+      const dest = new URL(trimSlash(config.loginOrigin));
+      const target = returnTo ?? (typeof window !== "undefined" ? window.location.href : void 0);
+      if (target && target !== "/") dest.searchParams.set("returnTo", target);
+      return dest.toString();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    destroy() {
+      destroyed = true;
+      clearTimer();
+      listeners.clear();
+    }
+  };
+}
+function trimSlash(s) {
+  return s.replace(/\/+$/, "");
+}
+
 // src/react/localStorageAdapter.ts
 function createLocalStorageAdapter() {
   const store = () => {
@@ -225,7 +360,17 @@ function createLocalStorageAdapter() {
 // src/react/FoirProvider.tsx
 import { jsx } from "react/jsx-runtime";
 var FoirContext = createContext(null);
-function FoirProvider({ env, adapter, children }) {
+function FoirProvider({
+  env,
+  adapter,
+  hostedSession,
+  children
+}) {
+  if (process.env.NODE_ENV !== "production" && adapter && hostedSession) {
+    console.warn(
+      "[foir] FoirProvider: `adapter` is ignored when `hostedSession` is set \u2014 the hosted session keeps the access token in memory and never persists it."
+    );
+  }
   const envRef = useRef(env);
   envRef.current = env;
   const adapterRef = useRef(adapter ?? createLocalStorageAdapter());
@@ -236,46 +381,86 @@ function FoirProvider({ env, adapter, children }) {
     setCustomer(c);
     setStatus(c ? "authenticated" : "unauthenticated");
   }, []);
+  const loginOrigin = hostedSession?.loginOrigin;
+  const sessionPath = hostedSession?.sessionPath;
+  const logoutPath = hostedSession?.logoutPath;
+  const refreshSkewSeconds = hostedSession?.refreshSkewSeconds;
+  const hosted = useMemo(() => {
+    if (!loginOrigin) return null;
+    return createFoirSessionClient({
+      loginOrigin,
+      sessionPath,
+      logoutPath,
+      refreshSkewSeconds,
+      onSignOut: () => apply(null)
+    });
+  }, [loginOrigin, sessionPath, logoutPath, refreshSkewSeconds, apply]);
   useEffect(() => {
     let cancelled = false;
     void (async () => {
+      if (hosted) {
+        const u = await hosted.getUser();
+        if (!cancelled) apply(u ? { id: u.customerId, email: u.email } : null);
+        return;
+      }
       const c = await getSessionCustomer(adapterRef.current);
       if (!cancelled) apply(c);
     })();
     return () => {
       cancelled = true;
     };
-  }, [apply]);
+  }, [apply, hosted]);
+  useEffect(() => {
+    if (!hosted) return;
+    return () => hosted.destroy();
+  }, [hosted]);
+  const assertTokenMode = useCallback(
+    (action) => {
+      if (hosted) {
+        throw new Error(
+          `[foir] ${action}() is not available in hostedSession mode \u2014 the customer signs in at your Foir login domain. Redirect to hostedSignInUrl() instead.`
+        );
+      }
+    },
+    [hosted]
+  );
   const signIn = useCallback(
     async (vars) => {
+      assertTokenMode("signIn");
       const c = await loginWithPassword(adapterRef.current, envRef.current, vars);
       apply(c);
       return c;
     },
-    [apply]
+    [apply, assertTokenMode]
   );
   const register = useCallback(
     async (vars) => {
+      assertTokenMode("register");
       const c = await registerWithPassword(adapterRef.current, envRef.current, vars);
       apply(c);
       return c;
     },
-    [apply]
+    [apply, assertTokenMode]
   );
   const requestOtp = useCallback(
-    (email) => customerRequestOTP(envRef.current, email),
-    []
+    (email) => {
+      assertTokenMode("requestOtp");
+      return customerRequestOTP(envRef.current, email);
+    },
+    [assertTokenMode]
   );
   const signInWithOtp = useCallback(
     async (vars) => {
+      assertTokenMode("signInWithOtp");
       const c = await loginWithOTP(adapterRef.current, envRef.current, vars);
       apply(c);
       return c;
     },
-    [apply]
+    [apply, assertTokenMode]
   );
   const signInWithProvider = useCallback(
     async (providerKey, opts) => {
+      assertTokenMode("signInWithProvider");
       const res = await customerLoginWithProvider(envRef.current, {
         providerKey,
         ...opts
@@ -284,31 +469,46 @@ function FoirProvider({ env, adapter, children }) {
         window.location.assign(res.redirectUrl);
       }
     },
-    []
+    [assertTokenMode]
   );
   const completeProviderLogin = useCallback(
     async (input) => {
+      assertTokenMode("completeProviderLogin");
       const result = await customerProviderCallback(envRef.current, input);
       const c = await saveSession(adapterRef.current, result);
       apply(c);
       return c;
     },
-    [apply]
+    [apply, assertTokenMode]
   );
   const signOut = useCallback(async () => {
+    if (hosted) {
+      await hosted.signOut();
+      return;
+    }
     await clearSession(adapterRef.current);
     apply(null);
-  }, [apply]);
+  }, [apply, hosted]);
   const refresh = useCallback(async () => {
+    if (hosted) {
+      return await hosted.getToken() !== null;
+    }
     const tokens = await refreshSession(adapterRef.current, envRef.current);
     if (!tokens) {
       apply(null);
       return false;
     }
     return true;
-  }, [apply]);
-  const getToken = useCallback(() => getSessionToken(adapterRef.current), []);
+  }, [apply, hosted]);
+  const getToken = useCallback(
+    () => hosted ? hosted.getToken() : getSessionToken(adapterRef.current),
+    [hosted]
+  );
   const getProviders = useCallback(() => getAuthProviders(envRef.current), []);
+  const hostedSignInUrl = useMemo(
+    () => hosted ? (returnTo) => hosted.signInUrl(returnTo) : null,
+    [hosted]
+  );
   const value = useMemo(
     () => ({
       status,
@@ -324,7 +524,8 @@ function FoirProvider({ env, adapter, children }) {
       signOut,
       refresh,
       getToken,
-      getProviders
+      getProviders,
+      hostedSignInUrl
     }),
     [
       status,
@@ -339,7 +540,8 @@ function FoirProvider({ env, adapter, children }) {
       signOut,
       refresh,
       getToken,
-      getProviders
+      getProviders,
+      hostedSignInUrl
     ]
   );
   return /* @__PURE__ */ jsx(FoirContext.Provider, { value, children });
@@ -374,7 +576,8 @@ function useFoirAuth() {
     signOut,
     refresh,
     getToken,
-    getProviders
+    getProviders,
+    hostedSignInUrl
   } = useFoirContext();
   return {
     signIn,
@@ -386,7 +589,8 @@ function useFoirAuth() {
     signOut,
     refresh,
     getToken,
-    getProviders
+    getProviders,
+    hostedSignInUrl
   };
 }
 

package/dist/server.d.ts

@@ -519,8 +519,8 @@ interface CallbackClient<TResult = unknown> {
  * payload structure on every call.
  *
  * `signingSecret` lives on the extension (set as `FOIR_SIGNING_SECRET` or
- * equivalent env var). The CLI publishes it during `foir push` so it's
- * available before any callback runs — see foir-cli writeConfigCredential.
+ * equivalent env var). `foir push` writes it there from the project's
+ * signing secret, so it's available before any callback runs.
  *
  * `fetch` is overridable for testability and to support runtimes (CF
  * Workers, Node) where `fetch` may not be the global.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {