Plugins/PortsManagement.ps1

function Get-CurrentPluginType { 'dns-01' }

function Add-DnsTxt {
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$RecordName,
        [Parameter(Mandatory, Position = 1)]
        [string]$TxtValue,

        [Parameter(Mandatory)]
        [SecureString]$PortsApiKey,

        [Parameter()]
        [ValidateSet('Production', 'Demo')]
        [string]$PortsEnvironment = 'Production',

        [Parameter(ValueFromRemainingArguments)]
        $ExtraParams
    )

    Set-PortsConfig -ApiKey $PortsApiKey -Environment $PortsEnvironment

    # check for an existing record
    Write-Debug "Checking for existing record"
    $ExistingTXTrecords = Get-PortsDnsRecord -RecordName $RecordName -RecordType TXT

    if ($ExistingTXTrecords | Where-Object { $_.rdata -eq $TxtValue }) {
        Write-Debug "Record $RecordName already contains $TxtValue. Nothing to do."
        return
    }

    $DnsRecordParams = @{
        RecordName = $RecordName
        RecordType = 'TXT'
        RecordData = $TxtValue
        Comment    = "Added by Posh-ACME on $(Get-Date -Format 'o')"
    }
    Add-PortsDnsRecord @DnsRecordParams | Out-Null


    <#
    .SYNOPSIS
        Add a DNS TXT record to Ports Management DNS.
 
    .DESCRIPTION
        Use Ports Management API to add a TXT record to a Ports Management DNS zone.
 
    .PARAMETER RecordName
        The fully qualified name of the TXT record.
 
    .PARAMETER TxtValue
        The value of the TXT record.
 
    .PARAMETER PortsApiKey
        The scoped API key that has been given read/write permissions to the necessary zones.
 
    .PARAMETER PortsEnvironment
        The API environment to connect to. 'Production' or 'Demo' is available. Defaults to Production.
 
    .PARAMETER ExtraParams
        This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports.
 
    .EXAMPLE
        Add-DnsTxt '_acme-challenge.example.com' 'txt-value' -PortsApiKey (Read-Host 'Ports API key' -AsSecureString)
 
        Adds a TXT record for the specified site with the specified value.
    #>

}

function Remove-DnsTxt {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$RecordName,

        [Parameter(Mandatory, Position = 1)]
        [string]$TxtValue,

        [Parameter(Mandatory)]
        [SecureString]$PortsApiKey,

        [Parameter()]
        [ValidateSet('Production', 'Demo')]
        [string]$PortsEnvironment = 'Production',

        [Parameter(ValueFromRemainingArguments)]
        $ExtraParams
    )

    Set-PortsConfig -ApiKey $PortsApiKey -Environment $PortsEnvironment

    # check for an existing record
    Write-Debug "Checking for existing record"
    $ExistingTXTrecords = Get-PortsDnsRecord -RecordName $RecordName -RecordType TXT

    if (-not ($ExistingTXTrecords | Where-Object { $_.rdata -eq $TxtValue })) {
        Write-Debug "Record $RecordName does not contain $TxtValue. Nothing to do."
        return
    }

    Remove-PortsDnsRecord -RecordName $RecordName -RecordType 'TXT' -RecordData $TxtValue | Out-Null

    <#
    .SYNOPSIS
        Remove a DNS TXT record from Ports Management DNS
 
    .DESCRIPTION
        Use Ports Management API to remove a TXT record from a Ports Management DNS zone.
 
    .PARAMETER RecordName
        The fully qualified name of the TXT record.
 
    .PARAMETER TxtValue
        The value of the TXT record.
 
    .PARAMETER PortsEnvironment
        The API environment to connect to. 'Production' or 'Demo' is available. Defaults to Production.
 
    .PARAMETER ExtraParams
        This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports.
 
    .EXAMPLE
        Remove-DnsTxt '_acme-challenge.example.com' 'txt-value' -PortsApiKey (Read-Host 'Ports API key' -AsSecureString)
 
        Removes a TXT record for the specified site with the specified value.
    #>

}

function Save-DnsTxt {
    [CmdletBinding()]
    param(
        [Parameter(ValueFromRemainingArguments)]
        $ExtraParams
    )
    <#
    .SYNOPSIS
        Not required.
        The Ports Management API applies changes directly. No saving/comitting required.
        Review and publish functionality is for the web interface only.
 
    .DESCRIPTION
        This provider does not require calling this function to commit changes to DNS records.
 
    .PARAMETER ExtraParams
        This parameter can be ignored and is only used to prevent errors when splatting with more parameters than this function supports.
    #>

}

############################
# Helper Functions
############################

# Ports Management API reference:
# https://demo.ports.management/pmapi-doc/openapi-ui/index.html#/



function Get-PortsApiRootUrl {
    [CmdLetBinding()]
    param (
        [Parameter(Position = 0)]
        [ValidateSet('Production', 'Demo')]
        [string]$Environment = 'Production'
    )

    $BaseUrl = switch ($Environment) {
        'Demo' {
            'https://demo.ports.management/pmapi'
            break
        }

        'Production' {
            'https://api.ports.management'
            break
        }
    }

    return $BaseUrl

    <#
    .SYNOPSIS
        Helper function to retrieve the base API url.
 
    .DESCRIPTION
        Find the base API URL to make REST calls against, given API version and environment.
 
    .PARAMETER Environment
        The Ports Management has a 'Demo' endpoint of their API in addition to Production. Useful for testing.
 
    .EXAMPLE
        Get-PortsApiRootUrl
 
        Retrieves the default base URL, for production use
 
    .EXAMPLE
        Get-PortsApiRootUrl -Environment 'Demo'
 
        Retrieves the base URL for demo use
    #>

}
function Set-PortsConfig {
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [securestring]$ApiKey,

        [Parameter()]
        [ValidateSet('Production', 'Demo')]
        [string]$Environment = 'Production'
    )

    $script:PortsConfig = @{
        ApiRoot = Get-PortsApiRootUrl -Environment $Environment
        ApiCredential = [PSCredential]::new('a', $ApiKey)
    }
}

function Invoke-PortsRestMethod {
    [CmdLetBinding()]
    param (
        [Parameter(Mandatory, Position = 0)]
        [ValidateNotNullOrEmpty()]
        [string]$Endpoint,

        [Parameter(Mandatory, Position = 1)]
        [Microsoft.PowerShell.Commands.WebRequestMethod]
        $Method,

        [Parameter(Position = 2)]
        [string]$Body,

        [Parameter(Position = 3, HelpMessage = 'Used to limit returned result count from supported endpoints')]
        [int]$ResultSize
    )

    if (-not $script:PortsConfig) {
        $PSCmdlet.ThrowTerminatingError(
            [System.Management.Automation.ErrorRecord]::new(
                "Ports configuration not set. Please initialise settings with 'Set-PortsConfig' before making any API calls.",
                'PortsConfigurationNotSet',
                [System.Management.Automation.ErrorCategory]::NotSpecified,
                $script:PortsConfig
            )
        )
    }

    $RestSplat = @{
        Method      = $Method
        Uri         = $script:PortsConfig.ApiRoot + $Endpoint
        ContentType = 'application/json; charset=utf-8'
        Headers     = @{
            # Extract plain text credential from Ports Config
            'X-API-KEY' = $script:PortsConfig.ApiCredential.GetNetworkCredential().Password
        }
    }
    Write-Debug "$Method $($RestSplat.Uri)"
    if ($PSBoundParameters.Keys -contains 'Body') {
        $RestSplat.Body = $Body
        Write-Debug "Body: $Body"
    }

    $Response = Invoke-RestMethod @RestSplat @script:UseBasic -ErrorAction 'Stop'
    Write-Debug "Response metadata: $($Response.meta)"

    # Validate that our result returns in an expected format
    if ($Response -and $null -eq $Response.meta.invocationId) {
        Write-Debug
        $PSCmdlet.ThrowTerminatingError(
            [System.Management.Automation.ErrorRecord]::new(
                "API response did not contain expected metadata",
                'PortsApiMetadataMissing',
                [System.Management.Automation.ErrorCategory]::InvalidData,
                $Response
            )
        )
    }

    $AllResults = $Response.data
    if ($Response.meta.total -le $Response.meta.limit) {
        return $AllResults
    }

    Write-Debug "Response returned paginated. Not all results were included in first request. Starting loop through pages."
    $BaseUri = $RestSplat.Uri
    # Loop through pages with offset and collect all results into array
    $AllResults += do {
        # Construct a new Uri with the pagination parameters
        $RestSplat.Uri = $BaseUri + "?offset=$($Response.meta.offset + $Response.meta.limit)"
        Write-Debug "$Method $($RestSplat.Uri)"
        if ($PSBoundParameters.Keys -contains 'Body') {
            $RestSplat.Body = $Body
            Write-Debug "Body: $Body"
        }
        $Response = Invoke-RestMethod @RestSplat @script:UseBasic -ErrorAction 'Stop'
        Write-Debug "Response metadata: $($Response.meta)"
        # Output data to array
        $Response.data
    } while ($Response.meta.total -gt ($Response.meta.offset + $Response.meta.limit))

    return $AllResults


    <#
    .SYNOPSIS
        Invoke-RestMethod wrapper for Ports Management API
 
    .DESCRIPTION
        Used for making REST API calls against the Ports Management API
 
    .PARAMETER Endpoint
        The Ports Management API endpoint to make a request to, for example /v1/zones
 
    .EXAMPLE
        Invoke-PortsRestMethod -Endpoint '/v1/zones' -Method 'GET'
        Retrieves all zones
    #>

}

function Find-PortsZone {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$RecordName
    )

    # setup a module variable to cache the record to zone mapping
    # so it's quicker to find later
    if (!$script:PortsRecordZones) { $script:PortsRecordZones = @{} }

    # check for the record in the cache
    if ($script:PortsRecordZones.ContainsKey($RecordName)) {
        Write-Verbose "Returning result from cache"
        return $script:PortsRecordZones.$RecordName
    }

    Write-Verbose "Attempting to find hosted zone for $RecordName"

    # We need to find the zone ID for the closest/deepest sub-zone that would
    # contain the record.
    $Pieces = $RecordName.Split('.')
    for ($i = 0; $i -lt ($pieces.Count - 1); $i++) {

        $ZoneTest = $pieces[$i..($pieces.Count - 1)] -join '.'
        Write-Debug "Checking $zoneTest"
        $Response = $null

        try {
            $Response = Invoke-PortsRestMethod -Endpoint "/v1/zones/$ZoneTest" -Method "Get"
        }
        catch {
            if (400 -eq $_.Exception.Response.StatusCode.value__) {
                Write-Debug "Zone not found: $zoneTest"
            }
            else { throw }
        }

        if ($Response) {
            Write-Debug "Reponse data received for $ZoneTest"
            $ZoneID = $Response[0].id
            $script:PortsRecordZones.$RecordName = $ZoneID
            return $ZoneID
        }
    }

    return $null
}

function Add-PortsDnsRecord {
    #Reference: https://demo.ports.management/pmapi-doc/openapi-ui/index.html#/dns/patch_v1_zones__name_
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$RecordName,

        [Parameter(Mandatory, Position = 1)]
        [ValidateSet('A', 'AAAA', 'CAA', 'CNAME', 'DNAME', 'LOC', 'MX', 'NAPTR', 'NS', 'PTR', 'RP', 'SRV', 'SSHFP', 'TLSA', 'TXT')]
        [string]$RecordType,

        [Parameter(Mandatory, Position = 2)]
        [string]$RecordData,

        [Parameter()]
        [int]$TTL,

        [Parameter()]
        [string]$Comment
    )

    if (-not ($ZoneID = Find-PortsZone -RecordName $RecordName)) {
        $PSCmdlet.ThrowTerminatingError(
            [System.Management.Automation.ErrorRecord]::new(
                "Unable to find Ports Management hosted zone for '$RecordName'",
                'PortsDnsZoneNotFound',
                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
                $RecordName # Offending object
            )
        )
    }

    # Strip the tailing identified zone from record name
    $RecShort = ($RecordName -ireplace [regex]::Escape($ZoneId), [string]::Empty).TrimEnd('.')
    if ($RecShort -eq [string]::Empty) {
        $RecShort = '@'
    }

    # Due to the Ports Management API utilizing JSON Merge (RFC 7396) for the zone records,
    # we cannot add or remove individual records in an array of records.
    # Therefore we need to save the existing state of the record before making changes,
    # to allow us insert our records into the existing array.

    $NewRecords = @()
    $ExistingRecords = Get-PortsDnsRecord -RecordName $RecordName -RecordType $RecordType
    if ($ExistingRecords) { $NewRecords += $ExistingRecords }
    $NewRecordData = @{rdata = $RecordData }

    if ($PSBoundParameters.Keys -contains 'TTL') {
        $NewRecordData['ttl'] = $TTL
    }

    if ($PSBoundParameters.Keys -contains 'Comment') {
        $NewRecordData['comments'] = $Comment
    }

    $NewRecords += [PSCustomObject]$NewRecordData

    $RequestData = @{
        data = @{
            type       = 'zone'
            id         = $ZoneID
            attributes = @{
                records = @{
                    $RecShort = @{
                        $RecordType = @(
                            $NewRecords
                        )
                    }
                }
            }
        }
    }

    $BodyJson = ConvertTo-Json -InputObject $RequestData -Depth 10 -Compress
    try {
        Invoke-PortsRestMethod -Method Patch -Endpoint "/v1/zones/$ZoneID" -Body $BodyJson | Out-Null
    }
    catch {
        $PortsError = $_.ErrorDetails.Message | ConvertFrom-Json
        if ($PortsError.error.message -eq "Zones with pending updates can't be updated by API") {
            $PSCmdlet.ThrowTerminatingError(
                [System.Management.Automation.ErrorRecord]::new(
                    "Zones with pending updates can't be updated by API. Check Ports Management for zone: '$ZoneID'",
                    'PortsDnsZonePendingUpdates',
                    [System.Management.Automation.ErrorCategory]::ResourceBusy,
                    $ZoneID # Offending object
                )
            )
        }
        else {
            throw
        }
    }
}

function Remove-PortsDnsRecord {
    #Reference: https://demo.ports.management/pmapi-doc/openapi-ui/index.html#/dns/patch_v1_zones__name_
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$RecordName,

        [Parameter(Mandatory, Position = 1)]
        [ValidateSet('A', 'AAAA', 'CAA', 'CNAME', 'DNAME', 'LOC', 'MX', 'NAPTR', 'NS', 'PTR', 'RP', 'SRV', 'SSHFP', 'TLSA', 'TXT')]
        [string]$RecordType,

        [Parameter(Mandatory, Position = 2)]
        [string]$RecordData
    )

    if (-not ($ZoneID = Find-PortsZone -RecordName $RecordName)) {
        $PSCmdlet.ThrowTerminatingError(
            [System.Management.Automation.ErrorRecord]::new(
                "Unable to find Ports Management hosted zone for '$RecordName'",
                'PortsDnsZoneNotFound',
                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
                $RecordName # Offending object
            )
        )
    }

    # Strip the tailing identified zone from record name
    $RecShort = ($RecordName -ireplace [regex]::Escape($ZoneId), [string]::Empty).TrimEnd('.')
    if ($RecShort -eq [string]::Empty) {
        $RecShort = '@'
    }

    # Due to the Ports Management API utilizing JSON Merge (RFC 7396) for the zone records,
    # we cannot add or remove individual records in an array of records.
    # Therefore we need to save the existing state of the record before making changes,
    # to allow us remove our specific record from the existing array.

    $ExistingRecords = Get-PortsDnsRecord -RecordName $RecordName -RecordType $RecordType

    # We must only remove records with the given value, not all records of the matching record type for the same record name
    $NewRecords = $ExistingRecords | Where-Object { $_.'rdata' -ne $RecordData }

    $RequestData = @{
        data = @{
            type       = 'zone'
            id         = $ZoneID
            attributes = @{
                records = @{
                    $RecShort = @{
                        $RecordType = @(
                            $NewRecords
                        )
                    }
                }
            }
        }
    }

    $BodyJson = ConvertTo-Json -InputObject $RequestData -Depth 10 -Compress
    Invoke-PortsRestMethod -Method Patch -Endpoint "/v1/zones/$ZoneID" -Body $BodyJson | Out-Null

}

function Get-PortsDnsRecord {
    #Reference: https://demo.ports.management/pmapi-doc/openapi-ui/index.html#/dns/get_v1_zones__name_
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, Position = 0)]
        [string]$RecordName,

        [Parameter(Position = 1)]
        [ValidateSet('A', 'AAAA', 'CAA', 'CNAME', 'DNAME', 'LOC', 'MX', 'NAPTR', 'NS', 'PTR', 'RP', 'SRV', 'SSHFP', 'TLSA', 'TXT')]
        [string]$RecordType
    )

    if (-not ($ZoneID = Find-PortsZone -RecordName $RecordName)) {
        $PSCmdlet.ThrowTerminatingError(
            [System.Management.Automation.ErrorRecord]::new(
                "Unable to find Ports Management hosted zone for '$RecordName'",
                'PortsDnsZoneNotFound',
                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
                $RecordName # Offending object
            )
        )
    }
    # Strip the tailing identified zone from record name
    $RecShort = ($RecordName -ireplace [regex]::Escape($ZoneId), [string]::Empty).TrimEnd('.')
    if ($RecShort -eq [string]::Empty) {
        $RecShort = '@'
    }

    $Response = Invoke-PortsRestMethod -Method GET -Endpoint "/v1/zones/$ZoneID"
    $Records = $Response.attributes.records.$RecShort
    if ($PSBoundParameters.Keys -contains 'RecordType') {
        return $Records.$RecordType
    }
    return $Records
}