using System.Security.Claims;

namespace ZB.MOM.WW.MxGateway.Server.Dashboard;

/// <summary>
/// Decides whether a dashboard principal may observe one session's mirrored
/// event stream (SEC-25 / TST-15). Consulted at every subscribe seam: the
/// SignalR <c>EventsHub.SubscribeSession</c> join and the in-process
/// <c>IDashboardSessionEventSubscriber.Subscribe</c> used by the
/// session-details page.
/// </summary>
/// <remarks>
/// The dashboard authenticates LDAP users while sessions are owned by API keys —
/// two disjoint identity domains — so the bridge is the session <em>tag</em>: a
/// session inherits its owning key's tags, and a dashboard group grants tags via
/// <c>MxGateway:Dashboard:GroupToTag</c>. See
/// <c>docs/plans/2026-07-10-dashboard-session-acl-tst15.md</c>.
/// </remarks>
public interface IDashboardSessionAcl
{
    /// <summary>
    /// Returns whether <paramref name="principal"/> may observe the events of the
    /// session identified by <paramref name="sessionId"/>.
    /// </summary>
    /// <param name="principal">
    /// The dashboard caller. <see langword="null"/>, unauthenticated, or claim-less
    /// principals (including the anonymous-localhost path) are treated as Viewers
    /// holding an empty tag grant.
    /// </param>
    /// <param name="sessionId">Session id the caller wants to observe.</param>
    /// <returns><see langword="true"/> when the caller may observe the session; otherwise <see langword="false"/>.</returns>
    bool CanViewSession(ClaimsPrincipal? principal, string sessionId);
}