### Basic Setup

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Registers the security headers middleware with default settings.

```csharp
var builder = WebApplication.CreateBuilder();
var app = builder.Build();
app.UseSecurityHeaders();
app.Run();
```

--------------------------------

### Custom Header Examples

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Examples of adding and removing custom security headers.

```csharp
// Add arbitrary headers
policies.AddCustomHeader("X-Custom-Header", "value");
policies.AddCustomHeader("X-App-Version", "1.0.0");

// Remove headers added by other middleware
policies.RemoveServerHeader();
policies.RemoveCustomHeaderExtensions("X-Powered-By");

// Per-request custom headers
policies.AddCustomHeader("X-Correlation-Id", 
    context => context.TraceIdentifier);
```

--------------------------------

### Caching Static Policies

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Example of caching static policies at startup for performance.

```csharp
// Create policies once at startup
var apiPolicy = new HeaderPolicyCollection()
    .AddDefaultApiSecurityHeaders();

builder.Services.AddSecurityHeaderPolicies(policies =>
{
    policies.AddPolicy("Api", apiPolicy);
    // Reuse the same collection instance
});
```

--------------------------------

### Program.cs Setup for Security Headers

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Complete C# example for setting up Content-Security-Policy with various directives including nonce and hashed attributes in Program.cs.

```csharp
var builder = WebApplication.CreateBuilder();

builder.Services.AddRazorPages();
builder.Services.AddSecurityHeaderPolicies(policies =>
{
    policies.SetDefaultPolicy(p =>
    {
        p.AddContentSecurityPolicy(csp =>
        {
            csp.AddUpgradeInsecureRequests();
            
            csp.AddDefaultSrc().Self();
            
            csp.AddScriptSrc()
                .Self()
                .WithNonce()
                .StrictDynamic();
            
            csp.AddStyleSrc()
                .Self()
                .WithHashTagHelper();
            
            csp.AddImgSrc().Self().Data();
        });
    });
});

var app = builder.Build();
app.UseSecurityHeaders();
app.MapRazorPages();
app.Run();
```

--------------------------------

### Cross-Origin-Resource-Policy Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Configures the Cross-Origin-Resource-Policy header. The example sets the policy to 'SameSite' to allow access from same-site origins.

```csharp
policies.AddCrossOriginResourcePolicy(builder =>
{
    // Options:
    // - SameOrigin(): Only same-origin access
    // - SameSite(): Same-site access
    // - CrossOrigin(): Allow any cross-origin access
    builder.SameSite();
});
```

--------------------------------

### AddFullscreen() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

Example of allowing fullscreen for all.

```csharp
builder.AddFullscreen().All();
```

--------------------------------

### Cross-Origin-Opener-Policy Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Configures the Cross-Origin-Opener-Policy header. The example sets the policy to 'SameOrigin' to isolate the document from cross-origin popups.

```csharp
policies.AddCrossOriginOpenerPolicy(builder =>
{
    // Options:
    // - SameOrigin(): Isolate from cross-origin popups
    // - SameOriginAllowPopups(): Allow controlled popups
    // - UnsafeNone(): Allow any popups (not recommended)
    builder.SameOrigin();
});
```

--------------------------------

### Example Usage

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/middleware-extensions.md

Example of configuring and using a named security policy.

```csharp
// Configure the policy in Startup
builder.Services.AddSecurityHeaderPolicies()
    .AddPolicy("DefaultPolicy", p => p.AddDefaultSecurityHeaders());

// Use it in the pipeline
app.UseSecurityHeaders("DefaultPolicy");
```

--------------------------------

### Install the NuGet package

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Command to install the NetEscapades.AspNetCore.SecurityHeaders.TagHelpers NuGet package.

```bash
dotnet package add Install-Package NetEscapades.AspNetCore.SecurityHeaders.TagHelpers
```

--------------------------------

### Permissions-Policy Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Configures Permissions-Policy directives to control browser feature access. This example restricts camera, microphone, and geolocation, while allowing fullscreen and autoplay.

```csharp
policies.AddPermissionsPolicy(builder =>
{
    builder.AddCamera().None();
    builder.AddMicrophone().None();
    builder.AddGeolocation().Self();
    builder.AddFullscreen().All();
    builder.AddAutoplay().Self();
});
```

--------------------------------

### Project file update

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Example of how the .csproj file is updated after installing the NuGet package.

```xml
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="NetEscapades.AspNetCore.SecurityHeaders" Version="1.3.1" />
    <PackageReference Include="NetEscapades.AspNetCore.SecurityHeaders.TagHelpers" Version="1.3.1" />
  </ItemGroup>
  
</Project>
```

--------------------------------

### Middleware Position Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/middleware-extensions.md

Example demonstrating the recommended placement of the security headers middleware early in the pipeline.

```csharp
var app = builder.Build();

// Add security headers early!
app.UseSecurityHeaders();

// Then add other middleware
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
```

--------------------------------

### Install using the .NET CLI

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Install the NetEscapades.AspNetCore.SecurityHeaders NuGet package using the dotnet CLI.

```bash
dotnet add package NetEscapades.AspNetCore.SecurityHeaders --version 1.3.1
```

--------------------------------

### Header Composition Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-extensions.md

Example demonstrating how to combine multiple security header policies.

```csharp
var policies = new HeaderPolicyCollection()
    // Prevent clickjacking
    .AddFrameOptionsDeny()
    
    // Prevent MIME sniffing
    .AddContentTypeOptionsNoSniff()
    
    // Force HTTPS for 2 years including subdomains
    .AddStrictTransportSecurityMaxAgeIncludeSubDomains(63072000)
    
    // Control referrer leaks
    .AddReferrerPolicyStrictOriginWhenCrossOrigin()
    
    // Remove server information
    .RemoveServerHeader()
    
    // Add custom headers
    .AddCustomHeader("X-Custom-Header", "value")
    
    // CSP configuration
    .AddContentSecurityPolicy(builder =>
    {
        builder.AddDefaultSrc().Self();
        builder.AddScriptSrc().Self();
    });

app.UseSecurityHeaders(policies);

```

--------------------------------

### Complete CSP Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

A comprehensive example demonstrating the configuration of various CSP directives.

```csharp
app.UseSecurityHeaders(policies =>
{
    policies.AddContentSecurityPolicy(builder =>
    {
        // Upgrade insecure requests and block mixed content
        builder.AddUpgradeInsecureRequests();
        builder.AddBlockAllMixedContent();

        // Default policy
        builder.AddDefaultSrc()
            .Self()
            .From("https://trusted-cdn.com");

        // Scripts: self, nonce, and specific CDN
        builder.AddScriptSrc()
            .Self()
            .From("https://cdn.example.com")
            .WithNonce()
            .StrictDynamic();

        // Styles: self, unsafe-inline, and Google Fonts
        builder.AddStyleSrc()
            .Self()
            .UnsafeInline()
            .From("https://fonts.googleapis.com")
            .WithHashTagHelper();

        // Fonts
        builder.AddFontSrc()
            .Self()
            .From("https://fonts.gstatic.com");

        // Restrict forms
        builder.AddFormAction().Self();

        // Prevent framing
        builder.AddFrameAncestors().None();

        // Disable plugins
        builder.AddObjectSrc().None();

        // Base URI
        builder.AddBaseUri().Self();

        // Reporting
        builder.AddReportUri()
            .To("https://report-uri.com/report/");
    });
});
```

--------------------------------

### Complete Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

This example demonstrates how to configure a Permissions-Policy, disabling most sensors and APIs while allowing fullscreen and picture-in-picture for the same origin, and specific domains for geolocation.

```csharp
app.UseSecurityHeaders(policies =>
{
    policies.AddPermissionsPolicy(builder =>
    {
        // Disable most sensors and APIs
        builder.AddAccelerometer().None();
        builder.AddAmbientLightSensor().None();
        builder.AddAutoplay().None();
        builder.AddCamera().None();
        builder.AddDisplayCapture().None();
        builder.AddEncryptedMedia().None();
        builder.AddGeolocation().None();
        builder.AddGyroscope().None();
        builder.AddMagnetometer().None();
        builder.AddMicrophone().None();
        builder.AddMidi().None();
        builder.AddPayment().None();
        builder.AddSpeaker().None();
        builder.AddUsb().None();
        builder.AddVR().None();
        builder.AddXrSpatialTracking().None();

        // Allow fullscreen
        builder.AddFullscreen().All();

        // Allow picture-in-picture for same origin
        builder.AddPictureInPicture().Self();

        // Allow geolocation for specific trusted domains
        builder.AddGeolocation()
            .Self()
            .For("https://maps.example.com");
    });
});
```

--------------------------------

### GetNonce Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

C# example demonstrating how to retrieve a nonce and use it in manually-constructed HTML for script tags.

```csharp
var nonce = HttpContext.GetNonce();
// Use in manually-constructed HTML
var html = $"<script nonce='{nonce}'>console.log('test');</script>";
```

--------------------------------

### AddCustomHeader() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-extensions.md

Example of adding custom headers like X-App-Version and X-Custom-Setting.

```csharp
policies.AddCustomHeader("X-App-Version", "1.0.0");
policies.AddCustomHeader("X-Custom-Setting", "value");

```

--------------------------------

### Multi-Tenant Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/endpoint-extensions.md

An example demonstrating how to apply different security header policies to different tenants by using a scoped service to determine the current tenant and select the appropriate policy.

```csharp
builder.Services.AddScoped<TenantService>();
builder.Services.AddSecurityHeaderPolicies((policies, provider) =>
{
    policies.SetDefaultPolicy(p => p.AddDefaultSecurityHeaders());
    
    policies.AddPolicy("TenantA", p => p
        .AddDefaultSecurityHeaders()
        .AddCustomHeader("X-Tenant", "A"));
    
    policies.AddPolicy("TenantB", p => p
        .AddDefaultSecurityHeaders()
        .AddCustomHeader("X-Tenant", "B"));

    policies.SetPolicySelector(context =>
    {
        var tenantService = context.HttpContext.RequestServices
            .GetRequiredService<TenantService>();
        
        var tenantId = tenantService.GetCurrentTenantId(context.HttpContext);
        var policyName = $"Tenant{tenantId}";
        
        if (context.ConfiguredPolicies.TryGetValue(policyName, out var policy))
        {
            return policy;
        }
        
        return context.DefaultPolicy;
    });
});

var app = builder.Build();
app.UseSecurityHeaders();

app.MapGet("/api/tenant-data", GetTenantData)
    .WithSecurityHeadersPolicy("TenantA");

app.Run();
```

--------------------------------

### Selective Feature Relaxation

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

This example shows how to start with secure defaults and selectively enable features, such as camera, microphone, and fullscreen for specific origins.

```csharp
policies.AddPermissionsPolicy(builder =>
{
    // Add all the default versions
    builder.AddDefaultSecureDirectives();

    // Override a directive to allow a specific feature
    builder.AddCamera()
        .Self()
        .For("https://video-conference.example.com");

    builder.AddMicrophone()
        .Self()
        .For("https://video-conference.example.com");

    builder.AddFullscreen()
        .Self()
        .For("https://video.example.com");
});
```

--------------------------------

### Installation

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/README.md

Install the NetEscapades.AspNetCore.SecurityHeaders NuGet package using the .NET CLI.

```bash
dotnet add package NetEscapades.AspNetCore.SecurityHeaders
```

--------------------------------

### Copy() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-policy-collection.md

Example of copying a default policy and adding a custom header.

```csharp
var modifiedPolicy = defaultPolicy.Copy()
    .AddCustomHeader("X-Modified", "true");
```

--------------------------------

### AddAutoplay() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

Example of controlling autoplay.

```csharp
builder.AddAutoplay().None();
```

--------------------------------

### SetScriptCSPHash Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

C# example demonstrating how to calculate and set a script CSP hash using HttpContext extensions.

```csharp
var hash = CalculateSHA256("console.log('test')");
HttpContext.SetScriptCSPHash(CSPHashType.SHA256, hash);
```

--------------------------------

### AddMediaSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for <audio> and <video> elements.

```csharp
builder.AddMediaSrc().Self();
```

--------------------------------

### Creating Policies Inline

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Creates a `HeaderPolicyCollection` inline and applies it to the middleware.

```csharp
var policies = new HeaderPolicyCollection()
    .AddFrameOptionsDeny()
    .AddContentTypeOptionsNoSniff()
    .AddStrictTransportSecurityMaxAgeIncludeSubDomains(maxAgeInSeconds: 31536000);

app.UseSecurityHeaders(policies);
```

--------------------------------

### HeaderPolicyCollection() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-policy-collection.md

Example of creating and adding headers to an empty HeaderPolicyCollection.

```csharp
var policies = new HeaderPolicyCollection()
    .AddFrameOptionsDeny()
    .AddContentTypeOptionsNoSniff();
```

--------------------------------

### Avoiding Per-Request Policy Creation

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Demonstrates the correct way to cache policies to avoid per-request creation overhead.

```csharp
// BAD: Creates new policy for every request
policies.SetPolicySelector(context =>
{
    return new HeaderPolicyCollection()
        .AddDefaultSecurityHeaders();
});

// GOOD: Cache the policy
var defaultPolicy = new HeaderPolicyCollection()
    .AddDefaultSecurityHeaders();

policies.SetPolicySelector(context =>
{
    // Reuse cached policy
    if (context.HttpContext.Request.Path.StartsWithSegments("/special"))
    {
        // Only copy and modify when necessary
        return defaultPolicy.Copy().AddCustomHeader("X-Special", "true");
    }
    return defaultPolicy;
});
```

--------------------------------

### HashTagHelper Example with Different Algorithms

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Example demonstrating how to use the HashTagHelper with different hash algorithms like SHA512.

```html
<script asp-add-content-to-csp csp-hash-type="SHA512">
    // Content will be hashed with SHA512
</script>
```

--------------------------------

### AddCamera() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

Example of denying camera access.

```csharp
builder.AddCamera().None();
```

--------------------------------

### Async Policy Selection

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Enables asynchronous selection of security policies, useful for fetching tenant-specific configurations.

```csharp
builder.Services.AddSecurityHeaderPolicies((policies, provider) =>
{
    policies.SetAsyncPolicySelector(async context =>
    {
        var tenantService = context.HttpContext.RequestServices
            .GetRequiredService<TenantService>();
        
        var tenant = await tenantService.GetCurrentTenantAsync(context.HttpContext);
        
        return context.ConfiguredPolicies[$"Tenant{tenant.Id}"];
    });
});
```

--------------------------------

### Cross-Origin-Embedder-Policy Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Configures the Cross-Origin-Embedder-Policy header. The example sets the policy to 'RequireCorp' which requires CORP headers on cross-origin resources.

```csharp
policies.AddCrossOriginEmbedderPolicy(builder =>
{
    // Options:
    // - RequireCorp(): Require CORP headers on cross-origin resources
    // - Credentialless(): Load without credentials
    // - UnsafeNone(): Allow unrestricted embedding (not recommended)
    builder.RequireCorp();
});
```

--------------------------------

### Adding the security headers middleware early in the pipeline

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

This example demonstrates the correct placement of the UseSecurityHeaders() middleware at the start of the application's middleware pipeline.

```csharp
var builder = WebApplication.CreateBuilder();

// 👇 Configure policies as shown previously
builder.Services.AddSecurityHeaderPolicies()
    .SetDefaultPolicy(policy => policy.AddDefaultSecurityHeaders())
    .AddPolicy("CustomPolicy", policy => policy.AddCustomHeader("X-Custom", "SomeValue"));

var app = builder.Build();

// Add the middleware to the start of your pipeline
// 👇
app.UseSecurityHeaders();

app.UseStaticFiles(); // other middleware
app.UseAuthentication();
app.UseRouting(); 

app.UseAuthorization();

app.MapGet("/", () => "Hello world");
app.Run();
```

--------------------------------

### AddDefaultSecurityHeaders() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-policy-collection.md

Example of adding default security headers and using them with UseSecurityHeaders.

```csharp
var policies = new HeaderPolicyCollection()
    .AddDefaultSecurityHeaders();

app.UseSecurityHeaders(policies);
```

--------------------------------

### NonceTagHelper Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Example of using the NonceTagHelper to add a nonce attribute to a script tag.

```html
<script asp-add-nonce>
    var body = document.getElementsByTagName('body')[0];
    var div = document.createElement('div');
    div.innerText = "I was added using the NonceHelper";
    body.appendChild(div);
</script>
```

--------------------------------

### AddMicrophone() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

Example of denying microphone access.

```csharp
builder.AddMicrophone().None();
```

--------------------------------

### Configuring CSP with Nonce

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Example of configuring the CSP builder to include nonces for script sources.

```csharp
builder.AddScriptSrc().Self().WithNonce()
```

--------------------------------

### Full Content Security Policy Configuration Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

A comprehensive example of configuring various CSP directives, including UpgradeInsecureRequests, BlockAllMixedContent, ReportUri, DefaultSrc, ConnectSrc, FontSrc, ObjectSrc, FormAction, ImgSrc, ScriptSrc, StyleSrc, MediaSrc, FrameAncestors, BaseUri, FrameSrc, and custom directives.

```csharp
public void Configure(IApplicationBuilder app)
{
    var policyCollection = new HeaderPolicyCollection()
        .AddContentSecurityPolicy(builder =>
        {
            builder.AddUpgradeInsecureRequests(); // upgrade-insecure-requests
            builder.AddBlockAllMixedContent(); // block-all-mixed-content

            builder.AddReportUri() // report-uri: https://report-uri.com
                .To("https://report-uri.com");

            builder.AddDefaultSrc() // default-src 'self' http://testUrl.com
                .Self()
                .From("http://testUrl.com");

            builder.AddConnectSrc() // connect-src 'self' http://testUrl.com
                .Self()
                .From("http://testUrl.com");

            builder.AddFontSrc() // font-src 'self'
                .Self();

            builder.AddObjectSrc() // object-src 'none'
                .None();

            builder.AddFormAction() // form-action 'self'
                .Self();

            builder.AddImgSrc() // img-src https:
                .OverHttps();

            builder.AddScriptSrc() // script-src 'self' 'unsafe-inline' 'unsafe-eval' 'report-sample'
                .Self()
                .UnsafeInline()
                .UnsafeEval()
                .ReportSample();

            builder.AddStyleSrc() // style-src 'self' 'unsafe-inline'
                .Self()
                .UnsafeInline();

            builder.AddMediaSrc() // media-src https:
                .OverHttps();

            builder.AddFrameAncestors() // frame-ancestors 'none'
                .None();

            builder.AddBaseUri() // base-uri 'self'
                .Self();

            builder.AddFrameSrc() // frame-src http://testUrl.com
                .From("http://testUrl.com");

            // You can also add arbitrary extra directives: plugin-types application/x-shockwave-flash"
            builder.AddCustomDirective("plugin-types", "application/x-shockwave-flash");

        })
        .AddCustomHeader("X-My-Test-Header", "Header value");

    app.UseSecurityHeaders(policyCollection);

    // other middleware e.g. static files, MVC etc  
}
```

--------------------------------

### Install using the Package Manager Console

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Install the NetEscapades.AspNetCore.SecurityHeaders NuGet package using the Visual Studio Package Manager Console.

```powershell
PM> Install-Package NetEscapades.AspNetCore.SecurityHeaders
```

--------------------------------

### AddAccelerometer() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

Example of controlling accelerometer access.

```csharp
builder.AddAccelerometer().Self();
```

--------------------------------

### AddDefaultApiSecurityHeaders() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-policy-collection.md

Example of adding default API security headers and using them with UseSecurityHeaders.

```csharp
var policies = new HeaderPolicyCollection()
    .AddDefaultApiSecurityHeaders();

app.UseSecurityHeaders(policies);
```

--------------------------------

### Minimal APIs Usage Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/endpoint-extensions.md

Example of configuring and applying security header policies in a Minimal API application.

```csharp
var builder = WebApplication.CreateBuilder();

builder.Services.AddSecurityHeaderPolicies(policies =>
{
    policies.SetDefaultPolicy(p => p.AddDefaultSecurityHeaders());
    
    policies.AddPolicy("ApiPolicy", p => p
        .AddDefaultApiSecurityHeaders());
    
    policies.AddPolicy("StrictPolicy", p => p
        .AddDefaultSecurityHeaders()
        .AddContentSecurityPolicy(csp => csp
            .AddDefaultSrc().None()
            .AddScriptSrc().Self()
        ));
});

var app = builder.Build();
app.UseSecurityHeaders();

// Default policy applied
app.MapGet("/", () => "Home").WithName("Home");

// API policy applied
app.MapGet("/api/users", GetUsers)
    .WithSecurityHeadersPolicy("ApiPolicy")
    .WithName("GetUsers");

// Strict policy applied
app.MapGet("/admin/dashboard", GetDashboard)
    .WithSecurityHeadersPolicy("StrictPolicy")
    .WithName("Dashboard");

app.Run();
```

--------------------------------

### Default Security Headers

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

A list of default security headers applied by the middleware.

```text
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000;
X-Frame-Options: Deny
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: object-src 'none'; form-action 'self'; frame-ancestors 'none'
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: credentialless
Cross-Origin-Resource-Policy: same-site
```

--------------------------------

### AddImgSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for images and favicons.

```csharp
builder.AddImgSrc().Self().OverHttps().Data();
```

--------------------------------

### Index.cshtml Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Demonstrates how to use tag helpers for inline scripts, styles, and event handlers to integrate with Content-Security-Policy.

```html
@page
@model IndexModel

<h1>Content-Security-Policy Example</h1>

<!-- Inline script with nonce -->
<script asp-add-nonce>
    function greet(name) {
        console.log('Hello, ' + name + '!');
    }
    greet('World');
</script>

<!-- Inline styles with hash -->
<style asp-add-content-to-csp>
    .highlight {
        background-color: yellow;
        font-weight: bold;
    }
</style>

<!-- Inline style attribute with hash -->
<p asp-add-csp-for-style style="color: blue;">
    This paragraph is blue
</p>

<!-- Event handler with hash -->
<button asp-add-csp-for-onclick onclick="greet('User')">
    Click me
</button>
```

--------------------------------

### MVC Controllers Usage Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/endpoint-extensions.md

Example of applying security header policies to MVC controllers and actions.

```csharp
[ApiController]
[Route("api/[controller]")]
[SecurityHeadersPolicy("ApiPolicy")]  // Apply to all actions
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetUser(int id)
    {
        return Ok(new { id, name = "User" });
    }

    [HttpPost]
    [SecurityHeadersPolicy("StrictPolicy")]  // Override for this action
    public IActionResult CreateUser([FromBody] UserModel user)
    {
        return CreatedAtAction("GetUser", new { id = 1 }, user);
    }
}

[Route("admin")]
[SecurityHeadersPolicy("AdminPolicy")]  // Apply to all actions
public class AdminController : ControllerBase
{
    [HttpGet("dashboard")]
    public IActionResult Dashboard()
    {
        return Ok();
    }
}
```

--------------------------------

### Minimal APIs Endpoint Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Applying specific security header policies to Minimal API endpoints.

```csharp
app.MapGet("/", Home).WithName("Home");  // Uses default policy

app.MapGet("/api/data", GetData)
    .WithSecurityHeadersPolicy("Api");

app.MapPost("/admin", Admin)
    .WithSecurityHeadersPolicy("StrictPolicy");
```

--------------------------------

### AttributeHashTagHelper Example Usage

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

HTML examples demonstrating how to use the AttributeHashTagHelper to hash inline style and onclick attributes for Content-Security-Policy.

```html
<!-- Hash style attribute -->
<h3 asp-add-csp-for-style style="color: red">
    Red text
</h3>

<!-- Hash onclick attribute -->
<button asp-add-csp-for-onclick onclick="alert('Hello!')">
    Click me
</button>

<!-- Hash multiple attributes with different algorithms -->
<div 
    asp-add-csp-for-style style="background: blue"
    asp-add-csp-for-onclick="SHA384" onclick="handleClick()">
    Content
</div>
```

--------------------------------

### AddStyleSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for stylesheets.

```csharp
builder.AddStyleSrc()
    .Self()
    .UnsafeInline()
    .From("https://fonts.googleapis.com")
    .WithHashTagHelper();  // For hash support
```

--------------------------------

### Content-Security-Policy Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Configures Content Security Policy (CSP) directives using a `CspBuilder`.

```csharp
policies.AddContentSecurityPolicy(builder =>
{
    // Upgrade insecure requests
    builder.AddUpgradeInsecureRequests();
    
    // Block mixed content
    builder.AddBlockAllMixedContent();
    
    // Default sources
    builder.AddDefaultSrc().Self();
    
    // Script sources with nonce
    builder.AddScriptSrc()
        .Self()
        .From("https://cdn.example.com")
        .WithNonce();
    
    // Style sources with hash
    builder.AddStyleSrc()
        .Self()
        .UnsafeInline()
        .WithHashTagHelper();
    
    // Restrict form submissions
    builder.AddFormAction().Self();
    
    // Prevent framing
    builder.AddFrameAncestors().None();
    
    // Disable plugins
    builder.AddObjectSrc().None();
    
    // Report violations
    builder.AddReportUri().To("https://report-uri.com/report/");
});
```

--------------------------------

### AddReportingEndpoints() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-extensions.md

Example of configuring reporting endpoints for CSP and COOP violation reports.

```csharp
policies.AddReportingEndpoints(builder =>
{
    builder.AddEndpoint("csp-endpoint", "https://report-uri.com/report");
    builder.AddEndpoint("coop-endpoint", "https://report-uri.com/report");
});

```

--------------------------------

### Dynamic Policy Selection

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Allows selecting security policies dynamically based on request properties.

```csharp
builder.Services.AddSecurityHeaderPolicies((policies, provider) =>
{
    policies.SetDefaultPolicy(p => p.AddDefaultSecurityHeaders());
    
    policies.SetPolicySelector(context =>
    {
        // Modify policy based on request
        if (context.HttpContext.Request.Path.StartsWithSegments("/admin"))
        {
            return context.DefaultPolicy.Copy()
                .AddCustomHeader("X-Admin", "true");
        }
        
        if (context.HttpContext.Request.Path.StartsWithSegments("/api"))
        {
            return context.ConfiguredPolicies["Api"];
        }
        
        return context.DefaultPolicy;
    });
});
```

--------------------------------

### Minimal Setup

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/index.md

Applies default security headers to all responses.

```csharp
var app = builder.Build();
app.UseSecurityHeaders();
app.Run();
```

--------------------------------

### Default API Security Headers

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

A list of default security headers specifically for API endpoints.

```text
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000;
X-Frame-Options: Deny
Content-Security-Policy: default-src 'none'; frame-ancestors 'none'
Referrer-Policy: no-referrer
Permissions-Policy: accelerometer=(), autoplay=(), camera=(), display-capture=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(), usb=(), web-share=(), xr-spatial-tracking=()
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Resource-Policy: same-site
```

--------------------------------

### Method Chaining Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-policy-collection.md

Demonstrates how to configure various security headers using method chaining on HeaderPolicyCollection.

```csharp
var policies = new HeaderPolicyCollection()
    .AddFrameOptionsDeny()
    .AddContentTypeOptionsNoSniff()
    .AddStrictTransportSecurityMaxAgeIncludeSubDomains(maxAgeInSeconds: 63072000)
    .AddReferrerPolicyStrictOriginWhenCrossOrigin()
    .RemoveServerHeader()
    .AddContentSecurityPolicy(builder =>
    {
        builder.AddObjectSrc().None();
        builder.AddFormAction().Self();
        builder.AddFrameAncestors().None();
    })
    .AddCrossOriginOpenerPolicy(x => x.SameOrigin())
    .AddCrossOriginEmbedderPolicy(builder => builder.Credentialless())
    .AddCrossOriginResourcePolicy(builder => builder.SameSite())
    .AddCustomHeader("X-My-Custom-Header", "value");

app.UseSecurityHeaders(policies);
```

--------------------------------

### Example CSP Header

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Illustrates a Content-Security-Policy header that might be generated, including nonces and hashes.

```http
Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-ryPzmoZScSR2xOwV0qTU9mFdFwGPN+gy3S2E1/VK1vg=' 'strict-dynamic'; style-src 'self' 'sha256-[hash-of-style-content]' 'sha256-[hash-of-inline-style]' 'sha256-[hash-of-onclick]'; img-src 'self' data:
```

--------------------------------

### AddFrameSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for <frame> and <iframe> elements.

```csharp
builder.AddFrameSrc().Self().From("https://trusted-domain.com");
```

--------------------------------

### AddScriptSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for JavaScript.

```csharp
builder.AddScriptSrc()
    .Self()
    .From("https://cdn.example.com/js")
    .WithNonce();  // For nonce support
```

--------------------------------

### NonceTagHelper Example Usage

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Example of how to use the NonceTagHelper in Razor views to add a nonce attribute to script and style elements.

```html
<script asp-add-nonce>
    console.log("This script is allowed via nonce");
</script>

<style asp-add-nonce>
    body { color: blue; }
</style>
```

--------------------------------

### Data() Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Allows data: URIs.

```csharp
builder.AddImgSrc().Data()
```

--------------------------------

### AddConnectSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for fetch, XMLHttpRequest, WebSocket, and EventSource.

```csharp
builder.AddConnectSrc()
    .Self()
    .From("https://api.example.com")
    .OverHttps();
```

--------------------------------

### AddObjectSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for <object>, <embed>, and <applet> elements.

```csharp
builder.AddObjectSrc().None();
```

--------------------------------

### Integration Test Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/index.md

An example of an integration test to verify that the security headers middleware is applied.

```csharp
[TestClass]
public class SecurityHeadersTests
{
    [TestMethod]
    public async Task Middleware_AppliesSecurityHeaders()
    {
        using var factory = new WebApplicationFactory<Program>();
        var client = factory.CreateClient();
        
        var response = await client.GetAsync("/");
        
        Assert.IsTrue(response.Headers.Contains("X-Frame-Options"));
        Assert.IsTrue(response.Headers.Contains("X-Content-Type-Options"));
    }
}
```

--------------------------------

### HashTagHelper Example Usage

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Example of how to use the HashTagHelper in Razor views to add CSP hashes to inline script and style elements.

```html
<!-- Script with default SHA256 hash -->
<script asp-add-content-to-csp>
    console.log("Allowed via hash");
</script>

<!-- Style with SHA384 hash -->
<style asp-add-content-to-csp csp-hash-type="SHA384">
    body { margin: 0; }
</style>
```

--------------------------------

### NonceTagHelper Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Example of how to configure Content Security Policy to work with the NonceTagHelper.

```csharp
policies.AddContentSecurityPolicy(builder =>
{
    builder.AddScriptSrc().Self().WithNonce();
    builder.AddStyleSrc().Self().WithNonce();
});
```

--------------------------------

### None() Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Allows no content for this directive.

```csharp
builder.AddObjectSrc().None()
```

--------------------------------

### From(string url) Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Allows content from a specific URL or host.

```csharp
builder.AddScriptSrc().From("https://cdn.example.com")
```

--------------------------------

### Accessing Nonce via HttpContext

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Example of how to get the current request's nonce using an extension method on HttpContext.

```csharp
string nonce = HttpContext.GetNonce();
```

--------------------------------

### AddSandbox() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Applies sandbox restrictions to embedded content.

```csharp
builder.AddSandbox()
    .AllowScripts()
    .AllowSameOrigin();
```

--------------------------------

### Minimal Example with Customization

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/README.md

Add security headers middleware and include a custom header.

```csharp
var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.UseSecurityHeaders(policies =>
{
    policies
        .AddDefaultSecurityHeaders()
        .AddCustomHeader("X-Custom-Header", "value");
});

app.Run();
```

--------------------------------

### HashTagHelper Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

Example of how to configure Content Security Policy to work with the HashTagHelper.

```csharp
policies.AddContentSecurityPolicy(builder =>
{
    builder.AddScriptSrc().Self().WithHashTagHelper();
    builder.AddStyleSrc().Self().WithHashTagHelper();
});
```

--------------------------------

### Self() Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Allows content from the same origin.

```csharp
builder.AddScriptSrc().Self()
```

--------------------------------

### AddReportUri() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Specifies URI for CSP violation reports.

```csharp
builder.AddReportUri()
    .To("https://report-uri.com/example");
```

--------------------------------

### AddFontSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for @font-face fonts.

```csharp
builder.AddFontSrc().Self().From("https://fonts.googleapis.com");
```

--------------------------------

### AddChildSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for web workers and nested contexts.

```csharp
builder.AddChildSrc().Self();
```

--------------------------------

### ReportSample() Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Includes first 40 characters of blocked content in violation reports.

```csharp
builder.AddScriptSrc().ReportSample()
```

--------------------------------

### WithNonce() Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Enables nonce-based allowlisting (for use with tag helpers).

```csharp
builder.AddScriptSrc().WithNonce()
```

--------------------------------

### HashTagHelper for Scripts

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Example of using the HashTagHelper to allow-list script content via hashing.

```html
<script asp-add-content-to-csp>
    var msg = document.getElementById('message');
    msg.innerText = "I'm allowed";
</script>
```

--------------------------------

### RemoveCustomHeaderExtensions() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-extensions.md

Example of removing the X-Powered-By header.

```csharp
policies.RemoveCustomHeaderExtensions("X-Powered-By");

```

--------------------------------

### Named Policies Configuration via Direct Options

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Configures named security header policies directly using options.

```csharp
builder.Services.AddSecurityHeaderPolicies().
    SetDefaultPolicy(p => p.AddDefaultSecurityHeaders())
    .AddPolicy("CustomPolicy", p => p.AddCustomHeader("X-Custom", "value"));
```

--------------------------------

### HashTagHelper for Styles

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Example of using the HashTagHelper to allow-list style content via hashing, with SHA384 specified.

```html
<style asp-add-content-to-csp csp-hash-type="SHA384">
#message {
    color: @color;
}
</style>
```

--------------------------------

### StrictDynamic() Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Enables script nonce or hash-based allowlisting.

```csharp
builder.AddScriptSrc().StrictDynamic().WithNonce()
```

--------------------------------

### Middleware Registration Order

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/README.md

Example showing the correct order for registering the security headers middleware.

```csharp
app.UseSecurityHeaders();  // Should be first
app.UseStaticFiles();
app.UseRouting();
```

--------------------------------

### Content-Security-Policy Builder

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/README.md

Fluent API example for configuring Content Security Policy (CSP) directives.

```csharp
.AddContentSecurityPolicy(builder =>
{
    builder.AddUpgradeInsecureRequests();
    builder.AddDefaultSrc().Self();
    builder.AddScriptSrc().Self().WithNonce();
    builder.AddStyleSrc().Self().UnsafeInline();
    builder.AddFormAction().Self();
    builder.AddFrameAncestors().None();
})
```

--------------------------------

### WithHashTagHelper() Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Enables hash-based allowlisting for inline styles (for use with tag helpers).

```csharp
builder.AddStyleSrc().WithHashTagHelper()
```

--------------------------------

### AddGeolocation() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

Example of denying geolocation access.

```csharp
builder.AddGeolocation().None();
```

--------------------------------

### Debugging Headers with curl

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/index.md

Example of how to check security headers using curl.

```bash
curl -i https://example.com
```

--------------------------------

### Secure Defaults for Permissions-Policy

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Applies OWASP-recommended secure defaults for Permissions-Policy. It also shows how to override specific feature directives.

```csharp
// Quick setup with OWASP-recommended secure defaults
policies.AddPermissionsPolicyWithDefaultSecureDirectives();

// Or explicitly:
policies.AddPermissionsPolicy(builder =>
{
    builder.AddDefaultSecureDirectives();
    
    // Override specific features
    builder.AddCamera().Self();
    builder.AddMicrophone().Self();
});
```

--------------------------------

### Configure CSP with nonces and hashes

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Example of configuring Content Security Policy in ASP.NET Core to use nonces and hashes.

```csharp
public void Configure(IApplicationBuilder app)
{
    var policyCollection = new HeaderPolicyCollection()
        .AddContentSecurityPolicy(builder =>
        {
            builder.AddUpgradeInsecureRequests(); 
            builder.AddDefaultSrc() // default-src 'self' http://testUrl.com
                .Self()
                .From("http://testUrl.com");

            builder.AddScriptSrc() // script-src 'self' 'unsafe-inline' 'nonce-<base64-value>'
                .Self()
                .UnsafeInline()
                .WithNonce(); // Allow elements marked with a nonce attribute

            builder.AddStyleSrc() // style-src 'self' 'strict-dynamic' 'sha256-<base64-value>'
                .Self()
                .WithHashTagHelper().UnsafeHashes(); // Allow allowlisted elements based on their SHA256 hash value
        })
        .AddCustomHeader("X-My-Test-Header", "Header value");

    app.UseSecurityHeaders(policyCollection);

    // other middleware e.g. static files, MVC etc  
}
```

--------------------------------

### Build and Test Commands

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/AGENTS.md

Commands for building and testing the project using Nuke wrappers.

```bash
./build.sh
./build.sh Test
./build.sh Compile --configuration Release
```

--------------------------------

### HeaderPolicyCollection(IReadOnlyHeaderPolicyCollection) Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-policy-collection.md

Example of creating a custom policy by copying and extending a base policy.

```csharp
var basePolicy = new HeaderPolicyCollection()
    .AddDefaultSecurityHeaders();

var customPolicy = new HeaderPolicyCollection(basePolicy)
    .AddCustomHeader("X-Custom-Header", "value");
```

--------------------------------

### Static Named Policies Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Demonstrates how to configure static named security header policies. It sets a default policy and an additional policy named 'Api', then applies the default policy to the application and a specific policy to an endpoint.

```csharp
builder.Services.AddSecurityHeaderPolicies(policies =>
{
    policies.SetDefaultPolicy(p => p.AddDefaultSecurityHeaders());
    policies.AddPolicy("Api", p => p.AddDefaultApiSecurityHeaders());
});

var app = builder.Build();
app.UseSecurityHeaders(); // Uses default policy

// On endpoints:
app.MapGet("/api/data", GetData).WithSecurityHeadersPolicy("Api");
```

--------------------------------

### Example: Multi-Tenant Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/service-collection-extensions.md

Demonstrates a multi-tenant configuration for security headers, including setting a default policy, per-tenant policies, and a dynamic policy selector.

```csharp
var builder = WebApplication.CreateBuilder();

builder.Services.AddScoped<TenantService>();
builder.Services.AddSecurityHeaderPolicies((policies, provider) =>
{
    // Shared policy for all tenants
    var defaultPolicy = new HeaderPolicyCollection()
        .AddFrameOptionsDeny()
        .AddContentTypeOptionsNoSniff();

    policies.SetDefaultPolicy(defaultPolicy);

    // Per-tenant policies
    policies.AddPolicy("TenantA", p => p
        .AddDefaultSecurityHeaders()
        .AddCustomHeader("X-Tenant", "A"));

    policies.AddPolicy("TenantB", p => p
        .AddDefaultSecurityHeaders()
        .AddCustomHeader("X-Tenant", "B"));

    // Dynamic policy selection
    policies.SetPolicySelector(context =>
    {
        var tenantService = context.HttpContext.RequestServices.GetRequiredService<TenantService>();
        var tenantId = tenantService.GetCurrentTenantId(context.HttpContext);

        var policyName = $"Tenant{tenantId}";
        return context.ConfiguredPolicies[policyName];
    });
});

var app = builder.Build();
app.UseSecurityHeaders();
app.Run();
```

--------------------------------

### AddClearSiteData() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/header-extensions.md

Example usage of AddClearSiteData to clear cookies, storage, and execution contexts.

```csharp
policies.AddClearSiteData(builder =>
{
    builder.Cookies()
        .Storage()
        .ExecutionContexts();
});

```

--------------------------------

### Example for AddCustomFeature(string featureName)

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/permissions-policy-builder.md

Example usage of AddCustomFeature to add an 'iframe' feature.

```csharp
builder.AddCustomFeature("iframe")
    .Self()
    .For("https://trusted-domain.com");
```

--------------------------------

### Combined Usage Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/cross-origin-policies.md

Demonstrates combining Cross-Origin Opener Policy, Cross-Origin Embedder Policy, and Cross-Origin Resource Policy.

```csharp
policies
    // Prevent cross-origin windows from accessing this page
    .AddCrossOriginOpenerPolicy(builder =>
        builder.SameOrigin()
    )
    
    // Require explicit permission for cross-origin resources
    .AddCrossOriginEmbedderPolicy(builder =>
        builder.RequireCorp()
    )
    
    // Restrict this resource to same-site access
    .AddCrossOriginResourcePolicy(builder =>
        builder.SameSite()
    );

```

--------------------------------

### Razor Pages PageModel Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/endpoint-extensions.md

Example of applying a security header policy to a Razor Pages PageModel.

```csharp
// AdminPages/Dashboard.cshtml.cs
using Microsoft.AspNetCore.Mvc.RazorPages;
using NetEscapades.AspNetCore.SecurityHeaders;

[SecurityHeadersPolicy("AdminPolicy")]
public class DashboardModel : PageModel
{
    public void OnGet()
    {
        // Page logic
    }
}
```

--------------------------------

### Using AddDefaultSecurityHeaders for terser configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

This example shows a more concise way to configure security headers by using the AddDefaultSecurityHeaders() helper method along with a custom header.

```csharp
public void Configure(IApplicationBuilder app)
{
    var policyCollection = new HeaderPolicyCollection()
        .AddDefaultSecurityHeaders()
        .AddCustomHeader("X-My-Test-Header", "Header value");

    app.UseSecurityHeaders(policyCollection);

    // other middleware e.g. static files, MVC etc  
}
```

--------------------------------

### WithSecurityHeadersPolicy() Example Usage

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/endpoint-extensions.md

Example of applying security header policies to endpoints using the WithSecurityHeadersPolicy extension method.

```csharp
app.MapGet("/api/data", () => "Hello World")
    .WithSecurityHeadersPolicy("ApiPolicy");

app.MapPost("/admin/dashboard", AdminController.Dashboard)
    .WithSecurityHeadersPolicy("StrictPolicy");
```

--------------------------------

### Policy Resolution Order Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/endpoint-extensions.md

Demonstrates how to configure default policies, named policies, and a custom policy selector to control which security headers are applied to different endpoints.

```csharp
builder.Services.AddSecurityHeaderPolicies(policies =>
{
    policies.SetDefaultPolicy(p => p.AddDefaultSecurityHeaders());
    
    policies.AddPolicy("Api", p => p.AddDefaultApiSecurityHeaders());
    
    policies.SetPolicySelector(context =>
    {
        // This runs first and can override everything
        if (context.HttpContext.Request.Path.StartsWithSegments("/special"))
        {
            var policy = context.DefaultPolicy.Copy()
                .AddCustomHeader("X-Special", "true");
            return policy;
        }
        return null;  // Fall through to endpoint or default policy
    });
});

var app = builder.Build();
app.UseSecurityHeaders();

// The API endpoint gets the "Api" policy
app.MapGet("/api/data", () => "data")
    .WithSecurityHeadersPolicy("Api");

// The /special endpoint gets the selector's modified policy
app.MapGet("/special", () => "special");

// Other endpoints get the default policy
app.MapGet("/", () => "home");

app.Run();
```

--------------------------------

### Verify package provenance using GitHub CLI

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Commands to verify the provenance of NuGet packages using the GitHub CLI.

```bash
gh attestation verify --owner andrewlock "NetEscapades.AspNetCore.SecurityHeaders.1.3.1.nupkg"
gh attestation verify --owner andrewlock "NetEscapades.AspNetCore.SecurityHeaders.TagHelpers.1.3.1.nupkg"
```

--------------------------------

### AttributeHashTagHelper Configuration Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/tag-helpers.md

C# code snippet showing how to configure Content-Security-Policy to allow hashed styles and scripts using the AttributeHashTagHelper.

```csharp
policies.AddContentSecurityPolicy(builder =>
{
    builder.AddStyleSrc().Self().UnsafeHashes();
    builder.AddScriptSrc().Self().UnsafeHashes();
});
```

--------------------------------

### AddCustomDirective() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Adds an arbitrary CSP directive.

```csharp
builder.AddCustomDirective("plugin-types", "application/x-shockwave-flash");
```

--------------------------------

### Verify SBOM attestations using GitHub CLI

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Commands to verify SBOM attestations for NuGet packages using the GitHub CLI, specifying the CycloneDX predicate type.

```bash
gh attestation verify --owner andrewlock --predicate-type https://cyclonedx.org/bom "NetEscapades.AspNetCore.SecurityHeaders.1.3.1.nupkg"
gh attestation verify --owner andrewlock --predicate-type https://cyclonedx.org/bom "NetEscapades.AspNetCore.SecurityHeaders.TagHelpers.1.3.1``.nupkg"
```

--------------------------------

### AttributeHashTagHelper for Style Attribute

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/README.md

Example of using the AttributeHashTagHelper to hash the 'style' attribute.

```html
<h3 asp-add-csp-for-style style="color: red">I will be styled red</h3>
```

--------------------------------

### OverHttps() Source Specification Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Allows content only over HTTPS.

```csharp
builder.AddImgSrc().OverHttps()
```

--------------------------------

### MVC with Attributes Endpoint Configuration

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/configuration.md

Applying specific security header policies to MVC controllers and actions using attributes.

```csharp
[ApiController]
[Route("api")]
[SecurityHeadersPolicy("Api")]  // Applied to all actions
public class ApiController : ControllerBase
{
    [HttpGet("data")]
    public IActionResult GetData() { }

    [HttpPost("data")]
    [SecurityHeadersPolicy("StrictPolicy")]  // Override for this action
    public IActionResult CreateData() { }
}
```

--------------------------------

### AddBaseUri() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Restricts valid URLs for `<base>` element.

```csharp
builder.AddBaseUri().Self();
```

--------------------------------

### Example: Configuring Security Headers with Service Provider Access

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/service-collection-extensions.md

Demonstrates how to register a custom service and then use it within the security header policy configuration to dynamically set HSTS max age.

```csharp
var builder = WebApplication.CreateBuilder();

// Register a custom tenant service
builder.Services.AddScoped<ITenantService, TenantService>();

// Configure policies based on tenant settings
builder.Services.AddSecurityHeaderPolicies((policies, provider) =>
{
    var tenantService = provider.GetRequiredService<ITenantService>();
    var maxAge = tenantService.GetHstsMaxAge();

    policies.SetDefaultPolicy(p => p
        .AddStrictTransportSecurityMaxAgeIncludeSubDomains(maxAgeInSeconds: maxAge)
        .AddDefaultSecurityHeaders());
});

var app = builder.Build();
app.UseSecurityHeaders();
app.Run();
```

--------------------------------

### AddFrameAncestors() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Controls which origins can embed the document in a frame.

```csharp
builder.AddFrameAncestors().None();
```

--------------------------------

### AddWorkerSrc() Example

Source: https://github.com/andrewlock/netescapades.aspnetcore.securityheaders/blob/main/_autodocs/api-reference/csp-builder.md

Valid sources for Worker, SharedWorker, and ServiceWorker.

```csharp
builder.AddWorkerSrc().Self();
```