Package com.tnsai.security.approval

Interface ApprovalTokenStore

All Known Implementing Classes:
InMemoryApprovalTokenStore
public interface ApprovalTokenStore
Store for managing approval tokens.

Provides persistent storage for approval tokens, enabling human-in-the-loop workflows where tokens can be created, stored, approved, and validated across system restarts.

Implementations

  • InMemoryApprovalTokenStore - In-memory (development)
  • RedisApprovalTokenStore - Redis-backed (distributed)
  • DatabaseApprovalTokenStore - SQL-backed (persistent)

Usage Example


 // Create store
 ApprovalTokenStore store = new InMemoryApprovalTokenStore();

 // Create and save token
 ApprovalToken token = store.createToken(
     "agent-1",
     "delete-data",
     Duration.ofMinutes(5)
 );

 // Wait for approval (async in real app)
 token.approve("admin@example.com");

 // Validate and consume
 boolean valid = store.validateAndConsume(
     token.getTokenId(),
     "agent-1",
     "delete-data"
 );

 if (valid) {
     executeAction();
 }
See Also:

  • Method Details

    • createToken

      ApprovalToken createToken(String agentId, String actionName, Duration ttl)
      Creates a new approval token.
      Parameters:
      agentId - agent ID
      actionName - action name
      ttl - time to live
      Returns:
      created token

    • createToken

      ApprovalToken createToken(String agentId, String actionName, Map<String,Object> parameters, Duration ttl)
      Creates a token with parameters.
      Parameters:
      agentId - agent ID
      actionName - action name
      parameters - action parameters
      ttl - time to live
      Returns:
      created token

    • save

      void save(ApprovalToken token)
      Saves a token to the store.
      Parameters:
      token - token to save

    • getToken

      Optional<ApprovalToken> getToken(String tokenId)
      Gets a token by ID.
      Parameters:
      tokenId - token ID
      Returns:
      token or empty if not found

    • validateAndConsume

      boolean validateAndConsume(String tokenId, String agentId, String actionName)
      Validates the token binding and requires a successful consume.

      This method:

      1. Looks up the token by ID
      2. Checks agent and action match (without consuming)
      3. Requires a successful ApprovalToken.consume() — approved, not expired, and not already consumed
      Parameters:
      tokenId - token ID
      agentId - expected agent ID
      actionName - expected action name
      Returns:
      true if valid and consumed

    • approve

      boolean approve(String tokenId, String approver)
      Approves a token.
      Parameters:
      tokenId - token ID
      approver - who approved
      Returns:
      true if successfully approved

    • reject

      boolean reject(String tokenId, String rejector, String reason)
      Rejects a token.
      Parameters:
      tokenId - token ID
      rejector - who rejected
      reason - rejection reason
      Returns:
      true if successfully rejected

    • listPending

      List<ApprovalToken> listPending()
      Lists pending tokens.
      Returns:
      list of pending tokens

    • listPendingForAgent

      List<ApprovalToken> listPendingForAgent(String agentId)
      Lists pending tokens for a specific agent.
      Parameters:
      agentId - agent ID
      Returns:
      list of pending tokens for agent

    • delete

      boolean delete(String tokenId)
      Deletes a token.
      Parameters:
      tokenId - token ID
      Returns:
      true if deleted

    • cleanupExpired

      int cleanupExpired()
      Cleans up expired tokens.
      Returns:
      number of tokens cleaned

    • count

      int count()
      Gets total token count.
      Returns:
      token count