OnionSproutsBot

Telegram bot for distributing software by The Tor Project.

Usage Guide

• (Optional) Install gettext and additional locales.

If you'd like to include any other locales other than English, you should consider installing gettext using sudo apt install gettext.

If you want to include any further translations, run sh download_translations.sh.

If everything went smoothly, the locales folder should now contain a set of files that look like this: onionsproutsbot+[locale].po. These files will be included automatically during the installation of the bot.

• Install the required Python dependencies.

If you are planning to work with the source code, run pip3 install -r requirements.txt. That should suffice on a system with Python 3.7+ and pip installed. If applicable (mostly on Linux systems), you can also use Python modules provided by software packages.

For example, on Debian, you can install the aiofiles dependency using apt install python3-aiofiles.

• Install the bot

In most cases, you can simply run pip install .. This will install the Telegram bot on your system.

• Follow Pyrogram's Project Setup Guide.

You will need a Telegram account, as well as a bot account that can also be created with the help of BotFather. Make sure to create an application on the Telegram website.

• After you're done, edit example.yaml.

You will need to enter your API key, your application's API hash and your bot's access token. Although this bot was designed to be used with a bot account, you can also use an access token for a user account. There is also a set of additional options, such as the default name and the location of the database file, where all the ID numbers of cached files that have already been uploaded to Telegram's servers are stored.

• If a .session file is not present, you will be asked to enter a phone number and an access code.

Make sure you're using an interactive terminal when running the bot for the first time. This will generate a file with the extension .session, which you can also copy to other machines. Make sure to keep that file secret!

• You can now run the bot using osbtg example.yaml!

Mirrors & Issue Tracker

Currently, the bot is being developed on The Tor Project's GitLab instance as a part of the gettor project.

If you do not wish to make an account, it is also possible to report issues directly using email.

Design & Documentation

Since the design of the bot is evolving constantly, there's currently no formal documentation. However, the design and the thought process that have gone into this are being extensively documented. The latest revision of the code always includes comments that correspond to the problems that we dealt with, and temporary countermeasures for problems that have not been fully thought out yet will definitely be there until they are resolved. Older commits may provide more context to certain design decisions.

• Original thread at The Tor Project's GitLab.
• Issue Tracker

What are the goals of this project?

Someone brought up to me once that other bots like mine have solved similar problems. Even though similar implementations exist, they achieve wildly different goals, they are not the same.

Here's a list of our goals in order to better describe what this project aims to be:

• Concurrent. Able to serve as many people as possible.
• Resilient. Mitigate as many attack vectors as possible.
• Expandable. Sustainable. Easily adaptable.
• New, complicated feature? Get it work, definitely clean up later.
• Low bandwidth, old devices, language barriers should not matter.
• Beginner-friendly. That way, it will also be maintainer-friendly.

Why Pyrogram?

Pyrogram, unlike most other libraries, does not interact with Telegram's Bot API, but uses the MTProto protocol instead, which is the library that Telegram clients use. Using MTProto is of paramount importance, as it is bound to the same limitations that an actual user is, which is also why a user account (with a set of API keys) is also required.

For example, a user can upload files that are as large as 2 GB. However, a simple bot can only upload files of up to 50 MBs.

I unfortunately found out about this the hard way, as I initially attempted to write the bot using python-telegram-bot, which is syntactically similar in many ways. That allowed me to copy and paste most of the code, but I had to think about a lot of design decisions all over again and, as Pyrogram isn't used as often as other competing libraries.

Although OnionSproutsBot is a project that is developed independently from The Tor Project, Inc., one of its goals is to integrate itself enough to the organization in order to ensure its longevity and usefulness.

Even if the majority of this project's authors do not have any business relationship with The Tor Project, Inc., the project still falls under what would be best described as the community surrounding the aforementioned organization. The maintainer also believes in the values represented by the organization and its community, which aim to foster an inclusive community where people feel safe to participate, engage and share their points of view.

For those reasons, the maintainer believes that OnionSproutsBot should use the Code of Conduct of The Tor Project, Inc. This does not mean that third parties will necessarily get involved in the resolution of a supposed interpersonal conflict; you are merely reminded that even if we are independent, we have a similar belief system and that you should choose to be awesome to your fellow human beings whenever possible.

The latest version of the Code of Conduct can be found here:

https://gitweb.torproject.org/community/policies.git/plain/code_of_conduct.txt

OnionSproutsBot is distributed under this license:

Copyright (c) 2020-2023, Panagiotis "Ivory" Vasilopoulos, et al.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above

copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the names of the copyright owners nor the names of its

contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.