日本語は下に。プラグインは日本語のみ。
Japanese description is available below. The plugin itself is available in Japanese only.

wsnAuth

wsnAuth is a Velocity plugin that links Minecraft accounts with Discord accounts and allows only verified players to join your network.

When an unverified player connects, they receive a six-digit verification code on the Minecraft disconnect screen. They can link their account by pressing the verification button in Discord and entering the code in the displayed form.

Features

• Minecraft and Discord account verification using a six-digit one-time code
• Discord server membership checks on every verified login
• Automatic assignment and removal of a verified Discord role
• Discord role synchronization with LuckPerms groups
• Live Discord server-status panel for all backend servers registered in Velocity
• PremiumVanish support for hiding vanished players from the status panel
• Configurable limit on the number of Minecraft accounts linked to one Discord account
• Protection against repeated invalid-code submissions
• Customizable Minecraft and Discord messages through messages.yml
• Persistent account links stored in JSON

Requirements

• Java 17 or newer
• Velocity 3.4.x
• A Discord Bot
• LuckPerms 5.4 or newer — optional, required only for role synchronization
• PremiumVanish — optional, used only to hide vanished players from the status panel

Velocity must use online-mode=true. Offline UUID configurations cannot securely preserve account ownership.

Installation

1. Download the plugin JAR.
2. Place it in the Velocity plugins directory.
3. Start Velocity once to generate the configuration files.
4. Stop Velocity and edit plugins/wsnauth/config.yml.
5. Start Velocity again.

The plugin will fail to connect to Discord on the first startup while the default Bot Token is still configured. This is expected; edit the generated configuration before starting Velocity again.

Discord Bot setup

Create a Bot in the Discord Developer Portal, then:

1. Enable Server Members Intent in the Bot settings.
2. Invite the Bot to the Discord server used for verification.
3. Grant the Bot the following permissions:
   • View Channels
   • Send Messages
   • Read Message History
   • Embed Links — required for the server-status panel
   • Manage Roles — required for the verified-role feature
4. When using automatic role assignment, place the Bot's role above the role it needs to manage.

Configuration example

discord:
  token: "YOUR_BOT_TOKEN_HERE"
  guildId: 123456789012345678
  adminId: 0
  verificationChannelId: 123456789012345678
  verifiedRoleId: 123456789012345678
  serverStatusChannelId: 123456789012345678
  inviteUrl: "https://discord.gg/your-invite"

security:
  maxFailures: 3
  blockMinutes: 5
  maxAccountsPerUser: 1

debug: false

role-sync:
  - roleId: 111111111111111111
    group: "member"
  - roleId: 222222222222222222
    group: "vip"

Set an optional Discord feature ID to 0 to disable that feature. If LuckPerms role synchronization is not needed, use role-sync: [].

The status channel can also be configured with the SERVER_STATUS_CHANNEL_ID environment variable. The environment variable takes priority over config.yml.

Verification flow

1. Connect to the Minecraft server.
2. Copy the six-digit code displayed on the disconnect screen.
3. Join the configured Discord server.
4. Press 認証を開始 in the verification channel.
5. Enter the code in the displayed form.
6. Reconnect to the Minecraft server after verification succeeds.

Verification codes expire after five minutes and can only be submitted once. Reconnect to the Minecraft server to receive a new code if the previous code expires or is consumed.

Commands

Command	Permission	Description
/unlink	None	Unlinks your Minecraft account from Discord
/discord <player>	discordauth.admin	Displays the player's linked Discord username, ID, and verification date

LuckPerms synchronization

Each entry under role-sync maps a Discord role to a LuckPerms group. Synchronization runs when:

• A mapped Discord role is added or removed
• A verified player connects to Minecraft
• Minecraft and Discord verification is completed

The LuckPerms group is granted while the Discord member has at least one role mapped to that group, and removed when they have none. Account verification continues to work normally when LuckPerms is not installed; only role synchronization is disabled.

Server-status panel

When serverStatusChannelId is configured, wsnAuth publishes one Discord Embed containing:

• The online or offline state of every backend server registered in Velocity
• Visible player names and player counts
• The number of currently available backend servers
• An offline status when the Velocity proxy shuts down

The status is checked every five seconds, and the Discord message is updated only when its contents change. Vanished players are excluded when PremiumVanish is installed.

Security and data

• Verified account links are stored in plugins/wsnauth/verified.json.
• Verification codes are held only in memory and are cleared when Velocity restarts.
• Codes contain six digits, expire after five minutes, and can be used only once.
• Invalid submissions are rate-limited per Discord account.
• A verified player who leaves the configured Discord server cannot connect until they rejoin.
• Never publish your Bot Token or verified.json.

---

日本語

wsnAuth は、Minecraft アカウントと Discord アカウントを連携し、認証済みプレイヤーだけを参加させる Velocity 用プラグインだよ。

未認証のプレイヤーが接続すると、Minecraft の切断画面に6桁の認証コードを表示するよ。Discord の認証チャンネルでボタンを押し、表示されたフォームにコードを入力するだけで連携できるよ。

主な機能

• 6桁のワンタイムコードによる Minecraft / Discord アカウント認証
• 認証済みプレイヤーの接続時に Discord サーバーへの参加状況を確認
• 認証済み Discord ロールの自動付与・削除
• Discord ロールと LuckPerms グループの同期
• Velocity 配下のサーバーを表示する Discord ライブステータス
• PremiumVanish と連携し、Vanish 中のプレイヤーをステータスから除外
• 1つの Discord アカウントへ連携できる Minecraft アカウント数の制限
• 無効な認証コードの連続入力に対する一時ブロック
• messages.yml による Minecraft / Discord メッセージの変更
• JSON による認証済みアカウントの保存

必要環境

• Java 17 以上
• Velocity 3.4.x
• Discord Bot
• LuckPerms 5.4 以上 — ロール同期を利用する場合のみ
• PremiumVanish — ステータス上で Vanish 中のプレイヤーを隠す場合のみ

Velocity の online-mode は true にしてね。オフライン UUID を利用する構成では、アカウントの所有者を安全に識別できないよ。

導入方法

1. プラグインの JAR をダウンロードするよ。
2. Velocity の plugins ディレクトリへ配置するよ。
3. Velocity を一度起動し、設定ファイルを生成するよ。
4. Velocity を停止して plugins/wsnauth/config.yml を編集するよ。
5. Velocity を再度起動するよ。

初回起動時は Bot Token が初期値なので、Discord への接続エラーが表示されるよ。これは正常な動作だよ。生成された設定ファイルへ正しい Token を設定してから再起動してね。

Discord Bot の準備

Discord Developer Portal で Bot を作成し、次の設定を行ってね。

1. Bot 設定の Server Members Intent を有効にするよ。
2. 認証に利用する Discord サーバーへ Bot を招待するよ。
3. Bot に以下の権限を付与するよ。
   • チャンネルを見る
   • メッセージを送信
   • メッセージ履歴を読む
   • 埋め込みリンク — サーバーステータスを利用する場合
   • ロールの管理 — 認証済みロールを利用する場合
4. ロールを自動付与する場合は、Bot のロールを付与対象ロールより上に配置するよ。

設定例

discord:
  token: "YOUR_BOT_TOKEN_HERE"
  guildId: 123456789012345678
  adminId: 0
  verificationChannelId: 123456789012345678
  verifiedRoleId: 123456789012345678
  serverStatusChannelId: 123456789012345678
  inviteUrl: "https://discord.gg/your-invite"

security:
  maxFailures: 3
  blockMinutes: 5
  maxAccountsPerUser: 1

debug: false

role-sync:
  - roleId: 111111111111111111
    group: "member"
  - roleId: 222222222222222222
    group: "vip"

任意機能の Discord ID を 0 にすると、その機能を無効化できるよ。LuckPerms ロール同期が不要な場合は role-sync: [] にしてね。

ステータスチャンネルは環境変数 SERVER_STATUS_CHANNEL_ID でも指定できるよ。環境変数が設定されている場合は config.yml より優先されるよ。

認証の流れ

1. Minecraft サーバーへ接続するよ。
2. 切断画面に表示された6桁のコードを確認するよ。
3. 設定された Discord サーバーへ参加するよ。
4. 認証チャンネルの 認証を開始 ボタンを押すよ。
5. 表示されたフォームにコードを入力するよ。
6. 認証完了後、Minecraft サーバーへ再接続するよ。

認証コードの有効期限は5分で、1回だけ送信できるよ。期限切れや使用済みの場合は、Minecraft サーバーへ接続し直して新しいコードを取得してね。

コマンド

コマンド	権限	説明
/unlink	なし	自分の Minecraft / Discord 連携を解除するよ
/discord <player>	discordauth.admin	指定プレイヤーの Discord ユーザー名、ID、認証日時を表示するよ

LuckPerms ロール同期

role-sync の各項目で Discord ロールと LuckPerms グループを対応させられるよ。同期は以下のタイミングで実行されるよ。

• Discord ロールが追加・削除されたとき
• 認証済みプレイヤーが Minecraft へ接続したとき
• Minecraft / Discord 認証が完了したとき

同じ LuckPerms グループに対応する Discord ロールを1つ以上持っている間はグループが付与され、すべて失うと削除されるよ。LuckPerms が導入されていなくてもアカウント認証は利用でき、ロール同期だけが無効になるよ。

サーバーステータス

serverStatusChannelId を設定すると、1つの Discord Embed に以下の情報を表示するよ。

• Velocity に登録された各バックエンドサーバーのオンライン・オフライン状態
• 表示中のプレイヤー名と人数
• 稼働中のバックエンドサーバー数
• Velocity 停止時のオフライン状態

ステータスは5秒ごとに確認し、内容が変化した場合だけ Discord メッセージを更新するよ。PremiumVanish が導入されている場合は、Vanish 中のプレイヤーを除外するよ。

セキュリティとデータ

• 認証済みアカウントは plugins/wsnauth/verified.json に保存するよ。
• 認証コードはメモリ上だけに保存し、Velocity の再起動時に消去するよ。
• コードは6桁、有効期限5分、1回限り有効だよ。
• 無効なコードの入力は Discord アカウント単位で制限するよ。
• 認証済みユーザーが対象の Discord サーバーから退出すると、再参加するまで接続できないよ。
• Bot Token や verified.json は公開しないでね。

License

wsnAuth is released under the MIT License.