Security and authentication

class HTTPAuthSecurityScheme(TypedDict):
    """HTTP security scheme supporting various authentication methods.
    
    Supports standard HTTP authentication schemes including Basic, Bearer,
    Digest, and custom schemes. Commonly used for token-based authentication
    with JWTs or other bearer token formats.
    """
    
    type: Required[Literal["http"]]
    """The type of the security scheme. Always "http"."""
    
    scheme: Required[str]
    """The HTTP authentication scheme (e.g., "basic", "bearer", "digest")."""
    
    bearer_format: NotRequired[str]
    """Format hint for bearer tokens (e.g., "JWT")."""
    
    description: NotRequired[str]
    """Human-readable description of the security scheme."""

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "description": "JWT bearer token authentication for API access"
}

{
  "type": "http",
  "scheme": "basic",
  "description": "HTTP Basic authentication with username and password"
}

class APIKeySecurityScheme(TypedDict):
    """API Key security scheme for key-based authentication.
    
    Supports passing API keys through query parameters, HTTP headers, or
    cookies. Commonly used for simple service-to-service authentication
    or public API access control.
    """
    
    type: Required[Literal["apiKey"]]
    """The type of the security scheme. Always "apiKey"."""
    
    name: Required[str]
    """The name of the header, query parameter, or cookie."""
    
    in_: Required[Literal["query", "header", "cookie"]]
    """Location of the API key: "query", "header", or "cookie"."""
    
    description: NotRequired[str]
    """Human-readable description of the security scheme."""

{
  "type": "apiKey",
  "name": "X-API-Key",
  "in": "header",
  "description": "API key passed in custom X-API-Key header"
}

class OAuth2SecurityScheme(TypedDict):
    """OAuth2 security scheme for delegated authorization.
    
    Supports multiple OAuth 2.0 flows including authorization code, implicit,
    password credentials, and client credentials. Used for secure delegated
    access where users authorize agents to act on their behalf.
    """
    
    type: Required[Literal["oauth2"]]
    """The type of the security scheme. Always "oauth2"."""
    
    flows: Required[dict[str, Any]]
    """OAuth2 flow configurations. Supported flows:
    - authorizationCode: Authorization code flow (most secure)
    - implicit: Implicit flow (browser-based)
    - password: Resource owner password credentials flow
    - clientCredentials: Client credentials flow (service-to-service)
    """
    
    description: NotRequired[str]
    """Human-readable description of the security scheme."""

{
  "type": "oauth2",
  "flows": {
    "authorizationCode": {
      "authorizationUrl": "https://auth.example.com/oauth/authorize",
      "tokenUrl": "https://auth.example.com/oauth/token",
      "scopes": {
        "read": "Read access to user data",
        "write": "Write access to user data",
        "admin": "Administrative access"
      }
    }
  },
  "description": "OAuth2 authorization code flow for user-delegated access"
}

class OpenIdConnectSecurityScheme(TypedDict):
    """OpenID Connect security scheme for identity authentication.
    
    Built on top of OAuth 2.0, OpenID Connect adds an identity layer for
    user authentication. Uses discovery documents for automatic configuration
    of endpoints and supported features.
    """
    
    type: Required[Literal["openIdConnect"]]
    """The type of the security scheme. Always "openIdConnect"."""
    
    open_id_connect_url: Required[str]
    """URL to the OpenID Connect discovery document.
    Typically: https://auth.example.com/.well-known/openid-configuration
    """
    
    description: NotRequired[str]
    """Human-readable description of the security scheme."""

{
  "type": "openIdConnect",
  "openIdConnectUrl": "https://auth.example.com/.well-known/openid-configuration",
  "description": "OpenID Connect authentication with automatic discovery for enterprise SSO"
}

class MutualTLSSecurityScheme(TypedDict):
    """Mutual TLS security scheme for certificate-based authentication.

    Uses client certificates for mutual authentication where both client
    and server verify each other's identity. Provides strong cryptographic
    authentication for high-security service-to-service communication.
    """

    type: Required[Literal["mutualTLS"]]
    """The type of the security scheme. Always "mutualTLS"."""

    description: NotRequired[str]
    """Human-readable description of the security scheme."""

{
  "type": "mutualTLS",
  "description": "Client certificate authentication for secure service-to-service communication"
}

SecurityScheme = Annotated[
    Union[
        HTTPAuthSecurityScheme,
        APIKeySecurityScheme,
        OAuth2SecurityScheme,
        OpenIdConnectSecurityScheme,
        MutualTLSSecurityScheme,
    ],
    Discriminator("type"),
]