feat(cli): verify offline evidence bundle integrity

[doublewhy]

Context

• Multiple adapter backends emit evidence bundles whose byte integrity must be reviewable without installing a simulator.
• Integrity is distinct from backend semantics, aggregate recomputation, privacy review, or scientific conclusions.

Problem

• There is no generic installed CLI for checking regular-file containment, exact inventory membership, hashes, sizes, and nested inventory closure.
• Backend-specific tools cannot provide a common offline tamper boundary.

Fix

• Add raes-adapters verify-bundle --bundle PATH with deterministic JSON, terminal, and Markdown output.
• Return 0 for verified, 2 for usage, 3 for invalid or tampered input, and 70 for internal failure.
• Reject symlinks, special files, traversal, duplicates, malformed inventories, mutation during hashing, and extra files.
• Enforce the fixed file, inventory, entry, byte, artifact, depth, and path limits from the delivery plan.
• Perform no writes, network access, simulator imports, semantic claims, or aggregate recomputation.

Acceptance

• Clean-wheel verification and tamper probes pass.
• Tests cover containment, inventory closure, all fixed limits, malformed input, stable renderers, and leakage resistance.
• Canonical verification passes; native simulator qualification remains an Ubuntu-authoritative lane.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #92). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #92). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan

Issue #92 remains the acceptance contract; the architecture-preflight guardrails in docs/decisions/offline-bundle-verifier-guardrails.md are binding.

1. Lock the hostile-input behavior with tests (TDD Paths A/C).

   • Extend tests/test_bundle_verifier.py with red regressions for intermediate-directory and root replacement, final-member special-file races, missing secure descriptor primitives, oversized integers/non-finite constants/deep JSON, exact regular-file and directory-work limits, streaming-memory behavior, and fixed exit/output leakage behavior.
   • Preserve the existing flat/transitive closure, renderer, import-isolation, read-only, and clean-wheel probes.

2. Replace pathname trust with descriptor-rooted verification (TDD Paths A/C).

   • Refactor src/raes_adapters/bundle_verifier.py to pin the root and traverse each component relative to admitted directory descriptors using no-follow, directory, close-on-exec, and non-blocking flags.
   • Record and recheck root/directory/file identities, bound directory traversal separately from the 100,000 regular-file contract, and fail closed when equivalent secure primitives are unavailable.
   • Keep paths logical POSIX names; do not use resolve() or backend-specific logic as authority.

3. Make resource and parser failures fail closed (TDD Paths A/C).

   • Stream artifact SHA-256 and byte counts in bounded chunks, buffer only the current inventory, and retain metadata rather than artifact contents.
   • Treat hostile JSON conversion/recursion/non-finite constants as malformed input (exit 3), reserving exit 70 for implementation defects.
   • Keep every fixed limit constant and input-independent; no flags, environment overrides, registries, or repair mode.

4. Document the installed contract and authority boundary (TDD Path D riding on executable tests).

   • Retain the focused guardrail note, add an operator-facing verifier page with formats, exit codes, limits, point-in-time/read-only semantics, and non-claims, then add it to mkdocs.yml and docs/index.md.
   • Keep private implementation records/exceptions private; the stable CLI card is operational presentation, not a RAES DTO, diagnostic schema, persisted attestation, or semantic claim.

5. Verify and publish on the existing PR branch.

   • Run focused verifier tests with coverage, strict Ruff/mypy/docs checks as needed, then the canonical uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify graph with the branch's REP-005 identity.
   • Run the configured review and test-quality cycles, fix every real finding, commit and push only to 92-REP-005-offline-bundle-verifier, update PR 93 with REP-005 — Drive and validate CAGE-2 replication across the CybORG sim and the ACES reference backend rae#639, REP-001, ADR-069/design references and verification evidence, and monitor CI/Sonar to green.

Whole-repository design check

• Security: closed argparse shape; no credentials/environment policy; descriptor-rooted filesystem admission; strict bounded JSON; fixed redaction-safe error cards; no shell, child process, network, simulator import, logging, or writes.
• Maintainability: retain the lazy dispatcher, existing inventory producer shape, fixed exit conventions, single distribution/lock, canonical nox graph, and existing clean-wheel probe; add no second verifier framework.
• Extensibility: new backends reuse the current inventory seal without registration. Renderer choice remains pure presentation. Inventory versions, algorithms, archives, remote stores, or semantic verification require separately governed work.
• Whole-repo surfaces: pyproject.toml, entrypoint isolation, verifier implementation/tests, distribution probe, MkDocs navigation, ADR-002/ADR-003, capability/evidence claim guardrails, CI/PR Gate, and the backend-local CybORG semantic verifier remain consistent and separately owned.

No CHANGELOG.md, version, RAES contract, raes_adapters.base authority, simulator dependency, workflow, or lockfile change is planned.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #92 (branch 92-REP-005-offline-bundle-verifier)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: ship-with-fixes

Architecture-fit: this is shaped correctly as an isolated, simulator-independent byte-integrity boundary: descriptor-rooted verification stays outside raes_adapters.base, presentation is separated from verification, and lazy dispatch preserves simulator import isolation. The inventory producer shape remains the extension seam without becoming a new RAES semantic contract. Code-quality: the streaming and mutation checks are cohesive and behaviorally tested, but the advertised invalid-input envelope still has a pathname-error gap that can misclassify hostile or malformed input as an internal defect.

Blocking findings (1):

1. [class] Malformed pathname text can escape the stable invalid-input envelope — src/raes_adapters/bundle_verifier.py:364
_relative_path() UTF-8-encodes untrusted path text without translating UnicodeEncodeError into BundleInvalid. On POSIX, os.scandir() represents undecodable filenames with surrogate escapes; JSON can likewise produce lone-surrogate path strings. The root admission path also catches only OSError, although an embedded-NUL --bundle value raises ValueError. These cases therefore reach the command's generic handler and return exit 70, contradicting the documented contract that malformed, unreadable, or hostile bundle input returns exit 3. Normalize pathname encoding/value failures at these admission boundaries to a stable BundleInvalid code and pin both filesystem-name and CLI-root cases with tests.

Security review

Verdict: ship

This change is shaped correctly: it isolates deterministic presentation from the verifier, keeps the byte-integrity boundary simulator-independent, and replaces pathname-based traversal with descriptor-rooted, no-follow, mount-pinned access. Strict parsing, fixed resource limits, non-blocking special-file admission, mutation detection, allowlisted output, and fail-closed platform checks are applied at the correct seam. It preserves a clean extension point for future renderers without weakening verification or exposing backend semantics.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #92 on branch '92-REP-005-offline-bundle-verifier'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #92)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: Architecture-fit: this is shaped correctly as an isolated, simulator-independent byte-integrity boundary: descriptor-rooted verification stays outside raes_adapters.base, presentation is separated from verification, and lazy dispatch preserves simulator import isolation. The inventory producer shape remains the extension seam without becoming a new RAES semantic contract. Code-quality: the streaming and mutation checks are cohesive and behaviorally tested, but the advertised invalid-input envelope still has a pathname-error gap that can misclassify hostile or malformed input as an internal defect.

Security reviewer: This change is shaped correctly: it isolates deterministic presentation from the verifier, keeps the byte-integrity boundary simulator-independent, and replaces pathname-based traversal with descriptor-rooted, no-follow, mount-pinned access. Strict parsing, fixed resource limits, non-blocking special-file admission, mutation detection, allowlisted output, and fail-closed platform checks are applied at the correct seam. It preserves a clean extension point for future renderers without weakening verification or exposing backend semantics.

Blocking findings: 1

Finding 1 — class (2 instances)

• ID: F1
• Title: [core] Malformed pathname text can escape the stable invalid-input envelope
• Location: src/raes_adapters/bundle_verifier.py:364
• Decision: fix
• Rationale: _relative_path() UTF-8-encodes untrusted path text without translating UnicodeEncodeError into BundleInvalid. On POSIX, os.scandir() represents undecodable filenames with surrogate escapes; JSON can likewise produce lone-surrogate …
• Instances:
  • src/raes_adapters/bundle_verifier.py:364
  • src/raes_adapters/bundle_verifier.py:747

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #92

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 92-REP-005-offline-bundle-verifier
Cycle: 1 / 1
Findings: 0 (clean run)

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 complete for issue #92 on branch '92-REP-005-offline-bundle-verifier'. Posted by the MCP server to enforce the gc_test_quality_review hard-cap-1 contract (issue #884 follow-up, default lowered in #906). Do not edit or delete — used by the next gc_test_quality_review invocation to count cycles.

[Brad-Edwards]

Review decision record — test-quality cycle 1 (issue #92)

Reviewer: test-quality
Cycle: 1

Architectural read:

This is an adversarial test suite for a security-critical, filesystem-only integrity verifier, and it earns that framing: every test drives real behavior through the public verify_bundle/main entry points and asserts on the resulting VerificationCard, exit code, or rendered output rather than on mock call counts. Where it injects TOCTOU races (directory-swap-to-symlink, FIFO substitution, identity mutation mid-hash, root replacement, late file addition) it does so by wrapping the SUT's own internal helpers (_scan, _identity, _inventory_payload, _file_flags) to deterministically time a real filesystem mutation between two real passes, then lets the actual O_NOFOLLOW/dir_fd/identity-comparison code run and fail closed — it never mocks away the security check being exercised. Coverage includes every documented admission limit at its exact boundary, every malformed-input class (JSON constants, oversized ints, parser recursion, exact-key inventory shapes, path traversal, NUL/backslash/double-slash paths, undecodable filesystem names), and negative-disclosure checks (secrets/paths never echoed to stdout/stderr, internal exception text suppressed). Both real bug classes I probed — a no-op verify_bundle and a weakened membership/tamper check — would be caught by multiple existing tests.

Blocking findings: 0 (clean run)

[Brad-Edwards]

Ready for review — issue #92

PR: #93
Plan: #92 (comment)

Outcome

Operators can now verify an evidence bundle offline from the base installation with descriptor-rooted containment, bounded resource use, exact inventory closure, and deterministic integrity-only results. Hostile filesystem and parser inputs fail closed without leaking paths or internals.

Files changed

Added:

• docs/bundle-verifier.md
• docs/decisions/offline-bundle-verifier-guardrails.md
• src/raes_adapters/_bundle_command.py
• src/raes_adapters/bundle_verifier.py
• src/raes_adapters/entrypoint.py
• tests/test_bundle_verifier.py

Modified:

• docs/index.md
• mkdocs.yml
• noxfile.py
• pyproject.toml

Reviews

• codex: One pathname error-classification class was fixed with regression coverage; the user directed proceeding without an over-cap confirmation pass, and post-fix completion and policy gates passed.
• test-quality: Clean; no findings.

Traceability reconciliation

• Pending — requirement status transition and IMPLEMENTS/TESTS reconciliation run in Phase E once the PR merges.

Status

• CI: ✅ green
• SonarCloud: ✅ passed
• PR ready for user review and merge. Ground Control reconciliation (requirement status + traceability) runs on merge (Phase E).

[Brad-Edwards]

Implemented the offline bundle-verifier hardening on PR #93.

• Uses descriptor-relative, no-follow traversal with mount and identity checks for root, directories, and files.
• Streams artifact hashing under fixed byte limits; bounds file, directory, inventory, entry, depth, and path work independently.
• Maps malformed JSON, pathname, and filesystem input to stable invalid-input results without exposing paths or exception details.
• Keeps verification simulator-independent, read-only, offline, and explicitly integrity-only.
• Adds operator documentation and adversarial coverage for races, mount/primitive failures, parser limits, memory use, exact boundaries, leakage, and exit codes.

Final state: 61 focused verifier tests pass; local completion and policy gates pass; all PR checks pass; SonarCloud reports 91.3% new-code coverage with zero violations, open issues, or hotspots.

[Brad-Edwards]

Final report — issue #92 complete

PR: #93
Plan: #92 (comment)

Outcome

Operators can verify an evidence bundle offline from the base installation with descriptor-rooted containment, bounded resource use, exact inventory closure, and deterministic integrity-only results. Hostile filesystem and parser inputs fail closed without exposing paths or internal details.

Added the offline evidence-bundle verifier, CLI integration, deterministic renderers, safety limits, documentation, and regression coverage.

Files changed

Added:

• docs/bundle-verifier.md
• docs/decisions/offline-bundle-verifier-guardrails.md
• src/raes_adapters/_bundle_command.py
• src/raes_adapters/bundle_verifier.py
• src/raes_adapters/entrypoint.py
• tests/test_bundle_verifier.py

Modified:

• docs/index.md
• mkdocs.yml
• noxfile.py
• pyproject.toml

Reviews

• codex: One pathname error-classification defect was corrected with regression coverage; the completion and policy gates then passed.
• test-quality: Clean; no findings.

Traceability reconciliation

• IMPLEMENTS / TESTS / DOCUMENTS added: 0
• Links updated: 0
• Stale links removed: 0

No repo-local requirement records or issue-to-requirement links required reconciliation.

Status

• CI: ✅ green
• SonarCloud: ✅ passed
• PR ready for user review and merge.