feat(auth): add JWT verification and OAuth client credentials - #8469

Add JWT verification, coordinated JWKS caching, API Gateway authorization, and OAuth client credentials with optional dependencies, documentation, examples, and tests.

Include exception-safe claims cleanup, sanitized provider errors, and lazy imports for OAuth-only clients and static-key verification.

Issue number: closes #8466

Summary

Changes

• Add strict asymmetric JWT verification with mandatory issuer, resource audience, and expiration checks; additive claim requirements; static keys; OIDC discovery; and coordinated JWKS refresh with maximum age, unknown-key cooldown, and failure backoff.
• Add resource-bound Cognito access-token verification, explicit multi-issuer composition, initialization prefetch, and a testing helper.
• Integrate with Event Handler middleware and REST/HTTP API Gateway authorizers, including scope checks, exception-safe claims cleanup, sanitized errors, opt-in scalar context, and policies restricted to the current request.
• Add OAuth client credentials using client_secret_basic, per-resource token caches, callable secrets, coordinated acquisition, bounded retries, and authenticated HTTPS requests.
• Load the public classes independently so OAuth-only functions avoid JWT/cryptography imports, and static-key verifiers avoid loading HTTP transport. Public imports, introspection, and verification behavior are preserved.
• Add 236 functional tests and 15 local HTTPS integration tests, API documentation, usage examples, and REST/HTTP SAM authorizer configuration with result caching disabled.
• Declare PyJWT, cryptography, and urllib3 as optional dependencies, update the lock file, and add dependency-isolation coverage.

User experience

Applications configure the issuer, resource audience, and permitted algorithms, then use verify() directly, attach require() to a route, or return authorize() from a Lambda authorizer. Outbound clients use auth_headers() with their own HTTP client or call request() for a separate downstream resource.

verifier = JWTVerifier(
    issuer="https://idp.example.com/",
    audience="https://orders.example.com",
    algorithms=["RS256"],
    required_claims=["sub"],
)

@app.get("/orders", middlewares=[verifier.require(scopes=["orders:read"])])
def orders():
    return {"subject": app.context["claims"]["sub"]}

Validation

Functional tests use real asymmetric signatures and in-memory HTTP endpoints, without external services. They cover expiration and key removal, failed refresh, concurrent acquisition, async thread offloading during initial fetch/expiry/rotation, Cognito token purpose and resource binding, authorizer event fixtures, scope precedence, secret rotation, retry limits, and error redaction.

Regression tests exercise an unhandled protected handler followed by public, denied, and authenticated invocations, verifying that claims never survive the failed request. Error tests inspect __context__, __cause__, rendered tracebacks, and Powertools Logger output for public verification, prefetch, authorizer, and OAuth operations, including failing secret loaders invoked inside an existing exception handler.

Fresh-process tests block JWT/cryptography imports while constructing an OAuth client, and block urllib3 while verifying valid and invalid signatures against static JWKS. They also check that remote-cache construction loads the transport and that public exports retain introspection, unknown-attribute errors, and star-import behavior. Four of these checks failed before the optimization; all five pass afterward.

HTTPS integration tests run the production urllib3 transport against a loopback TLS server with a generated test certificate. They verify discovery/JWKS retrieval, signed-token verification, token exchange and downstream authentication, untrusted-certificate rejection before credentials are sent, response-size limits, stalled and slowly arriving bodies, separate downstream timeouts, and redirect/retry behavior.

Additional deployment checks used the SAM example with temporary AWS-hosted HTTPS fixtures. They exercised REST and HTTP Gateway decisions, middleware challenges, disabled authorizer caching, OAuth acquisition/concurrency/downstream requests, exception cleanup, and remote key rotation/removal/outages on both architectures. A real HTTP API $default route supplied a concrete method/path ARN, which the existing IAM helper successfully authorized. All three test stacks were deleted, with resource cleanup independently verified. These checks ran through a standalone harness; they do not represent the entire repository's AWS end-to-end suite or live Cognito/Keycloak interoperability testing.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.