s8n/auth-limbo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
auth-limbo/docs/RESEARCH-LIMBO-PLUGIN-SURVEY.md
s8n ab1f607df6 docs: AuthLimbo v2 research + architecture + roadmap 
4 parallel research agents output (2026-05-07):
- RESEARCH-2B2T-QUEUE.md — 2b2t queue tech deep-dive: architecture, drama
  timeline, 5 patterns to copy + 5 to avoid
- RESEARCH-LIMBO-PLUGIN-SURVEY.md — open-source plugin survey: STEAL list
  (Elytrium LimboAPI/LimboAuth + PistonQueue), PATTERN list, SKIP list
- V2-ARCHITECTURE.md — Paper-only stack with Velocity-ready seam, 7-state
  login flow, snapshot-on-pre-login, transparent FIFO trust tiers
- V2-ROADMAP.md — M0-M5 milestones with acceptance criteria + dep graph

Stack decision: Paper-only for now (no proxy required), but architecture
split into Gatekeeper + Restore layers so future Velocity migration is
mechanical. Trip-wires codified for when to reconsider.

Anti-drama policy locked in code (not config): no paid priority, no
hidden veteran tier, transparent ban appeals.

Bootstrap repo at git.s8n.ru/s8n/auth-limbo-v2 ready for M0 work.
2026-05-07 19:31:40 +01:00

7.2 KiB
Raw Blame History

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.