Merge pull request #14 from tanem/docs/release-env-protection

docs: release wiring + accuracy pass across living docs

Author: tanem

CONTRIBUTING.md

@@ -12,7 +12,7 @@ uv run pre-commit install            # enable the gitleaks secret-scan hook
 ## Running tests and hooks
 
 ```bash
-uv run pytest                        # run the test suite (coverage gate: ≥95%)
+uv run pytest                        # run the test suite (coverage gate: 100%)
 uv run pre-commit run --all-files    # run the gitleaks hook manually
 uv run ruff check src/ tests/        # lint
 uv run ruff format --check src/ tests/  # check formatting
@@ -71,20 +71,20 @@ Don't hand-bump these versions — let Renovate's PRs flow through.
 
 Releases publish to PyPI via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — there is no stored API token. The publish workflow is [`.github/workflows/release.yml`](.github/workflows/release.yml).
 
-**One-time setup (already done for an existing project, required once per index):**
+**How it's wired:**
 
-- On PyPI and TestPyPI, register a pending publisher: owner `tanem`, repository `mt5-pnl-exporter`, workflow `release.yml`, environment `pypi` (PyPI) / `testpypi` (TestPyPI).
-- On GitHub, create the `pypi` and `testpypi` repository Environments.
+- The repo has two GitHub Environments, `pypi` and `testpypi`. The `pypi` Environment requires a reviewer (`tanem`), so a real publish pauses for manual approval before the immutable upload. "Prevent self-review" is off, so the solo maintainer approves their own release.
+- Both indices have a pending publisher registered — owner `tanem`, repository `mt5-pnl-exporter`, workflow `release.yml`, environment `pypi` (PyPI) / `testpypi` (TestPyPI). Each index needs this registered once before its first publish.
 
-**Rehearse to TestPyPI** (validates the OIDC handshake and the rendered page without burning a real version):
+**Rehearse to TestPyPI** — validates the OIDC handshake and the rendered page without burning a real version:
 
-1. Actions tab → `release` workflow → Run workflow (`workflow_dispatch`). This builds and uploads to TestPyPI.
+1. Actions tab → `release` workflow → Run workflow (`workflow_dispatch`). Builds and uploads to TestPyPI.
 
 **Publish a real release:**
 
 1. Tag the commit, e.g. `git tag v1.0.0`.
 2. Draft a GitHub Release against that tag with release notes (the notes are the changelog).
-3. Publish the Release. The `release: published` event runs `release.yml`, which builds and uploads to PyPI.
+3. Publish the Release. The `release: published` event runs `release.yml` and the publish job pauses on the `pypi` Environment. Approve it in the Actions tab; the job then builds and uploads to PyPI.
 
 A PyPI version is immutable once uploaded — the version number cannot be reused. The TestPyPI rehearsal de-risks the first upload.
 

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Scope
 
-This tool handles **read-only MT5 investor passwords** — credentials that can view account data but cannot place or modify trades — and a **snapshot encryption passphrase** used to age-encrypt the on-disk snapshot. Both live only on the Windows host where `poll` runs, in its OS keychain via `keyring` (Windows Credential Manager). Neither is written to disk, logs, or the snapshot file.
+This tool handles **read-only MT5 investor passwords** — credentials that can view account data but cannot place or modify trades — and a **snapshot encryption passphrase** used to age-encrypt the on-disk snapshot. Both live only on the Windows host where `export` runs, in its OS keychain via `keyring` (Windows Credential Manager). Neither is written to disk, logs, or the snapshot file.
 
 Vulnerabilities in scope:
 
@@ -22,6 +22,7 @@ Out of scope:
 - **GitHub Actions are pinned to commit SHAs** (not mutable tags), so a compromised or retagged action cannot inject code into CI. [Renovate](https://docs.renovatebot.com/) keeps the pins current via `helpers:pinGitHubActionDigests`.
 - **`lockFileMaintenance`** periodically refreshes `uv.lock` so transitive dependency security patches are picked up rather than pinned indefinitely.
 - Dependency update PRs (Renovate) must pass the full `tests` workflow before merging; see [`renovate.json`](renovate.json) and [`CONTRIBUTING.md`](CONTRIBUTING.md).
+- **Releases publish via PyPI [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)** (OIDC), so no long-lived PyPI API token is stored in the repo or CI; the `pypi` deployment environment also gates a real publish on manual approval. See [`CONTRIBUTING.md`](CONTRIBUTING.md)'s Releasing section.
 
 ## Reporting
 

docs/security-audit.md

@@ -20,7 +20,7 @@ Findings are listed below the table with patch references.
 | `secrets.py::get_encryption_passphrase` | passphrase | keychain read | n/a | n/a | ✓ returns to caller |
 | `secrets.py::set_encryption_passphrase` | passphrase | keychain write | ✓ | ✓ | ✓ accepts from caller |
 | `config.py::resolve_passwords` | investor pw | keychain read → dict | ✓ | ✓ (registered with `redact_filter` on read) | ✓ scoped to `MT5Source._passwords` |
-| `cli.py::poll` (encryption passphrase load) | passphrase | keychain read → `snapshot.read/write` | ✓ | ✓ (registered with `redact_filter` on read) | ✓ goes only to `pyrage.passphrase.encrypt/decrypt` |
+| `cli.py::export` (encryption passphrase load) | passphrase | keychain read → `snapshot.read/write` | ✓ | ✓ (registered with `redact_filter` on read) | ✓ goes only to `pyrage.passphrase.encrypt/decrypt` |
 | `secrets.py::redact_filter` | n/a (boundary) | log filter | n/a | n/a | covers `logging` handlers only; `rich.Console` output bypasses it — see **Finding 2** |
 | `config.py::check_file_perms` | n/a (boundary) | warn on `config.yaml` group/other-read | n/a | n/a | POSIX-only; no-op on Windows |