/**
* 安全工具类 - 防止 XSS 攻击
*/
import DOMPurify from 'dompurify';
import type { Config } from 'dompurify';
import {
domPurifySecurityHooks,
domPurifySecurityOptions,
markdownDomPurifyConfig,
} from './markdownDomPurify.ts';
const PROVIDER_IMAGE_PLACEHOLDER = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==';
const PROVIDER_FILE_SCHEME_RE = /^(local|minio|cos|tos|s3|oss|ks3|obs):\/\/\S+$/i;
// 配置 DOMPurify 的安全策略
const DOMPurifyConfig = {
// 允许的标签
ALLOWED_TAGS: [
'p', 'br', 'strong', 'em', 'u', 's', 'del', 'ins',
'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
'ul', 'ol', 'li', 'blockquote', 'pre', 'code',
'a', 'img', 'table', 'thead', 'tbody', 'tr', 'th', 'td',
'div', 'span', 'figure', 'figcaption', 'details', 'summary', 'think', 'button',
// Mermaid SVG 支持的标签
'svg', 'g', 'path', 'rect', 'circle', 'ellipse', 'line', 'polygon',
'polyline', 'text', 'tspan', 'defs', 'marker', 'filter', 'use',
'clippath', 'lineargradient', 'radialgradient', 'stop', 'pattern',
'image', 'foreignobject', 'desc', 'title', 'switch', 'symbol', 'mask',
// KaTeX MathML 支持的标签
'math', 'annotation', 'semantics', 'mo', 'mi', 'mn', 'msup', 'mrow', 'mfrac', 'msqrt', 'mroot', 'mstyle'
],
// 允许的属性
ALLOWED_ATTR: [
'href', 'title', 'alt', 'src', 'class', 'id', 'style', 'data-protected-src', 'data-img-loading',
'target', 'rel', 'width', 'height', 'open',
'type', 'aria-label', 'disabled', 'role', 'tabindex',
// Mermaid SVG 支持的属性
'd', 'fill', 'stroke', 'stroke-width', 'stroke-linecap', 'stroke-linejoin',
'stroke-dasharray', 'stroke-dashoffset', 'stroke-miterlimit', 'stroke-opacity',
'fill-opacity', 'opacity', 'transform', 'viewbox', 'preserveaspectratio',
'x', 'y', 'x1', 'y1', 'x2', 'y2', 'cx', 'cy', 'rx', 'ry', 'r',
'dx', 'dy', 'text-anchor', 'dominant-baseline', 'font-family', 'font-size',
'font-weight', 'font-style', 'letter-spacing', 'word-spacing',
'marker-start', 'marker-mid', 'marker-end', 'markerunits', 'markerwidth',
'markerheight', 'refx', 'refy', 'orient', 'points', 'offset',
'gradientunits', 'gradienttransform', 'spreadmethod', 'stop-color', 'stop-opacity',
'patternunits', 'patterntransform', 'clippathunits', 'maskunits',
'filterunits', 'primitiveunits', 'xmlns', 'xmlns:xlink', 'xlink:href',
'version', 'baseprofile', 'enable-background', 'overflow', 'visibility',
'display', 'pointer-events', 'cursor', 'data-emit', 'direction',
// KaTeX MathML 支持的属性
'mathvariant', 'encoding', 'aria-hidden'
],
USE_PROFILES: { html: true, svg: true, mathMl: true },
...domPurifySecurityOptions,
HOOKS: domPurifySecurityHooks,
};
/**
* 安全地清理 HTML 内容
* @param html 需要清理的 HTML 字符串
* @returns 清理后的安全 HTML 字符串
*/
export function sanitizeHTML(html: string): string {
if (!html || typeof html !== 'string') {
return '';
}
try {
const preparedHTML = protectProviderImageSrcInHTML(html);
return DOMPurify.sanitize(preparedHTML, DOMPurifyConfig as unknown as Config);
} catch (error) {
console.error('HTML sanitization failed:', error);
// 如果清理失败,返回转义的纯文本
return escapeHTML(html);
}
}
/** Sanitize assistant markdown HTML (code/mermaid toolbars, KaTeX, SVG). */
export function sanitizeMarkdownHTML(html: string): string {
if (!html || typeof html !== 'string') {
return '';
}
try {
const preparedHTML = protectProviderImageSrcInHTML(html);
return DOMPurify.sanitize(preparedHTML, markdownDomPurifyConfig as unknown as Config);
} catch (error) {
console.error('Markdown HTML sanitization failed:', error);
return escapeHTML(html);
}
}
export function protectProviderImageSrcInHTML(html: string): string {
if (!html) return html;
return html.replace(
/
]*?)\ssrc=(["'])(local|minio|cos|tos|s3|oss|ks3|obs):(?:\/\/|//|//)([^"']+)\2([^>]*)>/gi,
(_m, before, quote, provider, restPathRaw, after) => {
const restPath = decodeProviderURL(restPathRaw);
const protectedSrc = `${provider}://${restPath}`;
// A definitive 404 should not leave a skeleton behind. Streaming
// re-renders call this function repeatedly, so remember the missing
// source until the explicit end-of-stream retry clears the cache.
if (protectedFileMissingSources.has(protectedSrc)) {
return '';
}
// Reuse the already-hydrated blob if we have one, so repeated re-renders
// (typewriter streaming) keep the same stable image instead of flashing
// back to the placeholder every frame.
const cachedBlobURL = protectedFileBlobBySource.get(protectedSrc);
if (cachedBlobURL) {
return `
`;
}
// Not hydrated yet: render the 1x1 placeholder but tag it so CSS can give
// it a stable skeleton box. Otherwise width:auto/height:auto collapse the
// 1x1 gif to a ~1px line that violently jumps to full size once loaded.
return `
`;
},
);
}
function decodeProviderURL(raw: string): string {
return raw
.trim()
.replace(///gi, '/')
.replace(///g, '/')
.replace(/&/g, '&')
.replace(/"/g, '"');
}
function isProviderFileURL(url: string): boolean {
return PROVIDER_FILE_SCHEME_RE.test(url.trim());
}
function providerSourceFromImageSrc(src: string): string | null {
const decodedSrc = decodeProviderURL(src);
if (isProviderFileURL(decodedSrc)) {
return decodedSrc;
}
try {
const baseURL = typeof window !== 'undefined' ? window.location.origin : 'http://localhost';
const url = new URL(decodedSrc, baseURL);
const isFileProxy =
url.pathname === '/files' ||
/^\/api\/v1\/embed\/[^/]+\/files$/.test(url.pathname);
if (!isFileProxy) {
return null;
}
const filePath = (url.searchParams.get('file_path') || '').trim();
return isProviderFileURL(filePath) ? filePath : null;
} catch {
return null;
}
}
function normalizeProtectedImageElement(img: HTMLImageElement): string | null {
const protectedSrc = providerSourceFromImageSrc(
img.getAttribute('data-protected-src') || '',
);
const src = img.getAttribute('src') || '';
const sourceURL = protectedSrc || providerSourceFromImageSrc(src);
if (!sourceURL) {
return null;
}
img.setAttribute('data-protected-src', sourceURL);
if (!src.trim().startsWith('blob:')) {
img.setAttribute('src', PROVIDER_IMAGE_PLACEHOLDER);
}
return sourceURL;
}
/**
* 转义 HTML 特殊字符
* @param text 需要转义的文本
* @returns 转义后的文本
*/
export function escapeHTML(text: string): string {
if (!text || typeof text !== 'string') {
return '';
}
const map: { [key: string]: string } = {
'&': '&',
'<': '<',
'>': '>',
'"': '"',
"'": ''',
'/': '/',
'`': '`',
'=': '='
};
return text.replace(/[&<>"'`=\/]/g, (s) => map[s]);
}
/**
* 验证 URL 是否安全
* @param url 需要验证的 URL
* @returns 是否为安全 URL
*/
export function isValidURL(url: string): boolean {
if (!url || typeof url !== 'string') {
return false;
}
const trimmed = url.trim();
if (!trimmed) {
return false;
}
// 允许以 / 开头的站内相对路径(如本地存储 /files/images/xxx.jpg)
if (trimmed.startsWith('/') && !trimmed.startsWith('//')) {
return true;
}
// 允许 provider:// 形式,由前端后续鉴权拉取并替换为 blob URL
if (isProviderFileURL(trimmed)) {
return true;
}
try {
const urlObj = new URL(trimmed);
return ['http:', 'https:'].includes(urlObj.protocol);
} catch {
return false;
}
}
/**
* 安全地处理 Markdown 内容
* @param markdown Markdown 文本
* @returns 安全的 HTML 字符串
*/
export function safeMarkdownToHTML(markdown: string): string {
if (!markdown || typeof markdown !== 'string') {
return '';
}
// 首先转义可能的 HTML 标签
const escapedMarkdown = markdown
.replace(/