Name: BlazorFrame
Author: BlazorFrame

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 with configurable options
Programmatic Reload - Refresh iframe content without recreating the entire component

Documentation

Complete Documentation

:rocket: 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();

Auto-Resize Configuration

Control how the iframe automatically adjusts its height based on content:

<BlazorFrame Src="https://example.com"
            EnableAutoResize="true"
            ResizeOptions="@resizeOptions" />

@code {
    // Custom resize configuration
    private readonly ResizeOptions resizeOptions = new()
    {
        MinHeight = 200,
        MaxHeight = 2000,
        PollingInterval = 500,
        DebounceMs = 100,
        UseResizeObserver = true
    };
    
    // Or use built-in presets:
    // ResizeOptions.Default      - Balanced defaults
    // ResizeOptions.Performance  - Less frequent updates (better performance)
    // ResizeOptions.Responsive   - More frequent updates (smoother resizing)
}

Property	Default	Description
`MinHeight`	100	Minimum height in pixels
`MaxHeight`	50000	Maximum height in pixels
`PollingInterval`	500	Fallback polling interval (ms) when ResizeObserver unavailable
`DebounceMs`	100	Debounce delay to prevent excessive updates (0 to disable)
`UseResizeObserver`	true	Use ResizeObserver API when available

Programmatic Reload

Refresh iframe content without recreating the entire component - useful for PDFs, dynamic content, or cache-busting:

<BlazorFrame @ref="iframeRef" Src="@pdfUrl" />

<button @onclick="RefreshContent">Refresh</button>
<button @onclick="LoadNewDocument">Load New Document</button>

@code {
    private BlazorFrame? iframeRef;
    private string pdfUrl = "https://example.com/document.pdf";
    
    // Reload the current content
    private async Task RefreshContent()
    {
        if (iframeRef != null)
        {
            await iframeRef.ReloadAsync();
        }
    }
    
    // Load a new URL with cache-busting
    private async Task LoadNewDocument()
    {
        if (iframeRef != null)
        {
            var cacheBustedUrl = $"https://example.com/document.pdf?v={DateTime.UtcNow.Ticks}";
            await iframeRef.ReloadAsync(cacheBustedUrl);
        }
    }
}

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	Permissions	Use Case
None	No restrictions	Trusted content only
Basic	Scripts + same-origin	Most trusted widgets
Permissive	Scripts + same-origin + forms + popups	Interactive widgets
Strict	Scripts only (no same-origin)	Semi-trusted content
Paranoid	Empty sandbox (no permissions)	Untrusted content

API Reference

Component Parameters

Parameter	Type	Default	Description
`Src`	`string`	`""`	The URL to load in the iframe
`Width`	`string`	`"100%"`	Width of the iframe
`Height`	`string`	`"600px"`	Height of the iframe
`EnableAutoResize`	`bool`	`true`	Enable automatic height adjustment
`ResizeOptions`	`ResizeOptions?`	`null`	Configuration for auto-resize behavior
`EnableScroll`	`bool`	`false`	Enable scrolling on the wrapper
`EnableNavigationTracking`	`bool`	`false`	Track iframe navigation events
`AllowedOrigins`	`List<string>?`	`null`	Allowed origins for postMessage
`SecurityOptions`	`MessageSecurityOptions`	`new()`	Security configuration
`CspOptions`	`CspOptions?`	`null`	Content Security Policy configuration

Component Methods

Method	Returns	Description
`ReloadAsync()`	`Task`	Reloads the iframe content
`ReloadAsync(string newSrc)`	`Task`	Reloads with a new source URL
`SendMessageAsync(object data, string? targetOrigin)`	`Task<bool>`	Sends a message to the iframe
`SendTypedMessageAsync(string type, object? data, string? targetOrigin)`	`Task<bool>`	Sends a typed message
`GetRecommendedCspHeader()`	`CspHeader?`	Gets the recommended CSP header
`ValidateCspConfiguration()`	`CspValidationResult?`	Validates the CSP configuration

Events

Event	Type	Description
`OnLoad`	`EventCallback`	Fired when iframe loads
`OnMessage`	`EventCallback<string>`	Fired on message (raw JSON)
`OnValidatedMessage`	`EventCallback<IframeMessage>`	Fired on validated message
`OnSecurityViolation`	`EventCallback<IframeMessage>`	Fired on security violation
`OnNavigation`	`EventCallback<NavigationEvent>`	Fired on navigation
`OnUrlChanged`	`EventCallback<string>`	Fired on URL change
`OnMessageSent`	`EventCallback<string>`	Fired when message sent
`OnMessageSendFailed`	`EventCallback<Exception>`	Fired on send failure
`OnCspHeaderGenerated`	`EventCallback<CspHeader>`	Fired when CSP generated
`OnInitializationError`	`EventCallback<Exception>`	Fired on init failure

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 :heart: for the Blazor community

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 with configurable options
Programmatic Reload - Refresh iframe content without recreating the entire component

Documentation

Complete Documentation

:rocket: 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();

Auto-Resize Configuration

Control how the iframe automatically adjusts its height based on content:

<BlazorFrame Src="https://example.com"
            EnableAutoResize="true"
            ResizeOptions="@resizeOptions" />

@code {
    // Custom resize configuration
    private readonly ResizeOptions resizeOptions = new()
    {
        MinHeight = 200,
        MaxHeight = 2000,
        PollingInterval = 500,
        DebounceMs = 100,
        UseResizeObserver = true
    };
    
    // Or use built-in presets:
    // ResizeOptions.Default      - Balanced defaults
    // ResizeOptions.Performance  - Less frequent updates (better performance)
    // ResizeOptions.Responsive   - More frequent updates (smoother resizing)
}

Property	Default	Description
`MinHeight`	100	Minimum height in pixels
`MaxHeight`	50000	Maximum height in pixels
`PollingInterval`	500	Fallback polling interval (ms) when ResizeObserver unavailable
`DebounceMs`	100	Debounce delay to prevent excessive updates (0 to disable)
`UseResizeObserver`	true	Use ResizeObserver API when available

Programmatic Reload

Refresh iframe content without recreating the entire component - useful for PDFs, dynamic content, or cache-busting:

<BlazorFrame @ref="iframeRef" Src="@pdfUrl" />

<button @onclick="RefreshContent">Refresh</button>
<button @onclick="LoadNewDocument">Load New Document</button>

@code {
    private BlazorFrame? iframeRef;
    private string pdfUrl = "https://example.com/document.pdf";
    
    // Reload the current content
    private async Task RefreshContent()
    {
        if (iframeRef != null)
        {
            await iframeRef.ReloadAsync();
        }
    }
    
    // Load a new URL with cache-busting
    private async Task LoadNewDocument()
    {
        if (iframeRef != null)
        {
            var cacheBustedUrl = $"https://example.com/document.pdf?v={DateTime.UtcNow.Ticks}";
            await iframeRef.ReloadAsync(cacheBustedUrl);
        }
    }
}

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	Permissions	Use Case
None	No restrictions	Trusted content only
Basic	Scripts + same-origin	Most trusted widgets
Permissive	Scripts + same-origin + forms + popups	Interactive widgets
Strict	Scripts only (no same-origin)	Semi-trusted content
Paranoid	Empty sandbox (no permissions)	Untrusted content

API Reference

Component Parameters

Parameter	Type	Default	Description
`Src`	`string`	`""`	The URL to load in the iframe
`Width`	`string`	`"100%"`	Width of the iframe
`Height`	`string`	`"600px"`	Height of the iframe
`EnableAutoResize`	`bool`	`true`	Enable automatic height adjustment
`ResizeOptions`	`ResizeOptions?`	`null`	Configuration for auto-resize behavior
`EnableScroll`	`bool`	`false`	Enable scrolling on the wrapper
`EnableNavigationTracking`	`bool`	`false`	Track iframe navigation events
`AllowedOrigins`	`List<string>?`	`null`	Allowed origins for postMessage
`SecurityOptions`	`MessageSecurityOptions`	`new()`	Security configuration
`CspOptions`	`CspOptions?`	`null`	Content Security Policy configuration

Component Methods

Method	Returns	Description
`ReloadAsync()`	`Task`	Reloads the iframe content
`ReloadAsync(string newSrc)`	`Task`	Reloads with a new source URL
`SendMessageAsync(object data, string? targetOrigin)`	`Task<bool>`	Sends a message to the iframe
`SendTypedMessageAsync(string type, object? data, string? targetOrigin)`	`Task<bool>`	Sends a typed message
`GetRecommendedCspHeader()`	`CspHeader?`	Gets the recommended CSP header
`ValidateCspConfiguration()`	`CspValidationResult?`	Validates the CSP configuration

Events

Event	Type	Description
`OnLoad`	`EventCallback`	Fired when iframe loads
`OnMessage`	`EventCallback<string>`	Fired on message (raw JSON)
`OnValidatedMessage`	`EventCallback<IframeMessage>`	Fired on validated message
`OnSecurityViolation`	`EventCallback<IframeMessage>`	Fired on security violation
`OnNavigation`	`EventCallback<NavigationEvent>`	Fired on navigation
`OnUrlChanged`	`EventCallback<string>`	Fired on URL change
`OnMessageSent`	`EventCallback<string>`	Fired when message sent
`OnMessageSendFailed`	`EventCallback<Exception>`	Fired on send failure
`OnCspHeaderGenerated`	`EventCallback<CspHeader>`	Fired when CSP generated
`OnInitializationError`	`EventCallback<Exception>`	Fired on init failure

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 :heart: for the Blazor community

Tim-Maes/BlazorFramev2.5.0

Get Started

Readme

Features

Documentation

:rocket: Quick Start

Installation

Basic Usage

Configuration Examples

Auto-Resize Configuration

Programmatic Reload

Content Security Policy

Security

Content Security Policy

Message Validation

Sandbox Security Levels

API Reference

Component Parameters

Component Methods

Events

Demo

Requirements

Browser Support

Support

License

Tim-Maes/BlazorFramev2.5.0

Get Started

Readme

Features

Documentation

:rocket: Quick Start

Installation

Basic Usage

Configuration Examples

Auto-Resize Configuration

Programmatic Reload

Content Security Policy

Security

Content Security Policy

Message Validation

Sandbox Security Levels

API Reference

Component Parameters

Component Methods

Events

Demo

Requirements

Browser Support

Support

License