Login Workflow

This document describes the current login workflow implemented by the frontend in src/pages/login.tsx.

Overview

The login page supports multiple sign-in paths:

• SMS one-time code login (default tab)
• Password login (email + password)
• Email one-time code login
• Passkey (WebAuthn) login
• Third-party sign-in entry points (WeChat/GitHub)
• Register / Activate / Forgot password / Reset password flows

Core backend session model:

• Server sets session cookie cjj365
• Frontend refreshes auth state via GET /auth/status

1) Password Login

Frontend call:

• POST /auth/general
• body:

{
  "action": "login",
  "email": "user@example.com",
  "password": "...",
  "next": "/target(optional)"
}

Behavior:

1. Backend validates credentials and sets cookie.
2. Frontend forces checkAuthStatus({ force: true }).
3. Frontend redirects to next (or dashboard default).

2) SMS Login (Default)

SMS login is a two-step flow with human challenge.

Step A: Request code

1. Get challenge:
   • GET /auth/human-challenge
2. Solve challenge client-side (PoW SHA-256).
3. Request SMS code:
   • POST /auth/general

{
  "action": "sms-login",
  "phone_number": "+8613800138000",
  "next": "/target(optional)",
  "human_challenge_salt": "...",
  "human_challenge_sig": "...",
  "human_challenge_nonce": "...",
  "human_challenge_expires_at": 1710000000
}

Step B: Verify code

POST /auth/general

{
  "action": "sms-login",
  "phone_number": "+8613800138000",
  "verify_code": "123456",
  "next": "/target(optional)"
}

Behavior after verify success:

1. If the phone number already belongs to an existing account:

• Backend sets cookie.
• Frontend refreshes /auth/status.
• Continue normal redirect.

2. If the phone number does not belong to any existing account:

• Backend does not create a user yet.
• Backend returns status=PhoneResolutionRequired with a short-lived bind_session_id.
• Frontend shows an explicit choice:
  • bind an existing email account
  • create a new account

3. Only after one of those explicit follow-up actions succeeds does the backend create/update the user relation and set the login cookie.

3) Email One-Time Code Login

Two-step flow:

1. Request code:
   • POST /auth/general with action: "email-login" and email
2. Verify code:
   • POST /auth/general with action: "email-login", email, verify_code

On success, backend sets cookie and frontend refreshes /auth/status.

4) Register / Activate

Register

POST /auth/general

{
  "action": "register",
  "email": "user@example.com",
  "password": "StrongPassword123",
  "name": "username",
  "country_of_residence": "CN"
}

Notes:

• Username availability is checked via GET /auth/general?name=....
• Password policy is validated in frontend and backend.

Activate

POST /auth/general

{
  "action": "activate-user",
  "email": "user@example.com",
  "verify_code": "123456"
}

Behavior:

• If backend auto-signs-in after activation, frontend will detect it via /auth/status and redirect.
• Otherwise frontend falls back to login view.

5) Forgot / Reset Password

Request reset code

POST /auth/general

{
  "action": "request-reset-password",
  "email": "user@example.com"
}

Reset password

POST /auth/general

{
  "action": "reset-password",
  "email": "user@example.com",
  "verify_code": "123456",
  "new_password": "NewStrongPassword123"
}

After success, frontend returns to login mode and shows reset success message.

6) Passkey (WebAuthn) Login

Flow:

1. Fetch options:
   • POST /auth/webauthn/login/options
2. Browser navigator.credentials.get(...)
3. Verify assertion:
   • POST /auth/webauthn/login/verify
4. Backend sets cookie, frontend refreshes /auth/status, then redirects.

7) Third-Party Sign-In Entry

Current frontend uses full-page redirect entry points:

• GET /auth/weixin (+ callback)
• GET /auth/github (+ callback)

The callback page finalizes sign-in and returns control to app routes.

8) Redirect Rules

Source of target route:

1. next query param from login page URL
2. server-provided absolute redirect (data.to) when present
3. fallback dashboard route

For SMS onboarding special cases, frontend may override and redirect to profile completion page first.

9) Session Checkpoints

Important checkpoints used by frontend:

• GET /auth/status: authoritative session state
• GET /auth/profile: user profile data
• POST /auth/logout: clear current session

10) Source of Truth in Code

If this document drifts, validate against:

• src/pages/login.tsx
• src/components/AuthForm/index.tsx
• src/utils/api.ts
• src/types/auth.ts