feat(localdb): fail-closed bearer interceptor for the sync endpoint

2026-07-20 10:28:39 -04:00
parent 3b65c24bfb
commit 3d29be834e
2 changed files with 334 additions and 0 deletions
@@ -0,0 +1,162 @@
+using System.Security.Cryptography;
+using System.Text;
+using Grpc.Core;
+using Grpc.Core.Interceptors;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.LocalDb.Replication;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+/// <summary>
+///     Gates the LocalDb passive sync endpoint. The replication library deliberately leaves inbound
+///     authentication to the host — its <c>LocalDbSyncService</c> verifies nothing — so without this
+///     interceptor anything that can reach a driver node's sync port could stream arbitrary rows
+///     into that node's deployment-artifact cache.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Why that matters here specifically.</b> The cached artifact is what a driver node
+///         boots from when central SQL is unreachable. An attacker able to write it could choose
+///         the configuration a node comes up on during exactly the outage nobody is watching.
+///     </para>
+///     <para>
+///         <b>Scoped by method path.</b> Only calls under <c>/localdb_sync.v1.LocalDbSync/</c> are
+///         gated; every other method on the shared gRPC pipeline passes through untouched.
+///     </para>
+///     <para>
+///         <b>Fail-closed.</b> With no <c>LocalDb:Replication:ApiKey</c> configured, NO sync stream
+///         is accepted, authenticated or not. That is the deliberate choice: the alternative —
+///         treating "no key" as "no auth required" — would silently expose the endpoint on exactly
+///         the default configuration every node ships with. An operator enabling replication must
+///         set the same key on both nodes of the pair, which is already required for the initiator
+///         to dial out (<c>SyncBackgroundService</c> sends <c>Authorization: Bearer &lt;key&gt;</c>).
+///         A key typo therefore stops convergence outright rather than degrading to unauthenticated.
+///     </para>
+///     <para>
+///         Comparison is <see cref="CryptographicOperations.FixedTimeEquals"/> over UTF-8 bytes, so
+///         a wrong key cannot be recovered byte-by-byte from response timing. Length differences are
+///         unavoidably observable and are not sensitive.
+///     </para>
+/// </remarks>
+public sealed class LocalDbSyncAuthInterceptor : Interceptor
+{
+    private const string ServicePrefix = "/localdb_sync.v1.LocalDbSync/";
+    private const string AuthorizationHeader = "authorization";
+    private const string BearerPrefix = "Bearer ";
+
+    private readonly IOptions<ReplicationOptions> _options;
+    private readonly ILogger<LocalDbSyncAuthInterceptor> _logger;
+
+    /// <summary>Creates the interceptor.</summary>
+    /// <param name="options">Replication options; <c>ApiKey</c> is the expected bearer token.</param>
+    /// <param name="logger">Logger for denial diagnostics.</param>
+    public LocalDbSyncAuthInterceptor(
+        IOptions<ReplicationOptions> options,
+        ILogger<LocalDbSyncAuthInterceptor> logger)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        ArgumentNullException.ThrowIfNull(logger);
+
+        _options = options;
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public override Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
+        TRequest request,
+        ServerCallContext context,
+        UnaryServerMethod<TRequest, TResponse> continuation)
+    {
+        Authorize(context);
+        return continuation(request, context);
+    }
+
+    /// <inheritdoc />
+    public override Task DuplexStreamingServerHandler<TRequest, TResponse>(
+        IAsyncStreamReader<TRequest> requestStream,
+        IServerStreamWriter<TResponse> responseStream,
+        ServerCallContext context,
+        DuplexStreamingServerMethod<TRequest, TResponse> continuation)
+    {
+        Authorize(context);
+        return continuation(requestStream, responseStream, context);
+    }
+
+    /// <inheritdoc />
+    public override Task<TResponse> ClientStreamingServerHandler<TRequest, TResponse>(
+        IAsyncStreamReader<TRequest> requestStream,
+        ServerCallContext context,
+        ClientStreamingServerMethod<TRequest, TResponse> continuation)
+    {
+        Authorize(context);
+        return continuation(requestStream, context);
+    }
+
+    /// <inheritdoc />
+    public override Task ServerStreamingServerHandler<TRequest, TResponse>(
+        TRequest request,
+        IServerStreamWriter<TResponse> responseStream,
+        ServerCallContext context,
+        ServerStreamingServerMethod<TRequest, TResponse> continuation)
+    {
+        Authorize(context);
+        return continuation(request, responseStream, context);
+    }
+
+    /// <summary>
+    ///     Throws <see cref="RpcException"/> with <see cref="StatusCode.PermissionDenied"/> if this
+    ///     is a sync call that does not carry the configured bearer token. Non-sync calls return
+    ///     immediately.
+    /// </summary>
+    private void Authorize(ServerCallContext context)
+    {
+        if (!context.Method.StartsWith(ServicePrefix, StringComparison.Ordinal))
+            return;
+
+        var expected = _options.Value.ApiKey;
+        if (string.IsNullOrEmpty(expected))
+        {
+            _logger.LogWarning(
+                "Rejected a LocalDb sync call to {Method}: no LocalDb:Replication:ApiKey is configured, " +
+                "so the passive sync endpoint is closed. Configure the same key on both nodes of the pair.",
+                context.Method);
+            throw new RpcException(new Status(
+                StatusCode.PermissionDenied,
+                "LocalDb sync is not accepting connections: no API key is configured on this node."));
+        }
+
+        var presented = ExtractBearerToken(context.RequestHeaders);
+        if (presented is null || !FixedTimeEquals(presented, expected))
+        {
+            _logger.LogWarning(
+                "Rejected a LocalDb sync call to {Method}: {Reason}.",
+                context.Method,
+                presented is null ? "no bearer token presented" : "bearer token did not match");
+            throw new RpcException(new Status(
+                StatusCode.PermissionDenied,
+                "LocalDb sync authentication failed."));
+        }
+    }
+
+    private static string? ExtractBearerToken(Metadata headers)
+    {
+        // gRPC lowercases header keys on the wire; compare case-insensitively anyway so a
+        // hand-built Metadata in a test behaves the same as a real request.
+        foreach (var entry in headers)
+        {
+            if (!string.Equals(entry.Key, AuthorizationHeader, StringComparison.OrdinalIgnoreCase))
+                continue;
+
+            var value = entry.Value;
+            if (value is not null && value.StartsWith(BearerPrefix, StringComparison.OrdinalIgnoreCase))
+                return value[BearerPrefix.Length..];
+        }
+
+        return null;
+    }
+
+    private static bool FixedTimeEquals(string presented, string expected)
+        => CryptographicOperations.FixedTimeEquals(
+            Encoding.UTF8.GetBytes(presented), Encoding.UTF8.GetBytes(expected));
+}
@@ -0,0 +1,172 @@
+using Grpc.Core;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Options;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.LocalDb.Replication;
+using ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.IntegrationTests;
+
+/// <summary>
+///     LocalDb Phase 1 (Task 3) — the passive sync endpoint's inbound gate.
+/// </summary>
+/// <remarks>
+///     The replication library's <c>LocalDbSyncService</c> verifies nothing; inbound auth is
+///     explicitly the host's job. Without this interceptor, anything able to reach a driver node's
+///     sync port could stream arbitrary rows straight into that node's deployment-artifact cache —
+///     which is exactly what the node boots from when central SQL is unreachable.
+/// </remarks>
+public sealed class LocalDbSyncAuthInterceptorTests
+{
+    private const string SyncMethod = "/localdb_sync.v1.LocalDbSync/Sync";
+    private const string OtherMethod = "/otopcua.SomethingElse/Call";
+
+    private static LocalDbSyncAuthInterceptor CreateInterceptor(string? apiKey)
+        => new(
+            Options.Create(new ReplicationOptions { ApiKey = apiKey }),
+            NullLogger<LocalDbSyncAuthInterceptor>.Instance);
+
+    private static ServerCallContext CreateContext(string method, string? authorizationHeader)
+    {
+        var headers = new Metadata();
+        if (authorizationHeader is not null)
+            headers.Add("authorization", authorizationHeader);
+
+        return new FakeServerCallContext(method, headers);
+    }
+
+    /// <summary>
+    ///     Minimal <see cref="ServerCallContext"/> carrying just a method name and request headers —
+    ///     the only two things the interceptor reads.
+    /// </summary>
+    /// <remarks>
+    ///     Hand-rolled rather than using <c>Grpc.Core.Testing.TestServerCallContext</c>: that type
+    ///     ships in the retired native <c>Grpc.Core</c> package and does not exist on the grpc-dotnet
+    ///     stack this solution runs on.
+    /// </remarks>
+    private sealed class FakeServerCallContext(string method, Metadata requestHeaders)
+        : ServerCallContext
+    {
+        protected override string MethodCore => method;
+        protected override string HostCore => "localhost";
+        protected override string PeerCore => "ipv4:127.0.0.1:12345";
+        protected override DateTime DeadlineCore => DateTime.UtcNow.AddMinutes(1);
+        protected override Metadata RequestHeadersCore => requestHeaders;
+        protected override CancellationToken CancellationTokenCore => CancellationToken.None;
+        protected override Metadata ResponseTrailersCore { get; } = [];
+        protected override Status StatusCore { get; set; }
+        protected override WriteOptions? WriteOptionsCore { get; set; }
+
+        protected override AuthContext AuthContextCore { get; } =
+            new(null, new Dictionary<string, List<AuthProperty>>());
+
+        protected override ContextPropagationToken CreatePropagationTokenCore(
+            ContextPropagationOptions? options)
+            => throw new NotSupportedException();
+
+        protected override Task WriteResponseHeadersAsyncCore(Metadata responseHeaders)
+            => Task.CompletedTask;
+    }
+
+    /// <summary>Invokes the interceptor's unary path with a trivial continuation.</summary>
+    private static Task<string> Invoke(
+        LocalDbSyncAuthInterceptor interceptor, ServerCallContext context)
+        => interceptor.UnaryServerHandler<string, string>(
+            "request", context, (_, _) => Task.FromResult("ok"));
+
+    [Fact]
+    public async Task NonSyncMethod_PassesThrough_EvenWithNoKeyConfigured()
+    {
+        // The interceptor is registered on the whole AddGrpc pipeline, so it sees every call.
+        // It must be scoped strictly to the sync service.
+        var interceptor = CreateInterceptor(apiKey: null);
+        var context = CreateContext(OtherMethod, authorizationHeader: null);
+
+        (await Invoke(interceptor, context)).ShouldBe("ok");
+    }
+
+    [Fact]
+    public async Task SyncMethod_WithNoKeyConfigured_IsDenied_EvenWithABearerToken()
+    {
+        // Fail-closed. "No key configured" is the DEFAULT every node ships with, so treating it
+        // as "no auth required" would silently expose the endpoint on exactly the configuration
+        // that is most common. Presenting a token must not help.
+        var interceptor = CreateInterceptor(apiKey: null);
+        var context = CreateContext(SyncMethod, "Bearer anything-at-all");
+
+        var ex = await Should.ThrowAsync<RpcException>(() => Invoke(interceptor, context));
+        ex.StatusCode.ShouldBe(StatusCode.PermissionDenied);
+    }
+
+    [Fact]
+    public async Task SyncMethod_WithNoBearerToken_IsDenied()
+    {
+        var interceptor = CreateInterceptor("the-shared-key");
+        var context = CreateContext(SyncMethod, authorizationHeader: null);
+
+        var ex = await Should.ThrowAsync<RpcException>(() => Invoke(interceptor, context));
+        ex.StatusCode.ShouldBe(StatusCode.PermissionDenied);
+    }
+
+    [Fact]
+    public async Task SyncMethod_WithWrongBearerToken_IsDenied()
+    {
+        var interceptor = CreateInterceptor("the-shared-key");
+        var context = CreateContext(SyncMethod, "Bearer the-wrong-key");
+
+        var ex = await Should.ThrowAsync<RpcException>(() => Invoke(interceptor, context));
+        ex.StatusCode.ShouldBe(StatusCode.PermissionDenied);
+    }
+
+    [Fact]
+    public async Task SyncMethod_WithCorrectBearerToken_PassesThrough()
+    {
+        var interceptor = CreateInterceptor("the-shared-key");
+        var context = CreateContext(SyncMethod, "Bearer the-shared-key");
+
+        (await Invoke(interceptor, context)).ShouldBe("ok");
+    }
+
+    [Fact]
+    public async Task SyncMethod_WithCorrectKey_ButNoBearerScheme_IsDenied()
+    {
+        // A raw key with no "Bearer " prefix is not what SyncBackgroundService sends, and
+        // accepting it would widen the accepted credential shape for no reason.
+        var interceptor = CreateInterceptor("the-shared-key");
+        var context = CreateContext(SyncMethod, "the-shared-key");
+
+        var ex = await Should.ThrowAsync<RpcException>(() => Invoke(interceptor, context));
+        ex.StatusCode.ShouldBe(StatusCode.PermissionDenied);
+    }
+
+    [Fact]
+    public async Task SyncMethod_TokenComparison_IsNotAPrefixMatch()
+    {
+        // A prefix/StartsWith comparison would accept a truncated key and make the secret
+        // recoverable one character at a time.
+        var interceptor = CreateInterceptor("the-shared-key");
+        var context = CreateContext(SyncMethod, "Bearer the-shared-ke");
+
+        var ex = await Should.ThrowAsync<RpcException>(() => Invoke(interceptor, context));
+        ex.StatusCode.ShouldBe(StatusCode.PermissionDenied);
+    }
+
+    [Fact]
+    public async Task DuplexStreaming_IsGated_BecauseThatIsHowSyncActuallyRuns()
+    {
+        // The sync RPC is a bidirectional stream. Gating only the unary path would leave the real
+        // endpoint wide open while every unary test still passed.
+        var interceptor = CreateInterceptor("the-shared-key");
+        var context = CreateContext(SyncMethod, "Bearer the-wrong-key");
+
+        var ex = await Should.ThrowAsync<RpcException>(() =>
+            interceptor.DuplexStreamingServerHandler<string, string>(
+                requestStream: null!,
+                responseStream: null!,
+                context,
+                (_, _, _) => Task.CompletedTask));
+
+        ex.StatusCode.ShouldBe(StatusCode.PermissionDenied);
+    }
+}