nostr/bukkitstr
1
0
Fork 0
Code Issues Pull Requests Packages Releases 1 Activity

New README

Browse Source
This commit is contained in:
Stephen Vanderwarker
2025-05-10 08:07:11 -04:00
parent ecb801b7d5
commit a1b3b1662b
1 changed files with 84 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
README.md
View File

@@ -1,102 +1,122 @@
# 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.
## Demo
<video height="480" width="270" controls src="https://v.nostr.build/5XxsgV03wlo1iCPW.mp4"></video>
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.
## Features
- **WebSocket Integration**: Connects to a Nostr relay using WebSockets.
- **Player Authentication**: Players must authenticate with their Minecraft username via a Nostr event.
- **Movement Lock**: Prevents players from moving until they are authenticated.
- **Real-time Messaging**: Sends and receives messages from the Nostr relay in real-time.
* 🌐 **WebSocket Integration**: Connects to a configurable Nostr relay for real-time event communication and monitoring.
* 👤 **Profile Verification**: Checks for a kind 30078 Nostr event containing the player's Minecraft username, ensuring proper identity binding.
* 🔑 **Event-based Authentication**: Subscribes to kind 13378008 Nostr events to authenticate players based on signed Nostr messages.
* 🚫 **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
- **Java 8 or higher**
- **Maven** (for building the plugin)
- **Spigot/Paper** server (Minecraft 1.20 or higher)
* ☕ Java 8+ (or higher) - Needed to compile and run the plugin.
* 📦 Maven 3.x - Required for building the plugin from source.
* 🎮 Spigot/Paper server (Minecraft 1.20+) - Compatible with modern Minecraft servers.
## Installation
1. **Clone the repository**:
```sh
1. 📥 **Clone the repository**
```bash
git clone https://git.vanderwarker.family/nostr/bukkitstr.git
cd bukkitstr
```
2. **Configure the plugin**:
Make sure to replace `wss://your-nostr-relay-url` in the `BukkitstrPlugin.java` file with your actual Nostr relay WebSocket URL.
2. 🛠️ **Configure the relay URL**
3. **Build the plugin**:
```sh
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:
```java
URI uri = new URI("ws://localhost:10547");
```
> **ℹ️ Quick Relay Setup with `nak`**
> 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.
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.
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.
4. 🚀 **Deploy**
5. **Start your server**:
Start your Minecraft server and check the console for any errors. The plugin should initialize and connect to the Nostr relay.
- 📁 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.
## Usage
## Configuration
### Authentication Command
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.
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.
## Commands
```sh
/auth
```
| Command | Description |
|--------------|-------------------------------------------------------------------|
| `/nostrauth <pubkey>` | Begins the Nostr authentication process for the given public key. |
### Sign Event
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.
Next, you need to sign a event kind "13378008" and the "d" tag to be your Minecraft username.
### Authentication Flow
Using [nostril](https://github.com/jb55/nostril) is quite easy.
```sh
nostril --kind 13378008 --tag "d" "MinecraftUsername"
```
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.
Then send to the relay you've specified in src/../BukkitstrPlugin.java
2. ✅ **Profile Verification**
- The plugin checks the received event’s `content` (expected to be the Minecraft username).
- If the username matches the in-game player name, the plugin proceeds; otherwise, it aborts.
- This check ensures that players are truly the owners of the Nostr public key provided.
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.
### Player Authentication Process
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.
1. **Connect to the Nostr relay**: The plugin connects to the specified Nostr relay when the server starts.
2. **Send Authentication Request**: The plugin sends an initial request to the Nostr relay to listen for authentication events.
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.
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.
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.
## Developer Information
## Developing
### Source Code
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.
The main source code is located in the `src/main/java/family/vanderwarker/bukkitstr/BukkitstrPlugin.java` file.
## Troubleshooting
### Dependencies
- ❌ **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.
Ensure the following dependencies are added to your `pom.xml`:
## Contributing
```xml
<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>
```
🤝 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.
## Acknowledgments
## License
- Thanks to the SpigotMC community for their documentation and support.
- Thanks to the Nostr community for their innovative protocol.
- Thanks to [npub1826v365he5ty69lk3xgvzqrwy8587vdfrxnsz0k09khzustf8r7s6j7t95](nostr:npub1826v365he5ty69lk3xgvzqrwy8587vdfrxnsz0k09khzustf8r7s6j7t95)
- Thanks to ChatGPT 4.o
📄 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!
````