Merge pull request #1303 from Badgerati/Issue-1250

Resolve a threading issue with secrets; Handle SecretStore vaults better with inbuilt defaults; Write documentation for SecretStore vaults

.github/workflows/ci-pwsh_preview.yml

@@ -44,7 +44,7 @@ jobs:
 
     - name: Run Pester Tests
       shell: pwsh
-      run: | 
+      run: |
         Invoke-Build Test
 
     - name: Test docker builds

docs/Tutorials/ImportingModules.md

@@ -9,7 +9,7 @@ The older [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) and
 
 ## Modules
 
-Modules in Pode can be imported in the normal manor using `Import-Module`. The [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) function can now be used inside and outside of [`Start-PodeServer`](../../Functions/Core/Start-PodeServer), and should be used if you're using local modules via `ps_modules`.
+Modules in Pode can be imported in the normal manner using `Import-Module`. The [`Import-PodeModule`](../../Functions/Utilities/Import-PodeModule) function can now be used inside and outside of [`Start-PodeServer`](../../Functions/Core/Start-PodeServer), and should be used if you're using local modules via `ps_modules`.
 
 ### Import via Path
 

docs/Tutorials/Routes/Utilities/RouteGrouping.md

@@ -60,7 +60,7 @@ Add-PodeRouteGroup -Path '/api' -Authentication Basic -Middleware $mid -Routes {
 
 ## Static Routes
 
-The Groups for Static Routes work in the same manor as normal Routes, but you'll need to use [`Add-PodeStaticRouteGroup`](../../../../Functions/Routes/Add-PodeStaticRouteGroup) instead:
+The Groups for Static Routes work in the same manner as normal Routes, but you'll need to use [`Add-PodeStaticRouteGroup`](../../../../Functions/Routes/Add-PodeStaticRouteGroup) instead:
 
 ```powershell
 Add-PodeStaticRouteGroup -Path '/assets' -Source './content/assets' -Routes {
@@ -73,7 +73,7 @@ This will create 2 Static Routes at `/assets/images` and `/assets/videos`, refer
 
 ## Signal Routes
 
-Groupings for Signal Routes also work in the same manor as normal Routes, but you'll need to use [`Add-PodeSignalRouteGroup`](../../../../Functions/Routes/Add-PodeSignalRouteGroup) instead:
+Groupings for Signal Routes also work in the same manner as normal Routes, but you'll need to use [`Add-PodeSignalRouteGroup`](../../../../Functions/Routes/Add-PodeSignalRouteGroup) instead:
 
 ```powershell
 Add-PodeSignalRoute -Path '/ws' -Routes {

docs/Tutorials/Schedules.md

@@ -37,7 +37,7 @@ Add-PodeSchedule -Name 'date' -Cron @('@minutely', '@hourly') -ScriptBlock {
 }
 ```
 
-Usually all schedules are created within the main `Start-PodeServer` scope, however it is possible to create adhoc schedules with routes/etc. If you create adhoc schedules in this manor, you might notice that they don't run; this is because the Runspace that schedules use to run won't have been configured. You can configure by using `-EnablePool` on [`Start-PodeServer`](../../Functions/Core/Start-PodeServer):
+Usually all schedules are created within the main `Start-PodeServer` scope, however it is possible to create adhoc schedules with routes/etc. If you create adhoc schedules in this manner, you might notice that they don't run; this is because the Runspace that schedules use to run won't have been configured. You can configure by using `-EnablePool` on [`Start-PodeServer`](../../Functions/Core/Start-PodeServer):
 
 ```powershell
 Start-PodeServer -EnablePool Schedules {
@@ -169,18 +169,18 @@ Invoke-PodeSchedule -Name 'date' -ArgumentList @{ Date = [DateTime]::Now }
 
 The following is the structure of the Schedule object internally, as well as the object that is returned from [`Get-PodeSchedule`](../../Functions/Schedules/Get-PodeSchedule):
 
-| Name | Type | Description |
-| ---- | ---- | ----------- |
-| Name | string | The name of the Schedule |
-| StartTime | datetime | The delayed start time of the Schedule |
-| EndTime | datetime | The end time of the Schedule |
-| Crons | hashtable[] | The cron expressions of the Schedule, but parsed into an internal format |
-| CronsRaw | string[] | The raw cron expressions that were supplied |
-| Limit | int | The number of times the Schedule should run - 0 if running infinitely |
-| Count | int | The number of times the Schedule has run |
-| LastTriggerTime | datetime | The datetime the Schedule was last triggered |
-| NextTriggerTime | datetime | The datetime the Schedule will next be triggered |
-| Script | scriptblock | The scriptblock of the Schedule |
-| Arguments | hashtable | The arguments supplied from ArgumentList |
-| OnStart | bool | Should the Schedule run once when the server is starting, or once the server has fully loaded |
-| Completed | bool | Has the Schedule completed all of its runs |
+| Name            | Type        | Description                                                                                   |
+| --------------- | ----------- | --------------------------------------------------------------------------------------------- |
+| Name            | string      | The name of the Schedule                                                                      |
+| StartTime       | datetime    | The delayed start time of the Schedule                                                        |
+| EndTime         | datetime    | The end time of the Schedule                                                                  |
+| Crons           | hashtable[] | The cron expressions of the Schedule, but parsed into an internal format                      |
+| CronsRaw        | string[]    | The raw cron expressions that were supplied                                                   |
+| Limit           | int         | The number of times the Schedule should run - 0 if running infinitely                         |
+| Count           | int         | The number of times the Schedule has run                                                      |
+| LastTriggerTime | datetime    | The datetime the Schedule was last triggered                                                  |
+| NextTriggerTime | datetime    | The datetime the Schedule will next be triggered                                              |
+| Script          | scriptblock | The scriptblock of the Schedule                                                               |
+| Arguments       | hashtable   | The arguments supplied from ArgumentList                                                      |
+| OnStart         | bool        | Should the Schedule run once when the server is starting, or once the server has fully loaded |
+| Completed       | bool        | Has the Schedule completed all of its runs                                                    |

docs/Tutorials/Secrets/Examples/SecretStore.md

@@ -0,0 +1,84 @@
+# SecretStore
+
+This page gives some brief details, and an example, of how to use the `Microsoft.PowerShell.SecretStore` PowerShell module secret vault provider.
+
+This is a locally stored secret vault.
+
+## Install
+
+Before using the `Microsoft.PowerShell.SecretStore` provider, you will first need to install the module:
+
+```powershell
+Install-Module Microsoft.PowerShell.SecretManagement, Microsoft.PowerShell.SecretStore
+```
+
+## Register
+
+When registering a new secret vault using `Microsoft.PowerShell.SecretStore`, via [`Register-PodeSecretVault`], the `-UnlockSecret` parameter is **mandatory**. This will be used to assign the required default password for the secret vault and to periodically unlock the vault.
+
+There are also some default values set for some parameters to make life a little easier, however, these can be overwritten if needed by directly supplying the parameter:
+
+| Parameter                            | Default    | Description                                                                                                                      |
+| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `UnlockInterval`                     | 1 minute   | Used to assign an unlock period, as well as the PasswordTimeout to auto-lock the vault                                           |
+| `VaultParameters['Authentication']`  | Password   | Used to tell the vault to to be locked/unlocked                                                                                  |
+| `VaultParameters['Interaction']`     | None       | Used to tell the vault where it should be interactive or not                                                                     |
+| `VaultParameters['PasswordTimeout']` | 70 seconds | Used to auto-lock the vault after being unlocked. The value if not supplied is based on the `-UnlockInterval` value + 10 seconds |
+
+For example:
+
+```powershell
+Register-PodeSecretVault `
+    -Name 'ExampleVault' `
+    -ModuleName 'Microsoft.PowerShell.SecretStore' `
+    -UnlockSecret 'Sup3rSecur3Pa$$word!'
+```
+
+## Secret Management
+
+Creating, updating, and using secrets are all done in the usual manner, as outlined in the [Overview](../../Overview):
+
+```powershell
+# set a secret in the local vault
+Set-PodeSecret -Key 'example' -Vault 'ExampleVault' -InputObject 'hello, world!'
+
+# mount the "example" secret from local vault, making it accessible via $secret:example
+Mount-PodeSecret -Name 'example' -Vault 'ExampleVault' -Key 'example'
+
+# use the secret in a route
+Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+    Write-PodeJsonResponse @{ Value = $secret:example }
+}
+```
+
+## Example
+
+The following is a smaller example of the example [found here](https://github.com/Badgerati/Pode/blob/develop/examples/web-secrets-local.ps1) and shows how to set up a server to register a local SecretStore vault, manage a secret within that vault, and return it via a Route.
+
+```powershell
+Start-PodeServer -Threads 2 {
+    Add-PodeEndpoint -Address * -Port 8080 -Protocol Http
+
+    # register the vault
+    Register-PodeSecretVault `
+        -Name 'ExampleVault' `
+        -ModuleName 'Microsoft.PowerShell.SecretStore' `
+        -UnlockSecret 'Sup3rSecur3Pa$$word!'
+
+    # set a secret in the local vault
+    Set-PodeSecret -Key 'example' -Vault 'ExampleVault' -InputObject 'hello, world!'
+
+    # mount the "example" secret from local vault, making it accessible via $secret:example
+    Mount-PodeSecret -Name 'example' -Vault 'ExampleVault' -Key 'example'
+
+    # retrieve the secret in a route
+    Add-PodeRoute -Method Get -Path '/' -ScriptBlock {
+        Write-PodeJsonResponse @{ Value = $secret:example }
+    }
+
+    # update the secret in a route
+    Add-PodeRoute -Method Post -Path '/' -ScriptBlock {
+        $secret:example = $WebEvent.Data.Value
+    }
+}
+```