auth-limbo/docs/RESEARCH-LIMBO-PLUGIN-SURVEY.md

# 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.