Fax Tone/Send Module Modernization¶

Repository: klearcom-in/kc-web · Branch: global-logic
Module: Fax Tone/Send (test type 6)
Labels: ai-created, modernization, security, php, laravel, refactoring

User Story¶

As a platform engineer maintaining the kc-web Fax vertical,
I want the Fax Tone/Send module (test type 6) refactored to eliminate structural duplication, close a live IDOR security vulnerability, and establish automated test coverage,
So that future changes to fax sub-types touch one strategy class instead of 17+ service files, all fax_test_type authorization boundaries are enforced by policy, and regressions are caught before they reach production.

Background¶

The Fax Tone/Send module is structurally impaired by three compounding issues that block safe evolution:

1. Parallel-family duplication: 12 mirrored model classes, 14 database tables, and 4+ service pairs exist as "plain" and "verify+" families. Every bug fix and feature must be applied twice, and every if ($fax_test_type == 1) branch propagates through all layers.
2. IDOR security risk (OWASP A01): fax_test_type is used as an implicit authorization boundary throughout all layers with no policy enforcement. A caller can manipulate this value to access data from the wrong family without being rejected.
3. Zero test coverage: No PHPUnit/Pest test files exist for any of the 17+ services or 17 models in this module. Any refactoring is performed blind.

A secondary concern is REST API version proliferation: v1, v2, and v3 are all active, tripling the security patch surface with no active deprecation plan.

Analysis and design artifacts are in agent-runs/20260818T081205_xh1h09/ (01-code-analysis.md, 02-design-document.md, 03-task-list.md).

Scope¶

In Scope¶

Out of Scope¶

• Changes to the 14 existing database tables (all preserved intact)
• Billing or telecom engine integrations
• Any module other than Fax Tone/Send (test type 6)

Acceptance Criteria¶

1. AC-1 (Security): FaxTestTypePolicy exists and is bound to all fax controller actions; a request with a mismatched fax_test_type returns HTTP 403.
2. AC-2 (Strategy Pattern): FaxTestStrategyInterface with PlainFaxStrategy and VerifyFaxStrategy implementations is in place; no if ($fax_test_type == 1) branches remain in service or controller layers.
3. AC-3 (API Deprecation): All REST v1 and v2 routes return Deprecation and Sunset headers; REST v3 passes parity checks.
4. AC-4 (Test Coverage): PHPUnit/Pest test suite covers Form Requests, controllers, FaxMonitorService, strategies, and policy; coverage gate ≥80% enforced in CI.
5. AC-5 (No Regressions): All existing fax scheduling and billing integrations pass unchanged; php artisan migrate --pretend runs cleanly.
6. AC-6 (Controller SRP): KcFaxSchedulerController is split into ≤4 focused controllers, each with ≤2 responsibilities.

Technical Notes¶

• 32 tasks across 4 implementation phases defined in agent-runs/20260818T081205_xh1h09/03-task-list.md and tasks.json.
• Critical ordering constraint: T-24/T-25 (HTTP integration tests for existing behaviour) must complete before T-16/T-17 (service refactoring); T-26 (FaxMonitorService tests) before T-21 (chunking).
• No schema changes to existing tables — all 14 tables preserved throughout.
• MongoDB removal (Phase 4): fax_monitor_audit SQL table replaces MongoDB audit-only usage; migration is conditional on O-7 resolution.
• Eight open questions (O-1, O-3, O-4, O-5, O-7 are blockers for Phase 2) — see 02-design-document.md for full list including actual StoreFaxRequest field names, Laravel version, and whether fax_test_type is a stored column or request-only.

Dependencies¶

• Resolution of open design questions O-1, O-3, O-4, O-5, O-7 before any Phase 2 code is written.
• No external service or billing system changes required.

Labels: ai-created, modernization, security, php, laravel, refactoring