feat: update controls in the admin, release token scope, build info in CI images [CI]

The versions page shows each node's update state with update buttons, API tokens get a release scope that can only register releases (used by CI), and the CI image and release builds now pass the tag, commit and build time.
2026-10-06 22:57:04 +08:00
1 parent 993dd5c41c
commit 251e0cee99
@@ -1140,6 +1140,116 @@
        }
      }
    },
+    "/api/admin/releases": {
+      "post": {
+        "tags": [
+          "admin-build"
+        ],
+        "summary": "Register a CI-signed release manifest; online nodes get it right away (their updaters verify the signature). Admin or release tokens",
+        "operationId": "releases_publish",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PublishReleaseRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ReleaseDto"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDto"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDto"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDto"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Conflict",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDto"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "admin-build"
+        ],
+        "summary": "The latest signed release manifest of each component",
+        "operationId": "releases_list",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PageDtoOfReleaseDto"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDto"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDto"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
    "/api/admin/auth/logout": {
      "post": {
        "tags": [
@@ -3732,116 +3842,6 @@
        }
      }
    },
-    "/api/admin/releases": {
-      "get": {
-        "tags": [
-          "admin-build"
-        ],
-        "summary": "The latest signed release manifest of each component",
-        "operationId": "releases_list",
-        "responses": {
-          "200": {
-            "description": "OK",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PageDtoOfReleaseDto"
-                }
-              }
-            }
-          },
-          "401": {
-            "description": "Unauthorized",
-            "content": {
-              "application/problem+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDto"
-                }
-              }
-            }
-          },
-          "403": {
-            "description": "Forbidden",
-            "content": {
-              "application/problem+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDto"
-                }
-              }
-            }
-          }
-        }
-      },
-      "post": {
-        "tags": [
-          "admin-build"
-        ],
-        "summary": "Register a CI-signed release manifest; online nodes get it right away (their updaters verify the signature)",
-        "operationId": "releases_publish",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PublishReleaseRequest"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "201": {
-            "description": "Created",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ReleaseDto"
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Bad Request",
-            "content": {
-              "application/problem+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDto"
-                }
-              }
-            }
-          },
-          "401": {
-            "description": "Unauthorized",
-            "content": {
-              "application/problem+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDto"
-                }
-              }
-            }
-          },
-          "403": {
-            "description": "Forbidden",
-            "content": {
-              "application/problem+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDto"
-                }
-              }
-            }
-          },
-          "409": {
-            "description": "Conflict",
-            "content": {
-              "application/problem+json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ProblemDto"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
    "/api/admin/nodes/{id}/update": {
      "post": {
        "tags": [
@@ -7421,6 +7421,9 @@
    {
      "name": "admin-auth"
    },
+    {
+      "name": "admin-build"
+    },
    {
      "name": "admin-agents"
    },
@@ -7448,9 +7451,6 @@
    {
      "name": "admin-users"
    },
-    {
-      "name": "admin-build"
-    },
    {
      "name": "ops"
    },
@@ -19,13 +19,18 @@ public static class BuildEndpoints
            .Returns<BuildInfoDto>().ProducesProblems(401, 403);
        group.MapGet("/releases", ListReleasesAsync)
            .Api("releases_list", "The latest signed release manifest of each component", Tag).Returns<PageDto<ReleaseDto>>().ProducesProblems(401, 403);
-        group.MapPost("/releases", PublishReleaseAsync)
-            .Api("releases_publish", "Register a CI-signed release manifest; online nodes get it right away (their updaters verify the signature)", Tag)
-            .Returns<ReleaseDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409);
        group.MapPost("/nodes/{id}/update", RequestUpdateAsync)
            .Api("nodes_update", "Ask an online agent or probe to install the release it has been offered", Tag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403, 409);
    }

+    /// <summary>登记发布清单：挂在 <see cref="ReleaseGuard"/> 下，除了管理员，CI 用的 <c>release</c> 令牌也能调用（它只能做这一件事）。</summary>
+    public static void MapPublish(RouteGroupBuilder group)
+    {
+        group.MapPost("/releases", PublishReleaseAsync)
+            .Api("releases_publish", "Register a CI-signed release manifest; online nodes get it right away (their updaters verify the signature). Admin or release tokens", Tag)
+            .Returns<ReleaseDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409);
+    }
+
    private static async Task<IResult> GetAsync(HttpContext http, NodeInfoService nodes, ReleaseService releases, CancellationToken ct)
    {
        var items = (await nodes.ListAsync(ct))
@@ -103,6 +103,8 @@ public static class ApiModule
        RouteGroupBuilder admin = app.MapGroup("/api/admin");
        AuthEndpoints.MapLogin(admin);

+        BuildEndpoints.MapPublish(admin.MapGroup(string.Empty).AddEndpointFilter(ReleaseGuard.InvokeAsync));
+
        RouteGroupBuilder guarded = admin.MapGroup(string.Empty).AddEndpointFilter(AdminGuard.InvokeAsync);
        AuthEndpoints.MapSession(guarded);
        AgentEndpoints.Map(guarded);
@@ -62,7 +62,7 @@ public static class AdminGuard
        Principal principal = http.GetPrincipal();
        if (!principal.IsAdmin)
        {
-            return principal.CanRead
+            return principal.Scope != ApiScope.None
                ? Problems.Create(http, MonitorErrors.Forbidden, "the token scope does not allow this operation")
                : Problems.Create(http, MonitorErrors.Unauthorized, "authentication is required");
        }
@@ -80,6 +80,13 @@ public static class AdminGuard
    }
 }

+/// <summary>登记发布清单的守卫：管理员（会话要带 CSRF）或 release 令牌；release 令牌只能做这一件事。</summary>
+public static class ReleaseGuard
+{
+    public static async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next) =>
+        context.HttpContext.GetPrincipal().Scope == ApiScope.Release ? await next(context) : await AdminGuard.InvokeAsync(context, next);
+}
+
 /// <summary>展示层守卫：站点公开时匿名可读；私有时需要登录或只读令牌。</summary>
 public static class PublicGuard
 {
@@ -7,12 +7,13 @@ public enum PrincipalKind
    Token,
 }

-/// <summary>访问级别：作用域为 read 的令牌只读，admin 可以管理。</summary>
+/// <summary>访问级别：作用域为 read 的令牌只读，admin 可以管理，release 只能登记发布清单（给 CI 用，什么都读不了）。</summary>
 public enum ApiScope
 {
    None = 0,
-    Read = 1,
-    Admin = 2,
+    Release = 1,
+    Read = 2,
+    Admin = 3,
 }

 public sealed record Principal(PrincipalKind Kind, ApiScope Scope, string? UserId, string? Username, string? CsrfToken, string? TokenId)
@@ -22,6 +23,8 @@ public sealed record Principal(PrincipalKind Kind, ApiScope Scope, string? UserI
    public bool CanRead => Scope >= ApiScope.Read;

    public bool IsAdmin => Scope >= ApiScope.Admin;
+
+    public bool CanPublishRelease => Scope is ApiScope.Release or ApiScope.Admin;
 }

 public sealed record LoginResult(string SessionToken, string CsrfToken, long ExpiresAtMs, string UserId, string Username);
@@ -77,7 +77,7 @@ public sealed partial class AuthService
            await _store.TouchApiTokenAsync(token.Id, now, ct);
        }

-        ApiScope scope = token.Scope == "admin" ? ApiScope.Admin : ApiScope.Read;
+        ApiScope scope = token.Scope switch { "admin" => ApiScope.Admin, "release" => ApiScope.Release, _ => ApiScope.Read };
        return new Principal(PrincipalKind.Token, scope, null, token.Name, null, token.Id);
    }

@@ -135,9 +135,9 @@ public sealed partial class AuthService
            return ValidationError.Fail<CreatedApiToken>("name", "must be 1-64 characters");
        }

-        if (scope is not ("read" or "admin"))
+        if (scope is not ("read" or "admin" or "release"))
        {
-            return ValidationError.Fail<CreatedApiToken>("scope", "must be read or admin");
+            return ValidationError.Fail<CreatedApiToken>("scope", "must be read, admin or release");
        }

        string plaintext = TokenHash.NewToken("mon");
@@ -67,6 +67,40 @@ public sealed class UpdateTests
        Assert.Contains(anonymous.StatusCode, new[] { HttpStatusCode.Unauthorized, HttpStatusCode.Forbidden });
    }

+    [Fact]
+    public async Task ReleaseToken_CanOnlyRegisterReleases_AndAReadTokenCannotEvenDoThat()
+    {
+        async Task<string> NewTokenAsync(string scope)
+        {
+            using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = _backend.UniqueName("ci"), ["scope"] = scope }));
+            Assert.Equal(HttpStatusCode.Created, created.StatusCode);
+            return JsonNode.Parse(await created.Content.ReadAsStringAsync())!["plaintext"]!.GetValue<string>();
+        }
+
+        HttpClient Client(string token)
+        {
+            var client = new HttpClient { BaseAddress = _backend.BaseAddress };
+            client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
+            return client;
+        }
+
+        long seq = TimeProvider.System.GetUtcNow().ToUnixTimeSeconds() * 1000 + 50;
+        using HttpClient release = Client(await NewTokenAsync("release"));
+        using HttpClient read = Client(await NewTokenAsync("read"));
+        var body = BackendFixture.Json(new JsonObject { ["manifest"] = Manifest("probe", seq), ["signature"] = "MEUC" });
+
+        using HttpResponseMessage forbidden = await read.PostAsync("/api/admin/releases", BackendFixture.Json(new JsonObject { ["manifest"] = Manifest("probe", seq), ["signature"] = "MEUC" }));
+        Assert.Equal(HttpStatusCode.Forbidden, forbidden.StatusCode);
+        using HttpResponseMessage published = await release.PostAsync("/api/admin/releases", body);
+        Assert.Equal(HttpStatusCode.Created, published.StatusCode);
+
+        // release 令牌只能登记发布清单：读不了任何东西，也不能做别的管理操作
+        Assert.Equal(HttpStatusCode.Forbidden, (await release.GetAsync("/api/admin/agents")).StatusCode);
+        Assert.Equal(HttpStatusCode.Forbidden, (await release.GetAsync("/api/admin/releases")).StatusCode);
+        Assert.Equal(HttpStatusCode.Forbidden, (await release.PostAsync("/api/admin/nodes/agt_x/update", null)).StatusCode);
+        Assert.Equal(HttpStatusCode.Unauthorized, (await _backend.Anonymous.PostAsync("/api/admin/releases", BackendFixture.Json(new JsonObject { ["manifest"] = Manifest("probe", seq + 1), ["signature"] = "MEUC" }))).StatusCode);
+    }
+
    [Fact]
    public async Task UpdateRequest_ReachesTheNode_AndItsReportedStatusShowsInBuildInfo()
    {