[AZ-488] UAV tile batch upload + 5-rule quality gate

Replaces the 501 stub at POST /api/satellite/upload with a multipart
batch endpoint that ingests UAV-captured tiles, runs each item through
a 5-rule quality gate, and persists accepted tiles via the AZ-484
multi-source storage path with source='uav'.

Quality gate (in fixed order, first failure wins): JPEG format
(content-type + magic), size band 5 KiB-5 MiB, exact 256x256
dimensions, captured-at age (no future >30 s skew, no older than
7 days), luminance variance on 32x32 downsample. Closed reject-reason
enumeration in v1.0.0 contract.

Authorization: custom PermissionsRequirement / PermissionsAuthorization
Handler that reads the JWT `permissions` claim (tolerates both
repeated-string and JSON-array shapes). Endpoint protected by
RequiresGpsPermission policy; 401 without token, 403 without GPS perm.

Persistence: file-first to ./tiles/uav/{z}/{x}/{y}.jpg, then
ITileRepository.InsertAsync UPSERT (per-source UPSERT contract from
AZ-484). Per-item failures reported in response without aborting the
batch. Kestrel MaxRequestBodySize and FormOptions limits set to
MaxBatchSize x MaxBytes (default 100 x 5 MiB = 500 MiB).

New frozen contract: _docs/02_document/contracts/api/uav-tile-upload.md
v1.0.0. PT-08 NFR added to performance-tests.md as Deferred (harness
work tracked in PT-07 leftover, per AZ-488 § Risk 4).

Tests: 11 quality-gate unit tests, 5 handler unit tests, 3 file-path
unit tests, 12 permission-handler unit tests, 7 integration tests
(AC-1..AC-6, AC-8). All 253 unit tests + smoke integration suite
green.

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

SatelliteProvider.Api/Authentication/PermissionsRequirement.cs

@@ -0,0 +1,119 @@
+using System.Security.Claims;
+using System.Text.Json;
+using Microsoft.AspNetCore.Authorization;
+
+namespace SatelliteProvider.Api.Authentication;
+
+// AZ-488: enforces a required permission from the `permissions` JWT claim.
+// The claim may arrive as either:
+//   - a JWT array claim (multiple ClaimType="permissions" entries — Microsoft.IdentityModel
+//     splits arrays this way), OR
+//   - a single JSON-array string ("[\"GPS\",\"FL\"]") when a producer mis-encodes.
+// Both shapes are matched so the satellite-provider remains tolerant of upstream
+// producers that do not split array claims out of the box.
+public sealed class PermissionsRequirement : IAuthorizationRequirement
+{
+    public PermissionsRequirement(string requiredPermission)
+    {
+        if (string.IsNullOrWhiteSpace(requiredPermission))
+        {
+            throw new ArgumentException("Required permission must be a non-empty string.", nameof(requiredPermission));
+        }
+
+        RequiredPermission = requiredPermission;
+    }
+
+    public string RequiredPermission { get; }
+}
+
+public sealed class PermissionsAuthorizationHandler : AuthorizationHandler<PermissionsRequirement>
+{
+    public const string ClaimType = "permissions";
+
+    protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, PermissionsRequirement requirement)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        ArgumentNullException.ThrowIfNull(requirement);
+
+        var user = context.User;
+        if (user?.Identity?.IsAuthenticated != true)
+        {
+            return Task.CompletedTask;
+        }
+
+        if (UserHasPermission(user, requirement.RequiredPermission))
+        {
+            context.Succeed(requirement);
+        }
+
+        return Task.CompletedTask;
+    }
+
+    private static bool UserHasPermission(ClaimsPrincipal user, string requiredPermission)
+    {
+        foreach (var claim in user.FindAll(ClaimType))
+        {
+            if (string.Equals(claim.Value, requiredPermission, StringComparison.Ordinal))
+            {
+                return true;
+            }
+
+            if (TryReadJsonArray(claim.Value, out var values))
+            {
+                foreach (var value in values)
+                {
+                    if (string.Equals(value, requiredPermission, StringComparison.Ordinal))
+                    {
+                        return true;
+                    }
+                }
+            }
+        }
+
+        return false;
+    }
+
+    private static bool TryReadJsonArray(string value, out IReadOnlyList<string> items)
+    {
+        items = Array.Empty<string>();
+        if (string.IsNullOrWhiteSpace(value) || value[0] != '[')
+        {
+            return false;
+        }
+
+        try
+        {
+            using var document = JsonDocument.Parse(value);
+            if (document.RootElement.ValueKind != JsonValueKind.Array)
+            {
+                return false;
+            }
+
+            var result = new List<string>(document.RootElement.GetArrayLength());
+            foreach (var element in document.RootElement.EnumerateArray())
+            {
+                if (element.ValueKind == JsonValueKind.String)
+                {
+                    var text = element.GetString();
+                    if (!string.IsNullOrEmpty(text))
+                    {
+                        result.Add(text);
+                    }
+                }
+            }
+
+            items = result;
+            return result.Count > 0;
+        }
+        catch (JsonException)
+        {
+            return false;
+        }
+    }
+}
+
+public static class SatellitePermissions
+{
+    public const string Gps = "GPS";
+    public const string UavUploadPolicy = "RequiresGpsPermission";
+}

SatelliteProvider.Api/DTOs/UavTileBatchUploadRequest.cs

@@ -0,0 +1,16 @@
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+
+namespace SatelliteProvider.Api.DTOs;
+
+// AZ-488 / `uav-tile-upload.md` v1.0.0 — multipart envelope. `Metadata` carries the
+// JSON array of UavTileMetadata records; `Files` provides one IFormFile per record
+// at the matching ordinal index.
+public record UavTileBatchUploadRequest
+{
+    [FromForm(Name = "metadata")]
+    public string Metadata { get; init; } = string.Empty;
+
+    [FromForm(Name = "files")]
+    public IFormFileCollection? Files { get; init; }
+}

SatelliteProvider.Api/DTOs/UploadImageRequest.cs

@@ -1,30 +0,0 @@
-using System.ComponentModel.DataAnnotations;
-
-namespace SatelliteProvider.Api.DTOs;
-
-public record UploadImageRequest
-{
-    [Required]
-    public DateTime Timestamp { get; set; }
-
-    [Required]
-    public IFormFile? Image { get; set; }
-
-    [Required]
-    public double Lat { get; set; }
-
-    [Required]
-    public double Lon { get; set; }
-
-    [Required]
-    public double Height { get; set; }
-
-    [Required]
-    public double FocalLength { get; set; }
-
-    [Required]
-    public double SensorWidth { get; set; }
-
-    [Required]
-    public double SensorHeight { get; set; }
-}

SatelliteProvider.Api/Program.cs

@@ -1,4 +1,7 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http.Features;
 using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Server.Kestrel.Core;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
 using SatelliteProvider.Api;
@@ -29,6 +32,19 @@ DapperEnumTypeHandlers.RegisterAll();
 builder.Services.Configure<MapConfig>(builder.Configuration.GetSection("MapConfig"));
 builder.Services.Configure<StorageConfig>(builder.Configuration.GetSection("StorageConfig"));
 builder.Services.Configure<ProcessingConfig>(builder.Configuration.GetSection("ProcessingConfig"));
+builder.Services.Configure<UavQualityConfig>(builder.Configuration.GetSection("UavQuality"));
+
+var uavQuality = builder.Configuration.GetSection("UavQuality").Get<UavQualityConfig>() ?? new UavQualityConfig();
+var uavBatchBodyLimit = checked((long)uavQuality.MaxBatchSize * uavQuality.MaxBytes);
+builder.Services.Configure<KestrelServerOptions>(options =>
+{
+    options.Limits.MaxRequestBodySize = uavBatchBodyLimit;
+});
+builder.Services.Configure<FormOptions>(options =>
+{
+    options.MultipartBodyLengthLimit = uavBatchBodyLimit;
+    options.ValueLengthLimit = Math.Max(options.ValueLengthLimit, uavQuality.MaxBatchSize * 512);
+});
 
 builder.Services.AddSingleton<ITileRepository>(sp => new TileRepository(connectionString, sp.GetRequiredService<ILogger<TileRepository>>()));
 builder.Services.AddSingleton<IRegionRepository>(sp => new RegionRepository(connectionString));
@@ -41,7 +57,15 @@ builder.Services.AddRegionProcessing();
 builder.Services.AddRouteManagement();
 
 builder.Services.AddSatelliteJwt(builder.Configuration);
-builder.Services.AddAuthorization();
+builder.Services.AddSingleton<IAuthorizationHandler, PermissionsAuthorizationHandler>();
+builder.Services.AddAuthorization(options =>
+{
+    options.AddPolicy(SatellitePermissions.UavUploadPolicy, policy =>
+    {
+        policy.RequireAuthenticatedUser();
+        policy.Requirements.Add(new PermissionsRequirement(SatellitePermissions.Gps));
+    });
+});
 
 var allowedOrigins = builder.Configuration.GetSection("CorsConfig:AllowedOrigins").Get<string[]>() ?? Array.Empty<string>();
 var allowAnyOrigin = builder.Configuration.GetValue<bool>("CorsConfig:AllowAnyOrigin");
@@ -99,21 +123,24 @@ builder.Services.AddSwaggerGen(c =>
         }
     });
 
-    c.MapType<UploadImageRequest>(() => new OpenApiSchema
+    c.MapType<UavTileBatchUploadRequest>(() => new OpenApiSchema
     {
         Type = "object",
         Properties = new Dictionary<string, OpenApiSchema>
         {
-            ["timestamp"] = new() { Type = "string", Format = "date-time", Description = "Image capture timestamp" },
-            ["image"] = new() { Type = "string", Format = "binary", Description = "Image file to upload" },
-            ["lat"] = new() { Type = "number", Format = "double", Description = "Latitude coordinate where image was captured" },
-            ["lon"] = new() { Type = "number", Format = "double", Description = "Longitude coordinate where image was captured" },
-            ["height"] = new() { Type = "number", Format = "double", Description = "Height/altitude in meters where image was captured" },
-            ["focalLength"] = new() { Type = "number", Format = "double", Description = "Camera focal length in millimeters" },
-            ["sensorWidth"] = new() { Type = "number", Format = "double", Description = "Camera sensor width in millimeters" },
-            ["sensorHeight"] = new() { Type = "number", Format = "double", Description = "Camera sensor height in millimeters" }
+            ["metadata"] = new()
+            {
+                Type = "string",
+                Description = "JSON document `{ \"items\": [ { \"latitude\", \"longitude\", \"tileZoom\", \"tileSizeMeters\", \"capturedAt\" } ] }` where item ordinal index aligns with the matching file in `files`."
+            },
+            ["files"] = new()
+            {
+                Type = "array",
+                Description = "UAV tile JPEG files in the same order as `metadata.items`.",
+                Items = new OpenApiSchema { Type = "string", Format = "binary" }
+            }
         },
-        Required = new HashSet<string> { "timestamp", "image", "lat", "lon", "height", "focalLength", "sensorWidth", "sensorHeight" }
+        Required = new HashSet<string> { "metadata", "files" }
     });
 
     c.OperationFilter<ParameterDescriptionFilter>();
@@ -164,11 +191,16 @@ app.MapGet("/api/satellite/tiles/mgrs", GetSatelliteTilesByMgrs)
     .ProducesProblem(StatusCodes.Status501NotImplemented)
     .WithOpenApi(op => new(op) { Summary = "Get satellite tiles by MGRS coordinates (NOT IMPLEMENTED)" });
 
-app.MapPost("/api/satellite/upload", UploadImage)
-    .RequireAuthorization()
-    .Accepts<UploadImageRequest>("multipart/form-data")
-    .ProducesProblem(StatusCodes.Status501NotImplemented)
-    .WithOpenApi(op => new(op) { Summary = "Upload image with metadata (NOT IMPLEMENTED)" })
+app.MapPost("/api/satellite/upload", UploadUavTileBatch)
+    .RequireAuthorization(SatellitePermissions.UavUploadPolicy)
+    .Accepts<UavTileBatchUploadRequest>("multipart/form-data")
+    .Produces<UavTileBatchUploadResponse>(StatusCodes.Status200OK)
+    .ProducesProblem(StatusCodes.Status400BadRequest)
+    .WithOpenApi(op => new(op)
+    {
+        Summary = "Upload a batch of UAV-captured satellite tiles",
+        Description = "AZ-488 / `uav-tile-upload.md` v1.0.0. Multipart form: a JSON `metadata` field and an aligned `files` collection. Each item is graded by the 5-rule quality gate and persisted with `source='uav'` when accepted. Returns 200 with per-item results (mixed accept/reject), 400 for envelope-level errors (malformed metadata, missing files, oversized batch), 401 without a valid JWT, 403 without the `GPS` permission claim."
+    })
     .DisableAntiforgery();
 
 app.MapPost("/api/satellite/request", RequestRegion)
@@ -235,12 +267,33 @@ IResult GetSatelliteTilesByMgrs(string mgrs, double squareSideMeters)
         detail: "MGRS-based tile retrieval is not implemented.");
 }
 
-IResult UploadImage([FromForm] UploadImageRequest request)
+async Task<IResult> UploadUavTileBatch(
+    HttpContext httpContext,
+    IUavTileUploadHandler handler,
+    [FromForm] UavTileBatchUploadRequest request)
 {
-    return Results.Problem(
-        statusCode: StatusCodes.Status501NotImplemented,
-        title: "Not implemented",
-        detail: "Image upload is not implemented.");
+    ArgumentNullException.ThrowIfNull(request);
+
+    var files = request.Files ?? (IFormFileCollection)new FormFileCollection();
+    var uploadFiles = new List<UavUploadFile>(files.Count);
+    foreach (var file in files)
+    {
+        await using var stream = file.OpenReadStream();
+        using var buffer = new MemoryStream(checked((int)file.Length));
+        await stream.CopyToAsync(buffer, httpContext.RequestAborted);
+        uploadFiles.Add(new UavUploadFile(file.FileName, file.ContentType, buffer.ToArray()));
+    }
+
+    var result = await handler.HandleAsync(request.Metadata, uploadFiles, httpContext.RequestAborted);
+    if (result.EnvelopeRejected)
+    {
+        return Results.Problem(
+            statusCode: StatusCodes.Status400BadRequest,
+            title: "Invalid UAV tile batch",
+            detail: result.EnvelopeError);
+    }
+
+    return Results.Ok(result.Response);
 }
 
 async Task<IResult> RequestRegion([FromBody] RequestRegionRequest request, IRegionService regionService)

SatelliteProvider.Api/appsettings.json

@@ -26,6 +26,15 @@
   "Jwt": {
     "Secret": ""
   },
+  "UavQuality": {
+    "MinBytes": 5120,
+    "MaxBytes": 5242880,
+    "MaxAgeDays": 7,
+    "CapturedAtFutureSkewSeconds": 30,
+    "MinLuminanceVariance": 10.0,
+    "MaxBatchSize": 100,
+    "LuminanceSampleSize": 32
+  },
   "MapConfig": {
     "Service": "GoogleMaps",
     "ApiKey": "",