xinyu-pro 0.21.0

package/lib/plugin-dom-sandbox.ts

@@ -0,0 +1,327 @@
+// lib/plugin-dom-sandbox.ts - DOM 安全沙箱
+// 为插件提供受限的 DOM 操作能力，确保安全边界
+
+import { PluginResourceTracker } from './plugin-resource-tracker';
+import { sanitizeHTML, isTagAllowed, isAttrAllowed } from './plugin-html-sanitizer';
+import { UISlotId } from './plugin-types';
+
+/** DOM 沙箱配置 */
+interface DOMSandboxConfig {
+  pluginId: string;
+  resourceTracker: PluginResourceTracker;
+  getContainerElement: (slotId: UISlotId) => HTMLElement | null;
+}
+
+/** 创建的 DOM 元素代理信息 */
+interface DOMElementProxy {
+  __proxyId: string;
+  __pluginId: string;
+  __tag: string;
+  __attrs: Record<string, string>;
+  __children: Array<DOMElementProxy | string>;
+  __eventHandlers: Map<string, Array<(...args: unknown[]) => unknown>>;
+}
+
+/** 元素 ID 计数器（按插件隔离） */
+const elementCounters: Map<string, number> = new Map();
+
+/**
+ * 创建 DOM 沙箱 API
+ * 返回一个对象，包含所有安全的 DOM 操作方法
+ */
+export function createDOMSandbox(config: DOMSandboxConfig) {
+  const { pluginId, resourceTracker, getContainerElement } = config;
+
+  if (!elementCounters.has(pluginId)) {
+    elementCounters.set(pluginId, 0);
+  }
+
+  /**
+   * 创建一个 DOM 元素代理
+   */
+  function create(
+    tag: string,
+    attrs?: Record<string, string>,
+    children?: string | Array<DOMElementProxy | string>
+  ): DOMElementProxy {
+    // 验证标签名
+    if (!isTagAllowed(tag)) {
+      throw new Error(`[DOMSandbox] 插件 ${pluginId}: 不允许创建 <${tag}> 标签`);
+    }
+
+    const counter = (elementCounters.get(pluginId) || 0) + 1;
+    elementCounters.set(pluginId, counter);
+
+    const proxyId = `${pluginId}_el_${counter}`;
+
+    // 过滤属性
+    const safeAttrs: Record<string, string> = {};
+    if (attrs) {
+      for (const [key, value] of Object.entries(attrs)) {
+        if (isAttrAllowed(key)) {
+          safeAttrs[key] = String(value);
+        }
+      }
+    }
+
+    const proxy: DOMElementProxy = {
+      __proxyId: proxyId,
+      __pluginId: pluginId,
+      __tag: tag,
+      __attrs: safeAttrs,
+      __children: [],
+      __eventHandlers: new Map(),
+    };
+
+    // 处理子元素
+    if (children !== undefined) {
+      if (typeof children === 'string') {
+        proxy.__children.push(children);
+      } else if (Array.isArray(children)) {
+        proxy.__children.push(...children);
+      }
+    }
+
+    return proxy;
+  }
+
+  /**
+   * 将代理元素渲染为真实 DOM 并追加到容器
+   */
+  function append(containerId: string, element: DOMElementProxy | string): string | null {
+    const container = getContainerElement(containerId as UISlotId);
+    if (!container) {
+      console.warn(`[DOMSandbox] 插件 ${pluginId}: 容器 "${containerId}" 不存在`);
+      return null;
+    }
+
+    let realElement: HTMLElement;
+
+    if (typeof element === 'string') {
+      // HTML 字符串模式
+      const sanitized = sanitizeHTML(element);
+      const wrapper = document.createElement('div');
+      wrapper.innerHTML = sanitized;
+      wrapper.setAttribute('data-plugin-id', pluginId);
+
+      // 追加所有子节点
+      while (wrapper.firstChild) {
+        container.appendChild(wrapper.firstChild);
+      }
+
+      const wrapperId = `${pluginId}_html_${Date.now()}`;
+      resourceTracker.trackElement(pluginId, wrapperId, wrapper);
+      return wrapperId;
+    } else {
+      // 代理元素模式
+      realElement = renderProxyToDOM(element);
+      container.appendChild(realElement);
+      resourceTracker.trackElement(pluginId, element.__proxyId, realElement);
+      return element.__proxyId;
+    }
+  }
+
+  /**
+   * 移除插件创建的元素
+   */
+  function remove(elementId: string): boolean {
+    const element = resourceTracker.getElement(pluginId, elementId);
+    if (!element) {
+      console.warn(`[DOMSandbox] 插件 ${pluginId}: 元素 "${elementId}" 不存在或不属于该插件`);
+      return false;
+    }
+
+    try {
+      if (element.parentNode) {
+        element.parentNode.removeChild(element);
+      }
+      resourceTracker.untrackElement(pluginId, elementId);
+      return true;
+    } catch (e) {
+      console.error(`[DOMSandbox] 插件 ${pluginId}: 移除元素失败:`, e);
+      return false;
+    }
+  }
+
+  /**
+   * 更新元素属性
+   */
+  function update(elementId: string, props: Record<string, string>): boolean {
+    const element = resourceTracker.getElement(pluginId, elementId);
+    if (!element) {
+      console.warn(`[DOMSandbox] 插件 ${pluginId}: 元素 "${elementId}" 不存在或不属于该插件`);
+      return false;
+    }
+
+    try {
+      for (const [key, value] of Object.entries(props)) {
+        if (key === 'style') {
+          element.setAttribute('style', value);
+        } else if (key === 'className' || key === 'class') {
+          element.className = value;
+        } else if (key === 'textContent') {
+          element.textContent = value;
+        } else if (key === 'innerHTML') {
+          element.innerHTML = sanitizeHTML(value);
+        } else if (isAttrAllowed(key)) {
+          element.setAttribute(key, value);
+        }
+      }
+      return true;
+    } catch (e) {
+      console.error(`[DOMSandbox] 插件 ${pluginId}: 更新元素失败:`, e);
+      return false;
+    }
+  }
+
+  /**
+   * 获取容器引用（返回受限信息）
+   */
+  function getContainer(containerId: string): { id: string; exists: boolean; childCount: number } | null {
+    const container = getContainerElement(containerId as UISlotId);
+    if (!container) return null;
+    return {
+      id: containerId,
+      exists: true,
+      childCount: container.children.length,
+    };
+  }
+
+  /**
+   * 在容器内查询元素（仅限插件自己的元素）
+   */
+  function query(containerId: string, selector: string): Array<{ id: string; tag: string; textContent: string }> {
+    const container = getContainerElement(containerId as UISlotId);
+    if (!container) return [];
+
+    try {
+      const results: Array<{ id: string; tag: string; textContent: string }> = [];
+      const elements = container.querySelectorAll(selector);
+
+      elements.forEach((el) => {
+        // 检查元素自身或最近祖先的 data-plugin-id
+        const pluginOwner = el.closest<HTMLElement>('[data-plugin-id]');
+        if (pluginOwner && pluginOwner.getAttribute('data-plugin-id') === pluginId) {
+          results.push({
+            id: el.id || '',
+            tag: el.tagName.toLowerCase(),
+            textContent: el.textContent || '',
+          });
+        }
+      });
+
+      return results;
+    } catch (e) {
+      console.error(`[DOMSandbox] 插件 ${pluginId}: 查询失败:`, e);
+      return [];
+    }
+  }
+
+  /**
+   * 绑定事件
+   */
+  function on(elementId: string, event: string, handler: (...args: unknown[]) => unknown): boolean {
+    const element = resourceTracker.getElement(pluginId, elementId);
+    if (!element) {
+      console.warn(`[DOMSandbox] 插件 ${pluginId}: 元素 "${elementId}" 不存在`);
+      return false;
+    }
+
+    // 拦截危险事件
+    const forbiddenEvents = ['keydown', 'keyup', 'keypress'];
+    if (forbiddenEvents.includes(event)) {
+      console.warn(`[DOMSandbox] 插件 ${pluginId}: 不允许监听 "${event}" 事件`);
+      return false;
+    }
+
+    const wrappedHandler = (() => {
+      try {
+        handler();
+      } catch (err) {
+        console.error(`[DOMSandbox] 插件 ${pluginId} 事件处理器错误:`, err);
+      }
+    }) as EventListener;
+
+    element.addEventListener(event, wrappedHandler);
+    resourceTracker.trackEventListener(pluginId, {
+      element,
+      event,
+      handler: wrappedHandler,
+    });
+
+    return true;
+  }
+
+  /**
+   * 解绑事件
+   * 注意：简化处理，实际应精确匹配 handler
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  function off(elementId: string, event: string): boolean {
+    const element = resourceTracker.getElement(pluginId, elementId);
+    if (!element) return false;
+    return true;
+  }
+
+  /**
+   * 将代理元素递归渲染为真实 DOM
+   */
+  function renderProxyToDOM(proxy: DOMElementProxy): HTMLElement {
+    const element = document.createElement(proxy.__tag);
+    element.setAttribute('data-plugin-id', proxy.__pluginId);
+    element.setAttribute('data-proxy-id', proxy.__proxyId);
+
+    // 设置属性
+    for (const [key, value] of Object.entries(proxy.__attrs)) {
+      if (key === 'style') {
+        element.setAttribute('style', value);
+      } else if (key === 'className' || key === 'class') {
+        element.className = value;
+      } else {
+        element.setAttribute(key, value);
+      }
+    }
+
+    // 渲染子元素
+    for (const child of proxy.__children) {
+      if (typeof child === 'string') {
+        element.textContent = child;
+      } else if (child.__proxyId) {
+        element.appendChild(renderProxyToDOM(child));
+      }
+    }
+
+    // 绑定事件
+    proxy.__eventHandlers.forEach((handlers, eventName) => {
+      handlers.forEach((handler) => {
+        const wrappedHandler = ((e: Event) => {
+          try {
+            handler(e);
+          } catch (err) {
+            console.error(`[DOMSandbox] 事件处理器错误:`, err);
+          }
+        }) as EventListener;
+
+        element.addEventListener(eventName, wrappedHandler);
+        resourceTracker.trackEventListener(proxy.__pluginId, {
+          element,
+          event: eventName,
+          handler: wrappedHandler,
+        });
+      });
+    });
+
+    return element;
+  }
+
+  return {
+    create,
+    append,
+    remove,
+    update,
+    getContainer,
+    query,
+    on,
+    off,
+  };
+}

package/lib/plugin-events.ts

@@ -0,0 +1,88 @@
+// lib/plugin-events.ts - 插件状态变更跨标签页同步
+
+const CHANNEL_NAME = 'xinyu-plugin-binding-change';
+
+export interface PluginBindingChangeEvent {
+  /** 变更的插件 ID */
+  pluginId: string;
+  /** 新的启用状态 */
+  enabled: boolean;
+  /** 变更来源：'global' = 设置页（局外），'world' = 游戏页（局内） */
+  source: 'global' | 'world';
+  /** 关联的世界 ID（局内变更时） */
+  worldId?: string;
+}
+
+/** 插件配置变更事件 */
+export interface PluginConfigChangeEvent {
+  /** 变更的插件 ID */
+  pluginId: string;
+  /** 新的配置值 */
+  config: Record<string, unknown>;
+  /** 关联的世界 ID（如果有） */
+  worldId?: string;
+}
+
+let channel: BroadcastChannel | null = null;
+
+/** 获取 BroadcastChannel 单例（仅客户端） */
+function getChannel(): BroadcastChannel | null {
+  if (typeof window === 'undefined') return null;
+  if (!channel) {
+    try {
+      channel = new BroadcastChannel(CHANNEL_NAME);
+    } catch {
+      // 浏览器不支持 BroadcastChannel 时降级
+      console.warn('[PluginEvents] BroadcastChannel 不可用');
+    }
+  }
+  return channel;
+}
+
+/** 广播插件绑定变更事件（启用/禁用） */
+export function broadcastPluginBindingChange(event: PluginBindingChangeEvent): void {
+  const ch = getChannel();
+  if (ch) {
+    ch.postMessage({ type: 'binding', ...event });
+  }
+}
+
+/** 广播插件配置变更事件 */
+export function broadcastPluginConfigChange(event: PluginConfigChangeEvent): void {
+  const ch = getChannel();
+  if (ch) {
+    ch.postMessage({ type: 'config', ...event });
+  }
+}
+
+/** 监听插件绑定变更事件（启用/禁用） */
+export function onPluginBindingChange(
+  callback: (event: PluginBindingChangeEvent) => void
+): () => void {
+  const ch = getChannel();
+  if (!ch) return () => {};
+
+  const handler = (e: MessageEvent) => {
+    if (e.data?.type === 'binding') {
+      callback(e.data as PluginBindingChangeEvent);
+    }
+  };
+  ch.addEventListener('message', handler);
+  return () => ch.removeEventListener('message', handler);
+}
+
+/** 监听插件配置变更事件 */
+export function onPluginConfigChange(
+  callback: (event: PluginConfigChangeEvent) => void
+): () => void {
+  const ch = getChannel();
+  if (!ch) return () => {};
+
+  const handler = (e: MessageEvent) => {
+    if (e.data?.type === 'config') {
+      callback(e.data as PluginConfigChangeEvent);
+    }
+  };
+  ch.addEventListener('message', handler);
+  return () => ch.removeEventListener('message', handler);
+}

package/lib/plugin-files.ts

@@ -0,0 +1,186 @@
+// lib/plugin-files.ts - 插件文件读写工具（代码 + 资源）
+
+import { promises as fs } from 'fs';
+import path from 'path';
+
+/** 插件文件根目录 */
+const PLUGIN_ROOT = path.join(process.cwd(), 'data', 'plugins');
+
+/** 校验插件 ID 合法性（防止路径遍历攻击） */
+function isValidPluginId(id: string): boolean {
+  return /^[a-zA-Z0-9._-]+$/.test(id) && id.length <= 200 && !id.includes('..');
+}
+
+/** 校验文件路径安全性 */
+function isSafePath(filePath: string): boolean {
+  const normalized = path.normalize(filePath);
+  return !normalized.includes('..') && !path.isAbsolute(normalized) && normalized !== '';
+}
+
+/**
+ * 获取插件目录的绝对路径
+ */
+export function getPluginDir(pluginId: string): string {
+  if (!isValidPluginId(pluginId)) {
+    throw new Error(`非法插件 ID: ${pluginId}`);
+  }
+  return path.join(PLUGIN_ROOT, pluginId);
+}
+
+/**
+ * 获取插件代码文件的绝对路径
+ * @param pluginId 插件 ID
+ * @param entryFile 入口文件名（如 index.js），默认 plugin.js
+ */
+export function getPluginCodePath(pluginId: string, entryFile?: string): string {
+  return path.join(getPluginDir(pluginId), entryFile || 'plugin.js');
+}
+
+/**
+ * 获取插件代码的相对路径（存入数据库）
+ * @param pluginId 插件 ID
+ * @param entryFile 入口文件名（如 index.js），默认 plugin.js
+ */
+export function getPluginCodeRelativePath(pluginId: string, entryFile?: string): string {
+  return `data/plugins/${pluginId}/${entryFile || 'plugin.js'}`;
+}
+
+/**
+ * 读取插件代码
+ * @param pluginId 插件 ID
+ * @param entryFile 入口文件名（如 index.js），默认 plugin.js
+ */
+export async function readPluginCode(pluginId: string, entryFile?: string): Promise<string> {
+  const filePath = getPluginCodePath(pluginId, entryFile);
+  try {
+    return await fs.readFile(filePath, 'utf-8');
+  } catch {
+    throw new Error(`插件代码文件不存在: ${pluginId}/${entryFile || 'plugin.js'}`);
+  }
+}
+
+/**
+ * 写入插件代码
+ * @param pluginId 插件 ID
+ * @param code 代码内容
+ * @param entryFile 入口文件名（如 index.js），默认 plugin.js
+ */
+export async function writePluginCode(pluginId: string, code: string, entryFile?: string): Promise<string> {
+  const pluginDir = getPluginDir(pluginId);
+  await fs.mkdir(pluginDir, { recursive: true });
+  const fileName = entryFile || 'plugin.js';
+  const filePath = path.join(pluginDir, fileName);
+  await fs.writeFile(filePath, code, 'utf-8');
+  return getPluginCodeRelativePath(pluginId, fileName);
+}
+
+/**
+ * 删除插件整个目录（代码 + 资源）
+ */
+export async function deletePluginCode(pluginId: string): Promise<void> {
+  const pluginDir = getPluginDir(pluginId);
+  try {
+    await fs.rm(pluginDir, { recursive: true, force: true });
+  } catch {
+    // 目录不存在时忽略
+  }
+}
+
+/**
+ * 读取插件资源文件（返回 Buffer）
+ */
+export async function readPluginResource(pluginId: string, resourcePath: string): Promise<Buffer> {
+  if (!isValidPluginId(pluginId)) {
+    throw new Error(`非法插件 ID: ${pluginId}`);
+  }
+  if (!isSafePath(resourcePath)) {
+    throw new Error(`非法资源路径: ${resourcePath}`);
+  }
+
+  const absolutePath = path.join(PLUGIN_ROOT, pluginId, resourcePath);
+
+  // 安全检查：确保路径在插件目录内
+  const pluginDir = path.resolve(getPluginDir(pluginId));
+  const resolvedPath = path.resolve(absolutePath);
+  if (!resolvedPath.startsWith(pluginDir + path.sep)) {
+    throw new Error(`资源路径越界: ${resourcePath}`);
+  }
+
+  return await fs.readFile(absolutePath);
+}
+
+/**
+ * 读取插件资源文件（返回文本）
+ */
+export async function readPluginResourceText(pluginId: string, resourcePath: string): Promise<string> {
+  const buffer = await readPluginResource(pluginId, resourcePath);
+  return buffer.toString('utf-8');
+}
+
+/**
+ * 写入插件资源文件
+ */
+export async function writePluginResource(pluginId: string, resourcePath: string, data: Buffer | string): Promise<void> {
+  if (!isValidPluginId(pluginId)) {
+    throw new Error(`非法插件 ID: ${pluginId}`);
+  }
+  if (!isSafePath(resourcePath)) {
+    throw new Error(`非法资源路径: ${resourcePath}`);
+  }
+
+  const absolutePath = path.join(PLUGIN_ROOT, pluginId, resourcePath);
+  await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+  await fs.writeFile(absolutePath, data);
+}
+
+/**
+ * 删除插件资源文件
+ */
+export async function deletePluginResource(pluginId: string, resourcePath: string): Promise<void> {
+  if (!isValidPluginId(pluginId)) {
+    throw new Error(`非法插件 ID: ${pluginId}`);
+  }
+  if (!isSafePath(resourcePath)) {
+    throw new Error(`非法资源路径: ${resourcePath}`);
+  }
+
+  const absolutePath = path.join(PLUGIN_ROOT, pluginId, resourcePath);
+  try {
+    await fs.unlink(absolutePath);
+  } catch {
+    // 文件不存在时忽略
+  }
+}
+
+/**
+ * 列出插件目录下的所有文件
+ */
+export async function listPluginFiles(pluginId: string): Promise<string[]> {
+  const pluginDir = getPluginDir(pluginId);
+  const files: string[] = [];
+  try {
+    await collectFiles(pluginDir, pluginDir, files);
+  } catch {
+    // 目录不存在时返回空数组
+  }
+  return files;
+}
+
+/** 递归收集文件和目录 */
+async function collectFiles(baseDir: string, currentDir: string, result: string[]): Promise<void> {
+  const entries = await fs.readdir(currentDir, { withFileTypes: true });
+  let hasChild = false;
+  for (const entry of entries) {
+    hasChild = true;
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      await collectFiles(baseDir, fullPath, result);
+    } else {
+      result.push(path.relative(baseDir, fullPath));
+    }
+  }
+  // 空目录也收集（以 / 结尾标识）
+  if (!hasChild && currentDir !== baseDir) {
+    result.push(path.relative(baseDir, currentDir) + '/');
+  }
+}

package/lib/plugin-html-sanitizer.ts

@@ -0,0 +1,79 @@
+// lib/plugin-html-sanitizer.ts - HTML 净化器
+// 对插件注入的 HTML 字符串进行安全净化处理
+
+/** 允许的 HTML 标签 */
+const ALLOWED_TAGS = new Set([
+  'div', 'span', 'p', 'a', 'button', 'input', 'textarea', 'select', 'option',
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'ul', 'ol', 'li', 'table', 'thead', 'tbody', 'tr', 'th', 'td',
+  'img', 'svg', 'canvas', 'br', 'hr',
+  'strong', 'em', 'b', 'i', 'u', 's', 'code', 'pre', 'blockquote',
+  'label', 'form', 'fieldset', 'legend',
+  'header', 'footer', 'nav', 'main', 'section', 'article', 'aside',
+  'details', 'summary',
+]);
+
+/** 禁止的属性（事件处理器等） */
+const FORBIDDEN_ATTR_PREFIXES = ['on', 'srcdoc', 'formaction', 'xlink:href'];
+
+/** 禁止的标签 */
+const FORBIDDEN_TAGS = new Set(['script', 'style', 'link', 'meta', 'iframe', 'object', 'embed', 'applet']);
+
+/**
+ * 净化 HTML 字符串，移除危险标签和属性
+ * @param html 原始 HTML 字符串
+ * @param pluginId 插件 ID（用于添加标识属性）
+ * @returns 净化后的 HTML 字符串
+ */
+export function sanitizeHTML(html: string): string {
+  if (!html || typeof html !== 'string') return '';
+
+  let sanitized = html;
+
+  // 1. 移除 script 标签及其内容
+  sanitized = sanitized.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
+
+  // 2. 移除其他禁止标签（自闭合和开闭标签）
+  FORBIDDEN_TAGS.forEach((tag) => {
+    const regex = new RegExp(`<${tag}\\b[^>]*\\/?>`, 'gi');
+    sanitized = sanitized.replace(regex, '');
+    // 闭合标签
+    const closeRegex = new RegExp(`<\\/${tag}>`, 'gi');
+    sanitized = sanitized.replace(closeRegex, '');
+  });
+
+  // 3. 移除所有 on* 事件属性
+  sanitized = sanitized.replace(/\s+on\w+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]*)/gi, '');
+
+  // 4. 移除 srcdoc 属性
+  sanitized = sanitized.replace(/\s+srcdoc\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]*)/gi, '');
+
+  // 5. 移除 javascript: 协议
+  sanitized = sanitized.replace(/href\s*=\s*["']?\s*javascript\s*:/gi, 'href="about:blank"');
+
+  // 6. 移除 data: 协议中的非图片类型
+  sanitized = sanitized.replace(/src\s*=\s*["']?\s*data\s*:(?!image\/)[^"'\s>]*/gi, 'src=""');
+
+  // 7. 移除 expression() CSS（IE 特有）
+  sanitized = sanitized.replace(/expression\s*\([^)]*\)/gi, '');
+
+  // 8. 移除 vbscript:
+  sanitized = sanitized.replace(/vbscript\s*:/gi, '');
+
+  return sanitized;
+}
+
+/**
+ * 验证标签名是否安全
+ */
+export function isTagAllowed(tag: string): boolean {
+  return ALLOWED_TAGS.has(tag.toLowerCase());
+}
+
+/**
+ * 验证属性名是否安全
+ */
+export function isAttrAllowed(attr: string): boolean {
+  const lower = attr.toLowerCase();
+  return !FORBIDDEN_ATTR_PREFIXES.some((prefix) => lower.startsWith(prefix));
+}