# Trust Root and Certificate Chain Verification

## Module
Authority

## Status
IMPLEMENTED

## Description
Certificate chain validation checks, TSA certificate expiry monitoring, and timestamp token verification with configurable trust anchors and verification options.

## Implementation Details
- **Timestamp Token Verifier**: `src/Authority/__Libraries/StellaOps.Authority.Timestamping/TimeStampTokenVerifier.cs` (with partials `.CertificateChain.cs`, `.Signature.cs`, `.Validation.cs`, `.Warnings.cs`) -- verifies RFC 3161 timestamp tokens including certificate chain validation, signature verification, and trust anchor checks.
- **TSA Client**: `src/Authority/__Libraries/StellaOps.Authority.Timestamping/HttpTsaClient.cs` (with partials `.GetTimeStamp.cs`, `.ProviderOrdering.cs`, `.ProviderRequest.cs`, `.Verification.cs`) -- HTTP client for TSA servers implementing `ITimeStampAuthorityClient`.
- **TSA Provider Registry**: `src/Authority/__Libraries/StellaOps.Authority.Timestamping/TsaProviderRegistry.cs` (with partials `.HealthCheck.cs`, `.ProviderState.cs`, `.Providers.cs`, `.Reporting.cs`, `.Stats.cs`) -- manages TSA providers with health monitoring and failover.
- **Verification Options**: `src/Authority/__Libraries/StellaOps.Authority.Timestamping.Abstractions/TimeStampVerificationOptions.cs` -- configurable trust anchors, allowed algorithms, certificate policies.
- **Verification Result**: `src/Authority/__Libraries/StellaOps.Authority.Timestamping.Abstractions/TimeStampVerificationResult.cs` -- detailed result with errors and warnings.
- **Verification Error/Warning Codes**: `src/Authority/__Libraries/StellaOps.Authority.Timestamping.Abstractions/VerificationError.cs`, `VerificationErrorCode.cs`, `VerificationWarning.cs`, `VerificationWarningCode.cs`, `VerificationStatus.cs`.
- **TSA Health**: `src/Authority/__Libraries/StellaOps.Authority.Timestamping/TsaProviderHealth.cs`, `TsaHealthStatus.cs` -- health check types for TSA certificate expiry monitoring.
- **Signing Key Management**: `src/Authority/StellaOps.Authority/StellaOps.Authority/Signing/AuthoritySigningKeyManager.cs` -- manages authority signing keys with rotation; `AuthoritySigningKeyStatus.cs` tracks key health.
- **JWKS Service**: `src/Authority/StellaOps.Authority/StellaOps.Authority/Signing/AuthorityJwksService.cs` -- serves the JSON Web Key Set for public key distribution.
- **DSSE Statement Signer**: `src/Authority/StellaOps.Authority/StellaOps.Authority/Signing/AuthorityDsseStatementSigner.cs` -- signs in-toto/DSSE statements using authority keys.
- **KMS Key Source**: `src/Authority/StellaOps.Authority/StellaOps.Authority/Signing/KmsAuthoritySigningKeySource.cs` -- resolves signing keys from a Key Management Service.
- **File Key Source**: `src/Authority/StellaOps.Authority/StellaOps.Authority/Signing/FileAuthoritySigningKeySource.cs` -- resolves signing keys from local files.
- **Tests**: `src/Authority/__Tests/StellaOps.Authority.Timestamping.Tests/TimeStampTokenVerifierTests.cs`, `TsaProviderRegistryTests.cs`; `src/Authority/StellaOps.Authority/StellaOps.Authority.Tests/Signing/AuthorityJwksServiceTests.cs`, `AuthoritySigningKeyManagerTests.cs`, `KmsAuthoritySigningKeySourceTests.cs`, `TokenSignVerifyRoundtripTests.cs`

## E2E Test Plan
- [ ] Submit a timestamp request to a TSA server via `HttpTsaClient` and verify the returned timestamp token passes `TimeStampTokenVerifier` validation
- [ ] Verify certificate chain: provide a timestamp token with a valid chain and verify `TimeStampTokenVerifier.CertificateChain` validates each certificate up to the trust anchor
- [ ] Provide a timestamp token signed by an untrusted CA and verify the verifier rejects it with `VerificationErrorCode.UntrustedCertificate`
- [ ] Configure `TimeStampVerificationOptions` to reject weak algorithms (e.g., SHA-1) and verify tokens using SHA-1 are rejected
- [ ] Verify TSA health monitoring: register a TSA provider and verify `TsaProviderRegistry.HealthCheck` detects certificate expiry within the warning threshold
- [ ] Verify signing key rotation: rotate the authority signing key via `AuthoritySigningKeyManager` and verify the JWKS endpoint reflects the new key while the old key remains for validation
- [ ] Verify DSSE signing: sign a statement via `AuthorityDsseStatementSigner` and verify the signature can be validated using the JWKS public key
- [ ] Verify KMS key source: configure `KmsAuthoritySigningKeySource` and verify signing operations use the KMS-managed key