feat(gateway): thread ClientCorrelationId into constraint-denial audit (§1.2)

2026-06-15 09:42:40 -04:00
parent 639e36b1bc
commit 8415f35abd
7 changed files with 84 additions and 15 deletions
@@ -105,6 +105,7 @@ public sealed class MxAccessGatewayService(
            BulkConstraintPlan? bulkConstraintPlan = await ApplyConstraintsAsync(
                    session,
                    command,
+                    request.ClientCorrelationId,
                    context.CancellationToken)
                .ConfigureAwait(false);

@@ -279,17 +280,18 @@ public sealed class MxAccessGatewayService(
    private async Task<BulkConstraintPlan?> ApplyConstraintsAsync(
        GatewaySession session,
        MxCommand command,
+        string? correlationId,
        CancellationToken cancellationToken)
    {
        ApiKeyIdentity? identity = identityAccessor.Current;
        switch (command.Kind)
        {
            case MxCommandKind.AddItem:
-                await EnforceReadTagAsync(identity, command.Kind, command.AddItem.ItemDefinition, cancellationToken)
+                await EnforceReadTagAsync(identity, command.Kind, command.AddItem.ItemDefinition, correlationId, cancellationToken)
                    .ConfigureAwait(false);
                return null;
            case MxCommandKind.AddItem2:
-                await EnforceReadTagAsync(identity, command.Kind, command.AddItem2.ItemDefinition, cancellationToken)
+                await EnforceReadTagAsync(identity, command.Kind, command.AddItem2.ItemDefinition, correlationId, cancellationToken)
                    .ConfigureAwait(false);
                return null;
            case MxCommandKind.AddItemBulk:
@@ -298,6 +300,7 @@ public sealed class MxAccessGatewayService(
                        command,
                        command.AddItemBulk.ServerHandle,
                        command.AddItemBulk.TagAddresses,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
            case MxCommandKind.SubscribeBulk:
@@ -306,6 +309,7 @@ public sealed class MxAccessGatewayService(
                        command,
                        command.SubscribeBulk.ServerHandle,
                        command.SubscribeBulk.TagAddresses,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
            case MxCommandKind.AdviseItemBulk:
@@ -315,6 +319,7 @@ public sealed class MxAccessGatewayService(
                        command,
                        command.AdviseItemBulk.ServerHandle,
                        command.AdviseItemBulk.ItemHandles,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
            case MxCommandKind.ReadBulk:
@@ -323,6 +328,7 @@ public sealed class MxAccessGatewayService(
                        command,
                        command.ReadBulk.ServerHandle,
                        command.ReadBulk.TagAddresses,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
            case MxCommandKind.WriteBulk:
@@ -333,6 +339,7 @@ public sealed class MxAccessGatewayService(
                        command.WriteBulk.ServerHandle,
                        command.WriteBulk.Entries,
                        entry => entry.ItemHandle,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
            case MxCommandKind.Write2Bulk:
@@ -343,6 +350,7 @@ public sealed class MxAccessGatewayService(
                        command.Write2Bulk.ServerHandle,
                        command.Write2Bulk.Entries,
                        entry => entry.ItemHandle,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
            case MxCommandKind.WriteSecuredBulk:
@@ -353,6 +361,7 @@ public sealed class MxAccessGatewayService(
                        command.WriteSecuredBulk.ServerHandle,
                        command.WriteSecuredBulk.Entries,
                        entry => entry.ItemHandle,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
            case MxCommandKind.WriteSecured2Bulk:
@@ -363,6 +372,7 @@ public sealed class MxAccessGatewayService(
                        command.WriteSecured2Bulk.ServerHandle,
                        command.WriteSecured2Bulk.Entries,
                        entry => entry.ItemHandle,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
            case MxCommandKind.Write:
@@ -372,6 +382,7 @@ public sealed class MxAccessGatewayService(
                        command.Kind,
                        command.Write.ServerHandle,
                        command.Write.ItemHandle,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
                return null;
@@ -382,6 +393,7 @@ public sealed class MxAccessGatewayService(
                        command.Kind,
                        command.Write2.ServerHandle,
                        command.Write2.ItemHandle,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
                return null;
@@ -392,6 +404,7 @@ public sealed class MxAccessGatewayService(
                        command.Kind,
                        command.WriteSecured.ServerHandle,
                        command.WriteSecured.ItemHandle,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
                return null;
@@ -402,6 +415,7 @@ public sealed class MxAccessGatewayService(
                        command.Kind,
                        command.WriteSecured2.ServerHandle,
                        command.WriteSecured2.ItemHandle,
+                        correlationId,
                        cancellationToken)
                    .ConfigureAwait(false);
                return null;
@@ -414,6 +428,7 @@ public sealed class MxAccessGatewayService(
        ApiKeyIdentity? identity,
        MxCommandKind commandKind,
        string tagAddress,
+        string? correlationId,
        CancellationToken cancellationToken)
    {
        ConstraintFailure? failure = await constraintEnforcer
@@ -424,7 +439,7 @@ public sealed class MxAccessGatewayService(
            return;
        }

-        await constraintEnforcer.RecordDenialAsync(identity, commandKind.ToString(), tagAddress, failure, cancellationToken)
+        await constraintEnforcer.RecordDenialAsync(identity, commandKind.ToString(), tagAddress, failure, correlationId, cancellationToken)
            .ConfigureAwait(false);
        throw new RpcException(new Status(StatusCode.PermissionDenied, failure.Message));
    }
@@ -435,6 +450,7 @@ public sealed class MxAccessGatewayService(
        MxCommandKind commandKind,
        int serverHandle,
        int itemHandle,
+        string? correlationId,
        CancellationToken cancellationToken)
    {
        ConstraintFailure? failure = await constraintEnforcer
@@ -445,7 +461,7 @@ public sealed class MxAccessGatewayService(
            return;
        }

-        await constraintEnforcer.RecordDenialAsync(identity, commandKind.ToString(), itemHandle.ToString(System.Globalization.CultureInfo.InvariantCulture), failure, cancellationToken)
+        await constraintEnforcer.RecordDenialAsync(identity, commandKind.ToString(), itemHandle.ToString(System.Globalization.CultureInfo.InvariantCulture), failure, correlationId, cancellationToken)
            .ConfigureAwait(false);
        throw new RpcException(new Status(StatusCode.PermissionDenied, failure.Message));
    }
@@ -455,6 +471,7 @@ public sealed class MxAccessGatewayService(
        MxCommand command,
        int serverHandle,
        IReadOnlyList<string> tagAddresses,
+        string? correlationId,
        CancellationToken cancellationToken)
    {
        Dictionary<int, SubscribeResult> denied = [];
@@ -471,7 +488,7 @@ public sealed class MxAccessGatewayService(
                continue;
            }

-            await constraintEnforcer.RecordDenialAsync(identity, command.Kind.ToString(), tagAddress, failure, cancellationToken)
+            await constraintEnforcer.RecordDenialAsync(identity, command.Kind.ToString(), tagAddress, failure, correlationId, cancellationToken)
                .ConfigureAwait(false);
            denied[index] = new SubscribeResult
            {
@@ -507,6 +524,7 @@ public sealed class MxAccessGatewayService(
        MxCommand command,
        int serverHandle,
        IReadOnlyList<string> tagAddresses,
+        string? correlationId,
        CancellationToken cancellationToken)
    {
        // Mirrors FilterTagBulkAsync but produces BulkReadResult denial entries
@@ -526,7 +544,7 @@ public sealed class MxAccessGatewayService(
                continue;
            }

-            await constraintEnforcer.RecordDenialAsync(identity, command.Kind.ToString(), tagAddress, failure, cancellationToken)
+            await constraintEnforcer.RecordDenialAsync(identity, command.Kind.ToString(), tagAddress, failure, correlationId, cancellationToken)
                .ConfigureAwait(false);
            denied[index] = new BulkReadResult
            {
@@ -557,6 +575,7 @@ public sealed class MxAccessGatewayService(
        int serverHandle,
        Google.Protobuf.Collections.RepeatedField<TEntry> entries,
        Func<TEntry, int> getItemHandle,
+        string? correlationId,
        CancellationToken cancellationToken) where TEntry : class
    {
        // The four bulk-write families each carry a different per-entry message
@@ -586,6 +605,7 @@ public sealed class MxAccessGatewayService(
                    command.Kind.ToString(),
                    itemHandle.ToString(System.Globalization.CultureInfo.InvariantCulture),
                    failure,
+                    correlationId,
                    cancellationToken)
                .ConfigureAwait(false);
            denied[index] = new BulkWriteResult
@@ -637,6 +657,7 @@ public sealed class MxAccessGatewayService(
        MxCommand command,
        int serverHandle,
        IReadOnlyList<int> itemHandles,
+        string? correlationId,
        CancellationToken cancellationToken)
    {
        Dictionary<int, SubscribeResult> denied = [];
@@ -653,7 +674,7 @@ public sealed class MxAccessGatewayService(
                continue;
            }

-            await constraintEnforcer.RecordDenialAsync(identity, command.Kind.ToString(), itemHandle.ToString(System.Globalization.CultureInfo.InvariantCulture), failure, cancellationToken)
+            await constraintEnforcer.RecordDenialAsync(identity, command.Kind.ToString(), itemHandle.ToString(System.Globalization.CultureInfo.InvariantCulture), failure, correlationId, cancellationToken)
                .ConfigureAwait(false);
            denied[index] = new SubscribeResult
            {
@@ -120,20 +120,22 @@ public sealed class ConstraintEnforcer(
    /// <param name="commandKind">The command type (e.g., read, write).</param>
    /// <param name="target">The target being accessed (tag address or handle).</param>
    /// <param name="failure">The constraint failure details.</param>
+    /// <param name="correlationId">
+    ///     The per-request client correlation id, if any. Persisted as the audit record's
+    ///     <c>CorrelationId</c> when it parses as a GUID; a non-GUID value is dropped (left null).
+    /// </param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    public async Task RecordDenialAsync(
        ApiKeyIdentity? identity,
        string commandKind,
        string target,
        ConstraintFailure failure,
+        string? correlationId,
        CancellationToken cancellationToken)
    {
        // Emit a canonical Denied AuditEvent directly through the best-effort IAuditWriter
        // (Task 2.3 #6): structured Target ("<commandKind>:<target>") and a richer DetailsJson
        // envelope carrying constraint/message/commandKind/target.
-        // TODO(Task 2.3): CorrelationId is left null here. Threading the per-request
-        // ClientCorrelationId down to RecordDenialAsync would require an invasive IConstraintEnforcer
-        // signature change across the gRPC call path; that is deferred to a follow-up.
        AuditEvent auditEvent = new()
        {
            EventId = Guid.NewGuid(),
@@ -144,7 +146,7 @@ public sealed class ConstraintEnforcer(
            Category = CanonicalForwardingApiKeyAuditStore.ApiKeyCategory,
            Target = $"{commandKind}:{target}",
            SourceNode = null,
-            CorrelationId = null,
+            CorrelationId = Guid.TryParse(correlationId, out var cid) ? cid : (Guid?)null,
            DetailsJson = JsonSerializer.Serialize(new Dictionary<string, string>
            {
                ["constraint"] = failure.ConstraintName,
@@ -45,11 +45,16 @@ public interface IConstraintEnforcer
    /// <param name="commandKind">The kind of command denied.</param>
    /// <param name="target">The target of the denied command.</param>
    /// <param name="failure">The constraint failure details.</param>
+    /// <param name="correlationId">
+    ///     The per-request client correlation id, if any. Stored on the audit record's
+    ///     <c>CorrelationId</c> when it parses as a GUID; otherwise left null.
+    /// </param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    Task RecordDenialAsync(
        ApiKeyIdentity? identity,
        string commandKind,
        string target,
        ConstraintFailure failure,
+        string? correlationId,
        CancellationToken cancellationToken);
 }