# 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)
