Architecture note: Adding phone‑based 2FA with Twilio Verify

Requirements

The service must confirm a user’s possession of a phone number before allowing access to sensitive actions. Key non‑functional goals are:

• Verification code delivery latency under 2 seconds on average.
• Ability to retry sending a code with exponential back‑off.
• Never store the raw verification code; only a hashed reference to the Twilio verification SID may be persisted.
• Idempotent requests so that retries do not cause duplicate SMS charges.

Smallest suitable design

A thin wrapper service exposes a single HTTP endpoint POST /verify. The flow is:

1. Caller supplies phoneNumber (in E.164 format) and an optional idempotencyKey.
2. The wrapper calls Twilio’s Verify API (verify/v2/Services/{SERVICE_SID}/Verifications) to send a code.
3. Twilio returns a verificationSid. The wrapper immediately hashes this SID (e.g., SHA‑256 with a per‑environment secret) and stores the hash alongside the user identifier.
4. The wrapper responds with 202 Accepted and a client‑side token that references the hash (never the SID itself).
5. When the user submits the received code, the caller invokes POST /check with the token and the code. The wrapper looks up the stored hash, retrieves the original verificationSid from a short‑lived cache (or re‑queries Twilio if the cache missed), and calls Twilio’s Check endpoint (verify/v2/Services/{SERVICE_SID}/Verifications/{verificationSid}/Check).
6. Twilio responds with approved or pending; the wrapper maps this to HTTP 200 (success) or 400 (failure) and returns only a boolean outcome.

Implementation notes:

• Use Twilio’s official server‑side SDK (Node.js twilio or Java com.twilio.sdk) with TLS 1.2 enforced.
• Generate the idempotency key from a UUID v4 if the caller does not provide one; pass it as the Idempotency-Key header to Twilio.
• Store the hashed SID in a fast cache (e.g., Redis) with a TTL matching the verification expiry (typically 10 minutes).
• All secrets (Twilio Account SID, Auth Token, Verify Service SID, hashing secret) are fetched at runtime from a secret manager (AWS Secrets Manager, HashiCorp Vault, etc.) using the service’s IAM role; they never appear in source code or container images.

Trust and data boundaries

The wrapper treats Twilio as an external trusted party for code delivery and verification. Trust boundaries are:

• In‑boundary: The wrapper’s internal API, secret manager, and cache.
• Out‑of‑boundary: Twilio’s Verify API, the public telephone network, and the end‑user’s device.

Data that crosses the boundary:

• Phone number (E.164) is sent to Twilio; the wrapper redacts it from all logs.
• Verification SID is never exposed to callers; only its hash persists.
• Logs must omit any substring matching the pattern \d{6} (typical verification code) and the raw phone number.

Operational checks

To maintain reliability, monitor the following:

• Delivery success rate: Subscribe to Twilio status callbacks (StatusCallback) and increment a counter for each queued, sent, delivered, or failed event. Alert if the failed‑to‑sent ratio exceeds 5 % over a 5‑minute window.
• Rate‑limit headers: Twilio returns X-Twilio-RateLimit-Remaining and X-Twilio-RateLimit-Reset. The wrapper should read these headers and, when remaining < 10, apply a local throttling delay (e.g., 100 ms) before the next request.
• Latency metrics: Record time from wrapper receipt of POST /verify to Twilio’s sent callback, and from POST /check to Twilio’s check response. Target p95 < 2 s.
• Error code tracking: Capture Twilio error codes (e.g., 20400 – invalid parameters, 20404 – verification not found, 20429 – too many requests) and emit them to a monitoring system for trend analysis.

Example command to verify that no verification codes appear in logs (run on a log‑aggregation host with read‑only access to the service’s log stream):

# Requires: grep, regex support, access to /var/log/twilio-wrapper/*.log
# Risk: none – read‑only scan.
grep -E '\b[0-9]{6}\b' /var/log/twilio-wrapper/*.log | wc -l
# Expected output: 0 (any non‑zero indicates a logging violation)

Failure modes and design‑change triggers

Transient throttling (error 20429): If Twilio returns “Too Many Requests”, the wrapper should:

• Respect the Retry-After header if present.
• Apply exponential back‑off (starting at 500 ms, max 8 s) before retrying the send.
• After three consecutive throttles, optionally offer a fallback OTP channel (e.g., email‑based TOTP) to the user.

Pricing or regional availability change: A significant shift in Twilio’s SMS pricing or withdrawal of service from a region would prompt a review of the vendor abstraction layer. The wrapper could be extended to support an alternate provider (e.g., Authy, Nexmo) behind a common interface without changing the caller contract.

Data‑residency regulation: If a new law requires verification records to stay within a specific jurisdiction, the current design would need to:

1. Deploy a Twilio Verify Service instance in the allowed region (Twilio supports regional Services).
2. Store the hashed SID in a data store that complies with the residency rule (e.g., a regional Redis cluster or a cloud‑SQL instance).
3. Ensure the secret manager used for Twilio credentials is also region‑locked.

Only when such a regulatory shift occurs would the wrapper’s storage layer be changed; the API contract (POST /verify and POST /check) remains stable.

Verification checklist (staging)

1. Create a Twilio Verify Service in the Twilio Console (or via CLI) and note the SERVICE_SID.
2. Configure the wrapper’s environment variables to point to the secret manager entries for Account SID, Auth Token, and the Service SID.
3. Deploy the wrapper to a staging namespace (e.g., a Kubernetes dev cluster or AWS Lambda staging alias).
4. Using a test phone number approved in the Twilio Verify sandbox, send a request to POST /verify with a known idempotency key.
5. Confirm the response is 202 Accepted and that the logs contain no verification code or raw phone number (run the grep check above).
6. Retrieve the code from the Twilio sandbox UI, submit it to POST /check, and verify a 200 OK with body { "approved": true }.
7. Monitor the metrics endpoints for send latency, check latency, and error counters; ensure they stay within the targets defined above.

If any step fails, adjust the wrapper’s secret retrieval, idempotency handling, or logging filters before promoting to production.