capability = bahasa bisnis
permission = bahasa sistem
authorization decision = permission + context + relationship + state + policy
entitlement = hasil efektif yang dialami user

Capability:
  Close enforcement case

Protected operations:
  - submit closure recommendation
  - review closure recommendation
  - approve closure
  - reject closure
  - reopen closed case

Permissions:
  - case.closure.submit
  - case.closure.review
  - case.closure.approve
  - case.closure.reject
  - case.reopen

Contextual rules:
  - submitter cannot approve own recommendation
  - case must be in CLOSURE_RECOMMENDED state
  - approver must be assigned to same jurisdiction
  - sensitive evidence must already be reviewed
  - decision must be audited with reason

case.create
case.read
case.update
case.delete

case.create_draft
case.view_summary
case.view_sensitive_details
case.edit_draft
case.submit_for_review
case.assign_investigator
case.change_priority
case.escalate
case.approve_enforcement_action
case.close
case.reopen
case.export

cases.read
case_assignments.update
evidence_files.read
findings.update

case.view
case.assign
case.escalate
evidence.view
finding.submit
finding.approve
enforcement_action.issue

Operation: approve enforcement action
Tables touched:
  - enforcement_actions
  - cases
  - case_events
  - audit_events
  - notifications
Permission:
  enforcement_action.approve

public interface CaseCommandService {
    CaseId createDraft(CreateCaseCommand command);
    void submitForReview(CaseId caseId, SubmitReviewCommand command);
    void assignInvestigator(CaseId caseId, AssignInvestigatorCommand command);
    void escalate(CaseId caseId, EscalateCaseCommand command);
    void approveClosure(CaseId caseId, ApproveClosureCommand command);
}

Low-risk operation:
  maybe request-level guard + query scope is enough

High-risk operation:
  request guard + service guard + state transition guard + audit

Critical operation:
  all high-risk controls + SoD + approval workflow + immutable evidence

case.closure.approve is allowed only if:
  resource.type == CASE
  action == case.closure.approve
  case.status == CLOSURE_RECOMMENDED
  subject != case.closureRecommendedBy
  subject has jurisdiction over case.jurisdiction
  subject has active role CASE_CLOSURE_APPROVER

@PreAuthorize("hasRole('SUPERVISOR')")
@PostMapping("/cases/{id}/close")
public void close(@PathVariable UUID id) {
    service.close(id);
}

public void approveClosure(PrincipalRef principal, CaseId caseId, ApproveClosureCommand command) {
    CaseRecord caseRecord = caseRepository.getRequired(caseId);

    authz.verify(AuthorizationRequest.command()
        .subject(principal)
        .action(Action.CASE_CLOSURE_APPROVE)
        .resource(ResourceRef.caseRef(caseRecord.id(), caseRecord.tenantId()))
        .resourceAttributes(CaseAttributes.from(caseRecord))
        .context(OperationContext.from(command))
        .build());

    caseRecord.approveClosure(command.reason(), principal.userId());
    caseRepository.save(caseRecord);
}

public void approveClosure(String reason, UserId approverId) {
    if (status != CaseStatus.CLOSURE_RECOMMENDED) {
        throw new InvalidCaseTransitionException(status, CaseStatus.CLOSED);
    }
    if (closureRecommendedBy.equals(approverId)) {
        throw new SeparationOfDutyViolation("Recommender cannot approve closure");
    }
    this.status = CaseStatus.CLOSED;
    this.closedBy = approverId;
    this.closedReason = reason;
}

case:CASE-100#assignee@user:U-10
case:CASE-100#supervisor@user:U-20
case:CASE-100#viewer@group:regional-a-investigators#member
jurisdiction:JK-01#officer@user:U-30

user can case.view if user is assignee or reviewer or supervisor or officer of case.jurisdiction
user can case.edit_draft if user is owner and case.status == DRAFT
user can case.approve if user is reviewer and user != submittedBy

never trust tenant_id from request as the authorization boundary
always derive tenant boundary from authenticated context and persisted resource

@GetMapping("/tenants/{tenantId}/cases/{caseId}")
public CaseDto getCase(@PathVariable UUID tenantId, @PathVariable UUID caseId) {
    return caseRepository.findById(caseId)
        .map(mapper::toDto)
        .orElseThrow(NotFoundException::new);
}

public CaseDto getCase(PrincipalRef principal, TenantId tenantIdFromRoute, CaseId caseId) {
    TenantId effectiveTenant = tenantResolver.requireAllowedTenant(principal, tenantIdFromRoute);

    CaseRecord caseRecord = caseRepository.findVisibleCase(
            principal.userId(),
            effectiveTenant,
            caseId
        )
        .orElseThrow(NotFoundException::new);

    authz.verify(AuthorizationRequest.query()
        .subject(principal)
        .action(Action.CASE_VIEW)
        .resource(ResourceRef.caseRef(caseRecord.id(), caseRecord.tenantId()))
        .resourceAttributes(CaseAttributes.from(caseRecord))
        .build());

    return mapper.toDto(caseRecord);
}

select * from cases
order by created_at desc
limit 50 offset 0;
-- lalu filter di Java

select c.*
from cases c
where c.tenant_id = :tenant_id
  and exists (
      select 1
      from case_visibility v
      where v.case_id = c.id
        and v.user_id = :user_id
  )
order by c.created_at desc
limit :limit offset :offset;

public record AuthorizationContext(
    SubjectAttributes subject,
    ResourceAttributes resource,
    ActionAttributes action,
    EnvironmentAttributes environment,
    RequestMetadata request
) {}

Map<String, Object> ctx = new HashMap<>();
ctx.put("s", user);
ctx.put("status", "x");
ctx.put("foo", true);

public record CaseAuthorizationAttributes(
    TenantId tenantId,
    CaseStatus status,
    JurisdictionId jurisdictionId,
    UserId ownerId,
    UserId assigneeId,
    UserId submittedBy,
    Sensitivity sensitivity,
    boolean sealed
) {}

<resource>.<operation>
<resource>.<subdomain>.<operation>
<resource>.<operation>.<variant>

case.view
case.view_sensitive
case.create_draft
case.edit_draft
case.submit_for_review
case.assign
case.escalate
case.close
case.reopen

evidence.upload
evidence.view
evidence.view_sensitive
evidence.delete_draft
evidence.seal

finding.create
finding.submit
finding.review
finding.approve
finding.reject

enforcement_action.propose
enforcement_action.approve
enforcement_action.issue

report.export_case_summary
report.export_sensitive_evidence

button.submit.enabled
screen.case.detail.open
menu.admin.visible

case.submit_for_review
case.view
admin.user_access.manage

supervisor.approve
admin.delete
maker.submit
checker.approve

case.closure.approve
case.assignment.update
finding.review

case.update

case.edit_draft
case.change_priority
case.assign
case.escalate
case.approve_closure

if (authz.can(user, "CASE_APROVE")) { // typo
    approve(caseId);
}

public enum Action {
    CASE_VIEW("case.view"),
    CASE_VIEW_SENSITIVE("case.view_sensitive"),
    CASE_CREATE_DRAFT("case.create_draft"),
    CASE_EDIT_DRAFT("case.edit_draft"),
    CASE_SUBMIT_FOR_REVIEW("case.submit_for_review"),
    CASE_ASSIGN("case.assign"),
    CASE_ESCALATE("case.escalate"),
    CASE_CLOSURE_APPROVE("case.closure.approve"),
    CASE_REOPEN("case.reopen"),

    EVIDENCE_UPLOAD("evidence.upload"),
    EVIDENCE_VIEW("evidence.view"),
    EVIDENCE_VIEW_SENSITIVE("evidence.view_sensitive"),
    EVIDENCE_SEAL("evidence.seal"),

    REPORT_EXPORT_CASE_SUMMARY("report.export_case_summary"),
    REPORT_EXPORT_SENSITIVE_EVIDENCE("report.export_sensitive_evidence");

    private final String value;

    Action(String value) {
        this.value = value;
    }

    public String value() {
        return value;
    }
}

public final class PermissionCatalog {
    private final Map<String, PermissionDefinition> definitions;

    public PermissionCatalog(Collection<PermissionDefinition> definitions) {
        this.definitions = definitions.stream()
            .collect(Collectors.toUnmodifiableMap(PermissionDefinition::name, d -> d));
    }

    public PermissionDefinition requireKnown(String name) {
        PermissionDefinition definition = definitions.get(name);
        if (definition == null) {
            throw new UnknownPermissionException(name);
        }
        return definition;
    }

    public boolean isKnown(String name) {
        return definitions.containsKey(name);
    }
}

public record PermissionDefinition(
    String name,
    ResourceType resourceType,
    OperationKind operationKind,
    RiskLevel riskLevel,
    boolean objectLevelRequired,
    boolean auditRequired,
    boolean stateCheckRequired
) {}

role -> permissions

user:U-10
  memberOf group:regional-a-investigators

group:regional-a-investigators
  assigned role:case_investigator

role:case_investigator
  grants capability:case_investigation

capability:case_investigation
  grants permission:case.view
  grants permission:case.edit_draft
  grants permission:evidence.upload
  grants permission:finding.submit

permission:finding.submit
  resourceType: finding
  requires:
    - case.status in [UNDER_REVIEW, ESCALATED]
    - user is assigned investigator of case
    - case.tenant == user.activeTenant
  obligations:
    - audit_decision

public record EffectivePermission(
    UserId userId,
    TenantId tenantId,
    String permission,
    Set<String> scopes,
    Instant validFrom,
    Instant validUntil,
    String source,
    long policyVersion
) {}

public AuthorizationDecision decide(AuthorizationRequest request) {
    boolean hasBasePermission = permissionResolver
        .hasPermission(request.subject(), request.tenantId(), request.action().value());

    if (!hasBasePermission) {
        return AuthorizationDecision.deny("MISSING_PERMISSION");
    }

    RelationshipResult relationship = relationshipResolver.check(
        request.subject(),
        request.action(),
        request.resource()
    );

    if (!relationship.allowed()) {
        return AuthorizationDecision.deny("RELATIONSHIP_NOT_SATISFIED");
    }

    AttributeResult attributes = attributePolicy.evaluate(request);

    if (!attributes.allowed()) {
        return AuthorizationDecision.deny(attributes.reason());
    }

    return AuthorizationDecision.allow()
        .withObligation(Obligation.auditDecision())
        .build();
}

case_investigator_jakarta_low_risk_sensitive_export_disabled

role: case_investigator
permission: finding.submit
constraints:
  - tenant == active tenant
  - case.jurisdiction in subject.jurisdictions
  - subject is assigned to case
  - case.status permits submission

String scope = "ALL";

public sealed interface AccessScope permits GlobalScope, TenantScope, JurisdictionScope,
        OrganizationScope, ResourceScope, RelationshipScope, TemporaryScope {}

public record GlobalScope() implements AccessScope {}
public record TenantScope(TenantId tenantId) implements AccessScope {}
public record JurisdictionScope(JurisdictionId jurisdictionId) implements AccessScope {}
public record OrganizationScope(OrganizationId organizationId) implements AccessScope {}
public record ResourceScope(ResourceRef resource) implements AccessScope {}
public record RelationshipScope(String relation) implements AccessScope {}
public record TemporaryScope(AccessScope delegate, Instant validUntil) implements AccessScope {}

decision cache key = subject + action + resource + relevant scope + policy version + attribute version

public record Delegation(
    DelegationId id,
    UserId delegator,
    UserId delegatee,
    Set<String> permissions,
    AccessScope scope,
    Instant validFrom,
    Instant validUntil,
    String reason,
    DelegationStatus status
) {}

delegatee cannot receive more authority than delegator effectively has

public void createDelegation(UserId delegator, CreateDelegationCommand command) {
    for (String permission : command.permissions()) {
        authz.verify(AuthorizationRequest.command()
            .subject(PrincipalRef.user(delegator))
            .action(Action.DELEGATION_CREATE)
            .resource(ResourceRef.scope(command.scope()))
            .context(Map.of(
                "delegatedPermission", permission,
                "delegatee", command.delegatee()
            ))
            .build());

        authz.verify(AuthorizationRequest.command()
            .subject(PrincipalRef.user(delegator))
            .action(Action.from(permission))
            .resource(ResourceRef.scope(command.scope()))
            .build());
    }

    delegationRepository.save(...);
}

allow finding.approve if:
  user has finding.approve
  finding.status == SUBMITTED
  finding.submittedBy != user.id

public void approveFinding(PrincipalRef principal, FindingId findingId, ApproveFindingCommand command) {
    Finding finding = findingRepository.getRequired(findingId);

    authz.verify(AuthorizationRequest.command()
        .subject(principal)
        .action(Action.FINDING_APPROVE)
        .resource(ResourceRef.finding(finding.id(), finding.tenantId()))
        .resourceAttributes(FindingAttributes.from(finding))
        .build());

    finding.approve(principal.userId(), command.reason());
    findingRepository.save(finding);
}

public void approve(UserId approver, String reason) {
    if (submittedBy.equals(approver)) {
        throw new SeparationOfDutyViolation("Submitter cannot approve own finding");
    }
    if (status != FindingStatus.SUBMITTED) {
        throw new InvalidFindingTransitionException(status, FindingStatus.APPROVED);
    }
    this.status = FindingStatus.APPROVED;
    this.approvedBy = approver;
    this.approvedReason = reason;
}

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface RequiresAction {
    Action value();
}

@RequiresAction(Action.CASE_VIEW)
@GET
@Path("/cases/{caseId}")
public Response getCase(@PathParam("caseId") UUID caseId) {
    CaseDto dto = caseQueryService.getCase(currentPrincipal(), new CaseId(caseId));
    return Response.ok(dto).build();
}

POST /authorization/batch-decide

{
  "decisions": [
    { "action": "case.view", "resource": { "type": "case", "id": "CASE-100" } },
    { "action": "case.assign", "resource": { "type": "case", "id": "CASE-100" } },
    { "action": "case.closure.approve", "resource": { "type": "case", "id": "CASE-100" } }
  ]
}

{
  "decisions": [
    { "action": "case.view", "effect": "ALLOW" },
    { "action": "case.assign", "effect": "DENY", "reasonCode": "NOT_SUPERVISOR_FOR_JURISDICTION" },
    { "action": "case.closure.approve", "effect": "DENY", "reasonCode": "CASE_NOT_CLOSURE_RECOMMENDED" }
  ]
}

UI permission = hint
backend permission = enforcement

public interface CaseQueryRepository {
    Page<CaseSummaryRow> searchVisibleCases(
        UserId userId,
        TenantId tenantId,
        CaseSearchCriteria criteria,
        Pageable pageable
    );
}

select c.id, c.case_number, c.status, c.priority, c.created_at
from cases c
where c.tenant_id = :tenant_id
  and (
      c.owner_id = :user_id
      or c.assignee_id = :user_id
      or exists (
          select 1
          from jurisdiction_membership jm
          where jm.user_id = :user_id
            and jm.jurisdiction_id = c.jurisdiction_id
      )
  )
  and (:status is null or c.status = :status)
order by c.created_at desc
limit :limit offset :offset;

case.search uses visible_case predicate
case.export uses exportable_case predicate + enhanced audit

public void requestSensitiveReport(PrincipalRef principal, ReportRequest command) {
    authz.verify(... REPORT_EXPORT_SENSITIVE_EVIDENCE ...);

    reportJobRepository.enqueue(new ReportJob(
        command.reportType(),
        principal.userId(),
        command.filters(),
        authorizationSnapshot.capture(principal, Action.REPORT_EXPORT_SENSITIVE_EVIDENCE)
    ));
}

public void executeReportJob(ReportJob job) {
    AuthorizationSnapshot snapshot = job.authorizationSnapshot();

    authz.verifySnapshot(snapshot);

    if (job.requiresFreshAuthorization()) {
        authz.verify(AuthorizationRequest.command()
            .subject(PrincipalRef.user(job.requestedBy()))
            .action(Action.REPORT_EXPORT_SENSITIVE_EVIDENCE)
            .resource(ResourceRef.report(job.id(), job.tenantId()))
            .context(job.executionContext())
            .build());
    }

    reportGenerator.generate(job);
}

name: case.closure.approve
description: Approve a recommendation to close a regulatory case.
resourceType: case
riskLevel: critical
ownerTeam: enforcement-platform
introducedIn: 2026.07
objectLevelRequired: true
stateCheckRequired: true
auditRequired: true
sodRequired: true
allowedForRoles:
  - enforcement_approver
constraints:
  - case.status == CLOSURE_RECOMMENDED
  - subject.id != case.closureRecommendedBy
  - subject.jurisdictions contains case.jurisdictionId
obligations:
  - audit_decision
  - require_reason

case.update

case.edit_draft
case.change_priority
case.assign
case.escalate
case.closure.approve

@PreAuthorize("hasRole('ADMIN')")

@PreAuthorize("@caseGuard.canAssign(authentication, #caseId)")

authz.verify(commandRequest(principal, Action.CASE_ASSIGN, caseRecord));

case-detail-page-edit-button

regional_case_supervisor_jakarta_sensitive_level_2_approver

authz.can(user, "case.close")

user U-10 allowed permission case.update

user U-10 allowed case.closure.approve on case CASE-100 because role=enforcement_approver, jurisdiction=JK-01, case.status=CLOSURE_RECOMMENDED, policyVersion=42

{
  "permissions": ["case.approve", "case.export"]
}

public interface AuthorizationService {
    AuthorizationDecision decide(AuthorizationRequest request);

    default void verify(AuthorizationRequest request) {
        AuthorizationDecision decision = decide(request);
        if (!decision.allowed()) {
            throw new AccessDeniedException(decision.reasonCode());
        }
    }
}

public record ProtectedOperation(
    Action action,
    ResourceType resourceType,
    OperationKind operationKind,
    RiskLevel riskLevel,
    boolean requiresObject,
    boolean requiresState,
    boolean requiresAudit,
    Set<String> requiredAttributes
) {}

public interface PermissionResolver {
    boolean hasBasePermission(SubjectRef subject, TenantId tenantId, Action action);
}

public interface RelationshipResolver {
    RelationshipResult check(SubjectRef subject, Action action, ResourceRef resource);
}

public interface AttributePolicyEvaluator {
    AttributeResult evaluate(AuthorizationRequest request);
}

public final class DefaultAuthorizationService implements AuthorizationService {
    private final PermissionCatalog catalog;
    private final PermissionResolver permissionResolver;
    private final RelationshipResolver relationshipResolver;
    private final AttributePolicyEvaluator attributePolicyEvaluator;
    private final AuthorizationAuditSink auditSink;

    @Override
    public AuthorizationDecision decide(AuthorizationRequest request) {
        ProtectedOperation operation = catalog.requireOperation(request.action());

        AuthorizationDecision decision = evaluate(operation, request);
        auditSink.record(request, decision);
        return decision;
    }

    private AuthorizationDecision evaluate(ProtectedOperation operation, AuthorizationRequest request) {
        if (operation.requiresObject() && request.resource().isUnspecified()) {
            return AuthorizationDecision.deny("RESOURCE_REQUIRED");
        }

        if (!permissionResolver.hasBasePermission(
                request.subject(), request.tenantId(), request.action())) {
            return AuthorizationDecision.deny("MISSING_BASE_PERMISSION");
        }

        if (!relationshipResolver.check(
                request.subject(), request.action(), request.resource()).allowed()) {
            return AuthorizationDecision.deny("RELATIONSHIP_DENIED");
        }

        AttributeResult attributeResult = attributePolicyEvaluator.evaluate(request);
        if (!attributeResult.allowed()) {
            return AuthorizationDecision.deny(attributeResult.reasonCode());
        }

        return AuthorizationDecision.allow()
            .reasonCode("ALLOWED_BY_POLICY")
            .policyVersion(attributeResult.policyVersion())
            .obligations(operation.requiresAudit()
                ? Set.of(Obligation.auditDecision())
                : Set.of())
            .build();
    }
}

[ ] Apa nama operation dalam bahasa domain?
[ ] Resource type apa yang dilindungi?
[ ] Apakah ini command atau query?
[ ] Apakah butuh object-level authorization?
[ ] Apakah butuh field-level authorization?
[ ] Apakah butuh query scoping?
[ ] State apa yang memperbolehkan operation ini?
[ ] Relationship apa yang harus benar?
[ ] Tenant/jurisdiction/organization boundary apa yang berlaku?
[ ] Apakah ada data classification?
[ ] Apakah ada separation of duty?
[ ] Apakah delegation boleh?
[ ] Apakah operation boleh dilakukan service account?
[ ] Apakah operation bisa dijalankan async?
[ ] Apakah decision boleh di-cache?
[ ] Reason code apa untuk deny?
[ ] Audit apa yang wajib?
[ ] Test negatif apa yang harus ada?

A regulatory enforcement platform manages cases, evidence, findings, enforcement actions, and closure decisions.
Investigators work on assigned cases.
Reviewers review findings.
Approvers approve enforcement actions.
Supervisors assign and escalate cases.
Sensitive evidence requires clearance.
A user cannot approve their own submission.
Closed cases can only be reopened by a special approver.

case.view
case.view_sensitive
case.create_draft
case.edit_draft
case.submit_for_review
case.assign
case.escalate
case.closure.recommend
case.closure.approve
case.reopen

evidence.upload
evidence.view
evidence.view_sensitive
evidence.seal

finding.create
finding.submit
finding.review
finding.approve
finding.reject

enforcement_action.propose
enforcement_action.approve
enforcement_action.issue

report.export_case_summary
report.export_sensitive_evidence

allow if:
  subject has permission finding.approve
  tenant matches
  finding.status == SUBMITTED
  subject is reviewer for finding.case OR subject is supervisor for jurisdiction
  subject.id != finding.submittedBy
  subject.clearance >= finding.sensitivity
obligations:
  audit_decision
  require_reason

allow if:
  subject has permission case.view_sensitive
  tenant matches
  subject is assigned/reviewer/supervisor/approver for case
  subject.clearance >= case.sensitivity
  case is not sealed OR subject has sealed_case.view
obligations:
  audit_sensitive_access