Developer API Overview
Relevant source files
The following files were used as context for generating this wiki page:- API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java
- API/src/main/java/xyz/xreatlabs/nexauth/api/provider/NexAuthProvider.java
- API/src/main/java/xyz/xreatlabs/nexauth/api/PlatformHandle.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperBootstrap.java
- Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java
- API/src/main/java/xyz/xreatlabs/nexauth/api/database/ReadWriteDatabaseProvider.java
- API/src/main/java/xyz/xreatlabs/nexauth/api/crypto/CryptoProvider.java
The NexAuth Developer API provides a comprehensive, multi-platform toolkit for interacting with the NexAuth authentication system. It is designed to be platform-agnostic, using generics <P, S> to represent Player and Server objects, allowing for seamless integration on Paper, Velocity, and BungeeCord. The API exposes core functionalities such as authorization management, database interaction, event handling, and cryptographic services.
Developers can leverage this API to create custom integrations, extend authentication logic, or retrieve detailed user data. The central entry point is the NexAuthPlugin interface, which provides access to various specialized providers and handlers. This modular design allows developers to interact with specific subsystems like user authorization, database management, or 2FA without needing to understand the entire internal implementation.
Getting the API Instance
To interact with the NexAuth API, you must first obtain an instance of the NexAuthPlugin. The recommended way to do this is by depending on the NexAuthProvider interface, which is implemented by the platform-specific bootstrap class (e.g., PaperBootstrap).
The following diagram illustrates the process of obtaining the API instance.
Core API Components
The API is structured around a central NexAuthPlugin interface that provides access to various specialized providers and handlers. This design promotes separation of concerns and platform independence.
NexAuthPlugin<P, S> Interface
This is the main interface and the primary entry point for all API interactions. It uses generics <P> for the platform's Player object and <S> for the Server object. It provides getter methods for accessing all major subsystems.
The following class diagram shows the NexAuthPlugin interface and its relationship with other key API components.
Key Providers and Handlers
The NexAuthPlugin interface provides access to several specialized components, each managing a distinct aspect of the authentication system.
| Interface | Description |
|---|---|
PlatformHandle<P, S> | Abstracts platform-specific operations like kicking a player, moving them to a server, or getting their IP address. |
AuthorizationProvider<P> | Manages the authentication state of players, such as checking if a player is logged in. |
ReadWriteDatabaseProvider | Provides methods to read from and write to the user database, including fetching, updating, and creating user profiles. |
CryptoProvider | Handles password hashing and verification. Multiple algorithms are supported. |
ServerHandler<P, S> | Manages server logic, including selecting appropriate lobby or limbo servers for players. |
EventProvider<P, S> | Allows other plugins to listen for and react to various events within the NexAuth lifecycle. |
EmailHandler | Provides functionality to send emails, primarily for password resets and email verification. Null if disabled. |
TOTPProvider | Manages Time-based One-Time Password (2FA) logic. |
LimboIntegration<S> | Provides an integration point for a limbo server system, used to hold unauthenticated players. |
Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java, API/src/main/java/xyz/xreatlabs/nexauth/api/PlatformHandle.java
PlatformHandle<P, S>
The PlatformHandle is a crucial component for creating platform-agnostic plugins. It abstracts away the differences between server platforms like Paper and Velocity.
Key Methods:
getAudienceForPlayer(P player): Gets the Kyori AdventureAudiencefor a player.getUUIDForPlayer(P player): Gets theUUIDof a player.movePlayer(P player, S to): Moves a player to a different server/world.kick(P player, Component reason): Kicks a player from the server.getIP(P player): Retrieves the player's IP address.getServer(String name, boolean limbo): Gets a server/world instance by name.getPlatformIdentifier(): Returns a string identifying the platform (e.g., "paper", "velocity").
Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/PlatformHandle.java:19-106, Plugin/src/main/java/xyz/xreatlabs/nexauth/paper/PaperPlatformHandle.java:22-127
Extensibility
The API is designed to be extensible, allowing developers to register their own implementations for certain components.
Registering a Custom CryptoProvider
You can register a custom password hashing algorithm by implementing the CryptoProvider interface and registering it with the NexAuthPlugin.
// Example of registering a custom crypto provider
CryptoProvider myCustomProvider = new MyCustomCryptoProvider();
nexAuthPlugin.registerCryptoProvider(myCustomProvider);
Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java:125-129, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:286-291
The default crypto provider is configured via config.conf and can be one of several built-in types.
| Provider ID | Description |
|---|---|
SHA-256 | Older, not recommended. Kept for compatibility. |
SHA-512 | Safer than SHA-256, but still not recommended. |
BCrypt-2A | Recommended as a safe, modern hashing algorithm. |
Argon-2ID | Newest and potentially safer than BCrypt, but may have a higher performance impact. |
Sources: Plugin/src/main/java/xyz/xreatlabs/nexauth/common/config/ConfigurationKeys.java:80-89
Registering a Custom DatabaseProvider
The API allows for registering custom database providers, which is particularly useful for migrating data from other authentication plugins. This is done by creating a ReadDatabaseProviderRegistration and registering it.
This diagram shows the flow for registering a custom database provider for data migration.
Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java:112-118, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java:500-598
Common Use Case: Player Authentication Flow
The following sequence diagram illustrates a simplified view of how API components interact during a player's authentication process.
This diagram shows how the AuthorizationProvider, DatabaseProvider, and CryptoProvider work together to verify a player's password upon login.
Sources: API/src/main/java/xyz/xreatlabs/nexauth/api/NexAuthPlugin.java, Plugin/src/main/java/xyz/xreatlabs/nexauth/common/AuthenticNexAuth.java
Summary
The NexAuth Developer API is a powerful and flexible tool for developers. Its platform-agnostic design, modular provider system, and clear extension points for cryptography and data persistence make it suitable for a wide range of custom integrations. By leveraging the NexAuthPlugin interface, developers can safely and efficiently interact with the core features of NexAuth to build new functionalities or connect existing systems.