# Charon v4.3.0 - Table of Contents

Authentication & sessions for API's.

## Pages

- [Charon](readme.md)
- [LICENSE](license.md)
- [Upgrade guide](upgrade_guide.md)
- [Changelog](changelog.md)

## Modules

- [Charon](Charon.md): Authentication & sessions for API's.

- [Charon.Config](Charon.Config.md): Config struct.
- [Charon.Models.Session](Charon.Models.Session.md): A session.

- [Charon.Models.Tokens](Charon.Models.Tokens.md): Tokens to be communicated to the client.

- [Charon.SessionPlugs](Charon.SessionPlugs.md): Plugs to create, update/refresh and delete sessions.
When creating or updating a session, new tokens are created as well.

- [Charon.SessionStore](Charon.SessionStore.md): The persistent session store. See `Charon.SessionStore.Behaviour` for callbacks.
All functions delegate to the configured session store module.
- [Charon.SessionStore.Behaviour](Charon.SessionStore.Behaviour.md): Behaviour definition of a persistent session store.
Clients should not use the implementation directly, but should use `Charon.SessionStore`.
- [Charon.SessionStore.DummyStore](Charon.SessionStore.DummyStore.md): A dummy session store that can be used if fully stateless tokens are desired.

- [Charon.SessionStore.LocalStore](Charon.SessionStore.LocalStore.md): An in-memory persistent session store, implements behaviour `Charon.SessionStore`.
In addition to the required callbacks, this store also provides `get_all/3` and `delete_all/3` (for a user) functions.
- [Charon.SessionStore.RedisStore](Charon.SessionStore.RedisStore.md): A persistent session store based on Redis, which implements behaviour `Charon.SessionStore`.
In addition to the required callbacks, this store also provides `get_all/3` and `delete_all/3` (for a user) functions.
- [Charon.SessionStore.RedisStore.Config](Charon.SessionStore.RedisStore.Config.md): Config module for `Charon.SessionStore.RedisStore`.

- [Charon.SessionStore.RedisStore.Migrate](Charon.SessionStore.RedisStore.Migrate.md): Migrate Redis data older to newer data formats.

- [Charon.SessionStore.RedisStore.RedisClient](Charon.SessionStore.RedisStore.RedisClient.md): Redis client backed by a connection pool.

- [Charon.Telemetry](Charon.Telemetry.md): Telemetry integration for Charon.
- [Charon.TestHelpers](Charon.TestHelpers.md): Utility functions for writing tests.

- [Charon.TokenFactory](Charon.TokenFactory.md): Entrypoint for `Charon.TokenFactory.Behaviour` implementation.
All functions delegate to the configured module.

- [Charon.TokenFactory.Behaviour](Charon.TokenFactory.Behaviour.md): Behaviour for token-signing modules.
- [Charon.TokenFactory.Jwt](Charon.TokenFactory.Jwt.md): JWT's with either symmetric (HMAC) or asymmetric (EDDSA) signatures.
The default, simplest and most performant option is symmetric signatures (MAC),
with the key derived from the Charon base secret.
- [Charon.TokenFactory.Jwt.Config](Charon.TokenFactory.Jwt.Config.md): Config module for `Charon.TokenFactory.Jwt`.

- [Charon.TokenPlugs](Charon.TokenPlugs.md): The plugs in this module (and its submodules) can be used to verify tokens.
The token's presence, signature, expiration and any claims can be checked.
Additionally, the token's session can be loaded and, in case of a refresh token,
it can be verified that it matches the session.
- [Charon.TokenPlugs.OrdsetClaimHas](Charon.TokenPlugs.OrdsetClaimHas.md): Verifies that bearer token payload claims contain expected values using `m::ordsets` (ordered set) operations.
- [Charon.TokenPlugs.PutAssigns](Charon.TokenPlugs.PutAssigns.md): After verifying everything you would want to verify about a token,
assign data to the conn.
- [Charon.Utils](Charon.Utils.md): Utility functions, mainly getters and setters for module internals.

- [Charon.Utils.KeyGenerator](Charon.Utils.KeyGenerator.md): Derive a key from a base secret using PBKDF2.

- [Charon.Utils.PersistentTermCache](Charon.Utils.PersistentTermCache.md): Cache things using `m::persistent_term`. Be careful when using this; `m::persistent_term` is only suitable for very read-heavy storage, to the point the cached item should probably be write-once-read-often.

- Exceptions
  - [Charon.SessionPlugs.InsecureTokenTransportError](Charon.SessionPlugs.InsecureTokenTransportError.md): Error raised when token transport method "bearer" is requested by a browser client.

  - [Charon.SessionPlugs.SessionStorageError](Charon.SessionPlugs.SessionStorageError.md): Error raised when a new/updated session could not be stored.

  - [Charon.SessionPlugs.SessionUpdateConflictError](Charon.SessionPlugs.SessionUpdateConflictError.md): Error raised on an optimistic locking error when updating an existing session.