Improve compact token auth

api/src/main/java/io/bosonnetwork/crypto/CachedCryptoIdentity.java

@@ -77,12 +77,12 @@ public void initCache(Caffeine<Object, Object> caffeine) {
 
 	/**
 	 * Clears the cached {@link CryptoContext} instances.
-	 *
+	 * <p>
 	 * This method invalidates all entries in the cache, ensuring that any
 	 * cached cryptographic contexts are removed. Subsequent operations
 	 * will no longer utilize the invalidated contexts and may trigger
 	 * re-creation of new contexts as needed.
-	 *
+	 * <p>
 	 * If the cache is uninitialized or null, this method has no effect.
 	 */
 	public void clearCache() {
@@ -95,22 +95,22 @@ private CryptoContext getContext(Id id) throws CryptoException {
 	}
 
 	/**
-	 * Performs one-shot encryption of the given data for the specified recipient.
+	 * Performs one-shot encryption of the given data for the specified receiver.
 	 * <p>
-	 * This operation leverages a cached {@link CryptoContext} instance associated with the recipient,
+	 * This operation leverages a cached {@link CryptoContext} instance associated with the receiver,
 	 * reducing the overhead of repeatedly computing cryptographic contexts.
 	 *
-	 * @param recipient the recipient's {@link Id}; must not be {@code null}
+	 * @param receiver the receiver's {@link Id}; must not be {@code null}
 	 * @param data the plaintext data to encrypt; must not be {@code null}
 	 * @return the encrypted data including the nonce prepended
-	 * @throws NullPointerException if {@code recipient} or {@code data} is {@code null}
+	 * @throws NullPointerException if {@code receiver} or {@code data} is {@code null}
 	 * @throws CryptoException if an error occurs during encryption
 	 */
 	@Override
-	public byte[] encrypt(Id recipient, byte[] data) throws CryptoException {
-		Objects.requireNonNull(recipient, "recipient");
+	public byte[] encrypt(Id receiver, byte[] data) throws CryptoException {
+		Objects.requireNonNull(receiver, "receiver");
 		Objects.requireNonNull(data, "data");
-		return getContext(recipient).encrypt(data);
+		return getContext(receiver).encrypt(data);
 	}
 
 	/**

api/src/main/java/io/bosonnetwork/crypto/CryptoIdentity.java

@@ -85,23 +85,23 @@ public boolean verify(byte[] data, byte[] signature) {
 	}
 
 	/**
-	 * Performs one-shot encryption of the given data for the specified recipient.
+	 * Performs one-shot encryption of the given data for the specified receiver.
 	 *
-	 * @param recipient the recipient's {@link Id}; must not be {@code null}
+	 * @param receiver the receiver's {@link Id}; must not be {@code null}
 	 * @param data the plaintext data to encrypt; must not be {@code null}
 	 * @return the encrypted data including the nonce prepended
-	 * @throws NullPointerException if {@code recipient} or {@code data} is {@code null}
+	 * @throws NullPointerException if {@code receiver} or {@code data} is {@code null}
 	 * @throws CryptoException if an error occurs during encryption
 	 */
 	@Override
-	public byte[] encrypt(Id recipient, byte[] data) throws CryptoException {
-		Objects.requireNonNull(recipient, "recipient");
+	public byte[] encrypt(Id receiver, byte[] data) throws CryptoException {
+		Objects.requireNonNull(receiver, "receiver");
 		Objects.requireNonNull(data, "data");
 
 		try {
 			// TODO: how to avoid the memory copy?!
 			CryptoBox.Nonce nonce = CryptoBox.Nonce.random();
-			CryptoBox.PublicKey pk = recipient.toEncryptionKey();
+			CryptoBox.PublicKey pk = receiver.toEncryptionKey();
 			CryptoBox.PrivateKey sk = encryptionKeyPair.privateKey();
 			byte[] cipher = CryptoBox.encrypt(data, pk, sk, nonce);
 

api/src/main/java/io/bosonnetwork/service/Federation.java

@@ -26,6 +26,7 @@
 import java.util.concurrent.CompletableFuture;
 
 import io.bosonnetwork.Id;
+import io.bosonnetwork.web.CompactWebTokenAuth;
 
 /**
  * Federation manager (read-only) interface for the Boson Super Node services.
@@ -35,6 +36,22 @@
  * specific services hosted by federated nodes.
  */
 public interface Federation {
+	/**
+	 * Represents the type of incident that can occur within the federation.
+	 * This enumeration is used to classify and report issues related to
+	 * federated nodes or services.
+	 */
+	enum IncidentType {
+		/** Indicates a complete failure or unavailability of a service. */
+		SERVICE_OUTAGE,
+		/** Indicates a service encountering an operation failure or error. */
+		SERVICE_ERROR,
+		/** Indicates a poorly formed or invalid request received. */
+		MALFORMED_REQUEST,
+		/** Indicates an invalid or improperly constructed response sent. */
+		MALFORMED_RESPONSE
+	}
+
 	/**
 	 * Retrieves a federated node by its ID.
 	 *
@@ -43,7 +60,7 @@ public interface Federation {
 	 * @return a {@link CompletableFuture} that completes with the {@link FederatedNode} object if found,
 	 *         or completes exceptionally/with null if the node cannot be found or federated
 	 */
-	public CompletableFuture<? extends FederatedNode> getNode(Id nodeId, boolean federateIfNotExists);
+	CompletableFuture<? extends FederatedNode> getNode(Id nodeId, boolean federateIfNotExists);
 
 	/**
 	 * Retrieves a federated node by its ID.
@@ -65,7 +82,7 @@ default CompletableFuture<? extends FederatedNode> getNode(Id nodeId) {
 	 * @return a {@link CompletableFuture} that completes with {@code true} if the node exists,
 	 *         or {@code false} otherwise
 	 */
-	public CompletableFuture<Boolean> existsNode(Id nodeId);
+	CompletableFuture<Boolean> existsNode(Id nodeId);
 
 	/**
 	 * Retrieves information about a specific service hosted by a federated node.
@@ -75,7 +92,7 @@ default CompletableFuture<? extends FederatedNode> getNode(Id nodeId) {
 	 * @return a {@link CompletableFuture} that completes with the list of {@link ServiceInfo} if found,
 	 *         or completes exceptionally/with null if the service cannot be located
 	 */
-	public CompletableFuture<List<? extends ServiceInfo>> getServices(Id peerId, Id nodeId);
+	CompletableFuture<List<? extends ServiceInfo>> getServices(Id peerId, Id nodeId);
 
 	/**
 	 * Retrieves a list of services associated with a specific peer identified by its ID.
@@ -85,5 +102,34 @@ default CompletableFuture<? extends FederatedNode> getNode(Id nodeId) {
 	 *         representing the services associated with the specified peer, or completes exceptionally
 	 *         if an error occurs while retrieving the services
 	 */
-	public CompletableFuture<List<? extends ServiceInfo>> getServices(Id peerId);
+	CompletableFuture<List<? extends ServiceInfo>> getServices(Id peerId);
+
+	/**
+	 * Reports an incident associated with a specific federated node and peer.
+	 *
+	 * @param nodeId   the unique identifier of the federated node where the incident occurred
+	 * @param peerId   the unique identifier of the peer involved in the incident
+	 * @param incident the type of incident being reported
+	 * @param details  a detailed description of the incident
+	 * @return a {@link CompletableFuture} that completes when the incident has been reported successfully,
+	 *         or completes exceptionally if an error occurs during the reporting process
+	 */
+	CompletableFuture<Void> reportIncident(Id nodeId, Id peerId, IncidentType incident, String details);
+
+	/**
+	 * Retrieves the instance of {@link FederationAuthenticator} associated with this federation.
+	 *
+	 * @return the {@link FederationAuthenticator} responsible for managing authentication
+	 *         within the federation context.
+	 */
+	FederationAuthenticator getAuthenticator();
+
+	/**
+	 * Retrieves the instance of {@link CompactWebTokenAuth} used for handling
+	 * web token authentication within the federation.
+	 *
+	 * @return the {@link CompactWebTokenAuth} instance responsible for managing
+	 *         web token authentication.
+	 */
+	CompactWebTokenAuth getWebTokenAuthenticator();
 }