Skip to content

Commit 8808e39

Browse files
committed
fix(selectors): preserve escaped attributes and refine compiler fuzz checks
1 parent 495e029 commit 8808e39

6 files changed

Lines changed: 177 additions & 97 deletions

File tree

‎docs/api.md‎

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -23,49 +23,49 @@ Select descendants, test a match, or find the nearest matching ancestor.
2323

2424
| Method | Result |
2525
| --- | --- |
26-
| [`closest(selectors, element, callback)`](../src/nwsapi.mts#L5732) | Returns the nearest match, starting with the element, or `null`. |
27-
| [`first(selectors, context, callback)`](../src/nwsapi.mts#L5728) | Returns the first matching descendant, or `null`. |
28-
| [`match(selectors, element, callback)`](../src/nwsapi.mts#L5729) | Returns whether the element matches. |
29-
| [`select(selectors, context, callback)`](../src/nwsapi.mts#L5730) | Returns matching descendants. Results are arrays by default. `NODE_LIST` can enable static NodeList results. |
26+
| [`closest(selectors, element, callback)`](../src/nwsapi.mts#L5739) | Returns the nearest match, starting with the element, or `null`. |
27+
| [`first(selectors, context, callback)`](../src/nwsapi.mts#L5735) | Returns the first matching descendant, or `null`. |
28+
| [`match(selectors, element, callback)`](../src/nwsapi.mts#L5736) | Returns whether the element matches. |
29+
| [`select(selectors, context, callback)`](../src/nwsapi.mts#L5737) | Returns matching descendants. Results are arrays by default. `NODE_LIST` can enable static NodeList results. |
3030

3131
### Look up elements
3232

3333
Find elements directly by class, ID, or tag name.
3434

3535
| Method | Result |
3636
| --- | --- |
37-
| [`byClass(cls, context)`](../src/nwsapi.mts#L5726) | Returns elements with the class name. |
38-
| [`byId(id, context)`](../src/nwsapi.mts#L5724) | Returns elements with the ID. Duplicate IDs are allowed by default. |
39-
| [`byTag(tag, context)`](../src/nwsapi.mts#L5725) | Returns elements with the tag name. Use `*` for all elements. |
37+
| [`byClass(cls, context)`](../src/nwsapi.mts#L5733) | Returns elements with the class name. |
38+
| [`byId(id, context)`](../src/nwsapi.mts#L5731) | Returns elements with the ID. Duplicate IDs are allowed by default. |
39+
| [`byTag(tag, context)`](../src/nwsapi.mts#L5732) | Returns elements with the tag name. Use `*` for all elements. |
4040

4141
### Configure the engine
4242

4343
Change engine options and error handling.
4444

4545
| Method | Result |
4646
| --- | --- |
47-
| [`configure(option, clear)`](../src/nwsapi.mts#L5735) | Reads or changes options. Pass `true` as the second argument to clear compiled selectors. |
48-
| [`emit(message, proto)`](../src/nwsapi.mts#L5737) | Reports an error using the configured error policy. |
47+
| [`configure(option, clear)`](../src/nwsapi.mts#L5742) | Reads or changes options. Pass `true` as the second argument to clear compiled selectors. |
48+
| [`emit(message, proto)`](../src/nwsapi.mts#L5744) | Reports an error using the configured error policy. |
4949

5050
### Compile and extend selectors
5151

5252
Advanced APIs for compiled resolvers and trusted selector extensions.
5353

5454
| Method | Result |
5555
| --- | --- |
56-
| [`compile(selector, mode, callback, relative)`](../src/nwsapi.mts#L5734) | Compiles a selector into a resolver function. This is an advanced API. |
57-
| [`registerCombinator(combinator, resolver)`](../src/nwsapi.mts#L5750) | Adds a relationship between elements using trusted resolver code. |
58-
| [`registerOperator(operator, resolver)`](../src/nwsapi.mts#L5778) | Adds an attribute operator using a resolver with `p1`, `p2`, and `p3` fields. |
59-
| [`registerSelector(name, rexp, func)`](../src/nwsapi.mts#L5803) | Adds a selector pattern and a compiler callback that returns `source` and `status`. |
56+
| [`compile(selector, mode, callback, relative)`](../src/nwsapi.mts#L5741) | Compiles a selector into a resolver function. This is an advanced API. |
57+
| [`registerCombinator(combinator, resolver)`](../src/nwsapi.mts#L5757) | Adds a relationship between elements using trusted resolver code. |
58+
| [`registerOperator(operator, resolver)`](../src/nwsapi.mts#L5785) | Adds an attribute operator using a resolver with `p1`, `p2`, and `p3` fields. |
59+
| [`registerSelector(name, rexp, func)`](../src/nwsapi.mts#L5810) | Adds a selector pattern and a compiler callback that returns `source` and `status`. |
6060

6161
### Override browser DOM methods
6262

6363
Calling `NW.Dom.install()` redirects native `querySelector()`, `querySelectorAll()`, `matches()`, and `closest()` calls to NWSAPI. `uninstall()` restores them. Direct engine calls work without installation.
6464

6565
| Method | Result |
6666
| --- | --- |
67-
| [`install(all)`](../src/nwsapi.mts#L5743) | Replaces native selector methods; `querySelectorAll()` returns static NodeList-compatible snapshots. The `all` flag enables legacy iframe-load handling. |
68-
| [`uninstall()`](../src/nwsapi.mts#L5744) | Restores the native methods saved by `install()`. |
67+
| [`install(all)`](../src/nwsapi.mts#L5750) | Replaces native selector methods; `querySelectorAll()` returns static NodeList-compatible snapshots. The `all` flag enables legacy iframe-load handling. |
68+
| [`uninstall()`](../src/nwsapi.mts#L5751) | Restores the native methods saved by `install()`. |
6969

7070
<details>
7171
<summary>Configuration</summary>
@@ -100,22 +100,22 @@ These exports support extensions and debugging. Prefer query methods and `config
100100

101101
| Member | Purpose |
102102
| --- | --- |
103-
| [`CFG`](../src/nwsapi.mts#L5712) | Contains the compiler syntax settings. |
104-
| [`Config`](../src/nwsapi.mts#L5738) | Contains the active options. Use `configure()` to change them. |
105-
| [`M_BODY`](../src/nwsapi.mts#L5715) | Contains the matching resolver body template. |
106-
| [`M_TEST`](../src/nwsapi.mts#L5719) | Contains the matching resolver test template. |
107-
| [`matchLambdas`](../src/nwsapi.mts#L5704) | Caches compiled matching functions, not DOM results. |
108-
| [`matchResolvers`](../src/nwsapi.mts#L5707) | Caches matching plans, not DOM results. |
109-
| [`N_BODY`](../src/nwsapi.mts#L5716) | Exposes the matching resolver body template. |
110-
| [`N_TEST`](../src/nwsapi.mts#L5720) | Contains the alternate resolver test template. |
111-
| [`Operators`](../src/nwsapi.mts#L5746) | Contains registered attribute operators. |
112-
| [`S_BODY`](../src/nwsapi.mts#L5714) | Contains the selection resolver body template. |
113-
| [`S_TEST`](../src/nwsapi.mts#L5718) | Contains the selection resolver test template. |
114-
| [`selectLambdas`](../src/nwsapi.mts#L5705) | Caches compiled selection functions, not DOM results. |
115-
| [`Selectors`](../src/nwsapi.mts#L5747) | Contains registered selector extensions. |
116-
| [`selectResolvers`](../src/nwsapi.mts#L5708) | Caches selection plans, not DOM results. |
117-
| [`Snapshot`](../src/nwsapi.mts#L5739) | Contains the document state and helpers used by compiled selectors. |
118-
| [`Version`](../src/nwsapi.mts#L5741) | Contains the engine version string. |
103+
| [`CFG`](../src/nwsapi.mts#L5719) | Contains the compiler syntax settings. |
104+
| [`Config`](../src/nwsapi.mts#L5745) | Contains the active options. Use `configure()` to change them. |
105+
| [`M_BODY`](../src/nwsapi.mts#L5722) | Contains the matching resolver body template. |
106+
| [`M_TEST`](../src/nwsapi.mts#L5726) | Contains the matching resolver test template. |
107+
| [`matchLambdas`](../src/nwsapi.mts#L5711) | Caches compiled matching functions, not DOM results. |
108+
| [`matchResolvers`](../src/nwsapi.mts#L5714) | Caches matching plans, not DOM results. |
109+
| [`N_BODY`](../src/nwsapi.mts#L5723) | Exposes the matching resolver body template. |
110+
| [`N_TEST`](../src/nwsapi.mts#L5727) | Contains the alternate resolver test template. |
111+
| [`Operators`](../src/nwsapi.mts#L5753) | Contains registered attribute operators. |
112+
| [`S_BODY`](../src/nwsapi.mts#L5721) | Contains the selection resolver body template. |
113+
| [`S_TEST`](../src/nwsapi.mts#L5725) | Contains the selection resolver test template. |
114+
| [`selectLambdas`](../src/nwsapi.mts#L5712) | Caches compiled selection functions, not DOM results. |
115+
| [`Selectors`](../src/nwsapi.mts#L5754) | Contains registered selector extensions. |
116+
| [`selectResolvers`](../src/nwsapi.mts#L5715) | Caches selection plans, not DOM results. |
117+
| [`Snapshot`](../src/nwsapi.mts#L5746) | Contains the document state and helpers used by compiled selectors. |
118+
| [`Version`](../src/nwsapi.mts#L5748) | Contains the engine version string. |
119119

120120
</details>
121121

‎src/nwsapi.mts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5274,7 +5274,14 @@ interface AttributeOperator {
52745274
for (i = 0, l = selectors.length; l > i; ++i) {
52755275
if (!seen[selectors[i]!] && (seen[selectors[i]!] = true)) {
52765276
type = selectors[i]!.match(reOptimizer)
5277-
if (type && type[1] != ':' && (token = type)) {
5277+
// Escaped delimiters can resemble a terminal tag inside an attribute.
5278+
// Compile escaped selectors intact instead of narrowing that token.
5279+
if (
5280+
type &&
5281+
type[1] != ':' &&
5282+
selectors[i]!.indexOf('\\') < 0 &&
5283+
(token = type)
5284+
) {
52785285
token[1]! || (token[1] = '*')
52795286
optimized[i] = optimize(optimized[i]!, token as RegExpMatchArray)
52805287
} else {

‎test/repo/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,10 @@ under `test/`; the pristine WPT checkout remains under `upstream/wpt/`.
1414

1515
`pnpm run test:fuzz` runs Vitiate's coverage-guided selector targets for 15 seconds each.
1616
Set `FUZZ_TIME_MS` to change the budget. Generated valid selectors are checked against an independent engine before and after DOM mutation; arbitrary bytes exercise parser error handling.
17+
Agent sessions use minimal harness output and suppress routine progress, using the same Socket Lib-derived `isAgent` helper as unit tests. Interactive runs retain normal progress. Set `FUZZ_VERBOSE=1` for detailed output; failures and saved input paths are always reported.
1718
`pnpm run test:fuzz:replay` reruns saved seeds, coverage corpus, crashes and timeouts from `.vitiate/`.
1819
This is a cumulative corpus replay, not a reconstruction of the last run's random execution order.
1920
CI uploads that directory even when a fuzz target fails. To replay a CI run, extract its artifact into `.vitiate/` in this checkout and run the replay command.
2021
Keep minimized findings as ordinary regression tests before clearing local corpus files.
2122
The fuzz lane instruments the built engine, while regular tests remain on the ordinary Vitest configuration.
23+
The substring-based unsafe-eval detector is disabled because compiled selectors legitimately contain input text inside escaped literals. Parser exceptions, result checks, prototype-pollution detection and the other default detectors remain active.

‎test/repo/fuzz/selectors.fuzz.mts‎

Lines changed: 79 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,12 @@ import { fuzz } from '@vitiate/core'
33
import { JSDOM } from 'jsdom'
44
import factory from '../../../src/nwsapi.js'
55

6+
// Vitiate replay reads per-target detector options, not plugin defaults.
7+
// The unsafe-eval substring detector also flags correctly escaped literals.
8+
const compilerFuzzOptions = {
9+
detectors: { prototypePollution: true, unsafeEval: false },
10+
}
11+
612
const dom = new JSDOM(
713
'<!doctype html><main><section class="a"><p id="one" class="item" data-value="a">one</p><p class="item b" data-value="b">two</p><div><span class="b"></span></div></section><section class="b"><p class="item">three</p></section></main>',
814
)
@@ -31,68 +37,79 @@ function check(selector: string) {
3137

3238
// Coverage-guided bytes choose valid grammar productions. The DOM oracle is
3339
// independent; mutation forces cache invalidation between identical queries.
34-
fuzz('generated selectors agree before and after DOM mutation', data => {
35-
const simple = [
36-
'*',
37-
'p',
38-
'section',
39-
'.item',
40-
'.a',
41-
'.b',
42-
'#one',
43-
'[data-value]',
44-
'[data-value="a"]',
45-
]
46-
const pick = (offset: number) => simple[(data[offset] ?? 0) % simple.length]!
47-
const left = pick(0)
48-
const right = pick(1)
49-
const nth = ((data[3] ?? 0) % 5) + 1
50-
const choices = [
51-
left,
52-
`${left} ${right}`,
53-
`${left} > ${right}`,
54-
`${left} + ${right}`,
55-
`${left} ~ ${right}`,
56-
`${left}, ${right}`,
57-
`${left}:not(${right})`,
58-
`:is(${left}, ${right})`,
59-
`:where(${left}, ${right})`,
60-
`${left}:nth-child(${nth})`,
61-
`${left}:nth-child(2n+1)`,
62-
`${left}:has(> ${right})`,
63-
]
64-
const selector = choices[(data[2] ?? 0) % choices.length]!
65-
check(selector)
66-
const node = document.createElement('p')
67-
node.className = 'item b'
68-
node.setAttribute('data-value', 'a')
69-
document.getElementsByTagName('section')[0]!.appendChild(node)
70-
try {
40+
fuzz(
41+
'generated selectors agree before and after DOM mutation',
42+
data => {
43+
const simple = [
44+
'*',
45+
'p',
46+
'section',
47+
'.item',
48+
'.a',
49+
'.b',
50+
'#one',
51+
'[data-value]',
52+
'[data-value="a"]',
53+
'[data-value="vitiate_eval_inject"]',
54+
]
55+
const pick = (offset: number) =>
56+
simple[(data[offset] ?? 0) % simple.length]!
57+
const left = pick(0)
58+
const right = pick(1)
59+
const nth = ((data[3] ?? 0) % 5) + 1
60+
const choices = [
61+
left,
62+
`${left} ${right}`,
63+
`${left} > ${right}`,
64+
`${left} + ${right}`,
65+
`${left} ~ ${right}`,
66+
`${left}, ${right}`,
67+
`${left}:not(${right})`,
68+
`:is(${left}, ${right})`,
69+
`:where(${left}, ${right})`,
70+
`${left}:nth-child(${nth})`,
71+
`${left}:nth-child(2n+1)`,
72+
`${left}:has(> ${right})`,
73+
]
74+
const selector = choices[(data[2] ?? 0) % choices.length]!
7175
check(selector)
72-
} finally {
73-
node.remove()
74-
}
75-
check(selector)
76-
})
77-
78-
fuzz('arbitrary selector bytes cannot crash the parser', data => {
79-
const selector = data.toString('utf8')
80-
try {
81-
const all = engine.select(selector, document)
82-
const first = engine.first(selector, document)
83-
if (first !== (all[0] ?? null) || new Set(all).size !== all.length) {
84-
throw new Error(
85-
`Inconsistent selector result: ${JSON.stringify(selector)}`,
86-
)
76+
const node = document.createElement('p')
77+
node.className = 'item b'
78+
node.setAttribute('data-value', 'a')
79+
document.getElementsByTagName('section')[0]!.appendChild(node)
80+
try {
81+
check(selector)
82+
} finally {
83+
node.remove()
8784
}
88-
} catch (error) {
89-
// Invalid selector syntax is expected; internal runtime errors are bugs.
90-
if (
91-
!(
92-
error instanceof dom.window.DOMException && error.name === 'SyntaxError'
93-
)
94-
) {
95-
throw error
85+
check(selector)
86+
},
87+
compilerFuzzOptions,
88+
)
89+
90+
fuzz(
91+
'arbitrary selector bytes cannot crash the parser',
92+
data => {
93+
const selector = data.toString('utf8')
94+
try {
95+
const all = engine.select(selector, document)
96+
const first = engine.first(selector, document)
97+
if (first !== (all[0] ?? null) || new Set(all).size !== all.length) {
98+
throw new Error(
99+
`Inconsistent selector result: ${JSON.stringify(selector)}`,
100+
)
101+
}
102+
} catch (error) {
103+
// Invalid selector syntax is expected; internal runtime errors are bugs.
104+
if (
105+
!(
106+
error instanceof dom.window.DOMException &&
107+
error.name === 'SyntaxError'
108+
)
109+
) {
110+
throw error
111+
}
96112
}
97-
}
98-
})
113+
},
114+
compilerFuzzOptions,
115+
)

‎test/repo/unit/fuzz-regressions.test.mts‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,43 @@ import { expect, test } from 'vitest'
22
import { JSDOM } from 'jsdom'
33
import factory from '../../../src/nwsapi.js'
44

5+
test('escaped attribute values remain intact during candidate lookup', t => {
6+
const dom = new JSDOM('<!doctype html><p></p>')
7+
t.onTestFinished(() => dom.window.close())
8+
const document = dom.window.document
9+
const node = document.getElementsByTagName('p')[0]!
10+
node.setAttribute('data-value', '\\')
11+
const engine = factory(dom.window)
12+
for (const selector of [
13+
'[data-value=\\\\]',
14+
'p[data-value=\\\\]',
15+
'[data-value="\\\\"]',
16+
]) {
17+
expect(Array.from(document.querySelectorAll(selector))).toEqual([node])
18+
expect(Array.from(engine.select(selector, document))).toEqual([node])
19+
expect(engine.first(selector, document)).toBe(node)
20+
expect(engine.match(selector, node)).toBe(true)
21+
}
22+
})
23+
24+
test('eval detector sentinels remain ordinary selector data', t => {
25+
const dom = new JSDOM(
26+
'<!doctype html><p vitiate_eval_inject data-value="vitiate_eval_inject"></p>',
27+
)
28+
t.onTestFinished(() => dom.window.close())
29+
const engine = factory(dom.window)
30+
const document = dom.window.document
31+
const node = document.getElementsByTagName('p')[0]!
32+
for (const selector of [
33+
'p[vitiate_eval_inject]',
34+
'p[data-value="vitiate_eval_inject"]',
35+
]) {
36+
expect(Array.from(engine.select(selector, document))).toEqual([node])
37+
expect(engine.first(selector, document)).toBe(node)
38+
expect(engine.match(selector, node)).toBe(true)
39+
}
40+
})
41+
542
test('CSS attribute name escapes cannot become JavaScript octal escapes', t => {
643
const dom = new JSDOM('<!doctype html><p data-value="a"></p>')
744
t.onTestFinished(() => dom.window.close())
@@ -15,8 +52,12 @@ test('CSS attribute name escapes cannot become JavaScript octal escapes', t => {
1552
}
1653
// Minimized by the coverage-guided byte fuzzer.
1754
const selector = String.fromCharCode(92, 92, 92, 92, 91, 92, 51)
18-
expect(Array.from(engine.select(selector, document))).toEqual([])
19-
expect(engine.first(selector, document)).toBe(null)
55+
expect(() => engine.select(selector, document)).toThrow(
56+
dom.window.DOMException,
57+
)
58+
expect(() => engine.first(selector, document)).toThrow(
59+
dom.window.DOMException,
60+
)
2061
expect(() => engine.match(selector, node)).toThrow(dom.window.DOMException)
2162
})
2263

‎vitest.config.mts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
// test suite explicitly uses .config/vitest.config.mts.
33
import { defineConfig } from 'vitest/config'
44
import { vitiatePlugin } from '@vitiate/core/plugin'
5+
import { isAgent } from './scripts/repo/lib/is-agent.mts'
6+
7+
const minimalOutput = isAgent() && process.env['FUZZ_VERBOSE'] !== '1'
58

69
const budget = Number(process.env['FUZZ_TIME_MS'] ?? 15_000)
710
if (!Number.isSafeInteger(budget) || budget <= 0) {
@@ -31,11 +34,21 @@ export default defineConfig({
3134
fuzzTimeMs: budget,
3235
maxLen: 512,
3336
stopOnCrash: true,
34-
detectors: { prototypePollution: true },
37+
quiet: minimalOutput,
3538
},
3639
}),
3740
],
3841
test: {
42+
...(minimalOutput
43+
? {
44+
reporters: [
45+
'minimal' as const,
46+
...(process.env['GITHUB_ACTIONS'] === 'true'
47+
? ['github-actions' as const]
48+
: []),
49+
],
50+
}
51+
: {}),
3952
include: ['test/repo/fuzz/**/*.fuzz.mts'],
4053
passWithNoTests: false,
4154
testTimeout: budget + 30_000,

0 commit comments

Comments
 (0)