@erickxavier/no-js 1.10.1 → 1.11.0

package/src/evaluate.js

@@ -2,7 +2,7 @@
 //  EXPRESSION EVALUATOR
 // ═══════════════════════════════════════════════════════════════════════
 
-import { _config, _stores, _routerInstance, _filters, _warn, _notifyStoreWatchers } from "./globals.js";
+import { _config, _stores, _routerInstance, _filters, _warn, _notifyStoreWatchers, _globals } from "./globals.js";
 import { _i18n } from "./i18n.js";
 import { _collectKeys } from "./context.js";
 
@@ -1311,6 +1311,11 @@ export function evaluate(expr, ctx) {
     if (!("$i18n"   in scope)) scope.$i18n   = _i18n;
     if (!("$refs"   in scope)) scope.$refs   = ctx.$refs;
     if (!("$form"   in scope)) scope.$form   = ctx.$form || null;
+    // Inject plugin globals (cannot shadow local or core $ variables)
+    for (const gk in _globals) {
+      const key = "$" + gk;
+      if (!(key in scope)) scope[key] = _globals[gk];
+    }
 
     // Parse expression into AST (cached)
     let ast = _exprCache.get(mainExpr);
@@ -1347,6 +1352,11 @@ export function _execStatement(expr, ctx, extraVars = {}) {
     if (!("$router" in scope)) scope.$router = _routerInstance;
     if (!("$i18n"   in scope)) scope.$i18n   = _i18n;
     if (!("$refs"   in scope)) scope.$refs   = ctx.$refs;
+    // Inject plugin globals (before extraVars so $event etc. take priority)
+    for (const gk in _globals) {
+      const key = "$" + gk;
+      if (!(key in scope)) scope[key] = _globals[gk];
+    }
     Object.assign(scope, extraVars);
 
     // Snapshot context chain values for write-back comparison

package/src/fetch.js

@@ -2,9 +2,61 @@
 //  FETCH HELPER, URL RESOLUTION & CACHE
 // ═══════════════════════════════════════════════════════════════════════
 
-import { _config, _interceptors, _cache } from "./globals.js";
+import { _config, _interceptors, _cache, _plugins, _SENSITIVE_HEADERS, _SENSITIVE_RESPONSE_HEADERS, _log, _warn, _CANCEL, _RESPOND, _REPLACE } from "./globals.js";
 
 const _MAX_CACHE = 200;
+const _INTERCEPTOR_TIMEOUT = 5000;
+let _interceptorDepth = 0;
+const _MAX_INTERCEPTOR_DEPTH = 1;
+const _responseOriginals = new WeakMap();
+
+function _withTimeout(promise, ms, label) {
+  let id;
+  return Promise.race([
+    promise.finally(() => clearTimeout(id)),
+    new Promise((_, reject) => {
+      id = setTimeout(() => reject(new Error(label)), ms);
+    }),
+  ]);
+}
+
+function _isSensitiveHeader(name) {
+  return _SENSITIVE_HEADERS.has(name.toLowerCase()) || /^x-(auth|api)-/i.test(name);
+}
+
+// URL param redaction helper
+function _redactUrlParams(url) {
+  try {
+    const u = new URL(url, "http://localhost");
+    for (const key of [...u.searchParams.keys()]) {
+      if (/token|key|secret|auth|password|credential/i.test(key)) {
+        u.searchParams.set(key, "[REDACTED]");
+      }
+    }
+    // Return just the path+search if it was a relative URL
+    return url.startsWith("http") ? u.href : u.pathname + u.search;
+  } catch {
+    return url;
+  }
+}
+
+// Response redaction helper for untrusted interceptors
+function _redactResponse(response) {
+  const redactedHeaders = new Headers(response.headers);
+  for (const h of _SENSITIVE_RESPONSE_HEADERS) {
+    redactedHeaders.delete(h);
+  }
+  const redactedUrl = _redactUrlParams(response.url);
+  const redacted = Object.freeze({
+    status: response.status,
+    ok: response.ok,
+    statusText: response.statusText,
+    headers: redactedHeaders,
+    url: redactedUrl,
+  });
+  _responseOriginals.set(redacted, response);
+  return redacted;
+}
 
 export function resolveUrl(url, el) {
   if (
@@ -66,11 +118,65 @@ export async function _doFetch(
       _config.csrf.token || "";
   }
 
-  // Request interceptors
-  for (const fn of _interceptors.request) {
-    opts = fn(fullUrl, opts) || opts;
+  // ── Request interceptors ──
+  // Strip sensitive headers before passing to interceptors
+  const sensitiveHeaders = {};
+  for (const key of Object.keys(opts.headers)) {
+    if (_isSensitiveHeader(key)) {
+      sensitiveHeaders[key] = opts.headers[key];
+      delete opts.headers[key];
+    }
+  }
+
+  _interceptorDepth++;
+  try {
+    if (_interceptorDepth <= _MAX_INTERCEPTOR_DEPTH) {
+      for (let i = 0; i < _interceptors.request.length; i++) {
+        const entry = _interceptors.request[i];
+        const fn = entry.fn ?? entry;
+        const isTrusted = entry.pluginName && _plugins.get(entry.pluginName)?.options?.trusted === true;
+
+        const interceptorOpts = isTrusted
+          ? { ...opts, headers: { ...opts.headers, ...sensitiveHeaders } }
+          : { ...opts, headers: { ...opts.headers } };
+
+        const result = await _withTimeout(
+          Promise.resolve(fn(fullUrl, interceptorOpts)),
+          _INTERCEPTOR_TIMEOUT,
+          "Interceptor timeout",
+        ).catch(e => {
+          _warn(`Request interceptor [${i}] error:`, e.message);
+          return undefined;
+        });
+
+        if (result && result[_CANCEL]) {
+          _log("Request cancelled by interceptor", i);
+          throw new DOMException("Request cancelled by interceptor", "AbortError");
+        }
+        if (result && result[_RESPOND] !== undefined) {
+          _log("Request short-circuited by interceptor", i);
+          return result[_RESPOND];
+        }
+        if (result && typeof result === "object" && !result[_CANCEL] && result[_RESPOND] === undefined) {
+          if (result.headers && typeof result.headers === "object") {
+            const safeHeaders = { ...opts.headers };
+            for (const [key, value] of Object.entries(result.headers)) {
+              if (!_isSensitiveHeader(key)) {
+                safeHeaders[key] = value;
+              }
+            }
+            opts.headers = safeHeaders;
+          }
+        }
+      }
+    }
+  } finally {
+    _interceptorDepth--;
   }
 
+  // Re-apply sensitive headers after interceptor chain
+  Object.assign(opts.headers, sensitiveHeaders);
+
   // Retry logic
   const maxRetries = retries !== undefined ? retries : (_config.retries || 0);
   let lastError;
@@ -97,8 +203,33 @@ export async function _doFetch(
       clearTimeout(timeout);
 
       // Response interceptors
-      for (const fn of _interceptors.response) {
-        response = fn(response, fullUrl) || response;
+      for (let i = 0; i < _interceptors.response.length; i++) {
+        const entry = _interceptors.response[i];
+        const fn = entry.fn ?? entry;
+        const isTrusted = entry.pluginName && _plugins.get(entry.pluginName)?.options?.trusted === true;
+
+        const interceptorResponse = isTrusted ? response : _redactResponse(response);
+        const interceptorUrl = isTrusted ? fullUrl : _redactUrlParams(fullUrl);
+
+        const result = await _withTimeout(
+          Promise.resolve(fn(interceptorResponse, interceptorUrl)),
+          _INTERCEPTOR_TIMEOUT,
+          "Response interceptor timeout",
+        ).catch(e => {
+          _warn(`Response interceptor [${i}] error:`, e.message);
+          return undefined;
+        });
+
+        if (result && result[_REPLACE] !== undefined) {
+          _log("Response replaced by interceptor", i);
+          return result[_REPLACE];
+        }
+        if (result) response = result;
+      }
+
+      // Unwrap redacted shell back to real Response for data extraction
+      if (_responseOriginals.has(response)) {
+        response = _responseOriginals.get(response);
       }
 
       if (!response.ok) {

package/src/globals.js

@@ -12,7 +12,7 @@ export const _config = {
   csrf: null,
   cache: { strategy: "none", ttl: 300000 },
   templates: { cache: true },
-  router: { useHash: false, base: "/", scrollBehavior: "top", templates: "pages", ext: ".tpl" },
+  router: { useHash: false, base: "/", scrollBehavior: "top", templates: "pages", ext: ".tpl", focusBehavior: "none" },
   i18n: { defaultLocale: "en", fallbackLocale: "en", detectBrowser: false, loadPath: null, ns: [], cache: true, persist: false },
   debug: false,
   devtools: false,
@@ -33,6 +33,26 @@ export const _cache = new Map();
 export const _refs = {};
 export let _routerInstance = null;
 
+// ─── Plugin system shared state ─────────────────────────────────────────────
+export const _plugins = new Map();                    // name → { plugin, options }
+export const _globals = Object.create(null);          // name → reactive value (prototype-free)
+export const _globalOwners = Object.create(null);     // name → plugin name (collision tracking)
+export let _disposing = false;
+// Internal: used by index.js dispose() only — plugins receive the NoJS API, not module imports
+export function _setDisposing(v) { _disposing = v; }
+export let _currentPluginName = null;
+export function _setCurrentPluginName(v) { _currentPluginName = v; }
+
+export const _SENSITIVE_HEADERS = new Set([
+  'authorization', 'x-api-key', 'x-auth-token', 'cookie',
+  'proxy-authorization', 'set-cookie', 'x-csrf-token',
+]);
+
+export const _SENSITIVE_RESPONSE_HEADERS = new Set([
+  'set-cookie', 'x-csrf-token', 'x-auth-token',
+  'www-authenticate', 'proxy-authenticate',
+]);
+
 // ─── Lifecycle: tracks the element being processed by processElement ────────
 // Used by ctx.$watch and _onDispose to transparently tag watchers/disposers
 // with the owning DOM element — no changes needed in directive files.
@@ -103,3 +123,8 @@ export function _onDispose(fn) {
 export function _emitEvent(name, data) {
   (_eventBus[name] || []).forEach((fn) => fn(data));
 }
+
+// ─── Plugin sentinel symbols ────────────────────────────────────────────────
+export const _CANCEL  = Symbol("nojs.cancel");
+export const _RESPOND = Symbol("nojs.respond");
+export const _REPLACE = Symbol("nojs.replace");

package/src/index.js

@@ -17,6 +17,17 @@ import {
   _log,
   _warn,
   _notifyStoreWatchers,
+  _plugins,
+  _globals,
+  _globalOwners,
+  _disposing,
+  _setDisposing,
+  _currentPluginName,
+  _setCurrentPluginName,
+  _emitEvent,
+  _CANCEL,
+  _RESPOND,
+  _REPLACE,
 } from "./globals.js";
 import { _i18n, _loadI18nForLocale } from "./i18n.js";
 import { createContext } from "./context.js";
@@ -24,7 +35,7 @@ import { evaluate, resolve } from "./evaluate.js";
 import { findContext, _loadRemoteTemplates, _loadRemoteTemplatesPhase1, _loadRemoteTemplatesPhase2, _processTemplateIncludes } from "./dom.js";
 import { registerDirective, processTree } from "./registry.js";
 import { _createRouter } from "./router.js";
-import { initDevtools, _devtoolsEmit } from "./devtools.js";
+import { initDevtools, destroyDevtools, _devtoolsEmit } from "./devtools.js";
 
 // Side-effect imports: register built-in filters
 import "./filters.js";
@@ -41,6 +52,47 @@ import "./directives/refs.js";
 import "./directives/validation.js";
 import "./directives/i18n.js";
 import "./directives/dnd.js";
+import "./directives/head.js";
+
+// Lock core directives — plugins can only register NEW names
+import { _freezeDirectives } from "./registry.js";
+_freezeDirectives();
+
+// ═══════════════════════════════════════════════════════════════════════
+//  PLUGIN SYSTEM INTERNALS
+// ═══════════════════════════════════════════════════════════════════════
+
+let _initPromise = null;
+
+// Keep in sync with context.js proxy handler $xxx variables.
+// Any new $xxx context variable requires adding xxx to this list.
+const _RESERVED_GLOBAL_NAMES = new Set([
+  "store", "route", "router", "i18n", "refs", "form", "parent",
+  "watch", "set", "notify", "raw", "isProxy", "listeners",
+  "app", "config", "env", "debug", "version", "plugins", "globals",
+  "el", "event", "self", "this", "super", "window", "document",
+  "toString", "valueOf", "hasOwnProperty",
+]);
+
+const _DANGEROUS_REFS = typeof window !== "undefined"
+  ? new Set([eval, Function, window.eval, window.Function].filter(Boolean))
+  : new Set();
+
+function _isUnsafeGlobalValue(value) {
+  return _DANGEROUS_REFS.has(value);
+}
+
+function _deepCheckUnsafe(obj, seen = new Set()) {
+  if (!obj || typeof obj !== "object" || seen.has(obj)) return;
+  seen.add(obj);
+  for (const val of Object.values(obj)) {
+    if (_isUnsafeGlobalValue(val)) {
+      _warn("NoJS.global(): value contains a forbidden reference (eval/Function).");
+      throw new Error("unsafe_global");
+    }
+    if (val && typeof val === "object") _deepCheckUnsafe(val, seen);
+  }
+}
 
 // ═══════════════════════════════════════════════════════════════════════
 //  PUBLIC API
@@ -128,45 +180,221 @@ const NoJS = {
     }
   },
 
-  async init(root) {
-    if (typeof document === "undefined") return;
-    if (NoJS._initialized) return;
-    NoJS._initialized = true;
-    root = root || document.body;
-    _log("Initializing...");
-
-    // Load external locale files (blocking — translations must be available for first paint)
-    if (_config.i18n.loadPath) {
-      const locales = new Set([_i18n.locale, _config.i18n.fallbackLocale]);
-      await Promise.all([...locales].map((l) => _loadI18nForLocale(l)));
+  // ─── Plugin registration ──────────────────────────────────────────────
+  use(plugin, options = {}) {
+    if (_disposing) {
+      _warn("Cannot install plugins during dispose.");
+      return;
     }
 
-    // Inline template includes (e.g. skeletons) — synchronous, before any fetch
-    _processTemplateIncludes(root);
+    // Normalize function shorthand (named functions only)
+    if (typeof plugin === "function") {
+      if (!plugin.name || plugin.name === "anonymous") {
+        _warn('Plugin must have a unique, non-empty name. Use { name: "my-plugin", install: fn }.');
+        return;
+      }
+      plugin = { name: plugin.name, install: plugin };
+    }
 
-    // Determine active route path for phase 1 prioritization
-    const defaultRoutePath = _getDefaultRoutePath();
+    // Validate name
+    if (!plugin.name || typeof plugin.name !== "string" || plugin.name === "anonymous") {
+      _warn('Plugin must have a unique, non-empty name.');
+      return;
+    }
 
-    // Phase 1 (blocking): priority + non-route + default route templates
-    await _loadRemoteTemplatesPhase1(defaultRoutePath);
+    // Duplicate detection with object identity comparison
+    if (_plugins.has(plugin.name)) {
+      const existing = _plugins.get(plugin.name);
+      if (existing.plugin !== plugin) {
+        _warn(`Plugin "${plugin.name}" name collision: a different plugin with this name is already installed.`);
+      }
+      return;
+    }
 
-    // Check for route-view outlets to activate router
-    if (document.querySelector("[route-view]")) {
-      setRouterInstance(_createRouter());
+    // Log declared capabilities in debug mode
+    if (plugin.capabilities && _config.debug) {
+      _log(`Plugin "${plugin.name}" declares capabilities:`, plugin.capabilities);
     }
 
-    processTree(root); // ← first paint happens here
+    // Warn on trusted access
+    if (options.trusted === true) {
+      _warn(`WARNING: Plugin "${plugin.name}" installed with trusted access to sensitive HTTP headers.`);
+    }
 
-    // Init router after tree is processed
-    if (_routerInstance) await _routerInstance.init();
+    // Set current plugin name for interceptor tracking
+    _setCurrentPluginName(plugin.name);
+    try {
+      plugin.install(NoJS, options);
+    } finally {
+      _setCurrentPluginName(null);
+    }
 
-    _log("Initialized.");
+    _plugins.set(plugin.name, { plugin, options });
 
-    // Phase 2 (non-blocking): background preload remaining route templates
-    _loadRemoteTemplatesPhase2();
+    // If already initialized and plugin has init, await then call
+    if (_initPromise && plugin.init) {
+      _initPromise.then(() => plugin.init(NoJS)).catch(e => _warn(`Plugin "${plugin.name}" init error:`, e.message));
+    }
 
-    // DevTools integration
-    initDevtools(NoJS);
+    _log(`Plugin "${plugin.name}" installed.`);
+  },
+
+  // ─── Plugin globals ───────────────────────────────────────────────────
+  global(name, value) {
+    if (typeof name !== "string" || !name) {
+      _warn("NoJS.global() requires a non-empty string name.");
+      return;
+    }
+
+    // Block prototype pollution vectors
+    if (name === "__proto__" || name === "constructor" || name === "prototype") {
+      _warn(`NoJS.global(): "${name}" is a forbidden name.`);
+      return;
+    }
+
+    // Block reserved names
+    if (_RESERVED_GLOBAL_NAMES.has(name)) {
+      _warn(`NoJS.global(): "${name}" is reserved and cannot be used.`);
+      return;
+    }
+
+    // Validate identifier characters
+    if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name)) {
+      _warn(`NoJS.global(): "${name}" is not a valid identifier.`);
+      return;
+    }
+
+    // Block dangerous function references
+    if (_isUnsafeGlobalValue(value)) {
+      _warn(`NoJS.global(): value for "${name}" is a forbidden reference (eval/Function).`);
+      return;
+    }
+
+    // Warn on overwrite by a different plugin
+    if (name in _globals && _globalOwners[name] && _globalOwners[name] !== _currentPluginName) {
+      _warn(`Global "$${name}" owned by "${_globalOwners[name]}" is being overwritten.`);
+    }
+
+    // Sanitize object values to strip __proto__ keys
+    if (value && typeof value === "object" && !value.__isProxy) {
+      try {
+        value = JSON.parse(JSON.stringify(value));
+      } catch {
+        // Non-serializable objects — check for dangerous function references
+        try {
+          _deepCheckUnsafe(value);
+        } catch (safetyErr) {
+          if (safetyErr.message === "unsafe_global") return;
+          // Other errors pass through
+        }
+      }
+      // Wrap in reactive context for deep reactivity
+      value = createContext(value);
+    }
+
+    _globals[name] = value;
+    if (_currentPluginName) _globalOwners[name] = _currentPluginName;
+
+    // Notify all store watchers since globals are scope-wide
+    _notifyStoreWatchers();
+
+    _devtoolsEmit("global:set", { name, hasValue: value != null });
+    _log(`Global "$${name}" registered.`);
+  },
+
+  // ─── App teardown ─────────────────────────────────────────────────────
+  async dispose() {
+    _setDisposing(true);
+    try {
+      // Dispose plugins in reverse installation order
+      const entries = [..._plugins.entries()].reverse();
+      for (const [name, { plugin }] of entries) {
+        if (plugin.dispose) {
+          try {
+            let timeoutId;
+            await Promise.race([
+              Promise.resolve(plugin.dispose(NoJS)).finally(() => clearTimeout(timeoutId)),
+              new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error("Dispose timeout")), 3000);
+              }),
+            ]);
+          } catch (e) {
+            _warn(`Plugin "${name}" dispose error:`, e.message);
+          }
+        }
+      }
+      _plugins.clear();
+      for (const k in _globals) delete _globals[k];
+      for (const k in _globalOwners) delete _globalOwners[k];
+
+      // Clear interceptors
+      _interceptors.request.length = 0;
+      _interceptors.response.length = 0;
+
+      // Destroy router listeners
+      if (_routerInstance && _routerInstance.destroy) {
+        _routerInstance.destroy();
+      }
+      setRouterInstance(null);
+
+      // Clean up devtools listener
+      destroyDevtools();
+
+      _initPromise = null;
+      _log("Disposed.");
+    } finally {
+      _setDisposing(false);
+    }
+  },
+
+  // ─── Init (Promise-based lifecycle) ───────────────────────────────────
+  async init(root) {
+    if (typeof document === "undefined") return;
+    if (_initPromise) return _initPromise;
+    _initPromise = (async () => {
+      root = root || document.body;
+      _log("Initializing...");
+
+      // Load external locale files (blocking — translations must be available for first paint)
+      if (_config.i18n.loadPath) {
+        const locales = new Set([_i18n.locale, _config.i18n.fallbackLocale]);
+        await Promise.all([...locales].map((l) => _loadI18nForLocale(l)));
+      }
+
+      // Inline template includes (e.g. skeletons) — synchronous, before any fetch
+      _processTemplateIncludes(root);
+
+      // Determine active route path for phase 1 prioritization
+      const defaultRoutePath = _getDefaultRoutePath();
+
+      // Phase 1 (blocking): priority + non-route + default route templates
+      await _loadRemoteTemplatesPhase1(defaultRoutePath);
+
+      // Check for route-view outlets to activate router
+      if (document.querySelector("[route-view]")) {
+        setRouterInstance(_createRouter());
+      }
+
+      processTree(root); // ← first paint happens here
+
+      // Init router after tree is processed
+      if (_routerInstance) await _routerInstance.init();
+
+      _log("Initialized.");
+
+      // Phase 2 (non-blocking): background preload remaining route templates
+      _loadRemoteTemplatesPhase2();
+
+      // DevTools integration
+      initDevtools(NoJS);
+
+      // Plugin init hooks
+      for (const [, { plugin }] of _plugins) {
+        if (plugin.init) await plugin.init(NoJS);
+      }
+      _emitEvent("plugins:ready");
+    })();
+    return _initPromise;
   },
 
   // Register custom directive
@@ -230,9 +458,13 @@ const NoJS = {
     };
   },
 
-  // Request interceptors
+  // Request/response interceptors (with plugin tracking)
   interceptor(type, fn) {
-    if (_interceptors[type]) _interceptors[type].push(fn);
+    if (_interceptors[type]) {
+      _interceptors[type].push(
+        _currentPluginName ? { fn, pluginName: _currentPluginName } : fn
+      );
+    }
   },
 
   // Access global stores
@@ -258,7 +490,19 @@ const NoJS = {
   resolve,
 
   // Version
-  version: "1.10.1",
+  version: "1.11.0",
 };
 
+// Expose sentinel symbols as read-only properties
+Object.defineProperty(NoJS, "CANCEL",  { value: _CANCEL,  writable: false, configurable: false });
+Object.defineProperty(NoJS, "RESPOND", { value: _RESPOND, writable: false, configurable: false });
+Object.defineProperty(NoJS, "REPLACE", { value: _REPLACE, writable: false, configurable: false });
+
+// Backward-compat: _initialized getter/setter (tests use `NoJS._initialized = false` to reset)
+Object.defineProperty(NoJS, "_initialized", {
+  get() { return _initPromise !== null; },
+  set(v) { if (!v) _initPromise = null; },
+  configurable: true,
+});
+
 export default NoJS;

package/src/registry.js

@@ -2,17 +2,28 @@
 //  DIRECTIVE REGISTRY & DOM PROCESSING
 // ═══════════════════════════════════════════════════════════════════════
 
-import { _currentEl, _setCurrentEl, _storeWatchers } from "./globals.js";
+import { _currentEl, _setCurrentEl, _storeWatchers, _warn } from "./globals.js";
 import { _i18nListeners } from "./i18n.js";
 import { _devtoolsEmit, _ctxRegistry } from "./devtools.js";
 
 const _directives = new Map();
+let _frozen = false;
+const _coreDirectives = new Set();
 
 export function registerDirective(name, handler) {
+  if (_frozen && _coreDirectives.has(name)) {
+    _warn(`Cannot override core directive "${name}".`);
+    return;
+  }
   _directives.set(name, {
     priority: handler.priority ?? 50,
     init: handler.init,
   });
+  if (!_frozen) _coreDirectives.add(name);
+}
+
+export function _freezeDirectives() {
+  _frozen = true;
 }
 
 function _matchDirective(attrName) {