Web3 Authentication App

📚 Table of Contents

1. Overview
2. Why Use This
3. How It Works
   • TON Wallet Authentication Flow
   • EVM Wallet Authentication Flow
4. Installation
5. API Reference
   • POST /auth/payload
   • POST /auth/verify
6. Frontend Integration
7. Security Notes
8. Contributing
9. License

Overview

Web3 Auth API is a lightweight and secure authentication service that allows developers to verify the ownership of a user's blockchain wallet, on both EVM compatible networks (e.g Ethereum and Polygon) and The Open Network (TON) blockchain.

Instead of using traditional credentials (email/password), this API enables web services to authenticate users based on cryptographic wallet proofs.

Why Use This?

• Passwordless login using wallet signatures
• Cross-chain support (EVM + TON)
• Secure: Prevents replay attacks with nonce + timestamps
• Modular: Easy to plug into any web2/web3 frontend

Installation

• Clone the repository

  git clone https://github.com/cjScrypt/web3_auth_app

• Install dependencies

  npm install
  # or
  yarn install

• Set environment variables

  PORT="your_app_port"
  DATABASE_URL="your_db_url"
  JWT_SECRET="your_jwt_secret"
  TON_API_MAINNET="ton_mainnet_api_url"
  TON_API_TESTNET="ton_testnet_api_url"

• Run the server

  npm run dev

Server will start on http://localhost:3000 (or the port you configure).

How it works

1. Client Requests Payload

• The client (frontend) sends a request to the API to generate a payload for authentication.
• The payload includes a unique nonce and is signed on the server-side.
  

2. User Signs the Payload

• The client asks the user to sign the received payload using their wallet (EVM or TON).
• The wallet returns a signed message (proof).

3. Client Submits Proof

• The client sends the signed proof, wallet address, and the original payload back to the API for verification.

4. Server Verifies the Proof

• The server verifies:
  • The proof matches the original payload.
  • The address matches the signer.
  • The payload nonce is still valid and unused.

5. Successful Authentication

• If all checks pass, the server returns a signed JWT token to the client.
• The client can now use the JWT token for authenticated requests.

API Reference

POST /auth/generatePayload

• Request Body: GeneratePayloadDto

  {
    "address": "",
    "chainId": ""
  }

• Response Body

  {
    "data": "" // payload
  }

POST /auth/signin-evm

• Request Body: CheckEvmProofDto

  {
    "proof": "",
    "address": "0x...",
    "payloadToken": ""
  }

• Response Body

  {
    "data": {
        "token": "",
        "user": {
            "id": "",
            "walletAddress": "0x...",
            "firstName": "",
            "lastName": ""
        }
    }
  }

POST /auth/signin-ton

• Request Body: CheckTonProofDto

  {
      "address": "",
      "network": "",
      "public_key": "",
      "proof": {
          "timestamp": 1745254673793,
          "domain": {
              "lengthBytes": 1,
              "value": ""
          },
          "payload": "",
          "signature": "",
          "state_init": ""
      }
  }

Types

• GeneratePayloadDto:

  • address (string): User's wallet address
  • chainId (string): Blockchain type. Allowed values: ton or evm

• CheckEvmProofDto

  • proof (string): Wallet signature of payloadToken
  • address (string): User's address
  • payloadToken (string): Payload from the request

• CheckTonProofDto

  • address: User's TON wallet address,
  • network (string): Blockchain network. Allowed values: CHAIN.TESTNET or CHAIN.MAINNET
  • public_key (string): User's public key,
  • proof (string):
    • timestamp (Date): Time of signing (Date.now()),
    • domain:
      • lengthBytes (number): Length of the frontend domain name
      • value (string): Frontend domain name
    • payload (string): Payload from the request
    • signature (string): Base64-encoded signature
    • state_init (string): Wallet state init, used to reconstruct and verify the wallet address

Frontend Integration

Coming Soon!!

Security Notes

• Payload Expiration: Payloads are short-lived and expire after a limited time window to reduce the risk of replay attacks.
• Nonce Verification: Payloads are associated with a unique nonce stored temporarily in Redis. This nonce is removed from cache on expiration or successful verification.
• Signature Validation: Wallet signatures are strictly verified against the original payload and expected address

Contributing

Contributions are welcome. Please open an issue or submit a pull request if you would like to help improve the project. Thank you!

License

Licensed under the MIT License