Verify phones with WhatsApp

Integrate HiVouch WhatsApp phone verification into this codebase.

## What HiVouch does
HiVouch verifies a phone number by having the user SEND a WhatsApp message (reverse OTP). My backend creates a verification; HiVouch returns a one-time code inside a prefilled WhatsApp message. The user taps a button (or scans a QR code), WhatsApp opens with the message typed, they press send, and HiVouch marks the verification as verified. No code is typed back into my app.
Full docs: https://hivouch.com/docs

## Before writing code
1. Read the project and tell me which backend framework, frontend framework and auth/session system it uses, and where phone verification belongs (sign-up, login, or adding a phone to an account).
2. Propose the files you will add or change and wait for my OK.

## API (base https://api.hivouch.com/v1, JSON, Bearer auth)
- Secret key: env var HIVOUCH_SECRET_KEY (sk_test_... or sk_live_...). Backend only. Never send it to the browser or mobile app, never commit it. Add it to the project's env example file with an empty value.
- Webhook signing secret: env var HIVOUCH_WEBHOOK_SECRET (whsec_...).
- POST /verifications  body: {"phone": "+E164", "purpose": "login"|"signup"|"verify", "locale": "en"|"ar", "expires_in": 60-900 (default 300), "metadata": {"user_id": "..."}}. Send an "Idempotency-Key" header (a new UUID per attempt).
  Response 201: id, status ("pending"), hivouch_number, token_display, greeting, wa_link, client_secret, expires_at, metadata, livemode.
  purpose sets the wording the user sees in WhatsApp and on the page: "login" (default) says they are signing in, "signup" says they are signing up, "verify" says they verified their number. Use "signup" for creating an account (leave out phone for identify mode: the sender's number becomes the account), "verify" for checkout or a phone the user already gave you, "login" for signing in.
  Omitting phone creates an "identify" verification (if identify is on in project settings): whoever sends the message is identified, and verified_phone tells you the number. If the sender's WhatsApp username hides their phone, purpose "login" or "signup" still verifies with verified_phone null and whatsapp_user_id set; purpose "verify" and confirm mode cannot complete without the phone.
- GET /verifications/{id}  returns the verification. While pending it still includes wa_link, greeting and token_display; after that they are null. When verified: verified_phone (null when a WhatsApp username hides it), whatsapp_user_id, whatsapp_username (null if they have none), verified_at. Identify users by whatsapp_user_id or verified_phone only; whatsapp_username is for display and as a matching hint, because it can change and an old name can later belong to someone else.
- POST /verifications/{id}/cancel  cancels a pending verification.
- Errors: {"error": {"type", "code", "message", "param"}} with HTTP 400/401/402/403/404/409/429. Show the message to developers in logs, and a friendly message to users. On 429 respect the Retry-After header.

## Statuses
  - pending: Waiting for the user to send the WhatsApp message. Show the button, QR code and countdown.
  - verified: The right number sent the code. Confirm on your backend, then sign the user in.
  - mismatch: A different WhatsApp number sent the code. Ask the user to check the number and start again.
  - expired: Nothing arrived before expires_at. Offer to start again.
  - canceled: You canceled it with POST /v1/verifications/{id}/cancel.
  - disputed: The phone owner replied NO after a verification. Treat the sign-in as not trusted; the charge is refunded.

## Build it like this
1. Backend endpoint "start verification": validate the phone as E.164, call POST /verifications with metadata.user_id (or the pending sign-up id), store the verification id against the user/session, and return to the frontend ONLY: id, wa_link, greeting, token_display, hivouch_number, expires_at. Never return the secret key.
2. Frontend screen:
   - Mobile: a primary "Verify with WhatsApp" button linking to wa_link.
   - Desktop: a QR code of wa_link (use a small QR library), plus the same button.
   - Fallback text: "Send <greeting> to <hivouch_number> on WhatsApp", with a copy button.
   - A countdown to expires_at, and a "Start again" action that creates a new verification.
   - Use the greeting and wa_link exactly as returned. Never build, change or generate the code yourself: HiVouch issues it and ties it to this one verification.
3. Wait for the result, both ways:
   - Webhook: POST endpoint that reads the RAW body, verifies the HiVouch-Signature header (format "t=<unix>,v1=<hex>", v1 = HMAC-SHA256(HIVOUCH_WEBHOOK_SECRET, "<t>.<raw body>"), constant-time compare, reject if t is older than 300 seconds), deduplicates by event id, and handles verification.verified, verification.mismatch, verification.expired, verification.canceled, verification.disputed. Return 2xx within 10 seconds.
   - Polling fallback: the frontend asks MY backend for the status every 2 seconds while the screen is open (and again when the tab becomes visible, because the user comes back from WhatsApp); my backend calls GET /verifications/{id}.
4. Complete: only my backend decides. When status is "verified", check that the verification id belongs to this user/session and that metadata matches, then use verified_phone from HiVouch (never a phone number sent by the browser) to mark the phone verified or sign the user in. For sign-in or sign-up, if verified_phone is null, find or create the user by whatsapp_user_id instead (store it next to the phone when both are present); never treat a null or empty phone as an identity. Mark the verification id as used so it cannot complete a second session.
5. On "disputed" (the phone owner replied NO), revoke or flag the session or phone that verification created.

## Testing (test keys only, free, no WhatsApp needed)
Use an sk_test_ key and these numbers:
  - +12025550110: verifies right after it is created (the create response still says pending; read it again or wait for the webhook)
  - +12025550111: ends in mismatch, as if a different number sent the message
  - +12025550112: never gets a message and stays pending until it expires
Or create a verification for any number and call POST https://api.hivouch.com/v1/test/verifications/{id}/simulate to make it verify.
Add automated tests that mock the HiVouch HTTP calls for: start, verified, mismatch, expired, a bad webhook signature, a replayed webhook, and a verification id that belongs to another user.

## Done means
- The secret keys are only in env vars and only used server side.
- The flow works end to end with sk_test_ and +12025550110.
- Webhook signatures are checked, and nothing trusts the browser's word that a phone is verified.
- Tell me which env vars to set and where to add the webhook URL (HiVouch dashboard > Developers > Webhooks).