Auth server

The auth repository contains an application that lets users sign up for Chromia via various methods. As a dapp developer on Chromia, you want to use this to prevent attacks where users flood your dapp with accounts. Currently, the available options are:

Staking
Telegram

Information on configuring which methods you want to support is available in the setup section.

Staking

The staking module provides you with the possibility to allow your users to register an account if they have enough stake in a particular staking contract. Contracts are configured in the file staking/contracts/index.ts by updating the contracts map. The structure of the map looks like the following:

const contracts = {
  [contractAddress]: {
    address: string;
    url: string;
    abi: AbiItem[]
  }
}

Where contractAddress is the contract's address, url is the RPC URL of the chain which hosts the contract and abi is the ABI of the contract (can typically be found by looking at Etherscan or similar). By default, the application uses Chromia's staking contracts, deployed on Ethereum and Binance Smart Chain, but you are free to add your contracts and add or remove the default ones. So long as the custom staking contracts comply with the same interface.

note

The application will sum the user's stake across all the provided contracts. For example, if the staking limit is 1000 and the user has 200 staked on Ethereum and 800 staked on BSC, then the user's total stake will be 200 + 800 = 1000 and will be considered as having reached the staking limit.

API

The staking module exposes the following REST API:

`GET/auth/stake/enough?address=${evmAddress}`

used to determine if the provided address has enough stake to create an account. Example response:

{ "status": "SUCCESS", "data": { "hasEnoughStake": true } }

`GET/auth/stake/signing-message`

Retrieves the message to pass to MetaMask for user signing. Example response:

{
  "data": {
    "message": "Register an account on blockchain 1234"
  },
  "status": "SUCCESS"
}

`POST/auth/stake/create`

Creates a new postchain account for the user. The endpoint expects a metamask signature of the message returned by /auth/stake/signing-message. If the address corresponding to the private key signing the message has enough total stake, a postchain account'll be created. Example request:

{
  "signature": "0xd8b9bc03ef2384f7fd404c723f702f3426a044191778cd8570a9d9ca0214d5f108a04629f86e6acbdad599a828956b9b0df25fd1768e3c8bedd077a76f9c997d1b"
}

The Telegram module allows registration via Telegram. After sending the signed message to the correct endpoint, the user should be prompted with one of the following:

a link to t.me/<bot_username>?start=<address> (for example, t.me/MyRegistrationBot?start=0x0000000000000000000000000000000000000000)
the instructions to go to your telegram bot and use either /start <address> or /register <address>

It exposes two endpoints:

`POST /auth/telegram/`

Adds a signature for an address. The request body must include the address and signature.

Example:

{
  "address": "0x1234...",
  "signature": "0x5678..."
}

`GET /auth/telegram/:id`

Retrieves the signature for an address. Replace :id with the address in the URL.

Example:

GET /auth/telegram/0x1234...

Rate limiting is implemented on both endpoints to prevent abuse.

Installing auth server Rell module in your project

To include the auth server in your own Rell project, follow these steps:

Generate the auth server and the admin keys by running the following command:
```
chr keygen
```
caution
This command'll output a private key and a public key. Keep them safe, especially the private key, which should not be shared or exposed.
```
privkey=<privkey>
pubkey=<pubkey>
```
To save the generated keys to a file, use the --save option followed by the filename:
```
chr keygen --save .auth.secret
chr keygen --save .admin.secret
```
This'll save the keys to files named .auth.secret and .admin.secret in the current directory.

Add the following dependency to your chromia.yml:

libs:
  auth:
    registry: https://bitbucket.org/chromawallet/auth-server-ft4.git
    path: rell/src/auth
    tagOrBranch: main
    rid: x"77820D50A973CD478F661CB8690CBF70B45FF8672C2B7F4F66F76F33F12906E4"
    insecure: false

  ft4:
    registry: https://bitbucket.org/chromawallet/ft3-lib
    path: rell/src/lib/ft4
    tagOrBranch: v0.1.0r
    rid: x"561D4E625F47230E5A6E675C51049E74EA5CC5A0D1656D11F7AB299CF0D34BF3"
    insecure: false

Auth server Rell module depends on ft4, therefore we've to add ft4 dependency as well.

Add the following module argument:

moduleArgs:
  lib.ft4.admin:
    admin_pubkey: <admin pubkey>

  lib.auth:
    auth_pubkey: <auth pubkey>

Replace <auth pubkey> and <admin pubkey> with the public keys generated in Step 1.

Import the auth operations in your main Rell module:
```
import lib.auth;
```

:::Note

Remember to replace <auth pubkey> with the actual public key for auth in the module argument.

:::

Setting up the project

note

This app is just a node backend. You'll need to create some way for the users to interact with it. This section'll only explain how to set up the server-side software.

To set up and configure the app:

Clone the repository:

git clone git@bitbucket.org:chromawallet/auth-server-ft4.git

Install dependencies:

npm ci

Create an .env file and set up the necessary configuration variables. Here's an example of what your .env file could look like:

PORT=3001
MODE=dev
BLOCKCHAIN_RID=0F8B260F653457A5C7942018ED31BAE5EF53D6AE04FC4D402EC5F0DE26B5913D
BLOCKCHAIN_URL=http://localhost:7740
AUTH_PRIV_KEY=132EC6A758DCAA832DAFE032C4B23ABD9615C56792687ADBC561FCC377430CEC
STAKE_LIMIT=1000
TELEGRAM_API_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Start the server:

npm start

Available configuration options

These are the general options available:

Name	Description	Example
PORT	The port on which the app'll be listening	3001
MODE	Is this app running in development or production mode	dev\|prod
BLOCKCHAIN_RID	The blockchain rid of the postchain blockchain on which the app should create accounts	0F8B260F653457A5C7942018ED31BAE5EF53D6AE04FC4D402EC5F0DE26B5913D
BLOCKCHAIN_URL	The blockchain URL of the postchain blockchain on which the app should create accounts	http://localhost:7740
AUTH_PRIV_KEY	The user private key to perform register account operation	132EC6A758DCAA832DAFE032C4B23ABD9615C56792687ADBC561FCC377430CEC
AUTH_FLAGS	Comma separated list of flags used for registering a new account	A, T
STAKE_LIMIT	The minimum value the user needs to have staked to create an account. Only required if staking module is used.	1000
TELEGRAM_API_TOKEN	Your Telegram API token	123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

Auth server

Staking​

API​

GET/auth/stake/enough?address=${evmAddress}​

GET/auth/stake/signing-message​

POST/auth/stake/create​

Telegram​

POST /auth/telegram/​

GET /auth/telegram/:id​

Installing auth server Rell module in your project​

Setting up the project​

Available configuration options​