add trusted scriptlets to readme AG-16962

Merge in ADGUARD-FILTERS/scriptlets from fix/AG-16962 to release/v1.7

Squashed commit of the following:

commit 4f4e49c
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Fri Nov 11 18:34:29 2022 +0300

    improve allowed sources description

commit 0f7ffea
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Fri Nov 11 15:54:27 2022 +0300

    move tag types to helpers

commit d337805
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Fri Nov 11 15:49:25 2022 +0300

    fix quotes

commit 9d78d55
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Fri Nov 11 13:33:14 2022 +0300

    update description & swap tag to trustedScriptlet

commit 68ea2d8
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Nov 10 15:50:28 2022 +0300

    fix link

commit 3b3dd16
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Nov 10 15:22:06 2022 +0300

    improve readme

commit 9354743
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Nov 10 14:13:11 2022 +0300

    update tag on all trusteds and update about-trusteds

commit c252d85
Merge: 9863ab2 356dd0d
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Nov 10 13:58:12 2022 +0300

    Merge branch 'release/v1.7' into fix/AG-16962

commit 9863ab2
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Nov 10 13:48:39 2022 +0300

    add trustedscriptlet tag

commit 69dc7c0
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Nov 10 01:50:02 2022 +0300

    build separate wiki page for trusted scriptlets

commit c4a87c6
Merge: a93acba 0fb636b
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Nov 10 00:14:33 2022 +0300

    Merge branch 'release/v1.7' into fix/AG-16962

commit a93acba
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Thu Nov 10 00:05:54 2022 +0300

    fix tables of contents back, fix typo

commit a60a9c7
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Wed Oct 26 17:37:34 2022 +0300

    move trusteds under Scriptlets

commit 2adca6a
Author: Stanislav A <s.atroschenko@adguard.com>
Date:   Fri Oct 14 17:33:41 2022 +0300

    add trusted scriptlets to readme

README.md

@@ -6,6 +6,9 @@ AdGuard's Scriptlets and Redirect resources library which provides extended capa
     * [Syntax](#scriptlet-syntax)
     * [Available scriptlets](https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/about-scriptlets.md#scriptlets)
     * [Scriptlets compatibility table](https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/compatibility-table.md#scriptlets)
+    * [Trusted scriptlets](#trusted-scriptlets)
+        * [Restriction](#trusted-scriptlets-restriction)
+        * [Available trusted scriptlets](https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/about-trusted-scriptlets.md#trusted-scriptlets)
 * [Redirect resources](#redirect-resources)
     * [Syntax](#redirect-syntax)
     * [Available redirect resources](https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/about-redirects.md#redirect-resources)
@@ -49,12 +52,29 @@ example.org#%#//scriptlet('abort-on-property-read', 'alert')
 example.org#%#//scriptlet('remove-class', 'branding', 'div[class^="inner"]')
 ```
 
-This rule applies the `abort-on-property-read` scriptlet on all pages of `example.org` and its subdomains, and passes one orgument to it (`alert`).
+This rule applies the `abort-on-property-read` scriptlet on all pages of `example.org` and its subdomains, and passes one argument to it (`alert`).
 
 * **[Scriptlets list](https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/about-scriptlets.md#scriptlets)**
 * **[Scriptlets compatibility table](https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/compatibility-table.md#scriptlets)**
 
 
+### <a id="trusted-scriptlets"></a> Trusted scriptlets
+
+Trusted scriptlets are scriptlets with extended functionality. Their names are prefixed with `trusted-`, e.g `trusted-click-element`, to be easily distinguished from common scriptlets.
+
+#### <a id="trusted-scriptlets-restriction"></a> Restriction
+
+Trusted scriptlets application must be restricted due to dangerous nature of their capabilities. 
+Allowed sources of trusted scriptlets are:
+* filters created by AdGuard Team,
+* custom filters which were installed as `trusted`,
+* user rules.
+
+> Trusted scriptlets has no compatibility table as they are not compatible with any other blocker.
+
+**[Trusted scriptlets list](https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/about-trusted-scriptlets.md#trusted-scriptlets)**
+
+
 ## Redirect resources
 
 AdGuard is able to redirect web requests to a local "resource".

scripts/build-docs.js

@@ -8,9 +8,13 @@ const { getDataFromFiles } = require('./helpers');
 const {
     WIKI_DIR_PATH,
     scriptletsFilenames,
+    trustedScriptletsFilenames,
     redirectsFilenames,
     SCRIPTLETS_SRC_RELATIVE_DIR_PATH,
     REDIRECTS_SRC_RELATIVE_DIR_PATH,
+    SCRIPTLET_TYPE,
+    TRUSTED_SCRIPTLET_TYPE,
+    REDIRECT_TYPE,
 } = require('./constants');
 
 const STATIC_REDIRECTS_FILENAME = 'static-redirects.yml';
@@ -28,10 +32,16 @@ const blockingRedirectsPath = path.resolve(
 );
 
 const ABOUT_SCRIPTLETS_FILENAME = 'about-scriptlets.md';
+const ABOUT_TRUSTED_SCRIPTLETS_FILENAME = 'about-trusted-scriptlets.md';
 const ABOUT_REDIRECTS_FILENAME = 'about-redirects.md';
 
 const aboutScriptletsPath = path.resolve(__dirname, WIKI_DIR_PATH, ABOUT_SCRIPTLETS_FILENAME);
 const aboutRedirectsPath = path.resolve(__dirname, WIKI_DIR_PATH, ABOUT_REDIRECTS_FILENAME);
+const aboutTrustedScriptletsPath = path.resolve(
+    __dirname,
+    WIKI_DIR_PATH,
+    ABOUT_TRUSTED_SCRIPTLETS_FILENAME,
+);
 
 /**
  * Collects required comments from files and
@@ -42,17 +52,31 @@ const manageDataFromFiles = () => {
         scriptletsFilenames,
         SCRIPTLETS_SRC_RELATIVE_DIR_PATH,
     );
+
+    const dataFromTrustedScriptletsFiles = getDataFromFiles(
+        trustedScriptletsFilenames,
+        SCRIPTLETS_SRC_RELATIVE_DIR_PATH,
+    );
+
     const dataFromRedirectsFiles = getDataFromFiles(
         redirectsFilenames,
         REDIRECTS_SRC_RELATIVE_DIR_PATH,
     );
 
-    const fullData = dataFromScriptletsFiles.concat(dataFromRedirectsFiles).flat(Infinity);
+    const fullData = dataFromScriptletsFiles
+        .concat(dataFromTrustedScriptletsFiles)
+        .concat(dataFromRedirectsFiles)
+        .flat(Infinity);
 
-    const scriptletsData = fullData.filter(({ type }) => type === 'scriptlet');
-    const redirectsData = fullData.filter(({ type }) => type === 'redirect');
+    const scriptletsData = fullData.filter(({ type }) => type === SCRIPTLET_TYPE);
+    const trustedScriptletsData = fullData.filter(({ type }) => type === TRUSTED_SCRIPTLET_TYPE);
+    const redirectsData = fullData.filter(({ type }) => type === REDIRECT_TYPE);
 
-    return { scriptletsData, redirectsData };
+    return {
+        scriptletsData,
+        trustedScriptletsData,
+        redirectsData,
+    };
 };
 
 /**
@@ -171,6 +195,9 @@ const buildWikiAboutPages = () => {
     try {
         const filesData = manageDataFromFiles();
         const scriptletsMarkdownData = getMarkdownData(filesData.scriptletsData);
+
+        const trustedScriptletsMarkdownData = getMarkdownData(filesData.trustedScriptletsData);
+
         const redirectsMarkdownData = getMarkdownData(filesData.redirectsData);
         const staticRedirectsMarkdownData = getMarkdownDataForStaticRedirects();
         const blockingRedirectsMarkdownData = getMarkdownDataForBlockingRedirects();
@@ -183,6 +210,15 @@ ${scriptletsMarkdownData.body}`;
             scriptletsPageContent,
         );
 
+        // eslint-disable-next-line max-len
+        const trustedScriptletsPageContent = `## <a id="trusted-scriptlets"></a> Available Trusted Scriptlets
+${trustedScriptletsMarkdownData.list}* * *
+${trustedScriptletsMarkdownData.body}`;
+        fs.writeFileSync(
+            path.resolve(__dirname, aboutTrustedScriptletsPath),
+            trustedScriptletsPageContent,
+        );
+
         /* eslint-disable max-len */
         const redirectsPageContent = `## <a id="redirect-resources"></a> Available Redirect resources
 ${staticRedirectsMarkdownData.list}${redirectsMarkdownData.list}${blockingRedirectsMarkdownData.list}* * *

scripts/constants.js

@@ -22,6 +22,8 @@ const SRC_REDIRECTS_SUB_DIR = 'redirects';
 const SCRIPTLETS_SRC_RELATIVE_DIR_PATH = `${SRC_RELATIVE_DIR}/${SRC_SCRIPTLETS_SUB_DIR}`;
 const REDIRECTS_SRC_RELATIVE_DIR_PATH = `${SRC_RELATIVE_DIR}/${SRC_REDIRECTS_SUB_DIR}`;
 
+const TRUSTED_SCRIPTLETS_PREFIX = 'trusted-';
+
 // files which are not scriptlets in the source directory
 const NON_SCRIPTLETS_FILES = [
     'index.js',
@@ -30,8 +32,15 @@ const NON_SCRIPTLETS_FILES = [
     'scriptlets-wrapper.js',
     'scriptlets-umd-wrapper.js',
 ];
+
+const isUtilityFileName = (filename) => NON_SCRIPTLETS_FILES.includes(filename);
+const isTrustedScriptletsFilename = (filename) => filename.startsWith(TRUSTED_SCRIPTLETS_PREFIX);
+
 const scriptletsFilenames = getFilesList(SCRIPTLETS_SRC_RELATIVE_DIR_PATH)
-    .filter((el) => !NON_SCRIPTLETS_FILES.includes(el));
+    .filter((el) => !isUtilityFileName(el) && !isTrustedScriptletsFilename(el));
+
+const trustedScriptletsFilenames = getFilesList(SCRIPTLETS_SRC_RELATIVE_DIR_PATH)
+    .filter((el) => isTrustedScriptletsFilename(el));
 
 // files which are not redirects in the source directory
 const NON_REDIRECTS_FILES = [
@@ -49,5 +58,6 @@ module.exports = {
     SCRIPTLETS_SRC_RELATIVE_DIR_PATH,
     REDIRECTS_SRC_RELATIVE_DIR_PATH,
     scriptletsFilenames,
+    trustedScriptletsFilenames,
     redirectsFilenames,
 };

scripts/helpers.js

@@ -2,6 +2,10 @@ const path = require('path');
 const fs = require('fs-extra');
 const dox = require('dox');
 
+const SCRIPTLET_TYPE = 'scriptlet';
+const TRUSTED_SCRIPTLET_TYPE = 'trustedScriptlet';
+const REDIRECT_TYPE = 'redirect';
+
 /**
  * Asynchronously writes data to a file, replacing the file if it already exists.
  *
@@ -33,7 +37,7 @@ const getFilesList = (relativeDirPath) => {
 
 /**
  * Returns parsed tags data which we use to describe the sources:
- * - `@scriptlet`/`@redirect` to describe the type and name of source;
+ * - `@scriptlet`/`trustedScriptlet`/`@redirect` to describe the type and name of source;
  * - `@description` actual description for scriptlet or redirect.
  * required comments from file.
  * In one file might be comments describing scriptlet and redirect as well.
@@ -54,8 +58,9 @@ const getDescribingCommentTags = (filePath) => {
                 return false;
             }
             const [base] = tags;
-            return base?.type === 'scriptlet'
-                || base?.type === 'redirect';
+            return base?.type === SCRIPTLET_TYPE
+                || base?.type === TRUSTED_SCRIPTLET_TYPE
+                || base?.type === REDIRECT_TYPE;
         });
 
     if (describingComment.length === 0) {
@@ -122,4 +127,7 @@ module.exports = {
     writeFile,
     getFilesList,
     getDataFromFiles,
+    SCRIPTLET_TYPE,
+    TRUSTED_SCRIPTLET_TYPE,
+    REDIRECT_TYPE,
 };

src/scriptlets/trusted-click-element.js

@@ -6,7 +6,7 @@ import {
 
 /* eslint-disable max-len */
 /**
- * @scriptlet trusted-click-element
+ * @trustedScriptlet trusted-click-element
  *
  * @description
  * Clicks selected elements in a strict sequence, ordered by selectors passed, and waiting for them to render in the DOM first.

src/scriptlets/trusted-replace-fetch-response.js

@@ -20,7 +20,7 @@ import {
 
 /* eslint-disable max-len */
 /**
- * @scriptlet trusted-replace-fetch-response
+ * @trustedScriptlet trusted-replace-fetch-response
  *
  * @description
  * Replaces response text content of `fetch` requests if **all** given parameters match.

src/scriptlets/trusted-replace-xhr-response.js

@@ -18,7 +18,7 @@ import {
 
 /* eslint-disable max-len */
 /**
- * @scriptlet trusted-replace-xhr-response
+ * @trustedScriptlet trusted-replace-xhr-response
  *
  * @description
  * Replaces response content of `xhr` requests if **all** given parameters match.

src/scriptlets/trusted-set-cookie.js

@@ -12,7 +12,7 @@ import {
 
 /* eslint-disable max-len */
 /**
- * @scriptlet trusted-set-cookie
+ * @trustedScriptlet trusted-set-cookie
  *
  * @description
  * Sets a cookie with arbitrary name and value, with optional path

src/scriptlets/trusted-set-local-storage-item.js

@@ -7,7 +7,7 @@ import {
 
 /* eslint-disable max-len */
 /**
- * @scriptlet trusted-set-local-storage-item
+ * @trustedScriptlet trusted-set-local-storage-item
  *
  * @description
  * Adds item with arbitrary key and value to localStorage object, or updates the value of the key if it already exists.