namespace ZB.MOM.WW.OtOpcUa.Security.Audit;

/// <summary>
/// Resolves the current HTTP principal's actor string for inclusion in a canonical
/// <c>ZB.MOM.WW.Audit.AuditEvent</c> as the <c>Actor</c> field.
/// </summary>
/// <remarks>
/// The seam abstracts the identity source so that:
/// <list type="bullet">
///   <item>production code uses <see cref="HttpAuditActorAccessor"/> (reads the
///   authenticated Blazor cookie principal from <c>IHttpContextAccessor</c>); and</item>
///   <item>unit tests or non-HTTP contexts can substitute a stub or return
///   <see langword="null"/> (which triggers the <c>"system"</c> fallback in
///   <see cref="AuditActor.Resolve"/>).</item>
/// </list>
/// <para>
/// <b>Note:</b> OtOpcUa has no live structured <c>AuditEvent</c> emit sites as of Phase 3
/// (all production audit flows through the bespoke stored-procedure path). This seam is
/// forward-looking — wired and tested so that future emit sites can call
/// <see cref="AuditActor.Resolve"/> and get the Auth principal automatically.
/// </para>
/// </remarks>
public interface IAuditActorAccessor
{
    /// <summary>
    /// Returns the authenticated principal's actor string, or <see langword="null"/> when
    /// there is no current HTTP context or the user is not authenticated.
    /// </summary>
    string? CurrentActor { get; }
}