Metadata-Version: 2.4
Name: swp_protocol
Version: 0.0.4
Summary: protocol for wrapping packets
Home-page: https://github.com/sekret01/SWP
Author: Sekret
Author-email: asinskijp188@gmail.com
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=48.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# Sekret Wrapper Protocol (SWP)

Протокол для оборачивания пакетов. Используется для передачи данных между узлами прокси.

## Установка

```bash
pip install swp-protocol
```

---

## Список объектов

- `SWP`
- `ProtocolError`
- `AesGcmCrypto`
- `MessageType`

---

### `SWP`

Класс, реализующий функции упаковки данных в протокол SWP и распаковки обратно. Не создаёт объекты, работает с байтами.

**Атрибуты класса:**

| Атрибут | Тип | Значение по умолчанию | Описание |
|---------|-----|----------------------|----------|
| `AESGCM` | `bytes` | `b""` | Ключ для AES-GCM шифрования |
| `AUTO_ENCRYPT` | `bool` | `False` | Флаг автоматического шифрования полезной нагрузки |

---

### `ProtocolError`

Базовый класс ошибок протокола.

**Наследники:**
- `AesGcmKeyError` — ошибка, связанная с AES-GCM ключом (неверная длина или отсутствие)
- `HeaderNotCompliteError` — заголовок SWP-пакета получен не полностью

---

### `AesGcmCrypto`

Внутренний класс шифрования данных пакета. По умолчанию автоматическое шифрование выключено. Данный модуль не предполагает вмешательства разработчика.

---

### `MessageType`

Класс-перечисление типов сообщений.

| Тип | Значение | Описание |
|-----|----------|----------|
| `MSG_CONNECT` | `0x01` | Соединение с сервером |
| `MSG_DATA` | `0x02` | Передача сообщения |
| `MSG_CLOSE` | `0x03` | Отключение от сервера |

> **Note:** Предназначен для использования в функции `SWP.pack()`.

---

## Формат пакета SWP

| Поле | Размер (байт) | Тип | Описание |
|------|--------------|-----|----------|
| `magic` | 3 | `bytes` | Магическое число `\x53\x57\x50` |
| `msg_type` | 1 | `byte` | Тип сообщения |
| `target_len` | 1 | `byte` | Длина поля `target` |
| `payload_len` | 2 | `short` | Длина поля `payload` |
| `target` | `target_len` | `bytes` | Адрес получателя (домен, IP:port) |
| `payload` | `payload_len` | `bytes` | Полезная нагрузка |

---

## Пример использования

```python
from swp import SWP, MessageType

# Загрузка ключа — автошифрование включается автоматически
SWP.load_aesgcm(b"32_byte_key_for_aes_gcm_encryption!!")

# Упаковка сообщения (будет зашифровано)
packet = SWP.pack(
    msg_type=MessageType.MSG_DATA,
    target=b"https://example-domain.ex",
    payload=b"Hello, world!"
)

# Распаковка
data = SWP.unpack(packet)
print(data["msg_type"], data["target"], data["payload"])

# Отключение шифрования
SWP.set_auto_encrypt(False)
```

---

## Методы класса SWP

---

### `reset()`

Сброс параметров класса до начальных значений.

| Параметр | Тип | Описание |
|----------|-----|----------|
| — | — | — |

**Возвращает:**  
`None`

---

### `set_auto_encrypt(value: bool) -> None`

Включение или отключение автоматического шифрования тела пакетов.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `value` | `bool` | `True` — включить автоматическое шифрование, `False` — выключить |

**Возвращает:**  
`None`

**Исключения:**  
`AesGcmKeyError` — если не загружен AES-GCM ключ при попытке включить шифрование.

---

### `pack(msg_type, target, payload=b"") -> bytes`

Создание SWP-пакета из переданных данных.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `msg_type` | `int` | Тип сообщения (рекомендуется использовать `MessageType`) |
| `target` | `bytes` | Адрес получателя |
| `payload` | `bytes` | Полезная нагрузка (по умолчанию пустая строка) |

**Возвращает:**  
`bytes` — сформированный SWP-пакет (заголовок + `target` + `payload`).

> **Note:** Если включён `AUTO_ENCRYPT`, `payload` будет зашифрован перед упаковкой.

---

### `unpack_header(buffer) -> tuple[bytes, int, int, int]`

Извлечение данных заголовка из сырого пакета.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `buffer` | `bytes` | Сырой SWP-пакет (полный или частичный) |

**Возвращает:**  
`tuple[bytes, int, int, int]` — кортеж из четырёх элементов:  
(`PROTOCOL_MAGIC`, `msg_type`, `target_len`, `payload_len`)

**Исключения:**  
`HeaderNotCompliteError` — если размер буфера меньше размера заголовка (`HEADER_SIZE`).

---

### `unpack(buffer) -> dict`

Полная распаковка SWP-пакета с расшифровкой (если включена).

| Параметр | Тип | Описание |
|----------|-----|----------|
| `buffer` | `bytes` | Полный SWP-пакет |

**Возвращает:**  
`dict` — словарь с ключами:  
- `"msg_type"` (`int`) — тип сообщения,  
- `"target"` (`bytes`) — адрес получателя,  
- `"payload"` (`bytes`) — полезная нагрузка (расшифрованная, если `AUTO_ENCRYPT = True`).

---

### `get_full_package_size(buffer) -> int`

Определение полного размера пакета по его заголовку.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `buffer` | `bytes` | Начало SWP-пакета (минимум размер заголовка) |

**Возвращает:**  
`int` — полный размер пакета (`HEADER_SIZE + target_len + payload_len`).  
`-1` — если переданных данных меньше размера заголовка.

---

### `load_aesgcm(key) -> None`

Загрузка 32-байтного AES-GCM ключа и автоматическое включение шифрования.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `key` | `bytes` | Ключ шифрования (должен быть ровно 32 байта) |

**Возвращает:**  
`None`

**Исключения:**  
`AesGcmKeyError` — если длина ключа не равна 32.

> **Note:** Метод загружает ключ в `SWP.AESGCM` и автоматически устанавливает `SWP.AUTO_ENCRYPT = True`.

---

### `_encode(message) -> bytes`

Шифрование сообщения с использованием загруженного AES-GCM ключа.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `message` | `str` или `bytes` | Исходное сообщение (строка автоматически кодируется в UTF-8) |

**Возвращает:**  
`bytes` — зашифрованное сообщение.

---

### `_decode(message) -> bytes`

Расшифровка сообщения.

| Параметр | Тип | Описание |
|----------|-----|----------|
| `message` | `bytes` | Зашифрованное сообщение |

**Возвращает:**  
`bytes` — расшифрованное сообщение.

---

## Информация о проекте

- **Версия:** 0.0.4
- **Python:** 3.8+
- **Репозиторий:** [github.com/sekret01/SWP](https://github.com/sekret01/SWP.git)
