# RESEARCH — Limbo / Queue / Auth Plugin Survey Read-only research feeding **AuthLimbo v2**. 2026-05-07. --- ## 1. TL;DR **Top-3 STEAL** (vendor / shade / depend): 1. **Elytrium LimboAPI** (AGPL-3.0, Velocity) — virtual fake-server primitives at the Velocity packet layer. License-compatible, exactly the abstraction we need for "hold pre-login on the proxy, never let the player touch the Paper world". 2. **Elytrium LimboAuth** (AGPL-3.0, Velocity) — production auth flow built on LimboAPI. AuthMe-import path, BCrypt+TOTP, weak-password list. We can fork or depend; AGPL == AGPL. 3. **PistonQueue** (Apache-2.0, Bungee+Velocity+Bukkit) — closest open-source 2b2t-style queue, actively maintained, permissive license (we can shade safely into AGPL). **Top-3 PATTERN** (read & re-implement): 1. **AnarchyQueue (zeroBzeroT)** — clean Velocity/Paper split, separate queue-server, position-update cadence; small enough to read end-to-end. 2. **LeeesVelocityQueue** — minimal MIT priority/bypass model; good reference for *non-paid* trust-tier permissions. 3. **LimboFilter** — anti-bot CAPTCHA + packet-prep tricks; pattern only since AGPL fork would entangle us further. **Stack decision:** **Velocity + Paper, both required.** Pre-auth holding belongs at the proxy (LimboAPI virtual server) — Paper-only can't truly hide the world. Paper plugin keeps the post-auth chunk-preload + void-guard from current AuthLimbo. See §3. --- ## 2. Per-plugin detail | Plugin | License | Stack | Last release | Status | Rating | |---|---|---|---|---|---| | Elytrium LimboAPI | AGPL-3.0 | Velocity | 1.1.26 (2024-09) | Active, slowing | STEAL | | Elytrium LimboAuth | AGPL-3.0 | Velocity (LimboAPI) | 1.1.14 (2024-06) | Active | STEAL | | Elytrium LimboFilter | AGPL-3.0 | Velocity (LimboAPI) | 1.1.18 (2024-06) | Active | PATTERN | | PistonQueue (AlexProgrammerDE) | Apache-2.0 | Velocity+Bungee+Bukkit | 4.0.0 (2026-04) | Very active | STEAL | | AnarchyQueue (zeroBzeroT) | custom permissive (no-warranty) | Velocity | 3.0.13 (2025-10) | Active | PATTERN | | LeeesVelocityQueue | MIT | Velocity | 1.0.1 (2025-07) | Light, alive | PATTERN | | ajQueue | GPL-3.0-only | Velocity+Bungee+Paper | active 2.x | Active | PATTERN (license clash w/ AGPL is one-way OK) | | McMackety/velocity-queue | GPL-3.0 | Velocity (Kotlin) | 1.1.2 (2021-06) | **Archived** | SKIP | | Shirodo-Queue | MIT | Bungee | none | Hobby | SKIP | | ProjectPersistence/queue | n/a | mixed | n/a | **404** | SKIP | | NanoLimbo (Nan1t) | GPL-3.0 | standalone+proxy fwd | 1.12.0 (2026-04) | Active | PATTERN (no auth/queue, but reference impl) | | NanoLimboPlugin (bivashy) | GPL-3.0 | Velocity+Bungee | 1.8.1 (2024-06) | Maintenance | PATTERN | | AuthMe-Reloaded | GPL-3.0 | Spigot/Paper/Folia/Bungee/Velocity | 5.7.0 (2026-04) | Active | KEEP (current dep, not a v2 base) | | kennytv/Maintenance | GPL-3.0 | Paper/Bungee/Velocity/Sponge | active | Active | PATTERN (motd + whitelist gate UX) | | EaglerProxy | n/a | JS shim | active | Off-target | SKIP — not our threat model | | TitanProxy | closed-source | n/a | n/a | n/a | SKIP | Notes: - **NanoLimbo ≠ NanoLimboPlugin.** Former is a standalone Netty server; latter wraps it as a proxy plugin. Neither does auth. - **ProjectPersistence/queue** URL 404'd; treat as dead. - **McMackety/velocity-queue** archived 2021-08; Kotlin code is readable but do not depend. --- ## 3. Recommended architecture for AuthLimbo v2 ``` client ──► Velocity proxy ──► [LimboAPI virtual server: auth + queue] │ ▼ (only after auth+queue cleared) Paper backend ──► [auth-limbo Paper plugin: chunk-preload, void-guard, inventory snapshot] ``` ### Velocity side (new module `auth-limbo-velocity`) - **Depend:** `com.velocitypowered:velocity-api:3.4.x` - **Depend (compileOnly+shade):** `net.elytrium:limboapi:1.1.26` (AGPL — fine, we are AGPL). - **Vendor / fork:** parts of `LimboAuth` for the auth state-machine (BCrypt verify against AuthMe schema, TOTP, weak-password list). Do not pull the H2/MySQL stack — read AuthMe's existing SQLite directly to keep one source of truth. - **Queue logic:** port PistonQueue's `QueueListener` + position ticker (Apache-2.0 → AGPL is a clean re-license). Strip its paid tiers; replace with permission-based trust tiers (`authlimbo.priority.trusted`, `.regular`, no `.donor`). - **Anti-bot:** PATTERN from LimboFilter — client-brand check + join rate-limit; skip the CAPTCHA for now (UX cost too high for a small server). ### Paper side (existing `auth-limbo` plugin, becomes `auth-limbo-paper`) - Keep current chunk-preload + void-world generator. - Land ROADMAP F1 (void-damage guard), F2 (TP retry), F3 (3×3 preload), F5 (inventory snapshot) — these are *post-auth* defences and remain Paper-side. - Drop responsibility for "hide world pre-auth" — Velocity holds it now. ### Shared - Plugin-message channel `authlimbo:handshake` carries `{uuid, trust-tier, reconnect-token}` Velocity → Paper so the Paper side knows the player already passed auth+queue and skips its own login gate. ### Maven coords `net.elytrium:limboapi-api:1.1.26` (AGPL, compileOnly), `com.velocitypowered:velocity-api:3.4.0` (MIT), `AlexProgrammerDE/PistonQueue:4.0.0` (Apache-2.0, study), `io.papermc.paper:paper-api:1.21.11-R0.1` (GPL-3.0, compileOnly). --- ## 4. License compatibility matrix Outbound: AuthLimbo v2 = **AGPL-3.0**. Inbound combinations: | Source license | Compatible direction | Action | |---|---|---| | AGPL-3.0 (LimboAPI/Auth/Filter) | bidirectional | depend or shade freely | | GPL-3.0 (NanoLimbo, ajQueue, AuthMe, Maintenance) | one-way (GPL → AGPL ok) | depend; cannot upstream patches without coordination | | Apache-2.0 (PistonQueue) | one-way (permissive → AGPL) | shade or copy with NOTICE | | MIT (LeeesVelocityQueue, Shirodo) | one-way | shade or copy with attribution | | Custom no-warranty (AnarchyQueue) | unclear | **read code, do not vendor**; re-implement | | Closed (TitanProxy, EaglerProxy logic) | n/a | skip | AGPL §13 invariant: if we ship a network service modified from LimboAuth, source must be offered. Forgejo `git.s8n.ru` already satisfies this for our fleet. --- ## 5. Risks 1. **Elytrium upstream slowdown** — last release mid-2024. Pin to tag, plan soft-fork at git.s8n.ru for 1.21.11+ protocol fixes. 2. **AGPL §13** — modified network deploys need source-link. Footer + `/authlimbo source` covers it. 3. **PistonQueue size** — selective copy beats shading whole jar. 4. **AnarchyQueue licence ambiguity** — no-warranty header not OSI; read-only. 5. **Velocity↔Paper handshake** is a new failure mode; need integration test before deploy. 6. **No CAPTCHA** = bot-flood exposure. Acceptable for small private server; revisit if we open up. 7. **Reconnect token storage** (SQLite vs in-memory) still pending. --- ## 6. Sources Elytrium/{LimboAPI,LimboAuth,LimboFilter}, Nan1t/NanoLimbo, bivashy/NanoLimboPlugin, AlexProgrammerDE/PistonQueue, zeroBzeroT/AnarchyQueue, XeraPlugins/LeeesVelocityQueue, McMackety/velocity-queue (archived), ShirodoBurak/Shirodo-Queue, AuthMe/AuthMeReloaded, kennytv/Maintenance, modrinth/ajqueue.