diff --git a/README.md b/README.md index 865a75a..977ecbf 100644 --- a/README.md +++ b/README.md @@ -156,7 +156,10 @@ The administrator journey from Core-only bootstrap through online module installation, scale-out, and reversible environment promotion is defined in [System Administrator Lifecycle User Story](docs/SYSTEM_ADMINISTRATOR_LIFECYCLE_USER_STORY.md). The first Campaign-centric capability and infrastructure fit assessment is in -`docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`. +`docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md`. Its rerun tooling can collect and +verify a bounded installed composition; target, provider and production claims +remain separate, expiring attestations signed by independently scoped proof +authorities. # GovOPlaN Docker diff --git a/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md b/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md index 82ed3f3..220d811 100644 --- a/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md +++ b/docs/CAPABILITY_AND_INFRASTRUCTURE_FIT.md @@ -372,6 +372,103 @@ metadata, published-keyring integrity and optional local tag provenance; it does not prove installed artifacts, target providers, target infrastructure, or production fitness. Those remain separate proof checks above. +### Installed-composition evidence + +The same rerun can inspect the Python environment in which it executes and bind +that observation to the assessment and signed catalog: + +```bash +./.venv/bin/python tools/assessments/capability-fit.py \ + --public \ + --trusted-keyring /srv/govoplan/trust/catalog-keyring.json \ + --collect-installed-evidence /var/tmp/govoplan-installed-evidence.json \ + --output /var/tmp/govoplan-fit-review.json +``` + +The collector follows the strict +[`installed-composition-evidence.schema.json`](installed-composition-evidence.schema.json) +contract. It enumerates all installed distributions whose normalized name starts +with `govoplan-`, compares the enabled assessed package and module-manifest +versions, and identifies missing, duplicate and extra GovOPlaN distributions. +Those differences produce stable review targets for the affected composition +entries and evidence-backed conclusions. + +For each distribution, the collector also: + +- verifies every supported SHA-256 entry in installed wheel `RECORD` metadata, + within fixed limits of 256 GovOPlaN distributions, 10,000 files and 512 MiB + hashed per distribution, 50,000 files and 2 GiB hashed for one collection, + and 64 MiB for any single file; +- distinguishes immutable VCS commits and archive hashes from editable installs, + local directories, package-index/unknown origins and malformed metadata; +- compares a non-editable VCS commit with the assessment commit and, when one is + present, the signed catalog `selected_units` commit; +- records only package/module identifiers, versions, bounded counters, hashes + and stable error codes. It never writes direct URLs, paths, hostnames, + usernames, exception text or file contents. + +`RECORD` agreement proves that the files agree with their installed metadata; it +does not make self-consistent metadata a trusted release origin. Similarly, a +version string is not artifact integrity. Editable and directory-backed installs +remain mutable even when their small editable-install `RECORD` is valid. Archive +or index artifacts without a hash anchored by the assessed release remain +unanchored. These conditions cause review rather than being promoted to +immutable installed-release proof. + +Use `--installed-evidence PATH` to review evidence collected in a separate +environment. Evidence input and output are bounded to 4 MiB. Collection loads +the `govoplan.modules` entry-point factories in order to read module IDs and +manifest versions; that executes installed GovOPlaN manifest code. Run it only +inside the installation being assessed and with the same isolation expected for +other installed-artifact acceptance checks. This collector does not observe +which modules a running service activated, migrations, configuration, health, +or reference-journey behavior. Runtime activation therefore remains an explicit +unchecked boundary. + +### Target, provider and production proof boundary + +Installed evidence cannot approve a target environment, an external provider, +or production use. These scopes use a separate, expiring +[`capability-fit-boundary-evidence.schema.json`](capability-fit-boundary-evidence.schema.json) +bundle. The bundle is bound to the assessment ID, assessment release and exact +installed-evidence SHA-256 digest. It contains only opaque subject/control/result +IDs and content hashes, not endpoints, credentials, people or raw result files. + +Boundary evidence is accepted only when at least one Ed25519 signature validates +against a separately provisioned +[`capability-fit-proof-authority-keyring.schema.json`](capability-fit-proof-authority-keyring.schema.json). +Each authority key explicitly lists the scopes it may attest. Target and provider +claims use `passed` or `failed`; production claims use `approved` or `rejected`. +One claim per scope, unique control/artifact IDs, `issued_at < expires_at`, current +validity and exact digest binding are mandatory. Any schema, binding, time, +signature or authority blocker leaves every supplied boundary claim unchecked; +an authorized negative result is checked but requires review. +Signatures cover UTF-8 JSON with the `signatures` member omitted, object keys +sorted, compact `,`/`:` separators and non-ASCII characters escaped, matching +the tool's deterministic canonicalization. + +```bash +./.venv/bin/python tools/assessments/capability-fit.py \ + --public \ + --trusted-keyring /srv/govoplan/trust/catalog-keyring.json \ + --installed-evidence /srv/govoplan/evidence/installed.json \ + --boundary-evidence /srv/govoplan/evidence/target-proof.json \ + --boundary-authority-keyring /srv/govoplan/trust/proof-authorities.json +``` + +The authority keyring is a governance trust root. Do not download or generate it +from the proof bundle being checked, and do not reuse catalog signing authority +as implicit production authority. A target operator or approver must validate +the referenced drill/result artifacts before signing. The rerun verifies the +attestation and its bindings; it does not fetch or reinterpret those artifacts. +`--verification-time` exists for reproducible historical review. Live admission +must use the actual current time. + +No boundary bundle or production authority has been supplied for this current +assessment. Target environment, provider and production proof therefore remain +explicitly unchecked rather than inferred from the local GreenMail journey, +source tests or signed release metadata. + ## Evidence used in this slice - [Production-like profile](../dev/production-like/README.md) and @@ -389,6 +486,9 @@ production fitness. Those remain separate proof checks above. verified against a separately provisioned local trust keyring - Annotated source tags `govoplan-core/v0.1.13` and `govoplan-campaign/v0.1.10`, including their catalogued Python and WebUI refs +- Installed-composition, boundary-proof and independently scoped proof-authority + schemas plus their deterministic review tests; no current target or production + proof bundle is asserted Checks retained from the first assessment slice against its then-current workspace: diff --git a/docs/capability-fit-current.json b/docs/capability-fit-current.json index 3eba146..7dc3f9c 100644 --- a/docs/capability-fit-current.json +++ b/docs/capability-fit-current.json @@ -967,10 +967,12 @@ ], "proof_checks": [ "Materialize the signed catalog into an isolated installation and rerun contract, migration and module-permutation gates against the installed artifacts.", + "Collect the isolated installation with the bounded installed-composition evidence contract; require exact enabled package/module versions, complete RECORD verification and immutable provenance anchored to this assessment.", "Run a safe target-like Campaign through SMTP acceptance, IMAP append, reporting and audit.", "Drill worker, Redis and ambiguous-delivery failures without duplicate sends.", "Restore PostgreSQL, managed files, configuration and encrypted credentials and measure RPO/RTO.", "Validate proxy/TLS, cookies/CORS, account bootstrap, secret redaction, monitoring and alert delivery.", - "Measure representative Campaign/file/queue/database load and external throttling." + "Measure representative Campaign/file/queue/database load and external throttling.", + "Require separately issued, expiring and independently scope-authorized evidence before marking target environment, external provider or production approval proof as checked." ] }