Skip to content

# 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:

    1
    2
    3

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

Constraints:

    1

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

### Classes

### Functions

#### `` authenticate_request `async`

    1

    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:

    1

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

Guarantees:

    1

    - 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`

    1

    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:

    1

    - 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.