# STARTHERE — mgf-auth

> **Sibling library in the Magogi Foundation federation.**
> See [README.md](README.md) for what this library does and its
> public surface; see
> [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md)
> for the federation contract.

`mgf-auth` provides two **ISP-split auth verifier seams** for
`mgf-common` consumers — a generic `SessionVerifier` +
`WebhookVerifier`, a **Clerk** adapter (session-JWT verification +
Svix-webhook verification), typed 401 errors, and test mocks.

---

## For consumers (using this library)

1. **Pin** in your `pyproject.toml`:
   ```toml
   dependencies = ["mgf-auth[clerk]>=0.1,<0.2"]
   ```
   The `[clerk]` extra adds PyJWT for the session adapter; the
   webhook adapter is stdlib-only. See [CHANGELOG.md](CHANGELOG.md)
   for the current minor.
2. **Install:** `uv add "mgf-auth[clerk]"` (or
   `pip install "mgf-auth[clerk]"`).
3. **Read** [README.md](README.md) for the stable surface
   (`SessionVerifier` / `WebhookVerifier` / `WebhookEvent` /
   `ClerkSessionVerifier` / `ClerkWebhookVerifier` / the mocks).
4. **Wire it up** — `SessionVerifier` is generic over your principal
   type; supply a `principal_resolver` that maps Clerk claims to your
   own role-typed principal:
   ```python
   from mgf.auth.clerk_session import ClerkSessionVerifier, ClerkClaims
   from mgf.auth.clerk_webhook import ClerkWebhookVerifier

   session_verifier: ClerkSessionVerifier[MyPrincipal] = ClerkSessionVerifier(
       jwt_public_key=PEM, issuer="https://clerk.acme.example",
       principal_resolver=resolve,
   )
   principal = await session_verifier.verify_session(bearer_token)

   webhook_verifier = ClerkWebhookVerifier(webhook_secret=b"whsec_...")
   event = await webhook_verifier.verify_webhook(headers, raw_body)
   ```
   Tests use `MockSessionVerifier[MyPrincipal]()` and
   `MockWebhookVerifier()` — no Clerk, no network.
5. **Bootstrap your app** with mgf-common first — see
   [mgf-common/STARTHERE.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/STARTHERE.md).
   Typed 401 errors (`InvalidSessionError` /
   `InvalidWebhookSignatureError`) subclass mgf-common's
   `HttpUnauthorizedError`.
6. **Run** `mgf-common catch-up` periodically to verify
   federation drift; see
   [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) §6.

---

## For contributors

See [CONTRIBUTING.md](CONTRIBUTING.md). Standards are inherited
from [mgf-common](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).

---

## Quick links

| Resource | Where |
|---|---|
| Library purpose + surface | [README.md](README.md) |
| Release notes | [CHANGELOG.md](CHANGELOG.md) |
| Dependencies (both directions) | [DEPS.md](DEPS.md) |
| Feedback / papers | [FEEDBACK.md](FEEDBACK.md) |
| Federation contract | [FEDERATION.md](FEDERATION.md) → [mgf-common/FEDERATION.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/FEDERATION.md) |
| Cross-project standards | [mgf-standard/docs/standards/](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/) |
