# `mgf-fastapi` — structured-event catalogue (LG-15)

Every structured log record that carries an `event` field is registered here.
An `event` emitted without a row below is a defect (LG-15). Operators dashboard
and alert on these stable identifiers.

| `event` | Level | Where | Meaning | Queryable fields (`extra=`) |
|---|---|---|---|---|
| `mgf.fastapi.webhook.verification_failed` | WARNING | `webhooks/_request.py` `verify_request` | A webhook was rejected — forged signature, replayed/stale timestamp, missing header, over-cap body, or upstream-consumed body. Forged/replayed webhooks leave an audit trail (LG-15) instead of a silent 401. | `reason` (`missing_header` / `bad_timestamp` / `replay_window` / `signature_mismatch` / `body_too_large` / `body_consumed`), `audit` |
| `mgf.fastapi.ip_allowlist.trust_proxy_enabled` | WARNING | `security.py` `IpAllowlist.__init__` | `IpAllowlist` constructed with `trust_proxy=True` — confirm an upstream proxy strips client-supplied `X-Forwarded-For` (PAPER-27). | `audit` |
| `mgf.fastapi.ip_allowlist.denied` | WARNING | `security.py` `IpAllowlist.__call__` | A request was denied by the IP allowlist (no client IP, unparseable IP, or not in any configured network). | `reason` (`no_client_ip` / `unparseable_ip` / `not_in_allowlist`), `client_host`, `networks`, `audit` |
| `mgf.fastapi.auth.misconfigured` | ERROR | `security.py` `bearer_session` | The bearer verifier was never wired onto `app.state` — a deployment bug; the caller still gets a 401 (no internal state leaked). | `audit` |
| `mgf.fastapi.auth.rejected` | INFO | `security.py` `bearer_session` | The bearer verifier rejected a token (expired, malformed, provider error, …); translated to 401. | `verifier_error`, `audit` |
| `mgf.fastapi.db.setup` | INFO | `db.py` `setup_db` | Engine + sessionmaker creation (start / complete phases). | `operation` (`db.setup`), `phase` (`start` / `complete`) |
| `mgf.fastapi.db.teardown` | INFO | `db.py` `setup_db` | Engine disposed cleanly at lifespan exit. | `operation` (`db.setup`), `phase` (`teardown`) |
| `mgf.fastapi.db.dispose_failed` | WARNING | `db.py` lifespan teardown | Engine dispose raised during shutdown (logged-and-continued, RA-06). | `database_url_present`, exception info |
| `mgf.fastapi.rate_limit_exceeded` | INFO | `_rate_limit.py` | A request was denied by the token-bucket limiter. | client key, limit, window |

> **Namespace rename (LG-15):** the engine-dispose event was emitted as
> `mgf_fastapi.db.dispose_failed` (underscore) through v0.6.x; it is renamed to
> the consistent `mgf.fastapi.db.dispose_failed` (dot) here. Operators with an
> alert/dashboard target on the old underscore identifier must repoint it — this
> is a deliberate, one-time alert-target rename, after which all `mgf-fastapi`
> events share the single `mgf.fastapi.*` namespace.
