# Changelog

All notable changes to LabPilot are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [Unreleased] - 2026-04-16

### Changed

#### Codebase Remediation Closure

- Added a backend scan inventory audit and wired it into the architecture gate
  so new DynamoDB scan usage or scan-count drift fails CI unless explicitly
  allowlisted with rationale
- Added focused k6 load harnesses for audit logs, pool search, and order map,
  plus a local mock server used by CI to verify the scripts remain runnable
- Extended the test workflow with blocking performance hot-path regression and
  load-harness jobs
- Updated architecture, performance, and production-readiness docs to reflect
  the remediated baseline and the remaining explicit scan debt

### Added

- `scripts/audit_backend_scan_inventory.mjs`
- `amplify/tests/load/audit-logs.k6.js`
- `amplify/tests/load/pool-search.k6.js`
- `amplify/tests/load/order-map.k6.js`
- `amplify/tests/load/mock-server.mjs`

## [Unreleased] - 2026-01-29

### Fixed

#### Mock Mode & RBAC Shell Routing

- **Fixed phlebotomist users seeing ManagerShell instead of FieldWorkerShell**
  - Root cause: Mock data was enabled for orders/users, but `CapabilitiesService` still called real backend
  - Real backend user's role (often PhlebManager during testing) determined shell type
  - Fix: Created `MockCapabilitiesService` that respects mock mode configuration

- **Unified mock mode configuration to single source of truth**
  - Previously: Multiple hardcoded `_useMockData = true` flags scattered across files
  - Now: Single `_devMockOverride` flag in `MockConfig` controls all mock behavior
  - All services now use `MockGuards.shouldUseMock` consistently

### Added

#### Mock Mode Infrastructure

- **`lib/features/auth/data/mock_capabilities_service.dart`** (NEW FILE)
  - Mock capabilities service for UI development
  - Configurable role via `_mockRole` constant
  - Configurable company type via `_mockCompanyType` constant
  - Generates appropriate capabilities based on role (shell type, PHI access, etc.)

- **`docs/MOCK_MODE_CONFIGURATION.md`** (NEW FILE)
  - Comprehensive documentation for mock mode system
  - Quick start guide for testing different roles
  - Architecture diagram and file structure
  - Troubleshooting guide

### Changed

#### Mock Mode Configuration

- **`lib/core/mock/mock_config.dart`**
  - Added `_devMockOverride` constant as single source of truth for development
  - Updated `useMockData` getter to check override first, then environment flag
  - Added documentation comments explaining the configuration

- **`lib/features/auth/data/capabilities_provider.dart`**
  - Now uses `MockCapabilitiesService` when `MockGuards.shouldUseMock` is true
  - Added import for `mock_guards.dart` and `mock_capabilities_service.dart`
  - Added logging for which service is being used

- **`lib/features/orders/presentation/orders_controller.dart`**
  - Removed hardcoded `_useMockData = true` flag
  - Now uses `MockGuards.shouldUseMock` for repository selection
  - Simplified provider logic

- **`lib/features/orders/presentation/order_timeline_controller.dart`**
  - Removed hardcoded `_useMockData = true` flag
  - Now uses `MockGuards.shouldUseMock` for repository selection

- **`lib/features/specimens/data/print_data_service.dart`**
  - Removed hardcoded `useMockData = true` flag
  - Now uses `MockGuards.shouldUseMock` for service selection
  - Updated import from `mock_config.dart` to `mock_guards.dart`

---

## [Unreleased] - 2026-01-24

### Security

#### CRITICAL Fixes (HIPAA Compliance)

- **Fixed PHI exposure in orders map endpoint for SalesManager role**
  - File: `amplify/functions/order/map/handler.ts`
  - Issue: SalesManager was included in MANAGER_ROLES, allowing access to patient location data
  - Fix: Removed SalesManager from MANAGER_ROLES, added explicit `isSalesRole()` guard returning 403
  - Reference: RBAC_AUDIT_REPORT.md Issue #1

- **Fixed ungated address field in map response**
  - File: `amplify/functions/order/map/handler.ts`
  - Issue: `address` field was returned unconditionally to all callers (PHI leak)
  - Fix: Gated `address` and `patientName` fields with `hasPHIAccess(role)` check
  - Reference: RBAC_AUDIT_REPORT.md Issue #2

- **Added PHI audit comment for lat/lng location data**
  - Documented that latitude/longitude coordinates are considered PHI-equivalent
  - Sales roles are fully blocked from map endpoint (not just PHI fields stripped)

#### HIGH Priority Fixes (Authorization Gaps)

- **Added caller authorization check to invite-user endpoint**
  - File: `amplify/functions/user/invite-user/handler.ts`
  - Issue: Any authenticated user could invoke the endpoint to invite users
  - Fix: Added caller membership verification with `canManageUsers()` and `isSalesRole()` checks
  - Reference: RBAC_AUDIT_REPORT.md Issue #4

- **Removed SalesManager from assignment settings access**
  - File: `amplify/functions/settings/assignment/handler.ts`
  - Issue: SalesManager could modify auto-assignment rules (operational integrity risk)
  - Fix: Removed SalesManager from MANAGER_ROLES, added explicit `isSalesRole()` guard
  - Reference: RBAC_AUDIT_REPORT.md Issue #3

- **Added Sales role guards to order/available endpoint**
  - File: `amplify/functions/order/available/handler.ts`
  - Issue: No explicit role check for Sales roles (defense-in-depth gap)
  - Fix: Added `isSalesRole(role)` guard returning 403
  - Reference: RBAC_AUDIT_REPORT.md Issue #5

- **Added Sales role guards to order/accept endpoint**
  - File: `amplify/functions/order/accept/handler.ts`
  - Issue: No explicit role check for Sales roles (defense-in-depth gap)
  - Fix: Added `isSalesRole(role)` guard returning 403
  - Reference: RBAC_AUDIT_REPORT.md Issue #5

### Added

#### Infrastructure (Phase 3)

- **`amplify/shared/guards/require-guards.ts`** (NEW FILE)
  - Centralized authorization guard functions (nullable pattern)
  - `requireNonSales()` - Block all commercial roles
  - `requireOperationalManager()` - Require operational manager access
  - `requirePHIAccess()` - Require PHI access permissions
  - `requireUserManagement()` - Require user management permissions
  - `requireAdmin()` - Require administrator access

- **`OPERATIONAL_MANAGER_ROLES` constant**
  - File: `amplify/shared/utils/role-permissions.ts`
  - Centralized list of operational manager roles (excludes SalesManager)
  - Used for map, settings, team locations, and order management access

- **`isOperationalManager()` function**
  - File: `amplify/shared/utils/role-permissions.ts`
  - Check if role is an operational manager (excludes SalesManager)
  - Use instead of `isManagerRole()` for PHI/operational access checks

#### Testing (Phase 4)

- **Unit tests for RBAC guards**
  - File: `amplify/tests/shared/guards/require-guards.test.ts`
  - Tests for all guard functions
  - Verifies correct behavior for Sales roles, managers, and admins

- **Integration tests for RBAC endpoints**
  - File: `amplify/tests/functions/rbac-endpoints.integration.test.ts`
  - Tests Sales role 403 responses for protected endpoints
  - Verifies authorized roles receive 200 responses

#### Documentation (Phase 5)

- **Updated RBAC documentation**
  - File: `docs/ssot/40_ROLES_PERMISSIONS.md`
  - Added PHI Access Matrix with all roles and access levels
  - Added Sales Role Restrictions section (detailed enforcement)
  - Added Global Security Rule pattern
  - Added Operational Manager Roles explanation
  - Added Company Type Role Availability section

- **Created RBAC Audit Report**
  - File: `docs/RBAC_AUDIT_REPORT.md`
  - Comprehensive audit of RBAC implementation
  - 8 issues identified (2 critical, 3 high, 2 medium, 1 verified correct)
  - Root cause analysis and permanent fix patterns

- **Created RBAC Implementation Plan**
  - File: `docs/RBAC_IMPLEMENTATION_PLAN.md`
  - 5-phase remediation plan
  - Phased rollout with verification checklists
  - Testing and deployment procedures

- **Created CHANGELOG.md**
  - File: `docs/CHANGELOG.md`
  - Tracks all security fixes and changes
  - Follows Keep a Changelog format

### Changed

- **All handler-local MANAGER_ROLES arrays updated**
  - SalesManager removed from all local arrays
  - Comment added explaining exclusion per HIPAA compliance
  - Handlers: `orders/map`, `settings/assignment`

- **transition-rules.ts imports UserRole correctly**
  - File: `amplify/functions/order/transition/transition-rules.ts`
  - Already imports from `../../user/user.model` (no change needed)

- **PHI guard enforcement pattern standardized**
  - All PHI endpoints use `hasPHIAccess()` for field gating
  - All operational endpoints use `isSalesRole()` for full blocking
  - Defense-in-depth: Sales blocked at entry + fields gated as backup

### Deprecated

- **`isManagerRole()` for PHI/operational checks**
  - Use `isOperationalManager()` instead
  - `isManagerRole()` still available for UI purposes (includes SalesManager)

### Removed

- **SalesManager from operational access lists**
  - No longer in MANAGER_ROLES for map, settings, team locations
  - Cannot access PHI or operational endpoints

---

## Compliance Notes

### HIPAA References

| Fix | HIPAA Section | Standard |
|-----|---------------|----------|
| Map PHI exposure | 45 CFR 164.312 | Access Control |
| Address field leak | 45 CFR 164.312 | Access Control |
| Assignment settings | 45 CFR 164.308 | Security Management |
| User invite auth | 45 CFR 164.312 | Access Control |

### Audit Trail

- All 403 responses logged to CloudWatch
- ForbiddenError instances tracked for compliance reporting
- Role access patterns available for audit review

---

## Migration Guide

### For Developers

1. **Update guard imports**
   ```typescript
   import { requireNonSales, requireOperationalManager } from "../../../shared/guards/require-guards";
   ```

2. **Use standardized guard pattern**
   ```typescript
   const guard = requireOperationalManager(role);
   if (guard) return guard;
   ```

3. **Replace local MANAGER_ROLES with centralized constant**
   ```typescript
   import { OPERATIONAL_MANAGER_ROLES, isOperationalManager } from "../../../shared/utils/role-permissions";
   ```

### For Compliance Team

- Review RBAC_AUDIT_REPORT.md for detailed findings
- All critical PHI issues have been remediated
- Schedule follow-up audit in 30 days to verify effectiveness

---

*Maintained by: LabPilot Engineering Team*
*Compliance Contact: compliance@labpilot.com*