*-SqlDscServerPermission: Add commands SQL Server permission management

CHANGELOG.md

@@ -27,6 +27,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Enhanced workflow with proper environment variable configuration and DSCv3 verification.
   - Fixed environment variable persistence by using $GITHUB_ENV instead of
     job-level env declaration.
+- `New-SqlDscServerPermission`
+  - Added new public command to grant server permissions to a principal on a SQL Server Database Engine instance.
+- `Test-SqlDscServerPermission`
+  - Added new public command to test if server permissions for a principal are in the desired state.
+- `Remove-SqlDscServerPermission`
+  - Added new public command to remove (revoke) server permissions from a principal on a SQL Server Database Engine instance.
+- `Invoke-SqlDscServerPermissionOperation`
+  - Added new private function to encapsulate core logic for server permission operations.
+- `Test-SqlDscServerPermissionState`
+  - Added new private function to test if server permissions are in the desired state.
 - `Assert-SqlDscLogin`
   - Added new public command to validate that a specified SQL Server principal
     is a login.

source/Private/Invoke-SqlDscServerPermissionOperation.ps1

@@ -0,0 +1,132 @@
+<#
+    .SYNOPSIS
+        Invokes a server permission operation on a SQL Server principal.
+
+    .DESCRIPTION
+        This private function encapsulates the core logic for granting, denying,
+        or revoking server permissions on a SQL Server principal. It validates
+        the principal exists and executes the specified permission operation.
+
+    .PARAMETER ServerObject
+        Specifies current server connection object.
+
+    .PARAMETER Name
+        Specifies the name of the principal for which the permissions are modified.
+
+    .PARAMETER Permission
+        Specifies the permissions.
+
+    .PARAMETER State
+        Specifies the state of the permission operation (Grant, Deny, Revoke).
+
+    .PARAMETER WithGrant
+        Specifies that the principal should also be granted the right to grant
+        other principals the same permission. This parameter is only valid when
+        parameter State is set to Grant or Revoke.
+
+    .OUTPUTS
+        None.
+#>
+function Invoke-SqlDscServerPermissionOperation
+{
+    [CmdletBinding()]
+    [OutputType()]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter(Mandatory = $true)]
+        [Microsoft.SqlServer.Management.Smo.ServerPermissionSet]
+        $Permission,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Grant', 'Deny', 'Revoke')]
+        [System.String]
+        $State,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $WithGrant
+    )
+
+    # Validate that the principal exists
+    $testSqlDscIsPrincipalParameters = @{
+        ServerObject = $ServerObject
+        Name         = $Name
+    }
+
+    $isLogin = Test-SqlDscIsLogin @testSqlDscIsPrincipalParameters
+    $isRole = Test-SqlDscIsRole @testSqlDscIsPrincipalParameters
+
+    if (-not ($isLogin -or $isRole))
+    {
+        $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $Name, $ServerObject.InstanceName
+
+        $PSCmdlet.ThrowTerminatingError(
+            [System.Management.Automation.ErrorRecord]::new(
+                $missingPrincipalMessage,
+                'ISDSP0001', # cSpell: disable-line
+                [System.Management.Automation.ErrorCategory]::InvalidOperation,
+                $Name
+            )
+        )
+    }
+
+    # Get the permissions names that are set to $true in the ServerPermissionSet.
+    $permissionName = $Permission |
+        Get-Member -MemberType 'Property' |
+        Select-Object -ExpandProperty 'Name' |
+        Where-Object -FilterScript {
+            $Permission.$_
+        }
+
+    switch ($State)
+    {
+        'Grant'
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ServerPermission_GrantPermission -f ($permissionName -join ','), $Name
+            )
+
+            if ($WithGrant.IsPresent)
+            {
+                $ServerObject.Grant($Permission, $Name, $true)
+            }
+            else
+            {
+                $ServerObject.Grant($Permission, $Name)
+            }
+        }
+
+        'Deny'
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ServerPermission_DenyPermission -f ($permissionName -join ','), $Name
+            )
+
+            $ServerObject.Deny($Permission, $Name)
+        }
+
+        'Revoke'
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ServerPermission_RevokePermission -f ($permissionName -join ','), $Name
+            )
+
+            if ($WithGrant.IsPresent)
+            {
+                $ServerObject.Revoke($Permission, $Name, $false, $true)
+            }
+            else
+            {
+                $ServerObject.Revoke($Permission, $Name)
+            }
+        }
+    }
+}

source/Private/Test-SqlDscServerPermissionState.ps1

@@ -0,0 +1,152 @@
+<#
+    .SYNOPSIS
+        Tests if server permissions for a principal are in the desired state.
+
+    .DESCRIPTION
+        This private function tests if server permissions for a principal are
+        in the desired state by comparing current permissions with desired permissions.
+
+    .PARAMETER ServerObject
+        Specifies current server connection object.
+
+    .PARAMETER Name
+        Specifies the name of the principal to test.
+
+    .PARAMETER State
+        Specifies the desired state of the permission to be tested.
+
+    .PARAMETER Permission
+        Specifies the desired permissions as a ServerPermissionSet object.
+
+    .PARAMETER WithGrant
+        Specifies that the principal should have the right to grant other principals
+        the same permission. This parameter is only valid when parameter **State** is
+        set to 'Grant'.
+
+    .OUTPUTS
+        [System.Boolean]
+#>
+function Test-SqlDscServerPermissionState
+{
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateSet('Grant', 'GrantWithGrant', 'Deny')]
+        [System.String]
+        $State,
+
+        [Parameter(Mandatory = $true)]
+        [Microsoft.SqlServer.Management.Smo.ServerPermissionSet]
+        $Permission,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $WithGrant
+    )
+
+    Write-Verbose -Message (
+        $script:localizedData.ServerPermission_TestingDesiredState -f $Name, $ServerObject.InstanceName
+    )
+
+    # Handle WithGrant parameter by adjusting the effective state
+    $effectiveState = $State
+    if ($WithGrant.IsPresent -and $State -eq 'Grant')
+    {
+        $effectiveState = 'GrantWithGrant'
+    }
+
+    # Get current permissions
+    $serverPermissionInfo = $ServerObject |
+        Get-SqlDscServerPermission -Name $Name -ErrorAction 'SilentlyContinue'
+
+    if (-not $serverPermissionInfo)
+    {
+        Write-Verbose -Message (
+            $script:localizedData.ServerPermission_PermissionNotInDesiredState -f 'All', $effectiveState, $Name
+        )
+        return $false
+    }
+
+    # Convert current permissions to ServerPermission objects
+    $currentPermissions = $serverPermissionInfo | ConvertTo-SqlDscServerPermission
+
+    # Find the current permission for the desired state
+    $currentPermissionForState = $currentPermissions |
+        Where-Object -FilterScript {
+            $_.State -eq $effectiveState
+        }
+
+    if (-not $currentPermissionForState)
+    {
+        $currentPermissionForState = [ServerPermission] @{
+            State      = $effectiveState
+            Permission = @()
+        }
+    }
+
+    # Get the list of permission names that should be true in the permission set
+    $desiredPermissionNames = @()
+    $permissionProperties = $Permission | Get-Member -MemberType Property | Where-Object { $_.Name -ne 'IsEmpty' }
+
+    foreach ($property in $permissionProperties)
+    {
+        if ($Permission.$($property.Name) -eq $true)
+        {
+            $desiredPermissionNames += $property.Name
+        }
+    }
+
+    # Check if all desired permissions are present in current state
+    foreach ($desiredPermissionName in $desiredPermissionNames)
+    {
+        if ($desiredPermissionName -notin $currentPermissionForState.Permission)
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ServerPermission_PermissionNotInDesiredState -f $desiredPermissionName, $effectiveState, $Name
+            )
+            return $false
+        }
+    }
+
+    # Check if current state has permissions not in desired state (unless desired is empty)
+    if ($desiredPermissionNames.Count -gt 0)
+    {
+        foreach ($currentPermissionName in $currentPermissionForState.Permission)
+        {
+            if ($currentPermissionName -notin $desiredPermissionNames)
+            {
+                Write-Verbose -Message (
+                    $script:localizedData.ServerPermission_PermissionNotInDesiredState -f $currentPermissionName, $effectiveState, $Name
+                )
+                return $false
+            }
+        }
+    }
+    else
+    {
+        # If no permissions are desired, current should also be empty
+        if ($currentPermissionForState.Permission.Count -gt 0)
+        {
+            Write-Verbose -Message (
+                $script:localizedData.ServerPermission_PermissionNotInDesiredState -f ($currentPermissionForState.Permission -join ', '), $effectiveState, $Name
+            )
+            return $false
+        }
+    }
+
+    Write-Verbose -Message (
+        $script:localizedData.ServerPermission_InDesiredState -f $Name
+    )
+
+    return $true
+}