Authentication

RankHub uses a custom JWT-based authentication system. This page describes the token format, cookie handling, and auth flow.

Token Format

Authentication tokens are JSON Web Tokens (JWT) signed with HMAC-SHA256 using a server-side secret (JWT_SECRET).

JWT Payload

{
  "sub": "user-uuid",
  "email": "user@example.com",
  "role": "user",
  "iat": 1700000000,
  "exp": 1700086400
}

Field	Description
sub	User UUID (primary identifier)
email	User email address
role	User role: user, admin
iat	Issued at (Unix timestamp)
exp	Expiration (Unix timestamp, typically 24 hours)

Token Delivery

Tokens are delivered via httpOnly cookies to prevent XSS access:

• Cookie name: auth
• Flags: httpOnly, secure (in production), sameSite=Lax
• Path: /

For API usage (non-browser clients), the token can also be sent via the Authorization: Bearer <token> header.

Authentication Flow

Email/Password

1. POST /api/v1/auth/signup -- Creates account with hashed password. Returns auth cookie.
2. POST /api/v1/auth/signin -- Validates credentials. Returns auth cookie.
3. POST /api/v1/auth/signout -- Clears auth cookie.

OAuth (GitHub / Google)

1. GET /api/v1/auth/github or GET /api/v1/auth/google -- Returns 302 redirect to OAuth provider.
2. Provider redirects back to /api/v1/auth/:provider/callback with authorization code.
3. Server exchanges code for user info, creates or links account, sets auth cookie.

Email Verification

1. POST /api/v1/auth/send-verification -- Sends verification email (requires valid session).
2. POST /api/v1/auth/verify-email -- Verifies the email token (JSON body: { token: string }).

Password Reset

1. POST /api/v1/auth/forgot-password -- Sends reset email to registered address.
2. POST /api/v1/auth/reset-password -- Sets new password using the reset token.

Rate Limiting

Authentication endpoints have dedicated rate limits. See Rate Limiting for the full breakdown.

Endpoint	Limit
POST /auth/signup	5 per hour
POST /auth/signin	20 per minute
POST /auth/forgot-password	3 per hour

Failed sign-in attempts are tracked per email address and trigger escalating lockouts.