Introspection

jwtlib.introspection

Auth client and access-control utilities.

This module provides pure authentication and authorization logic for validating JWTs via service-to-service introspection and resolving authenticated users.

Key characteristics: - No framework or HTTP routing dependencies - Async-first and fully typed - Designed for use by adapters (HTTP, CLI, background workers) - Delegates token validity decisions to an external auth service

Responsibilities: - Calling the auth service introspection endpoint - Translating introspection responses into typed user models - Enforcing access control decisions at the logic layer

This module does NOT: - Parse HTTP requests or headers - Implement authentication policies - Perform JWT signature verification locally

authenticate_request `async`

authenticate_request(should_skip_authentication: Callable[[str, str], bool], *, method: str, path: str, authorization_token: Optional[str]) -> Optional[PublicUser]

Authenticate an incoming request using token introspection.

Determines whether authentication should be skipped for the given request context and, if not, resolves the authenticated user via token introspection.

Parameters:

Name	Type	Description	Default
`should_skip_authentication`	`Callable[[str, str], bool]`	Callable that decides whether authentication is required for a given HTTP method and path.	required
`method`	`str`	HTTP method of the incoming request.	required
`path`	`str`	Request path.	required
`authorization_token`	`Optional[str]`	JWT access token provided by the caller.	required

Returns:

Type	Description
`Optional[PublicUser]`	PublicUser if authentication succeeds.
`Optional[PublicUser]`	None if authentication is skipped.

Raises:

Type	Description
`InvalidToken`	If authentication is required but the token is missing, invalid, or revoked.
`AuthServiceUnavailable`	If the auth service cannot be reached.

Notes

This function does not parse Authorization headers; callers must supply the raw token.
Access-control policy is externalized via should_skip_authentication.
The returned PublicUser contains no sensitive information.

introspect_token `async`

introspect_token(token: str) -> dict[str, Any]

Introspect a JWT using the external authentication service.

Sends the provided JWT to the configured auth service introspection endpoint and validates the response.