rubiflow 1.0.0__tar.gz

rubiflow-1.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: rubiflow
+Version: 1.0.0
+Summary: High-Performance Async Python Framework for Rubika Messenger and SuperApp
+Author: RubiFlow Developers
+License-Expression: MIT
+Keywords: rubika,rubiflow,rubika-bot,async-rubika,messenger,superapp
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: cryptography>=41.0.0
+
+# ⚡ RubiFlow (روبی‌فلو)
+
+> **فریم‌ورک فوق‌سریع، ناهمگام (Async) و مدرن پایتون برای پیام‌رسان و سوپراپ روبیکا**  
+> *Next-Generation High-Performance Async Python Framework for Rubika Messenger & SuperApp*
+
+---
+
+## 🌟 چرا RubiFlow؟
+
+- **نام کاملاً اختصاصی و جدید:** نامی تک و ثبت‌نشده در PyPI که به جریان روان، غیرهمزمان و پرسرعت اشاره دارد.
+- **Async-First و با بالاترین بازده:** با موتور شبکه `aiohttp`، مدیریت Connection Pooling و رمزنگاری با توابع C در `cryptography`.
+- **رعایت کامل استانداردهای PEP 8 و Clean Architecture:** استفاده دقیق از Type Hints، مدل‌های داده‌ای (`dataclasses`) و مدیریت خطا با استثناهای اختصاصی.
+- **شناسایی خودکار سشن فایرفاکس:** توانایی اتصال آنی به حساب فعال در فایرفاکس (بدون نیاز به دریافت کد پیامکی مجدد).
+- **پشتیبانی از StringSession:** خروجی سشن به صورت یک رشته متنی فشرده و امن با پیشوند `RubiFlow$...` جهت استقرار روی سرورها.
+- **پوشش جامع بیش از ۳۰۰ متد:** پشتیبانی از پیام‌رسان کامل، روبینو (Rubino)، فیلم و سریال (VOD) و کیف پول.
+- **توابع کمکی و شی‌گرایی پیشرفته:** ارسال آسان پیام، ریپلای مستقیم با `message.reply("...")`، حذف و ویرایش، دریافت چت‌ها و پیام‌ها.
+
+---
+
+## 📦 نصب
+
+```bash
+pip install -e .
+```
+
+یا پیش‌نیازها:
+```bash
+pip install aiohttp cryptography
+```
+
+---
+
+## 🚀 شروع سریع (Quickstart)
+
+### ۱. اتصال خودکار از طریق سشن فایرفاکس
+```python
+import asyncio
+from rubiflow import Client
+
+async def main():
+    # اتصال مستقیم به سشن مرورگر فایرفاکس شما
+    app = Client.from_firefox()
+
+    async with app:
+        me = await app.get_me()
+        print(f"Logged in as: {me.full_name} (@{me.username})")
+
+        # ارسال پیام
+        msg = await app.send_message("u0...", "سلام از روبی‌فلو!")
+        print(f"پیام ارسال شد با آیدی: {msg.message_id}")
+
+asyncio.run(main())
+```
+
+---
+
+### ۲. ساخت بات پاسخگوی خودکار (Event-Driven Echo Bot)
+```python
+from rubiflow import Client, Message
+
+app = Client.from_firefox()
+
+@app.on_message()
+async def handle_message(msg: Message):
+    if msg.text == "سلام":
+        await msg.reply("درود! پیام شما توسط بات RubiFlow دریافت شد.")
+
+# اجرای مداوم بات
+app.run()
+```
+
+---
+
+### ۳. استفاده از رشته سشن (StringSession) برای سرور
+```python
+import asyncio
+from rubiflow import Client
+
+async def export_session():
+    app = Client.from_firefox()
+    async with app:
+        # دریافت رشته امن برای قرار دادن روی سرور یا متغیرهای محیطی
+        string_session = app.session.to_string()
+        print("Your StringSession:", string_session)
+
+        # بازیابی مجدد سشن
+        new_app = Client(session=string_session)
+        async with new_app:
+            me = await new_app.get_me()
+            print("Connected with StringSession as:", me.username)
+
+asyncio.run(export_session())
+```
+
+---
+
+## 📂 ساختار ماژولار پروژه
+
+```
+rubika-lib/
+├── pyproject.toml              # پیکربندی استاندارد بسته پایتون
+├── README.md                   # راهنمای کامل
+├── rubiflow/
+│   ├── __init__.py             # اکسپورت کلاس‌ها و توابع اصلی
+│   ├── client.py               # هسته کلاینت و متدهای سطح بالا
+│   ├── crypto.py               # موتور پرسرعت رمزنگاری روبیکا V6 (AES-256 + RSA-SHA256)
+│   ├── session.py              # مدیریت سشن (Firefox, StringSession, FileSession)
+│   ├── network.py              # ارتباطات ناهمگام با Connection Pooling
+│   ├── exceptions.py           # استثناهای اختصاصی (InvalidAuthError, ApiError, ...)
+│   └── models/
+│       ├── user.py             # کلاس داده کاربر (User)
+│       ├── chat.py             # کلاس داده گفتگو (Chat)
+│       └── message.py          # کلاس داده پیام همراه متدهای reply, delete, edit
+├── docs/
+│   ├── RUBIKA_API_FULL_REFERENCE.md   # کاتالوگ جامع بیش از ۳۰۰ متد روبیکا
+│   └── RUBIKA_CRYPTO_AND_PROTOCOL.md  # جزئیات مهندسی معکوس و رمزنگاری
+└── examples/
+    └── rubiflow_quickstart.py  # نمونه کد تست زنده و جامع
+```
+
+---
+
+## 🛡️ لایسنس
+توسعه داده شده تحت لایسنس MIT.

rubiflow-1.0.0/README.md

@@ -0,0 +1,124 @@
+# ⚡ RubiFlow (روبی‌فلو)
+
+> **فریم‌ورک فوق‌سریع، ناهمگام (Async) و مدرن پایتون برای پیام‌رسان و سوپراپ روبیکا**  
+> *Next-Generation High-Performance Async Python Framework for Rubika Messenger & SuperApp*
+
+---
+
+## 🌟 چرا RubiFlow؟
+
+- **نام کاملاً اختصاصی و جدید:** نامی تک و ثبت‌نشده در PyPI که به جریان روان، غیرهمزمان و پرسرعت اشاره دارد.
+- **Async-First و با بالاترین بازده:** با موتور شبکه `aiohttp`، مدیریت Connection Pooling و رمزنگاری با توابع C در `cryptography`.
+- **رعایت کامل استانداردهای PEP 8 و Clean Architecture:** استفاده دقیق از Type Hints، مدل‌های داده‌ای (`dataclasses`) و مدیریت خطا با استثناهای اختصاصی.
+- **شناسایی خودکار سشن فایرفاکس:** توانایی اتصال آنی به حساب فعال در فایرفاکس (بدون نیاز به دریافت کد پیامکی مجدد).
+- **پشتیبانی از StringSession:** خروجی سشن به صورت یک رشته متنی فشرده و امن با پیشوند `RubiFlow$...` جهت استقرار روی سرورها.
+- **پوشش جامع بیش از ۳۰۰ متد:** پشتیبانی از پیام‌رسان کامل، روبینو (Rubino)، فیلم و سریال (VOD) و کیف پول.
+- **توابع کمکی و شی‌گرایی پیشرفته:** ارسال آسان پیام، ریپلای مستقیم با `message.reply("...")`، حذف و ویرایش، دریافت چت‌ها و پیام‌ها.
+
+---
+
+## 📦 نصب
+
+```bash
+pip install -e .
+```
+
+یا پیش‌نیازها:
+```bash
+pip install aiohttp cryptography
+```
+
+---
+
+## 🚀 شروع سریع (Quickstart)
+
+### ۱. اتصال خودکار از طریق سشن فایرفاکس
+```python
+import asyncio
+from rubiflow import Client
+
+async def main():
+    # اتصال مستقیم به سشن مرورگر فایرفاکس شما
+    app = Client.from_firefox()
+
+    async with app:
+        me = await app.get_me()
+        print(f"Logged in as: {me.full_name} (@{me.username})")
+
+        # ارسال پیام
+        msg = await app.send_message("u0...", "سلام از روبی‌فلو!")
+        print(f"پیام ارسال شد با آیدی: {msg.message_id}")
+
+asyncio.run(main())
+```
+
+---
+
+### ۲. ساخت بات پاسخگوی خودکار (Event-Driven Echo Bot)
+```python
+from rubiflow import Client, Message
+
+app = Client.from_firefox()
+
+@app.on_message()
+async def handle_message(msg: Message):
+    if msg.text == "سلام":
+        await msg.reply("درود! پیام شما توسط بات RubiFlow دریافت شد.")
+
+# اجرای مداوم بات
+app.run()
+```
+
+---
+
+### ۳. استفاده از رشته سشن (StringSession) برای سرور
+```python
+import asyncio
+from rubiflow import Client
+
+async def export_session():
+    app = Client.from_firefox()
+    async with app:
+        # دریافت رشته امن برای قرار دادن روی سرور یا متغیرهای محیطی
+        string_session = app.session.to_string()
+        print("Your StringSession:", string_session)
+
+        # بازیابی مجدد سشن
+        new_app = Client(session=string_session)
+        async with new_app:
+            me = await new_app.get_me()
+            print("Connected with StringSession as:", me.username)
+
+asyncio.run(export_session())
+```
+
+---
+
+## 📂 ساختار ماژولار پروژه
+
+```
+rubika-lib/
+├── pyproject.toml              # پیکربندی استاندارد بسته پایتون
+├── README.md                   # راهنمای کامل
+├── rubiflow/
+│   ├── __init__.py             # اکسپورت کلاس‌ها و توابع اصلی
+│   ├── client.py               # هسته کلاینت و متدهای سطح بالا
+│   ├── crypto.py               # موتور پرسرعت رمزنگاری روبیکا V6 (AES-256 + RSA-SHA256)
+│   ├── session.py              # مدیریت سشن (Firefox, StringSession, FileSession)
+│   ├── network.py              # ارتباطات ناهمگام با Connection Pooling
+│   ├── exceptions.py           # استثناهای اختصاصی (InvalidAuthError, ApiError, ...)
+│   └── models/
+│       ├── user.py             # کلاس داده کاربر (User)
+│       ├── chat.py             # کلاس داده گفتگو (Chat)
+│       └── message.py          # کلاس داده پیام همراه متدهای reply, delete, edit
+├── docs/
+│   ├── RUBIKA_API_FULL_REFERENCE.md   # کاتالوگ جامع بیش از ۳۰۰ متد روبیکا
+│   └── RUBIKA_CRYPTO_AND_PROTOCOL.md  # جزئیات مهندسی معکوس و رمزنگاری
+└── examples/
+    └── rubiflow_quickstart.py  # نمونه کد تست زنده و جامع
+```
+
+---
+
+## 🛡️ لایسنس
+توسعه داده شده تحت لایسنس MIT.

rubiflow-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rubiflow"
+version = "1.0.0"
+description = "High-Performance Async Python Framework for Rubika Messenger and SuperApp"
+readme = "README.md"
+authors = [{ name = "RubiFlow Developers" }]
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+    "aiohttp>=3.9.0",
+    "cryptography>=41.0.0"
+]
+keywords = ["rubika", "rubiflow", "rubika-bot", "async-rubika", "messenger", "superapp"]
+
+[tool.setuptools.packages.find]
+include = ["rubiflow*"]

rubiflow-1.0.0/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-1.0.0/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-1.0.0/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