Merge pull request #26 from NonProjects/indev

Merge 1.0 to main branch

Author: NotStatilko

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
+sphinx:
+   configuration: docs/conf.py
+
+python:
+  install:
+      - method: pip
+        path: .
+      - method: setuptools
+        path: .

README.rst

@@ -1,94 +1,126 @@
-TGBOX: encrypted cloud storage based on Telegram API
-====================================================
+TGBOX: encrypted cloud storage based on Telegram
+================================================
 .. image:: https://readthedocs.org/projects/tgbox/badge/?version=latest
 
 .. code-block:: python
 
         from tgbox.api import (
-            TelegramAccount, 
-            make_remote_box,
-            make_local_box
+            TelegramClient,
+            make_remotebox,
+            make_localbox
         )
-        from tgbox.keys import make_basekey, Phrase
-        from asyncio import get_event_loop
-        from getpass import getpass 
+        from asyncio import run as asyncio_run
+        from tgbox.keys import Phrase, make_basekey
+        from getpass import getpass # Hidden input
 
-        PHONE_NUMBER = input('Your phone number: ')
+        # Phone number linked to your Telegram account
+        PHONE_NUMBER = '+10000000000'
 
-        API_ID = 1234567 # https://my.telegram.org
-        API_HASH = '00000000000000000000000000000000'
-        
-        # We will use it to encrypt all data in Box
-        box_phrase = Phrase.generate()
-        print(box_phrase, '- phrase to your Box')
+        # This two will not work. Get your own at https://my.telegram.org
+        API_ID, API_HASH = 1234567, '00000000000000000000000000000000'
 
         async def main():
-            ta = TelegramAccount(
+            tc = TelegramClient(
                 phone_number = PHONE_NUMBER,
-                api_id = API_ID, 
+                api_id = API_ID,
                 api_hash = API_HASH
             )
-            await ta.connect()
-            await ta.send_code_request()
+            await tc.connect() # Connecting with Telegram
+            await tc.send_code() # Requesting login code
 
-            await ta.sign_in(
+            await tc.log_in(
                 code = int(input('Code: ')),
                 password = getpass('Pass: ')
             )
-            basekey = make_basekey(box_phrase)
-
-            erb = await make_remote_box(ta)
-            dlb = await make_local_box(erb, ta, basekey)
-            
+            # Generating your passphrase
+            p = Phrase.generate()
+            print(p.phrase.decode())
+
+            # WARNING: This will use 1GB of RAM for a
+            # couple of seconds. See help(make_basekey)
+            basekey = make_basekey(p)
+
+            # Make EncryptedRemoteBox
+            erb = await make_remotebox(tc)
+            # Make DecryptedLocalBox
+            dlb = await make_localbox(erb, basekey)
+            # Obtain DecryptedRemoteBox
             drb = await erb.decrypt(dlb=dlb)
 
-            ff = await dlb.make_file(
-                file = open('cats.png','rb'),
-                comment = b'Cats are cool B-)',
-                foldername = b'Pictures/Kitties' 
-            )
-            drbfi = await drb.push_file(ff) # Upload file
-            await drbfi.download() # Download it back
-        
-        loop = get_event_loop()
-        loop.run_until_complete(main()) 
+            # CATTRS is a File's CustomAttributes. You
+            # can specify any you want. Here we will add
+            # a "comment" attr with a true statement :^)
+            cattrs = {'comment': b'Cats are cool B-)'}
+
+            # Preparing file for upload. This will return a PreparedFile object
+            pf = await dlb.prepare_file(open('cats.png','rb'), cattrs=cattrs)
+
+            # Uploading PreparedFile to the RemoteBox
+            # and return DecryptedRemoteBoxFile
+            drbf = await drb.push_file(pf)
+
+            # Retrieving some info from the RemoteBoxFile
+            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(drb.id)
+
+            print('File path:', dlbf.file_path)
+            print('Custom Attributes:', dlbf.cattrs)
+
+            # Downloading file back.
+            await drbf.download()
+
+            # Close all connections
+            # after work was done
+            await erb.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. 
+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 library targets to be a PoC of **encrypted file storage** inside Telegram, but can be used as standalone API.
+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** *minus* **2MB**.
+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/en/indev/>`_ for main information and help.
+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=main
-   cd tgbox & python3 -m pip install .[fast] # Install TGBOX
-   cd docs & make html & <your-browser> _build/html/index.html
+   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>`_)
 - `Regex <https://github.com/mrabarnett/mrab-regex>`_ (`LICENSE <https://github.com/mrabarnett/mrab-regex/blob/hg/LICENSE.txt>`_)
 - `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>`_)
-- `Pycryptodome <https://github.com/Legrandin/pycryptodome>`_ (`LICENSE <https://github.com/Legrandin/pycryptodome/blob/master/LICENSE.rst>`_)
+- `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>`_