┌─────────────────────────────────────────────────────────────┐
│                  JWT Authentication Flow                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. User submits email + password                           │
│         │                                                   │
│         ▼                                                   │
│  2. Server validates credentials                            │
│         │                                                   │
│         ▼                                                   │
│  3. Server returns a signed JWT (JSON Web Token)            │
│         │                                                   │
│         ▼                                                   │
│  4. Client stores the token (localStorage / cookie)         │
│         │                                                   │
│         ▼                                                   │
│  5. Client sends token in headers for every API request     │
│         │                                                   │
│         ▼                                                   │
│  6. Server verifies token and returns protected data        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

const login = async (email, password) => {
  const res = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password })
  });
  
  const data = await res.json();
  
  if (data.token) {
    // Store the token so it survives page refreshes.
    // The token is a signed string like "eyJhbG..." that
    // the server will verify on every protected request.
    localStorage.setItem('token', data.token);
  }
};

const token = localStorage.getItem('token');

const res = await fetch('/api/protected', {
  headers: {
    // The "Bearer" prefix is the standard convention.
    // Some APIs use a custom header like 'x-auth-token' instead.
    'Authorization': `Bearer ${token}`
  }
});

// api.js - a thin wrapper that auto-attaches the auth token
async function authFetch(url, options = {}) {
  const token = localStorage.getItem('token');

  const res = await fetch(url, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      // Spread any custom headers the caller provides
      ...options.headers,
      // Attach the token if one exists
      ...(token ? { Authorization: `Bearer ${token}` } : {})
    }
  });

  // If the server responds with 401, the token is expired or invalid.
  // Clear it and redirect to login so the user can re-authenticate.
  if (res.status === 401) {
    localStorage.removeItem('token');
    window.location.href = '/login';
  }

  return res;
}

// Usage throughout your app
const users = await authFetch('/api/users').then(r => r.json());

import { createContext, useState, useEffect, useContext } from 'react';

const AuthContext = createContext(null);

export const AuthProvider = ({ children }) => {
  const [user, setUser] = useState(null);
  // Start as `true` because we need to check for a saved token
  // before we know if the user is authenticated or not.
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    // On mount, check if a token already exists (e.g., the user
    // refreshed the page). If it does, validate it with the server.
    const token = localStorage.getItem('token');
    if (token) {
      // In production, you should verify the token with your
      // backend (e.g., GET /api/auth/me) to confirm it has not
      // expired or been revoked. For now we trust its presence.
      setUser({ token }); 
    }
    setLoading(false);
  }, []);

  const login = (token) => {
    localStorage.setItem('token', token);
    setUser({ token });
  };

  const logout = () => {
    localStorage.removeItem('token');
    setUser(null);
  };

  return (
    // Render children only after the auth check finishes.
    // This prevents a flash of the login page before the
    // saved token is read from localStorage.
    <AuthContext.Provider value={{ user, login, logout, loading }}>
      {!loading && children}
    </AuthContext.Provider>
  );
};

// Custom hook -- always prefer this over exporting the context directly.
// It gives you a single place to add error handling if the provider is missing.
export const useAuth = () => {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
};

import { Navigate, Outlet, useLocation } from 'react-router-dom';
import { useAuth } from './AuthContext';

const PrivateRoute = () => {
  const { user, loading } = useAuth();
  const location = useLocation();

  // While checking auth state, show a loading indicator instead of
  // flashing the login page. This prevents a jarring UX on page refresh.
  if (loading) return <div>Loading...</div>;

  // If not authenticated, redirect to login.
  // Save the current location in `state` so we can redirect back
  // after the user successfully logs in.
  return user
    ? <Outlet />
    : <Navigate to="/login" state={{ from: location }} replace />;
};

export default PrivateRoute;

import { Routes, Route } from 'react-router-dom';
import PrivateRoute from './PrivateRoute';
import Dashboard from './Dashboard';
import Login from './Login';

function App() {
  return (
    <Routes>
      {/* Public routes -- anyone can access these */}
      <Route path="/login" element={<Login />} />
      
      {/* Protected routes -- PrivateRoute checks auth first */}
      <Route element={<PrivateRoute />}>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/profile" element={<Profile />} />
      </Route>
    </Routes>
  );
}

function LoginPage() {
  const { login } = useAuth();
  const navigate = useNavigate();
  const location = useLocation();

  // The route the user was trying to visit before being redirected.
  // Falls back to /dashboard if they navigated to /login directly.
  const from = location.state?.from?.pathname || '/dashboard';

  const handleSubmit = async (e) => {
    e.preventDefault();
    const token = await authenticateWithServer(email, password);
    login(token);
    // Send the user to where they originally wanted to go
    navigate(from, { replace: true });
  };

  return (/* login form */);
}

function RoleRoute({ allowedRoles }) {
  const { user } = useAuth();

  // First check: is the user authenticated at all?
  if (!user) {
    return <Navigate to="/login" replace />;
  }

  // Second check: does the user's role match the allowed list?
  // This is an authorization check, not an authentication check.
  // The user is who they say they are -- but are they permitted?
  if (!allowedRoles.includes(user.role)) {
    return <Navigate to="/unauthorized" replace />;
  }

  return <Outlet />;
}

// Usage -- only admins and editors can access /admin
<Route element={<RoleRoute allowedRoles={['admin', 'editor']} />}>
  <Route path="/admin" element={<AdminPanel />} />
</Route>