Summary

• validate inbound Twilio SMS webhooks before scheduling message handling
• reject missing or forged X-Twilio-Signature requests with a fast 403 response
• add focused unit and integration-style regression tests for Twilio signature enforcement

Problem

The SMS adapter accepted any POST to /webhooks/twilio and immediately scheduled handle_message() without verifying that the request actually came from Twilio.

That meant anyone who knew the webhook URL could forge inbound SMS payloads and impersonate arbitrary phone numbers.

Investigation

Validated in a clean isolated worktree from current origin/main:

• searched for an existing issue/PR matching this specific Twilio signature-validation gap and did not find one
• confirmed gateway/platforms/sms.py::_handle_webhook() parsed form data and queued work without checking X-Twilio-Signature
• checked Twilio Python best practice: validate the full request URL + POST vars against the Auth Token (equivalent to RequestValidator.validate(url, post_vars, signature))
• got a second opinion via Claude Code, which recommended the same minimal fix shape and test coverage

Fix

• add _validate_twilio_signature() to SmsAdapter
• validate X-Twilio-Signature immediately after parsing the form body
• return empty TwiML with HTTP 403 on invalid or missing signature
• keep the webhook non-blocking for valid requests

Validation

Ran locally in the isolated worktree:

• pytest tests/gateway/test_sms.py -q -o addopts=
• python -m py_compile gateway/platforms/sms.py tests/gateway/test_sms.py

Result:

• 29 passed

Tests added

• signature helper unit tests:
  • valid signature
  • wrong signature
  • empty signature
  • tampered body
  • wrong URL
• webhook enforcement tests:
  • missing signature -> 403
  • invalid signature -> 403
  • valid signature -> 200