feat(signing): ✨ Add certificate validation options for code signing

- Introduced `-SkipValidation` parameter to bypass validation checks for certificates from `EnvVar` or `PfxFile` sources.
- Enhanced error handling for missing or invalid certificates.
- Updated localization strings for better clarity on certificate validation messages.

Author: HeyItsGilbert

PowerShellBuild/IB.tasks.ps1

@@ -1,28 +1,28 @@
 Remove-Variable -Name PSBPreference -Scope Script -Force -ErrorAction Ignore
 Set-Variable -Name PSBPreference -Option ReadOnly -Scope Script -Value (. ([IO.Path]::Combine($PSScriptRoot, 'build.properties.ps1')))
-$__DefaultBuildDependencies    = $PSBPreference.Build.Dependencies
+$__DefaultBuildDependencies = $PSBPreference.Build.Dependencies
 
 # Synopsis: Initialize build environment variables
-task Init {
+Task Init {
     Initialize-PSBuild -UseBuildHelpers -BuildEnvironment $PSBPreference
 }
 
 # Synopsis: Clears module output directory
-task Clean Init, {
+Task Clean Init, {
     Clear-PSBuildOutputFolder -Path $PSBPreference.Build.ModuleOutDir
 }
 
 # Synopsis: Builds module based on source directory
-task StageFiles Clean, {
+Task StageFiles Clean, {
     $buildParams = @{
-        Path                = $PSBPreference.General.SrcRootDir
-        ModuleName          = $PSBPreference.General.ModuleName
-        DestinationPath     = $PSBPreference.Build.ModuleOutDir
-        Exclude             = $PSBPreference.Build.Exclude
-        Compile             = $PSBPreference.Build.CompileModule
-        CompileDirectories  = $PSBPreference.Build.CompileDirectories
-        CopyDirectories     = $PSBPreference.Build.CopyDirectories
-        Culture             = $PSBPreference.Help.DefaultLocale
+        Path               = $PSBPreference.General.SrcRootDir
+        ModuleName         = $PSBPreference.General.ModuleName
+        DestinationPath    = $PSBPreference.Build.ModuleOutDir
+        Exclude            = $PSBPreference.Build.Exclude
+        Compile            = $PSBPreference.Build.CompileModule
+        CompileDirectories = $PSBPreference.Build.CompileDirectories
+        CopyDirectories    = $PSBPreference.Build.CopyDirectories
+        Culture            = $PSBPreference.Help.DefaultLocale
     }
 
     if ($PSBPreference.Help.ConvertReadMeToAboutHelp) {
@@ -59,7 +59,7 @@ $analyzePreReqs = {
 }
 
 # Synopsis: Execute PSScriptAnalyzer tests
-task Analyze -If (. $analyzePreReqs) Build,{
+Task Analyze -If (. $analyzePreReqs) Build, {
     $analyzeParams = @{
         Path              = $PSBPreference.Build.ModuleOutDir
         SeverityThreshold = $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel
@@ -86,7 +86,7 @@ $pesterPreReqs = {
 }
 
 # Synopsis: Execute Pester tests
-task Pester -If (. $pesterPreReqs) Build,{
+Task Pester -If (. $pesterPreReqs) Build, {
     $pesterParams = @{
         Path                         = $PSBPreference.Test.RootDir
         ModuleName                   = $PSBPreference.General.ModuleName
@@ -117,7 +117,7 @@ $genMarkdownPreReqs = {
 }
 
 # Synopsis: Generates PlatyPS markdown files from module help
-task GenerateMarkdown -if (. $genMarkdownPreReqs) StageFiles,{
+Task GenerateMarkdown -if (. $genMarkdownPreReqs) StageFiles, {
     $buildMDParams = @{
         ModulePath            = $PSBPreference.Build.ModuleOutDir
         ModuleName            = $PSBPreference.General.ModuleName
@@ -141,7 +141,7 @@ $genHelpFilesPreReqs = {
 }
 
 # Synopsis: Generates MAML-based help from PlatyPS markdown files
-task GenerateMAML -if (. $genHelpFilesPreReqs) GenerateMarkdown, {
+Task GenerateMAML -if (. $genHelpFilesPreReqs) GenerateMarkdown, {
     Build-PSBuildMAMLHelp -Path $PSBPreference.Docs.RootDir -DestinationPath $PSBPreference.Build.ModuleOutDir
 }
 
@@ -155,7 +155,7 @@ $genUpdatableHelpPreReqs = {
 }
 
 # Synopsis: Create updatable help .cab file based on PlatyPS markdown help
-task GenerateUpdatableHelp -if (. $genUpdatableHelpPreReqs) BuildHelp, {
+Task GenerateUpdatableHelp -if (. $genUpdatableHelpPreReqs) BuildHelp, {
     Build-PSBuildUpdatableHelp -DocsPath $PSBPreference.Docs.RootDir -OutputPath $PSBPreference.Help.UpdatableHelpOutDir
 }
 
@@ -184,21 +184,21 @@ Task Publish Test, {
 #region Summary Tasks
 
 # Synopsis: Builds help documentation
-task BuildHelp GenerateMarkdown,GenerateMAML
+Task BuildHelp GenerateMarkdown, GenerateMAML
 
 Task Build {
     if ([String]$PSBPreference.Build.Dependencies -ne [String]$__DefaultBuildDependencies) {
         throw [NotSupportedException]'You cannot use $PSBPreference.Build.Dependencies with Invoke-Build. Please instead redefine the build task or your default task to include your dependencies. Example: Task . Dependency1,Dependency2,Build,Test or Task Build Dependency1,Dependency2,StageFiles'
     }
-},StageFiles,BuildHelp
+}, StageFiles, BuildHelp
 
 # Synopsis: Execute Pester and ScriptAnalyzer tests
-task Test Analyze,Pester
+Task Test Analyze, Pester
 
-task . Build,Test
+Task . Build, Test
 
 # Synopsis: Signs module files (*.psd1, *.psm1, *.ps1) with an Authenticode signature
-task SignModule -If {
+Task SignModule -If {
     if (-not $PSBPreference.Sign.Enabled) {
         Write-Warning 'Module signing is not enabled.'
         return $false
@@ -246,7 +246,7 @@ task SignModule -If {
 }
 
 # Synopsis: Creates a Windows catalog (.cat) file for the built module
-task BuildCatalog -If {
+Task BuildCatalog -If {
     if (-not ($PSBPreference.Sign.Enabled -and $PSBPreference.Sign.Catalog.Enabled)) {
         Write-Warning 'Catalog generation is not enabled.'
         return $false
@@ -273,13 +273,13 @@ task BuildCatalog -If {
 }
 
 # Synopsis: Signs the module catalog (.cat) file with an Authenticode signature
-task SignCatalog -If {
+Task SignCatalog -If {
     if (-not ($PSBPreference.Sign.Enabled -and $PSBPreference.Sign.Catalog.Enabled)) {
         Write-Warning 'Catalog signing is not enabled.'
         return $false
     }
     if (-not (Get-Command -Name 'Set-AuthenticodeSignature' -ErrorAction Ignore)) {
-        Write-Warning 'Set-AuthenticodeSignature is not available. Module signing requires Windows.'
+        Write-Warning 'Set-AuthenticodeSignature is not available. Catalog signing requires Windows.'
         return $false
     }
     $true
@@ -327,6 +327,6 @@ task SignCatalog -If {
 }
 
 # Synopsis: Signs module files and catalog (meta task)
-task Sign SignCatalog
+Task Sign SignModule, SignCatalog
 
 #endregion Summary Tasks

PowerShellBuild/Public/Get-PSBuildCertificate.ps1

@@ -50,6 +50,10 @@ function Get-PSBuildCertificate {
         File system path to a PFX/P12 certificate file. Required when CertificateSource is PfxFile.
     .PARAMETER PfxFilePassword
         Password for the PFX file as a SecureString. Used by PfxFile source.
+    .PARAMETER SkipValidation
+        Skip validation checks (private key presence, expiration, Code Signing EKU) for certificates
+        loaded from EnvVar or PfxFile sources. Use with caution; invalid certificates will fail during
+        actual signing operations with less descriptive errors.
     .OUTPUTS
         System.Security.Cryptography.X509Certificates.X509Certificate2
         Returns the resolved certificate, or $null if none was found (Store/Thumbprint sources).
@@ -79,6 +83,11 @@ function Get-PSBuildCertificate {
     #>
     [CmdletBinding()]
     [OutputType([System.Security.Cryptography.X509Certificates.X509Certificate2])]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingPlainTextForPassword',
+        'CertificatePasswordEnvVar',
+        Justification = 'This is not a password in plain text. It is the name of an environment variable that contains the password, which is a common pattern for CI/CD pipelines and secrets management.'
+    )]
     param(
         [ValidateSet('Auto', 'Store', 'Thumbprint', 'EnvVar', 'PfxFile')]
         [string]$CertificateSource = 'Auto',
@@ -93,7 +102,9 @@ function Get-PSBuildCertificate {
 
         [string]$PfxFilePath,
 
-        [securestring]$PfxFilePassword
+        [securestring]$PfxFilePassword,
+
+        [switch]$SkipValidation
     )
 
     # Resolve 'Auto' to the actual source based on environment variable presence
@@ -104,7 +115,7 @@ function Get-PSBuildCertificate {
         } else {
             'Store'
         }
-        Write-Verbose "CertificateSource is 'Auto'. Resolved to '$resolvedSource'."
+        Write-Verbose ($LocalizedData.CertificateSourceAutoResolved -f $resolvedSource)
     }
 
     $cert = $null
@@ -119,18 +130,37 @@ function Get-PSBuildCertificate {
             }
         }
         'Thumbprint' {
-            $cert = Get-ChildItem -Path $CertStoreLocation |
-                Where-Object { $_.Thumbprint -eq $Thumbprint -and $_.HasPrivateKey -and $_.NotAfter -gt (Get-Date) } |
+            if ([string]::IsNullOrWhiteSpace($Thumbprint)) {
+                throw "CertificateSource 'Thumbprint' requires a non-empty Thumbprint value."
+            }
+
+            # Normalize thumbprint input by removing whitespace for robust matching
+            $normalizedThumbprint = ($Thumbprint -replace '\s', '')
+
+            $cert = Get-ChildItem -Path $CertStoreLocation -CodeSigningCert |
+                Where-Object {
+                    ($_.Thumbprint -replace '\s', '') -ieq $normalizedThumbprint -and
+                    $_.HasPrivateKey -and
+                    $_.NotAfter -gt (Get-Date)
+                } |
                 Select-Object -First 1
             if ($cert) {
                 Write-Verbose ($LocalizedData.CertificateResolvedFromThumbprint -f $Thumbprint, $cert.Subject)
             }
         }
         'EnvVar' {
             $b64Value = [System.Environment]::GetEnvironmentVariable($CertificateEnvVar)
-            $buffer   = [System.Convert]::FromBase64String($b64Value)
+            if ([string]::IsNullOrWhiteSpace($b64Value)) {
+                throw "Environment variable '$CertificateEnvVar' is not set or is empty. When using CertificateSource='EnvVar', you must provide a Base64-encoded PFX in this variable."
+            }
+
+            try {
+                $buffer = [System.Convert]::FromBase64String($b64Value)
+            } catch [System.FormatException] {
+                throw "Environment variable '$CertificateEnvVar' does not contain a valid Base64-encoded PFX value."
+            }
             $password = [System.Environment]::GetEnvironmentVariable($CertificatePasswordEnvVar)
-            $cert     = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($buffer, $password)
+            $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($buffer, $password)
             Write-Verbose ($LocalizedData.CertificateResolvedFromEnvVar -f $CertificateEnvVar)
         }
         'PfxFile' {
@@ -139,5 +169,27 @@ function Get-PSBuildCertificate {
         }
     }
 
+    # Validate certificates loaded from EnvVar or PfxFile sources unless -SkipValidation is specified
+    if ($cert -and -not $SkipValidation -and ($resolvedSource -eq 'EnvVar' -or $resolvedSource -eq 'PfxFile')) {
+        # Check for private key
+        if (-not $cert.HasPrivateKey) {
+            throw ($LocalizedData.CertificateMissingPrivateKey -f $cert.Subject)
+        }
+
+        # Check expiration
+        if ($cert.NotAfter -le (Get-Date)) {
+            throw ($LocalizedData.CertificateExpired -f $cert.NotAfter, $cert.Subject)
+        }
+
+        # Check for Code Signing EKU (1.3.6.1.5.5.7.3.3)
+        $codeSigningOid = '1.3.6.1.5.5.7.3.3'
+        $hasCodeSigningEku = $cert.EnhancedKeyUsageList | Where-Object { $_.ObjectId -eq $codeSigningOid }
+        if (-not $hasCodeSigningEku) {
+            throw ($LocalizedData.CertificateMissingCodeSigningEku -f $cert.Subject)
+        }
+
+        Write-Verbose "Certificate validation passed: HasPrivateKey=$($cert.HasPrivateKey), NotAfter=$($cert.NotAfter), CodeSigningEKU=Present"
+    }
+
     $cert
 }

PowerShellBuild/Public/New-PSBuildFileCatalog.ps1

@@ -65,7 +65,6 @@ function New-PSBuildFileCatalog {
         Path            = $ModulePath
         CatalogFilePath = $CatalogFilePath
         CatalogVersion  = $CatalogVersion
-        Verbose         = $VerbosePreference
     }
 
     Microsoft.PowerShell.Security\New-FileCatalog @catalogParams

PowerShellBuild/en-US/Messages.psd1

@@ -31,4 +31,8 @@ CertificateResolvedFromPfxFile=Resolved code signing certificate from PFX file [
 SigningModuleFiles=Signing [{0}] file(s) matching [{1}] in [{2}]...
 CreatingFileCatalog=Creating file catalog [{0}] (version {1})...
 FileCatalogCreated=File catalog created: [{0}]
+CertificateSourceAutoResolved=CertificateSource is 'Auto'. Resolved to '{0}'.
+CertificateMissingPrivateKey=The resolved certificate does not have an accessible private key. Code signing requires a certificate with a private key. Subject=[{0}]
+CertificateExpired=The resolved certificate has expired (NotAfter: {0}). Code signing requires a valid, unexpired certificate. Subject=[{1}]
+CertificateMissingCodeSigningEku=The resolved certificate does not have the Code Signing Enhanced Key Usage (EKU: 1.3.6.1.5.5.7.3.3). Subject=[{0}]
 '@

PowerShellBuild/psakeFile.ps1

@@ -312,7 +312,7 @@ $signCatalogPreReqs = {
         $result = $false
     }
     if (-not (Get-Command -Name 'Set-AuthenticodeSignature' -ErrorAction Ignore)) {
-        Write-Warning 'Set-AuthenticodeSignature is not available. Module signing requires Windows.'
+        Write-Warning 'Set-AuthenticodeSignature is not available. Catalog signing requires Windows.'
         $result = $false
     }
     $result