feat!: pre-handshake knock on the agent TCP ports; probes get the agent certificate public key [CI]

backend/shared/MoShiro.Measurement/Core/Contracts.cs

@@ -217,6 +217,9 @@ public sealed class BlockEnv
     /// <summary>拨号方：对端 TLS 证书的 SPKI 指纹；null 表示不校验证书（目标任务，目标是任意地址）。</summary>
     public byte[]? PeerSpkiSha256 { get; init; }
 
+    /// <summary>拨号方：和对端（Agent）的配对敲门密钥；每条 TCP 连接建立后先发敲门包。null 表示对端不要求敲门（目标任务的任意地址）。</summary>
+    public byte[]? KnockKey { get; init; }
+
     /// <summary>拨号方：列块出口。</summary>
     public IFragmentSink? Fragments { get; init; }
 
@@ -241,6 +244,7 @@ public sealed class BlockEnv
             TcpListen = TcpListen,
             PeerAddress = PeerAddress,
             PeerSpkiSha256 = PeerSpkiSha256,
+            KnockKey = KnockKey,
             Fragments = Fragments,
             MaxBulkMbps = MaxBulkMbps,
             MaxPacketsPerSecond = MaxPacketsPerSecond,

backend/shared/MoShiro.Measurement/MoShiro.Measurement.csproj

@@ -6,5 +6,6 @@
     <InternalsVisibleTo Include="MoShiro.Measurement.Tests" />
     <AdditionalFiles Include="$(MSBuildThisFileDirectory)../../BannedSymbols.Node.txt" />
     <ProjectReference Include="..\MoShiro.Protocol\MoShiro.Protocol.csproj" />
+    <ProjectReference Include="..\..\fleet\src\Fleet.Identity\Fleet.Identity.csproj" />
   </ItemGroup>
 </Project>

backend/shared/MoShiro.Measurement/Net/Tcp.cs

@@ -5,6 +5,7 @@ using System.Net.Sockets;
 using System.Security.Authentication;
 using System.Security.Cryptography;
 using System.Security.Cryptography.X509Certificates;
+using Fleet.Identity;
 using MoShiro.Protocol;
 
 namespace MoShiro.Measurement;
@@ -46,6 +47,12 @@ public sealed class TcpLink : IDisposable
             await client.ConnectAsync(env.PeerAddress!, port, ct);
             long tcpUs = env.Clock.NowUs() - start;
             Stream stream = client.GetStream();
+            if (env.KnockKey is { } knockKey)
+            {
+                // 预握手敲门：监听方不认就不会回任何字节
+                await stream.WriteAsync(Knock.Build(knockKey, env.Time.GetUtcNow().ToUnixTimeMilliseconds()), ct);
+            }
+
             long? tlsUs = null;
             if (tls)
             {
@@ -115,7 +122,7 @@ public sealed class TcpConnection
 public delegate Task TcpResponder(TcpConnection connection, CancellationToken ct);
 
 /// <summary>
-/// 监听方的 TCP 数据面：每个端口一个监听器。连接的第一个字节是 0x16 就先做 TLS（节点自己的证书），否则直接是明文。
+/// 监听方的 TCP 数据面：每个端口一个监听器。连接先过预握手敲门，然后第一个字节是 0x16 就先做 TLS（节点自己的证书），否则直接是明文。
 /// 随后是认证首帧（<c>"MN" | ver | session_id | stream_id | nonce | mac</c>，随机数只能用一次），通过之后交给按 <c>stream_id</c> 登记的处理函数。
 /// 首帧在限定时间内没有到达或者校验失败，直接关闭连接并计数。
 /// </summary>
@@ -128,11 +135,13 @@ public sealed class TcpAcceptor
     private readonly X509Certificate2 _certificate;
     private readonly IDataSessions _sessions;
     private readonly DataPlaneCounters _counters;
+    private readonly KnockGate _knock;
     private readonly ConcurrentDictionary<uint, TcpResponder> _handlers = new();
     private readonly List<TcpListener> _listeners = [];
 
-    public TcpAcceptor(IPAddress bind, IReadOnlyList<int> ports, X509Certificate2 certificate, IDataSessions sessions, DataPlaneCounters counters)
+    public TcpAcceptor(IPAddress bind, IReadOnlyList<int> ports, X509Certificate2 certificate, IDataSessions sessions, DataPlaneCounters counters, KnockGate knock)
     {
+        _knock = knock;
         _bind = bind;
         _ports = ports;
         _certificate = certificate;
@@ -214,6 +223,13 @@ public sealed class TcpAcceptor
                 using var authCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
                 authCts.CancelAfter(s_authTimeout);
 
+                // 预握手敲门：名册里的 Probe 才算得出敲门包；不通过就不写任何字节、直接断开
+                if (!await _knock.AdmitAsync(stream, (client.Client.RemoteEndPoint as IPEndPoint)?.Address, authCts.Token))
+                {
+                    _counters.DropInvalid();
+                    return;
+                }
+
                 byte[] first = new byte[1];
                 if (await stream.ReadAsync(first, authCts.Token) != 1)
                 {

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

@@ -149,9 +149,9 @@ public sealed class AgentEndpoint
     [JsonPropertyName("udp_ports")]
     public List<int> UdpPorts { get; set; } = [];
 
-    /// <summary>Agent 面向 Probe 的 TLS 证书指纹（SHA-256，base64）。</summary>
-    [JsonPropertyName("spki")]
-    public string Spki { get; set; } = "";
+    /// <summary>Agent 面向 Probe 的 TLS 证书公钥（SPKI，base64）：证书按它的 SHA-256 指纹固定，敲门密钥由它和 Probe 的身份密钥派生。</summary>
+    [JsonPropertyName("public_key")]
+    public string PublicKey { get; set; } = "";
 }
 
 /// <summary>期望状态文档（Fleet state type = <c>probe_agents</c>）：Backend 直接下发给每个 Probe 的 Agent 列表。</summary>
@@ -323,8 +323,9 @@ public sealed class AgentHelloMeta
     [JsonPropertyName("platform")]
     public PlatformInfo? Platform { get; set; }
 
-    [JsonPropertyName("tls_spki")]
-    public string? TlsSpki { get; set; }
+    /// <summary>Agent 面向 Probe 的 TLS 证书公钥（SPKI，base64）；面板据此得到证书指纹，并下发给 Probe 用来固定证书和派生敲门密钥。</summary>
+    [JsonPropertyName("tls_pubkey")]
+    public string? TlsPublicKey { get; set; }
 
     /// <summary>本机的公网地址（IPv4 公网地址、IPv6 全球单播地址）：面板据此自动填 <c>public_host</c> 和 <c>ipv6_host</c>，管理员手填的优先。</summary>
     [JsonPropertyName("addresses")]