Audit, Verification, And Retention
Operate audit logs, public verification logs, SIEM exports, anonymization, and retention cleanup.
Audit, Verification, And Retention
The backend records admin/sensitive actions in the audit log and public
verification attempts in verification_log. The maintenance worker handles
retention, verification metadata anonymization, and tamper-evident chain checks.
Audit Routes
| Route | Role | Scope |
|---|---|---|
GET /admin/api/v1/audit | PLATFORM_ADMIN, BILLING_OPERATOR | Recent audit rows across the instance. |
GET /api/v1/audit | CLIENT_ADMIN, AUDITOR | Tenant-scoped audit rows. |
Audit entries are append-oriented and include hash-chain fields. The maintenance worker verifies audit-chain continuity and records metrics/alerts on breaks.
Verification Routes
| Route | Role | Purpose |
|---|---|---|
GET /admin/api/v1/verification-log | PLATFORM_ADMIN, BILLING_OPERATOR | Inspect public verification attempts and statuses. |
GET /admin/api/v1/verification-log/export | PLATFORM_ADMIN, BILLING_OPERATOR | Export verification logs for SIEM or incident review. |
GET / POST /verify | Public | Verify by public code, certificate ID, canonical hash, or tx hash. |
GET / POST /api/v1/public/verify | Public | Versioned public verification alias. |
Public verification attempts store hashed requester IP/user-agent metadata.
Metadata is anonymized according to RETENTION_VERIFICATION_METADATA_TTL.
Verification Statuses
| Status | Meaning |
|---|---|
VALID | Certificate, canonical content, HMAC/PAdES, and anchor checks pass. |
VALID_NO_ANCHOR | Certificate is valid but not anchored. |
REVOKED | Certificate was revoked. |
UNKNOWN_CERTIFICATE | No certificate matched the supplied public identifiers. |
IDENTIFIER_MISMATCH | Multiple identifiers were supplied but did not point to the same certificate. |
INVALID_SIGNATURE | PAdES verification failed. |
INVALID_HMAC | Defensive HMAC verification failed. |
TAMPERED | Canonical data mismatch or integrity failure. |
NOT_ANCHORED | Expected anchor data is missing. |
BLOCKCHAIN_UNAVAILABLE | Chain lookup failed. |
UNAUTHORIZED_ANCHOR_SENDER | Anchor sender is not authorized for the certificate timestamp. |
INVALID_REQUEST | Request did not contain a valid verification lookup. |
RATE_LIMITED | Public verification rate limit rejected the request. |
Retention Settings
| Variable | Default intent |
|---|---|
RETENTION_AUDIT_LOG_TTL | Keep audit logs for 5 years. |
RETENTION_VERIFICATION_LOG_TTL | Keep public verification logs for 5 years. |
RETENTION_VERIFICATION_METADATA_TTL | Clear requester IP/user-agent hashes after 90 days. |
RETENTION_CLEANUP_INTERVAL | Maintenance worker cadence. |
RETENTION_BATCH_SIZE | Maximum rows touched per pass. |
WORM/Object Lock is deferred by product direction in this repository. Do not represent it as active until the product decision changes and storage policy is implemented.
Maintenance Worker
The command is:
/app/worker maintenance
If WORKER_POLL_INTERVAL is unset, the worker uses the configured retention
cleanup interval. It also verifies audit and receipt chains when the chain
verification interval is configured.
Operator Checks
| Check | SQL or route |
|---|---|
| Recent audit entries | GET /admin/api/v1/audit |
| Public verification anomalies | GET /admin/api/v1/verification-log |
| SIEM export | GET /admin/api/v1/verification-log/export |
| Retention progress | Maintenance worker logs and row counts. |
| Audit chain breaks | Grafana integrity metrics and maintenance worker logs. |
When retention prunes the oldest audit rows, the first remaining row becomes the trusted start for later chain verification. Preserve external backups before any retention policy change.