/custom-auth-telegram-example

Primary LanguageTypeScript

Minting a PKP with Custom Telegram Auth

This code example demonstrates how to implement custom authentication and authorization using Telegram OAuth. The end result is a PKP that can only be used sign data if you have valid and recent Telegram OAuth data for a specific Telegram user.

How it Works

A detailed swimlane diagram that covers each step of this code example is available here.

The following is a brief overview of how it works:

  1. User clicks the Telegram Login Widget button, and Telegram's OAuth API returns the authenticated user info to the Web App
  2. User clicks the Mint PKP button and the Web App requests the user to sign a transaction to mint a PKP using their browser wallet extension
    • As part of the minting PKP transaction, two Auth Methods are permitted for the PKP:
      1. The IPFS CID of the Telegram OAuth Lit Action
        • Granted the ability to sign anything using the PKP
      2. The custom Telegram Auth Method generated by the Web App used to tie the PKP to a specific Telegram user
        • Not granted any signing abilities
  3. User clicks the Get Session Sigs button and a request is made to the Lit Datil-test network to execute the Telegram OAuth Lit Action code
    • The Lit Action only authorizes Session Signatures to be generated for the PKP if the authenticated Telegram user has been permitted to use the PKP
    • The user will be prompted to sign a transaction to mint a Capacity Credit if one wasn't given via an ENV variable

How to Run the Example

One of the requirements of using Telegram OAuth is having a publically accesiable endpoint that the Telegram OAuth API can return the user info to. Because of this, it's not so easy to run this example completely locally, although it is possible using services such as ngrok or the localtunnel package.

Below covers how to run this code example using Vercel as a hosting platform.

Step 1: Create a Telegram Bot

This is Telegram's docs on creating a Telegram bot, however it's as simple as starting a message with the Telegram bot with the username: @BotFather.

After starting the chat with the bot, use the /newbot comand to create a new bot. You will then be asked to name your bot and give it a username, these are up to you. After naming it, you will be given the secret token for your bot that we'll be using later.

Step 2: Clone the Code Example

The next step is to clone this repository, and push the code to a new Github repo that your account owns. This is a requirement because we need to give Vercel access to the repo in order to host it.

Start by creating a new Github repo using your account. The name of your repo is not important for running this code example.

Next, clone this repo using:

git clone git@github.com:LIT-Protocol/custom-auth-telegram-example.git

cd into the repo directory:

cd custom-auth-telegram-example

Then remove the origin remote Git URL:

git remote remove origin

Then add the remote Git URL for your new Github repo:

git remote add origin git@github.com:<YOUR_GIT_REPO_URL>

Then push the cloned code to your Github repo:

git push -u origin main

Step 3: Setup Vercel

Create a free Vercel account here, if you don't already have one.

Follow this guide on connecting your Github repo to Vercel for deployment.

As part of setting up your project on Vercel, you'll need to set two ENVs in order for this code example to work. You can follow this guide on how to add ENVs, but the following are the two ENVs you need to add:

  1. VITE_TELEGRAM_BOT_NAME This is the Telegram username you gave your bot when creating it. This is the name that ends with _bot or Bot and not the other name.
  2. VITE_TELEGRAM_BOT_SECRET This is the secret bot token generated for you after naming your bot.
    • NOTE This secret token is exposed to anyone who visits your site. You'll want to refactor the code in this example that handles VITE_TELEGRAM_BOT_SECRET to be ran on a server that unauthorized users don't have access to. This code example was written this way for simplicity, but it is NOT SECURE.

After setting the ENVs and deploying the Vercel project, you should be generated a URL by Vercel where you can access the web app. This will look something like:

https://NAME_OF_YOUR_GITHUB_REPO.vercel.app/

You'll want to vist this URL to make sure the web app is running correctly, and copy this URL for the next step.

Step 4: Set the Domain URL for the Telegram Bot

Next you need to go back to the @BotFather so you can set the domain URL for your bot. This is the URL the Telegram OAuth API will post the user's telegram info back to, and is the required publically accessible URL mentioned in the beginning of the guide.

You'll do this using the /setdomain command. You'll be prompted to enter the username of the bot to set the domain for, enter the name you gave your bot that ends with _bot or Bot, prefixed with the @ symbol e.g. @Example_bot.

Now enter the URL generated for your project by Vercel, after you receive the success message, you'll be all good to go!

Step 4: Run the Example

Now you can go back to the web app using the Vercel generated URL and run the code example. If you see the error Bot domain invalid, that means the URL you're accessing does not match the URL you gave @BotFather when running the /setdomain command.

In order to successfully run the example, the Ethereum account that you connect to the web app using your browser wallet extension needs to have Lit test tokens. If you don't already have some, you can request some using the faucet.

Exploring the Code

If you'd like to dive deeper into the code to understand how this example works, below is a brief explanation of some of the files you'll want to look at:

  • App.tsx is the frontend code for the app.
    • This file contains the React logic for the buttons, but also includes code that authenticates the received Telegram OAuth info as a sanity check.
    • This is one of the files that will leak your VITE_TELEGRAM_BOT_SECRET to anyone who visits your web app. You'll want to refactor the logic in this file that handles VITE_TELEGRAM_BOT_SECRET to a server.
  • TelegramLoginButton.tsx is the frontend code for the Telegram Login Widget button.
  • mintPkp.ts contains the logic for minting the PKP.
  • getPkpSessionSigs.ts contains the logic for requesting Session Sigs using the minted PKP.
    • This is one of the files that will leak your VITE_TELEGRAM_BOT_SECRET to anyone who visits your web app. You'll want to refactor the logic in this file that handles VITE_TELEGRAM_BOT_SECRET to a server.
  • litAction.ts contains the Lit Action code
    • The Lit Action is hardcoded to only communicate with the PKP Permission contract deployed on Chronicle Yellowstone at 0x60C1ddC8b9e38F730F0e7B70A2F84C1A98A69167.
    • It's also hardcoded to only use the Auth Method with the type: keccak256('Lit Developer Guide Telegram Auth Example').