@tribe-nest/forge 2.2.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "2.2.0",
+  "version": "3.2.0",
   "publishConfig": {
     "access": "public"
   },

package/src/client/createForgeClient.ts

@@ -1,4 +1,21 @@
-import axios, { type AxiosInstance } from "axios";
+import axios, { type AxiosError, type AxiosInstance } from "axios";
+
+/**
+ * Access-token refresh (backend §7 cutover). Access tokens live ~15 minutes;
+ * when a request 401s the client exchanges the refresh token at `path` for a
+ * new pair and retries once. The refresh token ROTATES on every exchange, so
+ * `onRefreshed` must persist the new one.
+ */
+export interface ForgeClientRefreshOptions {
+  /** Exchange endpoint for this lane, e.g. "/public/sessions/refresh". */
+  path: string;
+  /** The current refresh token, or null when anonymous (no refresh attempted). */
+  getRefreshToken: () => string | null;
+  /** Persist the rotated pair and update whatever backs `getToken`. */
+  onRefreshed: (tokens: { token: string; refreshToken: string }) => void;
+  /** The chain is dead (revoked/expired/reused) — clear stored tokens. */
+  onFailed: () => void;
+}
 
 export interface ForgeClientOptions {
   /** Base URL of the TribeNest public API, e.g. https://api.tribenest.co */
@@ -13,6 +30,8 @@ export interface ForgeClientOptions {
    * place (Component 1) this is sent on every request to scope reads to the tenant.
    */
   publishableKey?: string;
+  /** Enable 401-triggered refresh-and-retry for this client's auth lane. */
+  refresh?: ForgeClientRefreshOptions;
 }
 
 /**
@@ -22,7 +41,12 @@ export interface ForgeClientOptions {
  * the base URL is injected (no `process.env`), the token is read per-request via a
  * closure, and `localStorage` access is SSR-guarded so the client is safe on Workers.
  */
-export const createForgeClient = ({ baseURL, getToken, publishableKey }: ForgeClientOptions): AxiosInstance => {
+export const createForgeClient = ({
+  baseURL,
+  getToken,
+  publishableKey,
+  refresh,
+}: ForgeClientOptions): AxiosInstance => {
   const client = axios.create({ baseURL });
 
   client.interceptors.request.use((config) => {
@@ -44,6 +68,65 @@ export const createForgeClient = ({ baseURL, getToken, publishableKey }: ForgeCl
     return config;
   });
 
+  if (refresh) {
+    // Single-flight: concurrent 401s (a page of queries expiring together) must
+    // produce ONE exchange — the refresh token rotates on use, so parallel
+    // exchanges would race each other through the server's grace window.
+    let inFlight: Promise<string | null> | null = null;
+
+    const exchange = (): Promise<string | null> => {
+      if (!inFlight) {
+        inFlight = (async () => {
+          const refreshToken = refresh.getRefreshToken();
+          if (!refreshToken) return null;
+          try {
+            // Bare axios on purpose — the shared client would recurse through
+            // this very interceptor.
+            const res = await axios.post(
+              `${baseURL}${refresh.path}`,
+              { refreshToken },
+              publishableKey ? { headers: { "x-forge-key": publishableKey } } : undefined,
+            );
+            const next = res.data as { token: string; refreshToken: string };
+            refresh.onRefreshed(next);
+            return next.token;
+          } catch {
+            refresh.onFailed();
+            return null;
+          } finally {
+            setTimeout(() => {
+              inFlight = null;
+            });
+          }
+        })();
+      }
+      return inFlight;
+    };
+
+    client.interceptors.response.use(
+      (response) => response,
+      async (error: AxiosError) => {
+        const config = error.config as (typeof error.config & { _retriedAfterRefresh?: boolean }) | undefined;
+        if (
+          error.response?.status === 401 &&
+          config &&
+          !config._retriedAfterRefresh &&
+          !config.url?.includes(refresh.path) &&
+          refresh.getRefreshToken()
+        ) {
+          const token = await exchange();
+          if (token) {
+            config._retriedAfterRefresh = true;
+            config.headers = config.headers ?? {};
+            config.headers["authorization"] = `Bearer ${token}`;
+            return client.request(config);
+          }
+        }
+        return Promise.reject(error);
+      },
+    );
+  }
+
   return client;
 };
 

package/src/client/tokenStorage.ts

@@ -0,0 +1,31 @@
+// localStorage keys for the two auth lanes a Forge site can carry. They live
+// here (not in the auth contexts) so the client factory and both contexts can
+// share them without an import cycle. The fan/member and app-user lanes are
+// deliberately separate pairs — an app-user session must never collide with a
+// profile session on the same site.
+//
+// Access tokens are ~15 minutes now (backend §7 cutover); the refresh token is
+// the long-lived credential and ROTATES on every exchange — always store the
+// one that came back, never re-use the one you sent.
+
+export const PUBLIC_ACCESS_TOKEN_KEY = "public-access-token";
+export const PUBLIC_REFRESH_TOKEN_KEY = "public-refresh-token";
+
+export const APP_ACCESS_TOKEN_KEY = "app-access-token";
+export const APP_REFRESH_TOKEN_KEY = "app-refresh-token";
+
+const canStore = () => typeof localStorage !== "undefined";
+
+export const readStoredToken = (key: string): string | null => (canStore() ? localStorage.getItem(key) : null);
+
+export const storeTokenPair = (accessKey: string, refreshKey: string, token: string, refreshToken?: string) => {
+  if (!canStore()) return;
+  localStorage.setItem(accessKey, token);
+  if (refreshToken) localStorage.setItem(refreshKey, refreshToken);
+};
+
+export const clearTokenPair = (accessKey: string, refreshKey: string) => {
+  if (!canStore()) return;
+  localStorage.removeItem(accessKey);
+  localStorage.removeItem(refreshKey);
+};

package/src/contexts/AppAuthContext.tsx

@@ -2,6 +2,13 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { useForge } from "../provider/ForgeProvider";
 import { createForgeClient } from "../client/createForgeClient";
+import {
+  APP_ACCESS_TOKEN_KEY as APP_ACCESS_KEY,
+  APP_REFRESH_TOKEN_KEY,
+  clearTokenPair,
+  readStoredToken,
+  storeTokenPair,
+} from "../client/tokenStorage";
 
 // App-user auth for a mini-app frontend (account_associations type='app'). This
 // is the app's OWN user base — distinct from TribeNest fans (usePublicAuth) and
@@ -9,7 +16,8 @@ import { createForgeClient } from "../client/createForgeClient";
 // client (its own localStorage key) so an app-user session never collides with a
 // profile session on the same site. Backed by /public/app-sessions/*.
 
-export const APP_ACCESS_TOKEN_KEY = "app-access-token";
+// Kept for compat — the canonical constant lives in client/tokenStorage.ts.
+export const APP_ACCESS_TOKEN_KEY = APP_ACCESS_KEY;
 
 export interface AppAuthUser {
   id: string;
@@ -38,9 +46,19 @@ export interface AppSignupInput {
   lastName?: string;
 }
 
-export type AppSignupResult =
-  | { status: "pending"; user: AppAuthUser }
-  | { status: "active"; user: AppAuthUser };
+/**
+ * What BOTH `signup` and `login` return: the platform emailed a 6-digit code and
+ * issued no session. Collect the code and call `verifyCode`. Neither entry point
+ * has a variant that logs a user straight in.
+ */
+export type AppAuthChallenge = { status: "verify_email"; email: string };
+
+/**
+ * The outcome of redeeming the code. `active` means signed in (token stored).
+ * `pending` means the address is proven but this app requires OWNER APPROVAL, so
+ * there is still no session — show a "waiting for approval" screen.
+ */
+export type AppAuthResult = { status: "pending"; user: AppAuthUser } | { status: "active"; user: AppAuthUser };
 
 interface AppAuthContextType {
   appId?: string;
@@ -49,10 +67,26 @@ interface AppAuthContextType {
   isInitialized: boolean;
   isLoading: boolean;
   errorMessage: string | null;
-  /** Sign up. When the app requires owner approval, returns status "pending" and
-   *  does NOT log the user in (no token) — show a "pending approval" screen. */
-  signup: (input: AppSignupInput) => Promise<AppSignupResult>;
-  login: (input: { email: string; password: string }) => Promise<void>;
+  /**
+   * Step 1 of 2. Creates the account and emails a 6-digit code; it NEVER logs the
+   * user in. Always returns `{ status: "verify_email" }` — including for an email
+   * the platform has never seen, so the response can't be used to discover which
+   * addresses are already registered. Collect the code, then call `verifyCode`.
+   */
+  signup: (input: AppSignupInput) => Promise<AppAuthChallenge>;
+  /**
+   * Step 1 of 2. Checks the password and emails a 6-digit code — it does NOT
+   * return a session. Collect the code and call `verifyCode`. (App login is
+   * two-factor by design; a wrong password still fails here, before any code.)
+   */
+  login: (input: { email: string; password: string }) => Promise<AppAuthChallenge>;
+  /**
+   * Step 2 of 2 for BOTH signup and login. Redeems the emailed code. On success
+   * the user is signed in (`active`) unless this app requires owner approval, in
+   * which case the address is proven but the session still waits (`pending`) —
+   * proving your email is not the owner approving you.
+   */
+  verifyCode: (input: { email: string; code: string }) => Promise<AppAuthResult>;
   logout: () => Promise<void>;
   refetch: () => Promise<void>;
   clearError: () => void;
@@ -80,7 +114,26 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
   // client (which carries the profile/member token).
   const tokenRef = useRef<string | null>(null);
   const client = useMemo(
-    () => createForgeClient({ baseURL: apiUrl, publishableKey, getToken: () => tokenRef.current }),
+    () =>
+      createForgeClient({
+        baseURL: apiUrl,
+        publishableKey,
+        getToken: () => tokenRef.current,
+        // App-user lane (backend §7): same 15-minute access tokens, own refresh
+        // chain on its own storage keys so it never collides with a fan session.
+        refresh: {
+          path: "/public/app-sessions/refresh",
+          getRefreshToken: () => readStoredToken(APP_REFRESH_TOKEN_KEY),
+          onRefreshed: ({ token: next, refreshToken }) => {
+            tokenRef.current = next;
+            storeTokenPair(APP_ACCESS_TOKEN_KEY, APP_REFRESH_TOKEN_KEY, next, refreshToken);
+          },
+          onFailed: () => {
+            tokenRef.current = null;
+            clearTokenPair(APP_ACCESS_TOKEN_KEY, APP_REFRESH_TOKEN_KEY);
+          },
+        },
+      }),
     [apiUrl, publishableKey],
   );
 
@@ -127,13 +180,41 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       setErrorMessage(null);
       try {
         const res = await client.post("/public/app-sessions/signup", { appId, ...input });
-        const { status, account, token } = res.data as { status: "pending" | "active"; account: AppAuthUser; token?: string };
+        const { email } = res.data as { status: "verify_email"; email: string };
+        // No token here, by design — see AppAuthChallenge.
+        return { status: "verify_email", email };
+      } catch (err) {
+        setErrorMessage(extractError(err));
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [appId, client],
+  );
+
+  const verifyCode = useCallback<AppAuthContextType["verifyCode"]>(
+    async ({ email, code }) => {
+      if (!appId) throw new Error("AppAuthProvider: no appId in Forge context.");
+      setIsLoading(true);
+      setErrorMessage(null);
+      try {
+        const res = await client.post("/public/app-sessions/verify", { appId, email, code });
+        const { status, account, token, refreshToken } = res.data as {
+          status: "pending" | "active";
+          account: AppAuthUser;
+          token?: string;
+          refreshToken?: string;
+        };
         if (status === "active" && token) {
           setToken(token);
+          if (refreshToken && typeof localStorage !== "undefined") {
+            localStorage.setItem(APP_REFRESH_TOKEN_KEY, refreshToken);
+          }
           setUser(account);
           return { status: "active", user: account };
         }
-        // Pending approval — no token issued.
+        // Email proven, but the owner still has to approve — no token issued.
         return { status: "pending", user: account };
       } catch (err) {
         setErrorMessage(extractError(err));
@@ -152,8 +233,10 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       setErrorMessage(null);
       try {
         const res = await client.post("/public/app-sessions", { appId, ...input });
-        setToken(res.data.token);
-        setUser(res.data.account);
+        // The password was checked, but no session is issued until the emailed
+        // code is redeemed — see AppAuthChallenge.
+        const { email } = res.data as { status: "verify_email"; email: string };
+        return { status: "verify_email", email };
       } catch (err) {
         setErrorMessage(extractError(err));
         throw err;
@@ -161,7 +244,7 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
         setIsLoading(false);
       }
     },
-    [appId, client, setToken],
+    [appId, client],
   );
 
   const logout = useCallback<AppAuthContextType["logout"]>(async () => {
@@ -171,6 +254,7 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       // best-effort — clear locally regardless
     }
     setToken(null);
+    if (typeof localStorage !== "undefined") localStorage.removeItem(APP_REFRESH_TOKEN_KEY);
     setUser(null);
   }, [client, setToken]);
 
@@ -184,6 +268,7 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       errorMessage,
       signup,
       login,
+      verifyCode,
       logout,
       refetch,
       clearError: () => setErrorMessage(null),
@@ -192,7 +277,7 @@ export function AppAuthProvider({ children }: { children: ReactNode }) {
       // crash in a render guard is worse than a hidden button.
       hasPermission: (permission: string) => (user?.permissions ?? []).includes(permission),
     }),
-    [appId, user, isInitialized, isLoading, errorMessage, signup, login, logout, refetch],
+    [appId, user, isInitialized, isLoading, errorMessage, signup, login, verifyCode, logout, refetch],
   );
 
   return <AppAuthContext.Provider value={value}>{children}</AppAuthContext.Provider>;

package/src/contexts/PublicAuthContext.tsx

@@ -23,8 +23,16 @@ enum Types {
   UpdateUser = "UPDATE_USER",
   UpdateErrorMessage = "UPDATE_ERROR_MESSAGE",
 }
-export const ACCESS_TOKEN_KEY = "public-access-token";
-export const PUBLIC_ACCESS_TOKEN_KEY = "public-access-token";
+import {
+  PUBLIC_ACCESS_TOKEN_KEY,
+  PUBLIC_REFRESH_TOKEN_KEY,
+  clearTokenPair,
+  storeTokenPair,
+} from "../client/tokenStorage";
+
+// Kept for compat — the canonical constants live in client/tokenStorage.ts.
+export const ACCESS_TOKEN_KEY = PUBLIC_ACCESS_TOKEN_KEY;
+export { PUBLIC_ACCESS_TOKEN_KEY };
 
 type AuthPayload = {
   [Types.Initial]: { isAuthenticated: boolean; user: PublicAuthUser | null };
@@ -198,8 +206,8 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
 
     try {
       const response = await client.post("/public/sessions", data);
-      const { token, account, smartLinkPath } = response.data;
-      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      const { token, refreshToken, account, smartLinkPath } = response.data;
+      storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, token, refreshToken);
       setToken(token);
       dispatch({ type: Types.Login, payload: { user: account } });
       return { smartLinkPath };
@@ -220,8 +228,8 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
 
     try {
       const response = await client.post("/public/sessions/verify", { email, code, profileId });
-      const { token, account, smartLinkPath } = response.data;
-      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      const { token, refreshToken, account, smartLinkPath } = response.data;
+      storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, token, refreshToken);
       setToken(token);
       dispatch({ type: Types.Login, payload: { user: account } });
       return { smartLinkPath };
@@ -264,8 +272,36 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
       const response = await client.post("/public/accounts", {
         ...data,
       });
-      const { token, account, smartLinkPath } = response.data;
-      localStorage.setItem(ACCESS_TOKEN_KEY, token);
+      // No token: signup issues no session until the emailed code is redeemed
+      // (see PublicAuthChallenge). Keep the caller's data — `verifyRegistration`
+      // needs the coupon/consent flags again to finish the job.
+      const { email } = response.data as { status: "verify_email"; email: string };
+      dispatch({ type: Types.Loading, payload: { isLoading: false } });
+      return { status: "verify_email" as const, email };
+    } catch (err: unknown) {
+      const error = err as ApiError;
+      dispatch({ type: Types.Loading, payload: { isLoading: false } });
+      throw error;
+    }
+  };
+
+  const verifyRegistration = async (data: {
+    email: string;
+    code: string;
+    profileId?: string;
+    couponCode?: string;
+    acceptedTerms?: boolean;
+    acceptedPrivacy?: boolean;
+  }) => {
+    dispatch({ type: Types.Loading, payload: { isLoading: true } });
+
+    try {
+      const response = await client.post("/public/accounts/verify", {
+        ...data,
+        profileId: data.profileId ?? profileId,
+      });
+      const { token, refreshToken, account, smartLinkPath } = response.data;
+      storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, token, refreshToken);
       setToken(token);
 
       dispatch({ type: Types.Register, payload: { user: account } });
@@ -279,7 +315,7 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
 
   const logout = async (persist = true) => {
     try {
-      localStorage.removeItem(ACCESS_TOKEN_KEY);
+      clearTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY);
       dispatch({ type: Types.Logout });
       if (persist) await client.delete("/sessions");
     } catch (error) {
@@ -308,6 +344,7 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
         resendLoginCode,
         logout,
         register,
+        verifyRegistration,
         updateLocalUser,
         clearErrorMessage,
         refetchUser,

package/src/data/queries/useCourseAccess.ts

@@ -38,7 +38,7 @@ export function useClaimCourseAccess() {
   const { client } = useForge();
 
   return useMutation<
-    { token?: string; accessId?: string },
+    { token?: string; refreshToken?: string; accessId?: string },
     unknown,
     { token: string; password: string; firstName: string; lastName: string }
   >({

package/src/index.ts

@@ -11,7 +11,12 @@ export type { ForgeClientOptions } from "./client/createForgeClient";
 // + theme). Most sites import just this.
 export { ForgeProvider, type ForgeProviderProps } from "./provider/ForgeAppProvider";
 // Low-level pieces for hand-composing the tree.
-export { ForgeClientProvider, useForge, type ForgeClientProviderProps, type ForgeContextValue } from "./provider/ForgeProvider";
+export {
+  ForgeClientProvider,
+  useForge,
+  type ForgeClientProviderProps,
+  type ForgeContextValue,
+} from "./provider/ForgeProvider";
 export { SiteConfigProvider, useInitialSiteConfig } from "./provider/SiteConfigProvider";
 
 // All domain types + enums/consts (models) and WebPage.
@@ -30,6 +35,8 @@ export {
   PublicAuthContext,
 } from "./contexts/PublicAuthContext";
 export type { AuthActions } from "./contexts/PublicAuthContext";
+export { PUBLIC_REFRESH_TOKEN_KEY, APP_REFRESH_TOKEN_KEY } from "./client/tokenStorage";
+export { safeRedirectPath } from "./utils/safeRedirect";
 // App-user auth (mini-apps) + the /admin guard.
 export {
   useAppAuth,
@@ -37,7 +44,8 @@ export {
   APP_ACCESS_TOKEN_KEY,
   type AppAuthUser,
   type AppSignupInput,
-  type AppSignupResult,
+  type AppAuthChallenge,
+  type AppAuthResult,
 } from "./contexts/AppAuthContext";
 export { useAppAdminGuard, type AppAdminGuardResult } from "./contexts/useAppAdminGuard";
 

package/src/provider/ForgeProvider.tsx

@@ -1,6 +1,13 @@
 import { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
 import type { AxiosInstance } from "axios";
 import { createForgeClient } from "../client/createForgeClient";
+import {
+  PUBLIC_ACCESS_TOKEN_KEY,
+  PUBLIC_REFRESH_TOKEN_KEY,
+  clearTokenPair,
+  readStoredToken,
+  storeTokenPair,
+} from "../client/tokenStorage";
 
 export interface ForgeContextValue {
   /** Base URL of the TribeNest public API. */
@@ -69,7 +76,29 @@ export const ForgeClientProvider = ({
   }, []);
 
   const client = useMemo(
-    () => createForgeClient({ baseURL: apiUrl, publishableKey, getToken: () => tokenRef.current }),
+    () =>
+      createForgeClient({
+        baseURL: apiUrl,
+        publishableKey,
+        getToken: () => tokenRef.current,
+        // Fan/member lane (backend §7): 15-minute access tokens, refresh token
+        // rotated per exchange. On a dead chain the stored pair is cleared so
+        // the next /me lands cleanly logged-out instead of looping on 401s.
+        refresh: {
+          path: "/public/sessions/refresh",
+          getRefreshToken: () => readStoredToken(PUBLIC_REFRESH_TOKEN_KEY),
+          onRefreshed: ({ token: next, refreshToken }) => {
+            tokenRef.current = next;
+            setTokenState(next);
+            storeTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY, next, refreshToken);
+          },
+          onFailed: () => {
+            tokenRef.current = null;
+            setTokenState(null);
+            clearTokenPair(PUBLIC_ACCESS_TOKEN_KEY, PUBLIC_REFRESH_TOKEN_KEY);
+          },
+        },
+      }),
     [apiUrl, publishableKey],
   );