annotate doc/tracker_templates.txt @ 8411:ef1ea918b07a reauth-confirm_id

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 John Rouillard <rouilj@ieee.org>
date Mon, 11 Aug 2025 14:01:12 -0400
parents 3614cd64f4c4
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 =========================
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 Roundup Tracker Templates
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 =========================
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
5 The templates distributed with Roundup are stored in the "share" directory
2826
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
6 nominated by Python. On Unix this is typically
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
7 ``/usr/share/roundup/templates/`` (or ``/usr/local/share...``) and
8313
3614cd64f4c4 build: issue2551397: remove support for python 3.6
John Rouillard <rouilj@ieee.org>
parents: 7744
diff changeset
8 on Windows this is ``c:\python38\share\roundup\templates\``.
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 The template loading looks in four places to find the templates:
2826
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
11
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 1. *share* - eg. ``<prefix>/share/roundup/templates/*``.
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13 This should be the standard place to find them when Roundup is
6728
f83e19465b70 Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents: 6727
diff changeset
14 installed running setup.py from source.
f83e19465b70 Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents: 6727
diff changeset
15 2. ``install_dir``/../<prefix>/share/....``, where prefix is the
6739
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6728
diff changeset
16 Python's ``sys.prefix``. ``sys.base_prefix`` or
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6728
diff changeset
17 `sys.base_prefix/local``. This finds templates (and locales)
6728
f83e19465b70 Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents: 6727
diff changeset
18 installed by pip. E.G. in a virtualenv located at (``sys.prefix``):
f83e19465b70 Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents: 6727
diff changeset
19 ``/tools/roundup``, roundup would be at:
8313
3614cd64f4c4 build: issue2551397: remove support for python 3.6
John Rouillard <rouilj@ieee.org>
parents: 7744
diff changeset
20 ``/tools/roundup/lib/python3.7/site-packages/roundup``. The
6728
f83e19465b70 Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents: 6727
diff changeset
21 templates would be at:
8313
3614cd64f4c4 build: issue2551397: remove support for python 3.6
John Rouillard <rouilj@ieee.org>
parents: 7744
diff changeset
22 ``/tools/roundup/lib/python3.7/site-packages/tools/roundup/share/roundup/templates/``. (Replace 3.7 with the Python version you are running.)
6739
00fe67eb8a91 Update locations templates and locale files are stored
John Rouillard <rouilj@ieee.org>
parents: 6728
diff changeset
23 3. ``<roundup.admin.__file__>/../../share/roundup/templates/*``.
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24 This will be used if Roundup's run in the distro (aka. source)
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25 directory.
6728
f83e19465b70 Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents: 6727
diff changeset
26 4. ``<current working dir>/*``.
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
27 This is for when someone unpacks a 3rd-party template.
6728
f83e19465b70 Add new location where templates and locales are found.
John Rouillard <rouilj@ieee.org>
parents: 6727
diff changeset
28 5. ``<current working dir>``.
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29 This is for someone who "cd"s to the 3rd-party template dir.
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31 Templates contain:
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32
2826
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
33 - modules ``schema.py`` and ``initial_data.py``
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
34 - directories ``html``, ``detectors`` and ``extensions``
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
35 (with appropriate contents)
7744
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
36 - optional directory ``lib`` which contains modules used by the other
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
37 tracker components
5762
b76be13e027e issue2551029: Jinja2 template install error.
John Rouillard <rouilj@ieee.org>
parents: 4557
diff changeset
38 - optional ``config_ini.ini`` file. It is structured like a tracker's
b76be13e027e issue2551029: Jinja2 template install error.
John Rouillard <rouilj@ieee.org>
parents: 4557
diff changeset
39 ``config.ini`` but contains only headers (e.g. ``[main]``) and
7744
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
40 *required* parameters that are different from defaults. For example::
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
41
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
42 [main]
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
43 template_engine = jinja2
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
44
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
45 static_files = static
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
46
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
47 These settings override the default values in the tracker's
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
48 ``config.ini`` when using roundup-admin to install a template.
2826
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
49 - template "marker" file ``TEMPLATE-INFO.txt``, which contains
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
50 the name of the template, a description of the template
eb0015a2caa5 template contents description changed to new layout
Alexander Smishlajev <a1s@users.sourceforge.net>
parents: 2133
diff changeset
51 and its intended audience.
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52
7744
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
53 An example TEMPLATE-INFO.txt:
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
54
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
55 .. code-block:: text
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
56
7744
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
57 Name: classic
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
58 Description: This is a generic issue tracker that may be used to
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
59 track bugs, feature requests, project issues or any
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
60 number of other types of issues. Most users of
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
61 Roundup will find that this template suits them,
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
62 with perhaps a few customisations.
6985f0ff3df3 doc: document lib, fix formating/example
John Rouillard <rouilj@ieee.org>
parents: 6739
diff changeset
63 Intended-For: All first-time Roundup users
2133
f01befe8a7fe *** empty log message ***
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64

Roundup Issue Tracker: http://roundup-tracker.org/