fix(web): correct idempotent replay payload and serialize concurrent duplicates

.agents/rules/security.md

@@ -17,7 +17,13 @@ Chained partitioned fixed-window limiter: **tenant → user → IP** (defaults 1
 
 ## Idempotency (`Web/Idempotency/`)
 
-Opt-in per endpoint with **`.WithIdempotency()`**. Reads the `Idempotency-Key` header (max 128 chars, 24h TTL); replays return the cached response with `Idempotency-Replayed: true`. Cache key is tenant-scoped (`CacheKeys.IdempotencyEntry`). Put it on POSTs that must be replay-safe (e.g. CreateTenant).
+Opt-in per endpoint with **`.WithIdempotency()`** on **authenticated** POST/PUTs that must be replay-safe (e.g. CreateTenant). Reads `Idempotency-Key` (max 128 chars, `DefaultTtl` 24h); a replay returns the cached status + body + `Location`/`ETag` and `Idempotency-Replayed: true`.
+
+- **Key scope:** resolved tenant (never the raw `tenant` header) + operation (method + route pattern) + route values + caller (`GetUserId()`, else `"anon"`), via `CacheKeys.IdempotencyEntry`.
+- **Only 2xx is stored**, before the body is sent, on `CancellationToken.None`. Probe and write must share one `IDistributedCache` + key + serializer, or replay silently never engages.
+- **Concurrent duplicates:** in-flight reservation under a `lock:` prefix (Redis `SET NX`, else in-process, `ReservationTtl` default 1m); cache re-probed after the lock; duplicate in flight → **409** + `Retry-After: 1`. Probe, reserve and release all fail open.
+- **`RequestAborted` is detached** while the handler runs, so a client disconnect can't cancel a committed side effect. Keep these handlers short; **never** on streaming or large-file endpoints (the response is buffered).
+- **Never on `AllowAnonymous()`** endpoints — all anonymous callers share `"anon"`. `IdempotencyWiringTests` fails the build if one appears.
 
 ## Quota enforcement (`Quota/`)
 

src/BuildingBlocks/Caching/CacheKeys.cs

@@ -16,7 +16,11 @@ public static class Tags
         /// <summary>Tag applied to every tenant theme entry.</summary>
         public const string Themes = "themes";
 
-        /// <summary>Tag applied to every idempotency replay entry.</summary>
+        /// <summary>
+        /// Reserved for idempotency replay entries — not applied to them today. Those entries live in
+        /// <c>IDistributedCache</c>, which carries no tags, so a tag purge does not reach them; they
+        /// expire on their own TTL instead.
+        /// </summary>
         public const string Idempotency = "idempotency";
 
         /// <summary>Per-tenant tag — invalidates all entries scoped to a tenant.</summary>

src/BuildingBlocks/Web/Idempotency/CachedIdempotentResponse.cs

@@ -1,18 +1,23 @@
-using System.ComponentModel;
-
 namespace FSH.Framework.Web.Idempotency;
 
 /// <summary>
 /// A cached HTTP response for idempotent replay.
 /// </summary>
-/// <remarks>
-/// Marked <see cref="ImmutableObjectAttribute"/> + <c>sealed</c> so HybridCache can reuse the
-/// in-process instance across requests without re-deserializing on every L1 hit.
-/// </remarks>
-[ImmutableObject(true)]
 public sealed record CachedIdempotentResponse
 {
     public int StatusCode { get; init; }
+
     public string? ContentType { get; init; }
+
     public byte[] Body { get; init; } = [];
+
+    /// <summary>
+    /// Response headers replayed alongside the body. Only headers that carry meaning for the caller
+    /// are captured (see the filter's allow-list) — the host sets the transport ones itself, and
+    /// replaying a stale <c>Content-Length</c> or <c>Transfer-Encoding</c> would corrupt the response.
+    /// Defaults to empty so entries written before headers were captured still deserialize.
+    /// Iterate it, do not look a header up by name: deserialization replaces this instance with a
+    /// plain case-SENSITIVE dictionary, so the initializer's comparer only holds on the write path.
+    /// </summary>
+    public IReadOnlyDictionary<string, string> Headers { get; init; } = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
 }

src/BuildingBlocks/Web/Idempotency/Extensions.cs

@@ -14,8 +14,20 @@ public static IServiceCollection AddHeroIdempotency(this IServiceCollection serv
         ArgumentNullException.ThrowIfNull(services);
         ArgumentNullException.ThrowIfNull(configuration);
 
+        // Validated at startup, like every other options block here. A misconfigured TTL fails
+        // SILENTLY otherwise: a zero or negative DefaultTtl throws inside the best-effort cache
+        // write, which logs a warning and moves on, so no response is ever stored and replay never
+        // engages — the exact silent failure this filter exists to have stopped having. A
+        // ReservationTtl of zero expires the in-flight lock the moment it is taken, so concurrent
+        // duplicates both run the handler.
         services.AddOptions<IdempotencyOptions>()
-            .BindConfiguration(nameof(IdempotencyOptions));
+            .BindConfiguration(nameof(IdempotencyOptions))
+            .Validate(o => !string.IsNullOrWhiteSpace(o.HeaderName), "IdempotencyOptions.HeaderName is required.")
+            .Validate(o => o.DefaultTtl > TimeSpan.Zero, "IdempotencyOptions.DefaultTtl must be greater than zero.")
+            .Validate(o => o.ReservationTtl > TimeSpan.Zero, "IdempotencyOptions.ReservationTtl must be greater than zero.")
+            .Validate(o => o.ReservationTtl <= o.DefaultTtl, "IdempotencyOptions.ReservationTtl must not exceed DefaultTtl — the reservation only has to outlast the handler.")
+            .Validate(o => o.MaxKeyLength > 0, "IdempotencyOptions.MaxKeyLength must be greater than zero.")
+            .ValidateOnStart();
 
         return services;
     }