# JWT Authentication Architecture

**Last Updated:** January 28, 2026  
**Status:** ✅ Implemented (Step 9 Complete)

## Overview

Pokedex.Online uses JWT (JSON Web Token) authentication for admin access to protected features like the Gamemaster Manager. The system provides:

- Token-based authentication (stateless)
- 7-day token expiration with refresh capability
- Permission-based access control
- Secure localStorage token storage
- Automatic Bearer token injection in API requests

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│ Client (Browser)                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  AdminLogin View                                           │
│  ↓ (password)                                             │
│  useAuth Composable (login → POST /auth/login)            │
│  ↓ (token received)                                       │
│  localStorage.setItem('auth_token', token)                │
│  ↓                                                        │
│  api-client.setDefaultHeader('Authorization', Bearer ...) │
│  ↓                                                        │
│  Router Guards (requiresAdmin check)                      │
│  ↓                                                        │
│  Protected Routes (GamemasterManager, etc.)               │
│                                                            │
└─────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────┐
│ Server (Express)                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Auth Routes (server/routes/auth.js)                       │
│  ↓ /auth/login (POST) → verifyPassword                    │
│  ↓ createToken(payload, secret, expiration)              │
│  ↓ return { token, user, expiresIn }                      │
│                                                            │
│  Auth Middleware (server/middleware/auth.js)              │
│  ↓ authMiddleware() → verifyToken(token)                  │
│  ↓ requirePermission() → check permissions                │
│  ↓ requireAdmin() → check isAdmin flag                    │
│                                                            │
│  Protected Routes                                          │
│  ↓ /api/gamemaster/* (with @authMiddleware)              │
│  ↓ /api/feature-flags/* (with @requirePermission)        │
│                                                            │
└─────────────────────────────────────────────────────────────┘
```

## File Structure

```
Frontend:
├── src/
│   ├── composables/
│   │   └── useAuth.js                 # Auth state management
│   ├── views/
│   │   └── AdminLogin.vue             # Login page
│   ├── router/
│   │   └── guards.js                  # Route protection
│   └── utilities/
│       └── api-client.js              # Enhanced with header mgmt
│
Backend:
├── server/
│   ├── utils/
│   │   └── jwt-utils.js               # Token creation/validation
│   ├── middleware/
│   │   └── auth.js                    # Auth middleware
│   └── routes/
│       └── auth.js                    # Auth endpoints
│
Tests:
└── tests/unit/
    ├── composables/
    │   └── useAuth.test.js            # Auth composable tests
    └── views/
        └── AdminLogin.test.js         # Login page tests
```

## API Endpoints

### POST /auth/login
Authenticate with password to receive JWT token.

**Request:**
```json
{
  "password": "admin-password"
}
```

**Response (Success):**
```json
{
  "success": true,
  "token": "eyJhbGc...",
  "expiresIn": 604800,
  "user": {
    "isAdmin": true,
    "permissions": ["admin", "gamemaster-edit"]
  }
}
```

**Response (Error):**
```json
{
  "error": "Invalid password",
  "code": "INVALID_PASSWORD"
}
```

### POST /auth/verify
Verify that a token is valid and get its metadata.

**Request:**
```json
{
  "token": "eyJhbGc..."
}
```

**Response:**
```json
{
  "valid": true,
  "user": {
    "isAdmin": true,
    "permissions": ["admin", "gamemaster-edit"]
  },
  "expiresIn": 3600,
  "expiresAt": "2026-02-04T17:48:00Z"
}
```

### POST /auth/refresh
Extend token expiration.

**Request:**
```json
{
  "token": "eyJhbGc..."
}
```

**Response:**
```json
{
  "success": true,
  "token": "eyJhbGc...",
  "expiresIn": 604800
}
```

### GET /auth/user
Get current user information (requires valid token).

**Headers:**
```
Authorization: Bearer eyJhbGc...
```

**Response:**
```json
{
  "user": {
    "isAdmin": true,
    "permissions": ["admin", "gamemaster-edit"],
    "loginTime": "2026-01-28T17:48:00Z"
  }
}
```

### POST /auth/logout
Logout endpoint (token invalidation happens client-side).

**Response:**
```json
{
  "success": true,
  "message": "Logged out successfully"
}
```

## Frontend Integration

### Using useAuth in Components

```javascript
import { useAuth } from '../composables/useAuth.js';

export default {
  setup() {
    const { 
      login,           // login(password)
      logout,          // logout()
      token,           // Reactive token ref
      user,            // Reactive user ref
      isAuthenticated, // Boolean computed
      isAdmin,         // Boolean computed
      hasPermission    // (perm) => boolean
    } = useAuth();

    return {
      login,
      logout,
      token,
      user,
      isAuthenticated,
      isAdmin,
      hasPermission
    };
  }
};
```

### Protected Routes

```javascript
import { setupAuthGuards } from './router/guards.js';

const router = createRouter({ ... });

setupAuthGuards(router);

// In route definitions:
{
  path: '/gamemaster-manager',
  component: GamemasterManager,
  meta: { requiresAdmin: true }  // Protected route
}
```

### Setting Up Auth on App Startup

```javascript
import { useAuth } from './composables/useAuth.js';

export default {
  async setup() {
    const { initializeAuth, setupAuthInterceptor } = useAuth();
    
    // Initialize from localStorage
    await initializeAuth();
    
    // Set up automatic token injection
    setupAuthInterceptor();
  }
};
```

## Security Considerations

### ✅ Implemented

- JWT tokens with HMAC-SHA256 signature
- 7-day expiration with refresh capability
- Bearer token in Authorization header
- Token stored in localStorage (browser-side)
- Permission-based access control
- Server-side token validation

### ⚠️ Recommendations

For production deployment:

1. **HTTPS Only:** Ensure all authentication over HTTPS
2. **Environment Secrets:** Store JWT_SECRET in environment variables
3. **Password Hashing:** Use bcrypt for password hashing on server
4. **CSRF Protection:** Add CSRF tokens for state-changing requests
5. **Rate Limiting:** Implement rate limiting on /auth/login endpoint
6. **Secure Cookies:** Consider httpOnly cookies for sensitive tokens
7. **Token Rotation:** Implement token rotation for long-lived sessions
8. **Logout Blacklist:** Maintain blacklist of revoked tokens (if needed)

### Current Limitations

- Passwords stored in environment/config (suitable for single admin scenario)
- No multi-user support yet (planned for future)
- Tokens valid until expiration (no immediate revocation)
- Single secret key (key rotation not yet implemented)

## Testing

Tests verify:

✅ useAuth composable state management  
✅ AdminLogin component rendering and interaction  
✅ Login/logout flow  
✅ Token state in localStorage  
✅ Permission checking logic  
✅ Router guard integration

Run tests:
```bash
npm test                  # Watch mode
npm test -- AdminLogin   # Specific test
npm run test:coverage    # Coverage report
```

## Next Steps (Phase 3: Steps 10-12)

- Feature flags system leveraging JWT permissions
- Secure backend configuration management
- Environment-based flag toggleput
- Flag caching and invalidation
- Admin panel for flag management

---

**Related Documentation:**
- [PROGRESS.md](./PROGRESS.md) - Full refactoring progress
- [REFACTORING-PLAN.md](./REFACTORING-PLAN.md) - Complete 68-step plan