Auth Server

This server facilitates communication between the Decentraland client and the auth dapp on the browser. It allows the client to execute wallet methods (eth_sendTransaction, personal_sign, etc.) using the wallet the user has on their browser by leveraging the auth dapp.

Table of Contents

• Features
• Dependencies & Related Services
• API Documentation
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Running the Service
• Testing

Features

• Authentication Request Management: Creates, stores, and manages authentication requests with automatic expiration (default: 5 minutes).
• WebSocket Real-Time Communication: Provides Socket.IO-based real-time communication for instant request/response handling between clients and the auth dapp.
• HTTP Polling Support: Offers REST endpoints as an alternative to WebSocket for environments where WebSocket is not available.
• Identity Management: Supports temporary identity creation and retrieval for auto-login flows.
• Signature Validation: Validates Ethereum signatures using @dcl/crypto Authenticator to ensure requests are authorized.
• Verification Codes: Generates random verification codes (0-99) for visual confirmation between client and auth dapp.

Dependencies & Related Services

This service interacts with the following services:

• Auth dApp: The browser-based application that executes wallet methods on behalf of the user using their connected wallet.
• Decentraland Client: The desktop application that initiates authentication requests.

External dependencies:

• @dcl/crypto: For Ethereum signature validation
• @dcl/schemas: For Decentraland schema types and validation
• Socket.IO: For WebSocket real-time communication

API Documentation

The API is fully documented using the OpenAPI standard. Its schema is located at docs/openapi.yaml.

Getting Started

Prerequisites

Before running this service, ensure you have the following installed:

• Node.js: Version 22.x or higher (LTS recommended)
• Yarn: Version 1.22.x or higher
• Docker: For containerized deployment (optional, for integration testing)

Installation

1. Clone the repository:

git clone https://github.com/decentraland/auth-server.git
cd auth-server

2. Install dependencies:

yarn install

3. Build the project:

yarn build

Configuration

The service uses environment variables for configuration. Create a .env file in the root directory containing the environment variables for the service to run. Use the .env.default variables as an example.

Running the Service

Running in development mode

To run the service in development mode:

yarn start:dev

Running in production mode

To run the compiled service:

yarn start

Testing

This service includes comprehensive test coverage with both unit and integration tests.

Running Tests

Run all tests with coverage:

yarn test

Run tests in watch mode:

yarn test:watch

Run only unit tests:

yarn test test/unit

Run only integration tests:

yarn test:integration

Test Structure

• Unit Tests (test/unit/): Test individual components and functions in isolation
• Integration Tests (test/integration/): Test the complete request/response cycle

For detailed testing guidelines and standards, refer to our Testing Standards documentation.

Onboarding Email Nudge System

The server includes a backend-driven email nudge system that detects when users stall during onboarding and sends contextual recovery emails via SendGrid.

Admin Endpoints (dev/staging only)

These endpoints are only mounted when ONBOARDING_ADMIN_ENABLED=true in .env. They are disabled by default in production.

POST /admin/onboarding/run-evaluator

Triggers the nudge evaluator manually (same logic the cron runs every 15 min). Finds users stuck at each checkpoint for 12h/24h/36h and sends the appropriate email.

curl -X POST http://localhost:8080/admin/onboarding/run-evaluator

POST /admin/onboarding/send-test-email

Sends a nudge email directly to a specific address, bypassing the database. Useful for previewing SendGrid templates.

# Send CP3 sequence 1 email to your inbox
curl -X POST http://localhost:8080/admin/onboarding/send-test-email \
  -H 'Content-Type: application/json' \
  -d '{"to": "you@example.com", "checkpointId": 3, "sequence": 1}'

# Send CP1 sequence 2
curl -X POST http://localhost:8080/admin/onboarding/send-test-email \
  -H 'Content-Type: application/json' \
  -d '{"to": "you@example.com", "checkpointId": 1, "sequence": 2}'

Parameters:

• to (string) — recipient email address
• checkpointId (1–7) — which checkpoint's content to use
• sequence (1, 2, 3) — which SendGrid template to use

GET /admin/onboarding/pending-nudges/:sequence

Returns users that would receive an email on the next cron run for a given sequence.

# Check who's pending for sequence 1 (12h)
curl http://localhost:8080/admin/onboarding/pending-nudges/1

# Response:
# {"sequence":1,"count":2,"nudges":[{"userId":"user@test.com","checkpointId":2,"email":"user@test.com"},...]}}

Working with authentication and blockchain requests

To understand more about how the server works with this requests, see docs/requests.md.

AI Agent Context

For detailed AI Agent context, see docs/ai-agent-context.md.