fix(gsm): secure and harden SMS delivery

[Adamskiee]

Summary

Hardens the complete SMS delivery path across the GSM gateway, main server, and mobile app.

• Bounds outbound GSM admission with a configurable first-in, first-out queue and rejects saturation with HTTP 503 and QUEUE_FULL.
• Prevents requests that expire before serial transmission from being written later, while allowing in-flight writes to wait for modem confirmation.
• Requires GSM_SECRET in the GSM service and validates X-GSM-Secret before POST /sms/send can create a log row or occupy the modem.
• Sends X-GSM-Secret from the main server for every direct gateway send.
• Reconciles orphaned pending log rows at startup as failed/SERVICE_CRASHED before the serial worker starts.
• Records rejected inbound messages with NO_ACCOUNT, BANNED_SENDER, or UNVERIFIED_SENDER.
• Preserves gateway HTTP 502 and 503 responses through the main server and increases proxy timeout and connection headroom for the bounded queue.
• Adds typed mobile GSM errors, keeps failed chat messages available for manual retry, and prevents verification or onboarding flows from reporting false success.
• Updates security, architecture, deployment, API, requirements, design, and testing documentation.

Why

The GSM modem is a physical serial bottleneck that takes seconds to process each message. Unbounded or unauthenticated access can occupy the only outbound disaster-response channel and cause a denial of service.

Power loss can also leave sms_log rows permanently pending. Startup marks those rows failed instead of replaying them because the modem may already have transmitted the SMS before the crash, and replay could duplicate emergency messages.

Behavior

Gateway admission

• SMS_SEND_QUEUE_MAXSIZE accepts values from 1 through 20 and defaults to 10 waiting requests.
• One additional request may be active.
• Saturated requests return HTTP 503 with QUEUE_FULL.
• Shutdown rejects queued and active requests with SERVICE_STOPPING.
• Queue wait and modem-readiness wait share a pre-write deadline.
• Once serial transmission starts, the request waits for confirmation or the post-write timeout.

Service authentication

Both HTTP directions use the same shared secret:

• Main server to GSM gateway: POST /sms/send with X-GSM-Secret
• GSM gateway to main server: POST /gsm/inbound with X-GSM-Secret

Both services fail startup when their required secret is missing. Port 8001 remains restricted to host loopback or the trusted Compose network as an additional boundary.

Crash recovery and observability

Before constructing SerialWorker, gateway startup changes every orphaned pending row to:

status=failed
failure_reason=SERVICE_CRASHED

Inbound sender eligibility failures are retained as rejected audit records rather than appearing as successfully received traffic.

Validation

• GSM gateway suite: 36 passed
• Main-server GSM proxy and health tests: 12 passed
• OpenAPI documentation drift check: passed
• Database documentation drift check: passed
• Mobile Jest run: 1,116 passed, with one unrelated parallel-run timeout
• Timed-out mobile auth suite rerun alone: 15 passed
• Mobile TypeScript check: passed
• Mobile ESLint: passed with one warning in generated .expo/types/router.d.ts
• Expo Doctor: 18/18 checks passed
• git diff --check: passed

The full server suite still depends on correctly isolated Redis, WebSocket lifespan, and database test services. The GSM-focused server tests pass.

Deployment notes

Set the same strong GSM_SECRET in the main server and GSM gateway environment files before restarting either service. Existing installed systemd units and restricted files under /etc/sapot/ still require the normal operator deployment procedure.

Do not automatically replay SERVICE_CRASHED messages. Operators should inspect them before deciding whether a manual resend is safe.

Additional QA coverage

• Adds the verified-phone testing scenario, which seeds qa_phone_verified with a valid Philippine phone number and a PhoneVerified record.
• Adds qa_phone_verified to the testing login-fixture allowlist for phone-verification-gated flows.
• Documents the scenario and covers both the seed state and /testing/login-as/qa_phone_verified.

Focused verification: ./venv/bin/pytest tests/test_qa_scenarios.py tests/test_testing_endpoints.py (28 passed).

A full server-suite run remains unavailable in this environment because the configured redis and db Docker hostnames cannot be resolved.