Authentication

class AuthMethod(str, Enum):
    """OAuth authorization method."""
    CODE = "code"        # Authorization code flow
    DEVICE = "device"    # Device code flow

def verify_subscription(
    access_token: str | None = None,
    *,
    force_refresh: bool = False,
) -> SubscriptionVerification:
    """Verify subscription status with the Esprit API."""
    token = access_token or get_auth_token()
    if not token:
        return {
            "valid": False,
            "plan": "free",
            "quota_remaining": {"scans": 0, "tokens": 0},
            "cloud_enabled": False,
            "available_models": [],
            "error": "No authentication token available.",
        }
    
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(
        f"{API_BASE_URL}/subscription/verify",
        headers=headers,
        timeout=15,
    )

class Credentials(TypedDict, total=False):
    """Stored credential structure."""
    access_token: str
    refresh_token: str
    expires_at: int  # Unix timestamp
    user_id: str
    email: str
    full_name: str | None
    plan: str  # 'free', 'pro', 'team'

@dataclass
class OAuthCredentials:
    type: str  # "oauth" or "api"
    access_token: str
    refresh_token: str | None = None
    expires_at: int | None = None  # Unix timestamp
    account_id: str | None = None
    extra: dict[str, Any] | None = None

def is_expired(self) -> bool:
    """Check if the access token has expired."""
    if not self.expires_at:
        return False
    now = int(datetime.now(tz=timezone.utc).timestamp())
    # Refresh 5 minutes before expiry
    return now >= (self.expires_at - 300)

class AccountPool:
    """Manages multiple OAuth accounts per provider."""
    
    def add_account(
        self,
        provider_id: str,
        credentials: OAuthCredentials,
        email: str,
    ) -> None:
        """Add an account to the pool."""
    
    def get_best_account(
        self,
        provider_id: str,
    ) -> StoredAccount | None:
        """Get the best available account (enabled, not rate limited)."""