[9] Jinjava 3.0: Add method and return type validator framework

[jasmith-hs]

Part of #1288.

Introduces an allowlist-based validator framework that controls which Java methods can be invoked from Jinja templates and what return types are permitted. This replaces the old blocklist approach (getRestrictedMethods / getRestrictedProperties / isRestrictedClass) with an opt-in model: only explicitly-permitted methods and return types are allowed through.

---

Why this matters

The old security model in JinjavaBeanELResolver worked by blocking known-bad things: a hardcoded set of method names (class, clone, hashCode, getClass, etc.), an isRestrictedClass check for dangerous types (Class, ClassLoader, Thread, Method, java.lang.reflect.*, com.fasterxml.jackson.databind.*), and optional per-config restricted method/property sets.

Blocklists are fundamentally fragile — they require anticipating every dangerous thing. An allowlist inverts the model: unknown things are rejected by default, and only types explicitly categorised as safe are permitted.

---

New components

Validator interfaces and config

• MethodValidator — interface with a single validateMethod(Method) that returns null to reject or the method to accept. Supports chaining additional validators.
• ReturnTypeValidator — same pattern but for return values: validateReturnType(Object).
• MethodValidatorConfig (@Value.Immutable) — specifies which methods are allowed, by exact Method instance, by declaring class canonical name, or by class name prefix. Has an onRejectedMethod callback for observability. Built via MethodValidatorConfig.builder().
• ReturnTypeValidatorConfig (@Value.Immutable) — specifies which return types are allowed, by exact canonical class name or by prefix. Has an onRejectedClass callback and an allowArrays flag (only enabled for the Collections group). Built via ReturnTypeValidatorConfig.builder().

Both configs enforce hard safety guarantees via @Value.Check: attempting to add java.lang.Object, java.lang.Class, java.lang.reflect.*, com.fasterxml.jackson.databind.*, or any com.hubspot.jinjava.* type outside the explicit safe groups throws IllegalStateException at construction time. Misconfiguration is a hard error, not a silent runtime bypass. This logic lives in BannedAllowlistOptions.

AllowlistGroup enum

Defines named semantic groups used to populate configs:

Group	Covers
JavaPrimitives	Boxed/unboxed primitives, String, BigDecimal, BigInteger
JinjavaObjects	PyList, PyMap, SizeLimitingPy*, PyishDate, FormattedDate, DummyObject, Namespace, SafeString, NullValue
Collections	All of the above plus PySet, SizeLimitingPySet, ArrayList, Guava forwarding collections, LinkedHashMap; also enables array return types
JinjavaTagConstructs	ForLoop, MacroFunction, EagerMacroFunction
JinjavaFilters	All classes under com.hubspot.jinjava.lib.filter (by package prefix)
JinjavaFunctions	ZonedDateTime (used by date functions)
JinjavaExpTests	All classes under com.hubspot.jinjava.lib.exptest (by package prefix)

AllowlistMethodValidator.DEFAULT and AllowlistReturnTypeValidator.DEFAULT are pre-built from all groups and used as the defaults in JinjavaConfig.

AllowlistMethodValidator / AllowlistReturnTypeValidator

Both validators use ConcurrentHashMap caches (keyed on Method or canonical class name) so the allowlist check is only evaluated once per unique method/type during a JVM session. The onRejected* callback fires for observability before the method/value is suppressed.

ReturnTypeValidatingJinjavaInterpreterResolver

A thin ELResolver decorator that wraps JinjavaInterpreterResolver. All getValue and invoke calls are passed through AllowlistReturnTypeValidator.validateReturnType() after resolution. ExpressionResolver now builds this wrapper instead of using JinjavaInterpreterResolver directly.

HasInterpreter

A small interface (JinjavaInterpreter interpreter()) implemented by JinjavaELContext and NoInvokeELContext. Allows the EL resolver layer to obtain the current interpreter from the context without a static getCurrent() call when the context is available.

---

Changes to existing components

JinjavaBeanELResolver

The central change. The old DEFAULT_RESTRICTED_METHODS, DEFAULT_RESTRICTED_PROPERTIES, and isRestrictedClass are removed entirely. Method validation is now delegated:

• findMethod — after resolving the candidate method, calls getJinjavaConfig().getMethodValidator().validateMethod(method). Returns null (method not found) if the validator rejects it.
• getReadMethod / getWriteMethod — same pattern, so property access also goes through the allowlist.
• coerceValue — new override replaces the old ____int3rpr3t3r____ hack. When a method parameter is typed JinjavaInterpreter, it injects JinjavaInterpreter.getCurrent() directly. Filters and expression tests that accept JinjavaInterpreter as a parameter continue to work without any special naming convention.
• Method lookup now uses a BeanMethods cache (Introspector.getBeanInfo → MethodDescriptor[] indexed by name) per class, stored in a ConcurrentHashMap<Class<?>, BeanMethods>. This avoids calling getClass().getMethods() on every invocation and removes the findAccessibleMethod scan from the hot path.

JinjavaConfig

• Removes getRestrictedMethods() and getRestrictedProperties().
• Adds getMethodValidator() (default: AllowlistMethodValidator.DEFAULT).
• Adds getReturnTypeValidator() (default: AllowlistReturnTypeValidator.DEFAULT).

Both new methods have @Value.Default so existing JinjavaConfig builders continue to work without changes.

JinjavaInterpreterResolver

Raw Set values are now wrapped in SizeLimitingPySet (analogous to how List and Map are already wrapped in their SizeLimiting* equivalents). This also means Set is now in the Collections allowlist group and can be returned from expressions.

PySet / SizeLimitingPySet

• PySet — a new ForwardingSet<Object> that implements PyWrapper. Includes a recursion-guarded hashCode() to handle sets that contain themselves.
• SizeLimitingPySet — mirrors SizeLimitingPyList / SizeLimitingPyMap. Enforces maxSize on construction, add, and addAll; emits a WARNING-level TemplateError when the set reaches 90% capacity.

ArrayBacked

Marker interface (T[] backingArray()) for types that expose a backing array, used to support array return types through the validator.

---

Tests

• ValidatorConfigBannedConstructsTest — verifies that banned types (Object, Class, java.lang.reflect, com.fasterxml.jackson.databind, JinjavaInterpreter) cannot be added to either MethodValidatorConfig or ReturnTypeValidatorConfig without throwing.
• JinjavaBeanELResolverTest — restructured to test the new allowlist-delegation behavior rather than the removed hardcoded blocklist.
• BaseJinjavaTest and most other tests updated to use explicit validator config where tests exercise method calls that go through the allowlist.

[rewaddell]

nit: I don't love the name, but it's tolerable. Could be BlocklistOptions or BanlistOptions

[jasmith-hs]

@rewaddell It's banning things from being added to the allowlist.

BlocklistOptions or BanlistOptions don't make sense because that insinuates that this class provides options for a blocklist or for a banlist, which isn't what it does, nor do we allow blocklists in jinjava anymore

BannedAllowlistOptions says: "we are banning you from adding these things to an allowlist"

Alternate suggestions:

• BannedAllowlistOptions
• AllowlistBanning
• AllowlistLegality
• AllowlistLegalityVerifier

Any pref?

[rewaddell]

Ok with that in mind, I do like BannedAllowlistOptions, thanks!

[rewaddell]

nit: This could be a HashSet and you could use fns.removeAll(disabledFunctions here or some other set operation

[jasmith-hs]

That isn't strictly better. As creating a HashSet is more expensive than creating an ArrayList.

I'm not really touching this code in this PR. These lines here are changed because I had some intermediate change that switched the disabled library to be ImmutableMap<Library, ImmutableSet<String>>, but I decided against doing that.

I kept these changes in because it's faster to return fns right away if there are no disabled functions rather than loop through it