update docs

server/middleware/auth.go

@@ -9,6 +9,7 @@ import (
 	"time"
 	"vctp/internal/auth"
 	"vctp/internal/settings"
+	"vctp/server/audit"
 )
 
 const (
@@ -61,6 +62,7 @@ func RequireAuth(logger *slog.Logger, cfg *settings.Settings) Handler {
 	})
 	if err != nil {
 		logger.Error("auth middleware init failed", "error", err)
+		audit.LogAuthEvent(logger, nil, "auth_middleware_init", "error", "reason", "jwt_service_init_failed", "error", err)
 		return func(next http.Handler) http.Handler {
 			return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 				writeJSONAuthError(w, http.StatusServiceUnavailable, "authentication service unavailable")
@@ -73,6 +75,7 @@ func RequireAuth(logger *slog.Logger, cfg *settings.Settings) Handler {
 			token, hasHeader, parseOK := extractBearerToken(r.Header.Get("Authorization"))
 			if !hasHeader {
 				if mode == authModeRequired {
+					audit.LogAuthEvent(logger, r, "token_validation", "deny", "reason", "missing_bearer_token", "auth_mode", mode)
 					writeJSONAuthError(w, http.StatusUnauthorized, "missing bearer token")
 					return
 				}
@@ -80,13 +83,14 @@ func RequireAuth(logger *slog.Logger, cfg *settings.Settings) Handler {
 				return
 			}
 			if !parseOK {
+				audit.LogAuthEvent(logger, r, "token_validation", "deny", "reason", "invalid_bearer_header", "auth_mode", mode)
 				writeJSONAuthError(w, http.StatusUnauthorized, "invalid bearer token")
 				return
 			}
 
 			claims, err := jwtSvc.VerifyToken(token)
 			if err != nil {
-				logger.Warn("auth middleware token validation failed", "path", r.URL.Path, "error", err)
+				audit.LogAuthEvent(logger, r, "token_validation", "deny", "reason", "invalid_token", "error", err)
 				writeJSONAuthError(w, http.StatusUnauthorized, "invalid bearer token")
 				return
 			}
@@ -111,10 +115,12 @@ func RequireRole(requiredRoles ...string) Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			claims, ok := ClaimsFromContext(r.Context())
 			if !ok {
+				audit.LogAuthEvent(nil, r, "role_authorization", "deny", "reason", "missing_auth_context", "required_roles", normalizedRequired)
 				writeJSONAuthError(w, http.StatusUnauthorized, "missing authentication context")
 				return
 			}
 			if !hasAnyRequiredRole(claims.Roles, normalizedRequired) {
+				audit.LogAuthEvent(nil, r, "role_authorization", "deny", "reason", "insufficient_role", "required_roles", normalizedRequired, "user_roles", normalizeRoles(claims.Roles), "subject", claims.Subject)
 				writeJSONAuthError(w, http.StatusForbidden, "insufficient role")
 				return
 			}