Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

26.1 KB
Raw Blame
/**
 * 安全工具类 - 防止 XSS 攻击
 */

import DOMPurify from 'dompurify';
import { applyProtectedFile, responseFileName, RESOURCE_PREVIEW_EVENT, type LoadedProtectedFile } from './protectedResource.ts';
import type { Config, NodeHook } from 'dompurify';
import {
  domPurifySecurityHooks,
  domPurifySecurityOptions,
  markdownDomPurifyConfig,
  markdownDomPurifySecurityHooks,
} from './markdownDomPurify.ts';
import {
  buildProtectedFileRequest,
  isProtectedFileProxyPath,
  isProviderFileURL,
  PROVIDER_SCHEME_PATTERN,
  resolveProtectedFileAccess,
  type ProtectedFileAccessContext,
} from './protectedFileAccess.ts';

const PROVIDER_IMAGE_PLACEHOLDER = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///ywAAAAAAQABAAACAUwAOw==';
const PROVIDER_IMG_SRC_RE = new RegExp(
  `<img\\b([^>]*?)\\ssrc=(["'])(${PROVIDER_SCHEME_PATTERN}):(?:\\/\\/|&#x2f;&#x2f;|&#47;&#47;)([^"']+)\\2([^>]*)>`,
  'gi',
);
const STORAGE_BACKEND_IMG_SRC_RE = new RegExp(
  `<img\\b([^>]*?)\\ssrc=(["'])storage:\\/\\/([0-9A-Za-z_-]+)\\/(${PROVIDER_SCHEME_PATTERN}):(?:\\/\\/|&#x2f;&#x2f;|&#47;&#47;)([^"']+)\\2([^>]*)>`,
  'gi',
);

type SecurityHooks = {
  beforeSanitizeElements: NodeHook;
  afterSanitizeElements: NodeHook;
};

const DOCUMENT_PREVIEW_IMAGE_ATTRS = ['loading', 'decoding', 'fetchpriority'] as const;

function sanitizeWithSecurityHooks(
  html: string,
  config: Config,
  hooks: SecurityHooks,
): string {
  DOMPurify.addHook('beforeSanitizeElements', hooks.beforeSanitizeElements);
  DOMPurify.addHook('afterSanitizeElements', hooks.afterSanitizeElements);
  try {
    return DOMPurify.sanitize(html, config);
  } finally {
    DOMPurify.removeHook('afterSanitizeElements', hooks.afterSanitizeElements);
    DOMPurify.removeHook('beforeSanitizeElements', hooks.beforeSanitizeElements);
  }
}

// 配置 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',
    'data-artifact-index', 'data-protected-resource', 'download',
    '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 },
  // USE_PROFILES 会整体替换 ALLOWED_ATTR,而 html profile 默认不含 target,
  // 导致 afterSanitizeElements hook 加上的 target="_blank" 在随后的
  // _sanitizeAttributes 中被剥离。用 ADD_ATTR 在 profile 之上追加该属性。
  ADD_ATTR: ['target'],
  ...domPurifySecurityOptions,
};

/**
 * 安全地清理 HTML 内容
 * @param html 需要清理的 HTML 字符串
 * @returns 清理后的安全 HTML 字符串
 */
export function sanitizeHTML(html: string): string {
  if (!html || typeof html !== 'string') {
    return '';
  }
  
  try {
    const preparedHTML = protectProviderImageSrcInHTML(html);
    return sanitizeWithSecurityHooks(
      preparedHTML,
      DOMPurifyConfig as unknown as Config,
      domPurifySecurityHooks,
    );
  } catch (error) {
    console.error('HTML sanitization failed:', error);
    // 如果清理失败,返回转义的纯文本
    return escapeHTML(html);
  }
}

export function applyDocumentPreviewImageAttributes(currentNode: Node): void {
  if (!('tagName' in currentNode) || !('setAttribute' in currentNode)) return;
  const element = currentNode as Element;
  if (element.tagName !== 'IMG') return;
  element.setAttribute('loading', 'lazy');
  element.setAttribute('decoding', 'async');
  element.setAttribute('fetchpriority', 'low');
}

export const documentPreviewDomPurifyConfig = {
  ...DOMPurifyConfig,
  // 在基础 ADD_ATTR 上追加,而不是覆盖,否则链接的 target="_blank" 又会被剥掉。
  ADD_ATTR: [...DOMPurifyConfig.ADD_ATTR, ...DOCUMENT_PREVIEW_IMAGE_ATTRS],
};

const documentPreviewSecurityHooks: SecurityHooks = {
  beforeSanitizeElements: domPurifySecurityHooks.beforeSanitizeElements,
  afterSanitizeElements: (currentNode) => {
    domPurifySecurityHooks.afterSanitizeElements(currentNode);
    applyDocumentPreviewImageAttributes(currentNode);
  },
};

/** Sanitize DocumentPreview Markdown and enforce a single image loading policy. */
export function sanitizeDocumentPreviewHTML(html: string): string {
  if (!html || typeof html !== 'string') {
    return '';
  }

  try {
    const preparedHTML = protectProviderImageSrcInHTML(html);
    return sanitizeWithSecurityHooks(
      preparedHTML,
      documentPreviewDomPurifyConfig as unknown as Config,
      documentPreviewSecurityHooks,
    );
  } catch (error) {
    console.error('Document preview 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 sanitizeWithSecurityHooks(
      preparedHTML,
      markdownDomPurifyConfig as unknown as Config,
      markdownDomPurifySecurityHooks,
    );
  } catch (error) {
    console.error('Markdown HTML sanitization failed:', error);
    return escapeHTML(html);
  }
}

function isRasterProtectedImage(file: LoadedProtectedFile): boolean {
  return file.blob.type.startsWith('image/') && !file.blob.type.includes('svg');
}

function imageAltFromTag(before: string, after: string): string {
  const match = `${before} ${after}`.match(/\salt=(["'])(.*?)\1/i);
  return match?.[2] ?? '';
}

function escapeAttr(value: string): string {
  return value
    .replace(/&/g, '&amp;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#x27;')
    .replace(/</g, '&lt;');
}

function buildProtectedFileCardTag(file: LoadedProtectedFile, source: string, alt: string): string {
  const name = file.fileName || alt || 'download';
  const label = alt || name;
  return `<a href="${escapeAttr(file.blobURL)}" download="${escapeAttr(name)}" class="protected-resource-card" data-protected-resource="${escapeAttr(source)}" title="${escapeAttr(name)}">${escapeHTML(label)}</a>`;
}

function buildProtectedImageTag(
  before: string,
  quote: string,
  protectedSrc: string,
  after: string,
): string {
  // Reuse the already-hydrated file if we have one, so repeated re-renders
  // (typewriter streaming) keep the same stable image or download card
  // instead of flashing back to the placeholder every frame.
  const cached = protectedFileBySource.get(protectedSrc);
  if (cached) {
    if (isRasterProtectedImage(cached)) {
      return `<img${before} src=${quote}${cached.blobURL}${quote} data-protected-src=${quote}${protectedSrc}${quote}${after}>`;
    }
    return buildProtectedFileCardTag(cached, protectedSrc, imageAltFromTag(before, after));
  }
  // 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 `<img${before} src=${quote}${PROVIDER_IMAGE_PLACEHOLDER}${quote} data-protected-src=${quote}${protectedSrc}${quote} data-img-loading=${quote}1${quote}${after}>`;
}

export function protectProviderImageSrcInHTML(html: string): string {
  if (!html) return html;
  const withProviderImages = html.replace(
    PROVIDER_IMG_SRC_RE,
    (_m, before, quote, provider, restPathRaw, after) => {
      const restPath = decodeProviderURL(restPathRaw);
      return buildProtectedImageTag(before, quote, `${provider}://${restPath}`, after);
    },
  );
  return withProviderImages.replace(
    STORAGE_BACKEND_IMG_SRC_RE,
    (_m, before, quote, backendID, provider, restPathRaw, after) => {
      const restPath = decodeProviderURL(restPathRaw);
      return buildProtectedImageTag(
        before,
        quote,
        `storage://${backendID}/${provider}://${restPath}`,
        after,
      );
    },
  );
}

function decodeProviderURL(raw: string): string {
  return raw
    .trim()
    .replace(/&#x2f;/gi, '/')
    .replace(/&#47;/g, '/')
    .replace(/&amp;/g, '&')
    .replace(/&quot;/g, '"');
}

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);
    if (!isProtectedFileProxyPath(url.pathname)) {
      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 } = {
    '&': '&amp;',
    '<': '&lt;',
    '>': '&gt;',
    '"': '&quot;',
    "'": '&#x27;',
    '/': '&#x2F;',
    '`': '&#x60;',
    '=': '&#x3D;'
  };
  
  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(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
    .replace(/<iframe\b[^<]*(?:(?!<\/iframe>)<[^<]*)*<\/iframe>/gi, '')
    .replace(/<object\b[^<]*(?:(?!<\/object>)<[^<]*)*<\/object>/gi, '')
    .replace(/<embed\b[^<]*(?:(?!<\/embed>)<[^<]*)*<\/embed>/gi, '');
  
  return escapedMarkdown;
}

/**
 * 清理用户输入
 * @param input 用户输入
 * @returns 清理后的安全输入
 */
export function sanitizeUserInput(input: string): string {
  if (!input || typeof input !== 'string') {
    return '';
  }
  
  // 移除控制字符
  let cleaned = input.replace(/[\x00-\x1F\x7F-\x9F]/g, '');
  
  // 限制长度
  if (cleaned.length > 10000) {
    cleaned = cleaned.substring(0, 10000);
  }
  
  return cleaned.trim();
}

/**
 * 验证图片 URL 是否安全
 * @param url 图片 URL
 * @returns 是否为安全的图片 URL
 */
export function isValidImageURL(url: string): boolean {
  if (!isValidURL(url)) {
    return false;
  }
  
  return true;
}

/**
 * 创建安全的图片元素
 * @param src 图片源
 * @param alt 替代文本
 * @param title 标题
 * @returns 安全的图片 HTML
 */
export function createSafeImage(src: string, alt: string = '', title: string = ''): string {
  if (!isValidImageURL(src)) {
    return '';
  }
  
  // src is validated by isValidImageURL; keep URL structure unchanged.
  // Only escape quotes to avoid breaking attributes.
  const safeSrc = src.replace(/"/g, '&quot;');
  const safeAlt = escapeHTML(alt);
  const safeTitle = escapeHTML(title);
  
  return `<img src="${safeSrc}" alt="${safeAlt}" title="${safeTitle}" class="markdown-image" style="max-width: 100%; height: auto;">`;
}

type ProtectedFileLoadResult =
  | ({ status: 'loaded' } & LoadedProtectedFile)
  | { status: 'missing' }
  | { status: 'failed' };

type HiddenProtectedImage = {
  display: string;
  parent: HTMLElement | null;
  parentDisplay: string;
};

type ProtectedFileCacheState = {
  blobByRequest: Map<string, LoadedProtectedFile>;
  fileBySource: Map<string, LoadedProtectedFile>;
  missingRequests: Set<string>;
  failures: Map<string, number>;
  inflight: Map<string, Promise<ProtectedFileLoadResult>>;
  retryGeneration: number;
  imageRequests: WeakMap<HTMLImageElement, string>;
  hiddenImages: WeakMap<HTMLImageElement, HiddenProtectedImage>;
};

// Keep object URLs alive across Vite hot updates. A hot update replaces this
// module but not the page document, so module-local Maps would forget valid
// blob URLs and make already-loaded images fall back to the 1x1 placeholder.
const protectedFileCacheState = (() => {
  const fresh = (): ProtectedFileCacheState => ({
    blobByRequest: new Map(),
    fileBySource: new Map(),
    missingRequests: new Set(),
    failures: new Map(),
    inflight: new Map(),
    retryGeneration: 0,
    imageRequests: new WeakMap(),
    hiddenImages: new WeakMap(),
  });
  if (typeof window === 'undefined') return fresh();
  const scope = window as typeof window & {
    __weknoraProtectedFileCacheV4__?: ProtectedFileCacheState;
  };
  scope.__weknoraProtectedFileCacheV4__ ||= fresh();
  return scope.__weknoraProtectedFileCacheV4__;
})();

const protectedFileBlobCache = protectedFileCacheState.blobByRequest;
// File keyed by the protected source URL (e.g. `resource://...`). Once an
// image or download card has been hydrated, re-renders of the same markdown
// can emit the blob src / card HTML directly instead of the placeholder.
const protectedFileBySource = protectedFileCacheState.fileBySource;
// A 404 may mean a temporary message ID was not found, not that the resource
// is missing in every message/workspace. Cache it only under that request.
const protectedFileMissingRequests = protectedFileCacheState.missingRequests;
// Throttle retries of failed file fetches. During streaming the same markdown
// is re-rendered on every chunk, producing brand-new <img> elements (so the
// per-element `authHydrated` flag is reset each time). Without throttling a
// not-yet-generated file (404) would be re-requested on every chunk. We record
// the last failure time per URL and skip re-fetching within a cooldown window,
// while still allowing a later attempt once the file becomes available.
const protectedFileFailureCache = protectedFileCacheState.failures;
const protectedFileInflight = protectedFileCacheState.inflight;
const PROTECTED_FILE_RETRY_COOLDOWN_MS = 5000;
const protectedImageRequests = protectedFileCacheState.imageRequests;
const hiddenProtectedImages = protectedFileCacheState.hiddenImages;

/**
 * 将 Markdown 里通过 /files 代理的图片,改为用带鉴权 Header 的 fetch 拉取后再显示。
 * 用于避免在 URL 中暴露 token。
 */
/**
 * 清除失败重试冷却记录。在流式结束等场景调用,让此前因文件尚未生成而 404
 * 的图片可以立即重新尝试加载,而无需等待冷却窗口结束。
 */
export function clearProtectedFileFailureCache(): void {
  // An earlier request can still be in flight when completion arrives. Its
  // failure must get one fresh attempt against the newly persisted message.
  protectedFileCacheState.retryGeneration++;
  protectedFileFailureCache.clear();
  protectedFileMissingRequests.clear();
}

function protectedImageSource(img: HTMLImageElement): string {
  return normalizeProtectedImageElement(img)
    || (img.getAttribute('data-protected-src') || '').trim()
    || (img.getAttribute('src') || '').trim();
}

function forEachProtectedImageWithSource(
  root: ParentNode,
  sourceURL: string,
  requestKey: string,
  callback: (img: HTMLImageElement) => void,
): void {
  root.querySelectorAll<HTMLImageElement>('img[data-protected-src]').forEach((candidate) => {
    if (protectedImageRequests.get(candidate) === requestKey && protectedImageSource(candidate) === sourceURL) callback(candidate);
  });
}

function hideMissingProtectedImages(root: ParentNode, sourceURL: string, requestKey: string): void {
  forEachProtectedImageWithSource(root, sourceURL, requestKey, (img) => {
    // Keep the node addressable for completion/scope retries. v-stable-html
    // skips unchanged HTML, so removing it would make a settled 404 permanent
    // even after failure state is cleared and the resource becomes readable.
    if (!hiddenProtectedImages.has(img)) {
      const parent = img.parentElement;
      const standalone = parent?.tagName === 'P' && !parent.textContent?.trim() && parent.children.length === 1
        ? parent : null;
      hiddenProtectedImages.set(img, {
        display: img.style.display, parent: standalone, parentDisplay: standalone?.style.display || '',
      });
    }
    img.style.display = 'none';
    img.setAttribute('data-protected-hidden', '1');
    const parent = hiddenProtectedImages.get(img)?.parent;
    if (parent) {
      parent.style.display = 'none';
      parent.setAttribute('data-protected-hidden', '1');
    }
    img.dataset.authHydrated = '0';
  });
}

function applyHydratedProtectedImage(root: ParentNode, sourceURL: string, file: LoadedProtectedFile, requestKey: string): void {
  forEachProtectedImageWithSource(root, sourceURL, requestKey, (img) => {
    const hidden = hiddenProtectedImages.get(img);
    if (hidden) {
      img.style.display = hidden.display;
      img.removeAttribute('data-protected-hidden');
      if (hidden.parent) {
        hidden.parent.style.display = hidden.parentDisplay;
        hidden.parent.removeAttribute('data-protected-hidden');
      }
      hiddenProtectedImages.delete(img);
    }
    if (!isRasterProtectedImage(file)) {
      applyProtectedFile(img, file, sourceURL);
      return;
    }
    img.src = file.blobURL;
    img.dataset.authHydrated = '1';
    img.removeAttribute('data-img-loading');
  });
}

function ensureProtectedResourceCardClicks(): void {
  if (typeof window === 'undefined') return;
  const scope = window as typeof window & { __weknoraProtectedCardClicks__?: boolean };
  if (scope.__weknoraProtectedCardClicks__) return;
  scope.__weknoraProtectedCardClicks__ = true;
  window.addEventListener('click', (event) => {
    const target = event.target as Element | null;
    const link = target?.closest?.('a.protected-resource-card');
    if (!(link instanceof HTMLAnchorElement)) return;
    if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return;
    const source = link.dataset.protectedResource || '';
    const file = protectedFileBySource.get(source);
    if (!file) return;
    const preview = new CustomEvent(RESOURCE_PREVIEW_EVENT, {
      detail: file,
      cancelable: true,
    });
    if (!window.dispatchEvent(preview)) event.preventDefault();
    event.stopPropagation();
  }, true);
}

/**
 * 将内容里的受保护图片(resource:// 等)通过对应的文件代理带鉴权拉取,
 * 再以 blob URL 替换显示。
 *
 * 走哪条代理由 {@link resolveProtectedFileAccess} 决定:应用入口注册的默认
 * 上下文(如嵌入应用的 Embed 平面)优先,组件只在同一鉴权平面内用
 * `access` 细化作用域(如知识库)。
 */
export async function hydrateProtectedFileImages(
  root: ParentNode | null | undefined,
  access?: ProtectedFileAccessContext,
): Promise<void> {
  if (!root || typeof window === 'undefined') {
    return;
  }

  ensureProtectedResourceCardClicks();

  const images = root.querySelectorAll<HTMLImageElement>(
    'img[data-protected-src], img[src^="resource://"], img[src^="storage://"], img[src^="local://"], img[src^="minio://"], img[src^="cos://"], img[src^="tos://"], img[src^="s3://"], img[src^="oss://"], img[src^="ks3://"], img[src^="obs://"]',
  );
  if (!images.length) {
    return;
  }

  const resolvedAccess = resolveProtectedFileAccess(access);

  await Promise.all(Array.from(images).map(async (img) => {
    const normalizedSourceURL = normalizeProtectedImageElement(img);
    const protectedSrc = (img.getAttribute('data-protected-src') || '').trim();
    const src = (img.getAttribute('src') || '').trim();
    const sourceURL = normalizedSourceURL || protectedSrc || src;
    if (!sourceURL) {
      return;
    }
    // A null request means this source cannot be fetched under the current
    // access context (not a storage path, or the embed token has not arrived
    // yet). Leave the placeholder so a later pass can retry.
    const request = buildProtectedFileRequest(sourceURL, resolvedAccess);
    if (!request) {
      img.dataset.authHydrated = '0';
      return;
    }
    const { url: requestURL, headers } = request;
    const requestKey = JSON.stringify([requestURL, headers]);
    if (img.dataset.authHydrated === '1' && src.startsWith('blob:') && protectedImageRequests.get(img) === requestKey) {
      return;
    }
    protectedImageRequests.set(img, requestKey);
    if (protectedFileMissingRequests.has(requestKey)) {
      hideMissingProtectedImages(root, sourceURL, requestKey);
      return;
    }
    img.dataset.authHydrated = '1';

    const cachedBlobURL = protectedFileBlobCache.get(requestKey);
    if (cachedBlobURL) {
      applyHydratedProtectedImage(root, sourceURL, cachedBlobURL, requestKey);
      return;
    }

    const lastFailure = protectedFileFailureCache.get(requestKey);
    if (lastFailure !== undefined && Date.now() - lastFailure < PROTECTED_FILE_RETRY_COOLDOWN_MS) {
      img.dataset.authHydrated = '0';
      return;
    }

    // Every component that references the same image awaits the shared task.
    // The previous Set-based de-dupe made later components return immediately;
    // only the component that started the fetch was updated, leaving all other
    // occurrences stuck on the transparent placeholder forever.
    let loadTask = protectedFileInflight.get(requestKey);
    if (!loadTask) {
      loadTask = (async (): Promise<ProtectedFileLoadResult> => {
        for (let attempt = 0; ; attempt++) {
          const generation = protectedFileCacheState.retryGeneration;
          try {
            const resp = await fetch(requestURL, {
              method: 'GET',
              headers,
              credentials: 'include',
            });
            if (!resp.ok) {
              if (attempt === 0 && generation !== protectedFileCacheState.retryGeneration) continue;
              if (resp.status === 404) {
                protectedFileFailureCache.set(requestKey, Date.now());
                return { status: 'missing' };
              }
              throw new Error(`HTTP ${resp.status}`);
            }
            const blob = await resp.blob();
            const blobURL = URL.createObjectURL(blob);
            const file = { blobURL, blob, fileName: responseFileName(resp.headers.get("Content-Disposition"), sourceURL) };
            protectedFileBlobCache.set(requestKey, file);
            protectedFileFailureCache.delete(requestKey);
            return { status: 'loaded', ...file };
          } catch (error) {
            if (attempt === 0 && generation !== protectedFileCacheState.retryGeneration) continue;
            console.warn('[security] hydrateProtectedFileImages failed:', error);
            protectedFileFailureCache.set(requestKey, Date.now());
            return { status: 'failed' };
          }
        }
      })().finally(() => protectedFileInflight.delete(requestKey));
      protectedFileInflight.set(requestKey, loadTask);
    }

    const result = await loadTask;
    // A late response for an old message ID must not remove or overwrite an
    // image that has since been reauthorized under its persisted message ID.
    if (protectedImageRequests.get(img) !== requestKey) return;
    if (result.status === 'loaded') {
      protectedFileBySource.set(sourceURL, result);
      protectedFileMissingRequests.delete(requestKey);
      applyHydratedProtectedImage(root, sourceURL, result, requestKey);
      return;
    }
    if (result.status === 'missing') {
      protectedFileMissingRequests.add(requestKey);
      hideMissingProtectedImages(root, sourceURL, requestKey);
      return;
    }
    if (result.status === 'failed') {
      img.dataset.authHydrated = '0';
    }
  }));
}