Plugin Framework

Workspace System

Tightly control filesystem access and logic execution for plugins through enterprise-grade sandboxing.

Authorization via Config

Plugin permissions are explicitly authorized in xypriss.config.jsonc under the $internal key.

json

{
    "$internal": {
        "@my-org/my-plugin": {
            "__xfs__": {
                "path": "ROOT://.private/plugin-data",
            }
        }
    }
}

Path Resolution Anchors

The path resolver enforces explicit semantic anchors to prevent unauthorized traversal.

ROOT://

Resolves relative to the Global Project Root. Shifts to Plugin Root when called within a plugin.

CWD://

Resolves relative to the active execution directory. Use with extreme caution as it grants host-level access.

Accessing Workspaces

Plugins retrieve their authorized filesystem instance from the global __sys__ API.

typescript

export function initMyPlugin() {
    const workspaceFS = __sys__.plugins.get("@my-org/my-plugin");
    
    if (!workspaceFS) {
        throw new Error("Plugin not authorized");
    }

    // Trapped within the assigned sandbox
    const files = workspaceFS.fs.lsDirs(".");
}

Void Sandbox (Bac à sable Éphémère)

If a plugin is not explicitly authorized, XyPriss provisions a Void Sandbox—an ephemeral, empty temporary directory. The plugin continues to run without crashing, but its filesystem operations natively return empty results, protecting real project data.

Multi-Tenant Isolation

Caller-Aware Resolution: Anchors like ROOT:// adapt automatically based on whether the caller is the host app or a specific plugin.

Env Sandboxing: Plugins can only "see" environment variables defined in their own .env files.

Plugin Development

Master the art of building scalable and secure plugins for XyPriss.