# Auth Architecture

## Goal

One user should authenticate once in `master` and then access other game services without re-login.

For this project, the recommended approach is:

- `master` is the single authentication provider
- user authentication uses JWT access tokens
- game services validate the same user JWT
- internal service-to-service calls use a separate auth mechanism

Do not use one shared secret or one "same key for everything" approach for both users and services.

## Recommended Model

### 1. User authentication

The user authenticates in `master`:

- via Telegram `initData` for TG game/webapp
- or via regular login if needed for admin panel

`master` verifies the user and issues:

- short-lived `access token` JWT
- optionally a `refresh token`

This `access token` is then sent to all game services in:

```http
Authorization: Bearer <access_token>
```

### 2. Validation in other services

Each game service:

- does not log the user in again
- does not store the user's password or Telegram auth secret
- only validates the JWT from `master`

This gives SSO behavior across all games and services.

### 3. Service-to-service authentication

Calls between backend services should use a separate mechanism:

- service JWT
- or HMAC
- or mTLS

Do not rely on a user JWT as the only trust mechanism between services.

## Why This Is Better

- the user logs in once
- all services trust one source of identity
- auth logic stays in one place
- compromised game service should not be able to mint user tokens
- easier role and permission management

## Token Strategy

### Access token

Use a short lifetime:

- `15m` to `30m` for user access token

Include claims like:

- `sub`: user ID
- `role`: `user`, `admin`, `moderator`
- `iss`: issuer, for example `master-auth`
- `aud`: target audience, for example `game-services`
- `exp`
- `iat`

Example payload:

```json
{
  "sub": "123",
  "role": "user",
  "iss": "master-auth",
  "aud": ["game-services"],
  "iat": 1735689600,
  "exp": 1735690500
}
```

### Refresh token

Use if you want silent re-login:

- lifetime `7d` to `30d`
- store server-side or make it revocable

Refresh token should be handled only by `master`.

## Signing Algorithm

Recommended:

- `RS256` or `EdDSA`

Why:

- `master` signs with a private key
- other services verify with a public key
- game services cannot issue tokens even if compromised

Avoid using one shared `HS256` secret across many services if you plan to scale.

## Telegram Login Flow

### Option A. Telegram WebApp / Mini App

Flow:

1. Client gets `initData` from Telegram.
2. Client sends `initData` to `master`.
3. `master` verifies Telegram signature.
4. `master` finds or creates the user.
5. `master` issues JWT access token.
6. Client uses that JWT in all other services.

### Option B. Telegram bot deep-link or custom auth

Same principle:

1. Telegram proves identity to `master`.
2. `master` converts that identity into your internal user.
3. `master` issues your platform JWT.

Telegram should only be the initial identity proof. After that, your platform should use its own JWT.

## Authorization Model

Authentication and authorization should be separated:

- authentication: who the user is
- authorization: what the user can do

Minimum authorization data in JWT:

- user ID
- role

If needed later, add:

- game access list
- scopes
- tenant/project ID

Do not put large mutable permission lists into JWT if they change often.

## How This Fits Current Project

Current state in this repo:

- HTTP API already uses JWT
- gRPC wallet currently uses HMAC metadata

Recommended target state:

- keep JWT for user-facing HTTP and user-facing gRPC
- keep HMAC or service JWT for trusted backend-to-backend calls

That means:

- admin panel and game client use user JWT
- wallet or internal processors may still use HMAC/service auth for internal calls

## Practical Architecture

### Public auth endpoints in `master`

Suggested endpoints:

- `POST /api/auth/telegram`
- `POST /api/auth/refresh`
- `POST /api/auth/logout`
- `GET /api/auth/me`

### Shared verification in services

Every service should have middleware/interceptor that:

- reads `Authorization: Bearer <token>`
- verifies signature
- checks `iss`, `aud`, `exp`
- extracts `sub` and `role`
- places user context into request context

## Recommended Rollout For This Repo

### Stage 1

- keep existing HTTP JWT auth
- add Telegram login endpoint in `master`
- issue JWT after Telegram verification

### Stage 2

- add JWT verification middleware for any external game-facing services
- keep current gRPC HMAC only for internal trusted integrations

### Stage 3

- if wallet becomes user-facing over gRPC, add JWT gRPC interceptor
- optionally keep HMAC/service JWT for internal callers only

## What Not To Do

- do not make each game service perform Telegram login separately
- do not duplicate user auth logic in every service
- do not use one shared secret for both user tokens and service authentication
- do not issue long-lived access tokens without refresh/revocation strategy

## Final Recommendation

Best approach for your case:

- authenticate the player once in `master`
- issue a platform JWT there
- reuse that JWT across all game services
- use separate service authentication for internal backend calls

This is the cleanest and safest SSO model for a TG game ecosystem.