byoi 0.1.0a1__py3-none-any.whl

byoi/models.py

@@ -0,0 +1,451 @@
+"""Pydantic models for the BYOI library.
+
+These models define the input and output schemas for BYOI operations.
+They can be used directly in FastAPI route definitions.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+__all__ = (
+    # Enums
+    "ClientType",
+    # Provider Models
+    "OIDCProviderConfig",
+    "OIDCProviderInfo",
+    # Auth Flow Models
+    "AuthorizationRequest",
+    "AuthorizationResponse",
+    "TokenExchangeRequest",
+    "TokenExchangeResponse",
+    "TokenRefreshRequest",
+    "TokenRefreshResponse",
+    # Identity Models
+    "IdentityInfo",
+    "LinkedIdentityInfo",
+    "LinkIdentityRequest",
+    "UnlinkIdentityRequest",
+    # User Models
+    "AuthenticatedUser",
+    "UserIdentities",
+)
+
+
+class ClientType(str, Enum):
+    """Type of client initiating authentication."""
+
+    WEB = "web"
+    DESKTOP = "desktop"
+    MOBILE = "mobile"
+
+
+# =============================================================================
+# Provider Models
+# =============================================================================
+
+
+class OIDCProviderConfig(BaseModel):
+    """Configuration for an OIDC provider.
+
+    This model is used to register a provider with BYOI.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(
+        ...,
+        description="Unique name for this provider (e.g., 'google', 'microsoft'). "
+        "Must start with a letter and contain only lowercase letters, numbers, underscores, or hyphens.",
+        min_length=1,
+        max_length=64,
+    )
+    display_name: str = Field(
+        ...,
+        description="Human-readable name for display purposes",
+        min_length=1,
+        max_length=128,
+    )
+    issuer: str = Field(
+        ...,
+        description="The OIDC issuer URL (used to discover endpoints)",
+    )
+    client_id: str = Field(
+        ...,
+        description="OAuth client ID",
+        min_length=1,
+    )
+    client_secret: str | None = Field(
+        default=None,
+        description="OAuth client secret (not required for public clients)",
+    )
+    scopes: list[str] = Field(
+        default=["openid", "email", "profile"],
+        description="OAuth scopes to request",
+    )
+    extra_auth_params: dict[str, str] = Field(
+        default_factory=dict,
+        description="Extra parameters to include in the authorization request",
+    )
+    jwks_uri_override: str | None = Field(
+        default=None,
+        description="Override the JWKS URI from discovery",
+    )
+    authorization_endpoint_override: str | None = Field(
+        default=None,
+        description="Override the authorization endpoint from discovery",
+    )
+    token_endpoint_override: str | None = Field(
+        default=None,
+        description="Override the token endpoint from discovery",
+    )
+    userinfo_endpoint_override: str | None = Field(
+        default=None,
+        description="Override the userinfo endpoint from discovery",
+    )
+    audience: str | None = Field(
+        default=None,
+        description="Expected audience claim (defaults to client_id)",
+    )
+    clock_skew_seconds: int = Field(
+        default=60,
+        description="Allowed clock skew for token validation (seconds)",
+        ge=0,
+        le=300,
+    )
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate and normalize the provider name.
+
+        Automatically converts to lowercase and validates the format.
+        """
+        import re
+
+        if not isinstance(v, str):
+            raise ValueError("Provider name must be a string")
+
+        # Auto-lowercase for convenience
+        v = v.lower()
+
+        # Validate format
+        if not re.match(r"^[a-z][a-z0-9_-]*$", v):
+            raise ValueError(
+                f"Provider name '{v}' is invalid. "
+                "Name must start with a letter and contain only lowercase letters, "
+                "numbers, underscores, or hyphens (e.g., 'google', 'my-provider', 'auth_provider1')."
+            )
+
+        return v
+
+
+class OIDCProviderInfo(BaseModel):
+    """Public information about a configured OIDC provider."""
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(..., description="Unique name for this provider")
+    display_name: str = Field(..., description="Human-readable name")
+    issuer: str = Field(..., description="The OIDC issuer URL")
+
+
+# =============================================================================
+# Auth Flow Models
+# =============================================================================
+
+
+class AuthorizationRequest(BaseModel):
+    """Request to initiate an authorization flow."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_name: str = Field(
+        ...,
+        description="Name of the provider to use",
+    )
+    redirect_uri: str = Field(
+        ...,
+        description="URI to redirect to after authorization",
+    )
+    client_type: ClientType = Field(
+        default=ClientType.WEB,
+        description="Type of client initiating the request",
+    )
+    extra_data: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Extra data to store with the auth state",
+    )
+
+
+class AuthorizationResponse(BaseModel):
+    """Response containing the authorization URL and state."""
+
+    model_config = ConfigDict(frozen=True)
+
+    authorization_url: str = Field(
+        ...,
+        description="URL to redirect the user to for authorization",
+    )
+    state: str = Field(
+        ...,
+        description="State parameter (store this for validation)",
+    )
+    provider_name: str = Field(
+        ...,
+        description="Name of the provider",
+    )
+    expires_at: datetime = Field(
+        ...,
+        description="When this authorization request expires",
+    )
+
+
+class TokenExchangeRequest(BaseModel):
+    """Request to exchange an authorization code for tokens."""
+
+    model_config = ConfigDict(frozen=True)
+
+    code: str = Field(
+        ...,
+        description="The authorization code from the callback",
+        min_length=1,
+    )
+    state: str = Field(
+        ...,
+        description="The state parameter from the callback",
+        min_length=1,
+    )
+    redirect_uri: str = Field(
+        ...,
+        description="The redirect URI used in the authorization request",
+    )
+
+
+class TokenExchangeResponse(BaseModel):
+    """Response from a successful token exchange."""
+
+    model_config = ConfigDict(frozen=True)
+
+    identity: "IdentityInfo" = Field(
+        ...,
+        description="Identity information from the ID token",
+    )
+    access_token: str = Field(
+        ...,
+        description="The access token",
+    )
+    token_type: str = Field(
+        default="Bearer",
+        description="The token type",
+    )
+    expires_in: int | None = Field(
+        default=None,
+        description="Token expiration time in seconds",
+    )
+    refresh_token: str | None = Field(
+        default=None,
+        description="The refresh token (if provided)",
+    )
+    id_token: str = Field(
+        ...,
+        description="The raw ID token",
+    )
+
+
+class TokenRefreshRequest(BaseModel):
+    """Request to refresh an access token using a refresh token."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_name: str = Field(
+        ...,
+        description="Name of the provider that issued the token",
+        min_length=1,
+    )
+    refresh_token: str = Field(
+        ...,
+        description="The refresh token",
+        min_length=1,
+    )
+    scope: str | None = Field(
+        default=None,
+        description="Optional scope to request (defaults to original scope)",
+    )
+
+
+class TokenRefreshResponse(BaseModel):
+    """Response from a successful token refresh."""
+
+    model_config = ConfigDict(frozen=True)
+
+    access_token: str = Field(
+        ...,
+        description="The new access token",
+    )
+    token_type: str = Field(
+        default="Bearer",
+        description="The token type",
+    )
+    expires_in: int | None = Field(
+        default=None,
+        description="Token expiration time in seconds",
+    )
+    refresh_token: str | None = Field(
+        default=None,
+        description="The new refresh token (if rotated)",
+    )
+    scope: str | None = Field(
+        default=None,
+        description="The scope of the access token",
+    )
+    id_token: str | None = Field(
+        default=None,
+        description="New ID token (if provided by the provider)",
+    )
+
+
+# =============================================================================
+# Identity Models
+# =============================================================================
+
+
+class IdentityInfo(BaseModel):
+    """Identity information extracted from an ID token."""
+
+    model_config = ConfigDict(frozen=True)
+
+    provider_name: str = Field(
+        ...,
+        description="Name of the provider",
+    )
+    subject: str = Field(
+        ...,
+        description="Subject identifier (unique per provider)",
+    )
+    email: str | None = Field(
+        default=None,
+        description="Email address",
+    )
+    email_verified: bool = Field(
+        default=False,
+        description="Whether the email is verified",
+    )
+    name: str | None = Field(
+        default=None,
+        description="Full name",
+    )
+    given_name: str | None = Field(
+        default=None,
+        description="Given/first name",
+    )
+    family_name: str | None = Field(
+        default=None,
+        description="Family/last name",
+    )
+    picture: str | None = Field(
+        default=None,
+        description="URL to profile picture",
+    )
+    locale: str | None = Field(
+        default=None,
+        description="User's locale",
+    )
+    extra_claims: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional claims from the ID token",
+    )
+
+
+class LinkedIdentityInfo(BaseModel):
+    """Information about a linked identity."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str = Field(..., description="Unique identifier for this link")
+    provider_name: str = Field(..., description="Name of the provider")
+    provider_display_name: str = Field(..., description="Display name of the provider")
+    email: str | None = Field(default=None, description="Email associated with this identity")
+    created_at: datetime = Field(..., description="When this link was created")
+    last_used_at: datetime | None = Field(
+        default=None,
+        description="When this identity was last used",
+    )
+
+
+class LinkIdentityRequest(BaseModel):
+    """Request to link a new identity to an existing user."""
+
+    model_config = ConfigDict(frozen=True)
+
+    user_id: str = Field(
+        ...,
+        description="ID of the user to link the identity to",
+    )
+    code: str = Field(
+        ...,
+        description="The authorization code from the callback",
+    )
+    state: str = Field(
+        ...,
+        description="The state parameter from the callback",
+    )
+    redirect_uri: str = Field(
+        ...,
+        description="The redirect URI used in the authorization request",
+    )
+
+
+class UnlinkIdentityRequest(BaseModel):
+    """Request to unlink an identity from a user."""
+
+    model_config = ConfigDict(frozen=True)
+
+    user_id: str = Field(
+        ...,
+        description="ID of the user",
+    )
+    identity_id: str = Field(
+        ...,
+        description="ID of the linked identity to remove",
+    )
+
+
+# =============================================================================
+# User Models
+# =============================================================================
+
+
+class AuthenticatedUser(BaseModel):
+    """Information about an authenticated user."""
+
+    model_config = ConfigDict(frozen=True)
+
+    user_id: str = Field(..., description="Unique identifier for the user")
+    email: str | None = Field(default=None, description="User's email address")
+    is_new_user: bool = Field(
+        default=False,
+        description="Whether this is a newly created user",
+    )
+    identity: IdentityInfo = Field(
+        ...,
+        description="Identity information used for authentication",
+    )
+    linked_identity_id: str = Field(
+        ...,
+        description="ID of the linked identity used for authentication",
+    )
+
+
+class UserIdentities(BaseModel):
+    """All linked identities for a user."""
+
+    model_config = ConfigDict(frozen=True)
+
+    user_id: str = Field(..., description="User's unique identifier")
+    identities: list[LinkedIdentityInfo] = Field(
+        default_factory=list,
+        description="List of linked identities",
+    )

byoi/pkce.py

@@ -0,0 +1,144 @@
+"""PKCE (Proof Key for Code Exchange) utilities.
+
+Implements RFC 7636 for preventing authorization code interception attacks.
+"""
+
+import base64
+import hashlib
+import secrets
+from typing import NamedTuple
+
+__all__ = (
+    "PKCEChallenge",
+    "generate_code_verifier",
+    "generate_code_challenge",
+    "generate_pkce_pair",
+    "generate_state",
+    "generate_nonce",
+)
+
+
+class PKCEChallenge(NamedTuple):
+    """A PKCE code verifier and challenge pair."""
+
+    code_verifier: str
+    code_challenge: str
+    code_challenge_method: str
+
+
+def generate_code_verifier(length: int = 64) -> str:
+    """Generate a cryptographically random code verifier.
+
+    The code verifier is a high-entropy cryptographic random string
+    using unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+    with a minimum length of 43 characters and a maximum length of 128 characters.
+
+    Args:
+        length: Length of the code verifier (43-128 characters).
+
+    Returns:
+        A random code verifier string.
+
+    Raises:
+        ValueError: If length is not between 43 and 128.
+    """
+    if not 43 <= length <= 128:
+        raise ValueError("Code verifier length must be between 43 and 128 characters")
+
+    # Use URL-safe base64 encoding of random bytes
+    # We need to generate enough bytes to get the desired length after base64 encoding
+    # base64 encoding expands 3 bytes to 4 characters
+    num_bytes = (length * 3) // 4 + 1
+    random_bytes = secrets.token_bytes(num_bytes)
+    verifier = base64.urlsafe_b64encode(random_bytes).decode("ascii")
+
+    # Remove padding and truncate to desired length
+    verifier = verifier.replace("=", "")[:length]
+
+    return verifier
+
+
+def generate_code_challenge(code_verifier: str, method: str = "S256") -> str:
+    """Generate a code challenge from a code verifier.
+
+    Args:
+        code_verifier: The code verifier string.
+        method: Challenge method - "S256" (recommended) or "plain".
+
+    Returns:
+        The code challenge string.
+
+    Raises:
+        ValueError: If method is not "S256" or "plain".
+    """
+    if method == "S256":
+        # SHA256 hash of the code verifier, then base64url encode
+        digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+        challenge = base64.urlsafe_b64encode(digest).decode("ascii")
+        # Remove padding
+        return challenge.rstrip("=")
+    elif method == "plain":
+        # Plain method just returns the verifier as-is
+        return code_verifier
+    else:
+        raise ValueError(f"Unsupported code challenge method: {method}")
+
+
+def generate_pkce_pair(verifier_length: int = 64, method: str = "S256") -> PKCEChallenge:
+    """Generate a PKCE code verifier and challenge pair.
+
+    Args:
+        verifier_length: Length of the code verifier (43-128 characters).
+        method: Challenge method - "S256" (recommended) or "plain".
+
+    Returns:
+        A PKCEChallenge containing the verifier, challenge, and method.
+    """
+    code_verifier = generate_code_verifier(verifier_length)
+    code_challenge = generate_code_challenge(code_verifier, method)
+    return PKCEChallenge(
+        code_verifier=code_verifier,
+        code_challenge=code_challenge,
+        code_challenge_method=method,
+    )
+
+
+def generate_state(length: int = 32) -> str:
+    """Generate a cryptographically random state parameter.
+
+    The state parameter is used to prevent CSRF attacks and maintain state
+    between the authorization request and callback.
+
+    Args:
+        length: Length of the state string (minimum 16).
+
+    Returns:
+        A random state string.
+
+    Raises:
+        ValueError: If length is less than 16.
+    """
+    if length < 16:
+        raise ValueError("State length must be at least 16 characters")
+
+    return secrets.token_urlsafe(length)
+
+
+def generate_nonce(length: int = 32) -> str:
+    """Generate a cryptographically random nonce.
+
+    The nonce is used in ID token validation to prevent replay attacks.
+
+    Args:
+        length: Length of the nonce string (minimum 16).
+
+    Returns:
+        A random nonce string.
+
+    Raises:
+        ValueError: If length is less than 16.
+    """
+    if length < 16:
+        raise ValueError("Nonce length must be at least 16 characters")
+
+    return secrets.token_urlsafe(length)