🌟 [Major]: Context as PSCustomObject (#48)

## Description

Think we are finally there:

- Context are now returned as `[PSCustomObjects]`.
  - Fixes #45
- SecureStrings are converted to plain text and prefixed with `[SECURE]`
and converted back when put in the customobject before being returned.
- Context are stored as JSON compressed strings.
  - Fixes #47
- Contexts now have an ID, that is decoupled from the contents of the
context, allowing to set them independently from the context values.
  - Fixes #46
- Removed initialization parameters for context vault, making the
initialization call simpler.
- Change parameter names for `Contexts`:
- The parameter identifying the context is now called `ID` and
`ContextID`.
- Change parameter names for `ContextSettings`:
- The parameter identifying the context is now called `ID` and
`ContextID`.
- Updated tests


## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [x] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

README.md

@@ -100,7 +100,7 @@ $script:Config = @{
 
 `src\loader.ps1`
 ```pwsh
-Write-Verbose "Initialized secret vault [$($script:Config.Context.VaultName)] of type [$($script:Config.Context.VaultType)]"
+Write-Verbose "Initialized secret vault [$($script:Config.VaultName)] of type [$($script:Config.VaultType)]"
 ### This is the context config for this module
 $contextParams = @{
     Name = $script:Config.Name

src/functions/private/Get-ContextVault.ps1

@@ -19,15 +19,15 @@ function Get-ContextVault {
     [CmdletBinding()]
     param()
 
-    if (-not $script:Config.Context.VaultName) {
+    if (-not $script:Config.VaultName) {
         throw 'Context vault name not set'
     }
 
-    Write-Verbose "Connecting to context vault [$($script:Config.Context.VaultName)]"
-    $secretVault = Get-SecretVault | Where-Object { $_.Name -eq $script:Config.Context.VaultName }
+    Write-Verbose "Connecting to context vault [$($script:Config.VaultName)]"
+    $secretVault = Get-SecretVault | Where-Object { $_.Name -eq $script:Config.VaultName }
     if (-not $secretVault) {
         Write-Error $_
-        throw "Context vault [$($script:Config.Context.VaultName)] not found"
+        throw "Context vault [$($script:Config.VaultName)] not found"
     }
 
     return $secretVault

src/functions/private/Initialize-ContextVault.ps1

@@ -25,11 +25,11 @@ function Initialize-ContextVault {
     param (
         # The name of the secret vault.
         [Parameter()]
-        [string] $Name = $script:Config.Context.VaultName,
+        [string] $Name = $script:Config.VaultName,
 
         # The type of the secret vault.
         [Parameter()]
-        [string] $Type = $script:Config.Context.VaultType
+        [string] $Type = $script:Config.VaultType
     )
     $vault = Get-SecretVault | Where-Object { $_.ModuleName -eq $Type }
     if (-not $vault) {

src/functions/private/JsonToObject/Convert-ContextHashtableToObjectRecursive.ps1

@@ -0,0 +1,64 @@
+function Convert-ContextHashtableToObjectRecursive {
+    <#
+        .SYNOPSIS
+        Converts a hashtable to a context object.
+
+        .DESCRIPTION
+        This function is used to convert a hashtable to a context object.
+        String values that are prefixed with '[SECURESTRING]', are converted back to SecureString objects.
+        Other values are converted to their original types, like ints, booleans, string, arrays, and nested objects.
+
+        .EXAMPLE
+        Convert-ContextHashtableToObjectRecursive -Hashtable @{
+            Name   = 'Test'
+            Token  = '[SECURESTRING]TestToken'
+            Nested = @{
+                Name  = 'Nested'
+                Token = '[SECURESTRING]NestedToken'
+            }
+        }
+
+        This example converts a hashtable to a context object, where the 'Token' and 'Nested.Token' values are SecureString objects.
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingConvertToSecureStringWithPlainText', '',
+        Justification = 'The securestring is read from the object this function reads.'
+    )]
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # Hashtable to convert to context object
+        [object] $Hashtable
+    )
+    $result = [pscustomobject]@{}
+
+    foreach ($key in $Hashtable.Keys) {
+        $value = $Hashtable[$key]
+        Write-Debug "Processing [$key]"
+        Write-Debug "Value type: $($value.GetType().FullName)"
+        Write-Debug "Value: $value"
+        if ($value -is [string] -and $value -like '`[SECURESTRING`]*') {
+            Write-Debug "Converting [$key] as [SecureString]"
+            $secureValue = $value -replace '^\[SECURESTRING\]', ''
+            $result | Add-Member -NotePropertyName $key -NotePropertyValue ($secureValue | ConvertTo-SecureString -AsPlainText -Force)
+        } elseif ($value -is [System.Collections.IEnumerable] -and ($value -isnot [string])) {
+            Write-Debug "Converting [$key] as [IEnumerable], including arrays and hashtables"
+            $result | Add-Member -NotePropertyName $key -NotePropertyValue @(
+                $value | ForEach-Object {
+                    if ($_ -is [hashtable]) {
+                        Convert-ContextHashtableToObjectRecursive $_
+                    } else {
+                        $_
+                    }
+                }
+            )
+        } elseif ($value -is [hashtable]) {
+            Write-Debug "Converting [$key] as [hashtable]"
+            $result | Add-Member -NotePropertyName $key -NotePropertyValue (Convert-ContextHashtableToObjectRecursive $value)
+        } else {
+            Write-Debug "Converting [$key] as regular value"
+            $result | Add-Member -NotePropertyName $key -NotePropertyValue $value
+        }
+    }
+    return $result
+}

src/functions/private/JsonToObject/ConvertFrom-ContextJson.ps1

@@ -0,0 +1,33 @@
+function ConvertFrom-ContextJson {
+    <#
+        .SYNOPSIS
+        Converts a JSON string to a context object.
+
+        .DESCRIPTION
+        Converts a JSON string to a context object.
+        [SECURESTRING] prefixed text is converted to SecureString objects.
+        Other values are converted to their original types, like ints, booleans, string, arrays, and nested objects.
+
+        .EXAMPLE
+        ConvertFrom-ContextJson -JsonString '{
+            "Name": "Test",
+            "Token": "[SECURESTRING]TestToken",
+            "Nested": {
+                "Name": "Nested",
+                "Token": "[SECURESTRING]NestedToken"
+            }
+        }'
+
+        This example converts a JSON string to a context object, where the 'Token' and 'Nested.Token' values are SecureString objects.
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # JSON string to convert to context object
+        [Parameter(Mandatory)]
+        [string] $JsonString
+    )
+
+    $hashtableObject = $JsonString | ConvertFrom-Json -Depth 100 -AsHashtable
+    return Convert-ContextHashtableToObjectRecursive $hashtableObject
+}

src/functions/private/ObjectToJSON/Convert-ContextObjectToHashtableRecursive.ps1

@@ -0,0 +1,70 @@
+function Convert-ContextObjectToHashtableRecursive {
+    <#
+        .SYNOPSIS
+        Converts a context object to a hashtable.
+
+        .DESCRIPTION
+        This function converts a context object to a hashtable.
+        Secure strings are converted to a string representation, prefixed with '[SECURESTRING]'.
+        Datetime objects are converted to a string representation using the 'o' format specifier.
+        Nested context objects are recursively converted to hashtables.
+
+        .EXAMPLE
+        Convert-ContextObjectToHashtableRecursive -Object ([PSCustomObject]@{
+            Name = 'MySecret'
+            AccessToken = '123123123' | ConvertTo-SecureString -AsPlainText -Force
+            Nested = @{
+                Name = 'MyNestedSecret'
+                NestedAccessToken = '123123123' | ConvertTo-SecureString -AsPlainText -Force
+            }
+        })
+
+        Converts the context object to a hashtable. Converts the AccessToken and NestedAccessToken secure strings to a string representation.
+    #>
+    [OutputType([hashtable])]
+    [CmdletBinding()]
+    param (
+        # The object to convert.
+        [object] $Object
+    )
+    $result = @{}
+
+    if ($Object -is [hashtable]) {
+        Write-Debug 'Converting [hashtable] to [PSCustomObject]'
+        $Object = [PSCustomObject]$Object
+    } elseif ($Object -is [string] -or $Object -is [int] -or $Object -is [bool]) {
+        Write-Debug 'returning as string'
+        return $Object
+    }
+
+    foreach ($property in $Object.PSObject.Properties) {
+        $value = $property.Value
+        Write-Debug "Processing [$($property.Name)]"
+        Write-Debug "Value type: $($value.GetType().FullName)"
+        if ($value -is [datetime]) {
+            Write-Debug '- as DateTime'
+            $result[$property.Name] = $value.ToString('o')
+        } elseif ($value -is [string] -or $Object -is [int] -or $Object -is [bool]) {
+            Write-Debug '- as string, int, bool'
+            $result[$property.Name] = $value
+        } elseif ($value -is [System.Security.SecureString]) {
+            Write-Debug '- as SecureString'
+            $value = $value | ConvertFrom-SecureString -AsPlainText
+            $result[$property.Name] = "[SECURESTRING]$value"
+        } elseif ($value -is [System.Collections.IEnumerable]) {
+            Write-Debug '- as IEnumerable, including arrays and hashtables'
+            $result[$property.Name] = @(
+                $value | ForEach-Object {
+                    Convert-ContextObjectToHashtableRecursive $_
+                }
+            )
+        } elseif ($value -is [psobject] -or $value -is [PSCustomObject]) {
+            Write-Debug '- as PSObject, PSCustomObject'
+            $result[$property.Name] = Convert-ContextObjectToHashtableRecursive $value
+        } else {
+            Write-Debug '- as regular value'
+            $result[$property.Name] = $value
+        }
+    }
+    return $result
+}

src/functions/private/ObjectToJSON/ConvertTo-ContextJson.ps1

@@ -0,0 +1,36 @@
+function ConvertTo-ContextJson {
+    <#
+        .SYNOPSIS
+        Takes an object and converts it to a JSON string.
+
+        .DESCRIPTION
+        Takes objects or hashtables and converts them to a JSON string.
+        SecureStrings are converted to plain text strings and prefixed with [SECURESTRING]. The conversion is recursive for any nested objects.
+        Use ConvertFrom-ContextJson to convert back to an object.
+
+        .EXAMPLE
+        ConvertTo-ContextJson -Context ([pscustomobject]@{
+            Name = 'MySecret'
+            AccessToken = '123123123' | ConvertTo-SecureString -AsPlainText -Force
+        })
+
+        Returns a JSON string representation of the object.
+
+        ```json
+        {
+            "Name": "MySecret",
+            "AccessToken ": "[SECURESTRING]123123123"
+        }
+        ```
+    #>
+    [OutputType([string])]
+    [CmdletBinding()]
+    param (
+        # The object to convert to a Context JSON string.
+        [Parameter(Mandatory)]
+        [object] $Context
+    )
+
+    $processedObject = Convert-ContextObjectToHashtableRecursive $Context
+    return ($processedObject | ConvertTo-Json -Depth 100 -Compress)
+}

src/functions/public/Context/Get-Context.ps1

@@ -6,66 +6,47 @@ filter Get-Context {
         Retrieves a context from the context vault.
 
         .DESCRIPTION
-        Retrieves contexts from a specified context vault. You can specify the name of the context to retrieve or use a wildcard pattern to retrieve
-        multiple contexts. If no name is specified, all contexts from the context vault will be retrieved.
-        Optionally, you can choose to retrieve the contexts as plain text by providing the -AsPlainText switch.
+        Retrieves a context from the context vault.
+        If no name is specified, all contexts from the context vault will be retrieved.
 
         .EXAMPLE
         Get-Context
 
         Get all contexts from the context vault.
 
         .EXAMPLE
-        Get-Context -Name 'MySecret'
+        Get-Context -ID 'MySecret'
 
         Get the context called 'MySecret' from the vault.
-
-        .EXAMPLE
-        Get-Context -Name 'My*'
-
-        Get all contexts that match the pattern 'My*' from the vault.
-
-        .EXAMPLE
-        'My*' | Get-Context
-
-        Get all contexts that match the pattern 'My*' from the vault.
     #>
-    [OutputType([hashtable])]
+    [OutputType([pscustomobject])]
     [CmdletBinding()]
     param(
-        # The name of the context to retrieve from the vault. Supports wildcard patterns.
-        [Parameter(
-            ValueFromPipeline,
-            ValueFromPipelineByPropertyName
-        )]
-        [SupportsWildcards()]
-        [Alias('Context', 'ContextName')]
-        [string] $Name = '*',
-
-        # Switch to retrieve all the contexts secrets as plain text.
+        # The name of the context to retrieve from the vault.
         [Parameter()]
-        [switch] $AsPlainText
+        [SupportsWildcards()]
+        [Alias('ContextID')]
+        [string] $ID
     )
 
     $contextVault = Get-ContextVault
 
-    Write-Verbose "Retrieving contexts from vault [$($contextVault.Name)] using pattern [$Name]"
-    $contexts = Get-SecretInfo -Vault $contextVault.Name | Where-Object { $_.Name -like "$($script:Config.Name)$Name" }
+    if (-not $PSBoundParameters.ContainsKey('ID')) {
+        Write-Verbose "Retrieving all contexts from [$($contextVault.Name)]"
+        $contexts = Get-SecretInfo -Vault $contextVault.Name | Select-Object -ExpandProperty Name
+    } elseif ([string]::IsNullOrEmpty($ID)) {
+        Write-Verbose "Return 0 contexts from [$($contextVault.Name)]"
+        return
+    } else {
+        $ID = "$($script:Config.SecretPrefix)$ID"
+        Write-Verbose "Retrieving context [$ID] from [$($contextVault.Name)]"
+        $contexts = Get-SecretInfo -Vault $contextVault.Name -Name $ID | Select-Object -ExpandProperty Name
+    }
 
-    Write-Verbose "Found [$($contexts.Count)] contexts in context vault [$($contextVault.Name)]"
+    Write-Verbose "Found [$($contexts.Count)] contexts in [$($contextVault.Name)]"
     $contexts | ForEach-Object {
-        Write-Verbose " - $($_.Name)"
-        Get-Secret -Name $_.Name -Vault $contextVault.Name -AsPlainText:$AsPlainText
+        Write-Verbose " - $_"
+        $contextJson = Get-Secret -Name $_ -Vault $contextVault.Name -AsPlainText
+        ConvertFrom-ContextJson -JsonString $contextJson
     }
 }
-
-Register-ArgumentCompleter -CommandName Get-Context -ParameterName Name -ScriptBlock {
-    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
-    $null = $commandName, $parameterName, $commandAst, $fakeBoundParameter
-
-    Get-SecretInfo -Vault $script:Config.Context.VaultName -Name "$($script:Config.Name)$wordToComplete*" -Verbose:$false |
-        ForEach-Object {
-            $contextName = $_.Name.Replace($script:Config.Name, '')
-            [System.Management.Automation.CompletionResult]::new($contextName, $contextName, 'ParameterValue', $contextName)
-        }
-}