@merqva/telegram-passport v1.0.2

Telegram Passport

Parse/Decrypt incoming Telegram Passport data

* Note: All the type definitions on this library are in compliance with those defined in the Telegram API specification

What does this library do?

Provided your Bot's Private Key, this library will:

• Decrypt the EncryptedCredentials object from the credentials field in PassportData
• Parse the fields on each EncryptedPassportElement from the data field in PassportData
• Decrypt de data field (if present) from the EncryptedPassportElement
• Validate the integrity of the decryted data

What doesn't this library do?

• Get the encrypted files corresponding to the requested fields* Download the encrypted files using the getFile API endpoint, then use the decryptData method to decrypt them

Usage

• First, create a new instance of the TelegramPassport class

const telegramPassport = new TelegramPassport("<bot_private_key>");

• Parse and decryp de data of all the elements shared with the bot

const data = telegramPassport.decryptPassportData(
    update.message.passport_data
);

// the nonce is retuned within the RequestedFields object

const nonce = data.nonce;

* update is the object representing the incoming Update that was sent to the Bot

• Decryting files

/*
get the data corresponding to the file you want to decryp
for example, the front side of the id card
*/

const id_frontSide = data.identity_card.front_side;

// download the file using the getFile API endpoint

...

// decryp the file

const file = telegramPassport.decryptData(
  downloaded_file_data,
  id_fronSide.secret,
  id_fronSide.file_hash,
);

• Depending on the fields you requested, you might not need to process the whole PassportData object; for example, the "phone_number" and "email" fields are not encrypted. Thus, you only need to decrypt the credentials to obtain the nonce, then, you can get "phone_number" and "email" from passport_data.data

/*
in this case, data will look like this

data: [
  {
    "type": "phone_number",
    "phone_number": "XXXXXXXXXXX",
    "hash": "the_base64-encoded_hash",
  },
  {
    "type": "email",
    "email": "johndoe@example.com",
    "hash": "the_base64-encoded_hash"
  },
]
*/

// decrypt the credentials

const credentials = telegramPassport.decryptPassportCredentials(
  update.message.passport_data.credentials,
);

* update is the object representing the incoming Update that was sent to the Bot

What can be inproved?

• The type "handling" in the decryptData method* Need a TS guru that can give me a hand with that, go check the code

Found a bug?

Open an issue (PRs are welcome)

* be patient, I might be busy

Stay in touch

• Author - Yoel Navas
• Website - merqva.com