feat(brief): WP-18 — ABAC capability spine (PRD-0002 phase P1)

Replace the FE-computed authorization anti-pattern in BriefStore.editable
(derived from the unverified X-Role header) with server-computed decision
flags, mirroring the existing HerregistratieDecisionsDto pattern:

- Backend: Authz.cs is the single authorization helper — the SAME check
  (Authz.CanActOn) both gates BriefStore.Review's mutations and computes
  the BriefDecisionsDto flags shipped on every brief response, so emit
  and enforce can never drift. New GET /me returns coarse, role-derived
  capabilities (PRD-0002 SS6).
- Every brief endpoint (including send, previously ungated on HttpContext)
  now returns a fresh BriefViewDto so decisions never go stale after a
  mutation.
- FE: brief.store.ts reads canEdit/canApprove/canReject/canSend off the
  loaded decisions instead of computing them from currentRole(); the
  brief.machine carries decisions through every status transition.
- New shared/domain/capability.ts + shared/application/access.store.ts +
  shared/infrastructure/me.adapter.ts: the general capability-spine
  infrastructure (AccessStore.can(), capabilityGuard) for future routes.

Deviates from the original WP-18 draft by NOT renaming auth/domain's
Session to a Principal union — ADR-0002 explicitly defers that refactor
until a second actor exists, and the brief workflow's drafter/approver
identity turned out to be a separate axis from the SSP login session
entirely. See docs/backlog/WP-18-abac-capability-spine.md for the full
as-built record.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backend/src/BigRegister.Api/Contracts/Dtos.cs

@@ -147,7 +147,14 @@ public sealed record BriefDto(
     IReadOnlyList<LetterSectionDto> Sections,
     BriefStatusDto Status, string DrafterId);
 
-public sealed record BriefViewDto(BriefDto Brief, IReadOnlyList<LibraryPassageDto> AvailablePassages);
+// Decision flags for the CURRENT acting principal + this brief's live status
+// (PRD-0002 phase P1) — the FE renders these, it never recomputes them.
+public sealed record BriefDecisionsDto(bool CanEdit, bool CanApprove, bool CanReject, bool CanSend);
+
+public sealed record BriefViewDto(BriefDto Brief, IReadOnlyList<LibraryPassageDto> AvailablePassages, BriefDecisionsDto Decisions);
 
 public sealed record SaveBriefRequest(IReadOnlyList<LetterSectionDto> Sections);
 public sealed record RejectBriefRequest(string Comments);
+
+// PRD-0002 §6: coarse, role-derived capabilities for nav/menu-level checks.
+public sealed record MeDto(IReadOnlyList<string> Capabilities);

backend/src/BigRegister.Api/Data/BriefStore.cs

@@ -1,4 +1,5 @@
 using BigRegister.Api.Contracts;
+using BigRegister.Domain.Authorization;
 
 namespace BigRegister.Api.Data;
 
@@ -72,11 +73,13 @@ public static class BriefStore
     }
   }
 
-  public static (Outcome, BriefEntity?) Approve(string owner, string actingId, string at) =>
-      Review(owner, actingId, e => new BriefStatusDto("approved", ApprovedBy: actingId, ApprovedAt: at));
+  public static (Outcome, BriefEntity?) Approve(string owner, Principal principal, string at) =>
+      Review(owner, principal, BriefAction.Approve, () =>
+          new BriefStatusDto("approved", ApprovedBy: Authz.ActingId(principal), ApprovedAt: at));
 
-  public static (Outcome, BriefEntity?) Reject(string owner, string actingId, string comments, string at) =>
-      Review(owner, actingId, e => new BriefStatusDto("rejected", RejectedBy: actingId, RejectedAt: at, Comments: comments));
+  public static (Outcome, BriefEntity?) Reject(string owner, Principal principal, string comments, string at) =>
+      Review(owner, principal, BriefAction.Reject, () =>
+          new BriefStatusDto("rejected", RejectedBy: Authz.ActingId(principal), RejectedAt: at, Comments: comments));
 
   public static (Outcome, BriefEntity?) Send(string owner, string at)
   {
@@ -109,15 +112,18 @@ public static class BriefStore
   }
 
   // Approve/reject share the guard: must be submitted, and the approver must differ
-  // from the drafter (a drafter cannot approve their own letter).
-  private static (Outcome, BriefEntity?) Review(string owner, string actingId, Func<BriefEntity, BriefStatusDto> next)
+  // from the drafter (a drafter cannot approve their own letter). The SoD check is
+  // Authz.CanActOn — the SAME check the screen DTO's decision flags use — checked
+  // BEFORE the status guard so Forbidden vs Conflict ordering matches the old
+  // inline check exactly.
+  private static (Outcome, BriefEntity?) Review(string owner, Principal principal, BriefAction action, Func<BriefStatusDto> next)
   {
     lock (_gate)
     {
       if (!_byOwner.TryGetValue(owner, out var e)) return (Outcome.Conflict, null);
-      if (actingId == e.DrafterId) return (Outcome.Forbidden, null);
+      if (!Authz.CanActOn(action, principal, e.DrafterId)) return (Outcome.Forbidden, null);
       if (e.Status.Tag != "submitted") return (Outcome.Conflict, null);
-      e.Status = next(e);
+      e.Status = next();
       return (Outcome.Ok, e);
     }
   }

backend/src/BigRegister.Api/Domain/Authorization/Authz.cs

@@ -0,0 +1,59 @@
+using BigRegister.Api.Contracts;
+using BigRegister.Api.Data;
+
+namespace BigRegister.Domain.Authorization;
+
+public enum PrincipalRole { Drafter, Approver }
+
+/// <summary>
+/// The acting identity for this request. dev stub — NOT a security boundary: resolved
+/// from the client-asserted X-Role header (mirrors the FE's `?role=` toggle). A real
+/// system builds this from verified AD/OIDC claims (PRD-0002 §3, §7); everything else
+/// in this file — the capability model, the single Authz.Can check both emitting and
+/// enforcing — carries over unchanged once that swap happens.
+/// </summary>
+public sealed record Principal(PrincipalRole Role);
+
+public enum BriefAction { Approve, Reject, Send }
+
+/// <summary>
+/// Single source of truth for brief authorization (PRD-0002 phase P1). The SAME
+/// check both computes the decision flags shipped on the screen DTO (emit) and
+/// gates the mutation endpoints (enforce) — so the two can never drift, closing the
+/// classic broken-object-level-authorization gap (PRD-0002 §7).
+/// </summary>
+public static class Authz
+{
+  public static Principal ResolvePrincipal(HttpContext ctx) =>
+      new(ctx.Request.Headers["X-Role"].ToString() == "approver" ? PrincipalRole.Approver : PrincipalRole.Drafter);
+
+  public static string ActingId(Principal principal) =>
+      principal.Role == PrincipalRole.Approver ? BriefStore.ApproverId : BriefStore.DrafterId;
+
+  /// Coarse, resource-independent capabilities for `GET /me` (nav/menu-level — NOT
+  /// tied to any specific brief's live status; contrast Decisions below).
+  public static IReadOnlyList<string> RoleCapabilities(Principal principal) =>
+      principal.Role == PrincipalRole.Approver
+          ? new[] { "brief:approve", "brief:reject", "brief:send" }
+          : Array.Empty<string>();
+
+  /// Role + four-eyes (SoD) check only — no status. This is the exact check
+  /// BriefStore.Review enforces before its status guard; kept separate from
+  /// Decisions() below so enforcement ORDER (Forbidden before Conflict) matches
+  /// today's behavior exactly.
+  public static bool CanActOn(BriefAction action, Principal principal, string drafterId) => action switch
+  {
+    BriefAction.Approve or BriefAction.Reject => ActingId(principal) != drafterId,
+    BriefAction.Send => true, // sending is a mechanical dispatch step, not role-gated today
+    _ => false,
+  };
+
+  /// Resource-aware decision for the screen DTO: "would this action succeed right
+  /// now" — role/SoD AND the brief's current status. This is what the UI renders;
+  /// it never re-derives these booleans itself.
+  public static BriefDecisionsDto Decisions(Principal principal, string status, string drafterId) => new(
+      CanEdit: principal.Role == PrincipalRole.Drafter && status is "draft" or "rejected",
+      CanApprove: CanActOn(BriefAction.Approve, principal, drafterId) && status == "submitted",
+      CanReject: CanActOn(BriefAction.Reject, principal, drafterId) && status == "submitted",
+      CanSend: CanActOn(BriefAction.Send, principal, drafterId) && status == "approved");
+}

backend/src/BigRegister.Api/Program.cs

@@ -2,6 +2,7 @@ using System.Text.Json;
 using System.Text.Json.Serialization;
 using BigRegister.Api.Contracts;
 using BigRegister.Api.Data;
+using BigRegister.Domain.Authorization;
 using BigRegister.Domain.Diplomas;
 using BigRegister.Domain.Documents;
 using BigRegister.Domain.Intake;
@@ -239,76 +240,81 @@ api.MapPost("/applications/{id}/submit", (string id, SubmitApplicationRequest re
 .ProducesProblem(StatusCodes.Status409Conflict)
 .Produces(StatusCodes.Status404NotFound);
 
-// --- Brief (letter composition). One demo brief per owner; the server owns the
-// status machine + role rules. Role is a dev-only stand-in via X-Role (mirrors the
-// X-Admin seam and the FE ?role= toggle) — no real identities in this POC. ---
+// PRD-0002 §6: coarse, role-derived capabilities for nav/menu-level checks (NOT
+// tied to a specific brief's live status — see BriefDecisionsDto for that).
+api.MapGet("/me", (HttpContext ctx) => new MeDto(Authz.RoleCapabilities(Authz.ResolvePrincipal(ctx))))
+.Produces<MeDto>();
 
-api.MapGet("/brief", () =>
+// --- Brief (letter composition). One demo brief per owner; the server owns the
+// status machine + authorization (Authz, PRD-0002 phase P1). Principal is a
+// dev-only stand-in via X-Role (mirrors the X-Admin seam and the FE ?role=
+// toggle) — no real identities in this POC. ---
+
+api.MapGet("/brief", (HttpContext ctx) =>
 {
   var e = BriefStore.GetOrCreate(DocumentStore.DemoOwner);
-  return new BriefViewDto(e.ToDto(), BriefSeed.PassagesFor(e.Beroep));
+  return ToView(ctx, e);
 })
 .Produces<BriefViewDto>();
 
 api.MapPut("/brief", (SaveBriefRequest req, HttpContext ctx) =>
 {
-  var (_, isDrafter) = BriefRole(ctx);
-  return BriefResult(BriefStore.Save(DocumentStore.DemoOwner, req.Sections, isDrafter), "Alleen de opsteller mag de brief bewerken.");
+  var isDrafter = Authz.ResolvePrincipal(ctx).Role == PrincipalRole.Drafter;
+  return BriefResult(ctx, BriefStore.Save(DocumentStore.DemoOwner, req.Sections, isDrafter), "Alleen de opsteller mag de brief bewerken.");
 })
-.Produces<BriefDto>()
+.Produces<BriefViewDto>()
 .ProducesProblem(StatusCodes.Status403Forbidden)
 .ProducesProblem(StatusCodes.Status409Conflict);
 
 api.MapPost("/brief/submit", (HttpContext ctx) =>
 {
-  var (_, isDrafter) = BriefRole(ctx);
+  var isDrafter = Authz.ResolvePrincipal(ctx).Role == PrincipalRole.Drafter;
   var r = BriefStore.Submit(DocumentStore.DemoOwner, isDrafter, Now());
   LogBrief("submit", r);
-  return BriefResult(r, "Alleen de opsteller mag indienen.");
+  return BriefResult(ctx, r, "Alleen de opsteller mag indienen.");
 })
 .WithName("briefSubmit") // distinct name so the generated client method isn't `submit2`
-.Produces<BriefDto>()
+.Produces<BriefViewDto>()
 .ProducesProblem(StatusCodes.Status403Forbidden)
 .ProducesProblem(StatusCodes.Status409Conflict);
 
 api.MapPost("/brief/approve", (HttpContext ctx) =>
 {
-  var (acting, _) = BriefRole(ctx);
-  var r = BriefStore.Approve(DocumentStore.DemoOwner, acting, Now());
+  var r = BriefStore.Approve(DocumentStore.DemoOwner, Authz.ResolvePrincipal(ctx), Now());
   LogBrief("approve", r);
-  return BriefResult(r, "De beoordelaar mag niet de opsteller zijn.");
+  return BriefResult(ctx, r, "De beoordelaar mag niet de opsteller zijn.");
 })
-.Produces<BriefDto>()
+.Produces<BriefViewDto>()
 .ProducesProblem(StatusCodes.Status403Forbidden)
 .ProducesProblem(StatusCodes.Status409Conflict);
 
 api.MapPost("/brief/reject", (RejectBriefRequest req, HttpContext ctx) =>
 {
-  var (acting, _) = BriefRole(ctx);
-  var r = BriefStore.Reject(DocumentStore.DemoOwner, acting, req.Comments, Now());
+  var r = BriefStore.Reject(DocumentStore.DemoOwner, Authz.ResolvePrincipal(ctx), req.Comments, Now());
   LogBrief("reject", r);
-  return BriefResult(r, "De beoordelaar mag niet de opsteller zijn.");
+  return BriefResult(ctx, r, "De beoordelaar mag niet de opsteller zijn.");
 })
-.Produces<BriefDto>()
+.Produces<BriefViewDto>()
 .ProducesProblem(StatusCodes.Status403Forbidden)
 .ProducesProblem(StatusCodes.Status409Conflict);
 
-api.MapPost("/brief/send", () =>
+api.MapPost("/brief/send", (HttpContext ctx) =>
 {
   // Send-time placeholder linting is FE-authoritative in this slice (no C# parity
-  // port); the backend only guards the approved→sent transition.
+  // port); the backend only guards the approved→sent transition (not role-gated
+  // today — see Authz.CanActOn(Send, …), a mechanical dispatch step).
   var r = BriefStore.Send(DocumentStore.DemoOwner, Now());
   LogBrief("send", r);
-  return BriefResult(r, "Versturen kan niet in deze status.");
+  return BriefResult(ctx, r, "Versturen kan niet in deze status.");
 })
-.Produces<BriefDto>()
+.Produces<BriefViewDto>()
 .ProducesProblem(StatusCodes.Status409Conflict);
 
-api.MapPost("/brief/reset", () =>
+api.MapPost("/brief/reset", (HttpContext ctx) =>
 {
   // Demo "start over": recreate a fresh draft. No guards — showcase affordance only.
   var e = BriefStore.ResetAndCreate(DocumentStore.DemoOwner);
-  return new BriefViewDto(e.ToDto(), BriefSeed.PassagesFor(e.Beroep));
+  return ToView(ctx, e);
 })
 .WithName("briefReset")
 .Produces<BriefViewDto>();
@@ -319,17 +325,16 @@ static bool IsAdmin(HttpContext ctx) => ctx.Request.Headers["X-Admin"] == "true"
 
 static string Now() => DateTimeOffset.UtcNow.ToString("o");
 
-// Dev-only role stand-in: X-Role: approver acts as the approver identity, anything
-// else (default) acts as the drafter.
-static (string acting, bool isDrafter) BriefRole(HttpContext ctx)
-{
-  var isDrafter = ctx.Request.Headers["X-Role"].ToString() != "approver";
-  return (isDrafter ? BriefStore.DrafterId : BriefStore.ApproverId, isDrafter);
-}
+BriefViewDto ToView(HttpContext ctx, BriefEntity e) => new(
+    e.ToDto(),
+    BriefSeed.PassagesFor(e.Beroep),
+    Authz.Decisions(Authz.ResolvePrincipal(ctx), e.Status.Tag, e.DrafterId));
 
-IResult BriefResult((BriefStore.Outcome outcome, BriefEntity? entity) r, string forbiddenDetail) => r.outcome switch
+// Emit (decision flags, via ToView) and enforce (Forbidden/Conflict below) both run
+// through Authz — see BriefStore.Review and Authz.CanActOn — so they cannot drift.
+IResult BriefResult(HttpContext ctx, (BriefStore.Outcome outcome, BriefEntity? entity) r, string forbiddenDetail) => r.outcome switch
 {
-  BriefStore.Outcome.Ok => Results.Ok(r.entity!.ToDto()),
+  BriefStore.Outcome.Ok => Results.Ok(ToView(ctx, r.entity!)),
   BriefStore.Outcome.Forbidden => Results.Problem(detail: forbiddenDetail, statusCode: StatusCodes.Status403Forbidden),
   _ => Results.Problem(detail: "Ongeldige overgang voor de huidige status van de brief.", statusCode: StatusCodes.Status409Conflict),
 };