simple-express-react-auth/README.md

A lightweight authentication package for Express/React apps with single password protection using cookie-session

# 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

```bash
npm install simple-express-react-auth
```

## Quick Start

### Express Setup

```javascript
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

```jsx
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

```jsx
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

```javascript
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

```javascript
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

```jsx
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.