xypriss 9.11.13 → 9.12.0

package/dist/src/utils/ProjectDiscovery.js

@@ -0,0 +1,302 @@
+import fs from "fs";
+import path from "path";
+import { ConfigSyntaxParser } from "./ConfigSyntaxParser";
+/**
+ * Checks if a directory is a "Real Project" root based on hierarchical criteria.
+ * Criteria:
+ * 1. (package.json + node_modules) -> Strong baseline
+ * 2. (package.json + src + tsconfig.json) -> High priority
+ */
+export function isProjectRoot(dir) {
+    const pkgPath = path.join(dir, "package.json");
+    if (!fs.existsSync(pkgPath))
+        return false;
+    // Strong Heuristics (Zero FS Read)
+    const hasNodeModules = fs.existsSync(path.join(dir, "node_modules"));
+    const hasTsConfig = fs.existsSync(path.join(dir, "tsconfig.json"));
+    const hasSrc = fs.existsSync(path.join(dir, "src"));
+    const hasXyConfig = fs.existsSync(path.join(dir, "xypriss.config.json")) ||
+        fs.existsSync(path.join(dir, "xypriss.config.jsonc"));
+    if (hasNodeModules || hasXyConfig || (hasSrc && hasTsConfig))
+        return true;
+    // Package Metadata Heuristic: A 'Real' package root is a unit that
+    // has an identity (name + version). This correctly identifies
+    // installed plugins even if they've been flattened or lack source configs.
+    try {
+        const pkgStr = fs.readFileSync(pkgPath, "utf-8");
+        // Fast pre-check before parsing JSON
+        if (pkgStr.includes('"name"') && pkgStr.includes('"version"')) {
+            const pkg = JSON.parse(pkgStr);
+            if (pkg.name && pkg.version)
+                return true;
+        }
+    }
+    catch {
+        // Any error in reading/parsing means it's not a valid project root
+    }
+    return false;
+}
+/**
+ * Identifies the project root for a given caller path by traversing up the filesystem.
+ */
+export function identifyProjectRoot(filePath) {
+    // Ensure the path is absolute and exists before traversing
+    if (!path.isAbsolute(filePath)) {
+        try {
+            filePath = path.resolve(filePath);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!fs.existsSync(filePath))
+        return undefined;
+    let current = path.dirname(filePath);
+    const systemRootDir = path.parse(current).root;
+    while (current !== systemRootDir) {
+        if (isProjectRoot(current)) {
+            return current;
+        }
+        current = path.dirname(current);
+    }
+    return undefined;
+}
+let rootInterceptor = null;
+export function setRootInterceptor(interceptor) {
+    rootInterceptor = interceptor;
+}
+/**
+ * Retrieves the project root of the code currently executing by analyzing the stack trace.
+ */
+export function getCallerProjectRoot() {
+    const stack = new Error().stack;
+    if (!stack)
+        return undefined;
+    const lines = stack.split("\n");
+    let callerFilePath = "";
+    let lastEngineFilePath = "";
+    // Line 0 is 'Error', Line 1 is the call to getCallerProjectRoot itself
+    for (let i = 2; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line || line.includes(" (node:") || line.includes(" (native"))
+            continue;
+        // Robust matching for file paths (handles both absolute and relative,
+        // but filters out non-file frames like '(native)' or 'replace (unknown)')
+        const match = line.match(/\((.*\.([jt]s|[cm]js)):\d+:\d+\)$/) ||
+            line.match(/at (.*\.([jt]s|[cm]js)):\d+:\d+$/);
+        if (!match)
+            continue;
+        const filePath = match[1];
+        if (!filePath || filePath === "native" || filePath === "node:fs")
+            continue;
+        // SKIP only purely internal engine files to find the real project caller.
+        // Even internal mods (/mods/) should be considered callers if they have their own root,
+        // so we don't skip them during stack analysis, but we still trust them for security.
+        if (isEngineCorePath(filePath)) {
+            lastEngineFilePath = filePath;
+            continue;
+        }
+        // Skip specifically the property getters if they appear differently
+        if (line.includes("at get [") ||
+            line.includes("at getStrict (") ||
+            line.includes("PluginAPI.") ||
+            line.includes("Plugin."))
+            continue;
+        callerFilePath = filePath;
+        break;
+    }
+    if (!callerFilePath)
+        return undefined;
+    const root = identifyProjectRoot(callerFilePath);
+    if (root && rootInterceptor) {
+        return rootInterceptor(root) || root;
+    }
+    return root;
+}
+/**
+ * Checks if a given file path belongs to the deep engine core.
+ * These files are skipped during stack analysis to find the user/plugin caller.
+ */
+export function isEngineCorePath(filePath) {
+    if (!filePath)
+        return false;
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    // Engine Core (Standard Framework Logic)
+    if (normalizedPath.includes("/XyPriss/src/") ||
+        normalizedPath.includes("/XyPriss/dist/") ||
+        normalizedPath.includes("/node_modules/xypriss/")) {
+        // EXCEPTION: Files inside /XyPriss/src/ and /XyPriss/dist/ are core,
+        // UNLESS the caller is another specific project (like simulations).
+        // But for isolation, we want to skip them.
+        return true;
+    }
+    return false;
+}
+/**
+ * Checks if a given file path belongs directly to the XyPriss Core Engine
+ * or if it comes from an external plugin / user space.
+ * This is used for SECURITY authorization.
+ */
+export function isCoreFrameworkPath(filePath) {
+    if (!filePath)
+        return false;
+    // Normalize path just in case
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    // console.log("[ProjectDiscovery:isCoreFrameworkPath]: normalizedPath: ", normalizedPath);
+    // Authorize trusted internal mods within the framework repository
+    if (normalizedPath.includes("/XyPriss/mods/"))
+        return true;
+    // Exclude other plugins even if they contain 'src' or are named 'xypriss-something'
+    if (normalizedPath.includes("/mods/"))
+        return false;
+    // Engine Core is always trusted
+    return isEngineCorePath(filePath);
+}
+/**
+ * Validates a call stack to determine whether the execution trace originated
+ * safely from within the core framework, dropping unauthorized usage.
+ */
+export function isCoreStack(stack) {
+    if (!stack)
+        return false;
+    // Parse the stack specifically to find the originating (calling) module
+    const lines = stack.split("\n");
+    // Line 0 is Error message. Line 1 is the interception site. Line 2+ traces back.
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        // Skip internal Node/Bun native APIs in the trace
+        if (line.includes(" (node:") ||
+            line.includes(" (bun:") ||
+            line.includes(" (internal:") ||
+            line.includes(" (native") ||
+            line.trim() === "at native")
+            continue;
+        // We look for the first real file in the trace that isn't native or our blocker script
+        // We use . (dot) to match both .ts and .js versions of the blocker
+        if (line.includes("NativeApiBlocker."))
+            continue;
+        if (line.includes("module.js") ||
+            line.includes("internal/modules/") ||
+            line.includes("node:internal"))
+            continue;
+        // If the first actionable file trace we find is outside the core, immediate rejection
+        // Skip common framework files to find the real caller
+        if (line.includes("ProjectDiscovery.") ||
+            line.includes("XyServerCreator.") ||
+            line.includes("PluginLoader.") ||
+            line.includes("PluginSecurity.") ||
+            line.includes("PluginHookRunner.") ||
+            line.includes("XPluginManager.") ||
+            line.includes("XyLifecycleManager.") ||
+            line.includes("ConfigLoader.") ||
+            line.includes("StartupProcessor.") ||
+            line.includes("System.") ||
+            line.includes("EnvApi.") ||
+            line.includes("ServerFactory.") ||
+            line.includes("sys.")) {
+            continue;
+        }
+        const match = line.match(/\((.*):\d+:\d+\)$/) ||
+            line.match(/at (.*):\d+:\d+$/) ||
+            line.match(/at (.*)$/);
+        if (match) {
+            const filePath = match[1];
+            if (filePath === "native" ||
+                filePath === "node:fs" ||
+                filePath === "fs")
+                continue;
+            const result = isCoreFrameworkPath(filePath);
+            return result;
+        }
+    }
+    return false;
+}
+/**
+ * Checks if a given file path belongs to a trusted dependency (root node_modules).
+ * Trusted dependencies are those installed in the main project's node_modules
+ * but NOT inside a plugin directory.
+ */
+export function isTrustedDependencyPath(filePath) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    // Authorize node_modules only if NOT inside a /mods/ directory
+    return (normalizedPath.includes("/node_modules/") &&
+        !normalizedPath.includes("/mods/"));
+}
+/**
+ * Checks if a given file path belongs to a plugin (resides in /mods/).
+ */
+export function isPluginPath(filePath) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    return normalizedPath.includes("/mods/");
+}
+/**
+ * Checks if a given file path belongs to a test directory (e.g., /.private/).
+ */
+export function isTestPath(filePath) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    return normalizedPath.includes("/.private/");
+}
+/**
+ * Loads and cleans a XyPriss configuration file (JSON or JSONC).
+ * Removes comments and trailing commas to ensure compatibility with standard JSON.parse.
+ */
+export function loadXyConfig(projectRoot) {
+    for (const name of ["xypriss.config.jsonc", "xypriss.config.json"]) {
+        const configPath = path.join(projectRoot, name);
+        if (fs.existsSync(configPath)) {
+            try {
+                const raw = fs.readFileSync(configPath, "utf-8");
+                const clean = raw
+                    .replace(/("(?:[^"\\]|\\.)*")|\/\/.*|\/\*[\s\S]*?\*\//g, (m, g) => (g ? g : ""))
+                    .replace(/("(?:[^"\\]|\\.)*")|,\s*([}\]])/g, (m, g1, g2) => g1 ? g1 : g2);
+                const rawJson = JSON.parse(clean);
+                // Load package.json from the same directory for resolution
+                let pkgJson = null;
+                const pkgPath = path.join(projectRoot, "package.json");
+                if (fs.existsSync(pkgPath)) {
+                    try {
+                        pkgJson = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+                    }
+                    catch { /* ignore */ }
+                }
+                // Resolve references &(pkg), &(env), etc.
+                const sys = globalThis.__sys__;
+                let envProvider = sys?.__env__;
+                if (sys?.__env__?.getForRoot) {
+                    envProvider = {
+                        has: (key) => sys.__env__.getForRoot(key, projectRoot) !== undefined,
+                        get: (key) => sys.__env__.getForRoot(key, projectRoot)
+                    };
+                }
+                const parser = new ConfigSyntaxParser(pkgJson, envProvider);
+                return parser.resolve(rawJson);
+            }
+            catch (e) {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Verifies if a given directory contains a valid XyPriss plugin contract.
+ * Required: xypriss.config.json(c) with the plugin's namespace under '$internal'
+ */
+export function verifyPluginContract(pluginRoot, pluginName) {
+    const config = loadXyConfig(pluginRoot);
+    if (!config)
+        return false;
+    const internal = config.$internal || config.internal;
+    if (!internal)
+        return false;
+    const pluginContract = internal[pluginName];
+    // The plugin must declare itself in the $internal block WITH 'type': 'plugin'
+    return !!(pluginContract && pluginContract.type === "plugin");
+}
+/**
+ * Retrieves the plugin configuration if it exists and is valid.
+ */
+export function getPluginConfig(pluginRoot) {
+    return loadXyConfig(pluginRoot);
+}
+//# sourceMappingURL=ProjectDiscovery.js.map

package/dist/src/utils/ProjectDiscovery.js.map

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

package/dist/src/utils/SecurityShield.d.ts

@@ -0,0 +1,11 @@
+/**
+ * **XyPriss Security Shield (Recursive Read-Only Proxy)**
+ *
+ * Protects the system API from any mutation attempts at runtime.
+ * This is a core component of the XyPriss Zero-Trust architecture.
+ *
+ * @param target The object to protect.
+ * @param label The name of the object for error messages.
+ */
+export declare function createSecurityShield<T extends object>(target: T, label?: string): T;
+//# sourceMappingURL=SecurityShield.d.ts.map

package/dist/src/utils/SecurityShield.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecurityShield.d.ts","sourceRoot":"","sources":["../../../src/utils/SecurityShield.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EACjD,MAAM,EAAE,CAAC,EACT,KAAK,GAAE,MAAkB,GAC1B,CAAC,CAiEH"}

package/dist/src/utils/SecurityShield.js

@@ -0,0 +1,57 @@
+/**
+ * **XyPriss Security Shield (Recursive Read-Only Proxy)**
+ *
+ * Protects the system API from any mutation attempts at runtime.
+ * This is a core component of the XyPriss Zero-Trust architecture.
+ *
+ * @param target The object to protect.
+ * @param label The name of the object for error messages.
+ */
+export function createSecurityShield(target, label = "__sys__") {
+    const proxyCache = new WeakMap();
+    function createProxy(obj, path) {
+        if (obj === null ||
+            (typeof obj !== "object" && typeof obj !== "function")) {
+            return obj;
+        }
+        if (proxyCache.has(obj))
+            return proxyCache.get(obj);
+        const handler = {
+            get(target, prop, receiver) {
+                const value = Reflect.get(target, prop, receiver);
+                // Prevent Proxy invariant violation
+                const desc = Object.getOwnPropertyDescriptor(target, prop);
+                if (desc && desc.configurable === false && desc.writable === false) {
+                    return value;
+                }
+                // If it's a function, we must bind it to the target to preserve 'this'
+                // context for internal protected state/properties.
+                if (typeof value === "function") {
+                    return value.bind(target);
+                }
+                if (value !== null && typeof value === "object") {
+                    const propName = typeof prop === "symbol" ? prop.toString() : String(prop);
+                    return createProxy(value, `${path}.${propName}`);
+                }
+                return value;
+            },
+            set(target, prop) {
+                const propName = typeof prop === "symbol" ? prop.toString() : String(prop);
+                throw new Error(`[XyPriss Security] Illegal Mutation: Property '${propName}' on '${path}' is protected and cannot be modified.`);
+            },
+            defineProperty(target, prop) {
+                const propName = typeof prop === "symbol" ? prop.toString() : String(prop);
+                throw new Error(`[XyPriss Security] Illegal Redefinition: Cannot redefine '${propName}' on '${path}'.`);
+            },
+            deleteProperty(target, prop) {
+                const propName = typeof prop === "symbol" ? prop.toString() : String(prop);
+                throw new Error(`[XyPriss Security] Illegal Deletion: Cannot delete '${propName}' from '${path}'.`);
+            },
+        };
+        const proxy = new Proxy(obj, handler);
+        proxyCache.set(obj, proxy);
+        return proxy;
+    }
+    return createProxy(target, label);
+}
+//# sourceMappingURL=SecurityShield.js.map

package/dist/src/utils/SecurityShield.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecurityShield.js","sourceRoot":"","sources":["../../../src/utils/SecurityShield.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAChC,MAAS,EACT,QAAgB,SAAS;IAEzB,MAAM,UAAU,GAAG,IAAI,OAAO,EAAe,CAAC;IAE9C,SAAS,WAAW,CAAC,GAAQ,EAAE,IAAY;QACvC,IACI,GAAG,KAAK,IAAI;YACZ,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,UAAU,CAAC,EACxD,CAAC;YACC,OAAO,GAAG,CAAC;QACf,CAAC;QAED,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEpD,MAAM,OAAO,GAAsB;YAC/B,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;gBACtB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAElD,oCAAoC;gBACpC,MAAM,IAAI,GAAG,MAAM,CAAC,wBAAwB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAC3D,IAAI,IAAI,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;oBACjE,OAAO,KAAK,CAAC;gBACjB,CAAC;gBAED,uEAAuE;gBACvE,mDAAmD;gBACnD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;oBAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC9B,CAAC;gBAED,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9C,MAAM,QAAQ,GACV,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;oBAC9D,OAAO,WAAW,CAAC,KAAK,EAAE,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC,CAAC;gBACrD,CAAC;gBACD,OAAO,KAAK,CAAC;YACjB,CAAC;YACD,GAAG,CAAC,MAAM,EAAE,IAAI;gBACZ,MAAM,QAAQ,GACV,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC9D,MAAM,IAAI,KAAK,CACX,kDAAkD,QAAQ,SAAS,IAAI,wCAAwC,CAClH,CAAC;YACN,CAAC;YACD,cAAc,CAAC,MAAM,EAAE,IAAI;gBACvB,MAAM,QAAQ,GACV,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC9D,MAAM,IAAI,KAAK,CACX,6DAA6D,QAAQ,SAAS,IAAI,IAAI,CACzF,CAAC;YACN,CAAC;YACD,cAAc,CAAC,MAAM,EAAE,IAAI;gBACvB,MAAM,QAAQ,GACV,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC9D,MAAM,IAAI,KAAK,CACX,uDAAuD,QAAQ,WAAW,IAAI,IAAI,CACrF,CAAC;YACN,CAAC;SACJ,CAAC;QAEF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC3B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,OAAO,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACtC,CAAC"}