Merge branch 'main' into dev

.gitattributes

@@ -6,3 +6,4 @@ packaging/update/*.sh text eol=lf
 packaging/container/*.sh text eol=lf
 ci/release-node-images.sh text eol=lf
 packaging/install/*.sh text eol=lf
+packaging/install/*.ps1 text eol=lf

README.md

@@ -20,7 +20,7 @@ MoShiro 是一个自托管的**网络线路质量观测工具**。它在若干 P
 ## 信任关系
 
 ```text
- 管理员 ── 账号密码（Cookie 会话 + CSRF）或 API 令牌（read · admin · release）──▶ Backend
+ 管理员 ── 账号密码（Cookie 会话 + CSRF）或 API 令牌（按能力授权）──▶ Backend
  访客   ── 匿名只读，站点设为公开时才可用（没有 IP、城市、ASN）──────────────▶ Backend 公开接口
 
  节点   ── 加入令牌一次性注册，之后用自己的 ECDSA P-256 密钥签名认证 ───────▶ Backend（只存公钥）
@@ -97,7 +97,8 @@ Backend、Agent、Probe 以 OCI 镜像发布（Linux amd64、arm64），Agent
 | 文档 | 内容 |
 | --- | --- |
 | [`docs/architecture.md`](docs/architecture.md) | 架构、数据链路、安全边界、设计决策 |
-| [`docs/security.md`](docs/security.md) | 零信任设计稿（尚未实现）：威胁模型、名册和操作员凭证、监听隐身、extension 授权 |
+| [`docs/security.md`](docs/security.md) | 零信任设计稿（部分已实现）：威胁模型、入网信任链、监听隐身、extension 授权 |
+| [`docs/access.md`](docs/access.md) | 访问控制与入网信任链设计（尚未实现）：账户、角色、能力、API key、提权窗口、passkey 到节点的签名链 |
 | [`docs/protocol.md`](docs/protocol.md)、[`backend/fleet/README.md`](backend/fleet/README.md) | 线协议、Fleet 节点框架（身份、注册、连接） |
 | [`docs/enrollment.md`](docs/enrollment.md) | 注册、身份、Probe 与 Agent 的接入 |
 | [`docs/measurement.md`](docs/measurement.md)、[`docs/analysis.md`](docs/analysis.md) | 采集引擎与任务模型、分析层与指标 |

backend/Directory.Build.props

@@ -13,7 +13,7 @@
     <UseArtifactsOutput>true</UseArtifactsOutput>
     <ArtifactsPath>$(MSBuildThisFileDirectory)artifacts</ArtifactsPath>
     <Deterministic>true</Deterministic>
-    <Version>0.1.1</Version>
+    <Version>0.2.0</Version>
     <NuGetAudit>false</NuGetAudit>
   </PropertyGroup>
   <ItemGroup>

backend/agent/src/MoShiro.Agent/AgentApp.cs

@@ -18,6 +18,7 @@ public sealed class AgentApp : IDisposable
     private readonly AgentConfig _config;
     private readonly bool _ipv6Supported;
     private readonly KnockGate _knock;
+    private readonly TrustAnchor _trust;
     private readonly RestartController _restart;
     private readonly RestartController? _ownedRestart;
     private readonly LoadedNodeIdentity _identity;
@@ -63,6 +64,7 @@ public sealed class AgentApp : IDisposable
         _admission = new AgentAdmission(_streams);
         _udp = new UdpMux(_sessions, _admission, _clock, _counters.Data, log, bind, config.Listen.UdpPorts);
         // 预握手敲门：控制端口和数据端口共用一个关卡（限速和去重一起算）；名册就是期望状态里的 peers
+        _trust = TrustAnchor.Load(config.Fleet.IdentityDir, log);
         _knock = new KnockGate(identity.PeerIdentity, RosterKeys, time);
         _tcp = new TcpAcceptor(bind, config.Listen.TcpPorts, identity.Certificate, _sessions, _counters.Data, _knock);
 
@@ -81,7 +83,7 @@ public sealed class AgentApp : IDisposable
         };
         var chunks = new ChunkAssembler(_streams, _clock, _counters, _outbox, identity.NodeId, time, log);
         var targets = new TargetRunners(chunks, identity.NodeId, _clock, time, log);
-        _tasks = new TaskManager(CreateGuard, _streams, env, targets, () => _udp.BoundPorts, () => _tcp.BoundPorts);
+        _tasks = new TaskManager(CreateGuard, _streams, env, targets, () => _udp.BoundPorts, () => _tcp.BoundPorts, _trust);
         _hub = new PeerHub(_sessions, _clock, chunks, _tasks, _uplink, time, log);
         _tests = new TestRunner(_tasks, _sessions, _streams, env, _uplink, config.Limits.MaxConcurrentTests, transport => transport == "udp" ? _udp.BoundPorts : _tcp.BoundPorts, time, log);
 
@@ -123,6 +125,9 @@ public sealed class AgentApp : IDisposable
 
     public int ControlPort => _peers.Port;
 
+    /// <summary>节点当前采用的操作员集合版本（没有固定信任根时是 0）。</summary>
+    public int TrustVersion => _trust.Version;
+
     public AgentCounters Counters => _counters;
 
     public FleetLink Link => _link;
@@ -270,6 +275,7 @@ public sealed class AgentApp : IDisposable
         {
             Server = new Uri(_config.Fleet.Server),
             Identity = _identity.Identity,
+            ServerVerifier = _trust,
             NodeId = _identity.NodeId,
             NodeVersion = Version,
             Capabilities = [MoShiroCapabilities.Base, MoShiroCapabilities.KindsPrefix + string.Join(',', BlockCatalog.AgentKinds)],

backend/agent/src/MoShiro.Agent/Tasks/TaskManager.cs

@@ -1,4 +1,5 @@
 using System.Text.Json;
+using Fleet.Hosting;
 using Fleet.Core;
 using Fleet.Rpc;
 using MoShiro.Measurement;
@@ -25,14 +26,16 @@ public sealed class TaskManager
     private readonly TargetRunners _targets;
     private readonly Func<IReadOnlyList<int>> _udpPorts;
     private readonly Func<IReadOnlyList<int>> _tcpPorts;
+    private readonly TrustAnchor _trust;
     private readonly Dictionary<ProbeSession, Dictionary<string, LineEntry>> _sessionLines = [];
     private volatile Dictionary<string, byte[]> _peers = new(StringComparer.Ordinal);
     private Dictionary<string, (TaskSpec Task, TaskDecision Decision)> _lineSpecs = [];
     private long _version;
     private BudgetGuard? _guard;
 
-    public TaskManager(Func<BudgetGuard> guardFactory, StreamRegistry streams, BlockEnv env, TargetRunners targets, Func<IReadOnlyList<int>> udpPorts, Func<IReadOnlyList<int>> tcpPorts)
+    public TaskManager(Func<BudgetGuard> guardFactory, StreamRegistry streams, BlockEnv env, TargetRunners targets, Func<IReadOnlyList<int>> udpPorts, Func<IReadOnlyList<int>> tcpPorts, TrustAnchor? trust = null)
     {
+        _trust = trust ?? TrustAnchor.None;
         _guardFactory = guardFactory;
         _streams = streams;
         _env = env;
@@ -98,6 +101,8 @@ public sealed class TaskManager
         _ = ct;
         var result = new StateSyncResult { AppliedVersion = version };
 
+        // 固定了操作员创世的节点：面板带来的新版本操作员集合，从固定的创世验过才采用（名册本身由面板决定）
+        _trust.Update(set.TrustChain);
         var peers = new Dictionary<string, byte[]>(StringComparer.Ordinal);
         foreach (PeerSpec peer in set.Peers)
         {

backend/fleet/src/Fleet.Core/TrustDtos.cs

@@ -0,0 +1,29 @@
+using System.Text.Json.Serialization;
+
+namespace Fleet.Core;
+
+/// <summary>passkey 对一段语句签出的断言（字段都是 base64url）。信任根的格式和验证在 Fleet.Identity 的 <c>OperatorTrust</c>。</summary>
+public sealed class SignedStatementDto
+{
+    [JsonPropertyName("statement")]
+    public string Statement { get; set; } = "";
+
+    [JsonPropertyName("credential_id")]
+    public string CredentialId { get; set; } = "";
+
+    [JsonPropertyName("authenticator_data")]
+    public string AuthenticatorData { get; set; } = "";
+
+    [JsonPropertyName("client_data_json")]
+    public string ClientDataJson { get; set; } = "";
+
+    [JsonPropertyName("signature")]
+    public string Signature { get; set; } = "";
+}
+
+/// <summary>操作员集合的链（创世在前）：节点注册时取来，从固定的创世指纹验过才采用。</summary>
+public sealed class TrustBundle
+{
+    [JsonPropertyName("chain")]
+    public List<SignedStatementDto> Chain { get; set; } = [];
+}

backend/fleet/src/Fleet.Enrollment.Client/EnrollmentClient.cs

@@ -2,13 +2,17 @@ using System.Security.Cryptography;
 using System.Text;
 using System.Text.Json;
 using System.Text.Json.Nodes;
+using System.Text.Json.Serialization;
 using Fleet.Core;
 using Fleet.Hosting;
 using Fleet.Identity;
 
 namespace Fleet.Enrollment.Client;
 
-public sealed record EnrollmentResult(string NodeId, string Status, string IdentityDirectory);
+[JsonSerializable(typeof(TrustBundle))]
+internal sealed partial class TrustBundleContext : JsonSerializerContext;
+
+public sealed record EnrollmentResult(string NodeId, string Status, string IdentityDirectory, bool Pinned = false);
 
 /// <summary>
 /// 用加入令牌注册（供 <c>fleet-enroll</c> 使用，也可以嵌入产品自己的安装工具）：
@@ -18,7 +22,8 @@ public sealed record EnrollmentResult(string NodeId, string Status, string Ident
 public static class EnrollmentClient
 {
     public static async Task<Result<EnrollmentResult>> EnrollAsync(
-        HttpClient http, Uri server, string joinToken, string name, string identityDirectory, string nodeVersion, JsonNode? productMeta, TimeProvider time, CancellationToken ct)
+        HttpClient http, Uri server, string joinToken, string name, string identityDirectory, string nodeVersion, JsonNode? productMeta, TimeProvider time, CancellationToken ct,
+        string? genesis = null, IReadOnlyList<string>? controllers = null)
     {
         string nodeFile = Path.Combine(identityDirectory, LoadedNodeIdentity.NodeFileName);
         if (File.Exists(nodeFile))
@@ -36,6 +41,18 @@ public static class EnrollmentClient
             tlsPublicKey = certificate.PublicKey.ExportSubjectPublicKeyInfo();
         }
 
+        // 安装命令里带了创世指纹（--genesis）和属主（--controllers）：先取操作员集合链，从固定的创世验起，
+        // 属主必须是集合里的凭证；对不上就不注册，也不把自己的密钥交出去。通过之后固定到本地 trust.json，Backend 之后改不了。
+        TrustBundle? bundle = null;
+        if (genesis is not null)
+        {
+            Result<TrustBundle> trusted = await FetchTrustAsync(http, server, joinToken, genesis, controllers ?? [], ct);
+            if (!trusted.TryGet(out bundle, out FleetError? trustError))
+            {
+                return Result<EnrollmentResult>.Fail(trustError);
+            }
+        }
+
         string pubkey = Convert.ToBase64String(identity.PublicKeySpki);
         string tokenHash = Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(joinToken)));
         var body = new JsonObject
@@ -76,10 +93,46 @@ public static class EnrollmentClient
         var store = new ConfigStore(identityDirectory);
         store.Write(LoadedNodeIdentity.KeyFileName, identity.ExportPkcs8());
         store.Write(LoadedNodeIdentity.TlsFileName, pfx);
+        if (bundle is not null)
+        {
+            TrustAnchor.Pin(identityDirectory, genesis!, bundle.Chain, controllers ?? []);
+        }
+
         // node.json 最后写：它存在就表示注册完整完成
         store.Write(
             LoadedNodeIdentity.NodeFileName,
             JsonSerializer.SerializeToUtf8Bytes(new NodeFile { NodeId = nodeId, Server = server.ToString().TrimEnd('/'), TlsSpki = Convert.ToBase64String(spki) }, NodeFileContext.Default.NodeFile));
-        return Result<EnrollmentResult>.Ok(new EnrollmentResult(nodeId, result["status"]!.GetValue<string>(), identityDirectory));
+        return Result<EnrollmentResult>.Ok(new EnrollmentResult(nodeId, result["status"]!.GetValue<string>(), identityDirectory, bundle is not null));
+    }
+
+    private static async Task<Result<TrustBundle>> FetchTrustAsync(HttpClient http, Uri server, string joinToken, string genesis, IReadOnlyList<string> controllers, CancellationToken ct)
+    {
+        static Result<TrustBundle> Refuse(string reason) => Result<TrustBundle>.Fail(FleetErrors.ProofInvalid, "refusing to enroll: " + reason);
+
+        using var request = new StringContent(new JsonObject { ["join_token"] = joinToken }.ToJsonString(), Encoding.UTF8, "application/json");
+        using HttpResponseMessage response = await http.PostAsync(new Uri(server, "/api/agent/v1/enroll/trust"), request, ct);
+        if (!response.IsSuccessStatusCode)
+        {
+            return Result<TrustBundle>.Fail(FleetErrors.JoinTokenInvalid, $"{(int)response.StatusCode}: the panel would not give the trust chain");
+        }
+
+        TrustBundle? bundle = JsonSerializer.Deserialize(await response.Content.ReadAsStringAsync(ct), TrustBundleContext.Default.TrustBundle);
+        if (bundle is null || bundle.Chain.Count == 0)
+        {
+            return Refuse("the panel has no operator trust root set up");
+        }
+
+        OperatorSet? current = OperatorTrust.VerifyChain(genesis, [.. bundle.Chain.Select(c => c.ToSigned())]);
+        if (current is null)
+        {
+            return Refuse("the panel's operator set does not match the pinned genesis fingerprint (wrong panel, or the panel was tampered with)");
+        }
+
+        if (controllers.Any(c => current.Keys.All(k => k.CredentialId != c)))
+        {
+            return Refuse("an owner passkey in the install command is not in the operator set");
+        }
+
+        return Result<TrustBundle>.Ok(bundle);
     }
 }

backend/fleet/src/Fleet.Hosting/TrustAnchor.cs

@@ -0,0 +1,170 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Fleet.Core;
+using Fleet.Identity;
+
+namespace Fleet.Hosting;
+
+/// <summary><c>trust.json</c>：安装时固定的创世指纹和属主，加见过的最新操作员集合链。</summary>
+public sealed class TrustFile
+{
+    [JsonPropertyName("genesis")]
+    public string Genesis { get; set; } = "";
+
+    [JsonPropertyName("chain")]
+    public List<SignedStatementDto> Chain { get; set; } = [];
+
+    /// <summary>属主：允许授权本节点 extension 会话（web ssh 等）的 passkey 凭证 id，安装时固定，必须是操作员集合里的凭证。</summary>
+    [JsonPropertyName("controllers")]
+    public List<string> Controllers { get; set; } = [];
+}
+
+[JsonSerializable(typeof(TrustFile))]
+public sealed partial class TrustFileContext : JsonSerializerContext;
+
+/// <summary>
+/// 节点的信任根：安装命令里带来的创世指纹和属主，在注册时固定到本地，之后 Backend 改不了。
+/// 操作员集合的新版本随期望状态下发，节点只接受从固定的创世出发、签名完整、版本更新的链。
+/// 属主只是被固定和保存：节点现在没有 extension，等做 extension 时由节点本地强制（见 docs/access.md 第 8 节）。
+/// </summary>
+public sealed class TrustAnchor : IServerVerifier
+{
+    public const string FileName = "trust.json";
+
+    private readonly ConfigStore? _store;
+    private readonly INodeLog _log;
+    private readonly object _gate = new();
+    private readonly TrustFile? _file;
+    private OperatorSet? _current;
+
+    private TrustAnchor(ConfigStore? store, TrustFile? file, OperatorSet? current, INodeLog log)
+    {
+        _store = store;
+        _file = file;
+        _current = current;
+        _log = log;
+    }
+
+    /// <summary>没有固定的创世（旧节点，或没有指纹的安装）。</summary>
+    public static TrustAnchor None { get; } = new(null, null, null, NullNodeLog.Instance);
+
+    public bool Pinned => _file is not null;
+
+    public string? Genesis => _file?.Genesis;
+
+    /// <summary>当前生效的操作员集合版本；没有固定时为 0。</summary>
+    public int Version
+    {
+        get
+        {
+            lock (_gate)
+            {
+                return _current?.Version ?? 0;
+            }
+        }
+    }
+
+    /// <summary>当前操作员集合里登记了服务器密钥：服务器必须在认证挑战里证明自己，链路用应用层加密。</summary>
+    public bool Required
+    {
+        get
+        {
+            lock (_gate)
+            {
+                return _current?.Servers is { Count: > 0 };
+            }
+        }
+    }
+
+    /// <summary>服务器的签名是不是当前操作员集合里登记的某把服务器密钥签的。</summary>
+    public bool Verify(string nonce, ReadOnlySpan<byte> serverEphemeralSpki, ReadOnlySpan<byte> signature)
+    {
+        IReadOnlyList<byte[]> servers;
+        lock (_gate)
+        {
+            servers = _current?.Servers ?? [];
+        }
+
+        foreach (byte[] server in servers)
+        {
+            if (ServerHello.Verify(server, nonce, serverEphemeralSpki, signature))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /// <summary>安装时固定的属主里，仍然在当前操作员集合里的那些（从集合里去掉的凭证不再有效）。</summary>
+    public IReadOnlyList<string> Controllers
+    {
+        get
+        {
+            lock (_gate)
+            {
+                return _file is null || _current is null ? [] : [.. _file.Controllers.Where(c => _current.Keys.Any(k => k.CredentialId == c))];
+            }
+        }
+    }
+
+    public static TrustAnchor Load(string identityDirectory, INodeLog log)
+    {
+        string path = Path.Combine(identityDirectory, FileName);
+        if (!File.Exists(path))
+        {
+            return new TrustAnchor(new ConfigStore(identityDirectory), null, null, log);
+        }
+
+        TrustFile file = NodeConfig.Load(path, TrustFileContext.Default.TrustFile);
+        OperatorSet? current = OperatorTrust.VerifyChain(file.Genesis, [.. file.Chain.Select(c => c.ToSigned())]);
+        if (current is null)
+        {
+            // 固定的创世和存下来的链对不上：不能当成「没有固定」放过，直接让节点起不来比悄悄失去保护好
+            throw new InvalidDataException($"{path} does not verify against its pinned genesis; remove the node's identity and enroll again");
+        }
+
+        return new TrustAnchor(new ConfigStore(identityDirectory), file, current, log);
+    }
+
+    /// <summary>注册时写下：固定的创世、验证过的链、属主。</summary>
+    public static void Pin(string identityDirectory, string genesis, IReadOnlyList<SignedStatementDto> chain, IReadOnlyList<string> controllers) =>
+        new ConfigStore(identityDirectory).Write(FileName, JsonSerializer.SerializeToUtf8Bytes(new TrustFile { Genesis = genesis, Chain = [.. chain], Controllers = [.. controllers] }, TrustFileContext.Default.TrustFile));
+
+    /// <summary>期望状态里带来的链：从固定的创世验起，比现有的新才采用并保存。返回当前链的版本（没有固定时为 0）。</summary>
+    public int Update(IReadOnlyList<SignedStatementDto>? chain)
+    {
+        lock (_gate)
+        {
+            if (_file is null || chain is not { Count: > 0 })
+            {
+                return _current?.Version ?? 0;
+            }
+
+            OperatorSet? candidate = OperatorTrust.VerifyChain(_file.Genesis, [.. chain.Select(c => c.ToSigned())]);
+            if (candidate is null)
+            {
+                _log.Warn("the operator set from the panel does not verify against the pinned genesis; ignoring it");
+                return _current!.Version;
+            }
+
+            if (candidate.Version > _current!.Version)
+            {
+                _file.Chain = [.. chain];
+                _current = candidate;
+                try
+                {
+                    _store?.Write(FileName, JsonSerializer.SerializeToUtf8Bytes(_file, TrustFileContext.Default.TrustFile));
+                }
+                catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+                {
+                    _log.Warn("could not save trust.json", ("err", ex.Message));
+                }
+
+                _log.Info("operator set updated", ("version", candidate.Version));
+            }
+
+            return _current.Version;
+        }
+    }
+}

backend/fleet/src/Fleet.Identity/NodeIdentity.cs

@@ -7,6 +7,9 @@ namespace Fleet.Identity;
 public static class SignaturePurpose
 {
     public const string Auth = "auth";
+
+    /// <summary>安全链路的认证：签名同时覆盖服务器和节点的临时公钥，把这次认证和这条加密链路绑在一起。</summary>
+    public const string AuthSecure = "auth2";
     public const string Peer = "peer";
     public const string Enroll = "enroll";
 }

backend/fleet/src/Fleet.Identity/OperatorTrust.cs

@@ -0,0 +1,171 @@
+using System.Buffers.Text;
+using System.Globalization;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace Fleet.Identity;
+
+/// <summary>passkey（WebAuthn）对一段文本签出的断言：<c>challenge = SHA-256(Statement 的 UTF-8)</c>。四个字段都是 base64url。</summary>
+public sealed record SignedStatement(string Statement, string CredentialId, string AuthenticatorData, string ClientDataJson, string Signature);
+
+/// <summary>一个操作员凭证：passkey 的凭证 id 和公钥（SPKI）。</summary>
+public sealed record OperatorKey(string CredentialId, byte[] PublicKeySpki);
+
+/// <summary>
+/// 操作员集合的一个版本。<c>RpId</c> 和 <c>Origins</c> 也在里面：节点验 WebAuthn 断言要用，而它们被操作员的签名覆盖，Backend 改不了。
+/// 创世版本（1）由它自己的某把凭证签名，指纹（<see cref="OperatorTrust.Fingerprint"/>）在安装时固定到节点；之后每个版本由上一版里的凭证签名。
+/// </summary>
+/// <param name="Servers">服务器密钥（SPKI）：操作员授权的 Backend 签名密钥。集合里登记了服务器密钥之后，节点要求服务器在认证挑战里用它签名，
+/// 并在这条链路上用应用层加密，所以 DNS 或证书层面的冒充拿不出这把密钥就骗不了节点。空 = 还没有启用。</param>
+public sealed record OperatorSet(int Version, string Previous, string RpId, IReadOnlyList<string> Origins, IReadOnlyList<OperatorKey> Keys, IReadOnlyList<byte[]>? Servers = null);
+
+/// <summary>
+/// 信任根：操作员（passkey）→ 操作员集合 → 节点本地固定的属主。设计见 docs/access.md 第 7 节。
+/// 安装命令里带着创世指纹和属主（passkey 的凭证 id）：节点把它们固定在本地，之后只认从创世出发、由操作员 passkey 签过名的集合版本，
+/// 属主必须是集合里的凭证。Backend 能转发集合，但签不出新的版本，也改不了节点已经固定的东西。
+/// 全是纯函数，只用 BCL，节点和 Backend 共用。语句是 <c>key=value</c> 的文本，第一行是带版本的标题；签名覆盖整段文本。
+/// </summary>
+public static class OperatorTrust
+{
+    public const string SetHeader = "moshiro-opset-v1";
+    public const string Genesis = "0";
+
+    public static string Encode(OperatorSet set)
+    {
+        var text = new StringBuilder();
+        text.Append(SetHeader).Append('\n')
+            .Append("version=").Append(set.Version.ToString(CultureInfo.InvariantCulture)).Append('\n')
+            .Append("prev=").Append(set.Previous).Append('\n')
+            .Append("rp=").Append(set.RpId).Append('\n')
+            .Append("origins=").Append(string.Join(',', set.Origins));
+        foreach (OperatorKey key in set.Keys)
+        {
+            text.Append("\nkey=").Append(key.CredentialId).Append(':').Append(Convert.ToBase64String(key.PublicKeySpki));
+        }
+
+        foreach (byte[] server in set.Servers ?? [])
+        {
+            text.Append("\nserver=").Append(Convert.ToBase64String(server));
+        }
+
+        return text.ToString();
+    }
+
+    /// <summary>严格解析：多一行、少一行、顺序不对都算坏。</summary>
+    public static OperatorSet? ParseSet(string text)
+    {
+        string[] lines = text.Split('\n');
+        if (lines.Length < 6 || lines[0] != SetHeader || !TryValue(lines[1], "version", out string version) || !int.TryParse(version, NumberStyles.None, CultureInfo.InvariantCulture, out int number) || number < 1
+            || !TryValue(lines[2], "prev", out string previous) || !TryValue(lines[3], "rp", out string rp) || rp.Length == 0 || !TryValue(lines[4], "origins", out string origins) || origins.Length == 0)
+        {
+            return null;
+        }
+
+        var keys = new List<OperatorKey>();
+        var servers = new List<byte[]>();
+        foreach (string line in lines.Skip(5))
+        {
+            if (servers.Count == 0 && TryValue(line, "key", out string value) && value.IndexOf(':', StringComparison.Ordinal) is > 0 and int split && TryBase64(value[(split + 1)..], out byte[] spki))
+            {
+                keys.Add(new OperatorKey(value[..split], spki));
+            }
+            else if (TryValue(line, "server", out string serverText) && TryBase64(serverText, out byte[] serverKey))
+            {
+                servers.Add(serverKey);
+            }
+            else
+            {
+                return null;
+            }
+        }
+
+        return keys.Count == 0 || (number == 1) != (previous == Genesis) ? null : new OperatorSet(number, previous, rp, origins.Split(','), keys, servers);
+    }
+
+    /// <summary>一段语句的指纹（SHA-256，小写十六进制）。创世版本的指纹就是安装命令里固定的那个。</summary>
+    public static string Fingerprint(string statement) => Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(statement)));
+
+    /// <summary>
+    /// 验证操作员集合的链：第一项是创世版本（指纹等于 <paramref name="pinnedGenesis"/>，自签），其后每一项由上一版里的凭证签名、版本加一、<c>prev</c> 指向上一版的指纹、域名不变。
+    /// 返回最后一版；不对返回 null。
+    /// </summary>
+    public static OperatorSet? VerifyChain(string pinnedGenesis, IReadOnlyList<SignedStatement> chain)
+    {
+        if (chain.Count == 0 || !string.Equals(Fingerprint(chain[0].Statement), pinnedGenesis, StringComparison.OrdinalIgnoreCase))
+        {
+            return null;
+        }
+
+        OperatorSet? current = null;
+        string? previousFingerprint = null;
+        foreach (SignedStatement link in chain)
+        {
+            OperatorSet? next = ParseSet(link.Statement);
+            if (next is null)
+            {
+                return null;
+            }
+
+            if (current is null)
+            {
+                if (next.Version != 1 || !VerifyOperator(link, next))
+                {
+                    return null;
+                }
+            }
+            else if (next.Version != current.Version + 1 || next.Previous != previousFingerprint || next.RpId != current.RpId || !VerifyOperator(link, current))
+            {
+                return null;
+            }
+
+            current = next;
+            previousFingerprint = Fingerprint(link.Statement);
+        }
+
+        return current;
+    }
+
+    /// <summary>断言是不是这个集合里某把凭证对 <c>Statement</c> 签的（要求用户验证；挑战是语句的 SHA-256）。</summary>
+    public static bool VerifyOperator(SignedStatement signed, OperatorSet set)
+    {
+        OperatorKey? key = set.Keys.FirstOrDefault(k => k.CredentialId == signed.CredentialId);
+        if (key is null || !TryDecode(signed.AuthenticatorData, out byte[] authData) || !TryDecode(signed.ClientDataJson, out byte[] clientData) || !TryDecode(signed.Signature, out byte[] signature))
+        {
+            return false;
+        }
+
+        return WebAuthnAssertion.Verify(key.PublicKeySpki, authData, clientData, signature, set.RpId, SHA256.HashData(Encoding.UTF8.GetBytes(signed.Statement)), set.Origins.Contains, requireUserVerification: true, out _);
+    }
+
+    private static bool TryValue(string line, string key, out string value)
+    {
+        value = "";
+        if (!line.StartsWith(key + "=", StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        value = line[(key.Length + 1)..];
+        return true;
+    }
+
+    private static bool TryBase64(string text, out byte[] data)
+    {
+        try
+        {
+            data = Convert.FromBase64String(text);
+            return data.Length > 0;
+        }
+        catch (FormatException)
+        {
+            data = [];
+            return false;
+        }
+    }
+
+    private static bool TryDecode(string text, out byte[] data)
+    {
+        data = [];
+        return Base64Url.IsValid(text) && (data = Base64Url.DecodeFromChars(text)).Length > 0;
+    }
+}

backend/fleet/src/Fleet.Identity/SecureChannel.cs

@@ -0,0 +1,173 @@
+using System.Buffers.Binary;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace Fleet.Identity;
+
+/// <summary>
+/// 节点这一侧用来确认「对面确实是我的操作员授权过的 Backend」的校验器：<c>Required</c> 为真（当前操作员集合里登记了服务器密钥）
+/// 时，服务器的挑战必须带着对得上的签名，否则节点不继续认证、也不交出任何东西。
+/// </summary>
+public interface IServerVerifier
+{
+    bool Required { get; }
+
+    /// <summary>服务器用它的服务器密钥对「挑战随机数加它这次连接的临时公钥」的签名。</summary>
+    bool Verify(string nonce, ReadOnlySpan<byte> serverEphemeralSpki, ReadOnlySpan<byte> signature);
+}
+
+/// <summary>服务器在挑战里给出的身份证明：服务器密钥（操作员签进集合）对「随机数加临时公钥」签名。纯函数。</summary>
+public static class ServerHello
+{
+    /// <summary>被签名的内容；服务器那一侧只拿到这个、用自己的密钥签（服务器密钥不一定是 BCL 的 ECDsa，可以在别处）。</summary>
+    public static byte[] Payload(string nonce, ReadOnlySpan<byte> serverEphemeralSpki) =>
+        Encoding.UTF8.GetBytes("fleet|v1|server|" + nonce + "|" + Convert.ToBase64String(serverEphemeralSpki));
+
+    public static byte[] Sign(ECDsa serverKey, string nonce, ReadOnlySpan<byte> serverEphemeralSpki) =>
+        serverKey.SignData(Payload(nonce, serverEphemeralSpki), HashAlgorithmName.SHA256, DSASignatureFormat.IeeeP1363FixedFieldConcatenation);
+
+    public static bool Verify(ReadOnlySpan<byte> serverKeySpki, string nonce, ReadOnlySpan<byte> serverEphemeralSpki, ReadOnlySpan<byte> signature)
+    {
+        try
+        {
+            using ECDsa key = ECDsa.Create();
+            key.ImportSubjectPublicKeyInfo(serverKeySpki, out _);
+            return key.VerifyData(Payload(nonce, serverEphemeralSpki), signature, HashAlgorithmName.SHA256, DSASignatureFormat.IeeeP1363FixedFieldConcatenation);
+        }
+        catch (CryptographicException)
+        {
+            return false;
+        }
+    }
+}
+
+/// <summary>
+/// 节点和 Backend 之间控制链路的应用层加密：两边的临时 ECDH 密钥协商出会话密钥，每个方向一把，AES-256-GCM，每帧带计数器。
+/// 所以即使 TLS 在中间被终止（Cloudflare、被冒充的证书），中间人没有服务器密钥，就拿不到明文，也改不了任何一帧。
+/// 帧格式：<c>计数器(8，大端) ‖ 密文 ‖ 标签(16)</c>；明文是 <c>帧类型(1) ‖ 内容</c>；计数器必须严格递增，重放、乱序、丢帧、篡改都会解密失败。
+/// </summary>
+public sealed class LinkCipher : IDisposable
+{
+    public const int Overhead = 8 + 16;
+
+    private const byte NodeToServer = 0;
+    private const byte ServerToNode = 1;
+
+    private readonly AesGcm _send;
+    private readonly AesGcm _receive;
+    private readonly byte _sendDirection;
+    private readonly byte _receiveDirection;
+    private readonly object _gate = new();
+    private long _sendCounter;
+    private long _receiveCounter;
+
+    private LinkCipher(byte[] sendKey, byte[] receiveKey, byte sendDirection, byte receiveDirection)
+    {
+        _send = new AesGcm(sendKey, 16);
+        _receive = new AesGcm(receiveKey, 16);
+        _sendDirection = sendDirection;
+        _receiveDirection = receiveDirection;
+    }
+
+    public static LinkCipher ForNode(EphemeralKey own, ReadOnlySpan<byte> serverEphemeralSpki, string nonce)
+    {
+        (byte[] n2s, byte[] s2n) = Derive(own, serverEphemeralSpki, own.PublicKeySpki, serverEphemeralSpki, nonce);
+        return new LinkCipher(n2s, s2n, NodeToServer, ServerToNode);
+    }
+
+    public static LinkCipher ForServer(EphemeralKey own, ReadOnlySpan<byte> nodeEphemeralSpki, string nonce)
+    {
+        (byte[] n2s, byte[] s2n) = Derive(own, nodeEphemeralSpki, nodeEphemeralSpki, own.PublicKeySpki, nonce);
+        return new LinkCipher(s2n, n2s, ServerToNode, NodeToServer);
+    }
+
+    private static (byte[] NodeToServerKey, byte[] ServerToNodeKey) Derive(EphemeralKey own, ReadOnlySpan<byte> remote, ReadOnlySpan<byte> nodeEphemeral, ReadOnlySpan<byte> serverEphemeral, string nonce)
+    {
+        byte[] secret = own.AgreeRaw(remote);
+        try
+        {
+            byte[] info = [.. Encoding.UTF8.GetBytes("fleet|v1|link|"), .. SHA256.HashData(serverEphemeral), .. SHA256.HashData(nodeEphemeral)];
+            byte[] material = HKDF.DeriveKey(HashAlgorithmName.SHA256, secret, 64, Encoding.UTF8.GetBytes(nonce), info);
+            return (material[..32], material[32..]);
+        }
+        finally
+        {
+            CryptographicOperations.ZeroMemory(secret);
+        }
+    }
+
+    /// <summary>加密一帧。</summary>
+    public byte[] Seal(byte kind, ReadOnlySpan<byte> data)
+    {
+        long counter;
+        lock (_gate)
+        {
+            counter = _sendCounter++;
+        }
+
+        byte[] output = new byte[Overhead + 1 + data.Length];
+        BinaryPrimitives.WriteInt64BigEndian(output, counter);
+        byte[] plaintext = new byte[1 + data.Length];
+        plaintext[0] = kind;
+        data.CopyTo(plaintext.AsSpan(1));
+        _send.Encrypt(Nonce(counter), plaintext, output.AsSpan(8, plaintext.Length), output.AsSpan(8 + plaintext.Length, 16), Aad(_sendDirection, counter));
+        return output;
+    }
+
+    /// <summary>解密一帧；计数器不是期望的下一个、或者标签不对，都返回 false。</summary>
+    public bool TryOpen(ReadOnlySpan<byte> frame, out byte kind, out byte[] data)
+    {
+        kind = 0;
+        data = [];
+        if (frame.Length < Overhead + 1)
+        {
+            return false;
+        }
+
+        long counter = BinaryPrimitives.ReadInt64BigEndian(frame);
+        lock (_gate)
+        {
+            if (counter != _receiveCounter)
+            {
+                return false;
+            }
+
+            int length = frame.Length - Overhead;
+            byte[] plaintext = new byte[length];
+            try
+            {
+                _receive.Decrypt(Nonce(counter), frame.Slice(8, length), frame.Slice(8 + length, 16), plaintext, Aad(_receiveDirection, counter));
+            }
+            catch (CryptographicException)
+            {
+                return false;
+            }
+
+            _receiveCounter++;
+            kind = plaintext[0];
+            data = plaintext[1..];
+            return true;
+        }
+    }
+
+    private static byte[] Nonce(long counter)
+    {
+        byte[] nonce = new byte[12];
+        BinaryPrimitives.WriteInt64BigEndian(nonce.AsSpan(4), counter);
+        return nonce;
+    }
+
+    private static byte[] Aad(byte direction, long counter)
+    {
+        byte[] aad = new byte[9];
+        aad[0] = direction;
+        BinaryPrimitives.WriteInt64BigEndian(aad.AsSpan(1), counter);
+        return aad;
+    }
+
+    public void Dispose()
+    {
+        _send.Dispose();
+        _receive.Dispose();
+    }
+}

backend/fleet/src/Fleet.Identity/SessionKeys.cs

@@ -16,6 +16,14 @@ public sealed class EphemeralKey : IDisposable
 
     public byte[] PublicKeySpki => _key.ExportSubjectPublicKeyInfo();
 
+    /// <summary>与对端的临时公钥做 ECDH，返回原始共享秘密；必须再经 KDF 才能当密钥用。</summary>
+    public byte[] AgreeRaw(ReadOnlySpan<byte> remotePublicKeySpki)
+    {
+        using ECDiffieHellman remote = ECDiffieHellman.Create();
+        remote.ImportSubjectPublicKeyInfo(remotePublicKeySpki, out _);
+        return _key.DeriveRawSecretAgreement(remote.PublicKey);
+    }
+
     /// <summary>
     /// 与对端的临时公钥协商，再经 HKDF-SHA256 派生会话凭据。
     /// 盐是服务端的随机数，info 绑定双方的临时公钥，防止凭据被挪用到别的握手上。

backend/fleet/src/Fleet.Identity/TrustMapping.cs

@@ -0,0 +1,11 @@
+using Fleet.Core;
+
+namespace Fleet.Identity;
+
+public static class TrustMapping
+{
+    public static SignedStatement ToSigned(this SignedStatementDto dto) => new(dto.Statement, dto.CredentialId, dto.AuthenticatorData, dto.ClientDataJson, dto.Signature);
+
+    public static SignedStatementDto ToDto(this SignedStatement signed) =>
+        new() { Statement = signed.Statement, CredentialId = signed.CredentialId, AuthenticatorData = signed.AuthenticatorData, ClientDataJson = signed.ClientDataJson, Signature = signed.Signature };
+}

backend/fleet/src/Fleet.Identity/WebAuthnAssertion.cs

@@ -0,0 +1,85 @@
+using System.Buffers.Text;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+namespace Fleet.Identity;
+
+/// <summary>
+/// 验证一次 WebAuthn 断言（<c>navigator.credentials.get</c> 的结果）。只支持 ES256（P-256 的 ECDSA），纯函数，只用 BCL：
+/// 面板用它验证 passkey 登录，节点以后用它验证 passkey 签出的委托（docs/access.md 第 7 节）。
+/// 不解析 CBOR——注册时的 attestation 解析只在 Backend 里。
+/// </summary>
+public static class WebAuthnAssertion
+{
+    public const byte FlagUserPresent = 0x01;
+    public const byte FlagUserVerified = 0x04;
+
+    /// <param name="publicKeySpki">注册时保存的凭证公钥（SPKI）。</param>
+    /// <param name="expectedChallenge">这次请求里服务端或签名人规定的挑战原文（不是 base64url）。</param>
+    /// <param name="originAllowed">校验 <c>clientDataJSON.origin</c>。</param>
+    /// <param name="signCount">authenticatorData 里的签名计数器。</param>
+    public static bool Verify(
+        ReadOnlySpan<byte> publicKeySpki, ReadOnlySpan<byte> authenticatorData, ReadOnlySpan<byte> clientDataJson, ReadOnlySpan<byte> signature,
+        string rpId, ReadOnlySpan<byte> expectedChallenge, Func<string, bool> originAllowed, bool requireUserVerification, out uint signCount)
+    {
+        signCount = 0;
+        if (authenticatorData.Length < 37 || !CryptographicOperations.FixedTimeEquals(authenticatorData[..32], SHA256.HashData(Encoding.UTF8.GetBytes(rpId))))
+        {
+            return false;
+        }
+
+        byte flags = authenticatorData[32];
+        if ((flags & FlagUserPresent) == 0 || (requireUserVerification && (flags & FlagUserVerified) == 0))
+        {
+            return false;
+        }
+
+        if (!ClientDataValid(clientDataJson, "webauthn.get", expectedChallenge, originAllowed))
+        {
+            return false;
+        }
+
+        try
+        {
+            using ECDsa key = ECDsa.Create();
+            key.ImportSubjectPublicKeyInfo(publicKeySpki, out _);
+            byte[] signed = [.. authenticatorData, .. SHA256.HashData(clientDataJson)];
+            if (!key.VerifyData(signed, signature, HashAlgorithmName.SHA256, DSASignatureFormat.Rfc3279DerSequence))
+            {
+                return false;
+            }
+        }
+        catch (CryptographicException)
+        {
+            return false;
+        }
+
+        signCount = (uint)((authenticatorData[33] << 24) | (authenticatorData[34] << 16) | (authenticatorData[35] << 8) | authenticatorData[36]);
+        return true;
+    }
+
+    /// <summary><c>clientDataJSON</c> 的 type、challenge、origin 都要对得上。注册和登录共用。</summary>
+    public static bool ClientDataValid(ReadOnlySpan<byte> clientDataJson, string expectedType, ReadOnlySpan<byte> expectedChallenge, Func<string, bool> originAllowed)
+    {
+        try
+        {
+            using JsonDocument document = JsonDocument.Parse(clientDataJson.ToArray());
+            JsonElement root = document.RootElement;
+            if (root.ValueKind != JsonValueKind.Object
+                || root.GetProperty("type").GetString() != expectedType
+                || root.GetProperty("origin").GetString() is not { } origin || !originAllowed(origin)
+                || root.GetProperty("challenge").GetString() is not { } challenge)
+            {
+                return false;
+            }
+
+            byte[] decoded = Base64Url.DecodeFromChars(challenge);
+            return CryptographicOperations.FixedTimeEquals(decoded, expectedChallenge);
+        }
+        catch (Exception ex) when (ex is JsonException or KeyNotFoundException or FormatException or InvalidOperationException)
+        {
+            return false;
+        }
+    }
+}

backend/fleet/src/Fleet.Link/FleetLink.cs

@@ -66,6 +66,12 @@ public sealed class FleetLinkOptions
     public long MaxInflightBytes { get; init; } = 4 << 20;
 
     public Backoff Backoff { get; init; } = new();
+
+    /// <summary>
+    /// 校验服务器身份：<see cref="IServerVerifier.Required"/> 为真（节点固定的操作员集合里登记了服务器密钥）时，
+    /// 服务器必须在挑战里证明自己，之后这条链路用应用层加密；否则按旧的方式（没有固定信任根的节点）。
+    /// </summary>
+    public IServerVerifier? ServerVerifier { get; init; }
 }
 
 /// <summary>
@@ -77,6 +83,7 @@ public sealed class FleetLink
     private const string RpcPath = "/api/agent/v1/rpc";
 
     private readonly FleetLinkOptions _options;
+    private volatile bool _secure;
     private readonly RpcRouter<LinkContext> _router;
     private readonly Dictionary<string, IStateHandler> _handlers;
     private readonly TimeProvider _time;
@@ -153,6 +160,9 @@ public sealed class FleetLink
         }
     }
 
+    /// <summary>当前这条链路是不是应用层加密的（服务器证明了身份）。</summary>
+    public bool IsSecure => _secure && IsConnected;
+
     private async Task<string> RunOnceAsync(CancellationToken ct)
     {
         using var socket = new ClientWebSocket();
@@ -160,7 +170,7 @@ public sealed class FleetLink
         socket.Options.KeepAliveTimeout = TimeSpan.FromSeconds(20); // 对端 20 秒没有回 Pong 就判定连接已死
         var builder = new UriBuilder(_options.Server) { Scheme = _options.Server.Scheme == "https" ? "wss" : "ws", Path = RpcPath };
         await socket.ConnectAsync(builder.Uri, ct);
-        await using var transport = new WsTransport(socket, _options.MaxFrameBytes);
+        await using var transport = new SecureTransport(new WsTransport(socket, _options.MaxFrameBytes));
 
         string? failure = await AuthenticateAsync(transport, ct);
         if (failure is not null)
@@ -168,6 +178,8 @@ public sealed class FleetLink
             return failure;
         }
 
+        _secure = transport.Secure;
+
         var session = new RpcSession<LinkContext>(transport, _router, new LinkContext(this), _time);
         using CancellationTokenSource sessionCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
         Task run = session.RunAsync(sessionCts.Token);
@@ -211,7 +223,7 @@ public sealed class FleetLink
     }
 
     /// <summary>挑战 → 签名 → 认证结果。失败返回原因；服务端禁用该节点时不再重试。</summary>
-    private async Task<string?> AuthenticateAsync(WsTransport transport, CancellationToken ct)
+    private async Task<string?> AuthenticateAsync(SecureTransport transport, CancellationToken ct)
     {
         using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(15), _time);
         using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct, timeout.Token);
@@ -222,9 +234,44 @@ public sealed class FleetLink
         }
 
         ChallengeParams nonce = challenge.Params.Value.Deserialize(FleetRpcContext.Default.ChallengeParams)!;
-        string signature = Convert.ToBase64String(_options.Identity.Sign(SignaturePurpose.Auth, _options.NodeId.Value, nonce.Nonce));
-        RpcMessage request = RpcMessage.Request(1, FleetMethods.Auth, new AuthParams { NodeId = _options.NodeId.Value, Signature = signature }, FleetRpcContext.Default.AuthParams);
-        await transport.SendAsync(new RpcFrame(FrameKind.Text, JsonSerializer.SerializeToUtf8Bytes(request, FleetRpcContext.Default.RpcMessage)), linked.Token);
+
+        // 固定了操作员集合、而集合里登记了服务器密钥：服务器必须证明自己，否则不继续，也不交出任何东西
+        EphemeralKey? ephemeral = null;
+        AuthParams authParams;
+        try
+        {
+            if (_options.ServerVerifier is { Required: true } verifier)
+            {
+                if (!TryDecodeBase64(nonce.ServerEphemeral, out byte[] serverEphemeral) || !TryDecodeBase64(nonce.ServerSignature, out byte[] serverSignature)
+                    || !verifier.Verify(nonce.Nonce, serverEphemeral, serverSignature))
+                {
+                    return "the server could not prove its identity (it is not the server your operator set authorizes)";
+                }
+
+                ephemeral = new EphemeralKey();
+                string serverEphemeralText = Convert.ToBase64String(serverEphemeral);
+                string nodeEphemeralText = Convert.ToBase64String(ephemeral.PublicKeySpki);
+                authParams = new AuthParams
+                {
+                    NodeId = _options.NodeId.Value,
+                    Signature = Convert.ToBase64String(_options.Identity.Sign(SignaturePurpose.AuthSecure, _options.NodeId.Value, nonce.Nonce, serverEphemeralText, nodeEphemeralText)),
+                    NodeEphemeral = nodeEphemeralText,
+                };
+                RpcMessage secureRequest = RpcMessage.Request(1, FleetMethods.Auth, authParams, FleetRpcContext.Default.AuthParams);
+                await transport.SendAsync(new RpcFrame(FrameKind.Text, JsonSerializer.SerializeToUtf8Bytes(secureRequest, FleetRpcContext.Default.RpcMessage)), linked.Token);
+                transport.Enable(LinkCipher.ForNode(ephemeral, serverEphemeral, nonce.Nonce));
+            }
+            else
+            {
+                authParams = new AuthParams { NodeId = _options.NodeId.Value, Signature = Convert.ToBase64String(_options.Identity.Sign(SignaturePurpose.Auth, _options.NodeId.Value, nonce.Nonce)) };
+                RpcMessage request = RpcMessage.Request(1, FleetMethods.Auth, authParams, FleetRpcContext.Default.AuthParams);
+                await transport.SendAsync(new RpcFrame(FrameKind.Text, JsonSerializer.SerializeToUtf8Bytes(request, FleetRpcContext.Default.RpcMessage)), linked.Token);
+            }
+        }
+        finally
+        {
+            ephemeral?.Dispose();
+        }
 
         while (true)
         {
@@ -259,7 +306,26 @@ public sealed class FleetLink
         }
     }
 
-    private static async Task<RpcMessage?> ReceiveMessageAsync(WsTransport transport, CancellationToken ct)
+    private static bool TryDecodeBase64(string? text, out byte[] data)
+    {
+        data = [];
+        if (string.IsNullOrEmpty(text))
+        {
+            return false;
+        }
+
+        try
+        {
+            data = Convert.FromBase64String(text);
+            return true;
+        }
+        catch (FormatException)
+        {
+            return false;
+        }
+    }
+
+    private static async Task<RpcMessage?> ReceiveMessageAsync(SecureTransport transport, CancellationToken ct)
     {
         RpcFrame? frame = await transport.ReceiveAsync(ct);
         return frame is { Kind: FrameKind.Text } f ? JsonSerializer.Deserialize(f.Data.Span, FleetRpcContext.Default.RpcMessage) : null;

backend/fleet/src/Fleet.Link/SecureTransport.cs

@@ -0,0 +1,57 @@
+using Fleet.Identity;
+using Fleet.Rpc;
+
+namespace Fleet.Link;
+
+/// <summary>
+/// 认证阶段是明文，认证通过之后换成应用层加密（<see cref="LinkCipher"/>）：此后每帧都是加密的二进制帧，明文帧一律拒绝。
+/// 认证阶段服务器的拒绝回复可能是明文（还没有协商好密钥），所以第一帧加密的回复到达之前允许一次明文文本帧。
+/// </summary>
+internal sealed class SecureTransport : IRpcTransport
+{
+    private readonly IRpcTransport _inner;
+    private LinkCipher? _cipher;
+    private bool _allowPlaintext = true;
+
+    public SecureTransport(IRpcTransport inner)
+    {
+        _inner = inner;
+    }
+
+    public bool Secure => _cipher is not null;
+
+    public void Enable(LinkCipher cipher) => _cipher = cipher;
+
+    public ValueTask SendAsync(RpcFrame frame, CancellationToken ct) =>
+        _cipher is null ? _inner.SendAsync(frame, ct) : _inner.SendAsync(new RpcFrame(FrameKind.Binary, _cipher.Seal((byte)frame.Kind, frame.Data.Span)), ct);
+
+    public async ValueTask<RpcFrame?> ReceiveAsync(CancellationToken ct)
+    {
+        RpcFrame? frame = await _inner.ReceiveAsync(ct);
+        if (frame is not { } received || _cipher is null)
+        {
+            return frame;
+        }
+
+        if (received.Kind == FrameKind.Binary && _cipher.TryOpen(received.Data.Span, out byte kind, out byte[] data))
+        {
+            _allowPlaintext = false;
+            return new RpcFrame((FrameKind)kind, data);
+        }
+
+        if (_allowPlaintext && received.Kind == FrameKind.Text)
+        {
+            return received; // 认证被拒绝时服务器还没有协商好密钥，回复是明文
+        }
+
+        throw new IOException("a frame on the secure link failed to authenticate");
+    }
+
+    public ValueTask CloseAsync(string reason, CancellationToken ct) => _inner.CloseAsync(reason, ct);
+
+    public async ValueTask DisposeAsync()
+    {
+        _cipher?.Dispose();
+        await _inner.DisposeAsync();
+    }
+}

backend/fleet/src/Fleet.Rpc/FleetMethods.cs

@@ -53,6 +53,14 @@ public sealed class ChallengeParams
 
     [JsonPropertyName("expires_at_ms")]
     public long ExpiresAtMs { get; set; }
+
+    /// <summary>服务器这次连接的临时 ECDH 公钥（SPKI，base64）；服务器有身份密钥时才有。</summary>
+    [JsonPropertyName("server_eph")]
+    public string? ServerEphemeral { get; set; }
+
+    /// <summary>服务器密钥对「随机数加临时公钥」的签名（base64）：节点据此确认对面是操作员授权的服务器。</summary>
+    [JsonPropertyName("server_sig")]
+    public string? ServerSignature { get; set; }
 }
 
 public sealed class AuthParams
@@ -63,6 +71,10 @@ public sealed class AuthParams
     /// <summary>对 <c>fleet|v1|auth|{node_id}|{nonce}</c> 的签名（base64）。</summary>
     [JsonPropertyName("signature")]
     public string Signature { get; set; } = "";
+
+    /// <summary>节点的临时 ECDH 公钥（SPKI，base64）：有它就是安全链路，签名覆盖双方的临时公钥，认证结果起所有帧都是加密的。</summary>
+    [JsonPropertyName("node_eph")]
+    public string? NodeEphemeral { get; set; }
 }
 
 public sealed class AuthResult

backend/fleet/src/Fleet.Server.Abstractions/NodeRecords.cs

@@ -33,7 +33,8 @@ public sealed record NewNode(
     string? NodeVersion,
     long NowMs,
     string Kind = "",
-    byte[]? TlsPublicKey = null);
+    byte[]? TlsPublicKey = null,
+    string? AddedBy = null);
 
 public sealed record JoinTokenRecord(
     string Id,
@@ -46,6 +47,7 @@ public sealed record JoinTokenRecord(
     long ExpiresAtMs,
     long? RevokedAtMs,
     long CreatedAtMs,
-    string Kind = "");
+    string Kind = "",
+    string? CreatedBy = null);
 
 public sealed record Presence(bool Online, long AtMs, string? NodeVersion, IReadOnlyList<string> Capabilities, string? HelloMetaJson);

backend/fleet/src/Fleet.Server.Abstractions/ServerContracts.cs

@@ -6,6 +6,24 @@ namespace Fleet.Server;
 
 public sealed record EnrollmentContext(string? RemoteIp, JsonElement? ProductMeta);
 
+/// <summary>
+/// 服务器的身份密钥：操作员用 passkey 把它的公钥签进操作员集合。有它的时候，认证挑战会带上服务器的签名，节点据此确认对面是真的服务器，
+/// 并在这条链路上用应用层加密。没有注册就是旧的行为（没有服务器身份）。
+/// </summary>
+public interface IServerIdentity
+{
+    byte[] PublicKeySpki { get; }
+
+    /// <summary>对一段内容签名（<c>Fleet.Identity.ServerHello.Payload</c> 给出的）。</summary>
+    byte[] Sign(ReadOnlySpan<byte> payload);
+}
+
+/// <summary>操作员集合的链（passkey 签的，创世在前）。没有初始化信任根时是空的。节点注册时用它确认「这个面板确实是我的操作员的」。</summary>
+public interface IOperatorTrustSource
+{
+    ValueTask<IReadOnlyList<SignedStatementDto>> ChainAsync(CancellationToken ct);
+}
+
 /// <summary>产品挂钩：节点注册成功之后调用。</summary>
 public interface IEnrollmentHook
 {

backend/fleet/src/Fleet.Server.Enrollment/EnrollmentModels.cs

@@ -37,6 +37,12 @@ public sealed class EnrollRequest
     public JsonElement? Meta { get; set; }
 }
 
+public sealed class TrustRequest
+{
+    [JsonPropertyName("join_token")]
+    public string JoinToken { get; set; } = "";
+}
+
 public sealed class EnrollResponse
 {
     [JsonPropertyName("node_id")]
@@ -69,5 +75,7 @@ public sealed class FleetProblem
 [JsonSourceGenerationOptions(DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]
 [JsonSerializable(typeof(EnrollRequest))]
 [JsonSerializable(typeof(EnrollResponse))]
+[JsonSerializable(typeof(TrustRequest))]
+[JsonSerializable(typeof(Fleet.Core.TrustBundle))]
 [JsonSerializable(typeof(FleetProblem))]
 internal sealed partial class EnrollmentJsonContext : JsonSerializerContext;

backend/fleet/src/Fleet.Server.Enrollment/FleetEnrollmentEndpoints.cs

@@ -20,9 +20,42 @@ public static class FleetEnrollmentEndpoints
             .WithTags("agent")
             .WithSummary("Enroll a node with a join token")
             .DisableAntiforgery();
+        // 注册之前取信任链：节点先确认这个面板的操作员集合和委托确实是它固定的创世签出来的，再把自己的密钥交出去
+        app.MapPost(path + "/trust", HandleTrustAsync)
+            .WithName("fleet_enroll_trust")
+            .WithTags("agent")
+            .WithSummary("The operator set chain and the grant of a join token, for the node to verify before it enrolls")
+            .DisableAntiforgery();
         return app;
     }
 
+    private static async Task<IResult> HandleTrustAsync(HttpContext http, FleetEnrollmentService service)
+    {
+        TrustRequest? request;
+        try
+        {
+            request = await JsonSerializer.DeserializeAsync(http.Request.Body, EnrollmentJsonContext.Default.TrustRequest, http.RequestAborted);
+        }
+        catch (JsonException)
+        {
+            request = null;
+        }
+
+        if (request is null || string.IsNullOrEmpty(request.JoinToken))
+        {
+            return Problem(StatusCodes.Status400BadRequest, FleetErrors.InvalidParams, "join_token is required");
+        }
+
+        Result<TrustBundle> result = await service.GetTrustAsync(request.JoinToken, http.RequestAborted);
+        if (!result.TryGet(out TrustBundle? bundle, out FleetError? error))
+        {
+            return Problem(error.Code == FleetErrors.JoinTokenExpired ? StatusCodes.Status410Gone : StatusCodes.Status401Unauthorized, error.Code, error.Message);
+        }
+
+        http.Response.Headers.CacheControl = "no-store";
+        return Results.Json(bundle, EnrollmentJsonContext.Default.TrustBundle);
+    }
+
     private static async Task<IResult> HandleAsync(HttpContext http, FleetEnrollmentService service)
     {
         EnrollRequest? request;

backend/fleet/src/Fleet.Server.Enrollment/FleetEnrollmentService.cs

@@ -9,13 +9,15 @@ public sealed partial class FleetEnrollmentService
 {
     private readonly IFleetStore _store;
     private readonly IEnumerable<IEnrollmentHook> _hooks;
+    private readonly IEnumerable<IOperatorTrustSource> _trust;
     private readonly FleetServerOptions _options;
     private readonly TimeProvider _time;
 
-    public FleetEnrollmentService(IFleetStore store, IEnumerable<IEnrollmentHook> hooks, FleetServerOptions options, TimeProvider time)
+    public FleetEnrollmentService(IFleetStore store, IEnumerable<IEnrollmentHook> hooks, IEnumerable<IOperatorTrustSource> trust, FleetServerOptions options, TimeProvider time)
     {
         _store = store;
         _hooks = hooks;
+        _trust = trust;
         _options = options;
         _time = time;
     }
@@ -80,7 +82,8 @@ public sealed partial class FleetEnrollmentService
             request.NodeVersion,
             nowMs,
             token.Kind,
-            tlsPublicKey);
+            tlsPublicKey,
+            token.CreatedBy);
 
         Result<NodeRecord> created = await _store.CreateNodeAsync(node, ct);
         if (!created.TryGet(out NodeRecord? record, out FleetError? error))
@@ -101,6 +104,30 @@ public sealed partial class FleetEnrollmentService
         });
     }
 
+    /// <summary>节点注册之前取：操作员集合的链。码要是有效的；不能用的码不给。</summary>
+    public async ValueTask<Result<TrustBundle>> GetTrustAsync(string joinToken, CancellationToken ct)
+    {
+        JoinTokenRecord? token = await _store.FindJoinTokenAsync(TokenHash.Sha256(joinToken), ct);
+        long nowMs = _time.GetUtcNow().ToUnixTimeMilliseconds();
+        if (token is null || token.RevokedAtMs is not null || token.Uses >= token.MaxUses)
+        {
+            return Result<TrustBundle>.Fail(FleetErrors.JoinTokenInvalid, "join token is invalid");
+        }
+
+        if (token.ExpiresAtMs <= nowMs)
+        {
+            return Result<TrustBundle>.Fail(FleetErrors.JoinTokenExpired, "join token has expired");
+        }
+
+        var bundle = new TrustBundle();
+        foreach (IOperatorTrustSource source in _trust)
+        {
+            bundle.Chain.AddRange(await source.ChainAsync(ct));
+        }
+
+        return Result<TrustBundle>.Ok(bundle);
+    }
+
     private static bool TryDecode(string text, out byte[] data)
     {
         try

backend/fleet/src/Fleet.Server.Link/FleetLinkHost.cs

@@ -23,8 +23,10 @@ public sealed class FleetLinkHost : IFleetConnections, IStateNotifier
         IEnumerable<IStateProvider> stateProviders,
         IEnumerable<IInbox> inboxes,
         IEnumerable<INodeEventSink> sinks,
-        FleetRouter router)
+        FleetRouter router,
+        IServerIdentity? serverIdentity = null)
     {
+        ServerIdentity = serverIdentity;
         Store = store;
         Options = options;
         Time = time;
@@ -38,6 +40,9 @@ public sealed class FleetLinkHost : IFleetConnections, IStateNotifier
 
     internal IFleetStore Store { get; }
 
+    /// <summary>服务器的身份密钥；没有时节点连接用旧的明文认证。</summary>
+    internal IServerIdentity? ServerIdentity { get; }
+
     internal FleetServerOptions Options { get; }
 
     internal TimeProvider Time { get; }

backend/fleet/src/Fleet.Server.Link/FleetServerBuilder.cs

@@ -109,7 +109,8 @@ public static class FleetServerExtensions
             provider.GetServices<IStateProvider>(),
             provider.GetServices<IInbox>(),
             provider.GetServices<INodeEventSink>(),
-            provider.GetRequiredService<FleetRouter>()));
+            provider.GetRequiredService<FleetRouter>(),
+            provider.GetService<IServerIdentity>()));
         services.AddSingleton<IFleetConnections>(provider => provider.GetRequiredService<FleetLinkHost>());
         services.AddSingleton<IStateNotifier>(provider => provider.GetRequiredService<FleetLinkHost>());
         return builder;

backend/fleet/src/Fleet.Server.Link/NodeConnection.Auth.cs

@@ -14,9 +14,19 @@ internal sealed partial class NodeConnection
     {
         string nonce = Convert.ToBase64String(RandomNumberGenerator.GetBytes(32));
         long expiresAtMs = _host.Time.GetUtcNow().Add(_host.Options.ChallengeTtl).ToUnixTimeMilliseconds();
-        await SendAsync(
-            RpcMessage.Notification(FleetMethods.Challenge, new ChallengeParams { Nonce = nonce, ExpiresAtMs = expiresAtMs }, FleetRpcContext.Default.ChallengeParams),
-            ct);
+
+        // 有服务器身份密钥：挑战里带上这次连接的临时公钥和服务器的签名，节点据此确认服务器、协商加密链路
+        using var serverEphemeral = _host.ServerIdentity is null ? null : new EphemeralKey();
+        var challenge = new ChallengeParams { Nonce = nonce, ExpiresAtMs = expiresAtMs };
+        string? serverEphemeralText = null;
+        if (_host.ServerIdentity is { } identity && serverEphemeral is not null)
+        {
+            serverEphemeralText = Convert.ToBase64String(serverEphemeral.PublicKeySpki);
+            challenge.ServerEphemeral = serverEphemeralText;
+            challenge.ServerSignature = Convert.ToBase64String(identity.Sign(ServerHello.Payload(nonce, serverEphemeral.PublicKeySpki)));
+        }
+
+        await SendAsync(RpcMessage.Notification(FleetMethods.Challenge, challenge, FleetRpcContext.Default.ChallengeParams), ct);
 
         using var timeout = new CancellationTokenSource(s_authTimeout, _host.Time);
         using CancellationTokenSource linked = CancellationTokenSource.CreateLinkedTokenSource(ct, timeout.Token);
@@ -48,10 +58,21 @@ internal sealed partial class NodeConnection
         }
 
         NodeRecord? node = auth is null ? null : await _host.Store.GetNodeAsync(new NodeId(auth.NodeId), ct);
+
+        // 安全链路：节点的签名覆盖双方的临时公钥（AuthSecure），验过之后这条连接上的所有帧都是加密的
+        byte[] nodeEphemeral = [];
+        bool secure = auth?.NodeEphemeral is not null && serverEphemeral is not null && serverEphemeralText is not null && TryDecode(auth.NodeEphemeral, out nodeEphemeral);
         bool signatureOk = node is not null
             && _host.Time.GetUtcNow().ToUnixTimeMilliseconds() <= expiresAtMs
             && TryDecode(auth!.Signature, out byte[] signature)
-            && NodeIdentity.Verify(node.PublicKey, signature, SignaturePurpose.Auth, auth.NodeId, nonce);
+            && (secure
+                ? NodeIdentity.Verify(node.PublicKey, signature, SignaturePurpose.AuthSecure, auth.NodeId, nonce, serverEphemeralText!, auth.NodeEphemeral!)
+                : auth.NodeEphemeral is null && NodeIdentity.Verify(node.PublicKey, signature, SignaturePurpose.Auth, auth.NodeId, nonce));
+        if (signatureOk && secure)
+        {
+            _cipher = LinkCipher.ForServer(serverEphemeral!, nodeEphemeral, nonce);
+        }
+
         if (!signatureOk)
         {
             // 节点不存在与签名错误返回同样的错误，不泄露节点是否存在。

backend/fleet/src/Fleet.Server.Link/NodeConnection.Send.cs

@@ -75,7 +75,15 @@ internal sealed partial class NodeConnection
                 return false;
             }
 
-            await _socket.SendAsync(bytes, WebSocketMessageType.Text, endOfMessage: true, ct);
+            if (_cipher is { } cipher)
+            {
+                await _socket.SendAsync(cipher.Seal(0, bytes), WebSocketMessageType.Binary, endOfMessage: true, ct);
+            }
+            else
+            {
+                await _socket.SendAsync(bytes, WebSocketMessageType.Text, endOfMessage: true, ct);
+            }
+
             return true;
         }
         catch (WebSocketException)

backend/fleet/src/Fleet.Server.Link/NodeConnection.Wire.cs

@@ -30,6 +30,19 @@ internal sealed partial class NodeConnection
 
             if (result.EndOfMessage)
             {
+                if (_cipher is { } cipher)
+                {
+                    // 加密链路上只接受通过认证的二进制帧；明文、被改过的、重放的、乱序的一律断开
+                    if (result.MessageType != WebSocketMessageType.Binary || !cipher.TryOpen(writer.WrittenSpan, out byte kind, out byte[] plain))
+                    {
+                        _closeReason ??= "frame failed authentication";
+                        await _socket.CloseOutputAsync(WebSocketCloseStatus.PolicyViolation, "frame failed authentication", CancellationToken.None);
+                        return null;
+                    }
+
+                    return new Frame(kind == 0, plain);
+                }
+
                 return new Frame(result.MessageType == WebSocketMessageType.Text, writer.WrittenSpan.ToArray());
             }
         }

backend/fleet/src/Fleet.Server.Link/NodeConnection.cs

@@ -2,6 +2,7 @@ using System.Collections.Concurrent;
 using System.Net.WebSockets;
 using System.Threading.Channels;
 using Fleet.Core;
+using Fleet.Identity;
 using Fleet.Rpc;
 
 namespace Fleet.Server;
@@ -24,6 +25,7 @@ internal sealed partial class NodeConnection : IDisposable
     private readonly Channel<bool> _stateSignal = Channel.CreateBounded<bool>(new BoundedChannelOptions(1) { FullMode = BoundedChannelFullMode.DropWrite });
     private readonly Dictionary<string, long> _lastPushedVersion = new(StringComparer.Ordinal);
     private readonly CancellationTokenSource _lifetime = new();
+    private LinkCipher? _cipher;
     private long _nextRequestId;
     private long _lastPresenceTicks;
     private NodeRecord? _node;
@@ -134,6 +136,7 @@ internal sealed partial class NodeConnection : IDisposable
 
     public void Dispose()
     {
+        _cipher?.Dispose();
         _lifetime.Dispose();
         _sendLock.Dispose();
     }

backend/fleet/tests/Fleet.Tests/OperatorTrustTests.cs

@@ -0,0 +1,123 @@
+using System.Buffers.Text;
+using System.Security.Cryptography;
+using System.Text;
+using Fleet.Identity;
+
+namespace Fleet.Tests;
+
+/// <summary>软件 passkey：只做断言（navigator.credentials.get 的结果），用来测信任链。</summary>
+internal sealed class TestAuthenticator : IDisposable
+{
+    public const string RpId = "panel.example.com";
+    public const string Origin = "https://panel.example.com";
+
+    private readonly ECDsa _key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+    private uint _counter;
+
+    public string CredentialId { get; } = Base64Url.EncodeToString(RandomNumberGenerator.GetBytes(32));
+
+    public OperatorKey Key => new(CredentialId, _key.ExportSubjectPublicKeyInfo());
+
+    public SignedStatement Sign(string statement, byte flags = 0x05, string origin = Origin)
+    {
+        byte[] challenge = SHA256.HashData(Encoding.UTF8.GetBytes(statement));
+        _counter++;
+        byte[] authData = [.. SHA256.HashData(Encoding.UTF8.GetBytes(RpId)), flags, (byte)(_counter >> 24), (byte)(_counter >> 16), (byte)(_counter >> 8), (byte)_counter];
+        byte[] clientData = Encoding.UTF8.GetBytes($"{{\"type\":\"webauthn.get\",\"challenge\":\"{Base64Url.EncodeToString(challenge)}\",\"origin\":\"{origin}\",\"crossOrigin\":false}}");
+        byte[] signature = _key.SignData([.. authData, .. SHA256.HashData(clientData)], HashAlgorithmName.SHA256, DSASignatureFormat.Rfc3279DerSequence);
+        return new SignedStatement(statement, CredentialId, Base64Url.EncodeToString(authData), Base64Url.EncodeToString(clientData), Base64Url.EncodeToString(signature));
+    }
+
+    public void Dispose() => _key.Dispose();
+}
+
+public sealed class OperatorTrustTests : IDisposable
+{
+    private readonly TestAuthenticator _alice = new();
+    private readonly TestAuthenticator _bob = new();
+
+    public void Dispose()
+    {
+        _alice.Dispose();
+        _bob.Dispose();
+    }
+
+    private OperatorSet Genesis(params TestAuthenticator[] keys) =>
+        new(1, OperatorTrust.Genesis, TestAuthenticator.RpId, [TestAuthenticator.Origin], [.. keys.Select(k => k.Key)]);
+
+    private SignedStatement SignedGenesis(OperatorSet set, TestAuthenticator signer) => signer.Sign(OperatorTrust.Encode(set));
+
+    [Fact]
+    public void TheGenesis_IsPinnedByItsFingerprint_AndMustBeSelfSigned()
+    {
+        OperatorSet set = Genesis(_alice);
+        SignedStatement genesis = SignedGenesis(set, _alice);
+        string pin = OperatorTrust.Fingerprint(genesis.Statement);
+
+        Assert.NotNull(OperatorTrust.VerifyChain(pin, [genesis]));
+        Assert.Null(OperatorTrust.VerifyChain(new string('0', 64), [genesis])); // 指纹对不上：Backend 换了一份创世
+        Assert.Null(OperatorTrust.VerifyChain(pin, [SignedGenesis(set, _bob)])); // 不是集合里的凭证签的（也改不了指纹）
+        Assert.Null(OperatorTrust.VerifyChain(pin, []));
+    }
+
+    [Fact]
+    public void ABackendThatSwapsTheKeys_CannotMakeAChainTheNodeAccepts()
+    {
+        SignedStatement real = SignedGenesis(Genesis(_alice), _alice);
+        string pin = OperatorTrust.Fingerprint(real.Statement);
+
+        using var attacker = new TestAuthenticator();
+        SignedStatement forged = SignedGenesis(Genesis(attacker), attacker); // 自洽的假创世，但指纹不同
+        Assert.Null(OperatorTrust.VerifyChain(pin, [forged]));
+
+        // 在真创世后面接一个攻击者签的更新：上一版里没有他的凭证
+        var update = new OperatorSet(2, OperatorTrust.Fingerprint(real.Statement), TestAuthenticator.RpId, [TestAuthenticator.Origin], [_alice.Key, attacker.Key]);
+        Assert.Null(OperatorTrust.VerifyChain(pin, [real, attacker.Sign(OperatorTrust.Encode(update))]));
+    }
+
+    [Fact]
+    public void AnUpdate_NeedsAKeyOfThePreviousVersion_AndFollowsTheChain()
+    {
+        SignedStatement genesis = SignedGenesis(Genesis(_alice), _alice);
+        string pin = OperatorTrust.Fingerprint(genesis.Statement);
+        var second = new OperatorSet(2, OperatorTrust.Fingerprint(genesis.Statement), TestAuthenticator.RpId, [TestAuthenticator.Origin], [_alice.Key, _bob.Key]);
+        SignedStatement signedSecond = _alice.Sign(OperatorTrust.Encode(second));
+
+        OperatorSet? current = OperatorTrust.VerifyChain(pin, [genesis, signedSecond]);
+        Assert.Equal(2, current?.Version);
+        Assert.Equal(2, current?.Keys.Count);
+
+        // 新加的 bob 可以签下一版（上一版里有他）
+        var third = new OperatorSet(3, OperatorTrust.Fingerprint(signedSecond.Statement), TestAuthenticator.RpId, [TestAuthenticator.Origin], [_bob.Key]);
+        Assert.Equal(3, OperatorTrust.VerifyChain(pin, [genesis, signedSecond, _bob.Sign(OperatorTrust.Encode(third))])?.Version);
+
+        // 版本号跳了、prev 不对、域名换了：都不行
+        var skipped = second with { Version = 3 };
+        Assert.Null(OperatorTrust.VerifyChain(pin, [genesis, _alice.Sign(OperatorTrust.Encode(skipped))]));
+        var wrongPrev = second with { Previous = new string('a', 64) };
+        Assert.Null(OperatorTrust.VerifyChain(pin, [genesis, _alice.Sign(OperatorTrust.Encode(wrongPrev))]));
+        var otherRp = second with { RpId = "evil.example" };
+        Assert.Null(OperatorTrust.VerifyChain(pin, [genesis, _alice.Sign(OperatorTrust.Encode(otherRp))]));
+    }
+
+    [Fact]
+    public void AnAssertion_NeedsUserVerification_TheRightOrigin_AndTheExactStatement()
+    {
+        OperatorSet set = Genesis(_alice);
+        Assert.True(OperatorTrust.VerifyOperator(_alice.Sign("hello"), set));
+        Assert.False(OperatorTrust.VerifyOperator(_alice.Sign("hello", flags: 0x01), set)); // 没有用户验证
+        Assert.False(OperatorTrust.VerifyOperator(_alice.Sign("hello", origin: "https://evil.example"), set));
+        Assert.False(OperatorTrust.VerifyOperator(_alice.Sign("hello") with { Statement = "hellO" }, set)); // 语句被改
+        Assert.False(OperatorTrust.VerifyOperator(_bob.Sign("hello"), set)); // 不在集合里
+    }
+
+    [Fact]
+    public void Parsing_IsStrict()
+    {
+        Assert.Null(OperatorTrust.ParseSet("moshiro-opset-v2\nversion=1"));
+        OperatorSet set = Genesis(_alice);
+        Assert.Equal(set.Keys[0].CredentialId, OperatorTrust.ParseSet(OperatorTrust.Encode(set))!.Keys[0].CredentialId);
+        Assert.Null(OperatorTrust.ParseSet(OperatorTrust.Encode(set with { Previous = "abc" }))); // 创世的 prev 必须是 0
+        Assert.Null(OperatorTrust.ParseSet(OperatorTrust.Encode(set) + "\nnot-a-key"));
+    }
+}

backend/fleet/tests/Fleet.Tests/SecureChannelTests.cs

@@ -0,0 +1,114 @@
+using System.Security.Cryptography;
+using Fleet.Identity;
+
+namespace Fleet.Tests;
+
+public sealed class SecureChannelTests
+{
+    private const string Nonce = "n0nce-from-the-server";
+
+    private static (LinkCipher Node, LinkCipher Server) Pair(string nodeNonce = Nonce, string serverNonce = Nonce)
+    {
+        using var node = new EphemeralKey();
+        using var server = new EphemeralKey();
+        return (LinkCipher.ForNode(node, server.PublicKeySpki, nodeNonce), LinkCipher.ForServer(server, node.PublicKeySpki, serverNonce));
+    }
+
+    [Fact]
+    public void TheServerProof_VerifiesOnlyForTheRightKey_Nonce_AndEphemeralKey()
+    {
+        using ECDsa serverKey = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+        using ECDsa other = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+        using var eph = new EphemeralKey();
+        using var otherEph = new EphemeralKey();
+        byte[] spki = serverKey.ExportSubjectPublicKeyInfo();
+        byte[] proof = ServerHello.Sign(serverKey, Nonce, eph.PublicKeySpki);
+
+        Assert.True(ServerHello.Verify(spki, Nonce, eph.PublicKeySpki, proof));
+        Assert.False(ServerHello.Verify(other.ExportSubjectPublicKeyInfo(), Nonce, eph.PublicKeySpki, proof)); // 别人的服务器密钥
+        Assert.False(ServerHello.Verify(spki, "another-nonce", eph.PublicKeySpki, proof)); // 挪到别的挑战上
+        Assert.False(ServerHello.Verify(spki, Nonce, otherEph.PublicKeySpki, proof)); // 中间人换了自己的临时公钥
+        Assert.False(ServerHello.Verify(spki, Nonce, eph.PublicKeySpki, proof.AsSpan(0, proof.Length - 1)));
+        Assert.False(ServerHello.Verify([1, 2, 3], Nonce, eph.PublicKeySpki, proof)); // 公钥不合法也不抛异常
+    }
+
+    [Fact]
+    public void BothDirections_RoundTrip_AndKeepTheFrameKind()
+    {
+        (LinkCipher node, LinkCipher server) = Pair();
+        using LinkCipher n = node;
+        using LinkCipher s = server;
+
+        byte[] toServer = n.Seal(0, "hello server"u8);
+        Assert.True(s.TryOpen(toServer, out byte kind, out byte[] data));
+        Assert.Equal(0, kind);
+        Assert.Equal("hello server"u8.ToArray(), data);
+
+        byte[] big = RandomNumberGenerator.GetBytes(300_000);
+        byte[] toNode = s.Seal(1, big);
+        Assert.True(n.TryOpen(toNode, out kind, out data));
+        Assert.Equal(1, kind);
+        Assert.Equal(big, data);
+        Assert.Equal(big.Length + LinkCipher.Overhead + 1, toNode.Length);
+    }
+
+    [Fact]
+    public void AReplayedReorderedTamperedOrReflectedFrame_IsRefused()
+    {
+        (LinkCipher node, LinkCipher server) = Pair();
+        using LinkCipher n = node;
+        using LinkCipher s = server;
+
+        byte[] first = n.Seal(0, "one"u8);
+        byte[] second = n.Seal(0, "two"u8);
+        Assert.False(s.TryOpen(second, out _, out _)); // 乱序（丢了第一帧）
+        Assert.True(s.TryOpen(first, out _, out _));
+        Assert.False(s.TryOpen(first, out _, out _)); // 重放
+        Assert.True(s.TryOpen(second, out _, out _));
+
+        byte[] tampered = n.Seal(0, "three"u8);
+        tampered[12] ^= 0x01;
+        Assert.False(s.TryOpen(tampered, out _, out _)); // 改了一位
+
+        byte[] fromNode = n.Seal(0, "four"u8);
+        (LinkCipher otherNode, LinkCipher otherServer) = Pair();
+        using LinkCipher on = otherNode;
+        using LinkCipher os = otherServer;
+        Assert.False(os.TryOpen(fromNode, out _, out _)); // 另一条连接的密钥打不开
+
+        byte[] fromServer = s.Seal(0, "reflected"u8);
+        Assert.False(s.TryOpen(fromServer, out _, out _)); // 方向不同：服务器发的东西不能原样塞回给服务器
+        Assert.False(n.TryOpen([1, 2, 3], out _, out _));
+    }
+
+    [Fact]
+    public void ADifferentNonce_GivesDifferentKeys()
+    {
+        (LinkCipher node, LinkCipher server) = Pair("nonce-a", "nonce-b"); // 两边对不上：没人能解开对方的东西
+        using LinkCipher n = node;
+        using LinkCipher s = server;
+        Assert.False(s.TryOpen(n.Seal(0, "x"u8), out _, out _));
+    }
+
+    [Fact]
+    public void AnOperatorSet_CarriesTheServerKeys_ThroughTheChain()
+    {
+        using var alice = new TestAuthenticator();
+        using ECDsa serverKey = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+        byte[] spki = serverKey.ExportSubjectPublicKeyInfo();
+        var set = new OperatorSet(1, OperatorTrust.Genesis, TestAuthenticator.RpId, [TestAuthenticator.Origin], [alice.Key], [spki]);
+        string text = OperatorTrust.Encode(set);
+
+        OperatorSet parsed = OperatorTrust.ParseSet(text)!;
+        Assert.Equal(spki, Assert.Single(parsed.Servers!));
+        Assert.Equal(text, OperatorTrust.Encode(parsed)); // 编码和解析互逆，指纹稳定
+
+        SignedStatement genesis = alice.Sign(text);
+        OperatorSet verified = OperatorTrust.VerifyChain(OperatorTrust.Fingerprint(text), [genesis])!;
+        Assert.Equal(spki, Assert.Single(verified.Servers!));
+
+        // 服务器密钥只能写在凭证后面；顺序不对、内容不是 base64 都算坏
+        Assert.Null(OperatorTrust.ParseSet(text + "\nkey=late:AAAA"));
+        Assert.Null(OperatorTrust.ParseSet(text + "\nserver=***"));
+    }
+}

backend/fleet/tools/fleet-enroll/Program.cs

@@ -12,7 +12,7 @@ string? name = Arg("--name");
 string? directory = Arg("--identity-dir");
 if (server is null || join is null || name is null || directory is null)
 {
-    Console.Error.WriteLine("usage: fleet-enroll --server <url> --join <token> --name <node name> --identity-dir <dir> [--meta <json>] [--version <v>]");
+    Console.Error.WriteLine("usage: fleet-enroll --server <url> --join <token> --name <node name> --identity-dir <dir> [--meta <json>] [--version <v>] [--genesis <trust root fingerprint> --controllers <passkey credential ids, comma separated>]");
     return 2;
 }
 
@@ -30,14 +30,17 @@ if (Arg("--meta") is { } metaText)
     }
 }
 
+string? genesis = Arg("--genesis");
+string[] controllers = (Arg("--controllers") ?? "").Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+
 using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
 Result<EnrollmentResult> result = await EnrollmentClient.EnrollAsync(
-    http, new Uri(server), join, name, directory, Arg("--version") ?? "0.0.0", meta, TimeProvider.System, CancellationToken.None);
+    http, new Uri(server), join, name, directory, Arg("--version") ?? "0.0.0", meta, TimeProvider.System, CancellationToken.None, genesis, controllers);
 if (!result.TryGet(out EnrollmentResult? enrolled, out FleetError? error))
 {
     Console.Error.WriteLine($"enrollment failed ({error.Code}): {error.Message}");
     return 1;
 }
 
-Console.WriteLine($"enrolled as {enrolled.NodeId} ({enrolled.Status}); identity written to {enrolled.IdentityDirectory}");
+Console.WriteLine($"enrolled as {enrolled.NodeId} ({enrolled.Status}); identity written to {enrolled.IdentityDirectory}" + (enrolled.Pinned ? "; operator trust pinned" : "; operator trust NOT pinned (no --genesis)"));
 return 0;

backend/probe/src/MoShiro.Probe/Link/AgentDirectory.cs

@@ -16,11 +16,13 @@ public sealed class AgentDirectory
     private readonly object _gate = new();
     private readonly ConfigStore _store;
     private readonly INodeLog _log;
+    private readonly TrustAnchor _trust;
     private List<KnownAgent> _agents = [];
     private long _version;
 
-    public AgentDirectory(ConfigStore store, string configDirectory, INodeLog log)
+    public AgentDirectory(ConfigStore store, string configDirectory, INodeLog log, TrustAnchor? trust = null)
     {
+        _trust = trust ?? TrustAnchor.None;
         _store = store;
         _log = log;
         string cache = Path.Combine(configDirectory, FileName);
@@ -68,6 +70,7 @@ public sealed class AgentDirectory
     public void Apply(ProbeAgentList result)
     {
         var next = new List<KnownAgent>();
+        _trust.Update(result.TrustChain);
         foreach (AgentEndpoint agent in result.Agents)
         {
             if (!string.IsNullOrWhiteSpace(agent.Host))

backend/probe/src/MoShiro.Probe/ProbeApp.cs

@@ -27,7 +27,8 @@ public sealed class ProbeApp : IDisposable
     public ProbeApp(ProbeFile file, LoadedNodeIdentity identity, string configDirectory, TimeProvider time, INodeLog log, RestartController? restart = null)
     {
         _log = log;
-        var directory = new AgentDirectory(new ConfigStore(configDirectory), configDirectory, log);
+        var trust = TrustAnchor.Load(file.Fleet.IdentityDir, log);
+        var directory = new AgentDirectory(new ConfigStore(configDirectory), configDirectory, log, trust);
         _env = new ConnectionEnv(identity.PeerIdentity, identity.NodeId.Value, file.Limits, directory, new MonoClock(time), time, log);
         directory.Changed += () => _changed.Release();
 
@@ -36,6 +37,7 @@ public sealed class ProbeApp : IDisposable
         {
             Server = new Uri(file.Fleet.Server),
             Identity = identity.Identity,
+            ServerVerifier = trust,
             NodeId = identity.NodeId,
             NodeVersion = Version,
             Capabilities = [MoShiroCapabilities.Base],

backend/shared/MoShiro.Protocol/MoShiroErrors.cs

@@ -11,6 +11,7 @@ public static class MoShiroErrors
     public static readonly ErrorCode CsrfFailed = new("csrf_failed");
     public static readonly ErrorCode Forbidden = new("forbidden");
     public static readonly ErrorCode SitePrivate = new("site_private");
+    public static readonly ErrorCode ElevationRequired = new("elevation_required");
     public static readonly ErrorCode NotFound = new("not_found");
     public static readonly ErrorCode AgentNotFound = new("agent_not_found");
     public static readonly ErrorCode ProbeNotFound = new("probe_not_found");

backend/shared/MoShiro.Protocol/Rpc/MoShiroRpc.cs

@@ -164,6 +164,9 @@ public sealed class ProbeAgentList
 
     [JsonPropertyName("agents")]
     public List<AgentEndpoint> Agents { get; set; } = [];
+
+    [JsonPropertyName("trust_chain")]
+    public List<SignedStatementDto>? TrustChain { get; set; }
 }
 
 /// <summary>注册元数据（MoShiro 定义，经 Fleet 的 <c>meta</c> 字段带上来）。</summary>

backend/shared/MoShiro.Protocol/Tasks/TaskSet.cs

@@ -56,6 +56,10 @@ public sealed class TaskSet
     /// <summary>允许连接到这个 Agent 的 Probe 公钥。</summary>
     [JsonPropertyName("peers")]
     public List<PeerSpec> Peers { get; set; } = [];
+
+    /// <summary>操作员集合的链（passkey 签的，创世在前）：节点从固定的创世指纹验过才采用。</summary>
+    [JsonPropertyName("trust_chain")]
+    public List<SignedStatementDto>? TrustChain { get; set; }
 }
 
 public static class TaskSchedule

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

@@ -1,4 +1,5 @@
 using Fleet.Core;
+using Fleet.Identity;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Routing;
@@ -17,50 +18,67 @@ public static class AgentEndpoints
     public static void Map(RouteGroupBuilder group)
     {
         group.MapGet("/agents", ListAsync)
-            .Api("agents_list", "All agents including pending and disabled ones", AgentsTag).Returns<PageDto<AgentDto>>().ProducesProblems(401, 403);
+            .Api("agents_list", "All agents including pending and disabled ones", AgentsTag).Returns<PageDto<AgentDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.FleetRead);
         group.MapGet("/agents/{id}", GetAsync)
-            .Api("agents_get", "One agent", AgentsTag).Returns<AgentDto>().ProducesProblems(401, 403, 404);
+            .Api("agents_get", "One agent", AgentsTag).Returns<AgentDto>().ProducesProblems(401, 403, 404)
+            .Requires(Capability.FleetRead);
         group.MapPatch("/agents/{id}", PatchAsync)
             .Accepts<AgentPatchRequest>("application/merge-patch+json", "application/json")
             .Api("agents_update", "Update name, labels, public host or visibility (merge-patch, If-Match supported)", AgentsTag)
-            .Returns<AgentDto>().ProducesProblems(400, 401, 403, 404, 409, 412);
+            .Returns<AgentDto>().ProducesProblems(400, 401, 403, 404, 409, 412)
+            .Requires(Capability.FleetWrite);
         group.MapPost("/agents/{id}/approve", (HttpContext http, AgentService agents, string id) => TransitionAsync(http, id, (nodeId, ct) => agents.ApproveAsync(nodeId, ct)))
-            .Api("agents_approve", "Approve a pending agent", AgentsTag).Returns<AgentDto>().ProducesProblems(401, 403, 404, 409);
+            .Api("agents_approve", "Approve a pending agent", AgentsTag).Returns<AgentDto>().ProducesProblems(401, 403, 404, 409)
+            .Requires(Capability.FleetEnroll);
         group.MapPost("/agents/{id}/disable", (HttpContext http, AgentService agents, string id) => TransitionAsync(http, id, (nodeId, ct) => agents.DisableAsync(nodeId, ct)))
-            .Api("agents_disable", "Disable an agent and drop its connection", AgentsTag).Returns<AgentDto>().ProducesProblems(401, 403, 404, 409);
+            .Api("agents_disable", "Disable an agent and drop its connection", AgentsTag).Returns<AgentDto>().ProducesProblems(401, 403, 404, 409)
+            .Requires(Capability.FleetWrite);
         group.MapPost("/agents/{id}/enable", (HttpContext http, AgentService agents, string id) => TransitionAsync(http, id, (nodeId, ct) => agents.EnableAsync(nodeId, ct)))
-            .Api("agents_enable", "Enable a disabled agent", AgentsTag).Returns<AgentDto>().ProducesProblems(401, 403, 404, 409);
+            .Api("agents_enable", "Enable a disabled agent", AgentsTag).Returns<AgentDto>().ProducesProblems(401, 403, 404, 409)
+            .Requires(Capability.FleetWrite);
         group.MapPost("/agents/{id}/takeover", (HttpContext http, AgentService agents, string id) => TransitionAsync(http, id, (nodeId, ct) => agents.TakeoverAsync(nodeId, ct)))
             .Api("agents_takeover", "Replace the existing node of the same name with this pending one, keeping history", AgentsTag)
-            .Returns<AgentDto>().ProducesProblems(401, 403, 404);
+            .Returns<AgentDto>().ProducesProblems(401, 403, 404)
+            .Requires(Capability.FleetEnroll);
         group.MapDelete("/agents/{id}", DeleteAsync)
             .Api("agents_delete", "Delete an agent; history expires with the retention policy", AgentsTag)
-            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403);
+            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403)
+            .Requires(Capability.FleetRevoke);
 
         group.MapGet("/join-tokens", ListTokensAsync)
-            .Api("join_tokens_list", "Join tokens", TokensTag).Returns<PageDto<JoinTokenDto>>().ProducesProblems(401, 403);
+            .Api("join_tokens_list", "Join tokens", TokensTag).Returns<PageDto<JoinTokenDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.FleetRead);
         group.MapPost("/join-tokens", CreateTokenAsync)
             .Api("join_tokens_create", "Create a join token for an agent or a probe (role); the plaintext is returned only once", TokensTag)
-            .Returns<CreatedJoinTokenDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403);
+            .Returns<CreatedJoinTokenDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403)
+            .Requires(Capability.FleetEnroll);
         group.MapDelete("/join-tokens/{id}", RevokeTokenAsync)
             .Api("join_tokens_revoke", "Revoke a join token; with purge=true delete the record for good", TokensTag)
-            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403);
+            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403)
+            .Requires(Capability.FleetEnroll);
 
         group.MapGet("/probes", ListProbesAsync)
-            .Api("probes_list", "All probes, with the agents each one is connected to", ProbeTag).Returns<PageDto<ProbeDto>>().ProducesProblems(401, 403);
+            .Api("probes_list", "All probes, with the agents each one is connected to", ProbeTag).Returns<PageDto<ProbeDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.FleetRead);
         group.MapGet("/probes/{id}", GetProbeAsync)
-            .Api("probes_get", "One probe", ProbeTag).Returns<ProbeDto>().ProducesProblems(401, 403, 404);
+            .Api("probes_get", "One probe", ProbeTag).Returns<ProbeDto>().ProducesProblems(401, 403, 404)
+            .Requires(Capability.FleetRead);
         group.MapPatch("/probes/{id}", PatchProbeAsync)
-            .Api("probes_update", "Rename a probe", ProbeTag).Returns<ProbeDto>().ProducesProblems(400, 401, 403, 404, 409);
+            .Api("probes_update", "Rename a probe", ProbeTag).Returns<ProbeDto>().ProducesProblems(400, 401, 403, 404, 409)
+            .Requires(Capability.FleetWrite);
         group.MapPost("/probes/{id}/revoke", RevokeProbeAsync)
             .Api("probes_revoke", "Revoke a probe: every agent drops its session and refuses it; history stays until it expires", ProbeTag)
-            .Returns<ProbeDto>().ProducesProblems(401, 403, 404);
+            .Returns<ProbeDto>().ProducesProblems(401, 403, 404)
+            .Requires(Capability.FleetRevoke);
         group.MapDelete("/probes/{id}", DeleteProbeAsync)
             .Api("probes_delete", "Delete a probe and its lines; stored data expires with the retention policy", ProbeTag)
-            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403);
+            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403)
+            .Requires(Capability.FleetRevoke);
         group.MapPost("/agents/{id}/probes/{probe_id}/disconnect", DisconnectProbeAsync)
             .Api("agents_probe_disconnect", "Make an agent drop one probe's session (the probe reconnects unless it is revoked)", AgentsTag)
-            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403, 404, 409);
+            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403, 404, 409)
+            .Requires(Capability.FleetWrite);
     }
 
     private static async Task<IResult> ListAsync(AgentService agents, CancellationToken ct) =>
@@ -112,11 +130,23 @@ public static class AgentEndpoints
     private static async Task<IResult> ListTokensAsync(JoinTokenService tokens, CancellationToken ct) =>
         TypedResults.Json(new PageDto<JoinTokenDto>([.. (await tokens.ListAsync(ct)).Select(Mappers.ToDto)], null), ApiJsonContext.Default.PageDtoJoinTokenDto);
 
-    private static async Task<IResult> CreateTokenAsync(HttpContext http, JoinTokenService tokens, CreateJoinTokenRequest request, BackendOptions options)
+    private static async Task<IResult> CreateTokenAsync(HttpContext http, JoinTokenService tokens, TrustService trust, CreateJoinTokenRequest request, BackendOptions options)
     {
         string baseUrl = options.PublicUrl ?? $"{http.Request.Scheme}://{http.Request.Host}";
+
+        // 信任根建立之后，命令里带上创世指纹和属主；属主默认是操作员集合里的全部 passkey，也可以只选其中几把
+        OperatorSet? set = await trust.CurrentAsync(http.RequestAborted);
+        string? genesis = set is null ? null : (await trust.StateAsync(AuthEndpoints.PasskeyContextOf(http, options), http.RequestAborted)).Genesis;
+        string[] controllers = set is null ? [] : [.. request.Controllers ?? [.. set.Keys.Select(k => k.CredentialId)]];
+        if (set is not null && controllers.Any(c => set.Keys.All(k => k.CredentialId != c)))
+        {
+            return Problems.From(http, ValidationError.Single("controllers", "must be passkeys of the operator set"));
+        }
+
+        var plan = new InstallPlan(genesis, controllers, InstallScripts.Sha256(InstallScripts.Sh), InstallScripts.Sha256(InstallScripts.Ps1));
+        http.SetDetail($"{request.Role ?? JoinTokenService.AgentRole}: {request.Note}");
         Result<CreatedJoinToken> result = await tokens.CreateAsync(
-            new Application.CreateJoinTokenRequest(request.Note, request.Labels, request.AutoApprove ?? true, request.MaxUses ?? 1, request.ExpiresInHours ?? 24, request.Role ?? JoinTokenService.AgentRole), baseUrl, http.RequestAborted);
+            new Application.CreateJoinTokenRequest(request.Note, request.Labels, request.AutoApprove ?? true, request.MaxUses ?? 1, request.ExpiresInHours ?? 24, request.Role ?? JoinTokenService.AgentRole, http.GetPrincipal().Label), baseUrl, plan, http.RequestAborted);
         if (!result.TryGet(out CreatedJoinToken? created, out FleetError? error))
         {
             return Problems.From(http, error);

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

@@ -0,0 +1,44 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Routing;
+using MoShiro.Backend.Application;
+using MoShiro.Protocol;
+
+namespace MoShiro.Backend.Api;
+
+/// <summary>审计日志：管理接口里每个写操作、登录和提权都会记一行，这里只读。</summary>
+public static class AuditEndpoints
+{
+    private const string Tag = "admin-audit";
+
+    /// <summary>handler 往这里放一句「这次具体做了什么」（例如新建令牌的名字），守卫记审计时一起写进去。</summary>
+    public const string DetailItem = "moshiro.audit.detail";
+
+    public static void Map(RouteGroupBuilder guarded) =>
+        guarded.MapGet("/audit", ListAsync)
+            .Api("audit_list", "Audit log of admin actions, newest first", Tag).Returns<PageDto<AuditDto>>().ProducesProblems(400, 401, 403)
+            .Requires(Capability.AuditRead);
+
+    public static void SetDetail(this HttpContext http, string detail) => http.Items[DetailItem] = detail;
+
+    private static async Task<IResult> ListAsync(HttpContext http, AuditService audit, string? actor, string? action, int? limit, string? cursor)
+    {
+        long? before = null;
+        if (cursor is not null)
+        {
+            if (!long.TryParse(cursor, out long parsed))
+            {
+                return Problems.From(http, ValidationError.Single("cursor", "is not a valid cursor"));
+            }
+
+            before = parsed;
+        }
+
+        int size = Math.Clamp(limit ?? 50, 1, 500);
+        IReadOnlyList<AuditRecord> rows = await audit.ListAsync(new AuditQuery(before, size + 1, string.IsNullOrEmpty(actor) ? null : actor, string.IsNullOrEmpty(action) ? null : action), http.RequestAborted);
+        bool more = rows.Count > size;
+        IReadOnlyList<AuditRecord> page = [.. rows.Take(size)];
+        string? next = more ? page[^1].Id.ToString(System.Globalization.CultureInfo.InvariantCulture) : null;
+        return TypedResults.Json(new PageDto<AuditDto>([.. page.Select(Mappers.ToDto)], next), ApiJsonContext.Default.PageDtoAuditDto);
+    }
+}

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

@@ -16,36 +16,86 @@ public static class AuthEndpoints
     public static void MapLogin(RouteGroupBuilder open)
     {
         open.MapPost("/auth/login", LoginAsync)
+            .AllowsAnonymous()
             .Api("auth_login", "Sign in with a username and password", Tag)
             .Returns<LoginResponse>().ProducesProblems(400, 401, 429);
+        open.MapPost("/auth/passkey/options", PasskeyLoginOptions)
+            .AllowsAnonymous()
+            .Api("auth_passkey_options", "A challenge for signing in with a passkey (discoverable credential, no username needed)", Tag)
+            .Returns<PasskeyRequestOptionsDto>().ProducesProblems(429);
+        open.MapPost("/auth/passkey/login", PasskeyLoginAsync)
+            .AllowsAnonymous()
+            .Api("auth_passkey_login", "Sign in with a passkey assertion; same response as the password sign-in", Tag)
+            .Returns<LoginResponse>().ProducesProblems(400, 401, 429);
     }
 
     public static void MapSession(RouteGroupBuilder guarded)
     {
         guarded.MapPost("/auth/logout", LogoutAsync)
             .Api("auth_logout", "Sign out and clear the session cookie", Tag)
-            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401);
+            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401)
+            .Requires(Capability.Authenticated);
+        guarded.MapGet("/auth/passkeys", ListPasskeysAsync)
+            .Api("auth_passkeys_list", "The signed-in user's passkeys", Tag)
+            .Returns<PageDto<PasskeyDto>>().ProducesProblems(401)
+            .Requires(Capability.Authenticated);
+        guarded.MapPost("/auth/passkeys/options", PasskeyCreationOptionsAsync)
+            .Api("auth_passkeys_options", "A challenge for registering a new passkey (the user must be signed in)", Tag)
+            .Returns<PasskeyCreationOptionsDto>().ProducesProblems(400, 401, 403)
+            .Requires(Capability.Authenticated);
+        guarded.MapPost("/auth/passkeys", RegisterPasskeyAsync)
+            .Api("auth_passkeys_register", "Register a passkey from a WebAuthn attestation (ES256, user verification required)", Tag)
+            .Returns<PasskeyDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409)
+            .Requires(Capability.Authenticated);
+        guarded.MapDelete("/auth/passkeys/{id}", DeletePasskeyAsync)
+            .Api("auth_passkeys_delete", "Remove one of your own passkeys", Tag)
+            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 404)
+            .Requires(Capability.Authenticated);
+        guarded.MapGet("/auth/elevation", ListElevation)
+            .Api("auth_elevation_list", "The elevation windows this session has open (sensitive actions need one)", Tag)
+            .Returns<PageDto<ElevationDto>>().ProducesProblems(401)
+            .Requires(Capability.Authenticated);
+        guarded.MapPost("/auth/elevation/options", ElevationOptionsAsync)
+            .Api("auth_elevation_options", "A challenge for opening an elevation window with a passkey touch", Tag)
+            .Returns<PasskeyRequestOptionsDto>().ProducesProblems(400, 401, 403, 429)
+            .Requires(Capability.Authenticated);
+        guarded.MapPost("/auth/elevation", ElevateAsync)
+            .Api("auth_elevate", "Open an elevation window from a passkey assertion (enroll 15 min, revoke 5 min, credential one use within 60 s)", Tag)
+            .Returns<ElevationDto>().ProducesProblems(400, 401, 403, 429)
+            .Requires(Capability.Authenticated);
+        guarded.MapDelete("/auth/elevation", EndElevation)
+            .Api("auth_elevation_end", "Close all elevation windows of this session", Tag)
+            .Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401)
+            .Requires(Capability.Authenticated);
         guarded.MapGet("/auth/me", Me)
             .Api("auth_me", "The current identity", Tag)
-            .Returns<MeDto>().ProducesProblems(401);
+            .Returns<MeDto>().ProducesProblems(401)
+            .Requires(Capability.Authenticated);
     }
 
-    private static async Task<IResult> LoginAsync(HttpContext http, LoginRequest request, AuthService auth, LoginRateLimiter limiter, BackendOptions options)
+    private static async Task<IResult> LoginAsync(HttpContext http, LoginRequest request, AuthService auth, AuditService audit, LoginRateLimiter limiter, BackendOptions options)
     {
-        string source = http.Connection.RemoteIpAddress?.ToString() ?? "unknown";
+        string source = http.ClientAddress();
         if (!limiter.TryAcquire(source, out int retryAfter))
         {
             return Problems.RetryAfter(http, new FleetError(MoShiroErrors.TooManyRequests, "too many sign-in attempts"), retryAfter);
         }
 
         Result<LoginResult> result = await auth.LoginAsync(request.Username ?? "", request.Password ?? "", http.RequestAborted);
+        string remote = source;
         if (!result.TryGet(out LoginResult? login, out FleetError? error))
         {
+            await audit.RecordAsync(null, request.Username ?? "", AuthMethods.Password, "auth.login", null, null, remote, false, http.RequestAborted);
             return Problems.From(http, error);
         }
 
-        // 跨域的前端（return_session）不用 Cookie：会话令牌放在响应里，之后用 Bearer 带上
-        bool returnSession = request.ReturnSession == true;
+        await audit.RecordAsync(login.UserId, login.Username, AuthMethods.Password, "auth.login", null, null, remote, true, http.RequestAborted);
+        return IssueSession(http, login, request.ReturnSession == true, options);
+    }
+
+    /// <summary>发放会话：Cookie（同源前端）或在响应里返回会话令牌（跨域前端的 return_session）。密码登录和 passkey 登录共用。</summary>
+    private static Microsoft.AspNetCore.Http.HttpResults.JsonHttpResult<LoginResponse> IssueSession(HttpContext http, LoginResult login, bool returnSession, BackendOptions options)
+    {
         if (!returnSession)
         {
             http.Response.Cookies.Append(
@@ -65,8 +115,193 @@ public static class AuthEndpoints
         return TypedResults.Json(new LoginResponse(login.UserId, login.Username, login.CsrfToken, Mappers.Time(login.ExpiresAtMs), returnSession ? login.SessionToken : null), ApiJsonContext.Default.LoginResponse);
     }
 
-    private static async Task<IResult> LogoutAsync(HttpContext http, AuthService auth)
+    /// <summary>这次请求的 WebAuthn 依赖方：配置优先，其次面板对外地址，最后是请求自己的主机。</summary>
+    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;
+        string rpId = !string.IsNullOrWhiteSpace(options.WebAuthnRpId) ? options.WebAuthnRpId.Trim() : configured?.Host ?? http.Request.Host.Host;
+        IEnumerable<string> origins = !string.IsNullOrWhiteSpace(options.WebAuthnOrigins)
+            ? options.WebAuthnOrigins.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries).Select(o => o.TrimEnd('/'))
+            : [configured is null ? own : configured.GetLeftPart(UriPartial.Authority)];
+        return new PasskeyContext(rpId, new HashSet<string>(origins, StringComparer.Ordinal));
+    }
+
+    /// <summary>限流。<paramref name="scope"/> 把「取挑战」和「提交登录」分成两个桶：页面加载取挑战不该占用登录失败的额度。</summary>
+    private static IResult Limited(HttpContext http, LoginRateLimiter limiter, out bool ok, string scope = "", int? limit = null)
+    {
+        string source = scope + (http.ClientAddress());
+        ok = limiter.TryAcquire(source, out int retryAfter, limit);
+        return ok ? TypedResults.NoContent() : Problems.RetryAfter(http, new FleetError(MoShiroErrors.TooManyRequests, "too many sign-in attempts"), retryAfter);
+    }
+
+    /// <summary>取挑战只是页面加载和点按钮，不是猜密码：额度比登录失败宽松，挑战总量另有上限（淘汰最旧的）。</summary>
+    private const int PasskeyOptionsPerMinute = 60;
+
+    private static IResult PasskeyLoginOptions(HttpContext http, PasskeyService passkeys, LoginRateLimiter limiter, BackendOptions options)
+    {
+        IResult limit = Limited(http, limiter, out bool ok, "passkey-options:", limit: PasskeyOptionsPerMinute);
+        if (!ok)
+        {
+            return limit;
+        }
+
+        RequestOptions o = passkeys.BeginLogin(PasskeyContextOf(http, options));
+        http.Response.Headers.CacheControl = "no-store";
+        return TypedResults.Json(new PasskeyRequestOptionsDto(o.Challenge, o.RpId, o.TimeoutMs), ApiJsonContext.Default.PasskeyRequestOptionsDto);
+    }
+
+    private static async Task<IResult> PasskeyLoginAsync(HttpContext http, PasskeyLoginRequest request, PasskeyService passkeys, AuditService audit, LoginRateLimiter limiter, BackendOptions options)
+    {
+        IResult limit = Limited(http, limiter, out bool ok);
+        if (!ok)
+        {
+            return limit;
+        }
+
+        Result<LoginResult> result = await passkeys.LoginAsync(
+            new PasskeyAssertion(request.CredentialId ?? "", request.AuthenticatorData ?? "", request.ClientDataJson ?? "", request.Signature ?? ""), PasskeyContextOf(http, options), http.RequestAborted);
+        string? remote = http.ClientAddress();
+        if (!result.TryGet(out LoginResult? login, out FleetError? error))
+        {
+            await audit.RecordAsync(null, "?", AuthMethods.Passkey, "auth.login", null, null, remote, false, http.RequestAborted);
+            return Problems.From(http, error);
+        }
+
+        await audit.RecordAsync(login.UserId, login.Username, AuthMethods.Passkey, "auth.login", null, null, remote, true, http.RequestAborted);
+        return IssueSession(http, login, request.ReturnSession == true, options);
+    }
+
+    private static async Task<IResult> ListPasskeysAsync(HttpContext http, PasskeyService passkeys)
+    {
+        string userId = http.GetPrincipal().UserId ?? "";
+        IReadOnlyList<PasskeyRecord> list = userId.Length == 0 ? [] : await passkeys.ListAsync(userId, http.RequestAborted);
+        return TypedResults.Json(new PageDto<PasskeyDto>([.. list.Select(Mappers.ToDto)], null), ApiJsonContext.Default.PageDtoPasskeyDto);
+    }
+
+    /// <summary>已经有 passkey 的用户再加一个，要先用已有的触碰一次；第一个 passkey（还没有可触碰的）不要求。</summary>
+    private static async Task<IResult?> CredentialGateAsync(HttpContext http, PasskeyService passkeys, bool consume)
+    {
+        string? userId = http.GetPrincipal().UserId;
+        return userId is null || (await passkeys.ListAsync(userId, http.RequestAborted)).Count == 0 ? null : ElevationGate.Require(http, ElevationClass.Credential, consume);
+    }
+
+    private static async Task<IResult> PasskeyCreationOptionsAsync(HttpContext http, PasskeyService passkeys, BackendOptions options)
+    {
+        if (await CredentialGateAsync(http, passkeys, consume: false) is { } needed)
+        {
+            return needed;
+        }
+
+        Result<CreationOptions> result = await passkeys.BeginRegistrationAsync(http.GetPrincipal(), PasskeyContextOf(http, options), http.RequestAborted);
+        if (!result.TryGet(out CreationOptions? o, out FleetError? error))
+        {
+            return Problems.From(http, error);
+        }
+
+        http.Response.Headers.CacheControl = "no-store";
+        return TypedResults.Json(new PasskeyCreationOptionsDto(o.Challenge, o.RpId, o.RpName, o.UserId, o.UserName, o.ExcludeCredentials, o.TimeoutMs), ApiJsonContext.Default.PasskeyCreationOptionsDto);
+    }
+
+    private static async Task<IResult> RegisterPasskeyAsync(HttpContext http, RegisterPasskeyRequest request, PasskeyService passkeys, BackendOptions options)
+    {
+        if (await CredentialGateAsync(http, passkeys, consume: true) is { } needed)
+        {
+            return needed;
+        }
+
+        Result<PasskeyRecord> result = await passkeys.RegisterAsync(
+            http.GetPrincipal(), new PasskeyRegistration(request.Name ?? "", request.CredentialId ?? "", request.AttestationObject ?? "", request.ClientDataJson ?? "", request.Transports), PasskeyContextOf(http, options), http.RequestAborted);
+        return result.TryGet(out PasskeyRecord? record, out FleetError? error)
+            ? TypedResults.Json(Mappers.ToDto(record), ApiJsonContext.Default.PasskeyDto, statusCode: StatusCodes.Status201Created)
+            : Problems.From(http, error);
+    }
+
+    private static async Task<IResult> DeletePasskeyAsync(HttpContext http, PasskeyService passkeys, string id)
+    {
+        if (ElevationGate.Require(http, ElevationClass.Credential, consume: true) is { } needed)
+        {
+            return needed;
+        }
+
+        return http.GetPrincipal().UserId is { } userId && await passkeys.DeleteAsync(userId, id, http.RequestAborted)
+            ? TypedResults.NoContent()
+            : Problems.Create(http, MoShiroErrors.NotFound, "no such passkey");
+    }
+
+    private static Microsoft.AspNetCore.Http.HttpResults.JsonHttpResult<PageDto<ElevationDto>> ListElevation(HttpContext http, ElevationService elevation)
+    {
+        IReadOnlyList<ElevationWindow> open = http.GetPrincipal().SessionId is { } session ? elevation.Active(session) : [];
+        return TypedResults.Json(new PageDto<ElevationDto>([.. open.Select(Mappers.ToDto)], null), ApiJsonContext.Default.PageDtoElevationDto);
+    }
+
+    private static async Task<IResult> ElevationOptionsAsync(HttpContext http, ElevationRequest request, PasskeyService passkeys, LoginRateLimiter limiter, BackendOptions options)
+    {
+        IResult limit = Limited(http, limiter, out bool ok, "elevation-options:", limit: PasskeyOptionsPerMinute);
+        if (!ok)
+        {
+            return limit;
+        }
+
+        if (!Elevation.TryParse(request.Class, out ElevationClass elevation))
+        {
+            return Problems.From(http, ValidationError.Single("class", "must be enroll, revoke or credential"));
+        }
+
+        Result<RequestOptions> result = await passkeys.BeginElevationAsync(http.GetPrincipal(), elevation, PasskeyContextOf(http, options), http.RequestAborted);
+        if (!result.TryGet(out RequestOptions? o, out FleetError? error))
+        {
+            return Problems.From(http, error);
+        }
+
+        http.Response.Headers.CacheControl = "no-store";
+        return TypedResults.Json(new PasskeyRequestOptionsDto(o.Challenge, o.RpId, o.TimeoutMs, o.AllowCredentials), ApiJsonContext.Default.PasskeyRequestOptionsDto);
+    }
+
+    private static async Task<IResult> ElevateAsync(HttpContext http, ElevationAssertionRequest request, PasskeyService passkeys, AuditService audit, LoginRateLimiter limiter, BackendOptions options)
+    {
+        IResult limit = Limited(http, limiter, out bool ok, "elevation:");
+        if (!ok)
+        {
+            return limit;
+        }
+
+        if (!Elevation.TryParse(request.Class, out ElevationClass elevation))
+        {
+            return Problems.From(http, ValidationError.Single("class", "must be enroll, revoke or credential"));
+        }
+
+        Principal principal = http.GetPrincipal();
+        Result<ElevationWindow> result = await passkeys.ElevateAsync(
+            principal, elevation, new PasskeyAssertion(request.CredentialId ?? "", request.AuthenticatorData ?? "", request.ClientDataJson ?? "", request.Signature ?? ""), PasskeyContextOf(http, options), http.RequestAborted);
+        if (!result.TryGet(out ElevationWindow? window, out FleetError? error))
+        {
+            await audit.RecordAsync(principal, "auth.elevate", null, Elevation.IdOf(elevation), http.ClientAddress(), false, http.RequestAborted);
+            return Problems.From(http, error);
+        }
+
+        http.SetDetail(Elevation.IdOf(elevation));
+        http.Response.Headers.CacheControl = "no-store";
+        return TypedResults.Json(Mappers.ToDto(window), ApiJsonContext.Default.ElevationDto);
+    }
+
+    private static Microsoft.AspNetCore.Http.HttpResults.NoContent EndElevation(HttpContext http, ElevationService elevation)
+    {
+        if (http.GetPrincipal().SessionId is { } session)
+        {
+            elevation.End(session);
+        }
+
+        return TypedResults.NoContent();
+    }
+
+    private static async Task<IResult> LogoutAsync(HttpContext http, AuthService auth, ElevationService elevation)
+    {
+        if (http.GetPrincipal().SessionId is { } own)
+        {
+            elevation.End(own);
+        }
+
         string? bearer = PrincipalResolver.BearerOf(http);
         if (bearer is not null)
         {
@@ -85,7 +320,7 @@ public static class AuthEndpoints
     {
         Principal principal = http.GetPrincipal();
         return TypedResults.Json(
-            new MeDto(principal.Kind.ToString().ToLowerInvariant(), principal.Scope.ToString().ToLowerInvariant(), principal.UserId, principal.Username, principal.CsrfToken),
+            new MeDto(principal.Kind.ToString().ToLowerInvariant(), [.. principal.Capabilities.Order(StringComparer.Ordinal)], principal.UserId, principal.Username, principal.CsrfToken, principal.AuthMethod.Length > 0 ? principal.AuthMethod : null),
             ApiJsonContext.Default.MeDto);
     }
 }

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

@@ -17,17 +17,23 @@ public static class BuildEndpoints
     {
         group.MapGet("/build-info", GetAsync)
             .Api("build_info_get", "Version, tag, commit, build time and update state of the backend and every agent and probe", Tag)
-            .Returns<BuildInfoDto>().ProducesProblems(401, 403);
+            .Returns<BuildInfoDto>().ProducesProblems(401, 403)
+            .Requires(Capability.UpdateRead);
         group.MapGet("/releases", ListReleasesAsync)
-            .Api("releases_list", "The latest signed release manifest of each component", Tag).Returns<PageDto<ReleaseDto>>().ProducesProblems(401, 403);
+            .Api("releases_list", "The latest signed release manifest of each component", Tag).Returns<PageDto<ReleaseDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.UpdateRead);
         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);
+            .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)
+            .Requires(Capability.UpdateConfirm);
         group.MapGet("/backend/update", BackendUpdateAsync)
-            .Api("backend_update_get", "Current channel and host-verified backend update", Tag).Returns<BackendUpdateDto>().ProducesProblems(401, 403);
+            .Api("backend_update_get", "Current channel and host-verified backend update", Tag).Returns<BackendUpdateDto>().ProducesProblems(401, 403)
+            .Requires(Capability.UpdateRead);
         group.MapPost("/backend/update", ConfirmBackendUpdateAsync)
-            .Api("backend_update_confirm", "Confirm one verified backend release before the host restarts it", Tag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(400, 401, 403, 412);
+            .Api("backend_update_confirm", "Confirm one verified backend release before the host restarts it", Tag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(400, 401, 403, 412)
+            .Requires(Capability.UpdateConfirm);
         group.MapGet("/backend/update/live", LiveBackendUpdateAsync)
-            .Api("backend_update_live", "Server-sent backend update notifications", Tag).Produces(StatusCodes.Status200OK, contentType: "text/event-stream").ProducesProblems(401, 403);
+            .Api("backend_update_live", "Server-sent backend update notifications", Tag).Produces(StatusCodes.Status200OK, contentType: "text/event-stream").ProducesProblems(401, 403)
+            .Requires(Capability.UpdateRead);
     }
 
     /// <summary>登记发布清单：挂在 <see cref="ReleaseGuard"/> 下，除了管理员，CI 用的 <c>release</c> 令牌也能调用（它只能做这一件事）。</summary>
@@ -35,7 +41,8 @@ public static class BuildEndpoints
     {
         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);
+            .Returns<ReleaseDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409)
+            .Requires(Capability.ReleasePublish);
     }
 
     private static async Task<IResult> GetAsync(HttpContext http, NodeInfoService nodes, ReleaseService releases, BackendUpdates backendUpdates, CancellationToken ct)

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

@@ -16,14 +16,18 @@ public static class DataEndpoints
     public static void Map(RouteGroupBuilder group)
     {
         group.MapGet("/raw/chunks", ListChunksAsync)
-            .Api("raw_chunks_list", "Raw chunk metadata", Tag).Returns<PageDto<RawChunkMetaDto>>().ProducesProblems(400, 401, 403);
+            .Api("raw_chunks_list", "Raw chunk metadata", Tag).Returns<PageDto<RawChunkMetaDto>>().ProducesProblems(400, 401, 403)
+            .Requires(Capability.DataRead);
         group.MapGet("/raw/chunks/{chunk_id}", DownloadChunkAsync)
             .Api("raw_chunks_get", "Download a raw chunk (application/vnd.moshiro.rawchunk)", Tag)
-            .Produces(StatusCodes.Status200OK, contentType: "application/vnd.moshiro.rawchunk").ProducesProblems(401, 403, 404, 410);
+            .Produces(StatusCodes.Status200OK, contentType: "application/vnd.moshiro.rawchunk").ProducesProblems(401, 403, 404, 410)
+            .Requires(Capability.DataRead);
         group.MapGet("/events", ListEventsAsync)
-            .Api("events_list", "Agent events", Tag).Returns<PageDto<EventDto>>().ProducesProblems(400, 401, 403);
+            .Api("events_list", "Agent events", Tag).Returns<PageDto<EventDto>>().ProducesProblems(400, 401, 403)
+            .Requires(Capability.EventsRead);
         group.MapGet("/analysis/recompute", RecomputeAsync)
-            .Api("analysis_recompute_get", "Progress of the metric backfill", Tag).Returns<RecomputeDto>().ProducesProblems(401, 403);
+            .Api("analysis_recompute_get", "Progress of the metric backfill", Tag).Returns<RecomputeDto>().ProducesProblems(401, 403)
+            .Requires(Capability.DataWrite);
     }
 
     private static async Task<IResult> ListChunksAsync(

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

@@ -15,9 +15,11 @@ public static class LinkEndpoints
     public static void Map(RouteGroupBuilder group)
     {
         group.MapGet("/links", ListAsync)
-            .Api("links_list", "Every probe/agent pair: whether it is linked, the manual override and whether it is connected", Tag).Returns<LinkMatrixDto>().ProducesProblems(401, 403);
+            .Api("links_list", "Every probe/agent pair: whether it is linked, the manual override and whether it is connected", Tag).Returns<LinkMatrixDto>().ProducesProblems(401, 403)
+            .Requires(Capability.FleetRead);
         group.MapPut("/links/{probe_id}/{agent_id}", SetAsync)
-            .Api("links_set", "Force a link on or off, or give it back to the automatic setting (enabled: null)", Tag).Returns<LinkDto>().ProducesProblems(400, 401, 403, 404);
+            .Api("links_set", "Force a link on or off, or give it back to the automatic setting (enabled: null)", Tag).Returns<LinkDto>().ProducesProblems(400, 401, 403, 404)
+            .Requires(Capability.FleetWrite);
     }
 
     private static async Task<IResult> ListAsync(AgentService agents, ProbeService probes, LinkService links, CancellationToken ct)

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

@@ -18,33 +18,59 @@ public static class SystemEndpoints
     public static void Map(RouteGroupBuilder group)
     {
         group.MapGet("/api-tokens", ListTokensAsync)
-            .Api("api_tokens_list", "API tokens", TokensTag).Returns<PageDto<ApiTokenDto>>().ProducesProblems(401, 403);
+            .Api("api_tokens_list", "API tokens", TokensTag).Returns<PageDto<ApiTokenDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.KeysRead);
         group.MapPost("/api-tokens", CreateTokenAsync)
-            .Api("api_tokens_create", "Create an API token (scope read or admin); the plaintext is returned only once", TokensTag)
-            .Returns<CreatedApiTokenDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403);
+            .Api("api_tokens_create", "Create an API token with the chosen capabilities (a subset of your own); the plaintext is returned only once", TokensTag)
+            .Returns<CreatedApiTokenDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403)
+            .Requires(Capability.KeysManage);
         group.MapDelete("/api-tokens/{id}", RevokeTokenAsync)
-            .Api("api_tokens_revoke", "Revoke an API token", TokensTag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403);
+            .Api("api_tokens_revoke", "Revoke an API token", TokensTag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403)
+            .Requires(Capability.KeysManage);
+
+        group.MapGet("/capabilities", CapabilitiesAsync)
+            .Api("capabilities_list", "The capability catalog: groups, which ones change trust, which are reserved, and the presets", TokensTag)
+            .Returns<CapabilityCatalogDto>().ProducesProblems(401, 403)
+            .Requires(Capability.KeysRead);
 
         group.MapGet("/settings", ListSettingsAsync)
-            .Api("settings_list", "Site settings and retention periods", SettingsTag).Returns<PageDto<SettingDto>>().ProducesProblems(401, 403);
+            .Api("settings_list", "Site settings and retention periods", SettingsTag).Returns<PageDto<SettingDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.SettingsRead);
         group.MapPatch("/settings", PatchSettingsAsync)
             .Accepts<Dictionary<string, JsonElement>>("application/merge-patch+json", "application/json")
-            .Api("settings_update", "Change settings (merge-patch)", SettingsTag).Returns<PageDto<SettingDto>>().ProducesProblems(400, 401, 403);
+            .Api("settings_update", "Change settings (merge-patch)", SettingsTag).Returns<PageDto<SettingDto>>().ProducesProblems(400, 401, 403)
+            .Requires(Capability.SettingsWrite);
 
         group.MapGet("/users", ListUsersAsync)
-            .Api("users_list", "Panel users", UsersTag).Returns<PageDto<UserDto>>().ProducesProblems(401, 403);
+            .Api("users_list", "Panel users", UsersTag).Returns<PageDto<UserDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.AccountsRead);
         group.MapPost("/users", CreateUserAsync)
-            .Api("users_create", "Create a panel user", UsersTag).Returns<UserDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409);
+            .Api("users_create", "Create a panel user", UsersTag).Returns<UserDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 409)
+            .Requires(Capability.AccountsManage);
         group.MapPatch("/users/{id}", ChangePasswordAsync)
-            .Api("users_update", "Change a user's password", UsersTag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(400, 401, 403);
+            .Api("users_update", "Change a user's password", UsersTag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(400, 401, 403)
+            .Requires(Capability.AccountsManage);
     }
 
+    private static Microsoft.AspNetCore.Http.HttpResults.JsonHttpResult<CapabilityCatalogDto> CapabilitiesAsync() =>
+        TypedResults.Json(
+            new CapabilityCatalogDto(
+                [.. CapabilityCatalog.Groups.Select(g => new CapabilityGroupDto(g, [.. CapabilityCatalog.All.Where(c => c.Group == g).Select(c => new CapabilityDto(c.Id, c.Trust, c.Reserved, c.Implies))]))],
+                [.. CapabilityCatalog.Presets.Select(p => new CapabilityPresetDto(p.Id, p.Capabilities))]),
+            ApiJsonContext.Default.CapabilityCatalogDto);
+
     private static async Task<IResult> ListTokensAsync(AuthService auth, CancellationToken ct) =>
         TypedResults.Json(new PageDto<ApiTokenDto>([.. (await auth.ListApiTokensAsync(ct)).Select(Mappers.ToDto)], null), ApiJsonContext.Default.PageDtoApiTokenDto);
 
     private static async Task<IResult> CreateTokenAsync(HttpContext http, AuthService auth, CreateApiTokenRequest request)
     {
-        Result<CreatedApiToken> result = await auth.CreateApiTokenAsync(request.Name ?? "", request.Scope ?? "", http.RequestAborted);
+        if (CapabilityCatalog.Expand(request.Capabilities ?? []).Any(c => CapabilityCatalog.Find(c)?.Trust == true) && ElevationGate.Require(http, ElevationClass.Credential, consume: true) is { } needed)
+        {
+            return needed; // 带信任类能力的 API key 等于把信任操作交给一份密钥：创建它要用 passkey 签一次
+        }
+
+        http.SetDetail($"{request.Name}: {string.Join(',', request.Capabilities ?? [])}");
+        Result<CreatedApiToken> result = await auth.CreateApiTokenAsync(request.Name ?? "", request.Capabilities ?? [], request.ExpiresInDays, http.GetPrincipal(), http.RequestAborted);
         if (!result.TryGet(out CreatedApiToken? created, out FleetError? error))
         {
             return Problems.From(http, error);

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

@@ -16,26 +16,34 @@ public static class TaskEndpoints
     public static void Map(RouteGroupBuilder group)
     {
         group.MapGet("/tasks", ListAsync)
-            .Api("tasks_list", "Tasks: line templates, per-agent overrides and target tasks", TasksTag).Returns<PageDto<TaskDto>>().ProducesProblems(401, 403);
+            .Api("tasks_list", "Tasks: line templates, per-agent overrides and target tasks", TasksTag).Returns<PageDto<TaskDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.TasksRead);
         group.MapPost("/tasks", CreateAsync)
             .Api("tasks_create", "Create a task; params are validated against the kind", TasksTag)
-            .Returns<TaskDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 404);
+            .Returns<TaskDto>(StatusCodes.Status201Created).ProducesProblems(400, 401, 403, 404)
+            .Requires(Capability.TasksWrite);
         group.MapGet("/tasks/{id}", GetAsync)
-            .Api("tasks_get", "One task", TasksTag).Returns<TaskDto>().ProducesProblems(401, 403, 404);
+            .Api("tasks_get", "One task", TasksTag).Returns<TaskDto>().ProducesProblems(401, 403, 404)
+            .Requires(Capability.TasksRead);
         group.MapPatch("/tasks/{id}", PatchAsync)
             .Accepts<PatchTaskRequest>("application/merge-patch+json", "application/json")
             .Api("tasks_update", "Change params, schedule, target or enabled (merge-patch, If-Match supported)", TasksTag)
-            .Returns<TaskDto>().ProducesProblems(400, 401, 403, 404, 412);
+            .Returns<TaskDto>().ProducesProblems(400, 401, 403, 404, 412)
+            .Requires(Capability.TasksWrite);
         group.MapDelete("/tasks/{id}", DeleteAsync)
-            .Api("tasks_delete", "Delete a task", TasksTag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403);
+            .Api("tasks_delete", "Delete a task", TasksTag).Returns<object>(StatusCodes.Status204NoContent).ProducesProblems(401, 403)
+            .Requires(Capability.TasksWrite);
 
         group.MapPost("/lines/{line_id}/tests", StartTestAsync)
             .Api("tests_start", "Start an on-demand test on a line", TestsTag)
-            .Returns<TestDto>(StatusCodes.Status202Accepted).ProducesProblems(400, 401, 403, 404, 409);
+            .Returns<TestDto>(StatusCodes.Status202Accepted).ProducesProblems(400, 401, 403, 404, 409)
+            .Requires(Capability.TasksWrite);
         group.MapGet("/lines/{line_id}/tests", ListTestsAsync)
-            .Api("tests_list", "Recent tests of a line", TestsTag).Returns<PageDto<TestDto>>().ProducesProblems(401, 403);
+            .Api("tests_list", "Recent tests of a line", TestsTag).Returns<PageDto<TestDto>>().ProducesProblems(401, 403)
+            .Requires(Capability.TasksRead);
         group.MapPost("/tests/{id}/cancel", CancelAsync)
-            .Api("tests_cancel", "Cancel a running test", TestsTag).Returns<TestDto>().ProducesProblems(401, 403, 404);
+            .Api("tests_cancel", "Cancel a running test", TestsTag).Returns<TestDto>().ProducesProblems(401, 403, 404)
+            .Requires(Capability.TasksWrite);
     }
 
     private static async Task<IResult> ListAsync(TaskService tasks, string? agent_id, string? scope, CancellationToken ct)

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

@@ -0,0 +1,79 @@
+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();
+    }
+
+    private static async Task<IResult> StateAsync(HttpContext http, TrustService trust, ReleaseService releases, BackendOptions options)
+    {
+        TrustState state = await trust.StateAsync(AuthEndpoints.PasskeyContextOf(http, options), http.RequestAborted);
+        http.Response.Headers.CacheControl = "no-store";
+        string sh = InstallScripts.Sha256(InstallScripts.Sh);
+        string ps1 = InstallScripts.Sha256(InstallScripts.Ps1);
+        return TypedResults.Json(Mappers.ToDto(state, options.PublicUrl ?? $"{http.Request.Scheme}://{http.Request.Host}", sh, ps1, await MatchesReleaseAsync(releases, sh, ps1, http.RequestAborted)), ApiJsonContext.Default.TrustStateDto);
+    }
+
+    /// <summary>面板提供的脚本和 CI 签名的发布清单里记的哈希是否一致（清单由 CI 签名，节点和浏览器之外的人改不了）。没有清单或没记哈希时返回 null。</summary>
+    private static async Task<bool?> MatchesReleaseAsync(ReleaseService releases, string sh, string ps1, CancellationToken ct)
+    {
+        foreach (string component in new[] { JoinTokenService.AgentRole, JoinTokenService.ProbeRole })
+        {
+            if (await releases.GetAsync(component, ct) is not { } offer)
+            {
+                continue;
+            }
+
+            using System.Text.Json.JsonDocument document = System.Text.Json.JsonDocument.Parse(offer.Manifest);
+            if (document.RootElement.TryGetProperty("install_sh", out System.Text.Json.JsonElement recordedSh) && document.RootElement.TryGetProperty("install_ps1", out System.Text.Json.JsonElement recordedPs1))
+            {
+                return string.Equals(recordedSh.GetString(), sh, StringComparison.Ordinal) && string.Equals(recordedPs1.GetString(), ps1, StringComparison.Ordinal);
+            }
+        }
+
+        return null;
+    }
+
+    private static async Task<IResult> CommitAsync(HttpContext http, SignedStatementDto signed, TrustService trust, AgentService agents, 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);
+        }
+
+        await agents.AfterAgentSetChangedAsync(http.RequestAborted); // 新的操作员集合要随名册下发给节点
+        http.SetDetail($"operator set v{state.Version}");
+        return TypedResults.Json(Mappers.ToDto(state), ApiJsonContext.Default.TrustStateDto, statusCode: StatusCodes.Status201Created);
+    }
+}

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

@@ -18,6 +18,7 @@ public static class ApiModule
     public static IServiceCollection AddMoShiroApi(this IServiceCollection services)
     {
         services.AddSingleton<SseLimiter>();
+        services.AddSingleton<ClientAddressResolver>();
         services.Configure<JsonOptions>(options =>
         {
             JsonSerializerOptions json = options.SerializerOptions;
@@ -103,13 +104,15 @@ public static class ApiModule
         RouteGroupBuilder admin = app.MapGroup("/api/admin");
         AuthEndpoints.MapLogin(admin);
 
-        BuildEndpoints.MapPublish(admin.MapGroup(string.Empty).AddEndpointFilter(ReleaseGuard.InvokeAsync));
+        BuildEndpoints.MapPublish(admin.MapGroup(string.Empty).AddEndpointFilter(CapabilityGuard.InvokeAsync));
 
-        RouteGroupBuilder guarded = admin.MapGroup(string.Empty).AddEndpointFilter(AdminGuard.InvokeAsync);
+        RouteGroupBuilder guarded = admin.MapGroup(string.Empty).AddEndpointFilter(CapabilityGuard.InvokeAsync);
         AuthEndpoints.MapSession(guarded);
         AgentEndpoints.Map(guarded);
         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/ClientAddress.cs

@@ -0,0 +1,80 @@
+using System.Net;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+using MoShiro.Backend.Application;
+
+namespace MoShiro.Backend.Api;
+
+/// <summary>
+/// 请求的真实来源地址。后端前面通常有反向代理（Cloudflare、frp、Caddy），套接字上看到的是最近一跳；
+/// 只有配置了 <see cref="BackendOptions.TrustedProxies"/>，并且连进来的正是其中之一，才相信转发头，
+/// 且从右往左跳过所有可信代理，取第一个不可信的地址（客户端自己伪造的在最左边，不会被采信）。
+/// 没配置就一律用套接字地址：宁可限流和审计里是代理的地址，也不让客户端自己报地址。
+/// </summary>
+public sealed class ClientAddressResolver
+{
+    private readonly IPNetwork[] _trusted;
+    private readonly string _header;
+
+    public ClientAddressResolver(BackendOptions options)
+    {
+        _header = string.IsNullOrWhiteSpace(options.TrustedProxyHeader) ? "X-Forwarded-For" : options.TrustedProxyHeader.Trim();
+        _trusted = [.. (options.TrustedProxies ?? "").Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries).Select(ParseNetwork)];
+    }
+
+    private static IPNetwork ParseNetwork(string text)
+    {
+        if (IPNetwork.TryParse(text, out IPNetwork network))
+        {
+            return network;
+        }
+
+        if (IPAddress.TryParse(text, out IPAddress? single))
+        {
+            return new IPNetwork(single, single.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork ? 32 : 128);
+        }
+
+        throw new InvalidOperationException($"TrustedProxies: '{text}' is not an IP address or CIDR range");
+    }
+
+    private bool IsTrusted(IPAddress address)
+    {
+        IPAddress normalized = address.IsIPv4MappedToIPv6 ? address.MapToIPv4() : address;
+        return _trusted.Any(n => n.Contains(normalized));
+    }
+
+    public string Resolve(HttpContext http)
+    {
+        IPAddress? remote = http.Connection.RemoteIpAddress;
+        if (remote is null)
+        {
+            return "unknown";
+        }
+
+        if (_trusted.Length == 0 || !IsTrusted(remote))
+        {
+            return remote.ToString();
+        }
+
+        string[] chain = [.. http.Request.Headers[_header].SelectMany(v => (v ?? "").Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))];
+        for (int i = chain.Length - 1; i >= 0; i--)
+        {
+            if (!IPAddress.TryParse(chain[i], out IPAddress? hop))
+            {
+                break; // 不是地址就不信这条头
+            }
+
+            if (!IsTrusted(hop))
+            {
+                return hop.ToString();
+            }
+        }
+
+        return remote.ToString();
+    }
+}
+
+public static class ClientAddressExtensions
+{
+    public static string ClientAddress(this HttpContext http) => http.RequestServices.GetRequiredService<ClientAddressResolver>().Resolve(http);
+}

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

@@ -9,6 +9,24 @@ public static class EndpointConventions
     public static RouteHandlerBuilder Api(this RouteHandlerBuilder builder, string operationId, string summary, string tag) =>
         builder.WithName(operationId).WithSummary(summary).WithTags(tag);
 
+    /// <summary>声明端点需要的能力（授权的唯一依据）；OpenAPI 里带上 <c>x-moshiro-capability</c>。</summary>
+    public static RouteHandlerBuilder Requires(this RouteHandlerBuilder builder, string capability) =>
+        builder.WithMetadata(new CapabilityRequirement(capability)).AddOpenApiOperationTransformer((operation, _, _) =>
+        {
+            operation.Extensions ??= new Dictionary<string, Microsoft.OpenApi.IOpenApiExtension>();
+            operation.Extensions["x-moshiro-capability"] = new Microsoft.OpenApi.JsonNodeExtension(System.Text.Json.Nodes.JsonValue.Create(capability));
+            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));
+
     public static RouteHandlerBuilder Returns<T>(this RouteHandlerBuilder builder, int status = StatusCodes.Status200OK) =>
         builder.Produces<T>(status);
 

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

@@ -1,4 +1,5 @@
 using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.DependencyInjection;
 using MoShiro.Backend.Application;
 using MoShiro.Protocol;
@@ -53,17 +54,32 @@ public static class PrincipalResolver
     }
 }
 
-/// <summary>管理层守卫：需要 admin 作用域；Cookie 会话的非 GET 请求必须带 <c>X-CSRF-Token</c>。</summary>
-public static class AdminGuard
+/// <summary>
+/// 端点声明自己需要的能力（<see cref="EndpointConventions.Requires"/>）。<c>Capability == null</c> 表示匿名可访问（登录）。
+/// 没有声明的 <c>/api/admin</c> 端点一律拒绝（并有对账测试保证不存在）。
+/// </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
 {
     public static async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
     {
         HttpContext http = context.HttpContext;
-        Principal principal = http.GetPrincipal();
-        if (!principal.IsAdmin)
+        CapabilityRequirement? requirement = http.GetEndpoint()?.Metadata.GetMetadata<CapabilityRequirement>();
+        if (requirement is null)
         {
-            return principal.Scope != ApiScope.None
-                ? Problems.Create(http, MoShiroErrors.Forbidden, "the token scope does not allow this operation")
+            return Problems.Create(http, MoShiroErrors.Forbidden, "this endpoint has no capability declaration");
+        }
+
+        Principal principal = http.GetPrincipal();
+        if (requirement.Capability is { } capability && !principal.Has(capability))
+        {
+            return principal.Kind != PrincipalKind.Anonymous
+                ? Problems.Create(http, MoShiroErrors.Forbidden, "the credential lacks the capability: " + capability)
                 : Problems.Create(http, MoShiroErrors.Unauthorized, "authentication is required");
         }
 
@@ -76,15 +92,50 @@ public static class AdminGuard
             }
         }
 
+        // 信任类的操作（加节点、吊销、改凭证）：登录用户还要有这一种的提权窗口；API key 自己带着能力，不经过这里
+        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;
+        }
+
+        if (principal.Kind != PrincipalKind.Anonymous && !HttpMethods.IsGet(http.Request.Method) && !HttpMethods.IsHead(http.Request.Method) && !HttpMethods.IsOptions(http.Request.Method))
+        {
+            // 写操作都记审计：响应发完之后才知道结果，所以放在 OnCompleted 里
+            string action = http.GetEndpoint()?.Metadata.GetMetadata<IEndpointNameMetadata>()?.EndpointName ?? http.Request.Path.Value ?? "";
+            if (action.EndsWith("_options", StringComparison.Ordinal))
+            {
+                return await next(context); // 取挑战不是操作
+            }
+
+            string? target = http.Request.RouteValues.Count == 0 ? null : string.Join(' ', http.Request.RouteValues.Where(v => v.Value is not null).Select(v => v.Key + "=" + v.Value));
+            http.Response.OnCompleted(() =>
+            {
+                http.Items.TryGetValue(AuditEndpoints.DetailItem, out object? detail);
+                return http.RequestServices.GetRequiredService<AuditService>()
+                    .RecordAsync(principal, action, target, detail as string, http.ClientAddress(), http.Response.StatusCode < 400).AsTask();
+            });
+        }
+
         return await next(context);
     }
 }
 
-/// <summary>登记发布清单的守卫：管理员（会话要带 CSRF）或 release 令牌；release 令牌只能做这一件事。</summary>
-public static class ReleaseGuard
+/// <summary>提权检查：登录用户（含用 return_session 拿到的 Bearer 会话）要有对应种类的有效窗口，API key 不需要。</summary>
+public static class ElevationGate
 {
-    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>没问题返回 null；否则 403 <c>elevation_required</c>，detail 是缺的窗口种类，前端据此触碰 passkey 后重试。</summary>
+    public static IResult? Require(HttpContext http, ElevationClass elevation, bool consume)
+    {
+        Principal principal = http.GetPrincipal();
+        if (principal.UserId is null)
+        {
+            return null;
+        }
+
+        return principal.SessionId is { } session && http.RequestServices.GetRequiredService<ElevationService>().Check(session, elevation, consume)
+            ? null
+            : Problems.Create(http, MoShiroErrors.ElevationRequired, Elevation.IdOf(elevation));
+    }
 }
 
 /// <summary>展示层守卫：站点公开时匿名可读；私有时需要登录或只读令牌。</summary>
@@ -93,7 +144,7 @@ public static class PublicGuard
     public static async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
     {
         HttpContext http = context.HttpContext;
-        if (!http.GetPrincipal().CanRead && !await http.RequestServices.GetRequiredService<SettingsService>().IsSitePublicAsync(http.RequestAborted))
+        if (!http.GetPrincipal().Has(Capability.PublicRead) && !await http.RequestServices.GetRequiredService<SettingsService>().IsSitePublicAsync(http.RequestAborted))
         {
             return Problems.Create(http, MoShiroErrors.SitePrivate, "this site is private; sign in or use a read-only token");
         }
@@ -102,5 +153,5 @@ public static class PublicGuard
     }
 
     /// <summary>被隐藏（public_visible = false）的线路只对已认证的访问者可见。</summary>
-    public static bool CanSeeHidden(HttpContext http) => http.GetPrincipal().CanRead;
+    public static bool CanSeeHidden(HttpContext http) => http.GetPrincipal().Has(Capability.PublicRead);
 }

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

@@ -41,7 +41,7 @@ public static class Mappers
     public static ProbeDto ToDto(ProbeView v) =>
         new(
             v.Probe.Id, v.Probe.Name, Time(v.Probe.CreatedAtMs), Time(v.Probe.RevokedAtMs), v.Revoked, v.Online,
-            [.. v.Connections.Select(c => new ProbeConnectionDto(c.AgentId.Value, c.AgentName, c.AgentOnline, c.Version, c.Remote, Time(c.SinceMs), c.IpVersion))], ProbeIpv6Of(v.Probe));
+            [.. v.Connections.Select(c => new ProbeConnectionDto(c.AgentId.Value, c.AgentName, c.AgentOnline, c.Version, c.Remote, Time(c.SinceMs), c.IpVersion))], ProbeIpv6Of(v.Probe), v.Probe.AddedBy);
 
     public static SeriesDto ToDto(SeriesResult r, bool live) =>
         new(
@@ -103,7 +103,7 @@ public static class Mappers
             : null;
         return new AgentDto(
             a.Id.Value, a.Name, StatusName(a.Status), view.Online, view.ProbeConnected, [.. view.Probes.Select(ToDto)], view.Host is null ? null : ToDto(view.Host), a.PublicHost, a.ProbeTcpPort, a.ProbeUdpPorts, a.Labels, a.PublicVisible,
-            a.Kinds, a.AgentVersion, limits, a.TaskVersion, a.AppliedTaskVersion, rejected, heartbeat, view.EndpointChanges, Time(a.CreatedAtMs), Time(a.LastSeenAtMs), a.Ipv6Host, a.Ipv6Supported, Ipv6Of(view), !a.PublicHostManual, !a.Ipv6HostManual);
+            a.Kinds, a.AgentVersion, limits, a.TaskVersion, a.AppliedTaskVersion, rejected, heartbeat, view.EndpointChanges, Time(a.CreatedAtMs), Time(a.LastSeenAtMs), a.Ipv6Host, a.Ipv6Supported, Ipv6Of(view), !a.PublicHostManual, !a.Ipv6HostManual, a.AddedBy);
     }
 
     public static Ipv6DiagnosticDto Ipv6Of(AgentView view)
@@ -154,9 +154,17 @@ 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));
+        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);
 
-    public static ApiTokenDto ToDto(ApiTokenRecord t) => new(t.Id, t.Name, t.Scope, Time(t.CreatedAtMs), Time(t.LastUsedAtMs), Time(t.RevokedAtMs));
+    public static TrustStateDto ToDto(TrustState s, string installUrl = "", string installSh = "", string installPs1 = "", bool? matches = null) => 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), installUrl, s.Operators ?? [], installSh, installPs1, matches, s.ServerKey, s.ServerKeyListed);
+
+    public static ElevationDto ToDto(ElevationWindow w) => new(Elevation.IdOf(w.Class), Time(w.ExpiresAtMs));
+
+    public static AuditDto ToDto(AuditRecord a) => new(a.Id, Time(a.AtMs), a.Actor, a.Method, a.Action, a.Target, a.Detail, a.Remote, a.Success);
+
+    public static PasskeyDto ToDto(PasskeyRecord p) => new(p.Id, p.Name, Time(p.CreatedAtMs), Time(p.LastUsedAtMs), p.Transports);
+
+    public static ApiTokenDto ToDto(ApiTokenRecord t) => new(t.Id, t.Name, t.Capabilities, Time(t.CreatedAtMs), Time(t.LastUsedAtMs), Time(t.ExpiresAtMs), Time(t.RevokedAtMs));
 
     public static RawChunkMetaDto ToDto(RawChunkMeta m) =>
         new(m.ChunkId.ToString(), m.AgentId.Value, m.Series, m.Kind, m.TaskId?.Value, m.TestId?.Value, m.Phase, Time(m.StartTs), m.DurationMs, m.Partial, m.Length);

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

@@ -46,7 +46,7 @@ public static class ErrorCodeHttpMap
 
         Add(400, MoShiroErrors.ValidationFailed, MoShiroErrors.BudgetExceeded, FleetErrors.InvalidParams);
         Add(401, MoShiroErrors.Unauthorized, MoShiroErrors.CsrfFailed, FleetErrors.Unauthorized);
-        Add(403, MoShiroErrors.Forbidden, MoShiroErrors.SitePrivate, FleetErrors.Forbidden, FleetErrors.ProofInvalid);
+        Add(403, MoShiroErrors.Forbidden, MoShiroErrors.SitePrivate, MoShiroErrors.ElevationRequired, FleetErrors.Forbidden, FleetErrors.ProofInvalid);
         Add(
             404, MoShiroErrors.NotFound, MoShiroErrors.AgentNotFound, MoShiroErrors.ProbeNotFound, MoShiroErrors.TaskNotFound, MoShiroErrors.TestNotFound, MoShiroErrors.ChunkNotFound,
             MoShiroErrors.TokenNotFound, MoShiroErrors.UnknownKind, MoShiroErrors.UnknownPlan, FleetErrors.NotFound);

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

@@ -1,3 +1,4 @@
+using Fleet.Core;
 using System.Text.Json;
 
 namespace MoShiro.Backend.Api;
@@ -5,9 +6,30 @@ namespace MoShiro.Backend.Api;
 /// <summary><c>return_session</c>：跨域的前端用——不设 Cookie，把会话令牌放在响应里，之后用 <c>Authorization: Bearer</c> 带上。</summary>
 public sealed record LoginRequest(string Username, string Password, bool? ReturnSession);
 
+/// <summary>浏览器 <c>navigator.credentials.create</c> 要的参数；二进制字段都是 base64url。</summary>
+public sealed record PasskeyCreationOptionsDto(string Challenge, string RpId, string RpName, string UserId, string UserName, IReadOnlyList<string> ExcludeCredentials, int TimeoutMs);
+
+/// <summary>浏览器 <c>navigator.credentials.get</c> 要的参数（可发现凭证：不需要先输用户名）。</summary>
+/// <param name="AllowCredentials">只有提权的挑战会带：这个用户自己的 passkey 的凭证 id。</param>
+public sealed record PasskeyRequestOptionsDto(string Challenge, string RpId, int TimeoutMs, IReadOnlyList<string>? AllowCredentials = null);
+
+/// <param name="Class"><c>enroll</c>（加节点）、<c>revoke</c>（吊销和删除）、<c>credential</c>（改凭证，用一次就没有）。</param>
+public sealed record ElevationRequest(string Class);
+
+public sealed record ElevationAssertionRequest(string Class, string CredentialId, string AuthenticatorData, string ClientDataJson, string Signature);
+
+public sealed record ElevationDto(string Class, DateTimeOffset ExpiresAt);
+
+public sealed record RegisterPasskeyRequest(string Name, string CredentialId, string AttestationObject, string ClientDataJson, IReadOnlyList<string>? Transports);
+
+public sealed record PasskeyLoginRequest(string CredentialId, string AuthenticatorData, string ClientDataJson, string Signature, bool? ReturnSession);
+
+public sealed record PasskeyDto(string Id, string Name, DateTimeOffset CreatedAt, DateTimeOffset? LastUsedAt, IReadOnlyList<string> Transports);
+
 public sealed record LoginResponse(string UserId, string Username, string CsrfToken, DateTimeOffset ExpiresAt, string? SessionToken);
 
-public sealed record MeDto(string Kind, string Scope, string? UserId, string? Username, string? CsrfToken);
+/// <param name="AuthMethod">会话是怎么登录的：<c>password</c>（没有任何能力，只能注册 passkey）或 <c>passkey</c>；API 令牌为空。</param>
+public sealed record MeDto(string Kind, IReadOnlyList<string> Capabilities, string? UserId, string? Username, string? CsrfToken, string? AuthMethod = null);
 
 public sealed record LocalLimitsDto(double MaxTotalMbps, long MaxTotalPps, IReadOnlyList<string> AllowedTargetCidrs, int MaxConcurrentTests);
 
@@ -42,7 +64,8 @@ public sealed record AgentDto(
     bool Ipv6Supported = false,
     Ipv6DiagnosticDto? Ipv6 = null,
     bool PublicHostAuto = true,
-    bool Ipv6HostAuto = true);
+    bool Ipv6HostAuto = true,
+    string? AddedBy = null);
 
 public sealed record Ipv6DiagnosticDto(bool? AddressConfigured, bool SocketSupported, bool? Listening, bool? HasGlobalAddress, bool? HasDefaultRoute, string State,
     string NetworkScope = "unknown", bool? HostHasGlobalAddress = null, bool? HostHasDefaultRoute = null);
@@ -52,13 +75,24 @@ 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");
+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 CreateJoinTokenRequest(string? Note, IReadOnlyList<string>? Labels, bool? AutoApprove, int? MaxUses, int? ExpiresInHours, string? Role = null);
+/// <param name="Controllers">属主：允许授权这个节点 extension 会话的 passkey 凭证 id（必须是操作员集合里的）；缺省是集合里的全部。没有建立信任根时忽略。</param>
+public sealed record CreateJoinTokenRequest(string? Note, IReadOnlyList<string>? Labels, bool? AutoApprove, int? MaxUses, int? ExpiresInHours, string? Role = null, IReadOnlyList<string>? Controllers = null);
 
 /// <summary>令牌明文只在创建的响应里出现一次。</summary>
 public sealed record InstallCommandsDto(string Linux, string Macos, string Windows);
 
+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>
+/// <param name="Operators">当前操作员集合里的 passkey 凭证 id：加入码的 <c>controllers</c> 只能从这里选。</param>
+/// <param name="InstallShSha256">面板提供的安装脚本的 SHA-256（命令里核对的就是它）。</param>
+/// <param name="InstallMatchesRelease">和 CI 签名的发布清单里记的哈希是否一致；没有清单或清单里没记时为空。不一致说明这个面板提供的脚本不是 CI 构建出来的那份。</param>
+public sealed record TrustStateDto(bool Initialized, string? Genesis, int Version, bool InSync, TrustProposalDto? Proposal, string InstallUrl = "", IReadOnlyList<string>? Operators = null, string InstallShSha256 = "", string InstallPs1Sha256 = "", bool? InstallMatchesRelease = null, string ServerKey = "", bool ServerKeyListed = false);
+
 public sealed record CreatedJoinTokenDto(JoinTokenDto Token, string Plaintext, InstallCommandsDto InstallCommands);
 
 /// <summary>Agent 眼中连着的一个 Probe（Agent 上报）。</summary>
@@ -67,7 +101,7 @@ public sealed record ConnectedProbeDto(string ProbeId, string? Version, string?
 /// <summary>某个 Probe 现在连着的一个 Agent。</summary>
 public sealed record ProbeConnectionDto(string AgentId, string AgentName, bool AgentOnline, string? Version, string? Remote, DateTimeOffset ConnectedSince, string IpVersion = "ipv4");
 
-public sealed record ProbeDto(string Id, string Name, DateTimeOffset CreatedAt, DateTimeOffset? RevokedAt, bool Revoked, bool Online, IReadOnlyList<ProbeConnectionDto> Connections, Ipv6DiagnosticDto? Ipv6 = null);
+public sealed record ProbeDto(string Id, string Name, DateTimeOffset CreatedAt, DateTimeOffset? RevokedAt, bool Revoked, bool Online, IReadOnlyList<ProbeConnectionDto> Connections, Ipv6DiagnosticDto? Ipv6 = null, string? AddedBy = null);
 
 /// <summary>一对（Probe，Agent）的线路开关：<c>linked</c> 是最终结果，<c>override</c> 是手动设置（<c>null</c> = 跟随自动连接），<c>connected</c> 是现在有没有连着。</summary>
 public sealed record LinkDto(string ProbeId, string ProbeName, string AgentId, string AgentName, bool Linked, bool? Override, bool Connected);
@@ -117,9 +151,19 @@ public sealed record RawChunkMetaDto(
     bool Partial,
     int Bytes);
 
-public sealed record ApiTokenDto(string Id, string Name, string Scope, DateTimeOffset CreatedAt, DateTimeOffset? LastUsedAt, DateTimeOffset? RevokedAt);
+public sealed record ApiTokenDto(string Id, string Name, IReadOnlyList<string> Capabilities, DateTimeOffset CreatedAt, DateTimeOffset? LastUsedAt, DateTimeOffset? ExpiresAt, DateTimeOffset? RevokedAt);
 
-public sealed record CreateApiTokenRequest(string Name, string Scope);
+/// <param name="Capabilities">能力列表（见 /api/admin/capabilities）；写蕴含读，只能是创建者自己拥有能力的子集。</param>
+/// <param name="ExpiresInDays">有效天数；缺省不过期。</param>
+public sealed record CreateApiTokenRequest(string Name, IReadOnlyList<string> Capabilities, int? ExpiresInDays = null);
+
+public sealed record CapabilityDto(string Id, bool Trust, bool Reserved, IReadOnlyList<string> Implies);
+
+public sealed record CapabilityGroupDto(string Id, IReadOnlyList<CapabilityDto> Capabilities);
+
+public sealed record CapabilityPresetDto(string Id, IReadOnlyList<string> Capabilities);
+
+public sealed record CapabilityCatalogDto(IReadOnlyList<CapabilityGroupDto> Groups, IReadOnlyList<CapabilityPresetDto> Presets);
 
 public sealed record CreatedApiTokenDto(ApiTokenDto Token, string Plaintext);
 

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

@@ -70,9 +70,23 @@ namespace MoShiro.Backend.Api;
 [JsonSerializable(typeof(RawChunkMetaDto))]
 [JsonSerializable(typeof(PageDto<RawChunkMetaDto>))]
 [JsonSerializable(typeof(PageDto<EventDto>))]
+[JsonSerializable(typeof(PageDto<AuditDto>))]
 [JsonSerializable(typeof(ApiTokenDto))]
 [JsonSerializable(typeof(PageDto<ApiTokenDto>))]
 [JsonSerializable(typeof(CreateApiTokenRequest))]
+[JsonSerializable(typeof(CapabilityCatalogDto))]
+[JsonSerializable(typeof(PasskeyCreationOptionsDto))]
+[JsonSerializable(typeof(PasskeyRequestOptionsDto))]
+[JsonSerializable(typeof(RegisterPasskeyRequest))]
+[JsonSerializable(typeof(PasskeyLoginRequest))]
+[JsonSerializable(typeof(Fleet.Core.SignedStatementDto), TypeInfoPropertyName = "FleetSignedStatement")]
+[JsonSerializable(typeof(TrustStateDto))]
+[JsonSerializable(typeof(ElevationRequest))]
+[JsonSerializable(typeof(ElevationAssertionRequest))]
+[JsonSerializable(typeof(ElevationDto))]
+[JsonSerializable(typeof(PageDto<ElevationDto>))]
+[JsonSerializable(typeof(PasskeyDto))]
+[JsonSerializable(typeof(PageDto<PasskeyDto>))]
 [JsonSerializable(typeof(CreatedApiTokenDto))]
 [JsonSerializable(typeof(PageDto<SettingDto>))]
 [JsonSerializable(typeof(Dictionary<string, JsonElement>), TypeInfoPropertyName = "SettingsPatch")]

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

@@ -10,6 +10,8 @@ public sealed record EdgePartialDto(bool First, bool Last);
 
 public sealed record GapDto(DateTimeOffset From, DateTimeOffset To, string Reason);
 
+public sealed record AuditDto(long Id, DateTimeOffset At, string Actor, string Method, string Action, string? Target, string? Detail, string? Remote, bool Success);
+
 public sealed record EventDto(long Id, string? AgentId, string Kind, DateTimeOffset At, string? Detail);
 
 public sealed record TestSummaryDto(string Id, string Plan, string Status, DateTimeOffset RequestedAt, DateTimeOffset? FinishedAt);

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

@@ -1,23 +1,32 @@
 using System.Reflection;
-using MoShiro.Backend.Application;
+using System.Security.Cryptography;
+using System.Text;
 
 namespace MoShiro.Backend.Api;
 
 /// <summary>
-/// 一行安装脚本：<c>packaging/install/</c> 下的 <c>install.sh</c> 和 <c>install.ps1</c> 作为嵌入资源打进 Backend，
-/// 这里把角色、网关、代码和镜像填进去。Agent 和 Probe 共用同一份，不分开维护。
+/// 一行安装脚本：<c>packaging/install/</c> 下的 <c>install.sh</c> 和 <c>install.ps1</c> 作为嵌入资源打进 Backend，<b>原样返回，不替换任何值</b>。
+/// 静态，所以它的 SHA-256 在一个版本内固定：CI 构建时算出来写进签名的发布清单，面板给的命令先核对哈希再执行（docs/access.md 第 15 节）。
+/// 角色、面板地址、代码都走命令里的环境变量。
 /// </summary>
 public static class InstallScripts
 {
-    public static string Render(string resource, InstallTarget target)
+    public const string Sh = "install.sh";
+    public const string Ps1 = "install.ps1";
+
+    /// <summary>CI 的发布公钥（<c>packaging/update/release-key.pub.pem</c>）：脚本里内置的就是这一把，测试核对两边一致。</summary>
+    public static string ReleaseKey() => Read("release-key.pub.pem").Trim();
+
+    public static string Script(string resource) => Read(resource);
+
+    /// <summary>脚本内容的 SHA-256（小写十六进制，按 UTF-8 字节）。</summary>
+    public static string Sha256(string resource) => Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(Read(resource))));
+
+    private static string Read(string resource)
     {
         using Stream stream = typeof(InstallScripts).Assembly.GetManifestResourceStream(resource)
             ?? throw new InvalidOperationException($"the embedded resource {resource} is missing");
         using var reader = new StreamReader(stream);
-        return reader.ReadToEnd()
-            .Replace("@@ROLE@@", target.Role, StringComparison.Ordinal)
-            .Replace("@@SERVER@@", target.Server, StringComparison.Ordinal)
-            .Replace("@@CODE@@", target.Code, StringComparison.Ordinal)
-            .Replace("@@IMAGE@@", target.Image, StringComparison.Ordinal);
+        return reader.ReadToEnd();
     }
 }

backend/src/MoShiro.Backend.Api/MoShiro.Backend.Api.csproj

@@ -9,5 +9,6 @@
     <ProjectReference Include="..\MoShiro.Backend.Application\MoShiro.Backend.Application.csproj" />
     <EmbeddedResource Include="..\..\..\packaging\install\install.sh" LogicalName="install.sh" />
     <EmbeddedResource Include="..\..\..\packaging\install\install.ps1" LogicalName="install.ps1" />
+    <EmbeddedResource Include="..\..\..\packaging\update\release-key.pub.pem" LogicalName="release-key.pub.pem" />
   </ItemGroup>
 </Project>

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

@@ -17,32 +17,45 @@ public static class OpsEndpoints
             .Api("health_get", "SQLite and the raw data directory are both writable", Tag)
             .Returns<HealthDto>().ProducesProblems(503);
         app.MapGet("/metrics", MetricsAsync)
-            .Api("metrics_get", "Prometheus metrics (admin token)", Tag)
+            .Api("metrics_get", "Prometheus metrics (requires ops.metrics)", Tag)
             .Produces(StatusCodes.Status200OK, contentType: "text/plain").ProducesProblems(401, 403);
-        // 一行安装：curl -fsSL 'https://panel/install?code=…' | bash（macOS 用 zsh），irm 'https://panel/install.ps1?code=…' | iex（Windows）。
-        // Agent 和 Probe 是同一份脚本，角色、网关和镜像由一次性代码决定；代码不能用就是 404。
-        app.MapGet("/install", (HttpContext http, JoinTokenService tokens, BackendOptions options, string? code) => InstallAsync(http, tokens, options, code, "install.sh", "text/x-shellscript"))
-            .Api("install_sh", "One-line installer for Linux and macOS nodes (agent or probe, decided by the code)", Tag)
-            .Produces(StatusCodes.Status200OK, contentType: "text/x-shellscript").ProducesProblems(404);
-        app.MapGet("/install.sh", (HttpContext http, JoinTokenService tokens, BackendOptions options, string? code) => InstallAsync(http, tokens, options, code, "install.sh", "text/x-shellscript"))
+        // 一行安装：面板给的命令先下载这份静态脚本、核对 SHA-256，再用环境变量里的面板地址、角色和一次性代码执行。
+        // 脚本不含任何一次性的值，所以不需要代码，也可以直接拿去和发布页公布的哈希核对。
+        app.MapGet("/install", (HttpContext http) => Static(http, InstallScripts.Sh, "text/x-shellscript"))
+            .Api("install_sh", "The static one-line installer for Linux and macOS nodes (same bytes for everyone; its SHA-256 is published with each release)", Tag)
+            .Produces(StatusCodes.Status200OK, contentType: "text/x-shellscript");
+        app.MapGet("/install.sh", (HttpContext http) => Static(http, InstallScripts.Sh, "text/x-shellscript"))
             .ExcludeFromDescription();
-        app.MapGet("/install.ps1", (HttpContext http, JoinTokenService tokens, BackendOptions options, string? code) => InstallAsync(http, tokens, options, code, "install.ps1", "text/plain"))
-            .Api("install_ps1", "One-line installer for Windows nodes (agent or probe, decided by the code)", Tag)
+        // 脚本要装的版本：CI 签名的发布清单（原样的字节）和签名。脚本用内置的发布公钥验签，再按清单里的 digest 拉镜像。
+        app.MapGet("/install/manifest", (HttpContext http, JoinTokenService tokens, ReleaseService releases, BackendOptions options, string? code) => ManifestAsync(http, tokens, releases, options, code, signature: false))
+            .Api("install_manifest", "The signed release manifest of the component an install code is for (exact signed bytes)", Tag)
+            .Produces(StatusCodes.Status200OK, contentType: "application/json").ProducesProblems(404);
+        app.MapGet("/install/manifest.sig", (HttpContext http, JoinTokenService tokens, ReleaseService releases, BackendOptions options, string? code) => ManifestAsync(http, tokens, releases, options, code, signature: true))
+            .Api("install_manifest_signature", "Base64 DER ECDSA P-256 signature of the manifest", Tag)
             .Produces(StatusCodes.Status200OK, contentType: "text/plain").ProducesProblems(404);
+        app.MapGet("/install.ps1", (HttpContext http) => Static(http, InstallScripts.Ps1, "text/plain"))
+            .Api("install_ps1", "The static one-line installer for Windows nodes (same bytes for everyone; its SHA-256 is published with each release)", Tag)
+            .Produces(StatusCodes.Status200OK, contentType: "text/plain");
     }
 
-    private static async Task<IResult> InstallAsync(HttpContext http, JoinTokenService tokens, BackendOptions options, string? code, string resource, string contentType)
+    private static async Task<IResult> ManifestAsync(HttpContext http, JoinTokenService tokens, ReleaseService releases, BackendOptions options, string? code, bool signature)
     {
         string baseUrl = options.PublicUrl ?? $"{http.Request.Scheme}://{http.Request.Host}";
         InstallTarget? target = string.IsNullOrEmpty(code) ? null : await tokens.ResolveInstallAsync(code, baseUrl, http.RequestAborted);
-        if (target is null)
+        ReleaseOffer? offer = target is null ? null : await releases.GetAsync(target.Role, http.RequestAborted);
+        if (offer is null)
         {
-            return Problems.Create(http, MoShiroErrors.NotFound, "the install code is invalid, expired or already used");
+            return Problems.Create(http, MoShiroErrors.NotFound, "no signed release is registered for this install code");
         }
 
-        string script = InstallScripts.Render(resource, target);
         http.Response.Headers.CacheControl = "no-store";
-        return TypedResults.Text(script, contentType + "; charset=utf-8");
+        return signature ? TypedResults.Text(offer.Signature, "text/plain; charset=utf-8") : TypedResults.Text(offer.Manifest, "application/json; charset=utf-8");
+    }
+
+    private static Microsoft.AspNetCore.Http.HttpResults.ContentHttpResult Static(HttpContext http, string resource, string contentType)
+    {
+        http.Response.Headers.CacheControl = "no-store";
+        return TypedResults.Text(InstallScripts.Script(resource), contentType + "; charset=utf-8");
     }
 
     private static async Task<IResult> HealthAsync(HttpContext http, OpsService ops)
@@ -57,11 +70,11 @@ public static class OpsEndpoints
     private static async Task<IResult> MetricsAsync(HttpContext http, OpsService ops)
     {
         Principal principal = http.GetPrincipal();
-        if (!principal.IsAdmin)
+        if (!principal.Has(Capability.OpsMetrics))
         {
-            return principal.CanRead
-                ? Problems.Create(http, MoShiroErrors.Forbidden, "an admin token is required")
-                : Problems.Create(http, MoShiroErrors.Unauthorized, "an admin token is required");
+            return principal.Kind != PrincipalKind.Anonymous
+                ? Problems.Create(http, MoShiroErrors.Forbidden, "the ops.metrics capability is required")
+                : Problems.Create(http, MoShiroErrors.Unauthorized, "authentication is required");
         }
 
         return TypedResults.Text(await ops.RenderPrometheusAsync(http.RequestAborted), "text/plain; version=0.0.4");

backend/src/MoShiro.Backend.Api/Public/LiveEndpoints.cs

@@ -70,7 +70,7 @@ public static class LiveEndpoints
             }
         }
 
-        string client = http.Connection.RemoteIpAddress?.ToString() ?? "unknown";
+        string client = http.ClientAddress();
         if (!limiter.TryAcquire(client))
         {
             return Problems.Create(http, MoShiroErrors.TooManyStreams, $"at most {options.MaxSsePerClient} live connections per client");

backend/src/MoShiro.Backend.Application/Admin/JoinTokenService.cs

@@ -1,13 +1,21 @@
 using Fleet.Core;
+using Fleet.Identity;
+using MoShiro.Protocol;
 
 namespace MoShiro.Backend.Application;
 
 /// <param name="Role"><c>agent</c>（默认）或 <c>probe</c>：用这个令牌注册出来的是哪种节点。</param>
-public sealed record CreateJoinTokenRequest(string? Note, IReadOnlyList<string>? Labels, bool AutoApprove, int MaxUses, int ExpiresInHours, string Role = JoinTokenService.AgentRole);
+public sealed record CreateJoinTokenRequest(string? Note, IReadOnlyList<string>? Labels, bool AutoApprove, int MaxUses, int ExpiresInHours, string Role = JoinTokenService.AgentRole, string? CreatedBy = null);
 
 /// <summary>各个系统上的一行安装命令：Linux 用 bash、macOS 用 zsh、Windows 用 PowerShell。命令里只有一次性代码，节点名字默认取主机名；Agent 和 Probe 是同一份脚本，角色由代码决定。</summary>
 public sealed record InstallCommands(string Linux, string Macos, string Windows);
 
+/// <summary>
+/// 安装命令里除了一次性的码，还带的公开值：信任根的创世指纹（节点把它固定下来）、属主（允许授权这个节点 extension 的 passkey 凭证 id）、
+/// 和面板提供的静态安装脚本的 SHA-256（命令先核对哈希再执行）。没有建立信任根时 <c>Genesis</c> 为空，节点不固定信任根。
+/// </summary>
+public sealed record InstallPlan(string? Genesis, IReadOnlyList<string> Controllers, string ScriptShSha256, string ScriptPs1Sha256);
+
 public sealed record CreatedJoinToken(JoinTokenInfo Info, string Plaintext, InstallCommands InstallCommands);
 
 /// <summary>安装脚本里要填的四个值。</summary>
@@ -35,7 +43,7 @@ public sealed class JoinTokenService
         _time = time;
     }
 
-    public async ValueTask<Result<CreatedJoinToken>> CreateAsync(CreateJoinTokenRequest request, string? requestBaseUrl, CancellationToken ct)
+    public async ValueTask<Result<CreatedJoinToken>> CreateAsync(CreateJoinTokenRequest request, string? requestBaseUrl, InstallPlan plan, CancellationToken ct)
     {
         var errors = new Dictionary<string, string>();
         if (request.Role is not (AgentRole or ProbeRole))
@@ -43,9 +51,9 @@ public sealed class JoinTokenService
             errors["role"] = "must be agent or probe";
         }
 
-        if (request.MaxUses is < 1 or > 1000)
+        if (request.MaxUses is < 1 or > 100_000)
         {
-            errors["max_uses"] = "must be between 1 and 1000";
+            errors["max_uses"] = "must be between 1 and 100000";
         }
 
         if (request.ExpiresInHours is < 1 or > 24 * 365)
@@ -72,14 +80,25 @@ public sealed class JoinTokenService
         long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
         JoinTokenInfo info = await _store.CreateAsync(
             Ulid.NewPrefixed("jtk", _time), TokenHash.Sha256(plaintext), request.Note, request.Labels ?? [], request.AutoApprove, KindOf(request.Role),
-            request.MaxUses, now + (request.ExpiresInHours * 3_600_000L), now, ct);
+            request.MaxUses, now + (request.ExpiresInHours * 3_600_000L), now, request.CreatedBy, ct);
 
-        string baseUrl = BaseUrl(requestBaseUrl);
-        string query = $"{baseUrl}/install?code={plaintext}";
-        return Result<CreatedJoinToken>.Ok(new CreatedJoinToken(info, plaintext, new InstallCommands(
-            $"curl -fsSL '{query}' | bash",
-            $"curl -fsSL '{query}' | zsh",
-            $"irm '{baseUrl}/install.ps1?code={plaintext}' | iex")));
+        return Result<CreatedJoinToken>.Ok(new CreatedJoinToken(info, plaintext, Commands(BaseUrl(requestBaseUrl), request.Role, plaintext, plan)));
+    }
+
+    /// <summary>
+    /// 一行安装命令：先下载静态脚本、核对 SHA-256，一致才执行；面板地址、角色、一次性码、信任根指纹和属主都走环境变量。
+    /// 里面没有任何私钥，码泄露最多让别人注册出一个节点。
+    /// </summary>
+    public static InstallCommands Commands(string baseUrl, string role, string code, InstallPlan plan)
+    {
+        string pin = plan.Genesis is null ? "" : $" MOSHIRO_GENESIS='{plan.Genesis}' MOSHIRO_CONTROLLERS='{string.Join(',', plan.Controllers)}'";
+        string env = $"MOSHIRO_SERVER='{baseUrl}' MOSHIRO_ROLE='{role}' MOSHIRO_CODE='{code}'{pin}";
+        string psPin = plan.Genesis is null ? "" : $"$env:MOSHIRO_GENESIS='{plan.Genesis}'; $env:MOSHIRO_CONTROLLERS='{string.Join(',', plan.Controllers)}'; ";
+        return new InstallCommands(
+            $"f=$(mktemp) && curl -fsSL '{baseUrl}/install' -o \"$f\" && echo \"{plan.ScriptShSha256}  $f\" | sha256sum -c - >/dev/null && {env} sh \"$f\"",
+            $"f=$(mktemp) && curl -fsSL '{baseUrl}/install' -o \"$f\" && echo \"{plan.ScriptShSha256}  $f\" | shasum -a 256 -c - >/dev/null && {env} sh \"$f\"",
+            $"$f = Join-Path $env:TEMP 'moshiro-install.ps1'; irm '{baseUrl}/install.ps1' -OutFile $f; if ((Get-FileHash $f -Algorithm SHA256).Hash -ne '{plan.ScriptPs1Sha256}') {{ throw 'the install script does not match its published hash' }}; "
+            + $"$env:MOSHIRO_SERVER='{baseUrl}'; $env:MOSHIRO_ROLE='{role}'; $env:MOSHIRO_CODE='{code}'; {psPin}iex (Get-Content -Raw $f)");
     }
 
     private string BaseUrl(string? requestBaseUrl) => (_options.PublicUrl ?? requestBaseUrl ?? "https://panel.example.com").TrimEnd('/');

backend/src/MoShiro.Backend.Application/Agents/AgentService.cs

@@ -24,9 +24,11 @@ public sealed partial class AgentService
 
     private readonly NodeInfoService _nodes;
     private readonly LinkService _links;
+    private readonly TrustService _trust;
 
-    public AgentService(IAgentStore agents, AgentRuntime runtime, IAgentGateway gateway, TaskPlanner planner, ISettingsStore settings, NodeInfoService nodes, LinkService links)
+    public AgentService(IAgentStore agents, AgentRuntime runtime, IAgentGateway gateway, TaskPlanner planner, ISettingsStore settings, NodeInfoService nodes, LinkService links, TrustService trust)
     {
+        _trust = trust;
         _links = links;
         _nodes = nodes;
         _agents = agents;
@@ -172,6 +174,9 @@ public sealed partial class AgentService
             });
         }
 
+        IReadOnlyList<Fleet.Core.SignedStatementDto> chain = await _trust.ChainAsync(ct);
+        result.TrustChain = chain.Count == 0 ? null : [.. chain];
+
         return result;
     }
 

backend/src/MoShiro.Backend.Application/ApplicationServiceCollectionExtensions.cs

@@ -35,6 +35,13 @@ public static class ApplicationServiceCollectionExtensions
         services.AddSingleton<IngestService>();
         services.AddSingleton<WindowComputer>();
         services.AddSingleton<AuthService>();
+        services.AddSingleton<PasskeyService>();
+        services.AddSingleton<AuditService>();
+        services.AddSingleton<ServerIdentityService>();
+        services.AddSingleton<Fleet.Server.IServerIdentity>(sp => sp.GetRequiredService<ServerIdentityService>());
+        services.AddSingleton<TrustService>();
+        services.AddSingleton<Fleet.Server.IOperatorTrustSource>(sp => sp.GetRequiredService<TrustService>());
+        services.AddSingleton<ElevationService>();
         services.AddSingleton<SettingsService>();
         services.AddSingleton<ReleaseService>();
         services.AddSingleton<ScheduleService>();

backend/src/MoShiro.Backend.Application/Audit/AuditService.cs

@@ -0,0 +1,60 @@
+using Microsoft.Extensions.Logging;
+
+namespace MoShiro.Backend.Application;
+
+/// <summary>
+/// 审计日志里的一行：谁（<see cref="Actor"/>，用户名或 <c>key:令牌名</c>）、怎么登录的（<see cref="Method"/>）、做了什么（<see cref="Action"/>，
+/// 管理接口的 operationId，或 <c>auth.login</c> 这类登录事件）、对谁（<see cref="Target"/>）、结果如何。
+/// </summary>
+public sealed record AuditRecord(long Id, long AtMs, string? UserId, string Actor, string Method, string Action, string? Target, string? Detail, string? Remote, bool Success);
+
+public sealed record AuditQuery(long? BeforeId, int Limit, string? Actor, string? Action);
+
+/// <summary>审计日志只追加：没有修改和单条删除，只按保留期整体清理。</summary>
+public sealed partial class AuditService
+{
+    /// <summary>保留一年。审计记录的是谁动过信任相关的东西，比监测数据留得久。</summary>
+    public const int RetentionDays = 365;
+
+    private readonly IAuditStore _store;
+    private readonly TimeProvider _time;
+    private readonly ILogger<AuditService> _logger;
+
+    public AuditService(IAuditStore store, TimeProvider time, ILogger<AuditService> logger)
+    {
+        _store = store;
+        _time = time;
+        _logger = logger;
+    }
+
+    /// <summary>记一条。写不进去只记日志，不能因为审计失败而让已经完成的操作报错。</summary>
+    public async ValueTask RecordAsync(Principal principal, string action, string? target, string? detail, string? remote, bool success, CancellationToken ct = default) =>
+        await RecordAsync(principal.UserId, principal.Label, MethodOf(principal), action, target, detail, remote, success, ct);
+
+    public async ValueTask RecordAsync(string? userId, string actor, string method, string action, string? target, string? detail, string? remote, bool success, CancellationToken ct = default)
+    {
+        try
+        {
+            await _store.AddAsync(new AuditRecord(0, _time.GetUtcNow().ToUnixTimeMilliseconds(), userId, actor, method, action, Clip(target, 200), Clip(detail, 500), remote, success), ct);
+        }
+        catch (Exception ex) when (ex is not OperationCanceledException)
+        {
+            LogFailed(ex, action);
+        }
+    }
+
+    public ValueTask<IReadOnlyList<AuditRecord>> ListAsync(AuditQuery query, CancellationToken ct) => _store.ListAsync(query, ct);
+
+    public ValueTask<int> PruneAsync(long nowMs, CancellationToken ct) => _store.DeleteOlderThanAsync(nowMs - (RetentionDays * 86_400_000L), ct);
+
+    /// <summary>登录方式：密码、passkey，或 API key。</summary>
+    public static string MethodOf(Principal principal) =>
+        principal.Kind == PrincipalKind.Anonymous ? "anonymous"
+        : principal.Kind == PrincipalKind.Token && principal.UserId is null ? "key"
+        : principal.AuthMethod.Length > 0 ? principal.AuthMethod : AuthMethods.Password;
+
+    private static string? Clip(string? text, int max) => text is { } t && t.Length > max ? t[..max] : text;
+
+    [LoggerMessage(Level = LogLevel.Warning, Message = "could not write the audit record for {Action}")]
+    private partial void LogFailed(Exception exception, string action);
+}

backend/src/MoShiro.Backend.Application/Auth/AuthModels.cs

@@ -7,24 +7,25 @@ public enum PrincipalKind
     Token,
 }
 
-/// <summary>访问级别：作用域为 read 的令牌只读，admin 可以管理，release 只能登记发布清单（给 CI 用，什么都读不了）。</summary>
-public enum ApiScope
+/// <summary>
+/// 已认证的主体：会话或 API key，带着它拥有的能力集合。授权只看 <see cref="Has"/>。
+/// </summary>
+public sealed record Principal(PrincipalKind Kind, IReadOnlySet<string> Capabilities, string? UserId, string? Username, string? CsrfToken, string? TokenId)
 {
-    None = 0,
-    Release = 1,
-    Read = 2,
-    Admin = 3,
-}
+    /// <summary>会话是怎么登录的（<see cref="AuthMethods"/>）：只有 passkey 登录的会话以后能提权。API key 为空。</summary>
+    public string AuthMethod { get; init; } = "";
 
-public sealed record Principal(PrincipalKind Kind, ApiScope Scope, string? UserId, string? Username, string? CsrfToken, string? TokenId)
-{
-    public static Principal Anonymous { get; } = new(PrincipalKind.Anonymous, ApiScope.None, null, null, null, null);
+    /// <summary>会话的标识（令牌哈希的十六进制）：提权窗口按它记。API key 为空。</summary>
+    public string? SessionId { get; init; }
 
-    public bool CanRead => Scope >= ApiScope.Read;
+    /// <summary>审计和归属里显示的名字：用户名，或者 <c>key:令牌名</c>。</summary>
+    public string Label => Kind == PrincipalKind.Token && UserId is null ? "key:" + (Username ?? TokenId) : Username ?? "anonymous";
 
-    public bool IsAdmin => Scope >= ApiScope.Admin;
+    public static Principal Anonymous { get; } = new(PrincipalKind.Anonymous, new HashSet<string>(), null, null, null, null);
 
-    public bool CanPublishRelease => Scope is ApiScope.Release or ApiScope.Admin;
+    public bool Has(string capability) => capability == Capability.Authenticated ? Kind != PrincipalKind.Anonymous : Capabilities.Contains(capability);
+
+    public static IReadOnlySet<string> SetOf(IEnumerable<string> capabilities) => new HashSet<string>(capabilities, StringComparer.Ordinal);
 }
 
 public sealed record LoginResult(string SessionToken, string CsrfToken, long ExpiresAtMs, string UserId, string Username);

backend/src/MoShiro.Backend.Application/Auth/AuthService.cs

@@ -37,11 +37,22 @@ public sealed partial class AuthService
             return Result<LoginResult>.Fail(MoShiroErrors.Unauthorized, "invalid credentials");
         }
 
+        return await CreateSessionAsync(user, AuthMethods.Password, ct);
+    }
+
+    /// <summary>已经确认了用户身份（例如 passkey 断言通过）之后建立会话。</summary>
+    public async ValueTask<Result<LoginResult>> CreateSessionForAsync(string userId, string method, CancellationToken ct) =>
+        await _store.GetUserAsync(userId, ct) is { } user
+            ? await CreateSessionAsync(user, method, ct)
+            : Result<LoginResult>.Fail(MoShiroErrors.Unauthorized, "invalid credentials");
+
+    private async ValueTask<Result<LoginResult>> CreateSessionAsync(UserRecord user, string method, CancellationToken ct)
+    {
         byte[] token = RandomNumberGenerator.GetBytes(32);
         byte[] csrf = RandomNumberGenerator.GetBytes(32);
         long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
         long expires = now + (long)_options.SessionLifetime.TotalMilliseconds;
-        await _store.CreateSessionAsync(new SessionRecord(SHA256.HashData(token), user.Id, csrf, now, expires), ct);
+        await _store.CreateSessionAsync(new SessionRecord(SHA256.HashData(token), user.Id, csrf, now, expires, method), ct);
         await _store.DeleteExpiredSessionsAsync(now, ct);
         return Result<LoginResult>.Ok(new LoginResult(Base64Url.Encode(token), Base64Url.Encode(csrf), expires, user.Id, user.Username));
     }
@@ -60,25 +71,24 @@ public sealed partial class AuthService
         }
 
         UserRecord? user = await _store.GetUserAsync(session.UserId, ct);
-        return user is null ? null : new Principal(PrincipalKind.Session, ApiScope.Admin, user.Id, user.Username, Base64Url.Encode(session.CsrfToken), null);
+        return user is null ? null : new Principal(PrincipalKind.Session, Principal.SetOf(CapabilityCatalog.ForSession(session.AuthMethod)), user.Id, user.Username, Base64Url.Encode(session.CsrfToken), null) { AuthMethod = session.AuthMethod, SessionId = Convert.ToHexString(session.IdSha256) };
     }
 
     public async ValueTask<Principal?> AuthenticateTokenAsync(string bearer, CancellationToken ct)
     {
         ApiTokenRecord? token = await _store.FindApiTokenAsync(TokenHash.Sha256(bearer), ct);
-        if (token is null || token.RevokedAtMs is not null)
+        long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
+        if (token is null || token.RevokedAtMs is not null || (token.ExpiresAtMs is { } expires && expires <= now))
         {
             return null;
         }
 
-        long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
         if (token.LastUsedAtMs is not { } last || now - last >= TokenTouchIntervalMs)
         {
             await _store.TouchApiTokenAsync(token.Id, now, ct);
         }
 
-        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);
+        return new Principal(PrincipalKind.Token, Principal.SetOf(token.Capabilities), null, token.Name, null, token.Id);
     }
 
     public async ValueTask LogoutAsync(string sessionToken, CancellationToken ct)
@@ -128,20 +138,48 @@ public sealed partial class AuthService
 
     public ValueTask<IReadOnlyList<UserRecord>> ListUsersAsync(CancellationToken ct) => _store.ListUsersAsync(ct);
 
-    public async ValueTask<Result<CreatedApiToken>> CreateApiTokenAsync(string name, string scope, CancellationToken ct)
+    /// <summary>
+    /// 创建 API key：能力必须都在目录里，并且是创建者自己拥有能力的子集（不能越权）；写蕴含读，结果稳定排序。
+    /// <paramref name="expiresInDays"/> 为空表示不过期。
+    /// </summary>
+    public async ValueTask<Result<CreatedApiToken>> CreateApiTokenAsync(string name, IReadOnlyList<string> capabilities, int? expiresInDays, Principal creator, CancellationToken ct)
     {
+        var errors = new Dictionary<string, string>();
         if (name.Length is 0 or > 64)
         {
-            return ValidationError.Fail<CreatedApiToken>("name", "must be 1-64 characters");
+            errors["name"] = "must be 1-64 characters";
         }
 
-        if (scope is not ("read" or "admin" or "release"))
+        string[] unknown = [.. capabilities.Where(c => !CapabilityCatalog.IsKnown(c))];
+        if (capabilities.Count == 0)
         {
-            return ValidationError.Fail<CreatedApiToken>("scope", "must be read, admin or release");
+            errors["capabilities"] = "choose at least one capability";
+        }
+        else if (unknown.Length > 0)
+        {
+            errors["capabilities"] = "unknown capability: " + string.Join(", ", unknown);
+        }
+
+        if (expiresInDays is < 1 or > 3650)
+        {
+            errors["expires_in_days"] = "must be between 1 and 3650";
+        }
+
+        IReadOnlyList<string> effective = CapabilityCatalog.Expand(capabilities.Where(CapabilityCatalog.IsKnown));
+        string[] beyond = [.. effective.Where(c => !creator.Has(c))];
+        if (beyond.Length > 0)
+        {
+            errors["capabilities"] = "you cannot grant what you do not have: " + string.Join(", ", beyond);
+        }
+
+        if (errors.Count > 0)
+        {
+            return ValidationError.Fail<CreatedApiToken>(errors);
         }
 
         string plaintext = TokenHash.NewToken("mos");
-        var record = new ApiTokenRecord(Ulid.NewPrefixed("tok", _time), name, scope, TokenHash.Sha256(plaintext), _time.GetUtcNow().ToUnixTimeMilliseconds(), null, null);
+        long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
+        var record = new ApiTokenRecord(Ulid.NewPrefixed("tok", _time), name, effective, TokenHash.Sha256(plaintext), now, null, expiresInDays is { } days ? now + (days * 86_400_000L) : null, null);
         await _store.CreateApiTokenAsync(record, ct);
         return Result<CreatedApiToken>.Ok(new CreatedApiToken(record, plaintext));
     }

backend/src/MoShiro.Backend.Application/Auth/Capabilities.cs

@@ -0,0 +1,143 @@
+namespace MoShiro.Backend.Application;
+
+/// <summary>
+/// 能力（capability）：一项具体的权限。端点声明自己需要哪一项，<see cref="Principal.Has"/> 是唯一的判断入口，
+/// 会话、API key 都走它。设计见 docs/access.md 第 2 节。
+/// </summary>
+public static class Capability
+{
+    /// <summary>任何已认证的主体（会话或 API key）；只有登出、查看自己这类端点用它。</summary>
+    public const string Authenticated = "authenticated";
+
+    public const string PublicRead = "public.read";
+
+    public const string FleetRead = "fleet.read";
+    public const string FleetWrite = "fleet.write";
+    public const string FleetEnroll = "fleet.enroll";
+    public const string FleetRevoke = "fleet.revoke";
+
+    public const string TasksRead = "tasks.read";
+    public const string TasksWrite = "tasks.write";
+
+    public const string DataRead = "data.read";
+    public const string DataWrite = "data.write";
+
+    public const string SettingsRead = "settings.read";
+    public const string SettingsWrite = "settings.write";
+
+    public const string UpdateRead = "update.read";
+    public const string UpdateConfirm = "update.confirm";
+    public const string ReleasePublish = "release.publish";
+
+    public const string KeysRead = "keys.read";
+    public const string KeysManage = "keys.manage";
+
+    public const string AccountsRead = "accounts.read";
+    public const string AccountsManage = "accounts.manage";
+
+    public const string AuditRead = "audit.read";
+    public const string EventsRead = "events.read";
+    public const string OpsMetrics = "ops.metrics";
+
+    // 预留：外部 webhook 回调和数据拉取（docs/access.md 5.4），目录里先存在，实现放后面
+    public const string DataExport = "data.export";
+    public const string WebhooksRead = "webhooks.read";
+    public const string WebhooksManage = "webhooks.manage";
+}
+
+/// <summary>一项能力的元数据。<c>Trust</c>：改变信任的能力（加节点、吊销、账户），后续会要求 passkey 签名；<c>Reserved</c>：还没有对应的功能。</summary>
+public sealed record CapabilityInfo(string Id, string Group, bool Trust = false, bool Reserved = false, params string[] Implies);
+
+public sealed record CapabilityPreset(string Id, IReadOnlyList<string> Capabilities);
+
+/// <summary>能力目录：分组、依赖（写蕴含读）、预设，以及创建 API key 时的校验。</summary>
+public static class CapabilityCatalog
+{
+    public static IReadOnlyList<CapabilityInfo> All { get; } =
+    [
+        new(Capability.PublicRead, "public"),
+
+        new(Capability.FleetRead, "fleet"),
+        new(Capability.FleetWrite, "fleet", false, false, Capability.FleetRead),
+        new(Capability.FleetEnroll, "fleet", false, false, Capability.FleetRead),
+        new(Capability.FleetRevoke, "fleet", true, false, Capability.FleetRead),
+
+        new(Capability.TasksRead, "tasks"),
+        new(Capability.TasksWrite, "tasks", false, false, Capability.TasksRead),
+
+        new(Capability.DataRead, "data"),
+        new(Capability.DataWrite, "data", false, false, Capability.DataRead),
+        new(Capability.DataExport, "data", false, true, Capability.DataRead),
+
+        new(Capability.SettingsRead, "settings"),
+        new(Capability.SettingsWrite, "settings", false, false, Capability.SettingsRead),
+
+        new(Capability.UpdateRead, "update"),
+        new(Capability.UpdateConfirm, "update", false, false, Capability.UpdateRead),
+        new(Capability.ReleasePublish, "update"),
+
+        new(Capability.KeysRead, "keys"),
+        new(Capability.KeysManage, "keys", false, false, Capability.KeysRead),
+
+        new(Capability.AccountsRead, "accounts"),
+        new(Capability.AccountsManage, "accounts", true, false, Capability.AccountsRead),
+
+        new(Capability.EventsRead, "ops"),
+        new(Capability.AuditRead, "ops"),
+        new(Capability.OpsMetrics, "ops"),
+
+        new(Capability.WebhooksRead, "integrations", false, true),
+        new(Capability.WebhooksManage, "integrations", false, true, Capability.WebhooksRead),
+    ];
+
+    private static readonly Dictionary<string, CapabilityInfo> s_byId = All.ToDictionary(c => c.Id, StringComparer.Ordinal);
+
+    public static IReadOnlyList<string> Groups { get; } = [.. All.Select(c => c.Group).Distinct()];
+
+    public static IReadOnlyList<CapabilityPreset> Presets { get; } =
+    [
+        new("read-only", [.. All.Where(c => !c.Reserved && c.Id.EndsWith(".read", StringComparison.Ordinal)).Select(c => c.Id)]),
+        new("operations", Expand([Capability.PublicRead, Capability.FleetWrite, Capability.TasksWrite, Capability.DataWrite, Capability.SettingsWrite, Capability.UpdateConfirm, Capability.EventsRead, Capability.AuditRead])),
+        new("enroll", Expand([Capability.FleetEnroll])),
+        new("ci-release", [Capability.ReleasePublish]),
+        new("all", [.. All.Select(c => c.Id)]),
+    ];
+
+    public static bool IsKnown(string id) => s_byId.ContainsKey(id);
+
+    public static CapabilityInfo? Find(string id) => s_byId.GetValueOrDefault(id);
+
+    /// <summary>补上蕴含的能力（写蕴含读），去重并排序，结果稳定。</summary>
+    public static IReadOnlyList<string> Expand(IEnumerable<string> ids)
+    {
+        var result = new SortedSet<string>(StringComparer.Ordinal);
+        foreach (string id in ids)
+        {
+            Add(result, id);
+        }
+
+        return [.. result];
+    }
+
+    private static void Add(SortedSet<string> set, string id)
+    {
+        if (id is Capability.Authenticated || !set.Add(id) || !s_byId.TryGetValue(id, out CapabilityInfo? info))
+        {
+            return;
+        }
+
+        foreach (string implied in info.Implies)
+        {
+            Add(set, implied);
+        }
+    }
+
+    /// <summary>登录会话的能力：全部，包括信任类；信任类的操作还要有效的提权窗口（<see cref="ElevationService"/>）。</summary>
+    public static IReadOnlyList<string> ForSession() => [.. All.Select(c => c.Id)];
+
+    /// <summary>
+    /// 按登录方式给会话能力：passkey 登录的拿全部；<b>密码登录的什么能力都没有</b>，只能做「已登录」就能做的事——
+    /// 看自己是谁、注册自己的第一个 passkey。管理员要先用密码进来加一个 passkey，之后用 passkey 登录才能管事。
+    /// </summary>
+    public static IReadOnlyList<string> ForSession(string authMethod) => authMethod == AuthMethods.Passkey ? ForSession() : [];
+}

backend/src/MoShiro.Backend.Application/Auth/ElevationService.cs

@@ -0,0 +1,135 @@
+namespace MoShiro.Backend.Application;
+
+/// <summary>
+/// 提权窗口的种类（docs/access.md 第 4 节）：加节点（15 分钟）、吊销和删除（5 分钟）、改凭证（60 秒，用一次就没有）。
+/// 窗口属于会话，不属于用户：换一台设备、一个浏览器就要重新触碰 passkey。
+/// </summary>
+public enum ElevationClass
+{
+    Enroll,
+    Revoke,
+    Credential,
+}
+
+public sealed record ElevationWindow(ElevationClass Class, long ExpiresAtMs);
+
+public static class Elevation
+{
+    public static string IdOf(ElevationClass elevation) => elevation switch
+    {
+        ElevationClass.Enroll => "enroll",
+        ElevationClass.Revoke => "revoke",
+        _ => "credential",
+    };
+
+    public static bool TryParse(string? id, out ElevationClass elevation)
+    {
+        (bool ok, elevation) = id switch
+        {
+            "enroll" => (true, ElevationClass.Enroll),
+            "revoke" => (true, ElevationClass.Revoke),
+            "credential" => (true, ElevationClass.Credential),
+            _ => (false, default),
+        };
+        return ok;
+    }
+
+    /// <summary>端点要求的能力需要哪一种窗口；不是信任类的能力返回 null。</summary>
+    public static ElevationClass? For(string capability) => capability switch
+    {
+        Capability.FleetRevoke => ElevationClass.Revoke,
+        Capability.AccountsManage => ElevationClass.Credential,
+        _ => null,
+    };
+}
+
+/// <summary>
+/// 会话的提权窗口，只在内存里：重启之后需要重新触碰 passkey，这正是想要的。API key 不经过这里（它自己带着能力，创建时已经签过）。
+/// </summary>
+public sealed class ElevationService
+{
+    private readonly BackendOptions _options;
+    private readonly TimeProvider _time;
+    private readonly object _gate = new();
+    private readonly Dictionary<string, Dictionary<ElevationClass, long>> _windows = [];
+
+    public ElevationService(BackendOptions options, TimeProvider time)
+    {
+        _options = options;
+        _time = time;
+    }
+
+    public TimeSpan LifetimeOf(ElevationClass elevation) => elevation switch
+    {
+        ElevationClass.Enroll => TimeSpan.FromMinutes(_options.ElevationEnrollMinutes),
+        ElevationClass.Revoke => TimeSpan.FromMinutes(_options.ElevationRevokeMinutes),
+        _ => TimeSpan.FromSeconds(_options.ElevationCredentialSeconds),
+    };
+
+    /// <summary>开窗口；已经有的窗口重新计时。返回到期时间。</summary>
+    public long Grant(string sessionId, ElevationClass elevation)
+    {
+        long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
+        long expires = now + (long)LifetimeOf(elevation).TotalMilliseconds;
+        lock (_gate)
+        {
+            Prune(now);
+            if (!_windows.TryGetValue(sessionId, out Dictionary<ElevationClass, long>? own))
+            {
+                _windows[sessionId] = own = [];
+            }
+
+            own[elevation] = expires;
+        }
+
+        return expires;
+    }
+
+    /// <summary>窗口是否有效。<paramref name="consume"/> 且是凭证类：同时用掉（一次有效）。</summary>
+    public bool Check(string sessionId, ElevationClass elevation, bool consume)
+    {
+        long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
+        lock (_gate)
+        {
+            if (!_windows.TryGetValue(sessionId, out Dictionary<ElevationClass, long>? own) || !own.TryGetValue(elevation, out long expires) || expires <= now)
+            {
+                return false;
+            }
+
+            if (consume && elevation == ElevationClass.Credential)
+            {
+                own.Remove(elevation);
+            }
+
+            return true;
+        }
+    }
+
+    public IReadOnlyList<ElevationWindow> Active(string sessionId)
+    {
+        long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
+        lock (_gate)
+        {
+            return _windows.TryGetValue(sessionId, out Dictionary<ElevationClass, long>? own)
+                ? [.. own.Where(w => w.Value > now).OrderBy(w => w.Key).Select(w => new ElevationWindow(w.Key, w.Value))]
+                : [];
+        }
+    }
+
+    /// <summary>主动结束全部窗口（点「结束」或退出登录）。</summary>
+    public void End(string sessionId)
+    {
+        lock (_gate)
+        {
+            _windows.Remove(sessionId);
+        }
+    }
+
+    private void Prune(long now)
+    {
+        foreach (string session in _windows.Where(p => p.Value.All(w => w.Value <= now)).Select(p => p.Key).ToList())
+        {
+            _windows.Remove(session);
+        }
+    }
+}

backend/src/MoShiro.Backend.Application/Auth/LoginRateLimiter.cs

@@ -15,8 +15,8 @@ public sealed class LoginRateLimiter
         _time = time;
     }
 
-    /// <summary>登记一次尝试；超限时返回 false 与建议的重试等待秒数。</summary>
-    public bool TryAcquire(string source, out int retryAfterSeconds)
+    /// <summary>登记一次尝试；超限时返回 false 与建议的重试等待秒数。<paramref name="limit"/> 缺省是登录失败的额度（每分钟 <see cref="BackendOptions.LoginAttemptsPerMinute"/> 次）。</summary>
+    public bool TryAcquire(string source, out int retryAfterSeconds, int? limit = null)
     {
         long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
         Queue<long> queue = _attempts.GetOrAdd(source, _ => new Queue<long>());
@@ -27,7 +27,7 @@ public sealed class LoginRateLimiter
                 queue.Dequeue();
             }
 
-            if (queue.Count >= _options.LoginAttemptsPerMinute)
+            if (queue.Count >= (limit ?? _options.LoginAttemptsPerMinute))
             {
                 retryAfterSeconds = (int)Math.Max(1, (60_000 - (now - queue.Peek()) + 999) / 1000);
                 return false;

backend/src/MoShiro.Backend.Application/Auth/PasskeyService.cs

@@ -0,0 +1,251 @@
+using System.Security.Cryptography;
+using System.Text;
+using Fleet.Core;
+using Fleet.Identity;
+using MoShiro.Protocol;
+
+namespace MoShiro.Backend.Application;
+
+public sealed record PasskeyRecord(string Id, string UserId, string Name, byte[] PublicKeySpki, long SignCount, IReadOnlyList<string> Transports, long CreatedAtMs, long? LastUsedAtMs);
+
+/// <summary>这次请求的 WebAuthn 依赖方：<c>RpId</c> 是域名，<c>Origins</c> 是浏览器会填进 <c>clientDataJSON.origin</c> 的来源。</summary>
+public sealed record PasskeyContext(string RpId, IReadOnlySet<string> Origins);
+
+public sealed record CreationOptions(string Challenge, string RpId, string RpName, string UserId, string UserName, IReadOnlyList<string> ExcludeCredentials, int TimeoutMs);
+
+public sealed record RequestOptions(string Challenge, string RpId, int TimeoutMs, IReadOnlyList<string>? AllowCredentials = null);
+
+public sealed record PasskeyRegistration(string Name, string CredentialId, string AttestationObject, string ClientDataJson, IReadOnlyList<string>? Transports);
+
+public sealed record PasskeyAssertion(string CredentialId, string AuthenticatorData, string ClientDataJson, string Signature);
+
+/// <summary>
+/// passkey 的注册与登录（WebAuthn，ES256，attestation 当 none）。挑战只在内存里，一次有效、5 分钟过期；
+/// 登录是「可发现凭证」：不需要先输用户名，凭证 id 找到用户。验证断言的纯函数在 <see cref="WebAuthnAssertion"/>（节点以后也用）。
+/// 设计见 docs/access.md 第 3 节。
+/// </summary>
+public sealed class PasskeyService
+{
+    private const int ChallengeBytes = 32;
+    private const int MaxPasskeysPerUser = 10;
+    private const int MaxPendingChallenges = 4096;
+    private static readonly TimeSpan s_challengeLifetime = TimeSpan.FromMinutes(5);
+
+    private readonly IAuthStore _store;
+    private readonly AuthService _auth;
+    private readonly ElevationService _elevation;
+    private readonly TimeProvider _time;
+    private readonly object _gate = new();
+    private readonly Dictionary<string, PendingChallenge> _challenges = [];
+
+    private sealed record PendingChallenge(string Purpose, string? UserId, long ExpiresAtMs);
+
+    private const string RegisterPurpose = "register";
+    private const string LoginPurpose = "login";
+
+    private static string ElevatePurpose(ElevationClass elevation) => "elevate:" + Elevation.IdOf(elevation);
+
+    public PasskeyService(IAuthStore store, AuthService auth, ElevationService elevation, TimeProvider time)
+    {
+        _store = store;
+        _auth = auth;
+        _elevation = elevation;
+        _time = time;
+    }
+
+    public async ValueTask<Result<CreationOptions>> BeginRegistrationAsync(Principal principal, PasskeyContext context, CancellationToken ct)
+    {
+        if (principal.UserId is not { } userId || principal.Username is not { } username)
+        {
+            return Result<CreationOptions>.Fail(MoShiroErrors.Forbidden, "passkeys belong to a signed-in user, not to an API token");
+        }
+
+        IReadOnlyList<PasskeyRecord> existing = await _store.ListPasskeysAsync(userId, ct);
+        if (existing.Count >= MaxPasskeysPerUser)
+        {
+            return ValidationError.Fail<CreationOptions>("passkeys", $"at most {MaxPasskeysPerUser} passkeys per user");
+        }
+
+        string challenge = Issue(RegisterPurpose, userId);
+        return Result<CreationOptions>.Ok(new CreationOptions(challenge, context.RpId, "MoShiro", Base64Url.Encode(Encoding.UTF8.GetBytes(userId)), username, [.. existing.Select(p => p.Id)], 60_000));
+    }
+
+    public async ValueTask<Result<PasskeyRecord>> RegisterAsync(Principal principal, PasskeyRegistration request, PasskeyContext context, CancellationToken ct)
+    {
+        if (principal.UserId is not { } userId)
+        {
+            return Result<PasskeyRecord>.Fail(MoShiroErrors.Forbidden, "passkeys belong to a signed-in user, not to an API token");
+        }
+
+        string name = request.Name.Trim();
+        if (name.Length is 0 or > 64)
+        {
+            return ValidationError.Fail<PasskeyRecord>("name", "must be 1-64 characters");
+        }
+
+        if (!TryDecode(request.AttestationObject, out byte[] attestation) || !TryDecode(request.ClientDataJson, out byte[] clientData) || !TryDecode(request.CredentialId, out byte[] id))
+        {
+            return ValidationError.Fail<PasskeyRecord>("credential", "malformed registration");
+        }
+
+        // 挑战在 clientDataJSON 里：先取出来，一次有效
+        if (!TryTakeChallenge(clientData, RegisterPurpose, userId, out byte[] challenge))
+        {
+            return Result<PasskeyRecord>.Fail(MoShiroErrors.ValidationFailed, "the registration challenge is unknown, expired or already used");
+        }
+
+        RegisteredCredential? credential = WebAuthnRegistration.Verify(attestation, clientData, context.RpId, challenge, context.Origins.Contains, requireUserVerification: true);
+        if (credential is null || !credential.CredentialId.AsSpan().SequenceEqual(id))
+        {
+            return Result<PasskeyRecord>.Fail(MoShiroErrors.ValidationFailed, "the registration could not be verified (ES256 with user verification is required)");
+        }
+
+        string credentialId = Base64Url.Encode(credential.CredentialId);
+        var record = new PasskeyRecord(credentialId, userId, name, credential.PublicKeySpki, credential.SignCount, request.Transports?.Take(8).ToArray() ?? [], _time.GetUtcNow().ToUnixTimeMilliseconds(), null);
+        return await _store.AddPasskeyAsync(record, ct)
+            ? Result<PasskeyRecord>.Ok(record)
+            : Result<PasskeyRecord>.Fail(MoShiroErrors.NameConflict, "this passkey is already registered");
+    }
+
+    public RequestOptions BeginLogin(PasskeyContext context) => new(Issue(LoginPurpose, null), context.RpId, 60_000);
+
+    /// <summary>验证断言并建立会话。失败一律 unauthorized，不区分原因。</summary>
+    public async ValueTask<Result<LoginResult>> LoginAsync(PasskeyAssertion request, PasskeyContext context, CancellationToken ct)
+    {
+        PasskeyRecord? passkey = await VerifyAsync(request, context, LoginPurpose, null, ct);
+        return passkey is null
+            ? Result<LoginResult>.Fail(MoShiroErrors.Unauthorized, "invalid credentials")
+            : await _auth.CreateSessionForAsync(passkey.UserId, AuthMethods.Passkey, ct);
+    }
+
+    /// <summary>提权的挑战：绑定用户和窗口种类，并列出这个用户的 passkey 让浏览器只选它们。没有 passkey 的用户没法提权。</summary>
+    public async ValueTask<Result<RequestOptions>> BeginElevationAsync(Principal principal, ElevationClass elevation, PasskeyContext context, CancellationToken ct)
+    {
+        if (principal.UserId is not { } userId || principal.SessionId is null)
+        {
+            return Result<RequestOptions>.Fail(MoShiroErrors.Forbidden, "only a signed-in user can elevate; API keys carry their capabilities already");
+        }
+
+        IReadOnlyList<PasskeyRecord> own = await _store.ListPasskeysAsync(userId, ct);
+        if (own.Count == 0)
+        {
+            return Result<RequestOptions>.Fail(MoShiroErrors.ValidationFailed, "register a passkey first (Users, My passkeys)");
+        }
+
+        return Result<RequestOptions>.Ok(new RequestOptions(Issue(ElevatePurpose(elevation), userId), context.RpId, 60_000, [.. own.Select(p => p.Id)]));
+    }
+
+    /// <summary>验证提权的断言（必须是这个用户自己的 passkey）并给这个会话开窗口。失败一律 unauthorized。</summary>
+    public async ValueTask<Result<ElevationWindow>> ElevateAsync(Principal principal, ElevationClass elevation, PasskeyAssertion request, PasskeyContext context, CancellationToken ct)
+    {
+        if (principal.UserId is not { } userId || principal.SessionId is not { } sessionId)
+        {
+            return Result<ElevationWindow>.Fail(MoShiroErrors.Forbidden, "only a signed-in user can elevate; API keys carry their capabilities already");
+        }
+
+        PasskeyRecord? passkey = await VerifyAsync(request, context, ElevatePurpose(elevation), userId, ct);
+        return passkey is null || passkey.UserId != userId
+            ? Result<ElevationWindow>.Fail(MoShiroErrors.Unauthorized, "invalid credentials")
+            : Result<ElevationWindow>.Ok(new ElevationWindow(elevation, _elevation.Grant(sessionId, elevation)));
+    }
+
+    /// <summary>验证一份断言：挑战（一次有效、种类和用户对得上）、签名、计数器；通过则记下使用并返回那个 passkey。</summary>
+    private async ValueTask<PasskeyRecord?> VerifyAsync(PasskeyAssertion request, PasskeyContext context, string purpose, string? userId, CancellationToken ct)
+    {
+        if (!TryDecode(request.CredentialId, out _) || !TryDecode(request.AuthenticatorData, out byte[] authData) || !TryDecode(request.ClientDataJson, out byte[] clientData) || !TryDecode(request.Signature, out byte[] signature))
+        {
+            return null;
+        }
+
+        if (!TryTakeChallenge(clientData, purpose, userId, out byte[] challenge))
+        {
+            return null;
+        }
+
+        PasskeyRecord? passkey = await _store.FindPasskeyAsync(request.CredentialId, ct);
+        if (passkey is null || !WebAuthnAssertion.Verify(passkey.PublicKeySpki, authData, clientData, signature, context.RpId, challenge, context.Origins.Contains, requireUserVerification: true, out uint signCount))
+        {
+            return null;
+        }
+
+        // 计数器只增不减；很多同步的 passkey 一直报 0，两边都是 0 时不检查
+        if ((signCount != 0 || passkey.SignCount != 0) && signCount <= passkey.SignCount)
+        {
+            return null;
+        }
+
+        await _store.TouchPasskeyAsync(passkey.Id, signCount, _time.GetUtcNow().ToUnixTimeMilliseconds(), ct);
+        return passkey;
+    }
+
+    public ValueTask<IReadOnlyList<PasskeyRecord>> ListAsync(string userId, CancellationToken ct) => _store.ListPasskeysAsync(userId, ct);
+
+    public ValueTask<bool> DeleteAsync(string userId, string passkeyId, CancellationToken ct) => _store.DeletePasskeyAsync(userId, passkeyId, ct);
+
+    private string Issue(string purpose, string? userId)
+    {
+        byte[] challenge = RandomNumberGenerator.GetBytes(ChallengeBytes);
+        string key = Base64Url.Encode(challenge);
+        long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
+        lock (_gate)
+        {
+            if (_challenges.Count >= MaxPendingChallenges)
+            {
+                foreach (string stale in _challenges.Where(p => p.Value.ExpiresAtMs <= now).Select(p => p.Key).ToList())
+                {
+                    _challenges.Remove(stale);
+                }
+
+                if (_challenges.Count >= MaxPendingChallenges)
+                {
+                    _challenges.Remove(_challenges.OrderBy(p => p.Value.ExpiresAtMs).First().Key); // 淘汰最旧的
+                }
+            }
+
+            _challenges[key] = new PendingChallenge(purpose, userId, now + (long)s_challengeLifetime.TotalMilliseconds);
+        }
+
+        return key;
+    }
+
+    /// <summary>从 clientDataJSON 取出 challenge，按它找到并移除（一次有效）。</summary>
+    private bool TryTakeChallenge(byte[] clientDataJson, string purpose, string? userId, out byte[] challenge)
+    {
+        challenge = [];
+        string? text;
+        try
+        {
+            using var document = System.Text.Json.JsonDocument.Parse(clientDataJson);
+            text = document.RootElement.GetProperty("challenge").GetString();
+        }
+        catch (Exception ex) when (ex is System.Text.Json.JsonException or KeyNotFoundException or InvalidOperationException)
+        {
+            return false;
+        }
+
+        if (text is null || !TryDecode(text, out byte[] raw))
+        {
+            return false;
+        }
+
+        long now = _time.GetUtcNow().ToUnixTimeMilliseconds();
+        lock (_gate)
+        {
+            if (!_challenges.Remove(Base64Url.Encode(raw), out PendingChallenge? pending) || pending.ExpiresAtMs <= now || pending.Purpose != purpose || pending.UserId != userId)
+            {
+                return false;
+            }
+        }
+
+        challenge = raw;
+        return true;
+    }
+
+    private static bool TryDecode(string text, out byte[] data) => Base64Url.TryDecode(text, out data) && data.Length > 0;
+}
+
+public static class AuthMethods
+{
+    public const string Password = "password";
+    public const string Passkey = "passkey";
+}

backend/src/MoShiro.Backend.Application/Auth/ServerIdentityService.cs

@@ -0,0 +1,82 @@
+using System.Security.Cryptography;
+using Fleet.Identity;
+using Fleet.Server;
+
+namespace MoShiro.Backend.Application;
+
+/// <summary>
+/// 服务器的身份密钥（P-256）：操作员用 passkey 把公钥签进操作员集合，之后节点只认带这把密钥签名的服务器，
+/// 并在这条链路上用应用层加密（TLS 在 Cloudflare 或被冒充的证书那里终止时，中间人拿不出这把密钥）。
+/// 私钥存在 Backend 的设置里：它保护的是「面板被冒充」，不是「面板被攻破」；面板被攻破时它也会泄露，那时要由 passkey 签一个换掉它的新集合版本。
+/// </summary>
+public sealed class ServerIdentityService : IServerIdentity, IDisposable
+{
+    private const string Key = "server.identity_key";
+
+    private readonly ISettingsStore _settings;
+    private readonly object _gate = new();
+    private ECDsa? _key;
+    private byte[]? _spki;
+
+    public ServerIdentityService(ISettingsStore settings)
+    {
+        _settings = settings;
+    }
+
+    public byte[] PublicKeySpki
+    {
+        get
+        {
+            EnsureLoaded();
+            return _spki!;
+        }
+    }
+
+    /// <summary>公钥的指纹（SHA-256，小写十六进制）：页面上给人核对。</summary>
+    public string Fingerprint => Convert.ToHexStringLower(SHA256.HashData(PublicKeySpki));
+
+    public byte[] Sign(ReadOnlySpan<byte> payload)
+    {
+        EnsureLoaded();
+        return _key!.SignData(payload, HashAlgorithmName.SHA256, DSASignatureFormat.IeeeP1363FixedFieldConcatenation);
+    }
+
+    /// <summary>启动时调用：读出或生成密钥。节点可能在启动完成之前就连上来，所以 <see cref="Sign"/> 也会按需加载。</summary>
+    public ValueTask EnsureAsync(CancellationToken ct)
+    {
+        EnsureLoaded(ct);
+        return ValueTask.CompletedTask;
+    }
+
+    private void EnsureLoaded(CancellationToken ct = default)
+    {
+        if (_key is not null)
+        {
+            return;
+        }
+
+        lock (_gate)
+        {
+            if (_key is not null)
+            {
+                return;
+            }
+
+            string? stored = _settings.GetAsync(Key, ct).AsTask().GetAwaiter().GetResult();
+            var key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+            if (stored is not null)
+            {
+                key.ImportPkcs8PrivateKey(Convert.FromBase64String(stored), out _);
+            }
+            else
+            {
+                _settings.SetAsync(Key, Convert.ToBase64String(key.ExportPkcs8PrivateKey()), ct).AsTask().GetAwaiter().GetResult();
+            }
+
+            _spki = key.ExportSubjectPublicKeyInfo();
+            _key = key;
+        }
+    }
+
+    public void Dispose() => _key?.Dispose();
+}

backend/src/MoShiro.Backend.Application/Auth/TrustService.cs

@@ -0,0 +1,141 @@
+using System.Security.Cryptography;
+using System.Text;
+using Fleet.Core;
+using Fleet.Identity;
+using Fleet.Server;
+using MoShiro.Protocol;
+
+namespace MoShiro.Backend.Application;
+
+/// <summary>要操作员用 passkey 签的下一版操作员集合：<c>Challenge</c> 是语句的 SHA-256（base64url），也就是 WebAuthn 的挑战。</summary>
+public sealed record TrustProposal(string Statement, int Version, string Challenge);
+
+/// <summary><c>InSync</c>：当前生效的集合和现有的 passkey、域名是否一致；不一致就需要签一个新版本。</summary>
+/// <param name="ServerKey">这个面板的服务器身份密钥的指纹；<c>ServerKeyListed</c>：当前生效的操作员集合里已经登记了它（节点据此认证服务器、加密链路）。</param>
+public sealed record TrustState(bool Initialized, string? Genesis, int Version, bool InSync, IReadOnlyList<SignedStatementDto> Chain, TrustProposal? Proposal, IReadOnlyList<string>? Operators = null, string ServerKey = "", bool ServerKeyListed = false);
+
+/// <summary>
+/// 信任根的 Backend 一侧：保存操作员集合的链、给操作员出下一版的语句、验证他签回来的版本。
+/// Backend <b>不持有任何签名的能力</b>：每一版都要操作员的 passkey 触碰；节点从安装命令里固定的创世指纹出发自己验链，
+/// 所以 Backend 在这里的验证只是不收垃圾，不是信任的来源。设计见 docs/access.md 第 7 节。
+/// </summary>
+public sealed class TrustService : IOperatorTrustSource, IDisposable
+{
+    private readonly IOperatorSetStore _store;
+    private readonly IAuthStore _auth;
+    private readonly ServerIdentityService _server;
+    private readonly TimeProvider _time;
+    private readonly SemaphoreSlim _gate = new(1, 1);
+
+    public TrustService(IOperatorSetStore store, IAuthStore auth, ServerIdentityService server, TimeProvider time)
+    {
+        _server = server;
+        _store = store;
+        _auth = auth;
+        _time = time;
+    }
+
+    public void Dispose() => _gate.Dispose();
+
+    public ValueTask<IReadOnlyList<SignedStatementDto>> ChainAsync(CancellationToken ct) => _store.ListAsync(ct);
+
+    /// <summary>当前生效的操作员集合（从创世验过的链）；还没有建立信任根返回 null。</summary>
+    public async ValueTask<OperatorSet?> CurrentAsync(CancellationToken ct)
+    {
+        IReadOnlyList<SignedStatementDto> chain = await _store.ListAsync(ct);
+        return chain.Count == 0 ? null : OperatorTrust.VerifyChain(OperatorTrust.Fingerprint(chain[0].Statement), [.. chain.Select(c => c.ToSigned())]);
+    }
+
+    public async ValueTask<TrustState> StateAsync(PasskeyContext context, CancellationToken ct)
+    {
+        IReadOnlyList<SignedStatementDto> chain = await _store.ListAsync(ct);
+        OperatorSet? current = chain.Count == 0 ? null : OperatorTrust.VerifyChain(OperatorTrust.Fingerprint(chain[0].Statement), [.. chain.Select(c => c.ToSigned())]);
+        TrustProposal? proposal = await ProposeAsync(chain, current, context, ct);
+        OperatorSet? proposed = proposal is null ? null : OperatorTrust.ParseSet(proposal.Statement);
+        bool inSync = current is not null && proposed is not null && Same(current, proposed);
+        return new TrustState(current is not null, chain.Count == 0 ? null : OperatorTrust.Fingerprint(chain[0].Statement), current?.Version ?? 0, inSync, chain, inSync ? null : proposal, current is null ? [] : [.. current.Keys.Select(k => k.CredentialId)], _server.Fingerprint, current?.Servers?.Any(k => k.AsSpan().SequenceEqual(_server.PublicKeySpki)) == true);
+    }
+
+    private async ValueTask<TrustProposal?> ProposeAsync(IReadOnlyList<SignedStatementDto> chain, OperatorSet? current, PasskeyContext context, CancellationToken ct)
+    {
+        IReadOnlyList<PasskeyRecord> passkeys = await _auth.ListAllPasskeysAsync(ct);
+        if (passkeys.Count == 0)
+        {
+            return null;
+        }
+
+        var next = new OperatorSet(
+            (current?.Version ?? 0) + 1,
+            chain.Count == 0 ? OperatorTrust.Genesis : OperatorTrust.Fingerprint(chain[^1].Statement),
+            context.RpId,
+            [.. context.Origins.Order(StringComparer.Ordinal)],
+            [.. passkeys.Select(p => new OperatorKey(p.Id, p.PublicKeySpki))],
+            [_server.PublicKeySpki]);
+        string statement = OperatorTrust.Encode(next);
+        return new TrustProposal(statement, next.Version, Base64Url.Encode(SHA256.HashData(Encoding.UTF8.GetBytes(statement))));
+    }
+
+    private static bool Same(OperatorSet a, OperatorSet b) =>
+        a.RpId == b.RpId && a.Origins.Order(StringComparer.Ordinal).SequenceEqual(b.Origins.Order(StringComparer.Ordinal))
+        && a.Keys.Select(k => k.CredentialId).Order(StringComparer.Ordinal).SequenceEqual(b.Keys.Select(k => k.CredentialId).Order(StringComparer.Ordinal))
+        && (a.Servers ?? []).Select(Convert.ToBase64String).Order(StringComparer.Ordinal).SequenceEqual((b.Servers ?? []).Select(Convert.ToBase64String).Order(StringComparer.Ordinal));
+
+    /// <summary>
+    /// 收下操作员签回来的一版（创世，或上一版里的凭证签的更新）：语句里的每把凭证都要是已注册的 passkey、域名对得上、链验得过。
+    /// 谁能调用由端点的能力和提权窗口把关；这里不看调用者。
+    /// </summary>
+    public async ValueTask<Result<TrustState>> CommitAsync(SignedStatementDto signed, PasskeyContext context, CancellationToken ct)
+    {
+        await _gate.WaitAsync(ct);
+        try
+        {
+            IReadOnlyList<SignedStatementDto> chain = await _store.ListAsync(ct);
+            OperatorSet? set = OperatorTrust.ParseSet(signed.Statement);
+            if (set is null)
+            {
+                return ValidationError.Fail<TrustState>("statement", "is not an operator set");
+            }
+
+            OperatorSet? current = chain.Count == 0 ? null : OperatorTrust.VerifyChain(OperatorTrust.Fingerprint(chain[0].Statement), [.. chain.Select(c => c.ToSigned())]);
+            if (set.Version != (current?.Version ?? 0) + 1)
+            {
+                return Result<TrustState>.Fail(MoShiroErrors.NameConflict, $"the operator set is at version {current?.Version ?? 0}; sign version {(current?.Version ?? 0) + 1}");
+            }
+
+            if (set.RpId != context.RpId || set.Origins.Any(o => !context.Origins.Contains(o)))
+            {
+                return ValidationError.Fail<TrustState>("statement", "the relying party or origins do not match this panel");
+            }
+
+            if (set.Servers is not { Count: > 0 } || !set.Servers.Any(k => k.AsSpan().SequenceEqual(_server.PublicKeySpki)))
+            {
+                // 集合里没有这个面板的服务器密钥：签下去之后固定了它的节点就认不出这个面板了
+                return ValidationError.Fail<TrustState>("statement", "must list this panel's server key");
+            }
+
+            IReadOnlyList<PasskeyRecord> registered = await _auth.ListAllPasskeysAsync(ct);
+            if (set.Keys.Any(k => !registered.Any(p => p.Id == k.CredentialId && p.PublicKeySpki.AsSpan().SequenceEqual(k.PublicKeySpki))))
+            {
+                return ValidationError.Fail<TrustState>("statement", "lists a passkey that is not registered on this panel");
+            }
+
+            List<SignedStatement> extended = [.. chain.Select(c => c.ToSigned()), signed.ToSigned()];
+            string genesis = OperatorTrust.Fingerprint(extended[0].Statement);
+            if (OperatorTrust.VerifyChain(genesis, extended) is not { } verified || verified.Version != set.Version)
+            {
+                return Result<TrustState>.Fail(MoShiroErrors.Forbidden, "the operator set is not signed by a passkey of the previous version");
+            }
+
+            if (!await _store.AddAsync(set.Version, signed, _time.GetUtcNow().ToUnixTimeMilliseconds(), ct))
+            {
+                return Result<TrustState>.Fail(MoShiroErrors.NameConflict, "this operator set version already exists");
+            }
+        }
+        finally
+        {
+            _gate.Release();
+        }
+
+        return Result<TrustState>.Ok(await StateAsync(context, ct));
+    }
+}

backend/src/MoShiro.Backend.Application/Auth/WebAuthnRegistration.cs

@@ -0,0 +1,177 @@
+using System.Security.Cryptography;
+using System.Text;
+using Fleet.Identity;
+
+namespace MoShiro.Backend.Application;
+
+/// <summary>注册成功后要保存的凭证。</summary>
+public sealed record RegisteredCredential(byte[] CredentialId, byte[] PublicKeySpki, uint SignCount);
+
+/// <summary>
+/// 解析并校验 WebAuthn 注册（<c>navigator.credentials.create</c> 的结果）。只接受 ES256；attestation 一律当 <c>none</c> 处理：
+/// 不验设备证明，信任浏览器的实现（docs/access.md）。CBOR 解析只在 Backend 里，节点不带。
+/// </summary>
+public static class WebAuthnRegistration
+{
+    public static RegisteredCredential? Verify(
+        ReadOnlySpan<byte> attestationObject, ReadOnlySpan<byte> clientDataJson, string rpId, ReadOnlySpan<byte> expectedChallenge,
+        Func<string, bool> originAllowed, bool requireUserVerification)
+    {
+        if (!WebAuthnAssertion.ClientDataValid(clientDataJson, "webauthn.create", expectedChallenge, originAllowed))
+        {
+            return null;
+        }
+
+        try
+        {
+            if (new MiniCbor(attestationObject.ToArray()).ReadValue() is not Dictionary<object, object> attestation
+                || attestation.GetValueOrDefault("authData") is not byte[] authData || authData.Length < 55)
+            {
+                return null;
+            }
+
+            if (!CryptographicOperations.FixedTimeEquals(authData.AsSpan(0, 32), SHA256.HashData(Encoding.UTF8.GetBytes(rpId))))
+            {
+                return null;
+            }
+
+            byte flags = authData[32];
+            const byte attestedData = 0x40;
+            if ((flags & WebAuthnAssertion.FlagUserPresent) == 0 || (flags & attestedData) == 0 || (requireUserVerification && (flags & WebAuthnAssertion.FlagUserVerified) == 0))
+            {
+                return null;
+            }
+
+            uint signCount = (uint)((authData[33] << 24) | (authData[34] << 16) | (authData[35] << 8) | authData[36]);
+            int idLength = (authData[53] << 8) | authData[54];
+            if (idLength is 0 or > 1023 || authData.Length < 55 + idLength)
+            {
+                return null;
+            }
+
+            byte[] credentialId = authData[55..(55 + idLength)];
+            var reader = new MiniCbor(authData[(55 + idLength)..]);
+            if (reader.ReadValue() is not Dictionary<object, object> cose
+                || cose.GetValueOrDefault(1L) is not long kty || kty != 2
+                || cose.GetValueOrDefault(3L) is not long alg || alg != -7
+                || cose.GetValueOrDefault(-1L) is not long curve || curve != 1
+                || cose.GetValueOrDefault(-2L) is not byte[] { Length: 32 } x
+                || cose.GetValueOrDefault(-3L) is not byte[] { Length: 32 } y)
+            {
+                return null;
+            }
+
+            using ECDsa key = ECDsa.Create(new ECParameters { Curve = ECCurve.NamedCurves.nistP256, Q = new ECPoint { X = x, Y = y } });
+            return new RegisteredCredential(credentialId, key.ExportSubjectPublicKeyInfo(), signCount);
+        }
+        catch (Exception ex) when (ex is InvalidDataException or CryptographicException or ArgumentException or IndexOutOfRangeException)
+        {
+            return null;
+        }
+    }
+}
+
+/// <summary>够用的 CBOR 读取器（RFC 8949）：整数、字节串、文本串、数组、映射、布尔和 null。输入有上限，嵌套有深度限制。</summary>
+internal sealed class MiniCbor
+{
+    private const int MaxDepth = 8;
+    private const int MaxItems = 64;
+
+    private readonly byte[] _data;
+    private int _position;
+
+    public MiniCbor(byte[] data)
+    {
+        _data = data;
+    }
+
+    public object? ReadValue(int depth = 0)
+    {
+        if (depth > MaxDepth || _position >= _data.Length)
+        {
+            throw new InvalidDataException("cbor too deep or truncated");
+        }
+
+        byte initial = _data[_position++];
+        int major = initial >> 5;
+        long argument = ReadArgument(initial & 0x1F);
+        switch (major)
+        {
+            case 0:
+                return argument;
+            case 1:
+                return -1 - argument;
+            case 2:
+                return Take(argument);
+            case 3:
+                return Encoding.UTF8.GetString(Take(argument));
+            case 4:
+                {
+                    CheckCount(argument);
+                    var list = new List<object?>();
+                    for (long i = 0; i < argument; i++)
+                    {
+                        list.Add(ReadValue(depth + 1));
+                    }
+
+                    return list;
+                }
+
+            case 5:
+                {
+                    CheckCount(argument);
+                    var map = new Dictionary<object, object>();
+                    for (long i = 0; i < argument; i++)
+                    {
+                        object key = ReadValue(depth + 1) ?? throw new InvalidDataException("null map key");
+                        map[key] = ReadValue(depth + 1)!;
+                    }
+
+                    return map;
+                }
+
+            case 7:
+                return initial switch { 0xF4 => false, 0xF5 => true, 0xF6 => null, _ => throw new InvalidDataException("unsupported simple value") };
+            default:
+                throw new InvalidDataException("unsupported cbor type");
+        }
+    }
+
+    private long ReadArgument(int info)
+    {
+        if (info < 24)
+        {
+            return info;
+        }
+
+        int length = info switch { 24 => 1, 25 => 2, 26 => 4, 27 => 8, _ => throw new InvalidDataException("indefinite lengths are not supported") };
+        byte[] bytes = Take(length);
+        long value = 0;
+        foreach (byte b in bytes)
+        {
+            value = (value << 8) | b;
+        }
+
+        return value < 0 ? throw new InvalidDataException("argument too large") : value;
+    }
+
+    private byte[] Take(long length)
+    {
+        if (length < 0 || length > _data.Length - _position)
+        {
+            throw new InvalidDataException("cbor truncated");
+        }
+
+        byte[] result = _data[_position..(_position + (int)length)];
+        _position += (int)length;
+        return result;
+    }
+
+    private static void CheckCount(long count)
+    {
+        if (count > MaxItems)
+        {
+            throw new InvalidDataException("cbor collection too large");
+        }
+    }
+}

backend/src/MoShiro.Backend.Application/BackendOptions.cs

@@ -26,6 +26,21 @@ public sealed class BackendOptions
 
     public int Pbkdf2Iterations { get; set; } = 600_000;
 
+    /// <summary>WebAuthn 的依赖方域名；缺省取 <see cref="PublicUrl"/> 的主机，没有就取请求的主机。passkey 绑定在这个域名上，改了会让已注册的 passkey 失效。</summary>
+    public string? WebAuthnRpId { get; set; }
+
+    /// <summary>允许的来源（逗号分隔，如 <c>https://panel.example.com</c>）；缺省是 <see cref="PublicUrl"/> 的来源，没有就取请求自己的来源。</summary>
+    public string? WebAuthnOrigins { get; set; }
+
+    /// <summary>提权窗口的长度（passkey 触碰一次之后）：加节点类的分钟数。</summary>
+    public int ElevationEnrollMinutes { get; set; } = 15;
+
+    /// <summary>吊销和删除类的分钟数。</summary>
+    public int ElevationRevokeMinutes { get; set; } = 5;
+
+    /// <summary>改凭证类（用一次就没有）的秒数。</summary>
+    public int ElevationCredentialSeconds { get; set; } = 60;
+
     /// <summary>会话 Cookie 带 Secure 标记（只提供 HTTPS）。本机用 HTTP 调试时才关闭。</summary>
     public bool SecureCookies { get; set; } = true;
 
@@ -35,6 +50,15 @@ public sealed class BackendOptions
     /// </summary>
     public string? CorsOrigins { get; set; }
 
+    /// <summary>
+    /// 可信的反向代理（逗号分隔的 IP 或 CIDR，如 <c>127.0.0.1,172.16.0.0/12</c>）。只有从这些地址连进来的请求，才采信
+    /// <see cref="TrustedProxyHeader"/> 里的客户端地址（用于登录限流、审计和 SSE 限制）；空 = 不信任任何转发头，用套接字地址。
+    /// </summary>
+    public string? TrustedProxies { get; set; }
+
+    /// <summary>携带客户端地址的头，缺省 <c>X-Forwarded-For</c>（Cloudflare 单独的 <c>CF-Connecting-IP</c> 也可以填这里）。</summary>
+    public string? TrustedProxyHeader { get; set; }
+
     public TimeSpan SessionLifetime { get; set; } = TimeSpan.FromHours(12);
 
     public int LoginAttemptsPerMinute { get; set; } = 10;

backend/src/MoShiro.Backend.Application/Models/AgentModels.cs

@@ -29,7 +29,8 @@ public sealed record AgentRecord(
     bool PublicHostManual = false,
     bool Ipv6HostManual = false,
     IReadOnlyList<string>? ReportedAddresses = null,
-    byte[]? TlsPublicKey = null);
+    byte[]? TlsPublicKey = null,
+    string? AddedBy = null);
 
 /// <summary>管理员可以修改的字段（merge-patch 语义：为 null 的字段不改）。</summary>
 public sealed class AgentPatch
@@ -76,10 +77,11 @@ public sealed record JoinTokenInfo(
     long ExpiresAtMs,
     long? RevokedAtMs,
     long CreatedAtMs,
-    string Kind = "");
+    string Kind = "",
+    string? CreatedBy = null);
 
 /// <summary>
 /// <see cref="PublicKey"/> 是连 Backend 的身份公钥，<see cref="PeerPublicKey"/> 是对等面（连 Agent）的公钥，两把是节点自己生成的独立密钥；
 /// Agent 的 <c>peers</c> 里放的是后者。
 /// </summary>
-public sealed record ProbeRecord(string Id, string Name, byte[] PublicKey, long CreatedAtMs, long? RevokedAtMs, string? Ipv6DiagnosticsJson = null, byte[]? PeerPublicKey = null);
+public sealed record ProbeRecord(string Id, string Name, byte[] PublicKey, long CreatedAtMs, long? RevokedAtMs, string? Ipv6DiagnosticsJson = null, byte[]? PeerPublicKey = null, string? AddedBy = null);

backend/src/MoShiro.Backend.Application/Ports/IAuthStore.cs

@@ -2,9 +2,9 @@ namespace MoShiro.Backend.Application;
 
 public sealed record UserRecord(string Id, string Username, byte[] PasswordHash, byte[] PasswordSalt, int Iterations, long CreatedAtMs);
 
-public sealed record SessionRecord(byte[] IdSha256, string UserId, byte[] CsrfToken, long CreatedAtMs, long ExpiresAtMs);
+public sealed record SessionRecord(byte[] IdSha256, string UserId, byte[] CsrfToken, long CreatedAtMs, long ExpiresAtMs, string AuthMethod = AuthMethods.Password);
 
-public sealed record ApiTokenRecord(string Id, string Name, string Scope, byte[] TokenSha256, long CreatedAtMs, long? LastUsedAtMs, long? RevokedAtMs);
+public sealed record ApiTokenRecord(string Id, string Name, IReadOnlyList<string> Capabilities, byte[] TokenSha256, long CreatedAtMs, long? LastUsedAtMs, long? ExpiresAtMs, long? RevokedAtMs);
 
 public interface IAuthStore
 {
@@ -31,6 +31,21 @@ public interface IAuthStore
 
     ValueTask CreateApiTokenAsync(ApiTokenRecord token, CancellationToken ct);
 
+    /// <summary>凭证 id 已经存在时返回 false。</summary>
+    ValueTask<bool> AddPasskeyAsync(PasskeyRecord passkey, CancellationToken ct);
+
+    ValueTask<PasskeyRecord?> FindPasskeyAsync(string credentialId, CancellationToken ct);
+
+    ValueTask<IReadOnlyList<PasskeyRecord>> ListPasskeysAsync(string userId, CancellationToken ct);
+
+    /// <summary>所有用户的 passkey（操作员集合从这里取）。</summary>
+    ValueTask<IReadOnlyList<PasskeyRecord>> ListAllPasskeysAsync(CancellationToken ct);
+
+    /// <summary>只能删自己的。</summary>
+    ValueTask<bool> DeletePasskeyAsync(string userId, string credentialId, CancellationToken ct);
+
+    ValueTask TouchPasskeyAsync(string credentialId, long signCount, long nowMs, CancellationToken ct);
+
     ValueTask<ApiTokenRecord?> FindApiTokenAsync(byte[] tokenSha256, CancellationToken ct);
 
     ValueTask<IReadOnlyList<ApiTokenRecord>> ListApiTokensAsync(CancellationToken ct);

backend/src/MoShiro.Backend.Application/Ports/StorePorts.cs

@@ -54,7 +54,7 @@ public interface IGeoLookup
 
 public interface IJoinTokenStore
 {
-    ValueTask<JoinTokenInfo> CreateAsync(string id, byte[] tokenSha256, string? note, IReadOnlyList<string> labels, bool autoApprove, string kind, int maxUses, long expiresAtMs, long nowMs, CancellationToken ct);
+    ValueTask<JoinTokenInfo> CreateAsync(string id, byte[] tokenSha256, string? note, IReadOnlyList<string> labels, bool autoApprove, string kind, int maxUses, long expiresAtMs, long nowMs, string? createdBy, CancellationToken ct);
 
     ValueTask<IReadOnlyList<JoinTokenInfo>> ListAsync(CancellationToken ct);
 
@@ -144,6 +144,24 @@ public interface IEventStore
     ValueTask<int> DeleteOlderThanAsync(long cutoffMs, CancellationToken ct);
 }
 
+/// <summary>操作员集合的链（passkey 签的版本，按版本号递增）。</summary>
+public interface IOperatorSetStore
+{
+    ValueTask<IReadOnlyList<SignedStatementDto>> ListAsync(CancellationToken ct);
+
+    /// <summary>追加一个版本；版本号已经有了返回 false。</summary>
+    ValueTask<bool> AddAsync(int version, SignedStatementDto signed, long nowMs, CancellationToken ct);
+}
+
+public interface IAuditStore
+{
+    ValueTask AddAsync(AuditRecord record, CancellationToken ct);
+
+    ValueTask<IReadOnlyList<AuditRecord>> ListAsync(AuditQuery query, CancellationToken ct);
+
+    ValueTask<int> DeleteOlderThanAsync(long cutoffMs, CancellationToken ct);
+}
+
 /// <summary>主机资源占用的历史：每个 Agent 每分钟一个样本。</summary>
 public interface IHostStore
 {

backend/src/MoShiro.Backend.Application/Retention/RetentionService.cs

@@ -12,19 +12,21 @@ public sealed partial class RetentionService : BackgroundService
     private readonly IMetricStore _metrics;
     private readonly IEventStore _events;
     private readonly IAuthStore _auth;
+    private readonly AuditService _audit;
     private readonly IHostStore _hosts;
     private readonly SettingsService _settings;
     private readonly LoginRateLimiter _limiter;
     private readonly TimeProvider _time;
     private readonly ILogger<RetentionService> _logger;
 
-    public RetentionService(IRawStore raw, IMetricStore metrics, IEventStore events, IHostStore hosts, IAuthStore auth, SettingsService settings, LoginRateLimiter limiter, TimeProvider time, ILogger<RetentionService> logger)
+    public RetentionService(IRawStore raw, IMetricStore metrics, IEventStore events, IHostStore hosts, IAuthStore auth, AuditService audit, SettingsService settings, LoginRateLimiter limiter, TimeProvider time, ILogger<RetentionService> logger)
     {
         _raw = raw;
         _metrics = metrics;
         _events = events;
         _hosts = hosts;
         _auth = auth;
+        _audit = audit;
         _settings = settings;
         _limiter = limiter;
         _time = time;
@@ -69,6 +71,7 @@ public sealed partial class RetentionService : BackgroundService
         await _events.DeleteOlderThanAsync(nowMs - (await _settings.GetIntAsync(SettingsService.EventDays, ct) * Steps.Day), ct);
         await _hosts.DeleteOlderThanAsync(nowMs - (await _settings.GetIntAsync(SettingsService.HostDays, ct) * Steps.Day), ct);
         await _auth.DeleteExpiredSessionsAsync(nowMs, ct);
+        await _audit.PruneAsync(nowMs, ct);
         _limiter.Prune();
     }
 

backend/src/MoShiro.Backend.Application/StartupTasks.cs

@@ -11,9 +11,11 @@ public sealed class StartupTasks : IHostedService
     private readonly IRawStore _raw;
     private readonly AuthService _auth;
     private readonly TaskService _tasks;
+    private readonly ServerIdentityService _identity;
 
-    public StartupTasks(IRawStore raw, AuthService auth, TaskService tasks)
+    public StartupTasks(IRawStore raw, AuthService auth, TaskService tasks, ServerIdentityService identity)
     {
+        _identity = identity;
         _raw = raw;
         _auth = auth;
         _tasks = tasks;
@@ -24,6 +26,7 @@ public sealed class StartupTasks : IHostedService
         await _raw.RecoverAsync(cancellationToken);
         await _auth.EnsureInitialAdminAsync(cancellationToken);
         await _tasks.SeedDefaultsAsync(cancellationToken);
+        await _identity.EnsureAsync(cancellationToken);
     }
 
     public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;

backend/src/MoShiro.Backend.Application/Tasks/TaskPlanner.cs

@@ -21,10 +21,12 @@ public sealed class TaskPlanner : IDisposable
     private readonly IProbeStore _probes;
     private readonly ISettingsStore _settings;
     private readonly LinkService _links;
+    private readonly TrustService _trust;
     private readonly SemaphoreSlim _gate = new(1, 1);
 
-    public TaskPlanner(ITaskStore tasks, IAgentStore agents, IProbeStore probes, ISettingsStore settings, LinkService links)
+    public TaskPlanner(ITaskStore tasks, IAgentStore agents, IProbeStore probes, ISettingsStore settings, LinkService links, TrustService trust)
     {
+        _trust = trust;
         _links = links;
         _tasks = tasks;
         _agents = agents;
@@ -65,6 +67,9 @@ public sealed class TaskPlanner : IDisposable
             document.Peers.Add(new PeerSpec { ProbeId = new ProbeId(probe.Id), PublicKey = Convert.ToBase64String(probe.PeerPublicKey!) });
         }
 
+        IReadOnlyList<Fleet.Core.SignedStatementDto> chain = await _trust.ChainAsync(ct);
+        document.TrustChain = chain.Count == 0 ? null : [.. chain];
+
         string hash = Convert.ToHexStringLower(SHA256.HashData(JsonSerializer.SerializeToUtf8Bytes(document, MoShiroJsonContext.Default.TaskSet)));
 
         await _gate.WaitAsync(ct);

backend/src/MoShiro.Backend.Storage.Sqlite/Schema.cs

@@ -5,7 +5,7 @@ namespace MoShiro.Backend.Storage.Sqlite;
 /// <summary>表结构。版本记录在 <c>PRAGMA user_version</c>；以后的迁移是按版本号追加的内置 SQL。</summary>
 internal static class Schema
 {
-    public const int CurrentVersion = 10;
+    public const int CurrentVersion = 13;
 
     public static void Migrate(SqliteConnection connection)
     {
@@ -140,6 +140,87 @@ internal static class Schema
             connection.Exec("PRAGMA user_version = 10");
             transaction.Commit();
         }
+
+        if (version < 11)
+        {
+            // 权限从三个作用域改成细粒度的能力。破坏性变更，不做兼容：旧的 API 令牌全部作废，需要重新创建
+            using SqliteTransaction transaction = connection.BeginTransaction();
+            connection.Exec("DROP TABLE api_tokens");
+            connection.Exec("""
+                CREATE TABLE api_tokens (
+                  id TEXT PRIMARY KEY,
+                  name TEXT NOT NULL,
+                  capabilities TEXT NOT NULL,
+                  token_sha256 BLOB NOT NULL UNIQUE,
+                  created_at INTEGER NOT NULL,
+                  last_used_at INTEGER,
+                  expires_at INTEGER,
+                  revoked_at INTEGER
+                )
+                """);
+            connection.Exec("PRAGMA user_version = 11");
+            transaction.Commit();
+        }
+
+        if (version < 12)
+        {
+            // passkey 登录：每个用户可以注册若干 passkey（凭证公钥 SPKI、签名计数器）；会话记录是怎么登录的，只有 passkey 登录的会话以后能提权
+            using SqliteTransaction transaction = connection.BeginTransaction();
+            connection.Exec("""
+                CREATE TABLE passkeys (
+                  id TEXT PRIMARY KEY,
+                  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+                  name TEXT NOT NULL,
+                  public_key BLOB NOT NULL,
+                  sign_count INTEGER NOT NULL DEFAULT 0,
+                  transports TEXT NOT NULL DEFAULT '[]',
+                  created_at INTEGER NOT NULL,
+                  last_used_at INTEGER
+                )
+                """);
+            connection.Exec("CREATE INDEX ix_passkeys_user ON passkeys (user_id)");
+            connection.Exec("ALTER TABLE sessions ADD COLUMN auth_method TEXT NOT NULL DEFAULT 'password'");
+            connection.Exec("PRAGMA user_version = 12");
+            transaction.Commit();
+        }
+
+        if (version < 13)
+        {
+            // 归属：加入码是谁创建的，节点是用哪个加入码（也就是谁）加进来的；审计日志
+            using SqliteTransaction transaction = connection.BeginTransaction();
+            connection.Exec("ALTER TABLE join_tokens ADD COLUMN created_by TEXT");
+            connection.Exec("ALTER TABLE agents ADD COLUMN added_by TEXT");
+            connection.Exec("ALTER TABLE probes ADD COLUMN added_by TEXT");
+            connection.Exec("""
+                CREATE TABLE audit_log (
+                  id INTEGER PRIMARY KEY,
+                  at INTEGER NOT NULL,
+                  user_id TEXT,
+                  actor TEXT NOT NULL,
+                  method TEXT NOT NULL,
+                  action TEXT NOT NULL,
+                  target TEXT,
+                  detail TEXT,
+                  remote TEXT,
+                  success INTEGER NOT NULL
+                )
+                """);
+            connection.Exec("CREATE INDEX ix_audit_time ON audit_log (at)");
+            connection.Exec(
+                """
+                CREATE TABLE operator_sets (
+                  version INTEGER PRIMARY KEY,
+                  statement TEXT NOT NULL,
+                  credential_id TEXT NOT NULL,
+                  authenticator_data TEXT NOT NULL,
+                  client_data_json TEXT NOT NULL,
+                  signature TEXT NOT NULL,
+                  created_at INTEGER NOT NULL
+                )
+                """);
+            connection.Exec("PRAGMA user_version = 13");
+            transaction.Commit();
+        }
     }
 
     /// <summary>

backend/src/MoShiro.Backend.Storage.Sqlite/SqliteAgentStore.cs

@@ -14,7 +14,7 @@ public sealed class SqliteAgentStore : IAgentStore, IFleetStore
 {
     private const string AgentColumns =
         "id, name, status, pubkey, tls_spki, public_host, probe_tcp_port, probe_udp_ports, labels, public_visible, kinds, agent_version, local_limits, " +
-        "task_version, applied_task_version, rejected, created_at, last_seen_at, row_version, ipv6_host, ipv6_supported, ipv6_diagnostics, public_host_manual, ipv6_host_manual, reported_addresses, tls_pubkey";
+        "task_version, applied_task_version, rejected, created_at, last_seen_at, row_version, ipv6_host, ipv6_supported, ipv6_diagnostics, public_host_manual, ipv6_host_manual, reported_addresses, tls_pubkey, added_by";
 
     private readonly SqliteDatabase _db;
 
@@ -157,8 +157,8 @@ public sealed class SqliteAgentStore : IAgentStore, IFleetStore
         byte[] hash = tokenSha256.ToArray();
         return _db.ReadAsync(
             c => c.QueryOne(
-                "SELECT id, token_sha256, note, labels, auto_approve, max_uses, uses, expires_at, revoked_at, created_at, kind FROM join_tokens WHERE token_sha256 = @h",
-                r => new JoinTokenRecord(r.GetString(0), r.Bytes(1), r.NullableString(2), StorageJson.Strings(r.GetString(3)), r.GetInt64(4) != 0, r.GetInt32(5), r.GetInt32(6), r.GetInt64(7), r.NullableLong(8), r.GetInt64(9), r.GetString(10)),
+                "SELECT id, token_sha256, note, labels, auto_approve, max_uses, uses, expires_at, revoked_at, created_at, kind, created_by FROM join_tokens WHERE token_sha256 = @h",
+                r => new JoinTokenRecord(r.GetString(0), r.Bytes(1), r.NullableString(2), StorageJson.Strings(r.GetString(3)), r.GetInt64(4) != 0, r.GetInt32(5), r.GetInt32(6), r.GetInt64(7), r.NullableLong(8), r.GetInt64(9), r.GetString(10), r.NullableString(11)),
                 ("@h", hash)),
             ct);
     }
@@ -184,9 +184,9 @@ public sealed class SqliteAgentStore : IAgentStore, IFleetStore
             }
 
             c.Exec(
-                "INSERT INTO agents (id, name, status, pubkey, tls_spki, labels, meta, agent_version, created_at) VALUES (@id, @name, @status, @pubkey, @spki, @labels, @meta, @version, @now)",
+                "INSERT INTO agents (id, name, status, pubkey, tls_spki, labels, meta, agent_version, created_at, added_by) VALUES (@id, @name, @status, @pubkey, @spki, @labels, @meta, @version, @now, @by)",
                 ("@id", node.Id.Value), ("@name", node.Name), ("@status", StatusText(node.Status)), ("@pubkey", node.PublicKey), ("@spki", node.TlsSpki),
-                ("@labels", StorageJson.ToJson(node.Labels)), ("@meta", node.MetaJson), ("@version", node.NodeVersion), ("@now", node.NowMs));
+                ("@labels", StorageJson.ToJson(node.Labels)), ("@meta", node.MetaJson), ("@version", node.NodeVersion), ("@now", node.NowMs), ("@by", node.AddedBy));
             return Result<NodeRecord>.Ok(ToNode(GetInternal(c, node.Id)!, node.MetaJson));
         }, ct);
 
@@ -204,8 +204,8 @@ public sealed class SqliteAgentStore : IAgentStore, IFleetStore
         }
 
         c.Exec(
-            "INSERT INTO probes (id, name, pubkey, peer_pubkey, created_at) VALUES (@id, @name, @pubkey, @peer, @now)",
-            ("@id", node.Id.Value), ("@name", node.Name), ("@pubkey", node.PublicKey), ("@peer", peerKey), ("@now", node.NowMs));
+            "INSERT INTO probes (id, name, pubkey, peer_pubkey, created_at, added_by) VALUES (@id, @name, @pubkey, @peer, @now, @by)",
+            ("@id", node.Id.Value), ("@name", node.Name), ("@pubkey", node.PublicKey), ("@peer", peerKey), ("@now", node.NowMs), ("@by", node.AddedBy));
         return Result<NodeRecord>.Ok(new NodeRecord(node.Id, node.Name, NodeStatus.Active, node.PublicKey, node.TlsSpki, node.Labels, node.MetaJson, node.NodeVersion, node.NowMs, null));
     }
 
@@ -267,7 +267,8 @@ public sealed class SqliteAgentStore : IAgentStore, IFleetStore
         r.GetInt64(22) != 0,
         r.GetInt64(23) != 0,
         StorageJson.Strings(r.GetString(24)),
-        r.NullableBytes(25));
+        r.NullableBytes(25),
+        r.NullableString(26));
 
     private static NodeRecord ToNode(AgentRecord a, string? metaJson) =>
         new(a.Id, a.Name, a.Status, a.PublicKey, a.TlsSpki, a.Labels, metaJson, a.AgentVersion, a.CreatedAtMs, a.LastSeenAtMs);

backend/src/MoShiro.Backend.Storage.Sqlite/SqliteAuditStore.cs

@@ -0,0 +1,33 @@
+using MoShiro.Backend.Application;
+
+namespace MoShiro.Backend.Storage.Sqlite;
+
+public sealed class SqliteAuditStore : IAuditStore
+{
+    private readonly SqliteDatabase _db;
+
+    public SqliteAuditStore(SqliteDatabase db)
+    {
+        _db = db;
+    }
+
+    public ValueTask AddAsync(AuditRecord record, CancellationToken ct) =>
+        _db.ExecuteAsync(
+            c => c.Exec(
+                "INSERT INTO audit_log (at, user_id, actor, method, action, target, detail, remote, success) VALUES (@at, @uid, @actor, @method, @action, @target, @detail, @remote, @ok)",
+                ("@at", record.AtMs), ("@uid", record.UserId), ("@actor", record.Actor), ("@method", record.Method), ("@action", record.Action),
+                ("@target", record.Target), ("@detail", record.Detail), ("@remote", record.Remote), ("@ok", record.Success ? 1 : 0)),
+            ct);
+
+    public ValueTask<IReadOnlyList<AuditRecord>> ListAsync(AuditQuery query, CancellationToken ct) =>
+        _db.ReadAsync<IReadOnlyList<AuditRecord>>(
+            c => c.Query(
+                "SELECT id, at, user_id, actor, method, action, target, detail, remote, success FROM audit_log " +
+                "WHERE (@before IS NULL OR id < @before) AND (@actor IS NULL OR actor = @actor) AND (@action IS NULL OR action = @action) ORDER BY id DESC LIMIT @limit",
+                r => new AuditRecord(r.GetInt64(0), r.GetInt64(1), r.NullableString(2), r.GetString(3), r.GetString(4), r.GetString(5), r.NullableString(6), r.NullableString(7), r.NullableString(8), r.GetInt64(9) != 0),
+                ("@before", query.BeforeId), ("@actor", query.Actor), ("@action", query.Action), ("@limit", query.Limit)),
+            ct);
+
+    public ValueTask<int> DeleteOlderThanAsync(long cutoffMs, CancellationToken ct) =>
+        _db.WriteAsync(c => c.Exec("DELETE FROM audit_log WHERE at < @cutoff", ("@cutoff", cutoffMs)), ct);
+}

backend/src/MoShiro.Backend.Storage.Sqlite/SqliteAuthStore.cs

@@ -6,7 +6,7 @@ namespace MoShiro.Backend.Storage.Sqlite;
 public sealed class SqliteAuthStore : IAuthStore
 {
     private const string UserColumns = "id, username, password_hash, password_salt, iterations, created_at";
-    private const string TokenColumns = "id, name, scope, token_sha256, created_at, last_used_at, revoked_at";
+    private const string TokenColumns = "id, name, capabilities, token_sha256, created_at, last_used_at, expires_at, revoked_at";
 
     private readonly SqliteDatabase _db;
 
@@ -46,13 +46,13 @@ public sealed class SqliteAuthStore : IAuthStore
     public ValueTask CreateSessionAsync(SessionRecord session, CancellationToken ct) =>
         _db.ExecuteAsync(
             c => c.Exec(
-                "INSERT INTO sessions (id_sha256, user_id, csrf_token, created_at, expires_at) VALUES (@id, @u, @csrf, @c, @e)",
-                ("@id", session.IdSha256), ("@u", session.UserId), ("@csrf", session.CsrfToken), ("@c", session.CreatedAtMs), ("@e", session.ExpiresAtMs)),
+                "INSERT INTO sessions (id_sha256, user_id, csrf_token, created_at, expires_at, auth_method) VALUES (@id, @u, @csrf, @c, @e, @m)",
+                ("@id", session.IdSha256), ("@u", session.UserId), ("@csrf", session.CsrfToken), ("@c", session.CreatedAtMs), ("@e", session.ExpiresAtMs), ("@m", session.AuthMethod)),
             ct);
 
     public ValueTask<SessionRecord?> GetSessionAsync(byte[] idSha256, CancellationToken ct) =>
         _db.ReadAsync(
-            c => c.QueryOne("SELECT id_sha256, user_id, csrf_token, created_at, expires_at FROM sessions WHERE id_sha256 = @id", r => new SessionRecord(r.Bytes(0), r.GetString(1), r.Bytes(2), r.GetInt64(3), r.GetInt64(4)), ("@id", idSha256)),
+            c => c.QueryOne("SELECT id_sha256, user_id, csrf_token, created_at, expires_at, auth_method FROM sessions WHERE id_sha256 = @id", r => new SessionRecord(r.Bytes(0), r.GetString(1), r.Bytes(2), r.GetInt64(3), r.GetInt64(4), r.GetString(5)), ("@id", idSha256)),
             ct);
 
     public ValueTask DeleteSessionAsync(byte[] idSha256, CancellationToken ct) =>
@@ -64,10 +64,34 @@ public sealed class SqliteAuthStore : IAuthStore
     public ValueTask CreateApiTokenAsync(ApiTokenRecord token, CancellationToken ct) =>
         _db.ExecuteAsync(
             c => c.Exec(
-                "INSERT INTO api_tokens (id, name, scope, token_sha256, created_at) VALUES (@id, @n, @s, @h, @at)",
-                ("@id", token.Id), ("@n", token.Name), ("@s", token.Scope), ("@h", token.TokenSha256), ("@at", token.CreatedAtMs)),
+                "INSERT INTO api_tokens (id, name, capabilities, token_sha256, created_at, expires_at) VALUES (@id, @n, @caps, @h, @at, @exp)",
+                ("@id", token.Id), ("@n", token.Name), ("@caps", StorageJson.ToJson(token.Capabilities)), ("@h", token.TokenSha256), ("@at", token.CreatedAtMs), ("@exp", token.ExpiresAtMs)),
             ct);
 
+    public ValueTask<bool> AddPasskeyAsync(PasskeyRecord passkey, CancellationToken ct) =>
+        _db.WriteAsync(
+            c => c.Scalar<long>("SELECT COUNT(*) FROM passkeys WHERE id = @id", ("@id", passkey.Id)) > 0
+                ? false
+                : c.Exec(
+                    "INSERT INTO passkeys (id, user_id, name, public_key, sign_count, transports, created_at) VALUES (@id, @u, @n, @k, @s, @t, @at)",
+                    ("@id", passkey.Id), ("@u", passkey.UserId), ("@n", passkey.Name), ("@k", passkey.PublicKeySpki), ("@s", passkey.SignCount), ("@t", StorageJson.ToJson(passkey.Transports)), ("@at", passkey.CreatedAtMs)) == 1,
+            ct);
+
+    public ValueTask<PasskeyRecord?> FindPasskeyAsync(string credentialId, CancellationToken ct) =>
+        _db.ReadAsync(c => c.QueryOne($"SELECT {PasskeyColumns} FROM passkeys WHERE id = @id", ReadPasskey, ("@id", credentialId)), ct);
+
+    public ValueTask<IReadOnlyList<PasskeyRecord>> ListPasskeysAsync(string userId, CancellationToken ct) =>
+        _db.ReadAsync<IReadOnlyList<PasskeyRecord>>(c => c.Query($"SELECT {PasskeyColumns} FROM passkeys WHERE user_id = @u ORDER BY created_at, id", ReadPasskey, ("@u", userId)), ct);
+
+    public ValueTask<IReadOnlyList<PasskeyRecord>> ListAllPasskeysAsync(CancellationToken ct) =>
+        _db.ReadAsync<IReadOnlyList<PasskeyRecord>>(c => c.Query($"SELECT {PasskeyColumns} FROM passkeys ORDER BY created_at, id", ReadPasskey), ct);
+
+    public ValueTask<bool> DeletePasskeyAsync(string userId, string credentialId, CancellationToken ct) =>
+        _db.WriteAsync(c => c.Exec("DELETE FROM passkeys WHERE id = @id AND user_id = @u", ("@id", credentialId), ("@u", userId)) == 1, ct);
+
+    public ValueTask TouchPasskeyAsync(string credentialId, long signCount, long nowMs, CancellationToken ct) =>
+        _db.ExecuteAsync(c => c.Exec("UPDATE passkeys SET sign_count = @s, last_used_at = @now WHERE id = @id", ("@id", credentialId), ("@s", signCount), ("@now", nowMs)), ct);
+
     public ValueTask<ApiTokenRecord?> FindApiTokenAsync(byte[] tokenSha256, CancellationToken ct) =>
         _db.ReadAsync(c => c.QueryOne($"SELECT {TokenColumns} FROM api_tokens WHERE token_sha256 = @h", ReadToken, ("@h", tokenSha256)), ct);
 
@@ -80,7 +104,11 @@ public sealed class SqliteAuthStore : IAuthStore
     public ValueTask TouchApiTokenAsync(string id, long nowMs, CancellationToken ct) =>
         _db.ExecuteAsync(c => c.Exec("UPDATE api_tokens SET last_used_at = @now WHERE id = @id", ("@id", id), ("@now", nowMs)), ct);
 
+    private const string PasskeyColumns = "id, user_id, name, public_key, sign_count, transports, created_at, last_used_at";
+
+    private static PasskeyRecord ReadPasskey(SqliteDataReader r) => new(r.GetString(0), r.GetString(1), r.GetString(2), r.Bytes(3), r.GetInt64(4), StorageJson.Strings(r.GetString(5)), r.GetInt64(6), r.NullableLong(7));
+
     private static UserRecord ReadUser(SqliteDataReader r) => new(r.GetString(0), r.GetString(1), r.Bytes(2), r.Bytes(3), r.GetInt32(4), r.GetInt64(5));
 
-    private static ApiTokenRecord ReadToken(SqliteDataReader r) => new(r.GetString(0), r.GetString(1), r.GetString(2), r.Bytes(3), r.GetInt64(4), r.NullableLong(5), r.NullableLong(6));
+    private static ApiTokenRecord ReadToken(SqliteDataReader r) => new(r.GetString(0), r.GetString(1), StorageJson.Strings(r.GetString(2)), r.Bytes(3), r.GetInt64(4), r.NullableLong(5), r.NullableLong(6), r.NullableLong(7));
 }

backend/src/MoShiro.Backend.Storage.Sqlite/SqliteConfigStores.cs

@@ -15,28 +15,28 @@ public sealed class SqliteJoinTokenStore : IJoinTokenStore
         _db = db;
     }
 
-    public ValueTask<JoinTokenInfo> CreateAsync(string id, byte[] tokenSha256, string? note, IReadOnlyList<string> labels, bool autoApprove, string kind, int maxUses, long expiresAtMs, long nowMs, CancellationToken ct) =>
+    public ValueTask<JoinTokenInfo> CreateAsync(string id, byte[] tokenSha256, string? note, IReadOnlyList<string> labels, bool autoApprove, string kind, int maxUses, long expiresAtMs, long nowMs, string? createdBy, CancellationToken ct) =>
         _db.WriteAsync(c =>
         {
             c.Exec(
-                "INSERT INTO join_tokens (id, token_sha256, note, labels, auto_approve, kind, max_uses, expires_at, created_at) VALUES (@id, @h, @note, @labels, @auto, @kind, @max, @exp, @now)",
+                "INSERT INTO join_tokens (id, token_sha256, note, labels, auto_approve, kind, max_uses, expires_at, created_at, created_by) VALUES (@id, @h, @note, @labels, @auto, @kind, @max, @exp, @now, @by)",
                 ("@id", id), ("@h", tokenSha256), ("@note", note), ("@labels", StorageJson.ToJson(labels)), ("@auto", autoApprove ? 1 : 0), ("@kind", kind),
-                ("@max", maxUses), ("@exp", expiresAtMs), ("@now", nowMs));
-            return new JoinTokenInfo(id, note, labels, autoApprove, maxUses, 0, expiresAtMs, null, nowMs, kind);
+                ("@max", maxUses), ("@exp", expiresAtMs), ("@now", nowMs), ("@by", createdBy));
+            return new JoinTokenInfo(id, note, labels, autoApprove, maxUses, 0, expiresAtMs, null, nowMs, kind, createdBy);
         }, ct);
 
     public ValueTask<IReadOnlyList<JoinTokenInfo>> ListAsync(CancellationToken ct) =>
         _db.ReadAsync<IReadOnlyList<JoinTokenInfo>>(
             c => c.Query(
-                "SELECT id, note, labels, auto_approve, max_uses, uses, expires_at, revoked_at, created_at, kind FROM join_tokens ORDER BY created_at DESC, id",
-                r => new JoinTokenInfo(r.GetString(0), r.NullableString(1), StorageJson.Strings(r.GetString(2)), r.GetInt64(3) != 0, r.GetInt32(4), r.GetInt32(5), r.GetInt64(6), r.NullableLong(7), r.GetInt64(8), r.GetString(9))),
+                "SELECT id, note, labels, auto_approve, max_uses, uses, expires_at, revoked_at, created_at, kind, created_by FROM join_tokens ORDER BY created_at DESC, id",
+                r => new JoinTokenInfo(r.GetString(0), r.NullableString(1), StorageJson.Strings(r.GetString(2)), r.GetInt64(3) != 0, r.GetInt32(4), r.GetInt32(5), r.GetInt64(6), r.NullableLong(7), r.GetInt64(8), r.GetString(9), r.NullableString(10))),
             ct);
 
     public ValueTask<JoinTokenInfo?> FindAsync(byte[] tokenSha256, CancellationToken ct) =>
         _db.ReadAsync(
             c => c.QueryOne(
-                "SELECT id, note, labels, auto_approve, max_uses, uses, expires_at, revoked_at, created_at, kind FROM join_tokens WHERE token_sha256 = @h",
-                r => new JoinTokenInfo(r.GetString(0), r.NullableString(1), StorageJson.Strings(r.GetString(2)), r.GetInt64(3) != 0, r.GetInt32(4), r.GetInt32(5), r.GetInt64(6), r.NullableLong(7), r.GetInt64(8), r.GetString(9)),
+                "SELECT id, note, labels, auto_approve, max_uses, uses, expires_at, revoked_at, created_at, kind, created_by FROM join_tokens WHERE token_sha256 = @h",
+                r => new JoinTokenInfo(r.GetString(0), r.NullableString(1), StorageJson.Strings(r.GetString(2)), r.GetInt64(3) != 0, r.GetInt32(4), r.GetInt32(5), r.GetInt64(6), r.NullableLong(7), r.GetInt64(8), r.GetString(9), r.NullableString(10)),
                 ("@h", tokenSha256)),
             ct);
 
@@ -58,12 +58,12 @@ public sealed class SqliteProbeStore : IProbeStore
 
     public ValueTask<IReadOnlyList<ProbeRecord>> ListAsync(CancellationToken ct) =>
         _db.ReadAsync<IReadOnlyList<ProbeRecord>>(
-            c => c.Query("SELECT id, name, pubkey, created_at, revoked_at, ipv6_diagnostics, peer_pubkey FROM probes ORDER BY created_at, id", r => new ProbeRecord(r.GetString(0), r.GetString(1), r.Bytes(2), r.GetInt64(3), r.NullableLong(4), r.NullableString(5), r.NullableBytes(6))),
+            c => c.Query("SELECT id, name, pubkey, created_at, revoked_at, ipv6_diagnostics, peer_pubkey, added_by FROM probes ORDER BY created_at, id", r => new ProbeRecord(r.GetString(0), r.GetString(1), r.Bytes(2), r.GetInt64(3), r.NullableLong(4), r.NullableString(5), r.NullableBytes(6), r.NullableString(7))),
             ct);
 
     public ValueTask<ProbeRecord?> GetAsync(string id, CancellationToken ct) =>
         _db.ReadAsync(
-            c => c.QueryOne("SELECT id, name, pubkey, created_at, revoked_at, ipv6_diagnostics, peer_pubkey FROM probes WHERE id = @id", r => new ProbeRecord(r.GetString(0), r.GetString(1), r.Bytes(2), r.GetInt64(3), r.NullableLong(4), r.NullableString(5), r.NullableBytes(6)), ("@id", id)),
+            c => c.QueryOne("SELECT id, name, pubkey, created_at, revoked_at, ipv6_diagnostics, peer_pubkey, added_by FROM probes WHERE id = @id", r => new ProbeRecord(r.GetString(0), r.GetString(1), r.Bytes(2), r.GetInt64(3), r.NullableLong(4), r.NullableString(5), r.NullableBytes(6), r.NullableString(7)), ("@id", id)),
             ct);
 
     public ValueTask SetIpv6DiagnosticsAsync(string id, string diagnosticsJson, CancellationToken ct) =>

backend/src/MoShiro.Backend.Storage.Sqlite/SqliteOperatorSetStore.cs

@@ -0,0 +1,28 @@
+using Fleet.Core;
+using MoShiro.Backend.Application;
+
+namespace MoShiro.Backend.Storage.Sqlite;
+
+public sealed class SqliteOperatorSetStore : IOperatorSetStore
+{
+    private readonly SqliteDatabase _db;
+
+    public SqliteOperatorSetStore(SqliteDatabase db)
+    {
+        _db = db;
+    }
+
+    public ValueTask<IReadOnlyList<SignedStatementDto>> ListAsync(CancellationToken ct) =>
+        _db.ReadAsync<IReadOnlyList<SignedStatementDto>>(
+            c => c.Query(
+                "SELECT statement, credential_id, authenticator_data, client_data_json, signature FROM operator_sets ORDER BY version",
+                r => new SignedStatementDto { Statement = r.GetString(0), CredentialId = r.GetString(1), AuthenticatorData = r.GetString(2), ClientDataJson = r.GetString(3), Signature = r.GetString(4) }),
+            ct);
+
+    public ValueTask<bool> AddAsync(int version, SignedStatementDto signed, long nowMs, CancellationToken ct) =>
+        _db.WriteAsync(
+            c => c.Exec(
+                "INSERT OR IGNORE INTO operator_sets (version, statement, credential_id, authenticator_data, client_data_json, signature, created_at) VALUES (@v, @s, @c, @a, @d, @g, @at)",
+                ("@v", version), ("@s", signed.Statement), ("@c", signed.CredentialId), ("@a", signed.AuthenticatorData), ("@d", signed.ClientDataJson), ("@g", signed.Signature), ("@at", nowMs)) == 1,
+            ct);
+}

backend/src/MoShiro.Backend.Storage.Sqlite/StorageServiceCollectionExtensions.cs

@@ -22,6 +22,8 @@ public static class StorageServiceCollectionExtensions
         services.AddSingleton<IHostStore, SqliteHostStore>();
         services.AddSingleton<INodeMetaStore, SqliteNodeMetaStore>();
         services.AddSingleton<IAuthStore, SqliteAuthStore>();
+        services.AddSingleton<IAuditStore, SqliteAuditStore>();
+        services.AddSingleton<IOperatorSetStore, SqliteOperatorSetStore>();
         services.AddSingleton<IRawStore, SqliteRawStore>();
         services.AddSingleton<IMetricStore, SqliteMetricStore>();
         services.AddSingleton<IStorageHealth, SqliteStorageHealth>();

backend/tests/MoShiro.Backend.Tests/AgentHarness.cs

@@ -41,12 +41,14 @@ public sealed class AgentHarness : IAsyncDisposable
 
     public byte[] TlsPublicKey => _identity.Certificate.PublicKey.ExportSubjectPublicKeyInfo();
 
-    public static async Task<AgentHarness> StartAsync(BackendFixture backend, Action<AgentConfig>? configure = null, string? name = null)
+    /// <param name="pin">带信任根固定的加入码（码、创世指纹、属主）：节点按固定了创世和属主的方式注册。</param>
+    public static async Task<AgentHarness> StartAsync(BackendFixture backend, Action<AgentConfig>? configure = null, string? name = null, (string Code, string Genesis, string[] Controllers)? pin = null)
     {
         string directory = Path.Combine(Path.GetTempPath(), "moshiro-agent-" + Guid.NewGuid().ToString("N"));
-        string token = await backend.CreateJoinTokenAsync();
+        string token = pin?.Code ?? await backend.CreateJoinTokenAsync();
         using var http = new HttpClient();
-        Result<EnrollmentResult> enrolled = await EnrollmentClient.EnrollAsync(http, backend.BaseAddress, token, name ?? backend.UniqueName("agent"), directory, AgentApp.Version, null, TimeProvider.System, CancellationToken.None);
+        Result<EnrollmentResult> enrolled = await EnrollmentClient.EnrollAsync(
+            http, backend.BaseAddress, token, name ?? backend.UniqueName("agent"), directory, AgentApp.Version, null, TimeProvider.System, CancellationToken.None, pin?.Genesis, pin?.Controllers);
         Assert.True(enrolled.IsSuccess, enrolled.IsSuccess ? "" : enrolled.Error.ToString());
 
         // 测试里的 Agent 只在回环上监听：手填 public_host（手动的优先于自动识别，Agent 上报本机真实地址也不会覆盖）

backend/tests/MoShiro.Backend.Tests/AotSmokeTests.cs

@@ -27,7 +27,7 @@ public sealed class AotSmokeTests
         login.EnsureSuccessStatusCode();
         string cookie = login.Headers.GetValues("Set-Cookie").Single().Split(';')[0];
         string csrf = JsonNode.Parse(await login.Content.ReadAsStringAsync())!["csrf_token"]!.GetValue<string>();
-        using var tokenRequest = new HttpRequestMessage(HttpMethod.Post, "/api/admin/api-tokens") { Content = BackendFixture.Json(new JsonObject { ["name"] = "aot", ["scope"] = "admin" }) };
+        using var tokenRequest = new HttpRequestMessage(HttpMethod.Post, "/api/admin/api-tokens") { Content = BackendFixture.Json(new JsonObject { ["name"] = "aot", ["capabilities"] = BackendFixture.AllCapabilities() }) };
         tokenRequest.Headers.Add("Cookie", cookie);
         tokenRequest.Headers.Add("X-CSRF-Token", csrf);
         using HttpResponseMessage tokenResponse = await http.SendAsync(tokenRequest);

backend/tests/MoShiro.Backend.Tests/ApiBasicsTests.cs

@@ -61,8 +61,11 @@ public sealed class ApiBasicsTests
     [Fact]
     public async Task Login_WithReturnSession_GivesABearerSession_WithoutACookie_AndNoCsrfNeeded()
     {
+        // 密码登录的会话没有任何能力（只能注册 passkey）；有能力的会话来自 passkey 登录
+        (string username, SoftwarePasskey passkey) = await _backend.CreateUserWithPasskeyAsync();
+        using SoftwarePasskey passkeyScope = passkey;
         using HttpClient client = _backend.NewClient();
-        using HttpResponseMessage login = await client.PostAsync("/api/admin/auth/login", BackendFixture.Json(new JsonObject { ["username"] = BackendFixture.AdminUser, ["password"] = BackendFixture.AdminPassword, ["return_session"] = true }));
+        using HttpResponseMessage login = await _backend.PasskeyLoginAsync(client, passkey);
         Assert.Equal(HttpStatusCode.OK, login.StatusCode);
         Assert.False(login.Headers.Contains("Set-Cookie"));
         string session = JsonNode.Parse(await login.Content.ReadAsStringAsync())!["session_token"]!.GetValue<string>();
@@ -73,9 +76,9 @@ public sealed class ApiBasicsTests
         me.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", session);
         using HttpResponseMessage meResponse = await client.SendAsync(me);
         Assert.Equal(HttpStatusCode.OK, meResponse.StatusCode);
-        Assert.Equal(BackendFixture.AdminUser, JsonNode.Parse(await meResponse.Content.ReadAsStringAsync())!["username"]!.GetValue<string>());
+        Assert.Equal(username, JsonNode.Parse(await meResponse.Content.ReadAsStringAsync())!["username"]!.GetValue<string>());
 
-        using var create = new HttpRequestMessage(HttpMethod.Post, "/api/admin/join-tokens") { Content = BackendFixture.Json(new JsonObject()) };
+        using var create = new HttpRequestMessage(HttpMethod.Post, "/api/admin/api-tokens") { Content = BackendFixture.Json(new JsonObject { ["name"] = "session-write", ["capabilities"] = new JsonArray("fleet.read") }) };
         create.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", session);
         using HttpResponseMessage created = await client.SendAsync(create);
         Assert.Equal(HttpStatusCode.Created, created.StatusCode);
@@ -94,8 +97,10 @@ public sealed class ApiBasicsTests
     [Fact]
     public async Task SessionCookie_RequiresCsrfHeaderOnUnsafeMethods()
     {
+        (_, SoftwarePasskey passkey) = await _backend.CreateUserWithPasskeyAsync();
+        using SoftwarePasskey passkeyScope = passkey;
         using HttpClient client = _backend.NewClient();
-        using HttpResponseMessage login = await client.PostAsync("/api/admin/auth/login", BackendFixture.Json(new JsonObject { ["username"] = BackendFixture.AdminUser, ["password"] = BackendFixture.AdminPassword }));
+        using HttpResponseMessage login = await _backend.PasskeyLoginAsync(client, passkey, returnSession: false);
         string csrf = JsonNode.Parse(await login.Content.ReadAsStringAsync())!["csrf_token"]!.GetValue<string>();
         string cookie = login.Headers.GetValues("Set-Cookie").Single().Split(';')[0];
 
@@ -104,19 +109,19 @@ public sealed class ApiBasicsTests
         using HttpResponseMessage me = await client.SendAsync(get);
         Assert.Equal(HttpStatusCode.OK, me.StatusCode);
 
-        using var withoutCsrf = new HttpRequestMessage(HttpMethod.Post, "/api/admin/join-tokens") { Content = BackendFixture.Json(new JsonObject()) };
+        using var withoutCsrf = new HttpRequestMessage(HttpMethod.Post, "/api/admin/api-tokens") { Content = BackendFixture.Json(new JsonObject { ["name"] = "session-write", ["capabilities"] = new JsonArray("fleet.read") }) };
         withoutCsrf.Headers.Add("Cookie", cookie);
         using HttpResponseMessage rejected = await client.SendAsync(withoutCsrf);
         Assert.Equal(HttpStatusCode.Unauthorized, rejected.StatusCode);
         Assert.Equal("csrf_failed", JsonNode.Parse(await rejected.Content.ReadAsStringAsync())!["code"]!.GetValue<string>());
 
-        using var wrongCsrf = new HttpRequestMessage(HttpMethod.Post, "/api/admin/join-tokens") { Content = BackendFixture.Json(new JsonObject()) };
+        using var wrongCsrf = new HttpRequestMessage(HttpMethod.Post, "/api/admin/api-tokens") { Content = BackendFixture.Json(new JsonObject { ["name"] = "session-write", ["capabilities"] = new JsonArray("fleet.read") }) };
         wrongCsrf.Headers.Add("Cookie", cookie);
         wrongCsrf.Headers.Add("X-CSRF-Token", csrf + "x");
         using HttpResponseMessage wrong = await client.SendAsync(wrongCsrf);
         Assert.Equal(HttpStatusCode.Unauthorized, wrong.StatusCode);
 
-        using var good = new HttpRequestMessage(HttpMethod.Post, "/api/admin/join-tokens") { Content = BackendFixture.Json(new JsonObject()) };
+        using var good = new HttpRequestMessage(HttpMethod.Post, "/api/admin/api-tokens") { Content = BackendFixture.Json(new JsonObject { ["name"] = "session-write", ["capabilities"] = new JsonArray("fleet.read") }) };
         good.Headers.Add("Cookie", cookie);
         good.Headers.Add("X-CSRF-Token", csrf);
         using HttpResponseMessage created = await client.SendAsync(good);
@@ -124,9 +129,9 @@ public sealed class ApiBasicsTests
     }
 
     [Fact]
-    public async Task ReadScopedToken_CanReadButNotManage()
+    public async Task PublicReadToken_CanReadThePublicApiButNothingUnderAdmin()
     {
-        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "viewer", ["scope"] = "read" }));
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "viewer", ["capabilities"] = BackendFixture.Capabilities("public.read") }));
         Assert.Equal(HttpStatusCode.Created, created.StatusCode);
         Assert.Equal("no-store", created.Headers.CacheControl!.ToString());
         string token = JsonNode.Parse(await created.Content.ReadAsStringAsync())!["plaintext"]!.GetValue<string>();
@@ -220,15 +225,6 @@ public sealed class ApiBasicsTests
         Assert.Contains("moshiro_agents_online", text);
         Assert.Contains("moshiro_analysis_queue_length", text);
     }
-
-    [Fact]
-    public async Task InstallScripts_RequireAValidCode()
-    {
-        // 一行安装脚本凭一次性代码获取；没有代码或代码不能用是 404（完整行为见 InstallTests）
-        using HttpResponseMessage response = await _backend.Anonymous.GetAsync("/install.sh");
-        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
-        Assert.Equal("not_found", JsonNode.Parse(await response.Content.ReadAsStringAsync())!["code"]!.GetValue<string>());
-    }
 }
 
 [CollectionDefinition("backend")]

backend/tests/MoShiro.Backend.Tests/AuditTests.cs

@@ -0,0 +1,68 @@
+using System.Net;
+using System.Text.Json.Nodes;
+
+namespace MoShiro.Backend.Tests;
+
+/// <summary>审计日志：写操作、登录成败都会记一行；谁做的（用户名或 key:令牌名）、结果、细节。</summary>
+[Collection("probe-e2e")]
+public sealed class AuditTests
+{
+    private readonly BackendFixture _backend;
+
+    public AuditTests(BackendFixture backend)
+    {
+        _backend = backend;
+    }
+
+    /// <summary>审计在响应发完之后才写，轮询一下。</summary>
+    private async Task<JsonNode?> FindAsync(string query, Func<JsonNode, bool> match)
+    {
+        for (int i = 0; i < 50; i++)
+        {
+            JsonNode page = JsonNode.Parse(await _backend.Admin.GetStringAsync("/api/admin/audit?" + query))!;
+            if (page["items"]!.AsArray().FirstOrDefault(x => x is not null && match(x)) is { } found)
+            {
+                return found;
+            }
+
+            await Task.Delay(100);
+        }
+
+        return null;
+    }
+
+    [Fact]
+    public async Task WriteActions_AreRecorded_WithWhoAndTheDetail()
+    {
+        string note = "audit-" + Guid.NewGuid().ToString("N")[..8];
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/join-tokens", BackendFixture.Json(new JsonObject { ["role"] = "probe", ["note"] = note }));
+        Assert.Equal(HttpStatusCode.Created, created.StatusCode);
+
+        JsonNode? row = await FindAsync("limit=100", x => x["detail"]?.GetValue<string>().Contains(note, StringComparison.Ordinal) == true);
+        Assert.NotNull(row);
+        Assert.StartsWith("key:", row["actor"]!.GetValue<string>(), StringComparison.Ordinal);
+        Assert.Equal("key", row["method"]!.GetValue<string>());
+        Assert.True(row["success"]!.GetValue<bool>());
+        Assert.False(string.IsNullOrEmpty(row["action"]!.GetValue<string>()));
+    }
+
+    [Fact]
+    public async Task FailedSignIn_IsRecorded_WithTheAttemptedName_AndWithoutThePassword()
+    {
+        string name = "nobody-" + Guid.NewGuid().ToString("N")[..8];
+        using HttpResponseMessage denied = await _backend.Anonymous.PostAsync("/api/admin/auth/login", BackendFixture.Json(new JsonObject { ["username"] = name, ["password"] = "secret-pw-123" }));
+        Assert.Equal(HttpStatusCode.Unauthorized, denied.StatusCode);
+
+        JsonNode? row = await FindAsync("action=auth.login&limit=100", x => x["actor"]!.GetValue<string>() == name);
+        Assert.NotNull(row);
+        Assert.False(row["success"]!.GetValue<bool>());
+        Assert.DoesNotContain("secret-pw-123", row.ToJsonString(), StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task Audit_NeedsItsOwnCapability()
+    {
+        using HttpResponseMessage response = await _backend.Anonymous.GetAsync("/api/admin/audit");
+        Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
+    }
+}

backend/tests/MoShiro.Backend.Tests/BackendFixture.cs

@@ -135,6 +135,46 @@ public class BackendFixture : IAsyncLifetime
         Admin.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", _adminToken);
     }
 
+    /// <summary>新建一个用户（管理员用 API key 建），用密码登录一次注册好 passkey。之后用 <see cref="PasskeyLoginAsync"/> 登录才有能力。</summary>
+    public async Task<(string Username, SoftwarePasskey Passkey)> CreateUserWithPasskeyAsync(string prefix = "user")
+    {
+        string name = UniqueName(prefix);
+        using HttpResponseMessage created = await Admin.PostAsync("/api/admin/users", Json(new JsonObject { ["username"] = name, ["password"] = "correct horse battery" }));
+        created.EnsureSuccessStatusCode();
+        using HttpClient session = NewClient();
+        using HttpResponseMessage login = await session.PostAsync("/api/admin/auth/login", Json(new JsonObject { ["username"] = name, ["password"] = "correct horse battery", ["return_session"] = true }));
+        login.EnsureSuccessStatusCode();
+        session.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", JsonNode.Parse(await login.Content.ReadAsStringAsync())!["session_token"]!.GetValue<string>());
+        var passkey = new SoftwarePasskey(BaseAddress.Host, BaseAddress.GetLeftPart(UriPartial.Authority));
+        using HttpResponseMessage options = await session.PostAsync("/api/admin/auth/passkeys/options", null);
+        options.EnsureSuccessStatusCode();
+        string challenge = JsonNode.Parse(await options.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>();
+        using HttpResponseMessage registered = await session.PostAsync("/api/admin/auth/passkeys", Json(passkey.Register("key", challenge)));
+        registered.EnsureSuccessStatusCode();
+        return (name, passkey);
+    }
+
+    /// <summary>用 passkey 登录（可发现凭证，不用用户名）；<paramref name="returnSession"/> 为真时不设 Cookie、把会话令牌放在响应里。</summary>
+    public async Task<HttpResponseMessage> PasskeyLoginAsync(HttpClient client, SoftwarePasskey passkey, bool returnSession = true)
+    {
+        using HttpResponseMessage options = await client.PostAsync("/api/admin/auth/passkey/options", null);
+        options.EnsureSuccessStatusCode();
+        JsonObject assertion = passkey.Assert(JsonNode.Parse(await options.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>());
+        assertion["return_session"] = returnSession;
+        return await client.PostAsync("/api/admin/auth/passkey/login", Json(assertion));
+    }
+
+    /// <summary>有能力的会话：新用户加 passkey，用 passkey 登录，会话令牌走 Bearer。</summary>
+    public async Task<(HttpClient Client, SoftwarePasskey Passkey, string Username)> CreateStrongSessionAsync(string prefix = "strong")
+    {
+        (string name, SoftwarePasskey passkey) = await CreateUserWithPasskeyAsync(prefix);
+        HttpClient client = NewClient();
+        using HttpResponseMessage login = await PasskeyLoginAsync(client, passkey);
+        login.EnsureSuccessStatusCode();
+        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", JsonNode.Parse(await login.Content.ReadAsStringAsync())!["session_token"]!.GetValue<string>());
+        return (client, passkey, name);
+    }
+
     public HttpClient NewClient() => new() { BaseAddress = BaseAddress };
 
     public string UniqueName(string prefix) => $"{prefix}-{Interlocked.Increment(ref _counter)}";
@@ -173,6 +213,11 @@ public class BackendFixture : IAsyncLifetime
         return JsonNode.Parse(text)!;
     }
 
+    /// <summary>目录里的全部能力（"all" 预设）。</summary>
+    public static JsonArray AllCapabilities() => Capabilities(CapabilityCatalog.Presets.Single(p => p.Id == "all").Capabilities.ToArray());
+
+    public static JsonArray Capabilities(params string[] ids) => [.. ids.Select(id => (JsonNode?)JsonValue.Create(id))];
+
     public static StringContent Json(JsonNode node, string mediaType = "application/json") =>
         new(node.ToJsonString(), Encoding.UTF8, mediaType);
 
@@ -228,19 +273,49 @@ public class BackendFixture : IAsyncLifetime
         await App.DisposeAsync();
     }
 
+    /// <summary>
+    /// 管理员的全能力 API key：和线上一样的路径——密码登录的会话没有任何能力，只能注册 passkey；
+    /// 注册之后用 passkey 登录才有能力，再触碰一次开凭证窗口，才能创建带信任类能力的 key。
+    /// </summary>
     private async Task<string> CreateAdminTokenAsync()
     {
         using HttpClient session = NewClient();
         using HttpResponseMessage login = await session.PostAsync(
-            "/api/admin/auth/login", Json(new JsonObject { ["username"] = AdminUser, ["password"] = AdminPassword }));
+            "/api/admin/auth/login", Json(new JsonObject { ["username"] = AdminUser, ["password"] = AdminPassword, ["return_session"] = true }));
         login.EnsureSuccessStatusCode();
-        JsonNode body = JsonNode.Parse(await login.Content.ReadAsStringAsync())!;
-        string cookie = login.Headers.GetValues("Set-Cookie").First().Split(';')[0];
+        session.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", JsonNode.Parse(await login.Content.ReadAsStringAsync())!["session_token"]!.GetValue<string>());
 
-        using var request = new HttpRequestMessage(HttpMethod.Post, "/api/admin/api-tokens") { Content = Json(new JsonObject { ["name"] = "tests", ["scope"] = "admin" }) };
-        request.Headers.Add("Cookie", cookie);
-        request.Headers.Add("X-CSRF-Token", body["csrf_token"]!.GetValue<string>());
-        using HttpResponseMessage created = await session.SendAsync(request);
+        string origin = BaseAddress.GetLeftPart(UriPartial.Authority);
+        using var passkey = new SoftwarePasskey(BaseAddress.Host, origin);
+        using (HttpResponseMessage options = await session.PostAsync("/api/admin/auth/passkeys/options", null))
+        {
+            options.EnsureSuccessStatusCode();
+            string challenge = JsonNode.Parse(await options.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>();
+            using HttpResponseMessage registered = await session.PostAsync("/api/admin/auth/passkeys", Json(passkey.Register("fixture", challenge)));
+            registered.EnsureSuccessStatusCode();
+        }
+
+        // passkey 登录：拿到有能力的会话（令牌走 Bearer）
+        using HttpClient strong = NewClient();
+        using (HttpResponseMessage options = await strong.PostAsync("/api/admin/auth/passkey/options", null))
+        {
+            options.EnsureSuccessStatusCode();
+            JsonObject assertion = passkey.Assert(JsonNode.Parse(await options.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>());
+            using HttpResponseMessage signedIn = await strong.PostAsync("/api/admin/auth/passkey/login", Json(assertion));
+            signedIn.EnsureSuccessStatusCode();
+            strong.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", JsonNode.Parse(await signedIn.Content.ReadAsStringAsync())!["session_token"]!.GetValue<string>());
+        }
+
+        using (HttpResponseMessage options = await strong.PostAsync("/api/admin/auth/elevation/options", Json(new JsonObject { ["class"] = "credential" })))
+        {
+            options.EnsureSuccessStatusCode();
+            JsonObject assertion = passkey.Assert(JsonNode.Parse(await options.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>());
+            assertion["class"] = "credential";
+            using HttpResponseMessage elevated = await strong.PostAsync("/api/admin/auth/elevation", Json(assertion));
+            elevated.EnsureSuccessStatusCode();
+        }
+
+        using HttpResponseMessage created = await strong.PostAsync("/api/admin/api-tokens", Json(new JsonObject { ["name"] = "tests", ["capabilities"] = AllCapabilities() }));
         created.EnsureSuccessStatusCode();
         return JsonNode.Parse(await created.Content.ReadAsStringAsync())!["plaintext"]!.GetValue<string>();
     }

backend/tests/MoShiro.Backend.Tests/CapabilityTests.cs

@@ -0,0 +1,132 @@
+using System.Net;
+using System.Net.Http.Headers;
+using System.Text.Json.Nodes;
+using Microsoft.AspNetCore.Routing;
+using Microsoft.Extensions.DependencyInjection;
+using MoShiro.Backend.Api;
+using MoShiro.Backend.Application;
+
+namespace MoShiro.Backend.Tests;
+
+/// <summary>能力模型（docs/access.md 第 2 节）：每个管理端点声明能力；密钥只能拿到自己拥有能力的子集；写蕴含读。</summary>
+[Collection("probe-e2e")]
+public sealed class CapabilityTests
+{
+    private readonly BackendFixture _backend;
+
+    public CapabilityTests(BackendFixture backend)
+    {
+        _backend = backend;
+    }
+
+    [Fact]
+    public void EveryAdminEndpoint_DeclaresACapabilityThatIsInTheCatalog()
+    {
+        RouteEndpoint[] endpoints = [.. _backend.Services.GetServices<EndpointDataSource>().SelectMany(s => s.Endpoints).OfType<RouteEndpoint>()
+            .Where(e => e.RoutePattern.RawText?.StartsWith("/api/admin", StringComparison.Ordinal) == true)];
+        Assert.NotEmpty(endpoints);
+        foreach (RouteEndpoint endpoint in endpoints)
+        {
+            CapabilityRequirement? requirement = endpoint.Metadata.GetMetadata<CapabilityRequirement>();
+            Assert.True(requirement is not null, $"{endpoint.RoutePattern.RawText} does not declare a capability");
+            if (requirement.Capability is { } capability)
+            {
+                Assert.True(capability == Capability.Authenticated || CapabilityCatalog.IsKnown(capability), $"{endpoint.RoutePattern.RawText} declares the unknown capability {capability}");
+            }
+        }
+
+        // 只有登录（密码和 passkey）是匿名的
+        Assert.Equal(["/api/admin/auth/login", "/api/admin/auth/passkey/login", "/api/admin/auth/passkey/options"], endpoints.Where(e => e.Metadata.GetMetadata<CapabilityRequirement>()!.Capability is null).Select(e => e.RoutePattern.RawText!).Distinct().Order(StringComparer.Ordinal).ToArray());
+    }
+
+    [Fact]
+    public void Catalog_ExpandsWritesToReads_AndPresetsAreConsistent()
+    {
+        Assert.Equal([Capability.FleetRead, Capability.FleetWrite], CapabilityCatalog.Expand([Capability.FleetWrite]));
+        Assert.Contains(Capability.FleetRead, CapabilityCatalog.Expand([Capability.FleetEnroll]));
+        foreach (CapabilityPreset preset in CapabilityCatalog.Presets)
+        {
+            Assert.All(preset.Capabilities, id => Assert.True(CapabilityCatalog.IsKnown(id), $"{preset.Id}: {id}"));
+            Assert.Equal(CapabilityCatalog.Expand(preset.Capabilities).ToArray(), preset.Capabilities.Order(StringComparer.Ordinal).ToArray()); // 预设已经包含了蕴含的能力
+        }
+
+        Assert.All(CapabilityCatalog.All.Where(c => c.Id.EndsWith(".write", StringComparison.Ordinal)), c => Assert.Contains(c.Id[..^"write".Length] + "read", c.Implies));
+    }
+
+    private async Task<HttpClient> KeyAsync(params string[] capabilities)
+    {
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = _backend.UniqueName("cap"), ["capabilities"] = BackendFixture.Capabilities(capabilities) }));
+        string body = await created.Content.ReadAsStringAsync();
+        Assert.True(created.StatusCode == HttpStatusCode.Created, body);
+        HttpClient client = _backend.NewClient();
+        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", JsonNode.Parse(body)!["plaintext"]!.GetValue<string>());
+        return client;
+    }
+
+    [Fact]
+    public async Task AKey_CanOnlyDoWhatItsCapabilitiesAllow_AndWriteImpliesRead()
+    {
+        using HttpClient reader = await KeyAsync(Capability.FleetRead);
+        using HttpClient writer = await KeyAsync(Capability.FleetWrite); // 写蕴含读
+        using HttpClient settings = await KeyAsync(Capability.SettingsRead);
+
+        Assert.Equal(HttpStatusCode.OK, (await reader.GetAsync("/api/admin/agents")).StatusCode);
+        Assert.Equal(HttpStatusCode.OK, (await writer.GetAsync("/api/admin/agents")).StatusCode);
+        Assert.Equal(HttpStatusCode.Forbidden, (await settings.GetAsync("/api/admin/agents")).StatusCode);
+        Assert.Equal(HttpStatusCode.Forbidden, (await reader.GetAsync("/api/admin/settings")).StatusCode);
+        Assert.Equal(HttpStatusCode.Forbidden, (await reader.GetAsync("/api/admin/raw/chunks")).StatusCode);
+
+        // 读不能写：fleet.read 的 key 不能生成加入代码，也不能创建 key
+        using HttpResponseMessage enroll = await reader.PostAsync("/api/admin/join-tokens", BackendFixture.Json(new JsonObject { ["role"] = "agent" }));
+        Assert.Equal(HttpStatusCode.Forbidden, enroll.StatusCode);
+        using HttpResponseMessage keys = await reader.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "x", ["capabilities"] = BackendFixture.Capabilities(Capability.FleetRead) }));
+        Assert.Equal(HttpStatusCode.Forbidden, keys.StatusCode);
+
+        // 没有凭证是 401，凭证不够是 403
+        Assert.Equal(HttpStatusCode.Unauthorized, (await _backend.Anonymous.GetAsync("/api/admin/agents")).StatusCode);
+        // /auth/me 列出实际拥有的能力（包含蕴含的）
+        JsonNode me = JsonNode.Parse(await (await writer.GetAsync("/api/admin/auth/me")).Content.ReadAsStringAsync())!;
+        Assert.Equal([Capability.FleetRead, Capability.FleetWrite], me["capabilities"]!.AsArray().Select(c => c!.GetValue<string>()).ToArray());
+    }
+
+    [Fact]
+    public async Task AKey_CannotGrantWhatItDoesNotHave_ButCanGrantASubset()
+    {
+        using HttpClient manager = await KeyAsync(Capability.KeysManage, Capability.FleetRead); // keys.manage 蕴含 keys.read
+        using HttpResponseMessage beyond = await manager.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "x", ["capabilities"] = BackendFixture.Capabilities(Capability.FleetRead, Capability.FleetEnroll) }));
+        Assert.Equal(HttpStatusCode.BadRequest, beyond.StatusCode);
+        Assert.Contains("fleet.enroll", await beyond.Content.ReadAsStringAsync(), StringComparison.Ordinal);
+
+        using HttpResponseMessage subset = await manager.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "sub", ["capabilities"] = BackendFixture.Capabilities(Capability.FleetRead) }));
+        Assert.Equal(HttpStatusCode.Created, subset.StatusCode);
+
+        using HttpResponseMessage unknown = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "x", ["capabilities"] = BackendFixture.Capabilities("fleet.nope") }));
+        Assert.Equal(HttpStatusCode.BadRequest, unknown.StatusCode);
+        using HttpResponseMessage empty = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "x", ["capabilities"] = new JsonArray() }));
+        Assert.Equal(HttpStatusCode.BadRequest, empty.StatusCode);
+    }
+
+    [Fact]
+    public async Task AKey_HasAnExpiry_AndTheCatalogEndpointDescribesEverything()
+    {
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "short", ["capabilities"] = BackendFixture.Capabilities(Capability.FleetRead), ["expires_in_days"] = 1 }));
+        JsonNode body = JsonNode.Parse(await created.Content.ReadAsStringAsync())!;
+        Assert.NotNull(body["token"]!["expires_at"]);
+        using HttpResponseMessage bad = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "x", ["capabilities"] = BackendFixture.Capabilities(Capability.FleetRead), ["expires_in_days"] = 0 }));
+        Assert.Equal(HttpStatusCode.BadRequest, bad.StatusCode);
+
+        JsonNode catalog = await _backend.GetJsonAsync(_backend.Admin, "/api/admin/capabilities");
+        string[] ids = [.. catalog["groups"]!.AsArray().SelectMany(g => g!["capabilities"]!.AsArray()).Select(c => c!["id"]!.GetValue<string>())];
+        Assert.Equal(CapabilityCatalog.All.Select(c => c.Id).Order(StringComparer.Ordinal).ToArray(), ids.Order(StringComparer.Ordinal).ToArray());
+        Assert.Contains(catalog["presets"]!.AsArray(), p => p!["id"]!.GetValue<string>() == "all");
+        Assert.Contains(catalog["groups"]!.AsArray().SelectMany(g => g!["capabilities"]!.AsArray()), c => c!["id"]!.GetValue<string>() == Capability.FleetRevoke && c["trust"]!.GetValue<bool>());
+    }
+
+    [Fact]
+    public async Task ReleaseKey_CanOnlyPublishReleases()
+    {
+        using HttpClient ci = await KeyAsync(Capability.ReleasePublish);
+        Assert.Equal(HttpStatusCode.Forbidden, (await ci.GetAsync("/api/admin/agents")).StatusCode);
+        Assert.Equal(HttpStatusCode.Forbidden, (await ci.GetAsync("/api/admin/backend/update")).StatusCode);
+    }
+}

backend/tests/MoShiro.Backend.Tests/ClientAddressTests.cs

@@ -0,0 +1,51 @@
+using System.Net;
+using Microsoft.AspNetCore.Http;
+using MoShiro.Backend.Api;
+using MoShiro.Backend.Application;
+
+namespace MoShiro.Backend.Tests;
+
+/// <summary>真实来源地址：只有从可信代理连进来的请求才采信转发头，而且取最右边第一个不可信的地址。</summary>
+public sealed class ClientAddressTests
+{
+    private static string Resolve(string? trusted, string remote, string? forwarded, string? header = null)
+    {
+        var resolver = new ClientAddressResolver(new BackendOptions { TrustedProxies = trusted, TrustedProxyHeader = header });
+        var http = new DefaultHttpContext();
+        http.Connection.RemoteIpAddress = IPAddress.Parse(remote);
+        if (forwarded is not null)
+        {
+            http.Request.Headers[header ?? "X-Forwarded-For"] = forwarded;
+        }
+
+        return resolver.Resolve(http);
+    }
+
+    [Fact]
+    public void WithoutTrustedProxies_TheSocketAddressIsUsed_AndTheHeaderIsIgnored() =>
+        Assert.Equal("203.0.113.9", Resolve(null, "203.0.113.9", "1.2.3.4"));
+
+    [Fact]
+    public void FromATrustedProxy_TheForwardedClientIsUsed() =>
+        Assert.Equal("198.51.100.7", Resolve("10.0.0.0/8", "10.1.2.3", "198.51.100.7"));
+
+    [Fact]
+    public void FromAnUntrustedPeer_TheHeaderIsIgnored() =>
+        Assert.Equal("203.0.113.9", Resolve("10.0.0.0/8", "203.0.113.9", "1.2.3.4"));
+
+    [Fact]
+    public void TheChainIsWalkedFromTheRight_SoAClientCannotForgeItsAddress() =>
+        Assert.Equal("198.51.100.7", Resolve("10.0.0.0/8,127.0.0.1", "10.1.2.3", "6.6.6.6, 198.51.100.7, 10.9.9.9"));
+
+    [Fact]
+    public void AGarbageHeader_FallsBackToTheSocketAddress() =>
+        Assert.Equal("10.1.2.3", Resolve("10.0.0.0/8", "10.1.2.3", "not-an-ip"));
+
+    [Fact]
+    public void ASingleAddressAndACustomHeaderWork() =>
+        Assert.Equal("198.51.100.7", Resolve("127.0.0.1", "127.0.0.1", "198.51.100.7", "CF-Connecting-IP"));
+
+    [Fact]
+    public void AMalformedTrustedProxyEntry_FailsAtStartup() =>
+        Assert.Throws<InvalidOperationException>(() => new ClientAddressResolver(new BackendOptions { TrustedProxies = "banana" }));
+}

backend/tests/MoShiro.Backend.Tests/ElevationTests.cs

@@ -0,0 +1,201 @@
+using System.Net;
+using System.Net.Http.Headers;
+using System.Text.Json.Nodes;
+
+namespace MoShiro.Backend.Tests;
+
+/// <summary>提权窗口：信任类操作（加节点、吊销、改凭证）要在登录之外再触碰一次 passkey；API key 自带能力不受影响。设计见 docs/access.md 第 4 节。</summary>
+[Collection("probe-e2e")]
+public sealed class ElevationTests
+{
+    private const string Password = "correct horse battery";
+
+    private readonly BackendFixture _backend;
+
+    public ElevationTests(BackendFixture backend)
+    {
+        _backend = backend;
+    }
+
+    private string Origin => _backend.BaseAddress.GetLeftPart(UriPartial.Authority);
+
+    private string RpId => _backend.BaseAddress.Host;
+
+    /// <summary>新建一个用户并用密码登录（会话令牌走 Bearer）。每个测试用自己的用户，互不影响。</summary>
+    private async Task<HttpClient> NewSessionAsync()
+    {
+        string name = _backend.UniqueName("elev");
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/users", BackendFixture.Json(new JsonObject { ["username"] = name, ["password"] = Password }));
+        Assert.Equal(HttpStatusCode.Created, created.StatusCode);
+        HttpClient client = _backend.NewClient();
+        using HttpResponseMessage login = await client.PostAsync("/api/admin/auth/login", BackendFixture.Json(new JsonObject { ["username"] = name, ["password"] = Password, ["return_session"] = true }));
+        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", JsonNode.Parse(await login.Content.ReadAsStringAsync())!["session_token"]!.GetValue<string>());
+        return client;
+    }
+
+    private async Task<(HttpClient, SoftwarePasskey)> StrongAsync()
+    {
+        (HttpClient client, SoftwarePasskey passkey, _) = await _backend.CreateStrongSessionAsync("elev");
+        return (client, passkey);
+    }
+
+    private async Task<SoftwarePasskey> RegisterAsync(HttpClient session, string name = "key")
+    {
+        var passkey = new SoftwarePasskey(RpId, Origin);
+        using HttpResponseMessage options = await session.PostAsync("/api/admin/auth/passkeys/options", null);
+        Assert.True(options.IsSuccessStatusCode, await options.Content.ReadAsStringAsync());
+        string challenge = JsonNode.Parse(await options.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>();
+        using HttpResponseMessage registered = await session.PostAsync("/api/admin/auth/passkeys", BackendFixture.Json(passkey.Register(name, challenge)));
+        Assert.True(registered.StatusCode == HttpStatusCode.Created, await registered.Content.ReadAsStringAsync());
+        return passkey;
+    }
+
+    private async Task<HttpResponseMessage> ElevateAsync(HttpClient session, SoftwarePasskey passkey, string cls, string? optionsFor = null)
+    {
+        using HttpResponseMessage options = await session.PostAsync("/api/admin/auth/elevation/options", BackendFixture.Json(new JsonObject { ["class"] = optionsFor ?? cls }));
+        Assert.True(options.IsSuccessStatusCode, await options.Content.ReadAsStringAsync());
+        JsonNode body = JsonNode.Parse(await options.Content.ReadAsStringAsync())!;
+        Assert.Contains(passkey.Id, body["allow_credentials"]!.AsArray().Select(x => x!.GetValue<string>())); // 浏览器只会让用户选自己的 passkey
+        JsonObject assertion = passkey.Assert(body["challenge"]!.GetValue<string>());
+        assertion["class"] = cls;
+        return await session.PostAsync("/api/admin/auth/elevation", BackendFixture.Json(assertion));
+    }
+
+    private static async Task<string?> ProblemCodeAsync(HttpResponseMessage response) => JsonNode.Parse(await response.Content.ReadAsStringAsync())?["code"]?.GetValue<string>();
+
+    /// <summary>需要「吊销」窗口的操作（删除节点）：有窗口时返回 204（删除是幂等的），没有窗口返回 403 elevation_required。</summary>
+    private static Task<HttpResponseMessage> Gated(HttpClient client) => client.DeleteAsync("/api/admin/agents/agt_nobody");
+
+    [Fact]
+    public async Task EnrollingNeedsAWindow_ThatOnlyAPasskeyTouchOpens()
+    {
+        (HttpClient session, SoftwarePasskey passkey) = await StrongAsync();
+        using HttpClient sessionScope = session;
+        using SoftwarePasskey passkeyScope = passkey;
+
+        using HttpResponseMessage denied = await Gated(session);
+        Assert.Equal(HttpStatusCode.Forbidden, denied.StatusCode);
+        Assert.Equal("elevation_required", await ProblemCodeAsync(denied));
+        Assert.Contains("revoke", await denied.Content.ReadAsStringAsync(), StringComparison.Ordinal);
+
+        using HttpResponseMessage elevated = await ElevateAsync(session, passkey, "revoke");
+        Assert.Equal(HttpStatusCode.OK, elevated.StatusCode);
+        Assert.Equal(HttpStatusCode.NoContent, (await Gated(session)).StatusCode); // 有窗口：到了业务层（删除是幂等的）
+        Assert.Equal(HttpStatusCode.NoContent, (await Gated(session)).StatusCode); // 窗口内不用再触碰
+
+        // 窗口只管它那一种
+        using HttpResponseMessage credential = await session.PostAsync("/api/admin/users", BackendFixture.Json(new JsonObject { ["username"] = _backend.UniqueName("x"), ["password"] = Password }));
+        Assert.Equal("elevation_required", await ProblemCodeAsync(credential));
+    }
+
+    [Fact]
+    public async Task ApiKeys_CarryTheirCapabilities_AndSkipTheWindow()
+    {
+        using HttpResponseMessage allowed = await Gated(_backend.Admin);
+        Assert.Equal(HttpStatusCode.NoContent, allowed.StatusCode); // API key 自带能力，不经过提权窗口
+    }
+
+    [Fact]
+    public async Task TheWindowCanBeListed_AndEndedEarly()
+    {
+        (HttpClient session, SoftwarePasskey passkey) = await StrongAsync();
+        using HttpClient sessionScope = session;
+        using SoftwarePasskey passkeyScope = passkey;
+        Assert.Empty(JsonNode.Parse(await session.GetStringAsync("/api/admin/auth/elevation"))!["items"]!.AsArray());
+
+        (await ElevateAsync(session, passkey, "revoke")).Dispose();
+        JsonArray open = JsonNode.Parse(await session.GetStringAsync("/api/admin/auth/elevation"))!["items"]!.AsArray();
+        Assert.Equal("revoke", Assert.Single(open)!["class"]!.GetValue<string>());
+
+        Assert.Equal(HttpStatusCode.NoContent, (await session.DeleteAsync("/api/admin/auth/elevation")).StatusCode);
+        Assert.Empty(JsonNode.Parse(await session.GetStringAsync("/api/admin/auth/elevation"))!["items"]!.AsArray());
+        Assert.Equal(HttpStatusCode.Forbidden, (await Gated(session)).StatusCode);
+    }
+
+    [Fact]
+    public async Task ACredentialWindow_IsSingleUse()
+    {
+        (HttpClient session, SoftwarePasskey passkey) = await StrongAsync();
+        using HttpClient sessionScope = session;
+        using SoftwarePasskey passkeyScope = passkey;
+
+        (await ElevateAsync(session, passkey, "credential")).Dispose();
+        using HttpResponseMessage first = await session.PostAsync("/api/admin/users", BackendFixture.Json(new JsonObject { ["username"] = _backend.UniqueName("made"), ["password"] = Password }));
+        Assert.Equal(HttpStatusCode.Created, first.StatusCode);
+        using HttpResponseMessage second = await session.PostAsync("/api/admin/users", BackendFixture.Json(new JsonObject { ["username"] = _backend.UniqueName("made"), ["password"] = Password }));
+        Assert.Equal("elevation_required", await ProblemCodeAsync(second));
+    }
+
+    [Fact]
+    public async Task OnlyYourOwnPasskey_WithTheRightChallengeAndKind_OpensAWindow()
+    {
+        (HttpClient mine, SoftwarePasskey myPasskey) = await StrongAsync();
+        (HttpClient theirs, SoftwarePasskey theirPasskey) = await StrongAsync();
+
+        // 别人的 passkey 签了我的挑战：不行（也不在 allow_credentials 里）
+        using HttpResponseMessage options = await mine.PostAsync("/api/admin/auth/elevation/options", BackendFixture.Json(new JsonObject { ["class"] = "enroll" }));
+        string challenge = JsonNode.Parse(await options.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>();
+        JsonObject foreign = theirPasskey.Assert(challenge);
+        foreign["class"] = "enroll";
+        Assert.Equal(HttpStatusCode.Unauthorized, (await mine.PostAsync("/api/admin/auth/elevation", BackendFixture.Json(foreign))).StatusCode);
+
+        // 挑战是给 revoke 要的，提交成 enroll：不行
+        using HttpResponseMessage wrongKind = await ElevateAsync(mine, myPasskey, "enroll", optionsFor: "revoke");
+        Assert.Equal(HttpStatusCode.Unauthorized, wrongKind.StatusCode);
+
+        // 挑战只能用一次
+        using HttpResponseMessage options2 = await mine.PostAsync("/api/admin/auth/elevation/options", BackendFixture.Json(new JsonObject { ["class"] = "enroll" }));
+        string challenge2 = JsonNode.Parse(await options2.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>();
+        JsonObject once = myPasskey.Assert(challenge2);
+        once["class"] = "enroll";
+        Assert.Equal(HttpStatusCode.OK, (await mine.PostAsync("/api/admin/auth/elevation", BackendFixture.Json(once))).StatusCode);
+        Assert.Equal(HttpStatusCode.Unauthorized, (await mine.PostAsync("/api/admin/auth/elevation", BackendFixture.Json(once))).StatusCode);
+
+        // 另一个用户的会话没有因此提权
+        Assert.Equal(HttpStatusCode.Forbidden, (await Gated(theirs)).StatusCode);
+    }
+
+    [Fact]
+    public async Task WithoutAPasskey_ThereIsNothingToTouch_AndTheFirstPasskeyNeedsNoWindow()
+    {
+        using HttpClient session = await NewSessionAsync();
+        using HttpResponseMessage none = await session.PostAsync("/api/admin/auth/elevation/options", BackendFixture.Json(new JsonObject { ["class"] = "enroll" }));
+        Assert.Equal(HttpStatusCode.BadRequest, none.StatusCode);
+
+        using SoftwarePasskey first = await RegisterAsync(session, "first"); // 第一个：不要求提权
+        using HttpResponseMessage second = await session.PostAsync("/api/admin/auth/passkeys/options", null);
+        Assert.Equal("elevation_required", await ProblemCodeAsync(second)); // 第二个起要先用已有的触碰
+        (await ElevateAsync(session, first, "credential")).Dispose();
+        using SoftwarePasskey added = await RegisterAsync(session, "second");
+
+        // 删除也要窗口
+        (await ElevateAsync(session, first, "credential")).Dispose();
+        Assert.Equal(HttpStatusCode.NoContent, (await session.DeleteAsync("/api/admin/auth/passkeys/" + added.Id)).StatusCode);
+        Assert.Equal(HttpStatusCode.Forbidden, (await session.DeleteAsync("/api/admin/auth/passkeys/" + first.Id)).StatusCode);
+    }
+
+    [Fact]
+    public async Task AKeyThatCarriesTrust_NeedsAPasskeySignatureToCreate()
+    {
+        (HttpClient session, SoftwarePasskey passkey) = await StrongAsync();
+        using HttpClient sessionScope = session;
+        using SoftwarePasskey passkeyScope = passkey;
+        var trusted = new JsonObject { ["name"] = _backend.UniqueName("ci"), ["capabilities"] = new JsonArray("fleet.revoke") };
+        var harmless = new JsonObject { ["name"] = _backend.UniqueName("ro"), ["capabilities"] = new JsonArray("fleet.read") };
+
+        Assert.Equal(HttpStatusCode.Created, (await session.PostAsync("/api/admin/api-tokens", BackendFixture.Json(harmless))).StatusCode);
+        using HttpResponseMessage denied = await session.PostAsync("/api/admin/api-tokens", BackendFixture.Json(trusted));
+        Assert.Equal("elevation_required", await ProblemCodeAsync(denied));
+        (await ElevateAsync(session, passkey, "credential")).Dispose();
+        Assert.Equal(HttpStatusCode.Created, (await session.PostAsync("/api/admin/api-tokens", BackendFixture.Json(trusted))).StatusCode);
+    }
+
+    [Fact]
+    public async Task ListingUsers_NeedsOnlyTheReadCapability()
+    {
+        (HttpClient session, SoftwarePasskey passkey) = await StrongAsync();
+        using HttpClient sessionScope = session;
+        using SoftwarePasskey passkeyScope = passkey;
+        Assert.Equal(HttpStatusCode.OK, (await session.GetAsync("/api/admin/users")).StatusCode); // 看列表不用提权
+    }
+}

backend/tests/MoShiro.Backend.Tests/InstallTests.cs

@@ -3,7 +3,10 @@ using System.Text.Json.Nodes;
 
 namespace MoShiro.Backend.Tests;
 
-/// <summary>一行安装：Agent 和 Probe 共用同一份脚本，角色、网关、镜像由一次性代码决定，节点名字默认取主机名。</summary>
+/// <summary>
+/// 一行安装：Agent 和 Probe 共用同一份<b>静态</b>脚本（所有人拿到的字节都一样，所以哈希固定、可以先核对再执行），
+/// 面板地址、角色、一次性代码都走命令里的环境变量；脚本再向面板取 CI 签名的发布清单来验证镜像。
+/// </summary>
 [Collection("probe-e2e")]
 public sealed class InstallTests
 {
@@ -23,7 +26,7 @@ public sealed class InstallTests
     [Theory]
     [InlineData("agent")]
     [InlineData("probe")]
-    public async Task Commands_AreOneLiners_WithoutAPlaceholder_AndTheScriptIsFilledInForTheRole(string role)
+    public async Task Commands_VerifyTheScriptHash_ThenRunItWithThePublicValues(string role)
     {
         JsonNode created = await CreateAsync(role);
         string code = created["plaintext"]!.GetValue<string>();
@@ -31,53 +34,97 @@ public sealed class InstallTests
         string linux = commands["linux"]!.GetValue<string>();
         string macos = commands["macos"]!.GetValue<string>();
         string windows = commands["windows"]!.GetValue<string>();
-        Assert.StartsWith("curl -fsSL '", linux, StringComparison.Ordinal);
-        Assert.EndsWith("/install?code=" + code + "' | bash", linux, StringComparison.Ordinal);
-        Assert.EndsWith("/install?code=" + code + "' | zsh", macos, StringComparison.Ordinal);
-        Assert.StartsWith("irm '", windows, StringComparison.Ordinal);
-        Assert.EndsWith("/install.ps1?code=" + code + "' | iex", windows, StringComparison.Ordinal);
+
+        Assert.StartsWith("f=$(mktemp) && curl -fsSL '", linux, StringComparison.Ordinal);
+        Assert.Contains("/install' -o \"$f\" && echo \"", linux, StringComparison.Ordinal);
+        Assert.Contains("sha256sum -c -", linux, StringComparison.Ordinal);
+        Assert.Contains($"MOSHIRO_ROLE='{role}'", linux, StringComparison.Ordinal);
+        Assert.Contains($"MOSHIRO_CODE='{code}'", linux, StringComparison.Ordinal);
+        Assert.EndsWith("sh \"$f\"", linux, StringComparison.Ordinal);
+        Assert.Contains("shasum -a 256 -c -", macos, StringComparison.Ordinal);
+        Assert.StartsWith("$f = Join-Path $env:TEMP", windows, StringComparison.Ordinal);
+        Assert.Contains($"$env:MOSHIRO_ROLE='{role}'", windows, StringComparison.Ordinal);
+        Assert.EndsWith("iex (Get-Content -Raw $f)", windows, StringComparison.Ordinal);
         Assert.DoesNotContain("<", linux + macos + windows, StringComparison.Ordinal); // 没有要用户自己替换的占位符
-
-        // 脚本不需要登录（拿代码就是授权），不带缓存
-        using HttpResponseMessage sh = await _backend.Anonymous.GetAsync("/install?code=" + code);
-        string script = await sh.Content.ReadAsStringAsync();
-        Assert.Equal(HttpStatusCode.OK, sh.StatusCode);
-        Assert.Equal("no-store", sh.Headers.CacheControl?.ToString());
-        Assert.Contains($"ROLE='{role}'", script, StringComparison.Ordinal);
-        Assert.Contains($"CODE='{code}'", script, StringComparison.Ordinal);
-        Assert.Contains($"/moshiro-{role}:latest'", script, StringComparison.Ordinal);
-        Assert.Contains("SERVER='http", script, StringComparison.Ordinal);
-        Assert.DoesNotContain("@@", script, StringComparison.Ordinal);
-
-        using HttpResponseMessage ps = await _backend.Anonymous.GetAsync("/install.ps1?code=" + code);
-        string powershell = await ps.Content.ReadAsStringAsync();
-        Assert.Equal(HttpStatusCode.OK, ps.StatusCode);
-        Assert.Contains($"$role = '{role}'", powershell, StringComparison.Ordinal);
-        Assert.DoesNotContain("@@", powershell, StringComparison.Ordinal);
     }
 
     [Fact]
-    public async Task Script_IsNotServedForUnknownRevokedOrUsedUpCodes()
+    public async Task TheScripts_AreStatic_TheSameBytesForEveryone_AndNeedNoCode()
     {
-        foreach (string path in new[] { "/install", "/install?code=", "/install?code=jt_nope", "/install.ps1?code=jt_nope", "/install.sh?code=jt_nope" })
+        foreach (string path in new[] { "/install", "/install.sh", "/install.ps1" })
+        {
+            using HttpResponseMessage first = await _backend.Anonymous.GetAsync(path);
+            using HttpResponseMessage second = await _backend.Anonymous.GetAsync(path + "?code=jt_whatever");
+            Assert.Equal(HttpStatusCode.OK, first.StatusCode);
+            Assert.Equal("no-store", first.Headers.CacheControl?.ToString());
+            string body = await first.Content.ReadAsStringAsync();
+            Assert.Equal(body, await second.Content.ReadAsStringAsync()); // 带不带码、带什么码，内容都一样
+            Assert.DoesNotContain("@@", body, StringComparison.Ordinal);
+            Assert.Contains("MOSHIRO_SERVER", body, StringComparison.Ordinal);
+            Assert.Contains("MOSHIRO_ROLE", body, StringComparison.Ordinal);
+            Assert.Contains("MOSHIRO_CODE", body, StringComparison.Ordinal);
+        }
+
+        // 同一份字节：sh 的两个路径一致
+        Assert.Equal(await _backend.Anonymous.GetStringAsync("/install"), await _backend.Anonymous.GetStringAsync("/install.sh"));
+    }
+
+    [Fact]
+    public async Task TheScripts_CarryTheReleaseKey_ThatTheBackendShips()
+    {
+        string key = MoShiro.Backend.Api.InstallScripts.ReleaseKey();
+        Assert.StartsWith("-----BEGIN PUBLIC KEY-----", key, StringComparison.Ordinal);
+        foreach (string path in new[] { "/install", "/install.ps1" })
+        {
+            string script = (await _backend.Anonymous.GetStringAsync(path)).Replace("\r\n", "\n", StringComparison.Ordinal);
+            Assert.Contains(key.Replace("\r\n", "\n", StringComparison.Ordinal), script, StringComparison.Ordinal); // 脚本里内置的和面板发布的是同一把
+        }
+    }
+
+    [Fact]
+    public async Task TheScript_GetsTheSignedManifestOfItsRole_ByteForByte()
+    {
+        string manifest = """{"schema":1,"component":"probe","channel":"dev","image":"registry.example/moshiro-dev/moshiro-probe","digest":"sha256:0000000000000000000000000000000000000000000000000000000000000000","tag":"dev-1","version":"0.1.1","commit":"abc","built_at":"2026-10-06T00:00:00Z","seq":1}""";
+        using HttpResponseMessage published = await _backend.Admin.PostAsync("/api/admin/releases", BackendFixture.Json(new JsonObject { ["manifest"] = manifest, ["signature"] = "MEUCIQDc" }));
+        Assert.True(published.StatusCode is HttpStatusCode.Created or HttpStatusCode.Conflict, await published.Content.ReadAsStringAsync());
+
+        string code = (await CreateAsync("probe"))["plaintext"]!.GetValue<string>();
+        using HttpResponseMessage served = await _backend.Anonymous.GetAsync("/install/manifest?code=" + code);
+        Assert.Equal(HttpStatusCode.OK, served.StatusCode);
+        Assert.Equal("no-store", served.Headers.CacheControl?.ToString());
+        Assert.Contains("\"component\":\"probe\"", await served.Content.ReadAsStringAsync(), StringComparison.Ordinal); // 签名对象是原始字节，面板一个字节也不改
+        using HttpResponseMessage signature = await _backend.Anonymous.GetAsync("/install/manifest.sig?code=" + code);
+        Assert.Equal(HttpStatusCode.OK, signature.StatusCode);
+        Assert.False(string.IsNullOrWhiteSpace(await signature.Content.ReadAsStringAsync()));
+    }
+
+    [Fact]
+    public async Task TheManifest_IsNotServedForUnknownRevokedOrUsedUpCodes()
+    {
+        foreach (string path in new[] { "/install/manifest", "/install/manifest?code=", "/install/manifest?code=jt_nope", "/install/manifest.sig?code=jt_nope" })
         {
             using HttpResponseMessage response = await _backend.Anonymous.GetAsync(path);
             Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
         }
 
-        JsonNode revoked = await CreateAsync("agent");
+        JsonNode revoked = await CreateAsync("probe");
         using HttpResponseMessage delete = await _backend.Admin.DeleteAsync("/api/admin/join-tokens/" + revoked["token"]!["id"]!.GetValue<string>());
         Assert.True(delete.IsSuccessStatusCode);
-        using HttpResponseMessage gone = await _backend.Anonymous.GetAsync("/install?code=" + revoked["plaintext"]!.GetValue<string>());
+        using HttpResponseMessage gone = await _backend.Anonymous.GetAsync("/install/manifest?code=" + revoked["plaintext"]!.GetValue<string>());
         Assert.Equal(HttpStatusCode.NotFound, gone.StatusCode);
 
-        // 用完了（一次性令牌已经注册过一个节点）
+        // 用完了（一次性令牌已经注册过一个节点）：脚本在动手之前就能从这里知道，给出明确的提示
         JsonNode used = await CreateAsync("probe");
         string code = used["plaintext"]!.GetValue<string>();
-        using HttpResponseMessage before = await _backend.Anonymous.GetAsync("/install?code=" + code);
-        Assert.Equal(HttpStatusCode.OK, before.StatusCode);
         await using (await MoShiro.TestSupport.AgentSimulator.EnrollAsync(_backend.Anonymous, code, _backend.UniqueName("used"))) { }
-        using HttpResponseMessage after = await _backend.Anonymous.GetAsync("/install?code=" + code);
+        using HttpResponseMessage after = await _backend.Anonymous.GetAsync("/install/manifest?code=" + code);
         Assert.Equal(HttpStatusCode.NotFound, after.StatusCode);
     }
+
+    [Fact]
+    public async Task Codes_RecordWhoCreatedThem()
+    {
+        JsonNode created = await CreateAsync("agent");
+        Assert.StartsWith("key:", created["token"]!["created_by"]!.GetValue<string>(), StringComparison.Ordinal); // Admin 客户端是 API key
+    }
 }

backend/tests/MoShiro.Backend.Tests/OpenApiConformanceTests.cs

@@ -53,7 +53,7 @@ public sealed partial class OpenApiConformanceTests
         foreach ((string path, _) in doc["paths"]!.AsObject())
         {
             string[] prefixes = ["/api/public/", "/api/admin/", "/api/agent/v1/"];
-            string[] roots = ["/healthz", "/metrics", "/install", "/install.ps1"];
+            string[] roots = ["/healthz", "/metrics", "/install", "/install.ps1", "/install/manifest", "/install/manifest.sig"];
             Assert.True(prefixes.Any(p => path.StartsWith(p, StringComparison.Ordinal)) || roots.Contains(path), $"{path} is outside the documented layers");
             foreach (string segment in path.Split('/', StringSplitOptions.RemoveEmptyEntries))
             {
@@ -122,7 +122,7 @@ public sealed partial class OpenApiConformanceTests
     public async Task EveryAdminOperation_DocumentsItsAuthenticationFailures()
     {
         JsonObject doc = await DocumentAsync();
-        foreach ((string path, string method, JsonObject operation) in Operations(doc).Where(o => o.Path.StartsWith("/api/admin/", StringComparison.Ordinal) && o.Path != "/api/admin/auth/login"))
+        foreach ((string path, string method, JsonObject operation) in Operations(doc).Where(o => o.Path.StartsWith("/api/admin/", StringComparison.Ordinal) && o.Path is not ("/api/admin/auth/login" or "/api/admin/auth/passkey/login" or "/api/admin/auth/passkey/options")))
         {
             JsonObject responses = operation["responses"]!.AsObject();
             Assert.True(responses.ContainsKey("401"), $"{method} {path} must document 401");

backend/tests/MoShiro.Backend.Tests/OperationsAndSecurityTests.cs

@@ -284,7 +284,7 @@ public sealed class OperationsAndSecurityTests
     [Fact]
     public async Task ApiTokens_CanBeRevoked_AndTheirPlaintextIsNeverListed()
     {
-        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "temp", ["scope"] = "read" }));
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/api-tokens", BackendFixture.Json(new JsonObject { ["name"] = "temp", ["capabilities"] = BackendFixture.Capabilities("public.read") }));
         JsonNode body = JsonNode.Parse(await created.Content.ReadAsStringAsync())!;
         string plaintext = body["plaintext"]!.GetValue<string>();
         string id = body["token"]!["id"]!.GetValue<string>();

backend/tests/MoShiro.Backend.Tests/PasskeyTests.cs

@@ -0,0 +1,281 @@
+using System.Net;
+using System.Net.Http.Headers;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json.Nodes;
+using Fleet.Core;
+
+namespace MoShiro.Backend.Tests;
+
+/// <summary>软件实现的 WebAuthn 认证器（ES256），用来在测试里走完整的注册和登录。</summary>
+public sealed class SoftwarePasskey : IDisposable
+{
+    private readonly ECDsa _key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+    private uint _counter;
+
+    public SoftwarePasskey(string rpId, string origin)
+    {
+        RpId = rpId;
+        Origin = origin;
+        CredentialId = RandomNumberGenerator.GetBytes(32);
+    }
+
+    public string RpId { get; }
+
+    public string Origin { get; }
+
+    public byte[] CredentialId { get; }
+
+    public string Id => Base64Url.Encode(CredentialId);
+
+    public JsonObject Register(string name, string challenge, byte flags = 0x45, string? origin = null, string? rpId = null)
+    {
+        ECParameters p = _key.ExportParameters(false);
+        byte[] cose = [.. MapHead(5), .. Int(1), .. Int(2), .. Int(3), .. Int(-7), .. Int(-1), .. Int(1), .. Int(-2), .. Bytes(p.Q.X!), .. Int(-3), .. Bytes(p.Q.Y!)];
+        byte[] authData = [.. SHA256.HashData(Encoding.UTF8.GetBytes(rpId ?? RpId)), flags, .. Counter(_counter), .. new byte[16], (byte)(CredentialId.Length >> 8), (byte)CredentialId.Length, .. CredentialId, .. cose];
+        byte[] attestation = [.. MapHead(3), .. Text("fmt"), .. Text("none"), .. Text("attStmt"), .. MapHead(0), .. Text("authData"), .. Bytes(authData)];
+        return new JsonObject
+        {
+            ["name"] = name,
+            ["credential_id"] = Id,
+            ["attestation_object"] = Base64Url.Encode(attestation),
+            ["client_data_json"] = Base64Url.Encode(ClientData("webauthn.create", challenge, origin ?? Origin)),
+            ["transports"] = new JsonArray("internal"),
+        };
+    }
+
+    public JsonObject Assert(string challenge, uint? counter = null, byte flags = 0x05, string? origin = null, string? rpId = null, bool tamper = false)
+    {
+        _counter = counter ?? _counter + 1;
+        byte[] authData = [.. SHA256.HashData(Encoding.UTF8.GetBytes(rpId ?? RpId)), flags, .. Counter(_counter)];
+        byte[] clientData = ClientData("webauthn.get", challenge, origin ?? Origin);
+        byte[] signature = _key.SignData([.. authData, .. SHA256.HashData(clientData)], HashAlgorithmName.SHA256, DSASignatureFormat.Rfc3279DerSequence);
+        if (tamper)
+        {
+            signature[^1] ^= 0x01;
+        }
+
+        return new JsonObject
+        {
+            ["credential_id"] = Id,
+            ["authenticator_data"] = Base64Url.Encode(authData),
+            ["client_data_json"] = Base64Url.Encode(clientData),
+            ["signature"] = Base64Url.Encode(signature),
+            ["return_session"] = true,
+        };
+    }
+
+    public void Dispose() => _key.Dispose();
+
+    private static byte[] ClientData(string type, string challenge, string origin) =>
+        Encoding.UTF8.GetBytes($"{{\"type\":\"{type}\",\"challenge\":\"{challenge}\",\"origin\":\"{origin}\",\"crossOrigin\":false}}");
+
+    private static byte[] Counter(uint value) => [(byte)(value >> 24), (byte)(value >> 16), (byte)(value >> 8), (byte)value];
+
+    // 最小的 CBOR 编码器：只写测试需要的几种
+    private static byte[] Head(int major, int length) =>
+        length < 24 ? [(byte)((major << 5) | length)] : length < 256 ? [(byte)((major << 5) | 24), (byte)length] : [(byte)((major << 5) | 25), (byte)(length >> 8), (byte)length];
+
+    private static byte[] MapHead(int count) => Head(5, count);
+
+    private static byte[] Int(int value) => value >= 0 ? Head(0, value) : Head(1, -1 - value);
+
+    private static byte[] Bytes(byte[] data) => [.. Head(2, data.Length), .. data];
+
+    private static byte[] Text(string text) => [.. Head(3, Encoding.UTF8.GetByteCount(text)), .. Encoding.UTF8.GetBytes(text)];
+}
+
+/// <summary>passkey 登录：注册、登录、拒绝各种错误的断言、只能管理自己的 passkey。设计见 docs/access.md 第 3 节。</summary>
+[Collection("probe-e2e")]
+public sealed class PasskeyTests
+{
+    private readonly BackendFixture _backend;
+
+    public PasskeyTests(BackendFixture backend)
+    {
+        _backend = backend;
+    }
+
+    private string Origin => _backend.BaseAddress.GetLeftPart(UriPartial.Authority);
+
+    private string RpId => _backend.BaseAddress.Host;
+
+    private async Task<HttpClient> PasswordSessionAsync(string user, string password)
+    {
+        HttpClient client = _backend.NewClient();
+        using HttpResponseMessage login = await client.PostAsync("/api/admin/auth/login", BackendFixture.Json(new JsonObject { ["username"] = user, ["password"] = password, ["return_session"] = true }));
+        string body = await login.Content.ReadAsStringAsync();
+        Assert.True(login.IsSuccessStatusCode, body);
+        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", JsonNode.Parse(body)!["session_token"]!.GetValue<string>());
+        return client;
+    }
+
+    private string _user = "";
+
+    /// <summary>每个测试用自己新建的用户：管理员已经有 fixture 的 passkey，再加就要提权，而这里测的是第一个 passkey 的流程。</summary>
+    private async Task<HttpClient> FreshSessionAsync()
+    {
+        _user = _backend.UniqueName("pk");
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/users", BackendFixture.Json(new JsonObject { ["username"] = _user, ["password"] = "correct horse battery" }));
+        Assert.Equal(HttpStatusCode.Created, created.StatusCode);
+        return await PasswordSessionAsync(_user, "correct horse battery");
+    }
+
+    /// <summary>用已有的 passkey 触碰一次，开凭证窗口（删除 passkey 需要）。</summary>
+    private static async Task ElevateAsync(HttpClient session, SoftwarePasskey passkey)
+    {
+        using HttpResponseMessage options = await session.PostAsync("/api/admin/auth/elevation/options", BackendFixture.Json(new JsonObject { ["class"] = "credential" }));
+        JsonObject assertion = passkey.Assert((await JsonOf(options))["challenge"]!.GetValue<string>());
+        assertion["class"] = "credential";
+        using HttpResponseMessage elevated = await session.PostAsync("/api/admin/auth/elevation", BackendFixture.Json(assertion));
+        Assert.Equal(HttpStatusCode.OK, elevated.StatusCode);
+    }
+
+    private static async Task<JsonNode> JsonOf(HttpResponseMessage response) => JsonNode.Parse(await response.Content.ReadAsStringAsync())!;
+
+    private async Task<string> RegistrationChallengeAsync(HttpClient session)
+    {
+        using HttpResponseMessage options = await session.PostAsync("/api/admin/auth/passkeys/options", null);
+        JsonNode body = await JsonOf(options);
+        Assert.Equal(HttpStatusCode.OK, options.StatusCode);
+        Assert.Equal(RpId, body["rp_id"]!.GetValue<string>());
+        return body["challenge"]!.GetValue<string>();
+    }
+
+    private async Task<string> LoginChallengeAsync()
+    {
+        using HttpResponseMessage options = await _backend.Anonymous.PostAsync("/api/admin/auth/passkey/options", null);
+        Assert.Equal(HttpStatusCode.OK, options.StatusCode);
+        return (await JsonOf(options))["challenge"]!.GetValue<string>();
+    }
+
+    private async Task<SoftwarePasskey> RegisterAsync(HttpClient session, string name = "laptop")
+    {
+        var passkey = new SoftwarePasskey(RpId, Origin);
+        using HttpResponseMessage registered = await session.PostAsync("/api/admin/auth/passkeys", BackendFixture.Json(passkey.Register(name, await RegistrationChallengeAsync(session))));
+        Assert.True(registered.StatusCode == HttpStatusCode.Created, await registered.Content.ReadAsStringAsync());
+        return passkey;
+    }
+
+    private async Task<HttpStatusCode> LoginStatusAsync(JsonObject assertion)
+    {
+        using HttpResponseMessage response = await _backend.Anonymous.PostAsync("/api/admin/auth/passkey/login", BackendFixture.Json(assertion));
+        return response.StatusCode;
+    }
+
+    [Fact]
+    public async Task APasskey_CanBeRegistered_ThenSignsInWithoutAUsername_AndTheSessionRemembersHowItWasMade()
+    {
+        using HttpClient session = await FreshSessionAsync();
+        using SoftwarePasskey passkey = await RegisterAsync(session);
+
+        JsonNode list = await JsonOf(await session.GetAsync("/api/admin/auth/passkeys"));
+        Assert.Contains(list["items"]!.AsArray(), p => p!["id"]!.GetValue<string>() == passkey.Id && p["name"]!.GetValue<string>() == "laptop");
+
+        using HttpResponseMessage login = await _backend.Anonymous.PostAsync("/api/admin/auth/passkey/login", BackendFixture.Json(passkey.Assert(await LoginChallengeAsync())));
+        JsonNode body = await JsonOf(login);
+        Assert.Equal(HttpStatusCode.OK, login.StatusCode);
+        Assert.Equal(_user, body["username"]!.GetValue<string>());
+        Assert.NotNull(body["session_token"]);
+        Assert.Equal("no-store", login.Headers.CacheControl?.ToString());
+
+        // 拿这个会话令牌就是登录状态，能力和密码登录一样
+        using var signedIn = new HttpClient { BaseAddress = _backend.BaseAddress };
+        signedIn.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", body["session_token"]!.GetValue<string>());
+        JsonNode me = await JsonOf(await signedIn.GetAsync("/api/admin/auth/me"));
+        Assert.Equal(_user, me["username"]!.GetValue<string>());
+        Assert.Contains(me["capabilities"]!.AsArray(), c => c!.GetValue<string>() == "fleet.read");
+    }
+
+    [Fact]
+    public async Task Assertions_AreRejected_WhenTheChallengeOriginRpOrSignatureIsWrong_OrTheChallengeIsReused()
+    {
+        using HttpClient session = await FreshSessionAsync();
+        using SoftwarePasskey passkey = await RegisterAsync(session);
+
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(passkey.Assert("bm90LWEtY2hhbGxlbmdl"))); // 没发过的挑战
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync(), origin: "https://evil.example")));
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync(), rpId: "evil.example")));
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync(), tamper: true)));
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync(), flags: 0x01))); // 没有用户验证（UV）
+
+        // 挑战只能用一次：同一份断言重放
+        string challenge = await LoginChallengeAsync();
+        JsonObject assertion = passkey.Assert(challenge);
+        Assert.Equal(HttpStatusCode.OK, await LoginStatusAsync(assertion));
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(assertion));
+
+        // 凭证不存在
+        using var stranger = new SoftwarePasskey(RpId, Origin);
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(stranger.Assert(await LoginChallengeAsync())));
+        // 缺字段不会崩
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(new JsonObject()));
+    }
+
+    [Fact]
+    public async Task TheSignCounter_OnlyMovesForward_WhenTheAuthenticatorUsesOne()
+    {
+        using HttpClient session = await FreshSessionAsync();
+        using SoftwarePasskey passkey = await RegisterAsync(session);
+
+        Assert.Equal(HttpStatusCode.OK, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync(), counter: 5)));
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync(), counter: 5))); // 克隆或回放
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync(), counter: 3)));
+        Assert.Equal(HttpStatusCode.OK, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync(), counter: 6)));
+    }
+
+    [Fact]
+    public async Task Registration_NeedsASignedInUser_AValidAttestation_AndAFreshChallenge()
+    {
+        // API 令牌不是用户：没有 passkey 可言
+        using HttpResponseMessage asToken = await _backend.Admin.PostAsync("/api/admin/auth/passkeys/options", null);
+        Assert.Equal(HttpStatusCode.Forbidden, asToken.StatusCode);
+        Assert.Equal(HttpStatusCode.Unauthorized, (await _backend.Anonymous.PostAsync("/api/admin/auth/passkeys/options", null)).StatusCode);
+
+        using HttpClient session = await FreshSessionAsync();
+        using var passkey = new SoftwarePasskey(RpId, Origin);
+        async Task<HttpStatusCode> TryAsync(JsonObject body)
+        {
+            using HttpResponseMessage response = await session.PostAsync("/api/admin/auth/passkeys", BackendFixture.Json(body));
+            return response.StatusCode;
+        }
+
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(passkey.Register("x", "bm90LWEtY2hhbGxlbmdl"))); // 没发过的挑战
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(passkey.Register("x", await RegistrationChallengeAsync(session), origin: "https://evil.example")));
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(passkey.Register("x", await RegistrationChallengeAsync(session), rpId: "evil.example")));
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(passkey.Register("x", await RegistrationChallengeAsync(session), flags: 0x41))); // 没有 UV
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(passkey.Register("x", await RegistrationChallengeAsync(session), flags: 0x05))); // 没有凭证数据
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(passkey.Register(" ", await RegistrationChallengeAsync(session)))); // 名字为空
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(new JsonObject { ["name"] = "x", ["credential_id"] = "AA", ["attestation_object"] = "AAAA", ["client_data_json"] = "AAAA" })); // 垃圾
+
+        // 正常注册，同一把凭证不能注册两次，也不能用登录用的挑战注册
+        string challenge = await RegistrationChallengeAsync(session);
+        Assert.Equal(HttpStatusCode.Created, await TryAsync(passkey.Register("ok", challenge)));
+        // 已经有 passkey 了，再注册要先触碰一次（凭证窗口，用一次就没有）
+        await ElevateAsync(session, passkey);
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(passkey.Register("again", challenge))); // 挑战只能用一次
+        await ElevateAsync(session, passkey);
+        Assert.Equal(HttpStatusCode.Conflict, await TryAsync(passkey.Register("again", await RegistrationChallengeAsync(session))));
+        await ElevateAsync(session, passkey);
+        Assert.Equal(HttpStatusCode.BadRequest, await TryAsync(new SoftwarePasskey(RpId, Origin).Register("x", await LoginChallengeAsync())));
+    }
+
+    [Fact]
+    public async Task APasskey_CanBeDeleted_OnlyByItsOwner_AndThenNoLongerSignsIn()
+    {
+        using HttpClient admin = await FreshSessionAsync();
+        using SoftwarePasskey passkey = await RegisterAsync(admin, "phone");
+
+        string other = _backend.UniqueName("user");
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/users", BackendFixture.Json(new JsonObject { ["username"] = other, ["password"] = "correct horse battery" }));
+        Assert.Equal(HttpStatusCode.Created, created.StatusCode);
+        using HttpClient intruder = await PasswordSessionAsync(other, "correct horse battery");
+        Assert.Equal(HttpStatusCode.Forbidden, (await intruder.DeleteAsync("/api/admin/auth/passkeys/" + passkey.Id)).StatusCode); // 没有窗口，连试都不行
+        Assert.DoesNotContain((await JsonOf(await intruder.GetAsync("/api/admin/auth/passkeys")))["items"]!.AsArray(), p => p!["id"]!.GetValue<string>() == passkey.Id);
+
+        Assert.Equal(HttpStatusCode.Forbidden, (await admin.DeleteAsync("/api/admin/auth/passkeys/" + passkey.Id)).StatusCode); // 删除要先触碰
+        await ElevateAsync(admin, passkey);
+        Assert.Equal(HttpStatusCode.NoContent, (await admin.DeleteAsync("/api/admin/auth/passkeys/" + passkey.Id)).StatusCode);
+        Assert.Equal(HttpStatusCode.Unauthorized, await LoginStatusAsync(passkey.Assert(await LoginChallengeAsync())));
+    }
+}

backend/tests/MoShiro.Backend.Tests/StorageTests.cs

@@ -302,7 +302,7 @@ public sealed class StorageTests : IDisposable
         var tokens = new SqliteJoinTokenStore(_db);
         var fleet = new SqliteAgentStore(_db);
         byte[] hash = TokenHash.Sha256("jt_race");
-        JoinTokenInfo created = await tokens.CreateAsync("jtk_1", hash, "note", ["a"], true, "", maxUses: 3, expiresAtMs: 10_000, nowMs: 1_000, default);
+        JoinTokenInfo created = await tokens.CreateAsync("jtk_1", hash, "note", ["a"], true, "", maxUses: 3, expiresAtMs: 10_000, nowMs: 1_000, createdBy: "alice", default);
         Assert.Equal(0, created.Uses);
 
         bool[] results = await Task.WhenAll(Enumerable.Range(0, 20).Select(_ => Task.Run(async () => await fleet.TryConsumeJoinTokenAsync("jtk_1", 2_000, default))));
@@ -310,7 +310,7 @@ public sealed class StorageTests : IDisposable
         Assert.Equal(3, (await fleet.FindJoinTokenAsync(hash, default))!.Uses);
 
         Assert.False(await fleet.TryConsumeJoinTokenAsync("jtk_1", 2_000, default));
-        JoinTokenInfo expiring = await tokens.CreateAsync("jtk_2", TokenHash.Sha256("jt_exp"), null, [], true, "", 5, expiresAtMs: 5_000, nowMs: 1_000, default);
+        JoinTokenInfo expiring = await tokens.CreateAsync("jtk_2", TokenHash.Sha256("jt_exp"), null, [], true, "", 5, expiresAtMs: 5_000, nowMs: 1_000, createdBy: null, default);
         Assert.False(await fleet.TryConsumeJoinTokenAsync(expiring.Id, 5_000, default), "expired at the boundary");
         Assert.True(await tokens.RevokeAsync("jtk_2", 3_000, default));
         Assert.False(await tokens.RevokeAsync("jtk_2", 3_000, default));

backend/tests/MoShiro.Backend.Tests/TrustTests.cs

@@ -0,0 +1,308 @@
+using System.Net;
+using System.Net.Http.Headers;
+using System.Runtime.CompilerServices;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json.Nodes;
+using Fleet.Core;
+using Fleet.Enrollment.Client;
+using Fleet.Hosting;
+using Fleet.Identity;
+using Microsoft.Extensions.DependencyInjection;
+using MoShiro.Backend.Application;
+
+namespace MoShiro.Backend.Tests;
+
+/// <summary>
+/// 信任根：操作员（passkey）签操作员集合；安装命令里带着创世指纹和属主（都是公开值），节点注册时验证面板的集合并固定在本地。
+/// 设计见 docs/access.md 第 7 节。
+/// </summary>
+[Collection("probe-e2e")]
+public sealed class TrustTests
+{
+    private static readonly ConditionalWeakTable<BackendFixture, Operator> s_operators = [];
+    private static readonly SemaphoreSlim s_gate = new(1, 1);
+
+    private readonly BackendFixture _backend;
+
+    public TrustTests(BackendFixture backend)
+    {
+        _backend = backend;
+    }
+
+    /// <summary>一个已经建立了信任根的操作员：自己的用户、passkey、会话，以及创世指纹。</summary>
+    private sealed record Operator(HttpClient Session, SoftwarePasskey Passkey, string Genesis);
+
+    private async Task<Operator> OperatorAsync()
+    {
+        await s_gate.WaitAsync();
+        try
+        {
+            if (s_operators.TryGetValue(_backend, out Operator? existing))
+            {
+                return existing;
+            }
+
+            // 操作员：有 passkey、用 passkey 登录的会话（密码会话什么能力都没有）
+            (HttpClient session, SoftwarePasskey passkey, _) = await _backend.CreateStrongSessionAsync("operator");
+
+            // 创世要凭证窗口（立根的人要先证明自己），再用 passkey 签集合本身
+            await ElevateAsync(session, passkey);
+            JsonNode state = JsonNode.Parse(await session.GetStringAsync("/api/admin/trust"))!;
+            Assert.False(state["initialized"]!.GetValue<bool>());
+            string statement = state["proposal"]!["statement"]!.GetValue<string>();
+            Assert.Equal(Base64UrlOf(statement), state["proposal"]!["challenge"]!.GetValue<string>());
+            using HttpResponseMessage genesis = await session.PostAsync("/api/admin/trust", BackendFixture.Json(Sign(passkey, statement)));
+            Assert.True(genesis.StatusCode == HttpStatusCode.Created, await genesis.Content.ReadAsStringAsync());
+            string fingerprint = JsonNode.Parse(await genesis.Content.ReadAsStringAsync())!["genesis"]!.GetValue<string>();
+            Assert.Equal(OperatorTrust.Fingerprint(statement), fingerprint);
+
+            var made = new Operator(session, passkey, fingerprint);
+            s_operators.Add(_backend, made);
+            return made;
+        }
+        finally
+        {
+            s_gate.Release();
+        }
+    }
+
+    private static string Base64UrlOf(string statement) => Fleet.Core.Base64Url.Encode(SHA256.HashData(Encoding.UTF8.GetBytes(statement)));
+
+    /// <summary>passkey 对语句签名（挑战是语句的 SHA-256），拼成接口要的断言对象。</summary>
+    private static JsonObject Sign(SoftwarePasskey passkey, string statement)
+    {
+        JsonObject assertion = passkey.Assert(Base64UrlOf(statement));
+        return new JsonObject
+        {
+            ["statement"] = statement,
+            ["credential_id"] = assertion["credential_id"]!.DeepClone(),
+            ["authenticator_data"] = assertion["authenticator_data"]!.DeepClone(),
+            ["client_data_json"] = assertion["client_data_json"]!.DeepClone(),
+            ["signature"] = assertion["signature"]!.DeepClone(),
+        };
+    }
+
+    private static async Task ElevateAsync(HttpClient session, SoftwarePasskey passkey)
+    {
+        using HttpResponseMessage options = await session.PostAsync("/api/admin/auth/elevation/options", BackendFixture.Json(new JsonObject { ["class"] = "credential" }));
+        JsonObject assertion = passkey.Assert(JsonNode.Parse(await options.Content.ReadAsStringAsync())!["challenge"]!.GetValue<string>());
+        assertion["class"] = "credential";
+        using HttpResponseMessage elevated = await session.PostAsync("/api/admin/auth/elevation", BackendFixture.Json(assertion));
+        Assert.Equal(HttpStatusCode.OK, elevated.StatusCode);
+    }
+
+    /// <summary>创建一个加入码（普通 API key 就行，不需要 passkey），返回响应里的码和三条安装命令。</summary>
+    private async Task<(string Code, JsonNode Commands, HttpStatusCode Status)> CreateCodeAsync(string role = "probe", string[]? controllers = null)
+    {
+        var body = new JsonObject { ["role"] = role, ["note"] = "trust test" };
+        if (controllers is not null)
+        {
+            body["controllers"] = new JsonArray([.. controllers.Select(c => (JsonNode?)c)]);
+        }
+
+        using HttpResponseMessage response = await _backend.Admin.PostAsync("/api/admin/join-tokens", BackendFixture.Json(body));
+        JsonNode result = JsonNode.Parse(await response.Content.ReadAsStringAsync())!;
+        return response.StatusCode == HttpStatusCode.Created ? (result["plaintext"]!.GetValue<string>(), result["install_commands"]!, response.StatusCode) : ("", result, response.StatusCode);
+    }
+
+    private async Task<Result<EnrollmentResult>> EnrollAsync(string code, string? genesis, string[]? controllers, string? directory = null)
+    {
+        directory ??= Path.Combine(Path.GetTempPath(), "moshiro-trust-id-" + Guid.NewGuid().ToString("N"));
+        using var http = new HttpClient();
+        return await EnrollmentClient.EnrollAsync(http, _backend.BaseAddress, code, _backend.UniqueName("node"), directory, "0.0.0-test", null, TimeProvider.System, default, genesis, controllers);
+    }
+
+    [Fact]
+    public async Task TheInstallCommand_CarriesOnlyPublicValues_AndChecksTheScriptHashFirst()
+    {
+        Operator op = await OperatorAsync();
+        (string code, JsonNode commands, HttpStatusCode status) = await CreateCodeAsync();
+        Assert.Equal(HttpStatusCode.Created, status);
+
+        string linux = commands["linux"]!.GetValue<string>();
+        string sha = Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(await _backend.Anonymous.GetStringAsync("/install"))));
+        Assert.Contains($"echo \"{sha}  $f\" | sha256sum -c -", linux, StringComparison.Ordinal); // 先核对哈希，一致才执行
+        Assert.Contains($"MOSHIRO_CODE='{code}'", linux, StringComparison.Ordinal);
+        Assert.Contains($"MOSHIRO_GENESIS='{op.Genesis}'", linux, StringComparison.Ordinal);
+        Assert.Contains(op.Passkey.Id, linux, StringComparison.Ordinal); // 默认属主：操作员集合里的全部 passkey
+        Assert.DoesNotContain("SEED", linux + commands["macos"] + commands["windows"], StringComparison.Ordinal); // 没有任何私钥在命令里
+        Assert.Contains("shasum -a 256 -c -", commands["macos"]!.GetValue<string>(), StringComparison.Ordinal);
+        string windowsSha = Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(await _backend.Anonymous.GetStringAsync("/install.ps1"))));
+        Assert.Contains($"-ne '{windowsSha}'", commands["windows"]!.GetValue<string>(), StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task ANode_PinsTheGenesisAndItsOwners_AtEnrollment()
+    {
+        Operator op = await OperatorAsync();
+        (string code, _, _) = await CreateCodeAsync(controllers: [op.Passkey.Id]);
+
+        string directory = Path.Combine(Path.GetTempPath(), "moshiro-trust-id-" + Guid.NewGuid().ToString("N"));
+        Result<EnrollmentResult> enrolled = await EnrollAsync(code, op.Genesis, [op.Passkey.Id], directory);
+        Assert.True(enrolled.IsSuccess, enrolled.IsSuccess ? "" : enrolled.Error.ToString());
+        Assert.True(enrolled.Value.Pinned);
+
+        TrustAnchor anchor = TrustAnchor.Load(directory, NullNodeLog.Instance);
+        Assert.True(anchor.Pinned);
+        Assert.Equal(op.Genesis, anchor.Genesis);
+        Assert.Equal([op.Passkey.Id], anchor.Controllers);
+        Assert.True(anchor.Version >= 1);
+    }
+
+    [Fact]
+    public async Task ANodeWithAWrongPin_RefusesBeforeSendingAnything_AndTheCodeStaysUsable()
+    {
+        Operator op = await OperatorAsync();
+        (string code, _, _) = await CreateCodeAsync();
+
+        Result<EnrollmentResult> wrong = await EnrollAsync(code, new string('0', 64), [op.Passkey.Id]);
+        Assert.False(wrong.IsSuccess);
+        Assert.Contains("genesis", wrong.Error.Message, StringComparison.Ordinal);
+
+        Result<EnrollmentResult> unknownOwner = await EnrollAsync(code, op.Genesis, ["not-a-credential-of-the-set"]);
+        Assert.False(unknownOwner.IsSuccess);
+        Assert.Contains("owner", unknownOwner.Error.Message, StringComparison.Ordinal);
+
+        Assert.True((await EnrollAsync(code, op.Genesis, [op.Passkey.Id])).IsSuccess); // 前两次都在交出密钥之前被拒绝，码没有被消耗
+    }
+
+    [Fact]
+    public async Task APlainCode_StillWorksWithoutAPin_ButTheNodeIsNotPinned()
+    {
+        (string code, _, _) = await CreateCodeAsync();
+        string directory = Path.Combine(Path.GetTempPath(), "moshiro-trust-id-" + Guid.NewGuid().ToString("N"));
+        Result<EnrollmentResult> enrolled = await EnrollAsync(code, null, null, directory);
+        Assert.True(enrolled.IsSuccess);
+        Assert.False(enrolled.Value.Pinned);
+        Assert.False(TrustAnchor.Load(directory, NullNodeLog.Instance).Pinned);
+    }
+
+    [Fact]
+    public async Task TheOwnersOfACode_MustBePasskeysOfTheOperatorSet()
+    {
+        await OperatorAsync();
+        (_, JsonNode problem, HttpStatusCode status) = await CreateCodeAsync(controllers: ["not-in-the-set"]);
+        Assert.Equal(HttpStatusCode.BadRequest, status);
+        Assert.Contains("controllers", problem.ToJsonString(), StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public async Task APinnedAgent_FollowsTheOperatorSet_WhenThePasskeysChange_AndOnlyWhenTheOperatorSigns()
+    {
+        Operator op = await OperatorAsync();
+        (string code, _, _) = await CreateCodeAsync(role: "agent", controllers: [op.Passkey.Id]);
+        await using AgentHarness agent = await AgentHarness.StartAsync(_backend, pin: (code, op.Genesis, [op.Passkey.Id]));
+        Assert.True(agent.App.Link.IsSecure, "a pinned agent must be on the encrypted link (the server proved itself with the key in the operator set)");
+        int before = agent.App.TrustVersion;
+        Assert.True(before >= 1);
+
+        // 账号下多了一把 passkey：集合和 passkey 不一致，面板给出下一版要签的语句
+        (_, SoftwarePasskey added) = await _backend.CreateUserWithPasskeyAsync("colleague");
+        using SoftwarePasskey addedScope = added;
+        JsonNode state = JsonNode.Parse(await op.Session.GetStringAsync("/api/admin/trust"))!;
+        Assert.False(state["in_sync"]!.GetValue<bool>());
+        string next = state["proposal"]!["statement"]!.GetValue<string>();
+
+        // 不是操作员签的（新来的 passkey 还不在上一版里）：不收
+        using HttpResponseMessage forged = await op.Session.PostAsync("/api/admin/trust", BackendFixture.Json(Sign(added, next)));
+        Assert.True(forged.StatusCode is HttpStatusCode.Forbidden or HttpStatusCode.BadRequest, await forged.Content.ReadAsStringAsync());
+        Assert.Equal(before, agent.App.TrustVersion);
+
+        // 现有操作员签：收下，随名册下发给节点，节点从固定的创世验过之后采用
+        using HttpResponseMessage committed = await op.Session.PostAsync("/api/admin/trust", BackendFixture.Json(Sign(op.Passkey, next)));
+        Assert.Equal(HttpStatusCode.Created, committed.StatusCode);
+        await BackendFixture.EventuallyAsync(() => Task.FromResult(agent.App.TrustVersion > before), because: "the pinned agent should adopt the operator-signed set");
+    }
+
+    [Fact]
+    public async Task TheGenesis_IsSetOnce_AndNeedsTheOperatorsSignature()
+    {
+        Operator op = await OperatorAsync();
+        JsonNode state = JsonNode.Parse(await op.Session.GetStringAsync("/api/admin/trust"))!;
+        Assert.True(state["initialized"]!.GetValue<bool>());
+        Assert.Equal(op.Genesis, state["genesis"]!.GetValue<string>());
+
+        // 语句被换掉，签名对不上：不收
+        JsonObject tampered = Sign(op.Passkey, "moshiro-opset-v1\nversion=99\nprev=x\nrp=x\norigins=x\nkey=a:AAAA");
+        tampered["statement"] = "moshiro-opset-v1\nversion=2\nprev=" + op.Genesis + "\nrp=" + _backend.BaseAddress.Host + "\norigins=" + _backend.BaseAddress.GetLeftPart(UriPartial.Authority) + "\nkey=a:AAAA";
+        using HttpResponseMessage rejected = await op.Session.PostAsync("/api/admin/trust", BackendFixture.Json(tampered));
+        Assert.True(rejected.StatusCode is HttpStatusCode.BadRequest or HttpStatusCode.Forbidden or HttpStatusCode.Conflict);
+
+        // 匿名没有可能立根或改根
+        using HttpResponseMessage anonymous = await _backend.Anonymous.PostAsync("/api/admin/trust", BackendFixture.Json(tampered));
+        Assert.Equal(HttpStatusCode.Unauthorized, anonymous.StatusCode);
+    }
+
+    [Fact]
+    public async Task APasswordSession_CanOnlyRegisterAPasskey_AndCreatingACodeNeedsNoPasskeyTouch()
+    {
+        // 密码登录的会话没有任何能力：连看节点列表都不行，只能注册 passkey
+        string name = _backend.UniqueName("pwonly");
+        using HttpResponseMessage created = await _backend.Admin.PostAsync("/api/admin/users", BackendFixture.Json(new JsonObject { ["username"] = name, ["password"] = "correct horse battery" }));
+        Assert.Equal(HttpStatusCode.Created, created.StatusCode);
+        using HttpClient password = _backend.NewClient();
+        using HttpResponseMessage login = await password.PostAsync("/api/admin/auth/login", BackendFixture.Json(new JsonObject { ["username"] = name, ["password"] = "correct horse battery", ["return_session"] = true }));
+        password.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", JsonNode.Parse(await login.Content.ReadAsStringAsync())!["session_token"]!.GetValue<string>());
+        JsonNode me = JsonNode.Parse(await password.GetStringAsync("/api/admin/auth/me"))!;
+        Assert.Empty(me["capabilities"]!.AsArray());
+        Assert.Equal("password", me["auth_method"]!.GetValue<string>());
+        Assert.Equal(HttpStatusCode.Forbidden, (await password.GetAsync("/api/admin/agents")).StatusCode);
+        Assert.Equal(HttpStatusCode.Forbidden, (await password.PostAsync("/api/admin/join-tokens", BackendFixture.Json(new JsonObject { ["role"] = "agent" }))).StatusCode);
+        using HttpResponseMessage options = await password.PostAsync("/api/admin/auth/passkeys/options", null);
+        Assert.Equal(HttpStatusCode.OK, options.StatusCode);
+
+        // passkey 登录的会话创建码：不需要提权窗口、不需要再触碰（创建码不是信任动作，信任在属主固定里）
+        (HttpClient strong, SoftwarePasskey passkey, _) = await _backend.CreateStrongSessionAsync("creator");
+        using HttpClient strongScope = strong;
+        using SoftwarePasskey passkeyScope = passkey;
+        using HttpResponseMessage code = await strong.PostAsync("/api/admin/join-tokens", BackendFixture.Json(new JsonObject { ["role"] = "agent" }));
+        Assert.Equal(HttpStatusCode.Created, code.StatusCode);
+    }
+
+    [Fact]
+    public async Task TheServerKey_IsSignedIntoTheOperatorSet_AndOnlyThatServerPassesTheNodesCheck()
+    {
+        Operator op = await OperatorAsync();
+        JsonNode state = JsonNode.Parse(await op.Session.GetStringAsync("/api/admin/trust"))!;
+        Assert.True(state["server_key_listed"]!.GetValue<bool>());
+        Assert.Equal(64, state["server_key"]!.GetValue<string>().Length);
+
+        (string code, _, _) = await CreateCodeAsync(controllers: [op.Passkey.Id]);
+        string directory = Path.Combine(Path.GetTempPath(), "moshiro-trust-id-" + Guid.NewGuid().ToString("N"));
+        Assert.True((await EnrollAsync(code, op.Genesis, [op.Passkey.Id], directory)).IsSuccess);
+        TrustAnchor anchor = TrustAnchor.Load(directory, NullNodeLog.Instance);
+        Assert.True(anchor.Required); // 集合里登记了服务器密钥：节点要求服务器证明自己
+
+        // 真服务器的证明过得了节点的校验；任何别的密钥（冒充者）、或者换了临时公钥的都过不了
+        ServerIdentityService server = _backend.Services.GetRequiredService<ServerIdentityService>();
+        using var ephemeral = new EphemeralKey();
+        byte[] proof = server.Sign(ServerHello.Payload("nonce-1", ephemeral.PublicKeySpki));
+        Assert.True(anchor.Verify("nonce-1", ephemeral.PublicKeySpki, proof));
+        using ECDsa impostor = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+        Assert.False(anchor.Verify("nonce-1", ephemeral.PublicKeySpki, ServerHello.Sign(impostor, "nonce-1", ephemeral.PublicKeySpki)));
+        using var otherEphemeral = new EphemeralKey();
+        Assert.False(anchor.Verify("nonce-1", otherEphemeral.PublicKeySpki, proof));
+        Assert.False(anchor.Verify("nonce-2", ephemeral.PublicKeySpki, proof));
+    }
+
+    [Fact]
+    public async Task AnOperatorSetWithoutThisPanelsServerKey_IsNotAccepted()
+    {
+        Operator op = await OperatorAsync();
+        JsonNode state = JsonNode.Parse(await op.Session.GetStringAsync("/api/admin/trust"))!;
+        string current = state["proposal"]?["statement"]?.GetValue<string>() ?? "";
+        if (current.Length == 0)
+        {
+            // 已经同步：用当前集合的内容拼一个没有服务器密钥的下一版
+            (_, SoftwarePasskey extra) = await _backend.CreateUserWithPasskeyAsync("bystander");
+            using SoftwarePasskey extraScope = extra;
+            state = JsonNode.Parse(await op.Session.GetStringAsync("/api/admin/trust"))!;
+            current = state["proposal"]!["statement"]!.GetValue<string>();
+        }
+
+        string withoutServer = string.Join('\n', current.Split('\n').Where(l => !l.StartsWith("server=", StringComparison.Ordinal)));
+        using HttpResponseMessage refused = await op.Session.PostAsync("/api/admin/trust", BackendFixture.Json(Sign(op.Passkey, withoutServer)));
+        Assert.Equal(HttpStatusCode.BadRequest, refused.StatusCode); // 签下去会让固定了它的节点认不出这个面板
+    }
+}