# 🛡️ Dotlaa ERP — Production Security Audit Report

This document presents a comprehensive production security audit of Dotlaa ERP backend and client environments based on code verification.

---

## 1. Multi-Tenant Data Isolation

Tenant isolation is fully automated, removing developer error when querying scoped data.

- **Isolation Engine:** [TenantScope.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/app/Scopes/TenantScope.php)
- **Automatic Scoping Trait:** [BelongsToTenant.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/app/Traits/BelongsToTenant.php)
- **Mechanism:** Every multi-tenant model (e.g. `Product`, `Inventory`, `Sale`, `Shift`, `Refund`) implements `BelongsToTenant`. This trait automatically binds a global Eloquent scope `TenantScope`, appending `where company_id = [active_tenant_id]` to every query.
- **Tenant Context Identification:** Set platform-wide inside [EnsureCompanyIsActive.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/app/Http/Middleware/EnsureCompanyIsActive.php):
  ```php
  $company = Company::where('subdomain', $subdomain)->first();
  ...
  app(TenantManager::class)->setTenant($company);
  ```

---

## 2. API Authentication & Token Management

- **Protocol:** Laravel Sanctum is used for API token security.
- **Middleware Protection:** Applied globally to all sensitive routes in [api.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/routes/api.php#L49):
  ```php
  Route::middleware(['auth:sanctum', 'company.active', 'throttle:api'])
  ```
- **Active Company Guard:** `company.active` mapping to [EnsureCompanyIsActive.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/app/Http/Middleware/EnsureCompanyIsActive.php) blocks request traffic if the tenant company status is `suspended` or `inactive`.

---

## 3. Role-Based Access Control (RBAC) & Route Policies

- **Underlying Engine:** `spatie/laravel-permission`
- **Fine-Grained Authorization:** Route actions are strictly gated using Laravel policies in controllers.
- **Policies Checked:**
  - **Sale Operations:** Gated in `SalePolicy::class`. Creating, completing, or cancelling sales checks the `'create-sales'` permission.
  - **Shift Operations:** Gated in `ShiftPolicy::class`. Cashiers can only view, open, or close shifts they created (`opened_by === user_id`). Managers or administrators possess unrestricted oversight within their tenant boundary.
  - **Returns:** Gated in `ReturnPolicy::class`. Creating and completing returns requires the `'process-returns'` permission.

---

## 4. API Rate Limiting (DDoS & Brute Force Prevention)

- **Login Endpoint:** Protected with custom Laravel rate limiter in [api.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/routes/api.php#L38):
  ```php
  Route::post('auth/login', [AuthController::class, 'login'])->middleware('throttle:login');
  ```
- **Global Protected API:** Throttled with `throttle:api` globally on authenticated requests, mitigating volumetric scanning or brute force extraction.

---

## 5. File Upload Security

- **Controller Handling:** [MediaController.php](file:///d:/dotlaa_pos/dotlaa_pos_backend/app/Http/Controllers/Api/V1/MediaController.php)
- **Upload Validation:** Validates that incoming uploads are strictly verified mime-type image assets (e.g. jpeg, png, webp, gif) and capped in size (typically 2MB) to prevent remote code execution (RCE) via malicious shell uploads.
- **Safe Storage Directory:** Uploaded files are renamed using cryptographic hashes and stored securely outside the server execution document roots inside `storage/app/public/media`.