Epic: Connect Share friends and single-player world sharing

[robinbraemer]

Goal

Build a Fabric client mod that lets a player share a single-player world with friends once, then keeps that friendship usable across world switches, restarts, LAN changes, and public IP changes.

Product behavior

• A host chooses Share with friends from the pause menu; no Open to LAN step is required.
• The first signed minekube://share/... link behaves like a friend request and only needs to be accepted once.
• Saved friends can be renamed, notified when a world is ready, allowed to join automatically, or removed.
• Sharing remains enabled across world switches and host rejoins until the host explicitly stops it.
• Join requests and friend-online events appear as global in-game notifications, while requests remain actionable in the Share screen.
• The UI is friends-first and hides transport details under advanced settings.

Routing

Choose the best route automatically in this order:

1. Signed libp2p direct connection on the LAN when both players have the mod.
2. Direct internet libp2p where reachable and explicitly enabled.
3. Minekube Connect as the NAT/relay fallback. Users do not need to self-host a relay.

Vanilla LAN discovery must not be duplicated as a second visible server list. Discovery is only a silent route optimization for saved friends.

Identity and security

• Persist one stable libp2p identity and one stable Share capability across worlds.
• Reuse the existing Connect endpoint and endpoint token; never create a database endpoint per world.
• Support importing an endpoint token created in the Minekube dashboard.
• Verify signed friend cards and match saved peer ID, public key, Share ID, and capability before direct join.
• Exchange reciprocal friend cards only after an approved Connect Share admission and explicit client consent.
• Authenticated Minecraft UUIDs may support future Connect fallback joins; offline-mode UUIDs must never be treated as trusted identity. Offline-mode friends use the signed libp2p peer identity and remain supported.
• Removing a friend revokes local automatic trust; later attempts require host approval.

Implementation constraints

• Fabric, Kotlin, and bundled Fabric Language Kotlin for low-friction installation.
• Support Minecraft 1.21.11 and 26.2 from shared version-independent code where possible.
• Use Arrow as the default Kotlin toolkit per share/AGENTS.md, including typed Either failures, resource safety, and bounded structured concurrency.
• Keep Connect plugin release, any hub image update, and production rollout separate from the mod artifact.

Acceptance criteria

• A friend saves one link, joins once with host approval, and both sides persist the relationship.
• The host closes Minecraft, changes world or network, reopens a world, and the saved friend can see it become ready without another link.
• Same-LAN friends use direct libp2p when available; otherwise the join succeeds through the saved Connect endpoint.
• An approved saved friend can join automatically by signed direct peer identity, or by an authenticated Minecraft identity over Connect.
• Offline-mode players work but cannot gain UUID-based automatic trust.
• The mod loads and the complete join flow works in PrismLauncher on Minecraft 26.2.
• Both Fabric targets pass their module tests and the repository build passes.