path: root/docs/librejs.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename librejs.info
@include version.texi
@settitle GNU LibreJS @value{VERSION}

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

Copyright @copyright{} 2011 2012 2014 2015 Loic J. Duros, 2022 Yuchen Pei

@quotation
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''.
@end quotation
@end copying

@dircategory GNUzilla
@direntry
* LibreJS: (librejs).               Detect nonfree nontrivial in GNU Icecat
@end direntry

@titlepage
@title GNU LibreJS
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Loic J. Duros  (@email{librejs@@lduros.net})
@author Yuchen Pei (@email{ycp@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@contents


@node Top
@top LibreJS
This manual is for GNU LibreJS (version @value{VERSION}, @value{UPDATED}).

@menu
* Overview::                    General purpose and information.
* Disclaimer::                  Emphasize what LibreJS does and does not.
* Installation::                Installing LibreJS from source. 
* How to Use::                  How to use LibreJS in IceCat.
* JavaScript Detection::        How LibreJS detects nontrivial Javascript.
* Free Licenses Detection::     List of licenses detected by LibreJS.
* Setting Your JavaScript Free::  Information for website owners/maintainers.
* LibreJS Development Notes::   Documentation about the development of
                                        LibreJS itself.
* Installation Requirements::   Requirements to build and install LibreJS.
* LibreJS Internals::           How LibreJS works under the hood.
* GNU Free Documentation License::  Copying and sharing this documentation.








@end menu

@node Overview
@chapter Overview

@cindex 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"(@url{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.


@node Disclaimer
@chapter Disclaimer

@cindex disclaimer

@itemize @bullet
@item
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.

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

@end itemize

@node Installation
@chapter Installation
@cindex Installation

You can install LibreJS directly using a generated @file{librejs.xpi}
file, or by building it from source (@xref{LibreJS Development Notes}).

You can also download it from
@url{https://www.gnu.org/software/librejs/} or
@url{https://addons.mozilla.org/addon/librejs/}, but due to Mozilla's
review process the download isn't always up to date.

@node How to Use
@chapter How to Use

@section 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.

@section 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.

@section 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, @dots{})

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.

@section Options

@table @dfn

You can manage LibreJS's preferences either from the extension's entry in your
browser's Add-ons Manager page (@code{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.

@item 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.

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

@item Complaint email body
Configure the default body used in complaint emails.
@end table

@node JavaScript Detection
@chapter JavaScript Detection
@cindex javascript

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:
@itemize @bullet
  @item
  It must call only primitives.
  @item
  The number of conditionals and loops must be at most 3.
  @item
  It does not declare an array more than 50 elements long.
  @item
  It must not call itself
@end itemize

For the rest of the script, outside of function definitions:
@itemize @bullet
  @item
  It must call only primitives and functions defined above in the page.
  @item
  The number of conditionals and loops must be at most 3.
@end itemize

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

Allowed primitives exclude:
  @itemize @bullet
    @item
    eval()
    @item
    ajax
    @item
    calling methods with the square bracket notation
    @item
    altering the dom
    @item 
    most other items found as methods of the `.window` object.
  @end itemize     


@node Free Licenses Detection
@chapter Free Licenses Detection
@cindex freelicenses

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.

@node Setting Your JavaScript Free
@chapter 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:

@itemize @bullet

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

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

@item
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!
@end itemize


@section 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 the
magnet link in the @code{canonicalUrl} field is that license's exact
corresponding magnet link.

The following json object which can be found in
@code{./common/license_definitions.json} file in the LibreJS code shows
all the licensees recognised by LibreJS.

@verbatiminclude ../common/license_definitions.json

@section 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
@email{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:
@url{http://www.gnu.org/licenses/license-list.html}

@section Known limitations

Service workers may cause false positives and false negatives, and
there are multiple ways to disable them.  The cleanest way is by
setting @code{dom.serviceWorkers.enabled} to @code{false} in the
@code{about:config} page of your browser.

@node LibreJS Development Notes
@chapter LibreJS Development Notes

@section Dependencies

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

@verbatim
  $ npm install acorn-loose jassha browserify
  $ export PATH=$PATH:./node_modules/.bin
@end verbatim

@section Building

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

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

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

Note: this @file{build.sh} script relies on no new source files being created.

@section Debugging

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

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

@section Testing

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

@section Headless testing

To launch the test suite from the command line, ensure the xpi package
has been built with automated test suite. Then install
selenium-webdriver and geckodriver, and ensure the latter is in $PATH:
@verbatim
  $ npm install selenium-webdriver geckodriver
  $ export PATH=$PATH:./node_modules/.bin
@end verbatim

Now you can invoke the test with
@verbatim
  $ node ./utilities/test.js
@end verbatim

which will print out a summary of test results.

Optionally you can also test with a chosen seed
@verbatim
  $ node ./utilities/test.js 12345
@end verbatim

@section Headless compliance check
To check whether a webpage is LibreJS-compliant from the command line,
ensure that the xpi package has been built WITHOUT the automated test
suite. Then install selenium-webdriver and geckodriver, and ensure the
latter is in $PATH:
@verbatim
  $ npm install selenium-webdriver
  $ npm install geckodriver
  $ export PATH=$PATH:./node_modules/.bin
@end verbatim

Now you can check a webpage for compliance with
@verbatim
  $ node ./utilities/compliance.js <url>
@end verbatim

It will open the url in a headless browser, save a screenshot, and
output the compliance check result.

For example, to check the compliance of the FSF homepage, do
@verbatim
  $ node ./utilities/compliance.js https://fsf.org
@end verbatim

@section Adding new whitelisted libraries

The script index.js in @file{./utilities/hash_script} generates the default
whitelist. Run it with the following command:

@command{node index.js > output}

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

@section Releasing a new version

@enumerate

@item
Run some tests and make sure they all pass.

@item
Make sure debug statements are set to false on lines 39/40 in
@file{main_background.js}.

@item
Update the version number in manifest.json.

@item
Add user-visible changes to @file{NEWS}.

@item
Update the version number in @file{docs/version.texi}.

@item
Commit and tag the release, and push to Savannah.

@item
Run build.sh in a clean repo and upload the generated
@file{librejs.xpi} to Mozilla.

@item
Fix any validation warnings or errors during the upload in the
previous step, test, re-tag the release, re-push to Savannah, and
re-upload to Mozilla.

@item
Generate docs from @file{docs/} using gnulib gendocs.sh script
(@url{https://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=build-aux/gendocs.sh}),
and commit the docs to the website cvs repo under the @file{manual/}
directory.  This will update the docs at
@url{https://www.gnu.org/software/librejs/manual/}.

@item
From this step onwards it is required that Mozilla has approved the
new version.  Download the signed xpi from Mozilla website
(@url{https://addons.mozilla.org/en-US/firefox/addon/librejs/}).

@item
Follow the steps in Information for GNU Maintainer to upload the
source tar ball (downloadable from cgit) and the signed xpi to the GNU
FTP server.

@item
Update the download links on the LibreJS webpage
(@url{https://gnu.org/s/librejs}) to point to the new release.

@item
Announce to info-gnu, help-librejs, bug-librejs mailing lists, and the
Savannah project News section.

@item
(Optional) Update projects that uses LibreJS like gnuzilla and
abrowser.
@end enumerate

@node Installation Requirements
@appendix Installation Requirements


@appendixsec 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.

@node LibreJS Internals
@appendix 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.


@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi


@bye