How zerozshare/openfriendcore works
1. Top-level shape
- This repo is a single Go CLI binary (cmd/openfriend) rather than a multi-service system.
- The executable is orchestrating three main runtime roles: authenticate, broadcast presence, and bridge Minecraft connections.
2. CLI entrypoint and mode selection
- cmd/openfriend/main.go and its helpers (paths.go, reset.go, skin.go, selfupdate.go, joinrunner.go, watch_parent.go) provide the user-facing commands and flags.
- The key modes are:
- Host mode: accept incoming Friends List joins and forward them to a local Minecraft server.
- Join mode: expose a local TCP port so the user’s Minecraft client can join a friend’s world through OpenFriend.
- Reset / skin / update utilities that operate on local state or external services.
3. Authentication subsystem
- internal/auth handles the full Microsoft/Xbox/Mojang authentication chain.
- It includes device-code login, token exchange, session management, and cryptographic storage so credentials can be reused across runs.
- The persistent session is saved locally as an encrypted auth file in the data directory, which is why the app can start without re-login after the first device-code flow.
4. Persistent local state
- The CLI stores machine-local state next to the binary or under the configured --data-dir.
- Main artifacts include:
- auth.pem for encrypted credentials
- status.json for runtime/status bookkeeping
- optional bypass.pem for the online-mode bypass key
- This local state is the boundary between long-lived identity/configuration and transient runtime connections.
5. Minecraft/Friends List API layer
- internal/api is a typed client for the Minecraft Java Edition friends-related backend.
- It covers:
- friend/profile resolution
- presence queries
- skin-related operations
- ID normalization helpers
- This layer is where the app translates between human-friendly names/PMIDs and the identifiers required by the backend services.
6. Presence broadcasting
- internal/presence is responsible for keeping the user visible on the Friends List.
- The broadcaster and refresher components periodically update the external presence state using the authenticated API client.
- This is the subsystem that makes OpenFriend “show up” to other players as joinable.
7. Signaling and peer setup
- internal/signaling manages the WebRTC-side negotiation used for Friends List joins.
- It includes:
- signaling client logic
- JSON-RPC message handling
- dispatch/endpoint definitions
- TURN configuration and transport helpers
- Architecturally, this is the control plane that sets up peer connectivity before any Minecraft bytes start flowing.
8. Bridge layer: WebRTC to TCP
- internal/bridge is the core data-plane adapter.
- It handles the handshake, session establishment, and TCP forwarding between:
- the remote Friends List/WebRTC peer connection
- the local or backend Minecraft TCP server
- In host mode, OpenFriend accepts an incoming join and forwards traffic to a configured backend server.
- In join mode, OpenFriend exposes a local TCP listener so the user’s Minecraft client can talk to a friend’s world through the negotiated peer connection.
9. Optional bypass support
- internal/bypass contains support for the shared-key path used for the online-mode bypass.
- The README explicitly says this is implemented but not yet fully verified end-to-end, and current practical usage is offline-mode servers only.
- For architecture diagrams, treat this as an optional authentication bypass branch that is not part of the default offline-mode bridge path.
10. Skin handling
- internal/skinimg validates and processes PNG skin images.
- The CLI can upload a selected skin so the Friends List icon/appearance reflects that image.
- This is a side channel into the presence/profile layer, not part of the TCP bridge.
11. Self-update and lifecycle management
- internal/update plus cmd/openfriend/selfupdate.go implement in-place binary replacement on supported platforms.
- watch_parent.go and the join runner utilities suggest the process can supervise child behavior and exit cleanly when the parent disappears.
- These are operational concerns around the main runtime, not part of the networking core.
12. External dependencies and boundaries
- The important external boundaries are:
- Microsoft login/device-code flow
- Xbox Live / Mojang authentication services
- Minecraft Friends List presence/signaling backend
- TURN/WebRTC infrastructure
- the target Minecraft TCP server
- The only local network service OpenFriend exposes is the TCP listener used in join mode; otherwise it is a client to remote services.
13. Supporting utilities
- internal/util provides common HTTP and UUID helpers used across auth, API, and signaling.
- internal/status appears to centralize runtime status representation used by the CLI and persisted status file.
14. How the system fits together
- The runtime sequence is: authenticate → refresh/broadcast presence → negotiate join via signaling → bridge traffic over TCP.
- The app is intentionally modular around those phases, so an architecture diagram should show separate lanes for identity/session, presence/control plane, and Minecraft traffic forwarding.
Main entry points: main.go Main CLI · client.go Signaling client · host.go Host bridge · join.go Join bridge
Components 27
CLI runtime
Entry commands, mode selection, and local lifecycle control.
- Main CLI · Command-line entrypoint that selects host, join, and utility modes.
cmd/openfriend/main.go - Join runner · Supervises join-mode lifecycle and process behavior around the main CLI.
cmd/openfriend/joinrunner.go - Paths · Resolves data-directory and file locations for persistent artifacts.
cmd/openfriend/paths.go - Reset · Clears or reinitializes local state and runtime bookkeeping.
cmd/openfriend/reset.go - Parent watch · Observes parent-process presence and supports clean shutdown behavior.
cmd/openfriend/watch_parent.go
Identity and state
Authentication, encrypted session storage, and persisted local state.
- Auth store · Persists encrypted credentials and reusable login state on disk.
internal/auth/store.go - Device login · Runs the Microsoft device-code authentication flow.
internal/auth/devicecode.go - Token chain · Handles Microsoft, Xbox, and Mojang token/session exchange.
internal/auth/tokens.go - Crypto · Encrypts and decrypts stored authentication material.
internal/auth/crypto.go - Status · Represents and persists runtime status bookkeeping.
internal/status/status.go
Control plane
Presence, signaling, and external service coordination.
- API client · Shared client for Minecraft Friends List backend calls.
internal/api/client.go - Friends API · Resolves friends, profiles, and join-related identifiers.
internal/api/friends.go - Presence API · Reads and writes presence state used for joinability.
internal/api/presence.go - Broadcaster · Keeps the user visible on Friends List by publishing presence updates.
internal/presence/broadcaster.go - Refresher · Periodically renews presence using the authenticated API client.
internal/presence/refresher.go - Signaling client · Coordinates WebRTC-side join negotiation with remote peers.
internal/signaling/client.go - JSON-RPC · Encodes and handles signaling messages over the transport.
internal/signaling/jsonrpc.go - TURN setup · Configures TURN and transport details for peer connectivity.
internal/signaling/turn.go
Minecraft bridge
Traffic forwarding between peer connectivity and TCP endpoints.
- Host bridge · Accepts incoming joins and forwards them to a backend Minecraft server.
internal/bridge/host.go - Join bridge · Exposes a local TCP listener for the Minecraft client in join mode.
internal/bridge/join.go - Handshake · Establishes the bridge session before bytes flow.
internal/bridge/handshake.go - TCP forward · Moves Minecraft traffic between the peer connection and the TCP endpoint.
internal/bridge/tcp.go - Bridge session · Tracks negotiated bridge state and active connection metadata.
internal/bridge/session.go
Operational tools
Skin, update, bypass, and status helpers.
- Bypass key · Supports the optional online-mode bypass key flow.
internal/bypass/key.go - Skin image · Validates and processes skin images for profile appearance.
internal/skinimg/skinimg.go - Updater · Performs in-place self-update and executable replacement.
internal/update/update.go - Utilities · Common HTTP and UUID helpers reused across subsystems.
internal/util/http.go
Connections 33
- Main CLI → Paths: resolves state · Locates persistent files and data directory for the current run.
- Main CLI → Device login: authenticates · Starts login when no reusable session is available.
- Main CLI → Broadcaster: broadcasts · Enters the presence loop after authentication.
- Main CLI → Signaling client: negotiates · Handles join signaling for host or join modes.
- Main CLI → Host bridge: host mode · Forwards incoming joins to a local Minecraft server.
- Main CLI → Join bridge: join mode · Creates the local listener used by the Minecraft client.
- Main CLI → Reset: utility · Runs state-reset operations when requested.
- Main CLI → Updater: self-update · Triggers in-place binary replacement when requested.
- Main CLI → Skin image: skin tool · Processes skin uploads from the CLI.
- Main CLI → Status: loads status · Reads and writes runtime bookkeeping.
- Device login → Token chain: exchanges · Completes the Microsoft/Xbox/Mojang token chain.
- Token chain → Crypto: seals · Encrypts material before persistence.
- Crypto → Auth store: persists · Writes encrypted auth state to disk.
- Auth store → Paths: uses paths · Reads the configured data-directory locations.
- API client → Utilities: helpers · Uses shared HTTP and UUID helpers.
- Broadcaster → Presence API: publishes · Updates presence through the backend API.
- Refresher → API client: refreshes via · Renewal loop uses the typed API client.
- Friends API → API client: served by · Friend and profile operations are issued through the shared client.
- Signaling client → JSON-RPC: encodes · Uses JSON-RPC messages for join negotiation.
- Signaling client → TURN setup: configures · Sets up TURN and transport parameters.
- Signaling client → Utilities: helpers · Reuses common utility functions.
- Host bridge → Handshake: starts · Begins session establishment for incoming joins.
- Join bridge → Handshake: starts · Begins session establishment for local-client joins.
- Handshake → Bridge session: creates · Creates the active bridge session state.
- Bridge session → TCP forward: drives · Session state governs traffic forwarding.
- TCP forward → Host bridge: serves · Host mode forwards to the backend Minecraft server.
- TCP forward → Join bridge: serves · Join mode forwards to the local Minecraft client listener.
- Host bridge → Signaling client: uses control plane · Relies on signaling to establish the peer connection.
- Join bridge → Signaling client: uses control plane · Relies on signaling to establish the peer connection.
- Bypass key → Host bridge: optional · Represents the optional online-mode bypass branch.
- Skin image → API client: uploads via · Skin operations feed the Friends List profile layer.
- Updater → Main CLI: replaces binary · Supports self-update of the running CLI.
- Status → Paths: stored under · Persists status data alongside other local state.