Extrode.NativeWeb.Permissions
0.1.0
See the version list below for details.
dotnet add package Extrode.NativeWeb.Permissions --version 0.1.0
NuGet\Install-Package Extrode.NativeWeb.Permissions -Version 0.1.0
<PackageReference Include="Extrode.NativeWeb.Permissions" Version="0.1.0" />
<PackageVersion Include="Extrode.NativeWeb.Permissions" Version="0.1.0" />
<PackageReference Include="Extrode.NativeWeb.Permissions" />
paket add Extrode.NativeWeb.Permissions --version 0.1.0
#r "nuget: Extrode.NativeWeb.Permissions, 0.1.0"
#:package Extrode.NativeWeb.Permissions@0.1.0
#addin nuget:?package=Extrode.NativeWeb.Permissions&version=0.1.0
#tool nuget:?package=Extrode.NativeWeb.Permissions&version=0.1.0
nativeweb.permissions
Per-model, per-operation permissions with groups. Decorate a model; the generated admin enforces four permissions it never made you name.
This project is the runtime half: the attributes, the Permission struct, the endpoint
filter, the per-request held set, the IPermissionStore seam and the access admin. The
build-time half is libs/nativeweb.permissions.generator, which emits one constant per
permission and the catalog. A consumer references both:
<ProjectReference Include="..\..\libs\nativeweb.permissions\nativeweb.permissions.csproj" />
<ProjectReference Include="..\..\libs\nativeweb.permissions.generator\nativeweb.permissions.generator.csproj"
OutputItemType="Analyzer"
ReferenceOutputAssembly="false" />
The whole API
[assembly: PermissionScope("sample")]
[Scaffold(Display = "Articles", Route = "articles")]
[Auth(Role = "admin")]
[Permissions]
public sealed class Article { /* ... */ }
That is the declaration. It produces four names — sample:article.view, .add, .change,
.delete — reached as ArticlePermissions.View, .Add, .Change, .Delete, and collected in
PermissionCatalog.All.
| Type | Where | What it does |
|---|---|---|
[PermissionScope("x")] |
assembly | The {scope} half of every name in this assembly. Two assemblies declaring Article produce different permissions |
[Permissions] |
class | The four. [Permissions("publish")] adds a fifth that gates nothing by itself |
Permission |
struct | One name. Every API takes this, never a string, which is what makes a removed declaration a build error |
IPermissions.AllowsAsync |
injected | The one call a hand-written endpoint makes |
IPermissionContext.HeldAsync |
injected | The subject's whole held set, one store read per subject |
PermissionEndpointFilter |
filter | What the scaffolding appends to each generated route, and what you add to gate your own |
IPermissionStore |
seam | Where grants live. You implement it, or take InMemoryPermissionStore |
MapAccessAdmin |
endpoints | Groups, members and grants, as pages |
Wiring
builder.Services.AddPermissions(PermissionCatalog.All);
builder.Services.AddSingleton<IPermissionStore>(sp => new MyPermissionStore(/* ... */));
app.MapScaffolding();
app.MapAccessAdmin("/admin", ScaffoldLayout.Page, ScaffoldLayout.AntiforgeryField)
.RequireAuthorization(policy => policy.RequireRole("admin"));
The catalog is passed rather than discovered: an assembly scan would make the set of declared permissions depend on what happened to be loaded.
MapAccessAdmin takes the page shell and the antiforgery field as delegates, and returns the
group ungated. It cannot name ScaffoldLayout, which is generated into your assembly, and it
does not choose its own gate because the gate is the host's decision.
Your pipeline must call app.UseAntiforgery(). Each of the seven posts carries
IAntiforgeryMetadata, so the middleware validates the token the field delegate renders, and
routing refuses the request outright if that middleware is absent, rather than letting an
unvalidated post through. UseNativeWebPipeline already does this; a host wiring its
own pipeline calls it after UseAuthentication and UseAuthorization.
Naming the subject
The subject is the NameIdentifier claim by default. A JWT bearer scheme configured not to map
inbound claims leaves sub as sub, and such a host says so:
builder.Services.AddPermissions(PermissionCatalog.All, options => options.ClaimName = "sub");
A subject that is not any one claim comes from a function instead:
builder.Services.AddPermissions(
PermissionCatalog.All,
options => options.Resolve = user => user.FindFirstValue("tenant") + ":" + user.FindFirstValue("sub"));
| Both configured | Refused at registration, so the application does not start |
| Anonymous principal | No subject, no store call, nothing logged: a public page is not a fault |
| Empty or whitespace answer | No subject, and no blank row in the store |
| Anything else | Handed to the store as it came back — nothing is trimmed or lower-cased |
Whatever comes back is the key of every grant row, every membership and every subject record, so a normalisation applied here would have to be applied identically by every store, every migration and every operator typing a subject into the access admin.
An authenticated principal that yields no subject is logged once per request, at warning. The message names what was looked for and which scheme authenticated the caller, never the claim values: a subject identifies a person, and a diagnostic carrying it would hand every product on this layer a retention question of its own.
A hand-written endpoint
A model needs no generated admin for any of this to work. Given
[Permissions("publish")] on Article:
app.MapPost("/articles/{id}/publish", async (string id, IPermissions permissions, HttpContext http) =>
await permissions.AllowsAsync(http.User, ArticlePermissions.Publish, id)
? Results.Ok()
: Results.Forbid());
Or the same gate as metadata, which is what the scaffolding does:
app.MapPost("/articles/{id}/publish", Publish)
.AddEndpointFilter(new PermissionEndpointFilter(ArticlePermissions.Publish, "id"));
What the store owes you
IPermissionStore is sixteen methods over five tables. apps/sample/JauntyPermissionStore.cs is
a worked implementation over PostgreSQL through JauntyQ, and
docs/specs/024-model-permissions/024-schema.sql is the DDL it expects, kept as a reference
nothing applies.
The schema is yours, not the framework's. NativeWeb ships no migration runner and creates no table. An application adopting this layer stamps the five tables and writes the store.
You must seed the first operator
A fresh database has nobody holding a permission, so nobody can reach the access admin to make
the first grant, so the admin is unreachable forever. Every application on this layer seeds its
own first subject; db/sample/migrations/0006_permissions.sql is the sample's, and the subject
it names is a value you look up from your provider, not a name you can guess.
Removing a group or a subject
Two destructive controls sit on the access admin, one on each detail page, and both are irreversible from the UI:
| Control | Route | What goes |
|---|---|---|
| Delete this group | POST /admin/access/groups/{id}/delete |
The group, every membership in it and every grant made to it. Members keep their own direct grants |
| Forget this subject | POST /admin/access/subjects/{subject}/delete |
The subject row, its direct grants and every group membership it holds. The groups themselves survive |
Each control names the counts it is about to remove, and each posts through the antiforgery
filter behind a confirmation. A post naming a group or subject that has gone since the page
rendered is a 409, not a silent success: DeleteGroupAsync and ForgetSubjectAsync both raise
PermissionConflictException when nothing was removed, in both shipped stores.
Forgetting a subject is not a ban. The next request that authenticates it writes the subject
row again through EnsureSubjectAsync, holding nothing. What the delete removes is the grants,
not the identity, which this layer does not own.
What it deliberately does not do
No identity. The subject is the
NameIdentifierclaim, whatever issued it. No credential, no profile field, no user table. The identity provider owns identity; this reads a string. Nothing here depends onnativeweb.signin.Which claim is configurable — see Naming the subject below. A host whose scheme surfaces the subject under another name says so once at registration. A host that does not, and whose scheme does not use NameIdentifier, gets no subject, which is the empty held set, which is a 403 from every gated route — now with one warning per request naming the claim that was looked for.
No row-level decisions.
AllowsAsyncand the filter both accept a resource identity and carry it to the store, and neither shipped store consults it. The decision is per model. That is what makes the held set one call per request instead of one per row — and the visible consequence is that a store which later grants per row would draw an Edit control on a row the subject cannot change, and refuse on the click.No policy language, no relationship graph, no decision service.
It does not replace
[Auth].[Auth]still takes roles and policies only. A model carrying both has the role decided first, by the authorization middleware, which runs ahead of any endpoint filter — so the AND in "role and permission" is the ordering, not code.
Removing a declaration
Two halves, and both matter.
Compile: every use site holds a Permission, and the only supply of values is the generated
constants. Delete the declaration and the call site fails as CS0117.
Grant: a grant row naming a permission the catalog no longer declares is inert — the held set
is intersected with the registry, so it can never admit anyone. The access admin still lists it,
marked undeclared, offering a revoke control and nothing else. Hiding it would leave a row
nobody could find to delete; offering it in the add list would let it be re-granted.
Which suite proves it
| Tier | Project |
|---|---|
| Unit | tests/nativeweb.permissions.tests.unit — the registry, the filter, the context, the access admin over a TestServer |
| Unit (generator) | tests/nativeweb.scaffold.tests.unit/PermissionGatingTests.cs — the emitted source, compiled and asserted |
| Integration | tests/nativeweb.permissions.tests.integration — JauntyPermissionStore against real PostgreSQL |
| Integration (admin) | tests/nativeweb.scaffold.tests.integration/PermissionGatingTests.cs — the rendered controls, with and without each grant |
| End-to-end | tests/nativeweb.permissions.tests.e2e — a browser against the published NativeAOT sample |
| AOT | tests/nativeweb.signin.tests.aot — the publish raises no trim or AOT warning |
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Extrode.NativeWeb.Scaffold (>= 0.1.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.