@uoj-lk/auth-react

React authentication middleware for University of Jaffna Auth Service with OAuth 2.0 + PKCE, httpOnly cookies, time-bound roles, and permissions.

📚 Complete Documentation Index | OAuth Quick Start | Full OAuth Guide | Permission System Update

⚡ What's New in v3.2.0

Network Resilience, Logging, and Safety Nets

• ⏱️ Request Timeouts: API calls now time out by default to avoid hanging UIs
• 🌐 Smarter Errors: isNetworkError, isTimeoutError, and getNetworkErrorMessage utilities for clearer UX
• 🛡️ Runtime Validation: Auth config validated at runtime with friendly errors
• 🧭 Error Boundary: <AuthErrorBoundary> prevents auth failures from crashing the app
• 🔎 Dev Diagnostics: Optional dev logging (enableDevLogging) to trace auth flows locally
• 🧩 DX Polishing: Components have display names; TypeScript defs updated for new helpers

See IMPROVEMENTS_INDEX.md for the full v3.2.0 changeset

✨ Features

🆕 New in v3.0.0

• 🚀 OAuth 2.0 + PKCE - Complete Authorization Code flow for SPAs
• 🔐 Secure Public Client - No client secrets in browser, PKCE required
• ⚡ Drop-in Components - <OAuthButton> and <OAuthCallback> ready to use
• 🎣 OAuth Hooks - startOAuthFlow() and handleOAuthCallback() in useAuth()
• 🛠️ PKCE Utilities - Code verifier/challenge generation with fallbacks
• 🔒 CSRF Protection - Automatic state validation
• 🌐 Works Anywhere - Web Crypto with js-sha256 fallback for non-secure contexts

Core Features

• 🔐 Complete Authentication - Session-based login, OAuth, automatic token refresh
• ⏰ Time-Bound Roles - Support for roles with start/end dates
• 🏢 Organization Context - Multi-organization role management
• 🎯 Permission-Based UI - Show/hide components based on permissions
• 🛡️ 8+ Middleware Components - Ready-to-use access control components
• 📊 Role Expiry Tracking - Automatic warnings for expiring roles
• 🔄 Flexible Permission Checks - Support for multiple formats and combinations
• 🎨 TypeScript Support - Full type definitions included
• 🔙 Backward Compatible - All v2.x features preserved

📦 Installation

npm install @uoj-lk/auth-react

Peer Dependencies

This package requires the following peer dependencies:

npm install react react-dom react-router-dom

📖 Documentation

📚 Complete Documentation Index →

Quick links:

• OAuth Quick Start - 30-second setup
• OAuth Complete Guide - In-depth OAuth guide
• Publishing Guide - Maintain & publish package

🚀 Quick Start

Method 1: OAuth 2.0 Flow (Recommended for SPAs)

1. Setup AuthProvider

import React from "react";
import { BrowserRouter as Router, Routes, Route } from "react-router-dom";
import {
  AuthProvider,
  OAuthButton,
  OAuthCallback,
  ProtectedRoute,
  AuthErrorBoundary,
} from "@uoj-lk/auth-react";
import Dashboard from "./pages/Dashboard";

// Configure authentication
const authConfig = {
  apiUrl: "https://api.example.com/api",
  clientId: "your-client-id",
  requestTimeout: 10000, // Optional: abort slow requests (ms)
  enableDevLogging: process.env.NODE_ENV === "development",
  // No clientSecret for public clients (SPAs)
};

function App() {
  return (
    <Router>
      <AuthErrorBoundary>
        <AuthProvider config={authConfig}>
          <Routes>
            {/* Login with OAuth */}
            <Route
              path="/login"
              element={
                <div>
                  <h1>Login</h1>
                  <OAuthButton authUrl="https://auth.example.com/oauth/authorize">
                    Sign in with OAuth
                  </OAuthButton>
                </div>
              }
            />

            {/* OAuth Callback Handler */}
            <Route
              path="/oauth/callback"
              element={
                <OAuthCallback tokenUrl="https://api.example.com/api/oauth/token" />
              }
            />

            {/* Protected Dashboard */}
            <Route
              path="/dashboard"
              element={
                <ProtectedRoute>
                  <Dashboard />
                </ProtectedRoute>
              }
            />
          </Routes>
        </AuthProvider>
      </AuthErrorBoundary>
    </Router>
  );
}

export default App;

2. Use Auth in Your Components

import { useAuth } from "@uoj-lk/auth-react";

function Dashboard() {
  const { user, logout, hasPermission, hasRole } = useAuth();

  return (
    <div>
      <h1>Welcome, {user?.firstName}!</h1>
      <button onClick={logout}>Logout</button>

      {hasRole("admin") && <div>Admin Panel</div>}
      {hasPermission("course", "create") && <button>Create Course</button>}
    </div>
  );
}

Handle Network/Timeout Errors

import {
  isNetworkError,
  isTimeoutError,
  getNetworkErrorMessage,
} from "@uoj-lk/auth-react";

async function saveProfile(payload) {
  try {
    // your API call here
  } catch (error) {
    if (isTimeoutError(error)) return alert("Request took too long");
    if (isNetworkError(error)) return alert("You appear offline");
    return alert(getNetworkErrorMessage(error));
  }
}

Method 2: Session-Based Login (Traditional)

1. Wrap Your App with AuthProvider

import React from "react";
import { BrowserRouter as Router, Routes, Route } from "react-router-dom";
import { AuthProvider, ProtectedRoute } from "@uoj-lk/auth-react";
import Login from "./pages/Login";
import Dashboard from "./pages/Dashboard";

// Configure authentication
const authConfig = {
  apiUrl: "https://your-auth-api.com/api",
  clientId: "your-client-id",
  clientSecret: "your-client-secret", // For confidential clients
};

function App() {
  return (
    <Router>
      <AuthProvider config={authConfig}>
        <Routes>
          <Route path="/login" element={<Login />} />
          <Route
            path="/dashboard"
            element={
              <ProtectedRoute>
                <Dashboard />
              </ProtectedRoute>
            }
          />
        </Routes>
      </AuthProvider>
    </Router>
  );
}

export default App;

2. Use Auth in Your Components

import { useAuth } from "@uoj-lk/auth-react";

function Login() {
  const { login } = useAuth();

  const handleSubmit = async (e) => {
    e.preventDefault();
    const { success } = await login({
      username: e.target.username.value,
      password: e.target.password.value,
    });

    if (success) {
      // Redirect to dashboard
    }
  };

  return <form onSubmit={handleSubmit}>...</form>;
}

function Dashboard() {
  const { user, logout, hasPermission } = useAuth();

  return (
    <div>
      <h1>Welcome, {user?.firstName}!</h1>
      <button onClick={logout}>Logout</button>

      {hasPermission("course", "create") && <button>Create Course</button>}
    </div>
  );
}

🔓 OAuth 2.0 Components (v3.0.0)

OAuthButton

Initiates OAuth 2.0 Authorization Code + PKCE flow.

import { OAuthButton } from "@uoj-lk/auth-react";

<OAuthButton
  authUrl="https://auth.example.com/oauth/authorize"
  scope="openid profile email"
  callbackPath="/oauth/callback"
  className="btn btn-primary"
>
  Sign in with OAuth
</OAuthButton>;

Props:

| Prop | Type | Default | Description | | -------------- | ----------- | ------------------------ | -------------------------- | | authUrl | string | Required | Authorization endpoint URL | | scope | string | 'openid profile email' | OAuth scopes | | callbackPath | string | '/oauth/callback' | Callback path | | extraParams | object | {} | Additional OAuth params | | className | string | 'btn btn-primary' | CSS classes | | children | ReactNode | 'Sign in with OAuth' | Button content | | disabled | boolean | false | Disable button |

OAuthCallback

Handles OAuth callback, validates state, exchanges code for tokens.

import { OAuthCallback } from "@uoj-lk/auth-react";

<OAuthCallback
  tokenUrl="https://api.example.com/api/oauth/token"
  successPath="/dashboard"
  errorPath="/login"
  onSuccess={(user) => console.log("Logged in:", user)}
  onError={(err) => console.error("Login failed:", err)}
/>;

Props:

| Prop | Type | Default | Description | | ------------------ | ----------- | ------------------- | ------------------- | | tokenUrl | string | Required | Token endpoint URL | | callbackPath | string | '/oauth/callback' | Callback path | | successPath | string | '/dashboard' | Redirect on success | | errorPath | string | '/login' | Redirect on error | | onSuccess | function | - | Success callback | | onError | function | - | Error callback | | loadingComponent | ReactNode | Default spinner | Custom loading UI | | errorComponent | function | Default alert | Custom error UI |

🔐 Middleware Components

ProtectedRoute

Requires user to be authenticated.

import { ProtectedRoute } from "@uoj-lk/auth-react";

<Route
  path="/dashboard"
  element={
    <ProtectedRoute redirectTo="/login">
      <Dashboard />
    </ProtectedRoute>
  }
/>;

RequireRole

Requires user to have a specific role.

import { RequireRole } from "@uoj-lk/auth-react";

<RequireRole role="Admin">
  <AdminPanel />
</RequireRole>;

RequirePermission

Requires user to have a specific permission.

import { RequirePermission } from "@uoj-lk/auth-react";

// Method 1: Separate resource and action
<RequirePermission resource="course" action="create">
  <CreateCourseButton />
</RequirePermission>

// Method 2: Combined permission string
<RequirePermission permission="course:create">
  <CreateCourseButton />
</RequirePermission>

RequireRoleInOrganization

Requires user to have a role in a specific organization.

import { RequireRoleInOrganization } from "@uoj-lk/auth-react";

<RequireRoleInOrganization role="Instructor" organizationId={1}>
  <CourseList />
</RequireRoleInOrganization>;

RequireAnyPermission

Requires user to have at least one of the specified permissions.

import { RequireAnyPermission } from "@uoj-lk/auth-react";

<RequireAnyPermission permissions={["course:create", "course:update"]}>
  <CourseEditor />
</RequireAnyPermission>;

RequireAllPermissions

Requires user to have all of the specified permissions.

import { RequireAllPermissions } from "@uoj-lk/auth-react";

<RequireAllPermissions permissions={["course:create", "student:read"]}>
  <FullCourseManager />
</RequireAllPermissions>;

RequireOrganization

Requires user to belong to a specific organization.

import { RequireOrganization } from "@uoj-lk/auth-react";

<RequireOrganization organizationId={1}>
  <DepartmentDashboard />
</RequireOrganization>;

ConditionalRender

Custom condition-based rendering.

import { ConditionalRender } from "@uoj-lk/auth-react";

<ConditionalRender
  condition={({ hasPermission, hasRole }) =>
    hasPermission("report:generate") && hasRole("Admin")
  }
>
  <AdvancedReports />
</ConditionalRender>;

🎯 useAuth Hook

The useAuth hook provides access to authentication state and helper functions.

Available Properties

const {
  // State
  user, // Current user object
  loading, // Loading state (initial auth check)
  permissionsLoading, // NEW v3.1: Permissions loading state
  error, // Error message
  isAuthenticated, // Boolean flag

  // Actions
  login, // Login function (session-based)
  logout, // Logout function

  // OAuth 2.0 (v3.0.0)
  startOAuthFlow, // Start OAuth authorization
  handleOAuthCallback, // Handle OAuth callback

  // Role Checks
  hasRole, // Check if user has a role
  hasRoleInOrganization, // Check role in specific org
  getActiveRoles, // Get all active roles

  // Permission Checks
  hasPermission, // Check single permission
  hasAnyPermission, // Check if has any of multiple
  hasAllPermissions, // Check if has all of multiple

  // Organization
  belongsToOrganization, // Check org membership
  getOrganizations, // Get all organizations
  getPermissionsForOrganization, // Get org permissions

  // Time-Bound Roles
  calculateDaysRemaining, // Calculate days to expiry
  getExpiringRoles, // Get roles expiring soon

  // Error Handling (NEW v3.1)
  parseError, // Parse API error details
  formatPermissionError, // Format 403 error message
  isPermissionError, // Check if error is 403
  isAuthenticationError, // Check if error is 401
  getErrorMessage, // Get user-friendly message
} = useAuth();

Examples

OAuth Login (v3.0.0)

const { startOAuthFlow } = useAuth();

const handleOAuthLogin = async () => {
  await startOAuthFlow({
    authUrl: "https://auth.example.com/oauth/authorize",
    scope: "openid profile email",
    callbackPath: "/oauth/callback",
  });
  // User will be redirected to authorization server
};

Session Login

const { login } = useAuth();

const handleSubmit = async (e) => {
  e.preventDefault();
  const result = await login({ username, password });

  if (result.success) {
    navigate("/dashboard");
  } else {
    setError(result.error);
  }
};

Check Permissions

const { hasPermission, hasAnyPermission } = useAuth();

// Single permission
if (hasPermission("course", "create")) {
  // Show create button
}

// Alternative format
if (hasPermission("course:create")) {
  // Show create button
}

// Multiple permissions (any)
if (hasAnyPermission(["course:create", "course:update"])) {
  // Show editor
}

Role Expiry Tracking

const { getExpiringRoles, calculateDaysRemaining } = useAuth();

const expiringRoles = getExpiringRoles(30); // Roles expiring in 30 days

expiringRoles.forEach((role) => {
  const daysLeft = calculateDaysRemaining(role.endDate);
  console.log(`${role.name} expires in ${daysLeft} days`);
});

🚨 Error Handling (v3.1.0)

useErrorHandler Hook

Handle API errors with permission-aware messaging:

import { useErrorHandler } from "@uoj-lk/auth-react";

function MyComponent() {
  const { handleError, handlePermissionError, isPermissionError } =
    useErrorHandler();

  const deleteRole = async (roleId) => {
    try {
      await api.deleteRole(roleId);
    } catch (error) {
      if (isPermissionError(error)) {
        // Handle 403 - show detailed permission requirements
        const permError = handlePermissionError(error);
        console.log(permError.formattedMessage);
        // "Insufficient permissions. Required permissions: roles:manage"
      } else {
        // Handle other errors
        const errorInfo = handleError(error);
        console.log(errorInfo.message);
      }
    }
  };
}

usePermissionCheck Hook

Check permissions with fallback support:

import { usePermissionCheck } from "@uoj-lk/auth-react";

const { canAccess } = usePermissionCheck();

// Check permission with role fallback
if (canAccess("course:update", "ADMIN")) {
  // Show edit button if has permission OR is admin
}

// Check multiple permissions
if (canAccess(["course:create", "course:update"])) {
  // Show editor if has ANY permission
}

useAuthState Hook

Simple access to authentication state:

import { useAuthState } from "@uoj-lk/auth-react";

const { isReady, isLoading, isPermissionsLoading, isAuthenticated } =
  useAuthState();

if (!isReady) {
  return <Loading />; // Wait for both auth and permissions
}

// Safe to check permissions now

PermissionErrorDisplay Component

Display formatted permission errors:

import { PermissionErrorDisplay } from "@uoj-lk/auth-react";

const [error, setError] = useState(null);

<PermissionErrorDisplay
  error={error}
  onDismiss={() => setError(null)}
  dismissable={true}
/>;

AsyncActionWithErrorHandling Component

Handle async actions with automatic error display:

import { AsyncActionWithErrorHandling } from "@uoj-lk/auth-react";

<AsyncActionWithErrorHandling
  onAction={async () => await api.deleteRole(roleId)}
  actionLabel="Delete Role"
  onSuccess={() => toast.success("Role deleted")}
/>;

FormWithPermissionHandling Component

Forms with permission-aware error handling:

import { FormWithPermissionHandling } from "@uoj-lk/auth-react";

<FormWithPermissionHandling
  onSubmit={handleSubmit}
  successMessage="Role created successfully"
>
  <MyFormFields />
</FormWithPermissionHandling>;

�️ OAuth Utilities (v3.0.0)

For advanced OAuth use cases, you can use the low-level utilities directly:

PKCE Utilities

import {
  generateCodeVerifier,
  computeCodeChallengeS256,
  generateState,
  storePKCE,
  loadPKCE,
  clearPKCE,
} from "@uoj-lk/auth-react";

// Generate PKCE parameters
const verifier = generateCodeVerifier(64); // 43-128 chars
const challenge = await computeCodeChallengeS256(verifier);
const state = generateState();

// Store for callback validation
storePKCE({ codeVerifier: verifier, state });

// Later, in callback
const { codeVerifier, state: storedState } = loadPKCE();

// After token exchange
clearPKCE();

OAuth Flow Utilities

import {
  buildAuthorizeUrl,
  parseCallbackParams,
  validateState,
  exchangeCodeForTokens,
  getRedirectUri,
} from "@uoj-lk/auth-react";

// Build authorization URL
const authUrl = buildAuthorizeUrl({
  authUrl: "https://auth.example.com/oauth/authorize",
  clientId: "your-client-id",
  redirectUri: getRedirectUri("/oauth/callback"),
  codeChallenge: challenge,
  state,
  scope: "openid profile email",
});

// Parse callback parameters
const { code, state, error, errorDescription } = parseCallbackParams(
  window.location.search
);

// Validate state (CSRF protection)
if (!validateState(state, storedState)) {
  console.error("State mismatch - possible CSRF attack");
}

// Exchange code for tokens
await exchangeCodeForTokens({
  tokenUrl: "https://api.example.com/api/oauth/token",
  code,
  clientId: "your-client-id",
  redirectUri: getRedirectUri("/oauth/callback"),
  codeVerifier,
  httpClient: axiosInstance,
});

Security Features:

• ✅ PKCE: Prevents authorization code interception
• ✅ State Validation: CSRF protection
• ✅ Secure RNG: Uses crypto.getRandomValues() when available
• ✅ Fallback Support: Works in non-secure contexts (development)

�📊 User Object Structure

interface User {
  id: number;
  username: string;
  email: string;
  firstName: string;
  lastName: string;
  phone?: string;
  isLdapUser: boolean;
  isActive: boolean;

  // Simple role names (backward compatibility)
  roles: string[];

  // Full role details with time-bound support
  roleDetails: RoleDetail[];

  // Aggregated permissions from all active roles
  permissions: Permission[];

  // Organizations user belongs to
  organizations: Organization[];
}

⚙️ Configuration

AuthProvider Props

| Prop | Type | Required | Default | Description | | ---------- | --------- | -------- | ------- | -------------------------------------------------------- | | children | ReactNode | Yes | - | Child components | | config | object | No | - | Configuration object with apiUrl, clientId, clientSecret | | authAPI | object | No | - | Custom API client (for advanced usage) |

Config Object

| Property | Type | Required | Default | Description | | -------------- | -------- | -------- | ------- | ---------------------- | | apiUrl | string | Yes | - | Backend API URL | | clientId | string | No | - | OAuth client ID | | clientSecret | string | No | - | OAuth client secret | | onLogout | function | No | - | Custom logout callback |

Environment Variables

If you're using Vite, you can set these in .env:

VITE_API_URL=https://your-auth-api.com/api
VITE_CLIENT_ID=your-client-id
VITE_CLIENT_SECRET=your-client-secret

Then use them in your config:

const authConfig = {
  apiUrl: import.meta.env.VITE_API_URL || "http://localhost:3000/api",
  clientId: import.meta.env.VITE_CLIENT_ID,
  clientSecret: import.meta.env.VITE_CLIENT_SECRET,
};

<AuthProvider config={authConfig}>{/* Your app */}</AuthProvider>;

Advanced Configuration

Custom Logout Callback

const authConfig = {
  apiUrl: "https://your-auth-api.com/api",
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  onLogout: () => {
    console.log("User logged out");
    // Custom cleanup logic
  },
};

Custom API Client

For advanced use cases, you can provide a custom API client:

import { createAuthAPI } from "@uoj-lk/auth-react";

const customAPI = createAuthAPI({
  apiUrl: "https://your-auth-api.com/api",
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  onLogout: () => {
    // Custom logout logic
  },
});

<AuthProvider authAPI={customAPI}>{/* Your app */}</AuthProvider>;

🔄 Automatic Token Refresh

The package automatically handles token refresh when the access token expires. The API client includes an interceptor that:

1. Detects 401 responses
2. Attempts to refresh the token using the refresh token
3. Retries the original request with the new token
4. Redirects to login if refresh fails

🎨 Custom Fallbacks

All middleware components support custom fallback UI:

<RequirePermission
  resource="course"
  action="delete"
  fallback={
    <div className="alert alert-danger">
      You don't have permission to delete courses. Contact your administrator.
    </div>
  }
>
  <DeleteButton />
</RequirePermission>

📚 Advanced Examples

Conditional Navigation Menu

import { ConditionalRender } from "@uoj-lk/auth-react";

function Navigation() {
  return (
    <nav>
      <ConditionalRender
        condition={({ hasPermission }) => hasPermission("course:read")}
      >
        <NavItem to="/courses">My Courses</NavItem>
      </ConditionalRender>

      <ConditionalRender condition={({ hasRole }) => hasRole("Admin")}>
        <NavItem to="/admin">Admin Panel</NavItem>
      </ConditionalRender>
    </nav>
  );
}

Role Expiry Warning

import { useAuth } from "@uoj-lk/auth-react";

function RoleExpiryAlert() {
  const { getExpiringRoles, calculateDaysRemaining } = useAuth();
  const expiringRoles = getExpiringRoles(30);

  if (expiringRoles.length === 0) return null;

  return (
    <div className="alert alert-warning">
      <strong>Warning!</strong> You have {expiringRoles.length} role(s) expiring
      soon:
      <ul>
        {expiringRoles.map((role, idx) => (
          <li key={idx}>
            {role.name} in {role.organization?.name} -
            {calculateDaysRemaining(role.endDate)} days remaining
          </li>
        ))}
      </ul>
    </div>
  );
}

Organization Switcher

import { useAuth } from "@uoj-lk/auth-react";

function OrganizationSelector() {
  const { getOrganizations, user } = useAuth();
  const organizations = getOrganizations();

  return (
    <select>
      {organizations.map((org) => (
        <option key={org.id} value={org.id}>
          {org.name} ({org.code})
        </option>
      ))}
    </select>
  );
}

🔒 Security Best Practices

OAuth 2.0 Security (v3.0.0)

PKCE Required: The package automatically implements PKCE (Proof Key for Code Exchange) for all OAuth flows to prevent authorization code interception attacks.

State Validation: Every OAuth request includes a random state parameter that is validated on callback to prevent CSRF attacks.

No Client Secrets: Public clients (SPAs) should never store client secrets. Use clientId only in AuthProvider config.

HTTPS in Production: OAuth requires HTTPS in production. The package works with HTTP in development but shows warnings.

// ✅ Good - Public client (SPA)
const authConfig = {
  apiUrl: "https://api.example.com/api",
  clientId: "your-client-id",
  // No clientSecret for SPAs
};

// ❌ Bad - Secret exposed in browser
const authConfig = {
  apiUrl: "https://api.example.com/api",
  clientId: "your-client-id",
  clientSecret: "secret-key", // NEVER in browser!
};

Environment Variables

Never hardcode sensitive credentials in your code. Always use environment variables:

// ✅ Good - Using environment variables
const authConfig = {
  apiUrl: import.meta.env.VITE_API_URL,
  clientId: import.meta.env.VITE_CLIENT_ID,
  clientSecret: import.meta.env.VITE_CLIENT_SECRET,
};

// ❌ Bad - Hardcoded credentials
const authConfig = {
  apiUrl: "https://api.example.com",
  clientId: "my-client-id",
  clientSecret: "my-secret-key", // NEVER DO THIS!
};

Token Storage

The package uses httpOnly cookies for token storage (when backend supports it) for enhanced security. Tokens are never exposed to JavaScript, preventing XSS attacks.

For OAuth flows, tokens are automatically stored in httpOnly cookies by the backend after successful authorization.

HTTPS Only

Always use HTTPS in production to prevent man-in-the-middle attacks:

const authConfig = {
  apiUrl: "https://your-api.com/api", // ✅ HTTPS
  // apiUrl: "http://your-api.com/api", // ❌ HTTP - Never in production!
};

Error Handling

The package automatically sanitizes error messages. API errors are caught and generic messages are shown to users to prevent information leakage.

Content Security Policy (CSP)

Configure your CSP headers to restrict API calls:

Content-Security-Policy: connect-src 'self' https://your-auth-api.com;

Input Validation

Always validate user input before passing to the login function:

const handleLogin = async (credentials) => {
  // Validate credentials
  if (!credentials.username || !credentials.password) {
    setError("Username and password are required");
    return;
  }

  if (credentials.username.length < 3) {
    setError("Invalid username format");
    return;
  }

  // Proceed with login
  const result = await login(credentials);
  // ...
};

Rate Limiting

Implement rate limiting on your authentication endpoints to prevent brute-force attacks. The package doesn't include rate limiting - this must be handled by your backend.

Audit Logging

Log authentication events (login, logout, failed attempts) on your backend for security auditing. Never log credentials or tokens.

🐛 Troubleshooting

OAuth Issues (v3.0.0)

"crypto.subtle is undefined"

Cause: Web Crypto API not available in non-secure context (http://)

Solution: This is normal for development. The package automatically falls back to js-sha256. For production, use HTTPS.

"State mismatch - possible CSRF attack"

Cause: State parameter doesn't match stored value

Solution:

• Don't refresh the page during OAuth flow
• Clear browser cache and try again
• Check that callback URL is registered correctly

"Missing authorization code"

Cause: Authorization was denied or redirect URI not registered

Solution:

• Check backend logs for authorization errors
• Verify redirect URI exactly matches backend registration
• Ensure user approved the authorization request

"Invalid client_id"

Cause: Client ID not configured or doesn't match backend

Solution: Verify clientId in AuthProvider config matches the client registered in backend.

General Issues

"useAuth must be used within AuthProvider"

Make sure AuthProvider wraps all components that use useAuth:

// ❌ Wrong
<BrowserRouter>
  <Routes>
    <Route path="/dashboard" element={<Dashboard />} />
  </Routes>
  <AuthProvider>...</AuthProvider>
</BrowserRouter>

// ✅ Correct
<BrowserRouter>
  <AuthProvider>
    <Routes>
      <Route path="/dashboard" element={<Dashboard />} />
    </Routes>
  </AuthProvider>
</BrowserRouter>

Token Refresh Not Working

Ensure your backend returns a refresh token on login and has a /auth/refresh endpoint.

Permissions Not Showing

Check that your backend returns the enriched user object with:

• roleDetails (array of role objects with permissions)
• permissions (aggregated permission array)
• organizations (user's organizations)

"apiUrl is required" Error

This error occurs when AuthProvider doesn't have a valid API URL. Fix by:

// Option 1: Provide config prop
<AuthProvider config={{ apiUrl: "https://your-api.com/api" }}>

// Option 2: Set environment variable
// In .env file:
VITE_API_URL=https://your-api.com/api

🛡️ Production Checklist

Before deploying to production, ensure:

• [ ] All sensitive credentials are in environment variables (not hardcoded)
• [ ] Using HTTPS for all API communication
• [ ] Environment variables are properly configured in your deployment platform
• [ ] Backend has rate limiting enabled on authentication endpoints
• [ ] Backend implements proper CORS policies
• [ ] Audit logging is enabled on backend
• [ ] Token expiration times are appropriate for your use case
• [ ] CSP headers are configured to restrict API calls
• [ ] Error messages don't expose sensitive information
• [ ] Authentication events are monitored and alerted

� Migration Guide

From v2.x to v3.0.0

Good news: No breaking changes! All v2.x code continues to work.

What's New

// v2.x - Still works in v3.0.0
const { user, login, logout, hasRole, hasPermission } = useAuth();

// v3.0.0 - New OAuth features available
const {
  user,
  login,
  logout,
  hasRole,
  hasPermission,
  startOAuthFlow, // NEW
  handleOAuthCallback, // NEW
} = useAuth();

Adding OAuth to Existing App

1. Install v3.0.0

   npm install @uoj-lk/[email protected]

2. Add OAuth routes (your existing session login still works)

   import { OAuthButton, OAuthCallback } from "@uoj-lk/auth-react";
   
   <Routes>
     {/* Existing session login - still works */}
     <Route path="/login" element={<LoginPage />} />
   
     {/* New OAuth option - add alongside */}
     <Route
       path="/oauth/start"
       element={<OAuthButton authUrl="...">OAuth Login</OAuthButton>}
     />
     <Route path="/oauth/callback" element={<OAuthCallback tokenUrl="..." />} />
   </Routes>;

3. Update config (optional - remove clientSecret for public clients)

   // v2.x config
   const authConfig = {
     apiUrl: "...",
     clientId: "...",
     clientSecret: "...", // Remove for SPAs
   };
   
   // v3.0.0 config (for OAuth public clients)
   const authConfig = {
     apiUrl: "...",
     clientId: "...",
     // No clientSecret for OAuth SPAs
   };

That's it! Your existing session-based login continues working, and you can now add OAuth as an alternative login method.

�📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📧 Support

For issues and questions:

• GitHub Issues: https://github.com/UoJ-LK/myuoj-auth/issues
• Documentation: https://github.com/UoJ-LK/myuoj-auth

🔗 Related Packages

• @uoj-lk/auth-node - Node.js/Express backend middleware (coming soon)

Made with ❤️ by University of Jaffna