mgf-fastapi 0.1.0__tar.gz

mgf_fastapi-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing and coverage
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.pyre/
+.pytype/
+
+# Ruff
+.ruff_cache/
+
+# Packaging
+MANIFEST
+
+# Claude Code — keep settings.json (committed for the team), ignore
+# per-machine local overrides + runtime locks/state.
+.claude/settings.local.json
+.claude/*.lock
+.claude/scheduled_tasks*
+
+# Maintainer planning notes (per-machine; never commit)
+my_stuff/

mgf_fastapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to `mgf-fastapi` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+the project follows [SemVer](https://semver.org/spec/v2.0.0.html). Per
+the 0.x window ([SemVer 0.x](https://semver.org/#spec-item-4) and rule
+**AP-03** from `mgf-common/docs/standards/API_DESIGN.md`), MINOR
+releases MAY break the public API. Pin tightly:
+
+```toml
+mgf-fastapi = ">=0.X.0,<0.Y"   # one minor at a time
+```
+
+The release-engineering discipline that produces this changelog is in
+[`mgf-common/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/standards/RELEASING.md).
+
+---
+
+## [Unreleased]
+
+Nothing yet.
+
+---
+
+## [0.1.0] — 2026-05-09
+
+PyPI: <https://pypi.org/project/mgf-fastapi/0.1.0/> · Tag: `v0.1.0`
+
+> **Maiden voyage** — extracted from `mgf-common` v0.28.0 per the
+> federation split plan ([mgf-common/docs/release/federation_roadmap.md](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md)).
+> Cutover guide: [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md).
+
+### Added
+
+- **`mgf.fastapi`** — top-level FastAPI integration. `bootstrap` ↔
+  FastAPI lifespan (`setup_lifespan`); `RequestIdMiddleware` +
+  `current_request_id()`; `ExceptionTranslationMiddleware` +
+  `DEFAULT_STATUS_MAP`; `Depends()` helpers (`get_app_context`,
+  `get_settings`, `get_request_id`); `REQUEST_ID_HEADER` constant.
+- **`mgf.fastapi.webhooks`** — Svix-shape HMAC webhook verification.
+  `WebhookHeaderSchema` (frozen dataclass; case-folds header names);
+  `SVIX_SCHEMA` (Svix preset; used verbatim by Clerk);
+  `HmacWebhookVerifier` (transport-agnostic core; thread-safe;
+  `verify(headers, body) -> (event_id, ts)`); `verify_request`
+  (async FastAPI request adapter).
+- **`mgf.fastapi.security`** — `IpAllowlist` FastAPI dependency.
+  CIDR allowlist with IPv4 + IPv6 dual-stack; cross-version matches
+  deliberately rejected. `trust_proxy=False` default concentrates
+  the proxy-trust footgun. Default `cidrs=LOOPBACK_CIDRS` so tests
+  work out-of-the-box.
+- **`mgf.fastapi.testing`** — `run_test_app` async context manager.
+  Starts uvicorn for a FastAPI app on a free port; yields the base
+  URL; tears down cleanly on context exit. Surfaces server-startup
+  exceptions immediately instead of timing out silently. Optional
+  `[testing]` extra pulls in `uvicorn>=0.30` + `httpx>=0.27`.
+- **`mgf.fastapi.exceptions`** — `HmacVerificationError(HttpUnauthorized)`.
+  Inherits the HTTP-01 status leaf from `mgf.common.exceptions` so
+  PAPER-24's `http_status` resolution maps to 401 in
+  `ExceptionTranslationMiddleware` without an explicit `status_map`
+  entry. (Other concrete leaves can be added here in subsequent
+  minors per the federation rule "siblings own their domain
+  concretes; mgf-common owns hierarchy roots + status leaves.")
+
+### Engineering
+
+- 83 tests carried over from `mgf-common/tests/unit/fastapi/` —
+  every pre-extraction failure mode and integration path stays
+  green at parity. Coverage threshold ≥80% (matches mgf-common's
+  standard).
+- Imports from `mgf.common.fastapi.*` rewrite to `mgf.fastapi.*`.
+  `HmacVerificationError` re-exported from `mgf.fastapi.exceptions`
+  rather than `mgf.common.exceptions` (the latter no longer ships
+  it as of mgf-common v0.28).
+- `mgf-common>=0.28,<0.29` runtime dependency. AP-03 0.x window
+  pin discipline applies — bump in lock-step with mgf-common's
+  next minor.
+- PEP 420 namespace package (no top-level `mgf/__init__.py`); the
+  wheel ships `src/mgf/` as-is so `mgf.fastapi` and `mgf.common`
+  coexist as siblings.

mgf_fastapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bassam Alsanie and mgf-common contributors
+
+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.

mgf_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: mgf-fastapi
+Version: 0.1.0
+Summary: FastAPI integration adapters for mgf-common — request-id + exception translation + lifespan + webhooks (Svix HMAC) + IpAllowlist + run_test_app. Sibling of mgf-common under the mgf.* namespace.
+Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf-fastapi
+Project-URL: Issues, https://codeberg.org/magogi-admin/mgf-fastapi/issues
+Project-URL: Changelog, https://codeberg.org/magogi-admin/mgf-fastapi/src/branch/master/CHANGELOG.md
+Author: Bassam Alsanie, mgf-fastapi contributors
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,ip-allowlist,middleware,request-id,svix,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: mgf-common<0.29,>=0.28
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Provides-Extra: testing
+Requires-Dist: httpx>=0.27; extra == 'testing'
+Requires-Dist: uvicorn>=0.30; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# `mgf-fastapi` — FastAPI integration adapters for mgf-common
+
+[![PyPI](https://img.shields.io/pypi/v/mgf-fastapi)](https://pypi.org/project/mgf-fastapi/)
+[![Python](https://img.shields.io/pypi/pyversions/mgf-fastapi)](https://pypi.org/project/mgf-fastapi/)
+
+> **Sibling of [`mgf-common`](https://pypi.org/project/mgf-common/)
+> under the `mgf.*` namespace.** Houses every FastAPI-specific
+> adapter that previously lived under `mgf.common.fastapi.*` —
+> extracted at mgf-common v0.28 / mgf-fastapi v0.1 per the
+> [federation split plan](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md).
+
+## What this provides
+
+| Submodule | What |
+|---|---|
+| `mgf.fastapi` | `bootstrap` ↔ FastAPI lifespan; `RequestIdMiddleware`; `ExceptionTranslationMiddleware`; `Depends()` helpers (`get_app_context`, `get_settings`, `get_request_id`); `setup_lifespan`. |
+| `mgf.fastapi.webhooks` | Svix-shape HMAC webhook verification (`HmacWebhookVerifier`, `WebhookHeaderSchema`, `SVIX_SCHEMA`, `verify_request`). |
+| `mgf.fastapi.security` | `IpAllowlist` FastAPI dependency with proxy-trust opt-in. |
+| `mgf.fastapi.testing` | `run_test_app` async context manager — start uvicorn for a FastAPI app on a free port; yield base URL; clean shutdown. |
+| `mgf.fastapi.exceptions` | `HmacVerificationError(HttpUnauthorized)` and other framework-domain concrete leaves. (HTTP-01 hierarchy roots stay in `mgf.common.exceptions`.) |
+
+## Install
+
+```bash
+pip install mgf-fastapi
+# Or with the test-helper extra (uvicorn + httpx for run_test_app):
+pip install 'mgf-fastapi[testing]'
+```
+
+Pulls in `mgf-common` and `fastapi` automatically.
+
+## Quick start
+
+```python
+from fastapi import FastAPI, Request
+from mgf.fastapi import (
+    ExceptionTranslationMiddleware,
+    RequestIdMiddleware,
+    setup_lifespan,
+)
+from mgf.fastapi.webhooks import HmacWebhookVerifier, verify_request
+
+app = FastAPI(lifespan=setup_lifespan(app_name="my-service", app_version="0.1.0"))
+app.add_middleware(ExceptionTranslationMiddleware)
+app.add_middleware(RequestIdMiddleware)
+
+webhook = HmacWebhookVerifier(secret=settings.webhook_secret)
+
+@app.post("/webhooks/clerk")
+async def clerk_webhook(request: Request) -> dict:
+    event_id, ts = await verify_request(request, webhook)
+    payload = await request.json()
+    # ... process the (now-trusted) payload ...
+    return {"ok": True}
+```
+
+## Documentation
+
+- [`docs/recipes/fastapi.md`](docs/recipes/fastapi.md) — full FastAPI service walkthrough.
+- [`docs/recipes/webhooks.md`](docs/recipes/webhooks.md) — HMAC webhook verification.
+- [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md) — maiden voyage migration story (the v0.28 split).
+- [`PUBLIC_API.md`](PUBLIC_API.md) — full public surface contract.
+- [`CHANGELOG.md`](CHANGELOG.md) — release history.
+
+For the federation-wide engineering standards (DESIGN_PRINCIPLES,
+ERROR_HANDLING, SECURITY, etc.) see
+[`mgf-common/docs/standards/`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/standards/).
+This sibling inherits them by reference; the standards source-of-truth
+lives in mgf-common.
+
+## Status
+
+🚧 **Experimental** — every public name is `experimental` per AP-09.
+Promotion to `stable` happens release-by-release as consumer feedback
+in [`FEEDBACK.md`](FEEDBACK.md) converges. The 0.x window applies.
+Pin tightly: `mgf-fastapi = ">=0.X.0,<0.Y"`.
+
+## Cross-references
+
+- **Filing process for sharp edges**: open an entry on
+  [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md)
+  with `[mgf-fastapi]` prefix, OR file directly on this repo's
+  Issues → maintainer mirrors into the canonical FEEDBACK.md.
+- **Federation pattern**:
+  [`mgf-common/docs/design/federation.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/design/federation.md).
+- **The split that created this sibling**:
+  [`mgf-common/docs/release/federation_roadmap.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md).

mgf_fastapi-0.1.0/PUBLIC_API.md

@@ -0,0 +1,138 @@
+# Public API — `mgf-fastapi`
+
+> ⚠️ **This file documents `master` HEAD.** Names listed here may
+> be unreleased. To learn what your installed wheel actually
+> ships, run `pip show mgf-fastapi` and compare against the
+> `__version__` field at the top of `PUBLIC_API.json`. The git
+> tag matching the published version is authoritative.
+
+This document is the **contract list** for `mgf-fastapi`. Every name
+listed below is a public name that consumers MAY depend on.
+
+The contract terms are defined in
+[`mgf-common/docs/standards/API_DESIGN.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/standards/API_DESIGN.md). In
+short:
+
+- **Stability tiers:**
+  - `experimental` — MAY change shape in any MINOR release
+    (the 0.x window keeps everything experimental in practice).
+  - `stable` — follows the deprecation cycle; removal only in MAJOR.
+  - `deprecated` — slated for removal; emits `DeprecationWarning`.
+- **Names not listed below are private.** Anything starting with
+  `_` (underscore-prefixed module names like `_lifespan.py`) is
+  internal and MAY change without notice.
+- **The 0.x window applies.** Per [SemVer](https://semver.org/) 0.x
+  semantics, MINOR releases MAY break the public API. Pin tightly:
+  `mgf-fastapi = ">=0.X.0,<0.Y"`.
+
+---
+
+## `mgf.fastapi`
+
+Top-level FastAPI integration adapters. Re-exports the load-bearing
+public names from the submodules. Closed-box: depends on
+`mgf-common` + `fastapi` only.
+
+| Name | Tier | Description |
+|---|---|---|
+| `setup_lifespan(*, app_name=None, app_version=None, settings=None)` | experimental | Build a FastAPI lifespan that runs `mgf.common.bootstrap()` at app startup. The resulting `AppContext` is stashed on `app.state.mgf_context` for dependency injection. LIFO unwind on shutdown. |
+| `RequestIdMiddleware` | experimental | ASGI middleware. Injects/forwards `X-Request-Id` header (case-insensitive); generates UUID4 if absent. Sets `request.state.request_id` AND a contextvar shared with `mgf.common._request_id` (so cross-framework processes correlate end-to-end). Echoes in response. |
+| `current_request_id() -> str` | experimental | Read the per-request id from the contextvar. Returns empty string outside a request. PEP 567 propagates across async children. |
+| `REQUEST_ID_HEADER = "X-Request-Id"` | experimental | Canonical header name. Inbound case-insensitive; outbound canonical. |
+| `ExceptionTranslationMiddleware` | experimental | ASGI middleware. Catches `AppError` from handlers; maps to typed JSON responses via `status_map` (default per category) AND falls back to `HttpError.http_status` (PAPER-24 resolution) for HTTP-01 leaves like `HttpUnauthorized`, `HttpForbidden`, `HttpNotFound`, etc. — including sibling-domain concretes like `HmacVerificationError` (401 via inheritance). Configurable via `status_map=` and `response_factory=` kwargs. Includes `request_id` in error body when `RequestIdMiddleware` is installed. |
+| `DEFAULT_STATUS_MAP: dict[type[AppError], int]` | experimental | Default exception → HTTP status mapping. `SchemaValidationError`→400, `ResourceNotFoundError`→404, `ResourceAlreadyExistsError`→409, `HostEnvironmentError`→503, `ConfigError`/`OperationError`/`VaultError`/`AppError`→500. |
+| `get_app_context(request) -> AppContext` | experimental | FastAPI dependency. Reads `request.app.state.mgf_context`; raises `AppConfigError` if unset (lifespan not wired). |
+| `get_settings(request) -> MgfSettings` | experimental | FastAPI dependency. Returns the `MgfSettings` from the active context. |
+| `get_request_id(request) -> str` | experimental | FastAPI dependency. Reads `request.state.request_id`; returns `""` if `RequestIdMiddleware` is not installed. |
+| `HmacVerificationError` | experimental | Re-exported from `mgf.fastapi.exceptions`. Convenience top-level alias for the most-commonly-caught sibling-domain exception. |
+
+---
+
+## `mgf.fastapi.exceptions`
+
+Sibling-domain concrete exception leaves. Per the federation rule
+(decision **D3** in the [federation roadmap](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md)),
+siblings own their domain concretes; mgf-common owns hierarchy
+roots + generic status-code leaves.
+
+| Name | Tier | Description |
+|---|---|---|
+| `HmacVerificationError` | experimental | A webhook HMAC signature failed verification. Inherits `mgf.common.exceptions.HttpUnauthorized` (status 401). Raised by `mgf.fastapi.webhooks.HmacWebhookVerifier` on any failure mode (missing header, unparseable timestamp, replay-window miss, signature mismatch). PAPER-24's `http_status` resolution maps it to 401 in `ExceptionTranslationMiddleware` without an explicit `status_map` entry. |
+
+---
+
+## `mgf.fastapi.webhooks`
+
+Svix-shape HMAC webhook verification. Pulls the per-consumer
+verification dance into one tested primitive. Closes
+[`mgf-common`'s PAPER-26](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md)
+(originally shipped in mgf-common v0.26; moved to this sibling at
+mgf-common v0.28 / mgf-fastapi v0.1).
+
+| Name | Tier | Description |
+|---|---|---|
+| `WebhookHeaderSchema(id_header, timestamp_header, signature_header)` | experimental | Frozen dataclass naming the three Svix-style headers a provider uses. Header names are case-folded to lowercase on construction. |
+| `SVIX_SCHEMA: WebhookHeaderSchema` | experimental | Pre-built schema for Svix's canonical headers (`svix-id` / `svix-timestamp` / `svix-signature`). Used by Clerk verbatim. Stripe / GitHub / Slack are deferred to follow-up papers. |
+| `HmacWebhookVerifier(*, secret, schema=SVIX_SCHEMA, replay_window_seconds=300, signature_prefix="v1,", now=time.time)` | experimental | Transport-agnostic verifier. `verify(headers, body) -> (event_id, ts)`. Raises `HmacVerificationError` on any failure (missing header, unparseable timestamp, replay-window miss, signature mismatch). Stateless and thread-safe. |
+| `verify_request(request, verifier) -> (event_id, ts)` | experimental | Async FastAPI request adapter. Reads `await request.body()`, lifts `request.headers` into the verifier's input, returns `verifier.verify(...)`. Caller MUST NOT have consumed the body yet. |
+
+See [`docs/recipes/webhooks.md`](docs/recipes/webhooks.md)
+for the full walkthrough including key rotation, custom schemas,
+and the consumer pattern for replacing per-provider verifiers.
+
+---
+
+## `mgf.fastapi.security`
+
+Request-side security primitives for FastAPI. Closes
+[`mgf-common`'s PAPER-27](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md)
+(originally shipped in mgf-common v0.27; moved to this sibling at
+mgf-common v0.28 / mgf-fastapi v0.1).
+
+| Name | Tier | Description |
+|---|---|---|
+| `IpAllowlist(cidrs=LOOPBACK_CIDRS, *, trust_proxy=False)` | experimental | FastAPI dependency that 403s requests whose client IP isn't in `cidrs`. Concentrates the proxy-trust footgun in one knob — `trust_proxy=False` default; honouring `X-Forwarded-For` requires explicit opt-in. IPv4 + IPv6 dual-stack with cross-version matches deliberately rejected. Misconfigured CIDRs raise at construction. |
+| `LOOPBACK_CIDRS: tuple[str, ...]` | experimental | The default `cidrs=` for `IpAllowlist` — `("127.0.0.0/8", "::1/128")`. Loopback-only so tests work out-of-the-box; consumers OVERRIDE for production. |
+
+---
+
+## `mgf.fastapi.testing`
+
+Test-server lifecycle helper. Closes
+[`mgf-common`'s PAPER-28](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md)
+(originally shipped in mgf-common v0.27; moved to this sibling at
+mgf-common v0.28 / mgf-fastapi v0.1).
+
+Optional `[testing]` extra: `pip install 'mgf-fastapi[testing]'`
+(pulls `uvicorn>=0.30` + `httpx>=0.27`).
+
+| Name | Tier | Description |
+|---|---|---|
+| `run_test_app(app, *, port=None, host="127.0.0.1", log_level="warning", startup_timeout_seconds=5.0)` | experimental | Async context manager. Starts uvicorn for `app` on a free port; yields `f"http://{host}:{port}"`; tears down cleanly on context exit (including under exception). `port=None` picks a free ephemeral port. Surfaces server-startup exceptions immediately instead of timing out silently. Raises `TimeoutError` if uvicorn doesn't reach `started` within `startup_timeout_seconds`. `CancelledError` from the serve task is suppressed on shutdown (expected). |
+
+---
+
+## Summary
+
+| Module | Public name count |
+|---|---|
+| `mgf.fastapi` | 10 |
+| `mgf.fastapi.exceptions` | 1 |
+| `mgf.fastapi.webhooks` | 4 |
+| `mgf.fastapi.security` | 2 |
+| `mgf.fastapi.testing` | 1 |
+| **Total** | **18** |
+
+(`HmacVerificationError` counted once — at `mgf.fastapi.exceptions`. The
+re-export at `mgf.fastapi` is a convenience alias.)
+
+---
+
+## Cross-references
+
+- [`CHANGELOG.md`](CHANGELOG.md) — release history.
+- [`docs/recipes/`](docs/recipes/) — full how-to for each surface.
+- [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md) — maiden voyage migration story (the v0.28 split).
+- [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md) — design conversation queue.
+- [`mgf-common/docs/standards/`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/standards/) — the federation-wide engineering standards.
+- [`mgf-common/docs/release/federation_roadmap.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md) — the split plan that created this sibling.

mgf_fastapi-0.1.0/README.md

@@ -0,0 +1,87 @@
+# `mgf-fastapi` — FastAPI integration adapters for mgf-common
+
+[![PyPI](https://img.shields.io/pypi/v/mgf-fastapi)](https://pypi.org/project/mgf-fastapi/)
+[![Python](https://img.shields.io/pypi/pyversions/mgf-fastapi)](https://pypi.org/project/mgf-fastapi/)
+
+> **Sibling of [`mgf-common`](https://pypi.org/project/mgf-common/)
+> under the `mgf.*` namespace.** Houses every FastAPI-specific
+> adapter that previously lived under `mgf.common.fastapi.*` —
+> extracted at mgf-common v0.28 / mgf-fastapi v0.1 per the
+> [federation split plan](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md).
+
+## What this provides
+
+| Submodule | What |
+|---|---|
+| `mgf.fastapi` | `bootstrap` ↔ FastAPI lifespan; `RequestIdMiddleware`; `ExceptionTranslationMiddleware`; `Depends()` helpers (`get_app_context`, `get_settings`, `get_request_id`); `setup_lifespan`. |
+| `mgf.fastapi.webhooks` | Svix-shape HMAC webhook verification (`HmacWebhookVerifier`, `WebhookHeaderSchema`, `SVIX_SCHEMA`, `verify_request`). |
+| `mgf.fastapi.security` | `IpAllowlist` FastAPI dependency with proxy-trust opt-in. |
+| `mgf.fastapi.testing` | `run_test_app` async context manager — start uvicorn for a FastAPI app on a free port; yield base URL; clean shutdown. |
+| `mgf.fastapi.exceptions` | `HmacVerificationError(HttpUnauthorized)` and other framework-domain concrete leaves. (HTTP-01 hierarchy roots stay in `mgf.common.exceptions`.) |
+
+## Install
+
+```bash
+pip install mgf-fastapi
+# Or with the test-helper extra (uvicorn + httpx for run_test_app):
+pip install 'mgf-fastapi[testing]'
+```
+
+Pulls in `mgf-common` and `fastapi` automatically.
+
+## Quick start
+
+```python
+from fastapi import FastAPI, Request
+from mgf.fastapi import (
+    ExceptionTranslationMiddleware,
+    RequestIdMiddleware,
+    setup_lifespan,
+)
+from mgf.fastapi.webhooks import HmacWebhookVerifier, verify_request
+
+app = FastAPI(lifespan=setup_lifespan(app_name="my-service", app_version="0.1.0"))
+app.add_middleware(ExceptionTranslationMiddleware)
+app.add_middleware(RequestIdMiddleware)
+
+webhook = HmacWebhookVerifier(secret=settings.webhook_secret)
+
+@app.post("/webhooks/clerk")
+async def clerk_webhook(request: Request) -> dict:
+    event_id, ts = await verify_request(request, webhook)
+    payload = await request.json()
+    # ... process the (now-trusted) payload ...
+    return {"ok": True}
+```
+
+## Documentation
+
+- [`docs/recipes/fastapi.md`](docs/recipes/fastapi.md) — full FastAPI service walkthrough.
+- [`docs/recipes/webhooks.md`](docs/recipes/webhooks.md) — HMAC webhook verification.
+- [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md) — maiden voyage migration story (the v0.28 split).
+- [`PUBLIC_API.md`](PUBLIC_API.md) — full public surface contract.
+- [`CHANGELOG.md`](CHANGELOG.md) — release history.
+
+For the federation-wide engineering standards (DESIGN_PRINCIPLES,
+ERROR_HANDLING, SECURITY, etc.) see
+[`mgf-common/docs/standards/`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/standards/).
+This sibling inherits them by reference; the standards source-of-truth
+lives in mgf-common.
+
+## Status
+
+🚧 **Experimental** — every public name is `experimental` per AP-09.
+Promotion to `stable` happens release-by-release as consumer feedback
+in [`FEEDBACK.md`](FEEDBACK.md) converges. The 0.x window applies.
+Pin tightly: `mgf-fastapi = ">=0.X.0,<0.Y"`.
+
+## Cross-references
+
+- **Filing process for sharp edges**: open an entry on
+  [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md)
+  with `[mgf-fastapi]` prefix, OR file directly on this repo's
+  Issues → maintainer mirrors into the canonical FEEDBACK.md.
+- **Federation pattern**:
+  [`mgf-common/docs/design/federation.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/design/federation.md).
+- **The split that created this sibling**:
+  [`mgf-common/docs/release/federation_roadmap.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md).