using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;

namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;

/// <summary>
/// CentralUI facade over the central-to-site OPC UA server-certificate trust
/// commands. Backs the "Trust certificate" affordance on the OPC UA
/// endpoint editor and the dedicated connection-certificates management page: it
/// forwards <see cref="TrustServerCertCommand"/> / <see cref="ListServerCertsCommand"/>
/// / <see cref="RemoveServerCertCommand"/> to the owning site via
/// <see cref="ZB.MOM.WW.ScadaBridge.Communication.CommunicationService"/>, which routes
/// them to the site Deployment Manager singleton.
/// </summary>
/// <remarks>
/// The service is the trust boundary for the cert-management capability: site-side
/// actors do not unwrap the central trust envelope, so the role check MUST run here
/// before any cross-cluster traffic is generated (mirrors <see cref="IBrowseService"/>
/// and <see cref="IEndpointVerificationService"/>). Trust + Remove
/// require the <c>Administrator</c> role; List requires the <c>Designer</c> role.
/// Transport failures (timeouts, unreachable sites) are translated into a typed
/// <see cref="CertTrustResult"/> so callers can render an inline outcome rather than
/// throwing.
///
/// <para>
/// The trusted-peer store is NODE-WIDE per site node (not per connection); a
/// trust/remove decision is broadcast by the site Deployment Manager to every site
/// node's <c>CertStoreActor</c>, and a list answers from the singleton's own node.
/// </para>
/// </remarks>
public interface ICertManagementService
{
    /// <summary>
    /// Trusts an OPC UA server certificate at every node of the owning site
    /// (Administrator-gated). The captured DER bytes are written into each node's
    /// trusted-peer PKI store under the thumbprint filename key.
    /// </summary>
    /// <param name="siteIdentifier">The target site identifier (the machine-readable <c>SiteIdentifier</c> used in Akka addresses, NOT the numeric primary key).</param>
    /// <param name="connectionName">The data connection the certificate was captured from (diagnostics / correlation only).</param>
    /// <param name="derBase64">The server certificate's DER encoding, base64-encoded.</param>
    /// <param name="thumbprint">The certificate thumbprint — used as the store filename key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that resolves to a <see cref="CertTrustResult"/> — success, or a classified failure (unauthorized / timeout / transport error).</returns>
    Task<CertTrustResult> TrustAsync(
        string siteIdentifier,
        string connectionName,
        string derBase64,
        string thumbprint,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Lists the certificates currently present in the owning site's trusted-peer
    /// and rejected PKI stores (Designer-gated). Answered from the site Deployment
    /// Manager singleton's own node.
    /// </summary>
    /// <param name="siteIdentifier">The target site identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that resolves to a <see cref="CertTrustResult"/> carrying the listed certificates on success.</returns>
    Task<CertTrustResult> ListAsync(
        string siteIdentifier,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Removes a previously-trusted OPC UA server certificate from every node of
    /// the owning site (Administrator-gated), identified by thumbprint.
    /// </summary>
    /// <param name="siteIdentifier">The target site identifier.</param>
    /// <param name="thumbprint">The thumbprint of the certificate to remove.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that resolves to a <see cref="CertTrustResult"/> — success, or a classified failure.</returns>
    Task<CertTrustResult> RemoveAsync(
        string siteIdentifier,
        string thumbprint,
        CancellationToken cancellationToken = default);
}
