Package com.tnsai.security

Interface SecurityEnforcerHandle

public interface SecurityEnforcerHandle
SPI handle for security enforcement.

This interface defines the security enforcement contract that ActionExecutor uses. The concrete implementation (SecurityEnforcer) lives in tnsai-quality and is discovered via SpiLoader.

When tnsai-quality is not on the classpath, the factory returns a no-op handle that retains undeclared legacy behavior but rejects declared access policies. On an action whose target is not a Role, it also refuses the declared @Security encryption, timeout and audit features and @AuditLog.

  • Field Details

  • Method Details

    • enforceAccess

      default void enforceAccess(AccessRequest request)
      Canonical role-independent access evaluation. Implementations predating this contract cannot silently authorize declared policies. Optional providers stay outside core; the default is deliberately fail-closed.

    • enforceAccessControl

      void enforceAccessControl(ActionMetadata action, Role role, String callerAgentId, Set<String> callerRoles)
      Enforces access control based on @Security annotation.
      Parameters:
      action - the action metadata
      role - the role containing the action
      callerAgentId - the ID of the calling agent (null if unknown)
      callerRoles - the roles of the calling agent
      Throws:
      SecurityException - if access is denied

    • processParameters

      Map<String,Object> processParameters(ActionMetadata action, Role role, Map<String,Object> parameters)
      Processes parameters based on security settings.
      Parameters:
      action - the action metadata
      role - the role containing the action
      parameters - the original parameters
      Returns:
      processed parameters (encrypted if required)

    • executeWithTimeout

      <T> T executeWithTimeout(ActionMetadata action, Role role, Callable<T> task)
      Executes an action with security timeout enforcement.
      Type Parameters:
      T - the result type
      Parameters:
      action - the action metadata
      role - the role containing the action
      task - the task to execute
      Returns:
      the execution result

    • processResult

      Object processResult(ActionMetadata action, Role role, Object result)
      Processes the result based on security settings.
      Parameters:
      action - the action metadata
      role - the role containing the action
      result - the original result
      Returns:
      processed result (encrypted if required)

    • audit

      void audit(ActionMetadata action, Role role, String callerAgentId, Map<String,Object> parameters, Object result, long durationMs)
      Logs audit information based on audit level.
      Parameters:
      action - the action metadata
      role - the role containing the action
      callerAgentId - the caller agent ID
      parameters - the action parameters
      result - the action result
      durationMs - execution duration in milliseconds

    • requireHonored

      default void requireHonored(ActionMetadata action, Object target)
      Refuses, before the action's body runs, an action whose target is not a Role and whose features this handle cannot honor. The executor calls it before processParameters(ActionMetadata, Object, Map).

      The default refuses when the action declares any feature the target-typed methods carry (encryptParams, encryptResult, a securityTimeout, an audit level or @AuditLog), so a handle that overrides only some of those methods is refused before the body runs, never after it. A handle that honors all four overrides this method to do nothing.

      Parameters:
      action - the action metadata
      target - the object containing the action
      Throws:
      SecurityException - UNAUTHORIZED when the handle cannot honor a declared feature

    • processParameters

      default Map<String,Object> processParameters(ActionMetadata action, Object target, Map<String,Object> parameters)
      Processes parameters based on security settings, for an action whose target is not a Role.

      The action's @Security features are SecurityFeatures.of(Object, java.lang.reflect.Method): every @Security on the target's class hierarchy, the action method and the methods it overrides. The default refuses as requireHonored(ActionMetadata, Object) does, and otherwise returns parameters unchanged. A handle overrides all four target-typed methods and requireHonored, or none of them.

      Parameters:
      action - the action metadata
      target - the object containing the action
      parameters - the original parameters
      Returns:
      processed parameters (encrypted if required)
      Throws:
      SecurityException - UNAUTHORIZED when the default cannot honor a declared feature

    • executeWithTimeout

      default <T> T executeWithTimeout(ActionMetadata action, Object target, Callable<T> task) throws Exception
      Executes an action with security timeout enforcement, for an action whose target is not a Role. A failure of task propagates unchanged.

      The default refuses when the action declares a securityTimeout, and otherwise calls task on the calling thread.

      Type Parameters:
      T - the result type
      Parameters:
      action - the action metadata
      target - the object containing the action
      task - the task to execute
      Returns:
      the execution result
      Throws:
      Exception - whatever task throws
      SecurityException - UNAUTHORIZED when the default cannot honor a declared timeout

    • processResult

      default Object processResult(ActionMetadata action, Object target, Object result)
      Processes the result based on security settings, for an action whose target is not a Role.

      The default refuses when the action declares encryptResult, and otherwise returns result unchanged.

      Parameters:
      action - the action metadata
      target - the object containing the action
      result - the original result
      Returns:
      processed result (encrypted if required)
      Throws:
      SecurityException - UNAUTHORIZED when the default cannot honor a declared encryption

    • audit

      default void audit(ActionMetadata action, Object target, String callerAgentId, Map<String,Object> parameters, Object result, long durationMs)
      Logs audit information based on audit level and @AuditLog, for an action whose target is not a Role.

      The default refuses when the action declares an audit level or @AuditLog, and otherwise does nothing.

      Parameters:
      action - the action metadata
      target - the object containing the action
      callerAgentId - the caller agent ID
      parameters - the action parameters
      result - the action result
      durationMs - execution duration in milliseconds
      Throws:
      SecurityException - UNAUTHORIZED when the default cannot honor a declared audit