     [file version.texi not included]

This manual is for GNU LibreJS (version VERSION, UPDATED), a GNU IceCat extension to detect and block nonfree nontrivial JavaScript on webpages.

Copyright © 2011 2012 2014 2015 Loic J. Duros

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

LibreJS
*******

This manual is for GNU LibreJS (version VERSION, UPDATED).

Overview
********

GNU LibreJS ---an add-on for GNU IceCat and Mozilla Firefox--- detects and blocks nonfree nontrivial JavaScript while allowing its execution on pages containing code that is either trivial and/or free.

Many websites run nontrivial JavaScript on your computer. Some use it for complex tasks; many use it gratuitously for minor jobs that could be done easily with plain HTML.  Sometimes this JavaScript code is malicious.  Either way, the JavaScript code is often nonfree.  For explanation of the issue, see "The JavaScript Trap"(http://www.gnu.org/philosophy/javascript-trap.html).

If you care about freedom in your computing, and don't wish to let all and sundry make you run nonfree programs, now you can prevent it by using LibreJS.

Disclaimer
**********

  * LibreJS is not a security tool. Its goal is to detect nonfree nontrivial JavaScript, and it currently does not detect whether free or trivial code is malicious or not. Other free Mozilla extensions and add-ons may be available for this purpose.

  * LibreJS is always a work in progress. If you find a bug, please report it to bug-librejs@gnu.org.

Installation
************

You can install LibreJS directly using a generated librejs.xpi file, or by building it from source.

You can also download it from https://addons.mozilla.org/addon/librejs/, but due to Mozilla's review process the download isn't always up to date.

How to Use
**********

LibreJS in action
=================

After installing the add-on, you will see the LibreJS widget in the add-on bar at the top right of the browser window.  After loading a page, left-click on the widget to view the deactivated JavaScript code from the page (both on page and external) and, if applicable, the scripts that were accepted.

Script Blacklist/whitelist
==========================

Scripts may be blacklisted or whitelisted through the pop-up menu box.

Whitelisted scripts will always be accepted and blacklisted scripts will always get rejected.

It is important to note that this feature recognizes which scripts are blacklisted and whitelisted based on hash. This means that even a slight difference in a script's code will cause it to be recognized as a separate script.

Sometimes, JavaScript will be dynamically generated so that it is different every time a website is loaded. These types of scripts cannot be whitelisted or blacklisted since they cannot be recognized.

LibreJS has a default whitelist of scripts that are known to be free but may not declare their license in a format that LibreJS can understand.

Complaint Feature
=================

It is very important to complain when a site has nonfree JavaScript code, especially if it won't work without that code.  LibreJS makes it easy to complain by heuristically finding where to send the complaint.

When nonfree/nontrivial code is detected in a page, LibreJS attempts to find a relevant contact link or email for the website you are visiting. In order to do so, it will attempt to visit a few links from the current page (for instance, a link labeled ``contact'' on the same domain as the current page, ...)

LibreJS detects contact pages, email addresses that are likely to be owned by the maintainer of the site, Twitter and identi.ca links, and phone numbers.

When you complain to the website for their nonfree nontrivial JavaScript, provide them with the link to the JavaScript Trap essay so that they can get more information on what the issue is and how they can solve it on their own site.

LibreJS includes a default subject line and body for the complaint email, with a link to the JavaScript Trap essay. This can be configured in the LibreJS add-on preferences in your web browser.

Options
=======

     You can manage LibreJS's preferences either from the extension's entry in your browser's Add-ons Manager page (about:addons) or by clicking the LibreJS toolbar icon and then the "Settings..." button on the top right of the popup. This will open a panel containing a whitelist/blacklist manager and a section to configure your complaints messages to site owners.

Whitelist/Blacklist

     LibreJS lets you whitelist or blacklist domain names and subdomains, to bypass the regular JavaScript checks. This might be useful, for example, if you are running your own code in a local web server, or if you don't want to waste computing resources on script origins you already know you can't trust. librejs provides a lists manager UI to handle both the lists on the top of its Options panel.

Complaint email subject
     Configure the default subject used in complaint emails.

Complaint email body
     Configure the default body used in complaint emails.

JavaScript Detection
********************

LibreJS considers a very strict subset of JavaScript to be acceptable for use in non-free scripts. This is meant to maximimize compatibility with websites that haven't tried to be LibreJS compatible.

We consider modification of the document non-trivial. There isn't much that javascript could do that we would consider trivial, for anything else a free software license would be required.

The criterion is as follows:

For each function definition:

  * It must call only primitives.

  * The number of conditionals and loops must be at most 3.

  * It does not declare an array more than 50 elements long.

  * It must not call itself

For the rest of the script, outside of function definitions:

  * It must call only primitives and functions defined above in the page.

  * The number of conditionals and loops must be at most 3.

"function" means anything executable that gets a name, including methods.

Allowed primitives exclude:

  * eval()

  * ajax

  * calling methods with the square bracket notation

  * altering the dom

  * most other items found as methods of the `.window` object.

Free Licenses Detection
***********************

The machine readable format for license declarations that LibreJS uses has changed in the most recent version. This was necessary in order to not break the asynchronous JS loading model that browsers use. Scripts are now evaluated independent of eachother and strictly as they arrive.

Setting Your JavaScript Free
****************************

The first step is releasing your JavaScript under a free license. If you are already using a free library, or you're not using any third-party libraries, it might only take a few minutes.

On your website, take a look at your HTML source. You can identify distinct pieces of JavaScript that might be free and some other that are nonfree.

This might be the case with an analytics tracker, social media widgets, and code that runs ads. Removing these pieces of code from your site is required to have the rest accepted as free. There are often alternatives to nonfree libraries or to third-party services:

  * If you have used nonfree third-party code as the base to write your own code, try to find a free alternative.

  * If you're using a third-party service such as an analytics service, replace it with a free alternative like Piwik.

  * If you can't find free JavaScript that has already been developed, write it yourself! Who knows, your own solution might be the start of a brilliant project!

License tags
============

LibreJS will allow non-trivial scripts to run as long as they use a free license.

In order for the license of a script to be recognized by LibreJS, it must be declared using a machine-readable license format.

This format is the same for both remote in-line scripts.

"// @license [magnet link] [identifier]" [Script here] "// @license-end"

"Identifier" is a name of a license from the following list and "magnet link" is that license's exact corresponding magnet link.

{
	'Apache-2.0':{
		'URL': 'http://www.apache.org/licenses/LICENSE-2.0',
		'Magnet link': 'magnet:?xt=urn:btih:8e4f440f4c65981c5bf93c76d35135ba5064d8b7&dn=apache-2.0.txt'
	},
	'Artistic-2.0':{
		'URL': 'http://www.perlfoundation.org/artistic_license_2_0',
		'Magnet link': 'magnet:?xt=urn:btih:54fd2283f9dbdf29466d2df1a98bf8f65cafe314&dn=artistic-2.0.txt'
	},
	'Boost':{
		'URL': 'http://www.boost.org/LICENSE_1_0.txt',
		'Magnet link': 'magnet:?xt=urn:btih:89a97c535628232f2f3888c2b7b8ffd4c078cec0&dn=Boost-1.0.txt'
	},
	'BSD-3-Clause':{
		'URL': 'http://opensource.org/licenses/BSD-3-Clause',
		'Magnet link': 'magnet:?xt=urn:btih:c80d50af7d3db9be66a4d0a86db0286e4fd33292&dn=bsd-3-clause.txt',
	},
	'CPAL-1.0':{
		'URL': 'http://opensource.org/licenses/cpal_1.0',
		'Magnet link': 'magnet:?xt=urn:btih:84143bc45939fc8fa42921d619a95462c2031c5c&dn=cpal-1.0.txt'
	},
	'CC0-1.0':{
		'URL': 'http://creativecommons.org/publicdomain/zero/1.0/legalcode',
		'Magnet link': 'magnet:?xt=urn:btih:90dc5c0be029de84e523b9b3922520e79e0e6f08&dn=cc0.txt'
	},
	'EPL-1.0':{
		'URL': 'http://www.eclipse.org/legal/epl-v10.html',
		'Magnet link': 'magnet:?xt=urn:btih:4c6a2ad0018cd461e9b0fc44e1b340d2c1828b22&dn=epl-1.0.txt'
	},
	'Expat':{
		'URL': 'http://www.jclark.com/xml/copying.txt',
		'Magnet link': 'magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt'
	},
	'FreeBSD':{
		'URL': 'http://www.freebsd.org/copyright/freebsd-license.html',
		'Magnet link': 'magnet:?xt=urn:btih:87f119ba0b429ba17a44b4bffcab33165ebdacc0&dn=freebsd.txt'
	},
	'GPL-2.0':{
		'URL': 'http://www.gnu.org/licenses/gpl-2.0.html',
		'Magnet link': 'magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt'
	},
	'GPL-3.0':{
		'URL': 'http://www.gnu.org/licenses/gpl-3.0.html',
		'Magnet link': 'magnet:?xt=urn:btih:1f739d935676111cfff4b4693e3816e664797050&dn=gpl-3.0.txt'
	},
	'LGPL-2.1':{
		'URL': 'http://www.gnu.org/licenses/lgpl-2.1.html',
		'Magnet link': 'magnet:?xt=urn:btih:5de60da917303dbfad4f93fb1b985ced5a89eac2&dn=lgpl-2.1.txt'
	},
	'LGPL-3.0':{
		'URL': 'http://www.gnu.org/licenses/lgpl-3.0.html',
		'Magnet link': 'magnet:?xt=urn:btih:0ef1b8170b3b615170ff270def6427c317705f85&dn=lgpl-3.0.txt'
	},
	'AGPL-3.0':{
		'URL': 'http://www.gnu.org/licenses/agpl-3.0.html',
		'Magnet link': 'magnet:?xt=urn:btih:0b31508aeb0634b347b8270c7bee4d411b5d4109&dn=agpl-3.0.txt'
	},
	'ISC':{
		'URL': 'https://www.isc.org/downloads/software-support-policy/isc-license/',
		'Magnet link': 'magnet:?xt=urn:btih:b8999bbaf509c08d127678643c515b9ab0836bae&dn=ISC.txt'
	},
	'MPL-2.0':{
		'URL': 'http://www.mozilla.org/MPL/2.0',
		'Magnet link': 'magnet:?xt=urn:btih:3877d6d54b3accd4bc32f8a48bf32ebc0901502a&dn=mpl-2.0.txt'
	},
	'UPL-1.0': {
		'URL': 'https://oss.oracle.com/licenses/upl/',
		'Magnet link': 'magnet:?xt=urn:btih:478974f4d41c3fa84c4befba25f283527fad107d&dn=upl-1.0.txt'
	},
	'WTFPL': {
		'URL': 'http://www.wtfpl.net/txt/copying/',
		'Magnet link': 'magnet:?xt=urn:btih:723febf9f6185544f57f0660a41489c7d6b4931b&dn=wtfpl.txt'
	},
	'Unlicense':{
		'URL': 'http://unlicense.org/UNLICENSE',
		'Magnet link': 'magnet:?xt=urn:btih:5ac446d35272cc2e4e85e4325b146d0b7ca8f50c&dn=unlicense.txt'
	},
	'X11':{
		'URL': 'http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3',
		'Magnet link': 'magnet:?xt=urn:btih:5305d91886084f776adcf57509a648432709a7c7&dn=x11.txt'
	},
	'Modified-BSD':{
		'URL': 'http://www.xfree86.org/current/LICENSE4.html',
		'Magnet link': 'magnet:?xt=urn:btih:12f2ec9e8de2a3b0002a33d518d6010cc8ab2ae9&dn=xfree86.txt'
	}
}

Undetected Free Licenses
========================

If you are using a free license that isn't detected by LibreJS and isn't listed in the previous section, please send a message to bug-librejs@gnu.org regarding this license, where code released under this license can be found, and where to find the license text and information.

Many free licenses are listed in this page: http://www.gnu.org/licenses/license-list.html

LibreJS Development Notes
*************************

Dependencies
============

LibreJS VERSION depends on a number of Node.js-based libraries that can be installed using the npm utility:

  $ npm install acorn-loose
  $ npm install jssha
  $ npm install browserify
  $ export PATH=$PATH:./node_modules/.bin

Building
========

To build the extension run:
  $ browserify main_background.js -o bundle.js

To build the extension plus create a .xpi package run:
  $ ./build.sh

To build the extension including the automated test suite (see TEST below) run:
  $ ./build.sh -t
or
  $ ./build.sh --test

Note: this build.sh script relies on no new source files being created.

Debugging
=========

To debug LibreJS, visit the special URL about:debugging. Click on `Enable add-on debugging` then `Load Temporary Add-on`. Navigate to LibreJS's unpacked source directory and select manifest.json.

Lines 39 and 40 in main_background.js assign two variables controlling the verbosity of dbg_print() statements. Make sure these are set to false before building a release.

Testing
=======

An automated test suite runs automatically in its own tab whenever the extension is loaded as a "Temporary add-on" from about:debugging. Otherwise (if included in the xpi) it can be launched from the UI by clicking the "Automated self test..." button.

Adding new whitelisted libraries
================================

The script index.js in ./hash_script generates the default whitelist. Run it with the following command:

node index.js > output

Then, just copy the contents of the file "output" to the appropriate place in main_background.js.

Releasing a new version
=======================

Update the version number in manifest.json.

Make sure debug statements are set to false on lines 39/40 in main_background.js.

Then run the build script build.sh.

Installation Requirements
*************************

Mozilla Browser
===============

You will need one of the many flavors of the Mozilla browser to use LibreJS. It can be installed on the following:

GNU IceCat,  Mozilla Firefox, Trisquel Abrowser, Debian Iceweasel.

LibreJS works on these browsers starting from version 60. We recommend that you use the latest version of your Mozilla browser. LibreJS has been tested on a GNU/Linux distribution, but it is compatible any operating system as long as you're using a compatible Mozilla browser.

LibreJS Internals
*****************

LibreJS intercepts HTTP responses and rewrites their contents after analyzing JavaScript within them. It does not remove script nodes and attributes from the page, but instead ``deactivates'' them by replacing their content with a commented notice.

LibreJS detects the most common cases using the HTTP response method described above, but in less common edge cases, or when running code locally, LibreJS cannot detect JavaScript during the response stage.

GNU Free Documentation License
******************************

     [file fdl.texi not included]