@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.
- package/README.md +62 -3
- package/dist/cli.cjs +52148 -47533
- package/dist/constants.js +4 -1
- package/dist/errors/conversion-errors/index.js +3 -2
- package/dist/errors/conversion-errors/unexpected-conversion-error.js +23 -0
- package/dist/errors/scan-errors.js +39 -0
- package/dist/errors/unavailable-sources-errors/unavailable-filter-source-error.js +10 -1
- package/dist/filter-converter/filter-converter.js +151 -6
- package/dist/index.js +5 -1
- package/dist/package.json.js +1 -1
- package/dist/rule/rule-badfilter.js +144 -55
- package/dist/rule/rule-validator.js +56 -6
- package/dist/rule/rule.js +95 -9
- package/dist/rule-converters/action-kind.js +121 -0
- package/dist/rule-converters/csp-condition-coverage.js +268 -0
- package/dist/rule-converters/csp-converter.js +132 -11
- package/dist/rule-converters/csp-rules-resolver.js +417 -0
- package/dist/rule-converters/regular-rule-converter.js +489 -129
- package/dist/rule-converters/rules-converter.js +75 -7
- package/dist/rule-converters/rules-grouper.js +5 -3
- package/dist/rules-scanner/rules-scanner.js +124 -56
- package/dist/ruleset/ruleset-with-source-map.js +5 -1
- package/dist/types/src/errors/conversion-errors/index.d.ts +7 -2
- package/dist/types/src/errors/conversion-errors/unexpected-conversion-error.d.ts +21 -0
- package/dist/types/src/errors/scan-errors.d.ts +38 -0
- package/dist/types/src/errors/unavailable-sources-errors/unavailable-filter-source-error.d.ts +9 -1
- package/dist/types/src/filter-converter/filter-converter-options.d.ts +18 -1
- package/dist/types/src/filter-converter/filter-converter.d.ts +83 -6
- package/dist/types/src/index.d.ts +7 -3
- package/dist/types/src/rule/rule-validator.d.ts +21 -0
- package/dist/types/src/rule/rule.d.ts +52 -2
- package/dist/types/src/rule-converters/csp-converter.d.ts +12 -0
- package/dist/types/src/ruleset/ruleset-with-source-map.d.ts +14 -0
- package/dist/utils/string.js +27 -1
- package/package.json +6 -6
- 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
|
|
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:
|
|
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
|