feat: operator trust root: passkey-signed operator set, signed join codes, nodes verify and pin the chain at enrollment [CI SKIP]

backend/src/MoShiro.Backend.Api/Admin/AuthEndpoints.cs

@@ -116,7 +116,7 @@ public static class AuthEndpoints
     }
 
     /// <summary>这次请求的 WebAuthn 依赖方：配置优先，其次面板对外地址，最后是请求自己的主机。</summary>
-    private static PasskeyContext PasskeyContextOf(HttpContext http, BackendOptions options)
+    internal static PasskeyContext PasskeyContextOf(HttpContext http, BackendOptions options)
     {
         string own = $"{http.Request.Scheme}://{http.Request.Host}";
         Uri? configured = Uri.TryCreate(options.PublicUrl, UriKind.Absolute, out Uri? uri) ? uri : null;

backend/src/MoShiro.Backend.Api/Admin/TrustEndpoints.cs

@@ -0,0 +1,74 @@
+using Fleet.Core;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Routing;
+using MoShiro.Backend.Application;
+using MoShiro.Protocol;
+
+namespace MoShiro.Backend.Api;
+
+/// <summary>
+/// 信任根（docs/access.md 第 7 节）：操作员集合由 passkey 签名，节点从安装命令里固定的创世指纹出发验证它；
+/// 带操作员委托的加入码也在这里创建——委托是 passkey 对「这个码」签的，面板自己签不出来。
+/// </summary>
+public static class TrustEndpoints
+{
+    private const string Tag = "admin-trust";
+
+    public static void Map(RouteGroupBuilder guarded)
+    {
+        guarded.MapGet("/trust", StateAsync)
+            .Api("trust_get", "The operator trust root: genesis fingerprint, version, whether it matches the registered passkeys, and the next version to sign", Tag)
+            .Returns<TrustStateDto>().ProducesProblems(401, 403)
+            .Requires(Capability.FleetRead);
+        guarded.MapPost("/trust", CommitAsync)
+            .Api("trust_commit", "Store the next operator set, signed with a passkey (the first one sets the genesis and needs a credential window)", Tag)
+            .Returns<TrustStateDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409)
+            .Requires(Capability.AccountsManage)
+            .ElevationExempt();
+        guarded.MapPost("/join-tokens/signed", CreateSignedTokenAsync)
+            .Api("join_tokens_create_signed", "Create a join code from a grant the operator signed with a passkey; the browser derives the code from a seed the panel never sees", Tag)
+            .Returns<JoinTokenDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409)
+            .Requires(Capability.FleetEnroll)
+            .ElevationExempt();
+    }
+
+    private static async Task<IResult> StateAsync(HttpContext http, TrustService trust, BackendOptions options)
+    {
+        TrustState state = await trust.StateAsync(AuthEndpoints.PasskeyContextOf(http, options), http.RequestAborted);
+        http.Response.Headers.CacheControl = "no-store";
+        return TypedResults.Json(Mappers.ToDto(state), ApiJsonContext.Default.TrustStateDto);
+    }
+
+    private static async Task<IResult> CommitAsync(HttpContext http, SignedStatementDto signed, TrustService trust, BackendOptions options)
+    {
+        PasskeyContext context = AuthEndpoints.PasskeyContextOf(http, options);
+        // 第一次（创世）是整个信任根的起点：除了 passkey 签名，还要凭证窗口，避免只拿到一个密码会话的人抢先立根
+        if ((await trust.StateAsync(context, http.RequestAborted)).Initialized is false && ElevationGate.Require(http, ElevationClass.Credential, consume: true) is { } needed)
+        {
+            return needed;
+        }
+
+        Result<TrustState> result = await trust.CommitAsync(signed, context, http.RequestAborted);
+        if (!result.TryGet(out TrustState? state, out FleetError? error))
+        {
+            return Problems.From(http, error);
+        }
+
+        http.SetDetail($"operator set v{state.Version}");
+        return TypedResults.Json(Mappers.ToDto(state), ApiJsonContext.Default.TrustStateDto, statusCode: StatusCodes.Status201Created);
+    }
+
+    private static async Task<IResult> CreateSignedTokenAsync(HttpContext http, CreateSignedJoinTokenRequest request, JoinTokenService tokens)
+    {
+        Result<JoinTokenInfo> result = await tokens.CreateSignedAsync(request.Grant, request.Note, request.Labels, request.AutoApprove ?? true, http.GetPrincipal().Label, http.RequestAborted);
+        if (!result.TryGet(out JoinTokenInfo? info, out FleetError? error))
+        {
+            return Problems.From(http, error);
+        }
+
+        http.SetDetail($"{JoinTokenService.RoleOf(info.Kind)}: {request.Note}");
+        http.Response.Headers.CacheControl = "no-store";
+        return TypedResults.Json(Mappers.ToDto(info), ApiJsonContext.Default.JoinTokenDto, statusCode: StatusCodes.Status201Created);
+    }
+}

backend/src/MoShiro.Backend.Api/ApiModule.cs

@@ -112,6 +112,7 @@ public static class ApiModule
         TaskEndpoints.Map(guarded);
         DataEndpoints.Map(guarded);
         AuditEndpoints.Map(guarded);
+        TrustEndpoints.Map(guarded);
         SystemEndpoints.Map(guarded);
         BuildEndpoints.Map(guarded);
         LinkEndpoints.Map(guarded);

backend/src/MoShiro.Backend.Api/Common/EndpointConventions.cs

@@ -18,6 +18,11 @@ public static class EndpointConventions
             return Task.CompletedTask;
         });
 
+    /// <summary>
+    /// 这个端点自己要求 passkey 签名（请求里带着断言），比提权窗口更强，所以不再要求窗口：守卫跳过信任类能力的提权检查。
+    /// </summary>
+    public static RouteHandlerBuilder ElevationExempt(this RouteHandlerBuilder builder) => builder.WithMetadata(new ElevationExemptMarker());
+
     /// <summary>匿名可访问的管理端点（登录）：显式声明，对账测试才能区分「忘了声明」。</summary>
     public static RouteHandlerBuilder AllowsAnonymous(this RouteHandlerBuilder builder) =>
         builder.WithMetadata(new CapabilityRequirement(null));

backend/src/MoShiro.Backend.Api/Common/Guards.cs

@@ -60,6 +60,9 @@ public static class PrincipalResolver
 /// </summary>
 public sealed record CapabilityRequirement(string? Capability);
 
+/// <summary>端点自己验 passkey 签名（见 <see cref="EndpointConventions.ElevationExempt"/>）。</summary>
+public sealed record ElevationExemptMarker;
+
 /// <summary>管理层守卫：按端点声明的能力授权；Cookie 会话的非 GET 请求必须带 <c>X-CSRF-Token</c>。</summary>
 public static class CapabilityGuard
 {
@@ -90,7 +93,7 @@ public static class CapabilityGuard
         }
 
         // 信任类的操作（加节点、吊销、改凭证）：登录用户还要有这一种的提权窗口；API key 自己带着能力，不经过这里
-        if (requirement.Capability is { } trusted && Elevation.For(trusted) is { } elevation && ElevationGate.Require(http, elevation, consume: true) is { } needed)
+        if (requirement.Capability is { } trusted && Elevation.For(trusted) is { } elevation && http.GetEndpoint()?.Metadata.GetMetadata<ElevationExemptMarker>() is null && ElevationGate.Require(http, elevation, consume: true) is { } needed)
         {
             return needed;
         }

backend/src/MoShiro.Backend.Api/Common/Mappers.cs

@@ -154,7 +154,9 @@ public static class Mappers
         new(t.Id.Value, t.Scope, t.AgentId?.Value, t.BaseTaskId?.Value, t.Kind, t.Target, t.Params, t.Schedule, t.Enabled, Time(t.UpdatedAtMs));
 
     public static JoinTokenDto ToDto(JoinTokenInfo t) =>
-        new(t.Id, t.Note, t.Labels, t.AutoApprove, t.MaxUses, t.Uses, Time(t.ExpiresAtMs), Time(t.RevokedAtMs), Time(t.CreatedAtMs), JoinTokenService.RoleOf(t.Kind), t.CreatedBy);
+        new(t.Id, t.Note, t.Labels, t.AutoApprove, t.MaxUses, t.Uses, Time(t.ExpiresAtMs), Time(t.RevokedAtMs), Time(t.CreatedAtMs), JoinTokenService.RoleOf(t.Kind), t.CreatedBy, t.Grant is not null);
+
+    public static TrustStateDto ToDto(TrustState s) => new(s.Initialized, s.Genesis, s.Version, s.InSync, s.Proposal is null ? null : new TrustProposalDto(s.Proposal.Statement, s.Proposal.Version, s.Proposal.Challenge));
 
     public static ElevationDto ToDto(ElevationWindow w) => new(Elevation.IdOf(w.Class), Time(w.ExpiresAtMs));
 

backend/src/MoShiro.Backend.Api/Contracts/AdminDtos.cs

@@ -1,3 +1,4 @@
+using Fleet.Core;
 using System.Text.Json;
 
 namespace MoShiro.Backend.Api;
@@ -73,13 +74,23 @@ public sealed record Ipv6DiagnosticDto(bool? AddressConfigured, bool SocketSuppo
 public sealed record AgentPatchRequest(string? Name, IReadOnlyList<string>? Labels, string? PublicHost, bool? PublicVisible, string? Ipv6Host = null, bool? PublicHostAuto = null, bool? Ipv6HostAuto = null);
 
 /// <param name="Role"><c>agent</c> 或 <c>probe</c>：用这个令牌注册出来的是哪种节点。</param>
-public sealed record JoinTokenDto(string Id, string? Note, IReadOnlyList<string> Labels, bool AutoApprove, int MaxUses, int Uses, DateTimeOffset ExpiresAt, DateTimeOffset? RevokedAt, DateTimeOffset CreatedAt, string Role = "agent", string? CreatedBy = null);
+public sealed record JoinTokenDto(string Id, string? Note, IReadOnlyList<string> Labels, bool AutoApprove, int MaxUses, int Uses, DateTimeOffset ExpiresAt, DateTimeOffset? RevokedAt, DateTimeOffset CreatedAt, string Role = "agent", string? CreatedBy = null, bool Signed = false);
 
 public sealed record CreateJoinTokenRequest(string? Note, IReadOnlyList<string>? Labels, bool? AutoApprove, int? MaxUses, int? ExpiresInHours, string? Role = null);
 
 /// <summary>令牌明文只在创建的响应里出现一次。</summary>
 public sealed record InstallCommandsDto(string Linux, string Macos, string Windows);
 
+/// <param name="Grant">操作员用 passkey 对这个码签的委托（语句加断言）。</param>
+public sealed record CreateSignedJoinTokenRequest(SignedStatementDto Grant, string? Note, IReadOnlyList<string>? Labels, bool? AutoApprove);
+
+public sealed record TrustProposalDto(string Statement, int Version, string Challenge);
+
+/// <param name="Genesis">创世版本的指纹：安装命令里固定到节点上的就是它。还没建立信任根时为空。</param>
+/// <param name="InSync">当前生效的集合和已注册的 passkey、域名一致；不一致（比如新加了 passkey）就要签一个新版本。</param>
+/// <param name="Proposal">下一个要签的版本（<c>challenge</c> 就是 WebAuthn 的挑战）。</param>
+public sealed record TrustStateDto(bool Initialized, string? Genesis, int Version, bool InSync, TrustProposalDto? Proposal);
+
 public sealed record CreatedJoinTokenDto(JoinTokenDto Token, string Plaintext, InstallCommandsDto InstallCommands);
 
 /// <summary>Agent 眼中连着的一个 Probe（Agent 上报）。</summary>

backend/src/MoShiro.Backend.Api/Contracts/ApiJsonContext.cs

@@ -79,6 +79,9 @@ namespace MoShiro.Backend.Api;
 [JsonSerializable(typeof(PasskeyRequestOptionsDto))]
 [JsonSerializable(typeof(RegisterPasskeyRequest))]
 [JsonSerializable(typeof(PasskeyLoginRequest))]
+[JsonSerializable(typeof(Fleet.Core.SignedStatementDto), TypeInfoPropertyName = "FleetSignedStatement")]
+[JsonSerializable(typeof(CreateSignedJoinTokenRequest))]
+[JsonSerializable(typeof(TrustStateDto))]
 [JsonSerializable(typeof(ElevationRequest))]
 [JsonSerializable(typeof(ElevationAssertionRequest))]
 [JsonSerializable(typeof(ElevationDto))]