6ec54460f8
- Create docs/AGENTS.md for AI assistants context - Create docs/WORKFLOWS.md consolidating deployment workflows - Remove redundant docs/root/ folder - Remove .agent/ folder (consolidated into docs/) - Update dates in all documentation files - Simplify README.md documentation section
151 lines
4.4 KiB
Markdown
151 lines
4.4 KiB
Markdown
# 🔐 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 |
|