updating documentation

CHANGELOG.md

@@ -1,12 +1,18 @@
 # PrivateBin version history
 
-  * **next (not yet released)**
+  * **1.2 (not yet released)**
     * ADDED: Translations for Spanish, Occitan, Norwegian, Portuguese, Dutch and Hungarian
     * ADDED: Option in configuration to change the default "PrivateBin" title of the site
+    * ADDED: Added display of video, audio & PDF, drag & drop, preview of attachments (#182)
+    * ADDED: QR code generation (#169)
+    * ADDED: Introduced DOMpurify library to sanitize generated HTML before display (#183)
+    * CHANGED: Force JSON request for getting paste data & password retry (#216)
     * CHANGED: Minimum required PHP version is 5.4 (#186)
     * CHANGED: Shipped .htaccess files were updated for Apache 2.4 (#192)
     * CHANGED: Cleanup of bootstrap template variants and moved icons to `img` directory
     * CHANGED: Removed option to hide clone button on expiring pastes, since this requires reading the paste for rendering the template, which leaks information on the pastes state
+    * CHANGED: Refactored JavaScript code, making it modular with private and public functions, making it much easier to maintain (#178)
+    * FIXED: To counteract regressions introduced by the refactoring, we finally introduced property based unit testing for the JavaScript code, this caught several regressions, but also some very old bugs not found so far (#32)
   * **1.1.1 (2017-10-06)**
     * CHANGED: Switched to `.php` file extension for configuration file, to avoid leaking configuration data in unprotected installation.
   * **1.1 (2016-12-26)**

CREDITS.md

@@ -22,6 +22,7 @@ Sébastien Sauvage - original idea and main developer
 * Nathaniel Olsen - jQuery upgrade
 * Alexander Demenshin - modal password dialog
 * PunKeel - Dockerfile
+* thororm - Display of video, audio & PDF, drag & drop, preview of attachments
 
 ## Translations
 * Hexalyse - French

INSTALL.md

@@ -1 +1,171 @@
-For installation instructions, see [our wiki](https://github.com/PrivateBin/PrivateBin/wiki/Installation).
+# Installation
+
+**TL;DR:** Download the
+[latest release archive](https://github.com/PrivateBin/PrivateBin/releases/latest)
+and extract it in your web hosts folder where you want to install your PrivateBin
+instance. We try to provide a mostly safe default configuration, but we urge you to
+check the [security section](#hardening-and-security) below and the [configuration
+options](#configuration) to adjust as you see fit.
+
+**NOTE:** See [our FAQ](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#how-can-i-securely-clonedownload-your-project) for information how to securely download the PrivateBin release files.
+
+### Minimal requirements
+
+- PHP version 5.4 or above
+- _one_ of the following sources of cryptographically safe randomness is required:
+  - PHP 7 or higher
+  - [Libsodium](https://download.libsodium.org/libsodium/content/installation/) and it's [PHP extension](https://paragonie.com/book/pecl-libsodium/read/00-intro.md#installing-libsodium)
+  - open_basedir access to `/dev/urandom`
+  - mcrypt extension
+  - com_dotnet extension
+  
+  Mcrypt needs to be able to access `/dev/urandom`. This means if `open_basedir` is set, it must include this file.
+- GD extension
+- some disk space or (optionally) a database supported by [PDO](https://secure.php.net/manual/book.pdo.php)
+- ability to create files and folders in the installation directory and the PATH defined in index.php
+- A web browser with javascript support
+
+## Hardening and security
+
+### Changing the path
+
+In the index.php you can define a different `PATH`. This is useful to secure your
+installation. You can move the configuration, data files, templates and PHP
+libraries (directories cfg, doc, data, lib, tpl, tst and vendor) outside of your
+document root. This new location must still be accessible to your webserver / PHP
+process (see also
+[open_basedir setting](https://secure.php.net/manual/en/ini.core.php#ini.open-basedir)).
+
+> #### PATH Example
+> Your PrivateBin installation lives in a subfolder called "paste" inside of
+> your document root. The URL looks like this:
+> http://example.com/paste/
+>
+> The full path of PrivateBin on your webserver is:
+> /home/example.com/htdocs/paste
+> 
+> When setting the path like this:
+> define('PATH', '../../secret/privatebin/');
+>
+> PrivateBin will look for your includes / data here:
+> /home/example.com/secret/privatebin
+
+### Transport security
+
+When setting up PrivateBin, also set up HTTPS, if you haven't already. Without HTTPS
+PrivateBin is not secure, as the javascript files could be manipulated during transmission.
+For more information on this, see our [FAQ entry on HTTPS setup](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#how-should-i-setup-https).
+
+### File-level permissions
+
+After completing the installation, you should make sure, other users on the system cannot read the config file or the `data/` directory, as – depending on your configuration – potential secret information are saved there.
+
+See [this FAQ item](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#what-are-the-recommended-file-and-folder-permissions-for-privatebin) for a detailed guide on how to "harden" the permissions of files and folders.
+
+## Configuration
+
+In the file `cfg/conf.php` you can configure PrivateBin. A `cfg/conf.sample.php`
+is provided containing all options and default values. You can copy it to
+`cfg/conf.php` and adapt it as needed. The config file is divided into multiple
+sections, which are enclosed in square brackets.
+
+In the `[main]` section you can enable or disable the discussion feature, set
+the limit of stored pastes and comments in bytes. The `[traffic]` section lets
+you set a time limit in seconds. Users may not post more often then this limit
+to your PrivateBin installation.
+
+More details can be found in the
+[configuration documentation](https://github.com/PrivateBin/PrivateBin/wiki/Configuration).
+
+## Advanced installation
+
+### Web server configuration
+
+A `robots.txt` file is provided in the root dir of PrivateBin. It disallows all
+robots from accessing your pastes. It is recommend to place it into the root of
+your web directory if you have installed PrivateBin in a subdirectory. Make sure
+to adjust it, so that the file paths match your installation. Of course also
+adjust the file if you already use a `robots.txt`.
+
+A `.htaccess.disabled` file is provided in the root dir of PrivateBin. It blocks
+some known robots and link-scanning bots. If you use Apache, you can rename the
+file to `.htaccess` to enable this feature. If you use another webserver, you
+have to configure it manually to do the same.
+
+### When using Cloudflare
+
+If you want to use PrivateBin behind Cloudflare, make sure you have disabled the Rocket
+loader and unchecked "Javascript" for Auto Minify, found in your domain settings,
+under "Speed". (More information
+[in this FAQ entry](https://github.com/PrivateBin/PrivateBin/wiki/FAQ#user-content-how-to-make-privatebin-work-when-using-cloudflare-for-ddos-protection))
+
+### Using a database instead of flat files
+
+In the configuration file the `[model]` and `[model_options]` sections let you
+configure your favourite way of storing the pastes and discussions on your
+server.
+
+`Filesystem` is the default model, which stores everything in files in the
+data folder. This is the recommended setup for most sites.
+
+Under high load, in distributed setups or if you are not allowed to store files
+locally, you might want to switch to the `Database` model. This lets you
+store your data in a database. Basically all databases that are supported by
+[PDO](https://secure.php.net/manual/en/book.pdo.php) may be used. Automatic table
+creation is provided for `pdo_ibm`, `pdo_informix`, `pdo_mssql`, `pdo_mysql`,
+`pdo_oci`, `pdo_pgsql` and `pdo_sqlite`. You may want to provide a table prefix,
+if you have to share the PrivateBin database with another application or you want
+to use a prefix for
+[security reasons](https://security.stackexchange.com/questions/119510/is-using-a-db-prefix-for-tables-more-secure).
+The table prefix option is called `tbl`.
+
+> #### Note
+> The `Database` model has only been tested with SQLite, MySQL and PostgreSQL,
+> although it would not be recommended to use SQLite in a production environment.
+> If you gain any experience running PrivateBin on other RDBMS, please let us
+> know.
+
+The following GRANTs (privileges) are required for the PrivateBin user in **MySQL**. In normal operation:
+- INSERT, SELECT, DELETE on the paste and comment tables
+- SELECT on the config table
+
+If you want PrivateBin to handle table creation (when you create the first paste) and updates (after you update PrivateBin to a new release), you need to give the user these additional privileges:
+- CREATE, INDEX and ALTER on the database
+- INSERT and UPDATE on the config table
+
+For reference or if you want to create the table schema for yourself to avoid having to give PrivateBin too many permissions (replace
+`prefix_` with your own table prefix and create the table schema with your favourite MySQL console):
+
+```sql
+CREATE TABLE prefix_paste (
+    dataid CHAR(16) NOT NULL,
+    data BLOB,
+    postdate INT,
+    expiredate INT,
+    opendiscussion INT,
+    burnafterreading INT,
+    meta TEXT,
+    attachment MEDIUMBLOB,
+    attachmentname BLOB,
+    PRIMARY KEY (dataid)
+);
+
+CREATE TABLE prefix_comment (
+    dataid CHAR(16),
+    pasteid CHAR(16),
+    parentid CHAR(16),
+    data BLOB,
+    nickname BLOB,
+    vizhash BLOB,
+    postdate INT,
+    PRIMARY KEY (dataid)
+);
+CREATE INDEX parent ON prefix_comment(pasteid);
+
+CREATE TABLE prefix_config (
+    id CHAR(16) NOT NULL, value TEXT, PRIMARY KEY (id)
+);
+INSERT INTO prefix_config VALUES('VERSION', '1.1.1');
+```
+
+In **PostgreSQL**, the data, attachment, nickname and vizhash columns needs to be TEXT and not BLOB or MEDIUMBLOB.

README.md

@@ -7,7 +7,7 @@
 [![Codacy Badge](https://api.codacy.com/project/badge/Coverage/094500f62abf4c9aa0c8a8a4520e4789)](https://www.codacy.com/app/PrivateBin/PrivateBin)
 [![Test Coverage](https://codeclimate.com/github/PrivateBin/PrivateBin/badges/coverage.svg)](https://codeclimate.com/github/PrivateBin/PrivateBin/coverage) [![Code Coverage](https://scrutinizer-ci.com/g/PrivateBin/PrivateBin/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/PrivateBin/PrivateBin/?branch=master)
 
-*Current version: 1.1.1*
+*Current version: 1.2*
 
 **PrivateBin** is a minimalist, open source online [pastebin](https://en.wikipedia.org/wiki/Pastebin)
 where the server has zero knowledge of pasted data.
@@ -90,17 +90,19 @@ file](https://github.com/PrivateBin/PrivateBin/wiki/Configuration):
   to adjust size limit)
 
 * Templates: By default there are bootstrap CSS, darkstrap and "classic ZeroBin"
-  themes and it is easy to adapt these to your own websites layout or create
+  to choose from and it is easy to adapt these to your own websites layout or
-  your own.
+  create your own.
 
 * Translation system and automatic browser language detection (if enabled in
   browser)
 
 * Language selection (disabled by default, as it uses a session cookie)
 
+* QR code generation of URL, to easily transfer pastes over to a mobile device
+
 ## Further resources
 
-* [Installation guide](https://github.com/PrivateBin/PrivateBin/wiki/Installation)
+* [Installation guide](https://github.com/PrivateBin/PrivateBin/blob/master/INSTALL.md)
 
 * [Upgrading from ZeroBin 0.19 Alpha](https://github.com/PrivateBin/PrivateBin/wiki/Upgrading-from-ZeroBin-0.19-Alpha)