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.

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.