refactor(core): decouple security validation via injectable policy

- Introduced SecurityPolicy interface to manage object and config sanitization.
- Removed hardcoded web-specific logic (CSS, LayoutBox) from core validation.
- Enabled dependency injection for platform-specific security strategies.
- Achieved true headless architecture for the profile validation layer.

Author: coocoodaegap

packages/core/src/index.ts

@@ -1,4 +1,12 @@
-import { ACTION_TYPES, BUTTON_MAP, CMP_TYPES, CONTEXT, STANDARD_ANCHORS, STANDARD_KEYS, VALID_UNITS } from './constants';
+import {
+  ACTION_TYPES,
+  BUTTON_MAP,
+  CMP_TYPES,
+  CONTEXT,
+  STANDARD_ANCHORS,
+  STANDARD_KEYS,
+  VALID_UNITS,
+} from './constants';
 
 export * from './runtime';
 export * from './types';

packages/core/src/runtime/profile.ts

@@ -9,8 +9,37 @@ import {
 import { Registry } from '../singletons/Registry';
 import { BaseEntity } from '../entities/BaseEntity';
 import { altDeepClone } from '../utils/object';
-import { sanitizeCssClass, sanitizePrototypePollution } from '../utils/security';
-import { compressLayoutBox, validateLayoutBox } from '../utils/layout';
+import { compressLayoutBox } from '../utils/layout';
+
+/**
+ * Interface defining the security and validation strategy for the engine.
+ * Decouples core logic from platform-specific checks (like CSS validation).
+ */
+export interface SecurityPolicy {
+  /**
+   * Scans and sanitizes the raw object (e.g., preventing prototype pollution).
+   */
+  sanitizeObject: <T>(raw: T) => T;
+
+  /**
+   * Validates and normalizes the config object of an item.
+   * This is where platform-specific checks (CSS units, class names) should live.
+   */
+  validateConfig: (type: string, config: any) => any;
+}
+
+/** Default "Pass-through" policy for non-secure or test environments */
+let _currentPolicy: SecurityPolicy = {
+  sanitizeObject: (obj) => obj,
+  validateConfig: (_, cfg) => cfg,
+};
+
+/**
+ * Injects a security policy into the core engine.
+ */
+export function setSecurityPolicy(policy: Partial<SecurityPolicy>) {
+  _currentPolicy = { ..._currentPolicy, ...policy };
+}
 
 const MAX_PROFILE_ITEMS = 100; // 单个配置允许的最大组件数
 const MAX_PROFILE_SIZE = 512 * 1024; // 512kB
@@ -40,7 +69,7 @@ export function validateProfile(raw: any): OmniPadProfile {
   }
 
   // 过滤原型链污染
-  raw = sanitizePrototypePollution(raw);
+  raw = _currentPolicy.sanitizeObject(raw);
 
   // ID 唯一性检查
   const idSet = new Set<string>();
@@ -68,12 +97,12 @@ export function validateProfile(raw: any): OmniPadProfile {
       id: String(item.id),
       type: String(item.type),
       parentId: item.parentId ? String(item.parentId) : undefined,
-      // 确保 config 存在，业务参数平铺于此
-      config: {
-        ...item.config,
-        layout: validateLayoutBox(item.config.layout),
-        cssClass: sanitizeCssClass(item.config.cssClass),
-      },
+      config: _currentPolicy.validateConfig(item.type, item.config || {}),
+      // config: {
+      //   ...item.config,
+      //   layout: validateLayoutBox(item.config.layout),
+      //   cssClass: sanitizeCssClass(item.config.cssClass),
+      // },
     };
   });
 

packages/core/src/types/index.ts

@@ -86,7 +86,7 @@ export type FlexibleLength = ParsedLength | string | number;
 /**
  * Anchor position used to determine the alignment of an element relative to its coordinates.
  */
-export type AnchorPoint = typeof STANDARD_ANCHORS[number];
+export type AnchorPoint = (typeof STANDARD_ANCHORS)[number];
 
 /**
  * =================================================================

packages/core/src/utils/index.ts

@@ -1,5 +1,6 @@
 export * from './cache';
 export * from './distill';
 export * from './id';
+export * from './layout';
 export * from './math';
 export * from './object';

packages/core/src/utils/layout.ts

@@ -1,61 +1,4 @@
-import { VALID_UNITS } from '../constants';
-import { LayoutBox, CssUnit, ParsedLength, FlexibleLength } from '../types';
-import { sanitizeDomString } from './security';
-
-/**
- * Convert the length input into a sanitized ParsedLength
- *
- * @param input - The raw length input.
- * @returns A sanitized ParsedLength.
- */
-export function parseLength(input: FlexibleLength | undefined): ParsedLength | undefined {
-  // 1. 处理空值或无效值
-  if (input == null) {
-    return undefined;
-  }
-
-  // 2. 处理 ParsedLength 对象
-  if (typeof input === 'object' && 'unit' in input && 'value' in input) {
-    return sanitizeParsedLength(input);
-  }
-
-  // 3. 处理纯数字：默认 px
-  if (typeof input === 'number') {
-    return {
-      value: Number.isFinite(input) ? input : 0,
-      unit: 'px',
-    };
-  }
-
-  // 4. 处理字符串
-  const val = input.trim().toLowerCase();
-  const numericPart = parseFloat(val);
-
-  // 检查数字部分是否有效
-  if (isNaN(numericPart)) {
-    return { value: 0, unit: 'px' };
-  }
-
-  // 直接截取剩下的所有内容作为单位
-  const unitPart = val.slice(String(numericPart).length).trim();
-
-  return sanitizeParsedLength({ value: numericPart, unit: unitPart as CssUnit });
-}
-
-/**
- * Check the whitelist of verification units and sanitize ParsedLength.
- */
-export const sanitizeParsedLength = (parsed: ParsedLength): ParsedLength => {
-  const { value, unit } = parsed;
-
-  if (!isNaN(value) && (VALID_UNITS as readonly string[]).includes(unit)) {
-    return { value, unit };
-  }
-
-  // 非法单位，降级为 px
-  console.warn(`[OmniPad-Core] Blocked invalid CSS unit: ${unit}`);
-  return { value: isNaN(value) ? 0 : value, unit: 'px' };
-};
+import { LayoutBox, ParsedLength } from '../types';
 
 /**
  * Convert the ParsedLength back to a CSS string
@@ -64,23 +7,6 @@ export const lengthToCss = (parsed: ParsedLength | undefined): string | undefine
   return parsed == null ? undefined : `${parsed.value}${parsed.unit}`;
 };
 
-/**
- * Validate a raw LayoutBox config.
- */
-export function validateLayoutBox(raw: LayoutBox): LayoutBox {
-  return {
-    ...raw,
-    left: parseLength(raw.left),
-    top: parseLength(raw.top),
-    right: parseLength(raw.right),
-    bottom: parseLength(raw.bottom),
-    width: parseLength(raw.width),
-    height: parseLength(raw.height),
-    // 关键：对选择器和类名进行脱毒处理 / Critical: Sanitize selector and class names
-    stickySelector: sanitizeDomString(raw.stickySelector),
-  };
-}
-
 /**
  * Compress layout properties into css strings.
  */

packages/core/src/utils/security.ts

@@ -35,7 +35,9 @@ const defaultProps = {
 };
 
 const { uid, core, state, domEvents, effectiveConfig, effectiveLayout, elementRef } =
-  useWidgetSetup<ButtonCore, ButtonState, ButtonConfig>(OmniPad.Types.BUTTON, props, { defaultProps });
+  useWidgetSetup<ButtonCore, ButtonState, ButtonConfig>(OmniPad.Types.BUTTON, props, {
+    defaultProps,
+  });
 
 // 转发交互
 const onPointerDown = (e: PointerEvent) => domEvents?.onPointerDown?.(e);

packages/vue/src/components/VirtualButton.vue

@@ -35,7 +35,10 @@ export function useWidgetConfig<T extends BaseConfig>(
   const treeNode = validateWidgetNode(props.treeNode, requiredType);
 
   // 确定父节点编号
-  const injectedParentId = inject<Ref<string | undefined>>(OmniPad.Context.PARENT_ID_KEY, ref(undefined));
+  const injectedParentId = inject<Ref<string | undefined>>(
+    OmniPad.Context.PARENT_ID_KEY,
+    ref(undefined),
+  );
   const parentId = computed(() => {
     return props.parentId || treeNode?.config?.parentId || injectedParentId.value;
   });

packages/vue/src/composables/useWidgetConfig.ts

@@ -4,8 +4,11 @@ import {
   setGamepadProvider,
   setGlobalSignalHandler,
   setRafProvider,
+  setSecurityPolicy,
 } from '@omnipad/core';
 import { dispatchKeyboardEvent } from './dom/action';
+import { sanitizeCssClass, sanitizePrototypePollution } from './ts/security';
+import { validateLayoutBox } from './ts/layout';
 
 export * from './dom';
 export * from './ts';
@@ -38,3 +41,15 @@ if (typeof navigator !== 'undefined' && navigator.getGamepads) {
     return gamepadSnapshot;
   });
 }
+
+setSecurityPolicy({
+  sanitizeObject: (obj) => sanitizePrototypePollution(obj),
+
+  validateConfig: (_, config) => {
+    return {
+      ...config,
+      layout: validateLayoutBox(config.layout),
+      cssClass: sanitizeCssClass(config.cssClass),
+    };
+  },
+});