feat: add TlsHelper, PeekableStream, and TlsRateLimiter

Add TLS utility classes for certificate loading, peekable stream for TLS
detection, token-bucket rate limiter for handshake throttling, and
TlsConnectionState for post-handshake info. Add TlsState property to
NatsClient. Fix X509Certificate2 constructor usage for .NET 10 compat.

src/NATS.Server/Tls/PeekableStream.cs

@@ -0,0 +1,71 @@
+namespace NATS.Server.Tls;
+
+public sealed class PeekableStream : Stream
+{
+    private readonly Stream _inner;
+    private byte[]? _peekedBytes;
+    private int _peekedOffset;
+    private int _peekedCount;
+
+    public PeekableStream(Stream inner) => _inner = inner;
+
+    public async Task<byte[]> PeekAsync(int count, CancellationToken ct = default)
+    {
+        var buf = new byte[count];
+        int read = await _inner.ReadAsync(buf.AsMemory(0, count), ct);
+        if (read < count) Array.Resize(ref buf, read);
+        _peekedBytes = buf;
+        _peekedOffset = 0;
+        _peekedCount = read;
+        return buf;
+    }
+
+    public override async ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken ct = default)
+    {
+        if (_peekedBytes != null && _peekedOffset < _peekedCount)
+        {
+            int available = _peekedCount - _peekedOffset;
+            int toCopy = Math.Min(available, buffer.Length);
+            _peekedBytes.AsMemory(_peekedOffset, toCopy).CopyTo(buffer);
+            _peekedOffset += toCopy;
+            if (_peekedOffset >= _peekedCount) _peekedBytes = null;
+            return toCopy;
+        }
+        return await _inner.ReadAsync(buffer, ct);
+    }
+
+    public override int Read(byte[] buffer, int offset, int count)
+    {
+        if (_peekedBytes != null && _peekedOffset < _peekedCount)
+        {
+            int available = _peekedCount - _peekedOffset;
+            int toCopy = Math.Min(available, count);
+            Array.Copy(_peekedBytes, _peekedOffset, buffer, offset, toCopy);
+            _peekedOffset += toCopy;
+            if (_peekedOffset >= _peekedCount) _peekedBytes = null;
+            return toCopy;
+        }
+        return _inner.Read(buffer, offset, count);
+    }
+
+    public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken ct)
+        => ReadAsync(buffer.AsMemory(offset, count), ct).AsTask();
+
+    // Write passthrough
+    public override void Write(byte[] buffer, int offset, int count) => _inner.Write(buffer, offset, count);
+    public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken ct) => _inner.WriteAsync(buffer, offset, count, ct);
+    public override ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, CancellationToken ct = default) => _inner.WriteAsync(buffer, ct);
+    public override void Flush() => _inner.Flush();
+    public override Task FlushAsync(CancellationToken ct) => _inner.FlushAsync(ct);
+
+    // Required Stream overrides
+    public override bool CanRead => _inner.CanRead;
+    public override bool CanSeek => false;
+    public override bool CanWrite => _inner.CanWrite;
+    public override long Length => throw new NotSupportedException();
+    public override long Position { get => throw new NotSupportedException(); set => throw new NotSupportedException(); }
+    public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
+    public override void SetLength(long value) => throw new NotSupportedException();
+
+    protected override void Dispose(bool disposing) { if (disposing) _inner.Dispose(); base.Dispose(disposing); }
+}

src/NATS.Server/Tls/TlsConnectionState.cs

@@ -0,0 +1,9 @@
+using System.Security.Cryptography.X509Certificates;
+
+namespace NATS.Server.Tls;
+
+public sealed record TlsConnectionState(
+    string? TlsVersion,
+    string? CipherSuite,
+    X509Certificate2? PeerCert
+);

src/NATS.Server/Tls/TlsHelper.cs

@@ -0,0 +1,65 @@
+using System.Net.Security;
+using System.Security.Authentication;
+using System.Security.Cryptography;
+using System.Security.Cryptography.X509Certificates;
+
+namespace NATS.Server.Tls;
+
+public static class TlsHelper
+{
+    public static X509Certificate2 LoadCertificate(string certPath, string? keyPath)
+    {
+        if (keyPath != null)
+            return X509Certificate2.CreateFromPemFile(certPath, keyPath);
+        return X509CertificateLoader.LoadCertificateFromFile(certPath);
+    }
+
+    public static X509Certificate2Collection LoadCaCertificates(string caPath)
+    {
+        var collection = new X509Certificate2Collection();
+        collection.ImportFromPemFile(caPath);
+        return collection;
+    }
+
+    public static SslServerAuthenticationOptions BuildServerAuthOptions(NatsOptions opts)
+    {
+        var cert = LoadCertificate(opts.TlsCert!, opts.TlsKey);
+        var authOpts = new SslServerAuthenticationOptions
+        {
+            ServerCertificate = cert,
+            EnabledSslProtocols = opts.TlsMinVersion,
+            ClientCertificateRequired = opts.TlsVerify,
+        };
+
+        if (opts.TlsVerify && opts.TlsCaCert != null)
+        {
+            var caCerts = LoadCaCertificates(opts.TlsCaCert);
+            authOpts.RemoteCertificateValidationCallback = (_, cert, chain, errors) =>
+            {
+                if (cert == null) return false;
+                using var chain2 = new X509Chain();
+                chain2.ChainPolicy.TrustMode = X509ChainTrustMode.CustomRootTrust;
+                foreach (var ca in caCerts)
+                    chain2.ChainPolicy.CustomTrustStore.Add(ca);
+                chain2.ChainPolicy.RevocationMode = X509RevocationMode.NoCheck;
+                var cert2 = cert as X509Certificate2 ?? X509CertificateLoader.LoadCertificate(cert.GetRawCertData());
+                return chain2.Build(cert2);
+            };
+        }
+
+        return authOpts;
+    }
+
+    public static string GetCertificateHash(X509Certificate2 cert)
+    {
+        var spki = cert.PublicKey.ExportSubjectPublicKeyInfo();
+        var hash = SHA256.HashData(spki);
+        return Convert.ToHexStringLower(hash);
+    }
+
+    public static bool MatchesPinnedCert(X509Certificate2 cert, HashSet<string> pinned)
+    {
+        var hash = GetCertificateHash(cert);
+        return pinned.Contains(hash);
+    }
+}

src/NATS.Server/Tls/TlsRateLimiter.cs

@@ -0,0 +1,25 @@
+namespace NATS.Server.Tls;
+
+public sealed class TlsRateLimiter : IDisposable
+{
+    private readonly SemaphoreSlim _semaphore;
+    private readonly Timer _refillTimer;
+    private readonly int _tokensPerSecond;
+
+    public TlsRateLimiter(long tokensPerSecond)
+    {
+        _tokensPerSecond = (int)Math.Max(1, tokensPerSecond);
+        _semaphore = new SemaphoreSlim(_tokensPerSecond, _tokensPerSecond);
+        _refillTimer = new Timer(Refill, null, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(1));
+    }
+
+    private void Refill(object? state)
+    {
+        int toRelease = _tokensPerSecond - _semaphore.CurrentCount;
+        if (toRelease > 0) _semaphore.Release(toRelease);
+    }
+
+    public Task WaitAsync(CancellationToken ct) => _semaphore.WaitAsync(ct);
+
+    public void Dispose() { _refillTimer.Dispose(); _semaphore.Dispose(); }
+}