External connections

Summary 🔗

The tl;dr is...

• LuckPerms uses an internet connection to securely download required libraries and translation bundles when it first starts
• LuckPerms will send data to a external service in order to provide certain functions (/lp editor etc)
• LuckPerms does not report to metrics or analytics services

The specific nature of these interactions and usages are documented below.

Downloading libraries 🔗

LuckPerms makes use of a lot of libraries - all of which are listed here.

The plugin can be configured and used in a number of ways. For example, it supports a number of storage methods, each of which require their own set of drivers. Most plugins simply bundle (or "shade") these libraries into the plugin jar file - however, this is not practical for LuckPerms, as the high number of libraries would produce a huge final jar size. The solution is to download the required libraries at runtime, depending on the configuration being used.

The download process 🔗

• Downloads will only be attempted for libraries which are required
• Downloaded binaries are cached in the /LuckPerms/libs/ folder after the initial download. If a library is already present here, a connection to the download server will not be attempted.
• The URL and version of libraries is hardcoded within the plugin - they will never automatically update.

All libraries are downloaded from https://libraries.luckperms.net/ or https://repo1.maven.org/maven2/. The latter is a public software repository commonly referred to as the "Central Repository" or "Maven Central", and the former is a repository owned and controlled by the LuckPerms project which mirrors Maven Central.

Maven Central is a trustworthy source - it is used by most Java developers and open source projects.

As a precautionary measure in case either of the sites become compromised, the plugin will perform additional verification during the download process to ensure that libraries are intact and as expected.

The verification process 🔗

Each dependency that can be downloaded at runtime, along with it's version and location within Maven Central is defined in this source code file in LuckPerms.

Each entry also includes a SHA-256 hash of the dependency file, at the time the release was first included within LuckPerms. This hash is used as a checksum for downloaded files.

When a dependency is downloaded from the repository, the same hashing process is performed on the downloaded data, and the hash of this is compared with the checksum of the dependency.

The integrity of the downloaded file can be assumed to be ok if the two hashes are equal. If the hashes are not equal, then one of two things has most likely happened:

• Only a part of the file has been downloaded, something went wrong in the download process
• The dependency file has been tampered with in some way, and should not be trusted

In both cases, the downloaded binary data is discarded by LuckPerms, and the plugins startup is cancelled.

These checks are put in place to minimise the risk of malicious code from being executed should the download servers become compromised. It effectively eliminates the possibility of arbitrary code execution taking place, and makes the system just as secure as shading the dependencies directly into the jar.

Downloading translation bundles 🔗

The messages used in LuckPerms commands have kindly been translated by the community.

These translations are automatically exported, compiled into "translation bundle" files, and then made available from an API endpoint. This means that translations can be added/improved over time, without requiring a recompilation of the plugin.

The translation bundles are updated automatically (roughly every 24 hours) by the plugin. This is a relatively safe process, as the translations themselves do not affect how the plugin works.

The functionality can be disabled in the LuckPerms config.

Web apps (/lp editor etc) 🔗

LuckPerms has a number of web apps that are hosted centrally for everyone to use.

• Web Editor - an editor for permissions data
• Verbose Viewer - a viewer for verbose recording logs
• Tree Viewer - a viewer to visualise tree permission structures

The clients for each of these applications can be found at

• https://luckperms.net/editor/
• https://luckperms.net/verbose/
• https://luckperms.net/treeview/

respectively.

The source code for these sites is freely available here: https://github.com/LuckPerms/LuckPermsWeb

Communication between the editors/viewers and the plugin (which runs on your Minecraft server) is performed using isolated data payloads. There is never any direct communication between the editors/viewers and the server.

You can freely share the links to editor sessions - any changes must always be applied by running a command on the Minecraft server, or by explictly trusting the editor session.

Data is posted to & read from https://usercontent.luckperms.net - effectively a very simple content storage system. This service is written and hosted by Luck.

Again, the source is freely available here: https://github.com/lucko/bytebin

Additional technical details can be found here.

Metrics and auto-updaters 🔗

• LuckPerms does not and never will report back to analytics or monitoring services.
• LuckPerms does not and never will automatically check for (or automatically install 😠) updates.