rubiflow 1.0.0__py3-none-any.whl

rubiflow/__init__.py

@@ -0,0 +1,34 @@
+"""
+RubiFlow: Next-Generation High-Performance Async Python Framework for Rubika.
+"""
+
+from .client import Client
+from .crypto import RubiFlowCrypto
+from .exceptions import (
+    ApiError,
+    CryptoError,
+    InvalidAuthError,
+    NetworkError,
+    NotFoundError,
+    RubiFlowError,
+)
+from .models import Chat, Message, User
+from .session import Session
+
+__version__ = "1.0.0"
+__author__ = "RubiFlow Team"
+
+__all__ = [
+    "Client",
+    "Session",
+    "RubiFlowCrypto",
+    "User",
+    "Chat",
+    "Message",
+    "RubiFlowError",
+    "ApiError",
+    "InvalidAuthError",
+    "NetworkError",
+    "CryptoError",
+    "NotFoundError",
+]

rubiflow/client.py

@@ -0,0 +1,203 @@
+"""
+Core asynchronous Client for RubiFlow.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .crypto import RubiFlowCrypto
+from .exceptions import RubiFlowError, check_api_status
+from .methods import Methods
+from .models import Message, User
+from .network import AsyncTransport
+from .session import Session
+
+logger = logging.getLogger("rubiflow")
+
+
+class Client(Methods):
+    """
+    High-performance, asynchronous Rubika client framework.
+    Inherits 300+ methods covering Messenger, Rubino, VOD, and Wallet.
+    """
+
+    DEFAULT_DC_URL = "https://messengerg2c332.iranlms.ir"
+    LIB_NAME = "RubiFlow"
+    LIB_VERSION = "1.0.0"
+
+    # Rubika protocol standard client signature
+    _INTERNAL_CLIENT = {
+        "app_name": "Main",
+        "app_version": "2.5.9",
+        "platform": "PWA",
+        "package": "m.rubika.ir",
+        "lang_code": "fa",
+    }
+
+    def __init__(
+        self,
+        session: Optional[Union[Session, str]] = None,
+        auth: Optional[str] = None,
+        private_key_pem: Optional[str] = None,
+        dc_url: Optional[str] = None,
+        timeout: float = 20.0,
+    ):
+        if isinstance(session, str):
+            if session.startswith("RubiFlow$") or session.startswith("Rubix$"):
+                self.session = Session.from_string(session)
+            else:
+                self.session = Session.load_from_file(session)
+        elif isinstance(session, Session):
+            self.session = session
+        elif auth and private_key_pem:
+            self.session = Session(
+                auth=auth,
+                private_key_pem=private_key_pem,
+                dc_url=dc_url or self.DEFAULT_DC_URL,
+            )
+        else:
+            # Temporary unauthenticated session
+            priv, _ = RubiFlowCrypto.generate_rsa_key_pair()
+            tmp = RubiFlowCrypto.generate_tmp_session(32)
+            self.session = Session(
+                auth=tmp,
+                private_key_pem=priv,
+                dc_url=dc_url or self.DEFAULT_DC_URL,
+            )
+
+        self.transport = AsyncTransport(timeout_seconds=timeout)
+        self._me: Optional[User] = None
+        self._message_handlers: List[Callable[[Message], Any]] = []
+        self._is_running = False
+
+    @classmethod
+    def from_firefox(cls) -> "Client":
+        """
+        Creates a Client connected directly to the user's active session in Firefox.
+        """
+        session = Session.from_firefox()
+        return cls(session=session)
+
+    async def __aenter__(self) -> "Client":
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.stop()
+
+    async def start(self) -> None:
+        """Initializes client and verifies session authentication."""
+        try:
+            me = await self.get_me()
+            self._me = me
+            logger.info("RubiFlow connected as @%s (%s)", me.username, me.guid)
+        except Exception as exc:
+            logger.warning("RubiFlow started with unverified session: %s", exc)
+
+    async def stop(self) -> None:
+        """Closes transport and background tasks."""
+        self._is_running = False
+        await self.transport.close()
+
+    # --- Core RPC Dispatcher ---
+
+    async def execute(
+        self,
+        method: str,
+        input_data: Optional[Dict[str, Any]] = None,
+        api_version: str = "6",
+    ) -> Dict[str, Any]:
+        """
+        Executes an encrypted and RSA-signed Rubika V6 RPC method.
+        """
+        inner_payload = {
+            "method": method,
+            "input": input_data or {},
+            "client": self._INTERNAL_CLIENT,
+        }
+
+        # 1. AES encrypt inner payload with derived secret
+        data_enc = RubiFlowCrypto.encrypt_aes(inner_payload, self.session.auth)
+
+        # 2. RSA-SHA256 signature
+        sign = RubiFlowCrypto.sign_rsa_sha256(data_enc, self.session.private_key_pem)
+
+        # 3. Disguise auth token
+        disguised_auth = RubiFlowCrypto.disguise_auth(self.session.auth)
+
+        request_body = {
+            "api_version": api_version,
+            "auth": disguised_auth,
+            "data_enc": data_enc,
+            "sign": sign,
+        }
+
+        response = await self.transport.post_json(self.session.dc_url, request_body)
+
+        if "data_enc" in response:
+            decrypted = RubiFlowCrypto.decrypt_aes(response["data_enc"], self.session.auth)
+            if isinstance(decrypted, str):
+                decrypted = json.loads(decrypted)
+            check_api_status(decrypted)
+            return decrypted
+
+        check_api_status(response)
+        return response
+
+    async def invoke(self, method: str, **kwargs) -> Dict[str, Any]:
+        """
+        Directly invokes any Rubika RPC method with arbitrary input arguments.
+        Example: await app.invoke('sendMessage', object_guid='u0...', text='Hello')
+        """
+        return await self.execute(method, kwargs)
+
+    # --- Event Handling & Bot Loop ---
+
+    def on_message(self) -> Callable[[Callable[[Message], Any]], Callable[[Message], Any]]:
+        """Decorator to register an asynchronous handler for incoming messages."""
+        def decorator(func: Callable[[Message], Any]) -> Callable[[Message], Any]:
+            self._message_handlers.append(func)
+            return func
+        return decorator
+
+    async def _polling_loop(self) -> None:
+        """Background poller for message updates."""
+        while self._is_running:
+            try:
+                chats = await self.get_chats()
+                for chat in chats:
+                    if chat.unread_count > 0:
+                        msgs = await self.get_messages(chat.guid, limit=chat.unread_count)
+                        for msg in msgs:
+                            for handler in self._message_handlers:
+                                if asyncio.iscoroutinefunction(handler):
+                                    await handler(msg)
+                                else:
+                                    handler(msg)
+                await asyncio.sleep(2)
+            except Exception as exc:
+                logger.error("Polling error: %s", exc)
+                await asyncio.sleep(5)
+
+    def run(self, coro: Optional[Any] = None) -> None:
+        """
+        Convenience runner for scripts and bot processes.
+        """
+        loop = asyncio.get_event_loop()
+        if coro is not None:
+            loop.run_until_complete(coro)
+            return
+
+        async def _main():
+            async with self:
+                self._is_running = True
+                await self._polling_loop()
+
+        try:
+            loop.run_until_complete(_main())
+        except (KeyboardInterrupt, SystemExit):
+            pass
+        finally:
+            loop.run_until_complete(self.stop())

rubiflow/crypto.py

@@ -0,0 +1,169 @@
+"""
+Cryptographic engine for RubiFlow (Rubika V6 Protocol).
+Implements AES-256-CBC, custom key derivation, substitution auth disguising,
+and RSA-SHA256 asymmetric signatures.
+"""
+
+import base64
+import json
+import random
+import string
+from typing import Any, Dict, Union
+
+from cryptography.hazmat.primitives import hashes, padding
+from cryptography.hazmat.primitives.asymmetric import padding as asym_padding
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+    load_pem_private_key,
+)
+
+from .exceptions import CryptoError
+
+
+class RubiFlowCrypto:
+    """Cryptographic operations required by the Rubika V6 protocol."""
+
+    STATIC_IV = b"\x00" * 16
+
+    @staticmethod
+    def generate_rsa_key_pair() -> tuple[str, str]:
+        """
+        Generates a new 1024-bit RSA key pair in PEM format.
+        Returns: (private_key_pem, public_key_pem)
+        """
+        private_key = rsa.generate_private_key(
+            public_exponent=65537,
+            key_size=1024,
+        )
+        private_pem = private_key.private_bytes(
+            encoding=Encoding.PEM,
+            format=PrivateFormat.PKCS8,
+            encryption_algorithm=NoEncryption(),
+        ).decode("utf-8")
+
+        public_pem = private_key.public_key().public_bytes(
+            encoding=Encoding.PEM,
+            format=PublicFormat.SubjectPublicKeyInfo,
+        ).decode("utf-8")
+
+        return private_pem, public_pem
+
+    @staticmethod
+    def generate_tmp_session(length: int = 32) -> str:
+        """Generates a random lowercase ASCII string for unauthenticated sessions."""
+        return "".join(random.choices(string.ascii_lowercase, k=length))
+
+    @staticmethod
+    def create_secret_passphrase(auth: str) -> str:
+        """
+        Derives the 32-character AES secret key from an auth token or tmp_session.
+        """
+        if len(auth) < 32:
+            raise CryptoError("Auth key or tmp_session must have at least 32 characters.")
+
+        t = auth[0:8]
+        i = auth[8:16]
+        p1 = auth[16:24]
+        p2 = auth[24:32]
+
+        chars = list(p1 + t + p2 + i)
+        for idx, char in enumerate(chars):
+            if "0" <= char <= "9":
+                chars[idx] = chr((ord(char) - ord("0") + 5) % 10 + ord("0"))
+            elif "a" <= char <= "z":
+                chars[idx] = chr((ord(char) - ord("a") + 9) % 26 + ord("a"))
+
+        return "".join(chars)
+
+    @staticmethod
+    def disguise_auth(auth: str) -> str:
+        """
+        Applies the Rubika V6 character substitution cipher to the auth string.
+        """
+        result = []
+        for char in auth:
+            if "0" <= char <= "9":
+                result.append(chr((13 + (ord(char) - ord("0"))) % 10 + ord("0")))
+            elif "A" <= char <= "Z":
+                result.append(chr((29 - (ord(char) - ord("A"))) % 26 + ord("A")))
+            elif "a" <= char <= "z":
+                result.append(chr((32 - (ord(char) - ord("a"))) % 26 + ord("a")))
+            else:
+                result.append(char)
+        return "".join(result)
+
+    @classmethod
+    def encrypt_aes(cls, data: Union[Dict[str, Any], str], auth: str) -> str:
+        """
+        Encrypts a dictionary or string payload using AES-256-CBC and returns Base64.
+        """
+        try:
+            passphrase = cls.create_secret_passphrase(auth).encode("utf-8")
+            if isinstance(data, dict):
+                raw_bytes = json.dumps(
+                    data, separators=(",", ":"), ensure_ascii=False
+                ).encode("utf-8")
+            else:
+                raw_bytes = data.encode("utf-8")
+
+            padder = padding.PKCS7(128).padder()
+            padded = padder.update(raw_bytes) + padder.finalize()
+
+            cipher = Cipher(algorithms.AES(passphrase), modes.CBC(cls.STATIC_IV))
+            encryptor = cipher.encryptor()
+            ciphertext = encryptor.update(padded) + encryptor.finalize()
+
+            return base64.b64encode(ciphertext).decode("utf-8")
+        except Exception as exc:
+            raise CryptoError(f"AES encryption failed: {exc}") from exc
+
+    @classmethod
+    def decrypt_aes(cls, encrypted_b64: str, auth: str) -> Union[Dict[str, Any], str]:
+        """
+        Decrypts a Base64 AES-256-CBC ciphertext and parses it as JSON if possible.
+        """
+        try:
+            passphrase = cls.create_secret_passphrase(auth).encode("utf-8")
+            raw_ciphertext = base64.b64decode(encrypted_b64)
+
+            cipher = Cipher(algorithms.AES(passphrase), modes.CBC(cls.STATIC_IV))
+            decryptor = cipher.decryptor()
+            padded_plain = decryptor.update(raw_ciphertext) + decryptor.finalize()
+
+            unpadder = padding.PKCS7(128).unpadder()
+            plain_bytes = unpadder.update(padded_plain) + unpadder.finalize()
+            plain_text = plain_bytes.decode("utf-8")
+
+            try:
+                return json.loads(plain_text)
+            except json.JSONDecodeError:
+                return plain_text
+        except Exception as exc:
+            raise CryptoError(f"AES decryption failed: {exc}") from exc
+
+    @staticmethod
+    def sign_rsa_sha256(data_enc_b64: str, private_key_pem: str) -> str:
+        """
+        Signs the data_enc string using RSA-SHA256 with the client's private key.
+        Returns the Base64-encoded signature.
+        """
+        try:
+            pem_bytes = (
+                private_key_pem.encode("utf-8")
+                if isinstance(private_key_pem, str)
+                else private_key_pem
+            )
+            private_key = load_pem_private_key(pem_bytes, password=None)
+            signature = private_key.sign(
+                data_enc_b64.encode("utf-8"),
+                asym_padding.PKCS1v15(),
+                hashes.SHA256(),
+            )
+            return base64.b64encode(signature).decode("utf-8")
+        except Exception as exc:
+            raise CryptoError(f"RSA signature failed: {exc}") from exc

rubiflow/exceptions.py

@@ -0,0 +1,64 @@
+"""
+Custom exceptions for the RubiFlow framework.
+"""
+
+from typing import Optional
+
+
+class RubiFlowError(Exception):
+    """Base exception for all RubiFlow errors."""
+
+    def __init__(self, message: str, status_det: Optional[str] = None):
+        super().__init__(message)
+        self.message = message
+        self.status_det = status_det
+
+    def __str__(self) -> str:
+        if self.status_det:
+            return f"{self.message} (status_det: {self.status_det})"
+        return self.message
+
+
+class ApiError(RubiFlowError):
+    """Raised when the Rubika API returns an error status."""
+
+
+class InvalidAuthError(ApiError):
+    """Raised when the session authentication token is invalid or expired."""
+
+
+class NetworkError(RubiFlowError):
+    """Raised when a network or transport issue occurs."""
+
+
+class CryptoError(RubiFlowError):
+    """Raised when an encryption or decryption error occurs."""
+
+
+class NotFoundError(ApiError):
+    """Raised when a requested resource (user, chat, message) is not found."""
+
+
+class FileError(RubiFlowError):
+    """Raised when file uploading or downloading fails."""
+
+
+def check_api_status(response_data: dict) -> None:
+    """
+    Checks the status and status_det fields of a Rubika response and raises
+    the appropriate typed exception if an error is present.
+    """
+    status = response_data.get("status")
+    status_det = response_data.get("status_det")
+
+    if status == "OK":
+        return
+
+    if status_det == "INVALID_AUTH":
+        raise InvalidAuthError(
+            "The session authentication token is invalid or has expired.", status_det
+        )
+    elif status_det in ("NOT_FOUND", "USER_NOT_FOUND", "CHAT_NOT_FOUND"):
+        raise NotFoundError(f"Requested resource was not found ({status_det}).", status_det)
+    else:
+        raise ApiError(f"Rubika API returned error: {status}", status_det)

rubiflow/methods/__init__.py

@@ -0,0 +1,52 @@
+"""
+Unified Methods Mixin combining all specialized API submodules.
+"""
+
+from .auth import AuthMethods
+from .channels import ChannelsMethods
+from .chats import ChatsMethods
+from .files import FilesMethods
+from .folders import FoldersMethods
+from .groups import GroupsMethods
+from .messages import MessagesMethods
+from .rubino import RubinoMethods
+from .settings import SettingsMethods
+from .users import UsersMethods
+from .vod import VodMethods
+from .wallet import WalletMethods
+
+
+class Methods(
+    AuthMethods,
+    MessagesMethods,
+    ChatsMethods,
+    GroupsMethods,
+    ChannelsMethods,
+    UsersMethods,
+    FilesMethods,
+    FoldersMethods,
+    SettingsMethods,
+    RubinoMethods,
+    VodMethods,
+    WalletMethods,
+):
+    """
+    Combined Mixin providing direct access to 300+ Rubika RPC methods.
+    """
+
+
+__all__ = [
+    "Methods",
+    "AuthMethods",
+    "MessagesMethods",
+    "ChatsMethods",
+    "GroupsMethods",
+    "ChannelsMethods",
+    "UsersMethods",
+    "FilesMethods",
+    "FoldersMethods",
+    "SettingsMethods",
+    "RubinoMethods",
+    "VodMethods",
+    "WalletMethods",
+]

rubiflow/methods/auth.py

@@ -0,0 +1,158 @@
+"""
+Authentication, 2-Step Verification, and Session management methods.
+"""
+
+from typing import Any, Dict, List, Optional
+
+
+class AuthMethods:
+    """Methods for login, registration, 2FA, and active sessions."""
+
+    async def execute(self, method: str, input_data: Optional[Dict[str, Any]] = None, api_version: str = "6") -> Dict[str, Any]:
+        raise NotImplementedError
+
+    async def send_code(
+        self,
+        phone_number: str,
+        send_type: str = "SMS",
+    ) -> Dict[str, Any]:
+        """Sends an activation SMS or internal code to a phone number."""
+        clean_phone = phone_number.replace("+", "").replace(" ", "").strip()
+        payload = {
+            "phone_number": clean_phone,
+            "send_type": send_type,
+        }
+        return await self.execute("sendCode", payload)
+
+    async def sign_in(
+        self,
+        phone_number: str,
+        phone_code_hash: str,
+        phone_code: str,
+    ) -> Dict[str, Any]:
+        """Verifies activation code and authenticates the user."""
+        clean_phone = phone_number.replace("+", "").replace(" ", "").strip()
+        payload = {
+            "phone_number": clean_phone,
+            "phone_code_hash": phone_code_hash,
+            "phone_code": phone_code,
+        }
+        return await self.execute("signIn", payload)
+
+    async def logout(self) -> Dict[str, Any]:
+        """Logs out and invalidates the current session token."""
+        return await self.execute("logout", {})
+
+    async def register_device(
+        self,
+        device_model: str = "RubiFlow Framework",
+        system_version: str = "Linux",
+        token: str = "",
+        token_type: str = "Web",
+    ) -> Dict[str, Any]:
+        """Registers device identification for the current account."""
+        payload = {
+            "app_version": "2.5.9",
+            "device_hash": "RubiFlow-" + getattr(self, "session", None).auth[:8] if hasattr(self, "session") else "RubiFlow",
+            "device_model": device_model,
+            "is_扶_mode": False,
+            "lang_code": "fa",
+            "system_version": system_version,
+            "token": token,
+            "token_type": token_type,
+        }
+        return await self.execute("registerDevice", payload)
+
+    async def get_dcs(self) -> Dict[str, Any]:
+        """Fetches the list of active Data Center (DC) URLs."""
+        return await self.execute("getDCs", {}, api_version="4")
+
+    async def get_base_info(self) -> Dict[str, Any]:
+        """Retrieves global platform configurations and server timestamps."""
+        return await self.execute("getBaseInfo", {}, api_version="0")
+
+    # --- Two-Step Verification (2FA) ---
+
+    async def setup_two_step_verification(
+        self,
+        password: str,
+        hint: Optional[str] = None,
+        recovery_email: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Sets up a two-step verification password."""
+        payload: Dict[str, Any] = {"password": password}
+        if hint:
+            payload["hint"] = hint
+        if recovery_email:
+            payload["recovery_email"] = recovery_email
+        return await self.execute("setupTwoStepVerification", payload)
+
+    async def check_two_step_passcode(self, password: str) -> Dict[str, Any]:
+        """Validates 2FA passcode during login."""
+        return await self.execute("checkTwoStepPasscode", {"password": password})
+
+    async def change_password(
+        self,
+        old_password: str,
+        new_password: str,
+        hint: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Changes the current two-step verification password."""
+        payload: Dict[str, Any] = {
+            "old_password": old_password,
+            "new_password": new_password,
+        }
+        if hint:
+            payload["hint"] = hint
+        return await self.execute("changePassword", payload)
+
+    async def abort_two_step_setup(self) -> Dict[str, Any]:
+        """Cancels an in-progress 2FA setup."""
+        return await self.execute("abortTwoStepSetup", {})
+
+    async def login_two_step_forget_password(self, phone_code_hash: str) -> Dict[str, Any]:
+        """Requests password recovery code sent to recovery email."""
+        return await self.execute("loginTwoStepForgetPassword", {"phone_code_hash": phone_code_hash})
+
+    async def login_disable_two_step(self, phone_code_hash: str, email_code: str) -> Dict[str, Any]:
+        """Disables 2FA using email confirmation code."""
+        return await self.execute(
+            "loginDisableTwoStep",
+            {"phone_code_hash": phone_code_hash, "email_code": email_code},
+        )
+
+    async def set_recovery_email(self, email: str) -> Dict[str, Any]:
+        """Sets or updates the account recovery email."""
+        return await self.execute("setRecoveryEmail", {"email": email})
+
+    async def verify_recovery_email(self, email_code: str) -> Dict[str, Any]:
+        """Confirms the recovery email verification code."""
+        return await self.execute("verifyRecoveryEmail", {"email_code": email_code})
+
+    async def abort_set_recovery_email(self) -> Dict[str, Any]:
+        """Aborts pending recovery email verification."""
+        return await self.execute("abortSetRecoveryEmail", {})
+
+    # --- Session Management ---
+
+    async def get_my_sessions(self) -> List[Dict[str, Any]]:
+        """Retrieves list of active logged-in sessions and devices."""
+        res = await self.execute("getMySessions", {})
+        return res.get("data", {}).get("sessions", [])
+
+    async def terminate_session(self, session_key: str) -> Dict[str, Any]:
+        """Terminates a specific active session by its session key."""
+        return await self.execute("terminateSession", {"session_key": session_key})
+
+    async def terminate_user_sessions(self) -> Dict[str, Any]:
+        """Terminates all other logged-in sessions except the current one."""
+        return await self.execute("terminateUserSessions", {})
+
+    async def action_on_unconfirmed_session(
+        self, session_key: str, action: str = "Accept"
+    ) -> Dict[str, Any]:
+        """Accepts or rejects an unconfirmed session login attempt."""
+        return await self.execute(
+            "actionOnUnconfirmedSession",
+            {"session_key": session_key, "action": action},
+        )