feat(shared): add audit package

[ginaxu1]

Summary

Land shared/audit on its own so it can be tagged as a real shared release (e.g. shared/v0.4.0) before payment and storage import it.

Auditor is about to become part of the exported payment and storage service surfaces. Those modules cannot require github.com/OpenNSW/core/shared v0.3.0 for a package that does not exist at that tag, and a replace => ../shared directive is not transitive — it only works when the declaring module is built from this monorepo checkout.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Other (please describe):

Changes Made

• Add shared/audit with Auditor, Event, Argus-aligned Action / Status, and a domain-owned Details interface (Metadata() map[string]any).
• Document the package in shared/README.md.
• Unit tests for Details round-trip and nil-Details behavior.

No consumer (payment / storage) changes in this PR.

Testing

• I have tested this change locally
• I have added tests that prove my fix is effective or that my feature works
• I have tested edge cases
• All existing tests pass

GOWORK=off go test -C shared ./... passes.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have checked that there are no merge conflicts

Related Issues

Split out of #149 at reviewer request. After this merges, please tag shared/v0.4.0 so #149 can bump require github.com/OpenNSW/core/shared in payment and storage and drop the local replace directives.

Blocks: #149, OpenNSW/nsw-srilanka#285

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0bb9dedd-8d13-48ff-8638-36197f160b22

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mushrafmim]

Event currently grows a set of fields per domain (GatewayID/Reference/Status for payment, Key/Filename/MimeType/Size for storage), with the comment "switch on Domain first" as the only thing keeping domains from reading each other's zero-valued fields. As more domains onboard (auth, notifications, ...), this struct grows without bound and loses any compile-time guarantee that a payment event doesn't carry storage fields.

Suggest replacing the domain-specific fields with a Details interface, so each domain owns its own payload type instead of shared/audit growing a field per domain:

type Details interface {
    Metadata() map[string]any
}

type Event struct {
    TraceID    string
    Timestamp  time.Time
    EventType  string
    Action     Action
    Status     Status
    ActorType  string
    ActorID    string
    TargetType string
    TargetID   string

    Details Details // nil when a domain has nothing extra to attach
}

payment.AuditDetails / storage.AuditDetails would live in their own packages and implement Metadata().

Worth doing now, while there are no consumers of this package yet. It also happens to line up field-for-field with github.com/LSFLK/argus/pkg/audit.AuditLogRequest (Action already uses Argus's CREATE/READ/UPDATE/DELETE values, Status SUCCESS/FAILURE instead of a Failure bool) — so if this is meant to eventually feed Argus, a bridge to AuditLogRequest becomes a straight field copy rather than a translation layer.

[ginaxu1]

Done, Event no longer has per-domain fields.

shared/audit now has Argus-aligned Action/Status plus a Details interface (Metadata() map[string]any). Domain payloads stay in the emitting packages (payment.AuditDetails / storage.AuditDetails on #149).