Align ESAPI URL-component semantics and define safe adapter context contracts

[jmanico]

Reviewed 2026-09-25 (America/Los_Angeles) against main at bd249f5. Execution order and cross-issue ownership: #169. Batch 01.

This scope replaces the dated implementation prescriptions in the original report and earlier comments; linked historical evidence remains useful but must be rechecked before implementation.

Review finding

ESAPIEncoder.encodeForURL still delegates to deprecated Encode.forUri and preserves & = / ? #, unlike ESAPI's component/form-encoding contract. CSS, JavaScript and URL method Javadocs were already clarified by #161; #155 also changed JavaScript output and added ordinary untagged-template support. The original comparison predates those changes and resolved an RC through the now-fixed dependency range.

Acceptance criteria

• Compare with the supported stable ESAPI default and compatibility matrix, including nulls, spaces, reserved delimiters, Unicode and malformed input. Decide and test form semantics (+) versus component semantics (%20) and document migration/output differences.
• Replace the URL delegate with a component-safe implementation, retaining checked-exception and documented null contracts. Encoding a component does not validate a whole URL or its scheme.
• Decide HTML-attribute behavior explicitly: preserve the quoted-attribute contract with accurate method Javadoc, or deliberately broaden escaping with parser/regression evidence. Do not promise safety for event handlers or URL attributes from HTML escaping alone.
• Retain precise CSS quoted-string and JavaScript string/ordinary-template contexts. Remove the old claim that ESAPI escaping makes arbitrary unquoted JavaScript fail closed; neither encoder is a general code sanitizer. Any proposed stronger escaping needs evidence of context safety and value preservation, not a punctuation-count comparison.
• Preserve the CSS size fix in 1.4.1, Support ordinary templates and preserve JavaScript Unicode data #155's template-boundary/Unicode behavior, Allow ESAPI adapter delegation to recover after missing configuration #165's lazy reference lookup, JSON delegation and disabled unsafe ESAPI SQL methods. Add focused parser/contract tests and release notes for output changes.

Coordinate URL migration text with #130 in the same batch. See OWASP context guidance. This is a security-sensitive contract review, not a new vulnerability classification.

Completed in batch 01

Merged #172 as fe5e0ad174481c2f23a566aa33069a0e45562785 following final diff review and all 20 successful GitHub checks. encodeForURL now delegates to Encode.forUriComponent: reserved delimiters and literal + are escaped, spaces remain %20, null remains the string "null", and unpaired surrogates remain -. UTF-8 is fixed and the checked-exception declaration remains. The reference form-encoding differences and complete-URL migration are documented for unreleased 1.5.

The quoted HTML attribute contract is retained and independently parsed; CSS/JavaScript supported contexts, prior security/Unicode fixes, JSON delegation, retryable lazy reference lookup, and default SQL disablement are preserved. Local reactor verification passed 2,126 tests; all 16 focused adapter tests passed for each of ten stable ESAPI versions. CI additionally passed browser tests, Java 8 unit tests, and packaged Java 8/11/17/21/25 consumers. The coordinated #130 deprecation work merged in #170; #172 clarifies application-level URL validation and enclosing contexts throughout the guidance.

Migration and contract details. No published 1.4.1 artifact changed.