User Login

Interface Information

• Endpoint: /api/auth/login
• Method: POST
• Content-Type: application/json
• Authentication Required: No

Request Parameters

Request Body

Parameter	Type	Required	Description
username	string	Yes	Username (minimum 3 characters)
password	string	Yes	Password (minimum 6 characters)
verifyToken	string	No	Slider verification token
verifyData	object	No	Slider verification data

verifyData Object

Parameter	Type	Required	Description
trackData	string	No	Slider track data
slideTime	number	No	Sliding time (milliseconds)
accuracy	number	No	Sliding accuracy

Request Examples

Basic Login

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456"
  }'

Login with Slider Verification

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "123456",
    "verifyToken": "abc123",
    "verifyData": {
      "trackData": "[[10,20,100],[30,40,200]]",
      "slideTime": 1500,
      "accuracy": 0.95
    }
  }'

Response Examples

Success Response

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@demo.com",
      "nickname": "Demo Administrator",
      "avatar": null,
      "bio": null,
      "role": "admin",
      "status": "active",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    },
    "rateLimitInfo": {
      "remaining": 4,
      "resetTime": "2025-01-24T12:30:00.000Z"
    }
  }
}

Error Responses

Parameter Validation Failed

{
  "success": false,
  "message": "Username and password cannot be empty"
}

Login Failed

{
  "success": false,
  "message": "Incorrect username or password"
}

Too Many Requests

{
  "success": false,
  "message": "Too many attempts for this account, please try again later"
}

Slider Verification Failed

{
  "success": false,
  "message": "Slider verification failed, please try again"
}

Security Mechanisms

1. Rate Limiting

The system implements multi-level rate limiting mechanisms:

• IP Level Limit: Default 5 attempts per 15 minutes
• Username Level Limit: Default 3 attempts per 15 minutes
• Strict Mode: 3 attempts per 10 minutes without verification code

2. Slider Verification

When rate limiting is triggered, slider verification is required:

• Slider verification token
• Slider track data
• Sliding time
• Sliding accuracy

Successful verification resets the rate limiting counters.

3. IP Detection

The system detects the client's real IP with the following priority:

1. X-Forwarded-For header (proxy servers)
2. X-Real-IP header
3. CF-Connecting-IP header (Cloudflare)
4. Socket remote address

Cookie Settings

After successful login, the backend sets the following cookie:

Set-Cookie: auth_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; Path=/; Max-Age=604800; SameSite=Strict; HttpOnly

• Name: auth_token
• Value: JWT Token
• Path: /
• Expiration: 7 days (configurable via JWT_EXPIRES_IN)
• SameSite: Strict (prevents CSRF)
• HttpOnly: HTTP only transmission (prevents XSS)

JWT Token Structure

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "userId": 1,
    "username": "admin",
    "role": "admin",
    "iat": 1737705600,
    "exp": 1738310400
  }
}

Usage Scenarios

1. Normal Login

Direct login with username and password, suitable for regular users.

2. Login with Verification

When rate limiting is triggered, the frontend should require users to complete slider verification.

3. Frontend Integration Example

// Using fetch
async function login(username, password, verifyData = null) {
  const body = {
    username,
    password
  }
  
  if (verifyData) {
    body.verifyToken = verifyData.token
    body.verifyData = {
      trackData: verifyData.trackData,
      slideTime: verifyData.slideTime,
      accuracy: verifyData.accuracy
    }
  }
  
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify(body)
  })
  
  const result = await response.json()
  
  if (!result.success) {
    // Handle error
    throw new Error(result.message)
  }
  
  // Login successful
  return result.data.user
}

Notes

1. Password Security: Passwords are not encrypted on the frontend, use HTTPS for transmission
2. Token Storage: Tokens are stored in HttpOnly cookies, no manual frontend storage required
3. Rate Limiting: Frontend should display remaining attempts based on rateLimitInfo
4. Verification Code: Slider verification is optional, required when high frequency is detected
5. IP Recording: The system records login IPs for security analysis

Related Interfaces

• Logout
• Get Current User
• Forgot Password