@drunkcoding/dknet-implementation-skills 0.1.0

package/skills/README.md

@@ -0,0 +1,47 @@
+# dknet-minimal skills
+
+Every folder here is one [Agent Skill](https://agentskills.io) (`<name>/SKILL.md`). The repository root is the
+`dknet-minimal` Claude Code plugin; the same files are what `npx skills add baoduy/DKNet.Templates` installs and what
+`@drunkcoding/dknet-minimal-skills` ships on npm. Start with `dknet-project-structure`.
+
+## Workflows (invoke as a slash command with arguments)
+
+| Skill | Arguments | Purpose |
+|---|---|---|
+| `/dknet-bdd-tests` | `<Feature> e.g. Orders` | Create and maintain Reqnroll + NUnit BDD .feature scenarios and step bindings in Minimal.App.BDDTests — request/status/response-body scenarios and domain-event side effects observed via log capture, for the hand-written PurchaseOrder and generator-driven Product samples. Use when adding or updating HTTP-facing scenarios for a DKNet.Templates feature. Result-level Result-object assertions, architecture rules and pure functional tests belong in the `dknet-unit-tests` skill instead — do not duplicate a behavior here that xUnit already covers. Invoke as `/dknet-bdd-tests <Feature>` to scaffold it for a feature. |
+| `/dknet-crud` | `<Feature> <Entity> [mode=manual\|auto] [version=V1]` | Create commands (Create/Update/business transitions/Delete) at the AppServices layer for a DKNet.Minimal feature — request contracts, FluentValidation validators, and SlimMessageBus handlers, in both the hand-written and generator-driven (CrudCreate/CrudUpdate/CrudAction) shapes. Use after the domain entity and EF Core mapper exist. Queries and paged lists are the `dknet-queries-specs` skill; response DTOs and Mapster are `dknet-dto-mapping`. Invoke as `/dknet-crud <Feature> <Entity> [mode=manual\|auto] [version=V1]` to scaffold it for a feature. |
+| `/dknet-docs` | `<Feature>` | Generate structured technical documentation and Mermaid architecture diagrams for completed features. Use this when documenting implemented features with README, architecture diagrams, and API references. Invoke as `/dknet-docs <Feature>` to scaffold it for a feature. |
+| `/dknet-endpoint` | `<Feature> <Entity> [mode=manual\|auto] [routePrefix] [version=V1]` | Create Minimal API endpoint configurations using this project's IEndpointConfig pattern — raw minimal-API routes mapped by hand, a single generated Map<Entity>Crud() call, or the underlying DKNet.AspCore.Extensions generic route helpers called directly. Use after AppServices actions (or CrudCreate/CrudUpdate/CrudAction entity attributes) are ready, to expose a feature over HTTP. Invoke as `/dknet-endpoint <Feature> <Entity> [mode=manual\|auto] [routePrefix] [version=V1]` to scaffold it for a feature. |
+| `/dknet-entity` | `<Feature> <Entity> [mode=manual\|auto] [props…] e.g. Orders Order mode=manual Number:string Total:decimal` | Create DDD domain entities following this project's AggregateRoot/DomainEntity inheritance pattern, either hand-written (mode=manual) or generator-declared (mode=auto). Use when adding a new domain entity or owned type to Minimal.Domains. Invoke as `/dknet-entity <Feature> <Entity> [mode=manual\|auto] [props…]` to scaffold it for a feature. |
+| `/dknet-feature-remove` | `<Feature> [--dry-run] e.g. Orders` | Retire a DKNet vertical-slice business feature end-to-end — deletes its folders across all six projects, cleans the out-of-folder touchpoints, and drops its tables via a new migration. |
+| `/dknet-feature` | `<Feature> <Entity> [mode=manual\|auto] [props…] e.g. Orders Order mode=manual Number:string Total:decimal` | Drive an end-to-end DKNet vertical-slice feature from plan to merged tests in either the manual or automated flow — orchestrates entity, CRUD, endpoint, tests, BDD, and docs. |
+| `/dknet-unit-tests` | `<Feature> <Entity> [mode=manual\|auto]` | Write xUnit + Shouldly tests for a DKNet.Templates feature in Minimal.App.Tests — architecture/convention rules, pure functional tests (entity methods, validators, specs, mapping), and result-level integration tests against ApiFixture + IMessageBus (handler Result failures, EF persistence, domain events). Use after AppServices actions and endpoint config are ready. Covers only what xUnit owns; HTTP request/response and event-log scenarios belong in the `dknet-bdd-tests` skill. Invoke as `/dknet-unit-tests <Feature> <Entity> [mode=manual\|auto]` to scaffold it for a feature. |
+
+## Reference skills (loaded by the agent when the topic comes up)
+
+| Skill | Teaches |
+|---|---|
+| `dknet-auth-and-ownership` | Explains authentication, per-route authorization scopes, acting-user attribution, row-level data ownership, and role-aware sensitive-data filtering in this template — including the demo authentication provider and how to write a test that runs with RequireAuthorization on. Use whenever adding a scope-guarded route, wiring acting-user attribution for a new feature, reasoning about data isolation between callers, or writing an auth-on integration test. |
+| `dknet-ddd-principles` | DDD tactical judgment for this codebase — aggregate boundaries, entity vs. value object, invariant enforcement, when to use a domain event, avoiding anemic domain models. Use before dknet-entity and dknet-crud whenever the aggregate shape or business-rule placement isn't obvious. |
+| `dknet-dto-mapping` | Design response DTOs and Mapster mapping for a DKNet.Minimal feature — hand-written vs [GenerateDto] shapes, custom Mapster IRegister mappings for values the generator's convention can't produce, LazyMapper, and the JSON/sensitive-data contract. Use after (or alongside) dknet-crud when a handler needs a DTO to return. |
+| `dknet-efcore-config` | Create EF Core entity type configurations (mappers), static data seeders, CoreDbContext wiring, and infra domain-service implementations following this project's assembly-scan auto-discovery conventions. Use after creating a domain entity, for both mode=manual and mode=auto entities. |
+| `dknet-feature-lifecycle` | The add/remove lifecycle of a DKNet vertical-slice business feature — how to choose the manual vs automated flow, the exact file footprint a feature occupies across all six projects, and the out-of-folder touchpoints a delete must clean up. Use before /dknet-feature or /dknet-feature-remove, and whenever you need to enumerate or retire an existing feature. |
+| `dknet-messaging-events` | Explains how this template wires SlimMessageBus as its command/query/event backbone, how the two domain-event styles (manual AddEvent vs declared RaisesEvent) reach a subscriber, and how to forward an event to an external Azure Service Bus topic. Use whenever adding a domain event, wiring an internal or external event consumer, or reasoning about how a command/query travels from an endpoint to its handler. |
+| `dknet-package-adoption` | Add DKNet's Core, EF Core, messaging/CQRS, or blob-storage NuGet packages to an EXISTING .NET project that was NOT created from the DKNet.Minimal.Template. Use when a consumer wants to reuse pieces of the DKNet framework in their own project layout without scaffolding a new solution. |
+| `dknet-platform-config` | Reference for everything the template wires outside a feature's own vertical slice — Program.cs start-up order, the FeatureManagement flag table, every configuration section and its defaults, launch-time jobs, the Aspire host, and the test-host overrides. Use when adding or changing a platform-level behavior (auth, rate limiting, health checks, telemetry, caching, CORS, a new flag, a new launch job) rather than a business feature. |
+| `dknet-project-structure` | Orientation to the DKNet.Minimal.Template layer boundaries, the six projects, the vertical-slice folder layout for a feature, and auto-discovery wiring. Use first, before any other dknet-* skill, when working in a solution generated from this template. |
+| `dknet-queries-specs` | Write read/query logic for a DKNet feature — Specification<T> filters, hand-written query requests/handlers dispatched over IMessageBus, and the generic filter/search/order/page list route every generator-driven CRUD slice gets for free. Use after the domain entity and DTO exist, whenever a feature needs anything more than the default GET-by-id. |
+| `dknet-scaffold` | Scaffold a new solution from the DKNet.Minimal template and get it running — dotnet new install/new, the six template parameters, what the generated tree looks like, first build/run with or without Aspire, deleting the two shipped sample features, and installing this skill plugin into the generated repo. Use when starting a new DKNet.Minimal solution, or when orienting inside a freshly generated one. |
+
+## Claude Code subagents (`../agents/`)
+
+- `dknet-architect` — Use when planning a new feature in a DKNet.Minimal.Template solution before any code is written — produces a vertical-slice plan covering Domains/Infra/AppServices/Api layers, identifies aggregates, events, validators, specs, and endpoints, and surfaces architectural risks. Read-only research; does not modify code.
+- `dknet-bdd-engineer` — Use to add or update Reqnroll + NUnit BDD scenarios for a DKNet feature. Builds .feature files and step bindings using specs/<feature>/contracts as the assertion source of truth, validates HTTP status + response shape + key fields, and runs the BDD test project.
+- `dknet-implementer` — Use to implement an approved DKNet feature plan end-to-end across Domains, Infra, AppServices, and Api layers, including EF migration, FluentValidation, Mapster DTOs, domain events, and endpoint wiring. Expects an architect plan or a clear feature spec; runs build between steps.
+
+## Authoring
+
+Rules every skill follows (enforced by `../validate-plugin.sh`): frontmatter `name` equals the folder, a single-line
+`description` (max 1024 chars), paths relative to the consumer solution root (`ApiEndpoints/Minimal.*`, never `src/`),
+other skills referenced by name, no links into this repository's `docs/`, exemplar code inlined. This index is
+generated from the frontmatter — regenerate it after changing a skill.

package/skills/dknet-auth-and-ownership/SKILL.md

@@ -0,0 +1,418 @@
+---
+name: dknet-auth-and-ownership
+description: Explains authentication, per-route authorization scopes, acting-user attribution, row-level data ownership, and role-aware sensitive-data filtering in this template — including the demo authentication provider and how to write a test that runs with RequireAuthorization on. Use whenever adding a scope-guarded route, wiring acting-user attribution for a new feature, reasoning about data isolation between callers, or writing an auth-on integration test.
+---
+
+# DKNet authentication, authorization, and ownership
+
+## `FeatureManagement:RequireAuthorization`
+
+When `true`, `AddAppConfig` calls `AddAuthConfig` (`Minimal.Api/Configs/Auth/AuthConfig.cs`):
+
+```csharp
+services.AddAuthentication().AddJwtBearer();
+
+services.AddAuthorization(options =>
+{
+    // Default deny: any endpoint not explicitly declared anonymous requires an authenticated caller.
+    options.FallbackPolicy = new AuthorizationPolicyBuilder()
+        .RequireAuthenticatedUser()
+        .Build();
+
+    options.AddPolicy(HasScopeRequirement.PolicyName,
+        policy => policy.Requirements.Add(new HasScopeRequirement("sample-scope")));
+
+    foreach (var scope in ProductScopes.All)
+        options.AddPolicy(scope, policy => policy.Requirements.Add(new HasScopeRequirement(scope)));
+});
+
+services.AddScoped<IClaimsTransformation, SampleClaimsTransformation>();
+services.AddScoped<IAuthorizationHandler, HasScopeHandler>();
+```
+
+JWT bearer validation reads its metadata address from `Authentication:Schemes:Bearer:MetadataAddress`
+(plus `ValidAudiences`/`ValidIssuer`). `FallbackPolicy` is default-deny: any route without an
+explicit `[AllowAnonymous]` requires an authenticated caller, even one with no scope requirement
+attached. `HasScopeRequirement`/`HasScopeHandler` check the `scp` or `scope` claim (space-separated,
+both spellings checked for provider portability). `SampleClaimsTransformation` is a `TODO`-marked
+seam for enriching the principal after authentication — replace it, don't add a parallel one.
+
+When `RequireAuthorization` is `false`, **no authentication or authorization middleware is
+registered at all**, unless `EnableDemoAuthentication` is separately on (below). There is no
+implicit fallback identity.
+
+`appsettings.json` ships `RequireAuthorization: true`. Both `appsettings.Development.json` and
+`appsettings.Testing.json` override it to `false` and turn `EnableDemoAuthentication` on instead —
+local development and the test hosts do not exercise real JWT validation by default.
+
+## Scopes → policies
+
+`Minimal.Api/ApiEndpoints/AutomatedSample/ProductScopes.cs` defines the scope constants for the
+`Product` feature:
+
+```csharp
+internal static class ProductScopes
+{
+    public const string Read = "products.read";
+    public const string Write = "products.write";
+    public const string Supplier = "products.supplier";
+    public const string Discontinue = "products.discontinue";
+    public static readonly string[] All = [Read, Write, Supplier, Discontinue];
+}
+```
+
+`AuthConfig`'s `foreach (var scope in ProductScopes.All)` loop registers **one authorization policy
+per scope, the scope value doubling as its own policy name** — so a route calls
+`.RequireAuthorization(ProductScopes.Read)` directly, no separate policy name to remember.
+
+A route only calls `RequireAuthorization(scope)` when the flag is actually on — calling it
+unconditionally would throw at request time if `RequireAuthorization` is off, because no policies
+were registered for the app to resolve against. `ProductV1Endpoint.Map` reads the flag once via DI
+and branches on it:
+
+```csharp
+var requireAuthorization = ((IEndpointRouteBuilder)group).ServiceProvider
+    .GetRequiredService<IOptions<FeatureOptions>>().Value.RequireAuthorization;
+
+group.MapProductCrud(o =>
+{
+    o.Exclude("Discontinue");
+    if (!requireAuthorization) return;
+
+    o.Configure(CrudOp.GetById, rb => rb.RequireAuthorization(ProductScopes.Read));
+    o.Configure(CrudOp.GetList, rb => rb.RequireAuthorization(ProductScopes.Read));
+    o.Configure(CrudOp.Create, rb => rb.RequireAuthorization(ProductScopes.Write));
+    o.Configure(CrudOp.Update, rb => rb.RequireAuthorization(ProductScopes.Write));
+    o.Configure(CrudOp.Delete, rb => rb.RequireAuthorization(ProductScopes.Write));
+    o.Configure("Approve", rb => rb.RequireAuthorization(ProductScopes.Write));
+    // Its own scope, not Write — holding only products.write must not be enough to assign it.
+    o.Configure("AssignSupplierReference", rb => rb.RequireAuthorization(ProductScopes.Supplier));
+});
+
+var discontinue = group.MapPut("{id:guid}/discontinue", /* ... */);
+if (requireAuthorization) discontinue.RequireAuthorization(ProductScopes.Discontinue);
+```
+
+`o.Configure(CrudOp, ...)` targets a generated composite route by operation kind (see
+`dknet-endpoint`); `o.Configure("RouteName", ...)` targets a specific `[CrudAction]` route by
+its C# member name. A hand-mapped route (`discontinue` above) calls `.RequireAuthorization(scope)`
+directly on the `RouteHandlerBuilder` the same way.
+
+`IEndpointConfig` also exposes an optional `string? AuthPolicy` member for gating an entire group
+under one policy (`null` means plain authentication) rather than per-route scopes — neither shipped
+sample overrides it; both use per-route `RequireAuthorization(scope)` inside `Map` instead, because
+different routes in the same group need different scopes.
+
+**Recipe: add a new scope for a new feature.**
+1. Add a constant (and to an `All` array, if you loop like `ProductScopes` does) in a
+   `<Feature>Scopes` static class next to the feature's endpoint config.
+2. Register it as a policy — either loop over your `All` array in `AuthConfig` the way
+   `ProductScopes.All` is registered, or call `options.AddPolicy(YourScopes.X, ...)` explicitly for a
+   one-off scope.
+3. Call `.RequireAuthorization(YourScopes.X)` on the route, gated behind the same
+   `FeatureOptions.RequireAuthorization` check `ProductV1Endpoint` uses — never call it
+   unconditionally.
+
+## Demo authentication
+
+`FeatureManagement:EnableDemoAuthentication` registers `DemoAuthenticationHandler`
+(`Minimal.Api/Configs/Auth/DemoAuthConfig.cs`) as the default authenticate/challenge scheme. Every
+request is authenticated, unconditionally, as a fixed fake identity:
+
+```csharp
+var identity = new ClaimsIdentity(
+    [
+        new Claim(ClaimTypes.Name, SharedConsts.DemoAccount),
+        new Claim(ClaimTypes.NameIdentifier, SharedConsts.SystemAccount)
+    ],
+    SchemeName);
+```
+
+`AddAppConfig` throws at start-up if both `RequireAuthorization` and `EnableDemoAuthentication` are
+`true` — the demonstration identity is never a real caller. Demo authentication exists to give
+local/demo runs a real authenticated principal, so acting-user attribution and ownership stamping
+still work, without standing up a real identity provider. It never gates access — no authorization
+services or policies are registered alongside it.
+
+## Acting user — three surfaces
+
+**Manual: `[FromClaim]`.** `CreatePurchaseOrderRequest.ByUser` is populated by
+`AddContextualRequestPopulation` (wired in `Program.cs`) before FluentValidation runs and before the
+handler is invoked:
+
+```csharp
+[FromClaim(ClaimTypes.Name)]
+public string? ByUser { get; set; }
+```
+
+There is no fallback: if the caller has no `ClaimTypes.Name` claim, `ByUser` stays `null`/empty, and
+the handler must reject it explicitly —
+
+```csharp
+if (string.IsNullOrEmpty(request.ByUser))
+    return Result.Fail<PurchaseOrderDto>("The caller is not authenticated.");
+```
+
+— from `CreatePurchaseOrderCommandHandler`. A payload value for `ByUser` is always overwritten, never
+trusted; this is a security seam, not a binding convenience.
+
+**Automated: `PrincipalProvider` + two save hooks.** A `[CrudCreate]`/`[CrudUpdate]`/`[CrudAction]`
+generated request forwards only `System.ComponentModel.DataAnnotations` attributes, so it can never
+carry `[FromClaim]`. Acting-user attribution instead goes through `PrincipalProvider`
+(`Minimal.Api/Configs/Handlers/PrincipalProvider.cs`), which implements `IPrincipalProvider`
+(`IDataOwnerProvider` + `ICurrentUserProvider` plus `ProfileId`/`Email`/`UserName`):
+
+```csharp
+string[] subjectClaimTypes =
+[
+    "http://schemas.microsoft.com/identity/claims/objectidentifier", "oid", ClaimTypes.NameIdentifier, "sub"
+];
+// first non-empty of these wins
+```
+
+Unauthenticated callers resolve to `SharedConsts.SystemAccount`. `ServiceConfigs.AddAllAppServices`
+wires it twice, deliberately as two separate hooks over the same value today:
+
+```csharp
+.AddDataOwnerProvider<CoreDbContext, PrincipalProvider>()   // stamps OwnedBy on insert, row-isolation key
+.AddCurrentUserProvider<CoreDbContext, PrincipalProvider>() // stamps CreatedBy/UpdatedBy from the same subject
+```
+
+`GetOwnershipKey()` and `GetCurrentUser()` return the same value today — kept as two methods (not
+collapsed into one) because the two hooks are wired independently and are free to diverge later if
+ownership and audit attribution ever need different claims.
+
+A domain method can still override the audit stamp explicitly — `Product.Approve(string byUser) =>
+SetUpdatedBy(byUser)` calls the base `SetUpdatedBy` directly, so `UpdatedBy` reflects the payload's
+`byUser` argument rather than the caller's own principal for that one action.
+
+**Table: manual vs. automated acting-user attribution**
+
+| | Manual (`PurchaseOrder`) | Automated (`Product`) |
+|---|---|---|
+| Carried on | `[FromClaim]` request property | Not on the request at all |
+| Populated by | `AddContextualRequestPopulation`, pre-validation | `PrincipalProvider`, at `SaveChanges` |
+| Empty/missing case | Handler must check and reject | `CreatedBy`/`UpdatedBy` stamped `SystemAccount`, or the write is refused (see ownership below) |
+| Override per-action | Pass a different value in the payload (validator's job to police that) | A domain method can call `SetUpdatedBy(explicitUser)` directly, as `Approve` does |
+
+**`[CrudAction]` pitfall.** A generated action method's parameter *name* becomes a bindable request
+property, regardless of what it's meant to represent. `Product.Approve(string byUser) =>
+SetUpdatedBy(byUser)` generates `ApproveProductRequest` with a caller-settable, `required string
+ByUser` property — any caller can claim to be approving as anyone. This is by design for `Approve`
+(the BDD suite calls it "approve as X"), but it means **never name a `[CrudAction]` parameter
+`byUser`/similar expecting it to be silently populated from the caller's identity** — a generated
+request has no `[FromClaim]` seam at all.
+
+## Row-level isolation
+
+`Product : AggregateRoot, IOwnedBy` carries an `OwnedBy` property. `CoreDbContext : IDataOwnerDbContext`
+exposes:
+
+```csharp
+public IEnumerable<string> AccessibleKeys =>
+    _dataKeyProvider is not null ? _dataKeyProvider.GetAccessibleKeys() : [];
+```
+
+DKNet's global query filter reads `AccessibleKeys` to scope every `IOwnedBy` entity's reads to the
+current caller — `ProductOwnershipIsolationTests` proves two authenticated callers sharing one
+host/database get distinct ownership keys and neither can read or list the other's row (a cross-read
+returns 404, not 403 — the filter denies it as "not found", it does not reveal existence).
+
+Before every `SaveChanges`, `CoreDbContext.EnsureOwnershipResolvable()` fails closed:
+
+```csharp
+private void EnsureOwnershipResolvable()
+{
+    if (_dataKeyProvider is null) return;
+    if (!string.IsNullOrEmpty(_dataKeyProvider.GetOwnershipKey())) return;
+
+    var hasUnattributableInsert = ChangeTracker.Entries()
+        .Any(e => e.State == EntityState.Added
+                  && e.Entity is IAuditedProperties { CreatedBy: null or "" }
+                  && e.Metadata.FindProperty(nameof(IAuditedProperties.CreatedBy)) is { IsNullable: false });
+
+    if (hasUnattributableInsert) throw new OwnershipRequiredException();
+}
+```
+
+If an authenticated caller's ownership key cannot be resolved and a new row would be left with no
+`CreatedBy`, this throws `OwnershipRequiredException` **before** EF Core attempts the insert —
+otherwise EF Core's own required-column check would throw a raw `DbUpdateException` that leaks
+column/entity names into the response. `FluentValidationConfig.AddErrorResponses` maps that
+exception to **403 Forbidden**:
+
+```csharp
+o.StatusCode = ctx =>
+{
+    if (ctx.Source == ErrorSource.Unhandled && ctx.Exception is OwnershipRequiredException)
+        return StatusCodes.Status403Forbidden;
+    return ctx.Errors.Any(e => e.Code?.StartsWith(PreconditionCodes.Prefix, StringComparison.Ordinal) == true)
+        ? StatusCodes.Status409Conflict
+        : null;
+};
+```
+
+`ProductOwnershipIsolationTests.AuthenticatedCallerWithNoSubjectClaim_IsRefusedWithForbidden_NoRowPersistedOrReadable`
+pins the whole chain: an authenticated caller with no resolvable subject claim gets 403, and the row
+is never persisted at all (checked with `IgnoreQueryFilters()` directly against the database, not
+just "unreadable over HTTP").
+
+**Tests that pin this area** (all in `Minimal.App.Tests/Integration/...`):
+
+- `AutomatedSample/V1/ProductOwnershipIsolationTests` — two distinct authenticated callers get
+  distinct ownership keys; neither can read or list the other's row; `oid` takes precedence over
+  `NameIdentifier` when both are present; a caller with no resolvable subject claim is refused 403
+  with no row left behind.
+- `AutomatedSample/V1/ProductAuditStampTests` — the acting caller is recorded as `CreatedBy`/
+  `UpdatedBy` even under a **fixed tenant** ownership key, proving `OwnedBy` (tenant) and
+  `CreatedBy`/`UpdatedBy` (individual actor) are stamped independently and never conflated.
+- `AutomatedSample/V1/ProductSecurityTests` — `CreatedBy`/`UpdatedBy` come from the authenticated
+  caller's own ownership key, never from any acting-user-shaped field in the request payload; an
+  explicit action (`Approve`) is the one place a payload-supplied acting user is legitimately
+  honored.
+- `ManualSample/V1/PurchaseOrderSecurityTests` — `[FromClaim] ByUser` always wins over any `byUser`
+  value present in the request body or query string.
+- `ManualSample/V1/PurchaseOrderNoNameClaimAttributionTests` — with no `ClaimTypes.Name` claim at
+  all, update/cancel/delete are all refused 400 and the stored order is unchanged.
+
+## Sensitive data
+
+`[SensitiveData("role")]` (DKNet.EfCore.Abstractions.Attributes) on an entity property means the
+JSON response omits that property for any caller who does not hold the named role; `[SensitiveData]`
+with no role means it is omitted for any caller who is not authenticated at all — any authenticated
+caller receives it regardless of role. On `Product`:
+
+```csharp
+[SensitiveData("pricing")]
+public decimal? SupplierCostPrice { get; private set; }
+
+[SensitiveData]
+public string? SupplierReferenceCode { get; private set; }
+```
+
+The attribute travels onto the generated DTO automatically; a hand-written DTO member that mirrors a
+`[SensitiveData]` entity property must carry the same attribute itself — it is not inherited through
+a plain property copy.
+
+Filtering is opt-in at the JSON-serialization layer, wired once in `ServiceConfigs.AddOptions`:
+
+```csharp
+services.AddSingleton<IConfigureOptions<JsonOptions>>(sp =>
+    new ConfigureOptions<JsonOptions>(op =>
+        op.SerializerOptions.UseRoleAwareSensitiveData(
+            sp.GetRequiredService<ISensitiveDataPrincipalAccessor>())));
+```
+
+`ISensitiveDataPrincipalAccessor`'s implementation is a two-line adapter over the already-registered
+`IHttpContextAccessor`:
+
+```csharp
+internal sealed class HttpContextSensitiveDataPrincipalAccessor(IHttpContextAccessor httpContextAccessor)
+    : ISensitiveDataPrincipalAccessor
+{
+    public ClaimsPrincipal? Current => httpContextAccessor.HttpContext?.User;
+}
+```
+
+**Tests:** `ProductSensitiveDataTests` (role-bearing vs. non-role-bearing authenticated callers, and
+that two callers are judged independently in either request order), `ProductSensitiveDataAnonymousTests`
+(an anonymous caller gets neither sensitive property but still gets the ordinary ones),
+`ProductSensitiveDataDemoAuthenticatedTests` (the demo identity gets the no-role property but not the
+`"pricing"`-role one, since the demo identity holds no roles).
+
+## Idempotency, in one paragraph
+
+POST routes are not idempotent unless the route calls `.RequiredIdempotentKey()` explicitly, with
+callers sending `X-Idempotency-Key`. The store is Redis when `ConnectionStrings:Redis` is set, else
+an in-process in-memory store; both use `ConflictHandling = IdempotentConflictHandling.ConflictResponse`
+(`Minimal.Api/Configs/AppConfig.cs`). See `dknet-crud` for how a handler's `Result`
+maps to a response body, and `dknet-platform-config` for CORS, security headers, and rate limiting.
+Status mapping: 400 validation, 401 no/invalid credential, 403 `OwnershipRequiredException` or a
+failed authorization policy, 404 not found or filtered out by ownership, 409 a
+`PreconditionCodes`-prefixed error, 429 rate limit, 500 unhandled.
+
+## Testing with authorization on
+
+`Program.cs` binds `FeatureOptions` from configuration in its very first lines — before
+`WebApplicationFactory`'s own `ConfigureAppConfiguration` override is merged in. A plain
+configuration override registered through the test factory's usual hook therefore cannot flip
+`RequireAuthorization` or `EnableDemoAuthentication`, because that early bind has already run by the
+time the override would apply. The shipped fixtures work around this by setting environment
+variables in the fixture's constructor, which **are** visible to `WebApplication.CreateBuilder(args)`
+at the point it builds its initial configuration:
+
+```csharp
+public sealed class AuthOnApiFixture : TestApiFactoryBase, IAsyncLifetime
+{
+    private const string RequireAuthorizationEnvKey = "FeatureManagement__RequireAuthorization";
+    private const string EnableDemoAuthenticationEnvKey = "FeatureManagement__EnableDemoAuthentication";
+
+    public AuthOnApiFixture()
+    {
+        Environment.SetEnvironmentVariable(RequireAuthorizationEnvKey, "true");
+        Environment.SetEnvironmentVariable(EnableDemoAuthenticationEnvKey, "false");
+    }
+
+    protected override void ConfigureTestServices(IServiceCollection services)
+    {
+        base.ConfigureTestServices(services);
+        TestAuthHandler.Register(services);
+    }
+    // ... clears both env vars again in Dispose
+}
+```
+
+This is only safe because the test assembly disables collection parallelization — no other test's
+host can boot while the variable is set, or it would leak into an unrelated test run.
+
+`TestAuthHandler` (`Minimal.App.TestSupport/TestAuthHandler.cs`) replaces the real JWT bearer scheme
+so a request can be authenticated without a live token. It issues a fixed name/subject and a scope
+claim built from every `ProductScopes` entry by default, overridable per request via a header:
+
+```csharp
+public const string ScopesHeaderName = "X-Test-Scopes";
+public static readonly string DefaultScopes = string.Join(' ', ProductScopes.All);
+
+var identity = new ClaimsIdentity(
+    [
+        new Claim(ClaimTypes.Name, CallerName),
+        new Claim(ClaimTypes.NameIdentifier, CallerProfileId.ToString()),
+        new Claim("scp", scopes)
+    ],
+    SchemeName);
+```
+
+To write an auth-on test for a new feature: add a fixture that mirrors `AuthOnApiFixture` (env vars
+in the constructor, cleared in `Dispose`, `TestAuthHandler.Register(services)` in
+`ConfigureTestServices`), then assert against `TestAuthHandler.CallerName` /
+`TestAuthHandler.CallerProfileId` the same way `PurchaseOrderSecurityTests`/`ProductSecurityTests`
+do. For a test that needs two distinct callers in one host (row-isolation tests),
+`Minimal.App.TestSupport/MultiSubjectAuthHandler.cs` reads the subject from a request header instead
+of a fixed constant — see `AuthOnMultiSubjectApiFixture` and `ProductOwnershipIsolationTests`. For a
+caller authenticated with no name claim at all, see `AuthOnNoNameClaimApiFixture`. For a fixed-tenant
+`OwnedBy` with a still-distinct acting `CreatedBy`, see `AuthOnFixedTenantApiFixture`.
+`RequireAuthorizationPlusDemoApiFixture` sets **both** flags on and, unlike every other fixture in
+that folder, does not implement `IAsyncLifetime` or reset the database — building the host is itself
+the thing under test, and it is expected to fail start-up.
+
+## Common mistakes
+
+- **What you might expect:** calling `.RequireAuthorization(scope)` unconditionally on a route.
+  **What actually happens:** with `RequireAuthorization` off, no policies were ever registered, so
+  the call throws at request time. Always gate it on `FeatureOptions.RequireAuthorization`, as
+  `ProductV1Endpoint` does.
+- **What you might expect:** giving a generated `[CrudAction]` a parameter meant to auto-populate
+  from the caller. **What actually happens:** it becomes an ordinary, caller-settable bound property
+  — there is no `[FromClaim]` seam on a generated request.
+- **What you might expect:** `EnableDemoAuthentication` is safe to leave on alongside
+  `RequireAuthorization` for a "belt and suspenders" local setup. **What actually happens:**
+  `AddAppConfig` throws at start-up — the two are hard mutually exclusive.
+- **What you might expect:** an unauthenticated caller's write just gets attributed to
+  `SharedConsts.SystemAccount` and proceeds. **What actually happens:** only true for a context with
+  no `IDataOwnerProvider` friction; once ownership stamping is wired (as it is for `Product`), a
+  caller whose subject claim cannot be resolved gets a 403 `OwnershipRequiredException`, not a
+  silent system-account write.
+- **What you might expect:** a config-file override in a `WebApplicationFactory` subclass can flip
+  `RequireAuthorization` for a single test class. **What actually happens:** `Program.cs` has already
+  bound `FeatureOptions` before that override merges in — only an environment variable set before the
+  host builds (in the fixture's constructor) takes effect.