VonixGuardian — Permissions & LuckPerms

Candidate State: 3.0.0-m1 Permission ModelCurrent Dev/Test

VonixGuardian integrates reflectively with LuckPerms. It requires no hard dependencies and ships with built-in vanilla op-level fallback.

1. Resolution Flow

Permission evaluation follows a two-tier strategy:

1. LuckPerms (Preferred): If permissions.useLuckPerms: true and LuckPerms is loaded, permissions are resolved via LuckPermsProvider.get(). Reflection is used so the plugin operates cleanly if LuckPerms is absent.
2. Vanilla Op-Level Fallback: If LuckPerms is absent, disabled, or returns UNDEFINED, the resolver consults the server op level:
   • If player opLevel >= permissions.defaultOpLevel (default 3), access is granted.
   • If not, access is denied.
   • Note: Without LuckPerms, there is no granular control—any level 3 op possesses full permissions.

---

2. Permission Node Table

Node	Primary Function	Command / Pipeline Hook	Op Fallback
vonixguardian.command.use	Root command visibility	/vg, /co, /guardian	0
vonixguardian.command.inspect	Block and container history inspection	/vg inspect (alias /vg i)	3
vonixguardian.command.lookup	Database query access	/vg lookup (alias /vg l)	3
vonixguardian.command.rollback	World modification reversal	/vg rollback, /vg undo	3
vonixguardian.command.restore	Re-applying reversed changes	/vg restore (alias /vg rs)	3
vonixguardian.command.purge	Destructive history trimming	/vg purge	3
vonixguardian.command.near	Local radius query shorthand	/vg near (alias /vg n)	3
vonixguardian.command.status	Performance & queue observability	/vg status	3
vonixguardian.command.reload	Re-reading configuration	/vg reload, /vg config	3
vonixguardian.command.teleport	Parity administrative teleport	/vg teleport (alias /vg tp)	3
vonixguardian.command.give	Parity item spawning	/vg give	3
vonixguardian.command.viewothers	Target queries without explicit u:	/vg lookup, /vg rollback	3
vonixguardian.command.bypass	Exempts holder from being logged	Action Pipeline (Source Hook)	3

---

3. Granular Lookup Child Permissions

Servers wishing to restrict staff or players to specific lookup categories can configure granular child nodes:

• vonixguardian.lookup.block — Allows querying block place and break history.
• vonixguardian.lookup.container — Allows querying container withdrawals and deposits.
• vonixguardian.lookup.item — Allows querying item drops, pickups, and crafting.
• vonixguardian.lookup.kill — Allows querying entity and player death records.
• vonixguardian.lookup.chat — Allows querying historical chat messages.
• vonixguardian.lookup.command — Allows querying operator and player commands.
• vonixguardian.lookup.sign — Allows querying sign edit text and front/back changes.
• vonixguardian.lookup.session — Allows querying player join, quit, and IP records.

---

4. Special Security Nodes

vonixguardian.command.bypass

High Security Risk — Never Grant to Humans

Actions performed by a player holding vonixguardian.command.bypass are never written to the audit database. If an operator with this node modifies the world, there is zero record and their edits cannot be rolled back.

Allowed Use Cases: Scripted server console automation, WorldEdit staging bots, or automated arena resets where logging causes database ballooning without investigative value.

vonixguardian.command.viewothers

Controls filter scoping behavior for lookups and rollbacks:

• Without viewothers: The query is automatically scoped to the executor’s own UUID (/vg lookup r:10 becomes /vg lookup u:<self> r:10). Non-staff players can safely check their own chests without inspecting other players.
• With viewothers: Operators can inspect any player’s activity across the entire server.

---

5. Recommended LuckPerms Role Setup

A two-tier group setup that separates investigation from destructive commands:

# --- Moderator Group (Investigation & Inspection) ---
/lp group moderator permission set vonixguardian.command.use true
/lp group moderator permission set vonixguardian.command.inspect true
/lp group moderator permission set vonixguardian.command.lookup true
/lp group moderator permission set vonixguardian.command.near true
/lp group moderator permission set vonixguardian.command.status true
/lp group moderator permission set vonixguardian.command.viewothers true

# --- Admin Group (Inherits Moderator + Reversal & Maintenance) ---
/lp group admin parent add moderator
/lp group admin permission set vonixguardian.command.rollback true
/lp group admin permission set vonixguardian.command.restore true
/lp group admin permission set vonixguardian.command.undo true
/lp group admin permission set vonixguardian.command.purge true
/lp group admin permission set vonixguardian.command.reload true

vonixguardian.command.undo is listed in the command spec. The loader tree currently gates /vg undo with vonixguardian.command.rollback. Grant rollback to allow undo.