Package com.tnsai.quality.security

Class SecurityEnforcer

java.lang.Object
com.tnsai.quality.security.SecurityEnforcer
All Implemented Interfaces:
com.tnsai.security.SecurityEnforcerHandle, AutoCloseable
public final class SecurityEnforcer extends Object implements com.tnsai.security.SecurityEnforcerHandle, AutoCloseable
Enforces security policies defined via @Security annotation.

This class is a facade that delegates to focused services:

  • AccessControlManager — caller ID checks, role-based checks, permission queries
  • EncryptionService — AES-256-GCM encrypt/decrypt
  • AuditLogger — field masking and audit logging at 4 levels

Timeout execution remains in this class since it requires the ExecutorService.

Usage


 // With auto-generated encryption key
 SecurityEnforcer enforcer = new SecurityEnforcer();

 // With custom encryption config
 EncryptionConfig config = EncryptionConfig.fromBase64Key(myKey);
 SecurityEnforcer enforcer = new SecurityEnforcer(config);

 // Before action execution; ActionExecutor calls enforceAccess(AccessRequest) as its access gate
 Map<String, Object> secureParams = enforcer.processParameters(action, role, params);

 // Execute with timeout
 Object result = enforcer.executeWithTimeout(action, role, () -> doExecute());

 // Process result
 Object secureResult = enforcer.processResult(action, role, result);
Author:
TnsAI Team
See Also:

  • Constructor Details

    • SecurityEnforcer

      public SecurityEnforcer()
      Creates a SecurityEnforcer with an auto-generated encryption key. Attempts to discover a PermissionProvider via ServiceLoader.

    • SecurityEnforcer

      public SecurityEnforcer(EncryptionConfig encryptionConfig)
      Creates a SecurityEnforcer with the specified encryption configuration. Attempts to discover a PermissionProvider via ServiceLoader.
      Parameters:
      encryptionConfig - the encryption configuration to use

    • SecurityEnforcer

      public SecurityEnforcer(EncryptionConfig encryptionConfig, com.tnsai.security.PermissionProvider permissionProvider)
      Creates a SecurityEnforcer with the specified encryption configuration and permission provider.
      Parameters:
      encryptionConfig - the encryption configuration to use
      permissionProvider - the permission provider (null for no permission checks)

  • Method Details

    • enforceAccess

      public void enforceAccess(com.tnsai.security.AccessRequest request)
      Specified by:
      enforceAccess in interface com.tnsai.security.SecurityEnforcerHandle

    • getEncryptionConfig

      public EncryptionConfig getEncryptionConfig()
      Gets the encryption configuration.
      Returns:
      the encryption configuration

    • getPermissionProvider

      public com.tnsai.security.PermissionProvider getPermissionProvider()
      Gets the permission provider, if any.
      Returns:
      the permission provider, or null if none registered

    • enforceAccessControl

      public void enforceAccessControl(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, String callerAgentId, Set<String> callerRoles)
      Enforces access control based on the action method's @Security, else the role class's own.

      This is not the executor's access gate and does not see inherited declarations: a @Security on a superclass, an interface or an overridden method is not checked here. The executor checks every @Security through enforceAccess(com.tnsai.security.AccessRequest).

      Specified by:
      enforceAccessControl in interface com.tnsai.security.SecurityEnforcerHandle
      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:
      com.tnsai.security.SecurityException - if access is denied

    • processParameters

      public Map<String,Object> processParameters(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, Map<String,Object> parameters)
      Processes parameters based on security settings. Handles encryption if encryptParams is true.
      Specified by:
      processParameters in interface com.tnsai.security.SecurityEnforcerHandle
      Parameters:
      action - the action metadata
      role - the role containing the action
      parameters - the original parameters
      Returns:
      processed parameters (encrypted if required)

    • requireHonored

      public void requireHonored(com.tnsai.metadata.ActionMetadata action, Object target)
      Honors every target-typed feature, so it refuses nothing.
      Specified by:
      requireHonored in interface com.tnsai.security.SecurityEnforcerHandle
      Parameters:
      action - the action metadata
      target - the object containing the action

    • processParameters

      public Map<String,Object> processParameters(com.tnsai.metadata.ActionMetadata action, Object target, Map<String,Object> parameters)
      Processes parameters for an action whose target is not a Role, as processParameters(ActionMetadata, Role, Map) does; its @Security features are read as on a Role.
      Specified by:
      processParameters in interface com.tnsai.security.SecurityEnforcerHandle
      Parameters:
      action - the action metadata
      target - the object containing the action
      parameters - the original parameters
      Returns:
      processed parameters (encrypted if required)

    • processResult

      public Object processResult(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, Object result)
      Processes the result based on security settings. Handles encryption if encryptResult is true.
      Specified by:
      processResult in interface com.tnsai.security.SecurityEnforcerHandle
      Parameters:
      action - the action metadata
      role - the role containing the action
      result - the original result
      Returns:
      processed result (encrypted if required)

    • processResult

      public Object processResult(com.tnsai.metadata.ActionMetadata action, Object target, Object result)
      Processes the result for an action whose target is not a Role, as processResult(ActionMetadata, Role, Object) does; its @Security features are read as on a Role.
      Specified by:
      processResult in interface com.tnsai.security.SecurityEnforcerHandle
      Parameters:
      action - the action metadata
      target - the object containing the action
      result - the original result
      Returns:
      processed result (encrypted if required)

    • executeWithTimeout

      public <T> T executeWithTimeout(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, Callable<T> task)
      Executes an action with security timeout enforcement. A failure of task is not a security violation: an unchecked exception or an error propagates unchanged, and a checked exception becomes a TnsAIException whose cause it is, as SecurityEnforcerHandle.NOOP does. Only the timeout and an interrupt of the waiting thread become a SecurityException.
      Specified by:
      executeWithTimeout in interface com.tnsai.security.SecurityEnforcerHandle
      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
      Throws:
      com.tnsai.exceptions.TnsAIException - if task throws a checked exception
      com.tnsai.security.SecurityException - if the timeout is exceeded or the waiting thread is interrupted

    • executeWithTimeout

      public <T> T executeWithTimeout(com.tnsai.metadata.ActionMetadata action, Object target, Callable<T> task) throws Exception
      Executes an action whose target is not a Role with security timeout enforcement; its @Security features are read as on a Role. Unlike executeWithTimeout(ActionMetadata, Role, Callable), which wraps a checked failure of task in a TnsAIException, every failure of task propagates unchanged: without a declared securityTimeout the task runs on the calling thread, and with one only the timeout and an interrupt of the waiting thread become a SecurityException.
      Specified by:
      executeWithTimeout in interface com.tnsai.security.SecurityEnforcerHandle
      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
      com.tnsai.security.SecurityException - if the timeout is exceeded

    • maskForLogging

      public Map<String,Object> maskForLogging(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, Map<String,Object> parameters)
      Masks sensitive fields in parameters for logging.
      Parameters:
      action - the action metadata
      role - the role containing the action
      parameters - the parameters to mask
      Returns:
      masked parameters safe for logging

    • audit

      public void audit(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, String callerAgentId, Map<String,Object> parameters, Object result, long durationMs)
      Logs audit information based on audit level.
      Specified by:
      audit in interface com.tnsai.security.SecurityEnforcerHandle
      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

    • audit

      public void audit(com.tnsai.metadata.ActionMetadata action, Object target, String callerAgentId, Map<String,Object> parameters, Object result, long durationMs)
      Logs audit information for an action whose target is not a Role, as audit(ActionMetadata, Role, String, Map, Object, long) does; its @Security features are read as on a Role.
      Specified by:
      audit in interface com.tnsai.security.SecurityEnforcerHandle
      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

    • encrypt

      public String encrypt(String value)
      Encrypts a string value using AES-256-GCM.

      The encrypted output format is: Base64(IV + ciphertext + authTag) where IV is prepended to allow decryption.

      Parameters:
      value - the plaintext value to encrypt
      Returns:
      Base64-encoded encrypted value
      Throws:
      com.tnsai.security.SecurityException - if encryption fails

    • decrypt

      public String decrypt(String encrypted)
      Decrypts a Base64-encoded AES-256-GCM encrypted value.
      Parameters:
      encrypted - the Base64-encoded encrypted value
      Returns:
      the decrypted plaintext value
      Throws:
      com.tnsai.security.SecurityException - if decryption fails or authentication fails

    • close

      public void close()
      Shuts down the timeout executor.
      Specified by:
      close in interface AutoCloseable

    • shutdown

      public void shutdown()
      Shuts down the timeout executor.