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

public enum CanonicalRole { Viewer, Operator, Engineer, Designer, Deployer, Administrator }

public sealed record GroupRoleMapping<TRole>(IReadOnlyList<TRole> Roles, object? Scope);

/// <summary>
/// Maps a user's directory group memberships to a set of roles (typically
/// <see cref="CanonicalRole"/>) plus an opaque scope payload.
/// </summary>
/// <typeparam name="TRole">The role vocabulary, e.g. <see cref="CanonicalRole"/>.</typeparam>
/// <remarks>
/// This library ships only the contract. Concrete canonical→native mappers are provided
/// per-consumer (config-backed for OtOpcUa/mxaccessgw, DB/delegate-backed for ScadaBridge),
/// because the backing store and the canonical→native role/permission expansion stay per-project
/// (see <c>scadaproj/components/auth/GAPS.md</c>, gaps C1/C2). No default implementation is shipped here.
/// </remarks>
public interface IGroupRoleMapper<TRole>
{
    /// <summary>
    /// Maps the supplied <paramref name="groups"/> to the roles and scope they grant.
    /// </summary>
    /// <param name="groups">The user's directory group memberships.</param>
    /// <param name="ct">A token to request cancellation of the operation.</param>
    /// <returns>The roles granted and an opaque scope payload.</returns>
    Task<GroupRoleMapping<TRole>> MapAsync(IReadOnlyList<string> groups, CancellationToken ct);
}
