minecraft-account-manager/docs/rcon.md

RCON administration

The administrator RCON console proxies commands through the Next.js server runtime. Browsers never receive RCON credentials and never open RCON sockets.

Command discovery and autocomplete

Select an enabled server and choose Refresh commands. The portal reads help, then its numbered pages, stripping Minecraft formatting codes and collecting slash-prefixed command entries and descriptions. Plugin/category headings are not executable suggestions. Discovery is best-effort: plugins can omit commands, customize help, or use unsupported formatting. Unknown commands remain freely enterable.

• Refresh is sequential and capped at 64 pages and 2,048 commands. Inconsistent pagination, limits, cancellation, or failed requests produce incomplete results rather than a complete-coverage claim.
• Type a command prefix to open suggestions. Arrow Up/Down selects; Tab/Enter inserts without executing; Escape dismisses. Mouse selection also inserts. With suggestions closed, Arrow Up/Down recalls submitted commands and restores the unsent draft. Enter then submits normally; the explicit submit button remains available.
• After a discovered command followed by whitespace is entered, a 350 ms debounce fetches help <command> once for usage hints. Wrapped usage remains readable. Balanced, bounded literal alternatives can suggest arguments, including nested alternatives; placeholders, optional/unsupported syntax, and overly complex usage are hints only, never invented values. This is not native Minecraft tab completion or live player-name completion.
• Commands, descriptions, and usage lookup results (including failures) stay in page memory, separately keyed by server ID, endpoint, and enabled state. Reload clears them; endpoint edits invalidate the matching cache. Refresh clears cached usage so failed lookups can be retried. Browsing already cached suggestions sends no RCON requests.
• Switching servers or submitting a manual command stops further discovery pages. An already-sent help request cannot be recalled; manual execution waits for that request to finish rather than racing it for the connection lock. Discovery and usage requests do not populate the console transcript or Arrow-key recall.
• Help requests use the same authorized, audited, bounded server-side command path as manual commands. Each request records a command audit event; responses and suggestion caches are not persisted. Help text is rendered as inert text, never HTML. Errors leave manual command entry available.

No additional Minecraft plugin, database migration, secret, or deployment setting is required for autocomplete.

Custom gear — vanilla-safe only

The Custom gear workshop below the terminal uses the same selected connection. Select an enabled server, Refresh players, choose a current Java player, then choose a weapon, tool or armor item. Portal registrations and historical logins are never evidence that someone is online. Refresh, server changes, endpoint edits and reload discard the recipient and any confirmation.

• Support is deliberately limited to Minecraft 26.2 / Purpur 2618 (5a85de0), using the bundled vanilla registry data. Every discovery/delivery checks bukkit:version; an unknown version is rejected. Purpur may initially answer only “Checking version”; refresh manually after it finishes. No automatic retries or version guesses. Plugins/datapacks that replace vanilla behavior are not certified by this catalog.
• The catalog contains 78 gear items and 43 enchantment definitions, extracted from the supported runtime's loaded registries. Only item-compatible enchantments at normal levels are accepted, with no duplicates or conflicting combinations. There is no unsafe mode. Changing the base item clears enchantments so incompatible selections cannot carry over silently.
• Names and up to 32 ordered lore lines are plain text. Empty interior/trailing lore rows are preserved. No rich text, click events, arbitrary components, selectors or command editing. The exact command is updated immediately and can be copied. The 1,024 UTF-8-byte bound includes escaping and every component; overflow is rejected, not truncated.
• Review delivery obtains a server-generated preview. Confirm and give one item sends only that exact command. Every target/item edit invalidates confirmation, and confirmation is consumed before sending. The server independently regenerates and validates fields; its HMAC confirmation binds the administrator, command and saved connection revision. Each version/list/give rechecks authorization and enabled state and uses the existing audit-before-send transport. A changed endpoint cannot redirect an already reviewed give.
• Vanilla /give may drop items if the inventory is full. This is not equipment replacement or a guarantee of inventory placement. A player can disconnect after the online check. RCON transport completion is not confirmed game-command success: read the safely displayed server response.
• A timeout, lost response or completion-audit failure may mean the item was already given. The UI blocks repeat submission while pending and never automatically retries. Check in-game before deliberately starting a new action. Confirmation is not an exactly-once receipt or durable idempotency mechanism.
• Names and lore are retained in command audit history with the administrator and server identity. Responses and credentials are not persisted; browser state is page-memory only. Discovery/version checks themselves are audited. There is no new schema, secret, plugin or deployment setting.

Reproducing the offline compatibility check

The checked-in catalog is apps/web/src/lib/gear-catalog.json. An opt-in test uses an existing extracted Purpur runtime and Java 25; it does not install/download tooling, start a server, create a world, or send RCON. It checks launcher and patched-runtime SHA-256, reloads vanilla registry data, compares every catalog entry, parses give grammar via the actual Bukkit vanilla-command adapter and Brigadier, then decodes ItemStacks to assert literal names/lore and enchantment levels. Legacy NBT and the obsolete enchantment levels wrapper are negative controls.

GEAR_RUNTIME=/absolute/path/to/cached/runtime \
GEAR_JAVA_HOME=/absolute/path/to/existing/java-25 \
npm test --workspace @minecraft-account-manager/web -- src/lib/gear-runtime.test.ts

Expected layout: purpur-26.2-2618.jar, versions/26.2/purpur-26.2.jar, and libraries/**/*.jar. The ordinary suite skips this explicit check when GEAR_RUNTIME is absent; do not describe that skip as fresh runtime verification. Keep the exact parser check and catalog comparison when changing support. A newer version requires new verification, not simply relaxing the version gate. Live item appearance, full-inventory and disconnect behavior remain separately approved post-deployment follow-ups.

Application configuration

Administrators may configure any syntactically valid DNS hostname and TCP port without deployment-managed endpoint configuration. IP literals, trailing-dot hostnames, and malformed DNS names are rejected whenever a connection is saved, tested, or used.

This flexibility means an authorized or compromised administrator can make RCON connection attempts to any DNS hostname and port reachable from the web runtime. Use cluster egress policy and administrator access controls to constrain that trust boundary where required.

Saved passwords are encrypted with AES-256-GCM and connection-bound authenticated data. By default, domain-separated credential and audit keys are derived from AUTH_SECRET. Deployments may instead provide independent 32-byte base64 values through RCON_CREDENTIAL_KEY and RCON_AUDIT_KEY. Rotating the credential key requires replacing saved RCON passwords.

Minecraft server configuration

Enable RCON with a high-entropy password supplied through the deployment secret. Server addresses may resolve internally or externally. Prefer private networking, a VPN, or an encrypted tunnel; do not expose plaintext RCON directly to the public internet.

The password entered in the administrator connection form must match the server password. Existing passwords are write-only; leave the replacement field blank when editing unrelated connection settings.

Security behavior

• Existing account-manager administrator authorization is rechecked for every connection mutation, test, and command.
• Commands are limited to 1,024 UTF-8 bytes and reject control characters.
• Each web process allows one operation per connection and at most eight RCON operations total. Size replica counts with that aggregate ceiling in mind.
• Each complete connect-and-response operation times out after five seconds and tears down the socket; cleanup is independently capped at one second.
• Responses are sanitized and limited to 64 KiB.
• Up to 50 command/response exchanges remain in a chronological page-memory transcript, and up to 50 submitted commands support Arrow Up/Arrow Down recall. Both are discarded on reload; commands and responses are never written to browser storage or application logs, and responses are not persisted. Audit events persist the complete submitted command, acting administrator and server identity, command verb, a domain-separated HMAC digest, and a correlated safe outcome. Persistent audit-backed command history is separate from page-memory recall.
• Connection passwords are never selected by page queries or returned to the browser.

RCON is plaintext TCP. Internal deployments should use network policy; external connections should use private routing, a VPN, or an encrypted tunnel rather than direct public exposure.

Migration

Apply the generated Drizzle migration before deploying the web image:

npx drizzle-kit migrate

Never use drizzle push for this schema change.