fastapi-csp-docs 0.1.0__py3-none-any.whl

fastapi_csp_docs/__init__.py

@@ -0,0 +1,21 @@
+from fastapi_csp_docs.docs import (
+    get_redoc_css,
+    get_redoc_html,
+    get_swagger_ui_html,
+    get_swagger_ui_init_js,
+    get_swagger_ui_oauth2_redirect_html,
+    get_swagger_ui_oauth2_redirect_js,
+)
+from fastapi_csp_docs.setup import setup
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "get_redoc_css",
+    "get_redoc_html",
+    "get_swagger_ui_html",
+    "get_swagger_ui_init_js",
+    "get_swagger_ui_oauth2_redirect_html",
+    "get_swagger_ui_oauth2_redirect_js",
+    "setup",
+]

fastapi_csp_docs/docs.py

@@ -0,0 +1,252 @@
+import json
+
+from typing import Any
+
+from fastapi.encoders import jsonable_encoder
+from fastapi.openapi.docs import swagger_ui_default_parameters
+from starlette.responses import HTMLResponse, Response
+
+
+def _html_safe_json(value: Any) -> str:
+    """Serialize a value to JSON with HTML special characters escaped.
+
+    This prevents injection when the JSON is embedded inside a <script> tag.
+    """
+    return json.dumps(value).replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026")
+
+
+def get_swagger_ui_init_js(
+    *,
+    openapi_url: str,
+    oauth2_redirect_url: str | None = None,
+    init_oauth: dict[str, Any] | None = None,
+    swagger_ui_parameters: dict[str, Any] | None = None,
+) -> Response:
+    """
+    Generate and return the response that initializes Swagger UI.
+
+    This is normally served as `swagger-initializer.js`, referenced from the
+    HTML generated by [get_swagger_ui_html][fastapi_csp_docs.docs.get_swagger_ui_html].
+
+    You would only call this function yourself if you needed to override some parts,
+    for example to serve the initializer script from your own endpoint.
+
+    :param openapi_url: URL of the OpenAPI schema for Swagger UI to render.
+    :param oauth2_redirect_url: URL of the OAuth2 redirect endpoint, or None to disable
+        OAuth2 login in the UI.
+    :param init_oauth: OAuth2 configuration passed to `ui.initOAuth()`, or None to skip it.
+    :param swagger_ui_parameters: extra Swagger UI parameters merged over FastAPI's defaults.
+    """
+    current_swagger_ui_parameters = swagger_ui_default_parameters.copy()
+    if swagger_ui_parameters:
+        current_swagger_ui_parameters.update(swagger_ui_parameters)
+
+    js = f"""
+    window.onload = function() {{
+    const ui = SwaggerUIBundle({{
+        url: '{openapi_url}',
+    """
+
+    for key, value in current_swagger_ui_parameters.items():
+        js += f"{_html_safe_json(key)}: {_html_safe_json(jsonable_encoder(value))},\n"
+
+    if oauth2_redirect_url:
+        js += f"oauth2RedirectUrl: window.location.origin + '{oauth2_redirect_url}',"
+
+    js += """
+    presets: [
+        SwaggerUIBundle.presets.apis,
+        SwaggerUIBundle.SwaggerUIStandalonePreset
+        ],
+    })"""
+
+    if init_oauth:
+        js += f"""
+        ui.initOAuth({_html_safe_json(jsonable_encoder(init_oauth))})
+        """
+
+    js += """
+    window.ui = ui;
+    };
+    """
+    return Response(content=js, media_type="text/javascript")
+
+
+def get_swagger_ui_html(
+    *,
+    title: str,
+    swagger_js_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
+    swagger_css_url: str = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
+    swagger_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+    swagger_ui_init_script_url: str = "/docs/swagger-initializer.js",
+) -> HTMLResponse:
+    """
+    Generate and return the HTML that loads Swagger UI for the interactive
+    API docs (normally served at `/docs`).
+
+    You would only call this function yourself if you needed to override some parts,
+    for example the URLs to use to load Swagger UI's JavaScript and CSS.
+
+    Read more about it in the
+    [FastAPI docs for Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/).
+
+    :param title: HTML page title.
+    :param swagger_js_url: URL of the Swagger UI JavaScript bundle.
+    :param swagger_css_url: URL of the Swagger UI CSS.
+    :param swagger_favicon_url: URL of the favicon.
+    :param swagger_ui_init_script_url: URL of the script that initializes Swagger UI, see
+        [get_swagger_ui_init_js][fastapi_csp_docs.docs.get_swagger_ui_init_js].
+    """
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+    <meta charset="UTF-8">
+    <title>{title}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link type="text/css" rel="stylesheet" href="{swagger_css_url}">
+    <link rel="shortcut icon" href="{swagger_favicon_url}">
+    </head>
+    <body>
+    <div id="swagger-ui"></div>
+    <script src="{swagger_js_url}" charset="UTF-8"></script>
+    <!-- `SwaggerUIBundle` is now available on the page -->
+    <script src="{swagger_ui_init_script_url}" charset="UTF-8"></script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(html)
+
+
+def get_redoc_html(
+    *,
+    openapi_url: str,
+    title: str,
+    redoc_js_url: str = "https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js",
+    redoc_favicon_url: str = "https://fastapi.tiangolo.com/img/favicon.png",
+    with_google_fonts: bool = True,
+    redoc_css_url: str = "/redoc/redoc.css",
+    google_fonts_css_url: str = "https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700",
+    disable_search: bool = False,
+) -> HTMLResponse:
+    """
+    Generate and return the HTML response that loads ReDoc for the alternative
+    API docs (normally served at `/redoc`).
+
+    You would only call this function yourself if you needed to override some parts,
+    for example the URLs to use to load ReDoc's JavaScript and CSS.
+
+    :param openapi_url: URL of the OpenAPI schema for ReDoc to render.
+    :param title: HTML page title.
+    :param redoc_js_url: URL of the ReDoc JavaScript bundle.
+    :param redoc_favicon_url: URL of the favicon.
+    :param with_google_fonts: whether to load the Montserrat/Roboto fonts from Google Fonts.
+    :param redoc_css_url: URL of the CSS reset required by ReDoc, see
+        [get_redoc_css][fastapi_csp_docs.docs.get_redoc_css].
+    :param google_fonts_css_url: URL of the Google Fonts stylesheet, used only when
+        `with_google_fonts` is True.
+    :param disable_search: whether to disable ReDoc's client-side search box (and the Web
+        Worker it runs in) — see the README section on `worker-src`.
+    """
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+    <title>{title}</title>
+    <!-- needed for adaptive design -->
+    <meta charset="utf-8"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    """
+    if with_google_fonts:
+        html += f"""
+    <link href="{google_fonts_css_url}" rel="stylesheet">
+    """
+    html += f"""
+    <link rel="shortcut icon" href="{redoc_favicon_url}">
+    <link rel="stylesheet" type="text/css" href="{redoc_css_url}">
+    <!--
+    ReDoc doesn't change outer page styles
+    -->
+    </head>
+    <body>
+    <noscript>
+        ReDoc requires Javascript to function. Please enable it to browse the documentation.
+    </noscript>
+    <redoc spec-url="{openapi_url}"{' disable-search="true"' if disable_search else ""}></redoc>
+    <script src="{redoc_js_url}"> </script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(html)
+
+
+def get_redoc_css() -> Response:
+    """
+    Generate and return the response with the CSS reset required by ReDoc.
+
+    This is normally served as `redoc.css`, referenced from the HTML
+    generated by [get_redoc_html][fastapi_csp_docs.docs.get_redoc_html].
+
+    You normally don't need to use or change this.
+    """
+    return Response(content="body{margin:0;padding:0;}", media_type="text/css")
+
+
+def get_swagger_ui_oauth2_redirect_html(
+    *,
+    oauth2_redirect_script_url: str = "oauth2-redirect.js",
+) -> HTMLResponse:
+    """
+    Generate the HTML response with the OAuth2 redirection for Swagger UI.
+
+    You would only call this function yourself if you needed to override some parts,
+    for example the URL of the OAuth2 redirect script.
+
+    :param oauth2_redirect_script_url: URL of the OAuth2 redirect script, see
+        [get_swagger_ui_oauth2_redirect_js][fastapi_csp_docs.docs.get_swagger_ui_oauth2_redirect_js].
+    """
+    html = f"""
+    <!doctype html>
+    <html lang="en-US">
+    <head>
+        <title>Swagger UI: OAuth2 Redirect</title>
+    </head>
+    <body>
+    <script src="{oauth2_redirect_script_url}"></script>
+    </body>
+    </html>
+    """
+    return HTMLResponse(content=html)
+
+
+def get_swagger_ui_oauth2_redirect_js() -> Response:
+    """
+    Generate and return the response with the OAuth2 redirection logic for
+    Swagger UI.
+
+    This is normally served as `oauth2-redirect.js`, referenced from the HTML
+    generated by
+    [get_swagger_ui_oauth2_redirect_html][fastapi_csp_docs.docs.get_swagger_ui_oauth2_redirect_html].
+
+    You normally don't need to use or change this.
+    """
+    # minified, copied from https://github.com/swagger-api/swagger-ui/blob/v5.32.8/dist/oauth2-redirect.js
+    js = (
+        '"use strict";function run(){var e,r,t,a=window.opener.swaggerUIRedirectOauth2,'
+        "o=a.state,n=a.redirectUrl;if((t=(r=/code|token|error/.test(window.location.hash)?"
+        'window.location.hash.substring(1).replace("?","&"):location.search.substring(1))'
+        '.split("&")).forEach((function(e,r,t){t[r]=\'"\'+e.replace("=",\'":"\')+\'"\'})),'
+        'e=(r=r?JSON.parse("{"+t.join()+"}",(function(e,r){return""===e?r:decodeURIComponent(r)}))'
+        ':{}).state===o,"accessCode"!==a.auth.schema.get("flow")&&"authorizationCode"!=='
+        'a.auth.schema.get("flow")&&"authorization_code"!==a.auth.schema.get("flow")||a.auth.code)'
+        "a.callback({auth:a.auth,token:r,isValid:e,redirectUrl:n});else if(e||a.errCb({authId:"
+        'a.auth.name,source:"auth",level:"warning",message:"Authorization may be unsafe, passed '
+        "state was changed in server Passed state wasn't returned from auth server\"}),r.code)"
+        "delete a.state,a.auth.code=r.code,a.callback({auth:a.auth,redirectUrl:n});else{let e;"
+        'r.error&&(e="["+r.error+"]: "+(r.error_description?r.error_description+". ":"no accessCode '
+        'received from the server. ")+(r.error_uri?"More info: "+r.error_uri:"")),a.errCb({authId:'
+        'a.auth.name,source:"auth",level:"error",message:e||"[Authorization failed]: no accessCode '
+        'received from the server"})}window.close()}"loading"!==document.readyState?run():'
+        'document.addEventListener("DOMContentLoaded",(function(){run()}));'
+    )
+    return Response(content=js, media_type="text/javascript")

fastapi_csp_docs/setup.py

@@ -0,0 +1,145 @@
+from fastapi import FastAPI
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, Response
+
+from fastapi_csp_docs.docs import (
+    get_redoc_css,
+    get_redoc_html,
+    get_swagger_ui_html,
+    get_swagger_ui_init_js,
+    get_swagger_ui_oauth2_redirect_html,
+    get_swagger_ui_oauth2_redirect_js,
+)
+
+
+def setup(
+    app: FastAPI,
+    *,
+    docs_url: str | None = "/docs",
+    redoc_url: str | None = "/redoc",
+) -> None:
+    """
+    Wire CSP-safe Swagger UI and ReDoc routes onto a FastAPI app.
+
+    Registers replacement routes for the interactive API docs (Swagger UI) and the
+    alternative API docs (ReDoc) that load their JavaScript/CSS from dedicated endpoints
+    instead of FastAPI's inline `<script>`/`<style>` tags, so a Content-Security-Policy
+    without `'unsafe-inline'` can be enforced.
+
+    The app must already be created with `docs_url=None`/`redoc_url=None`, e.g.
+    `FastAPI(docs_url=None, redoc_url=None)` — otherwise FastAPI's own built-in docs
+    would shadow the routes registered here.
+
+    Read more about it in the
+    [README](https://github.com/mat81black/fastapi-csp-docs#readme).
+
+    :param app: the FastAPI app to wire the docs routes onto.
+    :param docs_url: path to serve Swagger UI at, or None to skip it.
+    :param redoc_url: path to serve ReDoc at, or None to skip it.
+    :raises RuntimeError: if `app.docs_url` or `app.redoc_url` is still set.
+    """
+    if docs_url:
+        if app.docs_url:
+            raise RuntimeError(
+                f"fastapi_csp_docs.setup() cannot mount Swagger UI at {docs_url!r} because "
+                f"the app still serves its built-in docs at {app.docs_url!r}. Create the "
+                "FastAPI app with docs_url=None to disable it first, e.g. FastAPI(docs_url=None)."
+            )
+        if app.openapi_url:
+            _setup_swagger_ui(app, docs_url)
+    if redoc_url:
+        if app.redoc_url:
+            raise RuntimeError(
+                f"fastapi_csp_docs.setup() cannot mount ReDoc at {redoc_url!r} because "
+                f"the app still serves its built-in docs at {app.redoc_url!r}. Create the "
+                "FastAPI app with redoc_url=None to disable it first, e.g. FastAPI(redoc_url=None)."
+            )
+        if app.openapi_url:
+            _setup_redoc(app, redoc_url)
+
+
+def _setup_swagger_ui(app: FastAPI, docs_url: str) -> None:
+    swagger_ui_init_script_url = f"{docs_url.rstrip('/')}/swagger-initializer.js"
+
+    async def swagger_ui_init_script(req: Request) -> Response:
+        root_path = req.scope.get("root_path", "").rstrip("/")
+        openapi_url = root_path + app.openapi_url
+        oauth2_redirect_url = app.swagger_ui_oauth2_redirect_url
+        if oauth2_redirect_url:
+            oauth2_redirect_url = root_path + oauth2_redirect_url
+        return get_swagger_ui_init_js(
+            openapi_url=openapi_url,
+            oauth2_redirect_url=oauth2_redirect_url,
+            init_oauth=app.swagger_ui_init_oauth,
+            swagger_ui_parameters=app.swagger_ui_parameters,
+        )
+
+    app.add_route(
+        swagger_ui_init_script_url,
+        swagger_ui_init_script,
+        include_in_schema=False,
+    )
+
+    async def swagger_ui_html(req: Request) -> HTMLResponse:
+        root_path = req.scope.get("root_path", "").rstrip("/")
+        init_script_url = root_path + swagger_ui_init_script_url
+        return get_swagger_ui_html(
+            title=f"{app.title} - Swagger UI",
+            swagger_ui_init_script_url=init_script_url,
+        )
+
+    app.add_route(docs_url, swagger_ui_html, include_in_schema=False)
+
+    if app.swagger_ui_oauth2_redirect_url:
+        _setup_swagger_ui_oauth2_redirect(app, app.swagger_ui_oauth2_redirect_url)
+
+
+def _setup_swagger_ui_oauth2_redirect(app: FastAPI, oauth2_redirect_url: str) -> None:
+    oauth2_redirect_script_url = f"{oauth2_redirect_url.rstrip('/')}.js"
+
+    oauth2_redirect_js_response = get_swagger_ui_oauth2_redirect_js()
+
+    async def oauth2_redirect_script(req: Request) -> Response:
+        return oauth2_redirect_js_response
+
+    app.add_route(
+        oauth2_redirect_script_url,
+        oauth2_redirect_script,
+        include_in_schema=False,
+    )
+
+    async def swagger_ui_redirect(req: Request) -> HTMLResponse:
+        root_path = req.scope.get("root_path", "").rstrip("/")
+        redirect_script_url = root_path + oauth2_redirect_script_url
+        return get_swagger_ui_oauth2_redirect_html(
+            oauth2_redirect_script_url=redirect_script_url,
+        )
+
+    app.add_route(
+        oauth2_redirect_url,
+        swagger_ui_redirect,
+        include_in_schema=False,
+    )
+
+
+def _setup_redoc(app: FastAPI, redoc_url: str) -> None:
+    redoc_css_url = f"{redoc_url.rstrip('/')}/redoc.css"
+
+    redoc_css_response = get_redoc_css()
+
+    async def redoc_css(req: Request) -> Response:
+        return redoc_css_response
+
+    app.add_route(redoc_css_url, redoc_css, include_in_schema=False)
+
+    async def redoc_html(req: Request) -> HTMLResponse:
+        root_path = req.scope.get("root_path", "").rstrip("/")
+        openapi_url = root_path + app.openapi_url
+        css_url = root_path + redoc_css_url
+        return get_redoc_html(
+            openapi_url=openapi_url,
+            title=f"{app.title} - ReDoc",
+            redoc_css_url=css_url,
+        )
+
+    app.add_route(redoc_url, redoc_html, include_in_schema=False)

fastapi_csp_docs-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: fastapi-csp-docs
+Version: 0.1.0
+Summary: CSP-safe replacements for FastAPI's built-in /docs, /redoc, and OAuth2 redirect endpoints, with no inline script or style
+Project-URL: Homepage, https://github.com/mat81black/fastapi-csp-docs
+Project-URL: Repository, https://github.com/mat81black/fastapi-csp-docs
+Project-URL: Issues, https://github.com/mat81black/fastapi-csp-docs/issues
+Project-URL: Documentation, https://github.com/mat81black/fastapi-csp-docs#readme
+Project-URL: Changelog, https://github.com/mat81black/fastapi-csp-docs/blob/main/RELEASE_NOTES.md
+Author-email: Matteo Nieddu <mat81black@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.120.0
+Description-Content-Type: text/markdown
+
+# FastAPI CSP Docs
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-csp-docs.svg)](https://pypi.org/project/fastapi-csp-docs/)
+[![Test](https://github.com/mat81black/fastapi-csp-docs/actions/workflows/test.yml/badge.svg)](https://github.com/mat81black/fastapi-csp-docs/actions/workflows/test.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-csp-docs.svg)](https://pypi.org/project/fastapi-csp-docs/)
+[![License: MIT](https://img.shields.io/pypi/l/fastapi-csp-docs.svg)](https://github.com/mat81black/fastapi-csp-docs/blob/main/LICENSE)
+
+FastAPI's built-in `/docs`, `/redoc`, and OAuth2 redirect pages embed inline `<script>`/`<style>`
+tags, so they break under a Content-Security-Policy without `'unsafe-inline'`. Following FastAPI's
+own ["Custom Docs UI Static Assets"](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
+recipe only swaps the CDN URLs for local ones — it doesn't remove any inline content:
+`get_swagger_ui_html()` still embeds the Swagger UI bootstrap script inline, `get_redoc_html()`
+still embeds a `<style>` reset inline, and `get_swagger_ui_oauth2_redirect_html()` still embeds
+the OAuth2 redirect logic inline. `fastapi-csp-docs` replaces all three pages with versions that
+load every script and stylesheet from a separate endpoint, with no inline content anywhere.
+
+## Features
+
+- **Drop-in `setup()`**: one call replaces FastAPI's built-in `/docs`, `/redoc`, and OAuth2
+  redirect wiring — no inline script or style left anywhere.
+- **Fails fast on misconfiguration**: raises `RuntimeError` if the app's built-in docs aren't
+  disabled first, instead of silently letting them shadow the CSP-safe routes.
+- **CDN or fully self-hosted**: works with the default jsdelivr CDN
+  (`script-src 'self' <cdn-host>`) or entirely offline with your own static assets
+  (`script-src 'self'`, zero external origins).
+- **Reverse-proxy / sub-app aware**: doc URLs include the ASGI `root_path` computed per request,
+  so mounting under a prefix (`app.mount("/api", sub_app)`) works out of the box.
+- **Independently configurable mount paths**: `docs_url`/`redoc_url` are explicit `setup()`
+  parameters, each can be disabled on its own by passing `None`.
+- **Content generators exported for manual wiring**: the same building blocks `setup()` uses
+  internally are public, for a fully self-hosted setup with no CDN at all.
+
+## Requirements
+
+- Python >= 3.10
+- FastAPI >= 0.120.0
+
+## Installation
+
+```bash
+pip install fastapi-csp-docs
+# or
+uv add fastapi-csp-docs
+```
+
+## Quick start
+
+### Assisted mode (CDN-hosted Swagger UI / ReDoc)
+
+```python
+from fastapi import FastAPI, Request
+from starlette.responses import Response
+
+import fastapi_csp_docs
+
+app = FastAPI(docs_url=None, redoc_url=None)
+
+
+@app.middleware("http")
+async def add_csp_header(request: Request, call_next) -> Response:
+    response = await call_next(request)
+    response.headers["Content-Security-Policy"] = (
+        "default-src 'self'; "
+        "script-src 'self' https://cdn.jsdelivr.net; "
+        "style-src 'self' https://cdn.jsdelivr.net"
+    )
+    return response
+
+
+fastapi_csp_docs.setup(app)
+```
+
+`docs_url`/`redoc_url` must already be `None` on the app for whichever mode you're enabling —
+`setup()` raises `RuntimeError` otherwise, so FastAPI's built-in inline-script docs can't
+silently shadow the routes it registers.
+
+Full runnable version:
+[`examples/assisted_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/assisted_app.py).
+
+### Fully self-hosted mode (no CDN at all)
+
+For a CSP with zero external origins (`script-src 'self'`), skip `setup()` and wire the
+endpoints directly — same mechanics as FastAPI's own
+["Custom Docs UI Static Assets"](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
+recipe, but built from this package's content generators instead of `fastapi.openapi.docs`, so
+the OAuth2 redirect page stays script-free too:
+
+```python
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+
+import fastapi_csp_docs
+
+app = FastAPI(docs_url=None, redoc_url=None)
+app.mount("/static", StaticFiles(directory="static"), name="static")
+
+
+@app.get("/docs", include_in_schema=False)
+async def swagger_ui_html():
+    return fastapi_csp_docs.get_swagger_ui_html(
+        title=f"{app.title} - Swagger UI",
+        swagger_js_url="/static/swagger-ui-bundle.js",
+        swagger_css_url="/static/swagger-ui.css",
+        swagger_ui_init_script_url="/docs/swagger-initializer.js",
+    )
+```
+
+Full runnable version, including the `swagger-initializer.js`/`redoc.css`/OAuth2 redirect
+endpoints and the vendor assets:
+[`examples/self_hosted_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/self_hosted_app.py).
+
+## ReDoc and Content-Security-Policy
+
+Beyond the inline `<script>`/`<style>` tags this package removes from FastAPI's own generated
+HTML, ReDoc's *own* runtime does three more things that need explicit CSP entries. Both
+examples above already handle these (`examples/_csp.py` for the CDN-based ones,
+`examples/self_hosted_app.py` for the fully self-hosted one) — this section explains why.
+
+**Inline styles (`style-src`)** — ReDoc is built with `styled-components`, which injects
+`<style>` tags into the page at runtime instead of shipping one static stylesheet. This is
+unrelated to the inline content `fastapi-csp-docs` removes — it's ReDoc's own rendering
+mechanism, and this package can't eliminate it. A CSP hash allowlist is used to allow them
+without `'unsafe-inline'`: open DevTools, note the exact `'sha256-...'` value(s) the browser
+reports as blocked, and add them to `style-src`. These hashes are tied to the exact ReDoc
+build, so they need to be recaptured whenever `redoc.standalone.js` is upgraded.
+
+**Web Worker (`worker-src`)** — ReDoc runs its search indexing in a Web Worker, instantiated
+from a `blob:` URL rather than a separate `.js` file: the worker's entire source is inlined as
+a string inside `redoc.standalone.js`, so there's no real file URL to point `worker-src` at
+instead. Worker instantiation is governed by `worker-src`, not `script-src` — without it set
+explicitly, browsers fall back to `script-src`, which never matches a `blob:` URL, so search
+breaks the first time it's used (`Creating a worker from 'blob:...' violates ... worker-src`).
+Two ways to fix it:
+- Allow it explicitly: `worker-src 'self' blob:` — what `assisted_app.py` and the other
+  `setup()`-based examples do, since `setup()` deliberately has no CSP-specific parameters (it
+  mirrors FastAPI's own `docs_url`/`redoc_url` surface, nothing more).
+- Or skip the worker (and the search box) entirely by not using `setup()` for the ReDoc route:
+  pass `redoc_url=None` to `setup()` and wire `/redoc` yourself with
+  `get_redoc_html(disable_search=True)` instead — no `blob:` needed in `worker-src` then. See
+  [`examples/redoc_disable_search_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/redoc_disable_search_app.py).
+
+**Logo image (`img-src`)** — ReDoc's "API docs by Redocly" attribution logo hardcodes an
+absolute `cdn.redoc.ly` URL, with no supported way to override it or point it at a local file.
+There's no CSP hash mechanism for images (hash-source only applies to `script-src`/`style-src`), so the only way to allow it is
+whitelisting that origin in `img-src` — both examples do this, since it's a small, non-code
+image request and doesn't weaken `script-src`/`style-src` at all. It's the one external origin
+left in `self_hosted_app.py`'s otherwise fully self-hosted CSP.
+
+## Reference
+
+### `setup(app, *, docs_url="/docs", redoc_url="/redoc")`
+
+| Parameter  | Type          | Default   | Description                                                                                             |
+|------------|---------------|-----------|-----------------------------------------------------------------------------------------------------------|
+| `app`      | `FastAPI`     | required  | The app to wire the CSP-safe docs routes onto. Must be created with `docs_url=None`/`redoc_url=None` for whichever of the two this call sets up. |
+| `docs_url` | `str \| None` | `"/docs"` | Path to serve Swagger UI at, or `None` to skip it.                                                       |
+| `redoc_url`| `str \| None` | `"/redoc"`| Path to serve ReDoc at, or `None` to skip it.                                                            |
+
+Raises `RuntimeError` if `app.docs_url`/`app.redoc_url` is still set for the mode being enabled.
+
+### Content generators (manual wiring)
+
+| Function                                | Returns                          | Purpose                                                                    |
+|------------------------------------------|-----------------------------------|-----------------------------------------------------------------------------|
+| `get_swagger_ui_html`                    | `HTMLResponse`                   | Swagger UI page, referencing an external init script instead of inline JS. |
+| `get_swagger_ui_init_js`                 | `Response` (`text/javascript`)   | Swagger UI bootstrap script, with HTML-escaped JSON config.                |
+| `get_swagger_ui_oauth2_redirect_html`     | `HTMLResponse`                   | OAuth2 redirect page, referencing an external script instead of inline JS. |
+| `get_swagger_ui_oauth2_redirect_js`       | `Response` (`text/javascript`)   | OAuth2 redirect handshake logic.                                           |
+| `get_redoc_html`                         | `HTMLResponse`                   | ReDoc page, referencing an external stylesheet instead of inline `<style>`. Takes `disable_search` to drop the search box/Web Worker, see "ReDoc and Content-Security-Policy" above. |
+| `get_redoc_css`                          | `Response` (`text/css`)          | Minimal CSS reset ReDoc needs.                                             |
+
+## Examples
+
+| File                                                                                                                      | Description                                                                                     |
+|-----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
+| [`examples/assisted_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/assisted_app.py)             | `setup()` + CDN-hosted Swagger UI/ReDoc bundles, CSP header set via middleware.                    |
+| [`examples/self_hosted_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/self_hosted_app.py)       | Fully self-hosted docs (no CDN), manual wiring, vendor assets served from `examples/static/`.       |
+| [`examples/mounted_subapp_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/mounted_subapp_app.py) | `setup()` on a sub-app mounted under a prefix (`app.mount("/api", sub_app)`) — doc URLs resolve correctly via the ASGI `root_path`. |
+| [`examples/root_path_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/root_path_app.py)           | `setup()` on an app created with `FastAPI(root_path="/api")` — the reverse-proxy way of setting `root_path`, as opposed to mounting a sub-app. |
+| [`examples/oauth2_redirect_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/oauth2_redirect_app.py) | OAuth2 "Authorize" flow with a real security scheme, exercising the `/docs/oauth2-redirect` endpoint `setup()` registers. |
+| [`examples/redoc_disable_search_app.py`](https://github.com/mat81black/fastapi-csp-docs/blob/main/examples/redoc_disable_search_app.py) | `setup()` for Swagger UI + manual ReDoc wiring with `disable_search=True`, avoiding `worker-src 'self' blob:` entirely. |
+
+## Release Notes
+
+See [RELEASE_NOTES.md](https://github.com/mat81black/fastapi-csp-docs/blob/main/RELEASE_NOTES.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/mat81black/fastapi-csp-docs/blob/main/LICENSE).

fastapi_csp_docs-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fastapi_csp_docs/__init__.py,sha256=fKgm7WXvXSPA5ow5AHFpMl1570AmdkoaHNRw7orA3SU,486
+fastapi_csp_docs/docs.py,sha256=gPJ2Fq7JuAPqCS8iZKDIsTgybvN5Y-EzgajEl5N7Ezo,10011
+fastapi_csp_docs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastapi_csp_docs/setup.py,sha256=qeCLDOLFg46DYmqBtxU9e-Zd_qpr0vq1TYtNjI6Q1YQ,5373
+fastapi_csp_docs-0.1.0.dist-info/METADATA,sha256=n76sJhtFKswkzhCpoNhbhJzHlCf56mPYEGbTk1MgjpQ,13640
+fastapi_csp_docs-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+fastapi_csp_docs-0.1.0.dist-info/licenses/LICENSE,sha256=Tsif_IFIW5f-xYSy1KlhAy7v_oNEU4lP2cEnSQbMdE4,1086
+fastapi_csp_docs-0.1.0.dist-info/RECORD,,

fastapi_csp_docs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_csp_docs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Sebastián Ramírez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.