feat(auth): align paseto support with footer and assertion features

Author: alexandreteles

README.md

@@ -25,6 +25,7 @@ turn was inspired by `flask-jwt-extended`.
 - Support for adding custom claims to Tokens
 - Built-in Base64 Encoding of Tokens
 - Custom token types
+- PASETO footers and implicit assertions
 
 ## Installation
 

docs/advanced-usage/additional-claims.md

@@ -8,6 +8,19 @@ 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.
 
+`user_claims` is only for custom application data. Reserved top-level claims
+such as `sub`, `type`, `jti`, `exp`, `nbf`, `iat`, `iss`, `aud`, and `fresh`
+cannot be overridden there.
+
+Use the dedicated parameters instead:
+
+- `subject=` for `sub`
+- `fresh=` for access-token freshness
+- `audience=` for `aud`
+- `issuer=` for `iss`
+- `expires_time=` for `exp`
+- `create_token(type="...")` for custom token types
+
 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

docs/advanced-usage/footer-assertion.md

@@ -0,0 +1,98 @@
+FastAPI PASETO can carry optional PASETO footers and verify implicit
+assertions when you need stronger token binding than payload claims alone.
+
+```python hl_lines="10 30-36 42-44 49"
+{!../examples/footer_assertion.py!}
+```
+
+## What They Are
+
+**Footer**
+: Extra authenticated data attached to the token outside the payload.
+  A footer travels with the token and is protected by PASETO integrity checks,
+  but it is not meant for confidential application data.
+
+**Implicit assertion**
+: Extra authenticated data that does **not** travel inside the token at all.
+  The same value must be supplied again at verification time or validation
+  fails.
+
+In practice:
+
+- Put application claims you want to read later in the payload.
+- Put non-secret token metadata you want attached to the token in the footer.
+- Put request-bound context that should never be embedded in the token in the
+  implicit assertion.
+
+## Footers
+
+PASETO footers are useful for metadata such as:
+
+- `kid` values for key selection
+- routing or tenant hints
+- integration metadata that should stay outside the payload
+
+- Pass `footer=` to `create_access_token()`, `create_refresh_token()`, or
+  `create_token()` to include an optional PASETO footer.
+- After `paseto_required()` succeeds, call `get_token_footer()` to read the
+  decoded footer.
+- Footer data is authenticated by PASETO, but for `public` tokens it remains
+  visible to anyone holding the token.
+
+Example:
+
+```python
+token = Authorize.create_access_token(
+    subject="alice",
+    footer={"kid": "k4.lid.primary"},
+)
+
+Authorize.paseto_required()
+footer = Authorize.get_token_footer()
+```
+
+Use a footer when the metadata belongs to the token itself and can safely
+travel with it.
+
+## Implicit Assertions
+
+Implicit assertions are useful when the token must be bound to external context
+such as:
+
+- a tenant identifier chosen by the server
+- a channel or transport binding
+- a deployment- or service-specific contract
+
+- Pass `implicit_assertion=` when creating a token.
+- Pass the same `implicit_assertion=` value to `paseto_required()` when
+  validating it.
+- If the assertion is missing or mismatched, token validation fails.
+
+Example:
+
+```python
+token = Authorize.create_access_token(
+    subject="alice",
+    implicit_assertion="tenant-alpha",
+)
+
+Authorize.paseto_required(implicit_assertion="tenant-alpha")
+```
+
+Use an implicit assertion when the value should influence verification but
+should not be readable from the token or transported inside it.
+
+## Choosing Between Them
+
+Choose a **footer** when:
+
+- the verifier needs to read the metadata from the token itself
+- the value can safely travel with the token
+
+Choose an **implicit assertion** when:
+
+- the verifier already knows the value from surrounding context
+- the value should not be embedded into or exposed by the token
+
+Do not use either one for ordinary application claims such as user roles,
+permissions, or profile data. Those belong in the token payload.

docs/advanced-usage/validation.md

@@ -1,5 +1,6 @@
 FastAPI PASETO exposes validation controls for issuer, audience, custom token
-types, and base64-encoded tokens.
+types, base64-encoded tokens, and token-binding options such as implicit
+assertions.
 
 ```python hl_lines="18-22 35-45 49 56 63"
 {!../examples/validation.py!}
@@ -14,11 +15,16 @@ Use these options when you need stronger contracts than "any valid access token"
   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.
+- Use `implicit_assertion=` on both creation and validation when a token must
+  be bound to external request context.
 
 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`.
+- If you enable issuer validation for refresh or custom tokens, pass
+  `issuer=` when creating those tokens.
+
+For footer handling and `get_token_footer()`, see
+[Footers and Assertions](footer-assertion.md).

docs/api-doc.md

@@ -21,7 +21,7 @@ Registers the callback used to decide whether a decoded token has been revoked.
 
 ## Request Validation
 
-### `paseto_required(optional=False, fresh=False, refresh_token=False, type=None, base64_encoded=False, location=None, token_key=None, token_prefix=None, token=None)`
+### `paseto_required(optional=False, fresh=False, refresh_token=False, type=None, base64_encoded=False, location=None, token_key=None, token_prefix=None, token=None, implicit_assertion=b"")`
 
 Validates the current request or websocket connection against the supplied token
 requirements.
@@ -41,6 +41,8 @@ Parameters:
 - `token_prefix`: override the configured token prefix with another non-empty
   string for this check.
 - `token`: provide a raw token directly and bypass request or websocket lookup.
+- `implicit_assertion`: require the same implicit assertion that was used when
+  the token was created.
 
 Notes:
 
@@ -52,7 +54,7 @@ Notes:
 
 ## Token Creation
 
-### `create_access_token(subject, fresh=False, purpose=None, expires_time=None, audience=None, user_claims=None, base64_encode=False)`
+### `create_access_token(subject, fresh=False, purpose=None, expires_time=None, audience=None, issuer=None, user_claims=None, footer=None, implicit_assertion=b"", base64_encode=False)`
 
 Creates a new access token.
 
@@ -62,21 +64,25 @@ Creates a new access token.
 - `expires_time`: override the configured expiration with integer seconds,
   `datetime`, `timedelta`, or `False`.
 - `audience`: string or sequence of audience values added to `aud`.
-- `user_claims`: additional claims merged into the payload.
+- `issuer`: override the `iss` claim for this token. If omitted, access tokens
+  fall back to `authpaseto_encode_issuer`.
+- `user_claims`: additional non-reserved claims merged into the payload.
+- `footer`: optional PASETO footer as bytes, string, or dictionary.
+- `implicit_assertion`: optional implicit assertion bound to the token.
 - `base64_encode`: base64-encode the generated token string before returning it.
 
 Returns a token string.
 
-### `create_refresh_token(subject, purpose=None, expires_time=None, audience=None, user_claims=None, base64_encode=False)`
+### `create_refresh_token(subject, purpose=None, expires_time=None, audience=None, issuer=None, user_claims=None, footer=None, implicit_assertion=b"", base64_encode=False)`
 
 Creates a new refresh token.
 
 Parameters are the same as `create_access_token()`, except refresh tokens do not
-accept a `fresh` flag.
+accept a `fresh` flag and do not inherit `authpaseto_encode_issuer`.
 
 Returns a token string.
 
-### `create_token(subject, type, purpose=None, expires_time=None, audience=None, user_claims=None, base64_encode=False)`
+### `create_token(subject, type, purpose=None, expires_time=None, audience=None, issuer=None, user_claims=None, footer=None, implicit_assertion=b"", base64_encode=False)`
 
 Creates a custom token with the caller-provided `type` claim.
 
@@ -92,6 +98,11 @@ Returns a token string.
 Returns the decoded token payload for the current request or websocket
 connection, or `None` if no token has been validated successfully.
 
+### `get_token_footer()`
+
+Returns the decoded footer for the current request or websocket connection, or
+`None` if no token has been validated successfully or the token has no footer.
+
 ### `get_jti()`
 
 Returns the current token identifier from the `jti` claim, or `None` if no

docs/configuration/denylist.md

@@ -4,7 +4,8 @@
 `authpaseto_denylist_token_checks`
 :   Token types that should be checked against the denylist callback. Valid
     values are `access` and `refresh`. Pass a sequence to check both. Defaults
-    to `("access", "refresh")`.
+    to `("access", "refresh")`. Tokens whose `type` claim is not listed skip
+    the denylist callback.
 
 When denylist support is enabled, register a callback with
 `@AuthPASETO.token_in_denylist_loader`. That callback receives the decoded token

docs/configuration/general.md

@@ -39,8 +39,9 @@ defaults, and websocket transport settings used by `AuthPASETO`.
     seconds or a `datetime.timedelta`. Defaults to `0`.
 
 `authpaseto_encode_issuer`
-:   Issuer value automatically added by `create_access_token()`. Defaults to
-    `None`.
+:   Default issuer value automatically added by `create_access_token()`.
+    Refresh and custom tokens can set `iss` explicitly with `issuer=`.
+    Defaults to `None`.
 
 `authpaseto_decode_issuer`
 :   Expected `iss` claim value when decoding a token. If this is set, every

docs/examples.md

@@ -16,6 +16,7 @@ from example file to the relevant guide.
 | `examples/denylist_redis.py` | Redis-backed denylist storage | [Revoking Tokens](usage/revoking.md) |
 | `examples/additional_claims.py` | Custom claims in token payloads | [Additional claims](advanced-usage/additional-claims.md) |
 | `examples/purpose.py` | Local vs public token purpose | [Token Purpose](advanced-usage/purpose.md) |
+| `examples/footer_assertion.py` | Footers and implicit assertions | [Footers and Assertions](advanced-usage/footer-assertion.md) |
 | `examples/overrides.py` | Route-level transport overrides | [Per-route Overrides](advanced-usage/overrides.md) |
 | `examples/validation.py` | Issuer, audience, base64, and custom token types | [Validation and Custom Types](advanced-usage/validation.md) |
 | `examples/generate_doc.py` | Manual OpenAPI customization | [Generate Documentation](advanced-usage/generate-docs.md) |

docs/index.md

@@ -17,6 +17,7 @@ token-creation flow should feel familiar.
 - JSON body token transport for HTTP routes
 - Custom claims and custom token types
 - Base64-encoded token support
+- PASETO footers and implicit assertions
 
 ## Installation
 

docs/usage/revoking.md

@@ -5,6 +5,10 @@ Choose which token types should be checked with
 `token_in_denylist_loader()`. That callback receives the decoded token payload
 and should return `True` when the token has been revoked.
 
+Only the configured token types are checked. For example, if you set
+`authpaseto_denylist_token_checks=["refresh"]`, access tokens skip denylist
+lookups while refresh tokens still enforce them.
+
 This can be utilized to invalidate token in multiple cases, e.g.:
 - A user logs out and their currently active tokens need to be invalidated
 - You detect a replay attack and the leaked tokens need to be blocked