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.