@mosano-product-framework/sdk 0.2.0

package/dist/react/context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The context value shared by the provider and every hook.
+ *
+ * Kept in its own module so `provider.tsx` and `hooks.ts` can both import it
+ * without a cycle.
+ */
+import type { MPFRole } from '../auth/claims-types.js';
+import type { SessionManager, SignOutResult, TokenPair } from '../auth/session-manager.js';
+import type { TenantSelectionStore } from '../auth/tenant-selection.js';
+import type { AuthStore } from './store.js';
+export interface MPFAuthContextValue {
+    store: AuthStore;
+    session: SessionManager;
+    tenants: TenantSelectionStore;
+    /**
+     * Select a tenant.
+     *
+     * **Synchronous. No await, no network, no renew.** Tenant is a request header
+     * now, so switching tenants is a local state change — that single property is
+     * the entire point of the header-based design.
+     */
+    selectTenant(tenant: string | null, role?: MPFRole): void;
+    /** Adopt a fresh token pair (after sign-in). */
+    setTokens(tokens: TokenPair): void;
+    /**
+     * Sign out: revoke server-side (when a `revoke` was supplied) then clear
+     * locally. Never rejects; the outcome is in the result.
+     */
+    signOut(): Promise<SignOutResult>;
+    /** Load the tenant list from the current token's claims. */
+    refreshTenants(): void;
+    /**
+     * Fetch tenant display names, if a loader was supplied.
+     *
+     * Resolves once the attempt has settled; failures are reported through state
+     * rather than thrown, because a switcher that cannot show names should still
+     * render (with ids) rather than crash.
+     */
+    loadDirectory(): Promise<void>;
+    /** Whether a directory loader was supplied at all. */
+    readonly hasDirectoryLoader: boolean;
+}
+/**
+ * `null` when no provider is mounted, which is what `useMPFAuthOptional()`
+ * reports without throwing.
+ */
+export declare const MPFAuthContext: import("react").Context<MPFAuthContextValue | null>;

package/dist/react/hooks.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Hooks over the auth store.
+ *
+ * Every read goes through `useSyncExternalStore`, so React owns the
+ * subscription and concurrent rendering cannot tear.
+ */
+import type { MPFClaims, MPFRole } from '../auth/claims-types.js';
+import type { SignOutResult, TokenPair } from '../auth/session-manager.js';
+import type { TenantSelection } from '../auth/tenant-selection.js';
+import type { TenantDirectoryEntry } from '../auth/tenant-directory.js';
+import { type MPFAuthContextValue } from './context.js';
+import type { TenantDirectoryStatus, TenantEntry, TenantsStatus } from './store.js';
+/**
+ * The auth context, or `null` when no provider is mounted.
+ *
+ * For components that must render both inside and outside an authenticated
+ * shell (a marketing header reused on a dashboard, say) without crashing.
+ */
+export declare function useMPFAuthOptional(): MPFAuthContextValue | null;
+export interface UseAuthResult {
+    /** True once hydration has run — always true after the first render. */
+    hydrated: boolean;
+    /** True when an access token is present. */
+    authenticated: boolean;
+    /** Decoded (UNVERIFIED, UX-only) claims. */
+    claims: MPFClaims | null;
+    /** Await a usable access token, renewing if necessary. */
+    getAccessToken: () => Promise<string | null>;
+    /** Adopt a fresh token pair after sign-in. */
+    setTokens: (tokens: TokenPair) => void;
+    /**
+     * Sign out: revokes server-side (when the provider was given `revoke`) then
+     * clears locally. Resolves with `{ revoked, error? }` and never rejects —
+     * local state is always cleared, so a user who clicked sign-out ends up
+     * signed out regardless of the network. Does not navigate.
+     */
+    signOut: () => Promise<SignOutResult>;
+}
+/**
+ * Core auth state and actions.
+ */
+export declare function useAuth(): UseAuthResult;
+/**
+ * Decoded claims of the current access token.
+ *
+ * ⚠️ UNVERIFIED and forgeable by a hostile client. UX only — never gate a
+ * security-relevant branch on this.
+ */
+export declare function useClaims(): MPFClaims | null;
+export interface UseTenantsResult {
+    /**
+     * `'unloaded'` when there is no token, `'loaded'` otherwise.
+     *
+     * Only two states because this list comes from the token's claims: there is no
+     * fetch here, so there is nothing that can fail. The failure case that matters
+     * — "we could not find out what these tenants are called" — lives on
+     * {@link useTenantDirectory}, where it is real.
+     */
+    status: TenantsStatus;
+    /**
+     * Selectable tenants, always driven by the claims. `name` is present only once
+     * the directory has loaded; render `name ?? id` so a switcher degrades to the
+     * id rather than to nothing.
+     */
+    tenants: TenantEntry[];
+    /** Recompute from the current token's claims. */
+    refresh: () => void;
+}
+/**
+ * The tenants the current token grants access to.
+ *
+ * Synchronous and cannot fail: the answer is already in the access token, which
+ * is fresher than anything a round trip could tell us. Display names are a
+ * separate concern — see {@link useTenantDirectory}.
+ */
+export declare function useTenants(): UseTenantsResult;
+export interface UseTenantDirectoryResult {
+    /**
+     * Tri-state, deliberately: `'loaded'` with no names ("this user belongs to no
+     * tenants") must never be confused with `'failed'` ("we could not find out").
+     * Collapsing those is how an empty switcher comes to silently mean "the server
+     * was unreachable".
+     *
+     * Stays `'unloaded'` when no `loadTenantDirectory` was supplied to the
+     * provider.
+     */
+    status: TenantDirectoryStatus;
+    /** Fetched display metadata, keyed by tenant id. */
+    directory: Record<string, TenantDirectoryEntry>;
+    /** Why the fetch failed, when it did. */
+    error: Error | null;
+    /** Whether the provider was given a loader at all. */
+    available: boolean;
+    /** Fetch (or re-fetch) display names. */
+    load: () => Promise<void>;
+}
+/**
+ * Tenant display names.
+ *
+ * Opt-in: supply `loadTenantDirectory` to `<MPFAuthProvider>`. Without it
+ * `useTenants()` still lists every selectable tenant by id — a switcher works,
+ * it just shows ids.
+ *
+ * A failure here never removes tenants from `useTenants()`: the ids come from
+ * the token and stay selectable regardless.
+ */
+export declare function useTenantDirectory(): UseTenantDirectoryResult;
+/**
+ * The current tenant selection.
+ */
+export declare function useCurrentTenant(): TenantSelection;
+/**
+ * Select a tenant.
+ *
+ * **Synchronous — no await, no network, no renew.** Tenant is a request header,
+ * so switching is a local state change and the next request simply carries a
+ * different header. This is the entire payoff of the header-based design; a test
+ * asserts it fires zero fetches.
+ */
+export declare function useSelectTenant(): (tenant: string | null, role?: MPFRole) => void;

package/dist/react/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * React bindings for the MPF SDK.
+ *
+ * **Dependency-free apart from React itself** — no TanStack Query, no zustand,
+ * no router. State is held in a small external store read through
+ * `useSyncExternalStore`, so there are no peer-dependency constraints on how a
+ * consumer manages the rest of its data, and SWR / Apollo / plain-fetch users
+ * are all equally supported.
+ *
+ * This subpath imports only from `src/auth/` and public core types, never into
+ * `src/identity/` or `src/storage/` internals, so splitting it into its own package later is a
+ * directory move.
+ *
+ * @packageDocumentation
+ */
+export { MPFAuthProvider, type MPFAuthProviderProps } from './provider.js';
+export { useAuth, useClaims, useTenants, useTenantDirectory, useCurrentTenant, useSelectTenant, useMPFAuthOptional, type UseAuthResult, type UseTenantsResult, type UseTenantDirectoryResult, } from './hooks.js';
+export { MPFAuthContext, type MPFAuthContextValue } from './context.js';
+export { createAuthStore, createInitialState, type AuthState, type AuthStore, type TenantEntry, type TenantsStatus, type TenantDirectoryStatus, } from './store.js';

package/dist/react/index.js

@@ -0,0 +1,308 @@
+import { createDefaultStorage, createTenantSelection, SessionManager } from '../chunk-7WAV52EO.js';
+import { tryDecodeAccessToken, listTenants, defaultRoleForTenant, rolesForTenant } from '../chunk-AJWM5MDZ.js';
+import { createContext, useRef, useEffect, useMemo, useContext, useCallback, useSyncExternalStore } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+var MPFAuthContext = createContext(null);
+
+// src/react/store.ts
+function createInitialState(overrides = {}) {
+  return {
+    hydrated: false,
+    authenticated: false,
+    claims: null,
+    selection: { tenant: null },
+    tenantsStatus: "unloaded",
+    tenants: [],
+    directoryStatus: "unloaded",
+    directory: {},
+    directoryError: null,
+    ...overrides
+  };
+}
+function createAuthStore(initial) {
+  let state = initial;
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    getSnapshot() {
+      return state;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    setState(patch) {
+      let changed = false;
+      for (const key of Object.keys(patch)) {
+        if (state[key] !== patch[key]) {
+          changed = true;
+          break;
+        }
+      }
+      if (!changed) {
+        return;
+      }
+      state = { ...state, ...patch };
+      for (const listener of [...listeners]) {
+        listener();
+      }
+    }
+  };
+}
+function tenantsFromToken(token, directory = {}) {
+  const claims = tryDecodeAccessToken(token);
+  if (!claims) {
+    return [];
+  }
+  return listTenants(claims).map((id) => {
+    const meta = directory[id];
+    const defaultRole = defaultRoleForTenant(claims, id);
+    return {
+      id,
+      roles: rolesForTenant(claims, id),
+      ...defaultRole !== void 0 ? { defaultRole } : {},
+      ...meta?.name !== void 0 ? { name: meta.name } : {},
+      ...meta?.slug !== void 0 ? { slug: meta.slug } : {}
+    };
+  });
+}
+var warnedDeadSession = false;
+function defaultOnDeadSession() {
+  if (warnedDeadSession) {
+    return;
+  }
+  warnedDeadSession = true;
+  console.warn(
+    "[MPF SDK] The session is no longer valid and the user must sign in again. Pass `onDeadSession` to <MPFAuthProvider> to handle this (e.g. redirect to your login route). This SDK never navigates on your behalf."
+  );
+}
+function MPFAuthProvider(props) {
+  const {
+    children,
+    renew,
+    revoke,
+    storage,
+    onDeadSession = defaultOnDeadSession,
+    tenantProvider,
+    sessionOptions,
+    session: injectedSession,
+    loadTenantDirectory,
+    autoLoadTenantDirectory = true
+  } = props;
+  const value = useRef(null);
+  if (value.current === null) {
+    const resolvedStorage = storage ?? createDefaultStorage();
+    const tenants = tenantProvider ?? createTenantSelection({ storage: resolvedStorage });
+    const session = injectedSession ?? new SessionManager({
+      ...sessionOptions,
+      renew,
+      ...revoke ? { revoke } : {},
+      storage: resolvedStorage,
+      onDeadSession: (error) => onDeadSession(error)
+    });
+    const initialToken = session.peekAccessToken();
+    const initialState = createInitialState({
+      hydrated: true,
+      authenticated: initialToken !== null,
+      claims: session.getClaims(),
+      selection: tenants.get(),
+      ...initialToken ? { tenantsStatus: "loaded", tenants: tenantsFromToken(initialToken) } : {}
+    });
+    const store = createAuthStore(initialState);
+    const syncFromSession = () => {
+      const token = session.peekAccessToken();
+      store.setState({
+        authenticated: token !== null,
+        claims: session.getClaims()
+      });
+    };
+    value.current = {
+      store,
+      session,
+      tenants,
+      selectTenant(tenant, role) {
+        tenants.set(tenant, role);
+      },
+      setTokens(tokens) {
+        session.setTokens(tokens);
+        syncFromSession();
+        store.setState({
+          tenantsStatus: "loaded",
+          tenants: tenantsFromToken(
+            tokens.access_token,
+            store.getSnapshot().directory
+          )
+        });
+      },
+      async signOut() {
+        const result = await session.signOut();
+        tenants.clear();
+        store.setState({
+          authenticated: false,
+          claims: null,
+          tenantsStatus: "unloaded",
+          tenants: [],
+          // Names belong to the signed-out user; drop them with the session.
+          directoryStatus: "unloaded",
+          directory: {},
+          directoryError: null
+        });
+        return result;
+      },
+      refreshTenants() {
+        const token = session.peekAccessToken();
+        if (!token) {
+          store.setState({ tenantsStatus: "unloaded", tenants: [] });
+          return;
+        }
+        store.setState({
+          tenantsStatus: "loaded",
+          tenants: tenantsFromToken(token, store.getSnapshot().directory)
+        });
+      },
+      hasDirectoryLoader: loadTenantDirectory !== void 0,
+      async loadDirectory() {
+        if (!loadTenantDirectory) {
+          return;
+        }
+        const token = session.peekAccessToken();
+        if (!token) {
+          store.setState({
+            directoryStatus: "failed",
+            directoryError: new Error(
+              "No access token; cannot load tenant display names"
+            )
+          });
+          return;
+        }
+        const ids = tenantsFromToken(token).map((t) => t.id);
+        if (ids.length === 0) {
+          store.setState({
+            directoryStatus: "loaded",
+            directory: {},
+            directoryError: null
+          });
+          return;
+        }
+        store.setState({ directoryStatus: "loading", directoryError: null });
+        try {
+          const entries = await loadTenantDirectory(ids);
+          const directory = {};
+          for (const entry of entries) {
+            if (entry && typeof entry.id === "string") {
+              directory[entry.id] = entry;
+            }
+          }
+          store.setState({
+            directoryStatus: "loaded",
+            directory,
+            directoryError: null,
+            // Re-merge names into the claims-derived list.
+            tenants: tenantsFromToken(session.peekAccessToken(), directory)
+          });
+        } catch (error) {
+          store.setState({
+            directoryStatus: "failed",
+            directoryError: error instanceof Error ? error : new Error(String(error))
+          });
+        }
+      }
+    };
+  }
+  const ctx = value.current;
+  useEffect(() => {
+    const unsubscribeTenants = ctx.tenants.subscribe((selection) => {
+      ctx.store.setState({ selection });
+    });
+    return () => {
+      unsubscribeTenants();
+    };
+  }, [ctx]);
+  useEffect(() => {
+    ctx.store.setState({
+      authenticated: ctx.session.peekAccessToken() !== null,
+      claims: ctx.session.getClaims()
+    });
+  }, [ctx]);
+  const authenticated = ctx.store.getSnapshot().authenticated;
+  useEffect(() => {
+    if (!autoLoadTenantDirectory || !ctx.hasDirectoryLoader || !authenticated) {
+      return;
+    }
+    if (ctx.store.getSnapshot().directoryStatus !== "unloaded") {
+      return;
+    }
+    void ctx.loadDirectory();
+  }, [ctx, autoLoadTenantDirectory, authenticated]);
+  useEffect(() => {
+    return () => {
+      ctx.session.destroy();
+    };
+  }, [ctx]);
+  const memoized = useMemo(() => ctx, [ctx]);
+  return /* @__PURE__ */ jsx(MPFAuthContext.Provider, { value: memoized, children });
+}
+function useMPFAuthOptional() {
+  return useContext(MPFAuthContext);
+}
+function useRequiredContext(hook) {
+  const ctx = useContext(MPFAuthContext);
+  if (!ctx) {
+    throw new Error(
+      `${hook}() requires a <MPFAuthProvider> ancestor. Use useMPFAuthOptional() if the component can render without one.`
+    );
+  }
+  return ctx;
+}
+function useAuthState(hook, select) {
+  const ctx = useRequiredContext(hook);
+  return useSyncExternalStore(
+    ctx.store.subscribe,
+    () => select(ctx.store.getSnapshot()),
+    () => select(ctx.store.getSnapshot())
+  );
+}
+function useAuth() {
+  const ctx = useRequiredContext("useAuth");
+  const hydrated = useAuthState("useAuth", (s) => s.hydrated);
+  const authenticated = useAuthState("useAuth", (s) => s.authenticated);
+  const claims = useAuthState("useAuth", (s) => s.claims);
+  const getAccessToken = useCallback(() => ctx.session.getAccessToken(), [ctx]);
+  const setTokens = useCallback((tokens) => ctx.setTokens(tokens), [ctx]);
+  const signOut = useCallback(() => ctx.signOut(), [ctx]);
+  return { hydrated, authenticated, claims, getAccessToken, setTokens, signOut };
+}
+function useClaims() {
+  return useAuthState("useClaims", (s) => s.claims);
+}
+function useTenants() {
+  const ctx = useRequiredContext("useTenants");
+  const status = useAuthState("useTenants", (s) => s.tenantsStatus);
+  const tenants = useAuthState("useTenants", (s) => s.tenants);
+  const refresh = useCallback(() => ctx.refreshTenants(), [ctx]);
+  return { status, tenants, refresh };
+}
+function useTenantDirectory() {
+  const ctx = useRequiredContext("useTenantDirectory");
+  const status = useAuthState("useTenantDirectory", (s) => s.directoryStatus);
+  const directory = useAuthState("useTenantDirectory", (s) => s.directory);
+  const error = useAuthState("useTenantDirectory", (s) => s.directoryError);
+  const load = useCallback(() => ctx.loadDirectory(), [ctx]);
+  return { status, directory, error, available: ctx.hasDirectoryLoader, load };
+}
+function useCurrentTenant() {
+  return useAuthState("useCurrentTenant", (s) => s.selection);
+}
+function useSelectTenant() {
+  const ctx = useRequiredContext("useSelectTenant");
+  return useCallback(
+    (tenant, role) => ctx.selectTenant(tenant, role),
+    [ctx]
+  );
+}
+
+export { MPFAuthContext, MPFAuthProvider, createAuthStore, createInitialState, useAuth, useClaims, useCurrentTenant, useMPFAuthOptional, useSelectTenant, useTenantDirectory, useTenants };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/context.ts","../../src/react/store.ts","../../src/react/provider.tsx","../../src/react/hooks.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * The context value shared by the provider and every hook.\n *\n * Kept in its own module so `provider.tsx` and `hooks.ts` can both import it\n * without a cycle.\n */\n\nimport { createContext } from 'react';\n\nimport type { MPFRole } from '../auth/claims-types.js';\nimport type { SessionManager, SignOutResult, TokenPair } from '../auth/session-manager.js';\nimport type { TenantSelectionStore } from '../auth/tenant-selection.js';\nimport type { AuthStore } from './store.js';\n\nexport interface MPFAuthContextValue {\n  store: AuthStore;\n  session: SessionManager;\n  tenants: TenantSelectionStore;\n  /**\n   * Select a tenant.\n   *\n   * **Synchronous. No await, no network, no renew.** Tenant is a request header\n   * now, so switching tenants is a local state change — that single property is\n   * the entire point of the header-based design.\n   */\n  selectTenant(tenant: string | null, role?: MPFRole): void;\n  /** Adopt a fresh token pair (after sign-in). */\n  setTokens(tokens: TokenPair): void;\n  /**\n   * Sign out: revoke server-side (when a `revoke` was supplied) then clear\n   * locally. Never rejects; the outcome is in the result.\n   */\n  signOut(): Promise<SignOutResult>;\n  /** Load the tenant list from the current token's claims. */\n  refreshTenants(): void;\n  /**\n   * Fetch tenant display names, if a loader was supplied.\n   *\n   * Resolves once the attempt has settled; failures are reported through state\n   * rather than thrown, because a switcher that cannot show names should still\n   * render (with ids) rather than crash.\n   */\n  loadDirectory(): Promise<void>;\n  /** Whether a directory loader was supplied at all. */\n  readonly hasDirectoryLoader: boolean;\n}\n\n/**\n * `null` when no provider is mounted, which is what `useMPFAuthOptional()`\n * reports without throwing.\n */\nexport const MPFAuthContext = createContext<MPFAuthContextValue | null>(null);\n","/**\n * A tiny external store for `useSyncExternalStore`.\n *\n * Zero dependencies and no tearing: `useSyncExternalStore` is React's own\n * contract for reading external mutable state, so concurrent rendering cannot\n * observe two different snapshots within one commit. A `useState` +\n * `useEffect` mirror would.\n *\n * `getSnapshot` must return a **referentially stable** value while nothing has\n * changed, or React re-renders forever. Every mutation here therefore builds\n * exactly one new state object and every non-mutation returns the existing one.\n */\n\nimport type { MPFClaims } from '../auth/claims-types.js';\nimport type { TenantSelection } from '../auth/tenant-selection.js';\nimport type { TenantDirectoryEntry } from '../auth/tenant-directory.js';\n\n/**\n * Whether the selectable-tenant list is known.\n *\n * Only two states, because this list comes from the access token's claims: if\n * there is a token the answer is known, and if there is not, it is not. There is\n * no fetch, so there is nothing to fail. The thing that CAN fail is the display\n * name lookup — see {@link TenantDirectoryStatus}, which is where the\n * \"loaded-but-empty vs failed\" distinction actually earns its keep.\n */\nexport type TenantsStatus = 'unloaded' | 'loaded';\n\n/** Whether tenant display names have been fetched. */\nexport type TenantDirectoryStatus = 'unloaded' | 'loading' | 'loaded' | 'failed';\n\n/** A tenant as surfaced to the UI. */\nexport interface TenantEntry {\n  id: string;\n  /** Every role held in this tenant. */\n  roles: string[];\n  /**\n   * That tenant's default role: its explicit `dfr` claim when the token carries\n   * one, otherwise `roles[0]`. Absent only when the tenant grants no roles.\n   *\n   * Surfaced separately because `roles[0]` is no longer authoritative — a token\n   * may name a default that is not the first role listed.\n   */\n  defaultRole?: string;\n  /**\n   * Display name, present only once the directory has loaded. Render\n   * `name ?? id` so a switcher degrades to the id rather than to nothing.\n   */\n  name?: string;\n  /** URL-friendly slug, present only once the directory has loaded. */\n  slug?: string;\n}\n\nexport interface AuthState {\n  /** True once hydration has run. Always true after provider construction. */\n  hydrated: boolean;\n  /** True when an access token is present. */\n  authenticated: boolean;\n  /** Decoded (UNVERIFIED, UX-only) claims of the current access token. */\n  claims: MPFClaims | null;\n  /** Current tenant selection. */\n  selection: TenantSelection;\n  /** Whether the selectable-tenant list is known (i.e. whether a token exists). */\n  tenantsStatus: TenantsStatus;\n  /** Selectable tenants, meaningful only when `tenantsStatus === 'loaded'`. */\n  tenants: TenantEntry[];\n\n  /**\n   * Display-name lookup state.\n   *\n   * Tri-state on purpose: \"this user belongs to zero tenants\" and \"we could not\n   * find out what they are called\" must never be indistinguishable. Collapsing\n   * them is a real bug class — an empty switcher that silently means \"the server\n   * was unreachable\".\n   */\n  directoryStatus: TenantDirectoryStatus;\n  /** Fetched display metadata, keyed by tenant id. */\n  directory: Record<string, TenantDirectoryEntry>;\n  /** Why the directory fetch failed, when it did. */\n  directoryError: Error | null;\n}\n\nexport interface AuthStore {\n  getSnapshot(): AuthState;\n  subscribe(listener: () => void): () => void;\n  setState(patch: Partial<AuthState>): void;\n}\n\nexport function createInitialState(overrides: Partial<AuthState> = {}): AuthState {\n  return {\n    hydrated: false,\n    authenticated: false,\n    claims: null,\n    selection: { tenant: null },\n    tenantsStatus: 'unloaded',\n    tenants: [],\n    directoryStatus: 'unloaded',\n    directory: {},\n    directoryError: null,\n    ...overrides,\n  };\n}\n\n/**\n * Create an auth store.\n */\nexport function createAuthStore(initial: AuthState): AuthStore {\n  let state = initial;\n  const listeners = new Set<() => void>();\n\n  return {\n    getSnapshot() {\n      return state;\n    },\n\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n\n    setState(patch) {\n      // Skip no-op updates so `getSnapshot` stays referentially stable and\n      // React does not re-render for nothing.\n      let changed = false;\n      for (const key of Object.keys(patch) as Array<keyof AuthState>) {\n        if (state[key] !== patch[key]) {\n          changed = true;\n          break;\n        }\n      }\n      if (!changed) {\n        return;\n      }\n\n      state = { ...state, ...patch };\n      for (const listener of [...listeners]) {\n        listener();\n      }\n    },\n  };\n}\n","/**\n * `<MPFAuthProvider>` — wires a `SessionManager` and a `TenantSelectionStore`\n * into a React tree.\n */\n\nimport { useEffect, useMemo, useRef, type ReactNode } from 'react';\n\nimport type { MPFRole } from '../auth/claims-types.js';\nimport {\n  tryDecodeAccessToken,\n  listTenants,\n  rolesForTenant,\n  defaultRoleForTenant,\n} from '../auth/claims.js';\nimport { createDefaultStorage, type MPFAuthStorage } from '../auth/storage.js';\nimport {\n  SessionManager,\n  type SessionManagerOptions,\n  type TokenPair,\n} from '../auth/session-manager.js';\nimport {\n  createTenantSelection,\n  type TenantSelectionStore,\n} from '../auth/tenant-selection.js';\nimport type { DeadSessionError } from '../auth/errors.js';\nimport type {\n  TenantDirectoryEntry,\n  TenantDirectoryLoader,\n} from '../auth/tenant-directory.js';\nimport { MPFAuthContext, type MPFAuthContextValue } from './context.js';\nimport { createAuthStore, createInitialState, type AuthState, type TenantEntry } from './store.js';\n\nexport interface MPFAuthProviderProps {\n  children?: ReactNode;\n\n  /**\n   * Performs the network renewal. Wire to\n   * `(refreshToken) => authClient.renewSession({ refresh_token: refreshToken })`.\n   */\n  renew: SessionManagerOptions['renew'];\n\n  /**\n   * Revokes the session server-side on sign-out. Wire to\n   * `(refreshToken) => authClient.revokeSession({ refresh_token: refreshToken })`.\n   *\n   * Without it `signOut()` still clears local state — a sign-out button must\n   * always sign the user out — but the refresh token stays valid server-side\n   * until it expires. Supply it.\n   */\n  revoke?: SessionManagerOptions['revoke'];\n\n  /** Storage for the refresh token and tenant selection. @default localStorage */\n  storage?: MPFAuthStorage;\n\n  /**\n   * Called when the session is dead and the user must sign in again.\n   *\n   * A **callback, never a navigation**. Libraries do not navigate: routing is\n   * the application's concern and hard-coding `window.location` here would\n   * couple the SDK to one router and one URL scheme. Defaults to a one-time\n   * `console.warn`.\n   */\n  onDeadSession?: (error: DeadSessionError) => void;\n\n  /**\n   * Pre-built tenant selection store. Supply this when non-React code\n   * (a bare `createAuthClient`) must share the same selection.\n   */\n  tenantProvider?: TenantSelectionStore;\n\n  /** Overrides forwarded to the session manager (buffer, jitter, ...). */\n  sessionOptions?: Omit<SessionManagerOptions, 'renew' | 'storage' | 'onDeadSession'>;\n\n  /** Pre-built session manager. Mainly for tests. Takes precedence. */\n  session?: SessionManager;\n\n  /**\n   * Fetches tenant display names.\n   *\n   * Optional: without it `useTenants()` still returns every selectable tenant\n   * (ids and roles, straight from the token) and a switcher renders ids. Supply\n   * it to get names.\n   *\n   * Injected rather than built in so the React layer never depends on the\n   * GraphQL client. Use `TENANT_DIRECTORY_QUERY` with whichever client the app\n   * already has, and query it with `{ tenant: null }` — the `tenantless` role has\n   * the select permission a switcher needs.\n   */\n  loadTenantDirectory?: TenantDirectoryLoader;\n\n  /**\n   * Whether to fetch display names automatically once a token is present.\n   * @default true when `loadTenantDirectory` is supplied\n   */\n  autoLoadTenantDirectory?: boolean;\n}\n\n/**\n * Build the selectable-tenant list from decoded claims, merging any display\n * metadata already fetched.\n */\nfunction tenantsFromToken(\n  token: string | null,\n  directory: Record<string, TenantDirectoryEntry> = {},\n): TenantEntry[] {\n  const claims = tryDecodeAccessToken(token);\n  if (!claims) {\n    return [];\n  }\n\n  // Driven by the CLAIMS, never by the directory: a tenant the token does not\n  // grant must never appear in a switcher just because its name was fetched.\n  return listTenants(claims).map((id) => {\n    const meta = directory[id];\n    const defaultRole = defaultRoleForTenant(claims, id);\n    return {\n      id,\n      roles: rolesForTenant(claims, id),\n      ...(defaultRole !== undefined ? { defaultRole } : {}),\n      ...(meta?.name !== undefined ? { name: meta.name } : {}),\n      ...(meta?.slug !== undefined ? { slug: meta.slug } : {}),\n    };\n  });\n}\n\nlet warnedDeadSession = false;\n\nfunction defaultOnDeadSession(): void {\n  if (warnedDeadSession) {\n    return;\n  }\n  warnedDeadSession = true;\n  console.warn(\n    '[MPF SDK] The session is no longer valid and the user must sign in again. ' +\n      'Pass `onDeadSession` to <MPFAuthProvider> to handle this (e.g. redirect to ' +\n      'your login route). This SDK never navigates on your behalf.',\n  );\n}\n\n/** @internal test seam */\nexport function resetDeadSessionWarning(): void {\n  warnedDeadSession = false;\n}\n\nexport function MPFAuthProvider(props: MPFAuthProviderProps): JSX.Element {\n  const {\n    children,\n    renew,\n    revoke,\n    storage,\n    onDeadSession = defaultOnDeadSession,\n    tenantProvider,\n    sessionOptions,\n    session: injectedSession,\n    loadTenantDirectory,\n    autoLoadTenantDirectory = true,\n  } = props;\n\n  // Everything below is built ONCE, during the first render, and never\n  // recreated: a new SessionManager per render would restart timers and lose\n  // in-flight renewals.\n  const value = useRef<MPFAuthContextValue | null>(null);\n\n  if (value.current === null) {\n    const resolvedStorage = storage ?? createDefaultStorage();\n\n    const tenants =\n      tenantProvider ?? createTenantSelection({ storage: resolvedStorage });\n\n    const session =\n      injectedSession ??\n      new SessionManager({\n        ...sessionOptions,\n        renew,\n        ...(revoke ? { revoke } : {}),\n        storage: resolvedStorage,\n        onDeadSession: (error) => onDeadSession(error),\n      });\n\n    // Hydrate SYNCHRONOUSLY, before the first paint. An effect-based hydration\n    // renders one frame as unauthenticated and produces the classic login-form\n    // flash on reload — which is also what makes persisting the tenant\n    // selection actually visible to the user.\n    const initialToken = session.peekAccessToken();\n    const initialState: AuthState = createInitialState({\n      hydrated: true,\n      authenticated: initialToken !== null,\n      claims: session.getClaims(),\n      selection: tenants.get(),\n      ...(initialToken\n        ? { tenantsStatus: 'loaded' as const, tenants: tenantsFromToken(initialToken) }\n        : {}),\n    });\n\n    const store = createAuthStore(initialState);\n\n    const syncFromSession = (): void => {\n      const token = session.peekAccessToken();\n      store.setState({\n        authenticated: token !== null,\n        claims: session.getClaims(),\n      });\n    };\n\n    value.current = {\n      store,\n      session,\n      tenants,\n\n      selectTenant(tenant: string | null, role?: MPFRole) {\n        // Synchronous by construction: a header change, nothing more.\n        tenants.set(tenant, role);\n      },\n\n      setTokens(tokens: TokenPair) {\n        session.setTokens(tokens);\n        syncFromSession();\n        store.setState({\n          tenantsStatus: 'loaded',\n          tenants: tenantsFromToken(\n            tokens.access_token,\n            store.getSnapshot().directory,\n          ),\n        });\n      },\n\n      async signOut() {\n        // Full sequence: revoke server-side, then clear. The manager owns the\n        // ordering (revoke is an authenticated call, so it must precede the\n        // clear) and never throws.\n        const result = await session.signOut();\n        tenants.clear();\n        store.setState({\n          authenticated: false,\n          claims: null,\n          tenantsStatus: 'unloaded',\n          tenants: [],\n          // Names belong to the signed-out user; drop them with the session.\n          directoryStatus: 'unloaded',\n          directory: {},\n          directoryError: null,\n        });\n        return result;\n      },\n\n      refreshTenants() {\n        const token = session.peekAccessToken();\n        if (!token) {\n          store.setState({ tenantsStatus: 'unloaded', tenants: [] });\n          return;\n        }\n        store.setState({\n          tenantsStatus: 'loaded',\n          tenants: tenantsFromToken(token, store.getSnapshot().directory),\n        });\n      },\n\n      hasDirectoryLoader: loadTenantDirectory !== undefined,\n\n      async loadDirectory() {\n        if (!loadTenantDirectory) {\n          return;\n        }\n\n        const token = session.peekAccessToken();\n        if (!token) {\n          store.setState({\n            directoryStatus: 'failed',\n            directoryError: new Error(\n              'No access token; cannot load tenant display names',\n            ),\n          });\n          return;\n        }\n\n        const ids = tenantsFromToken(token).map((t) => t.id);\n        if (ids.length === 0) {\n          // No tenants to name. This is 'loaded' with nothing in it, which is\n          // emphatically NOT the same as 'failed'.\n          store.setState({\n            directoryStatus: 'loaded',\n            directory: {},\n            directoryError: null,\n          });\n          return;\n        }\n\n        store.setState({ directoryStatus: 'loading', directoryError: null });\n\n        try {\n          const entries = await loadTenantDirectory(ids);\n          const directory: Record<string, TenantDirectoryEntry> = {};\n          for (const entry of entries) {\n            if (entry && typeof entry.id === 'string') {\n              directory[entry.id] = entry;\n            }\n          }\n\n          store.setState({\n            directoryStatus: 'loaded',\n            directory,\n            directoryError: null,\n            // Re-merge names into the claims-derived list.\n            tenants: tenantsFromToken(session.peekAccessToken(), directory),\n          });\n        } catch (error) {\n          // A name lookup failure must not empty the switcher: the ids remain\n          // selectable and the UI degrades to showing them.\n          store.setState({\n            directoryStatus: 'failed',\n            directoryError: error instanceof Error ? error : new Error(String(error)),\n          });\n        }\n      },\n    };\n  }\n\n  const ctx = value.current;\n\n  // Keep the store in step with external mutations: token renewals (including\n  // ones driven by another tab) and tenant selections made outside React.\n  useEffect(() => {\n    const unsubscribeTenants = ctx.tenants.subscribe((selection) => {\n      ctx.store.setState({ selection });\n    });\n\n    return () => {\n      unsubscribeTenants();\n    };\n  }, [ctx]);\n\n  useEffect(() => {\n    // The session manager reports token changes through onTokensChanged, which\n    // is owned by whoever constructed it. Poll-free alternative: re-read on\n    // mount and rely on setTokens/signOut for the rest.\n    ctx.store.setState({\n      authenticated: ctx.session.peekAccessToken() !== null,\n      claims: ctx.session.getClaims(),\n    });\n  }, [ctx]);\n\n  // Fetch display names once, after mount, when a token is present. In an\n  // effect rather than during construction because it is a network call — the\n  // synchronous hydration above must not be blocked on it.\n  const authenticated = ctx.store.getSnapshot().authenticated;\n  useEffect(() => {\n    if (!autoLoadTenantDirectory || !ctx.hasDirectoryLoader || !authenticated) {\n      return;\n    }\n    if (ctx.store.getSnapshot().directoryStatus !== 'unloaded') {\n      return;\n    }\n    void ctx.loadDirectory();\n  }, [ctx, autoLoadTenantDirectory, authenticated]);\n\n  useEffect(() => {\n    return () => {\n      ctx.session.destroy();\n    };\n  }, [ctx]);\n\n  const memoized = useMemo(() => ctx, [ctx]);\n\n  return <MPFAuthContext.Provider value={memoized}>{children}</MPFAuthContext.Provider>;\n}\n","/**\n * Hooks over the auth store.\n *\n * Every read goes through `useSyncExternalStore`, so React owns the\n * subscription and concurrent rendering cannot tear.\n */\n\nimport { useCallback, useContext, useSyncExternalStore } from 'react';\n\nimport type { MPFClaims, MPFRole } from '../auth/claims-types.js';\nimport type { SignOutResult, TokenPair } from '../auth/session-manager.js';\nimport type { TenantSelection } from '../auth/tenant-selection.js';\nimport type { TenantDirectoryEntry } from '../auth/tenant-directory.js';\nimport { MPFAuthContext, type MPFAuthContextValue } from './context.js';\nimport type {\n  AuthState,\n  TenantDirectoryStatus,\n  TenantEntry,\n  TenantsStatus,\n} from './store.js';\n\n/**\n * The auth context, or `null` when no provider is mounted.\n *\n * For components that must render both inside and outside an authenticated\n * shell (a marketing header reused on a dashboard, say) without crashing.\n */\nexport function useMPFAuthOptional(): MPFAuthContextValue | null {\n  return useContext(MPFAuthContext);\n}\n\nfunction useRequiredContext(hook: string): MPFAuthContextValue {\n  const ctx = useContext(MPFAuthContext);\n  if (!ctx) {\n    throw new Error(\n      `${hook}() requires a <MPFAuthProvider> ancestor. ` +\n        'Use useMPFAuthOptional() if the component can render without one.',\n    );\n  }\n  return ctx;\n}\n\n/** Subscribe to a slice of auth state. */\nfunction useAuthState<T>(hook: string, select: (state: AuthState) => T): T {\n  const ctx = useRequiredContext(hook);\n  return useSyncExternalStore(\n    ctx.store.subscribe,\n    () => select(ctx.store.getSnapshot()),\n    () => select(ctx.store.getSnapshot()),\n  );\n}\n\nexport interface UseAuthResult {\n  /** True once hydration has run — always true after the first render. */\n  hydrated: boolean;\n  /** True when an access token is present. */\n  authenticated: boolean;\n  /** Decoded (UNVERIFIED, UX-only) claims. */\n  claims: MPFClaims | null;\n  /** Await a usable access token, renewing if necessary. */\n  getAccessToken: () => Promise<string | null>;\n  /** Adopt a fresh token pair after sign-in. */\n  setTokens: (tokens: TokenPair) => void;\n  /**\n   * Sign out: revokes server-side (when the provider was given `revoke`) then\n   * clears locally. Resolves with `{ revoked, error? }` and never rejects —\n   * local state is always cleared, so a user who clicked sign-out ends up\n   * signed out regardless of the network. Does not navigate.\n   */\n  signOut: () => Promise<SignOutResult>;\n}\n\n/**\n * Core auth state and actions.\n */\nexport function useAuth(): UseAuthResult {\n  const ctx = useRequiredContext('useAuth');\n\n  const hydrated = useAuthState('useAuth', (s) => s.hydrated);\n  const authenticated = useAuthState('useAuth', (s) => s.authenticated);\n  const claims = useAuthState('useAuth', (s) => s.claims);\n\n  const getAccessToken = useCallback(() => ctx.session.getAccessToken(), [ctx]);\n  const setTokens = useCallback((tokens: TokenPair) => ctx.setTokens(tokens), [ctx]);\n  const signOut = useCallback(() => ctx.signOut(), [ctx]);\n\n  return { hydrated, authenticated, claims, getAccessToken, setTokens, signOut };\n}\n\n/**\n * Decoded claims of the current access token.\n *\n * ⚠️ UNVERIFIED and forgeable by a hostile client. UX only — never gate a\n * security-relevant branch on this.\n */\nexport function useClaims(): MPFClaims | null {\n  return useAuthState('useClaims', (s) => s.claims);\n}\n\nexport interface UseTenantsResult {\n  /**\n   * `'unloaded'` when there is no token, `'loaded'` otherwise.\n   *\n   * Only two states because this list comes from the token's claims: there is no\n   * fetch here, so there is nothing that can fail. The failure case that matters\n   * — \"we could not find out what these tenants are called\" — lives on\n   * {@link useTenantDirectory}, where it is real.\n   */\n  status: TenantsStatus;\n  /**\n   * Selectable tenants, always driven by the claims. `name` is present only once\n   * the directory has loaded; render `name ?? id` so a switcher degrades to the\n   * id rather than to nothing.\n   */\n  tenants: TenantEntry[];\n  /** Recompute from the current token's claims. */\n  refresh: () => void;\n}\n\n/**\n * The tenants the current token grants access to.\n *\n * Synchronous and cannot fail: the answer is already in the access token, which\n * is fresher than anything a round trip could tell us. Display names are a\n * separate concern — see {@link useTenantDirectory}.\n */\nexport function useTenants(): UseTenantsResult {\n  const ctx = useRequiredContext('useTenants');\n\n  const status = useAuthState('useTenants', (s) => s.tenantsStatus);\n  const tenants = useAuthState('useTenants', (s) => s.tenants);\n  const refresh = useCallback(() => ctx.refreshTenants(), [ctx]);\n\n  return { status, tenants, refresh };\n}\n\nexport interface UseTenantDirectoryResult {\n  /**\n   * Tri-state, deliberately: `'loaded'` with no names (\"this user belongs to no\n   * tenants\") must never be confused with `'failed'` (\"we could not find out\").\n   * Collapsing those is how an empty switcher comes to silently mean \"the server\n   * was unreachable\".\n   *\n   * Stays `'unloaded'` when no `loadTenantDirectory` was supplied to the\n   * provider.\n   */\n  status: TenantDirectoryStatus;\n  /** Fetched display metadata, keyed by tenant id. */\n  directory: Record<string, TenantDirectoryEntry>;\n  /** Why the fetch failed, when it did. */\n  error: Error | null;\n  /** Whether the provider was given a loader at all. */\n  available: boolean;\n  /** Fetch (or re-fetch) display names. */\n  load: () => Promise<void>;\n}\n\n/**\n * Tenant display names.\n *\n * Opt-in: supply `loadTenantDirectory` to `<MPFAuthProvider>`. Without it\n * `useTenants()` still lists every selectable tenant by id — a switcher works,\n * it just shows ids.\n *\n * A failure here never removes tenants from `useTenants()`: the ids come from\n * the token and stay selectable regardless.\n */\nexport function useTenantDirectory(): UseTenantDirectoryResult {\n  const ctx = useRequiredContext('useTenantDirectory');\n\n  const status = useAuthState('useTenantDirectory', (s) => s.directoryStatus);\n  const directory = useAuthState('useTenantDirectory', (s) => s.directory);\n  const error = useAuthState('useTenantDirectory', (s) => s.directoryError);\n  const load = useCallback(() => ctx.loadDirectory(), [ctx]);\n\n  return { status, directory, error, available: ctx.hasDirectoryLoader, load };\n}\n\n/**\n * The current tenant selection.\n */\nexport function useCurrentTenant(): TenantSelection {\n  return useAuthState('useCurrentTenant', (s) => s.selection);\n}\n\n/**\n * Select a tenant.\n *\n * **Synchronous — no await, no network, no renew.** Tenant is a request header,\n * so switching is a local state change and the next request simply carries a\n * different header. This is the entire payoff of the header-based design; a test\n * asserts it fires zero fetches.\n */\nexport function useSelectTenant(): (tenant: string | null, role?: MPFRole) => void {\n  const ctx = useRequiredContext('useSelectTenant');\n  return useCallback(\n    (tenant: string | null, role?: MPFRole) => ctx.selectTenant(tenant, role),\n    [ctx],\n  );\n}\n"]}

package/dist/react/provider.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `<MPFAuthProvider>` — wires a `SessionManager` and a `TenantSelectionStore`
+ * into a React tree.
+ */
+import { type ReactNode } from 'react';
+import { type MPFAuthStorage } from '../auth/storage.js';
+import { SessionManager, type SessionManagerOptions } from '../auth/session-manager.js';
+import { type TenantSelectionStore } from '../auth/tenant-selection.js';
+import type { DeadSessionError } from '../auth/errors.js';
+import type { TenantDirectoryLoader } from '../auth/tenant-directory.js';
+export interface MPFAuthProviderProps {
+    children?: ReactNode;
+    /**
+     * Performs the network renewal. Wire to
+     * `(refreshToken) => authClient.renewSession({ refresh_token: refreshToken })`.
+     */
+    renew: SessionManagerOptions['renew'];
+    /**
+     * Revokes the session server-side on sign-out. Wire to
+     * `(refreshToken) => authClient.revokeSession({ refresh_token: refreshToken })`.
+     *
+     * Without it `signOut()` still clears local state — a sign-out button must
+     * always sign the user out — but the refresh token stays valid server-side
+     * until it expires. Supply it.
+     */
+    revoke?: SessionManagerOptions['revoke'];
+    /** Storage for the refresh token and tenant selection. @default localStorage */
+    storage?: MPFAuthStorage;
+    /**
+     * Called when the session is dead and the user must sign in again.
+     *
+     * A **callback, never a navigation**. Libraries do not navigate: routing is
+     * the application's concern and hard-coding `window.location` here would
+     * couple the SDK to one router and one URL scheme. Defaults to a one-time
+     * `console.warn`.
+     */
+    onDeadSession?: (error: DeadSessionError) => void;
+    /**
+     * Pre-built tenant selection store. Supply this when non-React code
+     * (a bare `createAuthClient`) must share the same selection.
+     */
+    tenantProvider?: TenantSelectionStore;
+    /** Overrides forwarded to the session manager (buffer, jitter, ...). */
+    sessionOptions?: Omit<SessionManagerOptions, 'renew' | 'storage' | 'onDeadSession'>;
+    /** Pre-built session manager. Mainly for tests. Takes precedence. */
+    session?: SessionManager;
+    /**
+     * Fetches tenant display names.
+     *
+     * Optional: without it `useTenants()` still returns every selectable tenant
+     * (ids and roles, straight from the token) and a switcher renders ids. Supply
+     * it to get names.
+     *
+     * Injected rather than built in so the React layer never depends on the
+     * GraphQL client. Use `TENANT_DIRECTORY_QUERY` with whichever client the app
+     * already has, and query it with `{ tenant: null }` — the `tenantless` role has
+     * the select permission a switcher needs.
+     */
+    loadTenantDirectory?: TenantDirectoryLoader;
+    /**
+     * Whether to fetch display names automatically once a token is present.
+     * @default true when `loadTenantDirectory` is supplied
+     */
+    autoLoadTenantDirectory?: boolean;
+}
+/** @internal test seam */
+export declare function resetDeadSessionWarning(): void;
+export declare function MPFAuthProvider(props: MPFAuthProviderProps): JSX.Element;