Skip to content

Commit a4c852d

Browse files
Tim-MaesTim-Maes
committed
Docs
1 parent 24f2e84 commit a4c852d

File tree

3 files changed

+192
-170
lines changed

3 files changed

+192
-170
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ A security-first Blazor iframe component with automatic resizing, cross-frame me
1717

1818
## Documentation
1919

20-
**[Complete Documentation](https://github.com/Tim-Maes/BlazorFrame/blob/master/docs/index.md)**
20+
**[Complete Documentation](https://github.com/Tim-Maes/BlazorFrame/blob/master/docs)**
2121

2222
- [Quick Start Guide](https://github.com/Tim-Maes/BlazorFrame/tree/master/docs/getting-started/quick-start.md)
2323

‎docs/index.md‎

Lines changed: 0 additions & 169 deletions
Original file line numberDiff line numberDiff line change
@@ -1,169 +0,0 @@
1-
# BlazorFrame Documentation
2-
3-
Welcome to the comprehensive documentation for **BlazorFrame** - the enhanced, secure Blazor iframe component with built-in security features, automatic resizing, and Content Security Policy integration.
4-
5-
## Available Documentation
6-
7-
### Getting Started
8-
- [**Quick Start**](getting-started/quick-start.md) - Get up and running in minutes
9-
10-
### Configuration
11-
- [**Configuration Guide**](configuration/index.md) - Complete configuration reference (New!)
12-
- [Security Configuration](configuration/security-options.md) - Security settings and presets
13-
- [Display Configuration](configuration/display-options.md) - Visual presentation options
14-
- [Communication Configuration](configuration/communication-options.md) - Cross-frame messaging
15-
- [CSP Configuration](configuration/csp-configuration.md) - Content Security Policy
16-
- [Advanced Configuration](configuration/advanced-options.md) - Performance and enterprise features
17-
18-
### Core Features
19-
- [**Component Parameters**](core-features/parameters.md) - Complete parameter reference
20-
21-
### Security Features
22-
- [**Sandbox Attributes**](security/sandbox.md) - Iframe sandbox security (New in v2.1)
23-
- [**Configuration Validation**](security/configuration-validation.md) - Real-time security validation (New in v2.1)
24-
25-
### Examples & Recipes
26-
- [**Common Scenarios**](examples/common-scenarios.md) - Real-world usage examples
27-
28-
### API Reference
29-
- [**MessageSecurityOptions**](api/message-security-options.md) - Security configuration API
30-
31-
### Advanced Topics
32-
- [**Troubleshooting**](advanced/troubleshooting.md) - Common issues and solutions
33-
34-
---
35-
36-
## What's New in v2.1
37-
38-
BlazorFrame v2.1 introduces powerful new security features:
39-
40-
### Sandbox Security
41-
- **Iframe Sandbox Attributes** - Comprehensive sandbox support with presets
42-
- **Sandbox Presets** - None, Basic, Permissive, Strict, and Paranoid levels
43-
- **Custom Sandbox Configuration** - Granular control over iframe permissions
44-
45-
### Enhanced Security
46-
- **HTTPS Enforcement** - Configurable transport security requirements
47-
- **Configuration Validation** - Real-time validation with conflict detection
48-
- **URL Validation** - Security validation for iframe sources
49-
50-
### Developer Experience
51-
- **Fluent Configuration API** - Easy-to-use extension methods
52-
- **Environment-Aware Defaults** - Automatic development/production configuration
53-
- **Comprehensive Validation** - Detailed error reporting and suggestions
54-
55-
---
56-
57-
## Quick Start
58-
59-
Get started with BlazorFrame in under 2 minutes:
60-
61-
# Install the package
62-
dotnet add package BlazorFrame@using BlazorFrame<BlazorFrame Src="https://example.com" />
63-
64-
<BlazorFrame Src="https://widget.example.com"
65-
SecurityOptions="@securityOptions"
66-
OnValidatedMessage="HandleMessage"
67-
OnSecurityViolation="HandleViolation" />
68-
69-
@code {
70-
private readonly MessageSecurityOptions securityOptions = new MessageSecurityOptions()
71-
.ForProduction()
72-
.WithBasicSandbox()
73-
.RequireHttps();
74-
75-
private Task HandleMessage(IframeMessage message) => Task.CompletedTask;
76-
private Task HandleViolation(IframeMessage violation) => Task.CompletedTask;
77-
}
78-
## Core Features Overview
79-
80-
### Security-First Design
81-
82-
BlazorFrame is built with security as the primary concern:
83-
84-
- **Origin Validation** - Automatic validation of message origins
85-
- **Message Filtering** - Comprehensive message content validation
86-
- **Sandbox Support** - Iframe content isolation with multiple security levels
87-
- **HTTPS Enforcement** - Configurable transport security requirements
88-
- **Real-time Validation** - Configuration conflict detection and resolution
89-
90-
### Automatic Resizing
91-
92-
Smart iframe height management:
93-
94-
- **Content-based Resizing** - Automatically adjusts to iframe content height
95-
- **Cross-origin Safe** - Handles cross-origin restrictions gracefully
96-
- **Performance Optimized** - Uses ResizeObserver when available, falls back to polling
97-
- **Configurable** - Can be disabled for fixed-height scenarios
98-
99-
### Cross-Frame Communication
100-
101-
Secure postMessage integration:
102-
103-
- **Validated Messages** - All messages undergo security validation
104-
- **Type-safe Events** - Strongly-typed message and violation events
105-
- **Origin Filtering** - Automatic origin-based message filtering
106-
- **Custom Validation** - Extensible validation pipeline
107-
108-
### Content Security Policy
109-
110-
Built-in CSP support:
111-
112-
- **Header Generation** - Automatic CSP header creation
113-
- **Fluent Configuration** - Easy-to-use configuration API
114-
- **Environment-aware** - Different settings for development/production
115-
- **Validation** - CSP configuration validation and suggestions
116-
117-
## Configuration Examples
118-
119-
### Development Configuration
120-
var devOptions = new MessageSecurityOptions()
121-
.ForDevelopment() // Relaxed security for development
122-
.WithPermissiveSandbox() // Allow most iframe interactions
123-
.Validate(); // Check configuration but don't throw### Production Configuration
124-
var prodOptions = new MessageSecurityOptions()
125-
.ForProduction() // Strict security for production
126-
.WithStrictSandbox() // Limited iframe permissions
127-
.ValidateAndThrow(); // Throw on configuration errors
128-
### Payment Widget Configuration
129-
var paymentOptions = new MessageSecurityOptions()
130-
.ForPaymentWidget() // Maximum security preset
131-
.ValidateAndThrow(); // Critical to validate payment configs
132-
### Custom Configuration
133-
var customOptions = new MessageSecurityOptions
134-
{
135-
EnableStrictValidation = true,
136-
MaxMessageSize = 32 * 1024,
137-
SandboxPreset = SandboxPreset.Basic,
138-
EnableSandbox = true,
139-
RequireHttps = true,
140-
AllowInsecureConnections = false,
141-
LogSecurityViolations = true
142-
};
143-
## Browser Support
144-
145-
BlazorFrame works in all modern browsers that support:
146-
147-
- **ES6 modules** - Modern JavaScript module support
148-
- **postMessage API** - Cross-frame communication with origin validation
149-
- **Blazor JavaScript interop** - .NET to JavaScript communication
150-
- **ResizeObserver** - Optimal auto-resize performance (fallback available)
151-
152-
## Requirements
153-
154-
- **.NET 8.0** or later
155-
- **Blazor Server** or **Blazor WebAssembly** project
156-
- Modern browser with ES6 modules support
157-
158-
---
159-
160-
## Support & Community
161-
162-
- **Issues**: [GitHub Issues](https://github.com/Tim-Maes/BlazorFrame/issues)
163-
- **Discussions**: [GitHub Discussions](https://github.com/Tim-Maes/BlazorFrame/discussions)
164-
- **Source Code**: [GitHub Repository](https://github.com/Tim-Maes/BlazorFrame)
165-
- **NuGet Package**: [BlazorFrame on NuGet](https://www.nuget.org/packages/BlazorFrame)
166-
167-
---
168-
169-
**Built with love for the Blazor community**

‎docs/readme.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# BlazorFrame Documentation
2+
3+
Welcome to the comprehensive documentation for **BlazorFrame** - the enhanced, secure Blazor iframe component with built-in security features, automatic resizing, and Content Security Policy integration.
4+
5+
## Available Documentation
6+
7+
### Getting Started
8+
- [**Quick Start**](getting-started/quick-start.md) - Get up and running in minutes
9+
10+
### Configuration
11+
- [**Configuration Guide**](configuration/index.md) - Complete configuration reference (New!)
12+
- [Security Configuration](configuration/security-options.md) - Security settings and presets
13+
- [Display Configuration](configuration/display-options.md) - Visual presentation options
14+
- [Communication Configuration](configuration/communication-options.md) - Cross-frame messaging
15+
- [CSP Configuration](configuration/csp-configuration.md) - Content Security Policy
16+
- [Advanced Configuration](configuration/advanced-options.md) - Performance and enterprise features
17+
18+
### Core Features
19+
- [**Component Parameters**](core-features/parameters.md) - Complete parameter reference
20+
21+
### Security Features
22+
- [**Sandbox Attributes**](security/sandbox.md) - Iframe sandbox security (New in v2.1)
23+
- [**Configuration Validation**](security/configuration-validation.md) - Real-time security validation (New in v2.1)
24+
25+
### Examples & Recipes
26+
- [**Common Scenarios**](examples/common-scenarios.md) - Real-world usage examples
27+
28+
### API Reference
29+
- [**MessageSecurityOptions**](api/message-security-options.md) - Security configuration API
30+
31+
### Advanced Topics
32+
- [**Troubleshooting**](advanced/troubleshooting.md) - Common issues and solutions
33+
34+
---
35+
36+
## What's New in v2.1
37+
38+
BlazorFrame v2.1 introduces powerful new security features:
39+
40+
### Sandbox Security
41+
42+
- **Iframe Sandbox Attributes** - Comprehensive sandbox support with presets
43+
- **Sandbox Presets** - None, Basic, Permissive, Strict, and Paranoid levels
44+
- **Custom Sandbox Configuration** - Granular control over iframe permissions
45+
46+
### Enhanced Security
47+
48+
- **HTTPS Enforcement** - Configurable transport security requirements
49+
- **Configuration Validation** - Real-time validation with conflict detection
50+
- **URL Validation** - Security validation for iframe sources
51+
52+
### Developer Experience
53+
54+
- **Fluent Configuration API** - Easy-to-use extension methods
55+
- **Environment-Aware Defaults** - Automatic development/production configuration
56+
- **Comprehensive Validation** - Detailed error reporting and suggestions
57+
58+
---
59+
60+
## Quick Start
61+
62+
Get started with BlazorFrame in under 2 minutes:
63+
64+
# Install the package
65+
```bash
66+
dotnet add package BlazorFrame
67+
```
68+
69+
```razor
70+
@using BlazorFrame<BlazorFrame Src="https://example.com" />
71+
72+
<BlazorFrame Src="https://widget.example.com"
73+
SecurityOptions="@securityOptions"
74+
OnValidatedMessage="HandleMessage"
75+
OnSecurityViolation="HandleViolation" />
76+
77+
@code {
78+
private readonly MessageSecurityOptions securityOptions = new MessageSecurityOptions()
79+
.ForProduction()
80+
.WithBasicSandbox()
81+
.RequireHttps();
82+
83+
private Task HandleMessage(IframeMessage message) => Task.CompletedTask;
84+
private Task HandleViolation(IframeMessage violation) => Task.CompletedTask;
85+
}
86+
```
87+
88+
## Core Features Overview
89+
90+
### Security-First Design
91+
92+
BlazorFrame is built with security as the primary concern:
93+
94+
- **Origin Validation** - Automatic validation of message origins
95+
- **Message Filtering** - Comprehensive message content validation
96+
- **Sandbox Support** - Iframe content isolation with multiple security levels
97+
- **HTTPS Enforcement** - Configurable transport security requirements
98+
- **Real-time Validation** - Configuration conflict detection and resolution
99+
100+
### Automatic Resizing
101+
102+
Smart iframe height management:
103+
104+
- **Content-based Resizing** - Automatically adjusts to iframe content height
105+
- **Cross-origin Safe** - Handles cross-origin restrictions gracefully
106+
- **Performance Optimized** - Uses ResizeObserver when available, falls back to polling
107+
- **Configurable** - Can be disabled for fixed-height scenarios
108+
109+
### Cross-Frame Communication
110+
111+
Secure postMessage integration:
112+
113+
- **Validated Messages** - All messages undergo security validation
114+
- **Type-safe Events** - Strongly-typed message and violation events
115+
- **Origin Filtering** - Automatic origin-based message filtering
116+
- **Custom Validation** - Extensible validation pipeline
117+
118+
### Content Security Policy
119+
120+
Built-in CSP support:
121+
122+
- **Header Generation** - Automatic CSP header creation
123+
- **Fluent Configuration** - Easy-to-use configuration API
124+
- **Environment-aware** - Different settings for development/production
125+
- **Validation** - CSP configuration validation and suggestions
126+
127+
## Configuration Examples
128+
129+
### Development Configuration
130+
131+
```csharp
132+
var devOptions = new MessageSecurityOptions()
133+
.ForDevelopment() // Relaxed security for development
134+
.WithPermissiveSandbox() // Allow most iframe interactions
135+
.Validate(); // Check configuration but don't throw### Production Configuration
136+
var prodOptions = new MessageSecurityOptions()
137+
.ForProduction() // Strict security for production
138+
.WithStrictSandbox() // Limited iframe permissions
139+
.ValidateAndThrow(); // Throw on configuration errors
140+
```
141+
142+
### Payment Widget Configuration
143+
144+
```csharp
145+
var paymentOptions = new MessageSecurityOptions()
146+
.ForPaymentWidget() // Maximum security preset
147+
.ValidateAndThrow(); // Critical to validate payment configs
148+
```
149+
150+
### Custom Configuration
151+
152+
```csharp
153+
var customOptions = new MessageSecurityOptions
154+
{
155+
EnableStrictValidation = true,
156+
MaxMessageSize = 32 * 1024,
157+
SandboxPreset = SandboxPreset.Basic,
158+
EnableSandbox = true,
159+
RequireHttps = true,
160+
AllowInsecureConnections = false,
161+
LogSecurityViolations = true
162+
};
163+
```
164+
165+
## Browser Support
166+
167+
BlazorFrame works in all modern browsers that support:
168+
169+
- **ES6 modules** - Modern JavaScript module support
170+
- **postMessage API** - Cross-frame communication with origin validation
171+
- **Blazor JavaScript interop** - .NET to JavaScript communication
172+
- **ResizeObserver** - Optimal auto-resize performance (fallback available)
173+
174+
## Requirements
175+
176+
- **.NET 8.0** or later
177+
- **Blazor Server** or **Blazor WebAssembly** project
178+
- Modern browser with ES6 modules support
179+
180+
---
181+
182+
## Support & Community
183+
184+
- **Issues**: [GitHub Issues](https://github.com/Tim-Maes/BlazorFrame/issues)
185+
- **Discussions**: [GitHub Discussions](https://github.com/Tim-Maes/BlazorFrame/discussions)
186+
- **Source Code**: [GitHub Repository](https://github.com/Tim-Maes/BlazorFrame)
187+
- **NuGet Package**: [BlazorFrame on NuGet](https://www.nuget.org/packages/BlazorFrame)
188+
189+
---
190+
191+
**Built with love for the Blazor community**

0 commit comments

Comments
 (0)