@adguard/agtree 2.1.2 → 3.0.0-alpha.1

package/dist/cjs/utils/text-encoder-polyfill.js

@@ -0,0 +1,80 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+/* eslint-disable no-param-reassign */
+/* eslint-disable no-bitwise */
+/**
+ * @file Utility for encoding strings to byte sequences.
+ */
+/**
+ * Checks if the given code point is an ASCII code point.
+ *
+ * @param codePoint Code point to check.
+ * @returns `true` if the given code point is an ASCII code point, `false` otherwise.
+ * @see {@link https://infra.spec.whatwg.org/#ascii-code-point}
+ */
+const isAsciiCodePoint = (codePoint) => {
+    return codePoint >= 0x0000 && codePoint <= 0x007F;
+};
+const OFFSETS = [0xC0, 0xE0, 0xF0];
+/**
+ * Encodes an UTF-8 string into a byte sequence according to the WHATWG spec.
+ *
+ * @param str String to encode.
+ * @param buffer Buffer to write the encoded bytes to.
+ * @returns Number of bytes written to the buffer.
+ * @see {@link https://encoding.spec.whatwg.org/#utf-8-encoder}
+ * @note Bytes written maybe larger than the string length, but never smaller.
+ * For example, the string '你好' has a length of 2, but its byte representation has a length of 6.
+ */
+const encodeIntoPolyfill = (str, buffer) => {
+    const { length } = buffer;
+    let read = 0;
+    let written = 0;
+    for (let i = 0; i < str.length;) {
+        const codePoint = str.codePointAt(i) || 0;
+        let bytesNeeded = 1;
+        if (isAsciiCodePoint(codePoint)) {
+            if (written >= length)
+                break; // Stop if no space in buffer
+            buffer[written] = codePoint;
+            written += 1;
+            read += 1; // Increment read for ASCII
+            i += 1;
+        }
+        else {
+            if (codePoint >= 0x0080 && codePoint <= 0x07FF) {
+                bytesNeeded = 2;
+            }
+            else if (codePoint >= 0x0800 && codePoint <= 0xFFFF) {
+                bytesNeeded = 3;
+            }
+            else if (codePoint >= 0x10000 && codePoint <= 0x10FFFF) {
+                bytesNeeded = 4;
+            }
+            if (written + bytesNeeded - 1 >= length) {
+                // Stop if no space for the whole encoding
+                break;
+            }
+            let count = bytesNeeded - 1;
+            const offset = OFFSETS[bytesNeeded - 2];
+            buffer[written] = (codePoint >> (6 * count)) + offset;
+            written += 1;
+            while (count > 0) {
+                buffer[written] = 0x80 | ((codePoint >> (6 * (count - 1))) & 0x3F);
+                written += 1;
+                count -= 1;
+            }
+            read += codePoint >= 0x10000 ? 2 : 1; // Increment read by 1 or 2 depending on code point
+            i += codePoint >= 0x10000 ? 2 : 1; // Move i by 1 or 2
+        }
+    }
+    return { read, written };
+};
+
+exports.encodeIntoPolyfill = encodeIntoPolyfill;

package/dist/cjs/utils/type-guards.js

@@ -0,0 +1,52 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+/**
+ * Checks whether the given value is undefined.
+ *
+ * @param value Value to check.
+ *
+ * @returns `true` if the value is 'undefined', `false` otherwise.
+ */
+const isUndefined = (value) => {
+    return typeof value === 'undefined';
+};
+/**
+ * Checks whether the given value is null.
+ *
+ * @param value Value to check.
+ *
+ * @returns `true` if the value is 'null', `false` otherwise.
+ */
+const isNull = (value) => {
+    return value === null;
+};
+/**
+ * Checks whether the given value is a string.
+ *
+ * @param value Value to check.
+ * @returns `true` if the value is a string, `false` otherwise.
+ */
+const isString = (value) => {
+    return typeof value === 'string';
+};
+/**
+ * Checks whether the given value is an array of Uint8Arrays.
+ *
+ * @param value Value to check.
+ *
+ * @returns True if the value type is an array of Uint8Arrays.
+ */
+const isArrayOfUint8Arrays = (value) => {
+    return Array.isArray(value) && value.every((chunk) => chunk instanceof Uint8Array);
+};
+
+exports.isArrayOfUint8Arrays = isArrayOfUint8Arrays;
+exports.isNull = isNull;
+exports.isString = isString;
+exports.isUndefined = isUndefined;

package/dist/cjs/validator/constants.js

@@ -0,0 +1,222 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var adblockers = require('../utils/adblockers.js');
+var constants = require('../utils/constants.js');
+
+/**
+ * Prefixes for different adblockers to describe the platform-specific modifiers data
+ * stored in the yaml files.
+ */
+const BLOCKER_PREFIX = {
+    [adblockers.AdblockSyntax.Adg]: 'adg_',
+    [adblockers.AdblockSyntax.Ubo]: 'ubo_',
+    [adblockers.AdblockSyntax.Abp]: 'abp_',
+};
+/**
+ * Set of all allowed characters for app name except the dot `.`.
+ */
+const APP_NAME_ALLOWED_CHARS = new Set([
+    ...constants.CAPITAL_LETTERS,
+    ...constants.SMALL_LETTERS,
+    ...constants.NUMBERS,
+    constants.UNDERSCORE,
+]);
+/**
+ * Allowed methods for $method modifier.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#method-modifier}
+ */
+const ALLOWED_METHODS = new Set([
+    'connect',
+    'delete',
+    'get',
+    'head',
+    'options',
+    'patch',
+    'post',
+    'put',
+    'trace',
+]);
+/**
+ * Allowed stealth options for $stealth modifier.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#stealth-modifier}
+ */
+const ALLOWED_STEALTH_OPTIONS = new Set([
+    'searchqueries',
+    'donottrack',
+    '3p-cookie',
+    '1p-cookie',
+    '3p-cache',
+    '3p-auth',
+    'webrtc',
+    'push',
+    'location',
+    'flash',
+    'java',
+    'referrer',
+    'useragent',
+    'ip',
+    'xclientdata',
+    'dpi',
+]);
+/**
+ * Allowed CSP directives for $csp modifier.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives}
+ */
+const ALLOWED_CSP_DIRECTIVES = new Set([
+    'base-uri',
+    'child-src',
+    'connect-src',
+    'default-src',
+    'fenced-frame-src',
+    'font-src',
+    'form-action',
+    'frame-ancestors',
+    'frame-src',
+    'img-src',
+    'manifest-src',
+    'media-src',
+    'navigate-to',
+    'object-src',
+    'plugin-types',
+    'prefetch-src',
+    'referrer',
+    'report-to',
+    'report-uri',
+    'require-trusted-types-for',
+    'sandbox',
+    'script-src',
+    'script-src-attr',
+    'script-src-elem',
+    'style-src',
+    'style-src-attr',
+    'style-src-elem',
+    'trusted-types',
+    'upgrade-insecure-requests',
+    'worker-src',
+]);
+/**
+ * Allowed directives for $permissions modifier.
+ *
+ * @see {@link https://adguard.app/kb/general/ad-filtering/create-own-filters/#permissions-modifier}
+ */
+const ALLOWED_PERMISSION_DIRECTIVES = new Set([
+    'accelerometer',
+    'ambient-light-sensor',
+    'autoplay',
+    'battery',
+    'browsing-topics',
+    'camera',
+    'display-capture',
+    'document-domain',
+    'encrypted-media',
+    'execution-while-not-rendered',
+    'execution-while-out-of-viewport',
+    'fullscreen',
+    'gamepad',
+    'geolocation',
+    'gyroscope',
+    'hid',
+    'identity-credentials-get',
+    'idle-detection',
+    'join-ad-interest-group',
+    'local-fonts',
+    'magnetometer',
+    'microphone',
+    'midi',
+    'payment',
+    'picture-in-picture',
+    'publickey-credentials-create',
+    'publickey-credentials-get',
+    'run-ad-auction',
+    'screen-wake-lock',
+    'serial',
+    'speaker-selection',
+    'storage-access',
+    'usb',
+    'web-share',
+    'xr-spatial-tracking',
+]);
+/**
+ * One of available tokens for $permission modifier value.
+ *
+ * @see {@link https://w3c.github.io/webappsec-permissions-policy/#structured-header-serialization}
+ */
+const PERMISSIONS_TOKEN_SELF = 'self';
+/**
+ * One of allowlist values for $permissions modifier.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Permissions_Policy#allowlists}
+ */
+const EMPTY_PERMISSIONS_ALLOWLIST = `${constants.OPEN_PARENTHESIS}${constants.CLOSE_PARENTHESIS}`;
+/**
+ * Allowed directives for $referrerpolicy modifier.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy}
+ */
+const REFERRER_POLICY_DIRECTIVES = new Set([
+    'no-referrer',
+    'no-referrer-when-downgrade',
+    'origin',
+    'origin-when-cross-origin',
+    'same-origin',
+    'strict-origin',
+    'strict-origin-when-cross-origin',
+    'unsafe-url',
+]);
+/**
+ * Prefixes for error messages used in modifier validation.
+ */
+const VALIDATION_ERROR_PREFIX = {
+    BLOCK_ONLY: 'Only blocking rules may contain the modifier',
+    EXCEPTION_ONLY: 'Only exception rules may contain the modifier',
+    INVALID_CSP_DIRECTIVES: 'Invalid CSP directives for the modifier',
+    INVALID_LIST_VALUES: 'Invalid values for the modifier',
+    INVALID_NOOP: 'Invalid noop modifier',
+    INVALID_PERMISSION_DIRECTIVE: 'Invalid Permissions-Policy directive for the modifier',
+    INVALID_PERMISSION_ORIGINS: 'Origins in the value is invalid for the modifier and the directive',
+    INVALID_PERMISSION_ORIGIN_QUOTES: 'Double quotes should be used for origins in the value of the modifier',
+    INVALID_REFERRER_POLICY_DIRECTIVE: 'Invalid Referrer-Policy directive for the modifier',
+    MIXED_NEGATIONS: 'Simultaneous usage of negated and not negated values is forbidden for the modifier',
+    NO_CSP_VALUE: 'No CSP value for the modifier and the directive',
+    NO_CSP_DIRECTIVE_QUOTE: 'CSP directives should no be quoted for the modifier',
+    NO_UNESCAPED_PERMISSION_COMMA: 'Unescaped comma in the value is not allowed for the modifier',
+    // TODO: implement later for $scp and $permissions
+    // NO_VALUE_ONLY_FOR_EXCEPTION: 'Modifier without value can be used only in exception rules',
+    NOT_EXISTENT: 'Non-existent modifier',
+    NOT_NEGATABLE_MODIFIER: 'Non-negatable modifier',
+    NOT_NEGATABLE_VALUE: 'Values cannot be negated for the modifier',
+    NOT_SUPPORTED: 'The adblocker does not support the modifier',
+    REMOVED: 'Removed and no longer supported modifier',
+    VALUE_FORBIDDEN: 'Value is not allowed for the modifier',
+    VALUE_INVALID: 'Value is invalid for the modifier',
+    VALUE_REQUIRED: 'Value is required for the modifier',
+};
+/**
+ * Prefixes for error messages related to issues in the source YAML files' data.
+ */
+const SOURCE_DATA_ERROR_PREFIX = {
+    INVALID_VALUE_FORMAT_REGEXP: "Invalid regular expression in 'value_format' for the modifier",
+    NO_DEPRECATION_MESSAGE: "Property 'deprecation_message' is required for the 'deprecated' modifier",
+    NO_VALUE_FORMAT_FOR_ASSIGNABLE: "Property 'value_format' should be specified for the assignable modifier",
+};
+
+exports.ALLOWED_CSP_DIRECTIVES = ALLOWED_CSP_DIRECTIVES;
+exports.ALLOWED_METHODS = ALLOWED_METHODS;
+exports.ALLOWED_PERMISSION_DIRECTIVES = ALLOWED_PERMISSION_DIRECTIVES;
+exports.ALLOWED_STEALTH_OPTIONS = ALLOWED_STEALTH_OPTIONS;
+exports.APP_NAME_ALLOWED_CHARS = APP_NAME_ALLOWED_CHARS;
+exports.BLOCKER_PREFIX = BLOCKER_PREFIX;
+exports.EMPTY_PERMISSIONS_ALLOWLIST = EMPTY_PERMISSIONS_ALLOWLIST;
+exports.PERMISSIONS_TOKEN_SELF = PERMISSIONS_TOKEN_SELF;
+exports.REFERRER_POLICY_DIRECTIVES = REFERRER_POLICY_DIRECTIVES;
+exports.SOURCE_DATA_ERROR_PREFIX = SOURCE_DATA_ERROR_PREFIX;
+exports.VALIDATION_ERROR_PREFIX = VALIDATION_ERROR_PREFIX;

package/dist/cjs/validator/helpers.js

@@ -0,0 +1,49 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var constants$1 = require('../utils/constants.js');
+var constants = require('./constants.js');
+
+/**
+ * Validates the noop modifier (i.e. only underscores).
+ *
+ * @param value Value of the modifier.
+ *
+ * @returns True if the modifier is valid, false otherwise.
+ */
+const isValidNoopModifier = (value) => {
+    return value.split('').every((char) => char === constants$1.UNDERSCORE);
+};
+/**
+ * Returns invalid validation result with given error message.
+ *
+ * @param error Error message.
+ *
+ * @returns Validation result `{ valid: false, error }`.
+ */
+const getInvalidValidationResult = (error) => {
+    return {
+        valid: false,
+        error,
+    };
+};
+/**
+ * Returns invalid validation result which uses {@link VALIDATION_ERROR_PREFIX.VALUE_REQUIRED} as prefix
+ * and specifies the given `modifierName` in the error message.
+ *
+ * @param modifierName Modifier name.
+ *
+ * @returns Validation result `{ valid: false, error }`.
+ */
+const getValueRequiredValidationResult = (modifierName) => {
+    return getInvalidValidationResult(`${constants.VALIDATION_ERROR_PREFIX.VALUE_REQUIRED}: '${modifierName}'`);
+};
+
+exports.getInvalidValidationResult = getInvalidValidationResult;
+exports.getValueRequiredValidationResult = getValueRequiredValidationResult;
+exports.isValidNoopModifier = isValidNoopModifier;

package/dist/cjs/validator/index.js

@@ -0,0 +1,176 @@
+/*
+ * AGTree v3.0.0-alpha.1 (build date: Tue, 12 Nov 2024 16:11:58 GMT)
+ * (c) 2024 Adguard Software Ltd.
+ * Released under the MIT license
+ * https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree#readme
+ */
+'use strict';
+
+var adblockers = require('../utils/adblockers.js');
+var constants = require('../utils/constants.js');
+var constants$1 = require('./constants.js');
+var helpers = require('./helpers.js');
+var value = require('./value.js');
+var clone = require('../utils/clone.js');
+var modifiers = require('../compatibility-tables/modifiers.js');
+var platforms = require('../compatibility-tables/platforms.js');
+
+/**
+ * @file Validator for modifiers.
+ */
+const convertSyntaxToGenericPlatform = (syntax) => {
+    switch (syntax) {
+        case adblockers.AdblockSyntax.Adg:
+            return platforms.GenericPlatform.AdgAny;
+        case adblockers.AdblockSyntax.Ubo:
+            return platforms.GenericPlatform.UboAny;
+        case adblockers.AdblockSyntax.Abp:
+            return platforms.GenericPlatform.AbpAny;
+        default:
+            throw new Error(`Unknown syntax: ${syntax}`);
+    }
+};
+/**
+ * Fully checks whether the given `modifier` valid for given blocker `syntax`:
+ * is it supported by the blocker, deprecated, assignable, negatable, etc.
+ *
+ * @param syntax Adblock syntax to check the modifier for.
+ * 'Common' is not supported, it should be specific — 'AdGuard', 'uBlockOrigin', or 'AdblockPlus'.
+ * @param modifier Parsed modifier AST node.
+ * @param isException Whether the modifier is used in exception rule.
+ * Needed to check whether the modifier is allowed only in blocking or exception rules.
+ *
+ * @returns Result of modifier validation.
+ */
+const validateForSpecificSyntax = (syntax, modifier, isException) => {
+    if (syntax === adblockers.AdblockSyntax.Common) {
+        throw new Error(`Syntax should be specific, '${adblockers.AdblockSyntax.Common}' is not supported`);
+    }
+    const modifierName = modifier.name.value;
+    const blockerPrefix = constants$1.BLOCKER_PREFIX[syntax];
+    if (!blockerPrefix) {
+        throw new Error(`Unknown syntax: ${syntax}`);
+    }
+    // needed for validation of negation, assignment, etc.
+    const specificBlockerData = modifiers.modifiersCompatibilityTable.getFirst(modifierName, convertSyntaxToGenericPlatform(syntax));
+    // if no specific blocker data is found
+    if (!specificBlockerData) {
+        return helpers.getInvalidValidationResult(`${constants$1.VALIDATION_ERROR_PREFIX.NOT_SUPPORTED}: '${modifierName}'`);
+    }
+    // e.g. 'object-subrequest'
+    if (specificBlockerData.removed) {
+        return helpers.getInvalidValidationResult(`${constants$1.VALIDATION_ERROR_PREFIX.REMOVED}: '${modifierName}'`);
+    }
+    if (specificBlockerData.deprecated) {
+        if (!specificBlockerData.deprecationMessage) {
+            throw new Error(`${constants$1.SOURCE_DATA_ERROR_PREFIX.NO_DEPRECATION_MESSAGE}: '${modifierName}'`);
+        }
+        // prepare the message which is multiline in the yaml file
+        const warn = specificBlockerData.deprecationMessage.replace(constants.NEWLINE, constants.SPACE);
+        return {
+            valid: true,
+            warn,
+        };
+    }
+    if (specificBlockerData.blockOnly && isException) {
+        return helpers.getInvalidValidationResult(`${constants$1.VALIDATION_ERROR_PREFIX.BLOCK_ONLY}: '${modifierName}'`);
+    }
+    if (specificBlockerData.exceptionOnly && !isException) {
+        return helpers.getInvalidValidationResult(`${constants$1.VALIDATION_ERROR_PREFIX.EXCEPTION_ONLY}: '${modifierName}'`);
+    }
+    // e.g. '~domain=example.com'
+    if (!specificBlockerData.negatable && modifier.exception) {
+        return helpers.getInvalidValidationResult(`${constants$1.VALIDATION_ERROR_PREFIX.NOT_NEGATABLE_MODIFIER}: '${modifierName}'`);
+    }
+    // e.g. 'domain'
+    if (specificBlockerData.assignable) {
+        if (!modifier.value) {
+            // TODO: ditch value_optional after custom validators are implemented for value_format for all modifiers.
+            // This checking should be done in each separate custom validator,
+            // because $csp and $permissions without value can be used only in extension rules,
+            // but $cookie with no value can be used in both blocking and exception rules.
+            /**
+             * Some assignable modifiers can be used without a value,
+             * e.g. '@@||example.com^$cookie'.
+             */
+            if (specificBlockerData.valueOptional) {
+                return { valid: true };
+            }
+            // for other assignable modifiers the value is required
+            return helpers.getValueRequiredValidationResult(modifierName);
+        }
+        /**
+         * TODO: consider to return `{ valid: true, warn: 'Modifier value may be specified' }` (???)
+         * for $stealth modifier without a value
+         * but only after the extension will support value for $stealth:
+         * https://github.com/AdguardTeam/AdguardBrowserExtension/issues/2107
+         */
+        if (!specificBlockerData.valueFormat) {
+            throw new Error(`${constants$1.SOURCE_DATA_ERROR_PREFIX.NO_VALUE_FORMAT_FOR_ASSIGNABLE}: '${modifierName}'`);
+        }
+        return value.validateValue(modifier, specificBlockerData.valueFormat);
+    }
+    if (modifier?.value) {
+        // e.g. 'third-party=true'
+        return helpers.getInvalidValidationResult(`${constants$1.VALIDATION_ERROR_PREFIX.VALUE_FORBIDDEN}: '${modifierName}'`);
+    }
+    return { valid: true };
+};
+// TODO: move to modifier.ts and use index.ts only for exporting
+/**
+ * Modifier validator class.
+ */
+class ModifierValidator {
+    /**
+     * Simply checks whether the modifier exists in any adblocker.
+     *
+     * **Deprecated** and **removed** modifiers are considered as **existent**.
+     *
+     * @param modifier Already parsed modifier AST node.
+     *
+     * @returns True if modifier exists, false otherwise.
+     */
+    // eslint-disable-next-line class-methods-use-this
+    exists = (modifier) => {
+        return modifiers.modifiersCompatibilityTable.existsAny(modifier.name.value);
+    };
+    /**
+     * Checks whether the given `modifier` is valid for specified `syntax`.
+     *
+     * For `Common` syntax it simply checks whether the modifier exists.
+     * For specific syntax the validation is more complex —
+     * deprecated, assignable, negatable and other requirements are checked.
+     *
+     * @param syntax Adblock syntax to check the modifier for.
+     * @param rawModifier Modifier AST node.
+     * @param isException Whether the modifier is used in exception rule, default to false.
+     * Needed to check whether the modifier is allowed only in blocking or exception rules.
+     *
+     * @returns Result of modifier validation.
+     */
+    validate = (syntax, rawModifier, isException = false) => {
+        const modifier = clone.clone(rawModifier);
+        // special case: handle noop modifier which may be used as multiple underscores (not just one)
+        // https://adguard.com/kb/general/ad-filtering/create-own-filters/#noop-modifier
+        if (modifier.name.value.startsWith(constants.UNDERSCORE)) {
+            // check whether the modifier value contains something else besides underscores
+            if (!helpers.isValidNoopModifier(modifier.name.value)) {
+                return helpers.getInvalidValidationResult(`${constants$1.VALIDATION_ERROR_PREFIX.INVALID_NOOP}: '${modifier.name.value}'`);
+            }
+            // otherwise, replace the modifier value with single underscore.
+            // it is needed to check whether the modifier is supported by specific adblocker due to the syntax
+            modifier.name.value = constants.UNDERSCORE;
+        }
+        if (!this.exists(modifier)) {
+            return helpers.getInvalidValidationResult(`${constants$1.VALIDATION_ERROR_PREFIX.NOT_EXISTENT}: '${modifier.name.value}'`);
+        }
+        // for 'Common' syntax we cannot check something more
+        if (syntax === adblockers.AdblockSyntax.Common) {
+            return { valid: true };
+        }
+        return validateForSpecificSyntax(syntax, modifier, isException);
+    };
+}
+const modifierValidator = new ModifierValidator();
+
+exports.modifierValidator = modifierValidator;