SafeTPFirewall

English | 中文说明 below

Paper / Folia server high-risk entity teleport safety confirmation plugin.

Features

• Intercepts tp / teleport commands involving @e (including nested execute ... run tp; @a is not intercepted)
• Supports player chat, console, RCON
• Requires typing /y to confirm before actual execution; auto-cancels after 30 seconds
• Can also type /n to cancel
• Operation logging: all key operations (intercept / confirm / execute / cancel / timeout) written to audit log

Audit Logging

• File: plugins/SafeTPFirewall/audit/audit-YYYY-MM-DD.log (daily rolling, append-only, thread-safe)
• Log content: timestamp | operation type | initiator | details
  • Operation types: INTERCEPT, CONFIRM, EXECUTED, EXEC_FAILED, CANCEL, TIMEOUT, EXPIRED
  • Initiator: players shown as player:name(UUID), console/RCON shown by source name
• Console log sync output toggle and master toggle are in the audit: config section of config.yml
• Upgrade note: when old config.yml does not contain audit: block, defaults (enabled) apply; to change config, manually add or delete old config and restart to regenerate

Folia Compatibility

• plugin.yml declares folia-supported: true
• All scheduling goes through Scheduler wrapper: detects Folia at runtime, auto-switches
  • Folia: Bukkit.getGlobalRegionScheduler() / entity.getScheduler() (player commands execute on player's region thread)
  • Paper: legacy Bukkit.getScheduler()
• Confirm commands initiated by players execute on player region thread; console/RCON uses global region thread
• Timeout check runs every 1 second (properly wired since v1.3; previously only lazily checked on /y, /n)

Installation

1. Place SafeTPFirewall.jar into server's plugins/ directory
2. Restart server
3. Check logs to confirm SafeTPFirewall enabled

Build (with internet)

mvn clean package
# Output: target/SafeTPFirewall.jar

Build (offline / no internet)

Ensure you have the Paper API jar (download from https://repo.papermc.io, or local Maven repo):

javac -cp paper-api-1.21.1.jar -d out \
  src/main/java/com/example/safetp/*.java
jar --create --file SafeTPFirewall.jar --main-class com.example.safetp.SafeTPFirewall -C out .

Demo

Accidental input:

/tp @e ~ ~ ~

Plugin response:

[SafeTP] High-risk entity teleport command detected!
Type /y within 30 seconds to confirm execution, or /n to cancel:
Original command: /tp @e ~ ~ ~

Type /y → executes; no input / wrong input / timeout → blocked ✅

Command Blocks / Function Notes

Paper does not provide in-process events for command block / function pre-execution. Proper protection methods:

1. Temporarily disable dangerous functions during events
2. Or restrict command-blocks level in paper.yml
3. Plugin provides log-command-block-only toggle for audit logging

Configuration

Edit plugins/SafeTPFirewall/config.yml to adjust timeout duration, source toggles, etc.

---

中文说明

Paper / Folia 端高危实体传送安全确认插件。

功能

• 拦截涉及 @e 的 tp / teleport 命令（含嵌套 execute ... run tp；@a 不拦截）
• 支持玩家聊天、控制台、RCON
• 需输入 /y 确认后才真正执行，30 秒超时自动取消
• 也可输入 /n 取消
• 操作留痕：所有关键操作（拦截/确认/执行/取消/超时）写入审计日志

操作留痕（审计日志）

• 文件：plugins/SafeTPFirewall/audit/audit-YYYY-MM-DD.log（按天滚动，追加写，线程安全）
• 记录内容：时间戳 | 操作类型 | 发起者 | 详情
  • 操作类型：INTERCEPT（拦截）CONFIRM（确认）EXECUTED（执行成功）EXEC_FAILED（执行失败）CANCEL（取消）TIMEOUT（超时）EXPIRED（确认时已超时）
  • 发起者：玩家显示 player:名字(UUID)，控制台/RCON 显示来源名
• 控制台日志同步输出开关、总开关见 config.yml 的 audit: 配置块
• 升级用户注意：旧 config.yml 不含 audit: 块时按默认值（开启）生效；如需改配置可手动添加或删除旧 config 重启生成

Folia 兼容

• plugin.yml 已声明 folia-supported: true
• 调度全部走 Scheduler 封装：运行时探测 Folia，自动切换
  • Folia：Bukkit.getGlobalRegionScheduler() / entity.getScheduler()（玩家命令在玩家所在 region 线程执行）
  • Paper：旧版 Bukkit.getScheduler()
• 确认命令由玩家发起时在玩家 region 线程执行，控制台/RCON 走全局 region 线程
• 超时检查每 1 秒调度一次（v1.3 起真正接上，此前只在 /y、/n 时惰性检查）

安装

1. 将 SafeTPFirewall.jar 放入服务端的 plugins/ 目录
2. 重启服务端
3. 查看日志确认 SafeTPFirewall 已启用

构建（有魔法网络）

mvn clean package
# 产物：target/SafeTPFirewall.jar

构建（无魔法网络 / 离线）

确保有 Paper API jar（从 https://repo.papermc.io 下载，或本地 Maven 仓库）：

javac -cp paper-api-1.21.1.jar -d out \
  src/main/java/com/example/safetp/*.java
jar --create --file SafeTPFirewall.jar --main-class com.example.safetp.SafeTPFirewall -C out .

效果演示

手滑输入：

/tp @e ~ ~ ~

插件响应：

[SafeTP] 检测到高危实体传送命令！
30 秒内输入 /y 确认执行，或输入 /n 取消：
原始命令: /tp @e ~ ~ ~

输入 /y → 执行；不输/输错/超时 → 不执行 ✅

命令方块 / function 说明

Paper 不提供命令方块/function 执行前的进程内事件，正经防护方式：

1. 活动期间临时禁用危险 function
2. 或在 paper.yml 中限制 command-blocks 等级
3. 插件提供 log-command-block-only 开关做审计日志

配置

编辑 plugins/SafeTPFirewall/config.yml 可调超时时间、来源开关等。