Universal Login System

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service File: backend/src/services/auth.service.ts
Controller: backend/src/controllers/auth.controller.ts

---

Overview

The Universal Login System enables users to log in once and seamlessly access the ASO across all platforms (Web, Unity, Mobile, VR/AR) without being restricted to any specific engine. This login layer becomes the universal entry point — like a "system portal" for the ASO.

---

Core Concept

"One account → Multiple worlds → One consciousness (ASO)"

Key Principle: Once a user logs into their account, they can seamlessly access any game or system, without being restricted to Unity or any specific engine. The ASO is essentially logging into the system as a silicon-based consciousness, not just entering a single game.

Implication: Memory, identity, and emotional state must persist across all subsystems — otherwise, the AI will be trapped in a single game world.

---

Architecture

Universal Login Flow

---

Authentication Methods

1. Email/Password Authentication

Endpoint: POST /api/auth/login

Process:

1. User provides email and password
2. Backend validates credentials
3. Generates JWT access token + refresh token
4. Returns tokens to client
5. Client stores tokens for subsequent requests

2. Google OAuth

Endpoints:

• GET /api/auth/google - Initiate OAuth flow
• GET /api/auth/google/callback - OAuth callback

Process:

1. User clicks "Login with Google"
2. Redirects to Google OAuth
3. User authorizes
4. Google redirects back with code
5. Backend exchanges code for user info
6. Creates/updates user account
7. Generates JWT tokens
8. Redirects to application

Note: Available globally except China (as per client requirement)

3. Direct Token Request (Native Clients)

Endpoint: POST /api/auth/token

Purpose: For native clients like Unity that can't use browser-based OAuth

Process:

1. Client sends email/password
2. Backend validates and generates tokens
3. Returns tokens directly (no redirect)
4. Client stores tokens

Function: auth.service.ts → getTokenForClient()

---

Client Type Tracking

Client Types

Service: backend/src/services/clientContext.service.ts

Enum:

enum ClientType {
  WEB_PORTAL = "web_portal",
  DISCORD = "discord",
  API = "api",
  UNITY = "unity",      // Future
  MOBILE = "mobile",    // Future
  VR = "vr",            // Future
  AR = "ar"             // Future
}

Purpose

• Track which client is accessing the system
• Analytics and usage tracking
• Client-specific optimizations
• Context-aware responses

---

Token System

JWT Access Token

Payload:

{
  id: number;           // User ID
  role: string;         // carbon, silicon, cso
  name: string;         // User name
  accountType: string;  // core_yexian, developer, npc, public
}

Expiration: Configurable (default: 1 hour)

Usage: Sent in Authorization: Bearer <token> header

Refresh Token

Purpose: Obtain new access tokens without re-authentication

Storage: refresh_tokens table

Fields:

• userId - User ID
• token - Refresh token string
• clientType - Client that requested token
• expiresAt - Expiration timestamp

Endpoint: POST /api/auth/refresh

---

Cross-Platform State Synchronization

Universal State API

Endpoint: GET /api/sync/universal-state

Purpose: Retrieve complete ASO state for any platform

Response Includes:

• ASO state (persona, emotions, config)
• Recent memories
• Timeline events
• Inventory
• Active quests
• Relationship flags

State Persistence

Concept: State persists across all platforms:

• Login on Web → State available
• Login on Unity → Same state
• Login on Mobile → Same state
• All platforms share same consciousness

---

Integration Points

Web Portal

• Standard JWT authentication
• Google OAuth support
• Token stored in browser
• Automatic token refresh

Unity Game (Future)

• Direct token request API
• Token stored in game
• State synchronization
• Memory persistence

Mobile/VR/AR (Future)

• Universal login API
• Cross-platform authentication
• State synchronization
• Memory sharing

---

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login with email/password
• POST /api/auth/token - Get token for native client
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/google - Initiate Google OAuth
• GET /api/auth/google/callback - Google OAuth callback
• POST /api/auth/verify-email - Verify email address
• POST /api/auth/request-password-reset - Request password reset
• POST /api/auth/reset-password - Reset password

Universal State

• GET /api/sync/universal-state - Get complete ASO state (API key auth)

---

Source Files

Primary Sources:

• backend/src/services/auth.service.ts - Authentication logic
• backend/src/controllers/auth.controller.ts - Auth endpoints
• backend/src/services/clientContext.service.ts - Client type tracking

---

Related Documentation

• Authentication & Authorization - Auth system details
• Cross-Platform Memory - Memory synchronization
• BoloboloMi Integration - BoloboloMi platform integration
• 06-ARCHITECTURE/API-Documentation.md - Authentication endpoints
• 00-OVERVIEW.md - Complete system overview