From 53d4ed13ee06c55dad8337aa556eb631afddd8ae Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Thu, 28 Mar 2013 20:17:55 +0000
Subject: [PATCH] docs: more work

---
 caf.pod | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 93 insertions(+), 7 deletions(-)

diff --git a/caf.pod b/caf.pod
index ed4c6c9..ce9e3fb 100644
--- a/caf.pod
+++ b/caf.pod
@@ -367,7 +367,7 @@ Discards the resources (open files, etc.) in the verifier object.
 
 =back
 
-=head REQUEST-RELATED FUNCTIONS AND METHODS
+=head1 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
@@ -409,11 +409,11 @@ 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
+C<check_nonpage> 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
+=head1 RESPONSE-RELATED FUNCTIONS AND METHODS
 
 =item C<< $authreq->url_with_query_params($params, [$nonpagetype]) >>
 
@@ -463,7 +463,7 @@ yourself (and indeed you must do so if you use C<check_divert>).
 
 =back
 
-=head OTHER FUNCTIONS AND METHODS
+=head1 OTHER FUNCTIONS AND METHODS
 
 =over
 
@@ -522,6 +522,81 @@ digits.
 
 =back
 
+=head1 REQUEST TYPES
+
+The C<$reqtype> values understood by C<check_nonpage> are strings.
+They are:
+
+=over
+
+=item C<PAGE>
+
+A top-level HTML page load.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<FRAME>
+
+An HTML frame.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<IFRAME>
+
+An HTML iframe.  May contain confidential information for
+the benefit of the logged-in user.
+
+=item C<SRCDUMP>
+
+Source dump request, whether for the licence or actual source code
+tarball; returned value is not secret.
+
+=item C<STYLESHEET>
+
+CSS stylesheet.  B<MUST NOT> contain any confidential data.  If the
+stylesheet depends on the user, then attackers may be able to
+determine what stylesheet the user is using.  Hopefully this is not a
+problem.
+
+=item C<FAVICON>
+
+"Favicon" - icon for display in the browser's url bar etc.  We aren't
+currently aware of a way that attackers can get a copy of this.
+
+=item C<ROBOTS>
+
+C<robots.txt>.  Should not contain any confidential data (obviously).
+
+=item C<IMAGE>
+
+Inline image, for an C<< <img src=...> >> element.
+
+Unfortunately it is not possible to sensibly show top-level
+confidential images (that is, have the user's browser directly visit a
+url which resolves to an image rather than an HTML page with an inline
+image).  This is because images need to have a per-session hidden form
+parameter to avoid cross-site scripting, which breaks bookmarks etc.
+
+=item C<SCRIPT>
+
+JavaScript for a C<< <script> >> element.  (Possibly confidential for
+the user.)
+
+=item C<AJAX-XML>
+
+C<< XMLHttpRequest >> returning XML data.  (Possibly
+confidential for the user.)
+
+=item C<AJAX-JSON>
+
+C<< XMLHttpRequest >> returning JSON data.  (Possibly
+confidential for the user.)
+
+=item C<AJAX-OTHER>
+
+C<< XMLHttpRequest >> returning data of some other kind.  (Possibly
+confidential for the user.)
+
+=back.
+
 =head1 SETTINGS
 
 C<new_verifier> and C<new_request> each take a list of settings, as
@@ -785,7 +860,8 @@ channel.  The default is C<< !!$cgi->https() >>.  See C<encrypted_only>.
 
 =head2 SETTINGS RELATED TO HTML GENERATION
 
-These are only used if you call C<check_ok> or xxx some other functions?.
+These are only used if you call C<check_ok> (or other functions
+mentioned in this section).
 
 Settings whose names are of the form C<gen_...> are hooks which each
 return an array of strings, normally HTML strings, for use by
@@ -1118,8 +1194,18 @@ xxx make _db_setup_do explicitly overrideable
 
 
 xxx divert spec
-xxx reqtype
-xxx settings
+xxx remaining settings
+ assocdb_password
+ username_password_error
+ login_ok
+ get_cookie_domain
+ gettext
+ print
+ debug
+
+xxx $message argument to $outfn->() is not for log, it's for manifest
+xxx document syntax of $message argument to $outfn->()
+
 xxx html generators
 xxx document cookie
 
-- 
2.30.2