Completely change json error response (pallets-eco#638)

Now return errors is always a simple list of errors.
we also return field_errors - which is the old wtforms dict of errors.

Support new wtforms 3.0 form level errors.

Convert some view code to utilize form level errors.

Author: jwag956

CHANGES.rst

@@ -8,29 +8,33 @@ Version 5.0.0
 
 Released TBD
 
+**PLEASE READ CHANGE NOTES CAREFULLY - THERE ARE LIKELY REQUIRED CHANGES YOU WILL HAVE TO MAKE**
+
 Features
 ++++++++
-- (:issue:`475`) Support for WebAuthn
-- (:issue:`479`) Support Two-factor recovery codes
-- (:pr:`532`) Support for Python 3.10
-- (:pr:`540`) Improve Templates in support of JS required by WebAuthn
+- (:issue:`475`) Support for WebAuthn.
+- (:issue:`479`) Support Two-factor recovery codes.
+- (:pr:`532`) Support for Python 3.10.
+- (:pr:`540`) Improve Templates in support of JS required by WebAuthn.
 - (:pr:`568`) Deprecate the old passwordless feature in favor of Unified Signin.
   Deprecate replacing login_manager so we can possibly vendor that in in the future.
 - (:pr:`608`) Add Icelandic translations. (ofurkusi)
 - (:issue:`256`) Add custom HTML attributes to improve user experience.
   This changed LoginForm quite a bit - please see backwards compatability concerns
   below. The default LoginForm and template should be the same as before.
+- (:pr:`xx`) The JSON errors response has been unified. Please see backwards
+  compatibility concerns below.
 
 Fixes
 +++++
-- (:pr:`591`) Make the required zxcvbn complexity score configurable (mephi42)
-- (:issue:`585`) Provide option to prevent user enumeration.
+- (:pr:`591`) Make the required zxcvbn complexity score configurable. (mephi42)
+- (:issue:`585`) Provide option to prevent user enumeration (i.e. Generic Responses).
 - (:issue:`531`) Get rid of Flask-Mail. Flask-Mailman is now the default preferred email package.
   Flask-Mail is still supported so there should be no backwards compatability issues.
 - (:issue:`597`) A delete option has been added to us-setup (form and view).
 - (:pr:`625`) Improve username support - the LoginForm now has a separate field for username if
   ``SECURITY_USERNAME_ENABLE`` is True, and properly displays input fields only if the associated
-  field is an identity attribute (as specified by :py:data:`SECURITY_USER_IDENTITY_ATTRIBUTES`)
+  field is an identity attribute (as specified by :py:data:`SECURITY_USER_IDENTITY_ATTRIBUTES`).
 - (:pr:`627`) Improve empty password handling. Prior, an unguessable password was set into the user
   record when a user registered without a password - now, the DB user model has been changed to
   allow nullable passwords. This provides a better user experience since Flask-Security now
@@ -90,6 +94,13 @@ Other:
 
     - `lost_device` -> `email`
     - `no_mail_access` -> `help`
+- JSON error responses. **THIS IS A BREAKING CHANGE**.
+  In earlier releases, the JSON error response could have either a `error` key which was for rare cases
+  where there was a single non-form related error, or an `errors` key which was a a dict as defined by WTForms.
+  Now, the `errors` key will contain a list of (localized) messages - both non-form related as well as any form related.
+  The key `field_errors` will contain the dict as specified by WTForms. Please note that starting with WTForms 3.0
+  form-level errors are supported and show up in the dict with the field name/key of "none". There are no changes to non-error
+  related JSON responses.
 
 For templates:
 

docs/openapi.yaml

@@ -946,7 +946,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/UsSetupValidateJsonResponse"
         302:
-          description: Successfuly validated and persisted sign in method.
+          description: Successfully validated and persisted sign in method.
           headers:
             Location:
               description: |
@@ -1890,26 +1890,29 @@ components:
           properties:
             response:
               type: object
+              required: [ errors ]
               description: >
-                For form validation errors, the 'errors' key will be set with a list of errors per
-                invalid form input field. For non-form related errors, the 'error' key will be set
-                with a single (localized) error string.
+                For form validation errors, the 'field_errors' key will be set with a list of errors per
+                invalid form input field (i.e. a dict of 'field-name': list of error strings).
+                The 'errors' key will be a simple list of both form and non-form related
+                errors (all form errors will also be included here).
               properties:
-                errors:
+                field_errors:
                   type: object
                   description: >
                     Errors per input/form field
-                  properties:
-                    field-name:
-                      type: array
-                      items:
-                        type: string
-                        example: field validation error.
-                        description: Error message (localized)
-                error:
-                  type: string
-                  example: "Unauthenticated"
-                  description: Error message (localized)
+                  additionalProperties:
+                    type: array
+                    items:
+                      type: string
+                      example: field validation error.
+                      description: Error message (localized)
+                errors:
+                  type: array
+                  items:
+                    type: string
+                    example: "Unauthenticated"
+                    description: Error message (localized)
     Verify:
       type: object
       required: [ password ]
@@ -1995,37 +1998,30 @@ components:
           type: boolean
         tf_validity_token:
           type: string
-          description: Code verifying the user has successfully verfied 2FA in the past. If verified, the user is able to skip validation of the second factor. Only used when SECURITY_TWO_FACTOR_ALWAYS_VALIDATE is False.
+          description: Code verifying the user has successfully verified 2FA in the past. If verified, the user is able to skip validation of the second factor. Only used when SECURITY_TWO_FACTOR_ALWAYS_VALIDATE is False.
     UsSigninJsonResponse:
-      type: object
-      description: >
-        The user successfully signed in. Note that depending on SECURITY_TWO_FACTOR and SECURITY_US_MFA_REQUIRED configuration variables, a second form of authentication might be required.
-      required: [meta, response]
-      properties:
-        meta:
-          type: object
-          required: [code]
-          properties:
-            code:
-              type: integer
-              example: 200
-              description: Http status code
-        response:
-          type: object
+      allOf:
+        - $ref: '#/components/schemas/BaseJsonResponse'
+        - type: object
+          description: >
+            The user successfully signed in. Note that depending on SECURITY_TWO_FACTOR and SECURITY_US_MFA_REQUIRED configuration variables, a second form of authentication might be required.
           properties:
-            authentication_token:
-              type: string
-              description: >
-                Token to be used in future token-based API calls. Only returned if "include_auth_token" parameter is set.
-            tf_required:
-              type: boolean
-              description: If two-factor authentication is required for caller.
-            tf_state:
-              type: string
-              description: if "setup_from_login" then the caller must go through two-factor setup endpoint. If "ready" then a code has been sent and should be supplied to SECURITY_TWO_FACTOR_TOKEN_VALIDATION_URL.
-            tf_primary_method:
-              type: string
-              description: Which method was used to send code.
+            response:
+              type: object
+              properties:
+                authentication_token:
+                  type: string
+                  description: >
+                    Token to be used in future token-based API calls. Only returned if "include_auth_token" parameter is set.
+                tf_required:
+                  type: boolean
+                  description: If two-factor authentication is required for caller.
+                tf_state:
+                  type: string
+                  description: if "setup_from_login" then the caller must go through two-factor setup endpoint. If "ready" then a code has been sent and should be supplied to SECURITY_TWO_FACTOR_TOKEN_VALIDATION_URL.
+                tf_primary_method:
+                  type: string
+                  description: Which method was used to send code.
     UsSigninSendCode:
       type: object
       required: [identity, chosen_method]
@@ -2064,39 +2060,32 @@ components:
           type: string
           description: phone number (this will be normalized). Required if chosen_method == "sms".
     UsSetupJsonResponse:
-      type: object
-      required: [meta, response]
-      properties:
-        meta:
-          type: object
-          required: [code]
-          properties:
-            code:
-              type: integer
-              example: 200
-              description: Http status code
-        response:
-          type: object
-          description: Response when setting up a new method. When deleting, nothing is returned.
+      allOf:
+        - $ref: '#/components/schemas/BaseJsonResponse'
+        - type: object
           properties:
-            chosen_method:
-              type: string
-              description: The chosen_method as passed into API.
-            phone:
-              type: string
-              description: The canonicalized phone number if setting up SMS
-            authr_key:
-              type: string
-              description: TOTP key for setting up authenticator (if chosen_method == 'authenticator')
-            authr_issuer:
-              type: string
-              description: Issuer as configured with TOTP_ISSUER (same as used in QRcode) (if chosen_method == 'authenticator')
-            authr_username:
-              type: string
-              description: Username (same as used in QRcode) (if chosen_method == 'authenticator')
-            state:
-              type: string
-              description: Opaque blob that must be pass to /us-setup/<state>. This is a signed, timed token.
+            response:
+              type: object
+              description: Response when setting up a new method. When deleting, nothing is returned.
+              properties:
+                chosen_method:
+                  type: string
+                  description: The chosen_method as passed into API.
+                phone:
+                  type: string
+                  description: The canonicalized phone number if setting up SMS
+                authr_key:
+                  type: string
+                  description: TOTP key for setting up authenticator (if chosen_method == 'authenticator')
+                authr_issuer:
+                  type: string
+                  description: Issuer as configured with TOTP_ISSUER (same as used in QRcode) (if chosen_method == 'authenticator')
+                authr_username:
+                  type: string
+                  description: Username (same as used in QRcode) (if chosen_method == 'authenticator')
+                state:
+                  type: string
+                  description: Opaque blob that must be pass to /us-setup/<state>. This is a signed, timed token.
     UsSetupValidateRequest:
       type: object
       required: [passcode]
@@ -2105,26 +2094,19 @@ components:
           type: string
           description: Code/Passcode as received from method being setup.
     UsSetupValidateJsonResponse:
-      type: object
-      required: [meta, response]
-      properties:
-        meta:
-          type: object
-          required: [code]
-          properties:
-            code:
-              type: integer
-              example: 200
-              description: Http status code
-        response:
-          type: object
+      allOf:
+        - $ref: '#/components/schemas/BaseJsonResponse'
+        - type: object
           properties:
-            chosen_method:
-              type: string
-              description: The chosen_method as passed into API.
-            phone:
-              type: string
-              description: Phone number if set.
+            response:
+              type: object
+              properties:
+                chosen_method:
+                  type: string
+                  description: The chosen_method as passed into API.
+                phone:
+                  type: string
+                  description: Phone number if set.
     TfSetup:
       type: object
       required: [setup]
@@ -2140,39 +2122,32 @@ components:
           description: phone number (this will be validated for format). Required if setup == "sms".
           example: 650-555-1212
     TfSetupJsonResponse:
-      type: object
-      required: [meta, response]
-      properties:
-        meta:
-          type: object
-          required: [code]
-          properties:
-            code:
-              type: integer
-              example: 200
-              description: Http status code
-        response:
-          type: object
+      allOf:
+        - $ref: '#/components/schemas/BaseJsonResponse'
+        - type: object
           properties:
-            tf_state:
-              type: string
-              description: >
-                Current state of Two Factor configuration. Not present when disabling 2FA. This will be set to 'validating_profile'
-                indicating the caller needs to call '/tf-validate' with the correct code.
-              example: validating_profile
-            tf_primary_method:
-              type: string
-              description: Current method being congfigured.
-              example: sms
-            tf_authr_key:
-              type: string
-              description: TOTP key for setting up authenticator (if tf_primary_method == 'authenticator')
-            tf_authr_issuer:
-              type: string
-              description: Issuer as configured with TOTP_ISSUER (same as used in QRcode) (if tf_primary_method == 'authenticator')
-            tf_authr_username:
-              type: string
-              description: Username (same as used in QRcode) (if tf_primary_method == 'authenticator')
+            response:
+              type: object
+              properties:
+                tf_state:
+                  type: string
+                  description: >
+                    Current state of Two Factor configuration. Not present when disabling 2FA. This will be set to 'validating_profile'
+                    indicating the caller needs to call '/tf-validate' with the correct code.
+                  example: validating_profile
+                tf_primary_method:
+                  type: string
+                  description: Current method being configured.
+                  example: sms
+                tf_authr_key:
+                  type: string
+                  description: TOTP key for setting up authenticator (if tf_primary_method == 'authenticator')
+                tf_authr_issuer:
+                  type: string
+                  description: Issuer as configured with TOTP_ISSUER (same as used in QRcode) (if tf_primary_method == 'authenticator')
+                tf_authr_username:
+                  type: string
+                  description: Username (same as used in QRcode) (if tf_primary_method == 'authenticator')
     TfValidateJsonResponse:
       type: object
       properties:

flask_security/tf_plugin.py

@@ -32,7 +32,6 @@
     get_message,
     get_within_delta,
     get_url,
-    json_error_response,
     login_user,
     simple_render_json,
     suppress_form_csrf,
@@ -327,7 +326,8 @@ def tf_illegal_state(form, redirect_to):
         do_flash(m, c)
         return redirect(get_url(redirect_to))
     else:
-        return _security._render_json(json_error_response(m), 400, None, None)
+        form.form_errors.append(m)
+        return base_render_json(form, include_user=False)
 
 
 def tf_clean_session():

flask_security/unified_signin.py

@@ -942,8 +942,8 @@ def us_setup_validate(token: str) -> "ResponseValue":
         m, c = get_message("US_SETUP_EXPIRED", within=cv("US_SETUP_WITHIN"))
     if invalid or expired:
         if _security._want_json(request):
-            payload = json_error_response(errors=m)
-            return _security._render_json(payload, 400, None, None)
+            form.form_errors.append(m)
+            return base_render_json(form, include_user=False)
         do_flash(m, c)
         return redirect(url_for_security("us_setup"))