diff --git a/docs/ARCHITECTURE.rst b/docs/ARCHITECTURE.rst index dcd450c..f3aa52d 100644 --- a/docs/ARCHITECTURE.rst +++ b/docs/ARCHITECTURE.rst @@ -5,13 +5,17 @@ Architecture .. uml:: architecture.uml +This program's design resembles a Resource-Method-Representation architecture pattern. This is due to the design choice of making it API-oriented, instead of +domain-oriented. Therefore -Programming Paradigm --------------------- +Router -This python package is mainly authored according to a functional programming -paradigm, however, strictly adhering to said seemed ignorant, since not all -objects in Python are immutable anyway. Modification of mutable input objects -are therefore not regarded as side-effects per se, due to the contractual nature -of a function's parameter signature. \ No newline at end of file + +Controller + + +Model + + +Backend diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst index dd31711..9ea8cdc 100644 --- a/docs/CONTRIBUTING.rst +++ b/docs/CONTRIBUTING.rst @@ -1,7 +1,7 @@ Contribution Guidelines ======================= -TO-DO test +TODO Prerequisites ------------- @@ -13,9 +13,11 @@ You need the following tools to be installed: .. code-block:: shell - $ git clone git@bitbucket.org:victorykit/ezcfn.git - $ cd ezcfn + $ git clone git@bitbucket.org:victorykit/httpaste.git + $ cd httpaste $ python3 -m pipenv install -d $ python3 -m pipenv run tox -e test $ python3 -m pipenv run tox -e build - $ python3 -m pipenv run tox -e build-docs \ No newline at end of file + $ python3 -m pipenv run tox -e docs + $ python3 -m pipenv run tox -e lint + $ python3 -m pipenv run tox -e format diff --git a/docs/README.rst b/docs/README.rst index d2af101..0bf034c 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -1,38 +1,41 @@ -httpaste -======== +httpaste - versatile HTTP pastebin +================================== .. only:: readme - ![](docs/_assets/images/dog-gf2faaf3f6_1920.png) + ![](docs/_assets/images/favpng_parrot-royalty-free-cartoon.png) .. only:: not readme - .. image:: _assets/images/dog-gf2faaf3f6_1920.png + .. image:: _assets/images/favpng_parrot-royalty-free-cartoon.png -Simple and safe pasting over HTTP. +httpaste is a pastebin application for easily pasting and retrieving data over +HTTP from shell environments and web browsers. It is inspired by `sprunge.us`_ +and `ix.io`_, but focuses on extendability, advanced security, with little to +no trade-off to simplicity. It can be hosted through WSGI, CGI, Fast CGI, or +as a standalone evaluation server. It offers multiple storage backends, such as +a filesystem backend, SQLite backend, MySQL backend, or MongoDB backend. -httpaste is a pastebin application for easily pasting and retrieving data over HTTP from shell environments and web browsers. It is inspired by sprunge.us and ix.io, but focuses on extendability and advanced security. +All pastes are being encrypted on the fly and can only be retrieved by an +authorized user, either through knowing the paste id of a public paste, or +having authentication credentials, as well as the paste id of a private paste. +This makes httpaste ideal as a pastebin for sensitive environments such as the +Tor network. Authentication credentials are created on-the-fly and don't require a sign-up process. -public and private pastes are supported. In any case, httpaste provides full anonymity, with each paste being stored encrypted. +httpaste supports output formatting for syntax highlighting (powered by +`pygments`_), as well as MIME type output manipulation, and input encoding. +Therefore httpaste can server as an anonymous object storage for small data. -Why ---- - -As a user: Sometimes we say and write stupid things. Things so stupid, that -others may even be offended. Others being so offended, that they wish to take -legal actions against you. Legal actions which infringe upon your rights for - privacy. Who is the others? Well, it's the - -Public pastes: Only people you share the paste id with are able to view the paste. Public pastes aren't indexed publicly, so Public pastes are encrypted with their paste id and the paste id is only -stored as a hash. Therefore the httpaste application hoster is unable to view any pastes, unless he maliciously logs any of the HTTP requests. +Minute-based and 'burn-after-read' paste expiration are supported. +httpaste focuses on security through cryptography, making it a computationally intensive application. .. include:: guide/get-started.rst Documentation ------------- -The documentation can be found under ``_. +The documentation can be found under ``_. Licensing @@ -51,11 +54,19 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License -along with this program. If not, see . +along with this program. If not, see . + +This program uses licensed third-party software. + .. toctree:: :maxdepth: 1 :caption: More Information ARCHITECTURE - CONTRIBUTING \ No newline at end of file + CONTRIBUTING + +.. _ix.io: http://ix.io/ +.. _sprunge.us: http://sprunge.us +.. _pygments: https://pygments.org/ +.. _icon: https://favpng.com/png_view/parrot-parrot-royalty-free-cartoon-png/gps7HM42 \ No newline at end of file diff --git a/docs/_assets/images/dog-gf2faaf3f6_1920.png b/docs/_assets/images/dog-gf2faaf3f6_1920.png deleted file mode 100644 index 51779a8..0000000 Binary files a/docs/_assets/images/dog-gf2faaf3f6_1920.png and /dev/null differ diff --git a/docs/_assets/images/favpng_parrot-royalty-free-cartoon.png b/docs/_assets/images/favpng_parrot-royalty-free-cartoon.png new file mode 100644 index 0000000..697c745 Binary files /dev/null and b/docs/_assets/images/favpng_parrot-royalty-free-cartoon.png differ diff --git a/docs/conf.py b/docs/conf.py index 1ad01bd..dad5404 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,7 +21,7 @@ extensions = [ 'sphinxcontrib.plantuml', 'sphinxarg.ext', 'sphinx.ext.viewcode', - 'sphinx_autodoc_typehints' + 'sphinx_autodoc_typehints', ] templates_path = ['_templates'] diff --git a/docs/guide/advanced-usage.rst b/docs/guide/advanced-usage.rst index 10a176c..99dfe01 100644 --- a/docs/guide/advanced-usage.rst +++ b/docs/guide/advanced-usage.rst @@ -1,8 +1,8 @@ Advanced Usage ============== -Binary Pastes -------------- +Binary Data +----------- httpaste supports encoding. Encode your data as Base64, Base85, Base32, or Base16 and provide an encoding specifier. @@ -14,4 +14,56 @@ Base16 and provide an encoding specifier. When getting pastes, you may provide a MIME type, if a client deduces the encoding by looking at the HTTP 'Content-Type' header. +.. code-block:: shell + $ curl "https://p.victoryk.it/paste/public/5Rt3E3n6?mime=application/pdf" + +Custom Expiration +----------------- + +Set a paste's lifetime to make it expire after a specified amount of time. The +lifetime must be provided in minutes and cannot be less than 1. A lifetime of +0 will evaluate to a lifetime 1. + +.. code-block:: shell + + $ echo "My paste expires after reading" | curl "http://localhost:8080/paste/public?lifetime=360" -F "data=<-" + http://localhost:8080/paste/public/5Rt3E3n6 + +Burn-After-Read Expiration +-------------------------- + +Set a paste's lifetime to <0 to make it expire right after reading + +.. code-block:: shell + + $ echo "My paste expires after reading" | curl "http://localhost:8080/paste/public?lifetime=-1" -F "data=<-" + http://localhost:8080/paste/public/5Rt3E3n6 + +.. code-block:: shell + + $ curl http://localhost:8080/paste/public/5Rt3E3n6 + My paste expires after reading + $ curl http://localhost:8080/paste/public/5Rt3E3n6 + {"detail":"Paste expired","status":410,"title":"Gone"} + +Syntax Higlighting +------------------ + +You can apply syntax highlighting to a multitude of formats. Consult the pygments documentation for valid specifiers. + +.. code-block:: shell + + $ curl "http://localhost:8080/paste/public/5Rt3E3n6?syntax=terraform" + +Highlighting, by default, will be formatted for 256 color terminals. You can also change the formatting. + +.. code-block:: shell + + $ curl "http://localhost:8080/paste/public/5Rt3E3n6?syntax=terraform&format=html" + +You can also add line numbers to the output. + +.. code-block:: shell + + $ curl "http://localhost:8080/paste/public/5Rt3E3n6?syntax=terraform&format=html&linenos=true" \ No newline at end of file diff --git a/docs/guide/backend.rst b/docs/guide/backend.rst index e1b6118..bc2f9c3 100644 --- a/docs/guide/backend.rst +++ b/docs/guide/backend.rst @@ -1,17 +1,16 @@ Backend ======= -Binary Pastes -------------- +The backend can be configured within the `[backend]` section of the configuration file. -httpaste supports encoding. Encode your data as Base64, Base85, Base32, or -Base16 and provide an encoding specifier. +SQLite +------ -.. code-block:: shell +.. autoclass:: httpaste.backend.sqlite.Parameters + :members: - $ cat my.pdf | base64 | curl "http://localhost:8080/paste/public?encoding=base64" - http://localhost:8080/paste/public/5Rt3E3n6 +Filesystem +---------- -When getting pastes, you may provide a MIME type, if a client deduces the encoding by looking at the HTTP 'Content-Type' header. - - $ curl "https://p.victoryk.it/paste/public/5Rt3E3n6?mime=application/pdf" +.. autoclass:: httpaste.backend.file.Parameters + :members: \ No newline at end of file diff --git a/docs/guide/cli.rst b/docs/guide/cli.rst new file mode 100644 index 0000000..6202617 --- /dev/null +++ b/docs/guide/cli.rst @@ -0,0 +1,7 @@ +Command-Line Interface +====================== + +.. argparse:: + :module: httpaste.__main__ + :func: parser + :prog: httpaste \ No newline at end of file diff --git a/docs/guide/cli.rstas b/docs/guide/cli.rstas deleted file mode 100644 index 4ac5d54..0000000 --- a/docs/guide/cli.rstas +++ /dev/null @@ -1,2 +0,0 @@ -Get Started -=========== \ No newline at end of file diff --git a/docs/guide/get-started.rst b/docs/guide/get-started.rst index 8e4d524..0bbeedc 100644 --- a/docs/guide/get-started.rst +++ b/docs/guide/get-started.rst @@ -1,68 +1,68 @@ Get Started =========== -Installation ------------- +Install +""""""" .. code-block:: shell $ python3 -m pip install httpaste-victorykit $ httpaste --help -Create configuration --------------------- + +Create Configuration +"""""""""""""""""""" .. code-block:: shell $ httpaste default-config --dump myconfig.ini -Run a local test server ------------------------ +.. note:: + The default configuration creates an in-memory SQLite backend, which is not + suitable for WWW deployments. Visit `backend`, for more + information on configuring the backend. + + +Run a Local Evaluation Server +""""""""""""""""""""""""""""" .. code-block:: shell $ httpaste standalone --config myconfig.ini --port 8080 - * Serving Flask app 'httpaste' (lazy loading) - * Environment: production - WARNING: This is a development server. Do not use it in a production deployment. - Use a production WSGI server instead. - * Debug mode: off - * Running on all addresses. - WARNING: This is a development server. Do not use it in a production deployment. - * Running on http://localhost:8080/ (Press CTRL+C to quit) + Publish a Private Paste ------------------------ +""""""""""""""""""""""" .. code-block:: shell - $ echo 'My first private paste' | curl -F 'data=<-' \ - -u myusername:mypassword \ - http://localhost:8080/paste/private + $ echo 'My first private paste' | curl -F 'data=<-' -u myusername:mypassword http://localhost:8080/paste/private http://localhost:8080/paste/private/UALUA9 .. note:: If the user does not exist, they will be created upon authentication. + Retrieve a Private Paste ------------------------- +"""""""""""""""""""""""" .. code-block:: shell $ curl -u myusername:mypassword http://localhost:8080/paste/private/UALUA9 My first private paste + Publish a Public Paste ------------------------ +"""""""""""""""""""""" .. code-block:: shell - $ echo 'My first public paste' | curl -F 'data=<-' \ - http://localhost:8080/paste/public + $ echo 'My first public paste' | curl -F 'data=<-' http://localhost:8080/paste/public http://localhost:8080/paste/public/X4L39J + Retrieve a Public Paste ------------------------- +"""""""""""""""""""""""" .. code-block:: shell diff --git a/docs/index.rst b/docs/index.rst index 5fc124a..bb9e5a0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,9 +2,12 @@ .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: Guides guide/get-started + guide/advanced-usage + guide/backend + guide/cli