AeThex Passport

Cross-platform identity service for the AeThex ecosystem. Unified authentication, profiles, and gaming platform connections (Roblox, Steam, Discord, Xbox, Epic).

Quick Start

cp .env.example .env       # fill in your values
npm install
npm run migrate            # prints SQL — run it in Supabase SQL Editor
npm run dev                # starts on port 3001

Visit API Docs (Swagger UI) for interactive API testing.

Key Features

• ✅ Email verification for account security
• ✅ JWT-based authentication with refresh tokens
• ✅ Multi-platform gaming account linking (5+ platforms)
• ✅ Audit logging for security events
• ✅ Rate limiting & helmet security headers
• ✅ Complete OpenAPI/Swagger documentation
• ✅ Supabase integration with SQL migrations

Architecture

API Endpoints

Method	Endpoint	Auth	Status	Description
POST	/api/v1/auth/register	—	201	Register new Passport
POST	/api/v1/auth/login	—	200	Login, returns tokens
POST	/api/v1/auth/verify-email	—	200	Verify email with token
POST	/api/v1/auth/refresh	—	200	Refresh access token
POST	/api/v1/auth/logout	✓	204	Logout (discard token)
GET	/api/v1/profile/me	✓	200	Get your full profile + platforms
PUT	/api/v1/profile/me	✓	200	Update profile (displayName, bio)
DELETE	/api/v1/profile/me	✓	204	Delete profile + all platforms
GET	/api/v1/platforms	✓	200	List connected platforms
GET	/api/v1/platforms/:name	✓	200	Get one platform
POST	/api/v1/platforms/connect	✓	201	Connect a gaming platform
DELETE	/api/v1/platforms/:name	✓	204	Disconnect a platform
GET	/api/v1/health	—	200	Health check (Railway ping)

Supported Platforms

roblox, steam, discord, xbox, epic

Authentication Flow

1. Register

POST /api/v1/auth/register
{
  "email": "user@example.com",
  "password": "securePassword123",
  "displayName": "JohnDoe"
}

Returns: user, accessToken, refreshToken, emailVerificationToken

2. Verify Email

POST /api/v1/auth/verify-email
{
  "token": "emailVerificationToken"
}

3. Login

POST /api/v1/auth/login
{
  "email": "user@example.com",
  "password": "securePassword123"
}

Returns: user, accessToken (15m), refreshToken (7d)

4. Use Access Token

GET /api/v1/profile/me
Authorization: Bearer <accessToken>

5. Refresh Token

POST /api/v1/auth/refresh
{
  "refreshToken": "refreshToken"
}

Connecting Gaming Platforms

POST /api/v1/platforms/connect
Authorization: Bearer <accessToken>
{
  "platformName": "roblox",
  "platformUserId": "123456789",
  "verificationToken": "verification_code_from_platform"
}

Database Schema

passport_users

id (TEXT, PRIMARY KEY)
email (TEXT, UNIQUE)
password (TEXT, hashed)
display_name, avatar_url, bio
email_verified (BOOLEAN)
email_verification_token, email_verification_expires_at
password_reset_token, password_reset_expires_at
created_at, updated_at (TIMESTAMPTZ)

passport_platforms

id (SERIAL, PRIMARY KEY)
passport_user_id → passport_users(id)
platform_name (roblox|steam|discord|xbox|epic)
platform_user_id (platform's user ID)
verification_token
connected_at (TIMESTAMPTZ)

passport_audit_logs

id (SERIAL, PRIMARY KEY)
user_id → passport_users(id)
action (login, register, platform_connected, etc)
details (JSONB)
ip_address, user_agent
created_at (TIMESTAMPTZ)

Deploy to Railway

1. Push this repo to GitHub
2. In Railway: New Project → Deploy from GitHub repo
3. Set all env vars from .env.example
4. Railway auto-detects npm start

Environment Variables

# Supabase (from your project dashboard)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=sbp_...

# JWT Secrets (generate with: openssl rand -hex 32)
JWT_SECRET=your_secret_here
JWT_REFRESH_SECRET=your_refresh_secret_here
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# Server
PORT=3001
ALLOWED_ORIGINS=http://localhost:3000,https://aethex.app

# Optional: Email service for verification (future)
# SENDGRID_API_KEY=...
# EMAIL_FROM=noreply@aethex.app

Structure

src/
  app.js              — Express entry point + Swagger setup
  config/
    supabase.js       — Supabase client
    swagger.js        — OpenAPI/Swagger config
  routes/
    auth.js           — Authentication endpoints
    profile.js        — Profile management
    platforms.js      — Gaming platform linking
    health.js         — Health check
  middleware/
    auth.js           — JWT verification
    errorHandler.js   — Centralized error handling
    rateLimiter.js    — Rate limiting
    validators.js     — Input validation
  services/
    authService.js    — Auth business logic
    profileService.js — Profile logic
    platformService.js — Platform logic
  utils/
    logger.js         — Logging
scripts/
  migrate.js          — Database migration SQL

Security Features

• Email Verification: Required for account creation
• JWT Tokens: Separate access (15m) & refresh (7d) tokens
• Password Hashing: bcryptjs with salt rounds 12
• Rate Limiting: 100 requests per 15 minutes per IP
• Helmet: Security headers (HSTS, CSP, etc)
• CORS: Configurable origin whitelist
• Audit Logging: Track user actions (login, platform connects)
• Token Blacklist Ready: Logout support with token invalidation

Development

# Install dependencies
npm install

# Run migrations (copy SQL output to Supabase)
npm run migrate

# Start development server (auto-reload with nodemon)
npm run dev

# Run tests (when available)
npm test

API Testing

1. Swagger UI: http://localhost:3001/api-docs
2. cURL Example:

# Register
curl -X POST http://localhost:3001/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@aethex.app",
    "password": "SecurePass123",
    "displayName": "TestUser"
  }'

# Verify email
curl -X POST http://localhost:3001/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "emailVerificationToken"}'

# Login
curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@aethex.app",
    "password": "SecurePass123"
  }'

# Get profile (requires token)
curl -X GET http://localhost:3001/api/v1/profile/me \
  -H "Authorization: Bearer <accessToken>"

Error Handling

All errors return JSON with status code and message:

{
  "error": "Invalid email or password.",
  "statusCode": 401,
  "message": "..."
}

Common codes:

• 400 — Validation error
• 401 — Unauthorized (invalid token/credentials)
• 404 — Not found
• 409 — Conflict (email exists, platform already connected)
• 429 — Rate limited
• 500 — Server error

Roadmap

• Password reset endpoint
• Two-factor authentication (TOTP)
• OAuth2/OpenID Connect support
• Mobile SDKs (React Native, Flutter)
• Admin dashboard
• Team/organization support
• Device trust & session management

Owner

AeThex Corporation — Identity standard governed by AeThex Foundation.

---

Last Updated: February 2026 | Version: 1.0.0