git.stella-ops.org/src/Attestor/StellaOps.Attestor/AGENTS.md

Attestor Guild

Mission

Operate the StellaOps Attestor service: accept signed DSSE envelopes from the Signer over mTLS, submit them to Rekor v2, persist inclusion proofs, and expose verification APIs for downstream services and operators.

Teams On Call

• Team 11 (Attestor API)
• Team 12 (Attestor Observability) — partners on logging, metrics, and alerting

Operating Principles

• Enforce mTLS + Authority tokens for every submission; never accept anonymous callers.
• Deterministic hashing, canonical JSON, and idempotent Rekor interactions (bundleSha256 is the source of truth).
• Persist everything (entries, dedupe, audit) before acknowledging; background jobs must be resumable.
• Structured logs + metrics for each stage (validate, submit, proof, persist, archive).
• Update TASKS.md, architecture docs, and tests whenever behaviour changes.

Key Directories

• src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService/ — Minimal API host and HTTP surface.
• src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/ — Domain contracts, submission/verification pipelines.
• src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Infrastructure/ — PostgreSQL, Redis, Rekor, and archival implementations.
• src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Tests/ — Unit and integration tests.

---

Epic 19 Charter — Attestor Console

Mission

Deliver the API, workers, and storage that power signing, verification, and lifecycle management of supply-chain attestations across StellaOps.

Scope

• DSSE envelope ingestion and retrieval.
• Verification pipeline orchestration, caching, and policy evaluation.
• Issuer/key registries, transparency log integration, and audit logging.
• Bulk verification workflows and air-gap bundle support.

Definition of Done

• Signing and verification APIs operate deterministically with full explainability.
• Policy enforcement integrated with Authority & Tenancy scopes.
• Transparency proof handling, key rotation, and revocation workflows implemented.

Required Reading

• docs/modules/attestor/architecture.md
• docs/modules/attestor/rekor-verification-design.md
• docs/modules/platform/architecture-overview.md

---

Active Sprints — Rekor Verification Enhancement

SPRINT_3000_0001_0001: Merkle Proof Verification (P0)

Objective: Implement cryptographic verification of Rekor inclusion proofs for offline/air-gap attestation validation.

Key Contracts:

// IRekorClient.cs — New method
Task<RekorInclusionVerificationResult> VerifyInclusionAsync(
    AttestorEntry entry,
    byte[] payloadDigest,
    byte[] rekorPublicKey,
    CancellationToken cancellationToken = default);

// MerkleProofVerifier.cs — RFC 6962 implementation
public static bool VerifyInclusion(
    byte[] leafHash,
    long leafIndex,
    long treeSize,
    IReadOnlyList<byte[]> proofHashes,
    byte[] expectedRootHash);

New Files:

• StellaOps.Attestor.Core/Rekor/RekorInclusionVerificationResult.cs
• StellaOps.Attestor.Core/Verification/MerkleProofVerifier.cs
• StellaOps.Attestor.Core/Verification/CheckpointVerifier.cs

SPRINT_3000_0001_0002: Rekor Retry Queue & Metrics (P1)

Objective: Implement durable retry queue for failed Rekor submissions with operational metrics.

Key Contracts:

// IRekorSubmissionQueue.cs
public interface IRekorSubmissionQueue
{
    Task<Guid> EnqueueAsync(string tenantId, string bundleSha256, byte[] dssePayload, string backend, CancellationToken ct);
    Task<IReadOnlyList<RekorQueueItem>> DequeueAsync(int batchSize, CancellationToken ct);
    Task MarkSubmittedAsync(Guid id, string rekorUuid, long? logIndex, CancellationToken ct);
    Task MarkRetryAsync(Guid id, string error, CancellationToken ct);
    Task MarkDeadLetterAsync(Guid id, string error, CancellationToken ct);
    Task<QueueDepthSnapshot> GetQueueDepthAsync(CancellationToken ct);
}

New Metrics:

• attestor.rekor_queue_depth (gauge)
• attestor.rekor_retry_attempts_total (counter)
• attestor.rekor_submission_status_total (counter)

New Files:

• StellaOps.Attestor.Core/Queue/IRekorSubmissionQueue.cs
• StellaOps.Attestor.Infrastructure/Queue/PostgresRekorSubmissionQueue.cs
• StellaOps.Attestor.Infrastructure/Workers/RekorRetryWorker.cs
• Migrations/00X_rekor_submission_queue.sql

SPRINT_3000_0001_0003: Time Skew Validation (P2)

Objective: Validate Rekor integrated_time to detect backdated or anomalous entries.

Key Contracts:

// ITimeSkewValidator.cs
public interface ITimeSkewValidator
{
    TimeSkewResult Validate(DateTimeOffset integratedTime, DateTimeOffset localTime);
}

public sealed record TimeSkewResult(
    TimeSkewSeverity Severity,  // Ok, Warning, Rejected
    TimeSpan Skew,
    string? Message);

Configuration (AttestorOptions.TimeSkewOptions):

• WarnThresholdSeconds: 300 (5 min)
• RejectThresholdSeconds: 3600 (1 hour)
• FutureToleranceSeconds: 60

New Files:

• StellaOps.Attestor.Core/Validation/ITimeSkewValidator.cs
• StellaOps.Attestor.Infrastructure/Validation/TimeSkewValidator.cs

---

Working Agreement

• 1. Update task status to DOING/DONE in both correspoding 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.