# Changelog

All notable changes to `mgf-auth` are documented here.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
the project follows [SemVer](https://semver.org/spec/v2.0.0.html). Per
the 0.x window ([SemVer 0.x](https://semver.org/#spec-item-4) and rule
**AP-03** from `mgf-standard/docs/standards/API_DESIGN.md`), MINOR
releases MAY break the public API. Pin tightly:

```toml
mgf-auth = ">=0.X.0,<0.Y"   # one minor at a time
```

The release-engineering discipline that produces this changelog is in
[`mgf-standard/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/RELEASING.md).

---

## [0.1.8] - 2026-06-26

### Changed
- Delegate Clerk/Svix webhook HMAC verification to the shared `mgf.common.webhooks` primitive (mgf-common 0.49); store the raw `whsec_`
  secret (single decode). Drop the duplicated signature dance. Widen the pin to `<0.50`.

## [0.1.7] - 2026-06-16

### Changed
- Widened the `mgf-common` pin to `<0.48` — mgf-common 0.47 is the pure-library release (the end-user CLI moved to `mgf-fed[cli]`); the importable API is unchanged.
- Regenerated `.woodpecker` so the supervisor lane calls `mtest` (the moved `mgf-common test` frontend is gone).

## [Unreleased]

Nothing yet.

---


## [0.1.6] — 2026-06-08 — depth-audit close-out (public API + EH/LG + _svix)

### Added
- `mgf.auth.__version__` (AP-13); CI tag-coherence asserts it.
- `PUBLIC_API.md` (tiers + exceptions + master-HEAD banner) + `PUBLIC_API.json`
  + generator + CI pins (AP-10/11, DOC-01/08/09, REL-03).
- Machine-readable `.reason` field on `InvalidSessionError` /
  `InvalidWebhookSignatureError` (EH-08).

### Changed
- Internal: `_decode_svix_secret` extracted to a neutral `mgf.auth._svix` codec
  so the generic core (incl. mocks) no longer imports the Clerk adapter; the
  import-linter contract is re-enabled in CI (DP-01).
- The auth-failure log event `auth_failure` → `mgf.auth.session_rejected`, with
  the failure reason in a queryable `extra` field (LG-15/16).
- Declined (CFM-04 §3): AP-14 (consumer-fixture import-linter), SC-14 (per-source
  lockout — a stateful rate-limit, the consumer's concern).

## [0.1.5] — 2026-06-06 — federation cohort: mgf-common 0.46 walk

Walk the `mgf-common` pin ceiling `<0.46 → <0.47` to accept the
library-API-neutral `mgf-common 0.46.0` (CLI-only release: new
`federation`/`design` commands + a `doctor --standards` gate; no library
surface change).

---

## [0.1.4] — 2026-06-04 — federation cohort: mgf-common 0.45 walk

PATCH: pin widened to `mgf-common>=0.41,<0.46` to accept mgf-common 0.45 (the
Codeberg package-distribution cutover — PKG-01..12). `mgf-*` resolve from the
`codeberg-mgf` index (PKG-06). No API change.

---

## [0.1.3] — 2026-06-01 — federation cohort: adopt mgf-common 0.44

PATCH: pin widened to `mgf-common>=0.41,<0.45` to accept the mgf-common 0.44 line
(which extracted the standards corpus + federation contract to the
`mgf-standard` sibling; pulled in transitively). `FEDERATION.md` stub +
`.claude/commands/sync.md` repointed at `mgf-standard`. No API change.

---

## [0.1.2] — 2026-05-28 — federation cohort publish (mgf-common 0.42.x)

Federation cohort wave: mgf-auth accepts **mgf-common 0.42.x** (pin widened to
`>=0.41,<0.43`) and ships to PyPI, carrying the previously-unpublished 0.1.1 work.

---

## [0.1.1] — 2026-05-28 — JWT/Svix bypass-attack regressions + test hardening

### Added

- Adopt `mgf-test-supervisor` + TS-04 + coverage gate (90%) + tier-0 smoke.
- JWT/Svix bypass-attack regression suite (13 tests): `alg=none`,
  RS256→HS256/384/512 confusion, tampered signature, forged claims, timestamp
  edges, webhook signature-tamper/stale-timestamp. The verifier rejected every
  attack (asserts 401 + that no principal leaked). No bypass found.
- `USERS.md` (DOC-16).

### Notes

- Test + dev-config only; no public API change. (`aud` remains unvalidated —
  noted inline as potential future hardening.)

---

## [0.1.0] — 2026-05-28 — maiden voyage

> **Initial extraction from PlasmaMapper** after its core re-design
> ISP-split the auth provider (ADR-016). PlasmaMapper is consumer #1.

### Added

- **`SessionVerifier[P]` / `WebhookVerifier`** — the two
  `@runtime_checkable` seams. `SessionVerifier` is **generic over
  the principal type** `P`: the JWT mechanics live here, but identity
  resolution (provider ids → your principal) is the consumer's
  `principal_resolver`, so no role/identity model is imposed.
- **`WebhookEvent`** — the verified-webhook DTO (`event_type`,
  `event_id`, `payload`, `received_at`).
- **`InvalidSessionError` / `InvalidWebhookSignatureError`** — typed
  **401** errors, subclassing `mgf.common`'s `HttpUnauthorizedError`.
- **`mgf.auth.clerk_session.ClerkSessionVerifier` / `ClerkClaims`** —
  Clerk session-JWT verification via PyJWT, gated behind the
  `[clerk]` extra so importing `mgf.auth` pulls no vendor SDK
  (import-linter-enforced).
- **`mgf.auth.clerk_webhook.ClerkWebhookVerifier`** — Svix-Signature
  HMAC-SHA256 webhook verification over `<id>.<ts>.<body>`,
  stdlib-only (no vendor dependency).
- **`MockSessionVerifier[P]` / `MockWebhookVerifier`** — in-process
  test doubles (`add_session`; `configure_webhook_secret` + a
  `sign()` helper) so consumer tests need no Clerk and no network.
- **`RevocationGate`** — composes a verifier with a consumer-supplied
  revocation check (session revocation itself stays a consumer
  concern, being DB-coupled and app-specific).
- **build-from-settings** — wiring helper to construct verifiers from
  consumer settings.

### Engineering

- PEP 420 namespace package (`src/mgf/`); coexists with the other
  `mgf.*` siblings.
- `mgf-common>=0.41,<0.42` runtime dependency. AP-03 0.x window pin
  discipline applies — bump in lock-step with mgf-common's next
  minor.
- Generic core (`_protocols` / `_events` / `_errors` / `mock`) is
  forbidden by import-linter from importing the Clerk adapter, so the
  vendor SDK (`pyjwt`) stays behind the `[clerk]` extra.
