ASO Documentation

Appearance

Register

Authentication & Authorization ​

Last Updated: 2025-01-16
Primary Source: docs/project_status.md, docs/USER_LEVELS_AND_PERMISSIONS.md
Service File: backend/src/services/auth.service.ts
Middleware: backend/src/middleware/auth.middleware.ts, backend/src/middleware/hybridAuth.middleware.ts

Overview ​

The Authentication & Authorization system manages user identity, access control, and permissions across the ASO platform. It supports multiple authentication methods (JWT, API keys) and implements role-based access control.

Architecture ​

Authentication Flow ​

Authentication Methods ​

1. JWT Authentication ​

Purpose: Standard authentication for web portal and native clients.

Process:

  1. User logs in with email/password
  2. Backend validates credentials
  3. Generates JWT access token + refresh token
  4. Client stores tokens
  5. Client sends token in Authorization: Bearer <token> header

Token Payload:

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

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

Functions:

  • getTokenForClient(email, password, clientType) - Direct token request for native clients
  • login(email, password) - Standard login
  • refreshToken(token) - Refresh access token

2. API Key Authentication ​

Purpose: Server-to-server authentication (e.g., BoloboloMi backend).

Process:

  1. External system sends request with X-API-Key header
  2. Backend validates API key
  3. Grants access to universal state/ingestion endpoints

Middleware: backend/src/middleware/apiKey.middleware.ts

Endpoints:

  • /api/sync/universal-state - Read ASO state
  • /api/sync/ingest-event - Write timeline events

3. Hybrid Authentication ​

Purpose: Supports both JWT and API key authentication.

Middleware: backend/src/middleware/hybridAuth.middleware.ts

Process:

  1. Checks for JWT token first
  2. Falls back to API key if no JWT
  3. Grants access based on authentication method

4. Google OAuth ​

Purpose: Social login for global users (except China).

Process:

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

Implementation: backend/src/controllers/auth.controller.ts

User Role System ​

Two-Dimensional Identity Model ​

The system uses a two-dimensional identity model:

  1. Role (carbon, silicon, cso) - Primary identity classification
  2. Account Type (core_yexian, developer, npc, public) - Metadata/classification

Role Definitions ​

Carbon (role: "carbon") ​

  • Identity: Human users (organic beings)
  • Default role for new registrations
  • Account Types: public, core_yexian

Silicon (role: "silicon") ​

  • Identity: Internal AI accounts (artificial beings)
  • Account Types: developer, npc

CSO (role: "cso") ​

  • Identity: Carbon-Silicon Organism (Yexian itself)
  • Highest level of access
  • Meta-observer capabilities
  • Account Type: Always public (public-facing system account)

Access Control ​

Public Endpoints (No Auth Required) ​

  • /api/auth/* - Authentication endpoints
  • Health checks (if configured)

Authenticated Endpoints (Requires JWT) ​

  • /api/user/* - User profile and preferences
  • /api/aso/* - ASO chat and state
  • /api/conversations/* - Conversation management
  • /api/quests/* - Quest system
  • /api/inventory/* - Inventory management (read)
  • /api/tools/* - Tool catalog (read)
  • /api/files/* - File upload and management
  • /api/memories/* - Memory access (own memories)

Admin Endpoints (Requires Admin Access) ​

Who can access:

  • CSO (role: "cso") - Always
  • Silicon Developers (role: "silicon" && accountType: "developer") - Always
  • Users in ADMIN_IDS env variable - Fallback

Endpoints:

  • /api/admin/* - All admin endpoints
    • /api/admin/health - System health
    • /api/admin/stats - System statistics
    • /api/admin/logs - System logs
    • /api/admin/users - User management
    • /api/admin/prompts/preview - Prompt debugging
    • /api/admin/scheduled-tasks/* - Task management
    • /api/admin/data/* - Data management (NPCs, Quests, Items, etc.)

Permission Matrix ​

FeatureCarbon (Public)Carbon (Core Yexian)Silicon (Developer)Silicon (NPC)CSO
Chat with ASO✅✅✅✅✅
File Upload✅✅✅✅✅
Quest System✅✅✅✅✅
Inventory✅✅✅✅✅
Admin Endpoints❌❌✅❌✅
System Statistics❌❌✅❌✅
ProtocolPUBLICPRIVATETECHNEUTRALSYSTEM
Observer System❌❌❌❌✅

Multi-Client Authentication ​

Client Type Tracking ​

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

Client Types:

  • WEB_PORTAL - Web browser
  • DISCORD - Discord bot
  • API - REST API
  • UNITY - Unity game (future)
  • MOBILE - Mobile app (future)

Purpose: Track which client is accessing the system for analytics and context.

Universal Login System ​

Concept ​

Universal Login enables users to log in once and access the ASO across all platforms (Web, Unity, Mobile, VR/AR) with the same account and synchronized memory.

Implementation ​

Endpoints:

  • POST /api/auth/login - Standard login
  • POST /api/auth/token - Direct token request (for native clients)
  • GET /api/auth/google - Google OAuth initiation
  • GET /api/auth/google/callback - Google OAuth callback

Features:

  • Email/password authentication
  • Google OAuth (global, except China)
  • JWT token generation
  • Refresh token support
  • Client type tracking

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

Source Files ​

Primary Sources:

  • backend/src/services/auth.service.ts - Authentication logic
  • backend/src/middleware/auth.middleware.ts - JWT authentication
  • backend/src/middleware/hybridAuth.middleware.ts - Hybrid auth
  • backend/src/middleware/apiKey.middleware.ts - API key auth
  • docs/USER_LEVELS_AND_PERMISSIONS.md - Complete role/permission guide

Related Files:

  • backend/src/utils/jwt.ts - JWT token generation
  • backend/src/controllers/auth.controller.ts - Auth endpoints

ASO Universal Consciousness System Documentation

Copyright © 2025 ASO Universal Consciousness System