BlazorFrame 2.0.0

BlazorFrame

A Blazor component that provides an enhanced iframe wrapper with automatic resizing, cross-frame communication, and seamless JavaScript interop with built-in security features.

Features

• Security-First Design - Origin validation, message filtering, and comprehensive security options
• Content Security Policy Integration - Built-in CSP helpers for iframe security
• Responsive - Dynamically resizes iframe based on content height (can be enabled/disabled)
• Cross-Frame Messaging - Built-in support for postMessage communication with validation
• Event Callbacks - OnLoad, OnMessage, and security event handling
• Flexible Styling - Customizable width, height, and additional attributes
• JavaScript Interop - Seamless integration with Blazor's JS interop
• Scrolling Control - Enable or disable scrolling within the iframe wrapper
• Disposal Pattern - Proper cleanup of resources and event listeners

Installation

Install the package via NuGet Package Manager:

dotnet add package BlazorFrame

Or via Package Manager Console:

Install-Package BlazorFrame

Quick Start (Secure by Default)

@using BlazorFrame

<BlazorFrame Src="https://example.com" />

The component automatically derives allowed origins from the Src URL for secure messaging.

Usage Examples

Basic Usage with Event Handling

@using BlazorFrame

<BlazorFrame Src="@iframeUrl"
            Width="100%"
            Height="400px"
            EnableAutoResize="true"
            EnableScroll="false"
            OnLoad="HandleIframeLoad"
            OnValidatedMessage="HandleValidatedMessage"
            OnSecurityViolation="HandleSecurityViolation"
            class="my-custom-iframe" />

@code {
    private string iframeUrl = "https://example.com";

    private Task HandleIframeLoad()
    {
        Console.WriteLine("Iframe loaded successfully!");
        return Task.CompletedTask;
    }

    private Task HandleValidatedMessage(IframeMessage message)
    {
        Console.WriteLine($"Secure message from {message.Origin}: {message.Data}");
        return Task.CompletedTask;
    }

    private Task HandleSecurityViolation(IframeMessage violation)
    {
        Console.WriteLine($"Security violation: {violation.ValidationError}");
        return Task.CompletedTask;
    }
}

Advanced Security Configuration

@using BlazorFrame

<BlazorFrame Src="@iframeUrl"
            AllowedOrigins="@allowedOrigins"
            SecurityOptions="@securityOptions"
            OnValidatedMessage="HandleValidatedMessage"
            OnSecurityViolation="HandleSecurityViolation" />

@code {
    private string iframeUrl = "https://widget.example.com";
    
    private List<string> allowedOrigins = new() 
    { 
        "https://widget.example.com", 
        "https://api.example.com" 
    };
    
    private MessageSecurityOptions securityOptions = new()
    {
        EnableStrictValidation = true,
        MaxMessageSize = 32 * 1024, // 32KB
        LogSecurityViolations = true
    };

    private Task HandleValidatedMessage(IframeMessage message)
    {
        // Handle validated, secure messages
        return Task.CompletedTask;
    }

    private Task HandleSecurityViolation(IframeMessage violation)
    {
        // Log, alert, or take corrective action
        Logger.LogWarning("Security violation: {Error}", violation.ValidationError);
        return Task.CompletedTask;
    }
}

Content Security Policy Integration

@using BlazorFrame

<BlazorFrame Src="@iframeUrl"
            CspOptions="@cspOptions"
            OnCspHeaderGenerated="HandleCspGenerated"
            OnValidatedMessage="HandleValidatedMessage" />

@code {
    private string iframeUrl = "https://widget.example.com";
    
    private CspOptions cspOptions = new CspOptions()
        .AllowSelf()
        .AllowFrameSources("https://widget.example.com", "https://trusted-cdn.com")
        .AllowHttpsFrames()
        .WithCustomDirective("img-src", "'self'", "data:", "https:");

    private Task HandleCspGenerated(CspHeader cspHeader)
    {
        // Apply CSP header to your response
        Console.WriteLine($"Generated CSP: {cspHeader.HeaderValue}");
        
        // In a real application, you might apply this to the HTTP response:
        // HttpContext.Response.Headers.Add(cspHeader.HeaderName, cspHeader.HeaderValue);
        
        return Task.CompletedTask;
    }

    private Task HandleValidatedMessage(IframeMessage message)
    {
        // Handle validated messages
        return Task.CompletedTask;
    }
}

Parameters

Security Features

Origin Validation

BlazorFrame automatically validates message origins to prevent unauthorized communication:

• Auto-derived origins: Automatically allows messages from the iframe's source domain
• Explicit allowlist: Override with custom allowed origins for multi-domain scenarios
• Protocol enforcement: Ensures HTTPS origins when possible

Message Validation

All incoming messages are validated before reaching your application:

public class MessageSecurityOptions
{
    /// <summary>List of allowed origins (null = auto-derive from Src)</summary>
    public List<string>? AllowedOrigins { get; set; }
    
    /// <summary>Enable strict JSON format validation</summary>
    public bool EnableStrictValidation { get; set; } = true;
    
    /// <summary>Maximum message size (default: 64KB)</summary>
    public int MaxMessageSize { get; set; } = 64 * 1024;
    
    /// <summary>Log security violations</summary>
    public bool LogSecurityViolations { get; set; } = true;
}

Validated Message Model

public class IframeMessage
{
    public required string Origin { get; init; }        // Verified sender origin
    public required string Data { get; init; }          // Validated JSON string
    public bool IsValid { get; init; }                  // Security validation result
    public string? ValidationError { get; init; }       // Error details (if any)
    public string? MessageType { get; init; }           // Extracted message type
}

Content Security Policy (CSP)

BlazorFrame includes comprehensive CSP support to enhance iframe security:

@using BlazorFrame

// Create CSP options with fluent API
var cspOptions = new CspOptions()
    .AllowSelf()
    .AllowFrameSources("https://trusted-domain.com")
    .AllowHttpsFrames()
    .WithScriptNonce("abc123")
    .ForProduction();

// Get CSP header for your HTTP response
var cspHeader = blazorFrame.GetRecommendedCspHeader();

CSP Configuration Examples

// Development environment (relaxed security)
var devCsp = new CspOptions().ForDevelopment();

// Production environment (strict security)
var prodCsp = new CspOptions()
    .ForProduction()
    .AllowFrameSources("https://trusted-widget.com")
    .WithScriptNonce(nonceValue);

// Custom configuration
var customCsp = new CspOptions()
    .AllowSelf()
    .AllowFrameSources("https://widget.example.com", "https://cdn.example.com")
    .AllowDataUrls()
    .WithCustomDirective("img-src", "'self'", "data:", "https:")
    .AsReportOnly("https://csp-report.example.com/report");

CSP Helper Methods

// Generate CSP meta tag for HTML
var metaTag = cspBuilder.BuildCspMetaTag(cspOptions);

// Generate JavaScript to set CSP dynamically
var jsCode = cspBuilder.BuildCspJavaScript(cspOptions);

// Validate CSP configuration
var validation = cspBuilder.ValidateCspOptions(cspOptions);
foreach (var warning in validation.Warnings)
{
    Console.WriteLine($"CSP Warning: {warning}");
}

Security Event Handling

Monitor and respond to security events:

<BlazorFrame OnSecurityViolation="HandleViolation" />

@code {
    private Task HandleViolation(IframeMessage violation)
    {
        // Log, alert, or take corrective action
        Logger.LogWarning("Security violation: {Error}", violation.ValidationError);
        return Task.CompletedTask;
    }
}

Automatic Resizing

BlazorFrame can automatically adjust the iframe height based on the content inside when EnableAutoResize is set to true (default). The component:

1. Monitors the iframe content document every 500ms
2. Calculates the maximum height from various document properties
3. Updates the iframe height dynamically
4. Handles cross-origin restrictions gracefully
5. Can be disabled by setting EnableAutoResize="false"

Cross-Frame Communication

Sending Messages from Iframe (Secure)

// Inside your iframe content - specify target origin for security
window.parent.postMessage({ 
    type: 'custom', 
    data: 'Hello from iframe!' 
}, 'https://your-parent-domain.com');

Special Resize Messages

// Send resize messages (validated automatically)
window.parent.postMessage({ 
    type: 'resize', 
    height: 800 
}, 'https://your-parent-domain.com');

Receiving Validated Messages

private Task HandleValidatedMessage(IframeMessage message)
{
    // message.Origin - verified sender origin
    // message.Data - validated JSON string
    // message.MessageType - extracted message type (if present)
    // message.IsValid - always true in this callback
    
    return Task.CompletedTask;
}

Styling and CSS

The component includes built-in CSS styling with wrapper classes:

• iframe-wrapper - Applied to all iframe wrappers
• iframe-wrapper scrollable - Applied when EnableScroll="true"

The wrapper provides:

• 100% width by default
• Hidden overflow (unless scrollable)
• Borderless iframe display

Examples

Loading Different Content Types

<BlazorFrame Src="https://docs.microsoft.com" />


<BlazorFrame Src="./local-content.html" />


<BlazorFrame Src="data:text/html,<h1>Hello World!</h1>" />
### Multi-Domain Setup
<BlazorFrame Src="https://widget.example.com"
            AllowedOrigins="@(new List<string> 
            { 
                "https://widget.example.com", 
                "https://api.example.com" 
            })" />

High-Security Configuration with CSP

@using BlazorFrame

<BlazorFrame Src="@secureUrl"
            SecurityOptions="@securityOptions"
            CspOptions="@cspOptions"
            OnSecurityViolation="HandleViolation"
            OnCspHeaderGenerated="HandleCspGenerated" />

@code {
    private string secureUrl = "https://secure-widget.com";
    
    private MessageSecurityOptions securityOptions = new()
    {
        EnableStrictValidation = true,
        MaxMessageSize = 16 * 1024, // 16KB limit
        LogSecurityViolations = true
    };
    
    private CspOptions cspOptions = new CspOptions()
        .ForProduction()
        .AllowFrameSources("https://secure-widget.com")
        .WithScriptNonce("secure-nonce-123")
        .WithCustomDirective("connect-src", "'self'", "https://api.secure-widget.com");
}

Responsive Design

<div class="container-fluid">
    <BlazorFrame Src="@contentUrl"
                Width="100%"
                Height="calc(100vh - 200px)"
                EnableAutoResize="false"
                style="min-height: 400px;" />
</div>

Disabling Auto-Resize for Fixed Height

<BlazorFrame Src="@contentUrl"
            Width="100%"
            Height="500px"
            EnableAutoResize="false"
            EnableScroll="true" />

Custom Styling and Attributes

<BlazorFrame Src="@iframeUrl"
            Width="800px"
            Height="600px"
            EnableAutoResize="false"
            EnableScroll="true"
            class="border rounded shadow"
            style="margin: 20px;"
            sandbox="allow-scripts allow-same-origin" />

Best Practices

1. Always specify target origin when sending messages from iframe content
2. Use OnValidatedMessage for new implementations instead of legacy OnMessage
3. Monitor security violations in production environments
4. Set appropriate MaxMessageSize based on your use case
5. Enable logging for security auditing
6. Use HTTPS for iframe sources when possible
7. Implement proper error handling for security violations

Requirements

• .NET 8.0 or later
• Blazor Server or Blazor WebAssembly

Browser Support

BlazorFrame works in all modern browsers that support:

• ES6 modules
• postMessage API with origin validation
• Blazor JavaScript interop

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check existing issues for solutions
• Suggest new features or improvements