Vite SPA

React Router Data Mode

React Router Framework Mode

Next.js App Router + RSC + BFF

session contract
permission contract
auth state machine
runtime adapters
route/data integration adapters
API client boundary
server enforcement boundary

React auth should be framework-integrated, not framework-owned.

Every route/component directly knows about provider SDK, cookies, router redirects, token refresh, role parsing, and permission rules.

Routes ask for session/permission through a small framework adapter.
Components consume a stable projection.
Server actions call server auth functions.
APIs enforce business authorization directly.

Auth core: what auth means.
Framework adapter: how this framework runs auth.
Provider adapter: how this IdP exposes identity/session.
Policy adapter: how permission decisions are fetched/evaluated.

export type AuthStatus =
  | "unknown"
  | "anonymous"
  | "authenticated"
  | "expired"
  | "forbidden"
  | "degraded";

export type SessionProjection = {
  status: AuthStatus;
  user?: {
    id: string;
    displayName: string;
    email?: string;
  };
  tenant?: {
    id: string;
    name: string;
    membershipId: string;
  };
  assurance?: {
    level: "low" | "medium" | "high";
    authTime?: string;
  };
  epochs?: {
    session: string;
    permission: string;
    policy: string;
  };
};

export type PermissionDecision =
  | {
      allowed: true;
      reason?: string;
      obligations?: PermissionObligation[];
    }
  | {
      allowed: false;
      reason:
        | "NO_SESSION"
        | "TENANT_REQUIRED"
        | "TENANT_FORBIDDEN"
        | "PERMISSION_DENIED"
        | "STEP_UP_REQUIRED"
        | "RESOURCE_NOT_FOUND"
        | "POLICY_UNAVAILABLE";
      recoverable: boolean;
      safeMessage: string;
      obligations?: PermissionObligation[];
    };

export type PermissionObligation =
  | { type: "MASK_FIELD"; field: string }
  | { type: "READ_ONLY"; field?: string }
  | { type: "REQUIRE_STEP_UP"; maxAgeSeconds: number }
  | { type: "AUDIT_REASON_REQUIRED" };

const decision = useCan({
  action: "case.approve",
  resource: { type: "case", id: caseId },
});

`useCan()` controls exposure.
The API controls authorization.

export interface AuthClient {
  getSnapshot(): SessionProjection;
  subscribe(listener: () => void): () => void;
  bootstrap(): Promise<SessionProjection>;
  login(options?: LoginOptions): Promise<void>;
  logout(options?: LogoutOptions): Promise<void>;
  refresh?(): Promise<SessionProjection>;
}

export type LoginOptions = {
  returnTo?: string;
  tenantHint?: string;
  stepUp?: boolean;
};

export type LogoutOptions = {
  reason?: "USER" | "SESSION_EXPIRED" | "REVOKED" | "TENANT_SWITCH";
  returnTo?: string;
};

export function createAuthStore(authClient: AuthClient) {
  return {
    getSnapshot: () => authClient.getSnapshot(),
    subscribe: (listener: () => void) => authClient.subscribe(listener),
    bootstrap: () => authClient.bootstrap(),
    login: (options?: LoginOptions) => authClient.login(options),
    logout: (options?: LogoutOptions) => authClient.logout(options),
  };
}

import { createContext, useContext, useSyncExternalStore } from "react";

const AuthContext = createContext<AuthClient | null>(null);

export function AuthProvider({
  client,
  children,
}: {
  client: AuthClient;
  children: React.ReactNode;
}) {
  return <AuthContext.Provider value={client}>{children}</AuthContext.Provider>;
}

export function useSessionProjection(): SessionProjection {
  const client = useContext(AuthContext);

  if (!client) {
    throw new Error("AuthProvider is missing");
  }

  return useSyncExternalStore(
    client.subscribe,
    client.getSnapshot,
    client.getSnapshot,
  );
}

/session endpoint
provider SDK
React Router loader hydration
Next.js server projection
BFF cookie session
memory-only SPA token manager

export function createSpaAuthClient(input: {
  fetchSession: () => Promise<SessionProjection>;
  startLogin: (options?: LoginOptions) => Promise<void>;
  startLogout: (options?: LogoutOptions) => Promise<void>;
}): AuthClient {
  let snapshot: SessionProjection = { status: "unknown" };
  const listeners = new Set<() => void>();

  function emit(next: SessionProjection) {
    snapshot = next;
    listeners.forEach((listener) => listener());
  }

  return {
    getSnapshot: () => snapshot,
    subscribe(listener) {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
    async bootstrap() {
      try {
        const next = await input.fetchSession();
        emit(next);
        return next;
      } catch {
        const degraded: SessionProjection = { status: "degraded" };
        emit(degraded);
        return degraded;
      }
    },
    login: input.startLogin,
    logout: input.startLogout,
  };
}

Do not persist refresh tokens in localStorage.
Use memory token if pure SPA bearer token model is required.
Prefer BFF/session cookie for higher-risk apps.
Clear app cache on logout and tenant switch.
Do not trust decoded token as authorization.

export async function requireSessionLoader({ request }: { request: Request }) {
  const session = await fetchSessionProjection(request);

  if (session.status === "anonymous" || session.status === "expired") {
    const returnTo = new URL(request.url).pathname;
    throw redirect(`/login?returnTo=${encodeURIComponent(returnTo)}`);
  }

  return session;
}

export function RootAuthHydrator() {
  const session = useLoaderData() as SessionProjection;
  const authClient = useAuthClient();

  useEffect(() => {
    authClient.replaceSnapshot(session);
  }, [authClient, session]);

  return <Outlet />;
}

export async function approveCaseAction({ request, params }: ActionArgs) {
  const session = await requireServerSession(request);

  await enforcePermission({
    subject: session.subject,
    action: "case.approve",
    resource: { type: "case", id: params.caseId! },
    context: { tenantId: session.tenantId },
  });

  return approveCase(params.caseId!, await request.formData());
}

Use route loaders/actions for data/mutation auth.
Use React hooks/components for exposure control.
Never rely on component guards alone.

Server Components
Client Components
Route Handlers
Server Actions
Middleware/Proxy

export async function getServerSessionProjection(): Promise<SessionProjection> {
  const session = await requireOrReadSessionFromCookies();

  if (!session) {
    return { status: "anonymous" };
  }

  return projectSessionForClient(session);
}

export function ClientAuthProvider({
  initialSession,
  children,
}: {
  initialSession: SessionProjection;
  children: React.ReactNode;
}) {
  const client = useMemo(() => createHydratedAuthClient(initialSession), [initialSession]);

  return <AuthProvider client={client}>{children}</AuthProvider>;
}

export async function GET() {
  const session = await getServerSessionProjection();

  return Response.json(session, {
    headers: {
      "Cache-Control": "no-store",
    },
  });
}

"use server";

export async function approveCase(input: { caseId: string }) {
  const session = await requireServerSession();

  await enforcePermission({
    subject: session.subject,
    action: "case.approve",
    resource: { type: "case", id: input.caseId },
    context: { tenantId: session.tenantId },
  });

  return approveCaseInDomain(input.caseId, session);
}

Server Components project safe data.
Route Handlers mutate cookies and expose BFF endpoints.
Server Actions enforce mutation authorization.
Client Components consume projection only.
Middleware/Proxy performs coarse route classification only.

Auth0 organization
Clerk organization
Cognito user pool/group
WorkOS organization/connection
OIDC acr/amr/auth_time
SAML attributes/groups

user
account
tenant
membership
role
permission
assurance
session
impersonation

export interface IdentityProviderAdapter {
  getLoginUrl(options: LoginOptions): Promise<string>;
  exchangeCallback(request: Request): Promise<ProviderSession>;
  logout(session: ProviderSession): Promise<void>;
  refresh?(session: ProviderSession): Promise<ProviderSession>;
}

export type ProviderSession = {
  providerUserId: string;
  issuer: string;
  subject: string;
  email?: string;
  name?: string;
  rawClaims: Record<string, unknown>;
  tokens?: {
    accessToken?: string;
    idToken?: string;
    refreshToken?: string;
    expiresAt?: number;
  };
};

export async function mapProviderToAppIdentity(
  providerSession: ProviderSession,
): Promise<AppIdentity> {
  const user = await findOrCreateUserByProviderSubject({
    issuer: providerSession.issuer,
    subject: providerSession.subject,
    email: providerSession.email,
  });

  return {
    userId: user.id,
    displayName: user.displayName,
    linkedProvider: {
      issuer: providerSession.issuer,
      subject: providerSession.subject,
    },
  };
}

hardcoded service policy
SQL permission tables
OPA/Rego
Cedar/Amazon Verified Permissions
OpenFGA/Zanzibar-style ReBAC
custom workflow policy engine

export interface PermissionService {
  check(input: PermissionCheckInput): Promise<PermissionDecision>;
  batchCheck(inputs: PermissionCheckInput[]): Promise<PermissionDecision[]>;
  listAllowedActions(input: ListAllowedActionsInput): Promise<AllowedAction[]>;
}

export type PermissionCheckInput = {
  subject: {
    userId: string;
    tenantId?: string;
    sessionId?: string;
  };
  action: string;
  resource: {
    type: string;
    id?: string;
    attributes?: Record<string, unknown>;
  };
  context?: {
    tenantId?: string;
    assuranceLevel?: string;
    authTime?: string;
    requestId?: string;
  };
};

export interface ApiClient {
  get<T>(path: string, options?: ApiOptions): Promise<T>;
  post<T>(path: string, body: unknown, options?: ApiOptions): Promise<T>;
  put<T>(path: string, body: unknown, options?: ApiOptions): Promise<T>;
  delete<T>(path: string, options?: ApiOptions): Promise<T>;
}

export type ApiOptions = {
  tenantId?: string;
  idempotencyKey?: string;
  signal?: AbortSignal;
  authMode?: "required" | "optional" | "none";
};

BFF/cookie: browser sends same-origin cookie; API client adds CSRF for unsafe methods.
Pure SPA/bearer: API client injects in-memory access token.
SSR/server: server API client attaches verified internal context.
Next Server Action: no browser API client involved; server calls domain directly.

fetch("/api/cases", {
  headers: {
    Authorization: `Bearer ${localStorage.getItem("token")}`,
  },
});

const cases = await apiClient.get<CaseList>("/cases", {
  authMode: "required",
  tenantId,
});

export type AuthEvent =
  | { type: "SESSION_BOOTSTRAPPED"; session: SessionProjection }
  | { type: "SESSION_EXPIRED"; reason: string }
  | { type: "SESSION_REFRESHED"; session: SessionProjection }
  | { type: "LOGOUT_STARTED"; reason: string }
  | { type: "LOGOUT_COMPLETED" }
  | { type: "TENANT_CHANGED"; tenantId: string }
  | { type: "PERMISSION_EPOCH_CHANGED"; epoch: string }
  | { type: "STEP_UP_COMPLETED"; assuranceLevel: string };

React Query adapter clears/invalidate caches.
React Router adapter revalidates routes.
Next client adapter refreshes router state.
BroadcastChannel adapter notifies other tabs.
Analytics adapter emits safe event metadata.

export interface AuthCacheCoordinator {
  onLogout(): Promise<void> | void;
  onTenantChanged(tenantId: string): Promise<void> | void;
  onPermissionEpochChanged(epoch: string): Promise<void> | void;
  onSessionExpired(): Promise<void> | void;
}

TanStack Query: queryClient.clear/remove/invalidate
React Router: revalidator.revalidate / route reload
Apollo: resetStore / clearStore
SWR: mutate keys
Browser storage: remove tenant/user scoped entries
Service worker: delete auth-sensitive caches
Next.js client: router.refresh where appropriate

src/
  auth/
    core/
      session-contract.ts
      permission-contract.ts
      auth-events.ts
      errors.ts
      state-machine.ts
    react/
      AuthProvider.tsx
      useSessionProjection.ts
      useCan.ts
      Can.tsx
    browser/
      spa-auth-client.ts
      broadcast-auth-events.ts
      browser-cache-coordinator.ts
    router/
      react-router-loaders.ts
      react-router-actions.ts
      route-permission-metadata.ts
    next/
      server-session.ts
      route-handlers.ts
      server-actions.ts
      middleware-classifier.ts
      ClientAuthProvider.tsx
    server/
      require-session.ts
      csrf.ts
      session-store.ts
      permission-service.ts
      audit.ts
    providers/
      oidc-provider-adapter.ts
      auth0-adapter.ts
      clerk-adapter.ts
      cognito-adapter.ts
    testing/
      auth-fixtures.ts
      permission-matrix.ts
      mock-auth-client.ts

core imports nothing from framework.
react imports core only.
router imports core/server/react as needed.
next imports core/server/react as needed.
browser never imports server.
server never imports React UI.
providers never leak raw claims into components.

browser code cannot import src/auth/server
client components cannot import token vault
shared code cannot import framework runtime APIs
edge code cannot import node-only modules

ESLint no-restricted-imports
package export maps
separate tsconfig paths
bundle analyzer
unit tests for import graph

{
  "rules": {
    "no-restricted-imports": [
      "error",
      {
        "patterns": [
          {
            "group": ["src/auth/server/*", "src/auth/node/*"],
            "message": "Server auth modules must not be imported into browser code."
          }
        ]
      }
    ]
  }
}

declare const serverOnlyBrand: unique symbol;

export type ServerOnly<T> = T & {
  readonly [serverOnlyBrand]: "server-only";
};

export type RawProviderTokens = ServerOnly<{
  accessToken: string;
  refreshToken?: string;
  idToken?: string;
}>;

SessionProjection
PermissionDecision
AuthClient
PermissionService
ApiClient
AuthEvent

bootstrap moves from component effect to root loader
redirect moves from component guard to loader redirect
mutation auth moves from component submit handler to route action/server API

root loader becomes server layout/session projection
route action becomes server action or route handler
React Router redirect becomes Next redirect/navigation
BFF route handlers become app/api route handlers
router revalidation becomes router.refresh/cache invalidation

IdentityProviderAdapter implementation
callback exchange handling
claim mapping
organization/tenant discovery mapping
webhook sync implementation

auth state transitions
permission decision normalization
deny-by-default behavior
error taxonomy mapping
auth event sequencing
cache coordinator triggers

AuthProvider exposes snapshot
useCan fails closed during unknown state
Can component hides/disables/explains correctly
session update rerenders subscribers

React Router loader redirects anonymous user
React Router action enforces mutation permission
Next Route Handler returns no-store session projection
Next Server Action enforces permission before mutation
Middleware/Proxy only performs coarse classification
SPA adapter bootstraps and handles degraded state

logout clears cache and redirects safely
permission epoch change invalidates UI
tenant switch clears previous tenant data
step-up required triggers recovery flow
server 403 rolls back optimistic UI

client bundle does not contain server secret module
client cannot spoof internal auth headers
component hidden button direct API call still denied
route direct URL access still checked by loader/server
stale permission cache fails closed

1. Framework adapter bootstraps session projection.
2. React AuthProvider exposes safe projection to UI.
3. Permission UI uses `useCan()` with decision projection.
4. API client sends intent through BFF/API.
5. Server validates session, CSRF, tenant, and permission.
6. Origin API enforces business authorization.
7. Audit records decision-relevant evidence.
8. Auth events invalidate caches and revalidate routes.

Core contracts do not import framework modules.
Browser code cannot import server modules.
Provider claims are mapped to app identity.
Permission contract does not expose raw policy internals.
Component checks fail closed.
Route/data checks exist where framework supports them.
Server mutation checks exist regardless of UI checks.
API authorization is tested independently from UI.
Logout clears framework caches and browser caches.
Tenant switch invalidates tenant-scoped state.
Step-up auth is represented in the same decision contract.
Auth errors have stable reason codes.
Audit events use app identity, not provider-only identity.

SPA vs SSR vs BFF trade-offs
BFF token hiding
Next.js App Router auth boundaries
React Server Component leakage risks
Edge middleware/proxy as coarse gate
SSR session refresh and cookie mutation boundaries
hydration/auth mismatch
secure layout composition
multi-runtime auth authority
framework-agnostic auth contracts

Auth code should follow authority boundaries, not component boundaries.

Domain layer:
  session projection
  permission decision
  auth event
  error taxonomy

Runtime layer:
  browser adapter
  router adapter
  server adapter
  edge adapter
  provider adapter
  policy adapter

Enforcement layer:
  BFF/session guard
  API authorization
  policy engine
  audit trail