Metadata-Version: 2.1
Name: tgback-x
Version: 1.1
Summary: tgback-x — a library for making Telegram account backups
Home-page: https://github.com/NonProjects/tgback-x
Download-URL: https://github.com/NonProjects/tgback-x/archive/refs/tags/v1.1.tar.gz
Author-email: thenonproton@pm.me
License: MIT
Keywords: Telegram,Backup,Account,Non-official
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyaes==1.6.1
Requires-Dist: telethon==1.38.1
Requires-Dist: phrasegen<2

# TGBACK-X — a library for making Telegram account backups

######  _[Check out the GUI implementation - XQt!](https://github.com/NotStatilko/tgback-x-qt)_

**TGBACK-X** is a little library which you can utilize to create an **encrypted backup of your Telegram account**. If you've been around here before then you probably heard about my old project called [TGBACK](https://github.com/NotStatilko/tgback) (without *X*). Actually, this library is an **implementation revisit** of the same concept with just about the same purpose.

The difference between the *old TGBACK* and *X version* (except completely different backup structure) is that this repository is **strictly Python library for devs** and doesn't have any App implementation (like Command line app that old *TGBACK* have). However most importantly, **this version doesn't create any backup files** (hence the *X* in name). Instead, it relies on the *Providers* — **third-party services that we use to store encrypted backup data.**

## **Idea behind:**

1. User type password or **we generate random N (default 8) mnemonic words**;
2. **We feed password to Scrypt** (1GB from defaults), obtain *Scrypt key*;
3. We make **(hash)** a unique *KeyID* from *Scrypt key* material;
4. We ask for Telegram login credentials, log into account;
5. We take account's **session** and construct a backup data;
6. We **encrypt backup data** with one of *Cryptography Protocol*;
7. We **store the encrypted backup data on Provider server by KeyID**.

In that way, User will be able to get Session only by typing secret Phrase. Obviously, this approach may impose some risks — anyone who will be able to type the same Phrase will obtain a full access to account. User should **treat its Phrase like Bitcoin seed phrase** and **never** use *X* version on a compromised Computer, e.g, with malwares / other programs that can record keyboard or screen.

Telegram session is no-special in TGBACK-X and can be killed at any time through Telegram Settings —> Devices or directly from backup data by itself. Disconnected Session is a useless pile of encoded bytes. If you feel that your Phrase may be compromised — **destroy session immediately**. You can always create a different one. Different backups keep different sessions, so they wouldn't be connected at all.

## **Default approach:**

**Default** (and currently only one implemented here) *Provider* is a `TelegramChannel`. That is, we keep your encrypted Telegram data inside Telegram! The *KeyID* would be a *Channel public link*, and *Backup data* would be regular message. We utilize interesting Telegram feature — any **public** Telegram channel can be previewed in Browser without login. [**See this for example**](https://t.me/s/X3KEK3ELMZDDJ5KXEIJMEH65L4CJCMAY) — is a backup that you can make with `TelegramChannel`. We fetch backup data (`TelegramChannel` use `JSON_AES_CBC_UB64` crypto protocol) through http requests, decrypt and give Session to User.

## Welcome, developers

I (hope I) made **TGBACK-X** library modular, so you can create your own *Provider* / *Protocol* classes. Currently there is no documentation, but I tried to describe everything in Docstrings. You can refer to them and check how default classes are implemented for basic understanding. While I don't think that there is any sense in adding new cryptography *Protocol* (`JSON_AES_CBC_UB64` seems about enough), different *Provider* would be interesting to see.

### Install
```
pip install tgback-x
```

### Quick Example

**Store Session (Create backup)**

```python3
import tgback_x
import phrasegen

API_ID: int=1234567 # Obtain at my.telegram.org
API_HASH: str='00000000000000000000000000000000'

client = tgback_x.TelegramClient(
    session=tgback_x.StringSession(),
    api_id=API_ID,
    api_hash=API_HASH
)
# You can also Sign-In with the .send_code_request() and
# the .sign_in() method, as this is just a quick example. See
# docs.telethon.dev/en/stable/quick-references/client-reference.html
client.start()

generator = phrasegen.Generator()
phrase = generator.en.generate()

print('Your phrase is', phrase)

# Customizable. Unique Salt is highly recommendable.
key = tgback_x.crypto.make_scrypt_key(phrase.encode())

provider = tgback_x.providers.TelegramChannel()
provider.store(tgback_x.crypto.Key(key), client)
```

**Get Session (Load backup)**
```python3
import tgback_x

phrase = b'here comes your phrase dio ozzy'
key = tgback_x.crypto.make_scrypt_key(phrase)

provider = tgback_x.providers.TelegramChannel()
client = provider.get(tgback_x.crypto.Key(key))

print(client.get_me())
```

**Destroy Session & Backup**
```python3
import tgback_x

phrase = b'here comes your phrase dio ozzy'
key = tgback_x.crypto.make_scrypt_key(phrase)

provider = tgback_x.providers.TelegramChannel()
provider.destroy(tgback_x.crypto.Key(key))
```
