Metadata-Version: 2.1
Name: tgbox
Version: 1.2.1
Summary: Encrypted cloud storage API based on a Telegram API
Home-page: https://github.com/NonProjects/tgbox
Author: NonProjects
Author-email: thenonproton@pm.me
License: LGPL-2.1
Download-URL: https://github.com/NonProjects/tgbox/archive/refs/tags/v1.2.1.tar.gz
Description: TGBOX: encrypted cloud storage based on Telegram
        ================================================
        .. epigraph::
                | This repository contains a set of classes and functions used to manage TGBOX.
                | Try the `tgbox-cli <https://github.com/NotStatilko/tgbox-cli>`__  if you're interested in working implementation!
        
        .. code-block:: python
        
                from asyncio import run as asyncio_run
                from getpass import getpass # Hidden input
        
                from tgbox.api import TelegramClient, make_remotebox, make_localbox
                from tgbox.keys import Phrase, make_basekey
        
                # This two will not work. Get your own at https://my.telegram.org
                API_ID, API_HASH = 1234567, '00000000000000000000000000000000'
                # Simple progress callback to track upload/download state
                PROGRESS_CALLBACK = lambda c,t: print(round(c/t*100),'%')
        
                async def main():
                    phone = input('Phone number: ')
        
                    tc = TelegramClient(
                        phone_number = phone,
                        api_id = API_ID,
                        api_hash = API_HASH
                    )
                    await tc.connect() # Connecting to Telegram
                    await tc.send_code() # Requesting login code
        
                    code = int(input('Login code: '))
                    password = getpass('Your password: ')
        
                    # Login to your Telegram account
                    await tc.log_in(password, code)
        
                    # Generate and show your Box phrase
                    print(phrase := Phrase.generate())
        
                    # WARNING: This will use 1GB of RAM for a
                    # couple of seconds. See help(make_basekey)
                    basekey = make_basekey(phrase)
        
                    erb = await make_remotebox(tc) # Make EncryptedRemoteBox
                    dlb = await make_localbox(erb, basekey) # Make DecryptedLocalBox
                    drb = await erb.decrypt(dlb=dlb) # Obtain DecryptedRemoteBox
        
                    # Write a file path to upload to your Box
                    file_to_upload = input('File to upload (path): ')
        
                    # Preparing for upload. Will return a PreparedFile object
                    pf = await dlb.prepare_file(open(file_to_upload,'rb'))
                    # Uploading PreparedFile to Remote and getting DecryptedRemoteBoxFile
                    drbf = await drb.push_file(pf, progress_callback=PROGRESS_CALLBACK)
        
                    # Retrieving some info from the RemoteBox file
                    print('File size:', drbf.size, 'bytes')
                    print('File name:', drbf.file_name)
        
                    # You can also access all information about
                    # the RemoteBoxFile you need from the LocalBox
                    dlbf = await dlb.get_file(drbf.id)
        
                    print('File size:', dlbf.size, 'bytes')
                    print('File path:', dlbf.file_path)
        
                    # Downloading your [already uploaded] file from Remote.
                    await drbf.download(progress_callback=PROGRESS_CALLBACK)
        
                    # Close all connections
                    # after work was done
                    await drb.done()
                    await dlb.done()
        
                asyncio_run(main())
        
        Motivation
        ----------
        
        The Telegram is beautiful app. Not only by mean of features and Client API, but it's also good in cryptography and secure messaging. In the last years, core and client devs of Telegram mostly work for "social-network features", i.e video chats and message reactions which is OK, but there also can be plenty of "crypto-related" things.
        
        Target
        ------
        
        This *[unofficial]* library targets to be a PoC of **encrypted file storage** inside the Telegram, but can be used as standalone API.
        
        Abstract
        --------
        
        We name *"encrypted cloud storage"* as **Box** and the API to it as **Tgbox**. There is **two** of boxes: the **RemoteBox** and the **LocalBox**. They define a basic primitives. You can share your Box and separate Files with other people absolutely secure - only You and someone you want will have decryption key, even through insecure communication canals (`e2e <https://en.wikipedia.org/wiki/End-to-end_encryption>`__). You can make unlimited amount of Boxes, Upload & Download speed is **faster** than in official Telegram clients and maximum filesize is around **2GB** and around **4GB** for Premium users.
        
        Documentation
        -------------
        
        See `ReadTheDocs <https://tgbox.readthedocs.io/>`__ for main information and help.
        
        You can also build docs from the source
        
        .. code-block:: console
        
           git clone https://github.com/NonProject/tgbox --branch=indev
           cd tgbox && python3 -m pip install .[doc] # Install with doc
           cd docs && make html && firefox _build/html/index.html
        
        Third party & thanks to
        -----------------------
        - `⭐️ <https://github.com/NonProjects/tgbox/stargazers>`__ **Stargazers!**
        - `Sphinx_rtd_theme <https://github.com/readthedocs/sphinx_rtd_theme>`__ (`MIT <https://github.com/readthedocs/sphinx_rtd_theme/blob/master/LICENSE>`__)
        - `Aiosqlite <https://github.com/omnilib/aiosqlite>`__ (`MIT <https://github.com/omnilib/aiosqlite/blob/main/LICENSE>`__)
        - `Telethon <https://github.com/LonamiWebs/Telethon>`__ (`MIT <https://github.com/LonamiWebs/Telethon/blob/master/LICENSE>`__)
        - `Ecdsa <https://github.com/tlsfuzzer/python-ecdsa>`__ (`LICENSE <https://github.com/tlsfuzzer/python-ecdsa/blob/master/LICENSE>`__)
        - `Filetype <https://github.com/h2non/filetype.py>`__ (`MIT <https://github.com/h2non/filetype.py/blob/master/LICENSE>`__)
        - `Cryptg <https://github.com/cher-nov/cryptg>`__ (`LICENSE <https://github.com/cher-nov/cryptg/blob/master/LICENSE.txt>`__)
        - `Cryptography <https://github.com/pyca/cryptography>`__ (`LICENSE <https://github.com/pyca/cryptography/blob/main/LICENSE>`__)
        
        Resources
        ---------
        - Official **developer channel**: `@nontgbox <https://telegram.me/nontgbox>`__
        - **Example** TGBOX **container**: `@nontgbox_non <https://telegram.me/nontgbox_non>`__
        
Keywords: Telegram,Cloud-Storage,Cloud,API,Asyncio,Non-official
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Description-Content-Type: text/x-rst
Provides-Extra: doc
Provides-Extra: fast
