# Security Policy

`mgf-fastapi` is a federation sibling of [`mgf-common`](https://pypi.org/project/mgf-common/),
shipping FastAPI integration adapters (lifespan + AppContext +
request-id middleware + exception-translation middleware + HMAC
webhook verifier + IP allowlist + bearer-session auth + test API
server). A vulnerability here may affect every FastAPI consumer
that depends on it, so we take security reports seriously.

## Supported versions

In the 0.x window, **only the latest MINOR receives security
patches.** Per [SemVer 0.x](https://semver.org/#spec-item-4) and
rule **AP-03** from `mgf-standard/docs/standards/API_DESIGN.md`,
each MINOR release MAY break the public API; we do not
branch-and-backport across minors. Security fixes ship as the
next PATCH on the latest MINOR.

| Version | Supported |
|---------|-----------|
| `0.4.x`         | ✅ — latest MINOR; security patches ship as `0.4.Y` |
| `0.3.x`         | ❌ — superseded by `0.4.x` |
| `< 0.3`         | ❌ — pre-PAPER-29 surface; upgrade to `0.4.x` |

When a security fix lands, the [`CHANGELOG.md`](CHANGELOG.md)
entry for the fixing release names the affected versions and
the upgrade path.

## Reporting a vulnerability

**Please do not open a public issue or pull request** until we have
had a chance to triage and patch.

To report a vulnerability privately, choose one of:

- **Email:** `bassam@magogi.org` with subject prefix
  `[mgf-fastapi security]`.
- **Codeberg private security advisory:** open a private
  vulnerability report via
  [the repository's Security tab](https://codeberg.org/magogi-admin/mgf-fastapi/security).

### What to include

- A description of the vulnerability and its impact.
- Steps to reproduce — a minimal failing test or HTTP transcript
  is ideal. For auth-related issues, the exact bearer-token /
  HMAC header shape matters.
- The version(s) of `mgf-fastapi` affected, plus the pinned
  `mgf-common` and `fastapi` versions.
- Python version + OS.
- Any suggested mitigations or patches you have in mind.

### What to expect

| Stage | Timeline |
|---|---|
| Acknowledgement | within 3 business days |
| Initial assessment + severity rating | within 7 business days |
| Patch + release | within 30 days for high-severity, 90 days for medium |
| Credit + public disclosure | coordinated with the reporter |

We follow a **90-day default embargo**, extendable by mutual
agreement if a patch is not yet ready. After the embargo expires
(or after a patch ships, whichever is first), the vulnerability is
disclosed in the [`CHANGELOG.md`](CHANGELOG.md) entry for the
fixing release, with credit to the reporter unless declined.

For severity ≥ medium we file a Codeberg security advisory and
request a CVE so PyPI auto-yanks affected versions.

## Scope

**In scope:**

- Code in `src/mgf/fastapi/` (the published `mgf-fastapi` package).
  Includes the HMAC webhook verifier (`webhooks._verifier`), the
  bearer-session resolver (`security.bearer_session`), the IP
  allowlist (`security.IpAllowlist`), the exception-translation
  middleware (`_exceptions`), and the test API server
  (`testing.run_test_app`).
- Build / release infrastructure (`pyproject.toml`, the manual
  release flow specified in
  [`mgf-standard/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/RELEASING.md)).

**Out of scope:**

- Vulnerabilities in `mgf-common` itself — report to
  [`mgf-common/SECURITY.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/SECURITY.md).
- Vulnerabilities in `fastapi`, `starlette`, `pydantic`, `httpx`
  or other transitive deps — report to the upstream project.
- Vulnerabilities in a consumer's own auth provider integration
  (Clerk, Auth0, Okta) — the `AuthVerifier` Protocol is the
  seam; consumer-side impls are out of scope.
- Self-inflicted DoS (e.g., running with `trust_proxy=True` on
  `IpAllowlist` while exposing the app DIRECTLY to the internet
  instead of behind a reverse proxy — see the PAPER-27
  documentation in
  [`docs/recipes/`](docs/recipes/) for the trust-anchor framing).

## Hardening recommendations for consumers

Consumers of `mgf-fastapi` adopt the
[`mgf-standard/docs/standards/SECURITY_STANDARD.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/SECURITY_STANDARD.md)
engineering standard as their baseline. Web-specific overlays
(request-id propagation, CSRF + CORS, session-cookie security
headers, rate-limiting) live in
[`mgf-standard/docs/standards/web/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/web/).

Particular attention paid to:
- **Webhook HMAC verification.** Always validate the timestamp
  against a replay window (`HmacWebhookVerifier` defaults to 5
  minutes; tune per upstream's recommended window).
- **Bearer-session validation.** The `AuthVerifier` Protocol
  treats failures (missing / expired / IdP outage) uniformly
  as `HttpUnauthorized` → 401. Do not leak token contents in
  error responses.
- **IP allowlist with `trust_proxy=True`.** Only use when a
  trusted reverse proxy (Envoy, nginx, CloudFront) is in
  front; otherwise `X-Forwarded-For` is attacker-controlled.

## A note on the standards

`mgf-fastapi` is a **federation sibling** under the project-shape
taxonomy from
[`mgf-standard/docs/standards/DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md) §2.0.
The cross-project engineering standards live in `mgf-common`; this
project inherits them. See [`docs/standards/README.md`](docs/standards/README.md)
for the pointer.
