Newspaper

A cross-platform Minecraft plugin/mod for remote server management via WebSocket with mutual TLS authentication.

中文文档

Features

• Mutual TLS (mTLS) — Password-derived certificate generation, zero manual cert exchange
• Dual Platform — Paper (1.21.1–26.2) and Fabric (1.21.1–26.2) from a shared codebase
• Shell Command Execution — Run system shell commands remotely with configurable timeout
• File Transfer — Upload and download files via Base64 over WebSocket
• Reverse Proxy — Outbound connection mode for servers behind NAT/firewall
• PROXY Protocol — Optional v1/v2 support for client IP detection behind reverse proxies
• Audit Logging — Tamper-proof audit log with continuous file locking
• Password Security — Auto-generated 128-bit keys with strength validation
• Internationalization — Built-in English (en) and Chinese (zh) translations
• Config Fault Tolerance — Invalid config entries are automatically reset to defaults with warnings

Version Support

Platform	Module	Minecraft Versions	Java
Paper	paper	1.21.1–26.2	21+
Fabric	fabric	26.1–26.2	25
Fabric (Legacy)	fabric-legacy	1.21.1–1.21.11	21

Note: Fabric uses two separate modules due to a breaking change in Minecraft 26.1 (Mojang removed class obfuscation, making Yarn intermediary mappings unavailable for 26.1+).

Fabric support is experimental. If you encounter crashes or unexpected behavior, please report them on the Issues page.

Alpha Version Notice

When you see a version tagged Alpha (e.g. v1.0.0-alpha.1), it is likely a release with known issues that has not been pulled. Alpha versions may contain unfinished features, known crash risks, or performance problems, and are primarily intended for early testing and feedback collection.

Authentication

Newspaper uses pure mTLS. Both server and client derive identical CA/server/client certificates from the shared password using BouncyCastle (secp256r1 + SHA-256). The TLS handshake performs mutual authentication — no application-layer auth messages needed.

If no password is configured, a 128-bit key is auto-generated, validated against security rules (uppercase, lowercase, digits), and printed to the console.

Connection Modes

Mode	Config Value	Description
Direct	direct	Server listens for incoming mTLS connections
Reverse Proxy	reverse	Server connects outward to a remote relay, retries every 5 min

connection-mode: "reverse"
reverse-proxy:
  host: "relay.example.com"
  port: 8080
  protocol: "wss"

Configuration

port: 8080
password: ""
ipv6: false
language: "en"
connection-mode: "direct"
enforce-password-strength: true
proxy-protocol: false
reverse-proxy:
  host: ""
  port: 8080
  protocol: "wss"
shell:
  timeout: 30
file-transfer:
  enabled: true
  root: ""
  restrict-upload: true
  disable: false
audit-log:
  enabled: true

Invalid config values are automatically reset to defaults with a WARN log. Supported validation rules:

Key	Rule
port	1–65535
connection-mode	direct or reverse
reverse-proxy.protocol	wss or ws
shell.timeout	>= 1

Commands

Command	Permission	Description
/newspaper reload	OP	Reload config and restart WebSocket server
/newspaper modify <key> <value>	OP	Modify a config field (e.g. port 9090)
/newspaper exec <command>	OP	Execute a system shell command
/newspaper lang <file>	OP	Load a language file (e.g. en, zh)

WebSocket API

Connection

Connect via wss://<host>:<port>/ (mTLS required). All data frames must be binary (opcode 0x2).

Request Format

{
  "type": "<operation_type>",
  "data": { ... }
}

Operation Types

Type	Description
console_message	Subscribe/poll/unsubscribe console output
chat_message	Subscribe/poll/unsubscribe chat messages
command	Execute a console command
command2	Execute a command as a specific player
player_join	Subscribe/poll/unsubscribe player join events
player_quit	Subscribe/poll/unsubscribe player quit events
online_players	Get online player list with details
server_info	Get server, Java, and memory info
config_modify	Modify configuration fields
config_reload	Reload configuration and restart WebSocket
shutdown	Shut down the Minecraft server
console_broadcast	Broadcast a message to all players
shell_command	Execute a system shell command
file_upload	Upload a file (Base64 content)
file_download	Download a file (returns Base64 content)

Examples

Shell command:

{ "type": "shell_command", "data": { "command": "ls -la", "timeout": 10 } }

File upload:

{ "type": "file_upload", "data": { "path": "backup/world.yml", "content": "<base64>" } }

File download:

{ "type": "file_download", "data": { "path": "config.yml" } }

Security

• Audit Log — Records WSS connection IDs, login attempts (success/failure), remote addresses, and operation details. The log file (audit.log) is continuously locked during server runtime to prevent tampering. File transfer operations targeting audit.log are blocked.
• File Transfer Security — Path traversal detection, optional upload directory restriction (server root by default), and global file transfer disable toggle.
• Password Strength — Enforced by default. Disabling it triggers a red warning. Auto-generated keys meet complexity requirements (uppercase, lowercase, 3+ alphabetical, 6+ digits).

License

MIT — see LICENSE.