# TANRAIL ONE — Phase 3.1 Security Remediation

## 1. Original Finding
The Phase 3.1 Core Data Foundation constructed perfectly agnostic database structures, but it completely omitted application-layer boundaries. Models (`Customer`, `Supplier`, `Item`) lacked Global Scopes and Authorization Policies, resulting in cross-organization and cross-business-unit data leakage.

## 2. Root Cause
Phase 3.1 was executed specifically to establish the Data Models, Migrations, and Enums. The application security boundaries were accidentally bypassed during the initial construction phase, as no Controllers or UI elements were built to necessitate them immediately. This violated the architecture's strict "Secure by Default" mandate at the Model level.

## 3. Correction
- **ContextManager Enhancement:** `ContextManager` was updated to securely extract and cache `active_org_id` into the session immediately when a user selects an active Business Unit. This prevents severe N+1 database querying during global scope resolution.
- **Global Scopes:** Created `OrganizationScope` and `BusinessUnitScope`. These are configured to forcefully fail the query if the scopes are triggered but no active context is found, ensuring the application fails securely.
- **Model Hooks:** Applied the respective Global Scopes via the `booted` method in `Customer`, `Supplier`, and `Item` models.
- **Authorization Policies:** Implemented `CustomerPolicy`, `SupplierPolicy`, and `ItemPolicy` utilizing Phase 2's hierarchical inheritance checker (`hasAccessToScope`) to strictly block hierarchy mismatch attacks (e.g. creating an Item in BU B when acting as Org A).

## 4. Files Changed
- `app/Domains/Core/Services/ContextManager.php`
- `app/Domains/Core/Scopes/OrganizationScope.php` [NEW]
- `app/Domains/Core/Scopes/BusinessUnitScope.php` [NEW]
- `app/Domains/Core/Models/Customer.php`
- `app/Domains/Core/Models/Supplier.php`
- `app/Domains/Core/Models/Item.php`
- `app/Domains/Core/Models/Role.php`
- `app/Domains/Core/Policies/CustomerPolicy.php` [NEW]
- `app/Domains/Core/Policies/SupplierPolicy.php` [NEW]
- `app/Domains/Core/Policies/ItemPolicy.php` [NEW]
- `app/Providers/AppServiceProvider.php`
- `database/factories/RoleFactory.php` [NEW]
- `tests/Feature/Core/Phase31AuditTest.php`
- `tests/Feature/Phase2FoundationTest.php`

## 5. Security Tests Added
Added all 12 requested strict boundary and verification tests to `Phase31AuditTest`:
1. Org A retrieves Customer A (Visible)
2. Org A retrieves Customer B (Denied/Invisible via Scope)
3. Org A retrieves Supplier A (Visible)
4. Org A retrieves Supplier B (Denied/Invisible via Scope)
5. BU A retrieves Item A (Visible)
6. BU A retrieves Item B (Denied/Invisible via Scope)
7. BU A user creates Item in BU B (Denied via Policy)
8. BU A user updates Item in BU B (Denied via Policy)
9. Org A user creates Item under BU B (Denied via Policy)
10. Org-level user accesses child BU (Allowed via Phase 2 trait inheritance)
11. Invalid hierarchy assignment (Org A context creating for BU B)
12. SKU Uniqueness check (Allowed across BUs, rejected within same BU).

## 6. Test Results
`php artisan test --filter=Phase31AuditTest`
- **Total Tests:** 12
- **Passed:** 12
- **Failed:** 0
- **Assertions:** 16

## 7. Regression Results
`php artisan test` (Full Suite)
- **Total Tests:** 29
- **Passed:** 29
- **Failed:** 0
*(Note: A regression test failure in Phase 2 caused by an invalid `Role` factory string casting has been permanently fixed).*

## 8. Architecture Compliance
The models now fully comply with `docs/06-data-architecture.md` which mandates Model-level isolation. Phase 2's authorization engine acts as the unified source of truth.

## 9. Remaining Risks
Currently, there are no known security risks or architectural deviations in the Phase 3.1 Data Foundation.