AsiBackbone.AspNetCore 7.2.0

AsiBackbone.AspNetCore

ASP.NET Core host adapters for AsiBackbone governance primitives.

Part of the stable 7.x package family. This README describes version 7.2.0 of this package.

This package acts as a thin web-host adapter around AsiBackbone.Core.

New to AsiBackbone? Start with the concept, not this package: Intent to Execution: An Accountability Pattern and the documentation site. This README covers one package in the family.

Important: This package provides host adapters only. Low-level helpers do not enforce decisions automatically; endpoint-governance middleware acts only when the host explicitly adds it to the pipeline and registers the required host-owned policy, capability, audit, persistence, and transaction services. Attributes and route-builder calls do not by themselves make audit records durable, immutable, tamper-evident, or transactionally safe.

Service registration

Register the ASP.NET Core integration package from a plain ASP.NET Core host through IServiceCollection.

using AsiBackbone.AspNetCore.DependencyInjection;

builder.Services.AddAsiBackboneAspNetCore();

Host applications may configure the integration options explicitly.

builder.Services.AddAsiBackboneAspNetCore(options =>
{
    options.IncludeRouteValues = true;
    options.IncludeEndpointMetadata = true;
    options.IncludeRequestMethod = true;
    options.IncludeRequestPath = false;
    options.TrustInboundCorrelationIdHeaders = true;
    options.CorrelationIdHeaderNames = ["X-Correlation-ID", "X-Request-ID"];
});

The base registration is intentionally narrow. It does not register persistence, EF Core, authentication handlers, MVC, Razor Pages, Minimal API endpoints, policy evaluators, capability grant validators, or host-specific authorization behavior.

Ergonomic endpoint governance

UseAsiBackboneEndpointGovernance() evaluates AsiBackbone endpoint metadata before endpoint execution.

using AsiBackbone.AspNetCore.Endpoints;

app.UseAsiBackboneEndpointGovernance();

app.MapPost("/high-risk-action", handler)
    .MarkGovernancePolicy<MyStrictPolicy>()
    .RequireAcknowledgment()
    .RequireCapabilityGrant("robotics.execute")
    .EmitGovernanceAudit();

Controller/action attributes are also available:

[GovernancePolicy(typeof(MyStrictPolicy))]
[RequireAcknowledgment]
[RequireCapabilityGrant("robotics.execute")]
[EmitGovernanceAudit]
public IActionResult ExecuteHighRiskAction()
{
    return Ok();
}

The metadata layer is optional and ergonomic. It does not replace full manual wire-up. Hosts that attach policy metadata should register an IGovernancePolicyEvaluator<GovernanceEvaluationContext>. Hosts that attach capability metadata should register an IEndpointCapabilityGrantValidator. Hosts that request audit emission should register a host-owned IDecisionReceiptSink.

Hosted outbox drain

AddAsiBackboneGovernanceOutboxDrainWorker registers a host-owned background worker that runs the provider-neutral Core GovernanceOutboxDrain through dependency injection.

using AsiBackbone.AspNetCore.DependencyInjection;
using AsiBackbone.Core.Emissions;
using AsiBackbone.Core.Outbox;
using AsiBackbone.Storage.InMemory.Outbox;

builder.Services.AddSingleton<IGovernanceOutboxStore, InMemoryGovernanceOutboxStore>();
builder.Services.AddSingleton<IGovernanceEmitter>(NoOpGovernanceEmitter.Instance);

builder.Services.Configure<GovernanceOutboxOptions>(options =>
{
    options.RetryDelay = TimeSpan.FromMinutes(2);
    options.DeferredDelay = TimeSpan.FromMinutes(5);
});

builder.Services.AddAsiBackboneGovernanceOutboxDrainWorker(options =>
{
    options.BatchSize = 25;
    options.PollingInterval = TimeSpan.FromSeconds(15);
});

GovernanceOutboxOptions controls persisted retry timing when an emitter does not supply its own RetryAfterUtc. RetryDelay applies to unexpected emitter exceptions converted to retryable failures. DeferredDelay applies to pending/deferred emission results without a retry-after timestamp. Both default to one minute to preserve the original drain behavior.

The worker resolves the drain from a scoped service provider so host-owned durable stores can depend on scoped infrastructure such as EF Core DbContext instances. Production hosts should avoid duplicate active drain workers against the same durable outbox unless their store implements leasing, row claiming, partitioning, or provider-side idempotency.

Request correlation and audit enrichment

IHttpGovernanceRequestCorrelationResolver resolves request correlation data from the current HttpContext without making Core depend on ASP.NET Core types.

The default resolver:

• ignores caller-controlled correlation headers;
• falls back to HttpContext.TraceIdentifier when header trust is disabled or no valid trusted header is present;
• captures a trace identifier from Activity.Current or the ASP.NET Core trace identifier;
• always records the server-owned HttpContext.TraceIdentifier as http.trace_identifier metadata;
• emits safe request metadata such as method, route pattern, endpoint display name, and route values;
• excludes sensitive request data such as headers, query strings, request bodies, cookies, and tokens by default.

Set TrustInboundCorrelationIdHeaders to true only behind a trusted ingress that removes caller-supplied values for the configured headers and writes its own correlation identifier. Opted-in values are trimmed and accepted only when printable and no longer than GovernanceIdentifierLimits.MaximumLength. Invalid values are discarded in full rather than truncated or partially sanitized. Do not enable header trust for requests received directly from untrusted callers, because doing so lets a caller choose the audit correlation key.

Example usage:

using AsiBackbone.AspNetCore.Correlation;
using AsiBackbone.Core.Audit;

GovernanceHttpRequestCorrelation correlation = correlationResolver.ResolveRequestCorrelation();

DecisionReceipt receipt = correlation.CreateDecisionReceipt(
    actor,
    "ApproveWidget",
    decision);

Use GovernanceHttpRequestCorrelation.ToEvaluationContext(...) when a web host needs to carry the resolved correlation identifier and safe request metadata into a framework-neutral Core policy evaluation context.

HTTP result mapping

GovernanceHttpResultMappingExtensions maps Core GovernanceDecision and OperationResult instances into ASP.NET Core IResult responses through explicit helpers.

using AsiBackbone.AspNetCore.Results;
using AsiBackbone.Core.Decisions;

GovernanceDecision decision = GovernanceDecision.Deny(
    "policy.denied",
    "Internal policy detail for audit only.",
    correlationId: "request-123");

return decision.ToHttpResult();

Default governance decision mapping:

Default operation-result mapping:

Reason codes and correlation identifiers are preserved by default when available. Reason messages, trace identifiers, policy versions, and policy hashes are not exposed by default because those values may reveal sensitive policy internals or diagnostic details.