feat(security): Add user confirmation/reauth for sensitive changes

Auditors can raise Reauth(reason) exception to require the user to
enter a token (e.g. account password) to verify the user is performing
the change.

Naming is subject to change.

actions.py: New ReauthAction class handler and verifyPassword() method
 for overriding if needed.

client.py: Handle Reauth exception by calling Client:reauth() method.
 Default client:reauth method.  Add 'reauth' action declaration.

exceptions.py: Define and document Reauth exception as a subclass of
 RoundupCGIException.

templating.py: Define method utils.embed_form_fields().

   The original form making a change to the database has a lot of form
   fields. These need to be resubmitted to Roundup as part of the form
   submission that verifies the user's password.

   This method turns all non file form fields into type=hidden inputs.
   It escapes the names and values to prevent XSS.

   For file form fields, it base64 encodes the contents and puts them
   in hidden pre blocks. The pre blocks have data attributes for the
   filename, filetype and the original field name. (Note the original
   field name is not used.)

   This stops the file content data (maybe binary e.g. jpegs) from
   breaking the html page. The reauth template runs JavaScript that
   turns the encoded data inside the pre tags back into a file. Then
   it adds a multiple file input control to the page and attaches all
   the files to it. This file input is submitted with the rest of the
   fields.

_generic.reauth.html (multiple tracker templates): Generates a form
 with id=reauth_form to:

   display any message from the Reauth exception to the user (e.g. why
   user is asked to auth).

   get the user's password

   submit the form

   embed all the form data that triggered the reauth

   recreate any file data that was submitted as part of the form and
   generate a new file input to push the data to the back end

 It has the JavaScript routine (as an IIFE) that regenerates a file
 input without user intervention.

 All the TAL based tracker templates use the same form. There is also
 one for the jinja2 template. The JavaScript for both is the same.

reference.txt: document embed_form_fields utility method.

upgrading.txt: initial upgrading docs.

TODO:

Finalize naming. I am leaning toward ConfirmID rather than Reauth.
Still looking for a standard name for this workflow.

Externalize the javascript in _generic.reauth.html to a seperate file
and use utils.readfile() to embed it or change the script to load it
from a @@file url.

Clean up upgrading.txt with just steps to implement and less feature
detail/internals.

Document internals/troubleshooting in reference.txt.

Add tests using live server.

Author: rouilj

CHANGES.txt

@@ -26,6 +26,10 @@ Fixed:
 
 Features:
 
+- add support for authorized changes. User can be prompted to enter
+  their password to authorize a change. If the user's password is
+  properly entered, the change is committed. (John Rouillard)
+
 2025-07-13 2.5.0
 
 Fixed:

doc/reference.txt

@@ -3577,6 +3577,11 @@ be added to the variable by using extensions_.
      - set_http_response sets the HTTP response code for the request.
    * - :meth:`url_quote <roundup.cgi.templating.TemplatingUtils.url_quote>`
      - quote some text as safe for a URL (ie. space, %, ...)
+   * - :meth:`embed_form_fields <roundup.cgi.templating.TemplatingUtils.embed_form_fields>`
+     - Creates a hidden input for each of the client's form fields. It
+       also embeds base64 encoded file contents into pre tags and
+       processes that informtion back into a file input control.
+
 
 -----
 

doc/upgrading.txt

@@ -103,6 +103,71 @@ your database.
 
   </details>
 
+.. index:: Upgrading; 2.5.0 to 2.6.0
+
+Migrating from 2.5.0 to 2.6.0
+=============================
+
+Support authorized changes in your tracker (optional)
+-----------------------------------------------------
+
+An auditor can require change verification with user's password.
+
+When changing sensitive information (e.g. passwords) it is
+useful to ask for a validated authorization. This makes sure
+that the user is present by typing their password.
+
+In an auditor adding::
+
+   from roundup.cgi.exceptions import Reauth
+
+   if 'password' in newvalues and not getattr(db, 'reauth_done', False):
+      raise Reauth('Add an optional message to the user')
+
+will present the user with a authorization page and optional message
+when the password is changed.  The page is generated from the
+``_generic.reauth.html`` template by default.
+
+Once the user enters their password and submits the page, the
+password will be verified using:
+
+    roundup.cgi.actions:LoginAction::verifyPassword()
+
+If the password is correct the original change is done.
+
+To prevent the auditor from trigering another Reauth, the
+attribute ``reauth_done`` is added to the db object. As a result,
+the getattr call will return True and not raise Reauth.
+
+You get one reauth for a submitted change. Note you cannot Reauth
+multiple properties separately. If you need to auth multiple
+properties separately, you need to reject the change and force the
+user to submit each sensitive property separately.  For example::
+
+   if 'password' in newvalues and 'realname' in newvalues:
+      raise Reject('Changing the username and the realname '
+		   'at the same time is not allowed. Please '
+		   'submit two changes.')
+
+   if 'password' in newvalues and not getattr(db, 'reauth_done', False):
+      raise Reauth()
+
+   if 'realname' in newvalues and not getattr(db, 'reauth_done', False):
+      raise Reauth()
+
+See also: client.py:Client:reauth(self, exception) which can be changed
+using interfaces.py in your tracker.
+
+You should copy ``_generic.reauth.html`` into your tracker's html
+subdirectory. See the classic template directory for a copy. If you
+are using jinja2, see the jinja2 template directory.  Then you can
+raise a Reauth exception and have the proper page displayed.
+
+Also javascript *MUST* be turned on if this is used with a file
+input. If JavaScript is not turned on, attached files are lost during
+the reauth step. Information from other types of inputs (password,
+date, text etc.) do not need JavaScript to work.
+
 .. index:: Upgrading; 2.4.0 to 2.5.0
 
 Migrating from 2.4.0 to 2.5.0

roundup/cgi/actions.py

@@ -23,7 +23,8 @@
            'SearchAction',
            'EditCSVAction', 'EditItemAction', 'PassResetAction',
            'ConfRegoAction', 'RegisterAction', 'LoginAction', 'LogoutAction',
-           'NewItemAction', 'ExportCSVAction', 'ExportCSVWithIdAction']
+           'NewItemAction', 'ExportCSVAction', 'ExportCSVWithIdAction',
+           'ReauthAction']
 
 
 class Action:
@@ -1843,6 +1844,134 @@ def handle(self):
 
         return '\n'
 
+class ReauthAction(Action):
+    '''Allow an auditor to require change verification with user's password.
+
+       When changing sensitive information (e.g. passwords) it is
+       useful to ask for a validated authorization. This makes sure
+       that the user is present by typing their password.
+
+       In an auditor adding::
+
+          if 'password' in newvalues and not getattr(db, 'reauth_done', False):
+             raise Reauth()
+
+       will present the user with a authorization page when the
+       password is changed.  The page is generated from the
+       _generic.reauth.html template by default.
+
+       Once the user enters their password and submits the page, the
+       password will be verified using:
+       roundup.cgi.actions:LoginAction::verifyPassword().  If the
+       password is correct the original change is done.
+
+       To prevent the auditor from trigering another Reauth, the
+       attribute "reauth_done" is added to the db object. As a result,
+       the getattr call will return True and not raise Reauth.
+
+       You get one reauth for the submitted change. Note you cannot
+       Reauth multiple properties separately. If you need to auth
+       multiple properties separately, you need to reject the change
+       and force the user to submit each sensitive property separately.
+       For example::
+
+          if 'password' in newvalues and 'realname' in newvalues:
+             raise Reject('Changing the username and the realname '
+                          'at the same time is not allowed. Please '
+                          'submit two changes.')
+
+          if 'password' in newvalues and not getattr(db, 'reauth_done', False):
+             raise Reauth()
+
+          if 'realname' in newvalues and not getattr(db, 'reauth_done', False):
+             raise Reauth()
+
+        Limitations: It can not handle file input fields.
+
+        See also: client.py:Client:reauth() which can be changed
+        using interfaces.py in your tracker.
+    '''
+
+    def handle(self):
+        ''' Handle a form with a reauth request.
+        '''
+
+        if self.client.env['REQUEST_METHOD'] != 'POST':
+            raise Reject(self._('Invalid request'))
+
+        if '@reauth_password' not in self.form:
+            self.client.add_error_message(self._('Password incorrect.'))
+            return
+
+        # Verify password
+        login = self.client.get_action_class('login')(self.client)
+        if not self.verifyPassword():
+            self.client.add_error_message(self._("Password incorrect."))
+            self.client.template = "reauth"
+
+            # Strip fields that are added by the template. All
+            # the rest of the fields in self.form.list are added
+            # as hidden fields by the reauth template.
+            self.form.list = [ x for x in self.form.list
+                               if x.name not in (
+                                       '@action',
+                                       '@csrf',
+                                       '@reauth_password',
+                                       '@template',
+                                       'submit'
+                               )
+                              ]
+            return
+
+        # extract the info we need to preserve/reinject into
+        # the next action.
+        
+        if '@next_action' not in self.form: # required to look up next action
+            self.client.add_error_message(
+                self._('Missing action to be authorized.'))
+            return
+
+        action = self.form['@next_action'].value.lower()
+
+        next_template = None;  # optional
+        if '@next_template' in self.form:
+            next_template = self.form['@next_template'].value
+
+        # rewrite the form for redisplay
+        # remove all the reauth_form_fields leaving just the original
+        # form fields from the form that trigered the reauth.
+        # We extracted @next_* above to route to the original action
+        # and template.
+
+        reauth_form_fields = ('@reauth_password', '@template',
+                              '@next_template', '@action',
+                              '@next_action', '@csrf', 'submit')
+
+        self.form.list = [ x for x in self.form.list
+                              if x.name not in reauth_form_fields
+                          ]
+
+        try:
+            action_klass = self.client.get_action_class(action)
+
+            # set the template to go back to
+            # use "" not None as this value gets encoded and None is invalid
+            self.client.template = next_template if next_template else ""
+            # use this in detector (to skip reauth
+            self.client.db.reauth_done = True
+            
+            # should raise exception Redirect
+            action_klass(self.client).execute()
+
+        except (ValueError, Reject) as err:
+            escape = not isinstance(err, RejectRaw)
+            self.add_error_message(str(err), escape=escape)
+
+    def verifyPassword(self):
+        login = self.client.get_action_class('login')(self.client)
+        return login.verifyPassword(self.userid,
+                                    self.form['@reauth_password'].value)
+
 
 class Bridge(BaseAction):
     """Make roundup.actions.Action executable via CGI request.

roundup/cgi/client.py

@@ -41,6 +41,7 @@ class SysCallError(Exception):
     NotFound,
     NotModified,
     RateLimitExceeded,
+    Reauth,
     Redirect,
     SendFile,
     SendStaticFile,
@@ -960,6 +961,8 @@ def inner_main(self):
 
         except SeriousError as message:
             self.write_html(str(message))
+        except Reauth as e:
+            self.reauth(e)
         except Redirect as url:
             # let's redirect - if the url isn't None, then we need to do
             # the headers, otherwise the headers have been set before the
@@ -1916,6 +1919,44 @@ def determine_context(self, dre=dre_url):
         if template_override is not None:
             self.template = template_override
 
+    def reauth(self, exception):
+        """Processing for a Reauth exception raised from an auditor.
+
+           Can be overridden by code in tracker's interfaces.py.
+        """
+        
+        from roundup.anypy.vendored.cgi import MiniFieldStorage
+
+        original_action = self.form['@action'].value if '@action' \
+            in self.form else ""
+        original_template = self.template
+
+        self.template = 'reauth'
+        self.form.list = [ x for x in self.form.list
+                           if x.name not in ('@action',
+                                             '@csrf',
+                                             '@template'
+                                             )]
+
+        # save the action and template used when the Reauth as
+        # triggered. Will be used to resolve the change by the reauth
+        # action when when reauth password verified.
+        if '@next_action' not in self.form.list:
+            self.form.list.append(MiniFieldStorage('@next_action',
+                                                   original_action))
+        if '@next_template' not in self.form.list:
+            self.form.list.append(MiniFieldStorage('@next_template',
+                                                   original_template))
+
+        if exception.args and "@reauth_message" not in self.form.list:
+            self.form.list.append(
+                MiniFieldStorage('@reauth_message',
+                                 html_escape(exception.args[0])
+                )
+            )
+
+        self.write_html(self.renderContext())
+
     # re for splitting designator, see also dre_url above this one
     # doesn't strip leading 0's from the id. Why not??
     dre = re.compile(r'([^\d]+)(\d+)')
@@ -2365,6 +2406,7 @@ def renderError(self, error, response_code=400, use_template=True):
         ('show',        actions.ShowAction),  # noqa: E241
         ('export_csv',  actions.ExportCSVAction),  # noqa: E241
         ('export_csv_id',  actions.ExportCSVWithIdAction),  # noqa: E241
+        ('reauth',      actions.ReauthAction),  # noqa: E241
     )
 
     def handle_action(self):

roundup/cgi/exceptions.py

@@ -14,6 +14,27 @@ class RoundupCGIException(RoundupException):
     pass
 
 
+class Reauth(RoundupCGIException):
+    """Raised by auditor, to trigger password verification before commit.
+
+       Before committing changes to sensitive fields, triggers the
+       following workflow:
+
+         1. user is presented with a page to enter his/her password
+         2. page is submitted to reauth action
+         3. password is verified by LoginAction.verifyPassword
+         4. change is committed to database.
+
+         If 3 fails, restart at step 1.
+
+         Client.reauth() method is used to handle step 1. Should be
+         able to be overridden in interfaces.py. Step 2 is done by
+         _generic.reauth.html. Steps 3 and 4 (and cycle back to 1) is
+         done by cgi/actions.py:Reauth action.
+    """
+    pass
+
+
 class HTTPException(RoundupCGIException):
     """Base exception for all HTTP error codes."""
     pass