Identifier Normalization & Improved Exists Logic

Author: mckaragoz

src/CodeBeam.UltimateAuth.Core/Contracts/Common/CaseHandling.cs

@@ -0,0 +1,8 @@
+namespace CodeBeam.UltimateAuth.Core.Contracts;
+
+public enum CaseHandling
+{
+    Preserve,
+    ToLower,
+    ToUpper
+}

src/CodeBeam.UltimateAuth.Server/Extensions/ServiceCollectionExtensions.cs

@@ -208,6 +208,7 @@ private static IServiceCollection AddUltimateAuthServerInternal(this IServiceCol
         services.TryAddScoped<IRefreshResponsePolicy, RefreshResponsePolicy>();
         services.TryAddSingleton<IAuthStore, InMemoryAuthStore>();
         services.TryAddScoped<ICurrentUser, HttpContextCurrentUser>();
+        services.TryAddScoped<IIdentifierNormalizer, IdentifierNormalizer>();
 
         services.TryAddScoped<IHubCapabilities, HubCapabilities>();
 

src/CodeBeam.UltimateAuth.Server/Infrastructure/Normalizer/IIdentifierNormalizer.cs

@@ -0,0 +1,8 @@
+using CodeBeam.UltimateAuth.Users.Contracts;
+
+namespace CodeBeam.UltimateAuth.Server.Infrastructure;
+
+public interface IIdentifierNormalizer
+{
+    NormalizedIdentifier Normalize(UserIdentifierType type, string value);
+}

src/CodeBeam.UltimateAuth.Server/Infrastructure/Normalizer/IdentifierNormalizer.cs

@@ -0,0 +1,132 @@
+using CodeBeam.UltimateAuth.Core.Contracts;
+using CodeBeam.UltimateAuth.Server.Options;
+using CodeBeam.UltimateAuth.Users.Contracts;
+using Microsoft.Extensions.Options;
+using System.Globalization;
+using System.Text;
+
+namespace CodeBeam.UltimateAuth.Server.Infrastructure;
+
+public sealed class IdentifierNormalizer : IIdentifierNormalizer
+{
+    private readonly UAuthIdentifierNormalizationOptions _options;
+
+    public IdentifierNormalizer(IOptions<UAuthServerOptions> options)
+    {
+        _options = options.Value.LoginIdentifiers.Normalization;
+    }
+
+    public NormalizedIdentifier Normalize(UserIdentifierType type, string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            return new(value, string.Empty, false, "identifier_empty");
+
+        var raw = value;
+        var normalized = BasicNormalize(value);
+
+        return type switch
+        {
+            UserIdentifierType.Email => NormalizeEmail(raw, normalized),
+            UserIdentifierType.Phone => NormalizePhone(raw, normalized),
+            UserIdentifierType.Username => NormalizeUsername(raw, normalized),
+            _ => NormalizeCustom(raw, normalized)
+        };
+    }
+
+    private static string BasicNormalize(string value)
+    {
+        var form = value.Normalize(NormalizationForm.FormKC).Trim();
+
+        var sb = new StringBuilder(form.Length);
+        foreach (var ch in form)
+        {
+            if (char.IsControl(ch))
+                continue;
+
+            if (ch is '\u200B' or '\u200C' or '\u200D' or '\uFEFF')
+                continue;
+
+            sb.Append(ch);
+        }
+
+        return sb.ToString();
+    }
+
+    private NormalizedIdentifier NormalizeUsername(string raw, string value)
+    {
+        if (value.Length < 3 || value.Length > 256)
+            return new(raw, value, false, "username_invalid_length");
+
+        value = ApplyCasePolicy(value, _options.UsernameCase);
+
+        return new(raw, value, true, null);
+    }
+
+    private NormalizedIdentifier NormalizeEmail(string raw, string value)
+    {
+        var atIndex = value.IndexOf('@');
+        if (atIndex <= 0 || atIndex != value.LastIndexOf('@'))
+            return new(raw, value, false, "email_invalid_format");
+
+        var local = value[..atIndex];
+        var domain = value[(atIndex + 1)..];
+
+        if (string.IsNullOrWhiteSpace(domain) || !domain.Contains('.'))
+            return new(raw, value, false, "email_invalid_domain");
+
+        try
+        {
+            var idn = new IdnMapping();
+            domain = idn.GetAscii(domain);
+        }
+        catch
+        {
+            return new(raw, value, false, "email_invalid_domain");
+        }
+
+        var normalized = $"{local}@{domain}";
+        normalized = ApplyCasePolicy(normalized, _options.EmailCase);
+
+        return new(raw, normalized, true, null);
+    }
+
+    private NormalizedIdentifier NormalizePhone(string raw, string value)
+    {
+        var sb = new StringBuilder();
+
+        foreach (var ch in value)
+        {
+            if (char.IsDigit(ch))
+                sb.Append(ch);
+            else if (ch == '+' && sb.Length == 0)
+                sb.Append(ch);
+        }
+
+        var digits = sb.ToString();
+
+        if (digits.Length < 7)
+            return new(raw, digits, false, "phone_invalid_length");
+
+        return new(raw, digits, true, null);
+    }
+
+    private NormalizedIdentifier NormalizeCustom(string raw, string value)
+    {
+        value = ApplyCasePolicy(value, _options.CustomCase);
+
+        if (value.Length == 0)
+            return new(raw, value, false, "identifier_invalid");
+
+        return new(raw, value, true, null);
+    }
+
+    private static string ApplyCasePolicy(string value, CaseHandling policy)
+    {
+        return policy switch
+        {
+            CaseHandling.ToLower => value.ToLowerInvariant(),
+            CaseHandling.ToUpper => value.ToUpperInvariant(),
+            _ => value
+        };
+    }
+}

src/CodeBeam.UltimateAuth.Server/Infrastructure/Normalizer/NormalizedIdentifier.cs

@@ -0,0 +1,7 @@
+namespace CodeBeam.UltimateAuth.Server.Infrastructure;
+
+public readonly record struct NormalizedIdentifier(
+    string Raw,
+    string Normalized,
+    bool IsValid,
+    string? ErrorCode);

src/CodeBeam.UltimateAuth.Server/Options/UAuthLoginIdentifierOptions.cs

@@ -1,4 +1,5 @@
-using CodeBeam.UltimateAuth.Users.Contracts;
+using CodeBeam.UltimateAuth.Core.Contracts;
+using CodeBeam.UltimateAuth.Users.Contracts;
 
 namespace CodeBeam.UltimateAuth.Server.Options;
 public sealed class UAuthLoginIdentifierOptions
@@ -17,6 +18,8 @@ public sealed class UAuthLoginIdentifierOptions
     public bool EnableCustomResolvers { get; set; } = true;
     public bool CustomResolversFirst { get; set; } = true;
 
+    public UAuthIdentifierNormalizationOptions Normalization { get; set; } = new();
+
     public bool EnforceGlobalUniquenessForAllIdentifiers { get; set; } = false;
 
     internal UAuthLoginIdentifierOptions Clone() => new()
@@ -26,6 +29,21 @@ public sealed class UAuthLoginIdentifierOptions
         RequireVerificationForPhone = RequireVerificationForPhone,
         EnableCustomResolvers = EnableCustomResolvers,
         CustomResolversFirst = CustomResolversFirst,
-        EnforceGlobalUniquenessForAllIdentifiers = EnforceGlobalUniquenessForAllIdentifiers
+        EnforceGlobalUniquenessForAllIdentifiers = EnforceGlobalUniquenessForAllIdentifiers,
+        Normalization = Normalization.Clone()
+    };
+}
+
+public sealed class UAuthIdentifierNormalizationOptions
+{
+    public CaseHandling UsernameCase { get; set; } = CaseHandling.Preserve;
+    public CaseHandling EmailCase { get; set; } = CaseHandling.ToLower;
+    public CaseHandling CustomCase { get; set; } = CaseHandling.Preserve;
+
+    internal UAuthIdentifierNormalizationOptions Clone() => new()
+    {
+        UsernameCase = UsernameCase,
+        EmailCase = EmailCase,
+        CustomCase = CustomCase
     };
 }

src/users/CodeBeam.UltimateAuth.Users.Contracts/Dtos/IdentifierExistenceQuery.cs

@@ -0,0 +1,13 @@
+using CodeBeam.UltimateAuth.Core.Domain;
+using CodeBeam.UltimateAuth.Core.MultiTenancy;
+
+namespace CodeBeam.UltimateAuth.Users.Contracts;
+
+public sealed record IdentifierExistenceQuery(
+    TenantKey Tenant,
+    UserIdentifierType Type,
+    string NormalizedValue,
+    IdentifierExistenceScope Scope,
+    UserKey? UserKey = null,
+    Guid? ExcludeIdentifierId = null
+    );

src/users/CodeBeam.UltimateAuth.Users.Contracts/Dtos/IdentifierExistenceScope.cs

@@ -0,0 +1,19 @@
+namespace CodeBeam.UltimateAuth.Users.Contracts;
+
+public enum IdentifierExistenceScope
+{
+    /// <summary>
+    /// Checks only within the same user.
+    /// </summary>
+    WithinUser,
+
+    /// <summary>
+    /// Checks within tenant but only primary identifiers.
+    /// </summary>
+    TenantPrimaryOnly,
+
+    /// <summary>
+    /// Checks within tenant regardless of primary flag.
+    /// </summary>
+    TenantAny
+}

src/users/CodeBeam.UltimateAuth.Users.Contracts/Dtos/UserIdentifierDto.cs

@@ -5,6 +5,7 @@ public sealed record UserIdentifierDto
     public Guid Id { get; set; }
     public required UserIdentifierType Type { get; set; }
     public required string Value { get; set; }
+    public string NormalizedValue { get; set; } = default!;
     public bool IsPrimary { get; set; }
     public bool IsVerified { get; set; }
     public DateTimeOffset CreatedAt { get; init; }

src/users/CodeBeam.UltimateAuth.Users.Contracts/Responses/IdentifierExistenceResult.cs

@@ -0,0 +1,10 @@
+using CodeBeam.UltimateAuth.Core.Domain;
+
+namespace CodeBeam.UltimateAuth.Users.Contracts;
+
+public sealed record IdentifierExistenceResult(
+    bool Exists,
+    UserKey? OwnerUserKey = null,
+    Guid? OwnerIdentifierId = null,
+    bool OwnerIsPrimary = false
+    );