twilio-verify

What this skill does

# twilio-verify

## Purpose

Enable OpenClaw to implement and operate Twilio Verify (V2) in production: SMS/voice/email OTP, TOTP, custom channels, phone verification, Verify Fraud Guard (risk scoring + blocking), and Silent Network Authentication (SNA) where available. This skill focuses on:

- Building a **reliable verification pipeline** (send → check → enforce) with **rate limits**, **fraud controls**, and **observability**.
- Integrating Verify with **Programmable Messaging/Voice**, **SendGrid**, and **webhook-driven** status/telemetry.
- Handling **real Twilio failure modes** (carrier filtering, invalid E.164, auth errors, rate limits) with deterministic remediation.
- Operating at scale: **cost controls**, **regional routing**, **idempotency**, and **abuse prevention**.

---

## Prerequisites

### Accounts & Twilio resources

- Twilio account with:
  - **Account SID** (`AC...`)
  - **Auth Token** (or API Key + Secret)
  - A **Verify Service SID** (`VA...`) created in Twilio Console → Verify → Services
- If using SMS/Voice:
  - A verified **Messaging Service** (recommended) or phone number(s)
  - If US A2P: **10DLC** registration completed for your brand/campaign (or use toll-free/short code as appropriate)
- If using email channel:
  - SendGrid account + verified sender domain, or Twilio Verify Email channel configuration (depending on your setup)
- If using SNA:
  - SNA availability depends on region/carrier and Twilio enablement; confirm in Console and with Twilio support.

### Local tooling (exact versions)

- Node.js **20.11.1** (LTS) or **18.19.1** (LTS)
- Python **3.12.2** (if using Python examples)
- Twilio helper libraries:
  - `twilio` npm package **4.22.0**
  - `twilio` Python package **9.0.5**
- HTTP tooling:
  - `curl` **8.5.0**
  - `jq` **1.7**
- Optional (recommended):
  - `ngrok` **3.13.1** for webhook testing
  - `openssl` **3.0.13** for signature verification utilities

### Auth setup (recommended patterns)

Prefer **API Key** auth over Auth Token for server-side apps.

- Create API Key in Twilio Console → Account → API keys & tokens:
  - API Key SID (`SK...`)
  - API Key Secret (store once)
- Store secrets in a secret manager (AWS Secrets Manager, GCP Secret Manager, Vault). Do not commit to repo.

Environment variables expected by examples:

- `TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- `TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` (if using Auth Token)
- `TWILIO_API_KEY_SID=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- `TWILIO_API_KEY_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- `TWILIO_VERIFY_SERVICE_SID=VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

---

## Core Concepts

### Verify Service

A Verify Service (`VA...`) is the policy boundary for:

- Channels enabled (sms, call, email, whatsapp, push, custom)
- Code length, locale templates, TTL, rate limits
- Fraud Guard configuration (risk thresholds, blocking)
- Webhooks (status callbacks, events)

Treat a Verify Service as an environment-scoped resource:
- `VA_prod...` for production
- `VA_staging...` for staging
- Separate services for different products/tenants only if policy differs materially.

### Verification vs Verification Check

- **Verification**: sending a challenge (OTP) to a destination (phone/email) via a channel.
- **Verification Check**: validating the user-provided code (or other factor) against the verification attempt.

Your application should:
1. Create verification (send)
2. Accept user input
3. Create verification check (verify)
4. Enforce outcome (issue session token, mark phone verified, etc.)

### Channels

Common channels:
- `sms`: OTP via SMS
- `call`: OTP via voice call (TwiML-driven by Twilio)
- `email`: OTP via email (Verify email channel or custom)
- `totp`: time-based one-time password (app-based)
- `whatsapp`: WhatsApp OTP (requires WhatsApp enablement)
- `custom`: your own delivery mechanism (push, in-app, etc.)

Channel selection should be policy-driven:
- Default to `sms`
- Offer `call` fallback for deliverability
- Offer `email` for account recovery or when phone is unavailable
- Offer `totp` for high-assurance accounts

### E.164 normalization

Twilio expects phone numbers in **E.164** format: `+14155552671`.

Do not accept raw user input directly. Normalize and validate:
- Use libphonenumber (Node: `google-libphonenumber` or `libphonenumber-js`)
- Store canonical E.164 in DB
- Reject ambiguous numbers early

### Rate limiting & abuse controls

Verify has built-in rate limiting, but you should also implement:
- Per-IP and per-identity throttles (Redis token bucket)
- Device fingerprinting / risk scoring
- Cooldowns after failed attempts
- CAPTCHA gating for suspicious traffic

### Fraud Guard (Verify Fraud Guard)

Fraud Guard helps detect:
- SIM swap risk
- High-risk destinations
- Traffic anomalies

Integrate Fraud Guard decisions into your auth flow:
- Block high-risk verifications
- Step-up to stronger factor (TOTP) if medium risk
- Log risk signals for incident response

### Webhooks & eventing

Use webhooks for:
- Verification status events
- Delivery outcomes (for messaging/voice)
- Audit trails and analytics

Design webhooks as:
- Idempotent (dedupe by event SID)
- Authenticated (Twilio signature validation)
- Retry-safe (Twilio retries on non-2xx)

### Silent Network Authentication (SNA)

SNA verifies a user’s phone number via carrier network signals without OTP entry (where supported). Treat it as:
- A **step-up** or **frictionless** verification path
- Not universally available; implement fallback to OTP
- Subject to carrier/region constraints and privacy requirements

---

## Installation & Setup

### Official Python SDK — Verify

**Repository:** https://github.com/twilio/twilio-python  
**PyPI:** `pip install twilio` · **Supported:** Python 3.7–3.13

```python
from twilio.rest import Client
client = Client()

SERVICE_SID = os.environ["TWILIO_VERIFY_SERVICE_SID"]

# Start verification (SMS / WhatsApp / email / TOTP)
verification = client.verify.v2.services(SERVICE_SID) \
    .verifications.create(to="+15558675309", channel="sms")
print(verification.status)

# Check code
check = client.verify.v2.services(SERVICE_SID) \
    .verification_checks.create(to="+15558675309", code="123456")
print(check.status)  # "approved" | "pending"
```

Source: [twilio/twilio-python — verify](https://github.com/twilio/twilio-python/blob/main/twilio/rest/verify/)

### Ubuntu 22.04 LTS (x86_64)

```bash
sudo apt-get update
sudo apt-get install -y curl jq ca-certificates gnupg

# Node.js 20.x (NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

node -v   # v20.11.1 (or later 20.x)
npm -v

# Python 3.12 (deadsnakes PPA)
sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install -y python3.12 python3.12-venv python3.12-dev
python3.12 --version
```

### Fedora 39 (x86_64)

```bash
sudo dnf install -y curl jq nodejs python3.12 python3.12-devel
node -v
python3.12 --version
```

### macOS 14 (Sonoma) — Intel & Apple Silicon

```bash
brew update
brew install node@20 [email protected] jq curl openssl@3

# Ensure PATH includes brew Node/Python
node -v
python3.12 --version
```

### Project dependencies (Node.js)

```bash
mkdir -p verify-service && cd verify-service
npm init -y
npm install [email protected] [email protected] [email protected] [email protected]
npm install --save-dev [email protected] [email protected] @types/[email protected]
```

### Project dependencies (Python)

```bash
mkdir -p verify-service-py && cd verify-service-py
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip==24.0
pip install twilio==9.0.5 fastapi==0.109.2 uvicorn==0.27.1 pydantic==2.6.1
```

### Environment configuration

Create a local env file (do not commit):

- Node: `/etc/openclaw/twilio-verify.env` (production) or `./.env` (local)
- Python: same

Example (local):

```bash
cat > ./.env <<'EOF'
TWILIO_ACCOUNT_SID=AC2f7c2c6b2d2f4a1b9a0b3c1d2e3f