Plugin Permission System #

The XyPriss Plugin System now includes a robust permission model that allows developers to strictly control which actions (hooks) a plugin is allowed to execute. This enhances security by ensuring that plugins only have access to the lifecycle events and features they explicitly require.

Overview #

By default, plugins may be allowed to execute any hook. However, you can configure pluginPermissions in your server options to enforce a whitelist of allowed hooks for specific plugins. If a plugin attempts to execute a hook that is not in its allowed list, the action is blocked, and an error is logged.

Configuration #

To configure permissions, add the pluginPermissions array to your ServerOptions when initializing the server.

Example Configuration #

import { createServer, PluginHookIds } from "xypriss";

const app = await createServer({
    // ... other options
    pluginPermissions: [
        {
            name: "my-secure-plugin",
            allowedHooks: [
                PluginHookIds.ON_SERVER_START,
                PluginHookIds.ON_REQUEST,
                // Add other allowed hooks here
            ],
            // Optional: 'allow' (default) or 'deny'
            policy: "allow",
        },
        {
            name: "untrusted-plugin",
            allowedHooks: [], // No hooks allowed
        },
    ],
});

Options #

• name: The name of the plugin as defined in its name property.
• allowedHooks: An array of PluginHookIds strings, or "*" to allow all hooks.
• policy: (Optional) "allow" or "deny". Defaults to "allow".
  • If policy is "deny", the allowedHooks list acts as a whitelist (only these are allowed).
  • If policy is "allow", the allowedHooks list acts as a whitelist if specified.

Available Hook IDs #

We provide standardized constants for all plugin hooks to avoid typos and ensure consistency. These are available via PluginHookIds.

Lifecycle Hooks #

• PluginHookIds.ON_REGISTER (PLG.LIFECYCLE.REGISTER): Called when the plugin is registered.
• PluginHookIds.ON_SERVER_START (PLG.LIFECYCLE.SERVER_START): Called when the server starts.
• PluginHookIds.ON_SERVER_READY (PLG.LIFECYCLE.SERVER_READY): Called when the server is fully ready (listening).
• PluginHookIds.ON_SERVER_STOP (PLG.LIFECYCLE.SERVER_STOP): Called when the server stops.

HTTP Request/Response Hooks #

• PluginHookIds.ON_REQUEST (PLG.HTTP.ON_REQUEST): Executed on every incoming request.
• PluginHookIds.ON_RESPONSE (PLG.HTTP.ON_RESPONSE): Executed when a response is finished.
• PluginHookIds.ON_ERROR (PLG.HTTP.ON_ERROR): Executed when an error occurs in a route.
• PluginHookIds.MIDDLEWARE (PLG.HTTP.MIDDLEWARE): Permission to register custom middleware.

Security Hooks #

• PluginHookIds.ON_SECURITY_ATTACK (PLG.SECURITY.ATTACK_DETECTED): Triggered when a security threat is detected.
• PluginHookIds.ON_RATE_LIMIT (PLG.SECURITY.RATE_LIMIT): Triggered when a rate limit is exceeded.

Metrics & Monitoring Hooks #

• PluginHookIds.ON_RESPONSE_TIME (PLG.METRICS.RESPONSE_TIME): Receives response time metrics.
• PluginHookIds.ON_ROUTE_ERROR (PLG.METRICS.ROUTE_ERROR): Receives route error metrics.

Logging Hooks #

• PluginHookIds.ON_CONSOLE_INTERCEPT (PLG.LOGGING.CONSOLE_INTERCEPT): Privileged Hook. Allows interception of all server and application console output. Disabled by default.

Routing #

• PluginHookIds.REGISTER_ROUTES (PLG.ROUTING.REGISTER_ROUTES): Permission to register new routes.

Advanced Permission Features #

Sticky Denied Hooks #

In addition to allowedHooks, XyPriss supports deniedHooks. These are "sticky" permissions that explicitly block a hook, regardless of any other allow rules (including the * wildcard).

• Priority: deniedHooks always take precedence over allowedHooks.
• Persistence: Once a hook is added to deniedHooks in the static configuration, it explicitly overrides any attempts to execute that hook.

Enforcement and Stability #

The permission system is integrated directly into the PluginManager execution pipeline.

1. Pre-execution Check: Before any hook is executed, the system verifies the plugin's effective permissions.
2. Denial Handling: If a hook is denied: - The execution is skipped for that specific plugin. - A logger.error is issued with details about the blocked attempt. - The server does not crash. The rest of the hook chain and the request lifecycle continue normally.

Configuration-Driven Permissions #

Permissions in XyPriss are primarily driven by the static configuration provided during server initialization. This ensures a predictable and secure environment where plugin capabilities are defined at startup.