OTSSignsOrchestrator/OTSSignsOrchestrator.Core/Services/IAuthentikService.cs

using OTSSignsOrchestrator.Core.Models.DTOs;

namespace OTSSignsOrchestrator.Core.Services;

/// <summary>
/// Provisions SAML applications in Authentik and retrieves IdP metadata
/// needed to render the Xibo SAML settings-custom.php template.
/// </summary>
public interface IAuthentikService
{
    /// <summary>
    /// Creates an Authentik SAML provider and application for the given Xibo instance,
    /// then fetches the IdP metadata (entity ID, x509 cert, SSO/SLO URLs).
    /// If the application already exists (by slug), returns its existing metadata.
    /// </summary>
    Task<AuthentikSamlConfig> ProvisionSamlAsync(
        string instanceAbbrev,
        string instanceBaseUrl,
        CancellationToken ct = default);

    /// <summary>
    /// Tests the connection to Authentik by fetching the current user.
    /// Optionally accepts override URL/key for testing before saving.
    /// </summary>
    Task<(bool Success, string Message)> TestConnectionAsync(
        string? overrideUrl = null,
        string? overrideApiKey = null,
        CancellationToken ct = default);

    /// <summary>
    /// Returns all available flows from Authentik.
    /// </summary>
    Task<List<AuthentikFlowItem>> ListFlowsAsync(
        string? overrideUrl = null,
        string? overrideApiKey = null,
        CancellationToken ct = default);

    /// <summary>
    /// Returns all certificate keypairs from Authentik.
    /// </summary>
    Task<List<AuthentikKeypairItem>> ListKeypairsAsync(
        string? overrideUrl = null,
        string? overrideApiKey = null,
        CancellationToken ct = default);

    /// <summary>
    /// Returns all groups from Authentik, optionally filtered to those with
    /// at least one member. Used for syncing groups to Xibo instances.
    /// </summary>
    Task<List<AuthentikGroupItem>> ListGroupsAsync(
        string? overrideUrl = null,
        string? overrideApiKey = null,
        CancellationToken ct = default);

    // ─────────────────────────────────────────────────────────────────────────
    // Customer invitation infrastructure
    // ─────────────────────────────────────────────────────────────────────────

    /// <summary>
    /// Creates a group in Authentik with the given name.
    /// Returns the group PK (UUID string). If a group with that name already exists, returns its PK.
    /// </summary>
    Task<string> CreateGroupAsync(string groupName, CancellationToken ct = default);

    /// <summary>
    /// Creates an invitation stage in Authentik.
    /// Returns the stage PK. If a stage with that name already exists, returns its PK.
    /// </summary>
    Task<string> CreateInvitationStageAsync(string stageName, bool continueWithoutInvitation = false, CancellationToken ct = default);

    /// <summary>
    /// Creates an enrollment flow in Authentik with the given name and slug.
    /// Returns the flow PK (UUID string). If a flow with that slug already exists, returns its PK.
    /// </summary>
    Task<string> CreateEnrollmentFlowAsync(string name, string slug, CancellationToken ct = default);

    /// <summary>
    /// Binds a stage to a flow at the specified order.
    /// </summary>
    Task BindStageToFlowAsync(string flowSlug, string stagePk, int order, CancellationToken ct = default);

    /// <summary>
    /// Creates an expression policy in Authentik.
    /// Returns the policy PK. If a policy with that name already exists, returns its PK.
    /// </summary>
    Task<string> CreateExpressionPolicyAsync(string name, string expression, CancellationToken ct = default);

    /// <summary>
    /// Binds a policy to a flow stage binding (so it executes when that stage runs).
    /// </summary>
    Task BindPolicyToFlowStageBoundAsync(string flowStageBindingPk, string policyPk, CancellationToken ct = default);

    /// <summary>
    /// Binds a policy to a flow (policy/group/user binding tab).
    /// </summary>
    Task BindPolicyToFlowAsync(string flowSlug, string policyPk, CancellationToken ct = default);

    /// <summary>
    /// Creates a role in Authentik with the given name.
    /// Returns the role PK. If a role with that name already exists, returns its PK.
    /// </summary>
    Task<string> CreateRoleAsync(string roleName, CancellationToken ct = default);

    /// <summary>
    /// Assigns a set of permissions to a role.
    /// Permission codenames follow Django format, e.g. "add_invitation", "view_invitation".
    /// </summary>
    Task AssignPermissionsToRoleAsync(string rolePk, IEnumerable<string> permissionCodenames, CancellationToken ct = default);

    /// <summary>
    /// Assigns a role to a group so all members of the group inherit the role's permissions.
    /// </summary>
    Task AssignRoleToGroupAsync(string rolePk, string groupPk, CancellationToken ct = default);

    /// <summary>
    /// Finds the flow-stage binding PK for a specific stage bound to a flow at a given order.
    /// Returns null if not found.
    /// </summary>
    Task<string?> GetFlowStageBindingPkAsync(string flowSlug, int order, CancellationToken ct = default);

    /// <summary>
    /// Looks up a built-in Authentik stage by partial name match (e.g. "default-enrollment-prompt").
    /// Returns the stage PK, or null if not found.
    /// </summary>
    Task<string?> FindStageByNameAsync(string nameContains, CancellationToken ct = default);
}