Migrate from Flask + Marshmallow to FastAPI + Pydantic

[somethingnew2-0]

Summary

Replaces Flask + Flask-RESTful + flask_apispec + Flask-SQLAlchemy + Flask-Migrate + Marshmallow with FastAPI + Pydantic v2 + plain Alembic. SQLAlchemy stays sync; async is a deferred follow-up.

Wire-compatible by design. Same URL paths, methods, query params, request/response JSON shape, error envelope ({"message": ...}), and RFC822 datetime format. The React frontend and any external clients work unchanged. A new regression test pass was added for every previously-omitted field surfaced during QA.

What's in the box

Framework swap

• OIDC ported from flask_oidc to Authlib + SessionMiddleware. Cloudflare Access JWT verification added (cached JWKS with thread-safe atomic refresh, kid rotation handling). Test/dev bypass via app.dependency_overrides.
• Existing models, operations, and Alembic migration files reused unchanged via a thin db compatibility shim (db.Model / db.session / Model.query / first_or_404). The shim is intentional scaffolding so the diff stays focused on the framework swap; removal is captured in POST_MIGRATION_TODO.md Bump the npm-major group with 9 updates #1.
• New Makefile + access CLI (Click) replace flask <cmd> invocations. gunicorn -k uvicorn.workers.UvicornWorker api.asgi:app replaces gunicorn api.wsgi:app. K8s manifests and example plugins updated. FLASK_ENV → ENV everywhere.
• Standalone alembic.ini at repo root replaces the Flask-Migrate stub.

Pydantic-first end to end

• All 43 typeable routes declare a response_model; OpenAPI now publishes 80 typed components instead of advertising every payload as {}, unblocking the frontend codegen step (POST_MIGRATION_TODO.md Reconfigure using the Okta Group Owners API to be opt-in #13).
• Routes return validated Pydantic instances directly; paginate() is generic on pagination_cls: type[PaginationResponse[T]].
• All POST/PUT bodies validated via typed Create*Body / Update*Body / Resolve*Body schemas. CreateGroupBody / UpdateGroupBody / CreateGroupRequestBody are discriminated unions on type, restoring the per-type name-pattern + length + REQUIRE_DESCRIPTIONS validation that the original *In schemas did.
• All list/audit endpoints consume typed Search*PaginationQuery models via Annotated[Model, Query()].
• Audit-log payloads modeled as explicit Pydantic refs (_AuditUserRef, _AuditAppRef, …) under AuditLogPayload(extra="forbid"), replacing the __dict__ fallback that was leaking the OktaUser profile JSONB blob (HRIS data) into audit logs.

Strict ORM serialization + eager-load hygiene

• All routes run Pydantic validation in strict from_attributes=True mode, so unloaded relationships raise InvalidRequestError at the responsible route instead of being silently swallowed and emitted as null.
• The eager-load topology for OktaUserGroupMemberDetail, RoleGroupMapDetail, OktaGroupTagMapDetail, and AppTagMapDetail, plus the polymorphic AppGroup/RoleGroup loader, is centralized in api/routers/_eager.py and reused across apps.py, groups.py, tags.py, users.py, role_requests.py, and access_requests.py so the loader stays in lockstep with the response schemas.

Auth gate

• App-wide Depends(require_authenticated) runs on every registered route. Allowlist: /api/healthz and /api/oidc/* only — /api/docs and /api/openapi.json are intentionally inside the gate even though they're already DEBUG-gated.
• The SPA mount at / was replaced with a catch-all GET /{spa_path:path} route so static assets inherit the auth dependency. Path-traversal rejected; unmapped /api/* returns 404 instead of the SPA index.
• New OIDCRedirectRequired exception → 307 to /api/oidc/login?next=… so the SPA's fetch() follows the IdP login flow instead of seeing a bare 403.
• request_id is always uuid4 server-side; the previous X-Request-Id header read let a caller pin every concurrent request to one shared SQLAlchemy session-scope key.

Tooling

• Makefile wraps install / migrate / init / run / sync / notify / pytest / pytest-postgres / ruff / mypy. README rewritten around make targets.
• make pytest-postgres spins up a disposable postgres:16 container and runs the suite end-to-end against it. CI green on both backends.
• tox -e ruff + tox -e mypy clean. Strict typing on routers/schemas is intentionally deferred (POST_MIGRATION_TODO.md Simplify docker #14) to keep this diff scoped to framework swap + parity.
• setup.py renamed name="api" → name="access"; version bumped 0.2 → 2.0 to match the planned 2.0 release. Audit logger renamed api.audit → access.audit.

Deferred follow-ups

See POST_MIGRATION_TODO.md — 21 items grouped by surface area. Highlights:

• Bump the npm-major group with 9 updates #1 Remove the db compatibility shim (~150 lines, mostly mechanical).
• Bump express from 4.18.2 to 4.19.2 #2/3 Async SQLAlchemy + async_scoped_session (gates use Okta's response headers for rate limits #11, async Okta HTTP).
• Bump @mui/lab from 5.0.0-alpha.154 to 5.0.0-alpha.169 #5–8 Wire-shape changes that need frontend coordination (ISO 8601 datetimes, exclude_none, RFC 9457 errors, fastapi-pagination).
• Reconfigure using the Okta Group Owners API to be opt-in #13 Frontend OpenAPI codegen (now unblocked by the typed response_model work).
• Bump the npm-minor group with 13 updates #20/21 Nonce-based CSP + trust X-Forwarded-* only from an allowlist (lifted from audit-report MED-4 / LOW-3).

Test plan

• pytest tests/ — 281/281 passing (sqlite); 268/268 passing on Postgres via make pytest-postgres
• tox -e ruff (check + format) clean; tox -e mypy clean (137 source files)
• alembic upgrade head against scratch sqlite — schema matches main
• make run-backend + manual smoke through the React UI: groups list, group detail (Okta/Role/App), access-request flow, group-request create/read/resolve, role-request resolve, audit pages (users/groups/expiring), /apps/<name> owner+non-owner groups, /users/@me group memberships, /tags/<name>
• /api/docs Swagger UI loads under DEBUG CSP
• OpenAPI now exposes 80 typed components on 43/47 endpoints
• CF Access end-to-end smoke in a deployed dev env (real JWT + service token)
• npm run dev regression sweep through groups/roles/apps/requests/audit
• Frontend OpenAPI codegen run (POST_MIGRATION_TODO Reconfigure using the Okta Group Owners API to be opt-in #13) once this lands

🤖 Generated with Claude Code

[willk-discord]

TBH if I could go back I would not use async sqlalchemy. At the time we moved to it to get the "async everything" benefits from FastAPI.... but in practice we have spent an extremely high amount of time dealing with the inane async contract SQLAlchemy provides. For an example:

class TicketModel(SiriusBaseModel):
    __tablename__ = "tickets"

    vulnerabilities: Mapped[List["VulnerabilityModel"]] = relationship(
        "VulnerabilityModel",
        secondary=ticket_vulnerabilities,
        lazy="immediate",  # Don't lazy-load these to make the translation between `schemas` and `models` easier
        back_populates="tickets",
    )
    # .... snipped ....

    select: Select[TicketModel] = (
        Select(TicketModel)
        .limit(1)

   ticket: TicketModel = await db.scalar(select)

   print(ticket.tickets[0]). # WE BLOW UP THE STACK HERE. REALLY.

Any relationship is a lazy loaded attribute. Async sqlalchemy just ignores our directives for immediate loading. Any lazy loaded attribute must be explicitly re-loaded before access just in time using the async await pattern. Failure to do so results in a greenlet not awaited error. This has caused Sirius to go to the pattern of immediately coercing from SQLAlchemy model -> Pydantic schema to avoid this cursed lazy loading. Other DB accesses can expire the lazy loaded attributes, especially when running in a green threaded context, which means that the safest option is to just either A) never use relationships B) always coerce to pydantic immediately (our choice) or C) not do async sqlalchemy.

My overwhelming experience with it is that async sqlalchemy is not production ready. It actively lies about its API contracts, and does not uphold them. This has caused us to invest heavily in integration tests because we cannot sanely reason about the different failure patterns.

[willk-discord]

This is a huge change set, so I'm not reviewing everything by hand. I looked at a sample of each major change set looking for patterns (expecting that LLMs are good at doing the same thing everywhere). This looks like a reasonable conversion to FastAPI! My main points of feedback are around not using Async SQLAlchemy if you can avoid it (not in this PR, noted as future work). Otherwise this seems idiomatic to me!