Introspection

jwtlib.introspection

Auth client and access-control utilities.

---

Summary

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

Notes

Responsibilities:

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

Constraints:

- This module intentionally does NOT: Parse HTTP requests or headers, implement authentication policies, or perform JWT signature verification locally.

Classes

Functions

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.

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	str | None	JWT access token provided by the caller.	required

Returns:

Type	Description
Optional[PublicUser]	PublicUser | None: PublicUser if authentication succeeds; 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

Responsibilities:

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

Guarantees:

- This function does not parse Authorization headers; callers must supply the raw token. Access-control policy is externalized via `should_skip_authentication`.

introspect_token async

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

Introspect a JWT using the external authentication service.

Parameters:

Name	Type	Description	Default
token	str	JWT access token to introspect.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary containing the authenticated user's public payload.

Raises:

Type	Description
InvalidToken	If the token is missing, invalid, inactive, or revoked.
AuthServiceUnavailable	If the auth service cannot be reached or fails unexpectedly.

Notes

Guarantees:

- This function treats the auth service as the source of truth. No local JWT validation or signature checking is performed here. The returned payload is expected to be safe for public exposure.