ISP-split auth verifier seams for mgf-common consumers — a generic SessionVerifier + WebhookVerifier, a Clerk adapter (session-JWT + Svix-webhook), typed 401 errors, and mocks. Sibling of mgf-common under the mgf.* namespace.
Project description
mgf-auth
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. A sibling of mgf-common under the mgf.* namespace.
Extracted from PlasmaMapper after its core re-design ISP-split the auth
provider (ADR-016). A consumer keeps its own role-typed principal —
SessionVerifier is generic over the principal type; identity
resolution (Clerk ids → your principal) is your principal_resolver.
Install
pip install "mgf-auth[clerk]" # [clerk] adds pyjwt for the session adapter
Use
from mgf.auth.clerk_session import ClerkSessionVerifier, ClerkClaims
from mgf.auth.clerk_webhook import ClerkWebhookVerifier
async def resolve(claims: ClerkClaims) -> MyPrincipal:
return MyPrincipal(user_id=uuid5(NS, claims.sub), role=map_role(claims.org_role), ...)
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) # -> MyPrincipal
webhook_verifier = ClerkWebhookVerifier(webhook_secret=b"whsec_...")
event = await webhook_verifier.verify_webhook(headers, raw_body) # -> WebhookEvent
Tests use MockSessionVerifier[MyPrincipal]() (add_session) and
MockWebhookVerifier() (configure_webhook_secret + the sign()
helper) — no Clerk, no network.
What's in it
| Name | What |
|---|---|
SessionVerifier / WebhookVerifier |
the two @runtime_checkable seams (session is generic over P) |
WebhookEvent |
the verified-webhook DTO (event_type, event_id, payload, received_at) |
InvalidSessionError / InvalidWebhookSignatureError |
typed 401 errors (subclass mgf.common HttpUnauthorizedError) |
mgf.auth.clerk_session.ClerkSessionVerifier / ClerkClaims |
PyJWT session verification ([clerk] extra) |
mgf.auth.clerk_webhook.ClerkWebhookVerifier |
Svix-Signature HMAC webhook verification (stdlib) |
MockSessionVerifier / MockWebhookVerifier |
in-process test doubles |
Design
- Generic over the principal (
SessionVerifier[P]): the JWT mechanics live here; the consumer'sprincipal_resolverproduces its own principal shape — no imposed role/identity model. - Vendor SDK behind an extra: importing
mgf.authpulls nopyjwt(import-linter-enforced); the Clerk session adapter is the only place that needs it. - Webhook side is stdlib-only (HMAC-SHA256 over
<id>.<ts>.<body>). - Session revocation (checking a
revoked_sessionstable) is a consumer concern — it's DB-coupled and app-specific, so it stays in the consumer, not here.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mgf_auth-0.1.2.tar.gz.
File metadata
- Download URL: mgf_auth-0.1.2.tar.gz
- Upload date:
- Size: 107.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.10.8 {"installer":{"name":"uv","version":"0.10.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
17c49f55b153c21aeaa813916d2905aeae5af6722d0648c8aab42c722bf73db3
|
|
| MD5 |
4c8e35e43af736a48ddc6410f817be9f
|
|
| BLAKE2b-256 |
f6d8dbb098d95dec6a82dba76a4b38fa0f71ffbbace7c0e6c5a710659cb2da63
|
File details
Details for the file mgf_auth-0.1.2-py3-none-any.whl.
File metadata
- Download URL: mgf_auth-0.1.2-py3-none-any.whl
- Upload date:
- Size: 15.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.10.8 {"installer":{"name":"uv","version":"0.10.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1dc409d39af4e60bd4327e441284a9efb2c380e3aa588ce9bc9080093b54990e
|
|
| MD5 |
1bca1cfec190e9e776f74898df7a1410
|
|
| BLAKE2b-256 |
2d1506ee9038b7fd79cc5be22628dd64b3bb253a613a103dfb4194b2a72d3906
|
