Simple Express React Auth

A lightweight authentication package for Express/React applications that provides single-password protection with session management.

Features

🔐 Single Password Authentication - Perfect for internal tools and admin panels
🍪 Cookie-based Sessions - Uses cookie-session for stateless sessions (no server storage needed)
⚛️ React Components - Ready-to-use components for login forms and protected routes
🛡️ Express Middleware - Easy route protection with middleware functions
🎨 Customizable - Flexible styling and configuration options
📦 Lightweight - Minimal dependencies, maximum functionality
🆕 Modern - Supports Express 5+, React 19+, bcrypt 6+

Installation

npm install simple-express-react-auth

Quick Start

Express Setup

const express = require('express');
const cookieSession = require('cookie-session');
const { expressAuth } = require('simple-express-react-auth');

const app = express();

// Session middleware (required)
app.use(cookieSession({
  name: 'session',
  keys: ['your-secret-key'], // Use multiple keys for key rotation
  maxAge: 24 * 60 * 60 * 1000 // 24 hours
}));

app.use(express.json());

// Create auth system
const { router, requireAuth } = expressAuth.createAuth({
  password: 'your-secret-password'
});

// Add auth routes
app.use('/auth', router);

// Protect your routes
app.get('/protected', requireAuth, (req, res) => {
  res.json({ message: 'This is protected!' });
});

app.listen(3000);

React Setup

import React from 'react';
import { AuthProvider, ProtectedRoute, LogoutButton } from 'simple-express-react-auth/react';

function App() {
  return (
    <AuthProvider apiBaseUrl="http://localhost:3000">
      <div>
        <h1>My Protected App</h1>
        <ProtectedRoute>
          <div>
            <p>Welcome! You are authenticated.</p>
            <LogoutButton />
          </div>
        </ProtectedRoute>
      </div>
    </AuthProvider>
  );
}

export default App;

API Reference

Express API

`createAuth(options)`

Creates authentication router and middleware.

Options:

password (string) - Plain text password to hash and use for auth
hashedPassword (string) - Pre-hashed password (alternative to password)
loginPath (string) - Login endpoint path relative to router mount (default: /login)
logoutPath (string) - Logout endpoint path relative to router mount (default: /logout)
statusPath (string) - Status endpoint path relative to router mount (default: /status)
saltRounds (number) - BCrypt salt rounds (default: 12)

Returns:

router - Express router with auth endpoints
requireAuth - Middleware for API route protection
requireAuthRedirect - Middleware for HTML route protection with redirect

Auth Endpoints

POST /auth/login - Login with password
GET /auth/logout - Logout and clear session
GET /auth/status - Check authentication status

React API

`AuthProvider`

Context provider for authentication state.

Props:

apiBaseUrl (string) - Base URL for auth API calls (default: '')
statusPath (string) - Status endpoint path (default: '/auth/status')
loginPath (string) - Login endpoint path (default: '/auth/login')
logoutPath (string) - Logout endpoint path (default: '/auth/logout')

`useAuth()`

Hook to access authentication state and methods.

Returns:

isAuthenticated (boolean) - Current auth status
isLoading (boolean) - Loading state
error (string|null) - Current error message
login(password) - Login function
logout() - Logout function
checkAuthStatus() - Refresh auth status

`ProtectedRoute`

Component that conditionally renders children based on auth status.

Props:

children - Content to render when authenticated
fallback - Custom component to render when not authenticated
loadingComponent - Custom loading component
className - CSS class name

`LoginForm`

Ready-to-use login form component.

Props:

onLoginSuccess - Callback function on successful login
className - CSS class name
submitButtonText - Button text (default: 'Login')
passwordPlaceholder - Input placeholder (default: 'Enter password')
showError - Show error messages (default: true)

`LogoutButton`

Button component for logging out.

Props:

children - Button content (default: 'Logout')
onLogoutSuccess - Callback function on successful logout
className - CSS class name
Plus any other button props

Advanced Usage

Custom Styling

import { LoginForm } from 'simple-express-react-auth/react';

function CustomLogin() {
  return (
    <div className="my-login-container">
      <LoginForm 
        className="my-login-form"
        submitButtonText="Sign In"
        passwordPlaceholder="Enter your password"
        onLoginSuccess={() => console.log('Logged in!')}
      />
    </div>
  );
}

Route Protection with Redirect

const { requireAuthRedirect } = expressAuth.createAuth({
  password: 'secret'
});

// Redirect to custom login page
app.get('/admin', requireAuthRedirect('/custom-login'), (req, res) => {
  res.send('Admin panel');
});

Pre-hashed Password

const bcrypt = require('bcrypt');

async function setupAuth() {
  const hashedPassword = await bcrypt.hash('my-password', 12); // Updated to use higher salt rounds
  
  const { router, requireAuth } = expressAuth.createAuth({
    hashedPassword: hashedPassword
  });
  
  return { router, requireAuth };
}

Custom Fallback for Protected Routes

function CustomProtectedRoute({ children }) {
  return (
    <ProtectedRoute
      fallback={
        <div className="custom-login">
          <h2>Access Restricted</h2>
          <LoginForm submitButtonText="Access System" />
        </div>
      }
    >
      {children}
    </ProtectedRoute>
  );
}

Requirements

Node.js 16+
Express 4+ or 5+
React 16.8+ (for hooks)
cookie-session (or compatible session middleware)

Security Notes

Always use HTTPS in production
Use strong session secrets/keys
Consider session configuration (secure cookies, etc.)
This package uses cookie-session for stateless sessions - no server-side storage required
This package is designed for internal tools, not public-facing authentication

License

ISC

Contributing

Contributions welcome! Please read the contributing guidelines and submit pull requests to the main repository.