Package com.privatechain.access.invite

Class InvitationService

java.lang.Object
com.privatechain.access.invite.InvitationService
public class InvitationService extends Object
Service for generating and verifying time-limited invitation tokens for new node onboarding.

An admin node uses this service to generate a signed invitation token for a new node that wishes to join a private blockchain network. The token contains the new node's ID, an expiry time, and an ECDSA signature over both, signed by the admin's private key.

When the new node presents its token, this service verifies the signature and checks the expiry. If both checks pass, the new node is added to the allowlist and assigned a default role (FR-AC-04, FR-AC-05).

Usage


 // On the admin node:
 invitationService.generateToken("new-node-123", Instant.now().plusSeconds(3600));
   // → sends token out-of-band to new node operator

 // On the joining node:
 if (invitationService.verifyToken(token)) {
     // Token is valid and node is now allowlisted
 } else {
     // Token is invalid or expired
 }
Since:
1.0.0
See Also:

  • Constructor Details

    • InvitationService

      public InvitationService(ECKeyPair adminKeyPair, PermissionManager permissionManager, AllowlistManager allowlistManager)
      Constructs an InvitationService with the given admin credentials and manager references.

      Only instances with the admin's key pair should be created; consumer nodes would have read-only access to the service or verify tokens using just the admin's public key.

      Parameters:
      adminKeyPair - the admin node's key pair (non-null)
      permissionManager - reference to the permission manager (non-null)
      allowlistManager - reference to the allowlist manager (non-null)
      Throws:
      NullPointerException - if any parameter is null

  • Method Details

    • generateToken

      public InvitationToken generateToken(String nodeId, Instant expiryTime)
      Generates a signed invitation token for a new node.

      The token contains the node ID, the expiry timestamp, and an ECDSA signature over both, computed using the admin's private key. The token is suitable for transmission to the new node out-of-band (e.g., email, secure chat).

      The token can be encoded via InvitationToken.getEncodedToken() for transport as a Base64 string.

      Parameters:
      nodeId - the node ID requesting to join (non-null, non-blank)
      expiryTime - the token expiry instant (non-null, must be in the future)
      Returns:
      an InvitationToken signed by the admin
      Throws:
      NullPointerException - if nodeId or expiryTime is null
      IllegalArgumentException - if nodeId is blank or expiryTime is in the past

    • generateToken

      public InvitationToken generateToken(String nodeId, long validitySeconds)
      Convenience overload that generates a token valid for a specified duration from now.
      Parameters:
      nodeId - the node ID requesting to join (non-null, non-blank)
      validitySeconds - how many seconds from now the token should expire (positive)
      Returns:
      an InvitationToken signed by the admin
      Throws:
      NullPointerException - if nodeId is null
      IllegalArgumentException - if nodeId is blank or validitySeconds is non-positive

    • verifyToken

      public boolean verifyToken(InvitationToken token)
      Verifies an invitation token: checks the signature and expiry.

      On success, the node is added to the allowlist and assigned the NodeRole.NODE_OBSERVER role. On failure, the node is not modified and this method returns false.

      Parameters:
      token - the token to verify (non-null)
      Returns:
      true if the token is valid and accepted; false if the signature is invalid, the token is expired, or verification fails
      Throws:
      NullPointerException - if token is null

    • verifyToken

      public boolean verifyToken(String encodedToken)
      Verifies an invitation token from an encoded (Base64) string.

      This is a convenience overload that parses the token before verification.

      Parameters:
      encodedToken - the Base64-encoded token (non-null, non-blank)
      Returns:
      true if the token is valid and accepted; false otherwise
      Throws:
      NullPointerException - if encodedToken is null
      IllegalArgumentException - if encodedToken is blank or malformed