# Security Policy

`mgf-http` is a federation sibling of [`mgf-common`](https://pypi.org/project/mgf-common/),
shipping an async HTTP client (`AsyncHttpClient`) — typed
`httpx` wrapper with retries, timeouts, header redaction, and
OTel-aware logging. A vulnerability here may affect every
consumer that makes outbound HTTP calls via this library, 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.2.x`  | ✅ — latest MINOR; security patches ship as `0.2.Y` |
| `0.1.x`  | ❌ — superseded by `0.2.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-http security]`.
- **Codeberg private security advisory:** open a private
  vulnerability report via
  [the repository's Security tab](https://codeberg.org/magogi-admin/mgf-http/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 header-redaction issues, the exact request
  shape matters.
- The version(s) of `mgf-http` affected, plus the pinned
  `mgf-common` and `httpx` 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**. After expiry (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.

## Scope

**In scope:**

- Code in `src/mgf/http/` (the published `mgf-http` package).
  Specifically: header redaction (`_client._redact_headers`),
  retry-policy boundaries (`_retry`), transport-level error
  translation (`_errors`), TLS-default-on warning.
- 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 `httpx`, `h2`, `anyio`, or other transitive
  deps — report to the upstream project.
- Self-inflicted issues: `verify_tls=False` in production
  (the library emits a `UserWarning`; running anyway is
  operator choice), running with a permissive retry policy
  against an idempotency-unsafe endpoint, leaking secrets
  through `extra=` log fields the redactor doesn't see.

## Hardening recommendations for consumers

Consumers of `mgf-http` 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. The Rules box at the top
of that document is the bar; the §15 mechanical-enforcement matrix
is the contract for what every consumer's CI should check.

Particular attention paid to:
- **TLS verification ON in production.** `verify_tls=False`
  is for development against self-signed certs only. The
  one-shot `UserWarning` is the audit trail.
- **Retry policy boundaries.** `POST` is excluded from
  `retryable_methods` by default — adding it requires the
  caller to ensure idempotency (key + ON CONFLICT, or a
  unique-claim store). Per **EH-12**.
- **Secret redaction set.** The default redacts known header
  shapes (`Authorization`, `X-Api-Key`, `Cookie`, `Set-Cookie`,
  `Proxy-Authorization`, …). Domain-specific headers
  (project-internal auth tokens) MUST be added via the
  `redact_headers=` kwarg.

## A note on the standards

`mgf-http` 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.
