|
| 1 | +# OwnershipGuard |
| 2 | + |
| 3 | +[](https://www.nuget.org/packages/OwnershipGuard/) |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +## Requirements |
| 8 | + |
| 9 | +- .NET 8 |
| 10 | +- ASP.NET Core 8 |
| 11 | + |
| 12 | +## Installation |
| 13 | + |
| 14 | +```bash |
| 15 | +dotnet add package OwnershipGuard |
| 16 | +``` |
| 17 | + |
| 18 | +```xml |
| 19 | +<PackageReference Include="OwnershipGuard" Version="x.y.z" /> |
| 20 | +``` |
| 21 | + |
| 22 | +## Quick Start |
| 23 | + |
| 24 | +1. Register services. |
| 25 | + |
| 26 | +```csharp |
| 27 | +using System.Security.Claims; |
| 28 | + |
| 29 | +builder.Services.AddOwnershipGuard(options => |
| 30 | +{ |
| 31 | + options.UserIdClaimType = ClaimTypes.NameIdentifier; |
| 32 | + options.TenantIdClaimType = "tenant_id"; |
| 33 | + options.UseProblemDetailsResponses = true; |
| 34 | + options.HideExistenceWhenForbidden = false; |
| 35 | +}); |
| 36 | +``` |
| 37 | + |
| 38 | +2. Register descriptors after `builder.Build()`. |
| 39 | + |
| 40 | +```csharp |
| 41 | +var app = builder.Build(); |
| 42 | +var registry = app.Services.GetRequiredService<IOwnershipDescriptorRegistry>(); |
| 43 | + |
| 44 | +// String key + ownership check |
| 45 | +registry.Register<Note>( |
| 46 | + sp => sp.GetRequiredService<YourDbContext>().Notes, |
| 47 | + n => n.Id, |
| 48 | + n => n.OwnerId); |
| 49 | + |
| 50 | +// Typed key (Guid) + ownership + tenant check |
| 51 | +registry.Register<Document, Guid>( |
| 52 | + sp => sp.GetRequiredService<YourDbContext>().Documents, |
| 53 | + d => d.Id, |
| 54 | + d => d.OwnerId, |
| 55 | + tenantSelector: d => d.TenantId); |
| 56 | +``` |
| 57 | + |
| 58 | +3. Apply the check to endpoints. |
| 59 | + |
| 60 | +Minimal API: |
| 61 | + |
| 62 | +```csharp |
| 63 | +var documentOwnership = new RequireOwnershipFilter("id", typeof(Document)); |
| 64 | +app.MapGet("/documents/{id}", ...).AddEndpointFilter(documentOwnership); |
| 65 | +app.MapPut("/documents/{id}", ...).AddEndpointFilter(documentOwnership); |
| 66 | +``` |
| 67 | + |
| 68 | +MVC: |
| 69 | + |
| 70 | +```csharp |
| 71 | +[ApiController] |
| 72 | +[Route("documents")] |
| 73 | +[RequireOwnership("id", typeof(Document))] |
| 74 | +public sealed class DocumentsController : ControllerBase |
| 75 | +{ |
| 76 | + [HttpGet("{id}")] |
| 77 | + public IActionResult Get(string id) => Ok(); |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +## Response Behavior |
| 82 | + |
| 83 | +| Status | Condition | |
| 84 | +|--------|-----------| |
| 85 | +| `400 Bad Request` | Route id is missing or empty, or typed key parsing fails (for `Register<T, TKey>`). | |
| 86 | +| `401 Unauthorized` | User claim is missing, or tenant claim is missing when a tenant-aware descriptor is used. | |
| 87 | +| `403 Forbidden` | Resource exists but ownership or tenant check fails, and `HideExistenceWhenForbidden` is `false`. | |
| 88 | +| `404 Not Found` | Resource does not exist, or ownership/tenant check fails when `HideExistenceWhenForbidden` is `true`. | |
| 89 | +| `500 Internal Server Error` | Descriptor is not registered for the requested entity type. | |
| 90 | + |
| 91 | +## Configuration |
| 92 | + |
| 93 | +| Option | Default | Description | |
| 94 | +|--------|---------|-------------| |
| 95 | +| `UserIdClaimType` | `ClaimTypes.NameIdentifier` | Claim type used to resolve the current user id. | |
| 96 | +| `TenantIdClaimType` | `"tenant_id"` | Claim type used to resolve the current tenant id when tenant checks are required. | |
| 97 | +| `UseProblemDetailsResponses` | `true` | When `true`, filters return ProblemDetails payloads for errors. When `false`, filters return plain status responses. | |
| 98 | +| `HideExistenceWhenForbidden` | `false` | When `true`, failed ownership/tenant checks return `404`; otherwise they return `403`. | |
| 99 | + |
| 100 | +## Optional Query Helpers |
| 101 | + |
| 102 | +```csharp |
| 103 | +using OwnershipGuard.EntityFrameworkCore; |
| 104 | + |
| 105 | +var ownedDocs = await db.Documents |
| 106 | + .WhereOwnedBy(userId, d => d.OwnerId) |
| 107 | + .ToListAsync(); |
| 108 | + |
| 109 | +var tenantDocs = await db.Documents |
| 110 | + .WhereTenant(tenantId, d => d.TenantId) |
| 111 | + .ToListAsync(); |
| 112 | +``` |
| 113 | + |
| 114 | +## Non-Goals |
| 115 | + |
| 116 | +OwnershipGuard does not implement: |
| 117 | + |
| 118 | +- Authentication |
| 119 | +- Authorization policy systems (RBAC) |
| 120 | +- Rate limiting |
| 121 | +- Input validation |
| 122 | + |
| 123 | +## Build, Test, and Pack |
| 124 | + |
| 125 | +```bash |
| 126 | +dotnet build OwnershipGuard.sln -c Release |
| 127 | +dotnet test -c Release |
| 128 | +dotnet pack -c Release src/OwnershipGuard/OwnershipGuard.csproj |
| 129 | +``` |
| 130 | + |
| 131 | +NuGet publish checklist: [NUGET_PUBLISH.md](NUGET_PUBLISH.md) |
| 132 | + |
| 133 | +## License |
| 134 | + |
| 135 | +MIT. See [LICENSE](LICENSE). |
0 commit comments