# API Key Management Module

Complete API key management for LandveX admin backend.

## Features

1. **Generate API Keys** — UUID-based keys with `lvx_` prefix
2. **Rotate Keys** — Revoke old key, create new with same config
3. **Revoke Keys** — Soft delete (revoke) or hard delete
4. **Rate Limiting** — Per-minute, per-hour, per-day limits per key
5. **Usage Tracking** — Append-only log with analytics
6. **Admin API Endpoints** — Full CRUD + rotation

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api-keys` | Create new API key |
| GET | `/api-keys` | List all API keys |
| GET | `/api-keys/:id` | Get key with usage stats |
| POST | `/api-keys/:id/rotate` | Rotate API key |
| DELETE | `/api-keys/:id` | Revoke (soft delete) |
| DELETE | `/api-keys/:id?hard=true` | Hard delete |

## Create API Key

```bash
curl -X POST http://localhost:3000/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "expiresInDays": 90,
    "rateLimitPerMinute": 120,
    "rateLimitPerHour": 5000,
    "rateLimitPerDay": 50000,
    "metadata": { "team": "platform", "env": "prod" }
  }'
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Integration",
  "key": "lvx_Af7x9K2mNpQwRt3Uv5Yz8BcDeFgHiJk",
  "keyPrefix": "lvx_Af7x9K2mNp",
  "status": "active",
  "rateLimitPerMinute": 120,
  "rateLimitPerHour": 5000,
  "rateLimitPerDay": 50000,
  "createdAt": "2026-07-03T03:47:00.000Z",
  "expiresAt": "2026-10-01T03:47:00.000Z",
  "metadata": { "team": "platform", "env": "prod" }
}
```

> ⚠️ **The `key` field is ONLY returned on creation. Store it securely — it cannot be retrieved later.**

## List API Keys

```bash
curl "http://localhost:3000/api-keys?status=active&limit=50&offset=0"
```

## Get Key with Stats

```bash
curl http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000
```

## Rotate Key

```bash
curl -X POST http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000/rotate
```

Returns new key. Old key is immediately revoked.

## Revoke Key

```bash
# Soft delete (revoke)
curl -X DELETE http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000

# Hard delete (permanent)
curl -X DELETE "http://localhost:3000/api-keys/550e8400-e29b-41d4-a716-446655440000?hard=true"
```

## Using API Keys

Include the key in the `X-API-Key` header:

```bash
curl -H "X-API-Key: lvx_Af7x9K2mNpQwRt3Uv5Yz8BcDeFgHiJk" \
  http://localhost:3000/api/v1/missions
```

Rate limit headers are included in responses:
```
X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 119
X-RateLimit-Limit-Hour: 5000
X-RateLimit-Remaining-Hour: 4999
X-RateLimit-Limit-Day: 50000
X-RateLimit-Remaining-Day: 49999
```

## Database Schema

Run the SQL migration:
```bash
psql -d landvex -f packages/api/src/routes/api-keys.sql
```

Tables:
- `api_keys` — Key metadata (hashed, never plain text)
- `api_key_usage` — Append-only usage log

Views:
- `api_keys_active` — Active, non-expired keys
- `api_key_usage_summary` — Aggregated usage stats

## Architecture

```
Express Router → ApiKeyService → ApiKeyRepository (PostgreSQL)
                      ↓
              ApiKeyUsageRepository (PostgreSQL)
                      ↓
              api_key_usage table
```

## Testing

```bash
cd packages/api
npm test -- api-keys.test.ts
```

Tests cover:
- Key creation with validation
- Listing with pagination and filtering
- Rotation (revoke old, create new)
- Revocation and deletion
- Key validation
- Rate limiting
- Usage tracking

## Files

| File | Description |
|------|-------------|
| `packages/api/src/models/api-key.ts` | Domain model |
| `packages/api/src/services/api-key-service.ts` | Business logic |
| `packages/api/src/middleware/api-key-auth.ts` | Auth & rate limiting middleware |
| `packages/api/src/routes/api-keys.ts` | Express routes |
| `packages/api/src/routes/api-keys.test.ts` | Tests |
| `packages/api/src/routes/api-keys.sql` | PostgreSQL schema |
| `packages/infrastructure/src/repositories/api-key-repository.ts` | Repository interfaces |
| `packages/infrastructure/src/adapters/postgresql/postgres-api-key-repository.ts` | PostgreSQL adapter |
| `packages/infrastructure/src/adapters/in-memory-api-key-repository.ts` | In-memory adapter (testing) |