Package com.privatechain.access.allowlist

Class AllowlistManager

java.lang.Object
com.privatechain.access.allowlist.AllowlistManager
public class AllowlistManager extends Object
Manages the allowlist of permitted node identifiers in a private blockchain network.

An allowlist is the set of node IDs which are permitted to participate in the private blockchain network. Messages from non-allowlisted nodes should be silently dropped before deserialization (FR-AC-01, NFR-SEC-04).

The allowlist can be persisted to durable storage via AllowlistStore, allowing membership changes to survive process restarts.

Thread safety

This class uses a CopyOnWriteArraySet for the allowlist, making it safe for concurrent reads. The trade-off is that modifications (add/remove) are slower than reads, but this is acceptable because permission updates happen infrequently.

Usage


 AllowlistManager allowlist = new AllowlistManager();
 allowlist.add("trusted-node-1");
 allowlist.add("trusted-node-2");

 if (!allowlist.isAllowed("peer-123")) {
     log.warn("Rejecting message from non-allowlisted node: {}", peer);
     return;
 }
Since:
1.0.0
See Also:

  • Constructor Details

    • AllowlistManager

      public AllowlistManager()
      Constructs an empty AllowlistManager.

      No nodes are allowed initially. Call add(String) or loadFromStore(AllowlistStore) to populate the allowlist.

    • AllowlistManager

      public AllowlistManager(Collection<String> initialNodes)
      Constructs an AllowlistManager pre-populated with initial node IDs.

      To restore allowlist from persistent storage, use loadFromStore(AllowlistStore) after construction.

      Parameters:
      initialNodes - collection of node IDs to allowlist (non-null; may be empty)
      Throws:
      NullPointerException - if initialNodes is null

  • Method Details

    • isAllowed

      public boolean isAllowed(String nodeId)
      Checks whether a node ID is on the allowlist.

      This method returns very quickly because it does not acquire locks; it is safe to call from hot paths such as inbound message handlers.

      Parameters:
      nodeId - the node identifier to check (non-null, non-blank)
      Returns:
      true if the node is allowlisted; false otherwise
      Throws:
      NullPointerException - if nodeId is null
      IllegalArgumentException - if nodeId is blank

    • size

      public int size()
      Returns the number of allowlisted nodes.
      Returns:
      count of nodes on the allowlist

    • isEmpty

      public boolean isEmpty()
      Returns true if the allowlist is empty.
      Returns:
      true if no nodes are allowlisted

    • getAllowedNodes

      public Set<String> getAllowedNodes()
      Returns all currently allowlisted node IDs.

      The returned set is a snapshot; modifications to the set do not affect the manager's internal state.

      Returns:
      unmodifiable set of allowlisted node IDs

    • add

      public void add(String nodeId)
      Adds a node ID to the allowlist.

      If the node ID is already on the list, this is a no-op.

      Parameters:
      nodeId - the node identifier to add (non-null, non-blank)
      Throws:
      NullPointerException - if nodeId is null
      IllegalArgumentException - if nodeId is blank

    • remove

      public void remove(String nodeId)
      Removes a node ID from the allowlist.

      If the node ID is not on the list, this is a no-op.

      Parameters:
      nodeId - the node identifier to remove (non-null, non-blank)
      Throws:
      NullPointerException - if nodeId is null
      IllegalArgumentException - if nodeId is blank

    • replaceAllowlist

      public void replaceAllowlist(Collection<String> newAllowlist)
      Replaces the allowlist with a new set of node IDs.

      All previously allowlisted nodes are removed, and the provided collection becomes the new allowlist.

      Parameters:
      newAllowlist - collection of node IDs (non-null; may be empty)
      Throws:
      NullPointerException - if newAllowlist is null

    • clear

      public void clear()
      Clears the allowlist, removing all node IDs.

    • loadFromStore

      public void loadFromStore(AllowlistStore store)
      Loads allowlisted node IDs from persistent storage.

      This method is typically called once at application startup to restore the allowlist from a previous session. It clears the current allowlist before loading persisted data.

      Parameters:
      store - the persistent storage implementation (non-null)
      Throws:
      NullPointerException - if store is null
      See Also:

    • saveToStore

      public void saveToStore(AllowlistStore store)
      Saves the current allowlist to persistent storage.

      This method is called to durably persist changes to the allowlist. The set passed to the store contains all currently allowlisted node IDs.

      Parameters:
      store - the persistent storage implementation (non-null)
      Throws:
      NullPointerException - if store is null
      See Also:

    • addFromInvitation

      public void addFromInvitation(String nodeId)
      Verifies an invitation token and adds the requested node to the allowlist.

      This method is called by the InvitationService after validating a token's signature and expiry. If both checks pass, the node ID is added to the allowlist.

      Parameters:
      nodeId - the node ID to add based on a valid invitation (non-null, non-blank)
      Throws:
      NullPointerException - if nodeId is null
      IllegalArgumentException - if nodeId is blank