Securing and Auditing Custom Full Site Editing (FSE) Block Themes and theme.json in Legacy Core PHP Implementations

Understanding the Threat Landscape for Custom FSE Block Themes

Custom Full Site Editing (FSE) block themes, while offering immense flexibility, introduce a new attack surface, particularly when integrated with legacy core PHP implementations. The primary concern lies in the potential for malicious code injection through user-editable theme files, template parts, and especially the `theme.json` configuration. Unlike traditional PHP-based themes where server-side validation and sanitization are more established, block themes rely heavily on JSON and JavaScript for their structure and presentation. This shift necessitates a rigorous approach to security auditing and the implementation of robust defenses, even within the context of existing PHP workflows.

Auditing `theme.json` for Vulnerabilities

The `theme.json` file is the central configuration hub for block themes. It defines styles, layout settings, and custom properties. A critical vulnerability arises if user-supplied data is directly reflected or executed within this file without proper sanitization. While WordPress core performs some validation, custom implementations or poorly secured plugins can bypass these checks.

Consider a scenario where a plugin dynamically generates or modifies `theme.json` based on user input. Without strict validation, an attacker could inject malicious CSS or even JavaScript snippets disguised as valid JSON values. For instance, a custom color picker that accepts arbitrary strings could be exploited:

Example: Malicious CSS Injection via `theme.json`

Imagine a `theme.json` snippet like this, potentially modified by a vulnerable plugin:

{
    "version": 2,
    "settings": {
        "color": {
            "custom": true,
            "palette": [
                {
                    "name": "Primary",
                    "slug": "primary",
                    "color": "#0073aa"
                },
                {
                    "name": "Secondary",
                    "slug": "secondary",
                    "color": "/*<script>alert('XSS')</script>*/ #ff0000"
                }
            ]
        }
    }
}

While WordPress core’s JSON parser will likely reject invalid JSON, attackers can craft payloads that are syntactically valid but semantically malicious. In this example, the injected comment might be interpreted by a browser’s CSS parser in certain contexts, or if the `theme.json` is processed by a less strict PHP parser before being outputted, it could lead to cross-site scripting (XSS).

PHP-based Validation for `theme.json`

To mitigate such risks in legacy PHP environments, it’s crucial to implement server-side validation before `theme.json` is parsed or applied. This involves intercepting the theme’s configuration and sanitizing any dynamic values.

<?php
/**
 * Sanitize and validate theme.json data.
 *
 * @param array $data The raw theme.json data.
 * @return array The sanitized theme.json data.
 */
function my_theme_sanitize_theme_json( array $data ): array {
    // Example: Sanitize custom colors
    if ( isset( $data['settings']['color']['palette'] ) && is_array( $data['settings']['color']['palette'] ) ) {
        foreach ( $data['settings']['color']['palette'] as $key => $color_entry ) {
            if ( isset( $color_entry['color'] ) ) {
                // Ensure color is a valid hex code or a predefined CSS color name.
                // Disallow script tags or other malicious HTML/CSS.
                $sanitized_color = sanitize_hex_color( $color_entry['color'] );
                if ( ! $sanitized_color ) {
                    // If not a hex color, check if it's a safe CSS color name or a valid CSS value.
                    // For simplicity, we'll only allow hex here, but a more robust solution
                    // would involve a whitelist of CSS color names or a more complex regex.
                    $data['settings']['color']['palette'][$key]['color'] = '#000000'; // Fallback to black
                } else {
                    $data['settings']['color']['palette'][$key]['color'] = $sanitized_color;
                }
            }
        }
    }

    // Add more sanitization rules for other settings (e.g., typography, spacing, layout)
    // Use WordPress sanitization functions like sanitize_text_field, esc_url, etc.
    // For complex structures, consider recursive sanitization.

    return $data;
}

// Hook into the theme_mod_theme_json filter if theme.json is being loaded via theme mods,
// or implement custom logic to intercept theme.json loading if it's dynamically generated.
// This example assumes a hypothetical scenario where theme.json is being processed.
// In a real-world scenario, you'd hook into the specific process that loads/applies theme.json.

// Example of how you might apply this if you were manually loading and processing theme.json:
/*
$raw_theme_json = file_get_contents( get_template_directory() . '/theme.json' );
$theme_json_data = json_decode( $raw_theme_json, true );

if ( json_last_error() === JSON_ERROR_NONE ) {
    $sanitized_theme_json = my_theme_sanitize_theme_json( $theme_json_data );
    // Now use $sanitized_theme_json for rendering or further processing.
}
*/
?>

The `sanitize_hex_color()` function is a good starting point, but a comprehensive solution requires sanitizing all user-editable fields within `theme.json`, including typography settings, spacing scales, and layout parameters. For custom properties, ensure they are validated against expected formats (e.g., valid CSS units, color values).

Securing Custom Block Templates and Template Parts

Custom block templates and template parts, often stored as `.html` files within the `templates` and `parts` directories of a theme, can also be targets for injection. While these files are primarily declarative (using block markup), they can contain attributes that might be vulnerable if processed insecurely by PHP functions.

Example: Malicious Attribute Injection

Consider a custom template part that includes an attribute intended to be dynamic, but is not properly escaped:

<!-- wp:group -->
<div class="wp-block-group">
    <!-- wp:paragraph -->
    <p>Dynamic Content Here</p>
    <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->
<!-- wp:html -->
<div data-custom-attribute="<script>console.log('malicious')</script>">Some HTML</div>
<!-- /wp:html -->

If a PHP function later retrieves and outputs this `data-custom-attribute` without proper escaping (e.g., using `echo $attribute_value;` instead of `echo esc_attr( $attribute_value );`), it can lead to XSS.

PHP-based Sanitization of Block Markup

When dealing with dynamically generated or user-influenced block markup within PHP, always use WordPress’s escaping functions. The `wp_kses_post()` function is powerful for sanitizing HTML content, but for attribute values, `esc_attr()` is the correct choice.

<?php
// Assume $dynamic_attribute_value is fetched from a user input or external source.
$dynamic_attribute_value = $_POST['user_input_attribute'] ?? '<script>console.log("default");</script>'; // Example of potentially unsafe data

// When outputting this value as an HTML attribute:
echo '<div data-custom-attribute="' . esc_attr( $dynamic_attribute_value ) . '">';
echo 'Some HTML';
echo '</div>';

// If you are processing raw HTML content that might contain blocks:
$raw_html_content = '<div data-malicious="<script>alert(1)</script>">Content</div><p>Another paragraph</p>';
// Use wp_kses_post for sanitizing HTML content that will be displayed as HTML.
// This will strip out disallowed tags and attributes, including script tags.
$sanitized_html = wp_kses_post( $raw_html_content );
echo $sanitized_html; // Output will be <div data-malicious="">Content</div><p>Another paragraph</p> (script tag removed)
?>

It’s crucial to understand the context in which data is being outputted. `esc_attr()` is for attribute values, `esc_html()` for general HTML content, and `esc_url()` for URLs.

Leveraging WordPress Hooks for Security Auditing

WordPress’s extensive hook system provides opportunities to intercept and audit theme operations. By hooking into relevant actions and filters, you can log potentially malicious activities or enforce security policies.

Logging `theme.json` Modifications

If your theme or a plugin allows dynamic modification of `theme.json` settings (e.g., via the Customizer or theme options), you can log these changes. This is invaluable for forensic analysis if a security incident occurs.

<?php
/**
 * Log changes to theme.json settings.
 * This hook is hypothetical and depends on how theme.json is modified.
 * If using theme_mod, you can hook into save_post or customize_save_after.
 */
function my_theme_log_theme_json_changes( $value, $name, $old_value ) {
    // Example: Logging changes to a specific setting
    if ( 'theme_json_data' === $name ) { // Assuming 'theme_json_data' is the theme mod name
        // Log the old and new values, user ID, timestamp, etc.
        error_log( sprintf(
            'Theme.json setting "%s" changed from "%s" to "%s" by user ID %d at %s',
            $name,
            print_r( $old_value, true ),
            print_r( $value, true ),
            get_current_user_id(),
            current_time( 'mysql' )
        ) );
    }
    return $value;
}
// This hook is illustrative. The actual hook depends on the mechanism used to save theme.json.
// For theme mods, you might hook into `update_option_theme_mods_your_theme_slug`.
// For custom database storage, hook into your custom save function.
// add_filter( 'pre_update_option', 'my_theme_log_theme_json_changes', 10, 3 );
?>

For more granular control, you might need to implement custom logic within your theme’s options or Customizer settings to log specific fields before they are saved.

Monitoring Block Rendering

While direct monitoring of every block’s rendering in PHP can be performance-intensive, you can selectively audit blocks that are known to be more susceptible to injection or that handle sensitive data. This often involves creating custom blocks with robust server-side validation.

<?php
/**
 * Server-side rendering for a custom block that might handle user input.
 * Example: A custom testimonial block.
 */
function my_custom_testimonial_block_render_callback( $attributes ) {
    $testimonial_text = isset( $attributes['text'] ) ? $attributes['text'] : '';
    $author_name      = isset( $attributes['author'] ) ? $attributes['author'] : '';

    // Sanitize and escape all dynamic content before rendering.
    $sanitized_text = wp_kses_post( $testimonial_text ); // Allow basic HTML in testimonial
    $escaped_author = esc_html( $author_name );       // Plain text for author name

    // Log potentially risky inputs if needed for auditing
    if ( $testimonial_text !== $sanitized_text || $author_name !== $escaped_author ) {
        error_log( sprintf(
            'Potential sanitization needed for testimonial block. Original text: "%s", Original author: "%s"',
            $testimonial_text,
            $author_name
        ) );
    }

    ob_start();
    ?>
    <blockquote class="wp-block-my-custom-testimonial">
        <p><?php echo $sanitized_text; ?></p>
        <cite><?php echo $escaped_author; ?></cite>
    </blockquote>
    <?php
    return ob_get_clean();
}

// Register the block (assuming it's already registered elsewhere)
// register_block_type( 'my-plugin/custom-testimonial', array(
//     'render_callback' => 'my_custom_testimonial_block_render_callback',
// ) );
?>

The key here is to treat all dynamic data as potentially untrusted and apply the appropriate sanitization and escaping functions based on its intended output context.

Advanced Diagnostics: Tracing `theme.json` and Block Data Flow

When debugging security issues or unexpected behavior related to FSE themes, tracing the flow of data from input to output is critical. This often involves understanding how WordPress core processes `theme.json` and how blocks are rendered.

Debugging `theme.json` Loading

WordPress loads `theme.json` through a series of filters. You can use these to inspect the data at various stages.

<?php
/**
 * Debugging hook to inspect theme.json data after core processing.
 */
function my_theme_debug_theme_json_data( $theme_json ) {
    // Log the entire theme.json structure for inspection.
    // Be cautious with logging large amounts of data in production.
    error_log( '--- theme.json data ---' );
    error_log( print_r( $theme_json, true ) );
    error_log( '-----------------------' );

    // You can also add conditional checks here to flag suspicious values.
    if ( isset( $theme_json['settings']['color']['custom'] ) && is_string( $theme_json['settings']['color']['custom'] ) && strpos( $theme_json['settings']['color']['custom'], '<script' ) !== false ) {
        error_log( '!!! Potential XSS detected in theme.json custom color setting !!!' );
    }

    return $theme_json;
}
// Hook into the filter that processes theme.json.
// The exact filter name might vary slightly with WordPress versions, but 'theme.json' is common.
add_filter( 'theme_json', 'my_theme_debug_theme_json_data', 999 ); // High priority to run late
?>

This hook allows you to see the final processed `theme.json` object before it’s used for rendering. You can then inspect its structure and values for any anomalies.

Tracing Block Rendering with `render_block` Filter

The `render_block` filter is invaluable for debugging how individual blocks are rendered on the server-side. It allows you to inspect the block’s attributes and the generated HTML.

<?php
/**
 * Debugging hook to inspect block rendering.
 */
function my_theme_debug_render_block( $block_content, $block ) {
    // Log information about the block being rendered.
    error_log( sprintf(
        'Rendering block: %s. Attributes: %s. Generated HTML (first 100 chars): %s',
        $block['blockName'],
        json_encode( $block['attrs'] ),
        substr( $block_content, 0, 100 )
    ) );

    // Example: Check for suspicious attributes in a specific block type.
    if ( 'core/html' === $block['blockName'] ) {
        if ( isset( $block['attrs']['content'] ) && strpos( $block['attrs']['content'], '<script' ) !== false ) {
            error_log( '!!! Potential XSS detected in core/html block content !!!' );
        }
    }

    return $block_content;
}
add_filter( 'render_block', 'my_theme_debug_render_block', 10, 2 );
?>

By enabling these debugging hooks temporarily in a staging environment, you can gain deep insights into how your custom FSE theme interacts with WordPress core and identify potential security weaknesses.

Conclusion: Proactive Security in FSE Development

Securing custom FSE block themes within legacy PHP implementations requires a shift in mindset. It’s no longer solely about sanitizing PHP output; it’s about understanding the declarative nature of blocks and JSON, and ensuring that any dynamic data integrated into these structures is rigorously validated and escaped. By implementing robust server-side validation, leveraging WordPress’s security functions, and employing advanced diagnostic techniques, you can build and maintain secure, performant FSE themes.