feat(system): enhance system architecture

internal/meta/audit.go

@@ -0,0 +1,45 @@
+package meta
+
+import (
+	"context"
+
+	"nadir/internal/auditlog"
+
+	"github.com/danielgtaylor/huma/v2"
+)
+
+type AuditListInput struct {
+	Limit int `query:"limit" default:"200" minimum:"1" maximum:"10000" doc:"Max entries to return, newest first"`
+}
+
+type AuditListOutput struct {
+	Body struct {
+		Entries []auditlog.Entry `json:"entries" doc:"Recorded actions, newest first"`
+	}
+}
+
+// RegisterAudit wires GET /api/audit. It lives in meta because a full module
+// for a single read-only endpoint is too shallow — the interface is nearly as
+// wide as the implementation. The audit trail is produced by the RBAC
+// middleware; this endpoint provides read-only access to it.
+func RegisterAudit(api huma.API, store *auditlog.Store) {
+	huma.Register(api, huma.Operation{
+		OperationID: "audit-list",
+		Method:      "GET",
+		Path:        "/api/audit",
+		Summary:     "List recorded actions",
+		Description: "Returns the audit trail of privileged write operations " +
+			"(who, what, when, result), newest first.",
+		Tags:     []string{"Meta", "Audit"},
+		Metadata: map[string]any{"module": "audit", "permission": "read"},
+		Errors:   []int{401, 403, 500},
+	}, func(ctx context.Context, in *AuditListInput) (*AuditListOutput, error) {
+		entries, err := store.List(in.Limit)
+		if err != nil {
+			return nil, huma.Error500InternalServerError("read audit log failed", err)
+		}
+		out := &AuditListOutput{}
+		out.Body.Entries = entries
+		return out, nil
+	})
+}