Administration Security

Administration Security

BlueMapWebChat 4.7.0 · Minecraft 1.18–26.2 · Java 17 baseline

28. Administrator and Moderator Features

Depending on role and configuration, the web administration UI provides:

• Message hide/delete controls
• Pin management
• Guest and IP mutes
• Session review and revoke
• Custom emoji folder/file management
• Upload and storage usage information
• Private-chat metadata administration
• Server console command panel

moderation:
  enabled: true
  allow-web-admin-panel: true
  allow-moderator-message-delete: true
  allow-moderator-guest-mute: true
  default-mute-minutes: 60

28.1 Private-Chat Metadata Super Administrators

private-chat-super-admins:
  - "ExactMinecraftName"
  - "00000000-0000-0000-0000-000000000000"

The metadata view shows room/thread titles and participants, message counts, approximate storage usage, retention state, cleanup previews, and metadata-management actions.

To allow read-only DM content review, enable the separate switch:

direct-message:
  admin-audit:
    enabled: true

Only accounts that satisfy both private-chat-super-admins and this switch can open an administrator DM thread. Normal ADMIN/MODERATOR roles are not enough. The audit view cannot send messages, hide participant messages, or mark them read. Every page load writes an admin.dm-audit-read record to the audit log without copying message bodies into the log.

28.2 Audit Log

audit:
  enabled: true
  directory: "audit"

Administrative actions are appended to dated files under plugins/BlueMapWebChat/audit by default. Audit records are not displayed in the web UI.

Operations security

This document summarizes settings to review for public deployments or HTTPS reverse-proxy setups.

Recommended public deployment

For public servers, keep the BlueMapWebChat HTTP server behind Caddy/Nginx instead of exposing it directly.

http:
  host: "127.0.0.1"
  port: 8899
  path-prefix: "/api"
  cors-origin: "https://map.example.com"
  trusted-proxies:
    - "127.0.0.1"
    - "::1"
  log-client-ip-resolution: false

For direct HTTP use, keep trusted-proxies: []. In that mode, client-supplied X-Forwarded-For is ignored and the direct socket IP is used.

Checking client IP resolution logs

When http.log-client-ip-resolution: true is enabled, the plugin writes lines like this to the server console and Minecraft server log:

[BlueMapWebChat] Client IP resolved: socket=127.0.0.1, trustedProxy=true, xForwardedFor=203.0.113.10, result=203.0.113.10, path=/api/config

Where to check:

Server console
logs/latest.log

On Linux:

grep "Client IP resolved" logs/latest.log

For live checking:

tail -f logs/latest.log | grep "Client IP resolved"

Turn log-client-ip-resolution back to false after checking. Requests such as /stream, /config, and /history may produce many log lines.

Expected trusted-proxies behavior

When Caddy/Nginx runs on the same host:

socket=127.0.0.1
trustedProxy=true
xForwardedFor=<real user IP>
result=<real user IP>

When trusted-proxies is empty or the proxy IP is not listed:

trustedProxy=false
result=<socket IP>

Rate limits, login failure limits, mute/ban, and admin IP restrictions use the result value.

Command feature

The web command feature is powerful. For public deployments, prefer:

commands:
  enabled: true
  allow-all: false
  min-role: ADMIN
  require-confirm: true

allow-all: true is not recommended outside private networks or personal servers because a compromised web admin account may lead to console command execution.

SSE connection limits

/stream is a long-lived SSE connection kept open by browsers.

security:
  max-sse-connections-per-ip: 5
  max-sse-connections-total: 200

Set either value to 0 to disable that limit. Limited clients receive too_many_stream_connections.

Known stability trade-offs

The following areas are intentionally left unchanged for stability:

- token query/header/body transport
- request body cache/limit
- pin / unpin / delete flow
- command execution flow

Previous experiments in these areas caused pinned-state issues or repeated first-message behavior, so avoid mixing them with small security patches unless doing a larger refactor.