Add LambdaAuth for ALB Lambda integration

[gillespied]

Summary

• New LambdaAuth class for AWS Lambda functions behind an Application Load Balancer with OIDC (Cognito) authentication
• Extracts OIDC headers from ALB Lambda events, verifies tokens, checks authorisation rules
• Simple API: get_auth_user(event) returns a User or raises, leaving response handling to the caller

Usage

from cognito_auth.lambda_auth import LambdaAuth
from cognito_auth import Authoriser

authoriser = Authoriser.from_lists(allowed_groups=["developers"])
auth = LambdaAuth(authoriser=authoriser)

def handler(event, context):
    try:
        user = auth.get_auth_user(event)
    except Exception:
        return {
            "statusCode": 302,
            "headers": {"Location": auth.redirect_url},
            "body": "",
        }

    return {"statusCode": 200, "body": f"Hello {user.email}!"}

Changes

File	Change
src/cognito_auth/lambda_auth.py	New LambdaAuth(BaseAuth) class with get_auth_user(event)
tests/cognito_auth/test_lambda_auth.py	8 tests covering success, missing headers, empty event, unauthorised, exception propagation, real event structure, and dev mode
docs/api/lambda-auth.md	Full documentation with quick start, configuration, behaviour, and examples
mkdocs.yml	Added LambdaAuth to nav
AGENTS.md	Added lambda_auth.py to package structure
pyproject.toml	Version bump to 0.3.2

Testing

All 159 tests pass (151 existing + 8 new). Linting clean.