# Mock Nafath API Documentation

## Overview
This mock API simulates the complete Nafath authentication process for development and testing purposes. It supports both OIDC redirect flow and MFA mobile flow with the same data structure as the real Nafath implementation.

## Base URL
```
http://localhost:8000/api/v1/auth/nafath/mock
```

## Authentication Flow

### 1. Start Authentication
**Endpoint:** `POST /start`

**Request Body (OIDC Flow):**
```json
{
  "locale": "ar"
}
```

**Request Body (MFA Flow):**
```json
{
  "national_id": "1234567890",
  "locale": "ar"
}
```

**Response (OIDC Flow):**
```json
{
  "data": {
    "attempt_id": "uuid",
    "attempt_token": "64-char-random-string",
    "authorization_url": "http://localhost:8000/api/v1/auth/nafath/mock/callback?state=uuid",
    "expires_at": "2025-01-01T12:00:00+00:00"
  }
}
```

**Response (MFA Flow):**
```json
{
  "data": {
    "attempt_id": "uuid",
    "attempt_token": "64-char-random-string",
    "random": "6-digit-code",
    "expires_at": "2025-01-01T12:00:00+00:00"
  }
}
```

### 2. Check Status
**Endpoint:** `GET /status/{attempt_id}`

**Headers:**
```
X-Nafath-Attempt-Token: {attempt_token}
```

**Response (Pending):**
```json
{
  "data": {
    "attempt_id": "uuid",
    "status": "pending",
    "provider_status": "PENDING",
    "message": null,
    "token_ready": false,
    "user": null
  }
}
```

**Response (Authenticated):**
```json
{
  "data": {
    "attempt_id": "uuid",
    "status": "authenticated",
    "provider_status": "COMPLETED",
    "message": null,
    "token_ready": true,
    "user": {
      "id": 1,
      "national_id": "1234567890",
      "name": "Mock User",
      "arabic_name": "مستخدم تجريبي",
      "english_name": "Mock User",
      "preferred_locale": "ar",
      "nationality": "SA",
      "gender": "M",
      "assurance_level": 3,
      "last_auth_method": "nafath"
    }
  }
}
```

### 3. Complete Authentication

#### For OIDC Flow:
**Endpoint:** `POST /callback`

**Request Body:**
```json
{
  "state": "{attempt_id}",
  "auto_complete": true
}
```

**Response:**
```json
{
  "success": true,
  "message": "Mock authentication completed successfully",
  "attempt_id": "uuid",
  "redirect_to": "http://localhost:8000/dashboard"
}
```

#### For MFA Flow:
**Endpoint:** `POST /complete-mfa`

**Request Body:**
```json
{
  "attempt_id": "{attempt_id}"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Mock MFA completed successfully",
  "attempt_id": "uuid"
}
```

### 4. Get API Token
**Endpoint:** `POST /token/{attempt_id}`

**Request Body:**
```json
{
  "attempt_token": "{attempt_token}",
  "device_name": "My Device"
}
```

**Response:**
```json
{
  "data": {
    "token": "plain-api-token",
    "token_type": "Bearer",
    "expires_at": "2025-01-01T13:00:00+00:00",
    "user": {
      "id": 1,
      "national_id": "1234567890",
      "name": "Mock User",
      "arabic_name": "مستخدم تجريبي",
      "english_name": "Mock User",
      "preferred_locale": "ar",
      "nationality": "SA",
      "gender": "M",
      "assurance_level": 3,
      "last_auth_method": "nafath"
    }
  }
}
```

## Testing Examples

### Using cURL

#### OIDC Flow:
```bash
# 1. Start authentication
curl -X POST http://localhost:8000/api/v1/auth/nafath/mock/start \
  -H "Content-Type: application/json" \
  -d '{"locale":"ar"}'

# 2. Simulate callback (use attempt_id from step 1)
curl -X POST http://localhost:8000/api/v1/auth/nafath/mock/callback \
  -H "Content-Type: application/json" \
  -d '{"state":"{attempt_id}","auto_complete":true}'

# 3. Check status (use attempt_id and attempt_token from step 1)
curl -X GET http://localhost:8000/api/v1/auth/nafath/mock/status/{attempt_id} \
  -H "X-Nafath-Attempt-Token: {attempt_token}"

# 4. Get token
curl -X POST http://localhost:8000/api/v1/auth/nafath/mock/token/{attempt_id} \
  -H "Content-Type: application/json" \
  -d '{"attempt_token":"{attempt_token}","device_name":"Test Device"}'
```

#### MFA Flow:
```bash
# 1. Start MFA authentication
curl -X POST http://localhost:8000/api/v1/auth/nafath/mock/start \
  -H "Content-Type: application/json" \
  -d '{"national_id":"1234567890","locale":"ar"}'

# 2. Complete MFA
curl -X POST http://localhost:8000/api/v1/auth/nafath/mock/complete-mfa \
  -H "Content-Type: application/json" \
  -d '{"attempt_id":"{attempt_id}"}'

# 3. Check status
curl -X GET http://localhost:8000/api/v1/auth/nafath/mock/status/{attempt_id} \
  -H "X-Nafath-Attempt-Token: {attempt_token}"

# 4. Get token
curl -X POST http://localhost:8000/api/v1/auth/nafath/mock/token/{attempt_id} \
  -H "Content-Type: application/json" \
  -d '{"attempt_token":"{attempt_token}","device_name":"Test Device"}'
```

### Using Postman

1. Import the OpenAPI specification (see `mock-nafath-api.yaml`)
2. Set base URL to `http://localhost:8000/api/v1/auth/nafath/mock`
3. Follow the collection order: Start → Callback/Complete-MFA → Status → Token

## Mock User Data

The mock system creates a user with the following credentials:
- **National ID:** 1234567890
- **Name:** Mock User
- **Arabic Name:** مستخدم تجريبي
- **Email:** mock@example.com
- **Nationality:** SA
- **Gender:** M
- **Assurance Level:** 3

## Rate Limiting

All endpoints are rate-limited:
- Start/Callback/Token: 20 requests per minute
- Status: 120 requests per minute

## Notes

- All attempts expire after 5 minutes
- Attempt tokens are hashed and stored securely
- API tokens are generated using the same mechanism as production
- The mock user is created on first successful authentication
- Database records are persisted like in production