save progress

src/Replay/__Libraries/StellaOps.Replay.Anonymization/ITraceAnonymizer.cs

@@ -0,0 +1,123 @@
+// <copyright file="ITraceAnonymizer.cs" company="StellaOps">
+// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
+// </copyright>
+// Sprint: SPRINT_20260105_002_002_TEST_trace_replay_evidence
+// Task: TREP-001, TREP-002
+
+using System.Collections.Immutable;
+
+namespace StellaOps.Replay.Anonymization;
+
+/// <summary>
+/// Anonymizes production traces for safe use in testing.
+/// </summary>
+public interface ITraceAnonymizer
+{
+    /// <summary>
+    /// Anonymize a production trace, removing PII and sensitive data.
+    /// </summary>
+    /// <param name="trace">The production trace to anonymize.</param>
+    /// <param name="options">Anonymization options.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The anonymized trace.</returns>
+    Task<AnonymizedTrace> AnonymizeAsync(
+        ProductionTrace trace,
+        AnonymizationOptions options,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Validate that a trace is properly anonymized.
+    /// </summary>
+    /// <param name="trace">The anonymized trace to validate.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Validation result.</returns>
+    Task<AnonymizationValidationResult> ValidateAnonymizationAsync(
+        AnonymizedTrace trace,
+        CancellationToken ct = default);
+}
+
+/// <summary>
+/// Options controlling trace anonymization behavior.
+/// </summary>
+/// <param name="RedactImageNames">Whether to redact container image names.</param>
+/// <param name="RedactUserIds">Whether to redact user identifiers.</param>
+/// <param name="RedactIpAddresses">Whether to redact IP addresses.</param>
+/// <param name="RedactFilePaths">Whether to redact file paths.</param>
+/// <param name="RedactEnvironmentVariables">Whether to redact environment variables.</param>
+/// <param name="PreserveTimingPatterns">Whether to preserve relative timing patterns.</param>
+/// <param name="AdditionalPiiPatterns">Additional regex patterns to treat as PII.</param>
+/// <param name="AllowlistedValues">Values to preserve without redaction.</param>
+public sealed record AnonymizationOptions(
+    bool RedactImageNames = true,
+    bool RedactUserIds = true,
+    bool RedactIpAddresses = true,
+    bool RedactFilePaths = true,
+    bool RedactEnvironmentVariables = true,
+    bool PreserveTimingPatterns = true,
+    ImmutableArray<string> AdditionalPiiPatterns = default,
+    ImmutableArray<string> AllowlistedValues = default)
+{
+    /// <summary>
+    /// Default anonymization options with all redactions enabled.
+    /// </summary>
+    public static AnonymizationOptions Default => new();
+
+    /// <summary>
+    /// Minimal anonymization that only redacts obvious PII.
+    /// </summary>
+    public static AnonymizationOptions Minimal => new(
+        RedactFilePaths: false,
+        RedactEnvironmentVariables: false);
+}
+
+/// <summary>
+/// Result of anonymization validation.
+/// </summary>
+/// <param name="IsValid">Whether the trace is properly anonymized.</param>
+/// <param name="Violations">Any detected PII violations.</param>
+/// <param name="Warnings">Non-critical warnings about the trace.</param>
+public sealed record AnonymizationValidationResult(
+    bool IsValid,
+    ImmutableArray<PiiViolation> Violations,
+    ImmutableArray<string> Warnings)
+{
+    /// <summary>
+    /// Creates a successful validation result.
+    /// </summary>
+    public static AnonymizationValidationResult Success() =>
+        new(true, ImmutableArray<PiiViolation>.Empty, ImmutableArray<string>.Empty);
+
+    /// <summary>
+    /// Creates a failed validation result with violations.
+    /// </summary>
+    public static AnonymizationValidationResult Failure(params PiiViolation[] violations) =>
+        new(false, [.. violations], ImmutableArray<string>.Empty);
+}
+
+/// <summary>
+/// A detected PII violation in an anonymized trace.
+/// </summary>
+/// <param name="SpanId">The span containing the violation.</param>
+/// <param name="FieldPath">Path to the field containing PII.</param>
+/// <param name="ViolationType">Type of PII detected.</param>
+/// <param name="SampleValue">Masked sample of the detected value.</param>
+public sealed record PiiViolation(
+    string SpanId,
+    string FieldPath,
+    PiiType ViolationType,
+    string SampleValue);
+
+/// <summary>
+/// Types of PII that can be detected.
+/// </summary>
+public enum PiiType
+{
+    IpAddress,
+    Email,
+    UserId,
+    FilePath,
+    ImageName,
+    EnvironmentVariable,
+    Uuid,
+    Custom
+}