up

src/Attestor/StellaOps.Attestor/AGENTS.md

@@ -40,8 +40,101 @@ Deliver the API, workers, and storage that power signing, verification, and life
 
 ## 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.

src/Attestor/StellaOps.Attestor/TASKS.md

@@ -0,0 +1,57 @@
+# Attestor · Sprint 3000-0001-0001 (Rekor Merkle Proof Verification)
+
+| Task ID | Status | Notes | Updated (UTC) |
+| --- | --- | --- | --- |
+| SPRINT_3000_0001_0001-T1 | DOING | Add `VerifyInclusionAsync` contract + wire initial verifier plumbing. | 2025-12-14 |
+| SPRINT_3000_0001_0001-T2 | TODO | | |
+| SPRINT_3000_0001_0001-T3 | TODO | | |
+| SPRINT_3000_0001_0001-T4 | TODO | | |
+| SPRINT_3000_0001_0001-T5 | TODO | | |
+| SPRINT_3000_0001_0001-T6 | TODO | | |
+| SPRINT_3000_0001_0001-T7 | TODO | | |
+| SPRINT_3000_0001_0001-T8 | TODO | | |
+| SPRINT_3000_0001_0001-T9 | TODO | | |
+| SPRINT_3000_0001_0001-T10 | TODO | | |
+| SPRINT_3000_0001_0001-T11 | TODO | | |
+| SPRINT_3000_0001_0001-T12 | TODO | | |
+
+# Attestor · Sprint 3000-0001-0002 (Rekor Durable Retry Queue & Metrics)
+
+| Task ID | Status | Notes | Updated (UTC) |
+| --- | --- | --- | --- |
+| SPRINT_3000_0001_0002-T1 | TODO | | |
+| SPRINT_3000_0001_0002-T2 | TODO | | |
+| SPRINT_3000_0001_0002-T3 | TODO | | |
+| SPRINT_3000_0001_0002-T4 | TODO | | |
+| SPRINT_3000_0001_0002-T5 | TODO | | |
+| SPRINT_3000_0001_0002-T6 | TODO | | |
+| SPRINT_3000_0001_0002-T7 | TODO | | |
+| SPRINT_3000_0001_0002-T8 | TODO | | |
+| SPRINT_3000_0001_0002-T9 | TODO | | |
+| SPRINT_3000_0001_0002-T10 | TODO | | |
+| SPRINT_3000_0001_0002-T11 | TODO | | |
+| SPRINT_3000_0001_0002-T12 | TODO | | |
+| SPRINT_3000_0001_0002-T13 | TODO | | |
+| SPRINT_3000_0001_0002-T14 | TODO | | |
+| SPRINT_3000_0001_0002-T15 | TODO | | |
+
+# Attestor · Sprint 3000-0001-0003 (Rekor Integrated Time Skew Validation)
+
+| Task ID | Status | Notes | Updated (UTC) |
+| --- | --- | --- | --- |
+| SPRINT_3000_0001_0003-T1 | TODO | | |
+| SPRINT_3000_0001_0003-T2 | TODO | | |
+| SPRINT_3000_0001_0003-T3 | TODO | | |
+| SPRINT_3000_0001_0003-T4 | TODO | | |
+| SPRINT_3000_0001_0003-T5 | TODO | | |
+| SPRINT_3000_0001_0003-T6 | TODO | | |
+| SPRINT_3000_0001_0003-T7 | TODO | | |
+| SPRINT_3000_0001_0003-T8 | TODO | | |
+| SPRINT_3000_0001_0003-T9 | TODO | | |
+| SPRINT_3000_0001_0003-T10 | TODO | | |
+| SPRINT_3000_0001_0003-T11 | TODO | | |
+
+Status changes must be mirrored in:
+- `docs/implplan/SPRINT_3000_0001_0001_rekor_merkle_proof_verification.md`
+- `docs/implplan/SPRINT_3000_0001_0002_rekor_retry_queue_metrics.md`
+- `docs/implplan/SPRINT_3000_0001_0003_rekor_time_skew_validation.md`