feat: add remaining Authentication API endpoints

PiHoleShell/PiHoleShell.psm1

@@ -18,7 +18,7 @@ Export-ModuleMember -Function @(
     #Actions
     'Update-PiHoleActionsGravity', 'Invoke-PiHoleFlushNetwork', 'Invoke-PiHoleFlushLogs', 'Restart-PiHoleDnsService' `
         #Authentication
-        'Remove-PiHoleCurrentAuthSession' , 'Get-PiHoleCurrentAuthSession', 'Remove-PiHoleAuthSession', `
+        'Remove-PiHoleCurrentAuthSession' , 'Get-PiHoleCurrentAuthSession', 'Remove-PiHoleAuthSession', 'Get-PiHoleAuthStatus', 'Get-PiHoleAuthTotp', `
         #GroupManagement
         'Get-PiHoleGroup', 'New-PiHoleGroup', 'Update-PiHoleGroup', 'Remove-PiHoleGroup', `
         #DnsControl

PiHoleShell/Public/Authentication/Get-PiHoleAuthStatus.ps1

@@ -0,0 +1,82 @@
+function Get-PiHoleAuthStatus {
+    <#
+.SYNOPSIS
+Check if authentication is required
+
+.DESCRIPTION
+Checks whether your Pi-hole requires a login for the calling client. Some Pi-hole
+configurations skip authentication entirely for trusted local clients, in which case this
+reports a valid session without needing a password at all. Pass -Password to instead check
+the status of a real login with that password.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER Password
+The API Password you generated from your PiHole server. Optional - omit it to check whether
+your Pi-hole requires a login at all for this client, without authenticating.
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleAuthStatus -PiHoleServer "http://pihole.domain.com:8080"
+
+.EXAMPLE
+Get-PiHoleAuthStatus -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/auth')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [string]$Password,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+    try {
+        if ($PSBoundParameters.ContainsKey('Password')) {
+            $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+        }
+
+        $Params = @{
+            Uri                  = "$($PiHoleServer.OriginalString)/api/auth"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+        if ($Sid) {
+            $Params.Headers = @{sid = $($Sid) }
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $Object = [PSCustomObject]@{
+                Valid    = $Response.session.valid
+                Totp     = $Response.session.totp
+                Sid      = $Response.session.sid
+                Csrf     = $Response.session.csrf
+                Validity = $Response.session.validity
+                Message  = $Response.session.message
+            }
+            Write-Output $Object
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

PiHoleShell/Public/Authentication/Get-PiHoleAuthTotp.ps1

@@ -0,0 +1,76 @@
+function Get-PiHoleAuthTotp {
+    <#
+.SYNOPSIS
+Suggest new TOTP credentials
+
+.DESCRIPTION
+Suggests new TOTP credentials for setting up two-factor authentication (2FA) on your Pi-hole.
+This only suggests a secret; it does not enable 2FA by itself.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER Password
+The API Password you generated from your PiHole server
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleAuthTotp -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
+    #>
+    [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/auth/totp')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]
+    param (
+        [Parameter(Mandatory = $true)]
+        [System.URI]$PiHoleServer,
+        [Parameter(Mandatory = $true)]
+        [string]$Password,
+        [bool]$IgnoreSsl = $false,
+        [bool]$RawOutput = $false
+    )
+    try {
+        $Sid = Request-PiHoleAuth -PiHoleServer $PiHoleServer -Password $Password -IgnoreSsl $IgnoreSsl
+
+        $Params = @{
+            Headers              = @{sid = $($Sid) }
+            Uri                  = "$($PiHoleServer.OriginalString)/api/auth/totp"
+            Method               = "Get"
+            SkipCertificateCheck = $IgnoreSsl
+            ContentType          = "application/json"
+        }
+
+        $Response = Invoke-RestMethod @Params
+
+        if ($RawOutput) {
+            Write-Output $Response
+        }
+        else {
+            $Object = [PSCustomObject]@{
+                Type      = $Response.totp.type
+                Account   = $Response.totp.account
+                Issuer    = $Response.totp.issuer
+                Algorithm = $Response.totp.algorithm
+                Digits    = $Response.totp.digits
+                Period    = $Response.totp.period
+                Offset    = $Response.totp.offset
+                Secret    = $Response.totp.secret
+                Codes     = $Response.totp.codes
+            }
+            Write-Output $Object
+        }
+    }
+
+    catch {
+        Write-Error -Message $_.Exception.Message
+    }
+
+    finally {
+        if ($Sid) {
+            Remove-PiHoleCurrentAuthSession -PiHoleServer $PiHoleServer -Sid $Sid -IgnoreSsl $IgnoreSsl
+        }
+    }
+}

README.md

@@ -202,6 +202,8 @@ Session handling is automatic for every command above, but these are available f
 
 | Function | Description |
 |---|---|
+| `Get-PiHoleAuthStatus` | Check if authentication is required |
+| `Get-PiHoleAuthTotp` | Suggest new TOTP credentials |
 | `Get-PiHoleCurrentAuthSession` | List of all current sessions including their validity and further information about the client such as the IP address and user agent. |
 | `Remove-PiHoleAuthSession` | Using this endpoint, a session can be deleted by its ID. |
 <!-- COMMAND-REFERENCE:END -->