update docs

server/audit/auth.go

@@ -0,0 +1,33 @@
+package audit
+
+import (
+	"log/slog"
+	"net/http"
+)
+
+const authAuditMessage = "auth_audit"
+
+// LogAuthEvent emits a structured auth audit log record.
+// It is intentionally generic and should never receive raw credentials or tokens.
+func LogAuthEvent(logger *slog.Logger, r *http.Request, event string, outcome string, attrs ...any) {
+	if logger == nil {
+		logger = slog.Default()
+	}
+
+	logAttrs := make([]any, 0, 14+len(attrs))
+	logAttrs = append(logAttrs, "category", "auth", "event", event, "outcome", outcome)
+	if r != nil {
+		requestPath := r.URL.RequestURI()
+		if requestPath == "" {
+			requestPath = r.URL.Path
+		}
+		logAttrs = append(logAttrs,
+			"method", r.Method,
+			"path", requestPath,
+			"remote", r.RemoteAddr,
+		)
+	}
+	logAttrs = append(logAttrs, attrs...)
+
+	logger.Info(authAuditMessage, logAttrs...)
+}