docs(docs): align documentation with current implementation

Author: alexandreteles

README.md

@@ -10,10 +10,12 @@
 
 ---
 
-FastAPI extension that provides PASETO (**P**lastform-**A**gnostic **SE**curity **TO**kens) Auth support\
-PASETO are a simpler, yet more secure alternative to JWTs.
+FastAPI extension that provides PASETO (**P**latform-**A**gnostic **SE**curity **TO**kens) Auth support.
+PASETO tokens are a simpler, yet more secure alternative to JWTs.
 
-If you were familiar with flask-jwt-extended or fastapi-jwt-auth this extension suitable for you, as this is forked from fastapi-jwt-auth which in turn used flask-jwt-extended as motivation
+If you are familiar with `flask-jwt-extended` or `fastapi-jwt-auth`, this
+extension should feel familiar. It is forked from `fastapi-jwt-auth`, which in
+turn was inspired by `flask-jwt-extended`.
 
 ## Features
 - Access tokens and refresh tokens
@@ -25,12 +27,18 @@ If you were familiar with flask-jwt-extended or fastapi-jwt-auth this extension
 - Custom token types
 
 ## Installation
-The easiest way to start working with this extension with pip
+
+This project is not published on PyPI. Install it from an immutable Git tag or
+commit hash instead.
 
 This project currently targets Python 3.14+.
 
 ```bash
-pip install fastapi-paseto
+uv add "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@vX.Y.Z"
+```
+
+```bash
+pip install "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@vX.Y.Z"
 ```
 
 Releases are built from GitHub Actions after a successful semantic release on
@@ -48,12 +56,6 @@ def get_config():
     return {"authpaseto_secret_key": "secret"}
 ```
 
-## FAQ
-- **Where's support for tokens in cookies?**\
-This project focuses on header-based PASETO authentication and only includes the features required for that workflow.\
-Cookie storage is intentionally out of scope for now because it adds a large amount of behavior that does not fit the current design.\
-If there is strong demand and a solid implementation, contributions adding cookie support can still be considered.
-
 ## Release Process
 Releases are automated with conventional commits and semantic versioning.
 Commits merged into `main` should follow the Conventional Commits format, for
@@ -82,11 +84,14 @@ gh attestation verify ./fastapi_paseto-X.Y.Z-py3-none-any.whl --repo Raze-System
 gh attestation verify ./fastapi_paseto-X.Y.Z-py3-none-any.whl --repo Raze-Systems/fastapi-paseto --signer-workflow .github/workflows/release.yml --predicate-type https://spdx.dev/Document/v2.3
 ```
 
-If you install directly from Git, pin an immutable tag or commit hash instead
-of `main`:
+If you prefer to install from a commit hash instead of a release tag:
 
 ```bash
-pip install "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@vX.Y.Z"
+uv add "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@<commit-sha>"
+```
+
+```bash
+pip install "fastapi-paseto @ git+https://github.com/Raze-Systems/fastapi-paseto.git@<commit-sha>"
 ```
 
 `pip` and `uv` record VCS origin metadata in `direct_url.json`, which helps

docs/advanced-usage/additional-claims.md

@@ -1,15 +1,19 @@
-You may want to store additional information in the access token or refresh token that you can later access in the protected views.
+You can store additional information in access, refresh, or custom tokens and
+read it later from protected endpoints.
+
+Pass a dictionary through the `user_claims` parameter of
+`create_access_token()`, `create_refresh_token()`, or `create_token()`, then
+read it back with `get_token_payload()`.
+
+Storing data in tokens can reduce repeated database lookups, but you still need
+to choose those claims carefully.
+
+When using the `public` purpose, the token payload is signed but not encrypted.
+Anyone with the token can read its contents, so do not store sensitive
+information there. Whether `local` tokens are appropriate for sensitive data is
+still your own security decision.
 
-This can be done easily by passion additional information as a dictionary to the parameter **user_claims** in the functions **create_access_token()** or **create_refresh_token()**, and the data can be accessed later in a protected endpoint with the **get_token_payload()** function.
 
-Storing data in the tokens can be good for performance.\
-If you store data in the tokens, you won't need to look it up from disk/DB next time you need it in a protected endpoint.\
-However, you might need to take care of what data you put in the tokens.
-
-**Note**: When using the "public" purpose of PASETO tokens, the data in the token will merely be signed, but not encrypted. This means anyone with access to the token can freely read it's contents.\
-Hence, do not store sensitive information in public tokens. Whether you trust local (encrypted) PASETO tokens to keep sensitive information is up to your own discretion.
-
-
-```python hl_lines="34-35 44"
-{!../examples/additional_claims.py!}
-```
+```python hl_lines="34-35 44"
+{!../examples/additional_claims.py!}
+```

docs/advanced-usage/bigger-app.md

@@ -1,6 +1,9 @@
-Because *fastapi-paseto* configures your setting via a class state that applies across all instances of the class, you only need to make sure to call **load_config**(callback) before declaring any endpoint. Thanks to `FastAPI` when you make an endpoint from `APIRouter` it will actually work as if everything was the same single app.
-
-So you only need to define **load_config**(callback) where your `FastAPI` instance is created or you can import it where you include all the routers. 
+Because *fastapi-paseto* stores configuration on class state shared by all
+`AuthPASETO` instances, you only need to call `load_config()` once before your
+routes start handling requests.
+
+In a larger FastAPI application, that usually means loading the config in the
+module that creates the main `FastAPI` app and then importing routers normally.
 
 ## An example file structure
 
@@ -17,19 +20,19 @@ Let's say you have a file structure like this:
 │       └── users.py
 ```
 
-Here an example of `app.py`
+Here is an example of `app.py`:
 
 ```python
 {!../examples/multiple_files/app.py!}
 ```
 
-Here an example of `users.py`
+Here is an example of `users.py`:
 
 ```python
 {!../examples/multiple_files/routers/users.py!}
 ```
 
-Here an example of `items.py`
+Here is an example of `items.py`:
 
 ```python
 {!../examples/multiple_files/routers/items.py!}

docs/advanced-usage/expiry_time.md

@@ -1,4 +1,10 @@
-You can also change the expiry time for a token via parameter **expires_time** in the **create_access_token()** or **create_refresh_token()** function. This takes a *datetime.timedelta*, *datetime.datetime*, *integer*, or even *boolean* and overrides the `authpaseto_access_token_expires` and `authpaseto_refresh_token_expires` settings. This can be useful if you have different use cases for different tokens.
+You can override the default token lifetime with the `expires_time` parameter on
+`create_access_token()`, `create_refresh_token()`, or `create_token()`.
+
+`expires_time` accepts a `datetime.timedelta`, `datetime.datetime`, integer
+seconds, or `False`. That override takes precedence over the configured
+`authpaseto_access_token_expires`, `authpaseto_refresh_token_expires`, or
+`authpaseto_other_token_expires` defaults.
 
 ```python
 @app.post('/create-dynamic-token')
@@ -8,7 +14,7 @@ def create_dynamic_token(Authorize: AuthPASETO = Depends()):
     return {"token": token}
 ```
 
-You can even disable expiration by setting **expires_time** to *False*:
+You can disable expiration by setting `expires_time=False`:
 
 ```python
 @app.post('/create-token-disable')

docs/advanced-usage/generate-docs.md

@@ -1,7 +1,10 @@
-It feels incomplete if there is no documentation because *fastapi-paseto* uses starlette requests directly to get headers, you must manually generate the documentation. Thanks to `FastAPI` you can generate doc easily via `Extending OpenAPI`.
+Because *fastapi-paseto* reads request data directly from Starlette request and
+websocket objects, FastAPI will not automatically describe those auth inputs in
+OpenAPI for you. If you want the generated docs to show the header or body
+contract, extend the OpenAPI schema manually.
+
+Here is an example:
 
-Here is an example to generate the doc:
-
-```python hl_lines="37 57-65 69 71-78"
-{!../examples/generate_doc.py!}
-```
+```python hl_lines="37 57-65 69 71-78"
+{!../examples/generate_doc.py!}
+```

docs/advanced-usage/overrides.md

@@ -0,0 +1,24 @@
+`paseto_required()` can override the configured token transport on a single
+route. This is useful when most of your application follows one convention, but
+one endpoint needs a different header name, body key, prefix, or a token that
+was already extracted by another dependency.
+
+The route-level override arguments are:
+
+- `location`
+- `token_key`
+- `token_prefix`
+- `token`
+
+```python hl_lines="37 44-48 55-60"
+{!../examples/overrides.py!}
+```
+
+Notes:
+
+- `location="json"` is only valid for HTTP requests.
+- `location="query"` is only valid for websocket handlers.
+- `token=` bypasses header, JSON, and query lookup entirely.
+- `token_prefix` can override the configured prefix with another non-empty
+  string. If you need to disable the prefix completely, set the transport type
+  to `None` in configuration.

docs/advanced-usage/purpose.md

@@ -1,15 +1,20 @@
-You can specify which purpose you would like to use for a PASETO by using the **purpose** parameter in **create_access_token()** or **create_refresh_token()**.
+You can choose the PASETO purpose used to create a token through the `purpose`
+parameter of `create_access_token()`, `create_refresh_token()`, or
+`create_token()`.
 
 Please read up on PASETO tokens to find out which is the best purpose for your use case, but to put it short:
 
-**Local** purpose means the token will be encrypted using symmetric encryption. Data in the token will not be accessible to people that get the token without also knowing your secret key.\
-This is useful if the token is used in an environment where every party that needs access to the token's contents is a secure environment under your control that you can share the secret key with.
+**Local** means the token is encrypted with symmetric cryptography. Someone who
+obtains the token cannot read its contents without the shared secret key.
+This is a good fit when every party that needs to decrypt the token is under
+your control.
+
+**Public** means the token is signed with your private key but not encrypted.
+The payload remains visible to anyone holding the token, so you should not put
+confidential data into public tokens. Public tokens can be verified with the
+matching public key, which is safe to share with untrusted parties.
 
-**Public** purpose means the token will not be encrypted, and instead will only be signed using your private key.
-The data in the key **will be visible to everyone that gets ahold of the key**, and you should not put any confidential or sensitive data into public keys.
-The key can then be validated using your public key, which is safe to share with not-trusted parties.
 
-
-```python hl_lines="16 35-36"
-{!../examples/purpose.py!}
-```
+```python hl_lines="16 35-36"
+{!../examples/purpose.py!}
+```

docs/advanced-usage/validation.md

@@ -0,0 +1,24 @@
+FastAPI PASETO exposes validation controls for issuer, audience, custom token
+types, and base64-encoded tokens.
+
+```python hl_lines="18-22 35-45 49 56 63"
+{!../examples/validation.py!}
+```
+
+Use these options when you need stronger contracts than "any valid access token":
+
+- Set `authpaseto_decode_issuer` to require an `iss` claim with a specific value.
+- Pass `audience=` when creating a token and set `authpaseto_decode_audience` to
+  enforce the expected audience on decode.
+- Use `create_token(type="...")` together with `paseto_required(type="...")`
+  for custom token flows such as email verification.
+- Use `base64_encode=True` when creating a token and
+  `paseto_required(base64_encoded=True)` when validating it.
+
+Important issuer detail:
+
+- `authpaseto_encode_issuer` automatically adds `iss` only to
+  `create_access_token()`.
+- `authpaseto_decode_issuer` applies to every decoded token.
+- If you enable issuer validation for refresh or custom tokens, those tokens
+  must still include `iss`, typically through `user_claims`.