scadaproj/ZB.MOM.WW.Auth/src/ZB.MOM.WW.Auth.Abstractions/Ldap/LdapContracts.cs

using System.Net.Security;

namespace ZB.MOM.WW.Auth.Abstractions.Ldap;

public enum LdapTransport { Ldaps, StartTls, None }

/// <summary>How <see cref="LdapOptions"/> authenticates a sign-in.</summary>
public enum LdapBindMode
{
    /// <summary>Bind as the service account, search for the user, re-bind as the user (0.3.0 behaviour).</summary>
    ServiceAccount,

    /// <summary>
    /// Bind as the signing-in user (identity built from <see cref="LdapOptions.UserBindTemplate"/>);
    /// a successful bind authenticates them, and the same connection reads their own entry for groups.
    /// No service account is used.
    /// </summary>
    User,
}

public sealed record LdapOptions
{
    public bool Enabled { get; init; } = true;
    public string Server { get; init; } = "localhost";
    public int Port { get; init; } = 3893;
    public LdapTransport Transport { get; init; } = LdapTransport.Ldaps;
    public bool AllowInsecure { get; init; }
    public string SearchBase { get; init; } = "";
    public string ServiceAccountDn { get; init; } = "";
    public string ServiceAccountPassword { get; init; } = "";
    public string UserNameAttribute { get; init; } = "cn";
    public string DisplayNameAttribute { get; init; } = "cn";
    public string GroupAttribute { get; init; } = "memberOf";
    public int ConnectionTimeoutMs { get; init; } = 10_000;

    /// <summary>
    /// Selects the authentication flow. <see cref="LdapBindMode.ServiceAccount"/> (the default) is the
    /// 0.3.0 bind-then-search-then-bind flow; <see cref="LdapBindMode.User"/> binds as the user and needs
    /// no <see cref="ServiceAccountDn"/> / <see cref="ServiceAccountPassword"/>.
    /// </summary>
    public LdapBindMode BindMode { get; init; } = LdapBindMode.ServiceAccount;

    /// <summary>
    /// <see cref="LdapBindMode.User"/> only: the simple-bind identity, with <c>{0}</c> replaced by the
    /// normalised login name. Must contain <c>{0}</c> exactly once.
    /// <para>
    /// Prefer the down-level form <c>EXAMPLE\{0}</c>: it maps exactly to the <c>sAMAccountName</c> the
    /// group search uses, so the account that binds is the account whose groups are read. A UPN
    /// template (<c>{0}@example.com</c>) is only correct where every account's UPN prefix equals its
    /// <c>sAMAccountName</c> — AD resolves a UPN bind against the explicit <c>userPrincipalName</c>, so
    /// a mismatch can fail sign-in or bind a different account than the one whose groups are read.
    /// </para>
    /// </summary>
    public string UserBindTemplate { get; init; } = "";

    /// <summary>
    /// <see cref="LdapBindMode.User"/> only: when <see langword="true"/> (default) a login typed as
    /// <c>DOMAIN\name</c> or <c>name@suffix</c> is reduced to <c>name</c>; when <see langword="false"/>
    /// such input is refused as bad credentials without contacting the directory.
    /// </summary>
    public bool AcceptDomainQualifiedNames { get; init; } = true;

    /// <summary>
    /// Ordered fallback LDAP endpoints tried when the primary (and any earlier fallback)
    /// fails with a system-side error (connect/TLS, service-account bind, or search).
    /// Each entry is <c>"host"</c> (adopts <see cref="Port"/>) or <c>"host:port"</c>.
    /// Empty (the default) disables failover entirely — single-endpoint behavior is
    /// unchanged. The TLS validation policy (<see cref="ServerCertificateValidationCallback"/>
    /// / <see cref="AllowInsecure"/>) applies to every endpoint. Endpoint preference is
    /// sticky: the service keeps using the last endpoint that answered until it fails.
    /// </summary>
    public IReadOnlyList<string> FallbackServers { get; init; } = Array.Empty<string>();

    /// <summary>
    /// Optional hook to harden (or, in dev, relax) TLS server-certificate validation for the
    /// <see cref="LdapTransport.Ldaps"/> / <see cref="LdapTransport.StartTls"/> transports. When
    /// <see langword="null"/> (the default) the LDAP client validates the server certificate against
    /// the OS trust store — it does <em>not</em> blind-accept. Supply a callback to pin a CA, validate
    /// the SAN against <see cref="Server"/>, or otherwise tighten validation. This is a code-only seam
    /// (not bound from configuration) and takes precedence over <see cref="AllowInsecure"/>.
    /// </summary>
    public RemoteCertificateValidationCallback? ServerCertificateValidationCallback { get; init; }
}

public enum LdapAuthFailure { BadCredentials, UserNotFound, AmbiguousUser, GroupLookupFailed, ServiceAccountBindFailed, Disabled }

public sealed record LdapAuthResult(bool Succeeded, string Username, string DisplayName, IReadOnlyList<string> Groups, LdapAuthFailure? Failure)
{
    public static LdapAuthResult Success(string username, string displayName, IReadOnlyList<string> groups) => new(true, username, displayName, groups, null);
    public static LdapAuthResult Fail(LdapAuthFailure failure) => new(false, "", "", Array.Empty<string>(), failure);
}

public interface ILdapAuthService
{
    /// <summary>
    /// Authenticates <paramref name="username"/> against the directory by bind-then-search and
    /// returns the outcome, including the resolved display name and group memberships on success.
    /// </summary>
    /// <param name="username">The login name to authenticate.</param>
    /// <param name="password">The credential to bind with.</param>
    /// <param name="ct">A token to request cancellation of the operation.</param>
    /// <returns>The authentication result.</returns>
    /// <remarks>
    /// The cancellation token is observed at entry only. Implementations backed by synchronous
    /// LDAP clients cannot abort an in-flight bind or search once it has been dispatched, so full
    /// cooperative cancellation is not guaranteed mid-call: a request that has already reached the
    /// directory will run to completion (subject to the configured connection timeout) even if the
    /// token is cancelled.
    /// </remarks>
    Task<LdapAuthResult> AuthenticateAsync(string username, string password, CancellationToken ct);
}