# 🔐 API Security & Access Levels

Security layers, authentication methods, and RBAC for GoHorse Jobs API.

> **Last Updated:** 2026-02-16

---

## 🛡️ Authentication Methods

| Method | Header/Cookie | Used By |
|--------|--------------|---------|
| **Bearer Token** | `Authorization: Bearer <token>` | Mobile apps, external integrations |
| **HttpOnly Cookie** | `jwt=<token>` | Web Frontend (Next.js), Backoffice |

**Cookie Properties:** `HttpOnly`, `Secure` (prod), `SameSite=Lax`

---

## 🔒 Security Middlewares

| Middleware | File | Description |
|------------|------|-------------|
| **Auth** | `middleware/auth.go` | JWT validation + RBAC |
| **CORS** | `middleware/cors.go` | Whitelist via `CORS_ORIGINS` |
| **Rate Limiting** | `middleware/rate_limit.go` | 100 req/min per IP |
| **Security Headers** | `middleware/security_headers.go` | OWASP headers (XSS, CSP) |
| **Sanitize** | `middleware/sanitize.go` | XSS sanitization in JSON |

---

## 🚦 Access Levels

| Level | Description | Middleware |
|-------|-------------|------------|
| **Public** | Open to everyone | None |
| **Authenticated** | Requires valid JWT | `HeaderAuthGuard` |
| **Role-Restricted** | JWT + Specific Role | `HeaderAuthGuard` + `adminOnly` |

---

## 🗺️ Route Permission Matrix

### 🟢 Public Routes

| Method | Route | Description |
|--------|-------|-------------|
| `GET` | `/` | Root check |
| `GET` | `/health` | Health check |
| `POST` | `/api/v1/auth/login` | Login |
| `POST` | `/api/v1/auth/register/candidate` | Candidate register |
| `POST` | `/api/v1/auth/register/company` | Company register |
| `GET` | `/api/v1/jobs` | List jobs |
| `GET` | `/api/v1/jobs/{id}` | Job details |
| `GET` | `/api/v1/companies/{id}` | Company details |
| `GET` | `/docs/*` | Swagger UI |

### 🟡 Authenticated Routes

| Method | Route | Description |
|--------|-------|-------------|
| `GET` | `/api/v1/users/me` | Get own profile |
| `PATCH` | `/api/v1/users/me/profile` | Update profile |
| `GET` | `/api/v1/notifications` | Get notifications |
| `POST` | `/api/v1/tokens` | Save FCM token |
| `GET` | `/api/v1/storage/upload-url` | Get pre-signed URL |
| `GET` | `/api/v1/conversations` | List conversations |
| `POST` | `/api/v1/applications` | Apply for job |

### 🟠 Recruiter / Company Admin

**Requires:** Role `admin` OR `recruiter`

| Method | Route | Description |
|--------|-------|-------------|
| `POST` | `/api/v1/jobs` | Create job |
| `PUT` | `/api/v1/jobs/{id}` | Update job |
| `DELETE` | `/api/v1/jobs/{id}` | Delete job |
| `GET` | `/api/v1/applications` | List applications |
| `PUT` | `/api/v1/applications/{id}/status` | Update status |

### 🔴 Admin / SuperAdmin

**Requires:** Role `superadmin` OR `admin`

| Method | Route | Description |
|--------|-------|-------------|
| `GET` | `/api/v1/users` | List all users |
| `POST` | `/api/v1/users` | Create user |
| `DELETE` | `/api/v1/users/{id}` | Delete user |
| `GET` | `/api/v1/admin/companies` | List companies |
| `PATCH` | `/api/v1/admin/companies/{id}/status` | Update company status |
| `GET` | `/api/v1/jobs/moderation` | Moderate jobs |
| `PATCH` | `/api/v1/jobs/{id}/status` | Approve/reject job |
| `GET` | `/api/v1/admin/email-templates` | List email templates |
| `PUT` | `/api/v1/admin/email-templates/{slug}` | Update template |
| `PUT` | `/api/v1/admin/email-settings` | Update SMTP settings |
| `POST` | `/api/v1/system/credentials` | Save credentials |
| `POST` | `/api/v1/system/cloudflare/purge` | Purge cache |

---

## 🧪 Testing Security

**1. Public Access (200 OK)**
```bash
curl https://api.gohorsejobs.com/api/v1/jobs
```

**2. Protected without Token (401)**
```bash
curl https://api.gohorsejobs.com/api/v1/users/me
```

**3. Admin Route as Candidate (403)**
```bash
curl -H "Authorization: Bearer <candidate_token>" \
  https://api.gohorsejobs.com/api/v1/users
```

**4. Admin Route as Admin (200 OK)**
```bash
curl -H "Authorization: Bearer <admin_token>" \
  https://api.gohorsejobs.com/api/v1/users
```

---

## 🔑 JWT Claims

```json
{
  "sub": "019438a1-2b3c-...",
  "email": "user@example.com",
  "role": "admin",
  "tenant_id": "019438a2-3c4d-...",
  "exp": 1735200000,
  "iat": 1735113600
}
```

---

## 🛡️ Password Security

| Feature | Implementation |
|---------|---------------|
| **Hashing** | BCrypt (10 rounds) |
| **Pepper** | `PASSWORD_PEPPER` env var |
| **Min Length** | 8 characters |
| **JWT Secret** | Min 32 characters |