vite-plugin-csp-guard/dist/sri/HtmlProcessor.d.ts

A Vite plugin that lets SPA applications generate a Content Security Policy (CSP).

import type { OutputBundle } from "rollup";
import type { HashAlgorithms } from "../types";
/**
 * Comprehensive configuration interface for HTML processor operations.
 * Centralizes all HTML processing configuration to reduce parameter passing
 * and provide a single source of truth for processing behavior.
 *
 * This configuration drives both SRI injection and dynamic chunk preloading.
 */
export interface HtmlProcessorConfig {
    /** Hash algorithm for integrity computation */
    algorithm: HashAlgorithms;
    /** CORS setting for integrity-enabled resources */
    crossorigin?: "anonymous" | "use-credentials";
    /** Base path for generating absolute URLs */
    base: string;
    /** Whether to inject modulepreload links for dynamic chunks */
    preloadDynamicChunks: boolean;
    /** Skip patterns for excluding resources from SRI processing */
    skipResources: string[];
    /** Debug logging flag */
    debug: boolean;
}
/**
 * Comprehensive HTML processor for SRI injection and preload link generation.
 * Handles HTML parsing, SRI injection, and dynamic chunk preloading with robust error handling.
 *
 * Key Features:
 * - Processes all HTML files in bundle with error boundaries
 * - Adds SRI attributes to existing elements
 * - Injects modulepreload links for dynamic chunks
 * - Handles duplicate link prevention
 * - Comprehensive error handling and logging
 */
export declare class HtmlProcessor {
    private readonly config;
    /**
     * Constructs a new HtmlProcessor with the provided configuration.
     *
     * @param config - Comprehensive configuration for HTML processing behavior
     */
    constructor(config: HtmlProcessorConfig);
    /**
     * Processes all HTML files in the bundle to inject SRI attributes and preload links.
     * Handles individual file failures gracefully while maintaining overall processing flow.
     *
     * Processing Flow:
     * 1. Extract and validate HTML files from bundle
     * 2. Process each HTML file with individual error boundaries
     * 3. Apply SRI attributes to existing elements
     * 4. Add preload links for dynamic chunks (if enabled)
     * 5. Update bundle with processed HTML content
     *
     * @param bundle - Output bundle containing HTML assets
     * @param sriByPathname - Mapping of pathnames to integrity hashes
     * @param dynamicChunkFiles - Set of dynamic chunk file names for preloading
     * @returns Promise<void> - Completes when all HTML files are processed
     */
    processHtmlFiles(bundle: OutputBundle, sriByPathname: Record<string, string>, dynamicChunkFiles: Set<string>): Promise<void>;
    /**
     * Extracts HTML assets from bundle with proper type validation.
     * Filters bundle entries to find only HTML assets with proper type checking.
     *
     * @param bundle - Output bundle to search
     * @returns Array<[string, OutputAsset]> - Array of HTML file name and asset pairs
     */
    private extractHtmlFiles;
    /**
     * Processes a single HTML file with comprehensive SRI injection and preload generation.
     *
     * Processing Steps:
     * 1. Extract and validate HTML content from asset
     * 2. Add SRI attributes to existing elements
     * 3. Add preload links for dynamic chunks (if enabled)
     * 4. Update asset source with processed HTML
     *
     * @param fileName - Name of the HTML file
     * @param asset - HTML asset from bundle
     * @param bundle - Complete bundle for resource resolution
     * @param sriByPathname - Integrity mappings
     * @param dynamicChunkFiles - Dynamic chunks for preloading
     * @returns Promise<void> - Completes when file is processed
     */
    private processSingleHtmlFile;
    /**
     * Extracts HTML content from asset with proper validation and type handling.
     * Handles both string and buffer sources with appropriate error reporting.
     *
     * @param asset - HTML asset to extract content from
     * @param fileName - File name for error reporting
     * @returns string | null - HTML content or null if invalid
     */
    private extractHtmlContent;
    /**
     * Adds SRI attributes to existing HTML elements using cheerio.
     * Processes script and link elements to add integrity and crossorigin attributes.
     *
     * @param htmlContent - Original HTML content
     * @param sriByPathname - Pre-computed integrity mappings
     * @returns Promise<string> - HTML with SRI attributes added
     */
    private addSriToHtmlContent;
    /**
     * Adds modulepreload link elements for dynamic chunks.
     * Injects link tags in the head section with integrity attributes.
     *
     * @param htmlContent - HTML content to modify
     * @param dynamicChunkFiles - Set of dynamic chunk file names
     * @param sriByPathname - Pre-computed integrity mappings
     * @returns Promise<string> - HTML with preload links added
     */
    private addDynamicChunkPreloads;
    /**
     * Checks if an element matches skip patterns and should be excluded from SRI processing.
     *
     * @param element - Cheerio element to check
     * @returns boolean - true if element should be skipped
     */
    private shouldSkipElement;
    /**
     * Checks if a link element is eligible for SRI based on rel and as attributes.
     *
     * @param element - Cheerio element to check
     * @returns boolean - true if element is eligible
     */
    private isLinkEligibleForSri;
    /**
     * Matches a pattern against a string (supports glob patterns with *).
     *
     * @param pattern - Pattern to match
     * @param str - String to test
     * @returns boolean - true if pattern matches
     */
    private matchesPattern;
    /**
     * Gets integrity value for a URL from the pre-computed mappings.
     *
     * @param url - URL to look up
     * @param sriByPathname - Pre-computed integrity mappings
     * @returns string | undefined - Integrity value or undefined
     */
    private getIntegrityForUrl;
}
//# sourceMappingURL=HtmlProcessor.d.ts.map