# Attestor Module — Agent Charter

## Mission
Manage the attestation and proof chain infrastructure for StellaOps:
- Accept DSSE-signed attestation bundles from Signer and other modules.
- Register attestations with Rekor v2 transparency log for tamper-evident anchoring.
- Provide verification APIs for proof chain validation (signature, payload, Rekor inclusion).
- Serve deterministic evidence bundles linking artifacts to SBOMs, VEX documents, and verdicts.
- Enable "Show Me The Proof" workflows with complete audit trails.

## Expectations
- Coordinate with Signer for cryptographic operations, Scanner/Excititor for attestation generation, and UI for proof visualization.
- Maintain deterministic serialization for reproducible verification outcomes.
- Support offline verification with bundled Rekor inclusion proofs.
- Provide REST APIs for proof chain queries, baseline selection, and trust indicators.
- Keep proof chain storage schema current with migrations.

## Key Components
- **StellaOps.Attestor**: Main attestation service and REST API endpoints
- **StellaOps.Attestor.Envelope**: DSSE envelope handling and serialization
- **StellaOps.Attestor.Types**: Core attestation models and schemas
- **StellaOps.Attestor.Verify**: Verification engine for signatures and Rekor proofs
- **__Libraries**: Shared attestation utilities and storage abstractions
- **__Tests**: Integration tests with Testcontainers for PostgreSQL

## Required Reading
- `docs/modules/attestor/README.md`
- `docs/modules/attestor/architecture.md`
- `docs/modules/attestor/implementation_plan.md`
- `docs/product/advisories/20-Dec-2025 - Stella Ops Reference Architecture.md`
- `docs/modules/platform/architecture-overview.md`

## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both corresponding sprint file `/docs/implplan/SPRINT_*.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

## Attestation Types
- **SBOM Attestations**: Link container images to SPDX/CycloneDX SBOMs
- **VEX Attestations**: Link OpenVEX statements to products
- **Verdict Attestations**: Link policy evaluation results to artifacts
- **Provenance Attestations**: SLSA provenance for build reproducibility
- **Reachability Attestations**: Link static analysis witness paths to findings

## Proof Chain Model
- **ProofNode**: Individual proof (SBOM, VEX, Verdict, Attestation) with digest and metadata
- **ProofEdge**: Relationship between nodes ("attests", "references", "supersedes")
- **ProofChain**: Complete directed graph from artifact to all linked evidence
- **ProofVerification**: Signature validation, payload hash check, Rekor inclusion proof

## Guardrails
- All attestations must use DSSE envelopes with multiple signature support.
- Rekor anchoring must be optional (support air-gapped deployments).
- Verification must work offline with bundled inclusion proofs.
- Proof chains must be deterministic (stable ordering, canonical serialization).
- Preserve determinism: sort outputs, normalize timestamps (UTC ISO-8601).
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
- Update runbooks/observability assets when operational characteristics change.