auth-patterns

# Authentication Patterns

## Overview

Authentication and authorization patterns for securing backend applications.

## Authentication Methods

### JWT (JSON Web Tokens)

```
┌─────────────────────────────────────────────────────────┐
│ Header.Payload.Signature                                │
│                                                         │
│ Header:  { "alg": "HS256", "typ": "JWT" }              │
│ Payload: { "sub": "user123", "exp": 1609459200, ... }  │
│ Signature: HMACSHA256(base64(header) + "." +            │
│            base64(payload), secret)                      │
└─────────────────────────────────────────────────────────┘
```

**Token Structure:**

```typescript
interface JWTPayload {
  sub: string;      // Subject (user ID)
  iat: number;      // Issued at
  exp: number;      // Expiration
  iss?: string;     // Issuer
  aud?: string;     // Audience
  roles?: string[]; // Custom claims
}
```

**Implementation:**

```typescript
import jwt from 'jsonwebtoken';

const ACCESS_TOKEN_EXPIRY = '15m';
const REFRESH_TOKEN_EXPIRY = '7d';

function generateTokens(user: User) {
  const accessToken = jwt.sign(
    { sub: user.id, roles: user.roles },
    process.env.JWT_SECRET,
    { expiresIn: ACCESS_TOKEN_EXPIRY }
  );

  const refreshToken = jwt.sign(
    { sub: user.id, type: 'refresh' },
    process.env.JWT_REFRESH_SECRET,
    { expiresIn: REFRESH_TOKEN_EXPIRY }
  );

  return { accessToken, refreshToken };
}

function verifyAccessToken(token: string): JWTPayload {
  return jwt.verify(token, process.env.JWT_SECRET) as JWTPayload;
}
```

### Session-Based Authentication

```typescript
// Session storage (Redis recommended for production)
interface Session {
  userId: string;
  createdAt: Date;
  expiresAt: Date;
  userAgent?: string;
  ipAddress?: string;
}

// Login
async function login(email: string, password: string, req: Request) {
  const user = await findUserByEmail(email);
  if (!user || !await verifyPassword(password, user.passwordHash)) {
    throw new AuthError('Invalid credentials');
  }

  const sessionId = generateSecureId();
  await redis.set(`session:${sessionId}`, JSON.stringify({
    userId: user.id,
    createdAt: new Date(),
    expiresAt: addDays(new Date(), 7),
    userAgent: req.headers['user-agent'],
  }), 'EX', 7 * 24 * 60 * 60);

  return sessionId;
}

// Middleware
async function authenticate(req: Request, res: Response, next: NextFunction) {
  const sessionId = req.cookies.session;
  if (!sessionId) return res.status(401).json({ error: 'Unauthorized' });

  const session = await redis.get(`session:${sessionId}`);
  if (!session) return res.status(401).json({ error: 'Session expired' });

  req.user = JSON.parse(session);
  next();
}
```

### OAuth 2.0 / OpenID Connect

```
┌──────────┐                              ┌──────────────┐
│  Client  │──────1. Auth Request──────▶│    Auth      │
│  (App)   │◀─────2. Auth Code──────────│   Provider   │
│          │──────3. Exchange Code──────▶│  (Google,    │
│          │◀─────4. Access Token───────│   GitHub)    │
│          │──────5. API Requests───────▶│              │
└──────────┘                              └──────────────┘
```

**Implementation with Passport.js:**

```typescript
import passport from 'passport';
import { Strategy as GoogleStrategy } from 'passport-google-oauth20';

passport.use(new GoogleStrategy({
    clientID: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    callbackURL: '/auth/google/callback',
  },
  async (accessToken, refreshToken, profile, done) => {
    const user = await findOrCreateUser({
      provider: 'google',
      providerId: profile.id,
      email: profile.emails[0].value,
      name: profile.displayName,
    });
    done(null, user);
  }
));

// Routes
app.get('/auth/google', passport.authenticate('google', {
  scope: ['profile', 'email']
}));

app.get('/auth/google/callback',
  passport.authenticate('google', { failureRedirect: '/login' }),
  (req, res) => res.redirect('/dashboard')
);
```

## Password Security

### Hashing

```typescript
import bcrypt from 'bcrypt';

const SALT_ROUNDS = 12;

async function hashPassword(password: string): Promise<string> {
  return bcrypt.hash(password, SALT_ROUNDS);
}

async function verifyPassword(password: string, hash: string): Promise<boolean> {
  return bcrypt.compare(password, hash);
}
```

### Password Requirements

```typescript
const PASSWORD_RULES = {
  minLength: 8,
  maxLength: 128,
  requireUppercase: true,
  requireLowercase: true,
  requireNumber: true,
  requireSpecial: true,
};

function validatePassword(password: string): string[] {
  const errors: string[] = [];

  if (password.length < PASSWORD_RULES.minLength) {
    errors.push(`Password must be at least ${PASSWORD_RULES.minLength} characters`);
  }
  if (PASSWORD_RULES.requireUppercase && !/[A-Z]/.test(password)) {
    errors.push('Password must contain an uppercase letter');
  }
  if (PASSWORD_RULES.requireLowercase && !/[a-z]/.test(password)) {
    errors.push('Password must contain a lowercase letter');
  }
  if (PASSWORD_RULES.requireNumber && !/\d/.test(password)) {
    errors.push('Password must contain a number');
  }
  if (PASSWORD_RULES.requireSpecial && !/[!@#$%^&*]/.test(password)) {
    errors.push('Password must contain a special character');
  }

  return errors;
}
```

## Authorization Patterns

### Role-Based Access Control (RBAC)

```typescript
type Role = 'admin' | 'editor' | 'viewer';

const PERMISSIONS: Record<Role, string[]> = {
  admin: ['read', 'write', 'delete', 'manage_users'],
  editor: ['read', 'write'],
  viewer: ['read'],
};

function hasPermission(user: User, permission: string): boolean {
  return user.roles.some(role =>
    PERMISSIONS[role]?.includes(permission)
  );
}

// Middleware
function requirePermission(permission: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!hasPermission(req.user, permission)) {
      return res.status(403).json({ error: '