Metadata-Version: 2.4
Name: cypheron
Version: 0.3.0
Summary: Authenticated streaming file encryption with Tink, encrypted keysets and Argon2id
Author: CYPHERON Team
License-Expression: Apache-2.0
Project-URL: Repository, https://gitlab.com/salyukov.gleb033/lyube-sec
Project-URL: Issues, https://gitlab.com/salyukov.gleb033/lyube-sec/-/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: cryptography<51,>=50.0.2
Requires-Dist: tink<2,>=1.16.1
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Requires-Dist: hypothesis<7,>=6.142; extra == "test"
Requires-Dist: pytest-cov<8,>=6; extra == "test"
Requires-Dist: argon2-cffi<26,>=25.1; extra == "test"
Dynamic: license-file

# CYPHERON

Аутентифицированное потоковое шифрование файлов для Python 3.10+.

**Tink Streaming AEAD · Зашифрованные наборы ключей · Контекст объекта · Apache-2.0**

[Документация и диаграммы](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/README.md) · [API](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/docs/API.md) · [Исходный код](https://gitlab.com/salyukov.gleb033/lyube-sec)

## Установка

```sh
python -m pip install cypheron==0.3.0
cypheron --version
```

Дистрибутив называется `cypheron`, импорт — `lyube_sec`, команда — `cypheron`. Нужна платформа с совместимыми wheel для Tink и cryptography.

## Возможности

- Tink AES-256-GCM-HKDF с сегментами 1 МиБ для новых интеграций.
- Привязка к доверенным `tenant`, `object_id`, `version` и ID ключа.
- Зашифрованные неизменяемые keyset-файлы и адаптер настроенного клиентом KMS.
- Потоковая ротация в отдельный файл без записи открытого текста на диск.
- Публикация выходного файла после полной проверки, приватные временные каталоги и очистка после штатных ошибок.
- CYBF v2 с AES-GCM или ChaCha20-Poly1305 и Argon2id для парольных файлов.
- Ограничения размера открытого текста и ресурсов Argon2id.

## Пример Python

Запустите пример в новом рабочем каталоге. Повторный запуск намеренно не перезаписывает существующие ключи и файлы.

```python
from pathlib import Path

from lyube_sec.api import (
    EncryptionContext,
    KeysetStore,
    create_local_wrapping_key,
    decrypt_streaming_file,
    encrypt_streaming_file,
    load_local_wrapping_key,
)

work = Path("cypheron-demo")
work.mkdir(mode=0o700)  # Новый каталог, доступный только владельцу на POSIX.
source = work / "input.txt"
source.write_text("Пример защищённого документа", encoding="utf-8")

# Однократная подготовка. В рабочем приложении отделите её от обработки файлов.
root_key = work / "root.key"
create_local_wrapping_key(root_key)
keys = KeysetStore(work / "keysets", load_local_wrapping_key(root_key))
keys.create("v1")

context = EncryptionContext(
    tenant="customer-42",
    object_id="document-7",
    version=1,
)

encrypt_streaming_file(
    keys=keys,
    key_id="v1",
    context=context,
    in_path=source,
    out_path=work / "encrypted.tink",
    max_bytes=10 * 1024 * 1024,  # Политика приложения: до 10 МиБ.
)

decrypt_streaming_file(
    keys=keys,
    key_id="v1",
    context=context,
    in_path=work / "encrypted.tink",
    out_path=work / "restored.txt",
    max_bytes=10 * 1024 * 1024,
)

assert source.read_bytes() == (work / "restored.txt").read_bytes()
```

Для компактности пример хранит все данные рядом. Корневой файл `root.key` **не зашифрован**: в эксплуатации защищайте его отдельно от keyset-файлов и их резервной копии. Сервер может использовать `KeysetStore.from_kms_client(...)`; права, учётные данные и SDK провайдера настраиваются отдельно.

Контекст необходимо сохранять в доверенной записи приложения. Библиотека не поддерживает собственную базу версий и не отклоняет повтор того же подлинного файла с тем же контекстом.

## Файлы под паролем

```sh
cypheron file-enc --password input.txt encrypted.cybf
cypheron file-dec --password encrypted.cybf restored.txt
```

Пароль вводится скрыто в терминале. Argon2id по умолчанию использует 64 МиБ, три прохода и четыре полосы. Бюджет процесса — 128 МиБ и две параллельные KDF-операции; сервис должен ограничивать суммарную нагрузку отдельно.

Tink и CYBF — разные форматы; используйте соответствующий API или CLI. Экспериментальный CYBF v1 отклоняется.

## Безопасность и проверка

Версия 0.3.0 локально проверена на macOS arm64: 198 тестов на Python 3.10 и 3.13, 93% покрытия строк; 3000 ограниченных мутаций потоков отклонены. Это не независимый аудит, сертификация или гарантия отсутствия ошибок. Удалённые проверки зависят от доступности CI; смотрите [pipeline](https://gitlab.com/salyukov.gleb033/lyube-sec/-/pipelines).

Расшифрование временно сохраняет открытый текст в приватном каталоге. Аварийная остановка может оставить временные данные. Нужна доверенная локальная файловая система; на Windows приватность зависит от ACL. Python не гарантирует стирание секретов из памяти. Компрометация хоста, утрата ключей, слабые пароли и авторизация приложения находятся за пределами гарантий шифрования.

[Политика безопасности](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/SECURITY.md) · [Модель угроз](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/docs/SECURITY.md) · [Результаты проверки](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/SECURITY_AUDIT_REPORT.md) · [Ключи и восстановление](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/docs/OPERATIONS.md)

## Лицензия

Copyright 2026 salyukov.gleb033 and contributors. Код и документация проекта распространяются по [Apache-2.0](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/LICENSE), если для стороннего материала не указано иное. [Уведомления об авторстве](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/NOTICE) и [лицензии зависимостей](https://gitlab.com/salyukov.gleb033/lyube-sec/-/blob/main/docs/THIRD_PARTY.md) сохраняют применимость.
