OpenQQAuth

OpenQQAuth

QQ-driven login & account authentication system for Minecraft — an open-source MQE alternative and beyond.

OpenQQAuth runs on the Velocity proxy: players are isolated behind a graphical authentication gate (dialog screens, virtual chest menu, virtual anvil — adapted across every protocol generation) until their identity is verified, then released to the backend Paper server. It uses QQ as the mandatory ownership credential for every account and supports three login methods:

• Offline password login — enter your password in the virtual anvil
• Premium fast login — encrypted handshake + hasJoined verification, passwordless once bound to QQ
• Bedrock login — Microsoft account identity (Floodgate), passwordless after QQ binding, with optional inheritance of a Java account's data

It also adds a login token system: after installing the Fabric / NeoForge dual-platform mod, players can click "Connect with Token" in the multiplayer screen and enter a credential privately sent by the QQ group bot for instant passwordless entry (30-day validity, revocable).

Domain glossary: CONTEXT.md · Architecture decisions: docs/adr/ · Spec: .scratch/qqauth/spec.md · External API research: .scratch/qqauth/api-reference.md

Table of Contents

• Features
• Architecture
• Requirements
• Quick Start
• Configuration Reference
• QQ Group Commands
• In-Game Commands
• Login & Binding Flows
• Login Tokens (mod)
• Chat Sync
• Permission Model
• Building from Source
• Supported Versions
• Development Guide
• FAQ
• License

Features

• Gate: unverified connections are confined to the login screen until authenticated, then released to the backend server
• Graphical authentication UI: dialog screens (1.21.6+) and virtual chest menus (older versions) for login-method selection; password entry always uses a virtual anvil (open / rename / left-click confirm / right-click clear / gray concrete to reset)
• Full protocol-generation support: anvil packets and item serialization are parameterized per protocol family (Legacy 1.7.21.12.2 / Flat 1.131.14.4 / Classic NBT 1.151.20.4 / Components 1.20.51.21.1 / Menu Refactor 1.21.2~1.21.5 / Dialog 1.21.6+), with rename-transport split (≤1.12.2 plugin channel / 1.13+ rename packet)
• Three login methods: offline password, premium fast login (encrypted handshake + hasJoined double check), and passwordless Bedrock
• QQ binding: verification-code flow (in-game code → send bind <code> in the group; sender QQ must match the target QQ, preventing code sniping)
• Premium binding: clickable chat hint to trigger, premium session + QQ verification code as two factors; premiumUuid-based matching survives name changes; /opa bindpremium for cross-name binding; impersonation protection (reject offline logins on premium-bound names + anti-sockpuppet account creation)
• Bedrock support: Floodgate detection, Cumulus form binding, /opa bindxbox inheritance binding (share a Java account's location/inventory), Java/Bedrock mutual exclusivity, /opa unbindxbox to restore an independent identity
• Fast login: same-IP reconnect within 30 minutes after ≥10 minutes online is passwordless (once per window); QQ notification on trigger ("not you? reply freeze", toggleable)
• Login tokens: 获取凭证 in the group → bot sends a credential privately → mod-side "Connect with Token"; 30-day validity, revocable; replay-protected (one-time nonce challenge-response)
• Remote self-service & administration from QQ: kick / freeze / unfreeze / ban / unban / list / status / check / exec / reload / reconnect
• Voluntary transfer: on name conflict, the original owner unbinds → admin confirms via transfer confirm → target takes over (ADR-0007, no forced takeover path)
• Domain events: PlayerAuthenticatedEvent / AccountBoundEvent / AccountFrozenEvent / AccountBannedEvent published for other plugins via Bukkit ServicesManager
• Read-only API: ReadOnlyAuthApi for Paper-side plugins (economy / land claims / whitelist integrations)
• Chat sync: optional bidirectional group ↔ in-game chat forwarding
• i18n: bilingual messages (zh_CN / en_US) with full translation-key coverage
• Security: password hashing (jBCrypt), failed-attempt lockout (5 tries / 1 min), per-IP session limits, bind rate limiting, session timeouts, replay protection, audit log for all admin operations

Architecture

┌──────────────┐     ┌──────────────────────────────┐     ┌──────────────┐
│  Minecraft   │────▶│  Velocity (OpenQQAuth gate)  │────▶│  Paper server │
│  client      │     │  dialog/chest/anvil auth UI   │     │ (API/events) │
└──────────────┘     │  LoginPipeline decision core  │     └──────────────┘
                     │  handshake/premium/Bedrock    │
                     └──────────────┬───────────────┘
                                    │ OneBot (WebSocket)
                     ┌──────────────▼───────────────┐
                     │   QQ group bot (bind/admin)  │
                     └──────────────────────────────┘

Requirements

• Java 21 (build & run)
• Gradle 9.6.1 (system-installed; this project does not use the Gradle wrapper)
• Velocity proxy (the production login-gate host)
• An OneBot 11 implementation (e.g. NapCat / go-cqhttp) over WebSocket
• Paper server (backend)
• Optional: Floodgate / Geyser (Bedrock support), Fabric / NeoForge client mod (token login)

Quick Start

1. Build

gradle --no-daemon :bootstrap:velocity:build   # Velocity plugin
gradle --no-daemon :bootstrap:paper:build      # Paper plugin
gradle --no-daemon :bootstrap:fabric:build :bootstrap:neoforge:build  # mod dual-platform jar

Artifacts land in each module's build/libs/.

2. Install

1. Put the velocity plugin jar in velocity/plugins/, the paper jar in paper/plugins/
2. Start Velocity once to generate the default config.yml, then edit as needed (see Configuration Reference)
3. Configure the QQ bot (OneBot 11 WebSocket): set qq-bot.ws-url and qq-bot.ws-token, and add admin QQs to qq-bot.admin-qqs
4. Restart Velocity; send reload in the group or run /opa reload as an admin to hot-reload config

3. Minimal working configuration

config-version: 1
qq-bot:
  ws-url: "ws://127.0.0.1:6700"   # OneBot WebSocket endpoint
  ws-token: ""                    # access token (if auth enabled)
  admin-qqs:                      # admin QQ list
    - "10001"
login:
  max-failed-attempts: 5          # password lockout threshold
  lockout-minutes: 1              # lockout duration (minutes)
storage:
  driver: sqlite
  sqlite-file: openqqauth.db

Configuration Reference

All configuration lives in config.yml in the Velocity plugin directory (QqAuthConfiguration, loaded via Configurate).

qq-bot (OneBot)

accounts

login

verify-code

token

sync-groups (chat sync)

storage

premium (premium detection)

QQ Group Commands

Commands are received by the QQ group bot. Permission tiers: see Permission Model.

Player self-service (BOUND_MEMBER)

Verification-code commands (in-group confirmation)

Admin commands (ADMIN)

In-Game Commands

In-game commands use the /opa prefix (Velocity command registration):

Login & Binding Flows

New player (offline)

1. Join the server → intercepted by the gate, enters the QQ binding flow directly
2. Enter your QQ number → the in-game screen shows a verification code
3. Send bind <code> in the QQ group (sender QQ must match the entered QQ — anti-sniping)
4. Binding succeeds → create a password in the anvil (two confirmation inputs) → released into the server

Returning player (offline)

• Select "offline" on the login screen → enter your password in the anvil → verified and released
• Forgot your password: click the gray concrete in the anvil to start a reset → set a new password → confirm with 重置 <code> in the group

Premium player

1. When the name matches a premium account, the chat shows "detected [id] has a premium account — bind?"
2. Click the hint → kicked with "use a premium client to join"
3. Reconnect with the premium client → encrypted handshake + hasJoined verification → send 绑定正版 <code> in the group to complete the QQ second factor
4. After binding, premium logins are passwordless (account matched by premiumUuid with identity rewrite; name changes don't matter)
5. Same person with a different name: /opa bindpremium for manual cross-name binding

Bedrock player (Floodgate)

1. Floodgate detects the Bedrock connection → skips the Java login screens, uses a Cumulus form to enter the QQ number directly
2. Send bind <code> in the group to confirm → bound and released (passwordless)
3. /opa bindxbox: inheritance-bind the Bedrock account to a Java account (shared location/inventory), Java/Bedrock mutually exclusive online
4. /opa unbindxbox or 解绑基岩 in the group: restore an independent identity (data kept while under the QQ account limit)

Fast login

• On reconnect: same IP within 30 minutes, previously online ≥10 minutes → passwordless auto-release (once per window)
• QQ notification on trigger: "account just joined via fast login — not you? reply freeze" (toggleable via fast-login-notify-qq)

Login Tokens (mod)

For players

1. Send 获取凭证 in the QQ group → the bot privately sends a 30-day token
2. Launch a client with the OpenQQAuth mod installed (Fabric or NeoForge)
3. Click "Connect with Token" in the bottom-right of the multiplayer screen → enter the token → connect
4. The server verifies and releases you passwordless; revoke at any time with 吊销凭证 if the token leaks

How it works

• During the login phase the token is sent over the mod channel (openqqauth:token); the Velocity side runs a 128-bit random nonce challenge-response to prevent replay
• Verification (TokenLoginChecker): token + account binding + not expired + not revoked → passwordless release on hit
• A failed token check never blocks the password path (the player stays at the password screen)
• Non-mod (vanilla) clients are unaffected and use password login as usual
• Optional local plaintext token storage (save-token toggle; cleared when disabled)

Chat Sync

With sync-groups.enabled:

• Group messages → in-game chat (group-to-game)
• In-game chat → group (game-to-group)
• In-game /opa at to @ a group member, /opa re to reply to a group message

Permission Model

Admin commands (bind / ban / exec / check / transfer / reload / reconnect, etc.) are written to the CommandAuditLog before and after execution.

Building from Source

# Full build: compile + test + checkstyle + spotless
gradle --no-daemon build

# Compile a single module
gradle --no-daemon :core:compileJava
gradle --no-daemon :bootstrap:velocity:compileJava
gradle --no-daemon :bootstrap:paper:compileJava
gradle --no-daemon :bootstrap:fabric:compileJava
gradle --no-daemon :bootstrap:neoforge:compileJava

# Run a module's tests
gradle --no-daemon :core:test
gradle --no-daemon :bootstrap:velocity:test

# Style checks
gradle --no-daemon :core:checkstyleMain :core:spotlessCheck

System-installed Gradle 9.6.1 is required (no wrapper). Build memory of -Xmx2G is recommended (see gradle.properties).

Supported Versions

Client Minecraft versions (protocol families)

Conclusion: clients from 1.12.2 up to the latest release (26.2) can log in. The UI auto-dispatches per version: dialog screens for 1.21.6+, virtual chest menus for older versions, and a virtual anvil for password input everywhere (rename split: ≤1.12.2 plugin channel / 1.13+ rename packet; item serialization: NBT ≤1.20.4 / Data Components ≥1.20.5).

Runtime requirements

Known limits

1. 1.7.2~1.12.1: the Legacy constant table exists, but this range is marked "theoretical floor, not committed" — packet-ID drift may occur; 1.12.2 is the recommended minimum for production
2. mod token side: the build baseline is MC 26.1.2; supporting other MC versions requires bumping minecraft = "26.1.2" in the build config and rebuilding
3. real Velocity connection wiring: ServerboundPacketHandler bridging for old families (<770) is a follow-up ticket; verified at the mock layer

Development Guide

• Issues & spec: .scratch/<feature>/ (spec + numbered tickets), see docs/agents/issue-tracker.md
• Triage labels: needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix, see docs/agents/triage-labels.md
• Domain glossary: CONTEXT.md (account / QQ / bind / gate / login screen / premium binding / inheritance binding, etc.)
• Architecture decisions: docs/adr/0001~0008 (virtual-anvil gate, offline premium detection, OneBot 11, login-screen layering, login tokens, fixed account keys, name conflict, fast-login trust model)
• Collaboration conventions: see CLAUDE.md (worktree isolation, impact-scope verification, per-ticket commits, concurrency cap)

Core source layout

core/src/main/java/dev/nmouzh/openqqauth/
├── account/      # account model, SQLite repository
├── anvil/        # anvil window state machine (UI-agnostic core)
├── api/          # read-only query API (for Paper plugins)
├── bedrock/      # Bedrock support (form sender, bind flow)
├── configuration/# config model (Configurate)
├── event/        # domain event bus (SimpleDomainEventBus)
├── gate/         # LoginPipeline, sessions, lockout, fast login
├── i18n/         # TranslationKey enum + bilingual resources
├── mojang/       # Mojang API client (name→UUID, hasJoined)
├── onebot/       # OneBot 11 client (WebSocket messaging)
├── password/     # password hashing (jBCrypt)
├── qq/           # QQ domain: bind/reset/unbind state machines, group commands, audit log, voluntary transfer
├── token/        # login tokens: issue/revoke/verify, transport protocol, mod channel
├── util/         # utilities
└── verify/       # verification code service

FAQ

Q: "Bot offline" — can't bind? A: New-player binding checks the bot's online state (BotOnlineProvider); when the bot is offline, binding operations degrade to a hint + kick. Confirm the OneBot connection (reconnect reconnects).

Q: Old clients like 1.12.2 can't log in? A: The anvil protocol and item serialization are parameterized per protocol family supporting the Legacy range (theoretical floor 1.7.2, 1.12.2 committed). Earlier 1.13 sub-versions and 1.7.2~1.12.1 packet-ID drift are "not committed"; real Velocity connection wiring (internal MinecraftConnection bridging) is a separate follow-up ticket.

Q: What happens if token verification fails? A: It never blocks the password path — the failure is only logged and the player stays at the password screen and can log in normally.

Q: How can other plugins read account info? A: On Paper, get ReadOnlyAuthApi (account/session queries) via Bukkit ServicesManager, and subscribe to domain events (PlayerAuthenticatedEvent, etc.). See PaperAuthEvents in bootstrap/paper for an integration example.

Q: Where is data stored? A: By default in the SQLite file openqqauth.db (storage.sqlite-file is configurable).

Q: How are name conflicts handled? A: Per ADR-0007 ("first come, first served for the past; premium-priority for the future"): conflicting parties can use voluntary transfer (owner unbinds → admin transfer confirm → target takes over). The system provides no forced-takeover path.

License

This project is licensed under CC0 1.0 Universal — free to use however you like, including relicensing for your own projects.