# TANRAIL ONE — Security & Access Control

## 1. Authentication Strategy
- **System:** Centralized login handling for all platform access.
- **Session:** Secure HttpOnly cookies for web access; Bearer Tokens (Sanctum/Passport) for API/Mobile access.
- **Password Policy:** Minimum 8 characters, requiring mixed casing and numbers. Account lockout after 5 failed attempts.

## 2. Authorization Model (RBAC + Context)
Standard Role-Based Access Control (RBAC) is insufficient because a user might be a "Manager" in the Restaurant, but just a "Viewer" in Catering.

### 2.1 The Tripartite Permission Matrix
Permissions are resolved by checking three dimensions:
1. **User Identity** (Who is it?)
2. **Action/Module Permission** (What are they trying to do? e.g., `inventory.edit`)
3. **Scope Context** (Where are they trying to do it?)
   - **Organization Level:** (e.g., Creating a new Business Unit). Only global admins.
   - **Business Unit Level:** (e.g., Viewing all Sales across a BU).
   - **Branch / Location Level:** (e.g., Making a stock adjustment in a specific storeroom).

### 2.2 Roles definition
Roles are collections of permissions.
- `Super Admin`: Bypasses all checks.
- `Executive`: Global read access, access to consolidated reports.
- `BU Manager`: Full CRUD within a assigned BU.
- `Cashier`: Create orders, process payments within an assigned Branch.
- `Accountant`: Access to Finance modules across assigned BUs.

## 3. Data Boundary Enforcement

### 3.1 Backend Protection (Critical)
- **Never trust the frontend.** If the frontend sends `{ order_id: 5, action: "cancel" }`, the backend controller must explicitly verify:
  `Gate::authorize('cancel', $order);`
- The Policy for the Order must check: Does the authenticated user have the `order.cancel` permission IN the `business_unit_id` that owns Order 5?

### 3.2 Global Scope Injection
- To prevent accidental data leaks (e.g., returning Catering products in the Restaurant POS), Global Scopes automatically append `WHERE business_unit_id = X` to queries based on the user's active session context.

## 4. Sensitive Operations
Certain actions require higher security thresholds.
- **Voiding Invoices / Deleting Payments:** Requires `finance.void` permission, typically restricted to Managers/Admins.
- **Manual Stock Adjustments (Negative):** Requires `inventory.adjust` and forces the user to log a reason.

## 5. Audit Logging
Every `POST`, `PUT`, `PATCH`, and `DELETE` request affecting business data must generate an audit log.
- `user_id`, `ip_address`, `timestamp`, `action`, `model`, `before_state`, `after_state`.
- This ensures full traceability if financial irregularities are detected.