# Story 2.1: JWT Authentication System

## Metadata
- **Story ID**: 2.1
- **Title**: JWT Authentication System
- **Epic**: 2 - Authentication & Authorization
- **Status**: Pending
- **Priority**: High
- **Estimated Time**: 6-8 hours
- **Dependencies**: 1.2, 1.5

## Goal
Implement a complete JWT-based authentication system with access tokens, refresh tokens, and secure token management.

## Description
This story implements the complete JWT authentication system including token generation, verification, authentication middleware, and login/refresh endpoints. The system supports short-lived access tokens and long-lived refresh tokens for secure authentication.

## Deliverables

### 1. Authentication Interfaces (`pkg/auth/auth.go`)
- `Authenticator` interface for token generation and verification
- `TokenClaims` struct with user ID, roles, tenant ID, expiration
- Token validation utilities

### 2. JWT Implementation (`internal/auth/jwt_auth.go`)
- Generate short-lived access tokens (15 minutes default)
- Generate long-lived refresh tokens (7 days default)
- Token signature verification using HMAC or RSA
- Token expiration validation
- Claims extraction and validation

### 3. Authentication Middleware (`internal/auth/middleware.go`)
- Extract JWT from `Authorization: Bearer <token>` header
- Verify token validity (signature and expiration)
- Inject authenticated user into request context
- Helper function: `auth.FromContext(ctx) *User`
- Handle authentication errors appropriately

### 4. Authentication Endpoints
- `POST /api/v1/auth/login` - Authenticate user and return tokens
  - Validate email and password
  - Return access + refresh tokens
  - Log login attempts
- `POST /api/v1/auth/refresh` - Refresh access token using refresh token
  - Validate refresh token
  - Issue new access token
  - Optionally rotate refresh token

### 5. gRPC Server (Microservices)
- Expose gRPC server for authentication service
- gRPC service definition in `api/proto/auth.proto`
- gRPC server implementation in `internal/auth/grpc/server.go`
- Service registration in service registry

### 6. Integration
- Integration with DI container
- Use `IdentityServiceClient` for user operations (if Identity service is separate)
- Integration with HTTP server
- Integration with user repository
- Integration with audit logging

## Implementation Steps

1. **Install Dependencies**
   ```bash
   go get github.com/golang-jwt/jwt/v5
   ```

2. **Create Authentication Interfaces**
   - Create `pkg/auth/auth.go`
   - Define Authenticator interface
   - Define TokenClaims struct

3. **Implement JWT Authentication**
   - Create `internal/auth/jwt_auth.go`
   - Implement token generation
   - Implement token verification
   - Handle token expiration

4. **Create Authentication Middleware**
   - Create `internal/auth/middleware.go`
   - Implement token extraction
   - Implement token verification
   - Inject user into context

5. **Create Authentication Endpoints**
   - Create login handler
   - Create refresh handler
   - Add routes to HTTP server

6. **Integrate with DI**
   - Create provider function
   - Register in container

## Acceptance Criteria
- [ ] Users can login and receive access and refresh tokens
- [ ] Access tokens expire after configured duration
- [ ] Refresh tokens can be used to obtain new access tokens
- [ ] Invalid tokens are rejected with appropriate errors
- [ ] Authenticated user is available in request context
- [ ] Login attempts are logged (success and failure)
- [ ] Token secrets are configurable
- [ ] Token claims include user ID, roles, and tenant ID

## Related ADRs
- [ADR-0017: JWT Token Strategy](../../adr/0017-jwt-token-strategy.md)
- [ADR-0029: Microservices Architecture](../../adr/0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](../../adr/0030-service-communication-strategy.md)

## Implementation Notes
- Use JWT v5 library
- Support both HMAC and RSA signing
- Token secrets should be configurable
- Consider token blacklisting for logout (future enhancement)
- Refresh tokens should be stored securely (database or cache)

## Testing
```bash
# Test authentication
go test ./internal/auth/...

# Test login endpoint
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password"}'

# Test refresh endpoint
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -H "Authorization: Bearer <refresh_token>"
```

## Files to Create/Modify
- `pkg/auth/auth.go` - Authentication interfaces
- `internal/auth/jwt_auth.go` - JWT implementation
- `internal/auth/middleware.go` - Authentication middleware
- `internal/auth/handler.go` - Authentication handlers
- `internal/di/providers.go` - Add auth provider
- `config/default.yaml` - Add JWT configuration