unlegitlibrary/README.MD

# UnlegitLibrary

UnlegitLibrary is a modular Java library focused on reusable core building blocks:
event handling, commands, addon loading, network communication (TCP/UDP with optional
TLS), and various utility classes.

## Contents
- Features
- Maven Integration
- ArgumentParser
- NetworkSystem (TCP/UDP + TLS/mTLS)
- Create Certificates
- License

## Features
- Addon system: loader, lifecycle, addon events
- Event system: listeners, priorities, cancellable events
- Command system: command manager, permissions, execute events
- NetworkSystem: TCP/UDP, packet handling, optional TLS security, UDP encryption
- Utilities: number/math, strings/colors, files, reflection, logging
- ArgumentParser: registration, validation, and execution of arguments


## Maven Integration
```xml
<repositories>
    <repository>
        <id>repounlegitdqrk</id>
        <url>https://repo.unlegitdqrk.dev/api/packages/unlegitdqrk/maven</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>dev.unlegitdqrk</groupId>
        <artifactId>unlegitlibrary</artifactId>
        <version>VERSION</version>
    </dependency>
</dependencies>
```

## ArgumentParser
### Basic Example
```java
ArgumentParser parser = new ArgumentParser(args);

Argument verbose = new Argument("verbose", "Enable verbose output", false);
verbose.setRun((arg, value) -> System.out.println("Verbose on"));
parser.registerArgument(verbose);

Argument mode = new Argument("mode", "Run mode", true, true, false, List.of("dev", "prod"));
mode.setRun((arg, value) -> System.out.println("Mode: " + value.orElse("")));
parser.registerArgument(mode);

parser.runArguments();
```

### Value Rules
- Constructor: `Argument(name, description, required, requireValue, optionalValue, values)`
- `requireValue=false` and `optionalValue=false`: no value allowed
- `requireValue=true` and `optionalValue=false`: value is required
- `requireValue=false` and `optionalValue=true`: value is optional
- `requireValue=true` and `optionalValue=true`: invalid combination
- If `values` is not empty, the provided value must be in the list

## NetworkSystem (TCP/UDP + TLS)
- TCP is the control channel (handshake, routing, session data).
- UDP is optional and encrypted using a symmetric key negotiated over TCP.
- TLS can be enabled or disabled.
- mTLS is supported (`ClientAuthMode.REQUIRED` + TrustStore on the server side).

### Basic Example
```java
PacketHandler packetHandler = new PacketHandler();
packetHandler.registerPacket(() -> new ExamplePacket(""));
EventManager eventManager = new EventManager();

NetworkServer server = new NetworkServer.Builder()
    .packetHandler(packetHandler)
    .eventManager(eventManager)
    .sslEnabled(false)
    .clientAuthMode(ClientAuthMode.NONE)
    .build();
server.start(25565, 25566);

NetworkClient client = new NetworkClient.Builder()
    .packetHandler(packetHandler)
    .sslEnabled(false)
    .build();
client.connect("127.0.0.1", 25565);
```

### TLS with TrustStore (Server Validation)
```java
KeyStore serverKeyStore = loadStore("certs/server.p12", "changeit".toCharArray());
KeyStore clientTrustStore = loadStore("certs/client-trust.p12", "changeit".toCharArray());
EventManager eventManager = new EventManager();

NetworkServer server = new NetworkServer.Builder()
    .packetHandler(packetHandler)
    .eventManager(eventManager)
    .sslEnabled(true)
    .clientAuthMode(ClientAuthMode.NONE)
    .keyStore(serverKeyStore, "changeit".toCharArray())
    .build();
server.start(25565, 25566);

NetworkClient client = new NetworkClient.Builder()
    .packetHandler(packetHandler)
    .sslEnabled(true)
    .trustStore(clientTrustStore)
    .build();
client.connect("127.0.0.1", 25565);
```

### TLS with Client Certificate (mTLS)
```java
KeyStore serverKeyStore = loadStore("certs/server.p12", "changeit".toCharArray());
KeyStore serverTrustStore = loadStore("certs/server-trust.p12", "changeit".toCharArray());
KeyStore clientKeyStore = loadStore("certs/client.p12", "changeit".toCharArray());
KeyStore clientTrustStore = loadStore("certs/client-trust.p12", "changeit".toCharArray());
EventManager eventManager = new EventManager();

NetworkServer server = new NetworkServer.Builder()
    .packetHandler(packetHandler)
    .eventManager(eventManager)
    .sslEnabled(true)
    .clientAuthMode(ClientAuthMode.REQUIRED)
    .keyStore(serverKeyStore, "changeit".toCharArray())
    .trustStore(serverTrustStore)
    .build();
server.start(25565, 25566);

NetworkClient client = new NetworkClient.Builder()
    .packetHandler(packetHandler)
    .sslEnabled(true)
    .keyStore(clientKeyStore, "changeit".toCharArray())
    .trustStore(clientTrustStore)
    .build();
client.connect("127.0.0.1", 25565);
```

## Certificates for NetworkSystem
### Create Root CA
```bash
openssl genrsa -out myCA.key 4096
openssl req -x509 -new -key myCA.key -sha256 -days 365 -out myCA.pem -addtext basicConstraints=critical,CA:TRUE -addtext keyUsage=critical,keyCertSign,cRLSign
```
- `myCA.key`: private CA key (keep secret)
- `myCA.pem`: public root certificate

### Create Server Certificate Based on Root CA
```bash
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr
openssl x509 -req -in server.csr -CA myCA.pem -CAkey myCA.key -CAcreateserial -out server.crt -days 365 -sha256
```
- `server.key`: private server key
- `server.crt`: server certificate signed by your root CA

### Optional: Create Client Certificate Based on Root CA
```bash
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr
openssl x509 -req -in client.csr -CA myCA.pem -CAkey myCA.key -CAcreateserial -out client.crt -days 365 -sha256
```
- `client.key`: private client key
- `client.crt`: client certificate signed by your root CA

### Helper: Load PKCS12 Store in Java
```java
private static KeyStore loadStore(String path, char[] password) throws Exception {
    KeyStore store = KeyStore.getInstance("PKCS12");
    try (FileInputStream in = new FileInputStream(path)) {
        store.load(in, password);
    }
    return store;
}
```

## License
### GNU General Public License v3.0 (GPLv3)
Default license for all users, projects, and distributions unless explicitly
agreed otherwise.

- License file in project: `LICENSE`
- Reference: https://repo.unlegitdqrk.dev/UnlegitDqrk/UnlegitLibrary/src/LICENSE

### Open Autonomous Public License (OAPL)
Special exception exclusively for the Open Autonomous Connection (OAC) project.
Within that context, OAPL terms take precedence.

- Reference: https://repo.open-autonomous-connection.org/Open-Autonomous-Connection/OAPL