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

New Telegram user completes auth inside Mini App without entering email or password.
Returning Telegram user gets the same session whether using Mini App or web Login Widget.
Replay protection and max-age validation apply to this endpoint.
Blocked Telegram accounts receive 403 and cannot circumvent by re-linking.
Auto-provisioned users have authProvider: telegram; existing users are unaffected.
"Continue with Telegram" button visible on the web login page.
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

3.5 KiB Raw Blame History