# Rekor Integration Technical Reference

**Source Advisories**:
- 30-Nov-2025 - Rekor Receipt Checklist for Stella Ops

**Last Updated**: 2025-12-14

---

## 1. REQUIREMENTS

- Rekor receipts must be deterministic, tenant-scoped, and verifiable offline
- For Authority/Sbomer/Vexer flows
- Field-level ownership map for receipts and bundles
- Offline verifier expectations
- Mirror snapshot rules
- DSSE/receipt schema pointers

## 2. DETERMINISM & OFFLINE

- Bundle TSA/time anchors with receipts
- Prefer mirror snapshots
- Avoid live log fetches in examples

## 3. DELIVERABLES

- Schema draft
- Offline verifier stub
- Module dossier updates

## 4. REKOR ENTRY STRUCTURE

```json
{
  "dsseSha256": "sha256:...",
  "rekor": {
    "uuid": "...",
    "logIndex": 12345,
    "logId": "...",
    "integratedTime": 1733736000,
    "inclusionProof": {
      "rootHash": "...",
      "hashes": ["...", "..."],
      "checkpoint": "..."
    }
  }
}
```

## 5. REKOR CLIENT INTERFACE

```csharp
public interface IRekorClient
{
    Task<RekorEntry> SubmitDsseAsync(
        DsseEnvelope envelope,
        CancellationToken ct = default
    );

    Task<bool> VerifyInclusionAsync(
        RekorEntry entry,
        byte[] payloadDigest,
        byte[] rekorPublicKey,
        CancellationToken ct = default
    );
}

public record RekorEntry(
    string Uuid,
    long LogIndex,
    string LogId,
    long IntegratedTime,
    InclusionProof Proof
);

public record InclusionProof(
    string RootHash,
    string[] Hashes,
    string Checkpoint
);
```

## 6. CLI VERIFICATION

### 6.1 Rekor CLI Commands

```bash
rekor-cli verify --rekor_server https://rekor.sigstore.dev \
  --signature artifact.sig \
  --public-key cosign.pub \
  --artifact artifact.bin
```

### 6.2 Persistence per Entry

- Rekor UUID
- Log index
- Integrated time
- Inclusion proof data

## 7. OFFLINE REKOR MIRROR

### 7.1 Mirror Structure

```
/evidence/tlog/
  checkpoint.sig         # signed tree head
  entries/               # *.jsonl (Merkle leaves) + proofs
```

### 7.2 Verification Steps

```
1. Recompute Merkle root from entries
2. Check matches `checkpoint.sig` (after verifying signature with tlog root key)
3. For each attestation:
   - Verify UUID/digest appears in entry pack
   - Verify inclusion proof resolves
```

## 8. REKOR STORAGE SCHEMA

```sql
CREATE TABLE rekor_entries (
  dsse_sha256 VARCHAR(64) PRIMARY KEY,
  log_index BIGINT NOT NULL,
  log_id TEXT NOT NULL,
  integrated_time BIGINT NOT NULL,
  inclusion_proof JSONB NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_rekor_log_index ON rekor_entries(log_index);
CREATE INDEX idx_rekor_integrated_time ON rekor_entries(integrated_time);
```

## 9. REKOR FAILURE HANDLING

### 9.1 Rekor Unavailable

```
If Rekor unavailable:
  - Store DSSE envelope locally
  - Queue for retry
  - Mark proof chain as "rekorStatus: pending"
  - Internal-only until Rekor sync succeeds
  - Flag in verification results
```

### 9.2 Rekor Verification Failed

```
If verification fails:
  - Log error with structured fields (rekorUuid, dsseDigest, failureReason)
  - Mark envelope as "rekor_verification_failed"
  - Do not accept as valid proof
  - Alert security team
```

## 10. INTEGRATION POINTS

### 10.1 Authority Module

- Submit signed attestations to Rekor
- Store receipts with DSSE envelopes
- Verify inclusion proofs on retrieval

### 10.2 Sbomer Module

- Submit SBOM attestations to Rekor
- Link Rekor UUID to SBOM entries

### 10.3 Vexer Module

- Submit VEX statements to Rekor
- Store receipts with VEX decisions

## 11. METRICS & OBSERVABILITY

```
rekor_submit_total{status="success|failed"}
rekor_submit_latency_seconds
rekor_verify_total{result="pass|fail"}
rekor_verify_latency_seconds
rekor_queue_depth (pending submissions)
rekor_retry_attempts_total
```

## 12. CONFIGURATION

```yaml
rekor:
  server_url: https://rekor.sigstore.dev
  public_key_path: /etc/stellaops/rekor-pub.pem
  offline_mode: false
  retry:
    max_attempts: 3
    initial_delay_ms: 1000
    max_delay_ms: 10000
  timeout_seconds: 30
```

## 13. OFFLINE BUNDLE INTEGRATION

### 13.1 Rekor Receipt in Offline Kit

**rekor-receipt.json**:
```json
{
  "uuid": "string",
  "logIndex": int,
  "rootHash": "string",
  "hashes": ["string"],
  "checkpoint": "string"
}
```

### 13.2 Offline Verification

```
1. Load Rekor public key from offline bundle
2. Verify checkpoint signature
3. Recompute Merkle root from inclusion proof
4. Verify root hash matches checkpoint
5. Verify DSSE envelope hash appears in proof
```

## 14. SECURITY CONSIDERATIONS

### 14.1 Trust Model

- Rekor provides transparency, not trust
- Trust derives from key verification
- Inclusion proof demonstrates timestamp
- Does not prove correctness of content

### 14.2 Key Pinning

- Pin Rekor public key via out-of-band distribution
- Verify checkpoint signatures before trusting
- Maintain key version history

### 14.3 Replay Protection

- Use integrated_time to detect backdated entries
- Compare with local clock (within reasonable skew)
- Alert on time anomalies

## 15. TESTING REQUIREMENTS

### 15.1 Integration Tests

- Submit DSSE to Rekor (staging)
- Verify inclusion proof
- Offline verification with mirror
- Retry on failure
- Timeout handling

### 15.2 Failure Scenarios

- Rekor unavailable
- Network timeout
- Invalid inclusion proof
- Signature verification failure
- Malformed response

## 16. OPERATIONAL PROCEDURES

### 16.1 Rekor Mirror Sync

```bash
# Download latest checkpoint
curl https://rekor.sigstore.dev/api/v1/log/checkpoint > checkpoint.sig

# Verify checkpoint signature
rekor-cli verify --checkpoint checkpoint.sig --public-key rekor-pub.pem

# Sync entries since last update
rekor-cli sync --since <last_log_index> --output ./entries/
```

### 16.2 Monitoring

- Alert on Rekor submission failures >1% over 5 minutes
- Alert on verification failures >0.1% over 5 minutes
- Alert on queue depth >1000 for >10 minutes

---

**Document Version**: 1.0
**Target Platform**: .NET 10, PostgreSQL ≥16, Angular v17