byoi 0.1.0a1__py3-none-any.whl

byoi/__init__.py

@@ -0,0 +1,233 @@
+"""BYOI - Bring Your Own Identity.
+
+A server library for FastAPI applications that provides OIDC authentication
+with support for multiple identity providers.
+
+Features:
+- PKCE (Proof Key for Code Exchange) - Prevent authorization code interception attacks
+- ID Token Validation - Full JWT validation with JWKS fetching and caching
+- Identity Linking - Users can link multiple providers (Google + Microsoft, etc.)
+- Nonce Validation - Prevents replay attacks
+- Proper Error Handling - Clean error responses throughout
+- FastAPI dependencies
+
+Example:
+    ```python
+    from contextlib import asynccontextmanager
+    from fastapi import FastAPI
+    from byoi import BYOI, BYOIConfig, OIDCProviderConfig
+
+    # Create your repository implementations
+    user_repo = MyUserRepository()
+    identity_repo = MyIdentityRepository()
+    auth_state_repo = MyAuthStateRepository()
+
+    # Configure BYOI
+    config = BYOIConfig(
+        user_repository=user_repo,
+        identity_repository=identity_repo,
+        auth_state_repository=auth_state_repo,
+        providers=[
+            OIDCProviderConfig(
+                name="google",
+                display_name="Google",
+                issuer="https://accounts.google.com",
+                client_id="your-client-id",
+                client_secret="your-client-secret",
+            ),
+        ],
+    )
+
+    byoi = BYOI(config)
+    app = FastAPI(lifespan=byoi.lifespan)
+
+    @app.post("/auth/login")
+    async def login(
+        request: TokenExchangeRequest,
+        auth_service: AuthServiceDep,
+    ):
+        return await auth_service.authenticate(request)
+    ```
+"""
+
+from byoi.cache import (
+    CacheProtocol,
+    InMemoryCache,
+    NullCache,
+    RedisCache,
+)
+from byoi.config import BYOI, BYOIConfig
+from byoi.dependencies import (
+    AuthServiceDep,
+    ProviderManagerDep,
+    create_auth_service_dependency,
+    create_provider_manager_dependency,
+    get_auth_service,
+    get_provider_manager,
+)
+from byoi.errors import (
+    AuthenticationError,
+    BYOIError,
+    CacheError,
+    CannotUnlinkLastIdentityError,
+    ConfigurationError,
+    IdentityAlreadyLinkedError,
+    IdentityError,
+    IdentityNotFoundError,
+    InvalidAudienceError,
+    InvalidCodeError,
+    InvalidIssuerError,
+    InvalidNonceError,
+    InvalidStateError,
+    JWKSFetchError,
+    ProviderDiscoveryError,
+    ProviderError,
+    ProviderNotFoundError,
+    StateExpiredError,
+    TokenExchangeError,
+    TokenExpiredError,
+    TokenRefreshError,
+    TokenValidationError,
+    UserNotFoundError,
+)
+from byoi.models import (
+    AuthenticatedUser,
+    AuthorizationRequest,
+    AuthorizationResponse,
+    ClientType,
+    IdentityInfo,
+    LinkedIdentityInfo,
+    LinkIdentityRequest,
+    OIDCProviderConfig,
+    OIDCProviderInfo,
+    TokenExchangeRequest,
+    TokenExchangeResponse,
+    TokenRefreshRequest,
+    TokenRefreshResponse,
+    UnlinkIdentityRequest,
+    UserIdentities,
+)
+from byoi.pkce import (
+    PKCEChallenge,
+    generate_code_challenge,
+    generate_code_verifier,
+    generate_nonce,
+    generate_pkce_pair,
+    generate_state,
+)
+from byoi.providers import OIDCDiscoveryDocument, ProviderManager
+from byoi.repositories import (
+    AuthStateRepositoryProtocol,
+    LinkedIdentityRepositoryProtocol,
+    UserRepositoryProtocol,
+)
+from byoi.service import AuthService
+from byoi.telemetry import (
+    configure_tracing,
+    get_tracer,
+    is_tracing_available,
+    span_context,
+    traced,
+    traced_async,
+)
+from byoi.tokens import TokenValidator, validate_id_token
+from byoi.types import (
+    AuthStateProtocol,
+    LinkedIdentityProtocol,
+    UserProtocol,
+)
+
+__version__ = "0.1.0a1"
+
+__all__ = (
+    # Version
+    "__version__",
+    # Main Configuration
+    "BYOI",
+    "BYOIConfig",
+    # Services
+    "AuthService",
+    "ProviderManager",
+    "TokenValidator",
+    # Cache
+    "CacheProtocol",
+    "InMemoryCache",
+    "RedisCache",
+    "NullCache",
+    # Protocols (for implementing applications)
+    "UserProtocol",
+    "LinkedIdentityProtocol",
+    "AuthStateProtocol",
+    # Repository Protocols
+    "UserRepositoryProtocol",
+    "LinkedIdentityRepositoryProtocol",
+    "AuthStateRepositoryProtocol",
+    # Pydantic Models - Provider
+    "OIDCProviderConfig",
+    "OIDCProviderInfo",
+    "OIDCDiscoveryDocument",
+    # Pydantic Models - Auth Flow
+    "AuthorizationRequest",
+    "AuthorizationResponse",
+    "TokenExchangeRequest",
+    "TokenExchangeResponse",
+    "TokenRefreshRequest",
+    "TokenRefreshResponse",
+    # Pydantic Models - Identity
+    "IdentityInfo",
+    "LinkedIdentityInfo",
+    "LinkIdentityRequest",
+    "UnlinkIdentityRequest",
+    # Pydantic Models - User
+    "AuthenticatedUser",
+    "UserIdentities",
+    # Enums
+    "ClientType",
+    # PKCE Utilities
+    "PKCEChallenge",
+    "generate_code_verifier",
+    "generate_code_challenge",
+    "generate_pkce_pair",
+    "generate_state",
+    "generate_nonce",
+    # Token Validation
+    "validate_id_token",
+    # Telemetry
+    "configure_tracing",
+    "get_tracer",
+    "is_tracing_available",
+    "span_context",
+    "traced",
+    "traced_async",
+    # FastAPI Dependencies
+    "get_provider_manager",
+    "get_auth_service",
+    "ProviderManagerDep",
+    "AuthServiceDep",
+    "create_provider_manager_dependency",
+    "create_auth_service_dependency",
+    # Errors
+    "BYOIError",
+    "ConfigurationError",
+    "ProviderError",
+    "ProviderNotFoundError",
+    "ProviderDiscoveryError",
+    "AuthenticationError",
+    "InvalidStateError",
+    "StateExpiredError",
+    "InvalidCodeError",
+    "TokenExchangeError",
+    "TokenRefreshError",
+    "TokenValidationError",
+    "InvalidNonceError",
+    "InvalidIssuerError",
+    "InvalidAudienceError",
+    "TokenExpiredError",
+    "JWKSFetchError",
+    "IdentityError",
+    "IdentityAlreadyLinkedError",
+    "IdentityNotFoundError",
+    "CannotUnlinkLastIdentityError",
+    "UserNotFoundError",
+    "CacheError",
+)

byoi/__main__.py

@@ -0,0 +1,228 @@
+"""Command-line interface for BYOI utilities.
+
+This module provides CLI commands for BYOI operations, including PKCE generation.
+
+Usage:
+    python -m byoi pkce [--length LENGTH] [--method METHOD] [--json]
+"""
+
+import argparse
+import json
+import sys
+
+from byoi.pkce import (
+    generate_nonce,
+    generate_pkce_pair,
+    generate_state,
+)
+
+
+def pkce_command(args: argparse.Namespace) -> int:
+    """Generate PKCE code verifier and challenge.
+
+    Args:
+        args: Parsed command line arguments.
+
+    Returns:
+        Exit code (0 for success).
+    """
+    try:
+        pkce = generate_pkce_pair(
+            verifier_length=args.length,
+            method=args.method,
+        )
+
+        if args.json:
+            output = {
+                "code_verifier": pkce.code_verifier,
+                "code_challenge": pkce.code_challenge,
+                "code_challenge_method": pkce.code_challenge_method,
+            }
+            if args.state:
+                output["state"] = generate_state()
+            if args.nonce:
+                output["nonce"] = generate_nonce()
+            print(json.dumps(output, indent=2))
+        else:
+            print(f"Code Verifier: {pkce.code_verifier}")
+            print(f"Code Challenge: {pkce.code_challenge}")
+            print(f"Code Challenge Method: {pkce.code_challenge_method}")
+            if args.state:
+                print(f"State: {generate_state()}")
+            if args.nonce:
+                print(f"Nonce: {generate_nonce()}")
+
+        return 0
+
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def state_command(args: argparse.Namespace) -> int:
+    """Generate an OAuth state parameter.
+
+    Args:
+        args: Parsed command line arguments.
+
+    Returns:
+        Exit code (0 for success).
+    """
+    try:
+        state = generate_state(length=args.length)
+
+        if args.json:
+            print(json.dumps({"state": state}, indent=2))
+        else:
+            print(f"State: {state}")
+
+        return 0
+
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def nonce_command(args: argparse.Namespace) -> int:
+    """Generate a nonce for ID token validation.
+
+    Args:
+        args: Parsed command line arguments.
+
+    Returns:
+        Exit code (0 for success).
+    """
+    try:
+        nonce = generate_nonce(length=args.length)
+
+        if args.json:
+            print(json.dumps({"nonce": nonce}, indent=2))
+        else:
+            print(f"Nonce: {nonce}")
+
+        return 0
+
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser for the CLI.
+
+    Returns:
+        The configured argument parser.
+    """
+    parser = argparse.ArgumentParser(
+        prog="byoi",
+        description="BYOI - Bring Your Own Identity CLI utilities",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 0.1.0a1",
+    )
+
+    subparsers = parser.add_subparsers(
+        title="commands",
+        description="Available commands",
+        dest="command",
+    )
+
+    # PKCE command
+    pkce_parser = subparsers.add_parser(
+        "pkce",
+        help="Generate PKCE code verifier and challenge",
+        description="Generate a PKCE code verifier and challenge pair for OAuth 2.0 PKCE flow.",
+    )
+    pkce_parser.add_argument(
+        "--length",
+        type=int,
+        default=64,
+        help="Length of the code verifier (43-128, default: 64)",
+    )
+    pkce_parser.add_argument(
+        "--method",
+        choices=["S256", "plain"],
+        default="S256",
+        help="Code challenge method (default: S256)",
+    )
+    pkce_parser.add_argument(
+        "--state",
+        action="store_true",
+        help="Also generate a state parameter",
+    )
+    pkce_parser.add_argument(
+        "--nonce",
+        action="store_true",
+        help="Also generate a nonce",
+    )
+    pkce_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+    pkce_parser.set_defaults(func=pkce_command)
+
+    # State command
+    state_parser = subparsers.add_parser(
+        "state",
+        help="Generate an OAuth state parameter",
+        description="Generate a cryptographically random state parameter for OAuth 2.0.",
+    )
+    state_parser.add_argument(
+        "--length",
+        type=int,
+        default=32,
+        help="Length of the state parameter (minimum 16, default: 32)",
+    )
+    state_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+    state_parser.set_defaults(func=state_command)
+
+    # Nonce command
+    nonce_parser = subparsers.add_parser(
+        "nonce",
+        help="Generate a nonce for ID token validation",
+        description="Generate a cryptographically random nonce for OIDC ID token validation.",
+    )
+    nonce_parser.add_argument(
+        "--length",
+        type=int,
+        default=32,
+        help="Length of the nonce (minimum 16, default: 32)",
+    )
+    nonce_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output in JSON format",
+    )
+    nonce_parser.set_defaults(func=nonce_command)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for the CLI.
+
+    Args:
+        argv: Command line arguments (defaults to sys.argv[1:]).
+
+    Returns:
+        Exit code.
+    """
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())