@foir/sdk 0.5.0 → 0.8.0

package/dist/auth/session-client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+export 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. */
+export interface FoirSessionUser {
+    customerId: string;
+    email: string;
+}
+export 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).
+ */
+export declare function createFoirSessionClient(config: FoirSessionConfig): FoirSessionClient;

package/dist/auth-session.js

@@ -0,0 +1,137 @@
+// 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(/\/+$/, "");
+}
+export {
+  createFoirSessionClient
+};