# Public API — `mgf-auth`

> **Master-HEAD banner (REL-03):** this file tracks the public surface of the
> CURRENT `main`/release. Verify the version you depend on via
> `mgf.auth.__version__` (mirrors `pyproject.toml::project.version`). The
> machine-readable companion is [`PUBLIC_API.json`](PUBLIC_API.json), generated
> from `mgf.auth.__all__` and pinned in CI.

The public surface is exactly `mgf.auth.__all__`. Everything under a leading
underscore (`mgf.auth._protocols`, `_errors`, `_events`, `_svix`,
`clerk_session`/`clerk_webhook` internals) is private.

- **Stability tiers:** `experimental` (MAY change shape in any MINOR — the 0.x
  window keeps everything experimental), `stable` (deprecation cycle; removal
  only in MAJOR), `deprecated` (scheduled for removal).

## `mgf.auth`

| Name | Tier | Description |
|---|---|---|
| `SessionVerifier` | experimental | Protocol: verify a session token → principal. ISP-split (verify_session only). |
| `WebhookVerifier` | experimental | Protocol: verify a signed webhook → typed `WebhookEvent`. |
| `WebhookEvent` | experimental | Frozen DTO returned by a `WebhookVerifier` (typed `event_id` identity + payload). |
| `InvalidSessionError` | experimental | Typed 401 (subclasses `mgf.common HttpUnauthorizedError`); `.reason` field. |
| `InvalidWebhookSignatureError` | experimental | Typed 401 for a bad/replayed webhook signature; `.reason` field. |
| `MockSessionVerifier` | experimental | In-memory `SessionVerifier` for consumer tests. |
| `MockWebhookVerifier` | experimental | In-memory `WebhookVerifier` for consumer tests. |

## Exceptions (AP-07)

Both typed errors subclass `mgf.common.exceptions.HttpUnauthorizedError` (HTTP 401)
and carry a machine-readable `.reason` field (EH-08). The token/secret is never
included in the message or `.reason` — forensic detail goes to WARNING logs.

## The Clerk adapter

`ClerkSessionVerifier` / `ClerkWebhookVerifier` live in `mgf.auth.clerk_session` /
`mgf.auth.clerk_webhook` — imported explicitly by consumers that use Clerk (they
pull the optional `[clerk]` extra). They are NOT in the generic `__all__` so that
`import mgf.auth` stays vendor-SDK-free (the import-linter contract).
