using Microsoft.AspNetCore.Authorization;
using ZB.MOM.WW.Auth.AspNetCore;

namespace ZB.MOM.WW.Secrets.Ui;

/// <summary>
/// Authorization policies and the roles that back them for the secrets-management UI.
/// </summary>
/// <remarks>
/// Two policies gate the UI, layered by privilege:
/// <list type="bullet">
///   <item>
///     <description>
///     <see cref="ManagePolicy"/> — view and administer secret <em>metadata</em> (the list
///     page, create/rename/delete affordances). Satisfied by <see cref="ManageRole"/>,
///     <see cref="RevealRole"/>, or <see cref="AdminRole"/>.
///     </description>
///   </item>
///   <item>
///     <description>
///     <see cref="RevealPolicy"/> — the strictly more privileged right to reveal a secret's
///     plaintext value. Satisfied only by <see cref="RevealRole"/> or <see cref="AdminRole"/>.
///     Because both reveal-granting roles also satisfy <see cref="ManagePolicy"/>, holding
///     reveal always implies manage.
///     </description>
///   </item>
/// </list>
/// Both policies require an authenticated user. The requirements are expressed as role checks
/// against the canonical <see cref="ZbClaimTypes.Role"/> claim, so the host maps its LDAP
/// groups to these role names (via its <c>IGroupRoleMapper</c> / <c>Security:Ldap:GroupToRole</c>
/// configuration) exactly as it does for every other <c>ZB.MOM.WW</c> role. The role-name
/// constants are deliberately minimal and can be overridden by the host by registering its own
/// policies under the same policy names instead of calling <see cref="AddSecretsAuthorization"/>.
/// </remarks>
public static class SecretsAuthorization
{
    /// <summary>Policy name for administering secret metadata (the list page and management actions).</summary>
    public const string ManagePolicy = "secrets:manage";

    /// <summary>Policy name for revealing a secret's plaintext value — strictly more privileged than <see cref="ManagePolicy"/>.</summary>
    public const string RevealPolicy = "secrets:reveal";

    /// <summary>Role that grants secret metadata management (satisfies <see cref="ManagePolicy"/>).</summary>
    public const string ManageRole = "secrets-manager";

    /// <summary>Role that grants secret value reveal (satisfies both <see cref="RevealPolicy"/> and <see cref="ManagePolicy"/>).</summary>
    public const string RevealRole = "secrets-reveal";

    /// <summary>Administrator role that satisfies every secrets policy.</summary>
    public const string AdminRole = "administrator";

    /// <summary>
    /// Registers the <see cref="ManagePolicy"/> and <see cref="RevealPolicy"/> policies on the
    /// supplied <see cref="AuthorizationOptions"/>. Each policy requires an authenticated user;
    /// <see cref="RevealPolicy"/> is a strict superset-privilege of <see cref="ManagePolicy"/>.
    /// </summary>
    /// <param name="options">The authorization options to add the policies to.</param>
    /// <returns>The same <paramref name="options"/> instance, to allow chaining.</returns>
    /// <exception cref="ArgumentNullException"><paramref name="options"/> is <c>null</c>.</exception>
    public static AuthorizationOptions AddSecretsAuthorization(this AuthorizationOptions options)
    {
        ArgumentNullException.ThrowIfNull(options);

        options.AddPolicy(ManagePolicy, policy => policy
            .RequireAuthenticatedUser()
            .RequireRole(ManageRole, RevealRole, AdminRole));

        options.AddPolicy(RevealPolicy, policy => policy
            .RequireAuthenticatedUser()
            .RequireRole(RevealRole, AdminRole));

        return options;
    }
}