@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,185 @@
1
+ import { Rule } from './rule.js';
2
+
3
+ /**
4
+ * Class for validating network rules against DNR (declarative network request) constraints.
5
+ * Ported from tsurlfilter's `RuleDeclarativeValidator`.
6
+ */
7
+ declare class RuleDeclarativeValidator {
8
+ /**
9
+ * Checks if the $removeparam value in the provided network rule
10
+ * is supported for conversion to MV3.
11
+ *
12
+ * @param rule Network rule.
13
+ * @param name Modifier's name.
14
+ *
15
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
16
+ */
17
+ private static checkRemoveParamModifierFn;
18
+ /**
19
+ * Checks if the provided rule is an allowlist rule.
20
+ *
21
+ * @param rule Network rule.
22
+ * @param name Modifier's name.
23
+ *
24
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
25
+ */
26
+ private static checkAllowRulesFn;
27
+ /**
28
+ * Checks if the specified modifier is included in rule explicitly.
29
+ *
30
+ * @param rule Network rule.
31
+ * @param name Modifier's name.
32
+ *
33
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
34
+ */
35
+ private static checkHasModifierExplicitlyFn;
36
+ /**
37
+ * Checks if the $removeheader value in the provided network rule
38
+ * is supported for conversion to MV3.
39
+ *
40
+ * @param rule Network rule.
41
+ * @param name Modifier's name.
42
+ *
43
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
44
+ */
45
+ private static checkRemoveHeaderModifierFn;
46
+ /**
47
+ * Checks if the $removeheader modifier is combined only with modifiers
48
+ * that are compatible with it, aligned with tsurlfilter's
49
+ * `RemoveHeaderCompatibleOptions` and `validateRemoveHeaderRule`.
50
+ *
51
+ * Because dnr-converter stores modifiers differently from tsurlfilter, two
52
+ * kinds of incompatible modifiers must be detected:
53
+ *
54
+ * First, loop-reachable modifiers present in `rule.enabledModifiers`
55
+ * (e.g. `$method`, `$csp`, `$redirect`, `$cookie`, `$removeparam`,
56
+ * `$app`, `$network`, DNS modifiers). Any enabled modifier that is not
57
+ * in {@link REMOVEHEADER_COMPATIBLE_MODIFIERS} makes the rule
58
+ * incompatible. This mirrors tsurlfilter's
59
+ * `enabledOptions ⊆ RemoveHeaderCompatibleOptions`.
60
+ *
61
+ * Second, the `$to` modifier, which is parsed into `permittedToDomains` /
62
+ * `restrictedToDomains` and therefore never enters `enabledModifiers`,
63
+ * so it is invisible to the loop. Tsurlfilter still rejects it (it sets
64
+ * the `$to` flag, which is absent from
65
+ * `RemoveHeaderCompatibleOptions`), so it is rejected here explicitly
66
+ * for parity.
67
+ *
68
+ * `$domain` and `$denyallow` set no flag in tsurlfilter and are compatible
69
+ * with `$removeheader`, so they are intentionally NOT checked here.
70
+ *
71
+ * Parity relies on `rule.ts` keeping `$to` and `$domain` in separate fields
72
+ * — only `$to` (`permittedToDomains`/`restrictedToDomains`) is field-only
73
+ * and thus invisible to the `enabledModifiers` loop.
74
+ *
75
+ * @param rule Network rule.
76
+ * @param name Modifier's name.
77
+ *
78
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
79
+ */
80
+ private static checkRemoveHeaderCompatibleModifiersFn;
81
+ /**
82
+ * Checks if the $method values in the provided network rule
83
+ * are supported for conversion to MV3.
84
+ *
85
+ * @param rule Network rule.
86
+ * @param name Modifier's name.
87
+ *
88
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
89
+ */
90
+ private static checkMethodModifierFn;
91
+ /**
92
+ * Checks if the $cookie values in the provided network rule
93
+ * are supported for conversion to MV3.
94
+ * Only $cookie without parameters is supported.
95
+ *
96
+ * @param rule Network rule.
97
+ * @param name Modifier's name.
98
+ *
99
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
100
+ */
101
+ private static checkCookieModifierFn;
102
+ /**
103
+ * Checks if rule is a "document"-allowlist and contains all these
104
+ * `$elemhide,content,urlblock,jsinject` modifiers at the same time.
105
+ * If it is - we allow partial conversion of this rule, because `$content`
106
+ * is not supported in MV3 at all and `$jsinject` and `$urlblock`
107
+ * are not implemented yet, but we can support at least allowlist-rule
108
+ * with `$elemhide` modifier (not in the DNR, but with tsurlfilter engine).
109
+ *
110
+ * @param rule Network rule.
111
+ * @param name Modifier's name.
112
+ *
113
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
114
+ */
115
+ private static checkDocumentAllowlistFn;
116
+ /**
117
+ * Checks if the $header values in the provided network rule
118
+ * are supported for conversion to MV3.
119
+ * DNR does not support regex patterns in HeaderInfo.values field.
120
+ *
121
+ * @param rule Network rule.
122
+ * @param name Modifier's name.
123
+ *
124
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
125
+ */
126
+ private static checkHeaderModifierFn;
127
+ /**
128
+ * The $redirect-rule support will be possible to implement after browsers add this feature:
129
+ * https://github.com/w3c/webextensions/issues/493.
130
+ *
131
+ * @param rule Network rule.
132
+ * @param name Modifier's name.
133
+ *
134
+ * @returns Error {@link UnsupportedModifierError} or null if rule is supported.
135
+ */
136
+ private static checkRedirectModifierFn;
137
+ /**
138
+ * Maps each canonical modifier name to its validation configuration.
139
+ */
140
+ private static optionsValidators;
141
+ /**
142
+ * Checks if a network rule can be converted to a declarative format or not.
143
+ * We skip the following modifiers:
144
+ *
145
+ * All specific exceptions:
146
+ * $genericblock;
147
+ * $jsinject;
148
+ * $urlblock;
149
+ * $content;
150
+ * $extension;
151
+ * $stealth;
152
+ *
153
+ * Following specific exceptions are not required to be converted, but they
154
+ * are used in the cosmetic filtering:
155
+ * $elemhide;
156
+ * $generichide;
157
+ * $specifichide;
158
+ *
159
+ * Other:
160
+ * $header;
161
+ * $popup;
162
+ * $csp;
163
+ * $replace;
164
+ * $cookie - if modifier is not empty and contains any parameters;
165
+ * $redirect - if the rule is allowlist;
166
+ * $removeparam - if it contains a negation, or regexp,
167
+ * or the rule is allowlist;
168
+ * $removeheader - if it contains a title from a prohibited list
169
+ * (see FORBIDDEN_HEADERS in Rule);
170
+ * $jsonprune;
171
+ * $method - if the modifier contains 'trace' method;
172
+ * $hls;
173
+ * $permissions.
174
+ *
175
+ * @param rule Network rule.
176
+ *
177
+ * @returns Boolean flag - `false` if the rule does not require conversion
178
+ * and `true` if the rule is convertible.
179
+ *
180
+ * @throws Error with type {@link UnsupportedModifierError} if the rule is not convertible.
181
+ */
182
+ static shouldConvertRule(rule: Rule): boolean;
183
+ }
184
+
185
+ export { RuleDeclarativeValidator };
@@ -0,0 +1,269 @@
1
+ import { NetworkRule, AnyRule } from '@adguard/agtree';
2
+ import { ResourceType, RequestMethod } from '../declarative-rule/rule-condition.js';
3
+ import { HttpHeaderMatcher } from './rule-types.js';
4
+
5
+ /**
6
+ * @file {@link Rule} — parsed and normalized network filtering rule.
7
+ *
8
+ * Priority calculation is delegated to {@link RulePriority}.
9
+ * Badfilter negation logic is delegated to {@link RuleBadfilter}.
10
+ */
11
+
12
+ /**
13
+ * Parsed and normalized network filtering rule.
14
+ *
15
+ * Instances are created exclusively via the static factory methods
16
+ * {@link Rule.createFromText} and {@link Rule.parseFromNode}.
17
+ */
18
+ declare class Rule {
19
+ /**
20
+ * Filter list ID from which the rule was extracted.
21
+ */
22
+ readonly filterListId: number;
23
+ /**
24
+ * Rule index within the filter list.
25
+ */
26
+ readonly index: number;
27
+ /**
28
+ * Original AST node. Kept for rule text generation and node-level
29
+ * inspection.
30
+ */
31
+ readonly node: NetworkRule;
32
+ /**
33
+ * URL pattern from the AST node (`node.pattern.value`).
34
+ */
35
+ readonly pattern: string;
36
+ /**
37
+ * Hash of the pattern, computed via `fastHash()`.
38
+ * Used for quick badfilter comparison.
39
+ */
40
+ readonly hash: number;
41
+ /**
42
+ * Whether this is an allowlist (exception) rule.
43
+ */
44
+ readonly allowlist: boolean;
45
+ /**
46
+ * Set of canonical modifier names that are enabled on this rule.
47
+ *
48
+ * Content-type modifiers (script, image, etc.) are tracked here
49
+ * **in addition to** being mapped to {@link permittedResourceTypes}.
50
+ */
51
+ readonly enabledModifiers: Set<string>;
52
+ /**
53
+ * Set of canonical modifier names that are disabled (negated) on
54
+ * this rule. E.g. `~third-party` → `"third-party"` in this set.
55
+ */
56
+ readonly disabledModifiers: Set<string>;
57
+ /**
58
+ * Permitted (non-negated) domains from the `$domain` modifier.
59
+ */
60
+ readonly permittedDomains: string[] | null;
61
+ /**
62
+ * Restricted (negated) domains from the `$domain` modifier.
63
+ */
64
+ readonly restrictedDomains: string[] | null;
65
+ /**
66
+ * Permitted destination domains from the `$to` modifier.
67
+ */
68
+ readonly permittedToDomains: string[] | null;
69
+ /**
70
+ * Restricted destination domains from the `$to` modifier.
71
+ */
72
+ readonly restrictedToDomains: string[] | null;
73
+ /**
74
+ * Exception domains from the `$denyallow` modifier.
75
+ */
76
+ readonly denyAllowDomains: string[] | null;
77
+ /**
78
+ * Permitted resource types set by content-type modifiers,
79
+ * already mapped to DNR {@link ResourceType} values.
80
+ */
81
+ readonly permittedResourceTypes: ResourceType[];
82
+ /**
83
+ * Restricted resource types set by negated content-type modifiers,
84
+ * already mapped to DNR {@link ResourceType} values.
85
+ */
86
+ readonly restrictedResourceTypes: ResourceType[];
87
+ /**
88
+ * Permitted HTTP methods from the `$method` modifier.
89
+ */
90
+ readonly permittedMethods: RequestMethod[] | null;
91
+ /**
92
+ * Restricted HTTP methods from the `$method` modifier.
93
+ */
94
+ readonly restrictedMethods: RequestMethod[] | null;
95
+ /**
96
+ * Name of the advanced modifier (e.g. `"csp"`, `"redirect"`,
97
+ * `"removeparam"`, `"removeheader"`, `"cookie"`, `"permissions"`).
98
+ */
99
+ readonly advancedModifierName: string | null;
100
+ /**
101
+ * Raw string value of the advanced modifier.
102
+ */
103
+ readonly advancedModifierValue: string | null;
104
+ /**
105
+ * Parsed data for the `$header` modifier.
106
+ */
107
+ readonly headerMatcher: HttpHeaderMatcher | null;
108
+ /**
109
+ * Effective header name to be removed by `$removeheader`.
110
+ * `null` when no valid `$removeheader` modifier is present.
111
+ */
112
+ readonly removeHeaderName: string | null;
113
+ /**
114
+ * Whether the `$removeheader` modifier targets request headers
115
+ * (true) or response headers (false).
116
+ */
117
+ readonly removeHeaderIsRequestType: boolean;
118
+ /**
119
+ * Whether the rule uses `$redirect-rule` (only redirects
120
+ * already-blocked requests) vs plain `$redirect`.
121
+ */
122
+ readonly isRedirectRuleModifier: boolean;
123
+ /**
124
+ * Computed DNR priority (positive integer ≥ 1).
125
+ */
126
+ readonly priority: number;
127
+ /**
128
+ * Creates a new {@link Rule} from filter list metadata and an already-converted
129
+ * network rule AST node.
130
+ *
131
+ * @param filterListId Filter list ID.
132
+ * @param index Rule index within the filter list.
133
+ * @param node Network rule AST node (must already be in AG syntax).
134
+ *
135
+ * @throws `SyntaxError` when the pattern contains spaces, the rule is too
136
+ * general, or any modifier is invalid.
137
+ */
138
+ private constructor();
139
+ /**
140
+ * Checks if the specified modifier is enabled on the rule.
141
+ *
142
+ * @param modifier Canonical modifier name (e.g. `"redirect"`, `"script"`).
143
+ *
144
+ * @returns `true` if the modifier is enabled.
145
+ */
146
+ isModifierEnabled(modifier: string): boolean;
147
+ /**
148
+ * Checks if the specified modifier is disabled (negated) on the rule.
149
+ *
150
+ * @param modifier Canonical modifier name.
151
+ *
152
+ * @returns `true` if the modifier is disabled.
153
+ */
154
+ isModifierDisabled(modifier: string): boolean;
155
+ /**
156
+ * Returns `true` if one and only the specified modifier is enabled.
157
+ *
158
+ * @param modifier Canonical modifier name.
159
+ *
160
+ * @returns `true` if the modifier is the only enabled modifier.
161
+ */
162
+ isSingleModifierEnabled(modifier: string): boolean;
163
+ /**
164
+ * Checks if the rule completely disables filtering (elemhide + content +
165
+ * urlblock + jsinject all enabled on an allowlist rule).
166
+ *
167
+ * @returns `true` if the rule disables all filtering.
168
+ */
169
+ isFilteringDisabled(): boolean;
170
+ /**
171
+ * Checks if the rule pattern is a regular expression.
172
+ *
173
+ * @returns `true` if the rule pattern is a regex.
174
+ */
175
+ isRegexRule(): boolean;
176
+ /**
177
+ * Returns the rule text generated from the AST node.
178
+ *
179
+ * @returns Rule text string.
180
+ */
181
+ getText(): string;
182
+ /**
183
+ * Gets a hash for the full text of the rule. Needed to keep the ID of the
184
+ * rule in the filter stable between runs (for CWS "skip review").
185
+ *
186
+ * @param salt Optional numeric salt for uniqueness.
187
+ *
188
+ * @returns Hash value in range [0, 2^31-1].
189
+ */
190
+ getTextHash(salt?: number): number;
191
+ /**
192
+ * Returns the applicable header name for `$removeheader`, or `null`
193
+ * if the direction doesn't match or no valid header is set.
194
+ *
195
+ * @param isRequestHeaders `true` for request headers, `false` for response.
196
+ *
197
+ * @returns Header name or `null`.
198
+ */
199
+ getApplicableHeaderName(isRequestHeaders: boolean): string | null;
200
+ /**
201
+ * Checks whether this rule (which must carry `$badfilter`) negates
202
+ * `targetRule`. Delegates to {@link RuleBadfilter.negates}.
203
+ *
204
+ * @param targetRule The rule to test for negation.
205
+ *
206
+ * @returns `true` if this rule negates `targetRule`.
207
+ */
208
+ negatesBadfilter(targetRule: Rule): boolean;
209
+ /**
210
+ * Determines the effective header name and direction for a
211
+ * `$removeheader` value.
212
+ *
213
+ * @param value Raw modifier value (may be empty for allowlist rules).
214
+ *
215
+ * @returns `name` — effective header name, or `null` when
216
+ * forbidden/unsupported; `isRequest` — `true` when targeting request
217
+ * headers.
218
+ */
219
+ private static computeRemoveHeaderInfo;
220
+ /**
221
+ * Parses the `$header` modifier value into an {@link HttpHeaderMatcher}.
222
+ *
223
+ * Expected format: `<header-name>` or `<header-name>:<value-or-/regex/>`.
224
+ *
225
+ * @param value Raw modifier value string.
226
+ *
227
+ * @returns Parsed header matcher.
228
+ */
229
+ private static parseHeaderModifier;
230
+ /**
231
+ * Checks if a network rule node is too general to be useful (no modifiers
232
+ * and pattern shorter than 4 characters).
233
+ *
234
+ * @param node Network rule AST node.
235
+ *
236
+ * @returns `true` if the rule is too general.
237
+ */
238
+ static isTooGeneral(node: NetworkRule): boolean;
239
+ /**
240
+ * Parses and converts rule text to AG syntax, then creates
241
+ * {@link Rule} instances from all resulting network-rule nodes.
242
+ *
243
+ * @param filterId Filter list ID.
244
+ * @param ruleIndex Rule index within the filter list.
245
+ * @param text Raw rule text.
246
+ *
247
+ * @returns Array of {@link Rule} parsed from `text`.
248
+ *
249
+ * @throws `Error` when parsing or conversion fails.
250
+ */
251
+ static createFromText(filterId: number, ruleIndex: number, text: string): Rule[];
252
+ /**
253
+ * Converts an already-parsed rule node to AG syntax and creates
254
+ * {@link Rule} instances from all resulting network-rule nodes.
255
+ *
256
+ * @param filterListId Filter list ID.
257
+ * @param index Rule index within the filter list.
258
+ * @param node Rule AST node.
259
+ *
260
+ * @returns Array of {@link Rule} parsed from `node`.
261
+ *
262
+ * @throws `Error` when conversion to AG syntax fails.
263
+ * @throws `SyntaxError` when the rule has spaces in pattern or is too
264
+ * general.
265
+ */
266
+ static parseFromNode(filterListId: number, index: number, node: AnyRule): Rule[];
267
+ }
268
+
269
+ export { HttpHeaderMatcher, Rule };
@@ -0,0 +1,128 @@
1
+ import * as v from 'valibot';
2
+
3
+ /**
4
+ * @file MetadataRuleset class for managing and serializing metadata rulesets.
5
+ *
6
+ * A metadata ruleset stores checksums and additional properties for a
7
+ * collection of DNR rulesets. It serializes to a JSON array containing a
8
+ * single declarative rule with a `metadata` field.
9
+ */
10
+
11
+ /**
12
+ * Metadata ruleset ID.
13
+ */
14
+ declare const METADATA_RULESET_ID = 0;
15
+ /**
16
+ * Checksum map validator.
17
+ */
18
+ declare const checksumMapValidator: v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>;
19
+ /**
20
+ * Checksum map type.
21
+ */
22
+ type ChecksumMap = v.InferOutput<typeof checksumMapValidator>;
23
+ /**
24
+ * Represents a specialized metadata ruleset for managing and validating
25
+ * metadata associated with various rulesets.
26
+ *
27
+ * This class handles checksums and additional properties, providing methods
28
+ * to manipulate and query this metadata.
29
+ */
30
+ declare class MetadataRuleset {
31
+ /**
32
+ * The underlying metadata rule holding checksums and additional properties.
33
+ */
34
+ private metadataRule;
35
+ /**
36
+ * Creates an instance of the MetadataRuleset class.
37
+ *
38
+ * @param checksums A map of checksums, where each key corresponds to a
39
+ * rule set ID and each value is the checksum for that ruleset.
40
+ * Defaults to an empty object.
41
+ * @param additionalProperties A collection of additional properties, where
42
+ * keys are property names and values are their associated data. These
43
+ * properties are JSON serializable but not validated by the class.
44
+ * Defaults to an empty object.
45
+ *
46
+ * @note
47
+ * Inputs are shallow-cloned so the instance owns its internal state.
48
+ */
49
+ constructor(checksums?: ChecksumMap, additionalProperties?: Record<string, unknown>);
50
+ /**
51
+ * Returns rule set id.
52
+ *
53
+ * @returns Rule set id.
54
+ */
55
+ getId(): string;
56
+ /**
57
+ * Sets checksum for the specified rule set.
58
+ *
59
+ * @param rulesetId Rule set id.
60
+ * @param checksum Checksum.
61
+ */
62
+ setChecksum(rulesetId: string, checksum: string): void;
63
+ /**
64
+ * Returns checksum for the specified rule set.
65
+ *
66
+ * @param rulesetId Rule set id.
67
+ *
68
+ * @returns Checksum or undefined if not found.
69
+ */
70
+ getChecksum(rulesetId: string): string | undefined;
71
+ /**
72
+ * Returns all rule set ids in the metadata.
73
+ *
74
+ * @returns Rule set ids.
75
+ */
76
+ getRulesetIds(): string[];
77
+ /**
78
+ * Gets additional property.
79
+ *
80
+ * @param key Property key.
81
+ *
82
+ * @returns Property value or undefined if not found.
83
+ */
84
+ getAdditionalProperty(key: string): unknown;
85
+ /**
86
+ * Sets additional property.
87
+ *
88
+ * @param key Property key.
89
+ * @param value Property value. The class does not validate that the value is
90
+ * JSON-serializable; callers are responsible for ensuring serializability.
91
+ */
92
+ setAdditionalProperty(key: string, value: unknown): void;
93
+ /**
94
+ * Checks whether additional property exists.
95
+ *
96
+ * @param key Property key.
97
+ *
98
+ * @returns Whether the property exists.
99
+ */
100
+ hasAdditionalProperty(key: string): boolean;
101
+ /**
102
+ * Removes additional property.
103
+ *
104
+ * @param key Property key.
105
+ */
106
+ removeAdditionalProperty(key: string): void;
107
+ /**
108
+ * Serializes the ruleset to a string.
109
+ *
110
+ * @param pretty Whether to prettify the output.
111
+ *
112
+ * @returns Serialized ruleset.
113
+ */
114
+ serialize(pretty?: boolean): string;
115
+ /**
116
+ * Deserializes the ruleset from a string.
117
+ *
118
+ * @param rawJson Serialized ruleset.
119
+ *
120
+ * @returns Deserialized ruleset.
121
+ *
122
+ * @throws {ValiError} If the metadata fails schema validation.
123
+ * @throws {SyntaxError} If `rawJson` is not valid JSON.
124
+ */
125
+ static deserialize(rawJson: string): MetadataRuleset;
126
+ }
127
+
128
+ export { METADATA_RULESET_ID, MetadataRuleset };
@@ -0,0 +1,70 @@
1
+ import { SourceRuleIdxAndFilterId } from './source-map.js';
2
+
3
+ /**
4
+ * @file Contains the RulesHashMap class for fast rule matching
5
+ * by hash, used for $badfilter checking.
6
+ */
7
+
8
+ type RuleHash = number;
9
+ /**
10
+ * Contains a hash of the rule and the 'coordinates' of this rule: the source
11
+ * filter ID and the rule index within this filter.
12
+ */
13
+ type HashWithSource = {
14
+ hash: RuleHash;
15
+ source: SourceRuleIdxAndFilterId;
16
+ };
17
+ /**
18
+ * Interface for rules hash map operations.
19
+ */
20
+ interface IRulesHashMap {
21
+ /**
22
+ * Tries to find rules with same hash and if found - returns theirs sources:
23
+ * filter id and rule id.
24
+ *
25
+ * @param hash Number hash to search rules with same hash.
26
+ *
27
+ * @returns List of sources (filter id and rule id) of rules with same hash as
28
+ * provided in parameter or empty array.
29
+ */
30
+ findRules(hash: number): SourceRuleIdxAndFilterId[];
31
+ /**
32
+ * Serializes map of rules hashes to JSON string.
33
+ *
34
+ * @returns JSON string.
35
+ */
36
+ serialize(): string;
37
+ }
38
+ /**
39
+ * Contains a dictionary where the key is the hash of the rule and the value is
40
+ * a list of sources for the rule. Storing this dictionary is necessary for fast
41
+ * rule matching, which can be negated by $badfilter.
42
+ */
43
+ declare class RulesHashMap implements IRulesHashMap {
44
+ /**
45
+ * Map of rule hashes to their sources.
46
+ */
47
+ private map;
48
+ /**
49
+ * Creates new {@link RulesHashMap}.
50
+ *
51
+ * @param listOfRulesWithHash List of rules hashes and rules sources:
52
+ * filter id with rule index.
53
+ */
54
+ constructor(listOfRulesWithHash: HashWithSource[]);
55
+ /** @inheritdoc */
56
+ findRules(hash: number): SourceRuleIdxAndFilterId[];
57
+ /**
58
+ * Deserializes dictionary from raw string.
59
+ *
60
+ * @param rawString The original dictionary that was serialized into a string.
61
+ *
62
+ * @returns Deserialized dictionary.
63
+ */
64
+ static deserializeSources(rawString: string): HashWithSource[];
65
+ /** @inheritdoc */
66
+ serialize(): string;
67
+ }
68
+
69
+ export { RulesHashMap };
70
+ export type { HashWithSource, IRulesHashMap };