RAMPART-454 Document security / maintenance assumptions flagged by review

Add in-place comments at the three locations the Gemini review flagged
as HIGH/MEDIUM risk so the assumptions are enforced the next time
someone touches these files, without changing behaviour:

- modules/distribution/bin.xml: prepend a MAINTENANCE NOTE describing
  why the <excludes> list on the lib/ dependencySet exists (the dist
  must not duplicate jars already shipped in the Axis2 distribution)
  and what must be re-checked whenever ${axis2.version} or any
  transitive dep moves -- otherwise we re-introduce the httpcore5
  5.2.5 vs 5.4.2 style silent breakage.

- pom.xml: prepend a SECURITY NOTE to the <properties> block listing
  the checklist reviewers must follow when bumping wss4j / opensaml /
  xmlsec / bouncycastle: read every intermediate CVE release note
  (not just the newest), make sure no weak algorithm or key size gets
  re-introduced as a default, and re-run the policy samples.

- RampartUtil.validateTransport: expand the inline comment at the
  jakarta.servlet.request.X509Certificate lookup site to name the
  Servlet-spec contract we're relying on and explicitly state that
  re-validation of the chain is the transport listener's job, not
  ours. The Javadoc on the method already documented the attribute
  name; this makes the responsibility split visible at the call site.

Author: robertlazarski

modules/distribution/bin.xml

@@ -1,3 +1,27 @@
+<!--
+  MAINTENANCE NOTE
+  ================
+  The <excludes> list on the lib/ dependencySet below is version-coupled to
+  the contents of the Axis2 binary distribution we install into. Its purpose
+  is to avoid shipping jars that Axis2 already provides; otherwise two copies
+  at different versions end up on the Axis2 runtime classpath (for example
+  httpcore5 5.2.5 alongside Axis2's 5.4.2) and the first one found wins,
+  which silently breaks HTTPClient5 transport and other components.
+
+  When bumping ${axis2.version} (or any transitive dependency in the lib/
+  set) the excludes MUST be re-reviewed:
+
+    1. Build the matching axis2 distribution (or unzip axis2-*-bin.zip).
+    2. Diff the jars in axis2/lib against this pom's effective dependency
+       list (mvn -pl modules/distribution dependency:list), comparing by
+       artifactId prefix.
+    3. Add any new overlaps as <exclude>group:artifact</exclude> entries.
+    4. Drop entries for artifacts Axis2 no longer ships.
+    5. Re-run the nine policy samples against the fresh rampart-dist to
+       confirm no sealing violations or NoSuchMethodErrors.
+
+  See the rampart-dist README / release checklist for the exact commands.
+-->
 <assembly>
     <id>bin</id>
     <baseDirectory>rampart-${version}</baseDirectory>

modules/rampart-core/src/main/java/org/apache/rampart/util/RampartUtil.java

@@ -1943,6 +1943,14 @@ public static void validateTransport(RampartMessageData messageData) throws Ramp
                         Object requestProperty = msgContext.getProperty(HTTPConstants.MC_HTTP_SERVLETREQUEST);
                         if (requestProperty instanceof HttpServletRequest) {
 		            HttpServletRequest request = (HttpServletRequest)requestProperty;
+                            // Per the Jakarta Servlet specification (section on SSL attributes),
+                            // a servlet container performing TLS client authentication MUST
+                            // expose the validated chain on the request under this attribute
+                            // name. Rampart relies on that contract: if the container is not
+                            // configured for client auth, or does not populate the attribute,
+                            // this lookup returns null and the check below fails the request.
+                            // We deliberately do not attempt to re-validate the chain here --
+                            // that is the transport listener's responsibility.
                             Object certificateChain = request.getAttribute("jakarta.servlet.request.X509Certificate"); //$NON-NLS-1$
                             if (certificateChain instanceof X509Certificate[]) {
                                 // HTTPS client certificate chain found

pom.xml

@@ -820,6 +820,29 @@
     </modules>
 
     <properties>
+        <!--
+          SECURITY NOTE
+          =============
+          Rampart sits directly on top of the WS-Security / SAML stack: WSS4J
+          handles signing/encryption/UsernameToken, Santuario XMLSec handles
+          XML DSig/XML Enc primitives, OpenSAML handles assertion processing,
+          and Bouncy Castle supplies the crypto providers. Any CVE in those
+          libraries is effectively a Rampart CVE as far as downstream users
+          are concerned.
+
+          When bumping any of the versions below (wss4j, opensaml, xmlsec,
+          bcprov/bcpkix) the reviewer must:
+
+            1. Read the upstream release notes / CVE feed for every version
+               skipped (not just the newest one) and note any fixes that
+               affect the code paths Rampart exercises (signing, encryption,
+               SAML issuance/validation, STS, policy processing).
+            2. Ensure no deprecated/weak algorithms (SHA-1, MD5, RSA-1.5,
+               3DES, < 2048-bit keys) are re-introduced as defaults through
+               the upgrade.
+            3. Re-run the full reactor plus the nine policy samples before
+               pushing.
+        -->
         <axis2.version>2.0.1-SNAPSHOT</axis2.version>
         <axiom.version>2.0.0</axiom.version>