Phone Verification Flow

Why this exists

POST /v1/send is blocked until a linked user has phone_verification_status = verified.

Flow

1. Verification session starts automatically after /start <token> or manually via POST /v1/phone-verification/start.
2. Gateway sends Telegram keyboard button with request_contact: true.
3. User shares contact.
4. Gateway validates self-contact (contact.user_id == from.id).
5. Phone is normalized, hashed with pepper, encrypted with AES-GCM, and persisted.
6. Status transitions to verified, session KV key is deleted.

Status values

• unverified: no valid verification.
• pending: verification requested and awaiting contact-share.
• verified: verification complete.

Tenant uniqueness rule

Within one developer_id, a phone hash can only map to one app_user_id.