Metadata-Version: 2.4
Name: django-image-sec-validator
Version: 0.1.1
Summary: Secure image validation and auto WebP conversion for Django
Author: wsl-pc
Author-email: dev@mws.per.jo
Requires-Python: >=3.11,<4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: django (>=5.2.17,<6.0.0)
Requires-Dist: filetype (>=1.2.0,<2.0.0)
Requires-Dist: pillow (>=12.3.0,<13.0.0)
Description-Content-Type: text/markdown

```markdown
# Django Image Security Validator

حزمة أمنية خفيفة وقوية لإطار عمل **Django**، تهدف إلى حماية الخوادم من هجمات البايلودات والملفات التنفيذية المخفية خلف صيغ الصور، من خلال الفحص المزدوج لترويسات الملفات والتحقق من البكسلات، مع إمكانية التحويل التلقائي الآمن إلى صيغة **WebP**.

---

## 🛠️ المميزات الرئيسية

1. **التحقق من Magic Bytes (عبر مكتبة filetype):** للتأكد من أن الامتداد والترويسة الفعلية للملف متطابقان ومنعان تزوير الملفات التنفيذية (PE files).
2. **التحقق من سلامة البكسلات (عبر Pillow):** فحص عميق للتأكد من أن الملف عبارة عن صورة سليمة وغير تالفة أو ملغومة.
3. **التطهير التلقائي (Auto WebP Conversion):** إعادة بناء الصورة وتحويلها إلى صيغة WebP لإزالة أي بيانات وصفية (Metadata) أو شيفرات مرفقة.
4. **متوافقة مع النماذج (Django Validators):** سهلة الربط المباشر مع `ImageField`.

---

## 📦 التثبيت

يمكنك تثبيت الحزمة محلياً باستخدام **Poetry** أو **pip**:

```bash
# باستخدام pip من مسار الحزمة محلياً
pip install path/to/django-image-sec-validator

# أو عبر Poetry في مشروعك الآخر
poetry add path/to/django-image-sec-validator

```

---

## 🚀 طريقة الاستخدام

### 1. استخدام الموثق (Validator) في النماذج (`models.py`)

يمكنك ربط دالة `validate_image_security` مباشرة بـ `ImageField` لمنع رفع أي ملفات مشبوهة أو مزيفة:

```python
from django.db import models
from django_image_sec_validator import validate_image_security, process_and_convert_to_webp

class UserProfile(models.Model):
    avatar = models.ImageField(
        upload_to='avatars/',
        validators=[validate_image_security]
    )

    def save(self, *args, **kwargs):
        # التحويل التلقائي إلى WebP عند الحفظ لتطهير الصورة نهائياً
        if self.avatar and not self.avatar.name.endswith('.webp'):
            self.avatar = process_and_convert_to_webp(self.avatar)
        super().save(*args, **kwargs)

```

### 2. الاستخدام المباشر للدوال في الـ Views أو Forms

إذا كنت ترغب في معالجة الملفات برمجياً قبل حفظها:

```python
from django.core.exceptions import ValidationError
from django_image_sec_validator import validate_image_security, process_and_convert_to_webp

def my_upload_view(request):
    if request.method == 'POST':
        uploaded_file = request.FILES.get('image')
        
        try:
            # 1. التحقق من أمان الملف
            validate_image_security(uploaded_file)
            
            # 2. معالجة وتحويل الصورة إلى WebP آمنة
            clean_image = process_and_convert_to_webp(uploaded_file, quality=85)
            
            # ... تابع حفظ الملف أو استخدامه ...
            
        except ValidationError as e:
            # التعامل مع الملف المرفق المرفوض
            print(e.message)

```

---

## 🛡️ متطلبات التشغيل

dependencies = [
    "pillow (>=12.3.0,<13.0.0)",
    "filetype (>=1.2.0,<2.0.0)",
    "django (>=5.2.17,<6.0.0)",
]

---

## 📄 الترخيص

هذا المشروع مرخص تحت رخصة MIT.
