fix: make walkDOM iterative to prevent stack overflow (GHSA-2v35-w6hq-6mfw)

karfau · karfau · commit cbdb0d7db8ae · 2026-04-18T13:16:19.000+02:00
Replace the recursive `walkDOM` implementation with an explicit stack of frames, each carrying `{node, context, phase}`. The `phase` field is one of two constants added to the function — `walkDOM.ENTER` (call `enter`, schedule children) and `walkDOM.EXIT` (call `exit`) — making the two-phase lifecycle of each frame self-documenting. Children are pushed by traversing from `lastChild` via `previousSibling`, which naturally places `firstChild` on top without requiring an intermediate array. The public API, `walkDOM.STOP` sentinel, and all five callers (`_visitNode`, `getTextContent`, `cloneNode`, `importNode`, `serializeToString`) are unchanged. The test script is updated to cap the Node.js stack at 256 KB via `--stack-size=256`, lowering the recursive-overflow threshold to ~2,600 frames. A new `test/recursion-regression.test.js` consolidates all deep-tree regression guards (GHSA-2v35-w6hq-6mfw) and enforces the constrained test environment via invariant checks. Depth tests covering all five callers at a 3,000-node tree (which exceeds the constrained overflow threshold) confirm the fix and guard against regression. `docs/walk-dom.md` is carried over from the 0.9.x branch. GHSA-2v35-w6hq-6mfw
diff --git a/docs/walk-dom.md b/docs/walk-dom.md
@@ -0,0 +1,117 @@
+# `walkDOM` — iterative tree traversal
+
+**Source**: [`lib/dom.js`](../lib/dom.js)
+
+`walkDOM` visits every node in a DOM subtree in depth-first order, calling
+caller-supplied `enter` and `exit` callbacks. It uses an explicit stack instead
+of recursion, so it is safe on arbitrarily deep trees.
+
+## Stack frame
+
+Each item on the work stack is a frame with three fields:
+
+| Field     | Purpose                                              |
+|-----------|------------------------------------------------------|
+| `node`    | The DOM node to process                              |
+| `context` | Opaque value threaded through the traversal          |
+| `phase`   | `ENTER` — call `enter`, schedule children and exit  |
+|           | `EXIT`  — call `exit` for the matching `enter`       |
+
+Each frame starts its life as `ENTER` and, after being processed, causes an
+`EXIT` frame for the same node to be pushed. The `EXIT` frame fires only after
+all descendants have been fully processed — which is exactly the post-order
+guarantee.
+
+## Control flow
+
+```mermaid
+flowchart TD
+    start([push ENTER frame for root]) --> loop
+
+    loop{stack empty?} -- no --> pop[pop frame]
+    loop -- yes --> done([return])
+
+    pop --> phase{frame.phase}
+
+    phase -- ENTER --> callEnter["childContext = enter(node, context)"]
+    callEnter --> check{childContext?}
+
+    phase -- EXIT --> callExit["call exit(node, context)\nif provided"]
+    callExit --> loop
+
+    check -- STOP --> ret([return STOP])
+    check -- otherwise --> pushExit["push EXIT frame\n{node, childContext}"]
+    pushExit --> descend{childContext\nnull or undefined?}
+    descend -- yes\nskip children --> loop
+    descend -- no --> pushChildren["push ENTER frames\nfrom lastChild via previousSibling\n(firstChild lands on top)"]
+    pushChildren --> loop
+```
+
+`EXIT` is always pushed — even when children are skipped — so `exit` is called
+once for every `enter`, symmetric and unconditional.
+
+## Why pushing EXIT before children guarantees post-order
+
+The stack is last-in-first-out. When an `ENTER` frame is processed, the following are
+pushed in this order:
+
+1. `EXIT` frame for the current node
+2. `ENTER` frames for children, traversed from `lastChild` via `previousSibling` — so `firstChild` lands on top and is processed first
+
+Because children are on top, they are processed first. The parent's `EXIT`
+frame sits below all of them and fires only after the last descendant finishes.
+
+### Stack trace
+
+```xml
+<root>
+  <A>
+    <A1/>
+  </A>
+  <B/>
+</root>
+```
+
+| Step | Actions                                                                                         | Stack after <br/>(list order, last item = next to pop)          |
+|------|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
+| init | push `ENTER(root)`                                                                              | `ENTER(root)`                                                   |
+| 1    | pop `ENTER(root)`,<br/> `enter(root)`,<br/> push `EXIT(root)`, `ENTER(B)`, `ENTER(A)` | `EXIT(root)`,<br/> `ENTER(B)`,<br/> `ENTER(A)`                  |
+| 2    | pop `ENTER(A)`,<br/> `enter(A)`,<br/> push `EXIT(A)`, `ENTER(A1)`                          | `EXIT(root)`,<br/> `ENTER(B)`,<br/> `EXIT(A)`,<br/> `ENTER(A1)` |
+| 3    | pop `ENTER(A1)`,<br/> `enter(A1)`,<br/> push `EXIT(A1)`                                         | `EXIT(root)`,<br/> `ENTER(B)`,<br/> `EXIT(A)`,<br/> `EXIT(A1)`  |
+| 4    | pop `EXIT(A1)`,<br/> `exit(A1)`                                                                 | `EXIT(root)`,<br/> `ENTER(B)`,<br/> `EXIT(A)`                   |
+| 5    | pop `EXIT(A)`,<br/> `exit(A)`                                                                   | `EXIT(root)`,<br/> `ENTER(B)`                                   |
+| 6    | pop `ENTER(B)`,<br/> `enter(B)`,<br/> push `EXIT(B)`                                            | `EXIT(root)`,<br/> `EXIT(B)`                                    |
+| 7    | pop `EXIT(B)`,<br/> `exit(B)`                                                                   | `EXIT(root)`                                                    |
+| 8    | pop `EXIT(root)`,<br/> `exit(root)`                                                             | _(empty)_                                                       |
+
+Call order: `enter(root)` → `enter(A)` → `enter(A1)` → `exit(A1)` → `exit(A)` → `enter(B)` → `exit(B)` → `exit(root)`.
+
+## Context isolation
+
+The value returned by `enter` becomes `childContext`. It is stored in:
+
+- the `EXIT` frame, so `exit` receives exactly what `enter` returned
+- all children's `ENTER` frames, so each child starts with the parent's output
+
+Siblings share the same `childContext` reference from their common parent.
+Callers that need per-element isolation must produce a fresh value inside
+`enter` (e.g. `namespaces.slice()` in `serializeToString`).
+
+## DOM mutation during traversal
+
+Only mutations to a node's **own children** inside its `enter` callback are
+supported. Because `lastChild` and `previousSibling` are read after `enter` returns, any
+children added or removed there are correctly reflected when the walker
+schedules the next level of frames.
+
+Mutating anything else — siblings of the current node, ancestors, or unrelated
+subtrees — produces unpredictable results. Nodes already queued on the stack
+are visited regardless of subsequent DOM changes; nodes inserted outside the
+current child list are never queued and therefore never visited. Neither
+`enter` nor `exit` is guaranteed to be called for such nodes.
+
+## `walkDOM.STOP`
+
+Returning `walkDOM.STOP` from `enter` causes the function to return `STOP`
+immediately, discarding the rest of the stack. No further `enter` or `exit`
+calls are made — including any pending `EXIT` frames for ancestors.
diff --git a/lib/dom.js b/lib/dom.js
@@ -617,40 +617,58 @@ function _visitNode(node, callback) {
  * sibling traversal continues normally.
  * 3. If `enter` returns `walkDOM.STOP`, the entire traversal is aborted immediately — no
  * further `enter` or `exit` calls are made.
- * 4. `firstChild` is read **after** `enter` returns, so `enter` may safely modify the node's
- * child list before the walker descends.
+ * 4. `lastChild` and `previousSibling` are read **after** `enter` returns, so `enter` may
+ * safely modify the node's own child list before the walker descends. Modifying siblings of
+ * the current node or any other part of the tree produces unpredictable results: nodes already
+ * queued on the stack are visited regardless of DOM changes, and newly inserted nodes outside
+ * the current child list are never visited.
  * 5. Calls `callbacks.exit(node, context)` (if provided) after all of a node's children have
  * been visited, passing the same `context` that `enter`
  * returned for that node.
  *
- * Note: this implementation is recursive. It will be converted to an iterative form in a later
- * step to eliminate stack-overflow risk on very deep trees.
+ * This implementation uses an explicit stack and does not recurse — it is safe on arbitrarily
+ * deep trees.
  *
  * @param {Node} node
  * Root of the subtree to walk.
  * @param {*} context
  * Initial context value passed to the root node's `enter`.
  * @param {{ enter: function(Node, *): *, exit?: function(Node, *): void }} callbacks
  * @returns {void | walkDOM.STOP}
+ * @see ../docs/walk-dom.md.
  */
 function walkDOM(node, context, callbacks) {
-	var childContext = callbacks.enter(node, context);
-	if (childContext === walkDOM.STOP) {
-		return walkDOM.STOP;
-	}
-	if (childContext !== null && childContext !== undefined) {
-		var child = node.firstChild;
-		while (child) {
-			var next = child.nextSibling;
-			if (walkDOM(child, childContext, callbacks) === walkDOM.STOP) {
+	// Each stack frame is {node, context, phase}:
+	//   walkDOM.ENTER — call enter, then push children
+	//   walkDOM.EXIT  — call exit
+	var stack = [{ node: node, context: context, phase: walkDOM.ENTER }];
+	while (stack.length > 0) {
+		var frame = stack.pop();
+		if (frame.phase === walkDOM.ENTER) {
+			var childContext = callbacks.enter(frame.node, frame.context);
+			if (childContext === walkDOM.STOP) {
 				return walkDOM.STOP;
 			}
-			child = next;
+			// Push exit frame before children so it fires after all children are processed (Last In First Out)
+			stack.push({ node: frame.node, context: childContext, phase: walkDOM.EXIT });
+			if (childContext === null || childContext === undefined) {
+				continue; // skip children
+			}
+			// lastChild is read after enter returns, so enter may modify the child list.
+			var child = frame.node.lastChild;
+			// Traverse from lastChild backwards so that pushing onto the stack
+			// naturally yields firstChild on top (processed first).
+			while (child) {
+				stack.push({ node: child, context: childContext, phase: walkDOM.ENTER });
+				child = child.previousSibling;
+			}
+		} else {
+			// frame.phase === walkDOM.EXIT
+			if (callbacks.exit) {
+				callbacks.exit(frame.node, frame.context);
+			}
 		}
 	}
-	if (callbacks.exit) {
-		callbacks.exit(node, childContext);
-	}
 }
 
 /**
@@ -660,6 +678,20 @@ function walkDOM(node, context, callbacks) {
  * @type {symbol}
  */
 walkDOM.STOP = Symbol('walkDOM.STOP');
+/**
+ * Phase constant for a stack frame that has not yet been visited.
+ * The `enter` callback is called and children are scheduled.
+ *
+ * @type {number}
+ */
+walkDOM.ENTER = 0;
+/**
+ * Phase constant for a stack frame whose subtree has been fully visited.
+ * The `exit` callback is called.
+ *
+ * @type {number}
+ */
+walkDOM.EXIT = 1;
 
 function Document(){
 	this.ownerDocument = this;
diff --git a/package.json b/package.json
@@ -27,6 +27,9 @@
 		"index.d.ts",
 		"lib"
 	],
+	"config": {
+		"test_stack_size": 256
+	},
 	"scripts": {
 		"lint": "eslint lib test",
 		"format": "prettier --write test",
@@ -35,7 +38,7 @@
 		"start": "nodemon --watch package.json --watch lib --watch test --exec 'npm --silent run test && npm --silent run lint'",
 		"stryker": "stryker run",
 		"stryker:dry-run": "stryker run -m '' --reporters progress",
-		"test": "jest",
+		"test": "node --stack-size=$npm_package_config_test_stack_size ./node_modules/.bin/jest",
 		"testrelease": "npm test && eslint lib",
 		"version": "./changelog-has-version.sh",
 		"release": "np --no-yarn --test-script testrelease --branch release-0.8.x patch"
diff --git a/test/recursion-regression.test.js b/test/recursion-regression.test.js
@@ -0,0 +1,73 @@
+'use strict'
+
+const { describe, test, expect, beforeAll } = require('@jest/globals')
+const { DOMImplementation, walkDOM } = require('../lib/dom')
+const { XMLSerializer } = require('../lib')
+const pkgJson = require('../package.json')
+
+// Must exceed the recursive-overflow threshold at the configured stack size
+// (~2,600 frames at 256 KB) so that re-introducing any recursive tree walk
+// causes these tests to fail.
+const DEEP_TREE_DEPTH = 3000
+
+test('npm_package_config_test_stack_size env var matches package.json config.test_stack_size', () => {
+	expect(process.env.npm_package_config_test_stack_size).toBe(
+		`${pkgJson.config.test_stack_size}`
+	)
+})
+test('test script uses $npm_package_config_test_stack_size', () => {
+	expect(pkgJson.scripts.test).toMatch(
+		' --stack-size=$npm_package_config_test_stack_size'
+	)
+})
+test('recursive function overflows within DEEP_TREE_DEPTH frames', () => {
+	function throwsAtLevel(lvl) {
+		var nextLvl = (lvl || 0) + 1
+		try {
+			return throwsAtLevel(nextLvl)
+		} catch (e) {
+			return nextLvl
+		}
+	}
+	expect(throwsAtLevel()).toBeLessThanOrEqual(DEEP_TREE_DEPTH)
+})
+
+describe('deep tree stack overflow guard (GHSA-2v35-w6hq-6mfw)', () => {
+	var deepRoot
+	beforeAll(() => {
+		var doc = new DOMImplementation().createDocument(null, 'root')
+		var current = doc.documentElement
+		for (var i = 0; i < DEEP_TREE_DEPTH; i++) {
+			var child = doc.createElement('n')
+			current.appendChild(child)
+			current = child
+		}
+		deepRoot = doc.documentElement
+	})
+
+	test('walkDOM', () => {
+		expect(() =>
+			walkDOM(deepRoot, null, {
+				enter: function () {
+					return 'ctx'
+				},
+			})
+		).not.toThrow()
+	})
+	test('getElementsByTagName', () => {
+		expect(() => deepRoot.getElementsByTagName('n')).not.toThrow()
+	})
+	test('textContent', () => {
+		expect(() => void deepRoot.textContent).not.toThrow()
+	})
+	test('serializeToString', () => {
+		expect(() => new XMLSerializer().serializeToString(deepRoot)).not.toThrow()
+	})
+	test('cloneNode(true)', () => {
+		expect(() => deepRoot.cloneNode(true)).not.toThrow()
+	})
+	test('importNode(node, true)', () => {
+		var destDoc = new DOMImplementation().createDocument(null, 'dest')
+		expect(() => destDoc.importNode(deepRoot, true)).not.toThrow()
+	})
+})
