xypriss 9.11.13 → 9.12.0

package/dist/src/plugins/builtin/xems/XemsBuiltinPlugin.js

@@ -0,0 +1,246 @@
+/**
+ * XEMS Core Built-in Plugin
+ *
+ * Handles the initialization, validation, and lifecycle of XEMS (XyPriss Entry Management System).
+ * Provides the core persistent storage and session management capabilities.
+ *
+ * Identifier: xypriss::xems.core
+ */
+import { Configs } from "../../../ConfigurationManager";
+import { XemsRunner } from "./XemsPlugin";
+export class XemsBuiltinPlugin {
+    constructor() {
+        this.name = "xypriss::xems.core";
+        this.version = "1.1.0";
+        this.type = "security";
+        this.description = "XyPriss Entry Management System (Session & Storage)";
+        this.sessionOptions = {
+            sandbox: "xems.internal-session",
+            cookieName: "xems_token",
+            headerName: "x-xypriss-token",
+            ttl: "15m",
+            autoRotation: true,
+            attachTo: "session",
+            gracePeriod: 1000,
+        };
+        this.hasValidSecret = false;
+        // Create a dedicated runner for this server instance to allow
+        // multiple servers to have isolated XEMS processes.
+        this.runner = new XemsRunner();
+    }
+    /**
+     * Initialize XEMS with system configuration
+     */
+    async onServerStart(server) {
+        const app = server.app;
+        const logger = app.logger;
+        // 1. Configuration Extraction
+        // Use local app config strictly to avoid global singleton pollution in multi-server/auxiliary modes
+        // If not explicitly configured, fallback to global defaults only if NOT an auxiliary server
+        let xemsOptions = app.configs?.server?.xems;
+        if (!xemsOptions) {
+            if (app.configs?.isAuxiliary) {
+                // Auxiliary servers should NEVER auto-spawn persistence unless explicitly requested.
+                // We provide minimal defaults to avoid crashes but keep features disabled.
+                xemsOptions = { enable: false };
+            }
+            else {
+                // Fallback to global singleton only for primary/non-auxiliary servers
+                xemsOptions = Configs.get("server")?.xems || { enable: false };
+            }
+        }
+        // Expose this instance's runner on the app object for multi-server support
+        app.xems = this.runner;
+        const isAuxiliary = app.configs?.isAuxiliary;
+        if (!isAuxiliary) {
+            logger.info("plugins", "Initializing XEMS Built-in Core Plugin...");
+        }
+        // Apply session options from config or defaults
+        this.sessionOptions = {
+            sandbox: xemsOptions.sandbox || "auth-session",
+            cookieName: xemsOptions.cookieName || "xems_token",
+            headerName: xemsOptions.headerName || "x-xypriss-token",
+            ttl: xemsOptions.ttl || "15m",
+            autoRotation: xemsOptions.autoRotation !== false,
+            attachTo: xemsOptions.attachTo || "session",
+            gracePeriod: xemsOptions.gracePeriod || 1000,
+        };
+        if (!isAuxiliary) {
+            logger.info("plugins", `XEMS Session Sandbox: ${this.sessionOptions.sandbox}`);
+        }
+        // Check for valid secret (mandatory for any XEMS API usage)
+        const secret = xemsOptions.persistence?.secret;
+        if (secret &&
+            typeof secret === "string" &&
+            Buffer.byteLength(secret, "utf8") === 32) {
+            this.hasValidSecret = true;
+        }
+        else if (xemsOptions.persistence?.enabled) {
+            logger.error("plugins", "XEMS Persistence enabled but no valid 32-byte secret found.");
+        }
+        // 2. Persistence Initialization
+        if (xemsOptions.persistence?.enabled) {
+            const { path: pathStr, secret, resources, } = xemsOptions.persistence;
+            if (pathStr && secret) {
+                // Use the static factory to get/create a runner for this path.
+                // This ensures multiple servers/plugins sharing a path also share the process.
+                this.runner = XemsRunner.getInstance(pathStr, {
+                    secret,
+                    cacheSize: resources?.cacheSize,
+                });
+                // Attach the shared runner to the app
+                app.xems = this.runner;
+                try {
+                    this.runner.enablePersistence(pathStr, secret, {
+                        cacheSize: resources?.cacheSize,
+                    });
+                }
+                catch (err) {
+                    logger.error("plugins", "Failed to enable XEMS persistence on shared runner", err);
+                }
+            }
+            else if (!isAuxiliary) {
+                logger.warn("plugins", "XEMS Persistence requested but path or secret missing. Running in ephemeral mode.");
+            }
+        }
+        // 3. Resource & Health Validation (Warmup)
+        try {
+            const startTime = performance.now();
+            const pong = await this.runner.ping();
+            const duration = performance.now() - startTime;
+            if (pong === "pong" || pong) {
+                if (!isAuxiliary) {
+                    logger.info("plugins", `XEMS Core validated successfully (Ping: ${duration.toFixed(3)}ms)`);
+                }
+            }
+            else {
+                logger.warn("plugins", "XEMS Core returned unexpected ping response");
+            }
+        }
+        catch (e) {
+            logger.error("plugins", "XEMS Core health check failed. Binary might be missing or crashed.", e);
+        }
+    }
+    /**
+     * Native/Fast validation logic (runs on every request)
+     */
+    async onRequest(req, res, next) {
+        const { sandbox, cookieName, headerName, ttl, autoRotation, attachTo } = this.sessionOptions;
+        // 1. Token Extraction
+        const token = (req.cookies && req.cookies[cookieName]) ||
+            req.headers[headerName];
+        // 2. Inject xLink (Session Initiation)
+        res.xLink = async (data, linkOptions) => {
+            if (!this.hasValidSecret) {
+                throw new Error("[XEMS] CRITICAL: Attempted to use XEMS API (xLink) without a valid 32-byte secret key configured. " +
+                    "Security policy requires a mandatory encryption key.");
+            }
+            let actualSandbox = sandbox;
+            let actualAttachTo = attachTo;
+            let actualTtl = ttl;
+            if (typeof linkOptions === "string") {
+                actualSandbox = linkOptions;
+            }
+            else if (linkOptions) {
+                if (linkOptions.sandbox)
+                    actualSandbox = linkOptions.sandbox;
+                if (linkOptions.attachTo)
+                    actualAttachTo = linkOptions.attachTo;
+                if (linkOptions.ttl)
+                    actualTtl = linkOptions.ttl;
+            }
+            const newToken = await this.runner
+                .from(actualSandbox)
+                .createSession(data, {
+                ttl: actualTtl,
+            });
+            res._xemsNewToken = newToken;
+            // Apply immediately
+            res.cookie(cookieName, newToken, {
+                httpOnly: true,
+                secure: true,
+                sameSite: "strict",
+            });
+            res.setHeader(headerName, newToken);
+            req[actualAttachTo] = data;
+            return newToken;
+        };
+        // 2b. Inject xUnlink (Session Termination)
+        res.xUnlink = async (unlinkOptions) => {
+            let actualSandbox = sandbox;
+            let actualAttachTo = attachTo;
+            if (typeof unlinkOptions === "string") {
+                actualSandbox = unlinkOptions;
+            }
+            else if (unlinkOptions) {
+                if (unlinkOptions.sandbox)
+                    actualSandbox = unlinkOptions.sandbox;
+                if (unlinkOptions.attachTo)
+                    actualAttachTo = unlinkOptions.attachTo;
+            }
+            const currentToken = (req.cookies && req.cookies[cookieName]) ||
+                req.headers[headerName];
+            if (currentToken) {
+                await this.runner.from(actualSandbox).del(currentToken);
+            }
+            res.clearCookie(cookieName);
+            res.removeHeader(headerName);
+            req[actualAttachTo] = null;
+        };
+        // 3. Session Recovery & Rotation
+        if (token && this.hasValidSecret) {
+            try {
+                const session = await this.runner.from(sandbox).rotate(token, {
+                    ttl,
+                    gracePeriod: this.sessionOptions.gracePeriod,
+                });
+                if (session) {
+                    req[attachTo] = session.data;
+                    if (autoRotation && session.newToken) {
+                        res._xemsNewToken = session.newToken;
+                        // Intercept response methods to inject the rotated token
+                        const originalSend = res.send;
+                        res.send = function (body) {
+                            const newToken = res._xemsNewToken;
+                            if (newToken) {
+                                res.cookie(cookieName, newToken, {
+                                    httpOnly: true,
+                                    secure: true,
+                                    sameSite: "strict",
+                                });
+                                res.setHeader(headerName, newToken);
+                            }
+                            return originalSend.call(this, body);
+                        };
+                        const originalJson = res.json;
+                        res.json = function (data) {
+                            const newToken = res._xemsNewToken;
+                            if (newToken) {
+                                res.cookie(cookieName, newToken, {
+                                    httpOnly: true,
+                                    secure: true,
+                                    sameSite: "strict",
+                                });
+                                res.setHeader(headerName, newToken);
+                            }
+                            return originalJson.call(this, data);
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                // Ignore session recovery errors (expired/invalid)
+            }
+        }
+        next();
+    }
+    /**
+     * Cleanup resources on server stop
+     */
+    async onServerStop() {
+        if (this.runner) {
+            this.runner.destroy();
+        }
+    }
+}
+//# sourceMappingURL=XemsBuiltinPlugin.js.map

package/dist/src/plugins/builtin/xems/XemsBuiltinPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XemsBuiltinPlugin.js","sourceRoot":"","sources":["../../../../../src/plugins/builtin/xems/XemsBuiltinPlugin.ts"],"names":[],"mappings":"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"}

package/dist/src/plugins/builtin/xems/XemsPlugin.d.ts

@@ -0,0 +1,169 @@
+import { XyApp } from "../../../types/XyApp.type";
+import { XyAppInternal } from "../../../types/httpServer.type";
+interface XemsCommand {
+    action: string;
+    key?: string;
+    value?: string;
+    sandbox?: string;
+    ttl?: string;
+    rotate?: boolean;
+    grace_period?: number;
+}
+interface XemsOptions {
+    persistPath?: string;
+    cacheSize?: number;
+    secret?: string;
+    gracePeriod?: number;
+}
+interface XemsResponse {
+    status: string;
+    data?: string;
+    new_token?: string;
+    error?: string;
+}
+export declare class XemsError extends Error {
+    action: string;
+    details: string;
+    constructor(action: string, details: string);
+}
+/**
+ * XEMS Runner (Long-running process manager)
+ * Manages the persistent Rust process for in-memory storage.
+ */
+export declare class XemsRunner {
+    private process;
+    private queue;
+    private isReady;
+    private binaryPath;
+    private options;
+    private logger;
+    constructor(options?: XemsOptions);
+    /**
+     * Enables hardware-bound persistent storage for XEMS.
+     */
+    private static runnersByPath;
+    /**
+     * Internal factory for getting or creating a runner for a specific path.
+     * This ensures only one process exists for a given file in the entire process.
+     */
+    static getInstance(pathStr: string, options?: XemsOptions): XemsRunner;
+    enablePersistence(pathStr: string, secret: string, resources?: {
+        cacheSize?: number;
+    }): void;
+    /**
+     * Finds the XEMS binary location.
+     * Starts with development paths, falls back to production locations.
+     */
+    /**
+     * Strategic discovery of the xems binary across different environments.
+     * Robust logic handling dev, prod, and installed contexts.
+     */
+    private discoverBinary;
+    private init;
+    private handleResponse;
+    execute(cmd: XemsCommand): Promise<XemsResponse>;
+    ping(): Promise<string>;
+    /**
+     * Set a value in a sandbox with optional TTL.
+     */
+    private set;
+    /**
+     * Get a value from a sandbox.
+     */
+    private get;
+    /**
+     * Delete/Invalidate a key in a sandbox.
+     */
+    private del;
+    /**
+     * [SESSION LAYER] Creates a new session entry.
+     * Generates a random opaque token, stores `data` under it, and returns the token.
+     * Use this when you don't care about the key — you just want a session handle.
+     *
+     * @param sandbox - The isolated namespace to store the session in
+     * @param data    - Any serializable data to associate with the session
+     * @param options - Optional TTL and rotation settings
+     * @returns The generated session token (opaque handle)
+     */
+    createSession(sandbox: string, data: any, options?: {
+        ttl?: string;
+        rotate?: boolean;
+    }): Promise<string>;
+    /**
+     * [SESSION LAYER] Resolves a session token back to its data.
+     * Optionally rotates the token (invalidates old one, issues a new one) to
+     * prevent replay attacks.
+     *
+     * USES ATOMIC ROTATION with Grace Period to prevent race conditions on
+     * simultaneous requests.
+     *
+     * @param token   - The opaque session token previously returned by createSession
+     * @param options - sandbox, optional rotation, optional new TTL, optional custom grace period
+     * @returns `{ data, newToken? }` or `null` if the token is expired/unknown
+     */
+    resolveSession(token: string, options: {
+        sandbox: string;
+        rotate?: boolean;
+        ttl?: string;
+        gracePeriod?: number;
+    }): Promise<{
+        data: any;
+        newToken?: string;
+    } | null>;
+    /**
+     * Fluent API entry point. Returns a context for a specific sandbox.
+     * @example xems.from("auth").set("user:1", data)
+     */
+    from(sandbox: string): XemsSandboxContext;
+    /**
+     * Alias for from()
+     * Fluent API entry point. Returns a context for a specific sandbox.
+     * @example xems.select("auth").set("user:1", data)
+     */
+    select(sandbox: string): XemsSandboxContext;
+    /**
+     * Contextual retrieval for multi-server environments.
+     * Returns the XEMS instance attached to the provided app object if available,
+     * otherwise returns this instance.
+     */
+    forApp(app: XyAppInternal | XyApp): XemsRunner;
+    /**
+     * Forcefully stops the XEMS process and cleans up resources.
+     */
+    destroy(): void;
+}
+/**
+ * Contextual wrapper for XEMS operations within a specific sandbox.
+ * Provides a cleaner, fluent API for advanced operations.
+ */
+declare class XemsSandboxContext {
+    private runner;
+    private sandbox;
+    constructor(runner: XemsRunner, sandbox: string);
+    /** Set a value in this sandbox */
+    set(key: string, value: string, ttl?: string): Promise<boolean>;
+    /** Get a value from this sandbox */
+    get(key: string): Promise<string | null>;
+    /** Remove a key from this sandbox */
+    del(key: string): Promise<boolean>;
+    /**
+     * Perform an atomic rotation of a token in this sandbox.
+     * Returns the original data and the new rotated token.
+     */
+    rotate(token: string, options?: {
+        ttl?: string;
+        gracePeriod?: number;
+    }): Promise<{
+        data: any;
+        newToken?: string;
+    } | null>;
+    /**
+     * Create a new session in this sandbox.
+     */
+    createSession(data: any, options?: {
+        ttl?: string;
+    }): Promise<string>;
+}
+export declare const xems: XemsRunner;
+export {};
+//# sourceMappingURL=XemsPlugin.d.ts.map

package/dist/src/plugins/builtin/xems/XemsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XemsPlugin.d.ts","sourceRoot":"","sources":["../../../../../src/plugins/builtin/xems/XemsPlugin.ts"],"names":[],"mappings":"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"}