> For the complete documentation index, see [llms.txt](https://easyauth.papelship.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://easyauth.papelship.com/documentation/plugins/custom-plugins.md).

# Custom Plugins

EasyAuth allows developers to build custom security extensions, telemetry hooks, and proprietary hardware detectors using the `i_plugin` interface.

***

## The `i_plugin` Interface

All plugins inherit from `easyauth::plugins::i_plugin` defined in `PluginManager.h`:

```cpp
#include "PluginManager.h"
#include <iostream>

class MyCustomPlugin : public easyauth::plugins::i_plugin {
public:
    MyCustomPlugin() = default;
    virtual ~MyCustomPlugin() = default;

    // 1. Return metadata about your plugin
    easyauth::plugins::plugin_info get_info() const override {
        easyauth::plugins::plugin_info info;
        info.id = "my_custom_detector";
        info.name = "Proprietary Threat Detector";
        info.version = "1.0.0";
        info.author = "MySecurityTeam";
        info.description = "Scans for custom blacklisted drivers and anomalous overlays";
        return info;
    }

    // 2. Attach custom telemetry data sent with every EasyAuth packet
    void append_telemetry(std::unordered_map<std::string, std::string>& out_telemetry) override {
        out_telemetry["my_custom_sensor"] = "active";
        out_telemetry["driver_count"] = "42";
    }

    // 3. React to EasyAuth lifecycle events
    void on_event(const easyauth::plugins::event_data& event) override {
        if (event.type == easyauth::plugins::event_type::session_initialized) {
            std::cout << "[MyCustomPlugin] Session initialized by core!\n";
        }
    }

    // 4. Implement custom security check callback
    easyauth::plugins::threat_detection on_security_check(bool deep_scan = false) override {
        easyauth::plugins::threat_detection threat;
        
        // Example check: scan for unauthorized overlay window
        if (FindWindowA(NULL, "DangerousOverlay")) {
            threat.detected = true;
            threat.threat_level = easyauth::plugins::threat_severity::critical;
            threat.reason = "DangerousOverlay detected";
            threat.recommended_action = easyauth::plugins::threat_action::ban_and_close;
        }

        return threat;
    }
};
```

***

## Registering Your Custom Plugin

Register your custom plugin before calling `easyauth::initialize()`:

```cpp
#include "qPapelEasyAuth.h"

int main() {
    // Instantiate your plugin as a shared pointer
    auto my_plugin = std::make_shared<MyCustomPlugin>();

    // Register with EasyAuth
    easyauth::register_plugin(my_plugin);

    // Initialize EasyAuth
    easyauth::initialize();

    // ... continue authentication ...
    return 0;
}
```