= Documentation for JWT Feature

The jwt feature adds support for JSON API access for all other features
that ship with Rodauth, using JWT (JSON Web Tokens) to hold the
session information. It depends on the json feature.

In order to use this feature, you have to set the +jwt_secret+ configuration
option with the secret used to cryptographically protect the token.

To use this JSON API, when processing responses for requests to a Rodauth
endpoint, check for the Authorization header, and use the value of the
response Authorization header as the request Authorization header in
future requests, if the response Authorization header is set. If the
response Authorization header is not set, then continue to use the
previous Authorization header.

When using this feature, consider using the <tt>json: :only</tt> option when
loading the rodauth plugin, if you want Rodauth to only handle
JSON requests.  If you don't use the <tt>json: :only</tt> option, the jwt feature
will probably result in an error if a request to a Rodauth endpoint comes
in with a Content-Type that isn't application/json, unless you also set
<tt>only_json? false</tt> in your rodauth configuration.

If you would like to check if a valid JWT was submitted with the current
request in your Roda app, you can call the +rodauth.valid_jwt?+ method.  If
+rodauth.valid_jwt?+ returns true, the contents of the jwt can be retrieved
from +rodauth.session+.

Logging the session out does not invalidate the previous JWT token by default.
If you would like this behavior, you can use the active_sessions feature, which
stores session identifiers in the database and deletes them when the session
expires. This provides a whitelist approach of revoking JWT tokens.

== Auth Value Methods

invalid_jwt_format_error_message :: The error message to use when a JWT with an invalid format is submitted in the Authorization header.
jwt_algorithm :: The JWT algorithm to use, +HS256+ by default.
jwt_authorization_ignore :: A regexp matched against the Authorization header, which skips JWT processing if it matches.  By default, HTTP Basic and Digest authentication are ignored.
jwt_authorization_remove :: A regexp to remove from the Authorization header before processing the JWT.  By default, a Bearer prefix is removed.
jwt_decode_opts :: An optional hash to pass to +JWT.decode+. Can be used to set JWT verifiers.
jwt_old_secret :: The previous JWT secret used, to support JWT secret rotation (only supported when using jwt 2.4+).  Access to this should be protected the same as a session secret.
jwt_secret :: The JWT secret to use.  Access to this should be protected the same as a session secret.
jwt_session_key :: A key to nest the session hash under in the JWT payload.  nil by default, for no nesting.
jwt_symbolize_deeply? :: Whether to symbolize the session hash deeply.  false by default.
use_jwt? :: Whether to use the JWT in the Authorization header for authentication information.  If false, falls back to using the rack session. By default, the Authorization header is used if it is present, if +only_json?+ is true, or if the request uses a json content type.

== Auth Methods

jwt_session_hash :: The session hash used to create the session_jwt. Can be used to set JWT claims.
jwt_token :: Retrieve the JWT token from the request, by default taking it from the Authorization header.
session_jwt :: An encoded JWT for the current session.
set_jwt_token(token) :: Set the JWT token in the response, by default storing it in the Authorization header.