[ENG-4059] Decode request values the way apps read them

[patchstackdave]

Rules now see request values decoded the way the app reads them.

• Percent-decoding. A % that starts no escape no longer stops the escapes around it from being decoded. This applies both to normalization and to the urldecode mutation. Each run of escapes is decoded as UTF-8, and bytes that are not valid UTF-8 become U+FFFD.

• +. The urldecode mutation reads + as a space, as form decoding does. server.REQUEST_URI and all read + in the query as a space. A + in the path, and an encoded %2B, stay a literal +.

• HTML character references. Normalization and the htmlentitydecode mutation now share one decoder. It handles named references such as :, numeric references without a closing ;, and an upper-case hex marker. Text after a decimal reference is kept (&#58abc becomes :abc).

• Structured values. urldecode, htmlentitydecode and base64_decode applied to an object or array decode each string inside it and keep the structure. This works for post.* values and for the output of json_decode, and structural matchers still see the shape. The walk is iterative, is bounded like the engine's leaf walk, and handles cyclic values and an own __proto__ key.

• Nesting depth. Normalization walks nested values iteratively, to the same depth bound as the engine's leaf walk, so every value that walk reaches is normalized. A value past the bound is still matched, in its raw form. Reaching the bound is reported as a container-cap skip through onSkip and coverage(), once per request. Evaluation results carry the limits they reached as skips.

Synthetic tests in tests/protect/request-decoding.test.ts pair every value a rule must match with one it must not, and cover both sides of the depth bound.

Validation: full suite (3,466 passed, 7 skipped), typecheck, and build.

🤖 Generated with Claude Code

[coderbuds]

Feature adds thorough request value decoding aligning with app behavior.

🎯 Quality: 100% Elite · 📦 Size: Large — consider splitting if possible

🤖 Authorship: Agent-written — Claude Code, going by its own attribution. Whether a person read it is unknown; coding agents can call the report-ai-usage tool to say.

📈 This month: Your 161st PR — above team average · Averaging Excellent

_{See how your team is trending →}

[patchstackdave]

/review