Plugin Permission System
XyPriss uses a Capability-Based Security Model to strictly control plugin actions, enforcing a zero-trust environment by default.
Permission Resolution Engine
Denied hooks always override allow-lists, even with wildcards.
High-privilege hooks must be explicitly declared as strings.
Configuring Permissions
Permissions are defined in the xypriss.config.jsonc file. This allows for granular control over what each plugin can and cannot do within your server instance.
You must define an explicit whitelist of hooks for each plugin within the $internal block. For a detailed guide on how to structure this configuration, see our tutorial.
Permission Constants
XyPriss provides semantic constants to define capabilities. Certain hooks are marked as Privileged and require extra caution. For a complete technical breakdown of each permission, see the .
| Permission ID | Level | Capability |
|---|---|---|
| XHS.HOOK.HTTP.REQUEST | PRIVILEGED | Intercept every incoming HTTP request. |
| XHS.PERM.SECURITY.CONFIGS | PRIVILEGED | Read full server configuration and secrets. |
| XHS.PERM.ROUTING.BYPASS | CRITICAL | Register routes outside the plugin namespace. |
| XHS.HOOK.METRICS.* | STANDARD | Monitor performance and error metrics. |
Request Data Masking
To protect PII (Personally Identifiable Information), XyPriss automatically masks sensitive request fields before passing them to plugin hooks.
req.bodyreq.queryreq.cookiesreq.headersreq.paramsWhen restricted, these fields return a standard security warning. Access requires the XHS.PERM.SECURITY.SENSITIVE_DATA permission.
Zero-Trust Signatures (G3)
The G3 architecture ensures plugin integrity via the xypriss.plugin.xsig manifest. This Ed25519-signed block prevents post-installation tampering.
Author Pinning (TOFU)
The author's public key is pinned upon first installation. Updates must be signed by the same key.
Deep Audit
The XHSC engine re-calculates the SHA-256 fingerprint of every plugin file during server startup.
Sticky Denials
XyPriss supports immutable "Sticky Denials" via the deniedHooks array. These always take precedence over the allowedHooks whitelist, including the * wildcard.
Enforcement Logic
Once a hook is denied in the static configuration, it cannot be overridden at runtime by any plugin management logic or dynamic permission updates.
High-Privilege Restrictions
Certain capabilities are classified as High-Privilege. To prevent accidental elevation, these are never granted via the * wildcard and must be explicitly declared.
Learn how to build and publish high-performance plugins for the XyPriss ecosystem.