@adguard/dnr-converter 1.0.0-alpha.2

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 (114) hide show
  1. package/README.md +476 -0
  2. package/dist/cli.cjs +58912 -0
  3. package/dist/constants.js +23 -0
  4. package/dist/declarative-rule/declarative-rule.js +15 -0
  5. package/dist/declarative-rule/header-info.js +12 -0
  6. package/dist/declarative-rule/modify-header-info.js +31 -0
  7. package/dist/declarative-rule/query-key-value.js +12 -0
  8. package/dist/declarative-rule/query-transform.js +12 -0
  9. package/dist/declarative-rule/redirect.js +14 -0
  10. package/dist/declarative-rule/rule-action.js +44 -0
  11. package/dist/declarative-rule/rule-condition.js +77 -0
  12. package/dist/declarative-rule/url-transform.js +30 -0
  13. package/dist/errors/conversion-errors/empty-domains-error.js +24 -0
  14. package/dist/errors/conversion-errors/empty-resources-error.js +24 -0
  15. package/dist/errors/conversion-errors/index.js +17 -0
  16. package/dist/errors/conversion-errors/invalid-declarative-rule-error.js +22 -0
  17. package/dist/errors/conversion-errors/unsupported-modifier-error.js +20 -0
  18. package/dist/errors/conversion-errors/unsupported-regexp-error.js +27 -0
  19. package/dist/errors/converter-options-errors/empty-or-negative-number-of-rules-error.js +18 -0
  20. package/dist/errors/converter-options-errors/index.js +15 -0
  21. package/dist/errors/converter-options-errors/negative-number-of-rules-error.js +18 -0
  22. package/dist/errors/converter-options-errors/resources-path-error.js +18 -0
  23. package/dist/errors/limitation-errors/index.js +17 -0
  24. package/dist/errors/limitation-errors/max-scanned-rules-error.js +20 -0
  25. package/dist/errors/limitation-errors/too-many-error.js +28 -0
  26. package/dist/errors/limitation-errors/too-many-regexp-rules-error.js +25 -0
  27. package/dist/errors/limitation-errors/too-many-rules-error.js +25 -0
  28. package/dist/errors/limitation-errors/too-many-unsafe-rules-error.js +25 -0
  29. package/dist/errors/unavailable-sources-errors/unavailable-filter-source-error.js +21 -0
  30. package/dist/errors/unavailable-sources-errors/unavailable-ruleset-source-error.js +21 -0
  31. package/dist/filter/filter.js +92 -0
  32. package/dist/filter-converter/filter-converter.js +385 -0
  33. package/dist/grouped-rules-converters/url-transform-converter.js +340 -0
  34. package/dist/index.js +30 -0
  35. package/dist/package.json.js +3 -0
  36. package/dist/re2-regexp/re2-validator.js +37 -0
  37. package/dist/re2-regexp/regex-validator-extension.js +30 -0
  38. package/dist/re2.wasm +0 -0
  39. package/dist/rule/option-names.js +65 -0
  40. package/dist/rule/rule-badfilter.js +81 -0
  41. package/dist/rule/rule-priority.js +88 -0
  42. package/dist/rule/rule-validator.js +455 -0
  43. package/dist/rule/rule.js +853 -0
  44. package/dist/rule/string-utils.js +49 -0
  45. package/dist/rule-converters/csp-converter.js +105 -0
  46. package/dist/rule-converters/regular-rule-converter.js +789 -0
  47. package/dist/rule-converters/remove-header-converter.js +97 -0
  48. package/dist/rule-converters/rules-converter.js +365 -0
  49. package/dist/rule-converters/rules-grouper.js +75 -0
  50. package/dist/rules-scanner/rules-scanner.js +136 -0
  51. package/dist/ruleset/metadata-rule.js +35 -0
  52. package/dist/ruleset/metadata-ruleset.js +162 -0
  53. package/dist/ruleset/rules-hash-map.js +71 -0
  54. package/dist/ruleset/ruleset-with-source-map.js +406 -0
  55. package/dist/ruleset/ruleset.js +54 -0
  56. package/dist/ruleset/source-map.js +283 -0
  57. package/dist/types/cli/convert-filters.d.ts +32 -0
  58. package/dist/types/cli/index.d.ts +7 -0
  59. package/dist/types/cli/utils.d.ts +19 -0
  60. package/dist/types/src/declarative-rule/declarative-rule.d.ts +32 -0
  61. package/dist/types/src/declarative-rule/header-info.d.ts +31 -0
  62. package/dist/types/src/declarative-rule/modify-header-info.d.ts +46 -0
  63. package/dist/types/src/declarative-rule/query-key-value.d.ts +24 -0
  64. package/dist/types/src/declarative-rule/query-transform.d.ts +21 -0
  65. package/dist/types/src/declarative-rule/redirect.d.ts +32 -0
  66. package/dist/types/src/declarative-rule/rule-action.d.ts +68 -0
  67. package/dist/types/src/declarative-rule/rule-condition.d.ts +262 -0
  68. package/dist/types/src/declarative-rule/url-transform.d.ts +69 -0
  69. package/dist/types/src/errors/conversion-errors/empty-domains-error.d.ts +21 -0
  70. package/dist/types/src/errors/conversion-errors/empty-resources-error.d.ts +21 -0
  71. package/dist/types/src/errors/conversion-errors/index.d.ts +27 -0
  72. package/dist/types/src/errors/conversion-errors/invalid-declarative-rule-error.d.ts +30 -0
  73. package/dist/types/src/errors/conversion-errors/unsupported-modifier-error.d.ts +20 -0
  74. package/dist/types/src/errors/conversion-errors/unsupported-regexp-error.d.ts +23 -0
  75. package/dist/types/src/errors/converter-options-errors/empty-or-negative-number-of-rules-error.d.ts +13 -0
  76. package/dist/types/src/errors/converter-options-errors/index.d.ts +23 -0
  77. package/dist/types/src/errors/converter-options-errors/negative-number-of-rules-error.d.ts +13 -0
  78. package/dist/types/src/errors/converter-options-errors/resources-path-error.d.ts +13 -0
  79. package/dist/types/src/errors/limitation-errors/index.d.ts +27 -0
  80. package/dist/types/src/errors/limitation-errors/max-scanned-rules-error.d.ts +18 -0
  81. package/dist/types/src/errors/limitation-errors/too-many-error.d.ts +33 -0
  82. package/dist/types/src/errors/limitation-errors/too-many-regexp-rules-error.d.ts +21 -0
  83. package/dist/types/src/errors/limitation-errors/too-many-rules-error.d.ts +21 -0
  84. package/dist/types/src/errors/limitation-errors/too-many-unsafe-rules-error.d.ts +21 -0
  85. package/dist/types/src/errors/unavailable-sources-errors/unavailable-filter-source-error.d.ts +19 -0
  86. package/dist/types/src/errors/unavailable-sources-errors/unavailable-ruleset-source-error.d.ts +19 -0
  87. package/dist/types/src/filter/filter.d.ts +74 -0
  88. package/dist/types/src/filter/types.d.ts +45 -0
  89. package/dist/types/src/filter-converter/conversion-result.d.ts +35 -0
  90. package/dist/types/src/filter-converter/filter-converter-options.d.ts +81 -0
  91. package/dist/types/src/filter-converter/filter-converter.d.ts +197 -0
  92. package/dist/types/src/index.d.ts +37 -0
  93. package/dist/types/src/rule/rule-types.d.ts +33 -0
  94. package/dist/types/src/rule/rule-validator.d.ts +185 -0
  95. package/dist/types/src/rule/rule.d.ts +269 -0
  96. package/dist/types/src/ruleset/metadata-ruleset.d.ts +128 -0
  97. package/dist/types/src/ruleset/rules-hash-map.d.ts +70 -0
  98. package/dist/types/src/ruleset/ruleset-with-source-map.d.ts +318 -0
  99. package/dist/types/src/ruleset/ruleset.d.ts +86 -0
  100. package/dist/types/src/ruleset/source-map.d.ts +45 -0
  101. package/dist/types/src/ruleset/types.d.ts +68 -0
  102. package/dist/types/src/utils/is-safe-rule.d.ts +20 -0
  103. package/dist/types/src/utils/ruleset-utils.d.ts +45 -0
  104. package/dist/types/src/version.d.ts +6 -0
  105. package/dist/url-transform-converter.js +338 -0
  106. package/dist/utils/error.js +22 -0
  107. package/dist/utils/is-safe-rule.js +25 -0
  108. package/dist/utils/lazy-loader.js +116 -0
  109. package/dist/utils/lazy.js +50 -0
  110. package/dist/utils/ruleset-utils.js +76 -0
  111. package/dist/utils/string.js +180 -0
  112. package/dist/utils/valibot.js +74 -0
  113. package/dist/version.js +7 -0
  114. package/package.json +122 -0
@@ -0,0 +1,789 @@
1
+ import { RuleGenerator } from '@adguard/agtree/generator';
2
+ import { getRedirectFilename } from '@adguard/scriptlets/redirects';
3
+ import { MASK_NEGATE_CHARACTER, MASK_REGEX_RULE, CSP_HEADER_NAME, PERMISSIONS_POLICY_HEADER_NAME, MASK_ANY_CHARACTER } from '../constants.js';
4
+ import { isConversionError } from '../errors/conversion-errors/index.js';
5
+ import { ResourcesPathError } from '../errors/converter-options-errors/resources-path-error.js';
6
+ import { re2Validator } from '../re2-regexp/re2-validator.js';
7
+ import { OPTION_NAMES } from '../rule/option-names.js';
8
+ import { RuleDeclarativeValidator } from '../rule/rule-validator.js';
9
+ import { getErrorMessage } from '../utils/error.js';
10
+ import { prepareASCII, removeSlashes, isRegexPattern, toASCII } from '../utils/string.js';
11
+ import { HeaderOperation } from '../declarative-rule/modify-header-info.js';
12
+ import { RuleActionType } from '../declarative-rule/rule-action.js';
13
+ import { DomainType, ResourceType } from '../declarative-rule/rule-condition.js';
14
+ import { EmptyResourcesError } from '../errors/conversion-errors/empty-resources-error.js';
15
+ import { EmptyDomainsError } from '../errors/conversion-errors/empty-domains-error.js';
16
+ import { UnsupportedRegexpError } from '../errors/conversion-errors/unsupported-regexp-error.js';
17
+
18
+ /**
19
+ * @typedef {import('../errors/conversion-errors').UnsupportedModifierError} UnsupportedModifierError
20
+ */ /**
21
+ * Contains the generic logic for converting a {@link Rule} into a {@link DeclarativeRule}.
22
+ *
23
+ * Descendant classes can override the {@link RegularRuleConverter.convert}
24
+ * method to add post-processing logic (e.g. grouping similar rules).
25
+ *
26
+ * Also descendant classes can use {@link RegularRuleConverter.convertRules},
27
+ * {@link RegularRuleConverter.convertRule} and {@link RegularRuleConverter.groupConvertedRules}
28
+ * methods, which contains the general logic of transformation and grouping of rules.
29
+ */ class RegularRuleConverter {
30
+ /**
31
+ * Checks if {@link Rule} can be converted to {@link RuleActionType.AllowAllRequests}.
32
+ *
33
+ * @param rule {@link Rule} to check.
34
+ *
35
+ * @returns Is rule compatible with {@link RuleActionType.AllowAllRequests}.
36
+ */ static isCompatibleWithAllowAllRequests(rule) {
37
+ const types = rule.permittedResourceTypes;
38
+ if (types.some((type)=>!RegularRuleConverter.ALLOW_ALL_REQUEST_COMPATIBLE_RESOURCE_TYPES.has(type))) {
39
+ return false;
40
+ }
41
+ return true;
42
+ }
43
+ /**
44
+ * Retrieves the redirect action for the provided {@link Rule}.
45
+ *
46
+ * @param rule {@link Rule} to get action for.
47
+ *
48
+ * @returns Redirect action, which describes where and how the request should be redirected.
49
+ *
50
+ * @throws Error {@link ResourcesPathError} when a network rule has
51
+ * a `$redirect` modifier and no path to web-accessible resources is specified.
52
+ */ getRedirectAction(rule) {
53
+ if (!rule.isModifierEnabled(OPTION_NAMES.REDIRECT)) {
54
+ return null;
55
+ }
56
+ const value = rule.advancedModifierValue;
57
+ if (!value) {
58
+ return null;
59
+ }
60
+ const resourcesPath = this.webAccessibleResourcesPath;
61
+ if (!resourcesPath) {
62
+ throw new ResourcesPathError('Empty web accessible resources path');
63
+ }
64
+ const filename = getRedirectFilename(value);
65
+ return {
66
+ extensionPath: `${resourcesPath}/${filename}`
67
+ };
68
+ }
69
+ /**
70
+ * Returns a redirect action for a `$removeparam` rule.
71
+ *
72
+ * Pipe-separated values (e.g. `utm_source|utm_medium`) are
73
+ * split into individual `removeParams` entries.
74
+ *
75
+ * In case if a param is an encoded URI, it is decoded first:
76
+ * https://github.com/AdguardTeam/AdguardBrowserExtension/issues/3014.
77
+ *
78
+ * @param rule {@link Rule} to get action for.
79
+ *
80
+ * @returns Redirect action, or `null` if the rule does not have a
81
+ * `$removeparam` modifier, its value is `null`, or a param value cannot be
82
+ * URI-decoded (in which case augmentation is skipped).
83
+ */ static getRemoveParamRedirectAction(rule) {
84
+ if (!rule.isModifierEnabled(OPTION_NAMES.REMOVEPARAM)) {
85
+ return null;
86
+ }
87
+ const value = rule.advancedModifierValue;
88
+ if (value === null) {
89
+ return null;
90
+ }
91
+ if (value === '') {
92
+ return {
93
+ transform: {
94
+ query: ''
95
+ }
96
+ };
97
+ }
98
+ // Split on pipe to support multiple param names in a single rule.
99
+ // If any segment contains invalid percent-encoding, decoding throws;
100
+ // skip augmentation by returning null, consistent with getRemoveParamToken().
101
+ let removeParams;
102
+ try {
103
+ removeParams = value.split(RegularRuleConverter.PIPE_SEPARATOR).map((p)=>decodeURIComponent(p));
104
+ } catch {
105
+ return null;
106
+ }
107
+ return {
108
+ transform: {
109
+ queryTransform: {
110
+ removeParams
111
+ }
112
+ }
113
+ };
114
+ }
115
+ /**
116
+ * Builds a param-aware urlFilter token for a $removeparam rule.
117
+ *
118
+ * For a rule like `$removeparam=utm_source` this method
119
+ * returns the string `^utm_source=` where the caret acts
120
+ * as a DNR separator matching query delimiters.
121
+ *
122
+ * Returns `null` when augmentation should be skipped:
123
+ * - empty or null param value (strip-all-params rule).
124
+ * - negation (`~param`).
125
+ * - regex (`/pattern/`).
126
+ * - pipe-separated values (`a|b`) — cannot generate a single token.
127
+ * - whitespace-only param name.
128
+ * - value cannot be URI-decoded.
129
+ * - param name contains urlFilter special characters (`|`, `*`, `^`).
130
+ *
131
+ * @param rule Rule with $removeparam modifier enabled.
132
+ *
133
+ * @returns A urlFilter token string, or null if augmentation should be skipped.
134
+ */ static getRemoveParamToken(rule) {
135
+ const value = rule.advancedModifierValue;
136
+ // Skip augmentation for strip-all, negation, regex, and pipe-separated params.
137
+ if (!value || value.startsWith(MASK_NEGATE_CHARACTER) || value.startsWith(MASK_REGEX_RULE) || value.includes(RegularRuleConverter.PIPE_SEPARATOR)) {
138
+ return null;
139
+ }
140
+ let decoded;
141
+ try {
142
+ decoded = decodeURIComponent(value);
143
+ } catch {
144
+ return null;
145
+ }
146
+ // Whitespace-only param names cannot form a useful urlFilter token.
147
+ if (!decoded || decoded.trim() === '') {
148
+ return null;
149
+ }
150
+ // If the decoded param name contains urlFilter special characters,
151
+ // we cannot safely embed it — fall back to non-augmented behavior.
152
+ if (RegularRuleConverter.URL_FILTER_SPECIAL_CHARS.test(decoded)) {
153
+ return null;
154
+ }
155
+ return `^${decoded}=`;
156
+ }
157
+ /**
158
+ * Returns rule modify headers action.
159
+ *
160
+ * @param rule {@link Rule} to get action for.
161
+ *
162
+ * @returns Modify headers action, which describes which
163
+ * headers should be changed: added, set or deleted.
164
+ */ static getModifyHeadersAction(rule) {
165
+ if (!rule.isModifierEnabled(OPTION_NAMES.REMOVEHEADER)) {
166
+ return null;
167
+ }
168
+ const removeRequestHeader = rule.getApplicableHeaderName(true);
169
+ if (removeRequestHeader) {
170
+ return {
171
+ requestHeaders: [
172
+ {
173
+ header: removeRequestHeader,
174
+ operation: HeaderOperation.Remove
175
+ }
176
+ ]
177
+ };
178
+ }
179
+ const removeResponseHeader = rule.getApplicableHeaderName(false);
180
+ if (removeResponseHeader) {
181
+ return {
182
+ responseHeaders: [
183
+ {
184
+ header: removeResponseHeader,
185
+ operation: HeaderOperation.Remove
186
+ }
187
+ ]
188
+ };
189
+ }
190
+ return null;
191
+ }
192
+ /**
193
+ * Returns rule modify headers action with removing Cookie headers from response and request.
194
+ *
195
+ * @param rule {@link Rule} to get action for.
196
+ *
197
+ * @returns Add headers action, which describes which headers should be added.
198
+ */ static getRemovingCookieHeadersAction(rule) {
199
+ if (!rule.isModifierEnabled(OPTION_NAMES.COOKIE)) {
200
+ return null;
201
+ }
202
+ return {
203
+ responseHeaders: [
204
+ {
205
+ operation: HeaderOperation.Remove,
206
+ header: 'Set-Cookie'
207
+ }
208
+ ],
209
+ requestHeaders: [
210
+ {
211
+ operation: HeaderOperation.Remove,
212
+ header: 'Cookie'
213
+ }
214
+ ]
215
+ };
216
+ }
217
+ /**
218
+ * Returns rule modify headers action with adding CSP headers to response.
219
+ *
220
+ * @param rule {@link Rule} to get action for.
221
+ *
222
+ * @returns Add headers action, which describes what headers should be added.
223
+ */ static getAddingCspHeadersAction(rule) {
224
+ if (!rule.isModifierEnabled(OPTION_NAMES.CSP)) {
225
+ return null;
226
+ }
227
+ const cspHeaderValue = rule.advancedModifierValue;
228
+ if (!cspHeaderValue) {
229
+ return null;
230
+ }
231
+ return {
232
+ operation: HeaderOperation.Append,
233
+ header: CSP_HEADER_NAME,
234
+ value: cspHeaderValue
235
+ };
236
+ }
237
+ /**
238
+ * Returns rule modify headers action with adding Permissions headers to response.
239
+ *
240
+ * @param rule {@link Rule} to get action for.
241
+ *
242
+ * @returns Add headers action, which describes what headers should be added.
243
+ */ static getAddingPermissionsHeadersAction(rule) {
244
+ if (!rule.isModifierEnabled(OPTION_NAMES.PERMISSIONS)) {
245
+ return null;
246
+ }
247
+ const permissionsHeaderValue = rule.advancedModifierValue;
248
+ if (!permissionsHeaderValue) {
249
+ return null;
250
+ }
251
+ return {
252
+ operation: HeaderOperation.Append,
253
+ header: PERMISSIONS_POLICY_HEADER_NAME,
254
+ value: permissionsHeaderValue
255
+ };
256
+ }
257
+ /**
258
+ * Retrieves the action for the provided {@link Rule}.
259
+ *
260
+ * @param rule {@link Rule} to get action for.
261
+ *
262
+ * @returns The action of a rule that describes what should be done with the request.
263
+ *
264
+ * @throws Error {@link ResourcesPathError} when specified an empty path to the web accessible resources.
265
+ */ getAction(rule) {
266
+ if (rule.allowlist) {
267
+ if (rule.isFilteringDisabled() && RegularRuleConverter.isCompatibleWithAllowAllRequests(rule)) {
268
+ return {
269
+ type: RuleActionType.AllowAllRequests
270
+ };
271
+ }
272
+ return {
273
+ type: RuleActionType.Allow
274
+ };
275
+ }
276
+ if (rule.isModifierEnabled(OPTION_NAMES.REDIRECT)) {
277
+ const redirectAction = this.getRedirectAction(rule);
278
+ if (redirectAction) {
279
+ return {
280
+ type: RuleActionType.Redirect,
281
+ redirect: redirectAction
282
+ };
283
+ }
284
+ }
285
+ if (rule.isModifierEnabled(OPTION_NAMES.REMOVEPARAM)) {
286
+ const removeParamRedirectAction = RegularRuleConverter.getRemoveParamRedirectAction(rule);
287
+ if (removeParamRedirectAction) {
288
+ return {
289
+ type: RuleActionType.Redirect,
290
+ redirect: removeParamRedirectAction
291
+ };
292
+ }
293
+ }
294
+ if (rule.isModifierEnabled(OPTION_NAMES.REMOVEHEADER)) {
295
+ const modifyHeadersAction = RegularRuleConverter.getModifyHeadersAction(rule);
296
+ if (modifyHeadersAction?.requestHeaders) {
297
+ return {
298
+ type: RuleActionType.ModifyHeaders,
299
+ requestHeaders: modifyHeadersAction.requestHeaders
300
+ };
301
+ }
302
+ if (modifyHeadersAction?.responseHeaders) {
303
+ return {
304
+ type: RuleActionType.ModifyHeaders,
305
+ responseHeaders: modifyHeadersAction.responseHeaders
306
+ };
307
+ }
308
+ }
309
+ if (rule.isModifierEnabled(OPTION_NAMES.CSP)) {
310
+ const headersAction = RegularRuleConverter.getAddingCspHeadersAction(rule);
311
+ if (headersAction) {
312
+ return {
313
+ type: RuleActionType.ModifyHeaders,
314
+ responseHeaders: [
315
+ headersAction
316
+ ]
317
+ };
318
+ }
319
+ }
320
+ if (rule.isModifierEnabled(OPTION_NAMES.PERMISSIONS)) {
321
+ const headersAction = RegularRuleConverter.getAddingPermissionsHeadersAction(rule);
322
+ if (headersAction) {
323
+ return {
324
+ type: RuleActionType.ModifyHeaders,
325
+ responseHeaders: [
326
+ headersAction
327
+ ]
328
+ };
329
+ }
330
+ }
331
+ if (rule.isModifierEnabled(OPTION_NAMES.COOKIE)) {
332
+ const removeCookieHeaders = RegularRuleConverter.getRemovingCookieHeadersAction(rule);
333
+ if (removeCookieHeaders) {
334
+ const { responseHeaders, requestHeaders } = removeCookieHeaders;
335
+ return {
336
+ type: RuleActionType.ModifyHeaders,
337
+ responseHeaders,
338
+ requestHeaders
339
+ };
340
+ }
341
+ }
342
+ return {
343
+ type: RuleActionType.Block
344
+ };
345
+ }
346
+ /**
347
+ * Retrieves the condition for the provided {@link Rule}.
348
+ *
349
+ * @param rule {@link Rule} to get condition for.
350
+ *
351
+ * @returns A rule condition that describes to which request the declarative rule should be applied.
352
+ */ static getCondition(rule) {
353
+ const condition = {};
354
+ // set `urlFilter` or `regexFilter` depending on the pattern type
355
+ const { pattern } = rule;
356
+ if (pattern) {
357
+ if (rule.isRegexRule()) {
358
+ condition.regexFilter = prepareASCII(removeSlashes(pattern));
359
+ } else {
360
+ // A pattern beginning with ||* is not allowed. Use * instead.
361
+ const patternWithoutVerticals = pattern.startsWith('||*') ? pattern.substring(2) : pattern;
362
+ condition.urlFilter = prepareASCII(patternWithoutVerticals);
363
+ }
364
+ }
365
+ // For $removeparam rules with a specific named parameter, append
366
+ // a param-aware token to urlFilter so that the rule only matches
367
+ // when the target parameter is present in the URL query string.
368
+ // This enables Chrome DNR to chain multiple redirect hops,
369
+ // stripping one parameter per hop until all are removed.
370
+ if (rule.isModifierEnabled(OPTION_NAMES.REMOVEPARAM)) {
371
+ const paramToken = RegularRuleConverter.getRemoveParamToken(rule);
372
+ if (paramToken !== null) {
373
+ if (condition.urlFilter) {
374
+ condition.urlFilter += `*${paramToken}`;
375
+ } else if (!condition.regexFilter) {
376
+ condition.urlFilter = paramToken;
377
+ }
378
+ }
379
+ }
380
+ // set `domainType`
381
+ if (rule.isModifierEnabled(OPTION_NAMES.THIRD_PARTY)) {
382
+ condition.domainType = DomainType.ThirdParty;
383
+ } else if (rule.isModifierDisabled(OPTION_NAMES.THIRD_PARTY)) {
384
+ condition.domainType = DomainType.FirstParty;
385
+ }
386
+ // set `initiatorDomains`
387
+ const permittedDomains = rule.permittedDomains?.filter((domain)=>!domain.includes(MASK_ANY_CHARACTER) && !isRegexPattern(domain));
388
+ if (permittedDomains && permittedDomains.length > 0) {
389
+ condition.initiatorDomains = toASCII(permittedDomains);
390
+ }
391
+ // set `excludedInitiatorDomains`
392
+ const excludedDomains = rule.restrictedDomains;
393
+ if (excludedDomains && excludedDomains.length > 0) {
394
+ condition.excludedInitiatorDomains = toASCII(excludedDomains);
395
+ }
396
+ // set `requestDomains`
397
+ const { permittedToDomains } = rule;
398
+ if (permittedToDomains && permittedToDomains.length > 0) {
399
+ condition.requestDomains = toASCII(permittedToDomains);
400
+ }
401
+ // Can be specified `$to` or `$denyallow`, but not together.
402
+ const { denyAllowDomains } = rule;
403
+ const { restrictedToDomains } = rule;
404
+ // set `excludedRequestDomains`
405
+ if (denyAllowDomains && denyAllowDomains.length !== 0) {
406
+ condition.excludedRequestDomains = toASCII(denyAllowDomains);
407
+ } else if (restrictedToDomains && restrictedToDomains.length !== 0) {
408
+ condition.excludedRequestDomains = toASCII(restrictedToDomains);
409
+ }
410
+ // set `excludedResourceTypes`
411
+ const { restrictedResourceTypes } = rule;
412
+ const hasExcludedResourceTypes = restrictedResourceTypes.length !== 0;
413
+ if (hasExcludedResourceTypes) {
414
+ // Shallow copy to drop reference linking (elements are primitive enum values)
415
+ condition.excludedResourceTypes = [
416
+ ...restrictedResourceTypes
417
+ ];
418
+ /**
419
+ * By default, we do not block the requests that
420
+ * are loaded in the browser tab ({@link ResourceType.MainFrame}).
421
+ */ if (!condition.excludedResourceTypes.includes(ResourceType.MainFrame)) {
422
+ condition.excludedResourceTypes.push(ResourceType.MainFrame);
423
+ }
424
+ }
425
+ // set `resourceTypes`
426
+ const { permittedResourceTypes } = rule;
427
+ if (!hasExcludedResourceTypes && permittedResourceTypes.length !== 0) {
428
+ condition.resourceTypes = permittedResourceTypes;
429
+ }
430
+ // set `requestMethods`
431
+ const { permittedMethods } = rule;
432
+ if (permittedMethods && permittedMethods.length !== 0) {
433
+ condition.requestMethods = permittedMethods;
434
+ }
435
+ // set `excludedRequestMethods`
436
+ const { restrictedMethods } = rule;
437
+ if (restrictedMethods && restrictedMethods.length !== 0) {
438
+ condition.excludedRequestMethods = restrictedMethods;
439
+ }
440
+ /**
441
+ * Set `isUrlFilterCaseSensitive` if the `$match-case` modifier is specified,
442
+ * because by default this option is false, so no need to specify it everywhere.
443
+ */ if (rule.isModifierEnabled(OPTION_NAMES.MATCH_CASE)) {
444
+ condition.isUrlFilterCaseSensitive = true;
445
+ }
446
+ /**
447
+ * Adds the {@link ResourceType.MainFrame} to the `resourceTypes`
448
+ * if the popup modifier is enabled. Popup rules apply only
449
+ * to document requests, so adding {@link ResourceType.MainFrame}
450
+ * ensures the rules are correctly applied.
451
+ */ if (rule.isModifierEnabled(OPTION_NAMES.POPUP)) {
452
+ condition.resourceTypes = condition.resourceTypes || [];
453
+ if (!condition.resourceTypes.includes(ResourceType.MainFrame)) {
454
+ condition.resourceTypes.push(ResourceType.MainFrame);
455
+ }
456
+ }
457
+ const emptyResourceTypes = !condition.resourceTypes && !condition.excludedResourceTypes;
458
+ if (emptyResourceTypes) {
459
+ /**
460
+ * Here we need to set {@link ResourceType.MainFrame} to apply to document requests
461
+ * as well (because by default it applies to all requests except document).
462
+ * And if we specify {@link ResourceType.MainFrame}, then we also need to specify all
463
+ * other types, so that it works not only for document requests, but
464
+ * also for all other types of requests.
465
+ */ const shouldMatchAllResourcesTypes = rule.isModifierEnabled(OPTION_NAMES.REMOVEHEADER) || rule.isModifierEnabled(OPTION_NAMES.CSP) || rule.isModifierEnabled(OPTION_NAMES.COOKIE) || rule.isModifierEnabled(OPTION_NAMES.TO) || rule.isModifierEnabled(OPTION_NAMES.METHOD);
466
+ /**
467
+ * `$permissions` and `$removeparam` modifiers must be applied only to `document` content-type
468
+ * ({@link ResourceType.MainFrame} and {@link ResourceType.SubFrame}) if they don't have resource types.
469
+ */ const shouldMatchOnlyDocument = rule.isModifierEnabled(OPTION_NAMES.REMOVEPARAM) || rule.isModifierEnabled(OPTION_NAMES.PERMISSIONS);
470
+ if (shouldMatchAllResourcesTypes) {
471
+ condition.resourceTypes = [
472
+ ResourceType.MainFrame,
473
+ ResourceType.SubFrame,
474
+ ResourceType.Stylesheet,
475
+ ResourceType.Script,
476
+ ResourceType.Image,
477
+ ResourceType.Font,
478
+ ResourceType.Object,
479
+ ResourceType.XmlHttpRequest,
480
+ ResourceType.Ping,
481
+ ResourceType.CspReport,
482
+ ResourceType.Media,
483
+ ResourceType.WebSocket,
484
+ ResourceType.WebTransport,
485
+ ResourceType.WebBundle,
486
+ ResourceType.Other
487
+ ];
488
+ } else if (shouldMatchOnlyDocument) {
489
+ condition.resourceTypes = [
490
+ ResourceType.MainFrame,
491
+ ResourceType.SubFrame
492
+ ];
493
+ }
494
+ }
495
+ // set response headers
496
+ if (rule.isModifierEnabled(OPTION_NAMES.HEADER)) {
497
+ const headerModifierMatcher = rule.headerMatcher;
498
+ if (headerModifierMatcher) {
499
+ const headerInfo = {
500
+ header: headerModifierMatcher.header
501
+ };
502
+ // Add values array if a value pattern is specified and is not a regex
503
+ // DNR does not support regex in the header info values field
504
+ // as of 14 November 2025 https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#type-HeaderInfo
505
+ const { value } = headerModifierMatcher;
506
+ if (typeof value === 'string' && !headerModifierMatcher.isRegExp) {
507
+ headerInfo.values = [
508
+ value
509
+ ];
510
+ }
511
+ condition.responseHeaders = [
512
+ headerInfo
513
+ ];
514
+ }
515
+ }
516
+ return condition;
517
+ }
518
+ /**
519
+ * Converts the {@link Rule} into a {@link DeclarativeRule}.
520
+ *
521
+ * @param id Rule ID.
522
+ * @param rule {@link Rule} to convert.
523
+ *
524
+ * @returns Converted {@link DeclarativeRule}.
525
+ *
526
+ * @throws An {@link UnsupportedModifierError} if the network rule contains an unsupported modifier
527
+ * OR an {@link EmptyResourcesError} if there is empty resources in the rule
528
+ * OR an {@link UnsupportedRegexpError} if regexp is not supported in the RE2 syntax.
529
+ * OR a {@link ResourcesPathError} when specified an empty path to the web accessible resources.
530
+ */ async convertRule(id, rule) {
531
+ // Build declarative rule
532
+ const declarativeRule = {
533
+ id,
534
+ action: this.getAction(rule),
535
+ condition: RegularRuleConverter.getCondition(rule)
536
+ };
537
+ // Set calculated priority
538
+ declarativeRule.priority = rule.priority;
539
+ // Validate created declarative rule and throw error if not valid
540
+ const conversionErr = await RegularRuleConverter.checkRuleApplication(rule, declarativeRule);
541
+ if (conversionErr) {
542
+ throw conversionErr;
543
+ }
544
+ return declarativeRule;
545
+ }
546
+ /**
547
+ * Verifies whether the converted {@link DeclarativeRule}:
548
+ * - has non-empty resource types,
549
+ * - has non-empty initiator domains if the original rule has permitted domains,
550
+ * - has supported regexp syntax in the `regexFilter` key.
551
+ *
552
+ * Note: some complex regexps are not allowed, e.g. back references,
553
+ * possessive quantifiers, negative lookaheads.
554
+ *
555
+ * @see {@link https://github.com/google/re2/wiki/Syntax}.
556
+ *
557
+ * @param rule The original {@link Rule}.
558
+ * @param declarativeRule The converted {@link DeclarativeRule}.
559
+ *
560
+ * @returns Different errors:
561
+ * - {@link EmptyResourcesError} if the rule has empty resources,
562
+ * - {@link UnsupportedRegexpError} if the regexp is not supported
563
+ * by RE2 syntax (See {@link https://github.com/google/re2/wiki/Syntax | syntax}),
564
+ * - {@link EmptyDomainsError} if the declarative rule has empty domains
565
+ * while the original rule has non-empty domains.
566
+ */ static async checkRuleApplication(rule, declarativeRule) {
567
+ const { regexFilter, resourceTypes } = declarativeRule.condition;
568
+ // Check for empty resource types
569
+ if (resourceTypes?.length === 0) {
570
+ return new EmptyResourcesError('Conversion resourceTypes is empty', rule, declarativeRule);
571
+ }
572
+ // Check for empty initiator domains if original rule has permitted domains
573
+ const { permittedDomains } = rule;
574
+ if (permittedDomains && permittedDomains.length > 0) {
575
+ const { initiatorDomains } = declarativeRule.condition;
576
+ if (!initiatorDomains || initiatorDomains.length === 0) {
577
+ const ruleText = RuleGenerator.generate(rule.node);
578
+ const msg = `Conversion initiatorDomains is empty, but original rule's domains not: "${ruleText}"`;
579
+ return new EmptyDomainsError(msg, rule, declarativeRule);
580
+ }
581
+ }
582
+ // Check for unsupported regexps
583
+ if (regexFilter) {
584
+ try {
585
+ await re2Validator.isRegexSupported(regexFilter);
586
+ } catch (e) {
587
+ const ruleText = RuleGenerator.generate(rule.node);
588
+ const message = `Regex is unsupported in rule: "${ruleText}"`;
589
+ return new UnsupportedRegexpError(message, rule, declarativeRule, getErrorMessage(e));
590
+ }
591
+ }
592
+ return null;
593
+ }
594
+ /**
595
+ * Checks the captured conversion error, if it is one of the expected
596
+ * conversion errors - returns it, otherwise adds information about
597
+ * the original rule, packages it into a new error and returns it.
598
+ *
599
+ * @param index Index of {@link Rule}.
600
+ * @param id Identifier of the desired declarative rule.
601
+ * @param error Captured error.
602
+ *
603
+ * @returns Initial error or new packaged error.
604
+ */ static catchConversionError(index, id, error) {
605
+ if (isConversionError(error)) {
606
+ return error;
607
+ }
608
+ const message = `Non-categorized error during a conversion rule (index - ${index}, id - ${id})`;
609
+ return error instanceof Error ? new Error(message, {
610
+ cause: error
611
+ }) : new Error(message);
612
+ }
613
+ /**
614
+ * Converts the provided list of {@link Rule} into {@link DeclarativeRule},
615
+ * collecting source rule identifiers for declarative rules and catching conversion errors.
616
+ *
617
+ * @param filterListId Filter list ID.
618
+ * @param rules List of {@link Rule}.
619
+ * @param usedIds Set with already used IDs to exclude duplications in IDs.
620
+ * Since we use hash of the rule text to generate ID, we need to ensure that
621
+ * the ID is unique for the whole ruleset (especially when we convert
622
+ * several filters into one ruleset).
623
+ *
624
+ * @returns Object of {@link ConvertedRules} which containing
625
+ * declarative rules, source rule identifiers, errors.
626
+ */ async convertRules(filterListId, rules, usedIds) {
627
+ const res = {
628
+ declarativeRules: [],
629
+ errors: [],
630
+ sourceMapValues: []
631
+ };
632
+ await Promise.all(rules.map(async (rule)=>{
633
+ const { index } = rule;
634
+ const id = RegularRuleConverter.generateId(rule, usedIds);
635
+ try {
636
+ // Validate rule can be converted to DNR format
637
+ const shouldConvert = RuleDeclarativeValidator.shouldConvertRule(rule);
638
+ if (!shouldConvert) {
639
+ // Rule doesn't require conversion (e.g. $elemhide-only rules)
640
+ return;
641
+ }
642
+ // Convert rule and collect source map value
643
+ const converted = await this.convertRule(id, rule);
644
+ res.sourceMapValues.push({
645
+ declarativeRuleId: converted.id,
646
+ sourceRuleIndex: index,
647
+ filterId: filterListId
648
+ });
649
+ res.declarativeRules.push(converted);
650
+ } catch (e) {
651
+ const err = RegularRuleConverter.catchConversionError(index, id, e);
652
+ res.errors.push(err);
653
+ }
654
+ }));
655
+ return res;
656
+ }
657
+ /**
658
+ * This function groups similar rules among those already
659
+ * converted into {@link DeclarativeRule}. If a similar
660
+ * rule is found, it combines the two {@link DeclarativeRule} into one.
661
+ *
662
+ * @param converted An instance of {@link ConvertedRules} that includes
663
+ * converted declarative rules, recorded errors, and a hash mapping
664
+ * declarative rule IDs to corresponding source test rule IDs.
665
+ * @param createRuleTemplate A function that generates the template of
666
+ * a declarative rule. This template is used to compare different
667
+ * declarative rules.
668
+ * @param combineRulePair A function that combines two similar
669
+ * declarative rules into one by merging their specific properties.
670
+ *
671
+ * @returns Object with grouped similar declarative rules.
672
+ */ static groupConvertedRules(converted, createRuleTemplate, combineRulePair) {
673
+ const rulesTemplates = new Map();
674
+ const saveRuleTemplate = (rule)=>{
675
+ const template = createRuleTemplate(rule);
676
+ rulesTemplates.set(template, rule);
677
+ };
678
+ const result = {
679
+ declarativeRules: [],
680
+ sourceMapValues: [],
681
+ errors: converted.errors
682
+ };
683
+ const { sourceMapValues, declarativeRules } = converted;
684
+ declarativeRules.forEach((declarativeRule)=>{
685
+ // Try to find a sibling declarative rule
686
+ const template = createRuleTemplate(declarativeRule);
687
+ const siblingDeclarativeRule = rulesTemplates.get(template);
688
+ // Try to find the source mapping for the current declarative rule
689
+ const source = sourceMapValues.find((s)=>s.declarativeRuleId === declarativeRule.id);
690
+ if (source === undefined) {
691
+ result.errors.push(new Error(`Cannot find source for converted rule "${declarativeRule}"`));
692
+ return;
693
+ }
694
+ /**
695
+ * If a similar rule is found, combine the two declarative rules into one
696
+ * and save the combined rule's template for future comparisons.
697
+ * Also, update the source mapping to reflect the new combined rule ID.
698
+ *
699
+ * If no similar rule is found, simply save the current
700
+ * rule's template and add the source mapping as is.
701
+ */ if (siblingDeclarativeRule) {
702
+ const combinedRule = combineRulePair(siblingDeclarativeRule, declarativeRule);
703
+ saveRuleTemplate(combinedRule);
704
+ result.sourceMapValues.push({
705
+ ...source,
706
+ declarativeRuleId: combinedRule.id
707
+ });
708
+ } else {
709
+ saveRuleTemplate(declarativeRule);
710
+ result.sourceMapValues.push(source);
711
+ }
712
+ });
713
+ result.declarativeRules = Array.from(rulesTemplates.values());
714
+ return result;
715
+ }
716
+ /**
717
+ * Creates unique ID for rule via adding salt to the hash of the rule if found duplicate ID.
718
+ *
719
+ * @param rule {@link Rule} to generate ID for.
720
+ * @param usedIds Set with already used IDs to exclude duplications in IDs.
721
+ *
722
+ * @returns Unique ID for the rule.
723
+ */ static generateId(rule, usedIds) {
724
+ let id = rule.getTextHash();
725
+ // While the ID is already used, we add salt to the hash of the rule
726
+ let salt = 0;
727
+ while(usedIds.has(id)){
728
+ salt += 1;
729
+ id = rule.getTextHash(salt);
730
+ }
731
+ usedIds.add(id);
732
+ return id;
733
+ }
734
+ /**
735
+ * Groups converted rules. Base implementation returns rules as-is without
736
+ * grouping.
737
+ *
738
+ * Subclasses (e.g. {@link CspConverter}, {@link RemoveHeaderConverter})
739
+ * override this to merge rules with identical conditions.
740
+ *
741
+ * @param converted Converted rules before grouping.
742
+ *
743
+ * @returns Converted rules after grouping.
744
+ */ // eslint-disable-next-line class-methods-use-this -- template method, overridden by subclasses
745
+ groupConverted(converted) {
746
+ return converted;
747
+ }
748
+ /**
749
+ * Converts provided bunch of {@link Rule} to {@link DeclarativeRule}
750
+ * via generating source map for it and catching errors of conversations.
751
+ *
752
+ * Subclasses can add post-processing logic by overriding
753
+ * {@link RegularRuleConverter.groupConverted}.
754
+ *
755
+ * @param filterListId Filter list ID.
756
+ * @param rules List of {@link Rule}.
757
+ * @param usedIds Set with already used IDs to exclude duplications in IDs.
758
+ *
759
+ * @returns Object of {@link ConvertedRules} which containing
760
+ * declarative rules, source rule identifiers, errors.
761
+ */ async convert(filterListId, rules, usedIds) {
762
+ const converted = await this.convertRules(filterListId, rules, usedIds);
763
+ return this.groupConverted(converted);
764
+ }
765
+ /**
766
+ * Constructor of {@link RegularRuleConverter}.
767
+ *
768
+ * @param webAccessibleResourcesPath Path to web accessible resources.
769
+ */ constructor(webAccessibleResourcesPath){
770
+ this.webAccessibleResourcesPath = webAccessibleResourcesPath;
771
+ }
772
+ }
773
+ /**
774
+ * Resource types that are compatible with {@link RuleActionType.AllowAllRequests}.
775
+ */ RegularRuleConverter.ALLOW_ALL_REQUEST_COMPATIBLE_RESOURCE_TYPES = new Set([
776
+ ResourceType.MainFrame,
777
+ ResourceType.SubFrame
778
+ ]);
779
+ /**
780
+ * Characters that have special meaning in Chrome DNR urlFilter syntax.
781
+ * If a $removeparam param name contains any of these, we cannot safely
782
+ * embed it as a urlFilter token and must skip the augmentation.
783
+ */ RegularRuleConverter.URL_FILTER_SPECIAL_CHARS = /[|*^]/;
784
+ /**
785
+ * Pipe character used as a separator in $removeparam multi-value rules,
786
+ * e.g. `$removeparam=utm_source|utm_medium`.
787
+ */ RegularRuleConverter.PIPE_SEPARATOR = '|';
788
+
789
+ export { RegularRuleConverter };