Security

Browser interaction
-> Heimdall request
-> server action
-> HTML response
-> DOM update

Security boundaries still matter at every step

// Default-enabled Heimdall setup
// If your app uses authentication:
builder.Services.AddAuthentication(/* scheme */);
builder.Services.AddAuthorization();

builder.Services.AddAntiforgery();

var app = builder.Build();

// Keep auth before antiforgery when both are present.
app.UseAuthentication();
app.UseAuthorization();
app.UseAntiforgery();
app.UseHeimdall();

GET /__heimdall/v1/csrf
-> requestToken returned
-> runtime caches token
-> token sent on later Heimdall requests

request fails with 400
-> response suggests csrf / antiforgery failure
-> cached token cleared
-> token fetched again
-> request retried once

EnableAntiforgery = true
GET /__heimdall/v1/bifrost/token?topic=...
+ antiforgery validation
-> short-lived subscribe token returned

EnableAntiforgery = false
-> antiforgery validation skipped
-> signed subscribe token + authorization still apply

[Authorize(Roles = "Admin")]
[ContentInvocation("admin.refresh")]
public static IHtmlContent RefreshAdminPanel(HttpContext ctx)
{
    return AdminPanel.Render(ctx.User);
}

builder.Services.AddHeimdall(options =>
{
    options.BifrostTopicPolicy = "BifrostTopic";
    options.AuthorizeBifrostTopic = (ctx, topic) =>
        ValueTask.FromResult(topic.StartsWith("user:"));
});

public sealed class TopicHandler
    : AuthorizationHandler<TopicRequirement, BifrostTopicResource>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        TopicRequirement requirement,
        BifrostTopicResource resource)
    {
        var topic = resource.Topic;
        var user = resource.HttpContext.User;
        return Task.CompletedTask;
    }
}

Auth redirect handling:
- content actions watch for followed redirects
- Bifrost token fetches watch for followed redirects
- 401 / 403 responses with Location are also handled
- ReturnUrl matching is case-insensitive
- the original parameter casing is preserved

/signin?returnUrl=/__heimdall/v1/content/actions
-> /signin?returnUrl=/current-page

Sanitized by the runtime:
- action response HTML
- OOB payload fragments
- error HTML flowing through Heimdall response handling

Initial page load:
- normal browser HTML parsing
- not sanitized by the Heimdall runtime

Heimdall response swap:
- sanitized by the Heimdall runtime before insertion

container.Add(StaticAssets.Get("fragments/home/hero.html"));

// Writes raw markup directly into the response

StaticAssets -> server emits raw HTML

If used in full page render:
-> sent directly to browser
-> normal page trust model applies

If used in Heimdall response:
-> response handled by the Heimdall runtime
-> script tags removed before insertion

Safe usage:
- app-owned fragments
- known markup shipped with the app

Context matters:
- full page render -> no runtime sanitization
- Heimdall response -> runtime sanitization applies

Not safe:
- user HTML
- untrusted third-party markup

OOB response
-> invocation target resolved
-> payload fragment extracted
-> script tags removed
-> target updated
-> invocation node removed

// Default:
Heimdall.config.oobEnabled = true

// Optional stricter mode:
Heimdall.config.oobEnabled = false

Request authenticity -> antiforgery for cookie auth,
                        or an intentional alternative
Server-owned markup  -> trust boundary
Runtime insertion    -> script stripping
App architecture     -> smallest possible trust surface

Initial page HTML
-> normal server trust boundary

Later Heimdall HTML
-> runtime insertion boundary
-> additional sanitization applied

ASP.NET Core security primitives
+ explicit trust boundaries
+ runtime insertion guardrails
-> secure HTML-first interaction model

using Microsoft.AspNetCore.Antiforgery;

// DEFAULT-ENABLED SETUP
builder.Services.AddAntiforgery();
builder.Services.AddHeimdall();

var protectedApp = builder.Build();
protectedApp.UseAntiforgery();
protectedApp.UseHeimdall();

// Narrow exception; the rest of Heimdall stays protected.
[RequireAntiforgeryToken(false)]
[ContentInvocation("public.preview")]
public static IHtmlContent Preview(PreviewRequest request)
    => PreviewPanel.Render(request);

// ALTERNATIVE: GLOBAL OPT-OUT
var noCsrfBuilder = WebApplication.CreateBuilder(args);
noCsrfBuilder.Services.AddHeimdall(options =>
    options.EnableAntiforgery = false);

var noCsrfApp = noCsrfBuilder.Build();
noCsrfApp.UseHeimdall();
// No AddAntiforgery() or UseAntiforgery()
// is required by Heimdall in this mode.

// Set before the first action or SSE subscription.
Heimdall.config.antiforgery = false;

EnableAntiforgery = true
-> content actions validate a token unless overridden
-> Bifrost token minting validates a token
-> Heimdall.config.antiforgery stays true

EnableAntiforgery = false
-> both token checks are skipped
-> Heimdall.config.antiforgery must be false
-> authentication and topic authorization still apply

const string FrontendPolicy = "HeimdallFrontend";

builder.Services.AddCors(options =>
{
    options.AddPolicy(FrontendPolicy, policy => policy
        .WithOrigins("https://app.example.com")
        .WithMethods("GET", "POST")
        .WithHeaders(
            "Content-Type",
            "Authorization",
            "X-Heimdall-Content-Action",
            // Include only while antiforgery is enabled.
            "RequestVerificationToken",
            "X-Heimdall-Client-Info"));
});

var app = builder.Build();
app.UseRouting();
app.UseCors(FrontendPolicy);
app.UseAuthentication();
app.UseAuthorization();
// Required only while Heimdall antiforgery is enabled.
app.UseAntiforgery();
app.UseHeimdall();

Heimdall.config.requestHeaders = async context => ({
  Authorization: `Bearer ${await auth.getToken({
    signal: context.signal
  })}`
});

// Cross-origin cookie auth is not enabled by this alone:
policy.AllowCredentials();

X-Heimdall-Content-Action  action routing
RequestVerificationToken  antiforgery when enabled
X-Heimdall-Client-Info     optional browser context
Authorization             application opt-in header
Content-Type              JSON or multipart request

Troubleshoot in order:
1. exact Origin is allowed
2. OPTIONS returns allowed method and headers
3. middleware order is CORS, auth, authorization,
   antiforgery when enabled, then Heimdall
4. JWT audience/issuer or antiforgery token is valid
5. browser request reaches the content endpoint