@orchestrator-claude/definitions 3.5.0

package/kb/auth-strategies.md

@@ -0,0 +1,742 @@
+---
+title: "Authentication Strategies"
+category: "security"
+tier: "foundational"
+tags: ["api", "auth", "jwt", "oauth", "security"]
+template: "api"
+---
+
+# Authentication Strategies
+
+## Overview
+
+This document defines authentication strategies and best practices for securing REST APIs, covering JWT, OAuth 2.0, API keys, and session-based authentication.
+
+**Project**: my-project
+**Template**: api
+
+---
+
+## 1. Authentication vs Authorization
+
+### Authentication
+
+**Who are you?** - Verifying user identity
+
+- Login with credentials
+- Token validation
+- Session management
+
+### Authorization
+
+**What can you do?** - Verifying permissions
+
+- Role-based access control (RBAC)
+- Permission checks
+- Resource ownership validation
+
+---
+
+## 2. JWT (JSON Web Token) Authentication
+
+### Overview
+
+JWT is a stateless authentication mechanism where tokens contain user identity and claims.
+
+**Pros:**
+- Stateless (no server-side session storage)
+- Scalable across multiple servers
+- Can include custom claims
+
+**Cons:**
+- Cannot revoke tokens before expiration
+- Larger payload than session IDs
+- Vulnerable if secret key compromised
+
+### JWT Structure
+
+```
+header.payload.signature
+
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
+eyJ1c2VySWQiOiIxMjMiLCJyb2xlIjoiYWRtaW4iLCJpYXQiOjE2MTYyMzkwMjJ9.
+SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
+
+### Implementation
+
+#### Install Dependencies
+
+```bash
+npm install jsonwebtoken bcrypt
+npm install --save-dev @types/jsonwebtoken @types/bcrypt
+```
+
+#### Generate Token
+
+```typescript
+// src/infrastructure/auth/JwtService.ts
+import jwt from 'jsonwebtoken';
+
+export interface TokenPayload {
+  userId: string;
+  email: string;
+  role: string;
+}
+
+export class JwtService {
+  private readonly secret: string;
+  private readonly expiresIn: string;
+
+  constructor() {
+    this.secret = process.env.JWT_SECRET!;
+    this.expiresIn = process.env.JWT_EXPIRES_IN || '24h';
+
+    if (!this.secret) {
+      throw new Error('JWT_SECRET is not defined');
+    }
+  }
+
+  generateToken(payload: TokenPayload): string {
+    return jwt.sign(payload, this.secret, {
+      expiresIn: this.expiresIn,
+      issuer: 'api-service',
+      audience: 'api-client',
+    });
+  }
+
+  verifyToken(token: string): TokenPayload {
+    try {
+      return jwt.verify(token, this.secret, {
+        issuer: 'api-service',
+        audience: 'api-client',
+      }) as TokenPayload;
+    } catch (err) {
+      throw new Error('Invalid or expired token');
+    }
+  }
+}
+```
+
+#### Authentication Middleware
+
+```typescript
+// src/presentation/middleware/authenticate.ts
+import type { Request, Response, NextFunction } from 'express';
+import { JwtService } from '../../infrastructure/auth/JwtService';
+
+const jwtService = new JwtService();
+
+export function authenticate(req: Request, res: Response, next: NextFunction) {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Missing or invalid authorization header',
+      timestamp: new Date().toISOString(),
+      path: req.path,
+    });
+  }
+
+  const token = authHeader.substring(7); // Remove 'Bearer ' prefix
+
+  try {
+    const payload = jwtService.verifyToken(token);
+
+    // Attach user info to request
+    req.user = {
+      id: payload.userId,
+      email: payload.email,
+      role: payload.role,
+    };
+
+    next();
+  } catch (err) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Invalid or expired token',
+      timestamp: new Date().toISOString(),
+      path: req.path,
+    });
+  }
+}
+```
+
+#### Login Endpoint
+
+```typescript
+// src/presentation/routes/auth.ts
+import bcrypt from 'bcrypt';
+import { JwtService } from '../../infrastructure/auth/JwtService';
+
+const jwtService = new JwtService();
+
+router.post('/api/v1/auth/login', async (req, res, next) => {
+  const { email, password } = req.body;
+
+  // Find user
+  const user = await userRepository.findByEmail(email);
+  if (!user) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Invalid credentials',
+    });
+  }
+
+  // Verify password
+  const isValidPassword = await bcrypt.compare(password, user.passwordHash);
+  if (!isValidPassword) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Invalid credentials',
+    });
+  }
+
+  // Generate token
+  const token = jwtService.generateToken({
+    userId: user.id,
+    email: user.email,
+    role: user.role,
+  });
+
+  res.json({
+    token,
+    user: {
+      id: user.id,
+      email: user.email,
+      role: user.role,
+    },
+  });
+});
+```
+
+#### Protected Route
+
+```typescript
+import { authenticate } from '../middleware/authenticate';
+
+router.get('/api/v1/profile', authenticate, async (req, res) => {
+  // req.user is populated by authenticate middleware
+  const user = await userRepository.findById(req.user.id);
+  res.json(user);
+});
+```
+
+---
+
+## 3. Refresh Tokens
+
+### Why Refresh Tokens?
+
+- Short-lived access tokens (15-30 min)
+- Long-lived refresh tokens (7-30 days)
+- Refresh tokens can be revoked
+
+### Implementation
+
+#### Database Schema
+
+```sql
+CREATE TABLE refresh_tokens (
+  id UUID PRIMARY KEY,
+  user_id UUID NOT NULL,
+  token_hash VARCHAR(255) NOT NULL,
+  expires_at TIMESTAMP NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW(),
+  revoked_at TIMESTAMP
+);
+```
+
+#### Generate Refresh Token
+
+```typescript
+import crypto from 'crypto';
+
+export class RefreshTokenService {
+  async generateRefreshToken(userId: string): Promise<string> {
+    const token = crypto.randomBytes(32).toString('hex');
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
+
+    // Store in database
+    await refreshTokenRepository.create({
+      userId,
+      tokenHash,
+      expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
+    });
+
+    return token;
+  }
+
+  async verifyRefreshToken(token: string): Promise<string | null> {
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
+
+    const refreshToken = await refreshTokenRepository.findByTokenHash(tokenHash);
+
+    if (!refreshToken || refreshToken.revokedAt || refreshToken.expiresAt < new Date()) {
+      return null;
+    }
+
+    return refreshToken.userId;
+  }
+
+  async revokeRefreshToken(token: string): Promise<void> {
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex');
+    await refreshTokenRepository.revoke(tokenHash);
+  }
+}
+```
+
+#### Refresh Endpoint
+
+```typescript
+router.post('/api/v1/auth/refresh', async (req, res) => {
+  const { refreshToken } = req.body;
+
+  const userId = await refreshTokenService.verifyRefreshToken(refreshToken);
+
+  if (!userId) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Invalid or expired refresh token',
+    });
+  }
+
+  const user = await userRepository.findById(userId);
+
+  // Generate new access token
+  const accessToken = jwtService.generateToken({
+    userId: user.id,
+    email: user.email,
+    role: user.role,
+  });
+
+  res.json({ accessToken });
+});
+```
+
+---
+
+## 4. Role-Based Access Control (RBAC)
+
+### Authorization Middleware
+
+```typescript
+// src/presentation/middleware/authorize.ts
+import type { Request, Response, NextFunction } from 'express';
+
+export function authorize(...allowedRoles: string[]) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (!req.user) {
+      return res.status(401).json({
+        error: 'Unauthorized',
+        message: 'Authentication required',
+      });
+    }
+
+    if (!allowedRoles.includes(req.user.role)) {
+      return res.status(403).json({
+        error: 'Forbidden',
+        message: 'Insufficient permissions',
+      });
+    }
+
+    next();
+  };
+}
+```
+
+### Usage
+
+```typescript
+import { authenticate } from '../middleware/authenticate';
+import { authorize } from '../middleware/authorize';
+
+// Only admins can delete users
+router.delete(
+  '/api/v1/users/:id',
+  authenticate,
+  authorize('admin'),
+  async (req, res) => {
+    // Delete user logic
+  }
+);
+
+// Admins and moderators can update users
+router.patch(
+  '/api/v1/users/:id',
+  authenticate,
+  authorize('admin', 'moderator'),
+  async (req, res) => {
+    // Update user logic
+  }
+);
+```
+
+---
+
+## 5. OAuth 2.0 (Third-Party Auth)
+
+### Overview
+
+OAuth 2.0 allows users to authenticate using third-party providers (Google, GitHub, etc.).
+
+### Install Passport.js
+
+```bash
+npm install passport passport-google-oauth20
+npm install --save-dev @types/passport @types/passport-google-oauth20
+```
+
+### Configure Google OAuth
+
+```typescript
+// src/infrastructure/auth/passport.ts
+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: '/api/v1/auth/google/callback',
+    },
+    async (accessToken, refreshToken, profile, done) => {
+      try {
+        // Find or create user
+        let user = await userRepository.findByEmail(profile.emails![0].value);
+
+        if (!user) {
+          user = await userRepository.create({
+            email: profile.emails![0].value,
+            name: profile.displayName,
+            googleId: profile.id,
+          });
+        }
+
+        done(null, user);
+      } catch (err) {
+        done(err, undefined);
+      }
+    }
+  )
+);
+```
+
+### OAuth Routes
+
+```typescript
+import passport from 'passport';
+
+// Redirect to Google login
+router.get(
+  '/api/v1/auth/google',
+  passport.authenticate('google', { scope: ['profile', 'email'], session: false })
+);
+
+// Google callback
+router.get(
+  '/api/v1/auth/google/callback',
+  passport.authenticate('google', { session: false }),
+  (req, res) => {
+    const user = req.user as User;
+
+    // Generate JWT
+    const token = jwtService.generateToken({
+      userId: user.id,
+      email: user.email,
+      role: user.role,
+    });
+
+    // Redirect to frontend with token
+    res.redirect(`${process.env.FRONTEND_URL}/auth/callback?token=${token}`);
+  }
+);
+```
+
+---
+
+## 6. API Key Authentication
+
+### Overview
+
+API keys are used for server-to-server authentication or public API access.
+
+**Use cases:**
+- Third-party integrations
+- Webhooks
+- Public API access
+
+### Generate API Key
+
+```typescript
+import crypto from 'crypto';
+
+export class ApiKeyService {
+  async generateApiKey(userId: string): Promise<string> {
+    const apiKey = `sk_${crypto.randomBytes(32).toString('hex')}`;
+    const keyHash = crypto.createHash('sha256').update(apiKey).digest('hex');
+
+    // Store in database
+    await apiKeyRepository.create({
+      userId,
+      keyHash,
+      createdAt: new Date(),
+    });
+
+    return apiKey;
+  }
+
+  async verifyApiKey(apiKey: string): Promise<string | null> {
+    const keyHash = crypto.createHash('sha256').update(apiKey).digest('hex');
+    const record = await apiKeyRepository.findByKeyHash(keyHash);
+
+    if (!record || record.revokedAt) {
+      return null;
+    }
+
+    return record.userId;
+  }
+}
+```
+
+### API Key Middleware
+
+```typescript
+// src/presentation/middleware/authenticateApiKey.ts
+import type { Request, Response, NextFunction } from 'express';
+
+export async function authenticateApiKey(
+  req: Request,
+  res: Response,
+  next: NextFunction
+) {
+  const apiKey = req.headers['x-api-key'] as string;
+
+  if (!apiKey) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Missing API key',
+    });
+  }
+
+  const userId = await apiKeyService.verifyApiKey(apiKey);
+
+  if (!userId) {
+    return res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Invalid API key',
+    });
+  }
+
+  const user = await userRepository.findById(userId);
+  req.user = user;
+
+  next();
+}
+```
+
+---
+
+## 7. Password Hashing
+
+### Use bcrypt
+
+```bash
+npm install bcrypt
+npm install --save-dev @types/bcrypt
+```
+
+### Hash Password
+
+```typescript
+import bcrypt from 'bcrypt';
+
+const SALT_ROUNDS = 10;
+
+export async function hashPassword(password: string): Promise<string> {
+  return bcrypt.hash(password, SALT_ROUNDS);
+}
+
+export async function verifyPassword(
+  password: string,
+  hash: string
+): Promise<boolean> {
+  return bcrypt.compare(password, hash);
+}
+```
+
+### Usage
+
+```typescript
+router.post('/api/v1/auth/register', async (req, res) => {
+  const { email, password } = req.body;
+
+  // Hash password
+  const passwordHash = await hashPassword(password);
+
+  // Create user
+  const user = await userRepository.create({
+    email,
+    passwordHash,
+  });
+
+  res.status(201).json({ user });
+});
+```
+
+---
+
+## 8. Security Best Practices
+
+### Environment Variables
+
+```env
+# JWT
+JWT_SECRET=your-secret-key-min-32-chars
+JWT_EXPIRES_IN=15m
+
+# Refresh Token
+REFRESH_TOKEN_EXPIRES_IN=30d
+
+# OAuth
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# API Keys
+API_KEY_PREFIX=sk_
+```
+
+### Security Headers (Helmet)
+
+```bash
+npm install helmet
+```
+
+```typescript
+import helmet from 'helmet';
+
+app.use(helmet());
+```
+
+### Rate Limiting
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5, // 5 attempts
+  message: 'Too many login attempts, please try again later',
+});
+
+router.post('/api/v1/auth/login', authLimiter, async (req, res) => {
+  // Login logic
+});
+```
+
+### HTTPS Only
+
+```typescript
+app.use((req, res, next) => {
+  if (process.env.NODE_ENV === 'production' && !req.secure) {
+    return res.redirect(`https://${req.headers.host}${req.url}`);
+  }
+  next();
+});
+```
+
+---
+
+## 9. Testing Authentication
+
+### Test Login
+
+```typescript
+import request from 'supertest';
+import { app } from '../src/server';
+
+describe('POST /api/v1/auth/login', () => {
+  it('should return token for valid credentials', async () => {
+    const response = await request(app)
+      .post('/api/v1/auth/login')
+      .send({
+        email: 'user@example.com',
+        password: 'SecureP@ss123',
+      })
+      .expect(200);
+
+    expect(response.body).toHaveProperty('token');
+    expect(response.body.token).toMatch(/^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$/); // JWT format
+  });
+
+  it('should return 401 for invalid credentials', async () => {
+    await request(app)
+      .post('/api/v1/auth/login')
+      .send({
+        email: 'user@example.com',
+        password: 'wrong-password',
+      })
+      .expect(401);
+  });
+});
+```
+
+### Test Protected Route
+
+```typescript
+describe('GET /api/v1/profile', () => {
+  it('should return user profile with valid token', async () => {
+    const token = generateValidToken();
+
+    const response = await request(app)
+      .get('/api/v1/profile')
+      .set('Authorization', `Bearer ${token}`)
+      .expect(200);
+
+    expect(response.body).toHaveProperty('id');
+  });
+
+  it('should return 401 without token', async () => {
+    await request(app).get('/api/v1/profile').expect(401);
+  });
+
+  it('should return 401 with invalid token', async () => {
+    await request(app)
+      .get('/api/v1/profile')
+      .set('Authorization', 'Bearer invalid-token')
+      .expect(401);
+  });
+});
+```
+
+---
+
+## 10. Common Pitfalls
+
+### DON'T
+
+1. **Store passwords in plain text** - Always hash with bcrypt
+2. **Use weak JWT secrets** - Min 32 characters, random
+3. **Include sensitive data in JWT** - No passwords, credit cards
+4. **Expose JWT secret in client** - Server-side only
+5. **Use long-lived access tokens** - Max 30 minutes
+6. **Forget to validate token expiration** - Always check `exp` claim
+7. **Allow password reuse** - Check against previous passwords
+8. **Skip HTTPS in production** - Always use HTTPS
+
+---
+
+## References
+
+- [JWT.io](https://jwt.io/)
+- [OAuth 2.0 RFC](https://datatracker.ietf.org/doc/html/rfc6749)
+- [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
+- [Passport.js Documentation](http://www.passportjs.org/)
+
+---
+
+**Generated for**: my-project
+**Template**: api
+**Constitution Preset**: orchestrator