changes
This commit is contained in:
sdarbinyan
327
TELEGRAM_USERAUTH_BACKEND.md
Normal file
327
TELEGRAM_USERAUTH_BACKEND.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# Telegram UserAuth Backend Contract
|
||||
|
||||
This document extracts the existing Telegram login flow into a repo-neutral contract for reuse in other projects.
|
||||
|
||||
The UI behavior, payloads, polling cadence, and session model stay the same. Only route names and cookie naming are generalized.
|
||||
|
||||
## Endpoint Renaming
|
||||
|
||||
| Current app contract | Reusable contract |
|
||||
|---|---|
|
||||
| `GET /auth/session` | `GET /userauth/session` |
|
||||
| `POST /auth/qr/create` | `POST /userauth/qr/create` |
|
||||
| `GET /auth/qr/poll?token=...` | `GET /userauth/qr/poll?token=...` |
|
||||
| `POST /auth/qr/confirm` | `POST /userauth/qr/confirm` |
|
||||
| `GET /auth/telegram/callback` | `GET /userauth/telegram/callback` |
|
||||
| `POST /auth/logout` | `POST /userauth/logout` |
|
||||
| `POST /websession/{sessionId}` | `POST /usersession/{sessionId}` |
|
||||
| Cookie `dx_session` | Cookie `userauth_session` |
|
||||
|
||||
## Flow Summary
|
||||
|
||||
There are two supported flows.
|
||||
|
||||
### 1. Direct login from button
|
||||
|
||||
1. Frontend opens `https://t.me/{botUsername}?start=auth_{callbackUrl}`.
|
||||
2. Telegram bot creates a session and sends the user a login button.
|
||||
3. The button points to `GET /userauth/telegram/callback?token={sessionId}`.
|
||||
4. Backend sets `userauth_session` cookie and redirects back to the storefront.
|
||||
5. Frontend calls `GET /userauth/session` and becomes authenticated.
|
||||
|
||||
### 2. QR login from desktop
|
||||
|
||||
1. Frontend opens dialog.
|
||||
2. Frontend calls `POST /userauth/qr/create`.
|
||||
3. Backend returns `{ token, url }` where `url` is a Telegram deep link.
|
||||
4. Frontend renders a QR from that URL.
|
||||
5. User scans QR and bot calls `POST /userauth/qr/confirm`.
|
||||
6. Frontend polls `GET /userauth/qr/poll?token=...` every 3 seconds.
|
||||
7. When status becomes `confirmed`, backend returns session payload and sets the cookie.
|
||||
8. Frontend syncs local cart using `POST /usersession/{sessionId}`.
|
||||
|
||||
## Session Shape
|
||||
|
||||
The frontend expects this exact response shape for the authenticated session.
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"telegramUserId": 123456789,
|
||||
"username": "ivan_petrov",
|
||||
"displayName": "Ivan Petrov",
|
||||
"active": true,
|
||||
"expiresAt": "2026-05-21T14:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|---|---|---|---|
|
||||
| `sessionId` | string | yes | Session identifier used in cart sync |
|
||||
| `telegramUserId` | number | yes | Telegram user ID |
|
||||
| `username` | string or null | no | Telegram username |
|
||||
| `displayName` | string | yes | User-facing full name |
|
||||
| `active` | boolean | yes | `false` means expired session |
|
||||
| `expiresAt` | ISO 8601 string | yes | Used by frontend refresh scheduling |
|
||||
|
||||
Recommended TTL:
|
||||
|
||||
- Session TTL: 24 hours
|
||||
- QR token TTL: 5 minutes
|
||||
|
||||
## HTTP Contract
|
||||
|
||||
### `POST /userauth/qr/create`
|
||||
|
||||
Creates a one-time QR login token when the dialog opens.
|
||||
|
||||
Request body:
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
Response `200`:
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "dG9rZW4tYWJjMTIz",
|
||||
"url": "https://t.me/userauth_bot?start=login_dG9rZW4tYWJjMTIz"
|
||||
}
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
- Generate a cryptographically secure token.
|
||||
- Save token with status `pending`.
|
||||
- Return a Telegram deep link in `url`.
|
||||
- Rate limit to 5 requests per minute per IP.
|
||||
|
||||
### `GET /userauth/qr/poll?token={token}`
|
||||
|
||||
Called every 3 seconds until confirmation or expiration.
|
||||
|
||||
Possible responses:
|
||||
|
||||
Pending:
|
||||
|
||||
```json
|
||||
{ "status": "pending" }
|
||||
```
|
||||
|
||||
Confirmed:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "confirmed",
|
||||
"session": {
|
||||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"telegramUserId": 123456789,
|
||||
"username": "ivan_petrov",
|
||||
"displayName": "Ivan Petrov",
|
||||
"active": true,
|
||||
"expiresAt": "2026-05-21T14:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Expired:
|
||||
|
||||
```json
|
||||
{ "status": "expired" }
|
||||
```
|
||||
|
||||
Behavior:
|
||||
|
||||
- If confirmed, set cookie `userauth_session` in the response.
|
||||
- Delete or invalidate the QR token after the first successful confirmed poll.
|
||||
- If token is unknown or expired, return `status: "expired"`.
|
||||
|
||||
### `POST /userauth/qr/confirm`
|
||||
|
||||
Internal endpoint called by the Telegram bot after the user scans the QR code.
|
||||
|
||||
Required header:
|
||||
|
||||
```text
|
||||
X-Bot-Secret: <shared secret between bot and backend>
|
||||
```
|
||||
|
||||
Request body:
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "dG9rZW4tYWJjMTIz",
|
||||
"telegram_user": {
|
||||
"id": 123456789,
|
||||
"first_name": "Ivan",
|
||||
"last_name": "Petrov",
|
||||
"username": "ivan_petrov"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response `200`:
|
||||
|
||||
```json
|
||||
{ "status": "ok" }
|
||||
```
|
||||
|
||||
Behavior:
|
||||
|
||||
- Validate `X-Bot-Secret`.
|
||||
- Validate token exists and is still `pending`.
|
||||
- Create a user session.
|
||||
- Store session ID on the QR token.
|
||||
- Mark QR token as `confirmed`.
|
||||
|
||||
### `GET /userauth/session`
|
||||
|
||||
Returns the currently active session based on the cookie.
|
||||
|
||||
Frontend behavior depends on this endpoint in two places:
|
||||
|
||||
- initial auth check on app startup
|
||||
- fallback polling if QR token creation fails
|
||||
|
||||
Response `200`:
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"telegramUserId": 123456789,
|
||||
"username": "ivan_petrov",
|
||||
"displayName": "Ivan Petrov",
|
||||
"active": true,
|
||||
"expiresAt": "2026-05-21T14:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Error handling:
|
||||
|
||||
- Any non-200 response is treated by the frontend as unauthenticated.
|
||||
|
||||
### `GET /userauth/telegram/callback?token={sessionId}`
|
||||
|
||||
Used for direct Telegram login from the primary button flow.
|
||||
|
||||
Behavior:
|
||||
|
||||
- Read the `token` query param.
|
||||
- Resolve it to a valid active session.
|
||||
- Set cookie `userauth_session`.
|
||||
- Redirect user to the storefront URL.
|
||||
|
||||
### `POST /userauth/logout`
|
||||
|
||||
Clears the backend session and expires the cookie.
|
||||
|
||||
Request body:
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
Response `200`:
|
||||
|
||||
```json
|
||||
{ "message": "ok" }
|
||||
```
|
||||
|
||||
### `POST /usersession/{sessionId}`
|
||||
|
||||
Synchronizes local cart immediately after successful login.
|
||||
|
||||
Request body:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"itemID": 123,
|
||||
"quantity": 2,
|
||||
"colour": "#ff0000",
|
||||
"size": "XL",
|
||||
"price": 1500
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- This payload is unchanged from the existing implementation.
|
||||
- `price` is already discounted on the frontend side.
|
||||
- The frontend skips the call if cart is empty.
|
||||
|
||||
## Telegram Deep Link Format
|
||||
|
||||
Direct login link format:
|
||||
|
||||
```text
|
||||
https://t.me/{botUsername}?start=auth_{urlEncodedCallbackUrl}
|
||||
```
|
||||
|
||||
QR login link format:
|
||||
|
||||
```text
|
||||
https://t.me/{botUsername}?start=login_{qrToken}
|
||||
```
|
||||
|
||||
Important limit:
|
||||
|
||||
- Telegram limits the `start` payload to 64 characters.
|
||||
- A base64url encoding of 32 random bytes plus `login_` fits safely.
|
||||
|
||||
## Cookie Requirements
|
||||
|
||||
Use these cookie settings for the frontend to work correctly across site and API origins.
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| Name | `userauth_session` |
|
||||
| Path | `/` |
|
||||
| HttpOnly | `true` |
|
||||
| Secure | `true` |
|
||||
| SameSite | `None` |
|
||||
| MaxAge | `86400` |
|
||||
| Domain | your shared parent domain, for example `.example.com` |
|
||||
|
||||
## CORS Requirements
|
||||
|
||||
Because the frontend sends credentials, backend must return an explicit origin.
|
||||
|
||||
Required headers:
|
||||
|
||||
```text
|
||||
Access-Control-Allow-Origin: https://your-frontend.example
|
||||
Access-Control-Allow-Credentials: true
|
||||
Access-Control-Allow-Methods: GET, POST, OPTIONS
|
||||
Access-Control-Allow-Headers: Content-Type
|
||||
```
|
||||
|
||||
Do not use `*` for `Access-Control-Allow-Origin` together with credentials.
|
||||
|
||||
## Frontend Runtime Expectations
|
||||
|
||||
The current dialog behavior is fixed and should be preserved by backend responses.
|
||||
|
||||
- QR polling interval: every 3 seconds
|
||||
- QR expiration on frontend: after 100 checks
|
||||
- If QR creation fails, frontend falls back to direct login URL and session polling
|
||||
- After login, frontend closes the dialog and re-checks session
|
||||
|
||||
## Minimal Backend Checklist
|
||||
|
||||
- Implement all six `userauth` endpoints and the `usersession` sync endpoint.
|
||||
- Store sessions for 24 hours.
|
||||
- Store QR tokens for 5 minutes.
|
||||
- Protect `POST /userauth/qr/confirm` with `X-Bot-Secret`.
|
||||
- Set `userauth_session` cookie on confirmed QR poll and direct callback.
|
||||
- Return the exact session JSON shape.
|
||||
- Support credentialed CORS.
|
||||
|
||||
## Bot Checklist
|
||||
|
||||
- Handle `/start login_{token}` and call `POST /userauth/qr/confirm`.
|
||||
- Handle `/start auth_{callbackUrl}` and provide a button that opens the callback URL.
|
||||
- Send success and expiration messages back to the user.
|
||||
- Share the same `X-Bot-Secret` value with backend.
|
||||
Reference in New Issue
Block a user