return 'ERROR_AUTHENTICATION_EXPIRED', when there's a session auth mismatch (#18670)

docs/topics/api/overview.rst

@@ -81,13 +81,16 @@ property will be present and will contain a constant corresponding to
 specific problems to help clients address the situation programmatically. The
 constants are as follows:
 
-    ========================  =========================================================
-                       Value  Description
-    ========================  =========================================================
-        ERROR_INVALID_HEADER  The ``Authorization`` header is invalid.
-     ERROR_SIGNATURE_EXPIRED  The signature of the token indicates it has expired.
-    ERROR_DECODING_SIGNATURE  The token was impossible to decode and probably invalid.
-    ========================  =========================================================
+    ============================  =====================================================
+                           Value  Description
+    ============================  =====================================================
+            ERROR_INVALID_HEADER  The ``Authorization`` header is invalid.
+         ERROR_SIGNATURE_EXPIRED  The signature of the token indicates it has expired.
+        ERROR_DECODING_SIGNATURE  The token was impossible to decode and probably
+                                  invalid.
+    ERROR_AUTHENTICATION_EXPIRED  The payload references an invalid session hash,
+                                  probably because the session has expired.
+    ============================  =====================================================
 
 
 .. _api-overview-maintainance:
@@ -431,6 +434,7 @@ These are `v5` specific changes - `v4` changes apply also.
 * 2021-11-25: added ``custom_license`` to version create/update endpoints to allow non-predefined licenses to be created and updated. https://github.com/mozilla/addons-server/issues/18034
 * 2021-12-09: enabled setting ``tags`` via addon submission and edit apis. https://github.com/mozilla/addons-server/issues/18268
 * 2021-12-09: changed ``license`` in version create/update endpoints to accept a license slug rather than numeric ID, and documented supported licenses. https://github.com/mozilla/addons-server/issues/18361
+* 2022-01-27: added ``ERROR_AUTHENTICATION_EXPIRED`` error code for authentication failures. https://github.com/mozilla/addons-server/issues/18669
 
 .. _`#11380`: https://github.com/mozilla/addons-server/issues/11380/
 .. _`#11379`: https://github.com/mozilla/addons-server/issues/11379/

src/olympia/api/authentication.py

@@ -142,7 +142,11 @@ class WebTokenAuthentication(BaseAuthentication):
                 'User tried to authenticate with invalid auth hash in'
                 'payload {}'.format(payload)
             )
-            raise exceptions.AuthenticationFailed()
+            msg = {
+                'detail': gettext('Auth hash mismatch. Session is likely expired.'),
+                'code': 'ERROR_AUTHENTICATION_EXPIRED',
+            }
+            raise exceptions.AuthenticationFailed(msg)
 
         # Set user in thread like UserAndAddrMiddleware does.
         core.set_user(user)

src/olympia/api/tests/test_authentication.py

@@ -303,47 +303,66 @@ class TestWebTokenAuthentication(TestCase):
 
     def test_user_id_is_none(self):
         token = self.client.generate_api_token(self.user, user_id=None)
-        with self.assertRaises(AuthenticationFailed):
+        with self.assertRaises(AuthenticationFailed) as exp:
             self._authenticate(token)
+        assert 'code' not in exp.exception.detail
 
     def test_no_user_id_in_payload(self):
         data = {
             'auth_hash': self.user.get_session_auth_hash(),
         }
         token = signing.dumps(data, salt=WebTokenAuthentication.salt)
-        with self.assertRaises(AuthenticationFailed):
+        with self.assertRaises(AuthenticationFailed) as exp:
             self._authenticate(token)
+        assert 'code' not in exp.exception.detail
 
     def test_no_auth_hash_in_payload(self):
         data = {
             'user_id': self.user.pk,
         }
         token = signing.dumps(data, salt=WebTokenAuthentication.salt)
-        with self.assertRaises(AuthenticationFailed):
+        with self.assertRaises(AuthenticationFailed) as exp:
             self._authenticate(token)
+        assert exp.exception.detail['code'] == 'ERROR_AUTHENTICATION_EXPIRED'
+        assert (
+            exp.exception.detail['detail']
+            == 'Auth hash mismatch. Session is likely expired.'
+        )
 
     def test_user_deleted(self):
         self.user.delete()
         token = self.client.generate_api_token(self.user)
-        with self.assertRaises(AuthenticationFailed):
+        with self.assertRaises(AuthenticationFailed) as exp:
             self._authenticate(token)
+        assert 'code' not in exp.exception.detail
 
     def test_invalid_user_not_found(self):
         token = self.client.generate_api_token(self.user, user_id=-1)
-        with self.assertRaises(AuthenticationFailed):
+        with self.assertRaises(AuthenticationFailed) as exp:
             self._authenticate(token)
+        assert 'code' not in exp.exception.detail
 
     def test_invalid_user_other_user(self):
         user2 = user_factory(read_dev_agreement=datetime.now())
         token = self.client.generate_api_token(self.user, user_id=user2.pk)
-        with self.assertRaises(AuthenticationFailed):
+        with self.assertRaises(AuthenticationFailed) as exp:
             self._authenticate(token)
+        assert exp.exception.detail['code'] == 'ERROR_AUTHENTICATION_EXPIRED'
+        assert (
+            exp.exception.detail['detail']
+            == 'Auth hash mismatch. Session is likely expired.'
+        )
 
     def test_wrong_auth_id(self):
         token = self.client.generate_api_token(self.user)
         self.user.update(auth_id=self.user.auth_id + 42)
-        with self.assertRaises(AuthenticationFailed):
+        with self.assertRaises(AuthenticationFailed) as exp:
             self._authenticate(token)
+        assert exp.exception.detail['code'] == 'ERROR_AUTHENTICATION_EXPIRED'
+        assert (
+            exp.exception.detail['detail']
+            == 'Auth hash mismatch. Session is likely expired.'
+        )
 
     def test_make_sure_token_is_decodable(self):
         token = self.client.generate_api_token(self.user)