annotate doc/Makefile @ 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 c3bf229d3d4b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
1 ##@ Default target
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
2 all: man_html tracker_config.txt admin_help.html ## make all docs under share
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
3 cd ..; ./setup.py build_doc
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
4
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
5 ##@ build doc parts
8274
c3bf229d3d4b doc: update tracker_config.txt
John Rouillard <rouilj@ieee.org>
parents: 8271
diff changeset
6 tracker_config.txt: ../roundup/configuration.py format_config.awk ## generate a current config file
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
7
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
8 python3 ../roundup/scripts/roundup_admin.py \
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
9 genconfig _temp_config.txt
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
10
8036
8b5f8b950f58 docs: add section anchors to config.ini in references.txt; change format
John Rouillard <rouilj@ieee.org>
parents: 7920
diff changeset
11 awk -f format_config.awk _temp_config.txt | \
8b5f8b950f58 docs: add section anchors to config.ini in references.txt; change format
John Rouillard <rouilj@ieee.org>
parents: 7920
diff changeset
12 cat -s > tracker_config.txt
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
13 rm -f _temp_config.txt
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
14
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
15 ## generate html versions of man pages for inclusion in documentation
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
16 # find all man pages and generate output file paths.
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
17 MAN_ROFF=$(wildcard ../share/man/man1/*.1)
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
18 MAN_HTML=$(patsubst ../share/man/man1/%.1,html_extra/man_pages/%.1.html,$(MAN_ROFF))
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
19
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
20 man_html: $(MAN_HTML) ## generate html versions of man pages for docs
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
21
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
22 html_extra/man_pages/%.1.html: ../share/man/man1/%.1
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
23 man --html=cat $< > $@
8075
08fcbdfe670b docs: set max width for man page paragraphs to 65ch
John Rouillard <rouilj@ieee.org>
parents: 8036
diff changeset
24 # set max width for paragraphs
08fcbdfe670b docs: set max width for man page paragraphs to 65ch
John Rouillard <rouilj@ieee.org>
parents: 8036
diff changeset
25 sed -i '/<style/,/<\/style/s/\(p\s* { \)margin/\1max-width: 65ch; margin/' $@
8116
d4fbfc6a7662 docs: add canonical link for all generated man pages
John Rouillard <rouilj@ieee.org>
parents: 8096
diff changeset
26 # add link rel=cannonical $@(F) takes
d4fbfc6a7662 docs: add canonical link for all generated man pages
John Rouillard <rouilj@ieee.org>
parents: 8096
diff changeset
27 # target $@ (html_extra/man_pages/x.1.html)
d4fbfc6a7662 docs: add canonical link for all generated man pages
John Rouillard <rouilj@ieee.org>
parents: 8096
diff changeset
28 # and returns file part (x.1.html)
d4fbfc6a7662 docs: add canonical link for all generated man pages
John Rouillard <rouilj@ieee.org>
parents: 8096
diff changeset
29 sed -i '/<head>/,/<\/head>/s#^<style#<link rel="canonical" href="https://www.roundup-tracker.org/docs/man_pages/$(@F)">\n<style#' $@
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
30 #man2html $< > $@
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
31
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
32 admin_help.html: ../roundup/admin.py ## generate html version of roundup-admin help (WIP)
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
33 python3 ../roundup/scripts/roundup_admin.py htmlhelp > admin_help.html
8096
ea1f377c87d6 docs: add roundup-admin interactive help output to admin_guide.txt
John Rouillard <rouilj@ieee.org>
parents: 8075
diff changeset
34
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
35 ##@ Utilties
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
36
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
37 clean: ## clean all generated docs
7920
6aa0525187cd doc: use generated config.ini in reference.txt
John Rouillard <rouilj@ieee.org>
parents:
diff changeset
38 rm -f _temp_config.txt tracker_config.txt \
8096
ea1f377c87d6 docs: add roundup-admin interactive help output to admin_guide.txt
John Rouillard <rouilj@ieee.org>
parents: 8075
diff changeset
39 html_extra/man_pages/*.1.html \
ea1f377c87d6 docs: add roundup-admin interactive help output to admin_guide.txt
John Rouillard <rouilj@ieee.org>
parents: 8075
diff changeset
40 admin_help.py
8271
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
41
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
42 # from https://www.thapaliya.com/en/writings/well-documented-makefiles/ via
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
43 # https://til.jakelazaroff.com/make/list-all-commands-in-a-makefile/
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
44 help: ## this output
8824c81cc431 doc: add make help to all Makefiles and fix 2 Makefiles
John Rouillard <rouilj@ieee.org>
parents: 8116
diff changeset
45 @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m<target>\033[0m\n"} /^[.a-zA-Z_-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

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