@adguard/dnr-converter 2.0.0 → 2.1.0

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 +51902 -47539
  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 +479 -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
package/README.md CHANGED
@@ -27,6 +27,7 @@ extensions.
27
27
  - [`ConverterOptions`](#converteroptions)
28
28
  - [Simple flow: `FilterConverter` + `Ruleset`](#simple-flow-filterconverter--ruleset)
29
29
  - [Advanced flow: `FilterConverter` with `withSourceMap: true` + `RulesetWithSourceMap`](#advanced-flow-filterconverter-with-withsourcemap-true--rulesetwithsourcemap)
30
+ - [Standalone CSP conversion: `convertCspRules()`](#standalone-csp-conversion-convertcsprules)
30
31
  - [Compact ruleset file format](#compact-ruleset-file-format)
31
32
  - [`MetadataRuleset`](#metadataruleset)
32
33
  - [`isSafeRule(rule)`](#issaferulerule)
@@ -70,13 +71,35 @@ MV3 limitations (inherent to the Declarative Net Request API) are:
70
71
  - `$important`, `$match-case`, `$method`, `$to`, `$denyallow`, `$header`
71
72
  (no regex values), `$all`
72
73
  - `$redirect` — allowlist rules not supported
73
- - `$csp`, `$removeparam`, `$removeheader`, `$permissions` — allowlist rules
74
+ - `$csp` — exceptions are supported only through `convertCspRules()`, which
75
+ sees all filters at once; the regular `convert()` still rejects an allowlist
76
+ `$csp` rule. An exception is applied when it has the exact conditions of the
77
+ blocker, when it is wider than the blocker's domain (`@@||example.com^$csp=x`
78
+ also cancels `||example.com/path$csp=x` and `||sub.example.com^$csp=x`), or
79
+ when it has no pattern and covers the whole blocker (`@@$csp=x` and
80
+ `@@*$csp=x` cancel `*$csp=x,domain=a.com` and `||a.com^$csp=x,third-party`).
81
+ Path-level subtraction is not expressible in DNR. An exception with `$domain` against a
82
+ blocker that also gets the `main_frame` rule is reported instead of applied
83
+ when the excluded domain overlaps the blocker's `$domain`, e.g.
84
+ `@@||a.com^$csp,domain=a.com` with `$csp=...,domain=a.com`, while
85
+ `@@||cdn.example.net^$csp,domain=a.com` against `$csp=...,domain=a.com` is
86
+ applied. Any exception applies only when it outranks the blocking rule, so
87
+ `@@||example.com^$csp` does not cancel `||example.com^$csp=...,important`,
88
+ and `@@||example.com^$csp=script-src 'none'` does not cancel
89
+ `||example.com^$csp=script-src 'none',important` either; this differs from
90
+ MV2, where the value-less exception wins, and from what the filtering log
91
+ shows in MV3
92
+ - `$removeparam`, `$removeheader`, `$permissions` — allowlist rules
74
93
  not supported; rules with identical conditions are combined only within the
75
94
  same filter, not across filters
76
95
  - `$urltransform` — limited; complex transforms produce multiple declarative
77
- rules via pipeline stages
96
+ rules via pipeline stages. `$urltransform` rules do not get the additional
97
+ target-hostname rule, so a `$domain` with permitted domains does not match
98
+ document navigations started by the browser. An excluded-only `$domain`
99
+ still matches them through the base rule.
78
100
  - `$cookie` — limited; only supported without parameters (bare `$cookie`)
79
- - `$badfilter` — partial: does not handle `$domain` intersections correctly
101
+ - `$badfilter` — partial: a `$domain` intersection disables the whole
102
+ declarative rule, not only the intersecting domains
80
103
 
81
104
  **Not yet supported / not convertible to DNR**:
82
105
 
@@ -177,6 +200,7 @@ Configuration for the conversion process:
177
200
  | `combine` | `boolean?` | Merge all input filters into a single combined rule set. |
178
201
  | `withSourceMap` | `boolean?` | When `true`, returns `RulesetWithSourceMap` instead of `Ruleset`. Enables source maps, `$badfilter` cross-filter support, and lazy loading. |
179
202
  | `badFilterRules` | `Rule[]?` | Static `$badfilter` rules to apply at scan time (`withSourceMap: true` only). |
203
+ | `excludeCspRules` | `boolean?` | Skip CSP rules during regular conversion when they are rebuilt by [`convertCspRules()`](#standalone-csp-conversion-convertcsprules) (`withSourceMap: true` only). |
180
204
 
181
205
  ### Simple flow: `FilterConverter` + `Ruleset`
182
206
 
@@ -273,6 +297,7 @@ const rulesToDisable = await converter.computeRulesToDisable(
273
297
  | `getDeclarativeRules()` | `Promise<DeclarativeRule[]>` | All converted DNR rules (lazy) |
274
298
  | `getUnsafeRules()` | `Promise<DeclarativeRule[]>` | Unsafe rules subset (lazy) |
275
299
  | `getRulesById(id)` | `Promise<SourceRuleAndFilterId[]>` | Source rules for a DNR rule |
300
+ | `getSourceRuleIndexes(declarativeRuleId)` | `Promise<SourceRuleIdxAndFilterId[]>` | Filter id and source rule index of each source of a DNR rule |
276
301
  | `getBadFilterRules()` | `NetworkRule[]` | `$badfilter` rules in this set |
277
302
  | `getRulesHashMap()` | `IRulesHashMap` | Hash map for fast `$badfilter` matching |
278
303
  | `getMetadataRulesCount()` | `number` | Metadata rules in the ruleset file the rule set was read from (0 if not read from a file) |
@@ -294,6 +319,40 @@ Result returned by converter methods:
294
319
  | `limitations` | `LimitationError[]` | Warnings about exceeded limits |
295
320
  | `declarativeRulesToCancel` | `UpdateStaticRulesOptions[]?` | Static rule IDs to disable (from `computeRulesToDisable`) |
296
321
 
322
+ ### Standalone CSP conversion: `convertCspRules()`
323
+
324
+ `$csp` exceptions need a pass over all filters at once: an exception from a user
325
+ rule must be able to cancel a blocking rule from a built-in filter, which
326
+ streaming conversion cannot do. `convertCspRules(filters, resourcesPath?)`
327
+ resolves the exceptions and returns a single combined ruleset of the remaining
328
+ CSP rules (source-map mode).
329
+
330
+ To avoid converting CSP rules twice, pass `excludeCspRules: true` to the regular
331
+ conversion. `$badfilter` rules stay in the stream — they can still disable other
332
+ rules.
333
+
334
+ ```ts
335
+ const converter = new FilterConverter();
336
+
337
+ const [regular] = await converter.convert(filters, {
338
+ withSourceMap: true,
339
+ combine: true,
340
+ excludeCspRules: true,
341
+ });
342
+ const csp = await converter.convertCspRules(filters, '/web-accessible-resources');
343
+ ```
344
+
345
+ Without `combine: true` the regular conversion returns one result per filter, so
346
+ the destructuring above would keep only the first filter.
347
+
348
+ Only candidate lines are parsed: a line must contain `csp` or a `csp` alias as a
349
+ modifier, so `csp` does not have to be the first modifier. `$badfilter` lines are
350
+ not candidates any more: the regular pass owns them. The whole text is still
351
+ split into lines, so the cost grows with the list size, while parsing stays
352
+ proportional to the number of candidates. Exceptions that cannot be applied — for
353
+ example path-level subtraction — are reported as conversion errors and leave the
354
+ blocking rule active.
355
+
297
356
  ### Compact ruleset file format
298
357
 
299
358
  `serializeCompact()` and `MetadataRuleset.serialize()` write a JSON array of