[AZ-810] Strict validation for POST /api/satellite/upload metadata

Adds the per-endpoint child of AZ-795 ("Strict Input Validation Epic")
for the UAV upload multipart endpoint. Three new validators land under
SatelliteProvider.Api/Validators/:

- UavTileBatchMetadataPayloadValidator: items NotNull + NotEmpty +
  count <= MaxBatchSize + RuleForEach dispatching to the per-item
  validator.
- UavTileMetadataValidator: lat / lon / tileZoom range, tileSizeMeters
  > 0, capturedAt within [now - MaxAgeDays, now + future-skew]; uses an
  injectable TimeProvider so unit tests can drive a fixed clock.
- UavUploadValidationFilter: IEndpointFilter that reads the multipart
  `metadata` form field, deserializes it with the strict global
  JsonSerializerOptions (so UnmappedMemberHandling.Disallow +
  [JsonRequired] from AZ-795 are honored), runs the FluentValidation
  chain, and enforces the cross-field `items.Count == files.Count`
  envelope rule. FluentValidation errors are prefixed with `metadata.`
  so wire keys look like `errors["metadata.items[0].latitude"]`.

[JsonRequired] is added to every non-optional axis on
UavTileMetadata and UavTileBatchMetadataPayload; FlightId stays
nullable per AZ-503 anonymous-flight semantics.

Coverage: 13 unit tests + 16 integration tests + 1 curl probe script
exercise the happy path and every failure mode. All 9 ACs covered;
no regression in AZ-488 UavUploadTests payloads (traced against the
new rules).

Documentation: uav-tile-upload.md bumped v1.1.0 -> v1.2.0 with the
new validation rules section + 400-shape examples + changelog entry.
api_program.md updated to describe the three new validators + filter
+ the AddTransient<UavUploadValidationFilter>() DI registration.

Reports: batch_04_cycle8_report.md + reviews/batch_04_cycle8_review.md
record the PASS_WITH_WARNINGS verdict (2 Low DRY-in-tests findings:
FixedTimeProvider duplication crossed the cycle-2 "promote to shared"
threshold; PostBatch helper duplicated between two integration
suites). Both deferred to follow-up PBIs.

Task spec archived: _docs/02_tasks/todo/AZ-810... -> done/.
Jira: AZ-810 transitioned In Progress -> In Testing.

Co-authored-by: Cursor <cursoragent@cursor.com>

SatelliteProvider.Api/Program.cs

@@ -122,6 +122,11 @@ builder.Services.ConfigureHttpJsonOptions(options =>
 builder.Services.AddValidatorsFromAssemblyContaining<Program>();
 GlobalValidatorConfig.ApplyOnce();
 
+// AZ-810: explicit registration so `.AddEndpointFilter<UavUploadValidationFilter>()`
+// on the UAV upload endpoint resolves the filter with its `IValidator<…>` + JSON
+// options constructor deps. Transient so each request gets a fresh instance.
+builder.Services.AddTransient<UavUploadValidationFilter>();
+
 builder.Services.AddEndpointsApiExplorer();
 builder.Services.AddSwaggerGen(c =>
 {
@@ -231,6 +236,7 @@ app.MapPost("/api/satellite/tiles/inventory", GetTilesInventory)
 
 app.MapPost("/api/satellite/upload", UploadUavTileBatch)
     .RequireAuthorization(SatellitePermissions.UavUploadPolicy)
+    .AddEndpointFilter<UavUploadValidationFilter>()
     .Accepts<UavTileBatchUploadRequest>("multipart/form-data")
     .Produces<UavTileBatchUploadResponse>(StatusCodes.Status200OK)
     .ProducesProblem(StatusCodes.Status400BadRequest)

SatelliteProvider.Api/Validators/UavTileBatchMetadataPayloadValidator.cs

@@ -0,0 +1,33 @@
+using FluentValidation;
+using Microsoft.Extensions.Options;
+using SatelliteProvider.Common.Configs;
+using SatelliteProvider.Common.DTO;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-810: root validator for the UAV upload metadata envelope. Runs from
+// inside the custom `UavUploadValidationFilter` (the endpoint takes a
+// multipart form, so the standard `WithValidation<T>()` JSON-body filter
+// doesn't apply). Error keys come out as `errors.items[…]` from this
+// validator and are prefixed with `metadata.` by the filter, producing
+// `errors.metadata.items[…]` in the final ValidationProblemDetails per
+// `_docs/02_document/contracts/api/error-shape.md` v1.0.0.
+public sealed class UavTileBatchMetadataPayloadValidator : AbstractValidator<UavTileBatchMetadataPayload>
+{
+    public UavTileBatchMetadataPayloadValidator(
+        IOptions<UavQualityConfig> qualityConfig,
+        TimeProvider? timeProvider = null)
+    {
+        ArgumentNullException.ThrowIfNull(qualityConfig);
+        var maxBatchSize = qualityConfig.Value.MaxBatchSize;
+
+        RuleFor(p => p.Items)
+            .NotNull().WithMessage("`items` is required.")
+            .NotEmpty().WithMessage("`items` must contain at least one entry.")
+            .Must(items => items is null || items.Count <= maxBatchSize)
+                .WithMessage($"`items` must contain at most {maxBatchSize} entries.");
+
+        RuleForEach(p => p.Items)
+            .SetValidator(new UavTileMetadataValidator(qualityConfig, timeProvider));
+    }
+}

SatelliteProvider.Api/Validators/UavTileMetadataValidator.cs

@@ -0,0 +1,67 @@
+using FluentValidation;
+using Microsoft.Extensions.Options;
+using SatelliteProvider.Common.Configs;
+using SatelliteProvider.Common.DTO;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-810: per-item metadata validator for the UAV upload endpoint. Runs as
+// a `RuleForEach.SetValidator(...)` chain child of `UavTileBatchMetadataPayloadValidator`,
+// so error keys come out as `errors.metadata.items[i].latitude`, `…tileZoom`,
+// `…capturedAt`, etc. once the `UavUploadValidationFilter` prefixes the result.
+//
+// CapturedAt freshness (rule 11) is the same window that
+// `IUavTileQualityGate.Validate` enforces; running the same check at the API
+// boundary lets us short-circuit before any file bytes are inspected. The
+// gate remains as a defence-in-depth backstop for unit tests of the gate
+// itself and for the unlikely path of a caller invoking
+// `IUavTileUploadHandler` directly (bypassing the filter).
+public sealed class UavTileMetadataValidator : AbstractValidator<UavTileMetadata>
+{
+    private const double MinLat = -90.0;
+    private const double MaxLat = 90.0;
+    private const double MinLon = -180.0;
+    private const double MaxLon = 180.0;
+    private const int MinZoom = 0;
+    private const int MaxZoom = 22;
+
+    public UavTileMetadataValidator(IOptions<UavQualityConfig> qualityConfig, TimeProvider? timeProvider = null)
+    {
+        ArgumentNullException.ThrowIfNull(qualityConfig);
+        var cfg = qualityConfig.Value;
+        var tp = timeProvider ?? TimeProvider.System;
+        var maxAgeDays = cfg.MaxAgeDays;
+        var futureSkewSeconds = cfg.CapturedAtFutureSkewSeconds;
+
+        RuleFor(m => m.Latitude)
+            .InclusiveBetween(MinLat, MaxLat)
+            .WithMessage($"`latitude` must be between {MinLat} and {MaxLat}.");
+
+        RuleFor(m => m.Longitude)
+            .InclusiveBetween(MinLon, MaxLon)
+            .WithMessage($"`longitude` must be between {MinLon} and {MaxLon}.");
+
+        RuleFor(m => m.TileZoom)
+            .InclusiveBetween(MinZoom, MaxZoom)
+            .WithMessage($"`tileZoom` must be between {MinZoom} and {MaxZoom} (slippy-map range).");
+
+        RuleFor(m => m.TileSizeMeters)
+            .GreaterThan(0.0)
+            .WithMessage("`tileSizeMeters` must be greater than 0.");
+
+        // Freshness window: capturedAt ∈ [now - MaxAgeDays, now + CapturedAtFutureSkewSeconds].
+        // `Must` lambdas close over `tp` so the comparison fetches fresh
+        // time per call (rule executes at validation time, not constructor
+        // time). Equivalent to AZ-488 Rule 4 in UavTileQualityGate.
+        RuleFor(m => m.CapturedAt)
+            .Must(capturedAt => capturedAt.ToUniversalTime() <= tp.GetUtcNow().UtcDateTime.AddSeconds(futureSkewSeconds))
+                .WithMessage($"`capturedAt` must be within {futureSkewSeconds}s of the current time (no future-dated tiles).")
+            .Must(capturedAt => capturedAt.ToUniversalTime() >= tp.GetUtcNow().UtcDateTime.AddDays(-maxAgeDays))
+                .WithMessage($"`capturedAt` must be within the last {maxAgeDays} days.");
+
+        // `FlightId` is intentionally not validated beyond JSON shape — AZ-503
+        // anonymous-flight semantics require null/missing to be a valid case.
+        // System.Text.Json already rejects malformed UUID strings at the
+        // deserializer with `JsonException` → 400 via GlobalExceptionHandler.
+    }
+}

SatelliteProvider.Api/Validators/UavUploadValidationFilter.cs

@@ -0,0 +1,122 @@
+using System.Text.Json;
+using FluentValidation;
+using Microsoft.AspNetCore.Http.Json;
+using Microsoft.Extensions.Options;
+using SatelliteProvider.Common.DTO;
+
+namespace SatelliteProvider.Api.Validators;
+
+// AZ-810: endpoint filter for `POST /api/satellite/upload`. The endpoint is
+// `multipart/form-data`, not a plain JSON body, so the standard
+// `WithValidation<T>()` filter (which expects an `[FromBody]` argument
+// already deserialized by the binder) cannot be used. This filter reads
+// the multipart `metadata` form field, deserializes it with the strict
+// global `JsonSerializerOptions` (which includes
+// `UnmappedMemberHandling.Disallow` from AZ-795), runs the FluentValidation
+// rules on `UavTileBatchMetadataPayload`, and adds the cross-field
+// alignment check (`metadata.items.Count == files.Count`).
+//
+// Failures are returned as RFC 7807 `ValidationProblemDetails` matching
+// `_docs/02_document/contracts/api/error-shape.md` v1.0.0; error-map keys
+// are prefixed with `metadata.` so paths like `items[0].latitude` from
+// the per-item validator surface to the caller as
+// `errors["metadata.items[0].latitude"]`.
+//
+// The downstream `IUavTileUploadHandler` retains its own envelope checks
+// as a defence-in-depth backstop (also covers callers invoking the
+// handler directly in unit tests). When the filter has already validated,
+// the handler's checks are no-ops by construction.
+public sealed class UavUploadValidationFilter : IEndpointFilter
+{
+    private const string MetadataKeyPrefix = "metadata.";
+    private const string MetadataField = "metadata";
+    private const string FilesField = "files";
+
+    private readonly IValidator<UavTileBatchMetadataPayload> _validator;
+    private readonly JsonSerializerOptions _jsonOptions;
+
+    public UavUploadValidationFilter(
+        IValidator<UavTileBatchMetadataPayload> validator,
+        IOptions<JsonOptions> jsonOptions)
+    {
+        _validator = validator ?? throw new ArgumentNullException(nameof(validator));
+        ArgumentNullException.ThrowIfNull(jsonOptions);
+        _jsonOptions = jsonOptions.Value.SerializerOptions;
+    }
+
+    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
+    {
+        var request = context.HttpContext.Request;
+        if (!request.HasFormContentType)
+        {
+            return Results.ValidationProblem(new Dictionary<string, string[]>
+            {
+                [MetadataField] = new[] { "Request must be `multipart/form-data`." },
+            });
+        }
+
+        var form = await request.ReadFormAsync(context.HttpContext.RequestAborted);
+        var metadataField = form[MetadataField].ToString();
+        var files = form.Files;
+
+        if (string.IsNullOrWhiteSpace(metadataField))
+        {
+            return Results.ValidationProblem(new Dictionary<string, string[]>
+            {
+                [MetadataField] = new[] { "`metadata` form field is required." },
+            });
+        }
+
+        UavTileBatchMetadataPayload? payload;
+        try
+        {
+            payload = JsonSerializer.Deserialize<UavTileBatchMetadataPayload>(metadataField, _jsonOptions);
+        }
+        catch (JsonException ex)
+        {
+            // System.Text.Json with UnmappedMemberHandling.Disallow + [JsonRequired]
+            // covers: unknown root/nested fields, missing required fields, type
+            // mismatches. Surface uniformly as `errors.metadata`.
+            return Results.ValidationProblem(new Dictionary<string, string[]>
+            {
+                [MetadataField] = new[] { $"`metadata` could not be parsed as JSON: {ex.Message}" },
+            });
+        }
+
+        if (payload is null)
+        {
+            return Results.ValidationProblem(new Dictionary<string, string[]>
+            {
+                [MetadataField] = new[] { "`metadata` must be a non-null JSON object." },
+            });
+        }
+
+        var result = await _validator.ValidateAsync(payload, context.HttpContext.RequestAborted);
+        if (!result.IsValid)
+        {
+            var prefixed = new Dictionary<string, string[]>(StringComparer.Ordinal);
+            foreach (var group in result.ToDictionary())
+            {
+                prefixed[MetadataKeyPrefix + group.Key] = group.Value;
+            }
+            return Results.ValidationProblem(prefixed);
+        }
+
+        if (payload.Items.Count != files.Count)
+        {
+            return Results.ValidationProblem(new Dictionary<string, string[]>
+            {
+                [MetadataKeyPrefix + "items"] = new[]
+                {
+                    $"`metadata.items` has {payload.Items.Count} entries but `files` has {files.Count}.",
+                },
+                [FilesField] = new[]
+                {
+                    $"`files` has {files.Count} entries but `metadata.items` has {payload.Items.Count}.",
+                },
+            });
+        }
+
+        return await next(context);
+    }
+}