Telegram Passport

Using this library in production? Let me know on Telegram (@bcrypt) and I'll be glad to list your project here.

This library lets you parse and use requested data from Telegram Passport that's sent to your bot. (It has no dependencies, too!)

Usage

First, create a TelegramPassport object with your private key.

const TelegramPassport = require('telegram-passport')
const passport = new TelegramPassport(yourPrivateKey) // The private key must be PEM-encoded

After this, you are ready to decrypt payloads. To decrypt a PassportData object from Telegram, use the decrypt method.

// Obtain passportData through some means
var decryptedData = passport.decrypt(passportData)

Here is an example of what the decrypt method will return for the scopes personal_details, email, passport, identity_card, and utility_bill.

{
  "payload": "bot_defined_payload",
  "address": {
    "data": {
      "city": "Somecity",
      "country_code": "US",
      "post_code": "92069",
      "state": "California",
      "street_line1": "Address line 1",
      "street_line2": ""
    }
  },
  "identity_card": {
    "data": {
      "document_no": "12345",
      "expiry_date": "01.23.2021"
    },
    "front_side": {
      "file": {
        "file_id": "SOME_FILE_ID",
        "file_date": 1528299109
      },
      "secret": "BASE64_ENCODED_SECRET",
      "hash": "BASE64_ENCODED_HASH"
    },
    "reverse_side": {
      "file": {
        "file_id": "SOME_FILE_ID",
        "file_date": 1528299109
      },
      "secret": "BASE64_ENCODED_SECRET",
      "hash": "BASE64_ENCODED_HASH"
    }
  },
  "personal_details": {
    "data": {
      "birth_date": "01.23.2000",
      "country_code": "US",
      "first_name": "Mark",
      "gender": "male",
      "last_name": "Zuckerberg",
      "residence_country_code": "US"
    }
  },
  "utility_bill": {
    "files": [
      {
        "file": {
          "file_id": "SOME_FILE_ID",
          "file_date": 1532621515
        },
        "secret": "BASE64_ENCODED_SECRET",
        "hash": "BASE64_ENCODED_HASH"
      },
      {
        "file": {
          "file_id": "SOME_FILE_ID",
          "file_date": 1532621515
        },
        "secret": "BASE64_ENCODED_SECRET",
        "hash": "BASE64_ENCODED_HASH"
      }
    ]
  }
}

Handling Files

Files are returned differently than the PassportFile object. Every file returned by this library is in this format:

{
  "file": {
    "file_id": "SOME_FILE_ID",
    "file_date": 1532621515
  },
  "secret": "BASE64_ENCODED_SECRET",
  "hash": "BASE64_ENCODED_HASH"
}

file contains the original PassportFile object that was returned by the bot API, and secret / hash are the secret / file_hash from the FileCredentials, accordingly.

To download a file, call getFile like normal with the file ID. Once you get the file data, however, you must decrypt it. To do so, you can call the decryptPassportCredentials method:

passport.decryptPassportCredentials(
  fileData, // Should be a Buffer
  Buffer.from(file.hash, "base64"), // It is assumed we are using our example object above
  Buffer.from(file.secret, "base64")
)

This will return the decrypted JPEG image data.

Source Code

The source code for this library is available here. Feel free to report issues there as well.

License

This library is licensed under the GNU GPL 3.0.

node-telegram-passport
Copyright (C) 2018  TJ Horner

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.