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
 enforcer.enforceAccessControl(action, role, callerAgentId, callerRoles);
 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:

  • Nested Class Summary

    Nested classes/interfaces inherited from interface com.tnsai.security.SecurityEnforcerHandle

    com.tnsai.security.SecurityEnforcerHandle.Factory

  • Field Summary

    Fields inherited from interface com.tnsai.security.SecurityEnforcerHandle

    NOOP

  • Constructor Summary

    Constructors
    Constructor
    Description
    SecurityEnforcer()
    Creates a SecurityEnforcer with an auto-generated encryption key.
    SecurityEnforcer(EncryptionConfig encryptionConfig)
    Creates a SecurityEnforcer with the specified encryption configuration.
    SecurityEnforcer(EncryptionConfig encryptionConfig, com.tnsai.security.PermissionProvider permissionProvider)
    Creates a SecurityEnforcer with the specified encryption configuration and permission provider.

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    void
    close()
    Shuts down the timeout executor.
    String
    decrypt(String encrypted)
    Decrypts a Base64-encoded AES-256-GCM encrypted value.
    String
    encrypt(String value)
    Encrypts a string value using AES-256-GCM.
    void
    enforceAccess(com.tnsai.security.AccessRequest request)
     
    void
    enforceAccessControl(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, String callerAgentId, Set<String> callerRoles)
    Enforces access control based on @Security annotation.
    <T> T
    executeWithTimeout(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, Callable<T> task)
    Executes an action with security timeout enforcement.
    EncryptionConfig
    getEncryptionConfig()
    Gets the encryption configuration.
    com.tnsai.security.PermissionProvider
    getPermissionProvider()
    Gets the permission provider, if any.
    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.
    Map<String,Object>
    processParameters(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, Map<String,Object> parameters)
    Processes parameters based on security settings.
    Object
    processResult(com.tnsai.metadata.ActionMetadata action, com.tnsai.roles.Role role, Object result)
    Processes the result based on security settings.
    void
    shutdown()
    Shuts down the timeout executor.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • 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 @Security annotation.
      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)

    • 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)

    • 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.
      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.security.SecurityException - if 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

    • 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.