fastapi2postman 0.2.0__tar.gz → 0.3.0__tar.gz

{fastapi2postman-0.2.0 → fastapi2postman-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi2postman
-Version: 0.2.0
+Version: 0.3.0
 Summary: Turn a FastAPI app into a Postman collection you can run straight away.
 Keywords: fastapi,postman,newman,openapi,api,cli
 Author: Ashhad Ahsan Rehman
@@ -77,6 +77,44 @@ Secret variables start blank, so the file holds no credentials. You fill them in
 
 **Auth the schema can't show.** Middleware, or a dependency that reads `request.headers`, doesn't appear in OpenAPI. Use `--bearer` to send `{{bearerToken}}` on every request that has no auth of its own.
 
+## Check your routes
+
+Two more commands read the routes themselves, so they also see what the schema leaves out: routes hidden from the docs, websockets, and plain Starlette routes.
+
+`routes` lists everything the app serves and what protects it, like `flask routes`:
+
+```console
+$ fastapi2postman routes --app main.py
+METHOD  PATH       AUTH        TAGS    NOTE
+GET     /health    -           -
+GET     /internal  -           -       hidden from the docs
+GET     /me        HTTPBearer  -
+POST    /orders    -           orders
+*       /static    ?           -       can't read: StaticFiles
+```
+
+`audit` fails when a route has no visible auth, so a route merged without its `Depends()` turns CI red:
+
+```console
+$ fastapi2postman audit --app main.py --allow "/health" --allow "/static*"
+2 of 5 routes have no visible auth:
+
+  GET   /internal  no auth, hidden from the docs
+  POST  /orders    no auth
+
+Protect them, or allow the ones meant to be open, for example --allow "/health" or --allow "GET /public/*".
+```
+
+It exits with 1 when it finds any, and 0 otherwise. `--allow` takes a path or a method and a path, and `*` matches anything, including `/`. An `--allow` that matches no route prints a warning, because it could let a route added later through unnoticed.
+
+Auth counts when a route's dependencies declare it, at any depth: a security scheme such as `HTTPBearer`, or a required header, query parameter or cookie named like a credential, such as `x_token` or `session_id`.
+
+**`audit` reads what routes declare and doesn't run them.** So:
+
+- Auth in middleware, or in a dependency reading `request.headers`, looks like no auth. Allow those routes.
+- A dependency that declares a token but never checks it still counts as auth. So does `auto_error=False`, which `routes` shows as `HTTPBearer (optional)`.
+- Plain Starlette routes and mounted apps such as `StaticFiles` have nothing to read, so they're always flagged until you allow them.
+
 ## Pointing it at your app
 
 Run it from your project root.

{fastapi2postman-0.2.0 → fastapi2postman-0.3.0}/README.md

@@ -50,6 +50,44 @@ Secret variables start blank, so the file holds no credentials. You fill them in
 
 **Auth the schema can't show.** Middleware, or a dependency that reads `request.headers`, doesn't appear in OpenAPI. Use `--bearer` to send `{{bearerToken}}` on every request that has no auth of its own.
 
+## Check your routes
+
+Two more commands read the routes themselves, so they also see what the schema leaves out: routes hidden from the docs, websockets, and plain Starlette routes.
+
+`routes` lists everything the app serves and what protects it, like `flask routes`:
+
+```console
+$ fastapi2postman routes --app main.py
+METHOD  PATH       AUTH        TAGS    NOTE
+GET     /health    -           -
+GET     /internal  -           -       hidden from the docs
+GET     /me        HTTPBearer  -
+POST    /orders    -           orders
+*       /static    ?           -       can't read: StaticFiles
+```
+
+`audit` fails when a route has no visible auth, so a route merged without its `Depends()` turns CI red:
+
+```console
+$ fastapi2postman audit --app main.py --allow "/health" --allow "/static*"
+2 of 5 routes have no visible auth:
+
+  GET   /internal  no auth, hidden from the docs
+  POST  /orders    no auth
+
+Protect them, or allow the ones meant to be open, for example --allow "/health" or --allow "GET /public/*".
+```
+
+It exits with 1 when it finds any, and 0 otherwise. `--allow` takes a path or a method and a path, and `*` matches anything, including `/`. An `--allow` that matches no route prints a warning, because it could let a route added later through unnoticed.
+
+Auth counts when a route's dependencies declare it, at any depth: a security scheme such as `HTTPBearer`, or a required header, query parameter or cookie named like a credential, such as `x_token` or `session_id`.
+
+**`audit` reads what routes declare and doesn't run them.** So:
+
+- Auth in middleware, or in a dependency reading `request.headers`, looks like no auth. Allow those routes.
+- A dependency that declares a token but never checks it still counts as auth. So does `auto_error=False`, which `routes` shows as `HTTPBearer (optional)`.
+- Plain Starlette routes and mounted apps such as `StaticFiles` have nothing to read, so they're always flagged until you allow them.
+
 ## Pointing it at your app
 
 Run it from your project root.

{fastapi2postman-0.2.0 → fastapi2postman-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi2postman"
-version = "0.2.0"
+version = "0.3.0"
 description = "Turn a FastAPI app into a Postman collection you can run straight away."
 readme = "README.md"
 license = "MIT"

{fastapi2postman-0.2.0 → fastapi2postman-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi2postman"
-version = "0.2.0"
+version = "0.3.0"
 description = "Turn a FastAPI app into a Postman collection you can run straight away."
 readme = "README.md"
 license = "MIT"

fastapi2postman-0.3.0/src/fastapi2postman/cli.py

@@ -0,0 +1,168 @@
+"""The fastapi2postman command."""
+
+import argparse
+import json
+import os
+import sys
+import textwrap
+from fnmatch import fnmatchcase
+from importlib import import_module, metadata
+from pathlib import Path
+
+from fastapi import FastAPI
+
+from . import to_postman
+from .routes import Route, list_routes
+
+_APP_HELP = "the app: main.py, main.py:api or package.main:api. The name defaults to app, and may be a factory"
+
+
+def _module_of(path: Path) -> tuple[str, Path]:
+    """The dotted name of a file and the folder to import it from, which is above its package if it's in one."""
+    parts = [path.stem]
+    root = path.parent
+    while (root / "__init__.py").is_file():
+        parts.insert(0, root.name)
+        root = root.parent
+    return ".".join(parts), root
+
+
+def _load_app(spec: str) -> FastAPI:
+    target, attribute = spec, "app"
+    if ":" in spec and not Path(spec).is_file():  # a colon can be part of a path: C:\project\app.py
+        target, attribute = spec.rsplit(":", 1)
+
+    name = target
+    search = [os.getcwd()]  # a console script has its own folder on sys.path, not the project's
+    if Path(target).is_file():
+        name, root = _module_of(Path(target).resolve())
+        search.insert(0, str(root))
+    sys.path[:0] = search
+
+    try:
+        module = import_module(name)
+    except ModuleNotFoundError as error:
+        if error.name != name and not name.startswith(f"{error.name}."):
+            raise  # something the app itself imports is missing, and the traceback says what
+        raise SystemExit(
+            f"fastapi2postman: cannot find {target!r}: give a .py file, or a module importable from {os.getcwd()}"
+        ) from error
+    if not hasattr(module, attribute):
+        raise SystemExit(f"fastapi2postman: {name} has no attribute {attribute!r}")
+
+    app = getattr(module, attribute)
+    if not isinstance(app, FastAPI) and callable(app):
+        app = app()  # a factory
+    if not isinstance(app, FastAPI):
+        raise SystemExit(f"fastapi2postman: {spec} gives {type(app).__name__}, not a FastAPI app")
+    return app
+
+
+def _export(argv: list[str]) -> None:
+    parser = argparse.ArgumentParser(
+        prog="fastapi2postman",
+        description="Turn a FastAPI app into a Postman collection you can run straight away.",
+        epilog="other commands: 'routes' lists every route with its auth, and 'audit' fails when a route has no auth. "
+        "Add --help to either one for details.",
+    )
+    parser.add_argument("--app", required=True, help=_APP_HELP)
+    parser.add_argument("--output", default="output.json", help="output file (default: %(default)s)")
+    parser.add_argument("--name", help="collection name (default: the app's title)")
+    parser.add_argument(
+        "--base-url", help="where the requests go (default: the app's first server, else http://localhost:8000)"
+    )
+    parser.add_argument("--host", help="shorthand for --base-url http://HOST:PORT")
+    parser.add_argument("--port", type=int, help="shorthand for --base-url http://HOST:PORT")
+    parser.add_argument(
+        "--bearer",
+        action="store_true",
+        help="send {{bearerToken}} on every request without auth of its own: for auth in middleware, or in a "
+        "dependency reading request.headers, which the app's schema can't show",
+    )
+    parser.add_argument("--version", action="version", version=metadata.version("fastapi2postman"))
+    args = parser.parse_args(argv)
+
+    base_url = args.base_url
+    if not base_url and (args.host or args.port):
+        base_url = f"http://{args.host or 'localhost'}:{args.port or 8000}"
+
+    collection = to_postman(_load_app(args.app), name=args.name, base_url=base_url, bearer=args.bearer)
+    text = json.dumps(collection, indent=2, ensure_ascii=False)
+    Path(args.output).write_text(text + "\n", encoding="utf-8")
+    count = sum(len(entry.get("item", [entry])) for entry in collection["item"])
+    print(f"{args.output}: {count} requests")
+
+
+def _table(rows: list[list[str]]) -> str:
+    widths = [max(len(row[column]) for row in rows) for column in range(len(rows[0]))]
+    lines = ["  ".join(cell.ljust(width) for cell, width in zip(row, widths, strict=True)).rstrip() for row in rows]
+    return "\n".join(lines)
+
+
+def _routes(argv: list[str]) -> None:
+    parser = argparse.ArgumentParser(
+        prog="fastapi2postman routes",
+        description="List every route the app serves with what protects it, including routes hidden from the docs.",
+    )
+    parser.add_argument("--app", required=True, help=_APP_HELP)
+    args = parser.parse_args(argv)
+
+    rows = [["METHOD", "PATH", "AUTH", "TAGS", "NOTE"]]
+    for route in list_routes(_load_app(args.app)):
+        auth = ", ".join(route.auth) or ("?" if route.unreadable else "-")
+        note = f"can't read: {route.unreadable}" if route.unreadable else "hidden from the docs" if route.hidden else ""
+        rows.append([route.method, route.path, auth, ", ".join(route.tags) or "-", note])
+    print(_table(rows))
+
+
+def _allows(pattern: str, route: Route) -> bool:
+    return fnmatchcase(f"{route.method} {route.path}" if " " in pattern else route.path, pattern)
+
+
+def _audit(argv: list[str]) -> None:
+    parser = argparse.ArgumentParser(
+        prog="fastapi2postman audit",
+        description="Fail when a route has no visible auth, including routes hidden from the docs. It reads what the "
+        "routes declare and doesn't run them, so it can't see auth in middleware, or what a dependency's code does.",
+    )
+    parser.add_argument("--app", required=True, help=_APP_HELP)
+    parser.add_argument(
+        "--allow",
+        action="append",
+        default=[],
+        metavar="PATTERN",
+        help='a route meant to be open, such as "/health" or "GET /public/*". Repeat it for more',
+    )
+    args = parser.parse_args(argv)
+
+    routes = list_routes(_load_app(args.app))
+    for pattern in args.allow:
+        if not any(_allows(pattern, route) for route in routes):
+            print(f"fastapi2postman: --allow {pattern!r} matches no route", file=sys.stderr)
+
+    unprotected = [route for route in routes if not route.auth]
+    flagged = [route for route in unprotected if not any(_allows(pattern, route) for pattern in args.allow)]
+    if not flagged:
+        with_auth = len(routes) - len(unprotected)
+        print(f"{len(routes)} routes: {with_auth} with auth, {len(unprotected)} allowed")
+        return
+
+    rows = []
+    for route in flagged:
+        why = f"can't read: {route.unreadable}" if route.unreadable else "no auth"
+        rows.append([route.method, route.path, why + (", hidden from the docs" if route.hidden else "")])
+    print(f"{len(flagged)} of {len(routes)} routes have no visible auth:\n")
+    print(textwrap.indent(_table(rows), "  "))
+    print(
+        '\nProtect them, or allow the ones meant to be open, for example --allow "/health" or --allow "GET /public/*".'
+    )
+    raise SystemExit(1)
+
+
+def main() -> None:
+    commands = {"routes": _routes, "audit": _audit}
+    argv = sys.argv[1:]
+    if argv and argv[0] in commands:
+        commands[argv[0]](argv[1:])
+    else:
+        _export(argv)

fastapi2postman-0.3.0/src/fastapi2postman/routes.py

@@ -0,0 +1,92 @@
+"""Every route an app really serves, and what protects it.
+
+The schema can't answer this. It leaves out routes hidden from the docs, websockets and plain Starlette routes, which
+are exactly what a check for open routes has to see, so this reads the routes themselves. Anything it doesn't recognise
+is reported as unreadable instead of being skipped, so a change in FastAPI's internals shows up in the audit rather than
+hiding routes from it.
+"""
+
+import re
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.security.base import SecurityBase
+from starlette.routing import Mount, WebSocketRoute
+
+from . import _SECRET
+
+_AUTH_PARAMETER = re.compile(f"{_SECRET.pattern}|authorization|session", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class Route:
+    method: str  # an HTTP method, WS for a websocket, or * when a mounted app decides
+    path: str
+    auth: list[str]  # security schemes by name, and required parameters that look like credentials
+    tags: list[str]
+    hidden: bool  # left out of the docs
+    unreadable: str  # the kind of route, when it has no dependencies to read auth from
+
+
+def _auth(dependant: Any) -> list[str]:
+    """What protects a route, from its dependencies at any depth. Only what they declare: their code isn't run."""
+    found = []
+    if isinstance(dependant.call, SecurityBase):
+        optional = not getattr(dependant.call, "auto_error", True)
+        found.append(dependant.call.scheme_name + (" (optional)" if optional else ""))
+    for parameter in (*dependant.header_params, *dependant.query_params, *dependant.cookie_params):
+        if parameter.field_info.is_required() and _AUTH_PARAMETER.search(parameter.alias):
+            found.append(parameter.alias)
+    for dependency in dependant.dependencies:
+        found.extend(_auth(dependency))
+    return list(dict.fromkeys(found))
+
+
+def _flatten(routes: Iterable[Any]) -> Iterator[Any]:
+    """The routes behind include_router(), which FastAPI 0.137+ keeps in a private object. Before that they're flat."""
+    for route in routes:
+        contexts = getattr(route, "effective_route_contexts", None)
+        if contexts is None:
+            yield route
+        else:
+            for context in contexts():
+                # Websockets, plain routes and mounts come with a ready-made route. API routes are the context itself.
+                yield getattr(context, "starlette_route", None) or context
+
+
+def _walk(routes: Iterable[Any], prefix: str, docs: set[str]) -> Iterator[Route]:
+    for route in _flatten(routes):
+        if isinstance(route, Mount):
+            mounted = prefix + route.path
+            if isinstance(route.app, FastAPI):
+                yield from _app_routes(route.app, mounted)
+            elif route.routes:
+                yield from _walk(route.routes, mounted, set())
+            else:
+                yield Route("*", mounted or "/", [], [], False, type(route.app).__name__)
+            continue
+        dependant = getattr(route, "dependant", None)
+        path = prefix + getattr(route, "path_format", getattr(route, "path", ""))
+        if dependant is None and path in docs:
+            continue
+        for method in getattr(route, "methods", None) or ["WS" if isinstance(route, WebSocketRoute) else "*"]:
+            yield Route(
+                method=method,
+                path=path or "/",
+                auth=[] if dependant is None else _auth(dependant),
+                tags=[getattr(tag, "value", tag) for tag in getattr(route, "tags", [])],
+                hidden=not getattr(route, "include_in_schema", True),
+                unreadable=type(route).__name__ if dependant is None else "",
+            )
+
+
+def _app_routes(app: FastAPI, prefix: str) -> Iterator[Route]:
+    own_docs = (app.openapi_url, app.docs_url, app.redoc_url, app.swagger_ui_oauth2_redirect_url)
+    yield from _walk(app.routes, prefix, {prefix + url for url in own_docs if url})
+
+
+def list_routes(app: FastAPI) -> list[Route]:
+    """Every route the app serves, apart from FastAPI's own docs, sorted by path and then method."""
+    return sorted(_app_routes(app, ""), key=lambda route: (route.path, route.method))

fastapi2postman-0.2.0/src/fastapi2postman/cli.py

@@ -1,89 +0,0 @@
-"""The fastapi2postman command."""
-
-import argparse
-import json
-import os
-import sys
-from importlib import import_module, metadata
-from pathlib import Path
-
-from fastapi import FastAPI
-
-from . import to_postman
-
-
-def _module_of(path: Path) -> tuple[str, Path]:
-    """The dotted name of a file and the folder to import it from, which is above its package if it's in one."""
-    parts = [path.stem]
-    root = path.parent
-    while (root / "__init__.py").is_file():
-        parts.insert(0, root.name)
-        root = root.parent
-    return ".".join(parts), root
-
-
-def _load_app(spec: str) -> FastAPI:
-    target, attribute = spec, "app"
-    if ":" in spec and not Path(spec).is_file():  # a colon can be part of a path: C:\project\app.py
-        target, attribute = spec.rsplit(":", 1)
-
-    name = target
-    search = [os.getcwd()]  # a console script has its own folder on sys.path, not the project's
-    if Path(target).is_file():
-        name, root = _module_of(Path(target).resolve())
-        search.insert(0, str(root))
-    sys.path[:0] = search
-
-    try:
-        module = import_module(name)
-    except ModuleNotFoundError as error:
-        if error.name != name and not name.startswith(f"{error.name}."):
-            raise  # something the app itself imports is missing, and the traceback says what
-        raise SystemExit(
-            f"fastapi2postman: cannot find {target!r}: give a .py file, or a module importable from {os.getcwd()}"
-        ) from error
-    if not hasattr(module, attribute):
-        raise SystemExit(f"fastapi2postman: {name} has no attribute {attribute!r}")
-
-    app = getattr(module, attribute)
-    if not isinstance(app, FastAPI) and callable(app):
-        app = app()  # a factory
-    if not isinstance(app, FastAPI):
-        raise SystemExit(f"fastapi2postman: {spec} gives {type(app).__name__}, not a FastAPI app")
-    return app
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        prog="fastapi2postman", description="Turn a FastAPI app into a Postman collection you can run straight away."
-    )
-    parser.add_argument(
-        "--app",
-        required=True,
-        help="the app: main.py, main.py:api or package.main:api. The name defaults to app, and may be a factory",
-    )
-    parser.add_argument("--output", default="output.json", help="output file (default: %(default)s)")
-    parser.add_argument("--name", help="collection name (default: the app's title)")
-    parser.add_argument(
-        "--base-url", help="where the requests go (default: the app's first server, else http://localhost:8000)"
-    )
-    parser.add_argument("--host", help="shorthand for --base-url http://HOST:PORT")
-    parser.add_argument("--port", type=int, help="shorthand for --base-url http://HOST:PORT")
-    parser.add_argument(
-        "--bearer",
-        action="store_true",
-        help="send {{bearerToken}} on every request without auth of its own: for auth in middleware, or in a "
-        "dependency reading request.headers, which the app's schema can't show",
-    )
-    parser.add_argument("--version", action="version", version=metadata.version("fastapi2postman"))
-    args = parser.parse_args()
-
-    base_url = args.base_url
-    if not base_url and (args.host or args.port):
-        base_url = f"http://{args.host or 'localhost'}:{args.port or 8000}"
-
-    collection = to_postman(_load_app(args.app), name=args.name, base_url=base_url, bearer=args.bearer)
-    text = json.dumps(collection, indent=2, ensure_ascii=False)
-    Path(args.output).write_text(text + "\n", encoding="utf-8")
-    count = sum(len(entry.get("item", [entry])) for entry in collection["item"])
-    print(f"{args.output}: {count} requests")