Document Telegram first-class auth

PRD - Telegram Phone Number Authentication.md

@@ -0,0 +1,67 @@
+# PRD: Telegram Phone Number Authentication
+
+> Source spec: `.taskmaster/docs/prd-telegram-phone-auth.md`
+> Related task: **Task 5.10** — Implement Telegram as first-class authentication provider
+
+---
+
+## Problem
+
+The current Telegram integration is a *secondary linking layer*: users must already have an Amanat email/password or Google account before they can connect Telegram. This breaks the natural Telegram Mini App user journey — someone who opens the Mini App from Telegram has already proven phone ownership to Telegram and reasonably expects to be authenticated with zero extra signup friction.
+
+## Core idea
+
+Telegram accounts are phone-number-verified. When the backend verifies `initData` from the Mini App (already implemented), it has cryptographic proof that the requester controls a specific Telegram identity. That proof is sufficient to create and sign in to an Amanat account — no email, no password required.
+
+The same principle applies to the **Telegram Login Widget**, the standard web-based flow that lets users authenticate on any browser page by confirming from their Telegram app.
+
+## Two auth paths covered
+
+| Context | Mechanism | Already have? |
+|---|---|---|
+| Inside Telegram Mini App | `initData` HMAC-SHA-256 (already verified server-side) | Partial — used for linking only |
+| Any browser (web login page) | Telegram Login Widget → signed callback | Missing |
+
+Both paths converge at a new `POST /auth/telegram` endpoint that: verifies the signature → looks up or creates the Amanat user → issues a JWT session.
+
+## New user provisioning
+
+When a Telegram user arrives with no existing account:
+
+- Account is auto-created (`authProvider: telegram`, `telegramVerified: true`)
+- No email required — email column becomes nullable (`sparse` unique index)
+- Name pre-filled from Telegram profile
+- Role defaults to `buyer`; user can change
+- A non-blocking onboarding screen offers (but does not require) email capture and preference setup
+
+## What does NOT change
+
+- Existing email/password and Google OAuth users are unaffected
+- High-risk actions (release, refund, dispute resolution) still require step-up confirmation regardless of auth provider
+- Telegram is not made the *only* auth method — it becomes an equal alternative
+- Raw phone number is never exposed to Amanat; Telegram user ID is the stable identity anchor
+
+## Key acceptance criteria
+
+1. New Telegram user completes auth inside Mini App without entering email or password.
+2. Returning Telegram user gets the same session whether using Mini App or web Login Widget.
+3. Replay protection and max-age validation apply to this endpoint.
+4. Blocked Telegram accounts receive 403 and cannot circumvent by re-linking.
+5. Auto-provisioned users have `authProvider: telegram`; existing users are unaffected.
+6. "Continue with Telegram" button visible on the web login page.
+7. High-risk action step-up policy is unchanged.
+
+## Collision and merge rules
+
+| Scenario | Behavior |
+|---|---|
+| New Telegram user | Auto-provision + TelegramLink |
+| Returning Telegram user | Auth as linked user |
+| Email user opens Mini App (not yet linked) | Prompt to link (existing task 5.2 flow) |
+| Same Telegram account on two app users | Rejected — TelegramLink.telegramUserId is unique |
+
+## See also
+
+- `.taskmaster/docs/prd-telegram-phone-auth.md` — full specification with endpoint contract, model changes, and frontend integration details
+- `PRD - Platform Audit Remediation Plan (2026-05-24).md` — security baseline this feature must not weaken
+- Task 5.2 (Identity linking), Task 5.8 (Security controls)