# 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**:

```csharp
// 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**:

```csharp
// 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**:

```csharp
// 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.