kKjIdZddlmZddlZddlmZddlZddlmZddl m Z ddl m Z ddl mZdd lmZdd lmZdd lmZeeZGd d e ZGddeZy)aClerk OAuth provider for FastMCP. This module provides a complete Clerk OAuth integration that's ready to use with a Clerk domain, client ID, and client secret. It handles all the complexity of Clerk's OAuth/OIDC flow, token validation, and user management. Clerk uses standard OIDC endpoints derived from the instance domain (e.g., ``https://.clerk.accounts.dev``). Token verification is performed via the introspection endpoint (RFC 7662) for security-critical checks (active status, audience, scopes), followed by the userinfo endpoint for profile enrichment. Userinfo failure is non-fatal. Example: ```python from fastmcp import FastMCP from fastmcp.server.auth.providers.clerk import ClerkProvider auth = ClerkProvider( domain="saving-primate-16.clerk.accounts.dev", client_id="your-clerk-client-id", client_secret="your-clerk-client-secret", base_url="https://my-server.com", ) mcp = FastMCP("My Protected Server", auth=auth) ``` ) annotationsN)Literal) AsyncKeyValue) AnyHttpUrl) TokenVerifier) AccessToken) OAuthProxy) parse_scopes) get_loggercPeZdZdZdddddd dfdZddZxZS) ClerkTokenVerifieruToken verifier for Clerk OAuth tokens. Clerk issues standard OIDC tokens. Verification uses the introspection endpoint (RFC 7662) as the primary security gate — it confirms the token is active and provides metadata (scopes, expiry, audience). The userinfo endpoint is called second for profile enrichment (name, email, picture) and its failure is non-fatal. When a ``client_id`` is configured, the audience from introspection is validated against it. When ``required_scopes`` are configured, introspection must return the token's scopes — the verifier will not assume scopes when introspection is unavailable. N ) client_id client_secretrequired_scopestimeout_seconds http_clientct|||jd|_||_||_||_||_d|jd|_d|jd|_ y)aInitialize the Clerk token verifier. Args: domain: Clerk instance domain (e.g., "saving-primate-16.clerk.accounts.dev") client_id: Clerk OAuth client ID, used for introspection endpoint authentication client_secret: Clerk OAuth client secret, used for introspection endpoint authentication required_scopes: Required OAuth scopes (e.g., ["openid", "email", "profile"]) timeout_seconds: HTTP request timeout http_client: Optional httpx.AsyncClient for connection pooling. When provided, the client is reused across calls and the caller is responsible for its lifecycle. When None (default), a fresh client is created per call. )r/https://z/oauth/userinfoz/oauth/token_infoN) super__init__rstripdomain _client_id_client_secretr _http_client _userinfo_url_introspection_url)selfrrrrrr __class__s t/Users/ahmed/devFolder/Ultron/claude-voice/.venv/lib/python3.12/site-packages/fastmcp/server/auth/providers/clerk.pyrzClerkTokenVerifier.__init__>so, 9mmC( #+.'' }OD$,T[[M9J"Kc K |jtj|jntj|j 4d{}d|i}|ddid}|j r(|jr|j |jf|d<n|j r|j |d<|j|jfi|d{}|jd k7r2tjd |j dddd{y|j}d |vs|d s'tjd  dddd{y|jd d}|r|jng}|jdxs|jd} d} |jd} | 2tj t"t$5t'| } ddd|j rB| |j k7r3tjd| |j  dddd{y|j(r|s2tjd|j( dddd{yt+|} t+|j(} | j-| s)tjd| |  dddd{y|jd}i} |j|j.d|ddd{}|jd k(r#|j}|s|jd}|s'tjd dddd{yt3|| xs||| || |jd|jd|jd|jd|jd|jd|jd |jd!|xsdd" #}tjd$||cdddd{S77a7$7#1swY]xYw7777G#t0$r!}tjd|Yd}~8d}~wwxYw77Z#1d{7swYyxYw#tj4$r }tjd%|Yd}~yd}~wt0$r }tjd&|Yd}~yd}~wwxYww)'aGVerify a Clerk OAuth token via introspection and userinfo. Calls the introspection endpoint first to validate the token and retrieve auth metadata (active status, scopes, expiry, audience). If the token passes security checks, the userinfo endpoint is called for profile enrichment. Userinfo failure is non-fatal. When a ``client_id`` is configured, the token's audience must match it. When ``required_scopes`` are configured, introspection must confirm them; tokens are rejected if scope information is unavailable. N)timeouttoken User-AgentzFastMCP-Clerk-OAuth)dataheadersauthrzClerk introspection failed: %dactivez=Clerk introspection: token inactive or missing 'active' fieldscopeaudexpz2Clerk token audience mismatch: got %s, expected %szGClerk token missing scope information; cannot verify required scopes %sz5Clerk token missing required scopes. Has %s, needs %ssubzBearer ) Authorizationr')r)zClerk userinfo call failed: %szClerk token missing 'sub' claimemailemail_verifiednamepicture given_name family_namepreferred_usernameiss) r1r/r3r4r5r6r7r8r9r:clerk_user_data)r&rscopes expires_atclaimsz,Clerk token verified successfully for sub=%sz Failed to verify Clerk token: %sz"Clerk token verification error: %s)r contextlib nullcontexthttpx AsyncClientrrrpostr status_codeloggerdebugjsongetsplitsuppress ValueError TypeErrorintrsetissubsetr Exceptionr RequestError)r r&clientintrospect_data_payloadintrospect_kwargsintrospect_responseintrospect_data scope_str token_scopesr/r=r0token_scopes_setrequired_scopes_setr1 user_datauserinfo_responsee access_tokens r" verify_tokenzClerkTokenVerifier.verify_token^sC $$0&&t'8'89&&t/C/CDEE29%0@'3 ,.CD+! ??t':':++1%f-__;???+K8,7FKK++-'-'# '22c9LL8+77 =EEE@#6":":"<?2/(:SLLW QEEET,//< 4=y02 %))%0TO4G4G 4T)- %))%0?#,,ZC%(X D??sdoo'=LLL  wEEEz''' ? 00 $IEEEJ(+<'8$*-d.B.B*C'.778HI S,/ $[EEEb&))%0"$  F.4jj**/6ug->*?!/9/)%)44;$5$:$:$< ""+--"6CLL!BCIEEEL +!jS')""!*w!7*3--8H*I ) f 5#,==#;&/mmL&A'0}}]'C.7mm|jd}| t|ngd}| t| nd}t||||| |}|r t|ni}t|d|dd|d|||||||xs|| | | |||||||xsd||t jd ||y) a[Initialize Clerk OAuth provider. Args: domain: Clerk instance domain (e.g., "saving-primate-16.clerk.accounts.dev"). This is used to derive all OAuth/OIDC endpoint URLs. client_id: Clerk OAuth application client ID client_secret: Clerk OAuth application client secret. Optional for PKCE public clients. When omitted, jwt_signing_key must be provided. base_url: Public URL where OAuth endpoints will be accessible (includes any mount path) resource_base_url: Optional public base URL for the protected resource metadata and token audience. Defaults to ``base_url``. issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL to avoid 404s during discovery when mounting under a path. redirect_path: Redirect path configured in Clerk OAuth app (defaults to "/auth/callback") required_scopes: Required Clerk scopes (defaults to ["openid", "email", "profile"]). Clerk supports: "openid", "email", "profile", "public_metadata", "private_metadata", "offline_access". valid_scopes: All scopes that clients are allowed to request, advertised through well-known endpoints. Defaults to required_scopes if not provided. timeout_seconds: HTTP request timeout for Clerk API calls (defaults to 10) allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients. If None (default), all URIs are allowed. If empty list, no URIs are allowed. client_storage: Storage backend for OAuth state (client registrations, encrypted tokens). If None, an encrypted file store will be created in the data directory (derived from ``platformdirs``). jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided, they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2. require_authorization_consent: Whether to require user consent before authorizing clients (default True). When "external", the built-in consent screen is skipped but no warning is logged, indicating that consent is handled externally by Clerk. consent_csp_policy: Custom CSP policy for the consent page. extra_authorize_params: Additional parameters to forward to Clerk's authorization endpoint. Example: {"prompt": "login"} to force re-authentication. http_client: Optional httpx.AsyncClient for connection pooling in token verification. When provided, the client is reused across verify_token calls and the caller is responsible for its lifecycle. When None (default), a fresh client is created per call. enable_cimd: Enable CIMD (Client ID Metadata Document) support for URL-based client IDs (default True). Set to False to disable. fallback_refresh_token_expiry_seconds: Lifetime for the FastMCP-issued refresh token when the upstream provider omits `refresh_expires_in` (e.g. Cognito, GitHub, many OIDC IdPs). Defaults to 1 year. The upstream refresh remains the source of truth. See `OAuthProxy` for details. fastmcp_access_token_expiry_seconds: Lifetime for the FastMCP-issued access token, decoupling it from the upstream provider's `expires_in`. Defaults to None (mirror the upstream lifetime). Set this for bridges whose upstream issues short-lived access tokens that some MCP clients can't refresh gracefully (e.g. `mcp-remote`). See `OAuthProxy` for details. token_expiry_threshold_seconds: Number of seconds before actual expiry to treat a token as expired, refreshing early to avoid races. Defaults to 0. rN)openidr3profile)rrrrrrrz/oauth/authorizez /oauth/token)upstream_authorization_endpointupstream_token_endpointupstream_client_idupstream_client_secrettoken_verifierbase_urlrmrornrqrrrsrtrurvrwrxryrzrpr{z>Initialized Clerk OAuth provider for domain %s with scopes: %s)rr r dictrrrErF)r rrrrrmrnrorrprrqrrrsrtrurvrwrxryrzrr{required_scopes_finalparsed_valid_scopesrextra_authorize_params_finalr!s r"rzClerkProvider.__init__s^s#*  )/ +7*BL & ,'1+#  -CD' ( % .6vh>N,O&.vhl$C(#0)/'!-X)E)+*G1-2W0S+I#?#G4,#+  0  L  ! r#),rr`rr`rrarzAnyHttpUrl | strrmAnyHttpUrl | str | NonernrrorarrbrprbrrMrqrbrrzAsyncKeyValue | Nonerszstr | bytes | Nonertz&bool | Literal['remember', 'external']rurarvboolrw int | NonerxrryrMrzzdict[str, str] | Nonerrcr{r)rerfrgrhrrirjs@r"rlrlsCJ%)59.2$(,0)-!9=/3.2PT)-!%<@:>./8<04 1D D  D " D # D 3D ,D "D *D 'D D '7D -D ,D (N!D "'#D $%D &0:'D (.8)D *),+D ,!6-D ../D 01D D r#rl)rh __future__rr?typingrrAkey_value.aio.protocolsrpydanticrfastmcp.server.authrfastmcp.server.auth.authrfastmcp.server.auth.oauth_proxyr fastmcp.utilities.authr fastmcp.utilities.loggingr rerEr rlr#r"rsT8# 1-06/0 H ~~Be Je r#