xypriss 9.14.29 → 9.14.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cjs/index.js CHANGED
@@ -1823,6 +1823,22 @@ class XessShieldRequiredError extends Error {
1823
1823
  }
1824
1824
  }
1825
1825
 
1826
+ /**
1827
+ * Frozen JavaScript Intrinsics (Primordials)
1828
+ *
1829
+ * Secures string handling and path normalization against prototype pollution attacks
1830
+ * targeting String.prototype.includes, String.prototype.replace, String.prototype.startsWith, etc.
1831
+ *
1832
+ * @internal
1833
+ * @see XSA-XESS-015
1834
+ */
1835
+ const _StringIncludes = Function.prototype.call.bind(String.prototype.includes);
1836
+ const _StringReplace = Function.prototype.call.bind(String.prototype.replace);
1837
+ const _StringStartsWith = Function.prototype.call.bind(String.prototype.startsWith);
1838
+ const _StringSlice = Function.prototype.call.bind(String.prototype.slice);
1839
+ const _StringSubstring = Function.prototype.call.bind(String.prototype.substring);
1840
+ const _StringIndexOf = Function.prototype.call.bind(String.prototype.indexOf);
1841
+ const _StringLastIndexOf = Function.prototype.call.bind(String.prototype.lastIndexOf);
1826
1842
  /**
1827
1843
  * Resolved canonical installation directory for the XyPriss engine core.
1828
1844
  * Anchoring this path at module load time eliminates heuristic substring bypasses.
@@ -1830,18 +1846,24 @@ class XessShieldRequiredError extends Error {
1830
1846
  * @internal
1831
1847
  * @see XSA-XESS-018
1832
1848
  */
1833
- let _resolvedEngineDir = "";
1849
+ let ENGINE_CORE_DIR = "";
1834
1850
  try {
1851
+ let thisFile = "";
1835
1852
  if (typeof ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)) }) !== "undefined" && (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href))) {
1836
- const thisFile = node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href))).replace(/\\/g, "/");
1837
- const srcIdx = thisFile.lastIndexOf("/src/");
1853
+ thisFile = _StringReplace(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href))), /\\/g, "/");
1854
+ }
1855
+ else if (typeof __filename !== "undefined") {
1856
+ thisFile = _StringReplace(__filename, /\\/g, "/");
1857
+ }
1858
+ if (thisFile) {
1859
+ const srcIdx = _StringLastIndexOf(thisFile, "/src/");
1838
1860
  if (srcIdx !== -1) {
1839
- _resolvedEngineDir = thisFile.slice(0, srcIdx + 5); // includes "/src/"
1861
+ ENGINE_CORE_DIR = _StringSlice(thisFile, 0, srcIdx + 1); // root directory with trailing '/'
1840
1862
  }
1841
1863
  else {
1842
- const distIdx = thisFile.lastIndexOf("/dist/");
1864
+ const distIdx = _StringLastIndexOf(thisFile, "/dist/");
1843
1865
  if (distIdx !== -1) {
1844
- _resolvedEngineDir = thisFile.slice(0, distIdx + 6); // includes "/dist/"
1866
+ ENGINE_CORE_DIR = _StringSlice(thisFile, 0, distIdx + 1); // root directory with trailing '/'
1845
1867
  }
1846
1868
  }
1847
1869
  }
@@ -1853,18 +1875,19 @@ catch {
1853
1875
  * Checks if a given file path belongs to the deep engine core.
1854
1876
  * These files are skipped during stack analysis to find the user/plugin caller.
1855
1877
  *
1856
- * @see XSA-XESS-018 - Heuristic path evaluation hardening
1878
+ * @see XSA-XESS-015 - Immune to prototype pollution on String.prototype
1879
+ * @see XSA-XESS-018 - Heuristic path evaluation hardening anchored on ENGINE_CORE_DIR
1857
1880
  */
1858
1881
  function isEngineCorePath(filePath) {
1859
1882
  if (!filePath)
1860
1883
  return false;
1861
- const normalizedPath = filePath.replace(/\\/g, "/");
1862
- if (_resolvedEngineDir && normalizedPath.startsWith(_resolvedEngineDir)) {
1884
+ const normalizedPath = _StringReplace(filePath, /\\/g, "/");
1885
+ if (ENGINE_CORE_DIR && _StringStartsWith(normalizedPath, ENGINE_CORE_DIR)) {
1863
1886
  return true;
1864
1887
  }
1865
- if (normalizedPath.includes("/XyPriss/src/") ||
1866
- normalizedPath.includes("/XyPriss/dist/") ||
1867
- normalizedPath.includes("/node_modules/xypriss/")) {
1888
+ if (_StringIncludes(normalizedPath, "/XyPriss/src/") ||
1889
+ _StringIncludes(normalizedPath, "/XyPriss/dist/") ||
1890
+ _StringIncludes(normalizedPath, "/node_modules/xypriss/")) {
1868
1891
  return true;
1869
1892
  }
1870
1893
  return false;
@@ -1874,22 +1897,46 @@ function isEngineCorePath(filePath) {
1874
1897
  * or if it comes from an external plugin / user space.
1875
1898
  * This is used for SECURITY authorization.
1876
1899
  *
1900
+ * @see XSA-XESS-015
1877
1901
  * @see XSA-XESS-018
1878
1902
  */
1879
1903
  function isCoreFrameworkPath(filePath) {
1880
1904
  if (!filePath)
1881
1905
  return false;
1882
- const normalizedPath = filePath.replace(/\\/g, "/");
1906
+ const normalizedPath = _StringReplace(filePath, /\\/g, "/");
1883
1907
  // Authorize trusted internal mods within the framework repository
1884
- if (normalizedPath.includes("/XyPriss/mods/"))
1908
+ if (_StringIncludes(normalizedPath, "/XyPriss/mods/"))
1885
1909
  return true;
1886
1910
  // Exclude other plugins even if they contain 'src' or are named 'xypriss-something'
1887
- if (normalizedPath.includes("/mods/"))
1911
+ if (_StringIncludes(normalizedPath, "/mods/"))
1888
1912
  return false;
1889
1913
  // Engine Core is always trusted
1890
1914
  return isEngineCorePath(filePath);
1891
1915
  }
1892
1916
 
1917
+ /***************************************************************************
1918
+ * XyPrissJS - Fast And Secure
1919
+ *
1920
+ * @author Nehonix
1921
+ * @license Nehonix OSL (NOSL)
1922
+ *
1923
+ * Copyright (c) 2025 Nehonix. All rights reserved.
1924
+ *
1925
+ * This License governs the use, modification, and distribution of software
1926
+ * provided by NEHONIX under its open source projects.
1927
+ * NEHONIX is committed to fostering collaborative innovation while strictly
1928
+ * protecting its intellectual property rights.
1929
+ * Violation of any term of this License will result in immediate termination of all granted rights
1930
+ * and may subject the violator to legal action.
1931
+ *
1932
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
1933
+ * INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
1934
+ * AND NON-INFRINGEMENT.
1935
+ * IN NO EVENT SHALL NEHONIX BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
1936
+ * OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE OR INABILITY TO USE THE SOFTWARE,
1937
+ * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
1938
+ *
1939
+ ***************************************************************************** */
1893
1940
  /**
1894
1941
  * Frozen JavaScript Intrinsics (Primordials)
1895
1942
  *
@@ -1900,12 +1947,44 @@ function isCoreFrameworkPath(filePath) {
1900
1947
  * @see XSA-XESS-015
1901
1948
  */
1902
1949
  const _ArrayIsArray = Array.isArray;
1903
- // const _StringIncludes = Function.prototype.call.bind(String.prototype.includes) as (str: string, search: string) => boolean;
1904
- // const _StringReplace = Function.prototype.call.bind(String.prototype.replace) as (str: string, pattern: RegExp | string, replacement: string) => string;
1905
- // const _StringStartsWith = Function.prototype.call.bind(String.prototype.startsWith) as (str: string, search: string) => boolean;
1950
+ const _ObjectEntries = Object.entries;
1951
+ // Freeze CallSite accessors at early bootstrap to prevent prototype poisoning
1952
+ let _CallSiteGetFileName = null;
1953
+ let _CallSiteGetFunctionName = null;
1954
+ let _CallSiteIsEval = null;
1955
+ try {
1956
+ const origPrepare = Error.prepareStackTrace;
1957
+ Error.prepareStackTrace = (_err, sites) => {
1958
+ if (_ArrayIsArray(sites) && sites.length > 0) {
1959
+ const proto = Object.getPrototypeOf(sites[0]);
1960
+ if (proto) {
1961
+ if (typeof proto.getFileName === "function") {
1962
+ _CallSiteGetFileName = Function.prototype.call.bind(proto.getFileName);
1963
+ }
1964
+ if (typeof proto.getFunctionName === "function") {
1965
+ _CallSiteGetFunctionName = Function.prototype.call.bind(proto.getFunctionName);
1966
+ }
1967
+ if (typeof proto.isEval === "function") {
1968
+ _CallSiteIsEval = Function.prototype.call.bind(proto.isEval);
1969
+ }
1970
+ try {
1971
+ Object.freeze(proto);
1972
+ }
1973
+ catch { }
1974
+ }
1975
+ }
1976
+ return "";
1977
+ };
1978
+ const e = new Error();
1979
+ void e.stack;
1980
+ Error.prepareStackTrace = origPrepare;
1981
+ }
1982
+ catch {
1983
+ // ignore
1984
+ }
1906
1985
  // Capture native V8 C++ CallSite bindings at module bootstrap before any third-party code executes.
1907
1986
  // `util.getCallSites` invokes v8::StackTrace::CurrentStackTrace directly in C++, completely
1908
- // bypassing `Error.prepareStackTrace` overrides and ignoring `//# sourceURL` directives.
1987
+ // bypassing `Error.prepareStackTrace` overrides, CallSite prototype manipulation, and ignoring `//# sourceURL` directives.
1909
1988
  const _nativeGetCallSites = typeof util.getCallSites === "function"
1910
1989
  ? util.getCallSites.bind(util)
1911
1990
  : null;
@@ -1957,6 +2036,9 @@ function isProjectRoot(dir) {
1957
2036
  }
1958
2037
  /**
1959
2038
  * Identifies the project or plugin root for a given caller path using xfpm metadata.
2039
+ *
2040
+ * @see XSA-XESS-015 - Immune to prototype pollution on String.prototype
2041
+ * @see XSA-XESS-018 - Anchored path verification
1960
2042
  */
1961
2043
  function identifyProjectRoot(filePath) {
1962
2044
  if (!filePath)
@@ -1969,37 +2051,43 @@ function identifyProjectRoot(filePath) {
1969
2051
  return undefined;
1970
2052
  }
1971
2053
  }
1972
- const normalized = filePath.replace(/\\/g, "/");
1973
- const primaryRoot = (process.env.XYPRISS_PROJECT_ROOT || process.cwd()).replace(/\\/g, "/");
2054
+ const normalized = _StringReplace(filePath, /\\/g, "/");
2055
+ const primaryRoot = _StringReplace(process.env.XYPRISS_PROJECT_ROOT || process.cwd(), /\\/g, "/");
1974
2056
  // 1. Direct O(1) match against verified plugins registered by xfpm
1975
2057
  const manifest = getPluginsManifest();
1976
2058
  if (manifest?.roots) {
1977
- for (const [pluginRoot, _pluginName] of Object.entries(manifest.roots)) {
1978
- const normPluginRoot = pluginRoot.replace(/\\/g, "/");
2059
+ const rootEntries = _ObjectEntries(manifest.roots);
2060
+ for (let i = 0; i < rootEntries.length; i++) {
2061
+ const [pluginRoot] = rootEntries[i];
2062
+ const normPluginRoot = _StringReplace(pluginRoot, /\\/g, "/");
1979
2063
  if (normalized === normPluginRoot ||
1980
- normalized.startsWith(normPluginRoot + "/")) {
2064
+ _StringStartsWith(normalized, normPluginRoot + "/")) {
1981
2065
  return pluginRoot;
1982
2066
  }
1983
2067
  }
1984
2068
  }
1985
2069
  // 2. Direct match against primary project root
1986
2070
  if (normalized === primaryRoot ||
1987
- normalized.startsWith(primaryRoot + "/")) {
2071
+ _StringStartsWith(normalized, primaryRoot + "/")) {
1988
2072
  // If inside node_modules, it is an undeclared/untrusted dependency, NOT the application root!
1989
- if (normalized.includes("/node_modules/")) {
2073
+ if (_StringIncludes(normalized, "/node_modules/")) {
1990
2074
  return undefined;
1991
2075
  }
1992
2076
  return primaryRoot;
1993
2077
  }
1994
2078
  // 3. Monorepo development mods (/mods/<name>/) fallback
1995
2079
  // @see XSA-XESS-018: Must be strictly anchored to the primary project root or framework monorepo
1996
- const modsIdx = normalized.lastIndexOf("/mods/");
1997
- if (modsIdx !== -1 && (normalized.startsWith(primaryRoot + "/") || isEngineCorePath(normalized))) {
1998
- const afterMods = normalized.substring(modsIdx + 6);
1999
- const nextSlash = afterMods.indexOf("/");
2000
- const modName = nextSlash === -1 ? afterMods : afterMods.substring(0, nextSlash);
2080
+ const modsIdx = _StringLastIndexOf(normalized, "/mods/");
2081
+ if (modsIdx !== -1 &&
2082
+ (_StringStartsWith(normalized, primaryRoot + "/") ||
2083
+ isEngineCorePath(normalized))) {
2084
+ const afterMods = _StringSubstring(normalized, modsIdx + 6);
2085
+ const nextSlash = _StringIndexOf(afterMods, "/");
2086
+ const modName = nextSlash === -1
2087
+ ? afterMods
2088
+ : _StringSubstring(afterMods, 0, nextSlash);
2001
2089
  if (modName) {
2002
- return normalized.substring(0, modsIdx + 6 + modName.length);
2090
+ return _StringSubstring(normalized, 0, modsIdx + 6 + modName.length);
2003
2091
  }
2004
2092
  }
2005
2093
  return undefined;
@@ -2007,34 +2095,67 @@ function identifyProjectRoot(filePath) {
2007
2095
  function normalizeScriptName(rawScript) {
2008
2096
  if (!rawScript)
2009
2097
  return "";
2010
- if (rawScript.startsWith("file://")) {
2098
+ if (_StringStartsWith(rawScript, "file://")) {
2011
2099
  try {
2012
2100
  return node_url.fileURLToPath(rawScript);
2013
2101
  }
2014
2102
  catch {
2015
- return rawScript.slice(7);
2103
+ return _StringSlice(rawScript, 7);
2016
2104
  }
2017
2105
  }
2018
2106
  return rawScript;
2019
2107
  }
2020
2108
  function isRuntimeLoaderPath(filePath) {
2021
- const norm = filePath.replace(/\\/g, "/");
2022
- return (norm.includes("/node_modules/tsx/") ||
2023
- norm.includes("/node_modules/ts-node/") ||
2024
- norm.includes("/node_modules/.bin/"));
2109
+ const norm = _StringReplace(filePath, /\\/g, "/");
2110
+ return (_StringIncludes(norm, "/node_modules/tsx/") ||
2111
+ _StringIncludes(norm, "/node_modules/ts-node/") ||
2112
+ _StringIncludes(norm, "/node_modules/.bin/"));
2025
2113
  }
2026
2114
  /**
2027
- * Captures raw C++ V8/JSC CallSite frames by temporarily overriding `Error.prepareStackTrace`
2028
- * synchronously during stack generation. This neutralizes any user/attacker `Error.prepareStackTrace`
2029
- * hijack and returns the full un-truncated call stack across both Node.js (V8) and Bun (JSC).
2115
+ * Captures raw C++ V8/JSC CallSite frames.
2030
2116
  *
2031
- * Hardened with indexed iteration to defeat prototype pollution on Array.prototype[Symbol.iterator].
2117
+ * Security Architecture (Fail-Closed & Anti-Spoofing):
2118
+ * 1. Prioritizes `util.getCallSites(64)` when running on Node.js/V8, directly invoking
2119
+ * the C++ v8::StackTrace without touching JavaScript prototype methods or `Error.prepareStackTrace`.
2120
+ * 2. Falls back to controlled `Error.prepareStackTrace` with frozen `CallSite.prototype` accessors
2121
+ * and indexed array iteration, immune to `Array.prototype[Symbol.iterator]` prototype pollution.
2032
2122
  *
2123
+ * @internal
2033
2124
  * @see XSA-XESS-015
2034
2125
  */
2035
2126
  function captureNativeFrames() {
2036
2127
  const frames = [];
2037
- // 1. Capture full CallSite array via controlled prepareStackTrace override (immune to prior Error.prepareStackTrace hijacks)
2128
+ // Priority 1: Native C++ V8 CallSite frames (util.getCallSites)
2129
+ // Directly queries V8 engine in C++, immune to Error.prepareStackTrace overrides,
2130
+ // CallSite prototype manipulation, and ignoring `//# sourceURL` directives.
2131
+ if (_nativeGetCallSites) {
2132
+ try {
2133
+ const nativeSites = _nativeGetCallSites(64);
2134
+ const nativeLen = _ArrayIsArray(nativeSites)
2135
+ ? nativeSites.length
2136
+ : 0;
2137
+ if (nativeLen > 0) {
2138
+ for (let i = 0; i < nativeLen; i++) {
2139
+ const s = nativeSites[i];
2140
+ if (!s)
2141
+ continue;
2142
+ const rawScript = s.scriptName || "";
2143
+ const fnName = s.functionName || "";
2144
+ frames[frames.length] = {
2145
+ filePath: normalizeScriptName(rawScript),
2146
+ fnName,
2147
+ isEval: !rawScript &&
2148
+ (fnName === "eval" || fnName === "anonymous"),
2149
+ };
2150
+ }
2151
+ return frames;
2152
+ }
2153
+ }
2154
+ catch {
2155
+ // fallback to Error.prepareStackTrace
2156
+ }
2157
+ }
2158
+ // Priority 2: Controlled Error.prepareStackTrace override (Node.js fallback / Bun JSC)
2038
2159
  const prevPrepare = Error.prepareStackTrace;
2039
2160
  const prevLimit = Error.stackTraceLimit;
2040
2161
  let rawSites = [];
@@ -2054,21 +2175,27 @@ function captureNativeFrames() {
2054
2175
  Error.prepareStackTrace = prevPrepare;
2055
2176
  Error.stackTraceLimit = prevLimit;
2056
2177
  }
2057
- // Use indexed iteration to avoid invoking monkey-patched Array.prototype[Symbol.iterator]
2178
+ // Use indexed iteration and frozen CallSite accessors to defeat prototype pollution
2058
2179
  for (let i = 0; i < rawSites.length; i++) {
2059
2180
  const site = rawSites[i];
2060
2181
  if (!site)
2061
2182
  continue;
2062
2183
  try {
2063
- const rawFile = typeof site.getFileName === "function"
2064
- ? site.getFileName() || ""
2065
- : "";
2066
- const fnName = typeof site.getFunctionName === "function"
2067
- ? site.getFunctionName() || ""
2068
- : "";
2069
- const isEval = typeof site.isEval === "function"
2070
- ? Boolean(site.isEval())
2071
- : false;
2184
+ const rawFile = _CallSiteGetFileName
2185
+ ? _CallSiteGetFileName(site) || ""
2186
+ : typeof site.getFileName === "function"
2187
+ ? site.getFileName() || ""
2188
+ : "";
2189
+ const fnName = _CallSiteGetFunctionName
2190
+ ? _CallSiteGetFunctionName(site) || ""
2191
+ : typeof site.getFunctionName === "function"
2192
+ ? site.getFunctionName() || ""
2193
+ : "";
2194
+ const isEval = _CallSiteIsEval
2195
+ ? Boolean(_CallSiteIsEval(site))
2196
+ : typeof site.isEval === "function"
2197
+ ? Boolean(site.isEval())
2198
+ : false;
2072
2199
  frames[frames.length] = {
2073
2200
  filePath: normalizeScriptName(rawFile),
2074
2201
  fnName,
@@ -2079,35 +2206,15 @@ function captureNativeFrames() {
2079
2206
  // ignore
2080
2207
  }
2081
2208
  }
2082
- // 2. Also merge frames from Node C++ util.getCallSites (which strips //# sourceURL on V8)
2083
- if (_nativeGetCallSites) {
2084
- try {
2085
- const nativeSites = _nativeGetCallSites(64);
2086
- const nativeLen = _ArrayIsArray(nativeSites) ? nativeSites.length : 0;
2087
- for (let i = 0; i < nativeLen; i++) {
2088
- const s = nativeSites[i];
2089
- if (!s)
2090
- continue;
2091
- const rawScript = s.scriptName || "";
2092
- const fnName = s.functionName || "";
2093
- frames[frames.length] = {
2094
- filePath: normalizeScriptName(rawScript),
2095
- fnName,
2096
- isEval: !rawScript &&
2097
- (fnName === "eval" || fnName === "anonymous"),
2098
- };
2099
- }
2100
- }
2101
- catch {
2102
- // ignore
2103
- }
2104
- }
2105
2209
  return frames;
2106
2210
  }
2107
2211
  /**
2108
2212
  * Verifies that an internal property accessor (such as `BaseApi.prototype.runner`)
2109
2213
  * or internal engine method is being invoked directly by an internal XyPriss core module
2110
2214
  * and not by userland or third-party `node_modules` code.
2215
+ *
2216
+ * @see XSA-XESS-015 - Immune to prototype pollution on String.prototype
2217
+ * @see XSA-XESS-018 - Excludes internal configuration proxies from bypassing caller checks
2111
2218
  */
2112
2219
  function isImmediateInternalEngineCall() {
2113
2220
  const frames = captureNativeFrames();
@@ -2118,15 +2225,15 @@ function isImmediateInternalEngineCall() {
2118
2225
  }
2119
2226
  if (!filePath)
2120
2227
  continue;
2121
- if (filePath.includes("[eval]")) {
2228
+ if (_StringIncludes(filePath, "[eval]")) {
2122
2229
  return false;
2123
2230
  }
2124
- if (filePath.startsWith("node:") ||
2125
- filePath.startsWith("bun:") ||
2231
+ if (_StringStartsWith(filePath, "node:") ||
2232
+ _StringStartsWith(filePath, "bun:") ||
2126
2233
  filePath === "native") {
2127
2234
  continue;
2128
2235
  }
2129
- const norm = filePath.replace(/\\/g, "/");
2236
+ const norm = _StringReplace(filePath, /\\/g, "/");
2130
2237
  // Skip stack-tracing plumbing and entrypoint caller wrappers inside the engine
2131
2238
  if (isEngineCorePath(norm)) {
2132
2239
  if (fnName === "captureNativeFrames" ||
@@ -2140,7 +2247,8 @@ function isImmediateInternalEngineCall() {
2140
2247
  fnName === "call" ||
2141
2248
  fnName === "callSync" ||
2142
2249
  fnName === "callSyncSubprocess" ||
2143
- fnName === "executeEnvCall") {
2250
+ fnName === "executeEnvCall" ||
2251
+ fnName === "configureShield") {
2144
2252
  continue;
2145
2253
  }
2146
2254
  }
@@ -2154,6 +2262,8 @@ function isImmediateInternalEngineCall() {
2154
2262
  * Immune to `Error.prepareStackTrace` hijacking AND `//# sourceURL` spoofing:
2155
2263
  * even if an attacker injects a fake frame via `new Function("//# sourceURL=...")`,
2156
2264
  * the attacker's own `node_modules/...` frame remains on the call stack and is detected.
2265
+ *
2266
+ * @see XSA-XESS-015 - Immune to prototype pollution on String.prototype and CallSite.prototype
2157
2267
  */
2158
2268
  function getVerifiedCallerInfo() {
2159
2269
  const frames = captureNativeFrames();
@@ -2170,15 +2280,15 @@ function getVerifiedCallerInfo() {
2170
2280
  }
2171
2281
  if (!filePath)
2172
2282
  continue;
2173
- if (filePath.includes("[eval]")) {
2283
+ if (_StringIncludes(filePath, "[eval]")) {
2174
2284
  return {
2175
2285
  root: undefined,
2176
2286
  isUntrusted: true,
2177
2287
  callerFile: filePath || "<eval>",
2178
2288
  };
2179
2289
  }
2180
- if (filePath.startsWith("node:") ||
2181
- filePath.startsWith("bun:") ||
2290
+ if (_StringStartsWith(filePath, "node:") ||
2291
+ _StringStartsWith(filePath, "bun:") ||
2182
2292
  filePath === "native") {
2183
2293
  continue;
2184
2294
  }
@@ -9120,6 +9230,7 @@ class EnvApi {
9120
9230
  "READABLE_STREAM",
9121
9231
  "BUN_CONFIG_VERBOSE_FETCH",
9122
9232
  "XYPRISS_ENV_SHIELD",
9233
+ "XYPRISS_SHIELD",
9123
9234
  "BUN_DISABLE_DYNAMIC_CHUNK_SIZE",
9124
9235
  // Node / Bun core HTTPS variables (read allowed for network clients, writes strictly guarded in set trap)
9125
9236
  "NODE_TLS_REJECT_UNAUTHORIZED",
@@ -9135,6 +9246,14 @@ class EnvApi {
9135
9246
  "TMP",
9136
9247
  ]);
9137
9248
  this.whitelistedFields = new Set(this.defaultWhitelist);
9249
+ /**
9250
+ * In-memory cache for whitelisted environment variables.
9251
+ * Populated directly from the Vault during engine bootstrap, enabling O(1)
9252
+ * synchronous reads from process.env without IPC or caller validation conflicts.
9253
+ *
9254
+ * @see XSA-XESS-019
9255
+ */
9256
+ this._whitelistedCache = new Map();
9138
9257
  _envRunnerStore.set(this, runner);
9139
9258
  const sealKey = crypto$2.randomBytes(32).toString("hex");
9140
9259
  _sealKeyStore.set(this, sealKey);
@@ -9210,7 +9329,9 @@ class EnvApi {
9210
9329
  // Keep process.env in sync strictly for declared whitelisted non-secret keys.
9211
9330
  // @see XSA-XESS-017: Never mirror XEMS_*, ENC_*, DOTENV_*, XY_*, or __* into process.env,
9212
9331
  // because Bun.env and import.meta.env bypass the Proxy shield and would expose plain secrets.
9332
+ // @see XSA-XESS-019: Maintain in-memory whitelisted cache for O(1) process.env reads.
9213
9333
  if (this.whitelistedFields.has(key)) {
9334
+ this._whitelistedCache.set(key, value);
9214
9335
  try {
9215
9336
  process.env[key] = value;
9216
9337
  }
@@ -9237,7 +9358,9 @@ class EnvApi {
9237
9358
  }
9238
9359
  this.executeEnvCall("delete", [key], { root });
9239
9360
  // @see XSA-XESS-017
9361
+ // @see XSA-XESS-019: Invalidate whitelisted cache on delete.
9240
9362
  if (this.whitelistedFields.has(key)) {
9363
+ this._whitelistedCache.delete(key);
9241
9364
  try {
9242
9365
  delete process.env[key];
9243
9366
  }
@@ -9441,30 +9564,6 @@ class EnvApi {
9441
9564
  is(envName) {
9442
9565
  return this.mode === envName;
9443
9566
  }
9444
- /**
9445
- * Configures the XESS (XyPriss Environment Security Shield) dynamically.
9446
- *
9447
- * **Security Enforcement:**
9448
- * Only the host application and internal engine are authorized to invoke this method.
9449
- * Invocations from third-party plugins in `node_modules` or foreign project roots
9450
- * are strictly blocked to prevent malicious tampering with the `process.env` whitelist.
9451
- *
9452
- * @deprecated Consider declaring `$env: { whitelist: [...] }` in `xypriss.config.jsonc` instead.
9453
- */
9454
- configureShield(config) {
9455
- const callerRoot = getCallerProjectRoot();
9456
- const runner = _envRunnerStore.get(this);
9457
- const hostRoot = runner ? runner.getRoot() : "";
9458
- /**
9459
- * @see XSA-XESS-018: Strict Fail-Closed check. If callerRoot cannot be resolved
9460
- * (e.g. called from third-party node_modules or unverified stack), block immediately.
9461
- */
9462
- if (!callerRoot || (callerRoot !== hostRoot && !isCoreFrameworkPath(callerRoot))) {
9463
- logger$1.warn("security", `Blocked unauthorized attempt by third-party caller at '${callerRoot || "<untrusted>"}' to configure Environment Security Shield.`);
9464
- return;
9465
- }
9466
- this[XY_ENV_CONFIGURE_SHIELD](config);
9467
- }
9468
9567
  /**
9469
9568
  * Configures the XESS (XyPriss Environment Security Shield) dynamically.
9470
9569
  *
@@ -9475,6 +9574,9 @@ class EnvApi {
9475
9574
  * and only accessible via this internal Symbol during early bootstrap.
9476
9575
  *
9477
9576
  * @internal
9577
+ * @see XSA-XESS-015
9578
+ * @see XSA-XESS-018
9579
+ * @see XSA-XESS-019
9478
9580
  * @param config - XESS configuration options.
9479
9581
  */
9480
9582
  [XY_ENV_CONFIGURE_SHIELD](config) {
@@ -9495,6 +9597,35 @@ class EnvApi {
9495
9597
  ]);
9496
9598
  }
9497
9599
  }
9600
+ // Cache all whitelisted values from the vault during trusted bootstrap
9601
+ this.refreshWhitelistedCache();
9602
+ }
9603
+ /**
9604
+ * Pre-populates the in-memory cache of whitelisted variables from the secure vault
9605
+ * during trusted engine bootstrap.
9606
+ *
9607
+ * This provides O(1) synchronous lookups for `process.env` without invoking `runner.runSync`,
9608
+ * preventing any conflict with Zero-Trust caller verification on restricted modules.
9609
+ *
9610
+ * @internal
9611
+ * @see XSA-XESS-019
9612
+ */
9613
+ refreshWhitelistedCache() {
9614
+ const runner = _envRunnerStore.get(this);
9615
+ const hostRoot = runner ? runner.getRoot() : "";
9616
+ for (const key of this.whitelistedFields) {
9617
+ if (!this.defaultWhitelist.has(key) || key === "PORT") {
9618
+ try {
9619
+ const res = this.executeEnvCall("get", [key], { root: hostRoot });
9620
+ if (res?.found && res.value !== undefined) {
9621
+ this._whitelistedCache.set(key, res.value);
9622
+ }
9623
+ }
9624
+ catch {
9625
+ // Vault might not be initialized or key not present yet
9626
+ }
9627
+ }
9628
+ }
9498
9629
  }
9499
9630
  // -------------------------------------------------------------------------
9500
9631
  // Native / system
@@ -9667,6 +9798,8 @@ class EnvApi {
9667
9798
  /**
9668
9799
  * Verifies whether the caller that directly triggered a process.env Proxy trap
9669
9800
  * belongs to the internal XyPriss engine core or to external user/plugin code.
9801
+ *
9802
+ * @see XSA-XESS-015 - Immune to prototype pollution on String.prototype
9670
9803
  */
9671
9804
  function isProxyCallerEngineCore() {
9672
9805
  const frames = captureNativeFrames();
@@ -9675,10 +9808,10 @@ class EnvApi {
9675
9808
  const { filePath, fnName } = frames[i];
9676
9809
  if (!filePath)
9677
9810
  continue;
9678
- if (filePath.startsWith("node:") ||
9679
- filePath.startsWith("bun:") ||
9811
+ if (_StringStartsWith(filePath, "node:") ||
9812
+ _StringStartsWith(filePath, "bun:") ||
9680
9813
  filePath === "native" ||
9681
- filePath.includes("[eval]")) {
9814
+ _StringIncludes(filePath, "[eval]")) {
9682
9815
  continue;
9683
9816
  }
9684
9817
  if (fnName === "captureNativeFrames" ||
@@ -9691,7 +9824,7 @@ class EnvApi {
9691
9824
  continue;
9692
9825
  }
9693
9826
  // The very first frame after the Proxy trap is the consumer that accessed process.env!
9694
- return isEngineCorePath(filePath.replace(/\\/g, "/"));
9827
+ return isEngineCorePath(_StringReplace(filePath, /\\/g, "/"));
9695
9828
  }
9696
9829
  return false;
9697
9830
  }
@@ -9703,21 +9836,28 @@ class EnvApi {
9703
9836
  if (typeof prop !== "string") {
9704
9837
  return Reflect.get(target, prop, receiver);
9705
9838
  }
9706
- if (isInsideShieldCheck || prop === "XYPRISS_PROJECT_ROOT" || prop === "XYPRISS_ENV_SHIELD") {
9839
+ /**
9840
+ * Fast bypass for internal engine shield checks to prevent proxy re-entrancy.
9841
+ * @see XSA-XESS-018
9842
+ * @see XSA-XESS-019
9843
+ */
9844
+ if (isInsideShieldCheck ||
9845
+ prop === "XYPRISS_PROJECT_ROOT" ||
9846
+ prop === "XYPRISS_ENV_SHIELD" ||
9847
+ prop === "XYPRISS_SHIELD") {
9707
9848
  return Reflect.get(target, prop, receiver);
9708
9849
  }
9709
- // Pass through whitelisted keys.
9710
- // @see XSA-XESS-019: Resolve whitelisted fields directly from the host Vault
9711
- // so that authorized public whitelisted variables can be read by all modules,
9712
- // including third-party dependencies, without returning the canary honeypot.
9850
+ /**
9851
+ * Whitelisted environment fields resolution:
9852
+ * Resolves in O(1) from the secure in-memory cache populated from the Vault.
9853
+ * Third-party packages in node_modules can read declared whitelisted keys safely
9854
+ * without triggering runner.runSync Zero-Trust caller rejection.
9855
+ *
9856
+ * @see XSA-XESS-019
9857
+ */
9713
9858
  if (self.whitelistedFields.has(prop)) {
9714
- if (!self.defaultWhitelist.has(prop) || prop === "PORT") {
9715
- const runner = _envRunnerStore.get(self);
9716
- const hostRoot = runner ? runner.getRoot() : "";
9717
- const res = self.executeEnvCall("get", [prop], { root: hostRoot });
9718
- if (res?.found && res.value !== undefined) {
9719
- return res.value;
9720
- }
9859
+ if (self._whitelistedCache.has(prop)) {
9860
+ return self._whitelistedCache.get(prop);
9721
9861
  }
9722
9862
  return Reflect.get(target, prop, receiver);
9723
9863
  }
@@ -9735,12 +9875,15 @@ class EnvApi {
9735
9875
  // All other keys (including ENC_*, DOTENV_*, __*, and application secrets):
9736
9876
  // direct process.env reads by untrusted/external callers are strictly intercepted and blocked!
9737
9877
  if (!warnedKeys.has(prop)) {
9738
- // @see XSA-XESS-019: Support both XYPRISS_SHIELD and XYPRISS_ENV_SHIELD silent flags
9878
+ /**
9879
+ * Check silent mode flags directly from the backing target object
9880
+ * to permanently prevent recursive proxy invocations.
9881
+ *
9882
+ * @see XSA-XESS-018
9883
+ * @see XSA-XESS-019
9884
+ */
9739
9885
  const isSilent = target["XYPRISS_ENV_SHIELD"] === "silent" ||
9740
- target["XYPRISS_SHIELD"] === "silent" ||
9741
- (typeof process !== "undefined" &&
9742
- (process.env?.XYPRISS_SHIELD === "silent" ||
9743
- process.env?.XYPRISS_ENV_SHIELD === "silent"));
9886
+ target["XYPRISS_SHIELD"] === "silent";
9744
9887
  if (!isSilent) {
9745
9888
  process.stderr.write(`\x1b[33m[SECURITY]\x1b[0m ` +
9746
9889
  `Direct access to process.env["${prop}"] is blocked. ` +