LibreJS 1 Overview 2 Disclaimer 3 Installation 4 How to Use 4.1 LibreJS in action 4.2 Script Blacklist/whitelist 4.3 Complaint Feature 4.4 Options 5 JavaScript Detection 6 Free Licenses Detection 7 Setting Your JavaScript Free 7.1 License tags 7.2 Undetected Free Licenses 7.3 Known limitations 8 LibreJS Development Notes 8.1 Dependencies 8.2 Building 8.3 Debugging 8.4 Testing 8.5 Headless testing 8.6 Headless compliance check 8.7 Adding new whitelisted libraries 8.8 Releasing a new version Appendix A Installation Requirements A.1 Mozilla Browser Appendix B LibreJS Internals Appendix C GNU Free Documentation License LibreJS ******* This manual is for GNU LibreJS (version 7.21, 17 September 2023). 1 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"(). 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. 2 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 . 3 Installation ************** You can install LibreJS directly using a generated ‘librejs.xpi’ file, or by building it from source (*Note LibreJS Development Notes::). You can also download it from or , but due to Mozilla's review process the download isn't always up to date. 4 How to Use ************ 4.1 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. 4.2 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. 4.3 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. 4.4 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. 5 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. 6 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. 7 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 Matomo. • 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! 7.1 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 ‘canonicalUrl’ field is that license's exact corresponding magnet link. The following json object which can be found in ‘./common/license_definitions.json’ file in the LibreJS code shows all the licensees recognised by LibreJS. { "AGPL-3.0": { "licenseName": "GNU AFFERO GENERAL PUBLIC LICENSE version 3", "identifier": "AGPL-3.0", "canonicalUrl": [ "http://www.gnu.org/licenses/agpl-3.0.html", "magnet:?xt=urn:btih:0b31508aeb0634b347b8270c7bee4d411b5d4109&dn=agpl-3.0.txt" ], "licenseFragments": [ { "text": " is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.", "type": "short" } ] }, "Apache-2.0": { "licenseName": "Apache License, Version 2.0", "identifier": "Apache-2.0", "canonicalUrl": [ "http://www.apache.org/licenses/LICENSE-2.0", "magnet:?xt=urn:btih:8e4f440f4c65981c5bf93c76d35135ba5064d8b7&dn=apache-2.0.txt" ], "licenseFragments": [ { "text": "Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0", "type": "short" } ] }, "Artistic-2.0": { "licenseName": "Artistic License 2.0", "identifier": "Artistic-2.0", "canonicalUrl": [ "http://www.perlfoundation.org/artistic_license_2_0", "magnet:?xt=urn:btih:54fd2283f9dbdf29466d2df1a98bf8f65cafe314&dn=artistic-2.0.txt" ], "licenseFragments": [] }, "BSD-2-Clause": { "licenseName": "BSD 2-Clause License", "identifier": "BSD-2-Clause", "canonicalUrl": [ "http://www.freebsd.org/copyright/freebsd-license.html", "magnet:?xt=urn:btih:87f119ba0b429ba17a44b4bffcab33165ebdacc0&dn=freebsd.txt" ], "licenseFragments": [ { "text": "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.", "type": "short" } ] }, "BSD-3-Clause": { "licenseName": "BSD 3-Clause License", "identifier": "BSD-3-Clause", "canonicalUrl": [ "http://opensource.org/licenses/BSD-3-Clause", "magnet:?xt=urn:btih:c80d50af7d3db9be66a4d0a86db0286e4fd33292&dn=bsd-3-clause.txt" ], "licenseFragments": [ { "text": "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 name of nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.", "type": "short" } ] }, "BSL-1.0": { "licenseName": "Boost Software License 1.0", "identifier": "BSL-1.0", "canonicalUrl": [ "http://www.boost.org/LICENSE_1_0.txt", "magnet:?xt=urn:btih:89a97c535628232f2f3888c2b7b8ffd4c078cec0&dn=Boost-1.0.txt" ], "licenseFragments": [ { "text": "Boost Software License Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the \"Software\") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following", "type": "short" } ] }, "CC-BY-1.0": { "licenseName": "Creative Commons Attribution 1.0 Generic", "identifier": "CC-BY-1.0", "canonicalUrl": [ "https://creativecommons.org/licenses/by/1.0/" ], "licenseFragments": [] }, "CC-BY-2.0": { "licenseName": "Creative Commons Attribution 2.0 Generic", "identifier": "CC-BY-2.0", "canonicalUrl": [ "https://creativecommons.org/licenses/by/2.0/" ], "licenseFragments": [] }, "CC-BY-2.5": { "licenseName": "Creative Commons Attribution 2.5 Generic", "identifier": "CC-BY-2.5", "canonicalUrl": [ "https://creativecommons.org/licenses/by/2.5/" ], "licenseFragments": [] }, "CC-BY-3.0": { "licenseName": "Creative Commons Attribution 3.0 Unported", "identifier": "CC-BY-3.0", "canonicalUrl": [ "https://creativecommons.org/licenses/by/3.0/" ], "licenseFragments": [] }, "CC-BY-4.0": { "licenseName": "Creative Commons Attribution 4.0 International", "identifier": "CC-BY-4.0", "canonicalUrl": [ "https://creativecommons.org/licenses/by/4.0/" ], "licenseFragments": [] }, "CC-BY-SA-1.0": { "licenseName": "Creative Commons Attribution-ShareAlike 1.0 Generic", "identifier": "CC-BY-SA-1.0", "canonicalUrl": [ "https://creativecommons.org/licenses/by-sa/1.0/" ], "licenseFragments": [] }, "CC-BY-SA-2.0": { "licenseName": "Creative Commons Attribution-ShareAlike 2.0 Generic", "identifier": "CC-BY-SA-2.0", "canonicalUrl": [ "https://creativecommons.org/licenses/by-sa/2.0/" ], "licenseFragments": [] }, "CC-BY-SA-2.5": { "licenseName": "Creative Commons Attribution-ShareAlike 2.5 Generic", "identifier": "CC-BY-SA-2.5", "canonicalUrl": [ "https://creativecommons.org/licenses/by-sa/2.5/" ], "licenseFragments": [] }, "CC-BY-SA-3.0": { "licenseName": "Creative Commons Attribution-ShareAlike 3.0 Unported", "identifier": "CC-BY-SA-3.0", "canonicalUrl": [ "https://creativecommons.org/licenses/by-sa/3.0/" ], "licenseFragments": [] }, "CC-BY-SA-4.0": { "licenseName": "Creative Commons Attribution-ShareAlike 4.0 International", "identifier": "CC-BY-SA-4.0", "canonicalUrl": [ "https://creativecommons.org/licenses/by-sa/4.0/" ], "licenseFragments": [] }, "CC0-1.0": { "licenseName": "Creative Commons CC0 1.0 Universal", "identifier": "CC0-1.0", "canonicalUrl": [ "http://creativecommons.org/publicdomain/zero/1.0/legalcode", "magnet:?xt=urn:btih:90dc5c0be029de84e523b9b3922520e79e0e6f08&dn=cc0.txt" ], "licenseFragments": [] }, "CECILL-2.0": { "licenseName": "CeCILL Free Software License Agreement v2.0", "identifier": "CECILL-2.0", "canonicalUrl": [ "https://www.cecill.info/licences/Licence_CeCILL_V2-en.txt", "magnet:?xt=urn:btih:dda0473d240d7febeac8fa265da27286ead0b1ce&dn=cecill-2.0.txt" ], "licenseFragments": [] }, "CPAL-1.0": { "licenseName": "Common Public Attribution License Version 1.0 (CPAL)", "identifier": "CPAL-1.0", "canonicalUrl": [ "http://opensource.org/licenses/cpal_1.0", "magnet:?xt=urn:btih:84143bc45939fc8fa42921d619a95462c2031c5c&dn=cpal-1.0.txt" ], "licenseFragments": [ { "text": "The contents of this file are subject to the Common Public Attribution License Version 1.0", "type": "short" }, { "text": "The term \"External Deployment\" means the use, distribution, or communication of the Original Code or Modifications in any way such that the Original Code or Modifications may be used by anyone other than You, whether those works are distributed or communicated to those persons or made available as an application intended for use over a network. As an express condition for the grants of license hereunder, You must treat any External Deployment by You of the Original Code or Modifications as a distribution under section 3.1 and make Source Code available under Section 3.2.", "type": "short" } ] }, "EPL-1.0": { "licenseName": "Eclipse Public License Version 1.0", "identifier": "EPL-1.0", "canonicalUrl": [ "http://www.eclipse.org/legal/epl-v10.html", "magnet:?xt=urn:btih:4c6a2ad0018cd461e9b0fc44e1b340d2c1828b22&dn=epl-1.0.txt" ], "licenseFragments": [ { "text": "THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE (\"AGREEMENT\"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.", "type": "short" } ] }, "Expat": { "licenseName": "Expat License (sometimes called MIT Licensed)", "identifier": "Expat", "canonicalUrl": [ "http://www.jclark.com/xml/copying.txt", "magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt" ], "licenseFragments": [ { "text": "Copyright Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.", "type": "short" } ] }, "FreeBSD": { "licenseName": "FreeBSD License", "identifi