This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/main by this push:
new 14856465c docs: add secure-usage guidance on trust state to Chaining
Interceptor (#318)
14856465c is described below
commit 14856465c3e8cdf63c5e086df2b289ae6937634f
Author: Lukasz Lenart <[email protected]>
AuthorDate: Wed Jul 29 09:04:41 2026 +0200
docs: add secure-usage guidance on trust state to Chaining Interceptor
(#318)
Action chaining populates the target action implicitly from the value
stack. Document the design-level guidance that follows from that: keep
authorization, trust, identity and approval state out of the chain and
re-derive it in the target action, prefer avoiding chaining, and narrow
what is copied via Unchainable or the includes/excludes parameters.
Cross-links the "Where authorization applies" overview on the
@StrutsParameter page.
Co-authored-by: Claude Opus 5 <[email protected]>
---
source/core-developers/chaining-interceptor.md | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/source/core-developers/chaining-interceptor.md
b/source/core-developers/chaining-interceptor.md
index be4c591d6..433fe04c3 100644
--- a/source/core-developers/chaining-interceptor.md
+++ b/source/core-developers/chaining-interceptor.md
@@ -58,6 +58,29 @@ When enabled (default is `false`):
no properties are copied.
- This is a **global** constant only — there is no per-interceptor override.
+## Security Considerations
+
+Action chaining makes the data path into the target action implicit: the
target is populated
+from whatever happens to be on the value stack rather than from an explicit
call. Keep that in
+mind when designing chained actions:
+
+- **Do not carry authorization, trust, identity, or approval state across a
chain.** Re-derive
+ such state from the session or your security context inside the target
action, so it never
+ depends on what a previous action left on the stack.
+- **Prefer avoiding chaining where practical.** It couples the two actions
together and makes
+ the target's inputs harder to reason about; a shared service or an explicit
redirect is
+ usually clearer.
+- **If chaining is required, narrow what is copied.** Implement
+ [Unchainable](/maven/struts2-core/apidocs/org/apache/struts2/Unchainable) on
objects that must
+ never be copied from, and use the interceptor's `includes` or `excludes`
parameters to limit
+ the copied properties to the ones the target genuinely needs.
+- **Do not expose a public setter on the target action for state that must not
be settable from
+ outside that action.** Anything with a public setter is, by design, part of
the action's
+ input surface.
+
+See also [Where authorization
applies](struts-parameter-annotation.html#where-authorization-applies)
+for an overview of the channels that can populate an action.
+
## Parameters
- `excludes` (optional) - the list of parameter names to exclude from copying
(all others will be included)
