# `mgf-auth` — scope policy

> `mgf-auth`'s **scope policy** (family **SP**) — what belongs in this auth-verifier
> seam library. A proposed addition is in scope only if it passes the §3 gate.

## §1 In scope (SP-01)

Verification seams + a vendor adapter for mgf-common consumers:

- ISP-split verifier **Protocols**: `SessionVerifier` (verify a session token →
  principal), `WebhookVerifier` (verify a signed webhook → typed event)
- a **Clerk adapter**: session-JWT verification (PyJWT, RS256, alg-pinned) +
  Svix-webhook signature verification (stdlib HMAC, replay-windowed)
- typed **401 errors** (`InvalidSessionError`, `InvalidWebhookSignatureError`)
- **mock** verifiers for consumer tests

The boundary: **verify a credential someone else issued, behind a swappable seam.**

## §2 Out of scope (SP-02) — with reasons

| Not here | Why | Where instead |
|---|---|---|
| Issuing / minting tokens | the IdP's job, not the verifier's | Clerk / your IdP |
| User / identity storage | consumer's domain database | the consumer app |
| Session lifecycle (refresh, logout) | consumer/IdP concern | Clerk SDK / the app |
| OAuth/OIDC flow orchestration | a flow library, not a verifier | `authlib` / the IdP SDK |
| Authorization / RBAC / permissions | this is authN, not authZ | the consumer's policy layer |
| A general-purpose JWT library | we pin Clerk's verification shape | `pyjwt` directly |

## §3 Scope-creep gate (SP-03)

A PR adding a module/helper MUST answer: (1) is it credential *verification* (else
out)? (2) does it keep the generic core free of vendor SDKs (the import-linter
contract)? (3) is there a consumer demand signal? Any "no/unclear" blocks it.

## §4 Adjacent scope (SP-04)

Adjacent (not yet in): an Authentik session adapter (named in the module docstrings
as the Phase-8 fallback), an API-key verifier, a JWKS-rotation cache. Promote
adjacent → in only on a documented consumer demand signal (a consumer forking, or
≥2 consumers asking), never speculatively.

## §5 Alternatives for out-of-scope needs (SP-05)

Token issuance/sessions → Clerk (or your IdP); OAuth flows → `authlib`; raw JWT →
`pyjwt`; authorization → the consumer's policy layer; identity storage → the app DB.

## §6 Revisiting scope (SP-06)

Revisited at every **MAJOR** boundary; a major bump re-justifies the surface against
§1/§2 and re-affirms the verify-only / vendor-behind-a-seam invariants.
