@adguard/dnr-converter 2.0.0 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +62 -3
  2. package/dist/cli.cjs +52148 -47533
  3. package/dist/constants.js +4 -1
  4. package/dist/errors/conversion-errors/index.js +3 -2
  5. package/dist/errors/conversion-errors/unexpected-conversion-error.js +23 -0
  6. package/dist/errors/scan-errors.js +39 -0
  7. package/dist/errors/unavailable-sources-errors/unavailable-filter-source-error.js +10 -1
  8. package/dist/filter-converter/filter-converter.js +151 -6
  9. package/dist/index.js +5 -1
  10. package/dist/package.json.js +1 -1
  11. package/dist/rule/rule-badfilter.js +144 -55
  12. package/dist/rule/rule-validator.js +56 -6
  13. package/dist/rule/rule.js +95 -9
  14. package/dist/rule-converters/action-kind.js +121 -0
  15. package/dist/rule-converters/csp-condition-coverage.js +268 -0
  16. package/dist/rule-converters/csp-converter.js +132 -11
  17. package/dist/rule-converters/csp-rules-resolver.js +417 -0
  18. package/dist/rule-converters/regular-rule-converter.js +489 -129
  19. package/dist/rule-converters/rules-converter.js +75 -7
  20. package/dist/rule-converters/rules-grouper.js +5 -3
  21. package/dist/rules-scanner/rules-scanner.js +124 -56
  22. package/dist/ruleset/ruleset-with-source-map.js +5 -1
  23. package/dist/types/src/errors/conversion-errors/index.d.ts +7 -2
  24. package/dist/types/src/errors/conversion-errors/unexpected-conversion-error.d.ts +21 -0
  25. package/dist/types/src/errors/scan-errors.d.ts +38 -0
  26. package/dist/types/src/errors/unavailable-sources-errors/unavailable-filter-source-error.d.ts +9 -1
  27. package/dist/types/src/filter-converter/filter-converter-options.d.ts +18 -1
  28. package/dist/types/src/filter-converter/filter-converter.d.ts +83 -6
  29. package/dist/types/src/index.d.ts +7 -3
  30. package/dist/types/src/rule/rule-validator.d.ts +21 -0
  31. package/dist/types/src/rule/rule.d.ts +52 -2
  32. package/dist/types/src/rule-converters/csp-converter.d.ts +12 -0
  33. package/dist/types/src/ruleset/ruleset-with-source-map.d.ts +14 -0
  34. package/dist/utils/string.js +27 -1
  35. package/package.json +6 -6
  36. package/dist/rule/string-utils.js +0 -49
@@ -4,6 +4,27 @@ import { UnsupportedModifierError } from '../errors/conversion-errors/unsupporte
4
4
  import { OPTION_NAMES } from './option-names.js';
5
5
  import { REMOVEHEADER_COMPATIBLE_MODIFIERS } from './rule.js';
6
6
 
7
+ /**
8
+ * Modifiers that only refine the matching condition of a CSP exception.
9
+ */ const CSP_EXCEPTION_COMPATIBLE_MODIFIERS = new Set([
10
+ OPTION_NAMES.CSP,
11
+ OPTION_NAMES.THIRD_PARTY,
12
+ OPTION_NAMES.MATCH_CASE,
13
+ OPTION_NAMES.IMPORTANT,
14
+ OPTION_NAMES.HEADER,
15
+ OPTION_NAMES.METHOD,
16
+ OPTION_NAMES.SCRIPT,
17
+ OPTION_NAMES.STYLESHEET,
18
+ OPTION_NAMES.SUBDOCUMENT,
19
+ OPTION_NAMES.OBJECT,
20
+ OPTION_NAMES.IMAGE,
21
+ OPTION_NAMES.XMLHTTPREQUEST,
22
+ OPTION_NAMES.MEDIA,
23
+ OPTION_NAMES.FONT,
24
+ OPTION_NAMES.WEBSOCKET,
25
+ OPTION_NAMES.OTHER,
26
+ OPTION_NAMES.PING
27
+ ]);
7
28
  /**
8
29
  * Class for validating network rules against DNR (declarative network request) constraints.
9
30
  * Ported from tsurlfilter's `RuleDeclarativeValidator`.
@@ -66,11 +87,6 @@ import { REMOVEHEADER_COMPATIBLE_MODIFIERS } from './rule.js';
66
87
  * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
67
88
  */ static checkRemoveHeaderModifierFn(rule, // eslint-disable-next-line @typescript-eslint/no-unused-vars
68
89
  name) {
69
- const value = rule.advancedModifierValue;
70
- // $removeheader without a value is valid
71
- if (!value) {
72
- return null;
73
- }
74
90
  // Check if the header resolves to a valid (non-forbidden) name
75
91
  const hasValidResponseHeader = rule.getApplicableHeaderName(false) !== null;
76
92
  const hasValidRequestHeader = rule.getApplicableHeaderName(true) !== null;
@@ -182,13 +198,17 @@ import { REMOVEHEADER_COMPATIBLE_MODIFIERS } from './rule.js';
182
198
  * $permissions.
183
199
  *
184
200
  * @param rule Network rule.
201
+ * @param allowCspException CSP exception validation flag.
185
202
  *
186
203
  * @returns Boolean flag - `false` if the rule does not require conversion
187
204
  * and `true` if the rule is convertible.
188
205
  *
189
206
  * @throws Error with type {@link UnsupportedModifierError} if the rule is not convertible.
190
- */ static shouldConvertRule(rule) {
207
+ */ static validateRule(rule, allowCspException) {
191
208
  for (const modifier of rule.enabledModifiers){
209
+ if (allowCspException && modifier === OPTION_NAMES.CSP) {
210
+ continue;
211
+ }
192
212
  const validator = this.optionsValidators[modifier];
193
213
  if (!validator) {
194
214
  continue;
@@ -214,6 +234,36 @@ import { REMOVEHEADER_COMPATIBLE_MODIFIERS } from './rule.js';
214
234
  }
215
235
  return true;
216
236
  }
237
+ /**
238
+ * Checks if a network rule can be converted to a declarative format or not.
239
+ *
240
+ * @param rule Network rule.
241
+ *
242
+ * @returns Boolean flag indicating whether the rule should be converted.
243
+ *
244
+ * @throws Error with type {@link UnsupportedModifierError} if the rule is not convertible.
245
+ */ static shouldConvertRule(rule) {
246
+ return RuleDeclarativeValidator.validateRule(rule, false);
247
+ }
248
+ /**
249
+ * Checks whether a CSP exception can enter CSP resolution.
250
+ *
251
+ * @param rule CSP exception rule.
252
+ *
253
+ * @returns True if the rule can enter CSP resolution.
254
+ *
255
+ * @throws Error with type {@link UnsupportedModifierError} if another modifier is not supported.
256
+ */ static shouldProcessCspException(rule) {
257
+ if (!rule.allowlist || !rule.isModifierEnabled(OPTION_NAMES.CSP)) {
258
+ return false;
259
+ }
260
+ for (const modifier of rule.enabledModifiers){
261
+ if (!CSP_EXCEPTION_COMPATIBLE_MODIFIERS.has(modifier)) {
262
+ throw new UnsupportedModifierError(`$csp exception is not compatible with $${modifier}`, rule);
263
+ }
264
+ }
265
+ return RuleDeclarativeValidator.validateRule(rule, true);
266
+ }
217
267
  }
218
268
  /**
219
269
  * Checks if the $cookie values in the provided network rule
package/dist/rule/rule.js CHANGED
@@ -416,11 +416,11 @@ import { RulePriority } from './rule-priority.js';
416
416
  const rules = [];
417
417
  for(let i = 0; i < rulesConvertedToAGSyntax.length; i += 1){
418
418
  const ruleNode = rulesConvertedToAGSyntax[i];
419
- if (ruleNode.category !== RuleCategory.Network || ruleNode.type !== NetworkRuleType.NetworkRule) {
419
+ if (!Rule.isNetworkRuleNode(ruleNode)) {
420
420
  continue;
421
421
  }
422
422
  try {
423
- rules.push(new Rule(filterId, ruleIndex, ruleNode));
423
+ rules.push(new Rule(filterId, ruleIndex, ruleNode, text));
424
424
  } catch (e) {
425
425
  throw new Error(// eslint-disable-next-line max-len
426
426
  `Cannot create Rule from filter "${filterId}" and rule "${text}": ${getErrorMessage(e)}`);
@@ -443,6 +443,7 @@ import { RulePriority } from './rule-priority.js';
443
443
  * general.
444
444
  */ static parseFromNode(filterListId, index, node) {
445
445
  let rulesConvertedToAG;
446
+ const originalText = Rule.getWrittenText(node);
446
447
  try {
447
448
  const conversionResult = RuleConverter.convertToAdg(node);
448
449
  if (conversionResult.isConverted) {
@@ -459,11 +460,11 @@ import { RulePriority } from './rule-priority.js';
459
460
  const rules = [];
460
461
  for(let i = 0; i < rulesConvertedToAG.length; i += 1){
461
462
  const ruleNode = rulesConvertedToAG[i];
462
- if (ruleNode.category !== RuleCategory.Network || ruleNode.type !== NetworkRuleType.NetworkRule) {
463
+ if (!Rule.isNetworkRuleNode(ruleNode)) {
463
464
  continue;
464
465
  }
465
466
  try {
466
- rules.push(new Rule(filterListId, index, ruleNode));
467
+ rules.push(new Rule(filterListId, index, ruleNode, originalText));
467
468
  } catch (e) {
468
469
  let msg = `"${getErrorMessage(e)}" in the rule: `;
469
470
  try {
@@ -478,16 +479,50 @@ import { RulePriority } from './rule-priority.js';
478
479
  return rules;
479
480
  }
480
481
  /**
481
- * Creates a new {@link Rule} from filter list metadata and an already-converted
482
- * network rule AST node.
482
+ * Checks whether the given node is a network rule node.
483
+ *
484
+ * @param node Rule AST node.
485
+ *
486
+ * @returns `true` if the node is a network rule node.
487
+ */ static isNetworkRuleNode(node) {
488
+ return node.category === RuleCategory.Network && node.type === NetworkRuleType.NetworkRule;
489
+ }
490
+ /**
491
+ * Returns the text of a rule node as written in the filter list.
492
+ *
493
+ * The parser records the raw text in `node.raws.text` when the `includeRaws`
494
+ * option is enabled, which the scanner always does. Nodes built by hand may
495
+ * lack it, so the text is regenerated as a fallback.
496
+ *
497
+ * @param node Rule AST node, must not be converted to AG syntax yet.
498
+ *
499
+ * @returns Rule text as written, or an empty string when it cannot be
500
+ * reconstructed.
501
+ */ static getWrittenText(node) {
502
+ if (typeof node.raws?.text === 'string') {
503
+ return node.raws.text;
504
+ }
505
+ try {
506
+ return RuleGenerator.generate(node);
507
+ } catch {
508
+ // A node that cannot be generated has no written form: the rule
509
+ // still works, it just cannot be serialized back to text.
510
+ return '';
511
+ }
512
+ }
513
+ /**
514
+ * Creates a new {@link Rule} from filter list metadata, an already-converted
515
+ * network rule AST node and the rule text as written in the filter list.
483
516
  *
484
517
  * @param filterListId Filter list ID.
485
518
  * @param index Rule index within the filter list.
486
519
  * @param node Network rule AST node (must already be in AG syntax).
520
+ * @param originalText Rule text as written in the filter list, captured
521
+ * before conversion to AG syntax.
487
522
  *
488
523
  * @throws `SyntaxError` when the pattern contains spaces, the rule is too
489
524
  * general, or any modifier is invalid.
490
- */ constructor(filterListId, index, node){
525
+ */ constructor(filterListId, index, node, originalText){
491
526
  /**
492
527
  * Set of canonical modifier names that are enabled on this rule.
493
528
  *
@@ -530,8 +565,19 @@ import { RulePriority } from './rule-priority.js';
530
565
  * `$removeparam`: a value-less `$removeparam` is stored as `''`, because
531
566
  * it carries a meaning of its own ("remove all query parameters") that
532
567
  * must be distinguishable from "no value".
568
+ *
569
+ * This is the parsed value used by the converters. For `$badfilter`
570
+ * identity see {@link originalText}.
533
571
  */ this.advancedModifierValue = null;
534
572
  /**
573
+ * CSP directive of a `$csp` rule, `null` when the directive is omitted.
574
+ *
575
+ * A dedicated field is required because {@link advancedModifierValue} is
576
+ * shared by every value-bearing advanced modifier and keeps only the last
577
+ * one: `$csp=script-src 'none',urltransform=/a/b/` would otherwise carry
578
+ * the url-transform value as the directive.
579
+ */ this.cspDirective = null;
580
+ /**
535
581
  * Parsed data for the `$header` modifier.
536
582
  */ this.headerMatcher = null;
537
583
  /**
@@ -546,6 +592,7 @@ import { RulePriority } from './rule-priority.js';
546
592
  * Whether the rule uses `$redirect-rule` (only redirects
547
593
  * already-blocked requests) vs plain `$redirect`.
548
594
  */ this.isRedirectRuleModifier = false;
595
+ this.originalText = originalText;
549
596
  const pattern = node.pattern.value;
550
597
  if (pattern && hasSpaces(pattern)) {
551
598
  throw new SyntaxError('Rule has spaces, seems to be a host rule');
@@ -778,13 +825,40 @@ import { RulePriority } from './rule-priority.js';
778
825
  this.advancedModifierValue = value;
779
826
  break;
780
827
  case OPTION_NAMES.CSP:
828
+ this.enabledModifiers.add(name);
829
+ this.cspDirective = value || null;
830
+ // Only an allowlist `$csp` may omit the directive: it means
831
+ // "cancel the CSP rules of the matching scope". A blocking
832
+ // rule without a directive would silently degrade into a
833
+ // plain blocking rule, so it is rejected, like in tsurlfilter.
834
+ if (!isAllowlist && !value) {
835
+ throw new SyntaxError('Invalid $csp rule: CSP directive must not be empty');
836
+ }
837
+ // `report-uri` and `report-to` make the browser send
838
+ // violation reports to a third-party host. tsurlfilter
839
+ // rejects any directive containing `report-`, so an unsupported
840
+ // report target cannot leak the browsing context.
841
+ if (value && value.toLowerCase().includes('report-')) {
842
+ throw new SyntaxError(`Invalid $csp rule: forbidden CSP directive: ${value}`);
843
+ }
844
+ break;
845
+ case OPTION_NAMES.PERMISSIONS:
846
+ this.enabledModifiers.add(name);
847
+ this.advancedModifierName = rawName;
848
+ this.advancedModifierValue = value || null;
849
+ // Same as `$csp`: only an allowlist rule may omit the
850
+ // directive. A blocking rule without it would silently
851
+ // degrade into a plain blocking rule.
852
+ if (!isAllowlist && !value) {
853
+ throw new SyntaxError('Invalid $permissions rule: permissions directive must not be empty');
854
+ }
855
+ break;
781
856
  case OPTION_NAMES.COOKIE:
782
857
  case OPTION_NAMES.REPLACE:
783
858
  case OPTION_NAMES.JSONPRUNE:
784
859
  case OPTION_NAMES.XMLPRUNE:
785
860
  case OPTION_NAMES.HLS:
786
861
  case OPTION_NAMES.REFERRERPOLICY:
787
- case OPTION_NAMES.PERMISSIONS:
788
862
  case OPTION_NAMES.URLTRANSFORM:
789
863
  this.enabledModifiers.add(name);
790
864
  this.advancedModifierName = rawName;
@@ -800,9 +874,14 @@ import { RulePriority } from './rule-priority.js';
800
874
  break;
801
875
  case OPTION_NAMES.REMOVEHEADER:
802
876
  {
877
+ // A rule without a header name cannot remove anything and
878
+ // would degrade into a plain blocking rule.
879
+ if (!value) {
880
+ throw new SyntaxError('Invalid $removeheader rule: removeheader value must not be empty');
881
+ }
803
882
  this.enabledModifiers.add(name);
804
883
  this.advancedModifierName = rawName;
805
- this.advancedModifierValue = value || null;
884
+ this.advancedModifierValue = value;
806
885
  const info = Rule.computeRemoveHeaderInfo(value);
807
886
  this.removeHeaderName = info.name;
808
887
  this.removeHeaderIsRequestType = info.isRequest;
@@ -848,6 +927,13 @@ import { RulePriority } from './rule-priority.js';
848
927
  if (this.denyAllowDomains !== null && this.permittedToDomains !== null) {
849
928
  throw new SyntaxError('Modifiers $denyallow and $to cannot be used together');
850
929
  }
930
+ // One declarative rule produces one action, and the CSP action would
931
+ // win the conversion and then be dropped by the CSP scope checks, so
932
+ // such a rule would do nothing at all. Reject the combination instead
933
+ // of silently removing cookies only.
934
+ if (this.enabledModifiers.has(OPTION_NAMES.CSP) && this.enabledModifiers.has(OPTION_NAMES.COOKIE)) {
935
+ throw new SyntaxError('$csp is not compatible with $cookie');
936
+ }
851
937
  // Validate modifier combinations (ported from tsurlfilter).
852
938
  if (this.enabledModifiers.has(OPTION_NAMES.REMOVEPARAM)) {
853
939
  for (const modifier of this.enabledModifiers){
@@ -0,0 +1,121 @@
1
+ import { OPTION_NAMES } from '../rule/option-names.js';
2
+
3
+ /**
4
+ * Kind of action the converter produces for a rule.
5
+ *
6
+ * Kinds follow the priority order of {@link RegularRuleConverter.getAction}:
7
+ * a rule may enable several modifiers, but only the highest-priority one
8
+ * determines the action.
9
+ */ var ActionKind = /*#__PURE__*/ function(ActionKind) {
10
+ ActionKind["Allow"] = "allow";
11
+ ActionKind["Redirect"] = "redirect";
12
+ ActionKind["RemoveParamRedirect"] = "removeParamRedirect";
13
+ ActionKind["RemoveHeader"] = "removeHeader";
14
+ ActionKind["Csp"] = "csp";
15
+ ActionKind["Permissions"] = "permissions";
16
+ ActionKind["Cookie"] = "cookie";
17
+ ActionKind["Block"] = "block";
18
+ return ActionKind;
19
+ }({});
20
+ /**
21
+ * Lists action kinds a rule may produce, in priority order.
22
+ *
23
+ * The list is structural: it contains every enabled action modifier in priority
24
+ * order plus `Block` as the fallback, so the caller can try to build an action
25
+ * for each kind until one succeeds.
26
+ *
27
+ * @param rule Rule to select action kinds for.
28
+ *
29
+ * @returns Action kinds in priority order, the last one always being `Block`.
30
+ */ const selectActionKinds = (rule)=>{
31
+ if (rule.allowlist) {
32
+ return [
33
+ "allow"
34
+ ];
35
+ }
36
+ const kinds = [];
37
+ if (rule.isModifierEnabled(OPTION_NAMES.REDIRECT)) {
38
+ kinds.push("redirect");
39
+ }
40
+ if (rule.isModifierEnabled(OPTION_NAMES.REMOVEPARAM)) {
41
+ kinds.push("removeParamRedirect");
42
+ }
43
+ if (rule.isModifierEnabled(OPTION_NAMES.REMOVEHEADER)) {
44
+ kinds.push("removeHeader");
45
+ }
46
+ if (rule.isModifierEnabled(OPTION_NAMES.CSP)) {
47
+ kinds.push("csp");
48
+ }
49
+ if (rule.isModifierEnabled(OPTION_NAMES.PERMISSIONS)) {
50
+ kinds.push("permissions");
51
+ }
52
+ if (rule.isModifierEnabled(OPTION_NAMES.COOKIE)) {
53
+ kinds.push("cookie");
54
+ }
55
+ kinds.push("block");
56
+ return kinds;
57
+ };
58
+ /**
59
+ * Checks whether a kind is guaranteed to produce an action for a rule.
60
+ *
61
+ * Header-appending modifiers produce nothing without a value, so such a rule
62
+ * falls through to the next kind. Modifiers which may fail on invalid input
63
+ * (`$redirect`, `$removeparam`, `$removeheader`, `$cookie`) are treated as
64
+ * producing an action, so the prediction never claims a lower-priority action
65
+ * which a broken higher-priority modifier would actually replace.
66
+ *
67
+ * @param rule Rule to check.
68
+ * @param kind Action kind to check.
69
+ *
70
+ * @returns `true` if the kind produces an action.
71
+ */ const producesAction = (rule, kind)=>{
72
+ switch(kind){
73
+ case "csp":
74
+ {
75
+ // `$csp` with `$cookie` is rejected while parsing, so a rule with
76
+ // a directive always produces the CSP action.
77
+ return rule.cspDirective !== null;
78
+ }
79
+ case "permissions":
80
+ {
81
+ // `advancedModifierValue` holds the value of the last advanced
82
+ // modifier, so a `$permissions` value is lost when another
83
+ // advanced modifier follows it.
84
+ return rule.advancedModifierValue !== null;
85
+ }
86
+ default:
87
+ {
88
+ return true;
89
+ }
90
+ }
91
+ };
92
+ /**
93
+ * Selects the action kind the converter will produce for a rule.
94
+ *
95
+ * @param rule Rule to select an action kind for.
96
+ *
97
+ * @returns First kind of {@link selectActionKinds} which produces an action.
98
+ */ const selectActionKind = (rule)=>{
99
+ const kinds = selectActionKinds(rule);
100
+ for(let i = 0; i < kinds.length; i += 1){
101
+ if (producesAction(rule, kinds[i])) {
102
+ return kinds[i];
103
+ }
104
+ }
105
+ return "block";
106
+ };
107
+ /**
108
+ * Checks whether a rule belongs to the CSP ruleset.
109
+ *
110
+ * Blocking rules belong there only when the converted action appends the CSP
111
+ * header: a rule combining `$csp` with a higher-priority modifier, such as
112
+ * `$redirect`, produces another action and must be converted by the regular
113
+ * pass. Exceptions have no
114
+ * converted action, so they belong there whenever `$csp` is enabled.
115
+ *
116
+ * @param rule Rule to check.
117
+ *
118
+ * @returns `true` if the rule is handled by the CSP pass.
119
+ */ const isCspRule = (rule)=>rule.allowlist ? rule.isModifierEnabled(OPTION_NAMES.CSP) : selectActionKind(rule) === "csp";
120
+
121
+ export { ActionKind, isCspRule, selectActionKind, selectActionKinds };
@@ -0,0 +1,268 @@
1
+ import { ResourceType, RequestMethod, DomainType } from '../declarative-rule/rule-condition.js';
2
+
3
+ /**
4
+ * Condition fields which describe the URL identity of a rule.
5
+ */ const URL_CONDITION_FIELDS = [
6
+ 'urlFilter',
7
+ 'regexFilter'
8
+ ];
9
+ /**
10
+ * Values of all domain types.
11
+ */ const ALL_DOMAIN_TYPES = Object.values(DomainType);
12
+ /**
13
+ * Values of all request methods.
14
+ */ const ALL_REQUEST_METHODS = Object.values(RequestMethod);
15
+ /**
16
+ * Values of all resource types.
17
+ */ const ALL_RESOURCE_TYPES = Object.values(ResourceType);
18
+ /**
19
+ * Checks whether one list of values contains all values of another one.
20
+ *
21
+ * @param superset List which may contain all values.
22
+ * @param subset List which must be contained.
23
+ *
24
+ * @returns `true` if the first list is a superset of the second one.
25
+ */ const isSuperset = (superset, subset)=>subset.every((value)=>superset.includes(value));
26
+ /**
27
+ * Checks whether two lists contain the same values in any order.
28
+ *
29
+ * @param left First list.
30
+ * @param right Second list.
31
+ *
32
+ * @returns `true` if the lists are equal up to the order.
33
+ */ const areEqualLists = (left, right)=>{
34
+ if (left === undefined || right === undefined) {
35
+ return left === right;
36
+ }
37
+ return left.length === right.length && isSuperset(left, right) && isSuperset(right, left);
38
+ };
39
+ /**
40
+ * Checks whether an exception's URL identity matches a blocking rule's one.
41
+ *
42
+ * `urlFilter` and `regexFilter` are compared one by one: a value stays tied to
43
+ * its field, otherwise a url filter would cover a regexp with the same text.
44
+ *
45
+ * DNR matches `urlFilter` case-insensitively unless the rule sets
46
+ * `isUrlFilterCaseSensitive`, so a case-insensitive exception compares the
47
+ * lowercased values: it matches the same URLs as the blocking rule. A regexp
48
+ * filter is always case-sensitive, so it is never lowercased.
49
+ *
50
+ * @param exceptionCondition Condition of the exception.
51
+ * @param blockingCondition Condition of the blocking rule.
52
+ *
53
+ * @returns `true` if both rules match the same URLs by construction.
54
+ */ const coversUrlCondition = (exceptionCondition, blockingCondition)=>{
55
+ const exceptionUrlFilter = exceptionCondition.isUrlFilterCaseSensitive ? exceptionCondition.urlFilter : exceptionCondition.urlFilter?.toLowerCase();
56
+ const blockingUrlFilter = exceptionCondition.isUrlFilterCaseSensitive ? blockingCondition.urlFilter : blockingCondition.urlFilter?.toLowerCase();
57
+ return exceptionUrlFilter === blockingUrlFilter && exceptionCondition.regexFilter === blockingCondition.regexFilter;
58
+ };
59
+ /**
60
+ * Builds the set of values allowed by an inclusion/exclusion condition pair.
61
+ *
62
+ * @param included Values allowed explicitly, `undefined` if all values are allowed.
63
+ * @param excluded Values excluded explicitly, `undefined` if nothing is excluded.
64
+ * @param all All values of the field.
65
+ *
66
+ * @returns Values allowed by the pair.
67
+ */ const getAllowedValues = (included, excluded, all)=>(included ?? all).filter((value)=>!(excluded ?? []).includes(value));
68
+ /**
69
+ * Checks whether an exception's party restriction covers a blocking rule's one.
70
+ *
71
+ * An absent `domainType` does not restrict the rule by the party, so it covers
72
+ * any restricted value.
73
+ *
74
+ * @param exceptionCondition Condition of the exception.
75
+ * @param blockingCondition Condition of the blocking rule.
76
+ *
77
+ * @returns `true` if the exception's restriction is not narrower.
78
+ */ const coversDomainType = (exceptionCondition, blockingCondition)=>isSuperset(exceptionCondition.domainType ? [
79
+ exceptionCondition.domainType
80
+ ] : ALL_DOMAIN_TYPES, blockingCondition.domainType ? [
81
+ blockingCondition.domainType
82
+ ] : ALL_DOMAIN_TYPES);
83
+ /**
84
+ * Checks whether an exception's resource types cover a blocking rule's ones.
85
+ *
86
+ * @param exceptionCondition Condition of the exception.
87
+ * @param blockingCondition Condition of the blocking rule.
88
+ *
89
+ * @returns `true` if the exception allows every resource type of the blocker.
90
+ */ const coversResourceTypes = (exceptionCondition, blockingCondition)=>isSuperset(getAllowedValues(exceptionCondition.resourceTypes, exceptionCondition.excludedResourceTypes, ALL_RESOURCE_TYPES), getAllowedValues(blockingCondition.resourceTypes, blockingCondition.excludedResourceTypes, ALL_RESOURCE_TYPES));
91
+ /**
92
+ * Checks whether an exception's request methods cover a blocking rule's ones.
93
+ *
94
+ * @param exceptionCondition Condition of the exception.
95
+ * @param blockingCondition Condition of the blocking rule.
96
+ *
97
+ * @returns `true` if the exception allows every method of the blocker.
98
+ */ const coversRequestMethods = (exceptionCondition, blockingCondition)=>isSuperset(getAllowedValues(exceptionCondition.requestMethods, exceptionCondition.excludedRequestMethods, ALL_REQUEST_METHODS), getAllowedValues(blockingCondition.requestMethods, blockingCondition.excludedRequestMethods, ALL_REQUEST_METHODS));
99
+ /**
100
+ * Checks whether an exception is not case-sensitive when a blocking rule is.
101
+ *
102
+ * A case-insensitive exception matches a superset of the blocker's URLs.
103
+ *
104
+ * @param exceptionCondition Condition of the exception.
105
+ * @param blockingCondition Condition of the blocking rule.
106
+ *
107
+ * @returns `true` if the exception is not narrower by the case sensitivity.
108
+ */ const coversCaseSensitivity = (exceptionCondition, blockingCondition)=>!exceptionCondition.isUrlFilterCaseSensitive || blockingCondition.isUrlFilterCaseSensitive === true;
109
+ /**
110
+ * Checks whether a domain belongs to a parent domain.
111
+ *
112
+ * @param domain Domain to check.
113
+ * @param parentDomain Potential parent domain.
114
+ *
115
+ * @returns `true` if the parent domain covers the domain.
116
+ */ const isDomainCovered = (domain, parentDomain)=>domain === parentDomain || domain.endsWith(`.${parentDomain}`);
117
+ /**
118
+ * Checks whether each domain in one list is covered by another list.
119
+ *
120
+ * @param subset Domains that must be covered.
121
+ * @param superset Domains that may cover them.
122
+ *
123
+ * @returns `true` if the first domain list is a subset of the second.
124
+ */ const isDomainListSubset = (subset, superset)=>subset !== undefined && superset !== undefined && subset.every((domain)=>superset.some((parentDomain)=>isDomainCovered(domain, parentDomain)));
125
+ /**
126
+ * Checks whether one DNR header condition covers another.
127
+ *
128
+ * @param header Header condition to check.
129
+ * @param coveringHeader Potential covering header condition.
130
+ *
131
+ * @returns `true` if the second header condition covers the first.
132
+ */ const isHeaderInfoCovered = (header, coveringHeader)=>{
133
+ // Header names are case-insensitive in DNR, so the exception may spell them
134
+ // differently from the blocking rule.
135
+ if (header.header.toLowerCase() !== coveringHeader.header.toLowerCase()) {
136
+ return false;
137
+ }
138
+ const coveringHeaderHasValueRestrictions = coveringHeader.values !== undefined || coveringHeader.excludedValues !== undefined;
139
+ return !coveringHeaderHasValueRestrictions || areEqualLists(header.values, coveringHeader.values) && areEqualLists(header.excludedValues, coveringHeader.excludedValues);
140
+ };
141
+ /**
142
+ * Checks whether two header conditions describe the same condition.
143
+ *
144
+ * @param header Header condition.
145
+ * @param otherHeader Header condition to compare with.
146
+ *
147
+ * @returns `true` if both conditions match the same headers.
148
+ */ const isSameHeader = (header, otherHeader)=>isHeaderInfoCovered(header, otherHeader) && isHeaderInfoCovered(otherHeader, header);
149
+ /**
150
+ * Checks whether each header condition is covered by another list.
151
+ *
152
+ * @param subset Header conditions that must be covered.
153
+ * @param superset Header conditions that may cover them.
154
+ *
155
+ * @returns `true` if the first header list is a subset of the second.
156
+ */ const isHeaderListSubset = (subset, superset)=>subset !== undefined && superset !== undefined && subset.every((header)=>superset.some((coveringHeader)=>isHeaderInfoCovered(header, coveringHeader)));
157
+ /**
158
+ * Checks whether each header condition list contains the same conditions.
159
+ *
160
+ * @param left First header list.
161
+ * @param right Second header list.
162
+ *
163
+ * @returns `true` if both lists describe the same headers.
164
+ */ const areEqualHeaderLists = (left, right)=>{
165
+ if (left === undefined || right === undefined) {
166
+ return left === right;
167
+ }
168
+ return left.length === right.length && left.every((header)=>right.some((otherHeader)=>isSameHeader(header, otherHeader))) && right.every((header)=>left.some((otherHeader)=>isSameHeader(header, otherHeader)));
169
+ };
170
+ /**
171
+ * Checks whether an exception's domain list covers a blocking rule's one.
172
+ *
173
+ * An absent exception list means the exception is not restricted by the
174
+ * condition at all, so it covers any list of the blocking rule. The same rule
175
+ * applies to `initiatorDomains` and `requestDomains`, which DNR treats as
176
+ * "all domains" when omitted.
177
+ *
178
+ * @param exceptionList Domains of the exception.
179
+ * @param blockingList Domains of the blocking rule.
180
+ *
181
+ * @returns `true` if the exception's list covers the blocking rule's list.
182
+ */ const coversDomainList = (exceptionList, blockingList)=>exceptionList === undefined || isDomainListSubset(blockingList, exceptionList);
183
+ /**
184
+ * Checks whether an exception excludes no more domains than a blocking rule.
185
+ *
186
+ * An absent exception list means the exception excludes nothing, so it covers
187
+ * any list of the blocking rule.
188
+ *
189
+ * @param exceptionList Domains excluded by the exception.
190
+ * @param blockingList Domains excluded by the blocking rule.
191
+ *
192
+ * @returns `true` if the exception excludes a subset of the blocking rule's list.
193
+ */ const coversExcludedDomains = (exceptionList, blockingList)=>exceptionList === undefined || isDomainListSubset(exceptionList, blockingList);
194
+ /**
195
+ * Checks whether an exception's response headers cover a blocking rule's ones.
196
+ *
197
+ * A rule matches when any header of its list matches, so the exception covers
198
+ * the blocking rule only when every blocking header is implied by some header
199
+ * of the exception: a response that matches the blocking rule must match the
200
+ * exception as well. An absent exception list means the exception is not
201
+ * restricted by headers, so it covers any list of the blocking rule.
202
+ *
203
+ * @param exceptionHeaders Headers of the exception.
204
+ * @param blockingHeaders Headers of the blocking rule.
205
+ *
206
+ * @returns `true` if the exception's list covers the blocking rule's list.
207
+ */ const coversResponseHeaders = (exceptionHeaders, blockingHeaders)=>exceptionHeaders === undefined || isHeaderListSubset(blockingHeaders, exceptionHeaders);
208
+ /**
209
+ * Comparators for every DNR condition field.
210
+ *
211
+ * The mapped type keeps the table exhaustive: a field added to
212
+ * {@link RuleCondition} without a comparator breaks the build, so a new
213
+ * condition field cannot be silently ignored by the resolver.
214
+ *
215
+ * Fields of one pair (`resourceTypes`/`excludedResourceTypes` and so on) share
216
+ * a comparator which reads both of them.
217
+ */ const CONDITION_COVERAGE = {
218
+ urlFilter: coversUrlCondition,
219
+ regexFilter: coversUrlCondition,
220
+ domainType: coversDomainType,
221
+ initiatorDomains: (exceptionCondition, blockingCondition)=>coversDomainList(exceptionCondition.initiatorDomains, blockingCondition.initiatorDomains),
222
+ excludedInitiatorDomains: (exceptionCondition, blockingCondition)=>coversExcludedDomains(exceptionCondition.excludedInitiatorDomains, blockingCondition.excludedInitiatorDomains),
223
+ requestDomains: (exceptionCondition, blockingCondition)=>coversDomainList(exceptionCondition.requestDomains, blockingCondition.requestDomains),
224
+ excludedRequestDomains: (exceptionCondition, blockingCondition)=>coversExcludedDomains(exceptionCondition.excludedRequestDomains, blockingCondition.excludedRequestDomains),
225
+ responseHeaders: (exceptionCondition, blockingCondition)=>coversResponseHeaders(exceptionCondition.responseHeaders, blockingCondition.responseHeaders),
226
+ excludedResponseHeaders: (exceptionCondition, blockingCondition)=>areEqualHeaderLists(exceptionCondition.excludedResponseHeaders, blockingCondition.excludedResponseHeaders),
227
+ tabIds: (exceptionCondition, blockingCondition)=>areEqualLists(exceptionCondition.tabIds, blockingCondition.tabIds),
228
+ excludedTabIds: (exceptionCondition, blockingCondition)=>areEqualLists(exceptionCondition.excludedTabIds, blockingCondition.excludedTabIds),
229
+ requestMethods: coversRequestMethods,
230
+ excludedRequestMethods: coversRequestMethods,
231
+ resourceTypes: coversResourceTypes,
232
+ excludedResourceTypes: coversResourceTypes,
233
+ isUrlFilterCaseSensitive: coversCaseSensitivity
234
+ };
235
+ /**
236
+ * All condition fields compared by the resolver.
237
+ */ const CONDITION_FIELDS = Object.keys(CONDITION_COVERAGE);
238
+ /**
239
+ * Condition fields compared by the non-URL coverage check.
240
+ */ const NON_URL_CONDITION_FIELDS = CONDITION_FIELDS.filter((field)=>!URL_CONDITION_FIELDS.includes(field));
241
+ /**
242
+ * Checks whether an exception covers the given condition fields of a blocking rule.
243
+ *
244
+ * @param exceptionCondition Condition of the exception.
245
+ * @param blockingCondition Condition of the blocking rule.
246
+ * @param fields Condition fields to compare.
247
+ *
248
+ * @returns `true` if the exception is not narrower in any of the fields.
249
+ */ const coversFields = (exceptionCondition, blockingCondition, fields)=>fields.every((field)=>CONDITION_COVERAGE[field](exceptionCondition, blockingCondition));
250
+ /**
251
+ * Checks whether an exception has the same URL identity and is not narrower
252
+ * than a blocking rule in any other condition.
253
+ *
254
+ * @param exceptionCondition Condition of the exception.
255
+ * @param blockingCondition Condition of the blocking rule.
256
+ *
257
+ * @returns `true` if the exception covers the blocking rule's condition.
258
+ */ const coversCondition = (exceptionCondition, blockingCondition)=>coversFields(exceptionCondition, blockingCondition, CONDITION_FIELDS);
259
+ /**
260
+ * Checks whether an exception covers a blocking rule's non-URL conditions.
261
+ *
262
+ * @param exceptionCondition Condition of the exception.
263
+ * @param blockingCondition Condition of the blocking rule.
264
+ *
265
+ * @returns `true` if the exception is not narrower in any non-URL field.
266
+ */ const coversNonUrlConditions = (exceptionCondition, blockingCondition)=>coversFields(exceptionCondition, blockingCondition, NON_URL_CONDITION_FIELDS);
267
+
268
+ export { coversCondition, coversNonUrlConditions, isDomainCovered };