Developer's info about InstallPasswordAddOn

Well, this is not feedback (yet), but rather a description about the internals of InstallPasswordAddOn...

-- HaraldJoerg - 14 Dec 2005

The Concept

The installation of a new password which is only available in encrypted form needs a workflow, consisting of a couple of web pages and mails, not necessarily presented to the same audience.

The implementation I have choosen is a simplification of Randal Schwartz's CPAN:CGI::Prototype::Hidden, or CPH for short, just because I like the concept. I did not take the original because:

1. It creates dependencies to CPAN which in my opinion would only be appropriate if the module would become a general workflow base for TWiki.
2. It's default template engine is Andy Wardley's Template Toolkit, or TT. I love the toolkit, but it draws in about half of CPAN. It would be overengineering to use it for just this little addon, and too tedious to integrate TWiki's rendering engine as a backend. This is left as an exercise to the reader .

Differences to Cairo's InstallPassword Mechanism

Feature	Cairo	InstallPasswordAddOn
User action	Fill form in Topic	Fill form in Topic
Verification of user's email	No	Like Dakar's TWikiRegistration
Admin action	Fill form in Topic	Click on link in Mail
Encrypted password transport	User and admin copy and paste	Behind TWiki's scenes
Who can approve	Member of TWikiAdminGroup	%WIKIWEBMASTER%
Password managers	HtPasswdUser only	HtPasswdUser only

CGI::Prototype::Hidden in a Nutshell

To save you the effort of investigating Randal's concept yourself, I'll outline it here:

• A workflow is separated in different "steps", each step is a web form, or a Perl package.
• Each step (package) has basically two parts (methods) - or to be precise, I've reduced it to two parts for the current implementation:
  1. A respond routine which evaluates the parameter from the form and takes appropriate action, and
  2. A render routine which prepares the feedback to the user
• The return value of respond routine decides what feedback will be given - for example which step is following next. In CPH this is done by returning the package name of the render routine.
• The default strategy is "keep in the same step until we have enough data for something else", so the render method usually presents the form leading into the respond method in the same package again. This is really cute. It allows to handle user errors (e.g. missing or inconsistent fields) within one package.
• To shuffle information around between the methods, CPH adds "slots" to the base object. I did not dare to apply the same technique to the TWiki object (yet), so I had to compromise. More on that in the next sections.
• The basic technique to preserve state between web forms during a workflow in CPH is to pass CPAN:CGI query object around. This I could adopt almost literally:
  1. The query is contained in the TWiki object, and
  2. Like CGI params are made available to TT by passing the CGI object, TWiki templates can access query parameters with its %URLPARAM% variable.
  3. CPH uses a hidden (sic!) variable to control the dispatcher. I have called it action, and it isn't always hidden.

You probably want to know more, and there is more. Randal Schwartz has written three columns in for the linux magazine, starting at Column 70.

Deviations from CPH Design in this Addon

• I have considered only two methods per step, whereas CPH has a more comprehensive design.
• I have left all the routines in one package, and did not create the individual steps as Perl objects. The routines are named with a strict convention <step><Method>, e.g. startRespond for the respond method for the first step, and they return code references instead of package names.
• The TWiki object is not designed to add arbitrary sub-objects, and I considered it too intrusive to just invent some presumably unused hash keys.
  • For the web pages to be created this is OK, because I have the CGI params at hand to pass information.
  • However, the mails should be considered "feedback" as well, and for a clean architecture they should be sent by the render routine. I moved sending the mails into the respond routine, immediately before returning. I had to duplicate code (one line, to be precise) but could avoid to trick the TWiki object.

Issues

Things I consider ugly though they are consistent with Dakar

• Throwing an oops exception is quite usual in the TWiki registration process, so I have used the same technique. What I consider ugly is that the Error.pm from the TWiki distribution (unlike the CPAN original) fills Apache's error log for every oops.
• The add-on needs quite a bunch of templates which are used for content and not for layout. Again, the registration procedure is similar...
• There is no convention regarding where modules supporting add-ons should be located. This add-on is no plugin (it doesn't need to register anything for TWiki's usual operation), and it is no contrib (because the code can't be used elsewhere). For reason of symmetry with bin/view etc. I have used the lib/TWiki/UI/ namespace. In current add-ons I have found:
  • CompareRevisionsAddOn in /lib/TWiki/UI/Compare.pm
  • GenPDFAddOn in /lib/TWiki/Contrib/GenPDF.pm
  • MailToTWikiAddOn in /lib/TWiki/Plugins/MailToTWikiPlugin.pm

Things I'm not quite happy with

• All templates are I18N'ed. However, Dakar doesn't seem to have a process of including addons and plugins to the L10N creation, and unfortunately a few of the texts are found in core Dakar. So, most of the texts will be English, but a few might be in whatever language the user chooses.
• Approval and password installation is not done by a member of TWikiAdminGroup, but of some persond responding to the mail address of %WIKIWEBMASTER%. I have no idea whether this is in line with TWiki's role model between those two (if there is any).
  • As a consequence the "random password" code is the only security measure in place. I don't know whether it is safe to assume that %WIKIWEBMASTER%s are members of TWikiAdminGroup?

Testcases and debugging

TWiki's unit test framework is not extremely well suited for workflow tests, because each step in the workflow needs the results of all previous steps preserved. So each of the tests passes through the whole process. Running the tests is a bit slow (12 wallclock seconds for 5 testcases on a 3.0GHz machine), because the testcases need to create a temporary web and then a temporary user in that web....

And unfortunately the syntax to pass parameters to TWiki in scripted mode isn't what I would call "well documented".

I've attached a file which fits into TWiki's unit test framework in DakarRelease SVN.

Dirty tricks

I found it comfortable to define (and export) the environment variable GATEWAY_INTERFACE to cheat TWiki into believing this is a CGI process and then debug with the Perl debugger and CGI's built-in command line capability like that:

perl -dT installpassword 'TWiki/InstallPassword?loginname=user;password=a;confirm=a;email=me@home;comment=BelieveMe'

There's a global variable to make InstallPassword.pm send its mails to STDERR instead of the mail recipient, so that they can be tracked from the apache error log, or from console when debugging:

 $TWiki::UI::InstallPassword::mailToStderr = 1

-- HaraldJoerg - 14 Dec 2005

Thanks Harald, this was the missing piece to upgrade twiki.org to Dakar!

I am surprised by the complexity compared to the Cairo installpasswd.

-- PeterThoeny - 15 Dec 2005

I've added a comparison table to Cairo's InstallPassword, and attached a couple of testcases.

About the complexity - this has mainly two reasons:

1. The addon supports the email verification step as introduced in DakarRelease registration. This requires some sort of "data persistence" which wasn't necessary in Cairo. I felt this was necessary for symmetry with the registration process: If you need a valid email address to register, you should need a valid email address to re-claim your wikiname, too.
2. The addon does the moving around of the encrypted password behind the scenes. No need to copy and paste between mail and forms. All mails are sent by TWiki code.

I've been musing about adding even more complexity by creating a TWiki topic in which a member of the TWikiAdminGroup can click on "approve" links for each of the candidates with open installation requests but opted against it because I think that even on very busy sites the number of requests will be a few per week.

CrawfordCurrie said that this should be a Contrib and not a Addon. This wouldn't change the user or admin interface, but some files would get different locations. I don't think I'll upload a new version just for that purpose, but if I ever add a new version, it will most likely be a Contrib, technically, unless there's feedback in the other direction.

-- HaraldJoerg - 16 Dec 2005

I added a SHORTDESCRIPTION to the "Add-On Info" section so that this add-on is represented properly in the AddOnPackage topic and query topics. Please feel free to take this into the next release.

-- PeterThoeny - 07 Oct 2006