Merge PR #15 command standards hardening

Author: MariusStorhaug

src/functions/private/Auth/Get-DomeneshopConfig.ps1

@@ -1,18 +1,47 @@
+#Requires -Modules @{ ModuleName = 'Context'; ModuleVersion = '8.1.6' }
+
 function Get-DomeneshopConfig {
+    <#
+        .SYNOPSIS
+        Get the Domeneshop module configuration.
+
+        .DESCRIPTION
+        Read the module configuration from the Context vault or return an in-memory default when no configuration has been stored.
+
+        .EXAMPLE
+        Get-DomeneshopConfig
+
+        Get the current Domeneshop module configuration.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Get-DomeneshopConfig.
+
+        .OUTPUTS
+        System.Object
+
+        The stored or default Domeneshop module configuration.
+
+        .NOTES
+        This read helper does not create or update Context vault entries.
+
+        .LINK
+        https://psmodule.io/Context/
+    #>
+    [OutputType([object])]
     [CmdletBinding()]
     param()
 
     $vault = 'Domeneshop'
     $id = '__Domeneshop.Config'
-    $config = Get-Context -ID $id -Vault $vault -ErrorAction SilentlyContinue
+    $config = Get-Context -ID $id -Vault $vault
 
     if (-not $config) {
-        $config = [ordered]@{
+        $config = [pscustomobject][ordered]@{
             DefaultContext = $null
             ApiBaseUri     = 'https://api.domeneshop.no/v0'
         }
-        Set-Context -ID $id -Vault $vault -Context $config
-        $config = Get-Context -ID $id -Vault $vault
     }
 
     $config

src/functions/private/Auth/Resolve-DomeneshopContext.ps1

@@ -1,23 +1,52 @@
 function Resolve-DomeneshopContext {
+    <#
+        .SYNOPSIS
+        Validate a resolved Domeneshop context.
+
+        .DESCRIPTION
+        Verify that a context resolved by a public command contains the credentials and API endpoint required by private helpers.
+
+        .EXAMPLE
+        Resolve-DomeneshopContext -Context $storedContext
+
+        Validate and emit a stored Domeneshop context.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Resolve-DomeneshopContext.
+
+        .OUTPUTS
+        System.Object
+
+        The validated Domeneshop context.
+
+        .NOTES
+        This helper never selects or defaults a context. Public commands own that behavior.
+
+        .LINK
+        https://psmodule.io/Context/
+    #>
+    [OutputType([object])]
     [CmdletBinding()]
     param(
-        [Parameter()]
-        [string] $Context
+        # The context object selected by a public command.
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [object] $Context
     )
 
-    $resolvedContext = if ($Context) {
-        Get-DomeneshopContext -Context $Context
-    } else {
-        Get-DomeneshopContext
+    if ($null -eq $Context) {
+        throw "No Domeneshop context found. Run 'Connect-DomeneshopAccount' first."
     }
 
-    if (-not $resolvedContext) {
-        throw "No Domeneshop context found. Run 'Connect-DomeneshopAccount' first."
+    if ([string]::IsNullOrWhiteSpace([string] $Context.Token) -or -not ($Context.Secret -is [securestring])) {
+        throw "The Domeneshop context [$($Context.ID)] is missing valid credentials."
     }
 
-    if ([string]::IsNullOrEmpty($resolvedContext.Token) -or -not ($resolvedContext.Secret -is [securestring])) {
-        throw "The Domeneshop context [$($resolvedContext.ID)] is missing valid credentials."
+    if ([string]::IsNullOrWhiteSpace([string] $Context.ApiBaseUri)) {
+        throw "The Domeneshop context [$($Context.ID)] is missing an API base URI."
     }
 
-    $resolvedContext
+    $Context
 }

src/functions/private/Auth/Set-DomeneshopDefaultContext.ps1

@@ -1,11 +1,46 @@
+#Requires -Modules @{ ModuleName = 'Context'; ModuleVersion = '8.1.6' }
+
 function Set-DomeneshopDefaultContext {
-    [CmdletBinding()]
+    <#
+        .SYNOPSIS
+        Set the default Domeneshop context name.
+
+        .DESCRIPTION
+        Persist the selected default context name in the Domeneshop configuration entry.
+
+        .EXAMPLE
+        Set-DomeneshopDefaultContext -Context 'production'
+
+        Set production as the default Domeneshop context.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Set-DomeneshopDefaultContext.
+
+        .OUTPUTS
+        None
+
+        Set-DomeneshopDefaultContext doesn't emit output.
+
+        .NOTES
+        The public caller is responsible for guarding this mutation with ShouldProcess.
+
+        .LINK
+        https://psmodule.io/Context/
+    #>
+    [OutputType([void])]
+    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Low')]
     param(
+        # The name of an existing Domeneshop context.
         [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
         [string] $Context
     )
 
     $config = Get-DomeneshopConfig
     $config.DefaultContext = $Context
-    Set-Context -ID '__Domeneshop.Config' -Vault 'Domeneshop' -Context $config
+    if ($PSCmdlet.ShouldProcess('Domeneshop module configuration', "Set [$Context] as the default context")) {
+        $null = Set-Context -ID '__Domeneshop.Config' -Vault 'Domeneshop' -Context $config
+    }
 }

src/functions/private/Get-DomeneshopApiBaseUri.ps1

@@ -1,14 +1,50 @@
 function Get-DomeneshopApiBaseUri {
+    <#
+        .SYNOPSIS
+        Get the API base URI from a resolved Domeneshop context.
+
+        .DESCRIPTION
+        Validate and normalize the API base URI stored on a resolved Domeneshop context.
+
+        .EXAMPLE
+        Get-DomeneshopApiBaseUri -Context $resolvedContext
+
+        Get the normalized API base URI for a resolved context.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Get-DomeneshopApiBaseUri.
+
+        .OUTPUTS
+        System.String
+
+        The normalized Domeneshop API base URI.
+
+        .NOTES
+        The caller must resolve and validate the context before invoking this helper.
+
+        .LINK
+        https://api.domeneshop.no/docs/
+    #>
+    [OutputType([string])]
     [CmdletBinding()]
     param(
+        # The resolved Domeneshop context containing an API base URI.
         [Parameter(Mandatory)]
+        [ValidateNotNull()]
         [object] $Context
     )
 
     $apiBaseUri = [string] $Context.ApiBaseUri
-    if ([string]::IsNullOrEmpty($apiBaseUri)) {
-        $apiBaseUri = 'https://api.domeneshop.no/v0'
+    if ([string]::IsNullOrWhiteSpace($apiBaseUri)) {
+        throw "The Domeneshop context [$($Context.ID)] does not define an API base URI."
+    }
+
+    $parsedUri = $null
+    if (-not [uri]::TryCreate($apiBaseUri, [System.UriKind]::Absolute, [ref] $parsedUri)) {
+        throw "The Domeneshop context [$($Context.ID)] contains an invalid API base URI."
     }
 
-    $apiBaseUri.TrimEnd('/')
+    $parsedUri.AbsoluteUri.TrimEnd('/')
 }

src/functions/private/Invoke-DomeneshopApiRequest.ps1

@@ -1,16 +1,56 @@
 function Invoke-DomeneshopApiRequest {
+    <#
+        .SYNOPSIS
+        Send an authenticated request to the Domeneshop API.
+
+        .DESCRIPTION
+        Build an HTTP Basic credential from a resolved Domeneshop context and send a REST request, optionally with a JSON body.
+
+        .EXAMPLE
+        Invoke-DomeneshopApiRequest -Method Get -Uri $uri -Context $resolvedContext
+
+        Send an authenticated GET request.
+
+        .EXAMPLE
+        Invoke-DomeneshopApiRequest -Method Post -Uri $uri -Context $resolvedContext -Body $body
+
+        Send an authenticated POST request with a JSON body.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Invoke-DomeneshopApiRequest.
+
+        .OUTPUTS
+        System.Object
+
+        The response returned by the Domeneshop API.
+
+        .NOTES
+        Transport errors are terminating so public callers fail fast.
+
+        .LINK
+        https://api.domeneshop.no/docs/
+    #>
+    [OutputType([object])]
     [CmdletBinding()]
     param(
+        # The HTTP method accepted by the Domeneshop API.
         [Parameter(Mandatory)]
         [ValidateSet('Get', 'Post', 'Put', 'Delete')]
         [string] $Method,
 
+        # The absolute Domeneshop API endpoint URI.
         [Parameter(Mandatory)]
-        [string] $Uri,
+        [ValidateNotNull()]
+        [uri] $Uri,
 
+        # The resolved Domeneshop context containing valid credentials.
         [Parameter(Mandatory)]
+        [ValidateNotNull()]
         [object] $Context,
 
+        # The request payload to serialize as JSON.
         [Parameter()]
         [AllowNull()]
         [object] $Body
@@ -26,12 +66,14 @@ function Invoke-DomeneshopApiRequest {
         Uri            = $Uri
         Authentication = 'Basic'
         Credential     = $credential
+        ErrorAction    = 'Stop'
     }
 
     if ($PSBoundParameters.ContainsKey('Body')) {
         $params['ContentType'] = 'application/json'
         $params['Body'] = ($Body | ConvertTo-Json -Depth 100)
     }
 
+    Write-Debug "Sending $Method request to [$Uri]."
     Invoke-RestMethod @params
 }

src/functions/public/Auth/Auth.md

@@ -0,0 +1,8 @@
+# Auth
+
+Public commands for storing and retrieving Domeneshop credential contexts.
+
+## Commands
+
+- `Connect-DomeneshopAccount`: Stores Domeneshop API credentials in the Context vault.
+- `Get-DomeneshopContext`: Gets a named or default context, or lists available contexts.

src/functions/public/Auth/Connect-DomeneshopAccount.ps1

@@ -1,3 +1,5 @@
+#Requires -Modules @{ ModuleName = 'Context'; ModuleVersion = '8.1.6' }
+
 function Connect-DomeneshopAccount {
     <#
         .SYNOPSIS
@@ -8,22 +10,52 @@ function Connect-DomeneshopAccount {
 
         .EXAMPLE
         Connect-DomeneshopAccount -Token 'my-token' -Secret (Read-Host -AsSecureString)
+
+        Store credentials in the default named context.
+
+        .INPUTS
+        None
+
+        You can't pipe objects to Connect-DomeneshopAccount.
+
+        .OUTPUTS
+        System.Object
+
+        The stored context when PassThru is specified.
+
+        .NOTES
+        Credentials are encrypted by the Context module.
+
+        .LINK
+        https://api.domeneshop.no/docs/
     #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingConvertToSecureStringWithPlainText', '',
+        Justification = 'String secrets remain supported for compatibility and are converted before storage.'
+    )]
     [OutputType([object])]
-    [CmdletBinding()]
+    [CmdletBinding(SupportsShouldProcess)]
     param(
+        # The Domeneshop API token used as the Basic authentication username.
         [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
         [string] $Token,
 
+        # The Domeneshop API secret as a string or secure string.
         [Parameter(Mandatory)]
+        [ValidateNotNull()]
         [object] $Secret,
 
+        # The name used to store and retrieve this credential context.
         [Parameter()]
+        [ValidateNotNullOrEmpty()]
         [string] $Context = 'default',
 
+        # Set this context as the default for commands that omit Context.
         [Parameter()]
         [switch] $Default,
 
+        # Emit the stored context after it is saved.
         [Parameter()]
         [switch] $PassThru
     )
@@ -43,14 +75,16 @@ function Connect-DomeneshopAccount {
         ConnectedAt = Get-Date
     }
 
-    Set-Context -ID $Context -Vault 'Domeneshop' -Context $contextObject
+    if ($PSCmdlet.ShouldProcess("Domeneshop context [$Context]", 'Store API credentials')) {
+        $null = Set-Context -ID $Context -Vault 'Domeneshop' -Context $contextObject
 
-    $config = Get-DomeneshopConfig
-    if ($Default -or [string]::IsNullOrEmpty($config.DefaultContext)) {
-        Set-DomeneshopDefaultContext -Context $Context
-    }
+        $config = Get-DomeneshopConfig
+        if ($Default -or [string]::IsNullOrWhiteSpace([string] $config.DefaultContext)) {
+            Set-DomeneshopDefaultContext -Context $Context
+        }
 
-    if ($PassThru) {
-        Get-DomeneshopContext -Context $Context
+        if ($PassThru) {
+            Get-DomeneshopContext -Context $Context
+        }
     }
 }