From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sat, 23 Feb 2013 20:38:27 +0000 (+0000)
Subject: docs: wip
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?a=commitdiff_plain;h=64aab607bcea54b44c8c1f83506a8966da99d04f;p=cgi-auth-flexible.git

docs: wip
---

diff --git a/cgi-auth-flexible.pm b/cgi-auth-flexible.pm
index ae53ca3..a4b8f56 100644
--- a/cgi-auth-flexible.pm
+++ b/cgi-auth-flexible.pm
@@ -1361,7 +1361,7 @@ call CGI::Auth::Flexible before answering AJAX requests as well as
 before generating HTML pages, of course, and to call it in every
 entrypoint to your system.
 
-=head1 INITIALISATION
+=head2 INITIALISATION
 
 Your application should, on startup (eg, when it is loaded by
 mod_perl) do
@@ -1372,7 +1372,7 @@ The resulting verifier object can be used to process individual
 requests, in each case with
 C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
 
-=head1 SIMPLE APPLICATIONS
+=head2 SIMPLE APPLICATIONS
 
 The simplist usage is to call C<< $request->check_ok() >> which will
 check the user's authentication.  If the user is not logged in it will
@@ -1383,7 +1383,7 @@ any further.  If the user is logged in it will return true.
 After calling C<check_ok> you can use C<< $request->get_username >>
 to find out which user the request came from.
 
-=head1 SOPHISTICATED APPLICATIONS
+=head2 SOPHISTICATED APPLICATIONS
 
 If you want to handle the flow control and to generate login forms,
 redirections, etc., yourself, you can say
@@ -1391,11 +1391,26 @@ C<< $divert = $request->check_divert >>.  This returns undef if
 the user is logged in, or I<divert spec> if some kind of login
 page or diversion should be generated.
 
-=head1 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
+=head2 GENERATING (MUTATING) FORMS AND AJAX QUERIES
+
+When you generate a C<POST> form or AJAX request you need to include a
+special secret hidden form parameter for the benefit of
+CGI::Auth::Generic.  This form parameter will be checked by
+C<check_ok>/C<check_divert> and should be ignored by your application.
+
+By default its name is C<caf_assochash>.  After calling C<check_ok> or
+C<check_divert> the value to put in your form can be obtained from
+C<secret_hidden_val>; C<secret_hidden_html> will generate the whole
+HTML C<< <input...> >> element.
+
+Do not put the secret value in URLs for C<GET> requests.
+
+=head2 MUTATING OPERATIONS AND EXTERNAL LINKS INTO YOUR SITE
 
 By default CGI::Auth::Flexible does not permit external links into
 your site.  All GET requests give a "click to continue" page which
-submits a form.
+submits a form.  In this configuration all your application's forms
+and AJAX requests should use C<POST>.
 
 This is because the alternative (for complicated reasons relating to
 the web security architecture) is to require your application to make
@@ -1403,12 +1418,21 @@ a special and different check when the incoming request is going to do
 some kind of action (such as modifying the user's setup, purchasing
 goods, or whatever) rather than just display HTML pages.
 
-To support external links, pass C<< promise_check_mutate => 1 >> in
-I<settings>, and then call C<< $authreq->check_mutate() >> before
-taking any actions.  If the incoming request is not suitable then
-C<< $authreq->check_mutate() >> will call C<die>.  If you do this you
-must make sure that you have no mutating C<GET> requests in your
-application - but you shouldn't have any of those anyway.
+To support external links, and C<GET> requests, pass C<<
+promise_check_mutate => 1 >> in I<settings>, and then call C<<
+$authreq->check_mutate() >> before taking any actions.  If the
+incoming request is not suitable then C<< $authreq->check_mutate() >>
+will call C<die>.  If you do this you must make sure that you have no
+mutating C<GET> requests in your application - but you shouldn't have
+any of those anyway.
+
+=head2 DATA STORAGE
+
+CGI::Auth::Flexible needs to store various information in plain files;
+it does this in the directory specified by the C<dir> parameter.
+
+It also needs to record state relating to user sessions in a database.
+There is no particular reason for this 
 
 =head1 SOURCE CODE DOWNLOAD
 
@@ -1475,11 +1499,11 @@ being in C<@INC> by default.  (See C<srcdump_filter_cwd>.)
 
 =back
 
-=head1 FUNCTIONS AND METHODS
+=head1 MAIN FUNCTIONS AND METHODS
 
 =over
 
-=item C<< CGI::Auth::Flexible::new_verifier(setting => value, ...) >>
+=item C<< CGI::Auth::Flexible->new_verifier(setting => value, ...) >>
 
 Initialises an instance and returns a verifier object.
 The arguments are setting pairs like a hash initialiser.
@@ -1503,4 +1527,20 @@ Checks whether the user is logged in.  Returns undef if the user is
 logged in and we should service the request.  Otherwise returns a
 divert spec (see L</DIVERT SPEC>) saying what should happen instead.
 
+This method may die if it doesn't like the request, in which case
+the request needs to be rejected.
+
+=item C<< $authreq->check_ok() >>
+
+Checks whether the user is logged in.  Returns true if the user is
+logged in and we should service the request.
+
+Otherwise it handles the request itself, generating any appropriate
+redirect, login form, or continuation page.  It then returns false and
+the application should not process the request further.
+
+=item C<< $authreq->disconnect() >>
+
+Disconnects from the 
+
 =back