A security-first Blazor iframe component with automatic resizing, cross-frame messaging, and comprehensive Content Security Policy integration.

Features

• Security-First Design - Built-in origin validation, message filtering, and sandbox isolation
• Content Security Policy - Comprehensive CSP integration with fluent configuration API
• Bidirectional Communication - Secure postMessage communication with validation for both directions
• Navigation Tracking - Capture iframe navigation events with URL and query parameters
• Sandbox Support - Multiple security levels from permissive to paranoid isolation
• Environment-Aware - Different configurations for development vs production
• Automatic Resizing - Smart height adjustment based on iframe content

Documentation

Complete Documentation

• Quick Start Guide
• Security Features
  • Configuration Validation
  • Sandbox
• Configuration Guide
  • Display options
  • Advanced options
  • Communication options
  • CSP configuration
  • Security options
• Real-world Examples
• API Reference
• Troubleshooting

🚀 Quick Start

Installation

dotnet add package BlazorFrame

Basic Usage

@using BlazorFrame

<!-- Simple iframe with automatic security -->
<BlazorFrame Src="https://example.com" />

<!-- Production-ready configuration with bidirectional communication and navigation tracking -->
<BlazorFrame @ref="iframeRef"
            Src="https://widget.example.com"
            EnableNavigationTracking="true"
            SecurityOptions="@securityOptions"
            OnValidatedMessage="HandleMessage"
            OnNavigation="HandleNavigation"
            OnSecurityViolation="HandleViolation" />

<button @onclick="SendDataToIframe">Send Data</button>

@code {
    private BlazorFrame? iframeRef;
    
    private readonly MessageSecurityOptions securityOptions = new MessageSecurityOptions()
        .ForProduction()        // Strict security settings
        .WithBasicSandbox()     // Enable iframe sandboxing
        .RequireHttps();        // Enforce HTTPS transport
        
    private Task HandleMessage(IframeMessage message)
    {
        Console.WriteLine($"Received message from {message.Origin}: {message.Data}");
        return Task.CompletedTask;
    }

    private Task HandleNavigation(NavigationEvent navigation)
    {
        Console.WriteLine($"Navigation to: {navigation.Url}");
        Console.WriteLine($"Query params: {string.Join(", ", navigation.QueryParameters)}");
        return Task.CompletedTask;
    }

    private Task HandleViolation(IframeMessage violation)
    {
        Console.WriteLine($"Security violation: {violation.ValidationError}");
        return Task.CompletedTask;
    }
    
    private async Task SendDataToIframe()
    {
        if (iframeRef != null)
        {
            await iframeRef.SendTypedMessageAsync("user-data", new { userId = 123, name = "John" });
        }
    }
}

Configuration Examples

// Development environment - relaxed security
var devOptions = new MessageSecurityOptions()
    .ForDevelopment()
    .WithPermissiveSandbox();

// Production environment - strict security
var prodOptions = new MessageSecurityOptions()
    .ForProduction()
    .WithStrictSandbox()
    .ValidateAndThrow();

// Payment widgets - maximum security
var paymentOptions = new MessageSecurityOptions()
    .ForPaymentWidget();

Content Security Policy

<BlazorFrame Src="https://widget.example.com"
            CspOptions="@cspOptions"
            OnCspHeaderGenerated="HandleCspGenerated" />

@code {
    private readonly CspOptions cspOptions = new CspOptions()
        .ForProduction()
        .AllowFrameSources("https://widget.example.com")
        .WithScriptNonce("secure-nonce-123");
        
    private Task HandleCspGenerated(CspHeader cspHeader)
    {
        // Apply CSP header to HTTP response
        // HttpContext.Response.Headers.Add(cspHeader.HeaderName, cspHeader.HeaderValue);
        return Task.CompletedTask;
    }
}

Security

Content Security Policy

Comprehensive CSP integration for defense-in-depth security:

• Automatic header generation - CSP headers built from iframe requirements
• Environment-aware policies - Different rules for development vs production
• Fluent configuration API - Easy-to-use builder pattern for CSP rules
• Violation monitoring - Real-time CSP violation reporting and analysis
• Nonce and hash support - Modern CSP techniques for script security

Message Validation

All iframe messages are automatically validated for:

• Origin verification - Ensures messages come from allowed domains
• Content validation - JSON structure and size limits
• Security filtering - Blocks malicious patterns and script injection
• Custom validation - Extensible validation pipeline

Sandbox Security Levels

Level	Description	Use Case
None	No restrictions	Trusted content only
Basic	Scripts + same-origin	Most trusted widgets
Permissive	+ forms + popups	Interactive widgets
Strict	Scripts + same-origin only	Display widgets
Paranoid	Scripts only	Untrusted content

Demo

Interactive Demo - Try different security configurations live

Requirements

• .NET 8.0 or later
• Blazor Server or Blazor WebAssembly
• Modern browser with ES6 modules support

Browser Support

• Chrome 91+
• Firefox 90+
• Safari 15+
• Edge 91+

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• NuGet: BlazorFrame Package

License

This project is licensed under the MIT License.

---

Built with ❤️ for the Blazor community