* CryptoContext provides a cryptographic context for encrypting and decrypting messages - * using public-key authenticated encryption. It manages nonce generation and validation - * to ensure message uniqueness and replay protection. + * using public-key authenticated encryption. It manages nonce generation for outgoing messages + * and provides a basic safeguard against immediate reuse of the previous incoming nonce + * (see {@link #decrypt(byte[])} for the precise, limited guarantee). *
** Thread Safety: The nonce generation for outgoing messages is synchronized to ensure @@ -138,14 +139,16 @@ public byte[] encrypt(byte[] data) { /** * Decrypts the given data, verifying and extracting the prepended nonce. *
- * This method checks for nonce reuse to prevent replay attacks. If the nonce - * is duplicated (i.e., the same as the last received nonce), a {@link CryptoException} - * is thrown. + * As a basic safeguard this rejects an exact repeat of the immediately previous + * peer nonce (throwing {@link CryptoException}). This is not full replay + * protection: it does not detect reuse of any earlier nonce, and the check is not thread-safe + * (concurrent {@code decrypt} calls may race). Callers that need strong replay protection must + * track seen nonces themselves. *
* * @param data The encrypted data, with the nonce prepended (nonce || ciphertext). * @return The decrypted plaintext data. - * @throws CryptoException If the input is invalid, the nonce is duplicated, or decryption fails. + * @throws CryptoException If the input is invalid, the nonce repeats the previous one, or decryption fails. * @throws NullPointerException if {@code data} is {@code null}. */ public byte[] decrypt(byte[] data) throws CryptoException { diff --git a/api/src/main/java/io/bosonnetwork/Id.java b/api/src/main/java/io/bosonnetwork/Id.java index 01ba391f..c6276521 100644 --- a/api/src/main/java/io/bosonnetwork/Id.java +++ b/api/src/main/java/io/bosonnetwork/Id.java @@ -83,6 +83,9 @@ public class Id implements Comparable
+ * Lookup result conventions: {@link #findNode} returns a {@link Result} that may carry the
+ * node's IPv4 and/or IPv6 address (either side may be {@code null}). Single-result lookups
+ * ({@link #findValue}, the single-result {@link #findPeer(Id)}) complete with {@code null} when
+ * nothing is found, while collection lookups ({@link #getPeers}, {@link #findPeer(Id, int, int, LookupOption)})
+ * complete with an empty list.
*/
public interface Node extends Identity {
/** The maximum age for a peer (2 hours). */
@@ -242,10 +249,10 @@ default CompletableFuture
+ * The concrete implementation is discovered via the {@link ServiceLoader} mechanism,
+ * looking up a registered {@link NodeFactory} provider (the Kademlia DHT node is
+ * provided by the {@code boson-dht} module).
*
* @param config the node configuration
* @return an initialized {@link Node} instance
- * @throws BosonException if the KadNode cannot be initialized
+ * @throws BosonException if no node implementation is available or it cannot be initialized
*/
static Node kadNode(NodeConfiguration config) throws BosonException {
- try {
- return (Node) Class.forName("io.bosonnetwork.kademlia.KadNode")
- .getConstructor(NodeConfiguration.class)
- .newInstance(config);
- } catch (ClassNotFoundException e) {
- throw new BosonException("KadNode not found in classpath", e);
- } catch (Exception e) {
- throw new BosonException("Internal error: can not instantiate KadNode", e);
- }
+ NodeFactory factory = ServiceLoader.load(NodeFactory.class).findFirst()
+ .orElseThrow(() -> new BosonException("No NodeFactory implementation found in classpath"));
+ return factory.create(config);
}
}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/NodeConfiguration.java b/api/src/main/java/io/bosonnetwork/NodeConfiguration.java
index 933d8a56..14d76a50 100644
--- a/api/src/main/java/io/bosonnetwork/NodeConfiguration.java
+++ b/api/src/main/java/io/bosonnetwork/NodeConfiguration.java
@@ -122,7 +122,7 @@ default Path dataDir() {
/**
* Provides the URL for database storage used by the DHT node.
*
- * @return the external database URL as a string, or {@code null} if not configured.
+ * @return the database URL as a string; defaults to {@code "jdbc:sqlite:node.db"}.
*/
default String databaseUri() {
return "jdbc:sqlite:node.db";
diff --git a/api/src/main/java/io/bosonnetwork/NodeFactory.java b/api/src/main/java/io/bosonnetwork/NodeFactory.java
new file mode 100644
index 00000000..090def52
--- /dev/null
+++ b/api/src/main/java/io/bosonnetwork/NodeFactory.java
@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package io.bosonnetwork;
+
+/**
+ * Service provider interface for creating {@link Node} instances.
+ *
+ * Implementations are discovered at runtime via the {@link java.util.ServiceLoader}
+ * mechanism, which decouples the {@code boson-api} contract from the concrete node
+ * implementation (e.g. the Kademlia DHT node in {@code boson-dht}). Providers register
+ * themselves through a {@code META-INF/services/io.bosonnetwork.NodeFactory} entry, or a
+ * {@code provides io.bosonnetwork.NodeFactory with ...} declaration when running on the
+ * Java module path.
+ *
+ * @see Node#kadNode(NodeConfiguration)
+ */
+public interface NodeFactory {
+ /**
+ * Creates and initializes a new {@link Node} instance using the provided configuration.
+ *
+ * @param config the node configuration
+ * @return an initialized {@link Node} instance
+ * @throws BosonException if the node cannot be initialized
+ */
+ Node create(NodeConfiguration config) throws BosonException;
+}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/NodeInfo.java b/api/src/main/java/io/bosonnetwork/NodeInfo.java
index 2aa73ebd..386e7fa4 100644
--- a/api/src/main/java/io/bosonnetwork/NodeInfo.java
+++ b/api/src/main/java/io/bosonnetwork/NodeInfo.java
@@ -29,7 +29,7 @@
import java.util.Objects;
/**
- * THis class represent the node information in the Boson network, it contains
+ * This class represents the node information in the Boson network; it contains
* basic node network information.
*/
public class NodeInfo {
@@ -44,12 +44,8 @@ public class NodeInfo {
* @param addr the node socket address.
*/
public NodeInfo(Id id, InetSocketAddress addr) {
- if (id == null)
- throw new IllegalArgumentException("Invalid node id: null");
-
- if (addr == null)
- throw new IllegalArgumentException("Invalid socket address: null");
-
+ Objects.requireNonNull(id, "id");
+ Objects.requireNonNull(addr, "addr");
if (addr.getPort() <= 0 || addr.getPort() > 65535)
throw new IllegalArgumentException("Invalid port: " + addr.getPort());
@@ -65,12 +61,8 @@ public NodeInfo(Id id, InetSocketAddress addr) {
* @param port the node port number.
*/
public NodeInfo(Id id, InetAddress addr, int port) {
- if (id == null)
- throw new IllegalArgumentException("Invalid node id: null");
-
- if (addr == null)
- throw new IllegalArgumentException("Invalid socket address: null");
-
+ Objects.requireNonNull(id, "id");
+ Objects.requireNonNull(addr, "addr");
if (port <= 0 || port > 65535)
throw new IllegalArgumentException("Invalid port: " + port);
@@ -86,12 +78,8 @@ public NodeInfo(Id id, InetAddress addr, int port) {
* @param port the node port number.
*/
public NodeInfo(Id id, String host, int port) {
- if (id == null)
- throw new IllegalArgumentException("Invalid node id: null");
-
- if (host == null)
- throw new IllegalArgumentException("Invalid socket address: null");
-
+ Objects.requireNonNull(id, "id");
+ Objects.requireNonNull(host, "host");
if (port <= 0 || port > 65535)
throw new IllegalArgumentException("Invalid port: " + port);
@@ -107,10 +95,8 @@ public NodeInfo(Id id, String host, int port) {
* @param port the node port number.
*/
public NodeInfo(Id id, byte[] addr, int port) {
- if (id == null)
- throw new IllegalArgumentException("Invalid node id: null");
- if (addr == null)
- throw new IllegalArgumentException("Invalid socket address: null");
+ Objects.requireNonNull(id, "id");
+ Objects.requireNonNull(addr, "addr");
if (port <= 0 || port > 65535)
throw new IllegalArgumentException("Invalid port: " + port);
@@ -129,8 +115,7 @@ public NodeInfo(Id id, byte[] addr, int port) {
* @param ni another node info object.
*/
protected NodeInfo(NodeInfo ni) {
- if (ni == null)
- throw new IllegalArgumentException("Invalid node info: null");
+ Objects.requireNonNull(ni, "ni");
this.id = ni.id;
this.addr = ni.addr;
@@ -202,10 +187,12 @@ public int getVersion() {
}
/**
- * Checks if the node information is identical with the other one.
+ * Checks whether this node info conflicts with another, i.e. they share the same id
+ * or the same socket address. This is a partial match used to detect identity/address
+ * collisions, not full equality (see {@link #equals(Object)}).
*
* @param other another node info object to check
- * @return true if the other node info object is identical with this, false otherwise.
+ * @return true if this and {@code other} share the same id or the same address, false otherwise.
*/
public boolean matches(NodeInfo other) {
if (other != null)
@@ -216,7 +203,7 @@ public boolean matches(NodeInfo other) {
@Override
public int hashCode() {
- return 0x6030A + Objects.hash(id, addr, version);
+ return 0x6030A + Objects.hash(id, addr);
}
@Override
diff --git a/api/src/main/java/io/bosonnetwork/PeerInfo.java b/api/src/main/java/io/bosonnetwork/PeerInfo.java
index aa65c7a4..00e38ac7 100644
--- a/api/src/main/java/io/bosonnetwork/PeerInfo.java
+++ b/api/src/main/java/io/bosonnetwork/PeerInfo.java
@@ -25,7 +25,6 @@
import static java.nio.charset.StandardCharsets.UTF_8;
-import java.nio.ByteBuffer;
import java.security.MessageDigest;
import java.text.Normalizer;
import java.util.Arrays;
@@ -37,8 +36,9 @@
import io.bosonnetwork.crypto.Hash;
import io.bosonnetwork.crypto.Random;
import io.bosonnetwork.crypto.Signature;
-import io.bosonnetwork.utils.Hex;
import io.bosonnetwork.json.Json;
+import io.bosonnetwork.utils.Bytes;
+import io.bosonnetwork.utils.Hex;
/**
* PeerInfo describes the service information published over the Boson DHT network.
@@ -65,7 +65,7 @@
public class PeerInfo {
/** The number of bytes in the nonce. */
- public static int NONCE_BYTES = 24;
+ public static final int NONCE_BYTES = 24;
/** Attribute key to omit the peer ID in the peer info used in JsonContext. */
public static final Object ATTRIBUTE_OMIT_PEER_ID = new Object();
@@ -102,15 +102,15 @@ public class PeerInfo {
private PeerInfo(Id peerId, byte[] privateKey, byte[] nonce, int sequenceNumber, Id nodeId, byte[] nodeSig,
byte[] signature, long fingerprint, String endpoint, byte[] extraData) {
this.publicKey = peerId;
- this.privateKey = privateKey;
- this.nonce = nonce;
+ this.privateKey = privateKey == null ? null : privateKey.clone();
+ this.nonce = nonce == null ? null : nonce.clone();
this.sequenceNumber = sequenceNumber;
this.nodeId = nodeId;
- this.nodeSig = nodeSig;
- this.signature = signature;
+ this.nodeSig = nodeSig == null ? null : nodeSig.clone();
+ this.signature = signature == null ? null : signature.clone();
this.fingerprint = fingerprint;
this.endpoint = endpoint;
- this.extraData = extraData;
+ this.extraData = extraData == null ? null : extraData.clone();
}
/**
@@ -149,14 +149,16 @@ public static PeerInfo of(Id peerId, byte[] nonce, int sequenceNumber, Id nodeId
*/
public static PeerInfo of(Id peerId, byte[] privateKey, byte[] nonce, int sequenceNumber, Id nodeId, byte[] nodeSig,
byte[] signature, long fingerprint, String endpoint, byte[] extraData) {
- if (peerId == null)
- throw new IllegalArgumentException("Invalid peer id: must not be null");
+ Objects.requireNonNull(peerId, "peerId");
+ Objects.requireNonNull(nonce, "nonce");
+ Objects.requireNonNull(signature, "signature");
+ Objects.requireNonNull(endpoint, "endpoint");
// noinspection DuplicatedCode
if (privateKey != null && privateKey.length != Signature.PrivateKey.BYTES)
throw new IllegalArgumentException("Invalid private key: incorrect length");
- if (nonce == null || nonce.length != NONCE_BYTES)
+ if (nonce.length != NONCE_BYTES)
throw new IllegalArgumentException("Invalid nonce: must be exactly NONCE_BYTES (24 bytes)");
if (sequenceNumber < 0)
@@ -170,11 +172,11 @@ public static PeerInfo of(Id peerId, byte[] privateKey, byte[] nonce, int sequen
throw new IllegalArgumentException("Invalid node signature: must be null when nodeId is null");
}
- if (signature == null || signature.length != Signature.BYTES)
+ if (signature.length != Signature.BYTES)
throw new IllegalArgumentException("Invalid signature: incorrect length");
- if (endpoint == null || endpoint.isEmpty())
- throw new IllegalArgumentException("Invalid endpoint: must not be null or empty");
+ if (endpoint.isEmpty())
+ throw new IllegalArgumentException("Invalid endpoint: must not be empty");
endpoint = Normalizer.normalize(endpoint, Normalizer.Form.NFC);
@@ -212,7 +214,7 @@ private static PeerInfo create(Identity peer, byte[] privateKey, Identity node,
byte[] nodeSig;
if (node != null) {
nodeId = node.getId();
- byte[] digest = Hash.sha256(publicKey.bytes(), nodeId.bytes(), nonce);
+ byte[] digest = Hash.sha256(publicKey.bytesUnsafe(), nodeId.bytesUnsafe(), nonce);
nodeSig = node.sign(digest);
} else {
nodeId = null;
@@ -250,7 +252,7 @@ public boolean hasPrivateKey() {
* @return The private key.
*/
public byte[] getPrivateKey() {
- return privateKey;
+ return privateKey == null ? null : privateKey.clone();
}
/**
@@ -259,7 +261,7 @@ public byte[] getPrivateKey() {
* @return the nonce
*/
public byte[] getNonce() {
- return nonce;
+ return nonce == null ? null : nonce.clone();
}
/**
@@ -286,7 +288,7 @@ public Id getNodeId() {
* @return the node signature
*/
public byte[] getNodeSignature() {
- return nodeSig;
+ return nodeSig == null ? null : nodeSig.clone();
}
/**
@@ -311,7 +313,7 @@ public boolean isAuthenticated() {
* @return The signature.
*/
public byte[] getSignature() {
- return signature;
+ return signature == null ? null : signature.clone();
}
/**
@@ -347,7 +349,7 @@ public boolean hasExtra() {
* @return the extra data
*/
public byte[] getExtraData() {
- return extraData;
+ return extraData == null ? null : extraData.clone();
}
/**
@@ -379,14 +381,14 @@ public Map For mutable values, this verifies the signature against the computed digest.
+ *
+ * For mutable values, this verifies the signature against the computed digest.
* For immutable values, this verifies that the id matches the hash of the data.
*
* @return {@code true} if the value is valid, {@code false} otherwise.
@@ -621,7 +629,7 @@ private enum Type { IMMUTABLE, SIGNED, ENCRYPTED }
private Identity identity = null;
private boolean keepPrivateKey;
- Id recipient = null;
+ private Id recipient = null;
private int sequenceNumber = 0;
private byte[] data = null;
diff --git a/api/src/main/java/io/bosonnetwork/Version.java b/api/src/main/java/io/bosonnetwork/Version.java
index 8e5b5af1..f200967a 100644
--- a/api/src/main/java/io/bosonnetwork/Version.java
+++ b/api/src/main/java/io/bosonnetwork/Version.java
@@ -23,7 +23,9 @@
package io.bosonnetwork;
+import java.nio.charset.StandardCharsets;
import java.util.Map;
+import java.util.Objects;
/**
* A representation of a version information for a Boson node. A version information
@@ -37,6 +39,9 @@ public final class Version {
"MK", "Meerkat" // Native regular node
);
+ private Version() {
+ }
+
/**
* Build a version from the software name and version number.
*
@@ -45,12 +50,14 @@ public final class Version {
* @return an integer that represent the version information
*/
public static int build(String name, int version) {
- byte[] nameBytes = name.getBytes();
+ Objects.requireNonNull(name, "name");
+ byte[] nameBytes = name.getBytes(StandardCharsets.US_ASCII);
+ if (nameBytes.length < 2)
+ throw new IllegalArgumentException("Invalid name: must be at least 2 characters");
return Byte.toUnsignedInt(nameBytes[0]) << 24 |
Byte.toUnsignedInt(nameBytes[1]) << 16 |
- (version & 0x0000FF00) |
- (version & 0x000000FF);
+ (version & 0x0000FFFF);
}
/**
@@ -64,9 +71,8 @@ public static String toString(int version) {
return VERSION_NOT_AVAILABLE;
String n = new String(new byte[] { (byte)(version >>> 24),
- (byte)((version & 0x00ff0000) >>> 16) });
- String v = Integer.toString((version & 0x0000ff00) |
- (version & 0x000000ff));
+ (byte)((version & 0x00ff0000) >>> 16) }, StandardCharsets.US_ASCII);
+ String v = Integer.toString(version & 0x0000ffff);
return names.getOrDefault(n, n) + "/" + v;
}
diff --git a/api/src/main/java/io/bosonnetwork/crypto/CachedCryptoIdentity.java b/api/src/main/java/io/bosonnetwork/crypto/CachedCryptoIdentity.java
index 209b9c40..c5817f82 100644
--- a/api/src/main/java/io/bosonnetwork/crypto/CachedCryptoIdentity.java
+++ b/api/src/main/java/io/bosonnetwork/crypto/CachedCryptoIdentity.java
@@ -1,3 +1,25 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
package io.bosonnetwork.crypto;
import java.util.Objects;
@@ -90,27 +112,37 @@ public void clearCache() {
cryptoContexts.invalidateAll();
}
+ /**
+ * Destroys this identity, first closing and clearing any cached {@link CryptoContext}
+ * instances (each holds a native shared key) and then wiping the underlying key material.
+ */
+ @Override
+ public void destroy() {
+ clearCache();
+ super.destroy();
+ }
+
private CryptoContext getContext(Id id) throws CryptoException {
return cryptoContexts != null ? cryptoContexts.get(id) : super.createCryptoContext(id);
}
/**
- * Performs one-shot encryption of the given data for the specified receiver.
+ * Performs one-shot encryption of the given data for the specified recipient.
*
- * This operation leverages a cached {@link CryptoContext} instance associated with the receiver,
+ * This operation leverages a cached {@link CryptoContext} instance associated with the recipient,
* reducing the overhead of repeatedly computing cryptographic contexts.
*
- * @param receiver the receiver's {@link Id}; must not be {@code null}
+ * @param recipient the recipient'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 receiver} or {@code data} is {@code null}
+ * @throws NullPointerException if {@code recipient} or {@code data} is {@code null}
* @throws CryptoException if an error occurs during encryption
*/
@Override
- public byte[] encrypt(Id receiver, byte[] data) throws CryptoException {
- Objects.requireNonNull(receiver, "receiver");
+ public byte[] encrypt(Id recipient, byte[] data) throws CryptoException {
+ Objects.requireNonNull(recipient, "recipient");
Objects.requireNonNull(data, "data");
- return getContext(receiver).encrypt(data);
+ return getContext(recipient).encrypt(data);
}
/**
diff --git a/api/src/main/java/io/bosonnetwork/crypto/CryptoBox.java b/api/src/main/java/io/bosonnetwork/crypto/CryptoBox.java
index 23ec2547..0fb9d689 100644
--- a/api/src/main/java/io/bosonnetwork/crypto/CryptoBox.java
+++ b/api/src/main/java/io/bosonnetwork/crypto/CryptoBox.java
@@ -41,6 +41,7 @@ public class CryptoBox implements AutoCloseable, Destroyable {
public static final int MAC_BYTES = 16;
private final Box box;
+ private boolean destroyed = false;
/**
* The crypto box public key object.
@@ -86,7 +87,7 @@ Box.PublicKey raw() {
}
/**
- * Get the raw bytes of this key.
+ * Returns the raw bytes of this key.
*
* @return the raw bytes of this key.
*/
@@ -94,7 +95,7 @@ public byte[] bytes() {
if (bytes == null)
bytes = key.bytesArray();
- return bytes;
+ return bytes.clone();
}
@Override
@@ -186,15 +187,15 @@ Box.SecretKey raw() {
}
/**
- * Get the raw bytes of this key.
+ * Returns the raw bytes of this secret key.
*
- * @return the raw bytes of this key.
+ * @return the raw bytes of this secret key.
*/
public byte[] bytes() {
if (bytes == null)
bytes = key.bytesArray();
- return bytes;
+ return bytes.clone();
}
@Override
@@ -245,7 +246,7 @@ public boolean isDestroyed() {
/**
* The crypto box key pair.
*/
- public static class KeyPair {
+ public static class KeyPair implements Destroyable {
/**
* The seed length in bytes.
*/
@@ -254,6 +255,7 @@ public static class KeyPair {
private final Box.KeyPair keyPair;
private PublicKey pk;
private PrivateKey sk;
+ private boolean destroyed = false;
private KeyPair(Box.KeyPair keyPair) {
this.keyPair = keyPair;
@@ -362,6 +364,28 @@ public boolean equals(Object obj) {
public int hashCode() {
return 0x6030A + keyPair.hashCode();
}
+
+ /**
+ * Destroys this key pair, wiping the underlying public and private key material.
+ */
+ @Override
+ public void destroy() {
+ if (!destroyed) {
+ publicKey().destroy();
+ privateKey().destroy();
+ destroyed = true;
+ }
+ }
+
+ /**
+ * Determine if this key pair has been destroyed.
+ *
+ * @return true if this key pair has been destroyed, false otherwise.
+ */
+ @Override
+ public boolean isDestroyed() {
+ return destroyed;
+ }
}
/**
@@ -534,7 +558,7 @@ public static byte[] encryptSealed(byte[] message, PublicKey receiver) {
public byte[] decrypt(byte[] cipher, Nonce nonce) throws CryptoException {
byte[] plain = box.decrypt(cipher, nonce.raw());
if (plain == null)
- throw new CryptoException("crypto_box_open_easy_afternm: failed");
+ throw new CryptoException("Decryption failed: invalid ciphertext or authentication failure");
return plain;
}
@@ -552,7 +576,7 @@ public byte[] decrypt(byte[] cipher, Nonce nonce) throws CryptoException {
public static byte[] decrypt(byte[] cipher, PublicKey sender, PrivateKey receiver, Nonce nonce) throws CryptoException {
byte[] plain = Box.decrypt(cipher, sender.raw(), receiver.raw(), nonce.raw());
if (plain == null)
- throw new CryptoException("crypto_box_open_easy: failed");
+ throw new CryptoException("Decryption failed: invalid ciphertext or authentication failure");
return plain;
}
@@ -569,7 +593,7 @@ public static byte[] decrypt(byte[] cipher, PublicKey sender, PrivateKey receive
public static byte[] decryptSealed(byte[] cipher, PublicKey pk, PrivateKey sk) throws CryptoException {
byte[] plain = Box.decryptSealed(cipher, pk.raw(), sk.raw());
if (plain == null)
- throw new CryptoException("crypto_box_seal_open: failed");
+ throw new CryptoException("Sealed-box decryption failed: invalid ciphertext or authentication failure");
return plain;
}
@@ -581,13 +605,15 @@ public void close() {
@Override
public void destroy() {
- box.close();
+ if (!destroyed) {
+ box.close();
+ destroyed = true;
+ }
}
@Override
public boolean isDestroyed() {
- // always return false as the inner box not exposed the isDestroyed() method
- return false;
+ return destroyed;
}
static {
diff --git a/api/src/main/java/io/bosonnetwork/crypto/CryptoException.java b/api/src/main/java/io/bosonnetwork/crypto/CryptoException.java
index dbb2241c..d4d42a1a 100644
--- a/api/src/main/java/io/bosonnetwork/crypto/CryptoException.java
+++ b/api/src/main/java/io/bosonnetwork/crypto/CryptoException.java
@@ -1,3 +1,25 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
package io.bosonnetwork.crypto;
import io.bosonnetwork.BosonException;
diff --git a/api/src/main/java/io/bosonnetwork/crypto/CryptoIdentity.java b/api/src/main/java/io/bosonnetwork/crypto/CryptoIdentity.java
index d93d716f..2582c09a 100644
--- a/api/src/main/java/io/bosonnetwork/crypto/CryptoIdentity.java
+++ b/api/src/main/java/io/bosonnetwork/crypto/CryptoIdentity.java
@@ -1,7 +1,30 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
package io.bosonnetwork.crypto;
import java.util.Arrays;
import java.util.Objects;
+import javax.security.auth.Destroyable;
import org.apache.tuweni.crypto.sodium.SodiumException;
@@ -14,10 +37,11 @@
* Provides functionality for signing, verifying, encrypting, and decrypting data
* using signature and encryption key pairs.
*/
-public class CryptoIdentity implements Identity {
+public class CryptoIdentity implements Identity, Destroyable {
private final Id id;
private final Signature.KeyPair keyPair;
private final CryptoBox.KeyPair encryptionKeyPair;
+ private boolean destroyed = false;
/**
* Constructs a new {@code CryptoIdentity} with a randomly generated signature key pair.
@@ -77,14 +101,14 @@ public boolean verify(byte[] data, byte[] signature) {
* {@inheritDoc}
*/
@Override
- public byte[] encrypt(Id receiver, byte[] data) throws CryptoException {
- Objects.requireNonNull(receiver, "receiver");
+ public byte[] encrypt(Id recipient, byte[] data) throws CryptoException {
+ Objects.requireNonNull(recipient, "recipient");
Objects.requireNonNull(data, "data");
try {
// TODO: how to avoid the memory copy?!
CryptoBox.Nonce nonce = CryptoBox.Nonce.random();
- CryptoBox.PublicKey pk = receiver.toEncryptionKey();
+ CryptoBox.PublicKey pk = recipient.toEncryptionKey();
CryptoBox.PrivateKey sk = encryptionKeyPair.privateKey();
byte[] cipher = CryptoBox.encrypt(data, pk, sk, nonce);
@@ -101,14 +125,14 @@ public byte[] encrypt(Id receiver, byte[] data) throws CryptoException {
* {@inheritDoc}
*/
@Override
- public byte[] encrypt(Id receiver, byte[] nonce, byte[] data) throws CryptoException {
- Objects.requireNonNull(receiver, "receiver");
+ public byte[] encrypt(Id recipient, byte[] nonce, byte[] data) throws CryptoException {
+ Objects.requireNonNull(recipient, "recipient");
Objects.requireNonNull(nonce, "nonce");
Objects.requireNonNull(data, "data");
try {
CryptoBox.Nonce n = CryptoBox.Nonce.fromBytes(nonce);
- CryptoBox.PublicKey pk = receiver.toEncryptionKey();
+ CryptoBox.PublicKey pk = recipient.toEncryptionKey();
CryptoBox.PrivateKey sk = encryptionKeyPair.privateKey();
return CryptoBox.encrypt(data, pk, sk, n);
} catch (SodiumException e) {
@@ -132,10 +156,6 @@ public byte[] decrypt(Id sender, byte[] data) throws CryptoException {
byte[] n = Arrays.copyOfRange(data, 0, CryptoBox.Nonce.BYTES);
CryptoBox.Nonce nonce = CryptoBox.Nonce.fromBytes(n);
- //if (lastPeerNonce != null && nonce.equals(lastPeerNonce))
- // throw new CryptoException("Duplicated nonce");
-
- // lastPeerNonce = nonce;
CryptoBox.PublicKey pk = sender.toEncryptionKey();
CryptoBox.PrivateKey sk = encryptionKeyPair.privateKey();
byte[] cipher = Arrays.copyOfRange(data, CryptoBox.Nonce.BYTES, data.length);
@@ -160,10 +180,6 @@ public byte[] decrypt(Id sender, byte[] nonce, byte[] data) throws CryptoExcepti
try {
CryptoBox.Nonce n = CryptoBox.Nonce.fromBytes(nonce);
- //if (lastPeerNonce != null && nonce.equals(lastPeerNonce))
- // throw new CryptoException("Duplicated nonce");
-
- // lastPeerNonce = nonce;
CryptoBox.PublicKey pk = sender.toEncryptionKey();
CryptoBox.PrivateKey sk = encryptionKeyPair.privateKey();
return CryptoBox.decrypt(data, pk, sk, n);
@@ -221,4 +237,27 @@ public boolean equals(Object o) {
return false;
}
+
+ /**
+ * Destroys this identity, wiping the underlying signature and encryption key material.
+ * After this call the identity must not be used for further cryptographic operations.
+ */
+ @Override
+ public void destroy() {
+ if (!destroyed) {
+ keyPair.destroy();
+ encryptionKeyPair.destroy();
+ destroyed = true;
+ }
+ }
+
+ /**
+ * Determine if this identity has been destroyed.
+ *
+ * @return true if this identity has been destroyed, false otherwise.
+ */
+ @Override
+ public boolean isDestroyed() {
+ return destroyed;
+ }
}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/crypto/CryptoUtil.java b/api/src/main/java/io/bosonnetwork/crypto/CryptoUtil.java
index 7eb77a10..98460255 100644
--- a/api/src/main/java/io/bosonnetwork/crypto/CryptoUtil.java
+++ b/api/src/main/java/io/bosonnetwork/crypto/CryptoUtil.java
@@ -43,15 +43,16 @@
import java.security.spec.PKCS8EncodedKeySpec;
import java.text.SimpleDateFormat;
import java.time.Instant;
+import java.time.ZoneOffset;
import java.time.temporal.ChronoUnit;
import java.util.Base64;
import java.util.Date;
-import java.util.Random;
import java.util.TimeZone;
import io.vertx.core.buffer.Buffer;
import io.vertx.core.net.PfxOptions;
+import io.bosonnetwork.BosonException;
import io.bosonnetwork.utils.Base58;
/**
@@ -164,7 +165,7 @@ private static byte[] encodeTBS(BigInteger serial, String cn, Date notBefore, Da
tbs.addInt(serial);
tbs.addSeq(new DerBuilder().addOid("1.3.101.112")); // Algorithm: Ed25519
tbs.addSeq(new DerBuilder().addSet(new DerBuilder().addSeq(new DerBuilder().addOid("2.5.4.3").addPrintableString(cn)))); // Issuer
- tbs.addSeq(new DerBuilder().addUtcTime(notBefore).addUtcTime(notAfter)); // Validity
+ tbs.addSeq(new DerBuilder().addTime(notBefore).addTime(notAfter)); // Validity
tbs.addSeq(new DerBuilder().addSet(new DerBuilder().addSeq(new DerBuilder().addOid("2.5.4.3").addPrintableString(cn)))); // Subject
tbs.addSeq(new DerBuilder().addSeq(new DerBuilder().addOid("1.3.101.112")).addBitString(pubKey)); // SubjectPublicKeyInfo
@@ -262,10 +263,18 @@ public DerBuilder addPrintableString(String s) throws IOException {
return addTag((byte) 0x13, s.getBytes(StandardCharsets.US_ASCII));
}
- public DerBuilder addUtcTime(Date d) throws IOException {
- SimpleDateFormat sdf = new SimpleDateFormat("yyMMddHHmmss'Z'");
- sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
- return addTag((byte) 0x17, sdf.format(d).getBytes(StandardCharsets.US_ASCII));
+ // RFC 5280: encode dates before 2050 as UTCTime, and 2050 or later as GeneralizedTime.
+ public DerBuilder addTime(Date d) throws IOException {
+ int year = d.toInstant().atZone(ZoneOffset.UTC).getYear();
+ if (year < 2050) {
+ SimpleDateFormat sdf = new SimpleDateFormat("yyMMddHHmmss'Z'");
+ sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
+ return addTag((byte) 0x17, sdf.format(d).getBytes(StandardCharsets.US_ASCII)); // UTCTime
+ } else {
+ SimpleDateFormat sdf = new SimpleDateFormat("yyyyMMddHHmmss'Z'");
+ sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
+ return addTag((byte) 0x18, sdf.format(d).getBytes(StandardCharsets.US_ASCII)); // GeneralizedTime
+ }
}
public DerBuilder addBitString(byte[] b) throws IOException {
@@ -327,7 +336,7 @@ public static String randomPassword(int length) {
String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()_-+=<>?/|";
StringBuilder sb = new StringBuilder(length);
- java.util.Random random = new Random();
+ SecureRandom random = new SecureRandom();
for (int i = 0; i < length; i++) {
int index = random.nextInt(characters.length());
sb.append(characters.charAt(index));
@@ -405,7 +414,7 @@ public static PfxOptions pfxOptionsFromCertAndPrivateKey(PemCertificateAndKey ce
/**
* Exception thrown when an error occurs during key conversion or certificate generation.
*/
- public static class KeyConvertException extends Exception {
+ public static class KeyConvertException extends BosonException {
private static final long serialVersionUID = -5975318365528633648L;
/**
diff --git a/api/src/main/java/io/bosonnetwork/crypto/Hash.java b/api/src/main/java/io/bosonnetwork/crypto/Hash.java
index e713490a..b5b4652a 100644
--- a/api/src/main/java/io/bosonnetwork/crypto/Hash.java
+++ b/api/src/main/java/io/bosonnetwork/crypto/Hash.java
@@ -1,3 +1,25 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
package io.bosonnetwork.crypto;
import java.security.MessageDigest;
@@ -6,8 +28,15 @@
/**
* Utility class providing methods for generating SHA-256 and MD5 hashes.
* Supports hashing single or multiple byte arrays, as well as performing double SHA-256 hashing.
+ *
+ * Security note: MD5 is cryptographically broken (not collision-resistant) and
+ * is provided only for non-cryptographic uses such as legacy checksums and interop. Never use the
+ * {@code md5*} methods for security-sensitive purposes; use the SHA-256 methods instead.
*/
public class Hash {
+ private Hash() {
+ }
+
/**
* Create a new SHA256 message digest object.
*
@@ -116,8 +145,11 @@ public static byte[] sha256Twice(byte[]... inputs) {
/**
* Create a new MD5 message digest object.
+ *
+ * Security note: MD5 is not collision-resistant; use only for
+ * non-cryptographic purposes. Prefer {@link #sha256()} for anything security-related.
*
- * @return the current thread's MD5 {@code MessageDigest}
+ * @return a new MD5 {@code MessageDigest} instance
*/
public static MessageDigest md5() {
try {
diff --git a/api/src/main/java/io/bosonnetwork/crypto/HybridTrustManager.java b/api/src/main/java/io/bosonnetwork/crypto/HybridTrustManager.java
index ac173cfc..dc751cad 100644
--- a/api/src/main/java/io/bosonnetwork/crypto/HybridTrustManager.java
+++ b/api/src/main/java/io/bosonnetwork/crypto/HybridTrustManager.java
@@ -57,7 +57,7 @@ public class HybridTrustManager implements X509TrustManager {
public HybridTrustManager(String expectedCn, byte[] expectedPublicKey) {
this.defaultTrustManager = getDefaultTrustManager();
this.expectedCn = expectedCn;
- this.expectedPublicKey = expectedPublicKey;
+ this.expectedPublicKey = expectedPublicKey == null ? null : expectedPublicKey.clone();
}
private static X509TrustManager getDefaultTrustManager() {
@@ -90,6 +90,35 @@ private static X509TrustManager getDefaultTrustManager() {
*/
@Override
public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException {
+ checkTrusted(chain, authType, false);
+ }
+
+ /**
+ * Checks whether the provided client certificate chain can be trusted.
+ *
+ * If the certificate is self-signed, it is validated against the expected CN and public key
+ * (same pinning as {@link #checkServerTrusted}). Otherwise, the validation is delegated to the
+ * system default trust manager. This implementation delegates the check to the system default trust manager.
+ * The string is hashed with SHA-256 and the 32-byte digest is folded down to the 8 bytes
+ * required by {@link KeyDerivation#contextLength()}.
+ *
+ * Note: the 8-byte context is a lossy reduction (libsodium's fixed context
+ * size), so distinct context strings can still collide and, for the same sub-key id, derive the
+ * same key. Use distinct sub-key ids when strong domain separation is required.
+ *
+ * @param context the context string; must not be null or empty
+ * @return the 8-byte derivation context
+ */
+ private static byte[] deriveContextBytes(String context) {
+ Objects.requireNonNull(context, "context");
+ if (context.isEmpty())
+ throw new IllegalArgumentException("context must not be empty");
+
+ final int len = KeyDerivation.contextLength(); // 8 bytes
+ byte[] contextBytes = new byte[len];
+ try {
+ MessageDigest sha = MessageDigest.getInstance("SHA-256");
+ byte[] hashBytes = sha.digest(context.getBytes(StandardCharsets.UTF_8));
+ for (int i = 0; i < hashBytes.length; i++)
+ contextBytes[i % len] += hashBytes[i];
+ } catch (NoSuchAlgorithmException e) {
+ throw new RuntimeException(e);
+ }
+ return contextBytes;
+ }
+
/**
* Signs a message with a given key.
*
diff --git a/api/src/main/java/io/bosonnetwork/crypto/package-info.java b/api/src/main/java/io/bosonnetwork/crypto/package-info.java
index 06b96182..d16d6209 100644
--- a/api/src/main/java/io/bosonnetwork/crypto/package-info.java
+++ b/api/src/main/java/io/bosonnetwork/crypto/package-info.java
@@ -22,7 +22,24 @@
*/
/**
- * The Ed25591 and Curve25519 crypto wrappers based on libsodium. See
- * https://www.libsodium.org/
+ * Cryptographic primitives for Boson — Ed25519 signatures and Curve25519 key exchange / encryption,
+ * wrapping libsodium.
+ *
+ * Boson uses libsodium-style 64-byte private keys (32-byte seed concatenated with the 32-byte
+ * public key). Holders of secret key material expose explicit {@code destroy()}/{@code close()}
+ * methods; failures are reported as {@link io.bosonnetwork.crypto.CryptoException}.
*/
package io.bosonnetwork.crypto;
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/cwt/Algorithm.java b/api/src/main/java/io/bosonnetwork/cwt/Algorithm.java
index b765eba3..c7ca1bc6 100644
--- a/api/src/main/java/io/bosonnetwork/cwt/Algorithm.java
+++ b/api/src/main/java/io/bosonnetwork/cwt/Algorithm.java
@@ -23,24 +23,28 @@
package io.bosonnetwork.cwt;
/**
- * Enumeration of cryptographic algorithms supported by the CWT implementation.
- * The integer values correspond to the algorithm identifiers defined in RFC 8152.
+ * Enumeration of COSE algorithm identifiers (RFC 8152) referenced by this package.
+ *
+ * Note: {@link SignedCwt} strictly enforces {@link #EDDSA} (Ed25519); it is the only
+ * algorithm accepted when signing or verifying. The {@code ES256}/{@code ES384}/{@code ES512}
+ * constants are defined for registry completeness and are not supported — a token using
+ * any of them is rejected during parsing.
*/
public enum Algorithm {
/**
- * ECDSA w/ SHA-256
+ * ECDSA w/ SHA-256. Defined for completeness; not supported by {@link SignedCwt}.
*/
ES256(-7),
/**
- * ECDSA w/ SHA-384
+ * ECDSA w/ SHA-384. Defined for completeness; not supported by {@link SignedCwt}.
*/
ES384(-35),
/**
- * ECDSA w/ SHA-512
+ * ECDSA w/ SHA-512. Defined for completeness; not supported by {@link SignedCwt}.
*/
ES512(-36),
/**
- * EdDSA / Ed25519
+ * EdDSA / Ed25519 — the only algorithm supported by {@link SignedCwt}.
*/
EDDSA(-8);
diff --git a/api/src/main/java/io/bosonnetwork/cwt/Claim.java b/api/src/main/java/io/bosonnetwork/cwt/Claim.java
index 421e0444..74044fd1 100644
--- a/api/src/main/java/io/bosonnetwork/cwt/Claim.java
+++ b/api/src/main/java/io/bosonnetwork/cwt/Claim.java
@@ -58,7 +58,7 @@ public enum Claim {
*/
ISSUED_AT(6),
/**
- * cti (CWT ID) Claim。
+ * cti (CWT ID) Claim
*/
CWT_ID(7),
@@ -103,9 +103,14 @@ public int getValue() {
/**
* Retrieves the Claim enumeration corresponding to the given integer value.
+ *
+ * Unlike {@link Header#valueOf(int)} and {@link Algorithm#valueOf(int)}, which throw on an
+ * unknown value, this method is deliberately lenient: any unrecognized key maps to
+ * {@link #APPLICATION_DEFINED}, since the CWT claim registry is open and tokens may legitimately
+ * carry application- or future-defined claims.
*
* @param value the integer value of the claim.
- * @return the corresponding Claim enumeration.
+ * @return the corresponding Claim enumeration, or {@link #APPLICATION_DEFINED} if unknown.
*/
public static Claim valueOf(int value) {
return switch (value) {
diff --git a/api/src/main/java/io/bosonnetwork/cwt/SignedCwt.java b/api/src/main/java/io/bosonnetwork/cwt/SignedCwt.java
index e4018f96..411d6d23 100644
--- a/api/src/main/java/io/bosonnetwork/cwt/SignedCwt.java
+++ b/api/src/main/java/io/bosonnetwork/cwt/SignedCwt.java
@@ -50,6 +50,13 @@
* cryptographic {@link Identity} and {@link Id} system, ensuring that the {@code "iss"} (Issuer)
* claim is intrinsically bound to the issuer's public key identifier.
*
+ * Security — the issuer is self-asserted: a token is verified against the Ed25519 public
+ * key carried in its own {@code "iss"} claim. A successful {@link #parse(byte[]) parse} therefore
+ * proves only that the token was signed by the holder of the key it names as issuer — it does
+ * not establish that this issuer is trusted. Callers MUST pin trust by configuring
+ * {@link Parser#requireIssuer(Id)} or by validating the {@code "iss"} claim against an allow-list
+ * after parsing. A valid signature alone is not authentication.
+ *
* References:
*
+ * The map itself is read-only, but {@code byte[]} claim values are returned by reference and
+ * must not be mutated by the caller.
*
- * @return a map of claims.
+ * @return an unmodifiable view of the claims.
*/
public Map
+ * Security: the signature is verified against the public key in the token's own
+ * {@code "iss"} claim (self-asserted issuer). Unless {@link #requireIssuer(Id)} was
+ * configured, a successful parse does not authenticate the issuer — validate {@code "iss"}
+ * against a trust anchor yourself. See the {@link SignedCwt class documentation}.
+ *
* @param coseBytes the raw CBOR bytes of the CWT.
* @return the parsed and verified {@code SignedCwt} object.
* @throws CwtException if parsing, structural validation, or cryptographic verification fails.
@@ -520,7 +529,11 @@ public SignedCwt parse(byte[] coseBytes) throws CwtException {
* but conveniently to check manually.
*/
Objects.requireNonNull(coseBytes);
+ if (coseBytes.length == 0)
+ throw new InvalidCborTagException("Empty token");
+ // Only the canonical single-byte encoding of CBOR tag 18 (0xD2) is accepted, matching
+ // what build() emits. Multi-byte tag encodings of the same value are not recognized.
int tag = Byte.toUnsignedInt(coseBytes[0]);
if (tag != COSE_SIGN_1_TAG)
throw new InvalidCborTagException("Unknown CBOR tag: " + tag);
@@ -549,6 +562,13 @@ public SignedCwt parse(byte[] coseBytes) throws CwtException {
if (alg != Algorithm.EDDSA.getValue())
throw new InvalidAlgorithmException("Unsupported algorithm: " + value);
+ // RFC 8152/9052 §3.1: a recipient that does not understand a header listed in "crit"
+ // MUST reject the token. This implementation understands no critical extensions, so the
+ // mere presence of a (non-empty) "crit" header is a rejection.
+ Object crit = protectedHeaders.get(Header.CRIT.getValue());
+ if (crit != null && !(crit instanceof List l && l.isEmpty()))
+ throw new InvalidCoseStructureException("Unsupported critical headers (crit) present");
+
if (!(sign1.get(1) instanceof Map uph))
throw new InvalidCoseStructureException("Unprotected headers should be a map");
@@ -580,7 +600,7 @@ public SignedCwt parse(byte[] coseBytes) throws CwtException {
throw new InvalidIssuerKeyException("Invalid issuer key");
if (expectedIssuer != null) {
- if (!Arrays.equals(issuer, expectedIssuer.bytes()))
+ if (!Arrays.equals(issuer, expectedIssuer.bytesUnsafe()))
throw new InvalidClaimException("Issuer mismatch");
}
@@ -647,7 +667,16 @@ public SignedCwt parse(byte[] coseBytes) throws CwtException {
* @throws CwtException if there is an error during parsing
*/
public SignedCwt parse(String base64Token) throws CwtException {
- return parse(Json.BASE64_DECODER.decode(base64Token));
+ if (base64Token == null)
+ throw new InvalidCoseStructureException("Token cannot be null");
+
+ byte[] coseBytes;
+ try {
+ coseBytes = Json.BASE64_DECODER.decode(base64Token);
+ } catch (IllegalArgumentException e) {
+ throw new InvalidCoseStructureException("Invalid base64 token", e);
+ }
+ return parse(coseBytes);
}
}
@@ -656,7 +685,6 @@ public SignedCwt parse(String base64Token) throws CwtException {
*/
public static class Builder {
private final Identity issuer;
- private long leeway;
private final Map
+ * Security: a token is verified against the public key carried in its own
+ * {@code "iss"} claim (self-asserted issuer), so a successful parse proves only that the holder of
+ * that key signed it — callers must pin trust via
+ * {@link io.bosonnetwork.cwt.SignedCwt.Parser#requireIssuer(io.bosonnetwork.Id)} or validate the
+ * issuer against a trust anchor after parsing.
+ *
+ *
- * Only letters, digits, and underscores are allowed (safe for SQL identifiers).
- * Optionally supports qualified names with a single dot (e.g., "table.column").
- *
* Example:
* Pagination p = Pagination.page(3, 20); // pageIndex=3, pageSize=20
- * p.toSql(); // " OFFSET 40 LIMIT 20"
+ * p.toSql(); // " LIMIT 20 OFFSET 40"
*
+ * These identifiers are interpolated directly into SQL/templates (only bound values are
+ * parameterized), so they must be restricted to safe characters to prevent SQL injection. Used by
+ * the query builders ({@link Filter}, {@link Ordering}) and by schema/configuration handling.
+ */
+public final class SqlSafety {
+ // Letters, digits and underscore; optionally a single qualifying dot (e.g. "table.column").
+ private static final Pattern COLUMN = Pattern.compile("^[A-Za-z_][A-Za-z0-9_]*(?:\\.[A-Za-z_][A-Za-z0-9_]*)?$");
+ // Bind-parameter token: letters, digits and underscore.
+ private static final Pattern PARAM_NAME = Pattern.compile("^[A-Za-z_][A-Za-z0-9_]*$");
+ // Schema name: a lowercase letter followed by up to 31 lowercase letters, digits or underscores.
+ private static final Pattern SCHEMA_NAME = Pattern.compile("^[a-z][a-z0-9_]{0,31}$");
+
+ private SqlSafety() {
+ }
+
+ /**
+ * Validates a SQL column name (optionally qualified, e.g. {@code table.column}) and returns it,
+ * so callers can validate and assign in one expression.
+ *
+ * @param column the column name; must not be null
+ * @return the validated column name
+ * @throws IllegalArgumentException if the column name is null or not a safe identifier
+ */
+ public static String validateColumn(String column) {
+ if (column == null || !COLUMN.matcher(column).matches())
+ throw new IllegalArgumentException("Invalid SQL column name: " + column);
+ return column;
+ }
+
+ /**
+ * Validates a bind-parameter name (the token used inside a {@code #{...}} placeholder) and
+ * returns it, so callers can validate and assign in one expression.
+ *
+ * @param paramName the parameter name; must not be null
+ * @return the validated parameter name
+ * @throws IllegalArgumentException if the parameter name is null or not a safe identifier
+ */
+ public static String validateParamName(String paramName) {
+ if (paramName == null || !PARAM_NAME.matcher(paramName).matches())
+ throw new IllegalArgumentException("Invalid SQL parameter name: " + paramName);
+ return paramName;
+ }
+
+ /**
+ * Validates and normalizes an optional SQL schema name. A {@code null} or empty name is treated
+ * as "no schema" and mapped to {@code null}; any other value must be a valid schema identifier
+ * and is returned unchanged.
+ *
+ * @param schema the schema name, may be {@code null} or empty
+ * @return the validated schema name, or {@code null} if the input was null or empty
+ * @throws IllegalArgumentException if a non-empty schema name is not a safe identifier
+ */
+ public static String validateSchema(String schema) {
+ if (schema == null || schema.isEmpty())
+ return null;
+
+ if (!SCHEMA_NAME.matcher(schema).matches())
+ throw new IllegalArgumentException("Invalid schema name: " + schema);
+
+ return schema;
+ }
+}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/database/VersionedSchema.java b/api/src/main/java/io/bosonnetwork/database/VersionedSchema.java
index 0f6279b3..f23c8752 100644
--- a/api/src/main/java/io/bosonnetwork/database/VersionedSchema.java
+++ b/api/src/main/java/io/bosonnetwork/database/VersionedSchema.java
@@ -22,6 +22,8 @@
package io.bosonnetwork.database;
+import static io.bosonnetwork.database.SqlSafety.validateSchema;
+
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
@@ -31,12 +33,12 @@
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
+import java.util.Locale;
import java.util.function.Function;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import io.vertx.core.Future;
-import io.vertx.core.Promise;
import io.vertx.core.Vertx;
import io.vertx.sqlclient.Row;
import io.vertx.sqlclient.RowSet;
@@ -133,12 +135,6 @@ public Path path() {
@Override
public int compareTo(Migration that) {
- if (this.version == that.version) {
- log.error("Migration check: Migration file version must be unique. File names: {} and {}",
- this.fileName(), that.fileName());
- throw new IllegalStateException("Migration file version must be unique");
- }
-
return Integer.compare(this.version, that.version);
}
}
@@ -176,10 +172,7 @@ public static VersionedSchema init(Vertx vertx, SqlClient client, Path migration
* @return a new {@link VersionedSchema} instance configured for the provided parameters
*/
public static VersionedSchema init(Vertx vertx, SqlClient client, String schema, Path migrationPath) {
- if (schema != null && !schema.matches("[a-z][a-z0-9_]{0,31}"))
- throw new IllegalArgumentException("Invalid schema name");
-
- return new VersionedSchema(vertx, client, schema, migrationPath);
+ return new VersionedSchema(vertx, client, validateSchema(schema), migrationPath);
}
/**
@@ -193,9 +186,13 @@ public SqlClient getClient() {
}
/**
- * Returns the last successfully applied schema version, if any.
+ * Returns the last successfully applied schema version.
+ *
+ * Before any migration has been applied (or recorded), this returns the empty sentinel version
+ * (version {@code 0}, with a {@code null} {@link SchemaVersion#hash()}) rather than {@code null}.
+ * Use {@code getCurrentVersion().version() == 0} to detect the "no migrations applied" state.
*
- * @return the current version or {@code null} if none recorded
+ * @return the current schema version; never {@code null}
*/
public SchemaVersion getCurrentVersion() {
return currentVersion;
@@ -217,6 +214,11 @@ public SchemaVersion getCurrentVersion() {
* If an already-applied migration differs in version or checksum,
* the migration process fails immediately. Concurrency: this is not designed to run concurrently against the same database from
+ * multiple instances. The {@code version} primary key prevents history corruption, but a losing
+ * concurrent runner may fail with a duplicate-key error. Run migrations from a single instance,
+ * or guard the call with an external lock.
+ * Used by the W3C adapter ({@link DIDDocument.CardView}) at sign time to build the bytes the
+ * signature will cover. {@code signedAt} must be set before signing because it is part of the
+ * signed data.
*
- * @param id the DID identifier
+ * @param id the DID identifier (required)
* @param credentials list of credentials (maybe null or empty)
* @param services list of services (maybe null or empty)
+ * @param signedAt the signing timestamp to embed
*/
- protected Card(Id id, List
+ * Note: {@code signedAt} is metadata and is not covered by the signature, so it is not
+ * cryptographically authenticated; do not rely on it for security decisions.
*
* @return the signature timestamp, or null if unsigned
*/
@@ -287,7 +296,7 @@ public Date getSignedAt() {
* @return the signature bytes, or null if unsigned
*/
public byte[] getSignature() {
- return signature;
+ return signature == null ? null : signature.clone();
}
/**
@@ -328,9 +337,11 @@ public void validate() throws InvalidSignatureException {
* @return byte array representing the signing data
*/
protected byte[] getSignData() {
- if (signature != null) // already signed
- return new Card(this, null, null).toBytes();
- else // unsigned
+ if (signature != null) // already signed
+ // Rebuild the bytes that were signed: {id, c, s, sat} (signature omitted).
+ // signedAt is part of the signed data so that the signing timestamp is authenticated.
+ return new Card(this, null).toBytes();
+ else // unsigned
return toBytes();
}
@@ -512,7 +523,7 @@ protected Service(String id, String type, String endpoint, Map
+ * Note: {@code signedAt} is metadata and is not covered by the signature (the signed
+ * data excludes it), so it is not cryptographically authenticated. The credential's validity
+ * window ({@link #getValidFrom()}/{@link #getValidUntil()}) is signed.
*
* @return Signed at date
*/
@@ -305,17 +308,16 @@ public Date getSignedAt() {
* @return Signature byte array
*/
public byte[] getSignature() {
- return signature;
+ return signature == null ? null : signature.clone();
}
/**
- * Determines if the credential is self-issued.
- * A credential is self-issued if the subject's id is null or equals the issuer.
+ * Determines if the credential is self-issued, i.e. the subject is the same as the issuer.
*
* @return True if self-issued, false otherwise
*/
public boolean selfIssued() {
- return subject.getId() == null || subject.getId().equals(issuer);
+ return Objects.equals(subject.getId(), getIssuer());
}
/**
@@ -378,9 +380,11 @@ public void validate() throws BeforeValidPeriodException, ExpiredException, Inva
* @return Byte array of the data to be signed or verified
*/
protected byte[] getSignData() {
- if (signature != null) // already signed
- return new Credential(this, null,null).toBytes();
- else // unsigned
+ if (signature != null) // already signed
+ // Rebuild the bytes that were signed: everything except the signature itself.
+ // signedAt is part of the signed data so that the signing timestamp is authenticated.
+ return new Credential(this, null).toBytes();
+ else // unsigned
return toBytes();
}
@@ -517,7 +521,7 @@ public static class Subject {
private final Map
+ * Used at sign time by {@link DIDDocumentBuilder} to compute the bytes the signature will
+ * cover. {@code signedAt} must be set so that it is part of the signed data; the resulting
+ * proof's {@code created} value should be the same timestamp.
+ *
+ * @param doc the DIDDocument to wrap
+ * @param signedAt the signing timestamp to embed in the signed bytes
*/
- protected BosonCard(DIDDocument doc, boolean unsigned) {
+ protected CardView(DIDDocument doc, Date signedAt) {
super(doc.id,
doc.credentials.stream().map(VerifiableCredential::toCredential).collect(Collectors.toList()),
doc.services.stream().map(s -> new Card.Service(s.getId(), s.getType(), s.getEndpoint(), s.getProperties()))
- .collect(Collectors.toList()));
+ .collect(Collectors.toList()),
+ signedAt);
this.doc = doc;
}
/**
- * Constructs a BosonCard from an existing Card and DIDDocument.
+ * Constructs a CardView from an existing Card and DIDDocument.
* @param card The Card to wrap
* @param doc The associated DIDDocument
*/
- protected BosonCard(Card card, DIDDocument doc) {
- super(card, card.getSignedAt(), card.getSignature());
+ protected CardView(Card card, DIDDocument doc) {
+ super(card, card.getSignature());
this.doc = doc;
}
@@ -798,7 +810,7 @@ protected Service(String id, String type, String endpoint, Map
- * Implementations of this interface are responsible for securely registering {@code Card} identities
- * and providing mechanisms for their asynchronous resolution. All registration and initialization
- * operations are performed asynchronously using {@link CompletableFuture}, enabling non-blocking workflows.
+ * Persistence semantics are backend-specific. The two typical models:
+ *
- * This interface also exposes a default Distributed Hash Table (DHT) based registry implementation
- * via the static DHTRegistry(...) method.
+ * What this interface intentionally does not include:
+ *
+ * All operations are asynchronous via {@link CompletableFuture}. The built-in DHT-based
+ * implementation is reachable through the {@link #DHTRegistry(Node) DHTRegistry(...)} factories.
*/
public interface Registry {
/**
- * Registers the {@code Card} as Value in the Distributed Hash Table (DHT).
+ * Publishes a signed {@link Card} so it can be resolved by its {@link Id}. The persistence
+ * model is backend-specific (see the {@linkplain Registry class Javadoc}):
+ *
- * The registration is performed asynchronously and requires a cryptographic
- * signature to ensure the authenticity and integrity of the {@code Card} data.
- * The {@code nonce} and {@code version} parameters provide replay protection and versioning.
- *
+ * Implementations cache full resolution results (the resolved {@code Card} plus its
+ * {@link Resolver.ResolutionMetadata metadata}) so the resolver can short-circuit a
+ * repeat lookup. Cache misses, expired entries, and storage errors leave it to the caller to
+ * resolve from the underlying source.
+ *
+ * Implementations may be in-memory, on disk, or remote; they may purge expired entries lazily
+ * on access and/or expose an explicit {@link #evictExpired()} hook.
+ *
+ * Use {@link #fileSystem(Path, long)} or {@link #fileSystem()} for the built-in on-disk
+ * implementation.
+ */
+public interface ResolutionCache {
+ /**
+ * Stores a resolution result for the given {@link Id}, replacing any previous entry.
+ * Implementations should only persist results the caller considers authoritative; negative
+ * or invalid results are typically not worth keeping.
+ *
+ * @param id the identifier being cached
+ * @param result the resolution result to cache (the resolved Card and its metadata)
+ * @throws ResolutionCacheException if storing fails (I/O error, serialization error, etc.)
+ */
+ void put(Id id, Resolver.ResolutionResult
+ * Part of the resolver exception hierarchy ({@link io.bosonnetwork.BosonException} →
+ * {@link RegistryException} → {@link ResolverException} → {@code ResolutionCacheException}),
+ * so it is a checked exception. {@link CachedResolver} treats it as recoverable: a cache failure is logged and the
+ * call falls through to the underlying resolver rather than propagating to the caller.
+ */
+public class ResolutionCacheException extends ResolverException {
+ private static final long serialVersionUID = 7301217164571775472L;
+
+ /**
+ * Constructs a new {@code ResolutionCacheException} with {@code null} as its detail message.
+ */
+ public ResolutionCacheException() {
+ super();
+ }
+
+ /**
+ * Constructs a new {@code ResolutionCacheException} with the specified detail message.
+ *
+ * @param message the detail message that explains the reason for the exception
+ */
+ public ResolutionCacheException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new {@code ResolutionCacheException} with the specified detail message
+ * and cause.
+ *
+ * @param message the detail message that explains the reason for the exception
+ * @param cause the cause of the exception (may be {@code null})
+ */
+ public ResolutionCacheException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new {@code ResolutionCacheException} with the specified cause.
+ *
+ * @param cause the cause of the exception (may be {@code null})
+ */
+ public ResolutionCacheException(Throwable cause) {
+ super(cause);
+ }
+}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/identifier/Resolver.java b/api/src/main/java/io/bosonnetwork/identifier/Resolver.java
index 2c101b18..cd673615 100644
--- a/api/src/main/java/io/bosonnetwork/identifier/Resolver.java
+++ b/api/src/main/java/io/bosonnetwork/identifier/Resolver.java
@@ -116,17 +116,17 @@ public static ResolutionStatus from(int code) {
*/
class ResolutionOptions {
// Default options: use cache, no TTL (0 disables TTL).
- private static final ResolutionOptions DEFAULT = new ResolutionOptions(true, 0); // no cache
+ private static final ResolutionOptions DEFAULT = new ResolutionOptions(true, 0);
- private final boolean usingCache;
+ private final boolean useCache;
private final long validTTL;
/**
- * @param usingCache whether to use cached results if available
+ * @param useCache whether to use cached results if available
* @param validTTL time-to-live for the cached result in milliseconds (0 disables TTL)
*/
- public ResolutionOptions(boolean usingCache, long validTTL) {
- this.usingCache = usingCache;
+ public ResolutionOptions(boolean useCache, long validTTL) {
+ this.useCache = useCache;
this.validTTL = validTTL;
}
@@ -134,8 +134,8 @@ public ResolutionOptions(boolean usingCache, long validTTL) {
* Whether to use cached results if available.
* @return true if cache should be used, false otherwise
*/
- public boolean usingCache() {
- return usingCache;
+ public boolean useCache() {
+ return useCache;
}
/**
@@ -160,7 +160,7 @@ public static ResolutionOptions defaultOptions() {
* Metadata describing the resolved result, such as creation date, update date, resolution time,
* deactivation status, and version.
*/
- class ResolutionResultMetadata {
+ class ResolutionMetadata {
@JsonProperty("created")
private final Date created;
@JsonProperty("updated")
@@ -179,7 +179,7 @@ class ResolutionResultMetadata {
* @param deactivated whether the resource is deactivated
* @param version version number of the resource
*/
- public ResolutionResultMetadata(Date created, Date updated, Date resolved, boolean deactivated, int version) {
+ public ResolutionMetadata(Date created, Date updated, Date resolved, boolean deactivated, int version) {
this.created = created;
this.updated = updated;
this.resolved = resolved;
@@ -239,7 +239,7 @@ class ResolutionResult
- * Implementations of this interface provide caching for the results of resolving
- * {@link Id} entities to their corresponding {@link Card} objects, typically to
- * improve resolution performance and reduce redundant network or computation cost.
- *
- * The cache may be in-memory, persistent (e.g., file-system based), or distributed.
- * Implementations may support cache expiration and/or eviction policies.
- *
- * The provided static factory methods allow creation of a file-system based cache
- * implementation, which persists cache entries to disk and supports expiration.
- */
-public interface ResolverCache {
- /**
- * Stores the resolution result for a given {@link Id} in the cache.
- *
- * @param id the identifier for which the result is being cached
- * @param result the resolved {@link Card} result to cache
- * @throws Exception if storing the result fails (e.g., I/O error or serialization error)
- */
- void put(Id id, Resolver.ResolutionResult
- * For file-system based caches, this may delete files whose entries have expired.
- *
- * @throws Exception if cleanup fails (e.g., I/O error)
- */
- void cleanup() throws Exception;
-
- /**
- * Clears all entries from the cache.
- *
- * For persistent caches, this typically removes all stored data (e.g., deletes all cache files).
- *
- * @throws Exception if clearing fails (e.g., I/O error)
- */
- void clear() throws Exception;
-
- /**
- * Creates a file-system based {@link ResolverCache} instance.
- *
- * Cache entries are persisted to the specified directory and will expire after the given duration.
- * Expired entries are automatically purged on access or via {@link #cleanup()}.
- *
- * @param cacheDir the directory to store cache files
- * @param expiration the duration in milliseconds after which cached entries expire
- * @return a file-system based cache instance
- * @throws Exception if the cache cannot be created (e.g., directory inaccessible)
- */
- static ResolverCache fileSystem(Path cacheDir, long expiration) throws Exception {
- return new FileSystemResolverCache(cacheDir, expiration);
- }
-
- /**
- * Creates a file-system based {@link ResolverCache} instance with default directory and expiration.
- *
- * The default location and expiration policy are implementation-defined.
- *
- * @return a file-system based cache instance with default settings
- * @throws Exception if the cache cannot be created
- */
- static ResolverCache fileSystem() throws Exception {
- return new FileSystemResolverCache();
- }
-}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/identifier/VerifiableCredential.java b/api/src/main/java/io/bosonnetwork/identifier/VerifiableCredential.java
index 2a057f5a..5215c463 100644
--- a/api/src/main/java/io/bosonnetwork/identifier/VerifiableCredential.java
+++ b/api/src/main/java/io/bosonnetwork/identifier/VerifiableCredential.java
@@ -121,9 +121,9 @@ public class VerifiableCredential extends W3CDIDFormat {
private final Proof proof;
/**
- * A transient BosonCredential representation of this verifiable credential.
+ * A transient CredentialView representation of this verifiable credential.
*/
- private transient BosonCredential bosonCredential;
+ private transient volatile CredentialView credentialView;
/**
* Internal constructor used by JSON deserializer.
@@ -156,9 +156,9 @@ protected VerifiableCredential(@JsonProperty(value = "@context") List
* This class is used internally to optimize storage and signing operations.
*/
- protected static class BosonCredential extends Credential {
+ protected static class CredentialView extends Credential {
private final VerifiableCredential vc;
/**
- * Constructs a BosonCredential from a VerifiableCredential.
+ * Constructs a CredentialView from a VerifiableCredential.
*
* @param vc the source verifiable credential
*/
- protected BosonCredential(VerifiableCredential vc) {
+ protected CredentialView(VerifiableCredential vc) {
super(DIDURL.create(vc.id).getFragment(),
vc.types.stream().filter(t -> !t.equals(DIDConstants.DEFAULT_VC_TYPE)).collect(Collectors.toList()),
vc.name, vc.description, vc.issuer, vc.validFrom, vc.validUntil,
@@ -623,13 +629,32 @@ protected BosonCredential(VerifiableCredential vc) {
}
/**
- * Constructs a BosonCredential from a Credential and associates it with a VerifiableCredential.
+ * Constructs a CredentialView from a Credential and associates it with a VerifiableCredential.
*
* @param cred the source credential
* @param vc the associated verifiable credential
*/
- protected BosonCredential(Credential cred, VerifiableCredential vc) {
- super(cred, cred.getSignedAt(), cred.getSignature());
+ protected CredentialView(Credential cred, VerifiableCredential vc) {
+ super(cred, cred.getSignature());
+ this.vc = vc;
+ }
+
+ /**
+ * Constructs a sat-stamped, unsigned CredentialView view of a VerifiableCredential.
+ *
+ * Used at sign time by {@link VerifiableCredentialBuilder} to compute the bytes the
+ * signature will cover. {@code signedAt} must be set so that it is part of the signed
+ * data; the resulting proof's {@code created} value should be the same timestamp.
+ *
+ * @param vc the source verifiable credential (proof may be null)
+ * @param signedAt the signing timestamp to embed in the signed bytes
+ */
+ protected CredentialView(VerifiableCredential vc, Date signedAt) {
+ super(DIDURL.create(vc.id).getFragment(),
+ vc.types.stream().filter(t -> !t.equals(DIDConstants.DEFAULT_VC_TYPE)).collect(Collectors.toList()),
+ vc.name, vc.description, vc.issuer, vc.validFrom, vc.validUntil,
+ vc.subject.id, vc.subject.claims,
+ signedAt, null);
this.vc = vc;
}
diff --git a/api/src/main/java/io/bosonnetwork/identifier/VerifiableCredentialBuilder.java b/api/src/main/java/io/bosonnetwork/identifier/VerifiableCredentialBuilder.java
index 395d3af0..3acc2bc7 100644
--- a/api/src/main/java/io/bosonnetwork/identifier/VerifiableCredentialBuilder.java
+++ b/api/src/main/java/io/bosonnetwork/identifier/VerifiableCredentialBuilder.java
@@ -282,8 +282,11 @@ public VerifiableCredential build() {
VerifiableCredential unsigned = new VerifiableCredential(contexts, idUrl.toString(), types,
name, description, issuer, validFrom, validUntil, subject, claims);
- byte[] signature = identity.sign(unsigned.getSignData());
- Proof proof = new Proof(Proof.Type.Ed25519Signature2020, now(),
+ // Stamp signedAt before signing so it is covered by the signature, and use the same
+ // timestamp as the proof's `created` value so verification reconstructs the same bytes.
+ Date signedAt = now();
+ byte[] signature = identity.sign(new VerifiableCredential.CredentialView(unsigned, signedAt).getSignData());
+ Proof proof = new Proof(Proof.Type.Ed25519Signature2020, signedAt,
VerificationMethod.defaultReferenceOf(issuer), Proof.Purpose.assertionMethod, signature);
return new VerifiableCredential(unsigned, proof);
diff --git a/api/src/main/java/io/bosonnetwork/identifier/VerifiablePresentation.java b/api/src/main/java/io/bosonnetwork/identifier/VerifiablePresentation.java
index 02e08c9b..d529045d 100644
--- a/api/src/main/java/io/bosonnetwork/identifier/VerifiablePresentation.java
+++ b/api/src/main/java/io/bosonnetwork/identifier/VerifiablePresentation.java
@@ -1,7 +1,29 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
package io.bosonnetwork.identifier;
import java.util.ArrayList;
-import java.util.Collections;
+import java.util.Date;
import java.util.List;
import java.util.Map;
import java.util.Objects;
@@ -51,7 +73,7 @@ public class VerifiablePresentation extends W3CDIDFormat {
private final Proof proof;
/** Transient compact Boson Vouch representation */
- private transient BosonVouch bosonVouch;
+ private transient volatile VouchView vouchView;
/**
* Internal constructor used by JSON deserializer to create a VerifiablePresentation instance.
@@ -74,11 +96,11 @@ protected VerifiablePresentation(@JsonProperty(value = "@context") List
+ * Note: this verifies signatures only. The validity period (validFrom/validUntil)
+ * of the embedded credentials is a caller policy and is NOT checked here; call
+ * {@link VerifiableCredential#validate()} on the individual credentials if needed.
*
* @throws InvalidSignatureException if signature verification fails
*/
@@ -230,15 +257,29 @@ public void validate() throws InvalidSignatureException {
}
/**
- * Checks whether the cryptographic proof is valid and genuine.
+ * Checks whether this presentation is genuine: the holder's proof verifies and every
+ * embedded {@link VerifiableCredential} is itself genuine. The holder's envelope signature
+ * alone is not sufficient, since it does not attest to the authenticity of the contained
+ * credentials.
+ *
+ * This checks signatures only, not the validity period of the embedded credentials.
*
- * @return true if the proof is present and verifies correctly; false otherwise
+ * @return true if the holder proof and all embedded credential signatures verify; false otherwise
*/
public boolean isGenuine() {
if (proof == null)
return false;
- return proof.verify(holder, getSignData());
+ try {
+ if (!proof.verify(holder, getSignData()))
+ return false;
+ } catch (RuntimeException e) {
+ // Malformed id makes sign-data reconstruction throw; treat as not genuine.
+ return false;
+ }
+
+ // The envelope is authentic; now require every embedded credential to be genuine too.
+ return credentials.stream().allMatch(VerifiableCredential::isGenuine);
}
/**
@@ -247,10 +288,10 @@ public boolean isGenuine() {
* @return Vouch representation of this presentation
*/
public Vouch toVouch() {
- if (bosonVouch == null)
- bosonVouch = new BosonVouch(this);
+ if (vouchView == null)
+ vouchView = new VouchView(this);
- return bosonVouch;
+ return vouchView;
}
/**
@@ -263,7 +304,7 @@ public Vouch toVouch() {
*/
public static VerifiablePresentation fromVouch(Vouch vouch, Map
+ * Used at sign time by {@link VerifiablePresentationBuilder} to compute the bytes the
+ * signature will cover. {@code signedAt} must be set so that it is part of the signed
+ * data; the resulting proof's {@code created} value should be the same timestamp.
*
- * @param vp the VerifiablePresentation instance
- * @param unsigned unused boolean flag to differentiate constructor
+ * @param vp the VerifiablePresentation instance (proof may be null)
+ * @param signedAt the signing timestamp to embed in the signed bytes
*/
- protected BosonVouch(VerifiablePresentation vp, boolean unsigned) {
+ protected VouchView(VerifiablePresentation vp, Date signedAt) {
super(vp.id == null ? null : DIDURL.create(vp.id).getFragment(),
vp.types.stream().filter(t -> !t.equals(DIDConstants.DEFAULT_VP_TYPE)).collect(Collectors.toList()),
vp.holder,
- vp.credentials.stream().map(VerifiableCredential::toCredential).collect(Collectors.toList()));
+ vp.credentials.stream().map(VerifiableCredential::toCredential).collect(Collectors.toList()),
+ signedAt);
this.vp = vp;
}
/**
- * Constructs a BosonVouch from an existing Vouch and associated VerifiablePresentation.
+ * Constructs a VouchView from an existing Vouch and associated VerifiablePresentation.
*
* @param vouch the existing Vouch instance
* @param vp the associated VerifiablePresentation
*/
- protected BosonVouch(Vouch vouch, VerifiablePresentation vp) {
- super(vouch, vouch.getSignedAt(), vouch.getSignature());
+ protected VouchView(Vouch vouch, VerifiablePresentation vp) {
+ super(vouch, vouch.getSignature());
this.vp = vp;
}
diff --git a/api/src/main/java/io/bosonnetwork/identifier/VerifiablePresentationBuilder.java b/api/src/main/java/io/bosonnetwork/identifier/VerifiablePresentationBuilder.java
index fdee3d8e..671565c6 100644
--- a/api/src/main/java/io/bosonnetwork/identifier/VerifiablePresentationBuilder.java
+++ b/api/src/main/java/io/bosonnetwork/identifier/VerifiablePresentationBuilder.java
@@ -1,6 +1,29 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
package io.bosonnetwork.identifier;
import java.util.ArrayList;
+import java.util.Date;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
@@ -321,14 +344,15 @@ public VerifiablePresentation build() {
List
- * This class provides a compact form for transmitting and storing a Verifiable Presentation,
- * mapping the standard VP fields to short JSON/CBOR keys as follows:
+ * A vouch is the holder's signed affirmation — "I, the holder, vouch for these credentials"
+ * — packaged in a short, CBOR/JSON-friendly layout. It mirrors {@code VerifiablePresentation}
+ * (the W3C form) the same way {@link Card} mirrors {@link DIDDocument}: same content, shorter keys
+ * and no JSON-LD vocabulary, so it's cheap to ship over the wire or pin in storage.
+ *
+ * Convert with {@link VerifiablePresentation#toVouch()} and {@link VerifiablePresentation#fromVouch(Vouch, java.util.Map)}.
+ * The signature covers everything except itself, including {@code signedAt}.
+ *
+ * Compact key map:
*
- * The caller should transfer ownership of the collections to the new instance.
- * Used for building unsigned {@code Vouch} objects.
+ * Used by the W3C adapter ({@link VerifiablePresentation.VouchView}) at sign time to build
+ * the bytes the signature will cover. {@code signedAt} must be set before signing because it
+ * is part of the signed data.
*
- * @param id the unique identifier for the presentation
- * @param types the types associated with the presentation
- * @param holder the identifier of the entity presenting the credentials
- * @param credentials the list of credentials included in the presentation
+ * @param id the unique identifier for the presentation (may be null)
+ * @param types the types associated with the presentation (may be null or empty)
+ * @param holder the holder identifier
+ * @param credentials the list of credentials
+ * @param signedAt the signing timestamp to embed
*/
- protected Vouch(String id, List
- * Mapped to the compact JSON/CBOR key {@code "sat"}.
+ * Mapped to the compact JSON/CBOR key {@code "sat"}. Note: {@code signedAt} is metadata and is
+ * not covered by the signature, so it is not cryptographically authenticated.
*
* @return the signing timestamp, or {@code null} if unsigned
*/
@@ -265,11 +273,16 @@ public Date getSignedAt() {
* @return the signature byte array, or {@code null} if unsigned
*/
public byte[] getSignature() {
- return signature;
+ return signature == null ? null : signature.clone();
}
/**
- * Validates the signature of this presentation.
+ * Validates this presentation: the holder's signature and the signature of every embedded
+ * credential must all verify.
+ *
+ * Note: this verifies signatures only. The validity period of the embedded
+ * credentials is a caller policy and is NOT checked here; call {@link Credential#validate()}
+ * on the individual credentials if needed.
*
* @throws InvalidSignatureException if the signature is invalid or not genuine
*/
@@ -279,17 +292,24 @@ public void validate() throws InvalidSignatureException {
}
/**
- * Checks if the signature of this presentation is genuine.
+ * Checks if this presentation is genuine: the holder's signature verifies and every
+ * embedded {@link Credential} is itself genuine. The holder's envelope signature alone is not
+ * sufficient, since it does not attest to the authenticity of the contained credentials.
*
- * @return {@code true} if the signature is valid and genuine, {@code false} otherwise
+ * @return {@code true} if the holder signature and all embedded credential signatures verify,
+ * {@code false} otherwise
*/
public boolean isGenuine() {
// Signature must be present and of correct length
if (signature == null || signature.length != Signature.BYTES)
return false;
- // Verify the signature against the sign data and holder's public key
- return Signature.verify(getSignData(), signature, holder.toSignatureKey());
+ // Verify the holder's signature against the sign data and holder's public key
+ if (!Signature.verify(getSignData(), signature, holder.toSignatureKey()))
+ return false;
+
+ // The envelope is authentic; now require every embedded credential to be genuine too.
+ return credentials.stream().allMatch(Credential::isGenuine);
}
/**
@@ -301,10 +321,11 @@ public boolean isGenuine() {
* @return the byte array to be signed or verified
*/
protected byte[] getSignData() {
- // If already signed, strip signature/signedAt for sign data
- if (signature != null) // already signed
- return new Vouch(this, null, null).toBytes();
- else // unsigned
+ if (signature != null) // already signed
+ // Rebuild the bytes that were signed: everything except the signature itself.
+ // signedAt is part of the signed data so that the signing timestamp is authenticated.
+ return new Vouch(this, null).toBytes();
+ else // unsigned
return toBytes();
}
@@ -412,4 +433,4 @@ public static VouchBuilder builder(Identity holder) {
Objects.requireNonNull(holder, "holder");
return new VouchBuilder(holder);
}
-}
+}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/identifier/VouchBuilder.java b/api/src/main/java/io/bosonnetwork/identifier/VouchBuilder.java
index a1bce1a6..ea93c827 100644
--- a/api/src/main/java/io/bosonnetwork/identifier/VouchBuilder.java
+++ b/api/src/main/java/io/bosonnetwork/identifier/VouchBuilder.java
@@ -1,6 +1,29 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
package io.bosonnetwork.identifier;
import java.util.ArrayList;
+import java.util.Date;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
@@ -290,11 +313,10 @@ public Vouch build() {
throw new IllegalStateException("Vouch must include at least one credential");
List
+ * This is a low-level structural transcoder operating on the raw factories: it copies the CBOR
+ * token stream into JSON and does not apply the Boson type module or the URL-safe Base64
+ * convention used by {@link #objectMapper()}/{@link #cborMapper()}. Binary CBOR fields are emitted
+ * using Jackson's default Base64 variant.
*
* @param cbor the byte array containing CBOR-encoded data
* @return a JSON string representation of the provided CBOR data
@@ -670,6 +698,10 @@ public static String cborToJson(byte[] cbor) {
/**
* Converts a JSON string to its CBOR (Concise Binary Object Representation) byte array representation.
+ *
+ * This is a low-level structural transcoder operating on the raw factories: it copies the JSON
+ * token stream into CBOR and does not apply the Boson type module or the URL-safe Base64
+ * convention used by {@link #objectMapper()}/{@link #cborMapper()}.
*
* @param json the JSON string to be converted to CBOR format; must not be null
* @return a byte array containing the CBOR encoded representation of the provided JSON string
@@ -691,12 +723,18 @@ public static byte[] jsonToCbor(String json) {
}
/**
- * Initializes and registers the Boson JSON Jackson module with the global Jackson DatabindCodec mapper.
+ * Initializes and registers the Boson JSON Jackson module with the global Vert.x
+ * {@link DatabindCodec} mapper.
+ *
+ * Process-global side effect: this mutates the singleton {@code DatabindCodec.mapper()}
+ * shared by all Vert.x JSON handling in the JVM — it registers the Boson type module and enables
+ * {@link DeserializationFeature#USE_BIG_DECIMAL_FOR_FLOATS} for every Vert.x JSON operation in
+ * the process, not just Boson code. Call it once during application startup.
*
- * This method ensures the Boson JSON module is registered only once. If already registered,
- * the method returns immediately. The module adds support for Boson-specific types and serialization behaviors.
+ * The method is idempotent and synchronized: the module is registered at most once even under
+ * concurrent calls.
*/
- public static void initializeBosonJsonModule() {
+ public static synchronized void initializeBosonJsonModule() {
if (DatabindCodec.mapper().getRegisteredModuleIds().stream()
.anyMatch(id -> id.equals(BOSON_JSON_MODULE_NAME)))
return; // already registered
diff --git a/api/src/main/java/io/bosonnetwork/json/JsonContext.java b/api/src/main/java/io/bosonnetwork/json/JsonContext.java
index f0656b9f..a9a63de8 100644
--- a/api/src/main/java/io/bosonnetwork/json/JsonContext.java
+++ b/api/src/main/java/io/bosonnetwork/json/JsonContext.java
@@ -94,7 +94,7 @@ public static JsonContext perCall(Object key, Object value) {
* @param value2 the second attribute value
* @return a per-call context with the specified attributes
*/
- static JsonContext perCall(Object key1, Object value1, Object key2, Object value2) {
+ public static JsonContext perCall(Object key1, Object value1, Object key2, Object value2) {
Map
+ * Although {@link DateSerializer} emits text dates at second precision, this deserializer is tolerant
+ * of both: it first parses the second-precision form and falls back to the millisecond-precision
+ * form ({@code yyyy-MM-dd'T'HH:mm:ss.SSS'Z'}), so millisecond-bearing strings still parse correctly.
*/
public class DateDeserializer extends StdDeserializer
* Handles serialization of Date objects to either ISO8601 string format (for text formats like JSON/YAML)
* or to epoch milliseconds (for binary formats like CBOR), depending on the output format.
+ *
+ * Precision: text output is intentionally truncated to second precision
+ * ({@code yyyy-MM-dd'T'HH:mm:ss'Z'}, matching RFC3339), so sub-second components are dropped in
+ * JSON/YAML. Binary (CBOR) output preserves full millisecond precision via epoch milliseconds. The
+ * matching {@link DateDeserializer} still accepts millisecond-precision strings on input.
*/
public class DateSerializer extends StdSerializer
+ * A consistent dual-encoding convention is applied: binary formats (CBOR) carry IDs, addresses and
+ * other byte fields as binary; text formats (JSON/YAML) use Base58 / string forms. The URL-safe
+ * Base64 variant is used throughout, and {@link io.bosonnetwork.json.Json#cborMapper()} /
+ * {@link io.bosonnetwork.json.Json#cborFactory()} also back the CBOR encoding of
+ * {@link io.bosonnetwork.cwt.SignedCwt}.
+ *
+ * The concrete (de)serializers live in the non-published {@code internal} subpackage.
+ */
+package io.bosonnetwork.json;
diff --git a/api/src/main/java/io/bosonnetwork/metrics/package-info.java b/api/src/main/java/io/bosonnetwork/metrics/package-info.java
new file mode 100644
index 00000000..7fb55464
--- /dev/null
+++ b/api/src/main/java/io/bosonnetwork/metrics/package-info.java
@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Service-provider interfaces for monitoring Boson network components.
+ *
+ * {@link io.bosonnetwork.metrics.Metrics} is the contract implemented by a metrics provider that
+ * wants to observe Boson services, and {@link io.bosonnetwork.metrics.Measured} is the marker
+ * interface for components that expose such metrics. The interfaces are intentionally minimal so a
+ * host application can plug in its own metrics backend.
+ */
+package io.bosonnetwork.metrics;
diff --git a/api/src/main/java/io/bosonnetwork/package-info.java b/api/src/main/java/io/bosonnetwork/package-info.java
index 216afe0e..09a54d2b 100644
--- a/api/src/main/java/io/bosonnetwork/package-info.java
+++ b/api/src/main/java/io/bosonnetwork/package-info.java
@@ -22,6 +22,31 @@
*/
/**
- * This package contains the public APIs and types for the Boson node.
+ * The core public API of the Boson network — the root types every other package and third-party
+ * SDK builds on.
+ *
+ * Supporting concerns live in subpackages: {@link io.bosonnetwork.crypto cryptography},
+ * {@link io.bosonnetwork.identifier DID/VC identity}, {@link io.bosonnetwork.cwt CWT tokens},
+ * {@link io.bosonnetwork.service layer-2 services}, {@link io.bosonnetwork.json serialization},
+ * {@link io.bosonnetwork.database database helpers}, {@link io.bosonnetwork.web web auth},
+ * {@link io.bosonnetwork.vertx Vert.x helpers} and {@link io.bosonnetwork.utils utilities}.
*/
package io.bosonnetwork;
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/service/BosonService.java b/api/src/main/java/io/bosonnetwork/service/BosonService.java
index 2fae33f2..4c784329 100644
--- a/api/src/main/java/io/bosonnetwork/service/BosonService.java
+++ b/api/src/main/java/io/bosonnetwork/service/BosonService.java
@@ -57,31 +57,38 @@ public interface BosonService {
String getName();
/**
- * Retrieves the host associated with the service.
+ * Returns the local bind host of the service (the address the service listens on
+ * locally — e.g. {@code 0.0.0.0}, {@code 127.0.0.1}, or a configured interface). This is
+ * deployment configuration and is generally different from the publicly-reachable host
+ * advertised in {@link #getPeerInfo()}.
*
- * @return a string representing the host's address.
+ * @return the local bind host.
*/
String getHost();
/**
- * Retrieves the port number associated with the service.
+ * Returns the local bind port of the service. Deployment configuration; usually
+ * different from any port advertised through {@link #getPeerInfo()}.
*
- * @return an integer representing the port number.
+ * @return the local bind port.
*/
int getPort();
/**
- * Retrieves the endpoint URL associated with the service.
+ * Returns the public endpoint URL that remote clients should use to reach this
+ * service. The endpoint encoded in {@link #getPeerInfo()} is normally the same value and is
+ * what gets gossiped/published over the network.
*
- * @return a string representing the service endpoint.
+ * @return the public service endpoint URL.
*/
String getEndpoint();
/**
- * Retrieves detailed information about the peer associated with the service.
+ * Returns the published peer information for this service — the public-facing identity, the
+ * advertised endpoint, and any associated metadata. This is what federation peers see when
+ * looking up the service.
*
- * @return a {@link PeerInfo} object containing peer-related information, such as
- * host, port, and other metadata.
+ * @return the {@link PeerInfo} for this service.
*/
PeerInfo getPeerInfo();
@@ -95,7 +102,11 @@ default boolean isFederationEnabled() {
}
/**
- * Get the running status
+ * Returns whether the service is currently running.
+ *
+ * The contract is: {@code true} only between a successful completion of {@link #start()} and
+ * the moment {@link #stop()} begins executing. While a {@code start()} or {@code stop()}
+ * future is still pending, this returns {@code false}.
*
* @return true if the service is running, false otherwise.
*/
@@ -103,6 +114,10 @@ default boolean isFederationEnabled() {
/**
* Initialize the service instance with the {@link ServiceContext} object.
+ *
+ * Must not block. {@code init} is called on the Vert.x event loop (following
+ * the standard Vert.x verticle init pattern); any I/O (config reads, schema setup, network
+ * calls) must be deferred to {@link #start()} where it can be performed asynchronously.
*
* @param context the {@link ServiceContext} object to initialize the service.
* @throws BosonServiceException if the error occurred during the initialization.
diff --git a/api/src/main/java/io/bosonnetwork/service/BosonServiceException.java b/api/src/main/java/io/bosonnetwork/service/BosonServiceException.java
index 8003dd32..42364baa 100644
--- a/api/src/main/java/io/bosonnetwork/service/BosonServiceException.java
+++ b/api/src/main/java/io/bosonnetwork/service/BosonServiceException.java
@@ -66,7 +66,6 @@ public BosonServiceException(String message) {
* {@link #getCause()} method). (A {@code null} value is
* permitted, and indicates that the cause is nonexistent or
* unknown.)
- * @since 1.4
*/
public BosonServiceException(String message, Throwable cause) {
super(message, cause);
@@ -84,9 +83,8 @@ public BosonServiceException(String message, Throwable cause) {
* {@link #getCause()} method). (A {@code null} value is
* permitted, and indicates that the cause is nonexistent or
* unknown.)
- * @since 1.4
*/
public BosonServiceException(Throwable cause) {
super(cause);
}
-}
+}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/service/BosonServiceFactory.java b/api/src/main/java/io/bosonnetwork/service/BosonServiceFactory.java
new file mode 100644
index 00000000..a5e63a40
--- /dev/null
+++ b/api/src/main/java/io/bosonnetwork/service/BosonServiceFactory.java
@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package io.bosonnetwork.service;
+
+/**
+ * Service provider interface for creating {@link BosonService} instances.
+ *
+ * Implementations are discovered at runtime via the {@link java.util.ServiceLoader}
+ * mechanism and keyed by their {@link #getType() type}, which lets the Boson super node
+ * select and instantiate the configured layer2 services without referencing concrete
+ * implementation class names. Providers register themselves through a
+ * {@code META-INF/services/io.bosonnetwork.service.BosonServiceFactory} entry, or a
+ * {@code provides io.bosonnetwork.service.BosonServiceFactory with ...} declaration when
+ * running on the Java module path.
+ */
+public interface BosonServiceFactory {
+ /**
+ * The unique identifier for the service type produced by this factory.
+ *
+ * Must equal the {@link BosonService#getType() type} of the services it creates.
+ *
+ * @return the unique type identifier string.
+ */
+ String getType();
+
+ /**
+ * Creates a new, uninitialized {@link BosonService} instance.
+ *
+ * The returned service is not yet initialized; the caller is responsible for invoking
+ * {@link BosonService#init(ServiceContext)} and {@link BosonService#start()}.
+ *
+ * @return a new {@link BosonService} instance.
+ */
+ BosonService create();
+}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/service/ClientAuthenticator.java b/api/src/main/java/io/bosonnetwork/service/ClientAuthenticator.java
index c1fc3f33..642552b3 100644
--- a/api/src/main/java/io/bosonnetwork/service/ClientAuthenticator.java
+++ b/api/src/main/java/io/bosonnetwork/service/ClientAuthenticator.java
@@ -29,55 +29,72 @@
/**
* Interface for authenticating clients (users and devices) within the Boson network.
*
- * Implementations provide mechanisms to verify the identity of users and devices
- * typically using cryptographic challenges and signatures (e.g., Ed25519).
+ * Implementations verify the identity of users and devices, typically using cryptographic
+ * challenges and signatures (e.g., Ed25519).
+ *
+ * Nonce/signature contract. The overloads that accept {@code (nonce, signature)}
+ * support three call shapes:
+ *
- * Implementations of this interface define the logic to determine if a user on a specific device
- * is granted permission to use the requested service.
+ * Implementations decide whether a user, acting from a specific device, is permitted to use the
+ * requested service, and — on success — return any authorization details the service will need
+ * downstream (issued tokens, granted features, rate-limit overrides, etc.).
+ *
+ * Result contract.
+ *
+ * Stability: the map shape is intentionally untyped pending a refined
+ * {@code AuthorizationDecision} type; do not couple your code to specific keys without
+ * coordinating with the implementation you target.
*/
public interface ClientAuthorizer {
/**
- * Authorizes the specified user and device for the given service.
+ * Authorizes the specified user and device for the given service. See the
+ * {@linkplain ClientAuthorizer interface Javadoc} for the success/failure contract.
*
- * @param userId the unique identifier of the user requesting access
- * @param deviceId the unique identifier of the device used for the request
+ * @param userId the unique identifier of the user requesting access
+ * @param deviceId the unique identifier of the device used for the request
* @param serviceType the identifier of the target service type to be accessed
- * @return a {@link CompletableFuture} that completes with a map containing authorization details
- * (e.g., tokens, permissions) if successful, or completes exceptionally if authorization fails
+ * @return a {@link CompletableFuture} that completes with the authorization-details map on
+ * success, or completes exceptionally with a {@link io.bosonnetwork.BosonException}
+ * on denial or system error
*/
CompletableFuture
- * This configuration allows any request but associates them with a specific node identity,
- * depending on the implementation of {@link AllowAllClientContext}.
- *
- * Provides an in-memory simulation environment configured with a specific node identity
- * but without Web Token Auth support.
- *
- * This class provides a standard implementation for accessing service context information,
- * including the Vert.x instance, the Boson node, authentication/authorization components,
- * federation details, configuration, and data persistence paths.
- */
-public class DefaultServiceContext implements ServiceContext {
- private final Vertx vertx;
- private final Node node;
- private final ClientContext clientContext;
- private final FederationContext federationContext;
- private final Map
- * Implementations of this interface provide mechanisms to verify the identity of other nodes
- * in the federation using cryptographic challenges and signatures.
+ * Implementations verify the identity of other nodes in the federation using cryptographic
+ * challenges and signatures.
+ *
+ * Nonce/signature contract. The {@code (id, nonce, signature)} overloads accept
+ * three argument shapes:
+ *
+ * A role describes what kind of principal is authenticated, derived on the server
+ * from the resolved client identity. Roles are populated into the Vert.x
+ * {@code User.authorizations()} (as {@code RoleBasedAuthorization}s) and enforced by route
+ * {@code AuthorizationHandler}s. They are a server-internal vocabulary, distinct from the
+ * over-the-wire {@link AccessScope} token scope values.
+ */
+public enum Role {
+ /**
+ * Role for a standard client principal (a user or one of the user's devices). Grants access to
+ * non-administrative client APIs.
+ */
+ CLIENT("client"),
+ /**
+ * Role for an administrative user. Granted only when the resolved {@link ClientUser} reports
+ * {@link ClientUser#isAdmin()}; grants access to administrative APIs.
+ */
+ ADMIN("admin"),
+ /**
+ * Role for a federation peer (a super node or a federated service). Grants access to
+ * inter-node / inter-service federation APIs.
+ */
+ FEDERATION("federation");
+
+ private final String value;
+
+ Role(String value) {
+ this.value = value;
+ }
+
+ @Override
+ public String toString() {
+ return value;
+ }
+}
diff --git a/api/src/main/java/io/bosonnetwork/service/ServiceContext.java b/api/src/main/java/io/bosonnetwork/service/ServiceContext.java
index c6bdfc71..3ab10b20 100644
--- a/api/src/main/java/io/bosonnetwork/service/ServiceContext.java
+++ b/api/src/main/java/io/bosonnetwork/service/ServiceContext.java
@@ -26,8 +26,6 @@
import java.nio.file.Path;
import java.util.Map;
-import io.vertx.core.Vertx;
-
import io.bosonnetwork.Id;
import io.bosonnetwork.Node;
@@ -37,11 +35,14 @@
*/
public interface ServiceContext {
/**
- * Get the Vert.x instance to be used by the current DHT node.
+ * Unwraps the context to provide the underlying infrastructure instance.
*
- * @return the {@link Vertx} instance.
+ * @param clazz the type of the infrastructure component (e.g. io.vertx.core.Vertx)
+ * @return the component instance, or null if not available or not supported
+ * @param
+ * Implementations MUST return a defensive copy — mutating the returned array MUST NOT affect
+ * the internal state of this {@code ServiceInfo}.
*
- * @return the extra data
+ * @return a defensive copy of the extra data, or {@code null} if no extra data is present
*/
byte[] getExtraData();
/**
- * Gets the extra data as a map.
+ * Gets the extra data parsed as a map.
+ *
+ * The returned map is immutable; modification attempts result in {@link UnsupportedOperationException}.
*
- * @return the extra data map
+ * @return an immutable map of extra data, or an empty map if no extra data is present
*/
Map
+ * A display {@link #name(String) name} is mandatory — operators publishing a profile must
+ * declare who they are. The {@code logo}, {@code website}, and {@code contact} fields are
+ * optional and only emitted into the profile credential when set.
*
* @return a new super node profile
- * @throws IllegalStateException if no profile metadata (name, logo, website, or contact) was provided
+ * @throws IllegalStateException if {@code name} has not been set
*/
public SuperNodeProfile build() {
+ if (name == null || name.isEmpty())
+ throw new IllegalStateException("Super node profile name is required");
+
Map
+ * Concurrency note: the up-front existence check and the
+ * {@code computeIfAbsent} insert are not a single atomic step. Two threads calling
+ * {@code addUser(sameId, ...)} concurrently can both observe "not present" and both return
+ * {@code true}; the {@code computeIfAbsent} call still atomizes the actual write, so only one
+ * {@link PlainUser} entry is inserted — the race is benign with respect to map state but the
+ * boolean return may over-report success. This is a test/bring-up helper; this trade-off is
+ * acceptable for that use.
*
* @param userId The unique identifier of the user to be added. Must not be null.
* @param name The name of the user to be added.
@@ -130,6 +138,12 @@ public boolean removeUser(Id userId) {
/**
* Adds a new device to the user registry for a specified user. If the device already exists
* globally, the addition will fail and return false. The user must already exist in the registry.
+ *
+ * Concurrency note: as with {@link #addUser(Id, String, String) addUser},
+ * the up-front {@code existsDeviceSync} check and the subsequent {@code compute} insert are
+ * not a single atomic step; concurrent {@code addDevice} calls for the same {@code deviceId}
+ * can both return {@code true} even though only one entry is actually inserted. The race is
+ * benign with respect to map state and acceptable for this test/bring-up helper.
*
* @param userId The unique identifier of the user to which the device will be added. Must not be null.
* @param deviceId The global unique identifier of the device to be added. Must not be null.
@@ -291,35 +305,22 @@ public void clear() {
@Override
public CompletableFuture
+ * A layer-2 service (web gateway, ion store, photon messaging, custom services, …) is published
+ * by an operator's super node and consumed by end users (clients) or by other super nodes
+ * (federation peers). This package defines the contracts on both sides of that boundary.
+ *
+ *
+ * Returns true for:
+ *
@@ -500,7 +517,7 @@ public static Stream
+ * Uses the well-known UDP-{@code connect} trick: opening an unbound {@link DatagramSocket}
+ * and {@code connect}ing it to a public address forces the kernel to pick the local address
+ * the OS would use to reach that destination — without actually sending any packets. The
+ * targets are Google DNS ({@code 8.8.8.8} for IPv4, {@code 2001:4860:4860::8888} for IPv6),
+ * which the kernel only needs to be able to route to, not to talk to.
*
* @param type the address class (Inet4Address or Inet6Address)
- * @return the address of the default routing interface, or null if not found
+ * @return the address of the default routing interface, or {@code null} if no such route
+ * exists (e.g. IPv6 unconfigured, host offline) or the resolved local address is the
+ * wildcard
* @throws IllegalArgumentException if the type is not supported
*/
public static InetAddress getDefaultRouteAddress(Class type) {
+ if (type != Inet4Address.class && type != Inet6Address.class)
+ throw new IllegalArgumentException("Unsupported type: " + type);
+
try (DatagramSocket socket = new DatagramSocket()) {
InetAddress target;
-
if (type == Inet4Address.class)
target = InetAddress.getByAddress(new byte[]{8, 8, 8, 8});
- else if (type == Inet6Address.class)
- target = InetAddress.getByName("2001:4860:4860::8888");
else
- throw new IllegalArgumentException("Unsupported type: " + type);
+ target = InetAddress.getByName("2001:4860:4860::8888");
socket.connect(new InetSocketAddress(target, 53));
InetAddress local = socket.getLocalAddress();
@@ -570,39 +594,42 @@ else if (type == Inet6Address.class)
return local;
return null;
- } catch (IOException e) {
+ } catch (SocketException | UnknownHostException e) {
+ // "No route", "address family not supported", offline, etc. — not a programming error.
+ return null;
+ } catch (Exception e) {
throw new RuntimeException("Failed to get default route address", e);
}
}
- /*/
- public static InetAddress getDefaultRouteAddress(Class type) {
- try {
- for (NetworkInterface nif : Collections.list(NetworkInterface.getNetworkInterfaces())) {
- if (!nif.isUp() || nif.isLoopback() || nif.isVirtual())
- continue;
-
- for (InetAddress addr : Collections.list(nif.getInetAddresses())) {
- if (!type.isInstance(addr))
- continue;
- if (addr.isAnyLocalAddress() || addr.isLoopbackAddress() || addr.isLinkLocalAddress())
- continue;
-
- return addr;
- }
- }
+ /**
+ * Retrieves the default network interface associated with the specified address type.
+ * The default network interface is determined by resolving the default routing
+ * address for the provided address type.
+ *
+ * @param type the address class (Inet4Address or Inet6Address) used to determine
+ * the default network interface.
+ * @return the default {@code NetworkInterface} for the specified address type,
+ * or {@code null} if no default interface is found.
+ * @throws RuntimeException if there is an error retrieving the network interface.
+ */
+ public static NetworkInterface getDefaultNetworkInterface(Class type) {
+ InetAddress defaultAddress = getDefaultRouteAddress(type);
+ if (defaultAddress == null)
return null;
+
+ try {
+ return NetworkInterface.getByInetAddress(defaultAddress);
} catch (SocketException e) {
- throw new RuntimeException("Failed to get default router address", e);
+ throw new RuntimeException("Failed to get default network interface", e);
}
}
- */
/**
* Converts a socket address to a readable string, with optional alignment.
* IPv6 addresses are enclosed in square brackets.
*
- * @param addr the socket address to convert
+ * @param addr the socket address to convert
* @param align whether to align the output (e.g., fixed width for IPv4/IPv6)
* @return the formatted string representation of the socket address
* @throws NullPointerException if sockAddr is null
diff --git a/api/src/main/java/io/bosonnetwork/utils/ApplicationLock.java b/api/src/main/java/io/bosonnetwork/utils/ApplicationLock.java
index 0f864be2..0e43f51c 100644
--- a/api/src/main/java/io/bosonnetwork/utils/ApplicationLock.java
+++ b/api/src/main/java/io/bosonnetwork/utils/ApplicationLock.java
@@ -24,11 +24,14 @@
import java.io.File;
import java.io.IOException;
+import java.nio.ByteBuffer;
import java.nio.channels.FileChannel;
import java.nio.channels.FileLock;
+import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;
+import java.time.Instant;
/**
* File based application instance exclusive lock, guarantee the application can only run
@@ -86,6 +89,16 @@ private void tryLock() throws IOException, IllegalStateException {
lock = fc.tryLock(0, Long.MAX_VALUE, false);
if (lock == null)
throw new IllegalStateException("Already locked by another instance.");
+ // Write owner metadata so a reader can answer "who is holding this?". Best-effort —
+ // failure to write the marker does not affect the lock itself.
+ try {
+ String marker = ProcessHandle.current().pid() + " " + Instant.now() + System.lineSeparator();
+ fc.truncate(0);
+ fc.write(ByteBuffer.wrap(marker.getBytes(StandardCharsets.UTF_8)));
+ fc.force(true);
+ } catch (IOException ignore) {
+ // Owner marker is informational only; the lock itself is held by the file lock.
+ }
} catch (IOException | RuntimeException | Error e) {
fc.close();
fc = null;
@@ -94,6 +107,10 @@ private void tryLock() throws IOException, IllegalStateException {
}
private void unlock() {
+ // Only delete the lock file if we are confident we still own it. Without this guard, a
+ // late-running close() after the OS released our file lock can end up deleting a successor
+ // process's lock file (the file name is the same but the OS-level lock has moved on).
+ boolean stillOwnsLock = lock != null && lock.isValid();
try {
if (lock != null) {
lock.close();
@@ -105,7 +122,8 @@ private void unlock() {
fc = null;
}
- Files.deleteIfExists(lockFile);
+ if (stillOwnsLock)
+ Files.deleteIfExists(lockFile);
} catch (IOException ignore) {
// Ignore cleanup errors
} finally {
diff --git a/api/src/main/java/io/bosonnetwork/utils/ByteBufferInputStream.java b/api/src/main/java/io/bosonnetwork/utils/ByteBufferInputStream.java
index 1e45f3e0..667579d8 100644
--- a/api/src/main/java/io/bosonnetwork/utils/ByteBufferInputStream.java
+++ b/api/src/main/java/io/bosonnetwork/utils/ByteBufferInputStream.java
@@ -24,12 +24,13 @@
package io.bosonnetwork.utils;
import java.io.IOException;
+import java.io.InputStream;
import java.nio.ByteBuffer;
/**
* Utility to present ByteBuffer data as an InputStream.
*/
-public class ByteBufferInputStream {
+public class ByteBufferInputStream extends InputStream {
/**
* The ByteBuffer object from which data is read.
*/
diff --git a/api/src/main/java/io/bosonnetwork/utils/Bytes.java b/api/src/main/java/io/bosonnetwork/utils/Bytes.java
new file mode 100644
index 00000000..f4134d1e
--- /dev/null
+++ b/api/src/main/java/io/bosonnetwork/utils/Bytes.java
@@ -0,0 +1,151 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package io.bosonnetwork.utils;
+
+/**
+ * Utility class for efficient conversion between primitive types and byte arrays.
+ */
+public final class Bytes {
+ private Bytes() {}
+
+ /**
+ * Converts an integer value to a byte array.
+ *
+ * @param value the integer value to convert
+ * @return a byte array of length 4 representing the integer
+ */
+ public static byte[] fromInteger(int value) {
+ byte[] b = new byte[4];
+ b[0] = (byte) (value >> 24);
+ b[1] = (byte) (value >> 16);
+ b[2] = (byte) (value >> 8);
+ b[3] = (byte) value;
+ return b;
+ }
+
+ /**
+ * Converts a byte array to an integer value.
+ *
+ * @param bytes the byte array to convert
+ * @return the integer value
+ */
+ public static int toInteger(byte[] bytes) {
+ return toInteger(bytes, 0);
+ }
+
+ /**
+ * Converts a byte array to an integer value starting from the specified offset.
+ *
+ * @param bytes the byte array to convert
+ * @param offset the offset in the byte array to start from
+ * @return the integer value
+ */
+ public static int toInteger(byte[] bytes, int offset) {
+ return ((bytes[offset] & 0xFF) << 24) |
+ ((bytes[offset + 1] & 0xFF) << 16) |
+ ((bytes[offset + 2] & 0xFF) << 8) |
+ (bytes[offset + 3] & 0xFF);
+ }
+
+ /**
+ * Converts a short value to a byte array.
+ *
+ * @param value the short value to convert
+ * @return a byte array of length 2 representing the short
+ */
+ public static byte[] fromShort(short value) {
+ byte[] b = new byte[2];
+ b[0] = (byte) (value >> 8);
+ b[1] = (byte) value;
+ return b;
+ }
+
+ /**
+ * Converts a byte array to a short value.
+ *
+ * @param bytes the byte array to convert
+ * @return the short value
+ */
+ public static short toShort(byte[] bytes) {
+ return toShort(bytes, 0);
+ }
+
+ /**
+ * Converts a byte array to a short value starting from the specified offset.
+ *
+ * @param bytes the byte array to convert
+ * @param offset the offset in the byte array to start from
+ * @return the short value
+ */
+ public static short toShort(byte[] bytes, int offset) {
+ return (short) (((bytes[offset] & 0xFF) << 8) |
+ (bytes[offset + 1] & 0xFF));
+ }
+
+ /**
+ * Converts a long value to a byte array.
+ *
+ * @param value the long value to convert
+ * @return a byte array of length 8 representing the long
+ */
+ public static byte[] fromLong(long value) {
+ byte[] b = new byte[8];
+ b[0] = (byte) (value >> 56);
+ b[1] = (byte) (value >> 48);
+ b[2] = (byte) (value >> 40);
+ b[3] = (byte) (value >> 32);
+ b[4] = (byte) (value >> 24);
+ b[5] = (byte) (value >> 16);
+ b[6] = (byte) (value >> 8);
+ b[7] = (byte) value;
+ return b;
+ }
+
+ /**
+ * Converts a byte array to a long value.
+ *
+ * @param bytes the byte array to convert
+ * @return the long value
+ */
+ public static long toLong(byte[] bytes) {
+ return toLong(bytes, 0);
+ }
+
+ /**
+ * Converts a byte array to a long value starting from the specified offset.
+ *
+ * @param bytes the byte array to convert
+ * @param offset the offset in the byte array to start from
+ * @return the long value
+ */
+ public static long toLong(byte[] bytes, int offset) {
+ return (((long) bytes[offset] & 0xFF) << 56) |
+ (((long) bytes[offset + 1] & 0xFF) << 48) |
+ (((long) bytes[offset + 2] & 0xFF) << 40) |
+ (((long) bytes[offset + 3] & 0xFF) << 32) |
+ (((long) bytes[offset + 4] & 0xFF) << 24) |
+ (((long) bytes[offset + 5] & 0xFF) << 16) |
+ (((long) bytes[offset + 6] & 0xFF) << 8) |
+ ((long) bytes[offset + 7] & 0xFF);
+ }
+}
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/utils/ConfigMap.java b/api/src/main/java/io/bosonnetwork/utils/ConfigMap.java
index ca1e3972..fb6deb1d 100644
--- a/api/src/main/java/io/bosonnetwork/utils/ConfigMap.java
+++ b/api/src/main/java/io/bosonnetwork/utils/ConfigMap.java
@@ -116,9 +116,15 @@ else if (val instanceof Boolean b)
return b ? 1 : 0;
else if (val instanceof String s)
try {
- return Double.parseDouble(s);
- } catch (NumberFormatException e) {
- throw new IllegalArgumentException("Invalid number value - " + key + ": " + val);
+ // Try long first to preserve precision for integer-valued strings; fall back to
+ // double for true floating-point values.
+ return Long.parseLong(s);
+ } catch (NumberFormatException ignoreLong) {
+ try {
+ return Double.parseDouble(s);
+ } catch (NumberFormatException e) {
+ throw new IllegalArgumentException("Invalid number value - " + key + ": " + val);
+ }
}
else
throw new IllegalArgumentException("Invalid number value - " + key + ": " + val);
@@ -362,7 +368,11 @@ public long getSize(String key) {
try {
long size = Long.parseLong(s, 0, idx, 10);
- return size * weight;
+ try {
+ return Math.multiplyExact(size, (long) weight);
+ } catch (ArithmeticException e) {
+ throw new IllegalArgumentException("Size value out of range for long - " + key + ": " + s, e);
+ }
} catch (NumberFormatException e) {
throw new IllegalArgumentException("Invalid size value - " + key + ": " + s, e);
}
@@ -435,8 +445,14 @@ public Duration getDuration(String key) {
try {
long number = Long.parseLong(s, 0, idx, 10);
- return Duration.ofMillis(number * unit.getDuration().toMillis());
- } catch (Exception e) {
+ long unitMillis = unit.getDuration().toMillis();
+ try {
+ return Duration.ofMillis(Math.multiplyExact(number, unitMillis));
+ } catch (ArithmeticException e) {
+ throw new IllegalArgumentException("Duration value out of range for long milliseconds - "
+ + key + ": " + s, e);
+ }
+ } catch (NumberFormatException e) {
throw new IllegalArgumentException("Invalid duration value - " + key + ": " + s, e);
}
} else {
@@ -558,9 +574,14 @@ public Id getId(String key, Id def) {
*
* The value must be a Map, which will be wrapped in a new ConfigMap instance.
*
+ * Note: unlike the scalar getters, this returns {@code null} (rather than
+ * throwing) when the key is absent. Nested sections are commonly optional, and callers can
+ * idiomatically write {@code if (m.getObject("section") == null)} to detect that. Use
+ * {@link #containsKey(Object)} first if you want to distinguish "absent" from "explicitly null."
*
* @param key the configuration key, key must not be null
- * @return a ConfigMap wrapping the nested configuration, or null if the key is not present
+ * @return a ConfigMap wrapping the nested configuration, or {@code null} if the key is not present
* @throws NullPointerException if the key is null
* @throws IllegalArgumentException if the value is not a Map
*/
@@ -583,10 +604,13 @@ public ConfigMap getObject(String key) {
*
* The value must be a List. The returned list is cast to the specified type parameter.
*
+ * Note: like {@link #getObject(String)}, this returns {@code null} (rather
+ * than throwing) when the key is absent — list configuration sections are commonly optional.
*
* @param
* All methods in this class are static and the class cannot be instantiated.
*/
-public class FileUtils {
+public final class FileUtils {
+ private FileUtils() {
+ }
+
+ /**
+ * Returns the resolved XDG base directory for the given env var name, falling back to
+ * {@code ~/relativeFallback} when the env var is absent or empty.
+ *
+ * @param envVar the XDG environment variable name (e.g. {@code XDG_CONFIG_HOME})
+ * @param relativeFallback the fallback path under the user home if the env var is unset
+ * @return the resolved path
+ */
+ private static Path xdgPath(String envVar, String relativeFallback) {
+ String xdg = System.getenv(envVar);
+ if (xdg != null && !xdg.isEmpty())
+ return Path.of(xdg);
+ return Path.of(System.getProperty("user.home"), relativeFallback);
+ }
+
/**
* Deletes the specified file or directory from the file system.
*
@@ -177,15 +195,10 @@ public static Path getSiteConfigDir() {
*/
public static Path getUserConfigDir() {
String osName = System.getProperty("os.name").toLowerCase();
- if (osName.startsWith("windows")) {
+ if (osName.startsWith("windows"))
return Path.of(System.getenv("APPDATA"));
- } else if (osName.startsWith("mac")) {
- // return Path.of(System.getProperty("user.home"), "Library/Preferences");
- return Path.of(System.getProperty("user.home"), ".config");
- } else {
- // Unix like OS
- return Path.of(System.getProperty("user.home"), ".config");
- }
+ // macOS uses XDG style here (intentionally — see class doc)
+ return xdgPath("XDG_CONFIG_HOME", ".config");
}
/**
@@ -236,15 +249,9 @@ public static Path getSystemDataDir() {
*/
public static Path getUserDataDir() {
String osName = System.getProperty("os.name").toLowerCase();
- if (osName.startsWith("windows")) {
+ if (osName.startsWith("windows"))
return Path.of(System.getenv("LOCALAPPDATA"));
- } else if (osName.startsWith("mac")) {
- //return Path.of(System.getProperty("user.home"), "Library/Application Support");
- return Path.of(System.getProperty("user.home"), ".local/share");
- } else {
- // Unix like OS
- return Path.of(System.getProperty("user.home"), ".local/share");
- }
+ return xdgPath("XDG_DATA_HOME", ".local/share");
}
/**
@@ -293,15 +300,9 @@ public static Path getSystemCacheDir() {
*/
public static Path getUserCacheDir() {
String osName = System.getProperty("os.name").toLowerCase();
- if (osName.startsWith("windows")) {
+ if (osName.startsWith("windows"))
return Path.of(System.getenv("LOCALAPPDATA"));
- } else if (osName.startsWith("mac")) {
- // return Path.of(System.getProperty("user.home"), "Library/Caches");
- return Path.of(System.getProperty("user.home"), ".cache");
- } else {
- // Unix like OS
- return Path.of(System.getProperty("user.home"), ".cache");
- }
+ return xdgPath("XDG_CACHE_HOME", ".cache");
}
/**
@@ -350,21 +351,22 @@ public static Path getSystemLogDir() {
*/
public static Path getUserLogDir() {
String osName = System.getProperty("os.name").toLowerCase();
- if (osName.startsWith("windows")) {
+ if (osName.startsWith("windows"))
return Path.of(System.getenv("LOCALAPPDATA"));
- } else if (osName.startsWith("mac")) {
- // return Path.of(System.getProperty("user.home"), "Library/Logs");
- return Path.of(System.getProperty("user.home"), ".local/state");
- } else {
- // Unix like OS
- return Path.of(System.getProperty("user.home"), ".local/state");
- }
+ return xdgPath("XDG_STATE_HOME", ".local/state");
}
/**
- * Converts a {@link URL} to a {@link Path}.
- * This method handles URLs with "jar" schemes and properly retrieves the corresponding
- * filesystem path for entries within JAR files.
+ * Converts a {@link URL} to a {@link Path}, handling both regular file URLs and entries
+ * inside JAR archives (the {@code jar:} scheme).
+ *
+ * JAR FileSystem caching: for a {@code jar:} URL this method opens a JAR
+ * {@link java.nio.file.FileSystem} lazily and caches it process-wide (subsequent calls for the
+ * same archive return the same FileSystem via the {@code FileSystemAlreadyExistsException}
+ * branch). The cached FileSystem is intentionally not closed — callers should not close the
+ * returned Path's FileSystem either, since other callers may still hold derived Paths into the
+ * same archive. In practice the number of distinct JARs is small (resource lookups), so this
+ * is the desired behavior.
*
* @param url the {@link URL} to be converted to a {@link Path}, must not be null
* @return the {@link Path} corresponding to the given {@link URL}
diff --git a/api/src/main/java/io/bosonnetwork/utils/Functional.java b/api/src/main/java/io/bosonnetwork/utils/Functional.java
index b1bed671..5917ca2b 100644
--- a/api/src/main/java/io/bosonnetwork/utils/Functional.java
+++ b/api/src/main/java/io/bosonnetwork/utils/Functional.java
@@ -28,7 +28,10 @@
/**
* Some functional helper methods.
*/
-public class Functional {
+public final class Functional {
+ private Functional() {
+ }
+
/**
* Feeds the object to the {@code Consumer} and return the object.
*
@@ -95,10 +98,18 @@ public interface ThrowingFunction
+ * This uses the "sneaky-throw" idiom — the original exception is rethrown
+ * as-is using a generic-erasure trick, not wrapped in a {@code RuntimeException}. A caller's
+ * {@code catch (IOException e)} clause will still match an {@code IOException} thrown from
+ * {@code f}, even though this method's signature does not declare it. Use this only where
+ * declaring the checked type is impossible (e.g. inside a {@code Function} / {@code Supplier})
+ * and the caller is prepared for the actual exception type to surface.
*
* @param
- * This method is useful for conditionally setting a value when the
- * {@code Variable} is empty. To unconditionally set a nullable value, use
- * the constructor or {@link #ofNullable}.
- *
+ * {@link io.bosonnetwork.utils.logging.HighlightingCompositeConverter} is a Logback converter that
+ * colors console output by log level (ERROR / WARN / INFO / TRACE) using ANSI codes; reference it
+ * from a Logback pattern layout to get colored logs in supported terminals.
+ */
+package io.bosonnetwork.utils.logging;
diff --git a/api/src/main/java/io/bosonnetwork/utils/package-info.java b/api/src/main/java/io/bosonnetwork/utils/package-info.java
index 6d8813e6..c74face1 100644
--- a/api/src/main/java/io/bosonnetwork/utils/package-info.java
+++ b/api/src/main/java/io/bosonnetwork/utils/package-info.java
@@ -22,6 +22,24 @@
*/
/**
- * Contains the basic utility and support classes.
+ * Common, dependency-light utility and support classes used across Boson.
+ *
+ *
* It provides interoperability between the Vert.x asynchronous programming model and the Java
* {@link CompletableFuture}/{@link CompletionStage} APIs. This allows developers to:
@@ -61,18 +61,21 @@
*
* @param
+ *
+ *
+ *
*
*/
-public class Json {
+public final class Json {
private static final String BOSON_JSON_MODULE_NAME = "io.bosonnetwork.utils.json.module";
/** Pre-configured Base64 encoder for URL-safe encoding without padding. */
@@ -95,43 +95,147 @@ public class Json {
/** Pre-configured Base64 decoder for URL-safe decoding. */
public static final Base64.Decoder BASE64_DECODER = Base64.getUrlDecoder();
- private static TypeReference{@link io.bosonnetwork.cwt.SignedCwt}
+ * The entry point: a CWT structured as a COSE_Sign1 single-signer object. It is specialized for
+ * Boson — it strictly enforces the EdDSA (Ed25519) signature algorithm and binds the {@code "iss"}
+ * (issuer) claim to a Boson {@link io.bosonnetwork.Id} / {@link io.bosonnetwork.Identity}. Build
+ * tokens with {@link io.bosonnetwork.cwt.SignedCwt#builder(io.bosonnetwork.Identity)} and verify
+ * them with {@link io.bosonnetwork.cwt.SignedCwt#parser()}.
+ * Codec vocabulary
+ * {@link io.bosonnetwork.cwt.Claim} (CWT claim keys), {@link io.bosonnetwork.cwt.Header} (COSE
+ * header parameters) and {@link io.bosonnetwork.cwt.Algorithm} (COSE algorithm identifiers)
+ * enumerate the integer keys used on the wire.
+ *
+ * Errors
+ * All parsing/validation failures are reported as {@link io.bosonnetwork.cwt.CwtException} or one
+ * of its typed subclasses (invalid CBOR tag, COSE structure, algorithm, signature, issuer key,
+ * claim, expiration, not-before, issued-at).
+ *
+ * References
+ *
+ */
+package io.bosonnetwork.cwt;
diff --git a/api/src/main/java/io/bosonnetwork/database/CollectionParameter.java b/api/src/main/java/io/bosonnetwork/database/CollectionParameter.java
index edb60bd0..8dcb75de 100644
--- a/api/src/main/java/io/bosonnetwork/database/CollectionParameter.java
+++ b/api/src/main/java/io/bosonnetwork/database/CollectionParameter.java
@@ -46,14 +46,16 @@ public class CollectionParameterLIKE condition
*/
public static Filter like(String column, Object value) {
- return like(column, column, value);
+ return like(column, defaultParamName(column, "like"), value);
}
/**
@@ -242,8 +238,7 @@ public static Filter like(String column, Object value) {
*/
public static Filter isNull(String column) {
Objects.requireNonNull(column);
- validateColumn(column);
- return new Unary(column, "IS NULL");
+ return new Unary(validateColumn(column), "IS NULL");
}
/**
@@ -254,8 +249,7 @@ public static Filter isNull(String column) {
*/
public static Filter isNotNull(String column) {
Objects.requireNonNull(column);
- validateColumn(column);
- return new Unary(column, "IS NOT NULL");
+ return new Unary(validateColumn(column), "IS NOT NULL");
}
/**
@@ -267,10 +261,12 @@ public static Filter isNotNull(String column) {
*/
public static Filter in(String column, Map
* Ordering order = Ordering.by("name").asc()
- * .then("created").desc();
+ * .then("created").desc()
+ * .build();
* String sql = order.toSql(); // " ORDER BY name ASC, created DESC"
*
*/
@@ -157,8 +160,7 @@ public static final class Builder {
private Builder(String column, Direction direction) {
Objects.requireNonNull(column);
- validateColumn(column);
- list.add(new Field(column, direction)); // default
+ list.add(new Field(validateColumn(column), direction)); // default
}
/**
@@ -190,8 +192,7 @@ public Builder desc() {
*/
public Builder then(String column, Direction direction) {
Objects.requireNonNull(column);
- validateColumn(column);
- list.add(new Field(column, direction));
+ list.add(new Field(validateColumn(column), direction));
return this;
}
@@ -220,20 +221,4 @@ public Ordering build() {
return new Ordering(list);
}
}
-
- /**
- * Validates that the column name contains only safe characters.
- * Safe query building
+ * Only bound values are parameterized; SQL identifiers (column / parameter / schema names)
+ * are interpolated, so they are validated through {@link io.bosonnetwork.database.SqlSafety} to
+ * prevent injection. The builders compose Vert.x {@code SqlTemplate} fragments:
+ *
+ *
+ *
+ * Execution
+ * {@link io.bosonnetwork.database.VertxDatabase} wraps a {@code SqlClient} (pool or single
+ * connection) with {@code withConnection}/{@code withTransaction} helpers and small row-mapping
+ * utilities. Per the project convention, use {@code withTransaction} for writes and
+ * {@code withConnection} for reads.
+ *
+ * Migrations
+ * {@link io.bosonnetwork.database.VersionedSchema} applies versioned
+ * {@code
+ *
*
+ *
+ *
+ *
+ * Implementations should reject the call when the card is not genuine
+ * ({@link Card#isGenuine()}) or when {@code identity.getId() != card.getId()}; both indicate
+ * caller misuse.
*
- *
*/
@JsonPropertyOrder({"id", "t", "h", "c", "sat", "sig"})
@@ -131,31 +137,33 @@ protected Vouch(@JsonProperty(value = "id") String id,
Objects.requireNonNull(signature, "signature");
this.id = id;
- // Defensive: always wrap as unmodifiable list (or empty)
- this.types = types == null || types.isEmpty() ? Collections.emptyList() : Collections.unmodifiableList(types);
+ // Defensive: copy and wrap as unmodifiable list (or empty)
+ this.types = types == null || types.isEmpty() ? List.of() : List.copyOf(types);
this.holder = holder;
- this.credentials = Collections.unmodifiableList(credentials);
+ this.credentials = List.copyOf(credentials);
this.signedAt = signedAt;
- this.signature = signature;
+ this.signature = signature.clone();
}
/**
- * Internal constructor used by {@link VouchBuilder}.
+ * Internal constructor for a sat-stamped but unsigned Vouch.
* Identity documents and claims
+ *
+ *
+ * Each object has a fluent {@code *Builder} (for example
+ * {@link io.bosonnetwork.identifier.CardBuilder}, {@link io.bosonnetwork.identifier.CredentialBuilder},
+ * {@link io.bosonnetwork.identifier.VerifiableCredentialBuilder}) that signs on build.
+ *
+ * Addressing and resolution
+ * {@link io.bosonnetwork.identifier.DIDURL} parses and builds {@code did:boson:} URLs;
+ * {@link io.bosonnetwork.identifier.DIDConstants} and {@link io.bosonnetwork.identifier.W3CDIDFormat}
+ * hold the shared constants. {@link io.bosonnetwork.identifier.Resolver} /
+ * {@link io.bosonnetwork.identifier.Registry} define DID resolution and publication, with a
+ * DHT-backed implementation ({@link io.bosonnetwork.identifier.DHTResolver},
+ * {@link io.bosonnetwork.identifier.DHTRegistry}) and a
+ * {@link io.bosonnetwork.identifier.ResolutionCache} (e.g.
+ * {@link io.bosonnetwork.identifier.FileSystemResolutionCache}) fronted by
+ * {@link io.bosonnetwork.identifier.CachedResolver}.
+ *
+ * References
+ *
+ *
+ */
+package io.bosonnetwork.identifier;
diff --git a/api/src/main/java/io/bosonnetwork/json/Json.java b/api/src/main/java/io/bosonnetwork/json/Json.java
index 6fda7e98..c48986c2 100644
--- a/api/src/main/java/io/bosonnetwork/json/Json.java
+++ b/api/src/main/java/io/bosonnetwork/json/Json.java
@@ -87,7 +87,7 @@
* {@link io.bosonnetwork.json.Json}
+ * The single entry point. It exposes pre-configured, shared (thread-safe) Jackson mappers/factories
+ * and convenience {@code toString} / {@code toPrettyString} / {@code toBytes} / {@code parse}
+ * helpers. The mappers register a module with custom (de)serializers for Boson domain types
+ * ({@link io.bosonnetwork.Id}, {@link io.bosonnetwork.NodeInfo}, {@link io.bosonnetwork.PeerInfo},
+ * {@link io.bosonnetwork.Value}, {@link java.util.Date}, {@link java.net.InetAddress}).
+ * {@link io.bosonnetwork.json.JsonContext}
+ * An immutable Jackson {@code ContextAttributes} subclass for passing per-call or shared
+ * serialization options (for example selecting the W3C-DID string form for IDs).
+ *
+ * Node and identity
+ * {@link io.bosonnetwork.Node} is the DHT node abstraction (lookups, value/peer storage, encrypt /
+ * decrypt / sign), created via {@link io.bosonnetwork.NodeFactory} from a
+ * {@link io.bosonnetwork.NodeConfiguration}. {@link io.bosonnetwork.Identity} and
+ * {@link io.bosonnetwork.UserProfile} model cryptographic identities.
+ *
+ * Addressing and DHT records
+ * {@link io.bosonnetwork.Id} is the 256-bit Ed25519-based identifier used for nodes, values and
+ * peers. {@link io.bosonnetwork.Value} (mutable/immutable stored data),
+ * {@link io.bosonnetwork.PeerInfo} (announced peers) and {@link io.bosonnetwork.NodeInfo} /
+ * {@link io.bosonnetwork.Network} describe what lives in and around the DHT.
+ *
+ * Operations and results
+ * Lookups are tuned by {@link io.bosonnetwork.LookupOption} and return their outcome through
+ * {@link io.bosonnetwork.Result}. Errors surface as {@link io.bosonnetwork.BosonException} and its
+ * subtypes (e.g. {@link io.bosonnetwork.ExpiredException}), and {@link io.bosonnetwork.Version}
+ * carries node version metadata.
+ *
+ *
+ *
*/
public interface ClientAuthenticator {
/**
- * Authenticates a user based on their ID and a cryptographic signature.
+ * Authenticates a user. See the {@linkplain ClientAuthenticator interface Javadoc} for the
+ * nonce/signature contract.
*
* @param userId the unique identifier of the user
- * @param nonce the random challenge data (nonce) used for authentication
- * @param signature the digital signature of the nonce, generated using the user's private key
- * @return a {@link CompletableFuture} that completes with {@code true} if the user is successfully authenticated,
+ * @param nonce the challenge data, or {@code null} for pre-authenticated mode
+ * @param signature the signature over {@code nonce}, or {@code null} for pre-authenticated mode
+ * @return a {@link CompletableFuture} that completes with {@code true} if the user is admitted,
* or {@code false} otherwise
*/
CompletableFuture
+ *
+ *
+ *
+ *
*
- * @param nodeIdentity the identity of the node allowing access; if null, generic allows-all behavior applies
- * @return a {@link ClientContext} instance configured with permissive access rules.
+ * @param nodeIdentity the identity that will sign issued web tokens (required if
+ * {@link #getWebAuthenticator()} will be called)
+ * @return a permissive {@link ClientContext}
*/
static ClientContext allowAll(Identity nodeIdentity) {
return new AllowAllClientContext(nodeIdentity);
}
/**
- * Returns a new in-memory client context suitable for testing with Node Identity.
- *
+ *
*/
public interface FederationAuthenticator {
/**
- * Authenticates a node in the federation.
+ * Authenticates a node in the federation. See the
+ * {@linkplain FederationAuthenticator interface Javadoc} for the nonce/signature contract.
*
* @param nodeId the unique identifier of the node to be authenticated
- * @param nonce the random challenge data (nonce) used for authentication
- * @param signature the digital signature of the nonce, generated using the node's private key
- * @return a {@link CompletableFuture} that completes with {@code true} if the node is successfully authenticated,
+ * @param nonce the challenge data, or {@code null} for pre-authenticated mode
+ * @param signature the signature over {@code nonce}, or {@code null} for pre-authenticated mode
+ * @return a {@link CompletableFuture} that completes with {@code true} if the node is admitted,
* or {@code false} otherwise
*/
CompletableFuture
+ *
*
- * @param nodeIdentity the {@link Identity} representing the node's identity in the federation context
- * @return a {@link FederationContext} instance that allows all operations while bypassing web token authentication
+ * @param nodeIdentity the identity that will sign issued web tokens (required if
+ * {@link #getWebAuthenticator()} will be called)
+ * @return a permissive {@link FederationContext}
*/
static FederationContext allowAll(Identity nodeIdentity) {
return new AllowAllFederationContext(nodeIdentity);
}
/**
- * Creates and returns a static {@link FederationContext} instance that is based
- * on a specific node identity. This method is suitable for scenarios requiring
- * static federation configuration for a particular node without the need for
- * token-based authentication mechanisms.
+ * Returns an in-memory federation context whose node and service registries are populated
+ * imperatively at test/bring-up time
+ * ({@link io.bosonnetwork.service.impl.StaticFederationContext} exposes
+ * {@code addNode(...)}, {@code addService(...)}, etc.). {@link #getWebAuthenticator()} returns
+ * a real {@link CwtAuth} backed by the registry and requires a non-null {@code nodeIdentity}.
*
- * @param nodeIdentity the {@link Identity} representing the identity of the node
- * within the federation context.
- * @return a {@link FederationContext} instance configured to use the specified
- * node identity and operate with a static federation configuration.
+ * @param nodeIdentity the identity that will sign issued web tokens (required if
+ * {@link #getWebAuthenticator()} will be called)
+ * @return an in-memory {@link FederationContext}
*/
static FederationContext staticContext(Identity nodeIdentity) {
return new StaticFederationContext(nodeIdentity);
diff --git a/api/src/main/java/io/bosonnetwork/service/Role.java b/api/src/main/java/io/bosonnetwork/service/Role.java
new file mode 100644
index 00000000..45871f77
--- /dev/null
+++ b/api/src/main/java/io/bosonnetwork/service/Role.java
@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2023 - bosonnetwork.io
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package io.bosonnetwork.service;
+
+/**
+ * Enum representing the authorization roles assigned to an authenticated principal.
+ * Authoring a service: {@link io.bosonnetwork.service.BosonService} +
+ * {@link io.bosonnetwork.service.BosonServiceFactory}
+ * A service implements {@link io.bosonnetwork.service.BosonService} (identity, public endpoint,
+ * lifecycle: {@code init} → {@code start} → {@code stop}) and ships a
+ * {@link io.bosonnetwork.service.BosonServiceFactory} discovered via Java
+ * {@link java.util.ServiceLoader} (a {@code META-INF/services/} entry, or a {@code provides}
+ * declaration on the module path). The hosting super node loads factories by
+ * {@link io.bosonnetwork.service.BosonServiceFactory#getType() type} and instantiates the
+ * configured ones.
+ *
+ * Runtime: the three contexts
+ * On {@code init}, the host hands the service a
+ * {@link io.bosonnetwork.service.ServiceContext}, a one-stop runtime handle:
+ *
+ *
+ *
+ * Client vs. federation
+ * The two "sides" each carry their own auth surface:
+ *
+ *
+ * Both authenticator interfaces share a "nonce/signature contract" (see their interface Javadoc):
+ * non-null nonce+signature ⇒ verify; both null ⇒ pre-authenticated mode; exactly one null ⇒ caller bug.
+ *
+ * Identity and access scopes
+ * Principal entitlements are exposed through {@link io.bosonnetwork.service.Role} (server-derived
+ * tiers: client / admin / federation) and {@link io.bosonnetwork.service.AccessScope}
+ * (the over-the-wire {@code api:*} scope strings). See
+ * {@link io.bosonnetwork.web.CwtAuth} for how the web layer maps a resolved principal into
+ * Vert.x {@code Authorizations}.
+ *
+ * Test/demo helpers
+ * The {@code impl/} subpackage ships ready-made contexts for testing and bring-up:
+ * {@link io.bosonnetwork.service.ClientContext#allowAll(io.bosonnetwork.Identity) allowAll},
+ * {@link io.bosonnetwork.service.ClientContext#staticContext(io.bosonnetwork.Identity) staticContext},
+ * {@link io.bosonnetwork.service.FederationContext#disabled() disabled},
+ * {@link io.bosonnetwork.service.FederationContext#allowAll(io.bosonnetwork.Identity) allowAll},
+ * and {@link io.bosonnetwork.service.FederationContext#staticContext(io.bosonnetwork.Identity) staticContext}.
*/
package io.bosonnetwork.service;
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/utils/AddressUtils.java b/api/src/main/java/io/bosonnetwork/utils/AddressUtils.java
index 05145fd5..89a2e7a6 100644
--- a/api/src/main/java/io/bosonnetwork/utils/AddressUtils.java
+++ b/api/src/main/java/io/bosonnetwork/utils/AddressUtils.java
@@ -23,9 +23,6 @@
package io.bosonnetwork.utils;
-import java.io.BufferedReader;
-import java.io.IOException;
-import java.io.InputStreamReader;
import java.net.DatagramSocket;
import java.net.Inet4Address;
import java.net.Inet6Address;
@@ -33,7 +30,6 @@
import java.net.InetSocketAddress;
import java.net.NetworkInterface;
import java.net.SocketException;
-import java.net.URL;
import java.net.UnknownHostException;
import java.util.ArrayList;
import java.util.Collections;
@@ -52,29 +48,37 @@
* @see Reserved IP addresses
* @see Martian packet
*/
-public class AddressUtils {
- // IPv4 Bogon ranges (excludes ranges covered by InetAddress methods)
+public final class AddressUtils {
+ private AddressUtils() {
+ }
+
+ // IPv4 Bogon ranges. Some entries overlap with InetAddress.isSiteLocalAddress() /
+ // isLoopbackAddress() / isLinkLocalAddress() / isMulticastAddress() — kept here explicitly
+ // so the table reads as a self-contained list of RFC-classified non-routable ranges.
// Reference: RFC 1918, RFC 6890
private static final String[] IPV4_BOGON_RANGES = {
- // "0.0.0.0/8", // Any local
- // "10.0.0.0/8", // Site local
+ "0.0.0.0/8", // Any local
+ "10.0.0.0/8", // Site local
"100.64.0.0/10", // Private network - shared address space (RFC 6598)
- // "127.0.0.0/8", // Loopback
- // "169.254.0.0/16", // Link local
- // "172.16.0.0/12", // Site local
+ "127.0.0.0/8", // Loopback
+ "169.254.0.0/16", // Link local
+ "172.16.0.0/12", // Site local
"192.0.0.0/24", // Reserved (IANA)
"192.0.2.0/24", // Documentation (TEST-NET-1)
- // "192.168.0.0/16", // Site local
+ "192.168.0.0/16", // Site local
"198.18.0.0/15", // Benchmarking (RFC 2544)
"198.51.100.0/24", // Documentation (TEST-NET-2)
"203.0.113.0/24", // Documentation (TEST-NET-3)
- // "224.0.0.0/4", // Multicast
+ "224.0.0.0/4", // Multicast
"233.252.0.0/24", // Documentation
"240.0.0.0/4", // Reserved (partially allocated)
- "255.255.255.255/32" // Broadcast
+ "255.255.255.255/32" // Broadcast
};
- // IPv6 Bogon ranges (excludes ranges covered by InetAddress methods)
+ // IPv6 Bogon ranges. Some entries overlap with InetAddress.isLinkLocalAddress() /
+ // isSiteLocalAddress() / isMulticastAddress(), and some are subsets of broader entries in this
+ // table (e.g. ::ffff:0:0/96 ⊂ ::/8; Teredo / Benchmarking / ORCHID ⊂ 2001::/23) — kept here
+ // explicitly so the table reads as a self-contained list of RFC-classified non-routable ranges.
// Reference: RFC 4291, RFC 6890
private static final String[] IPV6_BOGON_RANGES = {
"::/8", // Reserved
@@ -90,14 +94,14 @@ public class AddressUtils {
"3fff::/20", // Documentation
"3ffe::/16", // 6bone testing
"5f00::/16", // Segment Routing (SRv6) SIDs
- "fc00::/7" // Unique local address (RFC 4193)
- // "fe80::/10", // Link local
- // "fec0::/10", // Site local
- // "ff00::/8" // Multicast
+ "fc00::/7", // Unique local address (RFC 4193)
+ "fe80::/10", // Link local
+ "fec0::/10", // Site local
+ "ff00::/8" // Multicast
};
- private static List
+ *
+ *
+ * @param addr the IP address to check
+ * @return true if the address is private, false otherwise
+ * @throws NullPointerException if addr is null
+ */
+ public static boolean isPrivate(InetAddress addr) {
+ Objects.requireNonNull(addr, "Address cannot be null");
+ if (addr.isSiteLocalAddress())
+ return true;
+ byte[] b = addr.getAddress();
+ if (addr instanceof Inet4Address)
+ // RFC 6598: 100.64.0.0/10 — first byte 0x64 (100), top 2 bits of second byte = 01
+ return (b[0] & 0xff) == 100 && (b[1] & 0xc0) == 0x40;
+ if (addr instanceof Inet6Address)
+ // RFC 4193: fc00::/7 — top 7 bits = 1111110 (0xfc or 0xfd in the leading byte)
+ return (b[0] & 0xfe) == 0xfc;
+ return false;
+ }
+
/**
* Checks if the IP address is a unicast address.
*
+ *
*/
package io.bosonnetwork.utils;
\ No newline at end of file
diff --git a/api/src/main/java/io/bosonnetwork/vertx/BosonVerticle.java b/api/src/main/java/io/bosonnetwork/vertx/BosonVerticle.java
index 9aea2f0d..9869d31f 100644
--- a/api/src/main/java/io/bosonnetwork/vertx/BosonVerticle.java
+++ b/api/src/main/java/io/bosonnetwork/vertx/BosonVerticle.java
@@ -28,9 +28,7 @@
import io.vertx.core.Deployable;
import io.vertx.core.Future;
import io.vertx.core.Handler;
-import io.vertx.core.Promise;
import io.vertx.core.Vertx;
-import io.vertx.core.internal.ContextInternal;
import io.vertx.core.json.JsonObject;
/**
@@ -153,15 +151,13 @@ protected void prepare(Vertx vertx, Context context) {
*/
public final Future deploy(Context context) throws Exception {
prepare(context.owner(), context);
- ContextInternal internal = (ContextInternal) context;
- Promise