Local Node

Hyprism.LocalNode is a companion process for autonomous local-profile sessions. It listens only on 127.0.0.1, so client requests do not depend on DNS or a remote authentication server

Managed lifecycle

LocalNodeServiceFactory allocates a free port from 8443–9999 and a separate LocalNode/Sessions/<session-id> directory for each launch. Accounts and certificates are shared across these sessions

1. GameLauncher creates a node and passes the active instance directory
2. LocalNodeHost prepares certificates and launches the companion
3. The launcher waits for HTTPS health, then creates a local session
4. Client preparation redirects supported services and supplies certificate trust
5. Once the game starts, the launcher attaches its PID to the node
6. The node follows the game lifetime even if Desktop closes

Before attachment, a managed node follows its launcher owner. Lifecycle requests require the per-process X-HyPrism-Control secret

HTTP surface

Group	Routes and behavior
Health and keys	/health, /.well-known/jwks.json, /jwks.json
Session creation	POST /v1/sessions, /game-session, /game-session/new
Session lifetime	/game-session/child, /game-session/refresh, DELETE /game-session
Server handshake	/game-session/authorize, /server-join/auth-grant, /server-join/auth-token, /game-session/exchange, /validate, /server/auto-auth
Account and profile	/my-account/game-profile, /my-account/get-profiles, /my-account/get-launcher-data, /profile/uuid/{uuid}, /profile/username/{username}
Character	/my-account/skin, /my-account/cosmetics, /account-data/skin/{uuid}, /player-skins and child routes
Lifecycle	POST /v1/lifecycle/attach, POST /v1/lifecycle/stop for managed processes
Compatibility	Configs, telemetry, presence settings, empty social and server-discovery responses

The host rejects unexpected Host headers and limits request bodies to 2 MiB. Compatibility routes do not provide a shared friends graph, invitations, cloud synchronization, NAT traversal, or public discovery

The route implementation is Sources/Hyprism.LocalNode/LocalNodeApplication.cs; tests live in Tests/Hyprism.LocalNode.Tests/LocalNodeHostTests.cs

Tokens and character state

Each selected local profile receives an ephemeral Ed25519 signing key. Identity handoff includes the private JWK required by DualAuth. JWKS, grants, and access tokens expose public key material only

Authorization validates the player's Bearer session separately from the target server identity in the request body. Access tokens bind the requested certificate fingerprint through cnf.x5t#S256. Refresh and child sessions reuse the profile key

The active character is included in the string-valued skin claim. The cosmetics catalog reads installed items from the active instance's Assets.zip and uses a small fallback when that archive is unavailable

Certificate trust

The shared authority is stored in LocalNode/Certificate. Its server certificate is valid for the IP address rather than a particular port

Platform	Trust setup
Windows	Add the local authority to the current user's root store when absent
Linux	Supply a combined CA bundle to the game process
macOS	Register the local authority in admin trust settings, potentially showing a system prompt, and supply a CA bundle
Java on every platform	Supply a dedicated PKCS#12 trust store

The server certificate rotates when invalid, issued by a different authority, missing the endpoint IP, or within seven days of expiry. The local authority lasts ten years unless invalid. Canceling the macOS trust prompt aborts the launch

Private .pfx files belong to local state and must not be distributed with screenshots, logs, or test fixtures

Standalone development

A standalone node defaults to port 8443 and LocalNodeData beside its executable. For an isolated run from the repository root

hyprism_node_data="$(mktemp -d)"
dotnet run --project Sources/Hyprism.LocalNode -- \
  --data-directory "$hyprism_node_data" \
  --port 8443

Standalone startup can also configure platform certificate trust. Prefer the automated Local Node suite for tests, which disables system trust changes and pins its generated certificate

Option	Meaning
--data-directory	Runtime state directory
--hostname	Must be 127.0.0.1
--port	Standalone port from 1024 through 65535
--assets-path	Installed Assets.zip for the cosmetics catalog
--certificate-directory	Reuse a certificate authority and server certificate
--account-data-directory	Shared account and skin storage
--log-file	Override the bounded node log
--request-journal	Override the unknown-request journal
--owner-pid, --control-secret	Managed lifecycle pair, both required together

Arguments use --name value pairs. Unknown and duplicate options are rejected

Diagnostics and compatibility

Managed logs use the launcher's session log directory. Authentication diagnostics omit headers, token values, and request bodies

Protocol compatibility follows the open hytale-auth-server implementation. Automated tests cover HTTPS, account persistence, tokens, certificates, process lifetime, and client patch transitions; a new proprietary Hytale build still needs a real game launch to verify end-to-end compatibility

Source: LocalNodeApplication, LocalNodeHostTests