feat: improve error details of PGRST301 error

CHANGELOG.md

@@ -10,6 +10,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Improve the `PGRST106` error when the requested schema is invalid by @laurenceisla in #4089
   + It now shows the invalid schema in the `message` field.
   + The exposed schemas are now listed in the `hint` instead of the `message` field.
+- Improve error details of `PGRST301` error by @taimoorzaeem in #4051
 
 ## [13.0.6] - 2025-08-30
 

src/PostgREST/Auth.hs

@@ -76,8 +76,8 @@ parseToken AppConfig{..} (Just tkn) time = do
       --   BadAlgorithm
       --   KeyError
       --   BadCrypto
-      jwtDecodeError (JWT.KeyError _)     = JwtDecodeErr KeyError
-      jwtDecodeError (JWT.BadAlgorithm _) = JwtDecodeErr BadAlgorithm
+      jwtDecodeError (JWT.KeyError m)     = JwtDecodeErr $ KeyError m
+      jwtDecodeError (JWT.BadAlgorithm m) = JwtDecodeErr $ BadAlgorithm m
       jwtDecodeError JWT.BadCrypto        = JwtDecodeErr BadCrypto
       -- Control never reaches here, the decode function only returns the above three
       jwtDecodeError _                    = JwtDecodeErr UnreachableDecodeError

src/PostgREST/Error.hs

@@ -659,8 +659,8 @@ data JwtError
 data JwtDecodeError
   = EmptyAuthHeader
   | UnexpectedParts Int
-  | KeyError
-  | BadAlgorithm
+  | KeyError Text
+  | BadAlgorithm Text
   | BadCrypto
   | UnsupportedTokenType
   | UnreachableDecodeError
@@ -745,8 +745,8 @@ instance ErrorBody JwtError where
   message (JwtDecodeErr e) = case e of
     EmptyAuthHeader        -> "Empty JWT is sent in Authorization header"
     UnexpectedParts n      -> "Expected 3 parts in JWT; got " <> show n
-    KeyError               -> "No suitable key or wrong key type"
-    BadAlgorithm           -> "Wrong or unsupported encoding algorithm"
+    KeyError _             -> "No suitable key or wrong key type"
+    BadAlgorithm _         -> "Wrong or unsupported encoding algorithm"
     BadCrypto              -> "JWT cryptographic operation failed"
     UnsupportedTokenType   -> "Unsupported token type"
     UnreachableDecodeError -> "JWT couldn't be decoded"
@@ -762,6 +762,10 @@ instance ErrorBody JwtError where
     IatClaimNotNumber        -> "The JWT 'iat' claim must be a number"
     AudClaimNotStringOrArray -> "The JWT 'aud' claim must be a string or an array of strings"
 
+  details (JwtDecodeErr jde) = case jde of
+    KeyError dets     -> Just $ JSON.String dets
+    BadAlgorithm dets -> Just $ JSON.String dets
+    _                 -> Nothing
   details _ = Nothing
 
   hint _    = Nothing

test/io/test_io.py

@@ -93,6 +93,9 @@ def test_jwt_errors(defaultenv):
         response = postgrest.session.get("/", headers=headers)
         assert response.status_code == 401
         assert response.json()["message"] == "No suitable key or wrong key type"
+        assert (
+            response.json()["details"] == "None of the keys was able to decode the JWT"
+        )
 
         headers = jwtauthheader({"role": "not_existing"}, SECRET)
         response = postgrest.session.get("/", headers=headers)
@@ -141,6 +144,10 @@ def test_jwt_errors(defaultenv):
         response = postgrest.session.get("/", headers=headers)
         assert response.status_code == 401
         assert response.json()["message"] == "Wrong or unsupported encoding algorithm"
+        assert (
+            response.json()["details"]
+            == "JWT is unsecured but expected 'alg' was not 'none'"
+        )
 
     env = {
         **defaultenv,