feat(websocket): add websocket authorization support

Author: alexandreteles

README.md

@@ -19,6 +19,7 @@ If you were familiar with flask-jwt-extended or fastapi-jwt-auth this extension
 - Access tokens and refresh tokens
 - Freshness Tokens
 - Revoking Tokens
+- WebSocket authorization
 - Support for adding custom claims to Tokens
 - Built-in Base64 Encoding of Tokens
 - Custom token types
@@ -47,9 +48,6 @@ def get_config():
     return {"authpaseto_secret_key": "secret"}
 ```
 
-## Roadmap
-- Support for WebSocket authorization
-
 ## 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.\

docs/api-doc.md

@@ -20,7 +20,7 @@ In here you will find the API for everything exposed in this extension.
 #
 ### Protected Endpoint
 
-**paseto_required**(optional: bool = False, fresh: bool = False, refresh_token: bool = False, type: str = access, base64_encoded: bool = False):
+**paseto_required**(optional: bool = False, fresh: bool = False, refresh_token: bool = False, type: str = access, base64_encoded: bool = False, location = None, token_key = None, token_prefix = None, token = None):
 
     If you call this function, it will ensure that the requester has a valid access token before
     executing the code below your router. Depending on set options, it might not raise an exception even if the check fails.*
@@ -29,10 +29,17 @@ In here you will find the API for everything exposed in this extension.
         **optional**: Defines whether the check should continue even if no PASETO is found.\
                       (An exception will still always be raised if an invalid one is found.)
         **fresh**: If set to True, requires any PASETO found to be a fresh access token.
-        **refresh_token**: If set to True, checks for a refresh token instead of an access token.
-        **type**: If set to a string, this gets checked against the type of the token provided. Used for custom types other than access or refresh tokens.
-        **base64_encoded**: Whether the token to check is base64 encoded.
-    * Returns: None
+        **refresh_token**: If set to True, checks for a refresh token instead of an access token.
+        **type**: If set to a string, this gets checked against the type of the token provided. Used for custom types other than access or refresh tokens.
+        **base64_encoded**: Whether the token to check is base64 encoded.
+        **location**: Override the configured token location for this endpoint. HTTP supports `headers` and `json`; websocket handlers support `headers` and `query`.
+        **token_key**: Override the configured header name, JSON key, or websocket query key for this check.
+        **token_prefix**: Override the configured transport prefix such as `Bearer`.
+        **token**: Provide a raw token directly and bypass request/websocket transport lookup.
+    * Returns: None
+
+    For websocket handlers, call **paseto_required()** before `accept()`. Auth failures close
+    the connection with websocket close code `1008` and use the auth error message as the close reason.
 
 
 

docs/configuration/general.md

@@ -25,10 +25,21 @@
 `authpaseto_decode_audience`
 :   The audience or list of audiences you expect in a PASETO when decoding it. Defaults to `None`
 
-`authpaseto_access_token_expires`
-:   How long an access token should live before it expires. This takes value `integer` *(seconds)* or
-    `datetime.timedelta`, and defaults to **15 minutes**. Can be set to `False` to disable expiration.
-
-`authpaseto_refresh_token_expires`
-:   How long an refresh token should live before it expires. This takes value `integer` *(seconds)* or
-    `datetime.timedelta`, and defaults to **30 days**. Can be set to `False` to disable expiration.
+`authpaseto_access_token_expires`
+:   How long an access token should live before it expires. This takes value `integer` *(seconds)* or
+    `datetime.timedelta`, and defaults to **15 minutes**. Can be set to `False` to disable expiration.
+
+`authpaseto_refresh_token_expires`
+:   How long an refresh token should live before it expires. This takes value `integer` *(seconds)* or
+    `datetime.timedelta`, and defaults to **30 days**. Can be set to `False` to disable expiration.
+
+`authpaseto_websocket_token_location`
+:   Where websocket handlers should look for tokens during the handshake. Valid values are
+    `headers` and `query`. Defaults to `("headers",)`.
+
+`authpaseto_websocket_query_key`
+:   The query parameter name used when websocket query transport is enabled. Defaults to `token`.
+
+`authpaseto_websocket_query_type`
+:   Optional prefix to require in the websocket query parameter, similar to `authpaseto_header_type`.
+    Defaults to `None`.

docs/usage/websocket.md

@@ -0,0 +1,61 @@
+Create a file `websocket.py`:
+
+```python hl_lines="31 42-46 50-58"
+{!../examples/websocket.py!}
+```
+
+Websocket endpoints use the same dependency injection pattern as HTTP endpoints:
+
+```python
+@app.websocket("/ws/header")
+async def websocket_header(
+    websocket: WebSocket,
+    Authorize: AuthPASETO = Depends(),
+) -> None:
+    Authorize.paseto_required()
+    await websocket.accept()
+```
+
+The important rule is to call **paseto_required()** before `accept()`. If auth fails,
+the handshake is rejected with websocket close code `1008` and the auth error message
+is used as the close reason.
+
+## Header Authorization
+
+By default, websocket authorization reads the token from the configured auth header,
+reusing `authpaseto_header_name` and `authpaseto_header_type`.
+
+```
+Authorization: Bearer <access_token>
+```
+
+## Query Authorization
+
+Browsers often cannot attach custom auth headers during the websocket handshake. For
+those clients, you can either enable websocket query transport globally:
+
+```python
+@AuthPASETO.load_config
+def get_config():
+    return {
+        "authpaseto_secret_key": "secret",
+        "authpaseto_websocket_token_location": ["query"],
+    }
+```
+
+or opt into query transport for a single route:
+
+```python
+Authorize.paseto_required(location="query")
+```
+
+The default query parameter is `token`, and you can customize it with
+`authpaseto_websocket_query_key` or per-route with `token_key`.
+
+## Parity and Limits
+
+- `optional=True`, `fresh=True`, `refresh_token=True`, custom `type`, denylist checks,
+  issuer validation, audience validation, base64 decoding, and `token=` overrides all
+  work the same way for websocket handlers.
+- JSON body token transport is not supported for websocket handshakes, because there is
+  no request body available before the connection is accepted.

examples/websocket.py

@@ -0,0 +1,64 @@
+from fastapi import Depends, FastAPI, HTTPException, Request, WebSocket
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from fastapi_paseto import AuthPASETO
+from fastapi_paseto.exceptions import AuthPASETOException
+
+app = FastAPI()
+
+
+class User(BaseModel):
+    username: str
+    password: str
+
+
+@AuthPASETO.load_config
+def get_config():
+    """Return the application auth configuration."""
+
+    return {"authpaseto_secret_key": "secret"}
+
+
+@app.exception_handler(AuthPASETOException)
+def authpaseto_exception_handler(request: Request, exc: AuthPASETOException):
+    """Return auth exceptions as JSON for HTTP endpoints."""
+
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.message})
+
+
+@app.post("/login")
+def login(user: User, Authorize: AuthPASETO = Depends()):
+    """Issue an access token for the demo user."""
+
+    if user.username != "test" or user.password != "test":
+        raise HTTPException(status_code=401, detail="Bad username or password")
+
+    access_token = Authorize.create_access_token(subject=user.username)
+    return {"access_token": access_token}
+
+
+@app.websocket("/ws/header")
+async def websocket_header(
+    websocket: WebSocket,
+    Authorize: AuthPASETO = Depends(),
+) -> None:
+    """Authorize the websocket using the configured auth header."""
+
+    Authorize.paseto_required()
+    await websocket.accept()
+    await websocket.send_json({"user": Authorize.get_subject()})
+    await websocket.close()
+
+
+@app.websocket("/ws/query")
+async def websocket_query(
+    websocket: WebSocket,
+    Authorize: AuthPASETO = Depends(),
+) -> None:
+    """Authorize the websocket using a query parameter fallback."""
+
+    Authorize.paseto_required(location="query")
+    await websocket.accept()
+    await websocket.send_json({"user": Authorize.get_subject()})
+    await websocket.close()

mkdocs.yml

@@ -31,9 +31,10 @@ markdown_extensions:
 
 nav:
   - About: index.md
-  - Usage:
-    - Basic Usage: usage/basic.md
-    - Partially Protecting: usage/optional.md
+  - Usage:
+    - Basic Usage: usage/basic.md
+    - WebSocket Usage: usage/websocket.md
+    - Partially Protecting: usage/optional.md
     - Refresh Tokens: usage/refresh.md
     - Freshness Tokens: usage/freshness.md
     - Revoking Tokens: usage/revoking.md