From d7c82cfcf808291576f69fc3fc388855193b4645 Mon Sep 17 00:00:00 2001
From: Yosif Iliev <yosif.iliev@netcetera.com>
Date: Wed, 27 Aug 2025 16:13:45 +0300
Subject: [PATCH] Expose HTTP response headers in `NSError` for non-2xx
 responses

---
 Sources/AppAuthCore/OIDError.h          | 8 ++++++++
 Sources/AppAuthCore/OIDError.m          | 2 ++
 Sources/AppAuthCore/OIDErrorUtilities.m | 5 +++++
 3 files changed, 15 insertions(+)

diff --git a/Sources/AppAuthCore/OIDError.h b/Sources/AppAuthCore/OIDError.h
index 5131f0ad4..643666529 100644
--- a/Sources/AppAuthCore/OIDError.h
+++ b/Sources/AppAuthCore/OIDError.h
@@ -73,6 +73,14 @@ extern NSString *const OIDHTTPErrorDomain;
  */
 extern NSString *const OIDOAuthErrorResponseErrorKey;
 
+/*! @brief An error key used to access the HTTP response headers from a failed AppAuth request.
+    @discussion When an AppAuth request fails due to a non-2xx HTTP response, the server's
+        response headers are attached to the returned NSError's `userInfo` dictionary under this key.
+        The value is an NSDictionary<NSString *, id>, matching the structure of
+        NSHTTPURLResponse.allHeaderFields.
+ */
+extern NSString *const OIDHTTPResponseHeadersKey;
+
 /*! @brief The key of the 'error' response field in a RFC6749 Section 5.2 response.
     @remark error
     @see https://tools.ietf.org/html/rfc6749#section-5.2
diff --git a/Sources/AppAuthCore/OIDError.m b/Sources/AppAuthCore/OIDError.m
index 87c8623ee..e84623352 100644
--- a/Sources/AppAuthCore/OIDError.m
+++ b/Sources/AppAuthCore/OIDError.m
@@ -38,6 +38,8 @@
 
 NSString *const OIDOAuthErrorResponseErrorKey = @"OIDOAuthErrorResponseErrorKey";
 
+NSString *const OIDHTTPResponseHeadersKey = @"OIDHTTPResponseHeadersKey";
+
 NSString *const OIDOAuthErrorFieldError = @"error";
 
 NSString *const OIDOAuthErrorFieldErrorDescription = @"error_description";
diff --git a/Sources/AppAuthCore/OIDErrorUtilities.m b/Sources/AppAuthCore/OIDErrorUtilities.m
index 3b3c06075..022be2b04 100644
--- a/Sources/AppAuthCore/OIDErrorUtilities.m
+++ b/Sources/AppAuthCore/OIDErrorUtilities.m
@@ -133,6 +133,11 @@ + (NSError *)HTTPErrorWithHTTPResponse:(NSHTTPURLResponse *)HTTPURLResponse
       userInfo[NSLocalizedDescriptionKey] = serverResponse;
     }
   }
+  
+  if (HTTPURLResponse.allHeaderFields) {
+    userInfo[OIDHTTPResponseHeadersKey] = HTTPURLResponse.allHeaderFields;
+  }
+  
   NSError *serverError =
       [NSError errorWithDomain:OIDHTTPErrorDomain
                           code:HTTPURLResponse.statusCode