requests, in each case with
C<< $authreq = CGI::Auth::Flexible->new_request($cgi_query) >>.
-=head2 RESPONSE GENERATION - SIMPLE APPLICATIONS
+=head2 CHECKING AND RESPONSE GENERATION
+
+If the user is logged in, your application is to handle the request.
+Otherwise, the user needs to be presented with a login form or error
+message, as appropriate. CGI::Auth::Flexible provides two alternative
+interfaces for this:
+
+=head3 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
request; you can use C<< $request->get_username >> to find out which
user the request came from.
-=head2 RESPONSE GENERATION - SOPHISTICATED APPLICATIONS
+=head2 Sophisticated applications
If you want to handle the control flow and to generate login forms,
redirections, etc., yourself, you can say
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.
+page or diversion should be generated. See L</DIVERT SPEC> below for
+details of how to deal with the return value.
-=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-IGNORANT APPLICATIONS
+=head2 MUTATING OPERATIONS AND EXTERNAL LINKS
+
+=head3 Mutation-ignorant applications
By default CGI::Auth::Flexible does not permit external links into
your site. All GET requests give a "click to continue" page which
Such applications are also not able to provide user-specific CSS
stylesheets, javascript, favicons, etc.
-=head2 MUTATING OPERATIONS AND EXTERNAL LINKS - MUTATION-AWARE APPLICATIONS
+=head3 Mutation-aware applications
The alternative is for your application to always make a special check
when the incoming request is going to do some kind of action (such as
(You do not need to call C<check_nonpage> for POST requests, but it is
harmless to do so.)
+=head3 Mutation-aware applications - novel kinds of request
+
+If you want to support a kind of request perhaps not yet known about
+by CGI::Auth::Flexible, you can provide information about that new
+request kind using C<update_get_need_add_hidden>.
+
=head2 DATA STORAGE
CGI::Auth::Flexible needs to store various information in plain files;
For each source item in a dvcs, the entire dvcs history does
not contain anything confidential (or libellous). Also, all files which
-contain secrets are in the dvcs's C<.ignore> file. See
+contain secrets are in the dvcs's I<.ignore> file. See
C<srcdump_vcsscript_git> et al.
=item *
=item C<< $verifier->new_request($cgi_query) >>
-Prepares to process a request. C<$cgi_query> should normally
+Prepares to process a request. I<$cgi_query> should normally
be the query object from L<CGI(3perl)>. Most of the default
hook methods assume that it is; however if you replace enough of
the hook methods then you can pass any value you like and it
will be passed to your hooks.
-The return value is the authentication request object (C<$authreq>)
+The return value is the authentication request object (I<$authreq>)
which is used to check the incoming request and will contain
information about its credentials.
Discards the resources (open files, etc.) in the verifier object.
=back
+
+=head REQUEST-RELATED FUNCTIONS AND METHODS
+
+All of these are only valid after C<check_divert> or C<check_ok> has
+been called. (In the case of C<check_ok> it won't normally be sensible
+to call these functions unless C<check_ok> returned true.)
+
+=item C<< $authreq->get_divert() >>
+
+Returns the value previously returned by C<check_divert>.
+
+=item C<< $authreq->get_username() >>
+
+Returns the name of the logged-in user. If the user was not logged
+in (or their session had timed out, or something), returns undef.
+
+=item C<< $authreq->check_mutate() >>
+
+Declares to CGI::Auth::Generic that the request being handled will
+"mutate". That is, it will modify some server-side state (eg, adding
+items to shopping baskets, posting messages to blogs, sending emails,
+or whatever).
+
+If you have set the setting C<promise_check_mutate> you must call
+C<check_mutate> whenever appropriate. If you haven't then it's
+irrelevant. See L<MUTATING OPERATIONS AND EXTERNAL LINKS>.
+
+C<check_mutate> will either return successfully, indicating that all
+is well and the request should proceed, or it will die. If it dies
+that means that the request was improper, which can only result from a
+bug or an attack. So an "internal server error" is a suitable
+response.
+
+=item C<< $authreq->check_nonpage($method, $reqtype) >>
+
+Declares to CGI::Auth::Generic that the request is not a page request,
+but rather a request of type I<$reqtype>.
+
+If your application has set the setting C<promise_check_mutate>,
+whenever it is handling anything except an HTML page loads, it must
+call this function. See L</REQUEST TYPES>, and
+L<GENERATING URLS, FORMS AND AJAX QUERIES>.
+
+C<check_mutate> will either return successfully, indicating that all
+is well and the request should proceed, or it will die, like
+C<check_mutate>.
+
+=head RESPONSE-RELATED FUNCTIONS AND METHODS
+
+=item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
+
+Convenience function which returns a url for a GET request to this
+application.
+
+I<$params> is a hashref specifying the parameters and the PATH_INFO.
+The keys are the parameter names, and the values are array refs with
+the parameter value(s) (as strings, as yet unquoted). (They are array
+refs because it is possible to pass multiple values for the same
+parameter in a single request; normally each arrayref would be a
+singleton.)
+
+The request path will be the path to the application. If a parameter
+with name C<< '' >> is supplied, it is taken as the PATH_INFO - its
+value will be appended to the application path. (It should normally
+start with C<< / >>, and only one value should be supplied.)
+
+=item C<< something->need_add_hidden($method, $reqtype) >>
+
+Enquires whether a request of type I<$reqtype> using HTTP method
+I<$method> needs the hidden form parameter. See L</REQUEST TYPES>.
+
+=item C<< something->secret_hidden_val() >>
+
+Returns the value of the hidden form parameter. This should be
+included in all POST requests to your application (and thus be a
+hidden form parameter in all forms).
+
+It should also be in some (maybe all) GET requests. If your
+application is mutation-ignorant, it should be in all GET requests.
+If you are mutation-aware, you need to consult C<need_add_hidden>.
+
+The name of the hidden parameter is the setting C<assoc_param_name>,
+C<caf_hassochash> by default. xxx rename param and setting
+
+=item C<< something->secret_hidden_html() >>
+
+Returns the HTML for an C<INPUT> element specifying the hidden form
+parameter.
+
+=item C<< something->secret_cookie_val() >>
+
+Returns the value of the secret cookie. CGI::Auth::Flexible sets this
+cookie in the forms generated by C<check_ok>. You may also set it
+yourself (and indeed you must do so if you use C<check_divert>).
+
+=item C<< $authreq->chain_params() >>
+
+Returns a hash of the "relevant" parameters to this request, in a form
+used by XXX. This is all of the query parameters which are not
+related to CGI::Auth::Flexible. The PATH_INFO from the request is
+returned as the parameter C<< '' >>.
+
+xxx why use this function
+
+=back
+
+=head OTHER FUNCTIONS AND METHODS
+
+=over
+
+=item C<< $verifier_or_authreq->hash($data) >>
+
+Hashes the supplied data using the hash function specified by the
+C<hash_algorithm> setting, and converts the result to a string of hex
+digits.
+
+=item C<< something->update_get_need_add_hidden($reqtype, $value, [$force]) >>
+
+Updates CGI::Auth::Generic's knowledge about the various kinds of
+request, and whether they need the hidden form parameter. This
+function applies only to GET requests - POST requests always use the
+parameter.
+
+I<$reqtype> is the request type (the value which will be passed to
+C<check_nonpage> and C<need_add_hidden>. If you are supporting a new
+I<$reqtype> you shouuld coordinate with CGI::Auth::Flexible upstrea,
+or other users, to assign a unique request type name.
+
+This method may be called on an authreq or a verifier, in which case
+it will affect all authreqs using the same verifier. Or it may be
+called on the class as a whole, in which case it will affect the
+global default list for all verifiers.
+
+If I<$force> is supplied and true, this will override
+CGI::Auth::Flexible's existing knowledge. Otherwise this new setting
+will be ignored if CGI::Auth::Flexible already knows about the request
+type. (When called on a verifier or authreq, it will ignore the
+update in favour of existing knowledge recorded both globally in the
+class or due to previous requests on the same verifier.)
+
+See L</REQUEST TYPES>.
+
+=item C<< $verifier_or_authreq->($data) | CGI::Auth::Flexible->>>
+
+Hashes the supplied data using the hash function specified by the
+C<hash_algorithm> setting, and converts the result to a string of hex
+digits.
+
+=back
+
+
+
+xxx divert spec
+xxx reqtype
+xxx settings
+xxx html generators
+xxx document cookie
~ian / cgi-auth-flexible.git / blobdiff