日本語は下に。プラグインは日本語のみ。
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

Download the plugin JAR.
Place it in the Velocity plugins directory.
Start Velocity once to generate the configuration files.
Stop Velocity and edit plugins/wsnauth/config.yml.
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:

Enable Server Members Intent in the Bot settings.
Invite the Bot to the Discord server used for verification.
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
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

Connect to the Minecraft server.
Copy the six-digit code displayed on the disconnect screen.
Join the configured Discord server.
Press 認証を開始 in the verification channel.
Enter the code in the displayed form.
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 を利用する構成では、アカウントの所有者を安全に識別できません。

導入方法

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

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

Discord Bot の準備

Discord Developer Portal で Bot を作成し、次の設定を行ってください。

Bot 設定の Server Members Intent を有効にします。
認証に利用する Discord サーバーへ Bot を招待します。
Bot に以下の権限を付与します。
- チャンネルを見る
- メッセージを送信
- メッセージ履歴を読む
- 埋め込みリンク — サーバーステータスを利用する場合
- ロールの管理 — 認証済みロールを利用する場合
ロールを自動付与する場合は、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 より優先されます。

認証の流れ

Minecraft サーバーへ接続します。
切断画面に表示された6桁のコードを確認します。
設定された Discord サーバーへ参加します。
認証チャンネルの 認証を開始 ボタンを押します。
表示されたフォームにコードを入力します。
認証完了後、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.