diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index ccdbce7..4061421 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -5,3 +5,4 @@ This page is generated from repository and product-directory project files. - [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-audit/README.md` +- [Repo-docs-AUDIT-TRACE-CONTEXT](Repo-docs-AUDIT-TRACE-CONTEXT) - `/mnt/DATA/git/govoplan-audit/docs/AUDIT_TRACE_CONTEXT.md` diff --git a/Repo-README.md b/Repo-README.md index 178925f..48c6566 100644 --- a/Repo-README.md +++ b/Repo-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-audit/README.md`. > Origin: `repository`. @@ -10,6 +10,10 @@ `govoplan-audit` owns audit API route contributions during the GovOPlaN module split. -This repository owns the live `audit_log` table while preserving the -historical table name. It provides audit API route contributions and is the -target boundary for future audit sink/export capability work. +This repository owns the live `audit_log` table, audit API route +contributions, and the target boundary for future audit sink/export capability +work. + +See [docs/AUDIT_TRACE_CONTEXT.md](docs/AUDIT_TRACE_CONTEXT.md) for the standard +operational context fields used by admin, installer, and module lifecycle audit +entries. diff --git a/Repo-docs-AUDIT-TRACE-CONTEXT.md b/Repo-docs-AUDIT-TRACE-CONTEXT.md new file mode 100644 index 0000000..9022f81 --- /dev/null +++ b/Repo-docs-AUDIT-TRACE-CONTEXT.md @@ -0,0 +1,63 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-audit/docs/AUDIT_TRACE_CONTEXT.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Audit Trace Context + +Operational audit entries should let an administrator answer four questions: + +- who initiated the operation +- what object was changed +- which lifecycle request or run carried the change +- how the entry connects to surrounding request, installer, or worker logs + +The actor, tenant, scope, action, object type, and object ID remain first-class +`audit_log` columns. Additional operational context belongs in `details`. + +## Standard Fields + +Use these fields for admin, module lifecycle, installer, and worker operations: + +- `module_id`: module affected by the operation, when a single module is the + target. +- `request_id`: queued installer/admin request identifier. +- `run_id`: installer/worker run identifier. +- `outcome`: compact state such as `planned`, `queued`, `applied`, + `cancelled`, `failed`, or `completed`. +- `_trace.correlation_id`: request or workflow correlation ID. +- `_trace.causation_id`: event, run, or operation that caused this audit entry. + +Bulk operations may also include concise arrays such as `activated`, +`deactivated`, `mounted`, `planned_modules`, or sanitized `items`. + +## Redaction + +Audit detail payloads must not contain credentials, tokens, raw cookies, +authorization headers, private keys, message bodies, uploaded file content, or +other secret material. Use stable IDs, vault references, or package identifiers +instead. + +The compatibility helper in core, `audit_operation_context`, keeps the standard +fields compact and applies the shared audit redaction pass to additional detail +values. Feature modules should follow the same shape even when they later write +through a dedicated audit sink capability. + +## Module Lifecycle Events + +Module install, uninstall, enable, disable, rollback, and package-catalog +acceptance events should include: + +- `object_type`: `module_install_plan`, `module_install_request`, + `module_state`, or another stable lifecycle object type. +- `object_id`: module ID for single-module actions, otherwise `global` or the + request/run ID. +- `details.module_id`, `details.request_id`, or `details.run_id` when present. +- `details.outcome` with the lifecycle result. +- `details._trace` when the operation originated from a request or queued + daemon action. + +This keeps admin UI timelines, audit exports, and rollback diagnostics aligned +without coupling modules to the audit table implementation.