Can this subject perform this domain action on this domain resource in this context?

@PreAuthorize("hasRole('ADMIN')")
@PostMapping("/cases/{id}/close")
public CaseDto close(@PathVariable UUID id) {
    return caseService.close(id);
}

Does the caller have ADMIN?

Is this case in the caller's tenant?
Is the case assigned to the caller or their unit?
Is the case in a state where close is allowed?
Is the caller the same person who opened the case?
Is maker-checker required?
Is the resource under legal hold?
Is this a normal close, supervisory close, or forced close?
Which policy version made the decision?

public final class CaseFile {
    public void close(Authentication authentication) {
        if (!authentication.getAuthorities().contains(new SimpleGrantedAuthority("ROLE_ADMIN"))) {
            throw new AccessDeniedException("Denied");
        }
        this.status = CaseStatus.CLOSED;
    }
}

public final class CaseFile {
    public void close(CaseClosureCommand command) {
        requireOpen();
        requireClosureReason(command.reason());
        requireNoActiveLegalHold();
        this.status = CaseStatus.CLOSED;
        this.closedBy = command.actorId();
        this.closedAt = command.closedAt();
        this.closureReason = command.reason();
    }
}

AuthorizationDecision decision = authorizationService.check(
    AuthorizationRequest.builder()
        .subject(subject)
        .action(Action.CASE_CLOSE)
        .resource(ResourceRef.caseFile(command.caseId()))
        .context(Map.of(
            "tenantId", subject.tenantId(),
            "reason", command.reason(),
            "workflowSource", command.source()
        ))
        .build()
);

decision.requirePermit();

POST /cases/{id}/close              -> close case normally
POST /cases/{id}/force-close        -> force close exceptional case
POST /cases/{id}/approve-closure    -> approve another user's closure
POST /cases/{id}/reopen             -> reopen closed case

public final class CloseCaseUseCase {
    private final CaseRepository caseRepository;
    private final AuthorizationService authorizationService;
    private final Clock clock;
    private final AuditSink auditSink;

    public CloseCaseResult handle(SubjectContext subject, CloseCaseCommand command) {
        CaseFile caseFile = caseRepository.findVisibleCaseForUpdate(
            subject,
            command.caseId()
        ).orElseThrow(CaseNotFoundOrDeniedException::new);

        AuthorizationDecision decision = authorizationService.check(
            AuthorizationRequest.builder()
                .subject(subject)
                .action(Action.CASE_CLOSE)
                .resource(ResourceRef.caseFile(caseFile.id(), caseFile.tenantId()))
                .resourceAttributes(caseAttributes(caseFile))
                .context(Map.of(
                    "now", Instant.now(clock),
                    "reason", command.reason(),
                    "source", command.source()
                ))
                .build()
        );

        auditSink.record(decision.toAuditEvent());
        decision.requirePermit();

        caseFile.close(new CaseClosureCommand(
            subject.userId(),
            command.reason(),
            Instant.now(clock),
            command.source()
        ));

        caseRepository.save(caseFile);

        return CloseCaseResult.from(caseFile);
    }
}

1. Load through scoped repository.
2. Build authorization request with real resource attributes.
3. Evaluate policy.
4. Audit decision.
5. Enforce decision.
6. Mutate aggregate.
7. Persist.

Is the endpoint public?
Is a valid principal required?
Does the caller belong to the right coarse authority family?
Is this endpoint restricted to service accounts?
Is this admin API blocked from normal users?

@Bean
SecurityFilterChain security(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers(HttpMethod.GET, "/health").permitAll()
            .requestMatchers("/internal/**").hasAuthority("SCOPE_internal")
            .requestMatchers("/admin/**").hasAuthority("PERM_ADMIN_PORTAL_ACCESS")
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
        .build();
}

public interface AuthorizationService {
    AuthorizationDecision check(AuthorizationRequest request);

    default void require(AuthorizationRequest request) {
        check(request).requirePermit();
    }
}

authorizationService.require(
    AuthorizationRequest.forAction(subject, Action.EVIDENCE_UPLOAD)
        .on(ResourceRef.caseFile(caseId))
        .with("contentType", file.contentType())
        .with("sizeBytes", file.size())
        .build()
);

- Code review sees the exact authorization action.
- Tests can assert the guard exists.
- Audit receives domain-level action names.
- Policy can evolve without changing controller annotations.
- Use cases invoked from HTTP, CLI, Kafka, scheduler, and admin tools all share the same guard.

public final class ClosureEligibilityPolicy {
    public boolean canClose(CaseFile caseFile) {
        return caseFile.status() == CaseStatus.IN_REVIEW
            && caseFile.hasFinalRecommendation()
            && !caseFile.hasActiveLegalHold();
    }
}

public final class CloseCaseAuthorizationPolicy {
    public AuthorizationDecision evaluate(SubjectContext subject, CaseFile caseFile) {
        if (!subject.tenantId().equals(caseFile.tenantId())) {
            return AuthorizationDecision.deny("TENANT_MISMATCH");
        }
        if (!subject.hasPermission("case.close")) {
            return AuthorizationDecision.deny("MISSING_PERMISSION");
        }
        if (!caseFile.isAssignedTo(subject.userId()) && !subject.hasPermission("case.close.any")) {
            return AuthorizationDecision.deny("NOT_ASSIGNED");
        }
        return AuthorizationDecision.permit();
    }
}

if (!closureEligibilityPolicy.canClose(caseFile)) {
    throw new BusinessRuleViolation("Case is not eligible for closure");
}

authorizationService.require(closeCaseRequest(subject, caseFile));

- JWT claims
- OAuth scopes
- HTTP headers
- Spring Authentication
- JAX-RS SecurityContext
- session attributes
- request IP

public record ActorId(UUID value) {}

public final class CaseFile {
    public void assignTo(ActorId actor, InvestigatorId newAssignee, Instant now) {
        requireAssignable();
        this.assigneeId = newAssignee;
        this.assignmentHistory.add(new AssignmentChanged(actor, newAssignee, now));
    }
}

// Bad: aggregate accepts impossible transition because authorization was checked elsewhere
caseFile.setStatus(CaseStatus.CLOSED);

public void approveClosure(ActorId approver, Instant approvedAt) {
    if (status != CaseStatus.PENDING_CLOSURE_APPROVAL) {
        throw new InvalidCaseState("Case is not waiting for closure approval");
    }
    if (closureRequestedBy.equals(approver)) {
        throw new SeparationOfDutyViolation("Requester cannot approve own closure");
    }
    this.status = CaseStatus.CLOSED;
    this.closedAt = approvedAt;
    this.closedBy = approver;
}

case.update
case.approve
case.admin

case.draft.edit
case.submit_for_review
case.review.assign
case.recommendation.add
case.closure.request
case.closure.approve
case.reopen
case.escalate
case.evidence.upload
case.evidence.seal
case.export.redacted
case.export.full

public void transition(SubjectContext subject, TransitionCaseCommand command) {
    CaseFile caseFile = caseRepository.findVisibleCaseForUpdate(subject, command.caseId())
        .orElseThrow(CaseNotFoundOrDeniedException::new);

    CaseTransition transition = transitionCatalog.resolve(
        caseFile.status(),
        command.targetStatus(),
        command.reasonCode()
    );

    authorizationService.require(
        AuthorizationRequest.builder()
            .subject(subject)
            .action(transition.requiredAction())
            .resource(ResourceRef.caseFile(caseFile.id(), caseFile.tenantId()))
            .resourceAttributes(caseAttributes(caseFile))
            .context(Map.of(
                "fromStatus", caseFile.status().name(),
                "toStatus", command.targetStatus().name(),
                "transition", transition.name()
            ))
            .build()
    );

    caseFile.applyTransition(transition, subject.actorId(), clock.instant());
    caseRepository.save(caseFile);
}

Optional<CaseFile> findById(CaseId id);

Optional<CaseFile> findVisibleCaseForRead(SubjectContext subject, CaseId id);

Optional<CaseFile> findVisibleCaseForUpdate(SubjectContext subject, CaseId id);

Page<CaseSummary> searchVisibleCases(SubjectContext subject, CaseSearchCriteria criteria, PageRequest page);

select c.*
from case_file c
left join case_assignment a
  on a.case_id = c.id
 and a.user_id = :subject_user_id
where c.id = :case_id
  and c.tenant_id = :tenant_id
  and (
        c.owner_user_id = :subject_user_id
     or a.user_id is not null
     or exists (
          select 1
          from user_unit_membership uum
          where uum.user_id = :subject_user_id
            and uum.unit_id = c.responsible_unit_id
     )
  )
for update;

Can the subject see/load this resource?

Can the subject close it?
Can the subject export it?
Can the subject assign it to someone else?
Can the subject edit sealed evidence?
Can the subject override a legal hold?

CaseFile caseFile = caseRepository.findVisibleCaseForUpdate(subject, command.caseId())
    .orElseThrow(CaseNotFoundOrDeniedException::new);

caseFile.close(...); // Missing action authorization

visibility scope + action policy

public interface AuthorizationPort {
    AuthorizationDecision decide(AuthorizationRequest request);

    BatchAuthorizationDecision decideBatch(List<AuthorizationRequest> requests);
}

- In-process Java policy evaluator
- Spring Security adapter
- OPA REST adapter
- Cedar / Amazon Verified Permissions adapter
- OpenFGA adapter
- Test fake
- Shadow decision comparator

public record AuthorizationRequest(
    SubjectContext subject,
    Action action,
    ResourceRef resource,
    Map<String, Object> resourceAttributes,
    Map<String, Object> environment,
    Map<String, Object> requestContext,
    RequestMetadata metadata
) {
    public static Builder builder() {
        return new Builder();
    }
}

public record SubjectContext(
    SubjectId subjectId,
    TenantId tenantId,
    SubjectType type,
    Set<String> authorities,
    Set<String> groups,
    Set<String> scopes,
    Map<String, Object> attributes,
    Instant authenticatedAt
) {}

public record ResourceRef(
    ResourceType type,
    String id,
    TenantId tenantId,
    Optional<String> parentId
) {
    public static ResourceRef caseFile(CaseId id, TenantId tenantId) {
        return new ResourceRef(ResourceType.CASE_FILE, id.value().toString(), tenantId, Optional.empty());
    }
}

authorizationPort.decide(requestWithFullEntity(caseFile));

private Map<String, Object> caseAttributes(CaseFile caseFile) {
    return Map.of(
        "tenantId", caseFile.tenantId().value().toString(),
        "status", caseFile.status().name(),
        "classification", caseFile.classification().name(),
        "responsibleUnitId", caseFile.responsibleUnitId().value().toString(),
        "assigneeId", caseFile.assigneeId().map(InvestigatorId::value).map(UUID::toString).orElse(null),
        "legalHold", caseFile.hasActiveLegalHold(),
        "createdBy", caseFile.createdBy().value().toString()
    );
}

- policy only sees what it needs
- audit log remains bounded
- schema can be versioned independently from domain entity internals

String tenant = jwt.getClaimAsString("tid");
String user = jwt.getSubject();
List<String> roles = jwt.getClaimAsStringList("roles");

public final class JwtSubjectContextMapper {
    public SubjectContext fromJwt(Jwt jwt) {
        return new SubjectContext(
            new SubjectId(jwt.getSubject()),
            new TenantId(requiredClaim(jwt, "tenant_id")),
            SubjectType.USER,
            normalizeAuthorities(jwt),
            normalizeGroups(jwt),
            normalizeScopes(jwt),
            Map.of(
                "assuranceLevel", claim(jwt, "acr"),
                "departmentId", claim(jwt, "department_id"),
                "jurisdiction", claim(jwt, "jurisdiction")
            ),
            jwt.getIssuedAt()
        );
    }
}

@RestController
@RequestMapping("/cases")
public final class CaseController {
    private final CloseCaseUseCase closeCaseUseCase;
    private final SubjectContextFactory subjectContextFactory;

    @PostMapping("/{caseId}/close")
    public ResponseEntity<CaseDto> close(
        @AuthenticationPrincipal Jwt jwt,
        @PathVariable UUID caseId,
        @RequestBody CloseCaseHttpRequest body
    ) {
        SubjectContext subject = subjectContextFactory.fromJwt(jwt);

        CloseCaseResult result = closeCaseUseCase.handle(
            subject,
            new CloseCaseCommand(new CaseId(caseId), body.reason(), CommandSource.HTTP)
        );

        return ResponseEntity.ok(CaseDto.from(result));
    }
}

@Path("/cases")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public final class CaseResource {
    private final CloseCaseUseCase closeCaseUseCase;
    private final SubjectContextProvider subjectContextProvider;

    @POST
    @Path("/{caseId}/close")
    public Response close(
        @PathParam("caseId") UUID caseId,
        CloseCaseHttpRequest body
    ) {
        SubjectContext subject = subjectContextProvider.currentSubject();

        CloseCaseResult result = closeCaseUseCase.handle(
            subject,
            new CloseCaseCommand(new CaseId(caseId), body.reason(), CommandSource.HTTP)
        );

        return Response.ok(CaseDto.from(result)).build();
    }
}

{
  "caseId": "...",
  "tenantId": "tenant-a",
  "createdBy": "admin",
  "classification": "PUBLIC",
  "force": true
}

public record CloseCaseCommand(
    CaseId caseId,
    ClosureReason reason,
    CommandSource source
) {}

- subject.tenantId from authenticated subject mapping
- resource.tenantId from database
- classification from database
- force privilege from policy
- actor from subject context

public Page<CaseSummary> search(SubjectContext subject, CaseSearchCriteria criteria, PageRequest page) {
    CaseSearchScope scope = caseSearchScopeFactory.forSubject(subject);
    Page<CaseSummary> results = caseReadRepository.search(scope, criteria, page);
    return fieldAuthorization.redactCaseSummaries(subject, results);
}

public void assign(SubjectContext subject, AssignCaseCommand command) {
    CaseFile caseFile = caseRepository.findVisibleCaseForUpdate(subject, command.caseId())
        .orElseThrow(CaseNotFoundOrDeniedException::new);

    authorizationService.require(assignCaseRequest(subject, caseFile, command.newAssignee()));

    caseFile.assignTo(subject.actorId(), command.newAssignee(), clock.instant());
    caseRepository.save(caseFile);
}

- can the subject perform the mutation?
- can the transition happen?
- should the event be emitted?

- which rows can the subject see?
- which fields must be redacted?
- which filters/sorts are allowed?

HTTP endpoint checks authorization.
Endpoint publishes event.
Consumer performs sensitive update without checking authorization or without a trusted authorization snapshot.

authorizationService.require(requestFor(subject, Action.CASE_ESCALATE, caseFile));
caseFile.escalate(...);
eventPublisher.publish(new CaseEscalated(...));

public void handle(ExportRequested event) {
    AuthorizationSnapshot snapshot = event.authorizationSnapshot();
    snapshot.requireAction(Action.CASE_EXPORT_FULL);
    exportService.generate(event.exportId());
}

public void handle(DelayedClosureRequested event) {
    SubjectContext subject = subjectContextStore.load(event.subjectId());
    CaseFile caseFile = repository.findById(event.caseId()).orElseThrow();
    authorizationService.require(closeCaseRequest(subject, caseFile));
    caseFile.close(...);
}

public record AuthorizationSnapshot(
    SubjectId subjectId,
    TenantId tenantId,
    Action action,
    ResourceRef resource,
    Decision decision,
    String policyVersion,
    Instant decidedAt,
    Instant expiresAt,
    List<String> reasonCodes
) {
    public void requireUsableFor(Action expectedAction, ResourceRef expectedResource, Instant now) {
        if (decision != Decision.PERMIT) {
            throw new AccessDeniedException("Original decision was not permit");
        }
        if (!action.equals(expectedAction)) {
            throw new AccessDeniedException("Snapshot action mismatch");
        }
        if (!resource.equals(expectedResource)) {
            throw new AccessDeniedException("Snapshot resource mismatch");
        }
        if (now.isAfter(expiresAt)) {
            throw new AccessDeniedException("Authorization snapshot expired");
        }
    }
}

public record TenantId(String value) {
    public TenantId {
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException("tenant id is required");
        }
    }
}

public record SubjectContext(
    SubjectId subjectId,
    TenantId tenantId,
    SubjectType type,
    Set<String> permissions,
    Map<String, Object> attributes
) {}

public record ResourceRef(ResourceType type, String id, TenantId tenantId) {}

Optional<CaseFile> findVisibleCaseForRead(SubjectContext subject, CaseId id);

if (subject.hasRole("GLOBAL_ADMIN")) {
    return AuthorizationDecision.permit();
}

if (subject.hasPermission("platform.support.impersonate")) {
    return requireBreakGlass(
        subject,
        request,
        "Global support access requires ticket, reason, expiration, and audit"
    );
}

- purpose-bound
- time-bound
- tenant-bound when possible
- reason-required
- ticket-linked
- separately audited
- visible in access review
- excluded from normal user policy paths

public sealed interface UseCaseError permits NotFoundOrDenied, AccessDenied, BusinessViolation {}

public record NotFoundOrDenied(String resourceType) implements UseCaseError {}
public record AccessDenied(String reasonCode) implements UseCaseError {}
public record BusinessViolation(String code) implements UseCaseError {}

public final class ErrorMapper {
    public HttpResponse map(Throwable error) {
        return switch (error) {
            case CaseNotFoundOrDeniedException ignored -> HttpResponse.notFound();
            case AccessDeniedException denied -> HttpResponse.forbidden(publicMessage(denied));
            case BusinessRuleViolation violation -> HttpResponse.unprocessableEntity(violation.publicCode());
            default -> HttpResponse.internalServerError();
        };
    }
}

TENANT_MISMATCH
NOT_ASSIGNED
INSUFFICIENT_CLEARANCE
LEGAL_HOLD
POLICY_TIMEOUT

{"error":"not_found"}

{"error":"forbidden"}

@Test
void closeCase_requiresClosePermission() {
    SubjectContext subject = fixtures.investigatorWithout("case.close");
    CaseFile caseFile = fixtures.caseInReviewAssignedTo(subject.userId());

    caseRepository.save(caseFile);

    assertThatThrownBy(() -> useCase.handle(subject, new CloseCaseCommand(caseFile.id(), reason(), HTTP)))
        .isInstanceOf(AccessDeniedException.class);
}

@Test
void findVisibleCaseForRead_doesNotReturnOtherTenantCase() {
    SubjectContext subject = fixtures.subjectInTenant("tenant-a");
    CaseFile otherTenantCase = fixtures.caseInTenant("tenant-b");

    assertThat(repository.findVisibleCaseForRead(subject, otherTenantCase.id()))
        .isEmpty();
}

@ArchTest
static final ArchRule domainMustNotDependOnSpringSecurity = noClasses()
    .that().resideInAPackage("..domain..")
    .should().dependOnClassesThat().resideInAnyPackage("org.springframework.security..")
    .because("domain must not know transport/framework security types");

@Test
void closeCase_callsAuthorizationWithDomainAction() {
    useCase.handle(subject, command);

    verify(authorizationService).check(argThat(request ->
        request.action().equals(Action.CASE_CLOSE)
            && request.resource().type() == ResourceType.CASE_FILE
    ));
}

1. Controllers must not call repositories directly for protected resources.
2. Application services must not use raw JWT or Spring Authentication.
3. Domain must not depend on web/security framework classes.
4. Repositories for protected aggregates must expose scoped methods.
5. Use cases mutating protected resources must call AuthorizationPort.
6. Authorization decisions must be auditable.
7. Bulk/list/export use cases must use query scope before pagination/export.
8. Admin/break-glass use cases must require reason and ticket.
9. Field redaction must happen before DTO leaves application boundary.
10. Async commands must carry authorization snapshot or recheck plan.

@PreAuthorize("hasRole('SUPERVISOR')")

public void approve(Authentication auth) { ... }

repository.findById(id)

case.update

A case can be closed only if:
- caller belongs to the case tenant
- caller has case.closure.request or case.closure.approve depending on transition
- caller is assigned investigator or supervisor of responsible unit
- case is in IN_REVIEW or PENDING_CLOSURE_APPROVAL
- case has final recommendation
- case has no active legal hold
- maker cannot approve own closure
- highly sensitive cases require supervisor clearance
- all decisions must be auditable

RequestClosureUseCase
ApproveClosureUseCase
RejectClosureUseCase
ForceCloseCaseUseCase

public enum Action {
    CASE_CLOSURE_REQUEST,
    CASE_CLOSURE_APPROVE,
    CASE_CLOSURE_REJECT,
    CASE_FORCE_CLOSE
}

public void requestClosure(SubjectContext subject, RequestClosureCommand command) {
    CaseFile caseFile = caseRepository.findVisibleCaseForUpdate(subject, command.caseId())
        .orElseThrow(CaseNotFoundOrDeniedException::new);

    authorizationService.require(
        request(subject, Action.CASE_CLOSURE_REQUEST, caseFile)
            .with("reason", command.reason())
            .build()
    );

    caseFile.requestClosure(subject.actorId(), command.reason(), clock.instant());
    caseRepository.save(caseFile);
}

public void approveClosure(SubjectContext subject, ApproveClosureCommand command) {
    CaseFile caseFile = caseRepository.findVisibleCaseForUpdate(subject, command.caseId())
        .orElseThrow(CaseNotFoundOrDeniedException::new);

    authorizationService.require(
        request(subject, Action.CASE_CLOSURE_APPROVE, caseFile)
            .with("requestedBy", caseFile.closureRequestedBy().value().toString())
            .with("classification", caseFile.classification().name())
            .build()
    );

    caseFile.approveClosure(subject.actorId(), clock.instant());
    caseRepository.save(caseFile);
}

public void approveClosure(ActorId approver, Instant now) {
    if (status != CaseStatus.PENDING_CLOSURE_APPROVAL) {
        throw new InvalidCaseState("Case is not pending closure approval");
    }
    if (closureRequestedBy.equals(approver)) {
        throw new SeparationOfDutyViolation("Requester cannot approve own closure");
    }
    if (hasActiveLegalHold()) {
        throw new InvalidCaseState("Case has active legal hold");
    }

    this.status = CaseStatus.CLOSED;
    this.closedBy = approver;
    this.closedAt = now;
}

repository scope -> action policy -> domain invariant -> audit

1. What is the domain action name?
2. Is this endpoint merely a transport adapter?
3. Is the subject normalized before reaching the use case?
4. Is resource tenant bound in the type model?
5. Is object visibility enforced by scoped repository/load?
6. Is action authorization explicit in the application service?
7. Are resource attributes projected safely for policy?
8. Are domain invariants enforced inside the aggregate?
9. Are authorization denial and business invalidity separated?
10. Are list/search/export endpoints scoped before pagination?
11. Are field-level redaction and writable-field checks handled?
12. Does async execution use snapshot or recheck?
13. Are decisions audited with policy version and reason code?
14. Are admin/break-glass paths separately modeled?
15. Are architecture tests preventing framework leakage into domain?

If authorization depends only on route shape -> edge guard is enough.
If authorization depends on object ownership -> repository scope and object-level guard.
If authorization depends on lifecycle state -> use-case action policy and aggregate invariant.
If authorization depends on field sensitivity -> DTO/mapper field authorization.
If authorization depends on relationship graph -> ReBAC/OpenFGA-style model.
If authorization must be centrally governed -> external PDP/policy-as-code.
If authorization must be regulatory-defensible -> decision audit is mandatory.

Add @PreAuthorize and hope tests pass.

Model action, resource, subject, context, scope, decision, and audit explicitly.

Make unauthorized states hard to express.
Make protected loads scoped by default.
Make policy decisions observable and testable.
Make framework security an adapter, not the architecture.
Make async and batch paths obey the same authorization invariants.
Make every sensitive transition defensible under audit.

- Edge adapter authenticates and performs coarse route guards.
- SubjectContext normalizes identity into application language.
- Application service performs use-case authorization.
- Repository scopes object access by construction.
- Domain aggregate enforces business invariants.
- AuthorizationPort hides PDP implementation.
- AuditPort records decision evidence.
- Async flows carry snapshot or recheck.