Implement the resource server verification code

1 files changed, 49 insertions, 0 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index 850e2be..6a0e633 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -50,6 +50,7 @@ Free Documentation License''
 * The Json Web Token::
 * Caching on server side::
 * Running an Identity Provider::
+* Running a Resource Server::
 * Exceptional conditions::
 * GNU Free Documentation License::
 * Index::
@@ -433,6 +434,54 @@ starts to require the random number generator. You can safely delete
 this directory, but you need to restart the program to actually change
 the seed.
 
+@node Running a Resource Server
+@chapter Running a Resource Server
+
+@menu
+* The authenticator::
+@end menu
+
+A Solid server is the server that manages your data. It needs to check
+that the proofs of possession are correct, and the possessed key is
+signed by the identity provider.
+
+@node The authenticator
+@section The authenticator
+
+In @emph{(webid-oidc jws)}, the following function gives a simple API
+for a web server:
+
+@deffn function make-authenticator @var{jti-list} @var{[#server-uri]} @var{[#current-time]} @var{[#http-get]}
+Create an authenticator, i.e. a function that takes a request and
+request body and returns the webid of the authenticated user, or
+@code{#f} if it is not authenticated.
+
+To prevent replay attacks, each request is signed by the client with a
+different unique padding value. If such a value has already been seen,
+then the request must fail.
+
+The authenticator expects the client to demonstrate the possession of
+a key that the identity provider knows. So the client creates a DPoP
+proof, targetted to a specific URI. In order to check that the URI is
+correct, the authenticator needs the public URI of the service.
+
+The JTIs are checked within a small time frame. By default, the system
+time will be used. Otherwise, you can customize the
+@code{current-time} optional keyword argument, to pass a thunk
+returning a time from @emph{(srfi srfi-19)}.
+
+You may want to customize the @var{http-get} optional keyword argument
+to pass a function to replace @code{http-get} from @emph{(http
+client)}. This function takes an URI and optional @code{#:headers}
+arguments, makes the request, and return two values: the response, and
+the response body.
+
+This function, in @emph{(webid-oidc resource-server)}, returns a web
+request handler, taking the request and request body, and returning
+the subject of the access token. If an error happens, it is thrown;
+the function always returns a valid URI.
+@end deffn
+
 @node Exceptional conditions
 @chapter Exceptional conditions