Regulatory Case Evidence and Document Processing

- valid upload accepted for processing within 2 seconds
- 99% scanned within 10 minutes
- no accepted file without checksum
- no download without fresh authorization
- presigned download URL TTL <= 5 minutes
- evidence retained 7 years after case closure unless legal hold active
- DB credential rotated every 30 days without downtime
- config changes traceable to Git PR
- production scan cannot be disabled by config
- audit events durably stored within 60 seconds

public record EvidenceId(String value) {}
public record CaseId(String value) {}
public record FileId(String value) {}

public enum EvidenceStatus {
    DRAFT,
    UPLOAD_PENDING,
    QUARANTINED,
    SCANNING,
    ACCEPTED,
    REJECTED,
    LOCKED_BY_CASE,
    ARCHIVED,
    DELETION_REQUESTED,
    DELETED
}

public record FileIntegrity(
    long sizeBytes,
    String sha256,
    String detectedContentType,
    Instant verifiedAt
) {}

public record RetentionState(
    String policyVersion,
    Instant retentionUntil,
    boolean legalHold
) {}

EvidenceStatus.ACCEPTED requires:
- fileId exists
- object exists
- checksum verified
- scan decision CLEAN
- metadata committed
- audit event emitted

UPLOAD_PENDING -> ACCEPTED
REJECTED -> ACCEPTED
DELETED -> ACCEPTED
LOCKED_BY_CASE -> DELETED without retention/legal decision

1. POST /cases/{caseId}/evidence/upload-sessions
2. authorize actor
3. create metadata status=UPLOAD_PENDING
4. issue presigned PUT to quarantine/temp key
5. client uploads object
6. client completes session
7. API verifies object metadata
8. transition to QUARANTINED
9. enqueue scan

1. stream multipart request
2. enforce size/quota
3. compute checksum while streaming
4. write to temp/quarantine storage
5. create metadata
6. enqueue scan

multipartFile.getBytes()

quarantine/{yyyy}/{mm}/{dd}/{fileId}/payload
accepted/{yyyy}/{mm}/{dd}/{fileId}/payload
archive/{yyyy}/{mm}/{dd}/{fileId}/payload

cases/{caseId}/{originalFilename}

fileId
tenantId
ownerService=evidence-service
lifecycle=quarantine
checksumSha256
correlationId

CREATE TABLE evidence_file (
    evidence_id TEXT PRIMARY KEY,
    file_id TEXT NOT NULL UNIQUE,
    case_id TEXT NOT NULL,
    tenant_id TEXT NOT NULL,
    status TEXT NOT NULL,

    bucket TEXT NOT NULL,
    object_key TEXT NOT NULL,
    object_version TEXT NULL,

    original_filename_display TEXT NULL,
    detected_content_type TEXT NULL,
    size_bytes BIGINT NULL,
    sha256 TEXT NULL,

    scan_decision TEXT NULL,
    scan_policy_version TEXT NULL,
    scan_completed_at TIMESTAMPTZ NULL,

    retention_policy_version TEXT NULL,
    retention_until TIMESTAMPTZ NULL,
    legal_hold BOOLEAN NOT NULL DEFAULT FALSE,

    created_by TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL,
    updated_at TIMESTAMPTZ NOT NULL,
    version BIGINT NOT NULL
);

ALTER TABLE evidence_file
ADD CONSTRAINT accepted_evidence_integrity_check
CHECK (
  status <> 'ACCEPTED'
  OR (
    sha256 IS NOT NULL
    AND size_bytes IS NOT NULL
    AND scan_decision = 'CLEAN'
    AND object_key IS NOT NULL
  )
);

evidence:
  upload:
    max-size-mb: 500
    direct-upload-enabled: true
    presigned-upload-ttl: 5m
  download:
    presigned-download-ttl: 2m
    require-fresh-authorization: true
  scan:
    required: true
    timeout: 60s
  retention:
    default-years-after-case-closure: 7
    legal-hold-enabled: true

scan.required must be true
download.presigned-download-ttl <= 5m
retention.legal-hold-enabled must be true
upload.max-size-mb <= platform maximum

Git -> validation -> GitOps -> ConfigMap -> Spring Boot typed properties -> startup validation

create new -> distribute -> canary -> rollout -> prove new use -> revoke old

secret_current_version_info
DB audit login user
readiness DB check
dependency_auth_failure_total stable
old credential usage zero

canViewEvidenceMetadata
canDownloadEvidencePayload
canAttachEvidence
canDeleteEvidence
canApplyLegalHold
canExportEvidencePackage

Metadata access is not payload access.
Download grant requires fresh authorization.
Presigned URL issuance is audited.
Presigned URL is short-lived.

Authorization cache may improve performance,
but critical download action must use fresh or bounded-staleness decision.

evidence_upload_session_created_total
evidence_upload_completed_total
evidence_scan_pending_age_seconds
evidence_scan_completed_total{decision}
evidence_accepted_total
evidence_download_granted_total
evidence_download_denied_total{reason}
evidence_deletion_blocked_total{reason}
metadata_payload_mismatch_total
audit_outbox_oldest_age_seconds
config_current_version_info
secret_seconds_until_expiry
secret_refresh_failure_total
dependency_auth_failure_total

accepted evidence without checksum > 0
metadata-payload mismatch for accepted evidence > 0
scan pending p95 > 10 minutes
audit outbox oldest age > 60 seconds
secret expires in < 10 minutes and refresh failing
prod config scan.required false
mixed critical config versions beyond rollout window
old DB credential used after rotation window

[ ] invalid lifecycle transition rejected
[ ] accepted evidence requires clean scan/checksum
[ ] legal hold blocks delete
[ ] secret value toString redacts
[ ] config validation rejects unsafe prod values

[ ] direct upload session flow
[ ] object verification flow
[ ] scan worker flow
[ ] download authorization flow
[ ] audit outbox transaction
[ ] secret missing readiness
[ ] config startup validation

[ ] storage timeout
[ ] scanner timeout
[ ] duplicate event
[ ] DB deadlock/retry
[ ] audit sink down
[ ] secret rotation bad credential
[ ] ConfigMap drift
[ ] pod kill during processing

[ ] content type spoof
[ ] path traversal filename
[ ] unauthorized download
[ ] presigned URL not logged
[ ] ConfigMap secret scanner
[ ] broad RBAC forbidden
[ ] actuator restricted

No category below 4.
Critical systems need 5 in security, audit, retention, and recovery.

- typed config
- secret manager integration
- basic metadata model
- object storage adapter
- upload session
- lifecycle state machine
- audit outbox
- checksum verification

- scanner pipeline
- presigned direct upload/download
- authorization policy integration
- retention/legal hold
- reconciliation jobs
- metrics/logs/traces
- dashboards/alerts

- secret rotation automation
- config promotion platform
- chaos testing
- forensic drill
- access review
- cost controls
- object lock/versioning if required

- reusable file platform library
- config schema registry
- secret inventory and orchestrator
- standardized ADR/runbook templates
- self-service dashboards
- policy-as-code

see that MultipartFile.getOriginalFilename is not authority
see that ConfigMap update does not equal safe runtime reload
see that Kubernetes Secret update does not rotate DB connections
see that object storage key is not domain identity
see that cache can become security state
see that audit log must be durable before destructive operation
see that secret revocation before proof causes outage
see that retention is a domain rule, not only lifecycle policy
see that observability must map to invariants
see that rollback must be designed before rollout

Separate responsibility.
Name the artifact.
Own the lifecycle.
Validate the boundary.
Preserve the invariant.
Emit evidence.
Observe stress.
Reconcile drift.
Practice failure.

bytes + metadata + lifecycle + policy + audit

truth + ownership + consistency + reconstruction

schema + provenance + validation + promotion + rollback

capability + least privilege + TTL + rotation + proof

invariant + observability + runbook + game day + evidence

[ ] File identity independent of storage key
[ ] Metadata and payload consistency strategy exists
[ ] Accepted files require checksum and trust decision
[ ] Upload/download authorization separated
[ ] Presigned URLs short-lived and not logged
[ ] State source of truth explicit
[ ] Critical state not stored only in local disk/memory
[ ] Config typed, validated, versioned, and governed
[ ] Runtime reload only where safe
[ ] Secrets stored in secret manager or encrypted GitOps path
[ ] Secret rotation strategy tested
[ ] Least privilege IAM/RBAC applied
[ ] Sensitive data redaction tested
[ ] Audit events cover material decisions
[ ] Audit pipeline durable and monitored
[ ] Retention/legal hold enforced before delete
[ ] Reconciliation jobs deployed
[ ] Dashboards and alerts map to invariants
[ ] Failure/chaos tests run
[ ] Runbooks exist and are current
[ ] ADRs document major decisions

We uploaded the file.
We set the config.
We stored the secret.
We have logs.

We know who owns the file.
We know its lifecycle state.
We know its checksum.
We know who can access it.
We know which config version influenced behavior.
We know which secret version was used.
We know how it fails.
We know how it recovers.
We know how to prove what happened.