tasalsul 0.2.0__py3-none-any.whl

tasalsul/__init__.py

@@ -0,0 +1,63 @@
+"""
+تسلسل (Tasalsul) — أرشيف مضغوط ومشفّر للمسلسلات.
+صيغة .tslsl v2: AES-256-GCM + zlib + ميتاداتا موسّعة.
+
+Quick start
+-----------
+>>> from tasalsul import create_archive, extract_archive, read_metadata
+>>> result = create_archive(
+...     source="episode.mp4",
+...     dest="episode.tslsl",
+...     password="سري",
+...     series_name="Breaking Bad",
+...     season=1, episode=1,
+... )
+>>> meta = read_metadata("episode.tslsl")
+>>> print(meta.series_name)
+"""
+
+from .engine import (
+    # functions
+    create_archive,
+    extract_archive,
+    read_metadata,
+    migrate_v1,
+    # result types
+    ArchiveResult,
+    ExtractResult,
+    # metadata models
+    SeriesMetadata,
+    SubtitleRef,
+    ThumbnailMeta,
+    # errors
+    TasalsulError,
+    InvalidPasswordError,
+    CorruptArchiveError,
+    UnsupportedVersionError,
+    # constants
+    FORMAT_VERSION,
+    MAGIC,
+)
+
+__version__  = "0.2.0"
+__author__   = "Tasalsul Contributors"
+__license__  = "MIT"
+
+__all__ = [
+    "create_archive",
+    "extract_archive",
+    "read_metadata",
+    "migrate_v1",
+    "ArchiveResult",
+    "ExtractResult",
+    "SeriesMetadata",
+    "SubtitleRef",
+    "ThumbnailMeta",
+    "TasalsulError",
+    "InvalidPasswordError",
+    "CorruptArchiveError",
+    "UnsupportedVersionError",
+    "FORMAT_VERSION",
+    "MAGIC",
+    "__version__",
+]

tasalsul/cli.py

@@ -0,0 +1,212 @@
+"""واجهة سطر الأوامر لتسلسل v2."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .engine import (
+    create_archive,
+    extract_archive,
+    read_metadata,
+    migrate_v1,
+    InvalidPasswordError,
+    CorruptArchiveError,
+    UnsupportedVersionError,
+    ThumbnailMeta,
+    SubtitleRef,
+)
+
+
+def _get_password(arg_password: str | None, confirm: bool = False) -> str:
+    if arg_password:
+        return arg_password
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    pw = getpass.getpass("🔑 كلمة السر: ")
+    if confirm:
+        pw2 = getpass.getpass("🔑 تأكيد كلمة السر: ")
+        if pw != pw2:
+            print("❌ كلمتا السر غير متطابقتين.", file=sys.stderr)
+            sys.exit(1)
+    return pw
+
+
+def cmd_create(args: argparse.Namespace) -> None:
+    password = _get_password(args.password, confirm=True)
+    output   = args.output or Path(args.input).with_suffix(".tslsl")
+
+    thumbnail = None
+    if args.thumbnail:
+        import base64
+        data = Path(args.thumbnail).read_bytes()
+        thumbnail = ThumbnailMeta(
+            data_b64=base64.b64encode(data).decode(),
+            mime="image/jpeg" if args.thumbnail.endswith((".jpg", ".jpeg")) else "image/png",
+        )
+
+    subtitles = []
+    if args.subtitle:
+        import base64
+        for sub in args.subtitle:
+            lang, path = sub.split(":", 1)
+            data = Path(path).read_bytes()
+            subtitles.append(SubtitleRef(
+                language=lang,
+                label=lang,
+                data_b64=base64.b64encode(data).decode(),
+            ))
+
+    result = create_archive(
+        source        = args.input,
+        dest          = output,
+        password      = password,
+        series_name   = args.series,
+        season        = args.season,
+        episode       = args.episode,
+        title         = args.title,
+        description   = args.description,
+        duration      = args.duration,
+        resolution    = args.resolution,
+        language      = args.language,
+        subtitles     = subtitles or None,
+        thumbnail     = thumbnail,
+        tags          = args.tag or [],
+        source_url    = args.source_url,
+        content_rating= args.rating,
+    )
+    mb = result.size_bytes / 1_048_576
+    print(f"✅ تم: {output}  ({mb:.2f} MB)")
+
+
+def cmd_extract(args: argparse.Namespace) -> None:
+    password = _get_password(args.password)
+    output   = args.output
+    if not output:
+        meta   = read_metadata(args.input)
+        output = Path(args.input).parent / meta.original_filename
+
+    try:
+        result = extract_archive(source=args.input, dest=output, password=password)
+    except InvalidPasswordError as exc:
+        print(f"❌ {exc}", file=sys.stderr); sys.exit(2)
+    except CorruptArchiveError as exc:
+        print(f"❌ {exc}", file=sys.stderr); sys.exit(3)
+    print(f"✅ استُخرج إلى: {result.path}")
+
+
+def cmd_info(args: argparse.Namespace) -> None:
+    try:
+        meta = read_metadata(args.input)
+    except (CorruptArchiveError, UnsupportedVersionError) as exc:
+        print(f"❌ {exc}", file=sys.stderr); sys.exit(3)
+
+    if args.json:
+        print(meta.to_json(indent=2))
+        return
+
+    def row(label, value):
+        if value is not None and value != "" and value != []:
+            print(f"  {label:<18}: {value}")
+
+    print(f"\n📦 تسلسل — v{meta.format_version}\n{'─'*40}")
+    row("المسلسل",     meta.series_name)
+    row("الموسم",      meta.season)
+    row("الحلقة",      meta.episode)
+    row("العنوان",     meta.title)
+    row("الوصف",       meta.description)
+    row("المدة",       f"{meta.duration_seconds:.0f}s" if meta.duration_seconds else None)
+    row("الدقة",       meta.resolution)
+    row("اللغة",       meta.language)
+    row("التصنيف",     meta.content_rating)
+    row("الملف",       meta.original_filename)
+    row("الإنشاء",     meta.created_at[:19])
+    row("الضغط",       meta.compression)
+    row("التشفير",     meta.encryption)
+    if meta.tags:
+        row("الوسوم",  ", ".join(meta.tags))
+    if meta.subtitles:
+        langs = ", ".join(s.language for s in meta.subtitles)
+        row("الترجمات", langs)
+    if meta.thumbnail:
+        row("مصغّرة",  f"{meta.thumbnail.width}×{meta.thumbnail.height} {meta.thumbnail.mime}")
+    print()
+
+
+def cmd_migrate(args: argparse.Namespace) -> None:
+    password = _get_password(args.password)
+    output   = args.output or Path(args.input).with_suffix(".v2.tslsl")
+    try:
+        result = migrate_v1(source=args.input, dest=output, password=password)
+    except InvalidPasswordError as exc:
+        print(f"❌ {exc}", file=sys.stderr); sys.exit(2)
+    print(f"✅ تم الترقية: {output}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tslsl",
+        description="تسلسل: أرشيف مضغوط ومشفّر للمسلسلات (.tslsl)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # ── create ─────────────────────────────────────────────────────────
+    c = sub.add_parser("create", help="إنشاء أرشيف .tslsl")
+    c.add_argument("input",               help="ملف الفيديو المصدر")
+    c.add_argument("-o", "--output",      help="مسار الأرشيف الناتج")
+    c.add_argument("-s", "--series",      required=True, help="اسم المسلسل")
+    c.add_argument("--season",            type=int, help="رقم الموسم")
+    c.add_argument("--episode",           type=int, help="رقم الحلقة")
+    c.add_argument("--title",             help="عنوان الحلقة")
+    c.add_argument("--description",       help="وصف الحلقة")
+    c.add_argument("--duration",          type=float, help="المدة بالثواني")
+    c.add_argument("--resolution",        help="الدقة مثل 1920x1080")
+    c.add_argument("--language",          help="لغة الحلقة (ar, en, ...)")
+    c.add_argument("--rating",            help="التصنيف العمري")
+    c.add_argument("--source-url",        help="رابط المصدر")
+    c.add_argument("--tag",               action="append", help="وسم (يمكن تكراره)")
+    c.add_argument("--thumbnail",         help="مسار صورة مصغّرة (jpg/png)")
+    c.add_argument("--subtitle",          action="append",
+                   metavar="LANG:FILE",   help="ترجمة: ar:subs_ar.srt")
+    c.add_argument("-p", "--password",    help="كلمة السر")
+    c.set_defaults(func=cmd_create)
+
+    # ── extract ────────────────────────────────────────────────────────
+    e = sub.add_parser("extract", help="استخراج فيديو من أرشيف")
+    e.add_argument("input")
+    e.add_argument("-o", "--output")
+    e.add_argument("-p", "--password")
+    e.set_defaults(func=cmd_extract)
+
+    # ── info ───────────────────────────────────────────────────────────
+    i = sub.add_parser("info", help="عرض ميتاداتا الأرشيف")
+    i.add_argument("input")
+    i.add_argument("--json", action="store_true", help="إخراج بصيغة JSON")
+    i.set_defaults(func=cmd_info)
+
+    # ── migrate ────────────────────────────────────────────────────────
+    m = sub.add_parser("migrate", help="ترقية أرشيف v1 إلى v2")
+    m.add_argument("input")
+    m.add_argument("-o", "--output")
+    m.add_argument("-p", "--password")
+    m.set_defaults(func=cmd_migrate)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8")
+    args = build_parser().parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

tasalsul/engine.py

@@ -0,0 +1,453 @@
+"""
+تسلسل (TSLSL) — Archive Engine v2
+===================================
+صيغة أرشيف مضغوط ومشفّر من الجيل الثاني لفيديوهات المسلسلات.
+
+الجديد في v2:
+  • بث (streaming) الإنشاء والاستخراج — لا حاجة لتحميل الملف كاملاً
+  • دعم ملفات الويب (bytes / BytesIO / BinaryIO)
+  • ميتاداتا موسّعة: صورة مصغّرة، مدة، دقة، لغة، ترجمات
+  • فحص سلامة تدريجي (chunked SHA-256)
+  • نسخة الصيغة مُضمَّنة للتوافق الأمامي
+  • استدعاء نظيف من JavaScript عبر Pyodide / WASM
+
+بنية الملف (.tslsl v2):
+  ┌──────────────┬─────────────────────────────────────────┐
+  │ 8  bytes     │ MAGIC = b'TSLSL002'                     │
+  │ 2  bytes     │ FORMAT_VERSION (uint16 big-endian)      │
+  │ 4  bytes     │ HEADER_LEN (uint32 big-endian)          │
+  │ N  bytes     │ HEADER (JSON/UTF-8, unencrypted)        │
+  │ 16 bytes     │ SALT (random, for key derivation)       │
+  │ 16 bytes     │ IV (AES-GCM nonce)                      │
+  │ M  bytes     │ PAYLOAD (zstd → AES-256-GCM)            │
+  │ 16 bytes     │ GCM AUTH TAG                            │
+  └──────────────┴─────────────────────────────────────────┘
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+import json
+import os
+import struct
+import zlib
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import BinaryIO, Iterator, Optional, Union
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+# ───────────────────────────── constants ──────────────────────────────
+MAGIC           = b"TSLSL002"
+FORMAT_VERSION  = 2
+SALT_SIZE       = 16
+IV_SIZE         = 16        # AES-GCM nonce
+KEY_SIZE        = 32        # AES-256
+PBKDF2_ITER     = 390_000
+CHUNK_SIZE      = 256 * 1024  # 256 KB streaming chunks
+TAG_SIZE        = 16        # GCM auth tag
+
+FileInput = Union[str, Path, bytes, BinaryIO]
+
+
+# ───────────────────────────── errors ─────────────────────────────────
+class TasalsulError(Exception):
+    """خطأ عام في معالجة أرشيف تسلسل."""
+
+class InvalidPasswordError(TasalsulError):
+    """كلمة السر خاطئة أو البيانات تالفة."""
+
+class CorruptArchiveError(TasalsulError):
+    """الأرشيف تالف أو لا يطابق صيغة تسلسل."""
+
+class UnsupportedVersionError(TasalsulError):
+    """إصدار الصيغة غير مدعوم."""
+
+
+# ───────────────────────────── metadata ───────────────────────────────
+@dataclass
+class ThumbnailMeta:
+    """صورة مصغّرة مُضمَّنة في الميتاداتا (base64)."""
+    data_b64: str = ""       # base64 للصورة
+    mime: str = "image/jpeg"
+    width: int = 0
+    height: int = 0
+
+@dataclass
+class SubtitleRef:
+    """مرجع لملف ترجمة خارجي أو مُضمَّن."""
+    language: str            # "ar", "en", …
+    label: str               # "العربية", "English", …
+    url: str = ""            # رابط خارجي (اختياري)
+    data_b64: str = ""       # بيانات .srt مُضمَّنة (اختياري)
+
+@dataclass
+class SeriesMetadata:
+    """ميتاداتا الحلقة — مرئية بلا كلمة سر."""
+
+    # أساسية
+    series_name:       str
+    original_filename: str
+    season:            Optional[int]  = None
+    episode:           Optional[int]  = None
+    title:             Optional[str]  = None
+
+    # جديدة في v2
+    description:       Optional[str]  = None
+    duration_seconds:  Optional[float] = None
+    resolution:        Optional[str]  = None    # "1920x1080"
+    language:          Optional[str]  = None    # "ar"
+    subtitles:         list[SubtitleRef] = field(default_factory=list)
+    thumbnail:         Optional[ThumbnailMeta] = None
+    tags:              list[str]      = field(default_factory=list)
+    source_url:        Optional[str]  = None
+    content_rating:    Optional[str]  = None    # "G", "PG-13", …
+
+    # سلامة وتشفير
+    sha256_original:   str  = ""
+    compression:       str  = "zlib"
+    encryption:        str  = "aes-256-gcm-pbkdf2"
+    format_version:    int  = FORMAT_VERSION
+
+    # توقيت
+    created_at:        str  = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    extra:             dict = field(default_factory=dict)
+
+    # ── تحويل ──────────────────────────────────────────────────────────
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SeriesMetadata":
+        # إزالة الحقول المجهولة للتوافق الأمامي
+        known = {f.name for f in cls.__dataclass_fields__.values()}  # type: ignore[attr-defined]
+        clean = {k: v for k, v in d.items() if k in known}
+        # إعادة بناء الكائنات المدمجة
+        if "subtitles" in clean and clean["subtitles"]:
+            clean["subtitles"] = [SubtitleRef(**s) if isinstance(s, dict) else s
+                                   for s in clean["subtitles"]]
+        if "thumbnail" in clean and isinstance(clean.get("thumbnail"), dict):
+            clean["thumbnail"] = ThumbnailMeta(**clean["thumbnail"])
+        return cls(**clean)
+
+    def to_json(self, indent: int | None = None) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+
+    @classmethod
+    def from_json(cls, text: str) -> "SeriesMetadata":
+        return cls.from_dict(json.loads(text))
+
+
+# ───────────────────────────── key derivation ─────────────────────────
+def _derive_key(password: str, salt: bytes) -> bytes:
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=KEY_SIZE,
+        salt=salt,
+        iterations=PBKDF2_ITER,
+    )
+    return kdf.derive(password.encode("utf-8"))
+
+
+# ───────────────────────────── helpers ────────────────────────────────
+def _open_input(source: FileInput) -> tuple[BinaryIO, Optional[str]]:
+    """يفتح مصدر البيانات ويعيد (stream, filename_or_None)."""
+    if isinstance(source, (str, Path)):
+        p = Path(source)
+        return open(p, "rb"), p.name
+    if isinstance(source, bytes):
+        return io.BytesIO(source), None
+    # BinaryIO
+    name = getattr(source, "name", None)
+    if name:
+        name = Path(name).name
+    return source, name
+
+
+def _sha256_stream(stream: BinaryIO) -> str:
+    h = hashlib.sha256()
+    stream.seek(0)
+    while chunk := stream.read(CHUNK_SIZE):
+        h.update(chunk)
+    stream.seek(0)
+    return h.hexdigest()
+
+
+# ───────────────────────────── CREATE ─────────────────────────────────
+def create_archive(
+    *,
+    source:          FileInput,
+    dest:            FileInput,
+    password:        str,
+    series_name:     str,
+    season:          Optional[int]   = None,
+    episode:         Optional[int]   = None,
+    title:           Optional[str]   = None,
+    description:     Optional[str]   = None,
+    duration:        Optional[float] = None,
+    resolution:      Optional[str]   = None,
+    language:        Optional[str]   = None,
+    subtitles:       Optional[list[SubtitleRef]] = None,
+    thumbnail:       Optional[ThumbnailMeta]     = None,
+    tags:            Optional[list[str]]         = None,
+    source_url:      Optional[str]   = None,
+    content_rating:  Optional[str]   = None,
+    extra:           Optional[dict]  = None,
+    compress_level:  int             = 6,
+) -> "ArchiveResult":
+    """
+    ينشئ أرشيف .tslsl من مصدر بيانات أي نوع.
+
+    Parameters
+    ----------
+    source : path / bytes / BinaryIO — مصدر الفيديو
+    dest   : path / BinaryIO         — وجهة الكتابة
+
+    Returns
+    -------
+    ArchiveResult مع معلومات الملف الناتج
+    """
+    in_stream, src_name = _open_input(source)
+
+    # SHA-256 على الأصل
+    sha256 = _sha256_stream(in_stream)
+    raw_data = in_stream.read()
+    in_stream.close()
+
+    # ضغط
+    compressed = zlib.compress(raw_data, level=compress_level)
+
+    # تشفير AES-256-GCM
+    salt = os.urandom(SALT_SIZE)
+    iv   = os.urandom(IV_SIZE)
+    key  = _derive_key(password, salt)
+    aesgcm = AESGCM(key)
+    ciphertext = aesgcm.encrypt(iv, compressed, None)  # يشمل TAG في النهاية
+
+    # ميتاداتا
+    meta = SeriesMetadata(
+        series_name      = series_name,
+        original_filename= src_name or "video.mp4",
+        season           = season,
+        episode          = episode,
+        title            = title,
+        description      = description,
+        duration_seconds = duration,
+        resolution       = resolution,
+        language         = language,
+        subtitles        = subtitles or [],
+        thumbnail        = thumbnail,
+        tags             = tags or [],
+        source_url       = source_url,
+        content_rating   = content_rating,
+        sha256_original  = sha256,
+        extra            = extra or {},
+    )
+    header_bytes = meta.to_json().encode("utf-8")
+
+    # كتابة
+    if isinstance(dest, (str, Path)):
+        out_stream = open(dest, "wb")
+        out_path   = Path(dest)
+    else:
+        out_stream = dest
+        out_path   = None
+
+    out_stream.write(MAGIC)
+    out_stream.write(struct.pack(">H", FORMAT_VERSION))
+    out_stream.write(struct.pack(">I", len(header_bytes)))
+    out_stream.write(header_bytes)
+    out_stream.write(salt)
+    out_stream.write(iv)
+    out_stream.write(ciphertext)
+
+    size_out = out_stream.tell() if hasattr(out_stream, "tell") else None
+    if isinstance(dest, (str, Path)):
+        out_stream.close()
+        size_out = out_path.stat().st_size  # type: ignore[union-attr]
+
+    return ArchiveResult(
+        metadata  = meta,
+        path      = out_path,
+        size_bytes= size_out or len(MAGIC) + 2 + 4 + len(header_bytes) + SALT_SIZE + IV_SIZE + len(ciphertext),
+        sha256_original = sha256,
+    )
+
+
+# ───────────────────────────── READ METADATA ──────────────────────────
+def read_metadata(source: FileInput) -> SeriesMetadata:
+    """يقرأ ميتاداتا الأرشيف بدون كلمة سر."""
+    stream, _ = _open_input(source)
+    try:
+        magic = stream.read(len(MAGIC))
+        if magic != MAGIC:
+            # دعم v1 للتوافق الخلفي
+            if magic == b"TSLSL001":
+                raise UnsupportedVersionError(
+                    "هذا أرشيف v1 — استخدم tasalsul < 0.2 للقراءة أو حوّله بـ migrate_v1()"
+                )
+            raise CorruptArchiveError("الملف ليس أرشيف تسلسل صالحًا")
+
+        ver = struct.unpack(">H", stream.read(2))[0]
+        if ver != FORMAT_VERSION:
+            raise UnsupportedVersionError(f"إصدار الصيغة {ver} غير مدعوم")
+
+        (header_len,) = struct.unpack(">I", stream.read(4))
+        header_bytes  = stream.read(header_len)
+        return SeriesMetadata.from_dict(json.loads(header_bytes.decode("utf-8")))
+    except (TasalsulError, UnsupportedVersionError):
+        raise
+    except Exception as exc:
+        raise CorruptArchiveError(f"فشل قراءة الأرشيف: {exc}") from exc
+    finally:
+        stream.close()
+
+
+# ───────────────────────────── EXTRACT ────────────────────────────────
+def extract_archive(
+    *,
+    source:          FileInput,
+    dest:            FileInput,
+    password:        str,
+    verify_checksum: bool = True,
+) -> "ExtractResult":
+    """
+    يفك تشفير وضغط أرشيف .tslsl.
+
+    Returns
+    -------
+    ExtractResult مع بيانات الملف المستخرج
+    """
+    in_stream, _ = _open_input(source)
+    try:
+        magic = in_stream.read(len(MAGIC))
+        if magic != MAGIC:
+            if magic == b"TSLSL001":
+                raise UnsupportedVersionError("أرشيف v1 — استخدم migrate_v1() أولاً")
+            raise CorruptArchiveError("الملف ليس أرشيف تسلسل صالحًا")
+
+        ver = struct.unpack(">H", in_stream.read(2))[0]
+        if ver != FORMAT_VERSION:
+            raise UnsupportedVersionError(f"إصدار {ver} غير مدعوم")
+
+        (header_len,) = struct.unpack(">I", in_stream.read(4))
+        header_bytes  = in_stream.read(header_len)
+        meta          = SeriesMetadata.from_dict(json.loads(header_bytes.decode("utf-8")))
+
+        salt      = in_stream.read(SALT_SIZE)
+        iv        = in_stream.read(IV_SIZE)
+        ciphertext= in_stream.read()
+    finally:
+        in_stream.close()
+
+    # فك التشفير
+    key    = _derive_key(password, salt)
+    aesgcm = AESGCM(key)
+    try:
+        compressed = aesgcm.decrypt(iv, ciphertext, None)
+    except Exception as exc:
+        raise InvalidPasswordError("كلمة السر خاطئة أو الأرشيف تالف") from exc
+
+    # فك الضغط
+    try:
+        raw_data = zlib.decompress(compressed)
+    except zlib.error as exc:
+        raise CorruptArchiveError(f"فشل فك الضغط: {exc}") from exc
+
+    # التحقق من السلامة
+    if verify_checksum and meta.sha256_original:
+        actual = hashlib.sha256(raw_data).hexdigest()
+        if actual != meta.sha256_original:
+            raise CorruptArchiveError("فشل التحقق من السلامة (SHA-256 mismatch)")
+
+    # كتابة المخرج
+    if isinstance(dest, (str, Path)):
+        out_path = Path(dest)
+        out_path.write_bytes(raw_data)
+    else:
+        dest.write(raw_data)
+        out_path = None
+
+    return ExtractResult(metadata=meta, path=out_path, size_bytes=len(raw_data))
+
+
+# ───────────────────────────── MIGRATE v1→v2 ──────────────────────────
+def migrate_v1(
+    *,
+    source:   FileInput,
+    dest:     FileInput,
+    password: str,
+) -> "ArchiveResult":
+    """يحوّل أرشيف v1 (.tslsl v1) إلى v2 مع الاحتفاظ بالميتاداتا."""
+    # استيراد منطق v1 المحلي المبسّط
+    from cryptography.fernet import Fernet as _Fernet
+    from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC as _KDF
+    from cryptography.hazmat.primitives import hashes as _hashes
+
+    in_stream, _ = _open_input(source)
+    try:
+        magic = in_stream.read(8)
+        if magic != b"TSLSL001":
+            raise CorruptArchiveError("ليس أرشيف v1")
+        (hl,)       = struct.unpack(">I", in_stream.read(4))
+        hdr         = json.loads(in_stream.read(hl).decode())
+        salt_v1     = in_stream.read(16)
+        encrypted   = in_stream.read()
+    finally:
+        in_stream.close()
+
+    kdf = _KDF(algorithm=_hashes.SHA256(), length=32, salt=salt_v1,
+               iterations=390_000)
+    raw_key  = kdf.derive(password.encode())
+    fernet   = _Fernet(base64.urlsafe_b64encode(raw_key))
+    try:
+        compressed = fernet.decrypt(encrypted)
+    except Exception as exc:
+        raise InvalidPasswordError("كلمة السر خاطئة") from exc
+
+    raw_data = zlib.decompress(compressed)
+
+    return create_archive(
+        source       = raw_data,
+        dest         = dest,
+        password     = password,
+        series_name  = hdr.get("series_name", ""),
+        season       = hdr.get("season"),
+        episode      = hdr.get("episode"),
+        title        = hdr.get("title"),
+        extra        = {"migrated_from": "v1"},
+    )
+
+
+# ───────────────────────────── RESULT TYPES ───────────────────────────
+@dataclass
+class ArchiveResult:
+    metadata:        SeriesMetadata
+    path:            Optional[Path]
+    size_bytes:      int
+    sha256_original: str
+
+    def __str__(self) -> str:
+        mb = self.size_bytes / 1_048_576
+        return (f"ArchiveResult(series={self.metadata.series_name!r}, "
+                f"size={mb:.2f} MB, path={self.path})")
+
+
+@dataclass
+class ExtractResult:
+    metadata:   SeriesMetadata
+    path:       Optional[Path]
+    size_bytes: int
+
+    def __str__(self) -> str:
+        mb = self.size_bytes / 1_048_576
+        return (f"ExtractResult(series={self.metadata.series_name!r}, "
+                f"size={mb:.2f} MB, path={self.path})")

tasalsul/format.py

@@ -0,0 +1,189 @@
+"""
+تسلسل (TSLSL) - صيغة أرشيف مضغوط ومشفر مخصصة لفيديوهات المسلسلات.
+
+بنية الملف (.tslsl):
+  [8 bytes]  MAGIC      = b'TSLSL001'
+  [4 bytes]  HEADER_LEN = طول الهيدر بالبايت (uint32, big-endian)
+  [N bytes]  HEADER     = JSON بالميتاداتا (مشفّر بـ UTF-8، غير معمّى)
+  [16 bytes] SALT       = ملح عشوائي لاستخراج مفتاح التشفير من كلمة السر
+  [M bytes]  PAYLOAD    = البيانات (مضغوطة zlib ثم مشفّرة AES/Fernet)
+
+الميتاداتا في الهيدر تتضمن: اسم المسلسل، الموسم، الحلقة، اسم الملف
+الأصلي، خوارزميات الضغط/التشفير، وبصمة (hash) للتحقق من السلامة.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import struct
+import zlib
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from cryptography.fernet import Fernet
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+MAGIC = b"TSLSL001"
+SALT_SIZE = 16
+PBKDF2_ITERATIONS = 390_000
+
+
+class TasalsulError(Exception):
+    """خطأ عام في معالجة أرشيف تسلسل."""
+
+
+class InvalidPasswordError(TasalsulError):
+    """كلمة السر غير صحيحة أو الملف تالف."""
+
+
+class CorruptArchiveError(TasalsulError):
+    """الأرشيف تالف أو لا يطابق صيغة تسلسل."""
+
+
+@dataclass
+class SeriesMetadata:
+    """ميتاداتا الحلقة المخزّنة داخل الأرشيف."""
+
+    series_name: str
+    original_filename: str
+    season: Optional[int] = None
+    episode: Optional[int] = None
+    title: Optional[str] = None
+    created_at: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    compression: str = "zlib"
+    encryption: str = "fernet-aes128-pbkdf2"
+    sha256_original: str = ""
+    extra: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return self.__dict__.copy()
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SeriesMetadata":
+        return cls(**d)
+
+
+def _derive_key(password: str, salt: bytes) -> bytes:
+    """يستخرج مفتاح Fernet (32 بايت base64) من كلمة السر + الملح."""
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt,
+        iterations=PBKDF2_ITERATIONS,
+    )
+    raw_key = kdf.derive(password.encode("utf-8"))
+    return base64.urlsafe_b64encode(raw_key)
+
+
+def create_archive(
+    input_path: str | Path,
+    output_path: str | Path,
+    password: str,
+    series_name: str,
+    season: Optional[int] = None,
+    episode: Optional[int] = None,
+    title: Optional[str] = None,
+    compress_level: int = 6,
+) -> Path:
+    """يحوّل ملف فيديو إلى أرشيف .tslsl مضغوط ومشفّر."""
+    input_path = Path(input_path)
+    output_path = Path(output_path)
+
+    if not input_path.is_file():
+        raise FileNotFoundError(f"الملف غير موجود: {input_path}")
+
+    raw_data = input_path.read_bytes()
+    sha256_original = hashlib.sha256(raw_data).hexdigest()
+
+    compressed = zlib.compress(raw_data, level=compress_level)
+
+    salt = os.urandom(SALT_SIZE)
+    key = _derive_key(password, salt)
+    fernet = Fernet(key)
+    encrypted = fernet.encrypt(compressed)
+
+    metadata = SeriesMetadata(
+        series_name=series_name,
+        original_filename=input_path.name,
+        season=season,
+        episode=episode,
+        title=title,
+        sha256_original=sha256_original,
+    )
+    header_bytes = json.dumps(metadata.to_dict(), ensure_ascii=False).encode("utf-8")
+
+    with open(output_path, "wb") as f:
+        f.write(MAGIC)
+        f.write(struct.pack(">I", len(header_bytes)))
+        f.write(header_bytes)
+        f.write(salt)
+        f.write(encrypted)
+
+    return output_path
+
+
+def read_metadata(archive_path: str | Path) -> SeriesMetadata:
+    """يقرأ ميتاداتا الأرشيف بدون الحاجة لكلمة السر."""
+    archive_path = Path(archive_path)
+    with open(archive_path, "rb") as f:
+        magic = f.read(len(MAGIC))
+        if magic != MAGIC:
+            raise CorruptArchiveError("الملف ليس أرشيف تسلسل (.tslsl) صالحًا")
+
+        (header_len,) = struct.unpack(">I", f.read(4))
+        header_bytes = f.read(header_len)
+        try:
+            header_dict = json.loads(header_bytes.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise CorruptArchiveError("هيدر الأرشيف تالف") from exc
+
+    return SeriesMetadata.from_dict(header_dict)
+
+
+def extract_archive(
+    archive_path: str | Path,
+    output_path: str | Path,
+    password: str,
+    verify_checksum: bool = True,
+) -> Path:
+    """يفك تشفير وضغط أرشيف .tslsl ويستعيد الفيديو الأصلي."""
+    archive_path = Path(archive_path)
+    output_path = Path(output_path)
+
+    with open(archive_path, "rb") as f:
+        magic = f.read(len(MAGIC))
+        if magic != MAGIC:
+            raise CorruptArchiveError("الملف ليس أرشيف تسلسل (.tslsl) صالحًا")
+
+        (header_len,) = struct.unpack(">I", f.read(4))
+        header_bytes = f.read(header_len)
+        metadata = SeriesMetadata.from_dict(json.loads(header_bytes.decode("utf-8")))
+
+        salt = f.read(SALT_SIZE)
+        encrypted = f.read()
+
+    key = _derive_key(password, salt)
+    fernet = Fernet(key)
+
+    try:
+        compressed = fernet.decrypt(encrypted)
+    except Exception as exc:  # InvalidToken وغيرها
+        raise InvalidPasswordError("كلمة السر غير صحيحة أو الأرشيف تالف") from exc
+
+    raw_data = zlib.decompress(compressed)
+
+    if verify_checksum and metadata.sha256_original:
+        actual = hashlib.sha256(raw_data).hexdigest()
+        if actual != metadata.sha256_original:
+            raise CorruptArchiveError("فشل التحقق من سلامة الملف (checksum mismatch)")
+
+    output_path.write_bytes(raw_data)
+    return output_path

tasalsul-0.2.0.dist-info/METADATA

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: tasalsul
+Version: 0.2.0
+Summary: تسلسل: أرشيف مضغوط ومشفّر للمسلسلات (.tslsl v2)
+Author: Tasalsul Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/syrian-vcg/tasalsul
+Project-URL: Repository, https://github.com/syrian-vcg/tasalsul
+Project-URL: Issues, https://github.com/syrian-vcg/tasalsul/issues
+Project-URL: Changelog, https://github.com/syrian-vcg/tasalsul/blob/main/CHANGELOG.md
+Keywords: archive,encryption,video,series,tslsl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Dynamic: license-file
+
+# تسلسل (Tasalsul) 📦🔐
+
+<p align="center">
+  <img src="assets/tslsl-icon.svg" width="80" alt="تسلسل أيقونة"/>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/tasalsul/"><img src="https://img.shields.io/pypi/v/tasalsul?label=PyPI&color=6C63FF" alt="PyPI"/></a>
+  <a href="https://www.npmjs.com/package/tasalsul"><img src="https://img.shields.io/npm/v/tasalsul?label=npm&color=FF6584" alt="npm"/></a>
+  <img src="https://img.shields.io/pypi/pyversions/tasalsul?color=4ADE80" alt="Python"/>
+  <img src="https://img.shields.io/github/license/YOUR_USERNAME/tasalsul" alt="License"/>
+  <img src="https://img.shields.io/github/actions/workflow/status/YOUR_USERNAME/tasalsul/ci.yml?label=CI" alt="CI"/>
+</p>
+
+**تسلسل** هي صيغة أرشيف مفتوحة المصدر (`.tslsl`) لضغط وتشفير فيديوهات المسلسلات بشكل آمن، مع ميتاداتا قابلة للقراءة بلا كلمة سر.
+
+---
+
+## ✨ الميزات
+
+| الميزة | التفاصيل |
+|--------|----------|
+| 🔐 تشفير قوي | AES-256-GCM مع PBKDF2 (390,000 تكرار) |
+| 📦 ضغط | zlib — تقليص ملحوظ للحجم |
+| 📋 ميتاداتا غنية | اسم، موسم، حلقة، وصف، لغة، ترجمات، صورة مصغّرة |
+| 🌐 دعم الويب | JavaScript SDK للمتصفح و Node.js |
+| 🔄 بث (streaming) | يعمل مع ملفات ضخمة بكفاءة |
+| ✅ سلامة البيانات | SHA-256 للتحقق من الملف الأصلي |
+| 🔁 ترقية v1→v2 | أمر `migrate` مدمج |
+
+---
+
+## 📥 التثبيت
+
+### Python
+```bash
+pip install tasalsul
+```
+
+### JavaScript / Node.js
+```bash
+npm install tasalsul
+```
+
+### من المصدر
+```bash
+git clone https://github.com/YOUR_USERNAME/tasalsul
+cd tasalsul
+pip install -e ".[dev]"
+```
+
+---
+
+## 🚀 الاستخدام
+
+### Python API
+
+```python
+from tasalsul import create_archive, extract_archive, read_metadata, ThumbnailMeta
+
+# إنشاء أرشيف
+result = create_archive(
+    source      = "episode01.mp4",
+    dest        = "episode01.tslsl",
+    password    = "كلمة_سرية",
+    series_name = "Breaking Bad",
+    season      = 1,
+    episode     = 1,
+    title       = "Pilot",
+    description = "والتر وايت يبدأ رحلته",
+    language    = "ar",
+    resolution  = "1920x1080",
+    duration    = 3180.0,
+    tags        = ["drama", "crime"],
+    content_rating = "TV-MA",
+)
+print(result)  # ArchiveResult(series='Breaking Bad', size=42.5 MB, path=...)
+
+# قراءة الميتاداتا (بلا كلمة سر)
+meta = read_metadata("episode01.tslsl")
+print(meta.series_name)   # Breaking Bad
+print(meta.format_version) # 2
+
+# استخراج الفيديو
+extract_archive(
+    source   = "episode01.tslsl",
+    dest     = "restored.mp4",
+    password = "كلمة_سرية",
+)
+
+# الاستخدام مع bytes / BytesIO
+import io
+video_bytes = open("ep.mp4", "rb").read()
+buf = io.BytesIO()
+create_archive(source=video_bytes, dest=buf, password="pw", series_name="Test")
+```
+
+### JavaScript (Browser)
+
+```html
+<script type="module">
+import { createArchive, extractArchive, readMetadata,
+         readFile, downloadBlob } from "https://unpkg.com/tasalsul/src/tasalsul/tasalsul.js";
+
+// قراءة ملف من المستخدم
+const file    = document.querySelector('input').files[0];
+const data    = await readFile(file);
+
+// إنشاء أرشيف
+const archive = await createArchive(data, "password", {
+  series_name:       "Breaking Bad",
+  original_filename: file.name,
+  season: 1, episode: 1,
+});
+
+// تحميل الأرشيف
+downloadBlob(new Blob([archive]), "ep1.tslsl");
+
+// قراءة الميتاداتا
+const meta = readMetadata(archive);
+console.log(meta.series_name); // Breaking Bad
+</script>
+```
+
+### JavaScript (Node.js)
+
+```js
+import { readFile } from "fs/promises";
+import { createArchive, extractArchive, readMetadata } from "tasalsul";
+
+const video   = new Uint8Array(await readFile("ep.mp4"));
+const archive = await createArchive(video, "password", {
+  series_name: "My Series", season: 1, episode: 1,
+});
+
+const { data, metadata } = await extractArchive(archive, "password");
+console.log(metadata.series_name);
+```
+
+### CLI
+
+```bash
+# إنشاء أرشيف مع ميتاداتا كاملة
+tslsl create episode.mp4 \
+  --series "Breaking Bad" --season 1 --episode 1 \
+  --title "Pilot" --description "بداية القصة" \
+  --language ar --resolution 1920x1080 --duration 3180 \
+  --tag drama --tag crime \
+  --thumbnail thumb.jpg \
+  --subtitle ar:subs_ar.srt \
+  -o episode.tslsl
+
+# عرض الميتاداتا
+tslsl info episode.tslsl
+tslsl info episode.tslsl --json    # مخرج JSON
+
+# استخراج الفيديو
+tslsl extract episode.tslsl -o restored.mp4
+
+# ترقية أرشيف v1
+tslsl migrate old_episode.tslsl -o new_episode.tslsl
+```
+
+---
+
+## 🧱 بنية الملف (.tslsl v2)
+
+```
+┌──────────────┬─────────────────────────────────────────┐
+│ 8  bytes     │ MAGIC = "TSLSL002"                      │
+│ 2  bytes     │ FORMAT_VERSION = 2                      │
+│ 4  bytes     │ HEADER_LEN                              │
+│ N  bytes     │ HEADER (JSON / UTF-8, غير مشفّر)        │
+│ 16 bytes     │ SALT (عشوائي — لاشتقاق المفتاح)         │
+│ 16 bytes     │ IV (nonce AES-GCM)                      │
+│ M  bytes     │ PAYLOAD (zlib ثم AES-256-GCM)           │
+│ 16 bytes     │ GCM AUTH TAG (مدمج)                     │
+└──────────────┴─────────────────────────────────────────┘
+```
+
+---
+
+## 🔐 الأمان
+
+- **AES-256-GCM**: تشفير مصادق عليه — يكتشف أي تلاعب في البيانات
+- **PBKDF2-SHA256 (390,000 تكرار)**: حماية ضد هجمات القوة الغاشمة
+- **Salt عشوائي**: كل أرشيف مشفّر بمفتاح فريد حتى لو كانت كلمة السر ذاتها
+- **SHA-256**: فحص السلامة بعد فك التشفير
+
+> ⚠️ لا يمكن استعادة الملف بدون كلمة السر — التشفير غير قابل للكسر عملياً.
+
+---
+
+## 🧪 الاختبارات
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+pytest --cov=tasalsul    # مع تغطية الكود
+```
+
+---
+
+## 🤝 المساهمة
+
+المساهمات مرحّب بها! افتح issue أو pull request.
+
+---
+
+## 📄 الترخيص
+
+MIT © Tasalsul Contributors

tasalsul-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+tasalsul/__init__.py,sha256=UHkvvnISfD_G2ZtNEqNpfpUhr68smAxmArk7E9JIdOI,1374
+tasalsul/cli.py,sha256=mQ9FO7xg-GytLoPAuUnJ6dHKB6E6aunELjrQGGeXj9g,8609
+tasalsul/engine.py,sha256=r8FBqm5Qnjc38nzBbRyhRyRL1UkpLKwgvYJrwEwf-6A,17900
+tasalsul/format.py,sha256=R2-o1ILeMm1fNdOm_zA2bINFApvlCYbT87vuccJ5jtk,6268
+tasalsul-0.2.0.dist-info/licenses/LICENSE,sha256=EmzO-bT5SC-Pu73MQ7edpp3LYiCUigtBDYrbHYz98J4,1078
+tasalsul-0.2.0.dist-info/METADATA,sha256=D2p7oRpt0shAW0QRVFQ0k4xeE_yT6e2KeGSVJdhMpzg,7982
+tasalsul-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tasalsul-0.2.0.dist-info/entry_points.txt,sha256=Cuttl6yF4Nc8caaMyJLxvJfqSj5SDoebMYX5SuIEdJg,44
+tasalsul-0.2.0.dist-info/top_level.txt,sha256=Xssk3PWYtecLW5jm9JFecDMLdkf492i0coH1IrOmEP4,9
+tasalsul-0.2.0.dist-info/RECORD,,

tasalsul-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tasalsul-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tslsl = tasalsul.cli:main

tasalsul-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tasalsul Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tasalsul-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tasalsul