# TANRAIL ONE — Phase 4.0 Security & Multi-Tenant Architecture

## 1. Security Principles
Phase 4.0 strictly adheres to the core multi-tenant security principles of TANRAIL ONE:
1. **Server-Side Authorization**: Client-provided tenant identifiers (Organization ID, Business Unit ID) are NEVER trusted. All scopes are resolved server-side from active session context (`ContextManager`).
2. **Global & BU Scopes**: `OrganizationScope` and `BusinessUnitScope` automatically scope Eloquent queries for `Invoice`, `SupplierInvoice`, `CreditNote`, and `PaymentAllocation`.
3. **Cross-Tenant Attack Rejection**: Any attempt to allocate funds or link documents across different Business Units or Organizations is blocked by model observers and domain exceptions.

---

## 2. Specific Attack Vectors & Mitigations

### 2.1 Cross-Organization Payment Allocation Attack
- **Attack Vector**: An attacker attempts to allocate a `Payment` belonging to Organization A to settle an `Invoice` belonging to Organization B.
- **Mitigation**:
  - `PaymentAllocation::booted()` observer validates:
    `$payment->organization_id === $invoice->organization_id`.
  - Violations throw `CrossOrganizationException` and abort the transaction.

### 2.2 Cross-Business Unit Payment Allocation Attack
- **Attack Vector**: An attacker attempts to apply a payment from Business Unit 1 to an invoice in Business Unit 2.
- **Mitigation**:
  - `PaymentAllocation::booted()` observer validates:
    `$payment->business_unit_id === $invoice->business_unit_id`.
  - Violations throw `CrossBusinessUnitException`.

### 2.3 Over-Allocation & Double-Dipping Attack
- **Attack Vector**: An attacker submits concurrent requests allocating $100 against a payment that only has $50 unallocated, or against an invoice that only has $50 balance due.
- **Mitigation**:
  - `PaymentAllocationService` executes inside an atomic `DB::transaction()`.
  - The `Payment` and target `Invoice` records are queried using pessimistic locks (`lockForUpdate()`).
  - Allocation amount is strictly validated: `$amount <= $invoice->balance_due` and `$amount <= $payment->unallocated_amount`.

### 2.4 Issued Document Tampering Attack
- **Attack Vector**: An attacker attempts to modify amounts or line items on an `ISSUED` invoice or `APPROVED` supplier invoice to reduce tax liability or conceal theft.
- **Mitigation**:
  - Model observers on `Invoice` and `SupplierInvoice` block `update()` on financial attributes once issued/approved.
  - Modifying `subtotal`, `tax_amount`, `total`, or deleting lines raises `JournalImmutableException`.

---

## 3. Server-Side Authorization Matrix

| Action | Required Permission | Scoping Gate |
|---|---|---|
| Create Invoice | `invoices.create` | `EnsureActiveContext` + BU match |
| Issue Invoice | `invoices.issue` | `EnsureActiveContext` + BU match |
| Void Invoice | `invoices.void` | `EnsureActiveContext` + BU match + Draft status |
| Allocate Payment | `payments.allocate` | `EnsureActiveContext` + BU match + Lock check |
| Approve Supplier Bill | `bills.approve` | `EnsureActiveContext` + Manager Role + BU match |
| Issue Credit Note | `credit_notes.create` | `EnsureActiveContext` + Manager Role + BU match |