:)
-k

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

Contributing to OnionSproutsBot

Hi, thank you for taking the time to contribute to this project!

All types of contributions are encouraged and immensely appreciated. See the Table of Contents for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. We look forward to cooperating with you! :)

Table of Contents

• Translations
• Reporting Bugs
  • Users
  • Instance Administrators
• Submitting Merge Requests
  • Internationalization
  • Commit Messages
  • Formatting

Translations

You can contribute translations to this project on Weblate: https://hosted.weblate.org/projects/tor/

Reporting Bugs

If you're experiencing a problem with this project, the right place to report such issues is our bug tracker.

For us to be able to help, we need to know as much about your problem as possible.

Your report should contain the following information:

Users

This format should be preferred if you are reporting an issue on behalf of somebody else.

• What were you trying to do?
• What did you expect to happen? What happened instead?
• Did you get an error message? If yes, what did it say?

Instance Administrators

• Operating System (Name / Version)
• Version (Release / Commit Revision)
• Config file without credentials

Submitting Merge Requests

Internationalization

You can skip this section if your proposed change does not alter any strings that are visible to the user.

We use gettext to translate the bot between English and many other languages. As this is relatively unusual for this kind of project, we find it important to mention the steps to update the locale files, so as to keep this project accessible to everyone.

1. Ensure that gettext is installed. (Debian: sudo apt install gettext)
2. Copy the file header (containing e.g. the project title) present in OnionSproutsBot/locales/onionsproutsbot.pot
3. From the top directory, run the following command:

xgettext -L Python \
    --files-from=OnionSproutsBot/locales/POTFILES \
    --output=OnionSproutsBot/locales/onionsproutsbot.pot \
    --copyright-holder="The OnionSproutsBot Authors." \
    --package-name=OnionSproutsBot \
    --msgid-bugs-address="https://gitlab.torproject.org/tpo/anti-censorship/gettor-project/OnionSproutsBot/issues" \
    --no-location

4. Recover the old file header.

Commit Messages

The summary of your commit should not contain more than 50 characters. All other lines should not contain more than 70-75 characters..

Please try to be concise and precise about what your commit does. If you believe that the Summary adequately explains it, then that's more than enough.

Please try to avoid mentioning any crucial information about your change in the description of a Merge Request, and use the Commit for this purpose instead, as its contents will be automatically used for that description later.

An exception to this rule would be e.g. using the description of a Merge Request to directly address another contributor over something that is related to the review process, which probably isn't something that should forever "engrave" the commit tree.

Formatting

We use flake8 for formatting. The maximum length of a line, as defined in setup.cfg, is 132 columns.

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.