Access Control

Access Control (RBAC)

🧪 Beta preview — 5.x line, off by default. Access control replaces ZenithProxy's owner/whitelist model with role-based permissions. It is inert until you turn it on (perms enable on); with it off, behaviour is exactly the legacy owner-or-whitelist model. Built and released on the beta channel, not yet promoted to stable and not yet fully live-tested end-to-end.

Stock ZenithProxy is all-or-nothing: you're the account owner (or whitelisted) and can do everything, or you can't connect. Access control (RBAC) replaces that with roles + granular permissions + per-user API tokens, so you can let a group share one bot — each person limited to exactly what you allow.

Command: perms (admin-only).

Model

Default-deny. An unknown player has no access — can't connect, spectate, run commands, or pull pearls. You grant access by assigning a role, optionally adjusted with per-user grants and denies.

Roles (hierarchical)

Role	Gets
admin	everything (*), including the access-control system itself, config management, and admin-only modules
operator	all capability preset groups (≈ every module) + chat/utility/system management
user	control connection + the standard capability groups you assign
guest	pearl-pull + API only — no spectate, no control
(none)	default — no access at all

Each role includes the one below it. Only the four built-in roles are assignable (the hierarchy is built in).

Capability preset groups

Groups expand to a bundle of module.* permissions so you don't assign modules one by one:

• movement — pathfinder goto / boat / non-elytra movement
• travel — ElytraPilot / ElytraTrip (e-bounce, nether flight)
• combat — KillAura / AutoTotem / AutoEat / AutoArmor / SpawnPatrol / WhisperControl protect / …
• crafting — VillagerTrader / PearlDrop / AquariusMiner / KitMaker / Enchanter / Regear / stash
• automation — AntiAFK / AutoFish / AutoDrop / tasks

A handful of modules are admin-exclusive and never in a preset (CoordObfuscation, Spammer, VisualRange, ActionLimiter, config management, and the permission system itself).

Permission nodes

Wildcards: * matches everything, a trailing .* matches a prefix, and a deny always beats a grant.

command.<core|info|manage|module>     run commands by category
module.<name>                         toggle/use a module (e.g. module.killaura, module.whispercontrol)
action.move | action.chat | action.interact   in-world actions (enforced by RbacGuard)
connect.control | connect.spectate    how a user may join
pearl.pull | pearl.manage             stasis-pearl loading / management
group.<name>                          a capability preset (expands to module.*)

The HTTP command API

RBAC ships a token-authorized HTTP API so out-of-world members (and the ProxyBridge mod) can drive the bot:

• POST /command — runs a command as the token's subject, so all RBAC gating applies.
• POST /position — a member's client reports its location (powers come/protect across sessions).

Configure it with perms api:

perms api host <ip>     # bind address (default 127.0.0.1 = localhost-only)
perms api port <n>      # listen port (default 2480)
perms api rpm <n>       # rate limit, requests/min per token (0 = unlimited)

⚠️ Security. The API is bound to localhost by default and a token is always required. If you change perms api host to expose it to members out in the world, put it behind a firewall / VPN or a reverse proxy — never bind it openly to 0.0.0.0. Each token is hashed at rest, rate-limited (perms api rpm), and every command call is audit-logged.

Admin surfaces

You can administer RBAC three ways — all backed by the same config:

1. perms command (terminal / Discord / in-game) — the full CLI.
2. Discord panel — perms panel posts an interactive panel (toggle RBAC/API, add users in bulk, assign roles, flip capability checkboxes, issue/revoke tokens).
3. In-game admin screen — the ProxyBridge mod's /pb admin opens a GUI (needs an admin token).

Quick start

1. Add yourself / your admins first, then enable — so you don't lock yourself out (the account owner is always admin as a fail-safe).
2. Assign members and enable:

perms user add <name> user           # assign a role (creates the user)
perms user grant <name> group.travel  # add a capability group
perms token issue <name>              # prints a token ONCE — give it to them
perms api on                          # enable the HTTP API (localhost-bound)
perms enable on                       # turn the whole system on

3. Members register the bot in the ProxyBridge mod (/pb bots add <id> <ip:port> <token>) and use /pb pull, /pb goto, etc.

Migrating an existing whitelist

perms migrate          # dry-run: shows what would change
perms migrate apply    # whitelist → role `user`; spectator-only → `guest` + connect.spectate

The blacklist is ignored (default-deny already covers it). Migration is idempotent and never downgrades an already-assigned user.

Command reference

perms enable <on/off>                 # master switch (off = legacy owner/whitelist behaviour)
perms api <on/off>                    # the token-authed HTTP /command + /position server
perms api host <ip> | port <n> | rpm <n>   # bind address / port / rate limit (0 = unlimited)
perms status | reload | export
perms user list
perms user add <name> [role]
perms user role <name> <admin|operator|user|guest>
perms user grant <name> <perm>        # e.g. group.combat, module.killaura
perms user deny <name> <perm>
perms user ungrant <name> <perm> | undeny <name> <perm>
perms user mode <name> <control|spectate>
perms user info <name> | remove <name>
perms token issue <name> | revoke <name> <index>
perms role list | group list
perms migrate [apply]
perms panel                           # post the Discord admin panel