[T2.5a] X handle + follow endpoints (verify-x-handle, confirm-x-handle, x-follow-click)

[realproject7]

Epic: #1229 · Spec: §3.2, §3.3, §6.3 · Type: CODE · Estimate: 0.7 day · Depends on: T2.3 + T2.4a

Scope

Three new endpoints, all use lib/airdrop/siwe-verify.ts for auth. All accept { message, signature, ... } in body.

1. POST /api/airdrop/verify-x-handle

Body: { message, signature, username }
Action: Calls lookupXUser(username) → returns { display_name, avatar_url, follower_count, x_user_id, bio_snippet } for client to display in confirmation card. Does NOT persist to pl_activations.

2. POST /api/airdrop/confirm-x-handle

Body: { message, signature, username }
Action:

• Verifies SIWE → recovers address
• Server re-looks-up the username via lookupXUser (does NOT trust client-supplied x_user_id — RE1 Critical 2 fix)
• Derives x_user_id server-side from the fresh lookup
• UPSERTs pl_activations row with address + x_handle (lower-cased) + x_user_id + x_handle_confirmed_at = NOW()
• UNIQUE INDEX on LOWER(x_handle) WHERE confirmed catches 409 conflicts → return 409
• Also generates pl_referral_codes entry on first call per address if not exists
• Twitterapi.io outage path (R16): if lookupXUser throws, write x_handle only with x_handle_confirmed_at = NULL (pending state) — does NOT acquire UNIQUE lock

3. POST /api/airdrop/x-follow-click

Body: { message, signature }
Action:

• Verifies SIWE → recovers address
• Records pl_activations.x_follow_at = NOW()
• Sets activated_at = NOW() if SIWE + handle confirmed + this click together complete activation

Acceptance

• All 3 endpoints reject expired/invalid signatures with 401
• verify-x-handle returns lookup data without persisting
• confirm-x-handle server-side re-lookup verified (test by sending bogus x_user_id in body — server ignores it)
• UNIQUE conflict returns 409
• R16 graceful degrade: twitterapi.io down → pending row written without UNIQUE lock
• x-follow-click updates x_follow_at + sets activated_at when all 3 conditions met

Dependencies

T2.3 (lookupXUser), T2.4a (siwe-verify)

[realproject7]

Completed by PR #1280.