fix: rename nonce by state_token

docs/module/security.md

@@ -174,15 +174,6 @@ async def profile(user: User = Security(bearer.require(role=Role.USER))):
 The `prefix` (for `BearerTokenAuth`), cookie name and `secret_key` (for
 `CookieAuth`), and header name (for `APIKeyHeaderAuth`) are always preserved.
 
-`.require()` instances work transparently inside `MultiAuth`:
-
-```python
-multi = MultiAuth(
-    user_bearer.require(role=Role.USER),
-    org_bearer.require(role=Role.ADMIN),
-)
-```
-
 ## MultiAuth
 
 [`MultiAuth`](../reference/security.md#fastapi_toolsets.security.MultiAuth) combines multiple auth sources into a single callable. Sources are tried in order; the first one that finds a credential wins.
@@ -285,24 +276,24 @@ Returns a `(authorization_url, token_url, userinfo_url)` tuple. `userinfo_url` i
 
 ### Authorization redirect
 
-[`oauth_build_authorization_redirect()`](../reference/security.md#fastapi_toolsets.security.oauth_build_authorization_redirect) constructs the redirect to the provider's authorization page.  It requires a `nonce` — a random CSRF token generated by [`oauth_generate_nonce()`](../reference/security.md#fastapi_toolsets.security.oauth_generate_nonce) — that must be stored server-side (e.g. in the session) and verified on the callback to prevent login-CSRF attacks (RFC 6749 §10.12):
+[`oauth_build_authorization_redirect()`](../reference/security.md#fastapi_toolsets.security.oauth_build_authorization_redirect) constructs the redirect to the provider's authorization page.  It requires a `state_token` — a random CSRF token generated by [`oauth_generate_state_token()`](../reference/security.md#fastapi_toolsets.security.oauth_generate_state_token) — that must be stored server-side (e.g. in the session) and verified on the callback to prevent login-CSRF attacks ([RFC 6749 §10.12](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12)):
 
 ```python
 from fastapi import Request
-from fastapi_toolsets.security import oauth_build_authorization_redirect, oauth_generate_nonce
+from fastapi_toolsets.security import oauth_build_authorization_redirect, oauth_generate_state_token
 
 @app.get("/auth/google/login")
 async def google_login(request: Request):
     auth_url, _, _ = await oauth_resolve_provider_urls(GOOGLE_DISCOVERY_URL)
-    nonce = oauth_generate_nonce()
-    request.session["oauth_nonce"] = nonce  # requires SessionMiddleware
+    state_token = oauth_generate_state_token()
+    request.session["oauth_state"] = state_token  # requires SessionMiddleware
     return oauth_build_authorization_redirect(
         auth_url,
         client_id=GOOGLE_CLIENT_ID,
         scopes="openid email profile",
         redirect_uri="https://myapp.com/auth/google/callback",
         destination="/dashboard",
-        nonce=nonce,
+        state_token=state_token,
     )
 ```
 
@@ -310,7 +301,7 @@ async def google_login(request: Request):
 
 [`oauth_fetch_userinfo()`](../reference/security.md#fastapi_toolsets.security.oauth_fetch_userinfo) performs the two-step exchange: it POSTs the authorization code to the token endpoint, then GETs the userinfo endpoint with the resulting access token.
 
-On the callback, retrieve the stored nonce and pass it to [`oauth_decode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_decode_state) to verify the CSRF token before processing the code:
+On the callback, retrieve the stored token and pass it to [`oauth_decode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_decode_state) to verify the CSRF token before processing the code:
 
 ```python
 from fastapi import HTTPException, Request
@@ -318,11 +309,11 @@ from fastapi_toolsets.security import oauth_decode_state, oauth_fetch_userinfo
 
 @app.get("/auth/google/callback")
 async def google_callback(request: Request, code: str, state: str):
-    # Pop nonce first — single-use, regardless of whether verification succeeds
-    nonce = request.session.pop("oauth_nonce", None)
-    if nonce is None:
+    # Pop token first — single-use, regardless of whether verification succeeds
+    state_token = request.session.pop("oauth_state", None)
+    if state_token is None:
         raise HTTPException(status_code=400, detail="missing OAuth state")
-    destination = oauth_decode_state(state, expected_nonce=nonce, fallback="/")
+    destination = oauth_decode_state(state, expected_state_token=state_token, fallback="/")
     if not destination.startswith("/"):  # reject absolute URLs to prevent open-redirect
         destination = "/"
 
@@ -346,16 +337,16 @@ Pass `required_scopes` to guard against providers silently granting fewer scopes
 
 ### State encoding
 
-[`oauth_encode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_encode_state) and [`oauth_decode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_decode_state) encode and decode the destination URL together with the CSRF nonce embedded in the OAuth `state` parameter.  `oauth_decode_state` returns `fallback` if `state` is absent, malformed, or the nonce does not match:
+[`oauth_encode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_encode_state) and [`oauth_decode_state()`](../reference/security.md#fastapi_toolsets.security.oauth_decode_state) encode and decode the destination URL together with the CSRF token embedded in the OAuth `state` parameter.  `oauth_decode_state` returns `fallback` if `state` is absent, malformed, or the token does not match:
 
 ```python
 from fastapi_toolsets.security import oauth_encode_state, oauth_decode_state
 
-nonce = "my-random-nonce"
-encoded = oauth_encode_state("/dashboard", nonce)
-decoded = oauth_decode_state(encoded, expected_nonce=nonce, fallback="/")  # "/dashboard"
-decoded = oauth_decode_state(encoded, expected_nonce="wrong", fallback="/")  # "/"
-decoded = oauth_decode_state(None, expected_nonce=nonce, fallback="/")       # "/"
+state_token = oauth_generate_state_token()
+encoded = oauth_encode_state("/dashboard", state_token)
+decoded = oauth_decode_state(encoded, expected_state_token=state_token, fallback="/")  # "/dashboard"
+decoded = oauth_decode_state(encoded, expected_state_token="wrong", fallback="/")  # "/"
+decoded = oauth_decode_state(None, expected_state_token=state_token, fallback="/")       # "/"
 ```
 
 ---

docs/reference/security.md

@@ -15,7 +15,7 @@ from fastapi_toolsets.security import (
     oauth_decode_state,
     oauth_encode_state,
     oauth_fetch_userinfo,
-    oauth_generate_nonce,
+    oauth_generate_state_token,
     oauth_resolve_provider_urls,
 )
 ```
@@ -34,7 +34,7 @@ from fastapi_toolsets.security import (
 
 ## ::: fastapi_toolsets.security.oauth_fetch_userinfo
 
-## ::: fastapi_toolsets.security.oauth_generate_nonce
+## ::: fastapi_toolsets.security.oauth_generate_state_token
 
 ## ::: fastapi_toolsets.security.oauth_build_authorization_redirect