Define the access token API

1 files changed, 110 insertions, 1 deletions

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index 8d2d638..27295e0 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -118,9 +118,62 @@ are @emph{strings}, but we hope that in the future SRFI-180 will be
 more closely respected.
 
 @menu
+* The access token::
 * Generic JWTs::
 @end menu
 
+@node The access token
+@section The access token
+
+The access token is obtained by the client through a token request,
+and is presented to the server on each authenticated request. It is
+signed by the identity provider, and it contains enough information so
+that the server knows who the user is and who the agent is, and most
+importantly the fingerprint of the key that the client should use in a
+DPoP proof.
+
+The API is defined in @emph{(webid-oidc access-token)}.
+
+@deffn function access-token? @var{object}
+Check that @var{object} is a decoded access token.
+@end deffn
+
+There are field getters for the access token:
+
+@deffn function access-token-webid @var{token}
+@deffnx function access-token-iss @var{token}
+@deffnx function access-token-aud @var{token}
+@deffnx function access-token-exp @var{token}
+@deffnx function access-token-iat @var{token}
+@deffnx function access-token-cnf/jkt @var{token}
+@deffnx function access-token-client-id @var{token}
+Get the suitable field from the payload of @var{token}.
+@end deffn
+
+Access tokens can be signed and encoded as a string, or decoded.
+
+@deffn function access-token-decode @var{token} @var{[#http-get]}
+Decode @var{token}, as a string, into a decoded token. As with the ID
+token, the signature verification will need to fetch the oidc
+configuration of the claimed issuer, and check the signature against
+the published keys. The @code{http-get} optional keyword argument can
+set a different implementation of @code{http-get} from
+@emph{(web client)}, for instance to re-use the what has been obtained
+by the ID token validation. Return @code{#f} if it failed, or the
+decoded token otherwise.
+@end deffn
+
+@deffn function access-token-encode @var{token} @var{key}
+Encode @var{token} and sign it with the issuer’s @var{key}.
+@end deffn
+
+@deffn function issue-access-token @var{issuer-key} @var{#alg} @var{#webid} @var{#iss} @var{#exp} @var{#iat} @var{[#client-key} @var{|} @var{#cnf/jkt]} @var{#client-id}
+Create an access token, and encode it with @var{issuer-key}. You can
+either set the @code{#:cnf/jkt} keyword argument with the fingerprint
+of the client key, or set @code{#:client-key} directly, in which case
+the fingerprint will be computed for you.
+@end deffn
+
 @node Generic JWTs
 @section Generic JWTs
 
@@ -218,13 +271,41 @@ failed. @var{value} is the incorrect input, and @var{cause} is a
 low-level error.
 @end deftp
 
+@deftp {exception type} &incorrect-webid-field @var{value}
+The @var{value} of the webid field in the JWT is missing (if
+@code{#f}), or not an acceptable value.
+@end deftp
+
+@deftp {exception type} &incorrect-iss-field @var{value}
+The @var{value} of the iss field is incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-aud-field @var{value}
+The @var{value} of the aud field is incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-iat-field @var{value}
+The @var{value} of the iat field is incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-exp-field @var{value}
+The @var{value} of the exp field is incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-cnf/jkt-field @var{value}
+The @var{value} of the cnf/jkt field is incorrect.
+@end deftp
+
+@deftp {exception type} &incorrect-client-id-field @var{value}
+The @var{value} of the client-id field is incorrect.
+@end deftp
+
 @node Invalid JWT
 @section Invalid JWT
 Each JWT type – access token, DPoP proof, ID token, authorization code
 (this is internal to the identity provider) has different validation
 rules, and can fail in different ways.
 
-
 @deftp {exception type} &not-json @var{value} @var{cause}
 Cannot decode @var{value} to a JSON object.
 @end deftp
@@ -291,6 +372,26 @@ The @var{value} string is not an encoding of a valid JWS.
 The @var{jws} cannot be signed.
 @end deftp
 
+@deftp {exception type} &not-an-access-token @var{value} @var{cause}
+The @var{value} is not an access token.
+@end deftp
+
+@deftp {exception type} &not-an-access-token-header @var{value} @var{cause}
+The @var{value} is not an access token header.
+@end deftp
+
+@deftp {exception type} &not-an-access-token-payload @var{value} @var{cause}
+The @var{value} is not an access token payload.
+@end deftp
+
+@deftp {exception type} &cannot-decode-access-token @var{value} @var{cause}
+The @var{value} string is not an encoding of a valid access token.
+@end deftp
+
+@deftp {exception type} &cannot-encode-access-token @var{access-token} @var{key} @var{cause}
+The @var{access-token} cannot be signed.
+@end deftp
+
 @node Cannot fetch data on the web
 @section Cannot fetch data on the web
 In the client (local and public parts), resource server and identity
@@ -314,6 +415,14 @@ The @var{response} (from @emph{(web response)}) is not appropriate.
 The @var{value} is not appropriate an OIDC configuration.
 @end deftp
 
+@deftp {exception type} &cannot-fetch-issuer-configuration @var{issuer} @var{cause}
+It is impossible to fetch the configuration of @var{issuer}.
+@end deftp
+
+@deftp {exception type} &cannot-fetch-jwks @var{issuer} @var{uri} @var{cause}
+It is impossible to fetch the keys of @var{issuer} at @var{uri}.
+@end deftp
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License