# RootPack_RU Packaging Guide

This guide describes the reproducible process for assembling the sovereign cryptography bundle that backs RootPack_RU deployments.

## 1. What the bundle contains

| Directory | Purpose |
|-----------|---------|
| `artifacts/` | Published binaries for `StellaOps.Cryptography.Plugin.CryptoPro` and `StellaOps.Cryptography.Plugin.Pkcs11Gost` (targeting `net10.0`). |
| `config/rootpack_ru.crypto.yaml` | Opinionated configuration template that enables the `ru-offline` crypto profile and defines CryptoPro + PKCS#11 keys. |
| `docs/` | Validation runbook, audit report, and this packaging guide. |
| `trust/` | Russian trust-anchor PEM files copied from `certificates/russian_trusted_*`. |
| `README.txt` | High-level summary plus operator checklist. |

## 2. Build the bundle

```bash
# from repository root
scripts/crypto/package-rootpack-ru.sh
# optionally specify destination
scripts/crypto/package-rootpack-ru.sh /tmp/rootpack_ru_$(date -u +%Y%m%dT%H%M%SZ)
```

The script performs the following steps:

1. `dotnet publish` for the CryptoPro + PKCS#11 plug-ins (`Release` configuration).
2. Copies the relevant documentation (`docs/security/rootpack_ru_validation.md`, `docs/security/crypto-routing-audit-2025-11-07.md`, and this guide).
3. Includes the example configuration found at `etc/rootpack/ru/crypto.profile.yaml`.
4. Adds the Russian trust anchors from `certificates/russian_trusted_*`.
5. Emits `README.txt` and optionally creates a `*.tar.gz` archive (set `PACKAGE_TAR=0` to skip the tarball).

## 3. Attach deterministic test evidence

After running `scripts/crypto/package-rootpack-ru.sh`, execute the deterministic harness to capture logs:

```bash
scripts/crypto/run-rootpack-ru-tests.sh
# or specify ROOTPACK_LOG_DIR=/tmp/rootpack_ru_tests scripts/crypto/run-rootpack-ru-tests.sh
```

Copy the resulting `logs/rootpack_ru_<timestamp>/` directory into the bundle before distributing it (or store it alongside the tarball in your evidence store).

Each harness run produces a `README.tests` file plus matching `.log/.trx` pairs for every project. Move the entire directory under an evidence folder inside the bundle (for example `evidence/validation/<timestamp>/`) so operators can quickly locate the README, raw logs, and provider JSON snapshots when assembling compliance paperwork:

```bash
dest="${1:-out/rootpack_ru}"
ts="$(ls logs | grep rootpack_ru_ | sort | tail -n1)"
mkdir -p "${dest}/evidence/validation"
cp -a "logs/${ts}" "${dest}/evidence/validation/${ts}"
```

## 4. Hardware validation + audit metadata

Follow `docs/security/rootpack_ru_validation.md` to:

- Validate CryptoPro CSP and PKCS#11 tokens.
- Capture `stellaops crypto providers --profile ru-offline --json` output.
- Archive JWKS snapshots and `CryptoProviderMetrics` samples.
- Document hardware serials and operator initials in `hardware_notes.md`.

Store these artifacts under `logs/rootpack_ru_<timestamp>/` (same directory as the test harness outputs) and reference them in release paperwork.

## 5. Deployment summary

1. Import the bundled trust anchors into the target installation (Authority + Scanner).
2. Apply `config/rootpack_ru.crypto.yaml`, update certificate thumbprints, slots, and container labels to match the operator tokens.
3. Restart the services so `ICryptoProviderRegistry` reloads the `ru-offline` profile.
4. Re-run the validation runbook to confirm JWKS, telemetry, and RootPack evidence are aligned with the shipping bundle.