[DOC] Clarify that disabling principal parameter also disables JSR-250 annotations

[Allen-wick]

[DOC] Clarify that disabling principal parameter also disables JSR-250 annotations

Description

This PR updates the Javadoc for the disable-principal configuration parameters in the shiro-jakarta-ee and shiro-jaxrs modules to explicitly document their cascading side-effects on JSR-250 security annotations.

Context

This documentation improvement follows a private security report regarding JSR-250 annotation processing in the shiro-jaxrs module. The Apache Shiro Security Team confirmed:

1. The underlying code logic has been fixed (logic inversion bug)
2. The behavior where disabling the principal also disables JSR-250 annotations is by-design (since JSR-250 requires a valid Principal to evaluate against)
3. The documentation was unclear about this side-effect, which could lead developers to inadvertently create authorization gaps when tuning JAX-RS parameters

Per the security team's recommendation, this PR adds explicit warnings to the source code Javadoc to prevent future misconfigurations.

Changes

1. support/jakarta-ee/src/main/java/org/apache/shiro/ee/listeners/EnvironmentLoaderListener.java:

   • Added WARNING Javadoc block to SHIRO_WEB_DISABLE_PRINCIPAL_PARAM constant explaining that enabling this parameter silently disables JSR-250 annotations (@RolesAllowed, @PermitAll, @DenyAll)

2. support/jaxrs/src/main/java/org/apache/shiro/web/jaxrs/SubjectPrincipalRequestFilter.java:

   • Added WARNING Javadoc block to SHIRO_WEB_JAXRS_DISABLE_PRINCIPAL_PARAM constant with the same clarification

Why This Matters

• Prevents Silent Fail-Open: Developers who rely on JSR-250 annotations for declarative authorization will now be explicitly warned that enabling disable-principal removes this protection layer
• IDE Visibility: By adding the warning to Javadoc, developers using IDE auto-completion or reading generated API docs will see the warning immediately when configuring these parameters
• Security Best Practice: Aligns with the principle that security-critical configuration side-effects should be documented at the point of use

Testing

• This is a documentation-only change; no functional code modifications
• Javadoc can be generated via mvn javadoc:javadoc to verify formatting
• No new dependencies or build steps required

Related Issue

fixes #2763

---

Checklist:

• GitHub issue filed: [Doc] Clarify that disabling principal parameter also disables JSR-250 annotations #2763
• Pull request title formatted as [DOC] - ...
• Detailed description provided
• fixes #2763 added to link to related issue
• This is a trivial documentation change (javadoc comments), no mvn verify required per contribution guidelines
• Contribution licensed under Apache License 2.0

Thank you to the Apache Shiro Security Team for the transparent triage process and for guiding this documentation improvement.

[jbampton]

Checkstyle has failed.

Looks like the first line of your Java code comments are not indented properly

[Allen-wick]

Checkstyle has failed.

Looks like the first line of your Java code comments are not indented properly

Thanks for catching that. I've corrected the indentation for both Javadoc blocks to perfectly align with the code, and the Checkstyle CI should be passing now. Let me know if there's anything else needed.