diff --git a/README.md b/README.md index ece725d..045998b 100644 --- a/README.md +++ b/README.md @@ -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 - +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 - mvn clean package + 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"); ``` -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**: - Start your Minecraft server and check the console for any errors. The plugin should initialize and connect to the Nostr relay. +> **โ„น๏ธ 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. -## 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 -/auth -``` +## Configuration -### 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. -```sh -nostril --kind 13378008 --tag "d" "MinecraftUsername" -``` +| Command | Description | +|--------------|-------------------------------------------------------------------| +| `/nostrauth ` | 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 ` 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. **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. +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. -## 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 - - - org.java-websocket - Java-WebSocket - 1.5.2 - - - com.fasterxml.jackson.core - jackson-databind - 2.13.3 - - -``` +## Troubleshooting -## 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. -- Thanks to the Nostr community for their innovative protocol. -- Thanks to [npub1826v365he5ty69lk3xgvzqrwy8587vdfrxnsz0k09khzustf8r7s6j7t95](nostr:npub1826v365he5ty69lk3xgvzqrwy8587vdfrxnsz0k09khzustf8r7s6j7t95) -- Thanks to ChatGPT 4.o +## Contributing + +๐Ÿค 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. + +## 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! + +````