feat(auth): implement Auth API functionality

[briansumma]

Summary

This PR implements comprehensive authentication and authorization functionality for the Pythonik client, providing complete integration with Iconik's Auth API endpoints.

Features Added

Core Authentication

• Token Management: Create, refresh, revoke, and validate authentication tokens
• Multi-domain Login: Support for logging into multiple system domains
• Simple Login: Email/password authentication with marketplace integration
• External Auth: Third-party application authentication workflows

Identity Providers & SSO

• SAML Integration: Complete SAML SSO implementation with metadata handling
• Identity Provider Management: CRUD operations for IdP configurations
• Domain Binding: Link domains to specific identity providers
• OAuth & Active Directory: Support for OAuth and AD authentication

Multi-Factor Authentication

• OTP Support: One-time password generation and validation
• TOTP Integration: Time-based OTP for enhanced security
• MFA Configuration: Manage MFA requirements and methods

System Domain Management

• Domain Operations: Create, update, delete system domains
• Template System: Create domains from templates and referral codes
• Logo Management: Upload and manage domain logos
• Billing Integration: Handle billing tiers and limits

User Management

• Registration Workflows: Complete user registration with email verification
• Invitation System: Send and complete user invitations
• Password Management: Forgot/reset password with security checks
• Profile Management: User profile and preference handling

App Management

• Application CRUD: Manage applications and their configurations
• App Instances: Handle approved app instances and permissions
• External Auth Requests: Secure external application authentication

Additional Features

• Referral Codes: Create and manage referral code system
• Country Support: International country code management
• Password Policies: Configurable password strength requirements
• Marketplace Integration: Google Cloud Marketplace signup and linking

Technical Implementation

Models (926 lines)

• Comprehensive Schema Coverage: 50+ Pydantic models covering all Auth API endpoints
• Type Safety: Full type annotations with validation rules
• Flexible Input: Support for both Pydantic models and dictionary inputs
• Forward References: Proper model relationship handling

API Specification (1,676 lines)

• Complete Endpoint Coverage: 80+ methods covering all Auth API functionality
• Consistent Interface: Uniform parameter handling and response parsing
• Error Handling: Proper HTTP status code handling with documented exceptions
• Parameter Validation: Input validation with clear error messages

Testing (1,039 lines)

• Comprehensive Coverage: 50+ unit tests covering all major functionality
• Mock Integration: Proper request/response mocking for reliable testing
• Edge Cases: Testing for error conditions and edge cases
• Real-world Scenarios: Tests based on actual API usage patterns

Code Quality

• Import Organization: Clean import structure with proper alphabetical ordering
• Documentation: Complete docstrings for all methods with parameter descriptions
• Type Hints: Full type annotation coverage for better IDE support
• Error Documentation: Documented exceptions with HTTP status codes

Breaking Changes

None - This is a purely additive change with no modifications to existing functionality.

API Coverage

This implementation provides complete coverage of the Iconik Auth API including:

• /auth/ - Core authentication endpoints
• /apps/ - Application management
• /system_domains/ - Domain management
• /auth/saml/ - SAML SSO functionality
• /auth/multidomain/ - Multi-domain operations
• /invitation/ - User invitation workflows
• /registrations/ - User registration system
• /password/ - Password management
• /referral_codes/ - Referral system
• /marketplace/ - Marketplace integrations

Usage Examples

Basic Authentication

# Simple login
login_data = SimpleLoginSchema(email="user@example.com", password="password")
response = client.auth().simple_login(login=login_data)

# Multi-domain login
multi_login = MultiDomainLoginSchema(
    email="user@example.com", 
    system_domain_id="domain-id"
)
response = client.auth().login_multidomain(login=multi_login)

Token Management

# Create new token
response = client.auth().create_token()

# Check token validity
response = client.auth().check_token()

# Refresh token
response = client.auth().refresh_token()

System Domain Management

# Create system domain
domain_data = SystemDomainSchema(name="example.com", base_url="https://example.com")
response = client.auth().create_system_domain(domain=domain_data)

# List domains
response = client.auth().list_system_domains(query="example")

Identity Provider Setup

# Create SAML identity provider
provider_data = IdentityProviderSchema(
    settings={"entity_id": "https://idp.example.com", "sso_url": "https://idp.example.com/sso"},
    type="GENERIC"
)
response = client.auth().create_identity_provider(provider=provider_data)

Testing

All functionality has been thoroughly tested with:

• Unit tests for all major methods
• Mock server responses for API validation
• Error condition testing
• Integration scenario testing

Run tests with:

pytest pythonik/tests/test_auth.py -v

Dependencies

• No new external dependencies added
• Utilizes existing Pydantic models and request handling
• Compatible with existing client architecture

This implementation completes a major component of the Iconik API integration and provides users with comprehensive authentication and authorization capabilities essential for secure API interactions.