Гид контрибьютора tessera

Этот документ — гид для разработчика, который впервые открывает репозиторий и хочет внести изменение. Цель: рабочее окружение, прохождение тестов и первый PR за один день.

1. Локальная сборка

1.1 Системные зависимости

Astra Linux SE / Ubuntu 22.04 / Debian 12:

sudo apt install -y \
    build-essential pkg-config \
    libssl-dev libudev-dev libdbus-1-dev libpam0g-dev libsystemd-dev \
    softhsm2 opensc opensc-pkcs11 \
    pamtester clang

Toolchain Rust — фиксирован в rust-toolchain.toml. При наличии rustup toolchain скачивается автоматически:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup show              # выберет версию из rust-toolchain.toml

1.2 Сборка

cargo build --workspace
cargo build --workspace --release

1.3 Cargo features

Default: без специальных фич.
tessera_core/pkcs11-tests — включает интеграционные тесты, требующие реального gost-engine или softhsm2. Рецепт запуска с инициализацией токена softhsm2 — в §2.2.

2. Тесты

2.1 Юнит и обычные интеграционные тесты

cargo test --workspace

Все unit- и integration-тесты должны проходить.

2.2 Интеграционные тесты с softhsm2

sudo apt install softhsm2 opensc-pkcs11
softhsm2-util --init-token --slot 0 \
    --label test --pin 1234 --so-pin 5678
SOFTHSM2_CONF=/etc/softhsm/softhsm2.conf \
    cargo test --workspace --features tessera_core/pkcs11-tests

PKCS#11-тесты добавляют дополнительный набор интеграционных проверок (загрузка модуля, поиск сертификата, проверка CKA_EXTRACTABLE).

2.3 Smoke с `pamtester`

Требует Linux + root + установленный tessera:

# В отдельной VM Astra SE 1.8:
sudo apt install ./target/release/tessera_0.4.0-1_amd64.deb
sudo /usr/share/tessera/integrate-pam.sh --mode=2fa /etc/pam.d/sudo
pamtester sudo alice authenticate

3. Pre-commit hooks

В корне репозитория поставляется .pre-commit-config.yaml. Установка:

pip install pre-commit
pre-commit install

Что проверяется при коммите:

cargo fmt --all -- --check;
cargo clippy --workspace --all-targets -- -D warnings;
cargo deny check;
cargo test --workspace;
синтаксис bash-скриптов (bash -n);
совпадение версии Cargo.toml ↔ debian/changelog;
отсутствие placeholder’ов MAX_INTEGRITY OID в трекаемых файлах.

Если у вас нет pre-commit-фреймворка, можно запускать команды вручную:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

4. Стиль коммитов

Формат — Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Сообщения коммитов — на английском. Примеры:

feat(monitord): handle suspend/resume via D-Bus
fix(core): correct CRL freshness check for mode = "crl"
docs(install): add Mode A scenario with FAT32 media
chore: bump serde to 1.0.x
refactor(proto): rename Pong to HelloAck for consistency
test(monitord): add suspend_grace e2e test

<scope> соответствует крейту или модулю: monitord, core, proto, pam, install, arch, security, release, dev.

5. Workflow PR

Branch off main:

git checkout -b feat/awesome-feature main

Атомарные коммиты: один логически целостный коммит за раз. PR обычно содержит 1–5 коммитов.
Авто-запуск CI: GitHub Actions:
- .github/workflows/build.yml — тесты (ubuntu: cargo test, astra-контейнер: cargo nextest run), сборка .deb в обоих вариантах, lintian (ubuntu-нога);
- .github/workflows/lint.yml — cargo clippy -D warnings и supply-chain (cargo deny, cargo audit);
- .github/workflows/nightly.yml — ежесуточный прогон тестов в release-профиле. cargo fmt --check гоняется pre-commit-хуком, не в CI.
Code review checklist:
- есть ли тест на новую функциональность?
- обновлены ли соответствующие docs (configuration, architecture, threat-model)?
- не появилось ли новое поле в TOML без документации?
- не нарушает ли изменение fail-closed инварианты (см. architecture.md §13)?
- reproducible build не сломался?
Слить через squash + rebase merge. Большие PR — review по 3–5 коммитов; squash в main для чистой истории.

6. Как добавить новый PKCS#11-провайдер

Текущая поддержка реализована в crates/tessera_core/src/token/.

Шаги:

Изучить интерфейсы (PkcsModule, Session, Slot).
Реализовать новый адаптер в подмодуле (например, token/newvendor/).
Зарегистрировать его через crypto_backend = "pkcs11_native" с указанием pkcs11_module = "/usr/lib/libnewvendor.so".
Добавить тесты:
- positive: загрузка модуля + поиск сертификата;
- negative: модуль не загрузился (несуществующий путь);
- non-extractable: проверка CKA_EXTRACTABLE = false.
Обновить документацию:
- README.md — раздел «Поддерживаемые токены»;
- docs/install.md — раздел установки драйвера;
- docs/configuration.md — таблица модулей;
- docs/threat-model.md — §3.3 (если меняется модель угроз).

7. Как добавить новый источник host_id

См. crates/tessera_core/src/host_identity/.