PSModule
diff --git a/‎.github/workflows/Process-PSModule.yml
Lines changed: 3 additions & 0 deletions b/‎.github/workflows/Process-PSModule.yml
Lines changed: 3 additions & 0 deletions
diff --git a/‎README.md
Lines changed: 40 additions & 45 deletions b/‎README.md
Lines changed: 40 additions & 45 deletions
diff --git a/‎src/functions/private/Import-Context.ps1
Lines changed: 38 additions & 10 deletions b/‎src/functions/private/Import-Context.ps1
Lines changed: 38 additions & 10 deletions
diff --git a/‎src/functions/private/JsonToObject/Convert-ContextHashtableToObjectRecursive.ps1
Lines changed: 32 additions & 10 deletions b/‎src/functions/private/JsonToObject/Convert-ContextHashtableToObjectRecursive.ps1
Lines changed: 32 additions & 10 deletions
@@ -28,3 +28,6 @@ jobs:
   Process-PSModule:
     uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v3
     secrets: inherit
+    with:
+      Verbose: true
+      Debug: true
@@ -5,24 +5,27 @@ we aim to store this data using a the concept of `Contexts` that are stored loca
 developers separate user and module data from the module code, so that modules can be created in a way where users can resume from where they left off
 without having to reconfigure the module or log in to services that support refreshing sessions with data you can store, i.e., refresh tokens.
 
+The module uses NaCl based encryption delivered by the `libsodium` library to encrypt and decrypt the data stored in a `Context`. The module that
+serves this functionality is called [`Sodium`](https://github.com/someuser/Sodium) and is a dependency of this module. The
+[`Sodium`](https://github.com/someuser/Sodium) module is automatically installed when you install this module.
+
 ## What is a `Context`?
 
-The consept of `Contexts` is built on top of the functionality provided by the `Microsoft.PowerShell.SecretManagement` and
-`Microsoft.PowerShell.SecretStore` modules. The `Context` module manages a set of `secrets` that is stored in a `SecretVault` instance. A context in
-this case is a data structure that supports secrets and regular datatypes converted to a modified JSON structure and stored as a string based secret
-in the `SecretStore`. The `Context` is stored in the `SecretVault` as a secret with the name `Context:<ContextId>`.
+A `Context` is a way to persist user and module state securely on disk while ensuring data remains encrypted at rest. It stores structured data that
+can be represented in JSON format, including regular values and secure secrets. It can hold multiple secrets (such as passwords or API tokens)
+alongside general data like configuration settings, session metadata, or user preferences. Secure secrets are specially handled to maintain their
+security when stored and retrieved.
 
-The context is stored as compressed JSON and could look something like the examples below. These are the same data but one shows the JSON structure
-that is stored in the `SecretStore` and the other shows the same data as a `PSCustomObject` that could be used in a PowerShell script.
+When saving a `Context`, the data is converted to a plain-text JSON structure, then encrypted and written to disk. Secure strings are marked with a
+special prefix before encryption, ensuring they can be safely restored as secure strings when the `Context` is loaded back into memory.
 
-The ID of the context is the name of the secret that it is stored as in the `SecretStore`. The ID is also stored with the context as a property in the
-context data structure. This is to make it easier to find the context when you only have the context object.
+When imported, the encrypted data is decrypted, converted back into its original structured format, and held in memory, ensuring both usability and
+security.
 
 <details>
-<summary>Input to Set-Context - As a PSCustomObject</summary>
+<summary>1. Storing data (object or dictionary) in persistent storage using Set-Context</summary>
 
 Typical the first input to a context (altho it can also be a hashtable or any other object type that converts with JSON)
-This object should NOT have a property on root of the object called `ID` as this is added by the module.
 
 ```pwsh
 Set-Context -ID 'john_doe' -Context ([PSCustomObject]@{
@@ -92,14 +95,14 @@ Set-Context -ID 'john_doe' -Context ([PSCustomObject]@{
 </details>
 
 <details>
-<summary>The stored data in a secret - As a processed JSON</summary>
+<summary>2. How the data utimatly gets stored - As a processed JSON</summary>
 
 This is how the objecet above is stored, except that this is an uncomressed version for readability.
-Here you see that the `ID` property is added.
+Here you see that the `ID` property gets added.
 
 ```json
 {
-    "ID": "Context:john_doe",
+    "ID": "john_doe",
     "Username": "john_doe",
     "AuthToken": "[SECURESTRING]ghp_12345ABCDE67890FGHIJ",
     "LoginTime": "2024-11-21T21:16:56.2518249+01:00",
@@ -184,15 +187,15 @@ Here you see that the `ID` property is added.
 </details>
 
 <details>
-<summary>Output from Get-Context - As a PSCustomObject</summary>
+<summary>3. Imported data (as a PSCustomObject) and shown with Get-Context</summary>
 
 This is how the object is returned from the `Get-Context` function.
 Notice that the `ID` property has been added to the object.
 
 ```pwsh
 Get-Context -ID 'john_doe'
 
-ID                : Context:john_doe
+ID                : john_doe
 UserPreferences   : @{DefaultBranch=main; Notifications=; Theme=dark; CodeReview=System.Object[]}
 LastLoginAttempts : {@{Success=True; IP=System.Security.SecureString; Timestamp=11/24/2024 2:09:12 PM}, @{Success=False; IP=System.Security.SecureString; Timestamp=11/23/2024 3:09:12 PM}}
 IsTwoFactorAuth   : True
@@ -208,12 +211,6 @@ AccessScopes      : {repo, user, gist, admin:org}
 ```
 </details>
 
-## Prerequisites
-
-This module relies on [Microsoft.PowerShell.SecretManagement](https://github.com/powershell/SecretManagement) and
-[Microsoft.PowerShell.SecretStore](https://github.com/PowerShell/SecretStore). The module automatically installs these modules if they are not
-already installed.
-
 ## Installation
 
 Install the module from the PowerShell Gallery by running the following command:
@@ -230,33 +227,33 @@ Lets have a look at how to use the module to store these types of data in abit m
 
 ### Module settings
 
-To store module data, the module developer can create a context that defines a "namespace" for the module. This context can store settings and secrets
-for the module. A module developer can also create additional contexts for additional settings that share the same lifecycle, like settings
+To store module data, the module developer can create a `Context` that defines a "namespace" for the module. This `Context` can store settings
+for the module. A module developer can also create additional `Contexts` for additional settings that share the same lifecycle, like settings
 associated with a module extension.
 
-Let's say we have a module called `GitHub` that needs to store some settings and secrets. The module developer could initialize a context called
-`GitHub` as part of the loading section in the module code. All module configuration could be stored in this context by using the functionality in
-this module. The context for the module is stored in the `SecretVault` as a secret with the name `Context:GitHub`.
+Let's say we have a module called `GitHub` that needs to store some settings. The module developer could initialize a `Context` called
+`GitHub` as part of the loading section in the module code. All module configuration could be stored in this `Context` by using the functionality in
+this module. The context for the module is stored in the `ContextVault` as a `Context` with the ID `GitHub`.
 
 ### User Configuration
 
-To store user data, the module developer can create a new context that defines a "namespace" for the user configuration. So let's say a developer has
+To store user data, the module developer can create a new `Context` that defines a "namespace" for the user configuration. So let's say a developer has
 implemented this for the `GitHub` module, a user would log in using their details. The module would call upon `Context` functionality to create a new
-context under the `GitHub` namespace.
+`Context` under the `GitHub` namespace.
 
-Imagine a user called `BobMarley` logs in to the `GitHub` module. The following would exist in the context:
+Imagine a user called `BobMarley` logs in to the `GitHub` module. The following would exist in the `ContextVault`:
 
-- `Context:GitHub` containing module configuration, like default user, host, and client ID to use if not otherwise specified.
-- `Context:GitHub/BobMarley` containing user configuration, details about the user, secrets and default values for API calls etc.
+- `GitHub` containing module configuration, like default user, host, and client ID to use if not otherwise specified.
+- `GitHub/BobMarley` containing user configuration, details about the user, secrets and default values for API calls etc.
 
-Let's say the person also has another account on `GitHub` called `RastaBlasta`. After logging on with the second account, the following context would
-also exist in the context:
+Let's say the person also has another account on `GitHub` called `LennyKravitz`. After logging on the second account, the following `Context` would
+also exist in the `ContextVault`:
 
-- `Context:GitHub/RastaBlasta` containing user configuration, details about the user, secrets and default values for API calls etc.
+- `GitHub/LennyKravitz` containing user configuration, details about the user, secrets and default values for API calls etc.
 
-With this the module developer could allow users to set default context, and store a key of the name of that context in the module context. This way
-the module could automatically log in the user to the correct account when the module is loaded. The user could also switch between accounts by
-changing the default context.
+With this the module developer could allow users to set default `Context`, and store a key of the name of that `Context` in the module `Context`. This
+way the module could automatically log in the user to the correct account when the module is loaded. The user could also switch between accounts by
+changing the default `Context`.
 
 ### Setup for a New Module
 
@@ -291,21 +288,21 @@ try {
 2. Add some module configuration -> `$context = Get-Context -ID 'GitHub'` -> Change settings using the returned object and
    then `Set-Context -ID 'GitHub' -Context $context` to store the changes.
 
-### Setup for a New Context
+### Setup for a New user context
 
 To set up a new context for a user, the following steps should be taken:
 
-1. Create a set of integration functions that you can expose to the user and that uses the `Context` module to store user data. Its highly recommended
-   to do this so that you as a module developer can create the structure you want for the context, while also giving the user the expected function
+1. Create a set of public integration functions that uses the `Context` module to store user data. Its highly recommended
+   to do this so that you as a module developer can create the structure you want for the `Context`, while also giving the user the expected function
    names to interact with the module.
    - `Set-<ModuleName>Context` that uses `Set-Context`.
    - `Get-<ModuleName>Context` that uses `Get-Context`.
    - `Remove-<ModuleName>Context` that uses `Remove-Context`
 
-2. Create a new context for the user -> `Set-Context -ID 'GitHub.BobMarley'` -> Context `GitHub/BobMarley` is created.
+2. Create a new `Context` for the user `Connect-GitHub ...` -> `Set-Context -ID 'GitHub.BobMarley'` -> `Context` `GitHub/BobMarley` is created.
 3. Add some user configuration -> `$context = Get-Context -ID 'GitHub.BobMarley'` -> Change settings using the returned object and
 then `Set-Context -ID 'GitHub.BobMarley' -Context $context` to store the changes.
-4. Get the user configuration -> `Get-Context -Context 'GitHub/BobMarley'` -> The context object is returned, and you can access the data in it.
+4. Get the user configuration -> `Get-Context -Context 'GitHub/BobMarley'` -> The `Context` object is returned, and you can access the data in it.
 
 ## Contributing
 
@@ -323,6 +320,4 @@ If you do code, we'd love to have your contributions. Please read the [Contribut
 
 ## Links
 
-- SecretManagement | [GitHub](https://GitHub.com/powershell/SecretManagement) | [Docs](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.secretmanagement/?view=ps-modules)
-- SecretStore | [GitHub](https://GitHub.com/PowerShell/SecretStore) | [Docs](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.secretstore/?view=ps-modules)
-- [Overview of the SecretManagement and SecretStore modules | Microsoft Learn](https://learn.microsoft.com/en-us/powershell/utility-modules/secretmanagement/overview?view=ps-modules)
+- Sodium [GitHub](https://github.com/someuser/Sodium) | [PSGallery](https://www.powershellgallery.com/packages/Sodium)
@@ -1,17 +1,35 @@
-#Requires -Modules @{ ModuleName = 'Microsoft.PowerShell.SecretManagement'; RequiredVersion = '1.1.2' }
+#Requires -Modules @{ ModuleName = 'Sodium'; RequiredVersion = '2.1.1' }
 
 filter Import-Context {
     <#
         .SYNOPSIS
         Imports the context vault into memory.
 
         .DESCRIPTION
-        Imports the context vault into memory.
+        Imports all context files from the context vault directory into memory.
+        Each context is decrypted using the configured private key and stored
+        in the script-wide context collection for further use.
 
         .EXAMPLE
         Import-Context
 
+        Output:
+        ```powershell
+        VERBOSE: Importing contexts from vault: [C:\Vault]
+        VERBOSE: Found [3] contexts
+        VERBOSE: Importing context: [123456]
+        ```
+
         Imports all contexts from the context vault into memory.
+
+        .OUTPUTS
+        [pscustomobject].
+
+        .NOTES
+        Represents the imported context object containing ID, Path, and Context properties.
+
+        .LINK
+        https://psmodule.io/Sodium/Functions/Import-Context/
     #>
     [OutputType([object])]
     [CmdletBinding()]
@@ -27,15 +45,25 @@ filter Import-Context {
 
     process {
         try {
-            Write-Verbose "Importing contexts: [$($script:Config.SecretPrefix)*] from vault: $($script:Config.VaultName)"
-            $secretInfos = Get-SecretInfo -Name "$($script:Config.SecretPrefix)*" -Vault $script:Config.VaultName -Verbose:$false
-            Write-Verbose "Found [$($secretInfos.Count)] secrets"
-            $secretInfos | ForEach-Object {
-                Write-Verbose "- [$($_.Name)]"
-                $secretJson = $_ | Get-Secret -AsPlainText -Verbose:$false
-                $script:Contexts[$_.Name] = ConvertFrom-ContextJson -JsonString $secretJson
+            Write-Verbose "Importing contexts from vault: [$($script:Config.VaultPath)]"
+            $contextFiles = Get-ChildItem -Path $script:Config.VaultPath -Filter *.json -File -Recurse
+            Write-Verbose "Found [$($contextFiles.Count)] contexts"
+            $contextFiles | ForEach-Object {
+                $contextInfo = Get-Content -Path $_.FullName | ConvertFrom-Json
+                Write-Verbose "Importing context: [$($contextInfo.ID)]"
+                Write-Verbose ($contextInfo | Format-List | Out-String)
+                $params = @{
+                    SealedBox  = $contextInfo.Context
+                    PublicKey  = $script:Config.PublicKey
+                    PrivateKey = $script:Config.PrivateKey
+                }
+                $context = ConvertFrom-SodiumSealedBox @params
+                $script:Contexts[$contextInfo.ID] = [pscustomobject]@{
+                    ID      = $contextInfo.ID
+                    Path    = $contextInfo.Path
+                    Context = ConvertFrom-ContextJson -JsonString $context
+                }
             }
-
         } catch {
             Write-Error $_
             throw 'Failed to get context'
 
@@ -1,12 +1,13 @@
 function Convert-ContextHashtableToObjectRecursive {
     <#
         .SYNOPSIS
-        Converts a hashtable to a context object.
+        Converts a hashtable into a structured 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.
+        This function recursively converts a hashtable into a structured PowerShell object.
+        String values prefixed with '[SECURESTRING]' are converted back to SecureString objects.
+        Other values retain their original data types, including integers, booleans, strings, arrays,
+        and nested objects.
 
         .EXAMPLE
         Convert-ContextHashtableToObjectRecursive -Hashtable @{
@@ -18,17 +19,38 @@
             }
         }
 
-        This example converts a hashtable to a context object, where the 'Token' and 'Nested.Token' values are SecureString objects.
+        Output:
+        ```powershell
+        Name   : Test
+        Token  : System.Security.SecureString
+        Nested : @{ Name = Nested; Token = System.Security.SecureString }
+        ```
+
+        This example converts a hashtable into a structured object, where 'Token' and 'Nested.Token'
+        values are SecureString objects.
+
+        .OUTPUTS
+        PSCustomObject.
+
+        .NOTES
+        Returns an object where values are converted to their respective types,
+        including SecureString for sensitive values, arrays for list structures, and nested objects
+        for hashtables.
+
+        .LINK
+        https://psmodule.io/Context/Functions/Convert-ContextHashtableToObjectRecursive
     #>
+
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSAvoidUsingConvertToSecureStringWithPlainText', '',
-        Justification = 'The securestring is read from the object this function reads.'
+        Justification = 'The SecureString is extracted from the object being processed by this function.'
     )]
     [OutputType([pscustomobject])]
     [CmdletBinding()]
     param (
-        # Hashtable to convert to context object
-        [object] $Hashtable
+        # Hashtable to convert into a structured context object
+        [Parameter(Mandatory)]
+        [hashtable] $Hashtable
     )
 
     begin {
@@ -53,7 +75,7 @@
                     Write-Debug "Converting [$key] as [hashtable]"
                     $result | Add-Member -NotePropertyName $key -NotePropertyValue (Convert-ContextHashtableToObjectRecursive $value)
                 } elseif ($value -is [array]) {
-                    Write-Debug "Converting [$key] as [IEnumerable], including arrays and hashtables"
+                    Write-Debug "Converting [$key] as [array], processing elements individually"
                     $result | Add-Member -NotePropertyName $key -NotePropertyValue @(
                         $value | ForEach-Object {
                             if ($_ -is [hashtable]) {
@@ -64,7 +86,7 @@
                         }
                     )
                 } else {
-                    Write-Debug "Converting [$key] as regular value"
+                    Write-Debug "Adding [$key] as a standard value"
                     $result | Add-Member -NotePropertyName $key -NotePropertyValue $value
                 }
             }