feat(azure-policy): add alias normalization and denormalization (#635)

* feat: add Azure Policy alias normalization/denormalization Add normalizer and denormalizer for ARM JSON resources, enabling Azure Policy alias short names to become direct paths into a flat structure. - Normalizer: flattens properties wrappers, lowercases keys, resolves per-alias versioned ARM paths, handles sub-resource array flattening, element-level field remaps, and array base renames - Denormalizer: reverses all transformations with casing restoration - AliasRegistry: loads production alias catalogs and data policy manifests - Types: serde deserialization for ARM provider alias formats - YAML test suite: 13 test files covering normalize, denormalize, round-trip, data-plane, edge cases, malformed input, sub-resources, and registry API - Benchmark suite for normalization performance * feat: add FFI and C# bindings for alias normalization - FFI: alias_registry.rs with C-compatible API for loading catalogs, normalizing resources, and denormalizing back to ARM JSON - C#: AliasRegistry wrapper class with NativeMethods P/Invoke bindings and integration tests - Updated Cargo.lock files for new serde_json dependency
2026-08-05 02:16:11 +00:00 · 2026-03-30 18:44:36 -05:00
parent 35fb5d5953
commit d36f952133
46 changed files with 11265 additions and 316 deletions
--- a/bindings/csharp/Regorus.Tests/AliasRegistryTests.cs
+++ b/bindings/csharp/Regorus.Tests/AliasRegistryTests.cs
@@ -0,0 +1,191 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using Regorus;
+
+namespace Regorus.Tests;
+
+[TestClass]
+public class AliasRegistryTests
+{
+    private const string AliasesJson = @"[{
+        ""namespace"": ""Microsoft.Storage"",
+        ""resourceTypes"": [{
+            ""resourceType"": ""storageAccounts"",
+            ""aliases"": [{
+                ""name"": ""Microsoft.Storage/storageAccounts/supportsHttpsTrafficOnly"",
+                ""defaultPath"": ""properties.supportsHttpsTrafficOnly"",
+                ""paths"": []
+            }, {
+                ""name"": ""Microsoft.Storage/storageAccounts/accessTier"",
+                ""defaultPath"": ""properties.accessTier"",
+                ""paths"": []
+            }]
+        }]
+    }]";
+
+    private const string ManifestJson = @"{
+        ""dataNamespace"": ""Microsoft.KeyVault.Data"",
+        ""aliases"": [],
+        ""resourceTypeAliases"": [{
+            ""resourceType"": ""vaults/certificates"",
+            ""aliases"": [{
+                ""name"": ""Microsoft.KeyVault.Data/vaults/certificates/keySize"",
+                ""paths"": [{ ""path"": ""keySize"", ""apiVersions"": [""7.0""] }]
+            }]
+        }]
+    }";
+
+    [TestMethod]
+    public void Create_and_dispose_succeeds()
+    {
+        using var registry = new AliasRegistry();
+        Assert.AreEqual(0, registry.Length);
+    }
+
+    [TestMethod]
+    public void LoadJson_populates_registry()
+    {
+        using var registry = new AliasRegistry();
+        registry.LoadJson(AliasesJson);
+        Assert.AreEqual(1, registry.Length);
+    }
+
+    [TestMethod]
+    public void LoadManifest_populates_registry()
+    {
+        using var registry = new AliasRegistry();
+        registry.LoadManifest(ManifestJson);
+        Assert.AreEqual(1, registry.Length);
+    }
+
+    [TestMethod]
+    public void NormalizeAndWrap_produces_envelope()
+    {
+        using var registry = new AliasRegistry();
+        registry.LoadJson(AliasesJson);
+
+        var resource = @"{
+            ""name"": ""acct1"",
+            ""type"": ""Microsoft.Storage/storageAccounts"",
+            ""properties"": { ""supportsHttpsTrafficOnly"": true, ""accessTier"": ""Hot"" }
+        }";
+
+        var result = registry.NormalizeAndWrap(resource, "2023-01-01", "{}", "{}");
+        Assert.IsNotNull(result);
+
+        var envelope = JsonNode.Parse(result!)!;
+        Assert.IsNotNull(envelope["resource"]);
+        Assert.IsNotNull(envelope["parameters"]);
+        Assert.IsNotNull(envelope["context"]);
+
+        // Normalized resource should have lowercased alias field names
+        var res = envelope["resource"]!;
+        Assert.AreEqual(true, res["supportshttpstrafficonly"]?.GetValue<bool>());
+        Assert.AreEqual("Hot", res["accesstier"]?.GetValue<string>());
+        Assert.AreEqual("acct1", res["name"]?.GetValue<string>());
+    }
+
+    [TestMethod]
+    public void NormalizeAndWrap_with_context_and_parameters()
+    {
+        using var registry = new AliasRegistry();
+        registry.LoadJson(AliasesJson);
+
+        var resource = @"{
+            ""name"": ""acct1"",
+            ""type"": ""Microsoft.Storage/storageAccounts"",
+            ""properties"": { ""supportsHttpsTrafficOnly"": true }
+        }";
+        var context = @"{""resourceGroup"": {""name"": ""rg1""}}";
+        var parameters = @"{""env"": ""prod""}";
+
+        var result = registry.NormalizeAndWrap(resource, "2023-01-01", context, parameters);
+        Assert.IsNotNull(result);
+
+        var envelope = JsonNode.Parse(result!)!;
+        Assert.AreEqual("rg1", envelope["context"]!["resourceGroup"]!["name"]?.GetValue<string>());
+        Assert.AreEqual("prod", envelope["parameters"]!["env"]?.GetValue<string>());
+    }
+
+    [TestMethod]
+    public void Denormalize_restores_properties()
+    {
+        using var registry = new AliasRegistry();
+        registry.LoadJson(AliasesJson);
+
+        var normalized = @"{
+            ""name"": ""acct1"",
+            ""type"": ""Microsoft.Storage/storageAccounts"",
+            ""supportshttpstrafficonly"": true,
+            ""accesstier"": ""Hot""
+        }";
+
+        var result = registry.Denormalize(normalized, "2023-01-01");
+        Assert.IsNotNull(result);
+
+        var arm = JsonNode.Parse(result!)!;
+        Assert.AreEqual("acct1", arm["name"]?.GetValue<string>());
+        Assert.AreEqual(true, arm["properties"]!["supportsHttpsTrafficOnly"]?.GetValue<bool>());
+        Assert.AreEqual("Hot", arm["properties"]!["accessTier"]?.GetValue<string>());
+    }
+
+    [TestMethod]
+    public void Round_trip_normalize_then_denormalize()
+    {
+        using var registry = new AliasRegistry();
+        registry.LoadJson(AliasesJson);
+
+        var resource = @"{
+            ""name"": ""acct1"",
+            ""type"": ""Microsoft.Storage/storageAccounts"",
+            ""properties"": { ""supportsHttpsTrafficOnly"": true, ""accessTier"": ""Hot"" }
+        }";
+
+        // Normalize
+        var envelopeJson = registry.NormalizeAndWrap(resource, "2023-01-01", "{}", "{}");
+        Assert.IsNotNull(envelopeJson);
+
+        var envelope = JsonNode.Parse(envelopeJson!)!;
+        var normalizedResource = envelope["resource"]!.ToJsonString();
+
+        // Denormalize
+        var armJson = registry.Denormalize(normalizedResource, "2023-01-01");
+        Assert.IsNotNull(armJson);
+
+        var arm = JsonNode.Parse(armJson!)!;
+        Assert.AreEqual(true, arm["properties"]!["supportsHttpsTrafficOnly"]?.GetValue<bool>());
+        Assert.AreEqual("Hot", arm["properties"]!["accessTier"]?.GetValue<string>());
+        Assert.AreEqual("acct1", arm["name"]?.GetValue<string>());
+    }
+
+    [TestMethod]
+    public void DataPlane_manifest_normalize()
+    {
+        using var registry = new AliasRegistry();
+        registry.LoadManifest(ManifestJson);
+
+        var resource = @"{
+            ""type"": ""Microsoft.KeyVault.Data/vaults/certificates"",
+            ""keySize"": 2048
+        }";
+
+        var result = registry.NormalizeAndWrap(resource, "7.0", "{}", "{}");
+        Assert.IsNotNull(result);
+
+        var envelope = JsonNode.Parse(result!)!;
+        Assert.AreEqual(2048, envelope["resource"]!["keysize"]?.GetValue<int>());
+    }
+
+    [TestMethod]
+    [ExpectedException(typeof(InvalidOperationException))]
+    public void LoadJson_invalid_throws()
+    {
+        using var registry = new AliasRegistry();
+        registry.LoadJson("not valid json");
+    }
+}
--- a/bindings/csharp/Regorus/AliasRegistry.cs
+++ b/bindings/csharp/Regorus/AliasRegistry.cs
@@ -0,0 +1,153 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System;
+using Regorus.Internal;
+
+#nullable enable
+namespace Regorus
+{
+    /// <summary>
+    /// Manages Azure Policy alias definitions used for resource normalization
+    /// and policy compilation.
+    /// </summary>
+    public unsafe sealed class AliasRegistry : SafeHandleWrapper
+    {
+        /// <summary>
+        /// Create an empty alias registry.
+        /// </summary>
+        public AliasRegistry()
+            : base(RegorusAliasRegistryHandle.Create(), nameof(AliasRegistry))
+        {
+        }
+
+        /// <summary>
+        /// Load control-plane alias data (array of ProviderAliases) from a JSON string.
+        /// </summary>
+        /// <param name="json">JSON array of ProviderAliases (e.g. from Get-AzPolicyAlias or ResourceTypesAndAliases.json)</param>
+        public void LoadJson(string json)
+        {
+            Utf8Marshaller.WithUtf8(json, jsonPtr =>
+            {
+                UseHandle(regPtr =>
+                {
+                    CheckAndDropResult(API.regorus_alias_registry_load_json(
+                        (RegorusAliasRegistry*)regPtr, (byte*)jsonPtr));
+                    return 0;
+                });
+            });
+        }
+
+        /// <summary>
+        /// Load a data-plane policy manifest from a JSON string.
+        /// </summary>
+        /// <param name="json">JSON object containing a DataPolicyManifest</param>
+        public void LoadManifest(string json)
+        {
+            Utf8Marshaller.WithUtf8(json, jsonPtr =>
+            {
+                UseHandle(regPtr =>
+                {
+                    CheckAndDropResult(API.regorus_alias_registry_load_manifest(
+                        (RegorusAliasRegistry*)regPtr, (byte*)jsonPtr));
+                    return 0;
+                });
+            });
+        }
+
+        /// <summary>
+        /// Gets the number of resource types loaded in the registry.
+        /// </summary>
+        public long Length
+        {
+            get
+            {
+                return UseHandle(regPtr =>
+                {
+                    return ResultHelpers.GetIntResult(
+                        API.regorus_alias_registry_len((RegorusAliasRegistry*)regPtr));
+                });
+            }
+        }
+
+        /// <summary>
+        /// Normalize an ARM resource JSON and wrap it into the standard input envelope
+        /// expected by a compiled Azure Policy program.
+        /// </summary>
+        /// <param name="resourceJson">Raw ARM resource JSON</param>
+        /// <param name="apiVersion">API version string (e.g. "2023-01-01"), or null to use default alias paths</param>
+        /// <param name="contextJson">Additional context JSON object (pass "{}" if none)</param>
+        /// <param name="parametersJson">Policy parameter values JSON (pass "{}" if none)</param>
+        /// <returns>JSON string: { "resource": &lt;normalized&gt;, "context": &lt;context&gt;, "parameters": &lt;params&gt; }</returns>
+        public string? NormalizeAndWrap(string resourceJson, string? apiVersion = null, string contextJson = "{}", string parametersJson = "{}")
+        {
+            return Utf8Marshaller.WithUtf8(resourceJson, resPtr =>
+                Utf8Marshaller.WithUtf8(contextJson, ctxPtr =>
+                    Utf8Marshaller.WithUtf8(parametersJson, paramsPtr =>
+                    {
+                        if (apiVersion is null)
+                        {
+                            return UseHandle(regPtr =>
+                            {
+                                return ResultHelpers.GetStringResult(
+                                    API.regorus_alias_registry_normalize_and_wrap(
+                                        (RegorusAliasRegistry*)regPtr,
+                                        (byte*)resPtr, null,
+                                        (byte*)ctxPtr, (byte*)paramsPtr));
+                            });
+                        }
+                        else
+                        {
+                            return Utf8Marshaller.WithUtf8(apiVersion, apiPtr =>
+                                UseHandle(regPtr =>
+                                {
+                                    return ResultHelpers.GetStringResult(
+                                        API.regorus_alias_registry_normalize_and_wrap(
+                                            (RegorusAliasRegistry*)regPtr,
+                                            (byte*)resPtr, (byte*)apiPtr,
+                                            (byte*)ctxPtr, (byte*)paramsPtr));
+                                }));
+                        }
+                    })));
+        }
+
+        /// <summary>
+        /// Denormalize a previously-normalized resource JSON back to ARM format.
+        /// </summary>
+        /// <param name="normalizedJson">The normalized resource JSON</param>
+        /// <param name="apiVersion">API version string, or null to use default alias paths</param>
+        /// <returns>Denormalized ARM JSON string</returns>
+        public string? Denormalize(string normalizedJson, string? apiVersion = null)
+        {
+            return Utf8Marshaller.WithUtf8(normalizedJson, normPtr =>
+            {
+                if (apiVersion is null)
+                {
+                    return UseHandle(regPtr =>
+                    {
+                        return ResultHelpers.GetStringResult(
+                            API.regorus_alias_registry_denormalize(
+                                (RegorusAliasRegistry*)regPtr,
+                                (byte*)normPtr, null));
+                    });
+                }
+                else
+                {
+                    return Utf8Marshaller.WithUtf8(apiVersion, apiPtr =>
+                        UseHandle(regPtr =>
+                        {
+                            return ResultHelpers.GetStringResult(
+                                API.regorus_alias_registry_denormalize(
+                                    (RegorusAliasRegistry*)regPtr,
+                                    (byte*)normPtr, (byte*)apiPtr));
+                        }));
+                }
+            });
+        }
+
+        private static string? CheckAndDropResult(RegorusResult result)
+        {
+            return ResultHelpers.GetStringResult(result);
+        }
+    }
+}
--- a/bindings/csharp/Regorus/NativeMethods.cs
+++ b/bindings/csharp/Regorus/NativeMethods.cs
@@ -669,6 +669,55 @@ namespace Regorus.Internal
        internal static extern RegorusResult regorus_effect_schema_clear();

        #endregion
+
+        #region Alias Registry Methods
+
+        /// <summary>
+        /// Create a new, empty AliasRegistry.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_alias_registry_new", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern RegorusAliasRegistry* regorus_alias_registry_new();
+
+        /// <summary>
+        /// Drop an AliasRegistry.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_alias_registry_drop", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern void regorus_alias_registry_drop(RegorusAliasRegistry* registry);
+
+        /// <summary>
+        /// Load control-plane alias data (array of ProviderAliases) into the registry.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_alias_registry_load_json", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern RegorusResult regorus_alias_registry_load_json(RegorusAliasRegistry* registry, byte* json);
+
+        /// <summary>
+        /// Load a data-plane policy manifest into the registry.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_alias_registry_load_manifest", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern RegorusResult regorus_alias_registry_load_manifest(RegorusAliasRegistry* registry, byte* json);
+
+        /// <summary>
+        /// Return the number of resource types loaded in the alias registry.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_alias_registry_len", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern RegorusResult regorus_alias_registry_len(RegorusAliasRegistry* registry);
+
+        /// <summary>
+        /// Normalize an ARM resource JSON and wrap it into the standard input envelope.
+        /// Returns a JSON string.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_alias_registry_normalize_and_wrap", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern RegorusResult regorus_alias_registry_normalize_and_wrap(
+            RegorusAliasRegistry* registry, byte* resource_json, byte* api_version, byte* context_json, byte* parameters_json);
+
+        /// <summary>
+        /// Denormalize a previously-normalized resource JSON back to ARM format.
+        /// </summary>
+        [DllImport(LibraryName, EntryPoint = "regorus_alias_registry_denormalize", CallingConvention = CallingConvention.Cdecl, ExactSpelling = true)]
+        internal static extern RegorusResult regorus_alias_registry_denormalize(
+            RegorusAliasRegistry* registry, byte* normalized_json, byte* api_version);
+
+        #endregion
    }

    #region Native Structures
@@ -874,5 +923,13 @@ namespace Regorus.Internal
        public byte* content;
    }

+    /// <summary>
+    /// Wrapper for AliasRegistry.
+    /// </summary>
+    [StructLayout(LayoutKind.Sequential)]
+    internal unsafe partial struct RegorusAliasRegistry
+    {
+    }
+
    #endregion
 }
--- a/bindings/csharp/Regorus/SafeHandles.cs
+++ b/bindings/csharp/Regorus/SafeHandles.cs
@@ -183,4 +183,52 @@ namespace Regorus
            return true;
        }
    }
+
+    internal sealed class RegorusAliasRegistryHandle : SafeHandleZeroOrMinusOneIsInvalid
+    {
+        private RegorusAliasRegistryHandle() : base(ownsHandle: true)
+        {
+        }
+
+        internal static RegorusAliasRegistryHandle Create()
+        {
+            unsafe
+            {
+                var raw = Internal.API.regorus_alias_registry_new();
+                if (raw is null)
+                {
+                    throw new InvalidOperationException("Failed to create Regorus alias registry.");
+                }
+
+                var handle = new RegorusAliasRegistryHandle();
+                handle.SetHandle((IntPtr)raw);
+                return handle;
+            }
+        }
+
+        internal static RegorusAliasRegistryHandle FromPointer(IntPtr pointer)
+        {
+            if (pointer == IntPtr.Zero)
+            {
+                throw new ArgumentException("Pointer cannot be zero.", nameof(pointer));
+            }
+
+            var handle = new RegorusAliasRegistryHandle();
+            handle.SetHandle(pointer);
+            return handle;
+        }
+
+        protected override bool ReleaseHandle()
+        {
+            if (!IsInvalid)
+            {
+                unsafe
+                {
+                    Internal.API.regorus_alias_registry_drop((Internal.RegorusAliasRegistry*)handle);
+                }
+                SetHandle(IntPtr.Zero);
+            }
+            return true;
+        }
+    }
 }