bukkitstr/README.md

# BukkitstrPlugin

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 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) - 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**

   ```bash
   git clone https://git.vanderwarker.family/nostr/bukkitstr.git
   cd bukkitstr
   ```

2. 🛠️ **Configure the relay URL**

   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. 🚀 **Deploy**

   - 📁 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.

## Configuration

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.

## Commands

| Command      | Description                                                       |
|--------------|-------------------------------------------------------------------|
| `/nostrauth <pubkey>` | Begins the Nostr authentication process for the given public key. |

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

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.

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.

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.

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.

## Developing

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.

## Troubleshooting

- ❌ **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.

## 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!

````