Package com.tnsai.guardrails

Class InputGuardrailEnforcer

java.lang.Object
com.tnsai.guardrails.InputGuardrailEnforcer
public final class InputGuardrailEnforcer extends Object
Resolves the active input guardrail for an action and enforces it against the working-parameter map immediately before the action body runs.

The guardrail is expressed as an InputGuardrailConfig — sourced either from an @InputGuardrail annotation (method- or class-level) or, for builder-built roles, from RoleBuilder.inputGuardrail(...) via Role.getInputGuardrailConfig() (TNS-561). Resolution precedence: method annotation > builder role config > class annotation.

Phase 1 enforcement matrix

  • minLength / maxLength — character bounds on every String-typed parameter. 0 means "no bound" on either side.
  • blockPatterns — regex denylist; a parameter whose value matches ANY pattern violates.
  • allowPatterns — regex allowlist; a parameter whose value matches NONE violates. An empty list disables the allowlist (everything passes).
  • validators / sanitizers — stateless extension classes declared on the annotation. Validator failures follow onFailure; SANITIZE runs all declared sanitizers and then re-validates before dispatch.
  • onFailure — see applyFailureAction(com.tnsai.annotations.InputGuardrail.FailureAction, com.tnsai.guardrails.InputGuardrailConfig, com.tnsai.metadata.ActionMetadata, java.lang.String, com.tnsai.guardrails.GuardrailViolationException.Cause, java.lang.String, java.lang.String) for the full disposition.
Since:
0.5.4 (issue #171, Phase 1); builder-config path added 0.11.1 (TNS-561)

  • Method Details

    • enforce

      public static Map<String,Object> enforce(ActionMetadata action, Role role, Map<String,Object> params)
      Enforces the (possibly inherited) input guardrail on params. Returns a (possibly mutated) parameter map — for InputGuardrail.FailureAction.SANITIZE the offending values are replaced with sanitized copies; for InputGuardrail.FailureAction.WARN the originals pass through unchanged.

      Throws GuardrailViolationException for InputGuardrail.FailureAction.REJECT and InputGuardrail.FailureAction.REVIEW.

      Parameters:
      action - the action being executed (for guardrail discovery + error context)
      role - the role instance hosting the action (for builder config + class-level fallback)
      params - the working parameters about to be dispatched
      Returns:
      params with sanitized values substituted where applicable

    • enforceForTarget

      public static Map<String,Object> enforceForTarget(ActionMetadata action, Object target, Map<String,Object> params)
      Enforces method- or class-level input guardrails for a generic action target. This is the non-Role counterpart used by SCOP and function-shape tool dispatch.
      Parameters:
      action - action metadata containing the reflected method
      target - object that owns the action method; may be null for method-only lookup
      params - working parameters about to be dispatched
      Returns:
      params with safe replacements applied where configured