[Epic] Share a current Minecraft session through Connect

[robinbraemer]

Vision

Let a Minecraft player install the Connect client mod, press Share with
Connect, and let friends join the current single-player world. Vanilla Java
clients join through Minekube Connect. When both players have the mod, they
prefer direct libp2p connectivity where possible.

The long-term experience may also share the multiplayer server the host is
currently playing on. Build single-player sharing first. Treat multiplayer
relay as a separate later phase because it introduces third-party server
policy, authentication, virtual-host handshake, IP reputation, and rate-limit
concerns.

Phase 1 product decisions

• Fabric first, targeting Minecraft 1.21.11 and 26.2.
• Product logic is Kotlin and shared across both Minecraft versions.
• The host uses a dedicated Share with Connect action; Open to LAN is not
  required.
• The mod binds no publicly reachable Minecraft LAN or WAN listener.
• Each Minecraft installation creates and persists one Connect endpoint name
  and token, using the same token-file model as the Connect plugin.
• A player may instead import the exact endpoint name and dashboard-issued
  token for an endpoint they already own.
• Every world and share reuses that endpoint identity. Starting a world must
  not create another control-plane endpoint record.
• Stopping the share makes the stable hostname unreachable until sharing
  starts again.
• The endpoint identity is replaced only through an explicit, warned
  Reset Connect identity action. Authentication errors must never rotate it
  automatically.
• Online and offline-mode Java guests are supported. Profiles authenticated by
  Connect or Mojang may retain host approval for the current share; locally
  accepted offline identities are visibly unverified and approved per
  connection so a copied username cannot inherit approval.
• Modded peers automatically try direct libp2p on the same LAN.
• Internet-direct libp2p is attempted only when both peers opt in because it
  exposes their IP addresses to each other.
• Minekube Connect is the sole relay fallback. The mod does not operate or ask
  users to self-host another relay.

Host experience

1. Open a single-player world.
2. Select Share with Connect from the pause menu.
3. Create one Connect identity or import an existing dashboard endpoint and
   token.
4. Choose game mode, cheats, guest capacity, and whether to allow
   internet-direct attempts.
5. Start sharing.
6. Copy the stable Connect hostname for vanilla guests or the signed,
   per-share invitation for modded guests.
7. Approve or deny each player with their authentication level displayed.
8. Stop sharing explicitly or by leaving the world/closing Minecraft.

No port forwarding, router configuration, dedicated server, or server plugin
is required.

Persistent Connect identity

Store one identity per mod installation:

config/minekube-connect-share/config.json
config/minekube-connect-share/token.json

token.json uses the plugin-compatible {"token":"T-..."} shape. The token
is created once, protected with owner-only permissions where supported, never
included in invitations, and redacted from logs and UI. Standard
CONNECT_ENDPOINT and CONNECT_TOKEN environment variables override stored
values.

The import path accepts an endpoint name plus a pasted dashboard token or an
existing plugin-compatible token.json. It stages the pair, validates it
against Connect while rejecting player proposals, and atomically replaces
stored credentials only after success. Bad credentials, wrong organization,
network failure, cancellation, or crashes leave the prior identity unchanged.
The same path updates a token after the endpoint owner resets it in the
Dashboard.

World IDs and share IDs must never influence the endpoint name. A new share
rotates only ephemeral state: admission approvals, share capability, signed
invitation, and direct-peer identity.

Hybrid connection behavior

For a modded guest:

1. Try same-LAN direct libp2p.
2. If both peers consented, try direct internet candidates/hole punching.
3. Fall back to the persistent Connect hostname.
4. If Connect is unavailable and no direct path works, show an actionable
   failure; do not introduce an independent relay.

Vanilla guests use the Connect hostname. Connect sessions and direct sessions
converge on the same host admission policy and integrated-server connection
pipeline. Managed non-passthrough Connect profiles are trusted as
Connect-authenticated for paid or non-paid accounts. Direct online guests
complete normal Mojang/Microsoft authentication; direct offline guests are
explicitly marked unverified and never receive an automatic downgrade from
failed online authentication.

Phase 1 required work

• Add Kotlin/Fabric multi-version modules with a loader-neutral common core.
• Reuse Connect Java's endpoint registration, local-channel bridge, watch
  lifecycle, and isolated libp2p runtime.
• Publish the integrated server privately and inject external sessions without
  a public bind.
• Persist and reuse the Connect endpoint identity across worlds.
• Import and safely validate dashboard-created endpoint credentials.
• Implement current-share admission for Connect- or Mojang-authenticated UUIDs
  and per-connection admission for locally unverified offline identities,
  including allow, deny, timeout, capacity, rate limiting, and cleanup.
• Implement signed, expiring mod invitations.
• Implement same-LAN direct discovery/dialing.
• Implement opt-in internet-direct attempts and Connect fallback.
• Add host and guest UI, redaction, lifecycle cleanup, packaging, and separate
  mod release automation.

Acceptance criteria

• A host behind NAT shares a 1.21.11 or 26.2 single-player world without Open
  to LAN or port forwarding.
• An unmodified Java client joins through Connect and requires host approval.
• Online and offline-mode Java clients can join through Connect. Locally
  accepted offline identities are clearly labeled unverified and require new
  approval after reconnecting.
• At least two remote friends can join concurrently while the local host
  remains connected.
• A different world reuses the exact endpoint name and token; repeated shares
  do not create endpoint records.
• A dashboard-created endpoint and token can be imported and reused without
  creating another endpoint, preserving its public hostname and attached
  dashboard configuration.
• Rejecting a bad import leaves the prior working identity intact.
• Stopping sharing makes the hostname unreachable, and an old signed mod
  invitation cannot authorize a later share.
• Two modded players on one LAN can join directly with Connect unavailable.
• Internet-direct dialing never starts without confirmation on both peers.
• Failed direct connectivity falls back to Connect exactly once.
• Start/stop can be repeated without leaked listeners, threads, registrations,
  or stale routing.
• World exit, game shutdown, Connect outage, and tunnel failure fail closed
  with understandable UI state.
• Another machine cannot reach a Minecraft listener on the physical LAN unless
  the host separately uses vanilla Open to LAN.
• Tests cover identity persistence/import, admission, invitations, session
  bridging, transport ordering, isolation, cleanup races, both Fabric targets,
  and failure recovery.

Phase 2 — current multiplayer server relay

When the host is connected to a remote server, potentially create one
independent outbound connection per invited friend and tunnel it to that
target. Do not multiplex the host connection.

Before implementation, resolve:

• end-to-end versus Connect-edge authentication;
• preservation or rewriting of the original handshake hostname and SRV target;
• compatibility with proxies, online mode, secure profiles, resource packs,
  and protocol-version translation;
• third-party server consent and terms;
• all relayed players appearing behind the host IP;
• anti-bot, rate-limit, ban, abuse, and bandwidth implications; and
• Realms and servers that prohibit proxies or VPNs.

Non-goals for Phase 1

• Bedrock clients
• Realms sharing
• Current multiplayer-server relay
• World synchronization or host migration
• Friend graph or persistent invitations
• UPnP/public Minecraft TCP listeners
• Independent or self-hosted libp2p relays
• NeoForge, Forge, or Quilt artifacts
• Arbitrary TCP tunneling

Delivery notes

The detailed reviewed design lives in
docs/superpowers/specs/2026-07-30-connect-share-mod-design.md on the feature
branch. Plugin release, mod publication, Connect edge/API compatibility, and
production rollout are separate gates. A released mod alone does not mean the
feature is live.

[robinbraemer]

Implementation update from codex/connect-share-mod (rebased onto main / 0.13.3):

Implemented:

• Kotlin Fabric clients for Minecraft 1.21.11 (Java 21) and 26.2 (Java 25), with Arrow 2.2.3 established as the default Kotlin toolkit in share/AGENTS.md.
• Persistent per-installation Connect endpoint/token reuse, dashboard endpoint import, plugin-compatible token.json, and environment overrides.
• Loopback-only integrated-server publication; no Minecraft LAN/WAN listener and no Open to LAN requirement.
• Vanilla guest ingress through Connect with host approval and authenticated or explicitly unverified offline identities.
• Ephemeral signed invitations, mDNS LAN discovery, Noise/Yamux/TCP libp2p streams, host/guest loopback proxies, and no libp2p relay support.
• Automatic same-LAN direct routing, dual host/guest consent for internet-direct attempts, exactly-once Connect fallback, and direct-only degraded operation when Connect is unavailable.
• Native host setup/status/admission UI and title-screen Join Connect Share UI for both versions, including path labels and IP-disclosure warnings.
• Child-runtime packaging checks that instantiate the packaged direct node and prove its implementation loads from the isolated nested payload.

Verification:

• ./gradlew build: PASS (109 tasks).
• Both exact client targets reached the fully loaded title-screen/resource state with their mixins applied; only expected unauthenticated dev-session Mojang/Realms 401s appeared.
• Final artifacts contain no top-level libp2p, Netty, or Kotlin runtime packages; the nested payload contains the direct implementation plus libp2p/Netty.
• Manual acceptance procedure expanded in docs/connect-share-testing.md.

Still requiring external acceptance before release-ready status:

• A real two-machine same-LAN join.
• A live vanilla guest join through Connect with deny/allow coverage.
• A genuinely reachable internet-direct attempt and forced direct-failure to live Connect fallback.
• Listener scans and repeated lifecycle leak checks on both supported Minecraft versions.

The Epic should remain open until those real-network checks and release/product follow-up are completed.