A case may only transition from INVESTIGATION_OPEN to ENFORCEMENT_RECOMMENDED if:
1. actor has CASE_RECOMMEND permission for the case jurisdiction,
2. all mandatory evidence items are attached and hash-verified,
3. conflict-of-interest check is clear or overridden by authorized supervisor,
4. transition emits an immutable audit event,
5. previous state version matches optimistic lock version.

Invariant: <Subject> must/must not <condition> when <context>, unless <explicit exception>, and violation must <failure mode + evidence>.

Invariant: A submitted evidence file must not be replaced in place after case submission; any correction must create a new version linked to the original, preserve original content hash, and emit an audit event.

<Actor> may perform <Action> on <Object> only when <Context/Policy> and system records <Evidence>.

A regional enforcement officer may approve a preliminary finding on a case only when the case jurisdiction matches the officer assignment, the case is in REVIEW_READY state, no conflict flag is active, and the system records actor ID, assignment snapshot, decision reason, previous state, new state, timestamp, request ID, and audit hash-chain link.

<Data asset> must be protected for <property> against <threat actor> while <state: in transit/at rest/in use/in logs/backups> using <mechanism class>, with <key ownership/lifecycle>, and verified by <test/control>.

Citizen national ID must be protected for confidentiality against database read-only compromise while stored in the application database using application-layer envelope encryption; data keys are generated per record group, wrapped by KMS-managed key, rotated every 90 days, and verified by tests proving plaintext does not appear in DB rows, application logs, traces, or message payloads.

A request/event carrying <operation> must be accepted only once within <scope> and <time window>; duplicate or stale requests must be rejected or idempotently resolved with auditable outcome.

A signed partner webhook for enforcement payment confirmation must include event ID, timestamp, body hash, and HMAC signature. The receiver rejects timestamps outside ±5 minutes, rejects duplicate event IDs for 24 hours, and stores verification outcome with correlation ID.

For <security-relevant action>, the system must emit <audit event fields> to <append-only sink> before/within the same transaction as <state mutation>, and failure must <fail closed or defined compensating control>.

For every case status transition, the system must emit an audit event containing actor ID, acting role, tenant/jurisdiction, case ID, previous state, new state, reason code, request ID, source IP category, timestamp, and previous audit hash before committing the transition; if audit emission fails, the transition must fail closed.

Because <condition/design weakness>, <threat actor> can <attack action>, causing <impact>, affecting <scope>, unless <control> is implemented and verified by <evidence>.

Because case transition authorization is checked only at endpoint role level, an internal officer with generic REVIEWER role can approve cases outside their jurisdiction, causing unauthorized enforcement decisions and regulatory challenge exposure across all tenants, unless object-level jurisdiction policy is enforced and verified by negative authorization tests.

Local requirement -> ASVS category -> Implementation task -> Test evidence -> Residual risk

# Secure Design: <Feature/System>

## 1. Context
- Business purpose
- Data flow
- Trust boundaries
- External dependencies

## 2. Assets
- Data assets
- Identity assets
- Integrity assets
- Operational assets

## 3. Actors
- Human actors
- Service actors
- Admin actors
- External/partner actors
- Attacker assumptions

## 4. Abuse Cases
- Abuse case list
- Credibility and impact

## 5. Security Requirements
- Actor-action-object-context-evidence requirements
- Crypto/data protection requirements
- Audit requirements
- Availability/abuse requirements

## 6. Security Invariants
- Always-true rules
- Enforcement points

## 7. Controls
- Prevent/detect/respond/recover controls
- Java/framework/API choices

## 8. Verification Plan
- Unit tests
- Integration tests
- Negative security tests
- Manual review
- Operational checks

## 9. Residual Risk
- Accepted risks
- Owner
- Expiry/review date

## 10. Decision Records
- Key/cert/token/session/authz decisions

REQ-CASE-001: A case status transition must be accepted only when the authenticated actor has object-level permission for the case jurisdiction, the requested transition is valid from current state, and the actor satisfies role/state separation constraints.

REQ-CASE-002: Every successful case status transition must create an append-only audit event containing actor, subject, jurisdiction, previous state, new state, reason code, evidence version references, request ID, timestamp, and previous audit hash.

REQ-CASE-003: A transition request must include idempotency key scoped to actor + case + requested transition; duplicate request with same body returns original outcome, while same key with different body is rejected and audited.

REQ-CASE-004: Approved decision fields must not be updated in place. Correction requires a superseding decision record, correction reason, supervisor authorization, and audit linkage to original record.

INV-CASE-001: No case state change is committed without an audit event in the same transaction boundary or a fail-closed equivalent.

INV-CASE-002: No actor can approve a case where actor.jurisdiction does not include case.jurisdiction at decision time.

INV-CASE-003: Approved decision records are immutable; corrections are append-only superseding records.

@Transactional
public TransitionResult transitionCase(TransitionCommand command, Actor actor) {
    CaseRecord current = caseRepository.loadForUpdate(command.caseId());

    authorization.requireAllowed(actor, "case.transition", current);
    stateMachine.requireValidTransition(current.status(), command.targetStatus());
    separationOfDuties.requireSatisfied(actor, current, command.targetStatus());

    IdempotencyDecision idem = idempotency.checkOrReserve(
        command.idempotencyKey(),
        actor.id(),
        command.caseId(),
        command.canonicalHash()
    );

    if (idem.isReplayOfSameRequest()) {
        return idem.previousResult();
    }

    CaseRecord updated = current.transitionTo(command.targetStatus(), command.reasonCode());

    AuditEvent event = AuditEvent.caseTransition()
        .actor(actor)
        .caseId(current.id())
        .previousState(current.status())
        .newState(updated.status())
        .reason(command.reasonCode())
        .requestId(command.requestId())
        .previousAuditHash(auditRepository.latestHash(current.id()))
        .build();

    caseRepository.save(updated);
    auditRepository.append(event); // must fail closed with transaction
    idempotency.complete(command.idempotencyKey(), updated.resultReference());

    return TransitionResult.success(updated.id(), updated.status());
}

Given <asset/context/state>
And <actor identity/policy>
When <action/attack/failure>
Then <expected security decision>
And <evidence/side effect>
And <no forbidden side effect>

Given a case in REVIEW_READY under jurisdiction A
And an authenticated officer assigned only to jurisdiction B
When the officer requests APPROVE transition
Then the API returns authorization failure
And no case state is changed
And an authorization-denied audit event is recorded
And no decision notification is published

We accept the risk because unlikely.

Risk: Partner webhook replay beyond 24 hours could duplicate notification processing if event ID store is lost.
Reason accepted: Downstream operation is idempotent by payment reference; financial mutation has independent uniqueness constraint.
Compensating controls: Daily reconciliation detects duplicate notification outcomes; duplicate mutation impossible due to DB unique constraint.
Owner: Payments Engineering + Risk Owner.
Review date: 2026-09-30.

Add encryption.

Implement application-layer envelope encryption for citizen national ID in CaseProfile table:
- AES-GCM using per-record DEK
- DEK wrapped by KMS key alias/case-pii-v1
- key reference stored with ciphertext
- plaintext absent from DB/logs/traces
- migration supports existing rows
- tests cover decrypt failure, wrong AAD, tampered ciphertext, and key unavailable behavior

REQ-WH-001: The webhook receiver must accept requests only over HTTPS from configured endpoint path and must not rely on source IP as sole authentication.

REQ-WH-002: Each webhook request must include partner ID, event ID, timestamp, body SHA-256 digest, key ID, and HMAC signature over canonical request components.

REQ-WH-003: The receiver must select the verification secret by partner ID and key ID, reject unknown key IDs, and support overlapping active keys during rotation.

REQ-WH-004: The receiver must reject timestamps outside ±5 minutes unless partner-specific risk acceptance exists.

REQ-WH-005: The receiver must reject duplicate event IDs within 24 hours; duplicate event with identical body returns previous processing result if idempotent, while duplicate event ID with different body is rejected and audited.

REQ-WH-006: Signature comparison must use constant-time comparison and must fail closed on malformed canonicalization input.

REQ-WH-007: Verification failures must emit security events without logging raw secrets, full signatures, or sensitive payload fields.

INV-WH-001: No webhook side effect occurs before signature, timestamp, and replay checks pass.

INV-WH-002: A webhook event ID maps to exactly one canonical body hash within the replay retention window.

INV-WH-003: Unknown partner ID or key ID never falls back to a default shared secret.

Threat -> Requirement -> Invariant -> Control -> Code shape -> Test -> Operational evidence -> Risk decision