OwnershipGuard 0.3.0

OwnershipGuard

OwnershipGuard is an ASP.NET Core library that enforces ownership checks and optional tenant checks before endpoint or MVC action execution. It centralizes resource access validation by route id and helps prevent IDOR and broken access control caused by missing per-endpoint checks.

Requirements

• .NET 8
• ASP.NET Core 8

Installation

dotnet add package OwnershipGuard

<PackageReference Include="OwnershipGuard" Version="x.y.z" />

Quick Start

1. Register services.

using System.Security.Claims;

builder.Services.AddOwnershipGuard(options =>
{
    options.UserIdClaimType = ClaimTypes.NameIdentifier;
    options.TenantIdClaimType = "tenant_id";
    options.UseProblemDetailsResponses = true;
    options.HideExistenceWhenForbidden = false;
    // Optional AccessProof feature:
    // options.AccessProof.Enabled = true;
});

2. Register descriptors after builder.Build().

var app = builder.Build();
var registry = app.Services.GetRequiredService<IOwnershipDescriptorRegistry>();

// String key + ownership check
registry.Register<Note>(
    sp => sp.GetRequiredService<YourDbContext>().Notes,
    n => n.Id,
    n => n.OwnerId);

// Typed key (Guid) + ownership + tenant check
registry.Register<Document, Guid>(
    sp => sp.GetRequiredService<YourDbContext>().Documents,
    d => d.Id,
    d => d.OwnerId,
    tenantSelector: d => d.TenantId);

3. Apply the check to endpoints.

Minimal API:

app.MapGet("/documents/{id}", ...).RequireOwnership<Document>("id");
app.MapPut("/documents/{id}", ...).RequireOwnership<Document>("id");

MVC:

[ApiController]
[Route("documents")]
[RequireOwnership("id", typeof(Document))]
public sealed class DocumentsController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(string id) => Ok();
}

AccessProof (Optional)

AccessProof issues a short-lived signed token after successful ownership checks. On the next matching request, filter can validate this token and skip DB ownership lookup.

builder.Services.AddDistributedMemoryCache(); // or a real distributed cache provider

builder.Services.AddOwnershipGuard(options =>
{
    options.AccessProof.Enabled = true;
    options.AccessProof.EmitResponseHeader = false;
});

Forwarding to trusted downstream services:

builder.Services
    .AddHttpClient("downstream")
    .AddOwnershipProofForwarding();

Defaults:

• Enabled = false
• HeaderName = "X-Ownership-Proof"
• TokenTtl = 2 minutes
• EmitResponseHeader = false
• Invalid/missing proof falls back to normal ownership DB check

Fail-fast:

• If AccessProof.Enabled = true and IDistributedCache is not registered, startup throws an InvalidOperationException.

Response Behavior

Startup Validation (Fail-Fast)

OwnershipGuard validates ownership descriptors during startup.

• Minimal API endpoints are validated when configured with .RequireOwnership<TEntity>("id").
• MVC actions are validated when decorated with [RequireOwnership(...)].
• If a required descriptor is missing, app startup fails with InvalidOperationException and endpoint details.

Plugin Model

OwnershipGuard plugins let you package descriptor registration in reusable modules. Plugins run during app startup before fail-fast descriptor validation.

public sealed class DocumentsOwnershipPlugin : IOwnershipGuardPlugin
{
    public Task ConfigureAsync(OwnershipGuardPluginContext context, CancellationToken cancellationToken = default)
    {
        context.DescriptorRegistry.Register<Document, Guid>(
            sp => sp.GetRequiredService<AppDbContext>().Documents,
            d => d.Id,
            d => d.OwnerId,
            tenantSelector: d => d.TenantId);

        return Task.CompletedTask;
    }
}

builder.Services
    .AddOwnershipGuard()
    .AddOwnershipGuardPlugin<DocumentsOwnershipPlugin>();

Analyzer Rules & Migration

OwnershipGuard ships with built-in Roslyn guardrails to enforce canonical wiring patterns in IDE and CI.

• OG1001 (Error): flags raw Minimal API ownership wiring through .AddEndpointFilter(...) when RequireOwnershipFilter is used.
  • Preferred form: .RequireOwnership<TEntity>("id")
• OG1002 (Error): flags raw MVC ownership wiring through [TypeFilter(...)] / [ServiceFilter(...)] with RequireOwnershipActionFilter.
  • Preferred form: [RequireOwnership("id", typeof(TEntity))]

You can suppress rules per standard Roslyn flow (.editorconfig, NoWarn) when needed.

Minimal API migration example:

// before
app.MapGet("/documents/{id}", ...).AddEndpointFilter(new RequireOwnershipFilter("id", typeof(Document)));

// after
app.MapGet("/documents/{id}", ...).RequireOwnership<Document>("id");

MVC migration example:

// before
[TypeFilter(typeof(RequireOwnershipActionFilter), Arguments = new object[] { "id", typeof(Document) })]

// after
[RequireOwnership("id", typeof(Document))]

Configuration

Optional error message overrides (when set, used as ProblemDetails.Title; when null, built-in defaults are used): MissingResourceIdMessage, InvalidResourceIdInRouteMessage, UnauthorizedMessage, TenantNotSpecifiedMessage, InvalidResourceIdMessage, NotFoundMessage, ForbiddenMessage, DescriptorNotRegisteredMessage. Useful for i18n or custom wording.

Optional Query Helpers

using OwnershipGuard.EntityFrameworkCore;

var ownedDocs = await db.Documents
    .WhereOwnedBy(userId, d => d.OwnerId)
    .ToListAsync();

var tenantDocs = await db.Documents
    .WhereTenant(tenantId, d => d.TenantId)
    .ToListAsync();

Non-Goals

OwnershipGuard does not implement:

• Authentication
• Authorization policy systems (RBAC)
• Rate limiting
• Input validation

License

MIT. See LICENSE.