nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Document Telegram first-class auth

Browse Source
This commit is contained in:
Siavash Sameni
2026-05-24 16:12:46 +04:00
parent 7651d69811
commit fa7234cbe1
9 changed files with 457 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
04 - Flows/Authentication Flow.md
View File

@@ -95,10 +95,27 @@ sequenceDiagram
| Method | Endpoint | Source |
|---|---|---|
| `POST` | `/api/auth/login` | `backend/src/services/auth/authRoutes.ts:22` → `authController.login` |
| `POST` | `/api/auth/telegram` | `authRoutes.ts` → `authController.telegramAuth` |
| `POST` | `/api/auth/refresh-token` | `authRoutes.ts:24-27` → `authController.refreshToken` |
| `POST` | `/api/auth/logout` | `authRoutes.ts:68` → `authController.logout` (protected) |
| `GET` | `/api/auth/profile` | `authRoutes.ts:69` → `authController.getProfile` |
## Telegram first-class auth flow
Telegram is now a peer auth provider alongside email/password, Google, and passkeys.
1. The Telegram Mini App shell reads raw signed launch data from `window.Telegram.WebApp.initData`; browser login can submit a Telegram Login Widget payload.
2. The frontend posts the raw signed payload to `POST /api/auth/telegram`; it never trusts `initDataUnsafe` for authentication.
3. Backend verifies the Telegram signature:
- Mini App uses `verifyMiniAppInitData()` with the Telegram WebAppData HMAC algorithm.
- Login Widget uses `verifyTelegramLoginWidget()` with the Telegram Login Widget HMAC algorithm.
4. Backend rejects stale `auth_date`, bot accounts, replayed Mini App `initData`, and blocked `TelegramLink` records.
5. If an active `TelegramLink` exists, backend signs in that Amanat user. If no link exists, backend creates a Telegram-only user with nullable email, `authProvider: "telegram"`, `telegramVerified: true`, then creates the link.
6. Backend issues the standard access token and refresh token pair. The frontend stores them in `localStorage` under `accessToken` and `refreshToken`, then hydrates the current session.
7. If `isNewUser=true`, the Mini App opens a lightweight onboarding overlay and points the user to account settings for optional email, language, currency, and wallet details.
High-risk actions are unchanged: escrow release, refund, dispute-sensitive, and wallet-sensitive operations still use the existing protected backend authorization and step-up gates. Telegram auth only establishes the user session.
## Database writes
- **`users` collection**: `lastLoginAt` updated; `refreshTokens` array gains one entry per successful login or refresh.