breadcrumb-the-shire/agent-system/runs/TEST-COVERAGE-GATEWAYS-001/plan.json

{
  "task_id": "TEST-COVERAGE-GATEWAYS-001",
  "summary": "Add PHPUnit tests for 3 critical untested gateways: AuthCryptoGateway, SettingsCryptoGateway, OidcHttpGateway. These are security-critical components with 0% test coverage. (Amended: PermissionGateway removed — does not exist in codebase.)",
  "assumptions": [
    "AuthCryptoGateway and SettingsCryptoGateway wrap lib/Support/Crypto.php — tests verify correct delegation and error handling.",
    "OidcHttpGateway makes HTTP calls to Microsoft OIDC endpoints — tests will mock the HTTP client.",
    "AMENDED: PermissionGateway does not exist in codebase — removed from scope. ARCH-GATEWAY-COMPLIANCE-001 did not create it.",
    "Focus on security-critical gateways first; remaining 19 untested gateways can follow in a later task."
  ],
  "scope": {
    "in": [
      "New: tests/Service/Auth/AuthCryptoGatewayTest.php — encryption/decryption delegation",
      "New: tests/Service/Settings/SettingsCryptoGatewayTest.php — settings value encryption",
      "New: tests/Service/Auth/OidcHttpGatewayTest.php — OIDC token validation, HTTP error handling",
      "REMOVED: tests/Service/Access/PermissionGatewayTest.php — PermissionGateway does not exist in codebase"
    ],
    "out": [
      "Non-critical gateways (AddressBook, Import, Directory scope gateways)",
      "Production code changes",
      "Repository tests",
      "Integration tests with real HTTP or crypto operations"
    ]
  },
  "guardrails": {
    "required_guard_ids": [
      "GR-TEST-001",
      "GR-TEST-002",
      "GR-SEC-005",
      "GR-LANG-001",
      "GR-LANG-002"
    ],
    "required_quality_gate_ids": [
      "QG-001",
      "QG-002",
      "QG-006"
    ]
  },
  "success_criteria": [
    {
      "id": "SC-001",
      "criterion": "All 3 test files exist with happy-path + error/edge-case coverage for every public method. (Amended from 4: PermissionGateway does not exist in codebase.)"
    },
    {
      "id": "SC-002",
      "criterion": "AuthCryptoGateway and SettingsCryptoGateway tests verify that Crypto class is used (not raw openssl), per GR-SEC-005. Verification via encrypted payload format assertion (base64-wrapped JSON with v/iv/tag/ct fields proving AES-256-GCM via Crypto) is acceptable when Crypto is not constructor-injected."
    },
    {
      "id": "SC-003",
      "criterion": "OidcHttpGateway tests cover: successful token exchange, invalid token response, network timeout, malformed response body."
    },
    {
      "id": "SC-004",
      "criterion": "PHPUnit (QG-001), PHPStan (QG-002), and CS (QG-006) pass green; zero new failures introduced by this task (pre-existing failures are out of scope)."
    }
  ],
  "implementation_steps": [
    {
      "id": "S1",
      "title": "Analyze public API of all 4 gateways",
      "description": "Read each gateway, list public methods, identify constructor dependencies, plan test scenarios.",
      "guard_refs": ["GR-TEST-001"]
    },
    {
      "id": "S2",
      "title": "Write AuthCryptoGatewayTest",
      "description": "Test encrypt/decrypt delegation to Crypto class. Test error handling for invalid keys, empty input, corrupted ciphertext.",
      "guard_refs": ["GR-TEST-001", "GR-SEC-005"]
    },
    {
      "id": "S3",
      "title": "Write SettingsCryptoGatewayTest",
      "description": "Test settings value encryption/decryption. Test round-trip (encrypt then decrypt returns original). Test error paths.",
      "guard_refs": ["GR-TEST-001", "GR-SEC-005"]
    },
    {
      "id": "S4",
      "title": "Write OidcHttpGatewayTest",
      "description": "Mock HTTP client. Test token exchange happy path, invalid response codes (401, 500), network errors, malformed JSON response, missing required fields in token response.",
      "guard_refs": ["GR-TEST-001", "GR-TEST-002"]
    },
    {
      "id": "S5",
      "title": "REMOVED — PermissionGateway does not exist",
      "description": "PermissionGateway was assumed to exist but does not. Step removed from scope.",
      "guard_refs": []
    },
    {
      "id": "S6",
      "title": "Run quality gates",
      "description": "QG-001, QG-002, QG-006.",
      "guard_refs": ["GR-LANG-002"]
    }
  ],
  "tests": [
    "tests/Service/Auth/AuthCryptoGatewayTest.php",
    "tests/Service/Settings/SettingsCryptoGatewayTest.php",
    "tests/Service/Auth/OidcHttpGatewayTest.php",
    "REMOVED: tests/Service/Access/PermissionGatewayTest.php — PermissionGateway does not exist"
  ],
  "acceptance_checks": [
    "SC-001: All 3 test files pass with >= 3 test methods each (amended from 4: PermissionGateway removed)",
    "SC-002: AuthCrypto + SettingsCrypto tests verify Crypto delegation via payload format assertions (AES-256-GCM structure with v/iv/tag/ct fields)",
    "SC-003: OidcHttpGatewayTest has test methods for success, 401, 500, timeout, malformed JSON",
    "SC-004: QG-001 + QG-002 + QG-006: zero new failures introduced by this task (pre-existing failures are out of scope)"
  ],
  "risks": [
    {
      "risk": "OidcHttpGateway may use PHP native curl/file_get_contents instead of injectable HTTP client",
      "mitigation": "If not mockable, document as tech debt and test at integration level with a mock HTTP server, or refactor to accept an HTTP client interface."
    },
    {
      "risk": "RESOLVED: PermissionGateway does not exist in codebase",
      "mitigation": "Removed from scope. No action needed."
    }
  ]
}