@master-auth/react

React authentication package for Master Auth system - a secure, password-based authentication solution.

Installation

npm install @master-auth/react

Quick Start

import React from 'react';
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { MasterAuthProvider, ProtectedRoute, AuthCallback } from '@master-auth/react';

function App() {
  return (
    <MasterAuthProvider applicationId="your-app-id">
      <BrowserRouter>
        <Routes>
          <Route path="/auth/callback" element={<AuthCallback />} />
          <Route
            path="/dashboard"
            element={
              <ProtectedRoute>
                <Dashboard />
              </ProtectedRoute>
            }
          />
        </Routes>
      </BrowserRouter>
    </MasterAuthProvider>
  );
}

API Reference

<MasterAuthProvider>

The root provider component that wraps your application and provides authentication context.

Props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | applicationId | string | Yes | Your Master Auth application ID | | children | ReactNode | Yes | Your application components |

Example:

<MasterAuthProvider applicationId="your-app-id">
  <App />
</MasterAuthProvider>

<ProtectedRoute>

A wrapper component that protects routes requiring authentication. Automatically redirects to login if user is not authenticated.

Props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | children | ReactNode | Yes | Components to render when authenticated | | loadingComponent | ReactNode | No | Custom loading component (default: centered "Loading...") | | fallback | ReactNode | No | Component to show before redirect when not authenticated |

Example:

<ProtectedRoute
  loadingComponent={<Spinner />}
  fallback={<div>Redirecting to login...</div>}
>
  <Dashboard />
</ProtectedRoute>

Behavior:

• Checks for local authentication credentials
• Validates token with backend
• Shows loading state during validation
• Redirects to Master Auth login if invalid/missing credentials
• Renders children when authenticated

<AuthCallback>

Handles the OAuth callback from Master Auth login. Place this component at your callback route.

Props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | onSuccess | (path: string) => void | No | Custom success handler (default: navigates to /dashboard) | | onError | () => void | No | Custom error handler (default: redirects to login after 2s) | | loadingComponent | ReactNode | No | Custom loading component (default: centered "Authenticating...") |

Example:

<AuthCallback
  onSuccess={(path) => {
    console.log('Login successful!');
    navigate(path);
  }}
  onError={() => {
    console.error('Login failed');
    navigate('/');
  }}
  loadingComponent={<Spinner />}
/>

Behavior:

• Extracts authentication parameters from URL (token, salt, sessionId, expiresIn)
• Saves credentials to localStorage
• Validates token with backend
• Calls onSuccess or navigates to /dashboard on success
• Calls onError or redirects to login on failure

useAuth()

Hook to access authentication state and methods.

Returns:

{
  isAuthenticated: boolean;
  logout: () => void;
  user?: any;
}

Example:

import { useAuth } from '@master-auth/react';

function Profile() {
  const { isAuthenticated, logout, user } = useAuth();

  return (
    <div>
      {isAuthenticated ? (
        <>
          <p>Welcome back!</p>
          <button onClick={logout}>Logout</button>
        </>
      ) : (
        <p>Please log in</p>
      )}
    </div>
  );
}

Environment Variables

Your application needs to know its Master Auth application ID. Set it in your environment:

For Vite:

VITE_APPLICATION_ID=your-app-id

Then use it in your app:

<MasterAuthProvider applicationId={import.meta.env.VITE_APPLICATION_ID}>
  <App />
</MasterAuthProvider>

For Create React App:

REACT_APP_APPLICATION_ID=your-app-id

<MasterAuthProvider applicationId={process.env.REACT_APP_APPLICATION_ID}>
  <App />
</MasterAuthProvider>

Complete Example

Here's a complete example with routing, protected pages, and authentication:

// App.jsx
import React from 'react';
import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
import { MasterAuthProvider, ProtectedRoute, AuthCallback, useAuth } from '@master-auth/react';

// Public landing page
function LandingPage() {
  return (
    <div>
      <h1>Welcome to My App</h1>
      <p>Please log in to continue</p>
    </div>
  );
}

// Protected dashboard
function Dashboard() {
  const { logout, user } = useAuth();

  return (
    <div>
      <h1>Dashboard</h1>
      <p>You are logged in!</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

// Custom loading component
function LoadingSpinner() {
  return (
    <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', minHeight: '100vh' }}>
      <div className="spinner">Loading...</div>
    </div>
  );
}

function App() {
  return (
    <MasterAuthProvider applicationId={import.meta.env.VITE_APPLICATION_ID}>
      <BrowserRouter>
        <Routes>
          {/* Public routes */}
          <Route path="/" element={<LandingPage />} />

          {/* Auth callback route */}
          <Route
            path="/auth/callback"
            element={
              <AuthCallback
                loadingComponent={<LoadingSpinner />}
                onSuccess={(path) => {
                  console.log('Authentication successful');
                }}
              />
            }
          />

          {/* Protected routes */}
          <Route
            path="/dashboard"
            element={
              <ProtectedRoute loadingComponent={<LoadingSpinner />}>
                <Dashboard />
              </ProtectedRoute>
            }
          />

          {/* Catch all redirect */}
          <Route path="*" element={<Navigate to="/" replace />} />
        </Routes>
      </BrowserRouter>
    </MasterAuthProvider>
  );
}

export default App;

How It Works

1. Setup: Wrap your app with <MasterAuthProvider> and provide your application ID
2. Login Flow: User clicks login → redirected to Master Auth → authenticates → redirected back to your /auth/callback route
3. Callback: <AuthCallback> processes the authentication, saves credentials, and redirects to dashboard
4. Protected Routes: <ProtectedRoute> validates credentials and grants access to authenticated users
5. State Management: Use useAuth() hook to access authentication state anywhere in your app

TypeScript Support

This package includes TypeScript definitions. All components and hooks are fully typed.

import type {
  MasterAuthConfig,
  AuthCredentials,
  ValidationResponse,
  AuthContextValue
} from '@master-auth/react';

License

ISC