feat: Document the API in OpenAPI, unify problem responses

The hand-written firmware-api-spec.md is gone; the generated Scalar
document is now the contract. Controllers carry XML docs and
ProducesResponseType attributes for every status they can return, with
the error codes behind each one noted inline.

Authorization failures on the versioned API surface now answer with a
problem body naming the unmet requirements instead of a bare 403.
Browser requests to the admin UI still fall through to the redirect.

JSON settings live in one place, so problem bodies written from
middleware are shaped like the ones written from controllers. Errors
and JSON serialization each move to their own namespace.

Author: hhvrc

README.md

@@ -29,10 +29,9 @@ secrets.
 
 ### API Documentation
 
-The Scalar API reference is served at `/scalar` on any running instance.
-
-`firmware-api-spec.md` in this repository is the canonical contract for the firmware endpoints:
-response shapes, caching rules, error codes and the release workflow. Consumers should conform to it.
+The Scalar API reference is served at `/scalar` on any running instance. It is generated from the
+controllers, one document per API version, and covers response shapes, caching rules and the problem
+details returned on error.
 
 # Configuration
 
@@ -239,8 +238,6 @@ the build fails. With `?nofail` the release is created in `editing` status inste
 published until a maintainer fixes the notes through the admin endpoint. Releases that outlive their
 TTL are aborted by a background job that runs every five minutes.
 
-See sections 5.2 and 5.3 of `firmware-api-spec.md` for request bodies and the changelog format.
-
 # Deployment / Self Hosting
 
 The stack is small:

RepositoryServer/ApiSurface.cs

@@ -0,0 +1,20 @@
+namespace OpenShock.RepositoryServer;
+
+/// <summary>
+/// Tells the versioned API surface apart from the browser-facing admin UI.
+/// </summary>
+/// <remarks>
+/// The two want different answers to the same authentication or authorization failure: an API caller
+/// wants a status code and a problem body, a browser wants to be sent to the login page. Deciding on
+/// path rather than sniffing Accept headers keeps the behaviour identical for curl, fetch and the
+/// admin UI.
+/// </remarks>
+public static class ApiSurface
+{
+    /// <summary>
+    /// True for anything under the versioned API prefixes; everything else is assumed to be a browser
+    /// that can usefully follow a redirect.
+    /// </summary>
+    public static bool IsApiPath(PathString path) =>
+        path.StartsWithSegments("/1") || path.StartsWithSegments("/2");
+}

RepositoryServer/AuthenticationHandlers/GitHubAuthentication.cs

@@ -1,17 +1,15 @@
 using System.Net;
 using System.Net.Http.Headers;
-using System.Net.Mime;
 using System.Security.Claims;
 using System.Text.Json;
 using AspNet.Security.OAuth.GitHub;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication.Cookies;
 using Microsoft.AspNetCore.Authentication.OAuth;
-using Microsoft.Extensions.Options;
 using OpenShock.Internal.Common.Problems;
 using OpenShock.RepositoryServer.Config;
 using OpenShock.RepositoryServer.Errors;
-using JsonOptions = Microsoft.AspNetCore.Http.Json.JsonOptions;
+using OpenShock.RepositoryServer.JsonSerialization;
 
 namespace OpenShock.RepositoryServer.AuthenticationHandlers;
 
@@ -205,7 +203,7 @@ private static Task WriteProblemOrRedirect<TOptions>(
         RedirectContext<TOptions> context, OpenShockProblem problem)
         where TOptions : AuthenticationSchemeOptions
     {
-        if (IsApiPath(context.Request.Path))
+        if (ApiSurface.IsApiPath(context.Request.Path))
         {
             return WriteProblemAsync(context.HttpContext, problem);
         }
@@ -214,25 +212,10 @@ private static Task WriteProblemOrRedirect<TOptions>(
         return Task.CompletedTask;
     }
 
-    /// <summary>
-    /// Versioned API surface. Everything under these prefixes answers with a status code; anything
-    /// else is assumed to be a browser that can usefully follow a redirect.
-    /// </summary>
-    private static bool IsApiPath(PathString path) =>
-        path.StartsWithSegments("/1") || path.StartsWithSegments("/2");
-
     private static Task WriteProblemAsync(HttpContext httpContext, OpenShockProblem problem)
     {
         if (httpContext.Response.HasStarted) return Task.CompletedTask;
 
-        problem.RequestId = httpContext.TraceIdentifier;
-        httpContext.Response.StatusCode = problem.Status!.Value;
-
-        var serializerOptions = httpContext.RequestServices
-            .GetRequiredService<IOptions<JsonOptions>>()
-            .Value.SerializerOptions;
-
-        return httpContext.Response.WriteAsJsonAsync(problem, serializerOptions,
-            contentType: MediaTypeNames.Application.ProblemJson);
+        return problem.WriteAsJsonAsync(httpContext, JsonOptions.Default, httpContext.RequestAborted);
     }
 }

RepositoryServer/AuthenticationHandlers/OpenShockAuthorizationMiddlewareResultHandler.cs

@@ -0,0 +1,37 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Authorization.Policy;
+using OpenShock.RepositoryServer.Errors;
+using OpenShock.RepositoryServer.JsonSerialization;
+
+namespace OpenShock.RepositoryServer.AuthenticationHandlers;
+
+/// <summary>
+/// Answers a failed authorization with a problem body naming the requirements that were not met,
+/// instead of the framework default of a bare 403.
+/// </summary>
+/// <remarks>
+/// Only the versioned API surface is handled here. A browser hitting an admin page is left to the
+/// default handler, which calls Forbid on the cookie scheme and lands in
+/// <see cref="GitHubAuthentication.ConfigureCookie"/>'s access-denied event - the redirect a page
+/// request wants. Challenges (401) always fall through for the same reason: they are what start a
+/// login.
+/// </remarks>
+public sealed class OpenShockAuthorizationMiddlewareResultHandler : IAuthorizationMiddlewareResultHandler
+{
+    private readonly AuthorizationMiddlewareResultHandler _defaultHandler = new();
+
+    public Task HandleAsync(RequestDelegate next, HttpContext context, AuthorizationPolicy policy,
+        PolicyAuthorizationResult authorizeResult)
+    {
+        if (authorizeResult.Forbidden && ApiSurface.IsApiPath(context.Request.Path))
+        {
+            var failedRequirements = authorizeResult.AuthorizationFailure?.FailedRequirements
+                                         .Select(x => x.ToString() ?? "error") ?? [];
+
+            return AuthorizationError.PolicyNotMet(failedRequirements)
+                .WriteAsJsonAsync(context, JsonOptions.Default, context.RequestAborted);
+        }
+
+        return _defaultHandler.HandleAsync(next, context, policy, authorizeResult);
+    }
+}

RepositoryServer/Components/_Imports.razor

@@ -15,7 +15,7 @@
 @using OpenShock.RepositoryServer.Components.Layout
 @using OpenShock.RepositoryServer.Components.Pages
 @using OpenShock.RepositoryServer.Enums
-@using OpenShock.RepositoryServer.Problems
+@using OpenShock.RepositoryServer.Errors
 @using OpenShock.RepositoryServer.RepoServerDb
 @using OpenShock.RepositoryServer.Services.Admin
 @using OpenShock.RepositoryServer.Components.Shared

RepositoryServer/Controllers/AuthController.cs

@@ -2,6 +2,7 @@
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using OpenShock.Internal.Common;
+using OpenShock.Internal.Common.Problems;
 using OpenShock.RepositoryServer.AuthenticationHandlers;
 using OpenShock.RepositoryServer.Errors;
 using System.Net.Mime;
@@ -32,8 +33,12 @@ public AuthController(AdminAuthMode authMode)
     /// <summary>
     /// Starts the GitHub login. Returns a redirect to GitHub's authorization page.
     /// </summary>
+    /// <response code="302">Redirect to GitHub, or straight to <paramref name="returnUrl"/> under the development bypass.</response>
+    /// <response code="400">The return url is not a relative path on this server.</response>
     [HttpGet("login")]
     [AllowAnonymous]
+    [ProducesResponseType(StatusCodes.Status302Found)]
+    [ProducesResponseType<OpenShockProblem>(StatusCodes.Status400BadRequest, MediaTypeNames.Application.ProblemJson)] // InvalidReturnUrl
     public IActionResult Login([FromQuery] string? returnUrl)
     {
         // An open redirect here would be worth something: the victim arrives from a real login on the

RepositoryServer/Controllers/V1/CiCdController.cs

@@ -3,8 +3,9 @@
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.EntityFrameworkCore;
 using OpenShock.Internal.Common;
+using OpenShock.Internal.Common.Problems;
 using OpenShock.RepositoryServer.Config;
-using OpenShock.RepositoryServer.Problems;
+using OpenShock.RepositoryServer.Errors;
 using OpenShock.RepositoryServer.RepoServerDb;
 using OpenShock.RepositoryServer.Services;
 using Semver;
@@ -41,9 +42,19 @@ public CiCdController(RepoServerContext db, IStorageService storage, ApiConfig a
     /// Publishes a desktop module version by uploading a zip file.
     /// The file is hashed server-side, uploaded to storage, and recorded in the database.
     /// </summary>
+    /// <response code="201">The version was published.</response>
+    /// <response code="400">The version is not valid semver, or the uploaded zip is missing or rejected.</response>
+    /// <response code="403">The calling repository does not own this module.</response>
+    /// <response code="404">The module does not exist.</response>
+    /// <response code="409">This version has already been published.</response>
     [HttpPut("modules/{moduleId}/versions/{moduleVersion}")]
     [Consumes("multipart/form-data")]
     [RequestSizeLimit(256 * 1024 * 1024)] // 256 MB
+    [ProducesResponseType(StatusCodes.Status201Created)]
+    [ProducesResponseType<OpenShockProblem>(StatusCodes.Status400BadRequest, MediaTypeNames.Application.ProblemJson)] // VersionInvalidSemver, ZipMissing, ZipInvalid, ZipEmpty, ZipPathTraversal, ZipDisallowedDirectory, ZipDisallowedRootFile
+    [ProducesResponseType<OpenShockProblem>(StatusCodes.Status403Forbidden, MediaTypeNames.Application.ProblemJson)] // ModuleNotOwned
+    [ProducesResponseType<OpenShockProblem>(StatusCodes.Status404NotFound, MediaTypeNames.Application.ProblemJson)] // ModuleNotFound
+    [ProducesResponseType<OpenShockProblem>(StatusCodes.Status409Conflict, MediaTypeNames.Application.ProblemJson)] // VersionAlreadyExists
     public async Task<IActionResult> PublishVersion(
         [FromRoute] string moduleId,
         [FromRoute] string moduleVersion,
@@ -86,7 +97,7 @@ public async Task<IActionResult> PublishVersion(
         var file = Request.Form.Files.GetFile("zip");
         if (file == null)
         {
-            return BadRequest(new { error = "No file uploaded. Expected a file field named 'zip'." });
+            return Problem(ModuleError.ZipMissing);
         }
 
         // Read file into memory for validation + hashing + storage upload

RepositoryServer/Controllers/V1/RepoController.cs

@@ -29,7 +29,12 @@ public RepoController(RepoServerContext db, ApiConfig apiConfig)
         _apiConfig = apiConfig;
     }
 
+    /// <summary>
+    /// Gets the desktop module repository index: every module and its published versions.
+    /// </summary>
+    /// <response code="200">The repository index.</response>
     [HttpGet]
+    [ProducesResponseType<Repository>(StatusCodes.Status200OK, MediaTypeNames.Application.Json)]
     public async Task<IActionResult> GetRepo()
     {
         var moduleRaw = await _db.Modules.Include(x => x.Versions).ToArrayAsync();

RepositoryServer/Controllers/V2/Firmware/BoardsController.cs

@@ -23,8 +23,16 @@ public BoardsController(RepoServerContext db)
         _db = db;
     }
 
+    /// <summary>
+    /// Lists the known boards.
+    /// </summary>
+    /// <param name="chip">Optional chip name filter, matched case-insensitively.</param>
+    /// <param name="includeDiscontinued">Whether to include boards that are no longer produced.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <response code="200">The matching boards, ordered by name.</response>
     [HttpGet]
     [CacheControl(300)]
+    [ProducesResponseType<List<FirmwareBoardDto>>(StatusCodes.Status200OK, MediaTypeNames.Application.Json)]
     public async Task<IActionResult> ListBoards(
         [FromQuery] string? chip,
         [FromQuery] bool includeDiscontinued = true,

RepositoryServer/Controllers/V2/Firmware/ChipsController.cs

@@ -22,8 +22,14 @@ public ChipsController(RepoServerContext db)
         _db = db;
     }
 
+    /// <summary>
+    /// Lists the known chips.
+    /// </summary>
+    /// <param name="ct">Cancellation token.</param>
+    /// <response code="200">The chips, ordered by name.</response>
     [HttpGet]
     [CacheControl(300)]
+    [ProducesResponseType<List<FirmwareChipDto>>(StatusCodes.Status200OK, MediaTypeNames.Application.Json)]
     public async Task<IActionResult> ListChips(CancellationToken ct)
     {
         var rows = await _db.FirmwareChips