Feat/unified error envelope, unified response migration, and validation hardening

[Rashed99Azm]

refactor: unify error messages and responses across all API layers

Summary

Enforces Response<T> as the single response contract across the entire API surface, ensuring consistent response payloads regardless of where a request is handled.

This change completes the response standardization effort by covering handlers, middleware, authentication, rate limiting, validation, and short-circuit endpoints.

Changes

Handler Layer

• Standardized all handler responses through Response<T>.Ok() / Response<T>.Fail()

• All endpoints return via .ToHttpResult()

Middleware Layer

• Updated ExceptionHandlingMiddleware to emit the same response envelope structure:

{
  "success": true,
  "code": "...",
  "message": "...",
  "data": {},
  "errors": [],
  "traceId": "...",
  "correlationId": "...",
  "timestamp": "..."
}

Authentication & Authorization

• JWT OnChallenge responses use the shared envelope

• JWT OnForbidden responses use the shared envelope

• Rate limiting OnRejected responses use EnvelopeWriter

Short-Circuit Endpoints

• Replaced inline Results.StatusCode(...)

• Replaced inline Results.Ok(...)

• Standardized responses through:

  • EnvelopeResults.*

  • Response<T>.Ok().ToHttpResult()

Validation

• FluentValidation failures return the standard envelope

• Domain validation failures return the standard envelope

• Unified field-level validation errors through a shared FieldError structure

Content Endpoints

The following remain raw responses by design:

• File downloads

• iCal responses

• HTTP 204 No Content responses

All error paths for these endpoints still return the standard envelope.

Development Endpoints

• /dev/* endpoints are intentionally excluded from envelope enforcement

Remaining Flat-Response Violations

This PR closes the final three known flat-response violations:

Before | After -- | -- Results.StatusCode(415) | EnvelopeResults.UnsupportedMediaType() Results.StatusCode(415) | EnvelopeResults.UnsupportedMediaType() Results.Ok(summary) | Response.Ok(summary).ToHttpResult()

Result

• ✅ Single response contract across all API layers

• ✅ Consistent success and error payloads

• ✅ Unified validation error structure

• ✅ Authentication, middleware, and rate-limiting responses aligned

• ✅ All known flat-response violations eliminated