New README
This commit is contained in:
148
README.md
148
README.md
@@ -1,102 +1,122 @@
|
|||||||
# BukkitstrPlugin
|
# BukkitstrPlugin
|
||||||
|
|
||||||
BukkitstrPlugin is a Minecraft plugin that integrates with the Nostr relay to authenticate players. Players must authenticate by signing a valid Nostr event before they can move in the game.
|
BukkitstrPlugin is a Minecraft (Spigot/Paper) plugin that integrates with a Nostr relay via WebSockets to authenticate players before they can move in-game. It leverages Nostr events (kinds 30078 for profile metadata and 13378008 for authentication) tagged with `d=mcauth` to verify a player's Nostr public key and their Minecraft username. This ensures a secure and decentralized method of authentication, leveraging the power of the Nostr protocol to validate player identities seamlessly.
|
||||||
|
|
||||||
## Demo
|
|
||||||
<video height="480" width="270" controls src="https://v.nostr.build/5XxsgV03wlo1iCPW.mp4"></video>
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **WebSocket Integration**: Connects to a Nostr relay using WebSockets.
|
* 🌐 **WebSocket Integration**: Connects to a configurable Nostr relay for real-time event communication and monitoring.
|
||||||
- **Player Authentication**: Players must authenticate with their Minecraft username via a Nostr event.
|
* 👤 **Profile Verification**: Checks for a kind 30078 Nostr event containing the player's Minecraft username, ensuring proper identity binding.
|
||||||
- **Movement Lock**: Prevents players from moving until they are authenticated.
|
* 🔑 **Event-based Authentication**: Subscribes to kind 13378008 Nostr events to authenticate players based on signed Nostr messages.
|
||||||
- **Real-time Messaging**: Sends and receives messages from the Nostr relay in real-time.
|
* 🚫 **Movement Lock**: Prevents unauthenticated players from moving in the game, providing a clear incentive to complete verification.
|
||||||
|
* 🧩 **Concurrent Auth Handling**: Supports multiple concurrent authentication attempts, allowing simultaneous joins without conflict.
|
||||||
|
* 🧱 **Built-in Resilience**: Reconnects to the WebSocket on failure and retries authentication flow.
|
||||||
|
* 📝 **Detailed Logging**: Logs each authentication step to help track errors and validate successful verification.
|
||||||
|
|
||||||
## Prerequisites
|
## Prerequisites
|
||||||
|
|
||||||
- **Java 8 or higher**
|
* ☕ Java 8+ (or higher) - Needed to compile and run the plugin.
|
||||||
- **Maven** (for building the plugin)
|
* 📦 Maven 3.x - Required for building the plugin from source.
|
||||||
- **Spigot/Paper** server (Minecraft 1.20 or higher)
|
* 🎮 Spigot/Paper server (Minecraft 1.20+) - Compatible with modern Minecraft servers.
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
1. **Clone the repository**:
|
1. 📥 **Clone the repository**
|
||||||
```sh
|
|
||||||
|
```bash
|
||||||
git clone https://git.vanderwarker.family/nostr/bukkitstr.git
|
git clone https://git.vanderwarker.family/nostr/bukkitstr.git
|
||||||
cd bukkitstr
|
cd bukkitstr
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Configure the plugin**:
|
2. 🛠️ **Configure the relay URL**
|
||||||
Make sure to replace `wss://your-nostr-relay-url` in the `BukkitstrPlugin.java` file with your actual Nostr relay WebSocket URL.
|
|
||||||
|
|
||||||
3. **Build the plugin**:
|
In `src/main/java/family/vanderwarker/bukkitstr/BukkitstrPlugin.java`, update the WebSocket URI to your Nostr relay address (default is `ws://localhost:10547`). This relay will be the core communication point for receiving and validating Nostr events:
|
||||||
```sh
|
|
||||||
mvn clean package
|
```java
|
||||||
|
URI uri = new URI("ws://localhost:10547");
|
||||||
```
|
```
|
||||||
|
|
||||||
4. **Copy the plugin JAR**:
|
|
||||||
Copy the generated `bukkitstr-plugin-1.0-SNAPSHOT.jar` file from the `target` directory to your Minecraft server's `plugins` directory.
|
|
||||||
|
|
||||||
5. **Start your server**:
|
> **ℹ️ Quick Relay Setup with `nak`**
|
||||||
Start your Minecraft server and check the console for any errors. The plugin should initialize and connect to the Nostr relay.
|
> To spin up a temporary Nostr relay locally, install and use `nak` from [the nak repository](https://git.vanderwarker.family/nostr/nak):
|
||||||
|
> ```bash
|
||||||
|
> nak serve
|
||||||
|
> ```
|
||||||
|
> This starts a relay at `ws://localhost:10547` for testing purposes.
|
||||||
|
|
||||||
## Usage
|
3. 🏗️ **Build the plugin**
|
||||||
|
Run the following Maven command to build the JAR file:
|
||||||
|
```bash
|
||||||
|
mvn clean package
|
||||||
|
```
|
||||||
|
This creates the JAR under the `target/` directory.
|
||||||
|
|
||||||
### Authentication Command
|
4. 🚀 **Deploy**
|
||||||
|
|
||||||
Players need to use the `/auth` command to start the authentication process. The plugin will wait for a Nostr event containing the player's Minecraft username in the `d` tag content.
|
- 📁 Copy the generated JAR (`target/bukkitstr-plugin-1.0-SNAPSHOT.jar`) into your server's `plugins/` directory.
|
||||||
|
- 🔄 Start or reload your Spigot/Paper server to activate the plugin.
|
||||||
|
- 📃 Review the logs for initialization status and any connection errors to the relay.
|
||||||
|
|
||||||
```sh
|
## Configuration
|
||||||
/auth
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sign Event
|
Currently, there are no external configuration files. All configuration such as relay URI and internal logging behavior is hardcoded in the plugin source. To change the Nostr relay URL or logging settings, modify `BukkitstrPlugin.java` and rebuild. Future versions may include a `config.yml` file to simplify configuration for server admins.
|
||||||
|
|
||||||
Next, you need to sign a event kind "13378008" and the "d" tag to be your Minecraft username.
|
## Commands
|
||||||
|
|
||||||
Using [nostril](https://github.com/jb55/nostril) is quite easy.
|
| Command | Description |
|
||||||
```sh
|
|--------------|-------------------------------------------------------------------|
|
||||||
nostril --kind 13378008 --tag "d" "MinecraftUsername"
|
| `/nostrauth <pubkey>` | Begins the Nostr authentication process for the given public key. |
|
||||||
```
|
|
||||||
|
|
||||||
Then send to the relay you've specified in src/../BukkitstrPlugin.java
|
This command kicks off the authentication process and informs the player of their current verification status. Additional commands may be introduced later to support logging out or checking current auth status.
|
||||||
|
|
||||||
|
### Authentication Flow
|
||||||
|
|
||||||
### Player Authentication Process
|
1. 🏁 **Start Authentication**
|
||||||
|
- Player runs `/nostrauth <pubkey>` in-game.
|
||||||
|
- Plugin sends a subscription for kind `30078` with `#d=["mcauth"]` to fetch profile metadata.
|
||||||
|
- The user must ensure their Nostr profile metadata includes a valid reference to their Minecraft username.
|
||||||
|
|
||||||
1. **Connect to the Nostr relay**: The plugin connects to the specified Nostr relay when the server starts.
|
2. ✅ **Profile Verification**
|
||||||
2. **Send Authentication Request**: The plugin sends an initial request to the Nostr relay to listen for authentication events.
|
- The plugin checks the received event’s `content` (expected to be the Minecraft username).
|
||||||
3. **Wait for Nostr Event**: When a player uses the `/auth` command, the plugin waits for a Nostr event containing the player's username in the `d` tag.
|
- If the username matches the in-game player name, the plugin proceeds; otherwise, it aborts.
|
||||||
4. **Authenticate Player**: If the received Nostr event's `d` tag content matches the player's username, the player is authenticated and can move freely. Otherwise, they will receive an authentication failure message.
|
- This check ensures that players are truly the owners of the Nostr public key provided.
|
||||||
|
|
||||||
## Developer Information
|
3. 🔄 **Auth Event Subscription**
|
||||||
|
- Plugin subscribes to kind `13378008` events tagged `#d=["mcauth"]` for the same pubkey.
|
||||||
|
- Player signs and sends a Nostr event with kind `13378008` and content set to their Minecraft username.
|
||||||
|
- A unique challenge can be added in future versions for extra security.
|
||||||
|
|
||||||
### Source Code
|
4. 🟢 **Authentication Success**
|
||||||
|
- If the incoming event matches the expected content and pubkey, the player is marked authenticated and can move.
|
||||||
|
- Authentication is stored in memory and may be cached using local storage in the future.
|
||||||
|
- Authentication expires after ~30 days for security.
|
||||||
|
|
||||||
The main source code is located in the `src/main/java/family/vanderwarker/bukkitstr/BukkitstrPlugin.java` file.
|
5. ⛔ **Movement Restriction**
|
||||||
|
- Until authenticated, any `PlayerMoveEvent` is cancelled and the player is prompted to authenticate.
|
||||||
|
- Players are periodically reminded to complete authentication if they haven't already.
|
||||||
|
|
||||||
### Dependencies
|
## Developing
|
||||||
|
|
||||||
Ensure the following dependencies are added to your `pom.xml`:
|
1. 🧠 Import the project into your IDE (IntelliJ IDEA, Eclipse, etc.).
|
||||||
|
2. ✏️ Modify source under `src/main/java/family/vanderwarker/bukkitstr/` to change plugin logic.
|
||||||
|
3. 🛠️ Run `mvn clean package` to build after changes.
|
||||||
|
4. 🧪 Test on a local Spigot/Paper instance to verify the changes.
|
||||||
|
5. 🧰 Use in-game logs and console output to debug behavior and confirm expected flow.
|
||||||
|
|
||||||
```xml
|
## Troubleshooting
|
||||||
<dependencies>
|
|
||||||
<dependency>
|
|
||||||
<groupId>org.java-websocket</groupId>
|
|
||||||
<artifactId>Java-WebSocket</artifactId>
|
|
||||||
<version>1.5.2</version>
|
|
||||||
</dependency>
|
|
||||||
<dependency>
|
|
||||||
<groupId>com.fasterxml.jackson.core</groupId>
|
|
||||||
<artifactId>jackson-databind</artifactId>
|
|
||||||
<version>2.13.3</version>
|
|
||||||
</dependency>
|
|
||||||
</dependencies>
|
|
||||||
```
|
|
||||||
|
|
||||||
## Acknowledgments
|
- ❌ **Invalid URI**: Ensure the relay URL is valid and reachable over the network. Check firewall or NAT settings.
|
||||||
|
- 🕵️ **No Profile Found**: Make sure you have created a kind `30078` Nostr event with tag `d=mcauth` containing your Minecraft username. This acts as your identity declaration.
|
||||||
|
- 📭 **Auth Event Missing**: Sign and publish a kind `13378008` Nostr event with tag `d=mcauth` and content set to your Minecraft username using your preferred Nostr client or automation tool.
|
||||||
|
- 📊 **Debugging Tips**: Enable verbose logs by adding custom logging hooks inside the Java source. Check WebSocket connection status during runtime.
|
||||||
|
|
||||||
- Thanks to the SpigotMC community for their documentation and support.
|
## Contributing
|
||||||
- Thanks to the Nostr community for their innovative protocol.
|
|
||||||
- Thanks to [npub1826v365he5ty69lk3xgvzqrwy8587vdfrxnsz0k09khzustf8r7s6j7t95](nostr:npub1826v365he5ty69lk3xgvzqrwy8587vdfrxnsz0k09khzustf8r7s6j7t95)
|
🤝 Contributions and pull requests are welcome! Please fork the repository and open a merge request. Suggestions for new features such as challenge-response authentication, persistent auth storage, and permission integration are appreciated. All contributors should follow standard Java coding practices.
|
||||||
- Thanks to ChatGPT 4.o
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
📄 This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
|
||||||
|
|
||||||
|
This plugin is provided "as is", without warranty of any kind. Use at your own risk in production environments. Contributions are welcome to improve reliability and expand features!
|
||||||
|
|
||||||
|
````
|
||||||
|
|||||||
Reference in New Issue
Block a user