Context.psm1
|
[Diagnostics.CodeAnalysis.SuppressMessageAttribute( 'PSAvoidAssignmentToAutomaticVariable', 'IsWindows', Justification = 'IsWindows doesnt exist in PS5.1' )] [Diagnostics.CodeAnalysis.SuppressMessageAttribute( 'PSUseDeclaredVarsMoreThanAssignments', 'IsWindows', Justification = 'IsWindows doesnt exist in PS5.1' )] [CmdletBinding()] param() $baseName = [System.IO.Path]::GetFileNameWithoutExtension($PSCommandPath) $script:PSModuleInfo = Import-PowerShellDataFile -Path "$PSScriptRoot\$baseName.psd1" $script:PSModuleInfo | Format-List | Out-String -Stream | ForEach-Object { Write-Debug $_ } $scriptName = $script:PSModuleInfo.Name Write-Debug "[$scriptName] - Importing module" if ($PSEdition -eq 'Desktop') { $IsWindows = $true } #region [functions] - [private] Write-Debug "[$scriptName] - [functions] - [private] - Processing folder" #region [functions] - [private] - [Set-ContextVault] Write-Debug "[$scriptName] - [functions] - [private] - [Set-ContextVault] - Importing" #Requires -Modules @{ ModuleName = 'Sodium'; RequiredVersion = '2.2.0' } function Set-ContextVault { <# .SYNOPSIS Sets the context vault. .DESCRIPTION Sets the context vault. If the vault does not exist, it will be initialized. Once the context vault is set, the keys will be prepared for use. The vault consists of multiple security shards, including a machine-specific shard, a user-specific shard, and a seed shard stored within the vault directory. .EXAMPLE Set-ContextVault Initializes or loads the context vault, setting up necessary key pairs. .OUTPUTS None. .NOTES This function modifies the script-scoped configuration and prepares the vault for use. .LINK https://psmodule.io/Context/Functions/Set-ContextVault #> [CmdletBinding(SupportsShouldProcess)] param() begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" } process { try { Write-Verbose "Loading context vault from [$($script:Config.VaultPath)]" $vaultExists = Test-Path $script:Config.VaultPath Write-Verbose "Vault exists: $vaultExists" if (-not $vaultExists) { Write-Verbose 'Initializing new vault' $null = New-Item -Path $script:Config.VaultPath -ItemType Directory } Write-Verbose 'Checking for existing seed shard' $seedShardPath = Join-Path -Path $script:Config.VaultPath -ChildPath $script:Config.SeedShardPath $seedShardExists = Test-Path $seedShardPath Write-Verbose "Seed shard exists: $seedShardExists" if (-not $seedShardExists) { Write-Verbose 'Creating new seed shard' $keys = New-SodiumKeyPair Set-Content -Path $seedShardPath -Value "$($keys.PrivateKey)$($keys.PublicKey)" } $seedShard = Get-Content -Path $seedShardPath $machineShard = [System.Environment]::MachineName $userShard = [System.Environment]::UserName #$userInputShard = Read-Host -Prompt 'Enter a seed shard' # Eventually 4 shards. +1 for user input. $seed = $machineShard + $userShard + $seedShard # + $userInputShard $keys = New-SodiumKeyPair -Seed $seed $script:Config.PrivateKey = $keys.PrivateKey $script:Config.PublicKey = $keys.PublicKey Write-Verbose 'Vault initialized' $script:Config.Initialized = $true } catch { Write-Error $_ throw 'Failed to initialize context vault' } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [private] - [Set-ContextVault] - Done" #endregion [functions] - [private] - [Set-ContextVault] #region [functions] - [private] - [JsonToObject] Write-Debug "[$scriptName] - [functions] - [private] - [JsonToObject] - Processing folder" #region [functions] - [private] - [JsonToObject] - [Convert-ContextHashtableToObjectRecursive] Write-Debug "[$scriptName] - [functions] - [private] - [JsonToObject] - [Convert-ContextHashtableToObjectRecursive] - Importing" function Convert-ContextHashtableToObjectRecursive { <# .SYNOPSIS Converts a hashtable into a structured context object. .DESCRIPTION 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 @{ Name = 'Test' Token = '[SECURESTRING]TestToken' Nested = @{ Name = 'Nested' Token = '[SECURESTRING]NestedToken' } } 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 extracted from the object being processed by this function.' )] [OutputType([pscustomobject])] [CmdletBinding()] param ( # Hashtable to convert into a structured context object [Parameter(Mandatory)] [hashtable] $Hashtable ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" } process { try { $result = [pscustomobject]@{} foreach ($key in $Hashtable.Keys) { $value = $Hashtable[$key] Write-Debug "Processing [$key]" Write-Debug "Value: $value" Write-Debug "Type: $($value.GetType().Name)" 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 [hashtable]) { Write-Debug "Converting [$key] as [hashtable]" $result | Add-Member -NotePropertyName $key -NotePropertyValue (Convert-ContextHashtableToObjectRecursive $value) } elseif ($value -is [array]) { Write-Debug "Converting [$key] as [array], processing elements individually" $result | Add-Member -NotePropertyName $key -NotePropertyValue @( $value | ForEach-Object { if ($_ -is [hashtable]) { Convert-ContextHashtableToObjectRecursive $_ } else { $_ } } ) } else { Write-Debug "Adding [$key] as a standard value" $result | Add-Member -NotePropertyName $key -NotePropertyValue $value } } return $result } catch { Write-Error $_ throw 'Failed to convert hashtable to object' } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [private] - [JsonToObject] - [Convert-ContextHashtableToObjectRecursive] - Done" #endregion [functions] - [private] - [JsonToObject] - [Convert-ContextHashtableToObjectRecursive] #region [functions] - [private] - [JsonToObject] - [ConvertFrom-ContextJson] Write-Debug "[$scriptName] - [functions] - [private] - [JsonToObject] - [ConvertFrom-ContextJson] - Importing" function ConvertFrom-ContextJson { <# .SYNOPSIS Converts a JSON string to a context object. .DESCRIPTION Converts a JSON string to a context object. Text prefixed with `[SECURESTRING]` is converted to SecureString objects. Other values are converted to their original types, such as integers, booleans, strings, arrays, and nested objects. .EXAMPLE $content = @' { "Name": "Test", "Token": "[SECURESTRING]TestToken", "Nested": { "Name": "Nested", "Token": "[SECURESTRING]NestedToken" } } '@ ConvertFrom-ContextJson -JsonString $content Output: ```powershell Name : Test Token : System.Security.SecureString Nested : @{Name=Nested; Token=System.Security.SecureString} ``` Converts a JSON string to a context object, ensuring 'Token' and 'Nested.Token' values are SecureString objects. .OUTPUTS [pscustomobject]. .NOTES Returns a PowerShell custom object with SecureString conversion applied where necessary. .LINK https://psmodule.io/Context/Functions/ConvertFrom-ContextJson/ #> [OutputType([pscustomobject])] [CmdletBinding()] param ( # JSON string to convert to context object [Parameter()] [string] $JsonString = '{}' ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" } process { try { $hashtableObject = $JsonString | ConvertFrom-Json -Depth 100 -AsHashtable return Convert-ContextHashtableToObjectRecursive $hashtableObject } catch { Write-Error $_ throw 'Failed to convert JSON to object' } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [private] - [JsonToObject] - [ConvertFrom-ContextJson] - Done" #endregion [functions] - [private] - [JsonToObject] - [ConvertFrom-ContextJson] Write-Debug "[$scriptName] - [functions] - [private] - [JsonToObject] - Done" #endregion [functions] - [private] - [JsonToObject] #region [functions] - [private] - [ObjectToJson] Write-Debug "[$scriptName] - [functions] - [private] - [ObjectToJson] - Processing folder" #region [functions] - [private] - [ObjectToJson] - [Convert-ContextObjectToHashtableRecursive] Write-Debug "[$scriptName] - [functions] - [private] - [ObjectToJson] - [Convert-ContextObjectToHashtableRecursive] - Importing" 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 } }) Output: ```powershell Name : MySecret AccessToken : [SECURESTRING]123123123 Nested : @{Name=MyNestedSecret; NestedAccessToken=[SECURESTRING]123123123} ``` Converts the context object to a hashtable. Secure strings are converted to a string representation. .OUTPUTS hashtable. .NOTES Returns a hashtable representation of the input object. Secure strings are converted to prefixed string values. .LINK https://psmodule.io/Context/Functions/Convert-ContextObjectToHashtableRecursive #> [OutputType([hashtable])] [CmdletBinding()] param ( # The object to convert. [Parameter()] [object] $Object = @{} ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" } process { try { $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) { $name = $property.Name $value = $property.Value Write-Debug "Processing [$name]" Write-Debug "Value: $value" Write-Debug "Type: $($value.GetType().Name)" 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 [psobject] -or $value -is [PSCustomObject] -or $value -is [hashtable]) { Write-Debug '- as PSObject, PSCustomObject or hashtable' $result[$property.Name] = Convert-ContextObjectToHashtableRecursive $value } elseif ($value -is [System.Collections.IEnumerable]) { Write-Debug '- as IEnumerable, including arrays and hashtables' $result[$property.Name] = @( $value | ForEach-Object { Convert-ContextObjectToHashtableRecursive $_ } ) } else { Write-Debug '- as regular value' $result[$property.Name] = $value } } return $result } catch { Write-Error $_ throw 'Failed to convert context object to hashtable' } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [private] - [ObjectToJson] - [Convert-ContextObjectToHashtableRecursive] - Done" #endregion [functions] - [private] - [ObjectToJson] - [Convert-ContextObjectToHashtableRecursive] #region [functions] - [private] - [ObjectToJson] - [ConvertTo-ContextJson] Write-Debug "[$scriptName] - [functions] - [private] - [ObjectToJson] - [ConvertTo-ContextJson] - Importing" function ConvertTo-ContextJson { <# .SYNOPSIS Converts an object into a JSON string. .DESCRIPTION Converts objects or hashtables into a JSON string. SecureStrings are converted to plain text strings and prefixed with `[SECURESTRING]`. The conversion is recursive for any nested objects. The function allows converting back using `ConvertFrom-ContextJson`. .EXAMPLE ConvertTo-ContextJson -Context ([pscustomobject]@{ Name = 'MySecret' AccessToken = '123123123' | ConvertTo-SecureString -AsPlainText -Force }) -ID 'CTX-001' Output: ```json { "Name": "MySecret", "AccessToken": "[SECURESTRING]123123123", "ID": "CTX-001" } ``` Converts the given object into a JSON string, ensuring SecureStrings are handled properly. .OUTPUTS System.String. .NOTES A JSON string representation of the provided object, including secure string transformations. .LINK https://psmodule.io/Context/Functions/ConvertTo-ContextJson #> [OutputType([string])] [CmdletBinding()] param ( # The object to convert to a Context JSON string. [Parameter()] [object] $Context = @{}, # The ID of the context. [Parameter(Mandatory)] [string] $ID ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" } process { try { $processedObject = Convert-ContextObjectToHashtableRecursive $Context $processedObject['ID'] = $ID return ($processedObject | ConvertTo-Json -Depth 100 -Compress) } catch { Write-Error $_ throw 'Failed to convert object to JSON' } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [private] - [ObjectToJson] - [ConvertTo-ContextJson] - Done" #endregion [functions] - [private] - [ObjectToJson] - [ConvertTo-ContextJson] Write-Debug "[$scriptName] - [functions] - [private] - [ObjectToJson] - Done" #endregion [functions] - [private] - [ObjectToJson] #region [functions] - [private] - [Utilities] Write-Debug "[$scriptName] - [functions] - [private] - [Utilities] - Processing folder" #region [functions] - [private] - [Utilities] - [PowerShell] Write-Debug "[$scriptName] - [functions] - [private] - [Utilities] - [PowerShell] - Processing folder" #region [functions] - [private] - [Utilities] - [PowerShell] - [Get-PSCallStackPath] Write-Debug "[$scriptName] - [functions] - [private] - [Utilities] - [PowerShell] - [Get-PSCallStackPath] - Importing" function Get-PSCallStackPath { <# .SYNOPSIS Creates a string representation of the current call stack. .DESCRIPTION This function generates a string representation of the current call stack. It allows skipping the first and last elements of the call stack using the `SkipFirst` and `SkipLatest` parameters. By default, it skips the first function (typically `<ScriptBlock>`) and the last function (`Get-PSCallStackPath`) to present a cleaner view of the actual call stack. .EXAMPLE Get-PSCallStackPath Output: ```powershell First-Function\Second-Function\Third-Function ``` Returns the call stack with the first (`<ScriptBlock>`) and last (`Get-PSCallStackPath`) functions removed. .EXAMPLE Get-PSCallStackPath -SkipFirst 0 Output: ```powershell <ScriptBlock>\First-Function\Second-Function\Third-Function ``` Includes the first function (typically `<ScriptBlock>`) in the call stack output. .EXAMPLE Get-PSCallStackPath -SkipLatest 0 Output: ```powershell First-Function\Second-Function\Third-Function\Get-PSCallStackPath ``` Includes the last function (`Get-PSCallStackPath`) in the call stack output. .OUTPUTS System.String. .NOTES A string representing the call stack path, with function names separated by backslashes. .LINK https://psmodule.io/PSCallStack/Functions/Get-PSCallStackPath/ #> [CmdletBinding()] param( # The number of functions to skip from the last function called. # The last function in the stack is this function (`Get-PSCallStackPath`). [Parameter()] [int] $SkipLatest = 1, # The number of functions to skip from the first function called. # The first function is typically `<ScriptBlock>`. [Parameter()] [int] $SkipFirst = 1 ) $skipFirst++ $cmds = (Get-PSCallStack).Command $functionPath = $cmds[($cmds.Count - $skipFirst)..$SkipLatest] -join '\' $functionPath = $functionPath -replace '^.*<ScriptBlock>\\' $functionPath = $functionPath -replace '^.*.ps1\\' return $functionPath } Write-Debug "[$scriptName] - [functions] - [private] - [Utilities] - [PowerShell] - [Get-PSCallStackPath] - Done" #endregion [functions] - [private] - [Utilities] - [PowerShell] - [Get-PSCallStackPath] Write-Debug "[$scriptName] - [functions] - [private] - [Utilities] - [PowerShell] - Done" #endregion [functions] - [private] - [Utilities] - [PowerShell] Write-Debug "[$scriptName] - [functions] - [private] - [Utilities] - Done" #endregion [functions] - [private] - [Utilities] Write-Debug "[$scriptName] - [functions] - [private] - Done" #endregion [functions] - [private] #region [functions] - [public] Write-Debug "[$scriptName] - [functions] - [public] - Processing folder" #region [functions] - [public] - [Get-Context] Write-Debug "[$scriptName] - [functions] - [public] - [Get-Context] - Importing" #Requires -Modules @{ ModuleName = 'Sodium'; RequiredVersion = '2.2.0' } function Get-Context { <# .SYNOPSIS Retrieves a context from the context vault. .DESCRIPTION Retrieves a context by reading and decrypting context files directly from the vault directory. If no ID is specified, all available contexts will be returned. Wildcards are supported to match multiple contexts. .EXAMPLE Get-Context Output: ```powershell Repositories : {@{Languages=System.Object[]; IsPrivate=False; Stars=130; CreatedDate=2/9/2024 10:45:11 AM; Name=Repo2}} AccessScopes : {repo, user, gist, admin:org} AuthToken : MyFirstSuperSecretToken TwoFactorMethods : {TOTP, SMS} IsTwoFactorAuth : True ApiRateLimits : @{ResetTime=2/9/2025 11:15:11 AM; Remaining=4985; Limit=5000} UserPreferences : @{CodeReview=System.Object[]; Notifications=; Theme=dark; DefaultBranch=main} SessionMetaData : @{Device=Windows-PC; Location=; BrowserInfo=; SessionID=sess_abc123} LastLoginAttempts : {@{Success=True; Timestamp=2/9/2025 9:45:11 AM; IP=192.168.1.101}, @{Success=False}} ID : GitHub/User-3 Username : john_doe LoginTime : 2/9/2025 10:45:11 AM Repositories : {@{Languages=System.Object[]; IsPrivate=False; Stars=130; CreatedDate=2/9/2024 10:45:11 AM; Name=Repo2}} AccessScopes : {repo, user, gist, admin:org} AuthToken : MySuperSecretToken TwoFactorMethods : {TOTP, SMS} IsTwoFactorAuth : True ApiRateLimits : @{ResetTime=2/9/2025 11:15:11 AM; Remaining=4985; Limit=5000} UserPreferences : @{CodeReview=System.Object[]; Notifications=; Theme=dark; DefaultBranch=main} SessionMetaData : @{Device=Windows-PC; Location=; BrowserInfo=; SessionID=sess_abc123} LastLoginAttempts : {@{Success=True; Timestamp=2/9/2025 9:45:11 AM; IP=192.168.1.101}, @{Success=False}} ID : GitHub/User-8 Username : jane_doe LoginTime : 2/9/2025 10:45:11 AM ``` Retrieves all contexts from the context vault (directly from disk). .EXAMPLE Get-Context -ID 'MySecret' Retrieves the context called 'MySecret' from the vault. .EXAMPLE 'My*' | Get-Context Output: ```powershell ID : MyConfig Config : {ConfigKey=ConfigValue} ID : MySecret Key : EncryptedValue AuthToken : EncryptedToken Favorite : {Color=Blue; Number=7} ID : MySettings Setting : {SettingKey=SettingValue} Config : {ConfigKey=ConfigValue} YourData : {DataKey=DataValue} ``` Retrieves all contexts that start with 'My' from the context vault (directly from disk). .OUTPUTS [System.Object] .NOTES Returns a list of contexts matching the specified ID or all contexts if no ID is specified. Each context object contains its ID and corresponding stored properties. .LINK https://psmodule.io/Context/Functions/Get-Context/ #> [OutputType([object])] [CmdletBinding()] param( # The name of the context to retrieve from the vault. Supports wildcards. [Parameter( ValueFromPipeline, ValueFromPipelineByPropertyName )] [AllowEmptyString()] [SupportsWildcards()] [string[]] $ID = '*' ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" if (-not $script:Config.Initialized) { Set-ContextVault } } process { Write-Verbose "Retrieving contexts - ID: [$($ID -join ', ')]" foreach ($item in $ID) { Write-Verbose "Retrieving contexts - ID: [$item]" # Read context files directly from disk instead of using in-memory cache $contextFiles = Get-ChildItem -Path $script:Config.VaultPath -Filter *.json -File -Recurse foreach ($file in $contextFiles) { try { $contextInfo = Get-Content -Path $file.FullName | ConvertFrom-Json if ($contextInfo.ID -like $item) { # Decrypt and return the context $params = @{ SealedBox = $contextInfo.Context PublicKey = $script:Config.PublicKey PrivateKey = $script:Config.PrivateKey } $contextObj = ConvertFrom-SodiumSealedBox @params ConvertFrom-ContextJson -JsonString $contextObj } } catch { Write-Warning "Failed to read or decrypt context file: $($file.FullName). Error: $_" } } } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [public] - [Get-Context] - Done" #endregion [functions] - [public] - [Get-Context] #region [functions] - [public] - [Get-ContextInfo] Write-Debug "[$scriptName] - [functions] - [public] - [Get-ContextInfo] - Importing" function Get-ContextInfo { <# .SYNOPSIS Retrieves info about a context from the context vault. .DESCRIPTION Retrieves info about context files directly from the vault directory on disk. If no ID is specified, all available info on contexts will be returned. Wildcards are supported to match multiple contexts. Only metadata (ID and Path) is returned without decrypting the context contents. .EXAMPLE Get-ContextInfo Output: ```powershell ID : MySettings Path : ...\b7c01dbe-bccd-4c7e-b075-c5aac1c43b1a.json ID : MyConfig Path : ...\feacc853-5bea-48d1-b751-41ce9768d48e.json ID : MySecret Path : ...\3e223259-f242-4e97-91c8-f0fd054cfea7.json ID : Data Path : ...\b7c01dbe-bccd-4c7e-b075-c5aac1c43b1a.json ID : PSModule.GitHub Path : ...\feacc853-5bea-48d1-b751-41ce9768d48e.json ``` Retrieves all contexts from the context vault (directly from disk). .EXAMPLE Get-ContextInfo -ID 'MySecret' Output: ```powershell ID : MySecret Path : ...\3e223259-f242-4e97-91c8-f0fd054cfea7.json ``` Retrieves the context called 'MySecret' from the context vault (directly from disk). .EXAMPLE 'My*' | Get-ContextInfo Output: ```powershell ID : MyConfig Path : .../feacc853-5bea-48d1-b751-41ce9768d48e.json ID : MySecret Path : .../3e223259-f242-4e97-91c8-f0fd054cfea7.json ID : MySettings Path : .../b7c01dbe-bccd-4c7e-b075-c5aac1c43b1a.json ``` Retrieves all contexts that start with 'My' from the context vault (directly from disk). .OUTPUTS [System.Object] .NOTES Returns a list of context information matching the specified ID or all contexts if no ID is specified. Each context object contains its ID and corresponding path to where the context is stored on disk. .LINK https://psmodule.io/Context/Functions/Get-ContextInfo/ #> [OutputType([object])] [CmdletBinding()] param( # The name of the context to retrieve from the vault. Supports wildcards. [Parameter( ValueFromPipeline, ValueFromPipelineByPropertyName )] [AllowEmptyString()] [SupportsWildcards()] [string[]] $ID = '*' ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" if (-not $script:Config.Initialized) { Set-ContextVault } } process { Write-Verbose "Retrieving context info - ID: [$ID]" foreach ($item in $ID) { # Read context files directly from disk instead of using in-memory cache $contextFiles = Get-ChildItem -Path $script:Config.VaultPath -Filter *.json -File -Recurse foreach ($file in $contextFiles) { try { $contextInfo = Get-Content -Path $file.FullName | ConvertFrom-Json if ($contextInfo.ID -like $item) { # Return only metadata (ID and Path), don't decrypt the Context property [PSCustomObject]@{ ID = $contextInfo.ID Path = $contextInfo.Path } } } catch { Write-Warning "Failed to read context file: $($file.FullName). Error: $_" } } } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [public] - [Get-ContextInfo] - Done" #endregion [functions] - [public] - [Get-ContextInfo] #region [functions] - [public] - [Remove-Context] Write-Debug "[$scriptName] - [functions] - [public] - [Remove-Context] - Importing" function Remove-Context { <# .SYNOPSIS Removes a context from the context vault. .DESCRIPTION This function removes a context (or multiple contexts) from the vault. It supports: - Supply one or more IDs as strings (e.g. -ID 'Ctx1','Ctx2') - Supply objects that contain an ID property The function accepts pipeline input for easier batch removal. .EXAMPLE Remove-Context -ID 'MySecret' Output: ```powershell Removing context [MySecret] Removed item: MySecret ``` Removes a context called 'MySecret' by specifying its ID. .EXAMPLE Remove-Context -ID 'Ctx1','Ctx2' Output: ```powershell Removing context [Ctx1] Removed item: Ctx1 Removing context [Ctx2] Removed item: Ctx2 ``` Removes two contexts, 'Ctx1' and 'Ctx2'. .EXAMPLE 'Ctx1','Ctx2' | Remove-Context Output: ```powershell Removing context [Ctx1] Removed item: Ctx1 Removing context [Ctx2] Removed item: Ctx2 ``` Removes two contexts, 'Ctx1' and 'Ctx2' via pipeline input. .EXAMPLE $ctxList = @( [PSCustomObject]@{ ID = 'Ctx1' }, [PSCustomObject]@{ ID = 'Ctx2' } ) $ctxList | Remove-Context Output: ```powershell Removing context [Ctx1] Removed item: Ctx1 Removing context [Ctx2] Removed item: Ctx2 ``` Accepts pipeline input: multiple objects each having an ID property. .OUTPUTS [System.String] .NOTES Returns the name of each removed context if successful. .LINK https://psmodule.io/Context/Functions/Remove-Context/ #> [CmdletBinding(SupportsShouldProcess)] param( # One or more IDs as strings of the contexts to remove. [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )] [SupportsWildcards()] [string[]] $ID ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Begin" if (-not $script:Config.Initialized) { Set-ContextVault } } process { foreach ($item in $ID) { Write-Verbose "Processing ID [$item]" # Find contexts by scanning disk files instead of using in-memory cache $contextFiles = Get-ChildItem -Path $script:Config.VaultPath -Filter *.json -File -Recurse foreach ($file in $contextFiles) { try { $contextInfo = Get-Content -Path $file.FullName | ConvertFrom-Json if ($contextInfo.ID -like $item) { Write-Verbose "Removing context [$($contextInfo.ID)]" if ($PSCmdlet.ShouldProcess($contextInfo.ID, 'Remove secret')) { $file.FullName | Remove-Item -Force Write-Verbose "Removed context file: $($file.FullName)" } } } catch { Write-Warning "Failed to read context file: $($file.FullName). Error: $_" } } } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [public] - [Remove-Context] - Done" #endregion [functions] - [public] - [Remove-Context] #region [functions] - [public] - [Rename-Context] Write-Debug "[$scriptName] - [functions] - [public] - [Rename-Context] - Importing" function Rename-Context { <# .SYNOPSIS Renames a context. .DESCRIPTION This function renames a context by retrieving the existing context with the old ID, setting the new context with the provided new ID, and removing the old context. If a context with the new ID already exists, the operation will fail unless the `-Force` switch is specified. .EXAMPLE Rename-Context -ID 'PSModule.GitHub' -NewID 'PSModule.GitHub2' Output: ```powershell Context 'PSModule.GitHub' renamed to 'PSModule.GitHub2' ``` Renames the context 'PSModule.GitHub' to 'PSModule.GitHub2'. .EXAMPLE 'PSModule.GitHub' | Rename-Context -NewID 'PSModule.GitHub2' Output: ```powershell Context 'PSModule.GitHub' renamed to 'PSModule.GitHub2' ``` Renames the context 'PSModule.GitHub' to 'PSModule.GitHub2' using pipeline input. .OUTPUTS [System.String] .NOTES The confirmation message indicating the successful renaming of the context. .LINK https://psmodule.io/Context/Functions/Rename-Context/ #> [CmdletBinding(SupportsShouldProcess)] param ( # The ID of the context to rename. [Parameter( Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName )] [string] $ID, # The new ID of the context. [Parameter(Mandatory)] [string] $NewID, # Force the rename even if the new ID already exists. [Parameter()] [switch] $Force ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" if (-not $script:Config.Initialized) { Set-ContextVault } } process { $context = Get-Context -ID $ID if (-not $context) { throw "Context with ID '$ID' not found." } $existingContext = Get-Context -ID $NewID if ($existingContext -and -not $Force) { throw "Context with ID '$NewID' already exists." } if ($PSCmdlet.ShouldProcess("Renaming context '$ID' to '$NewID'")) { $context | Set-Context -ID $NewID Remove-Context -ID $ID } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [public] - [Rename-Context] - Done" #endregion [functions] - [public] - [Rename-Context] #region [functions] - [public] - [Set-Context] Write-Debug "[$scriptName] - [functions] - [public] - [Set-Context] - Importing" #Requires -Modules @{ ModuleName = 'Sodium'; RequiredVersion = '2.2.0' } function Set-Context { <# .SYNOPSIS Set a context and store it in the context vault. .DESCRIPTION If the context does not exist, it will be created. If it already exists, it will be updated. The context is securely stored on disk using encryption mechanisms. Each context operation reads the current state from disk to ensure consistency across processes. .EXAMPLE Set-Context -ID 'PSModule.GitHub' -Context @{ Name = 'MySecret' } Output: ```powershell ID : PSModule.GitHub Path : C:\Vault\Guid.json Context : @{ Name = 'MySecret' } ``` Creates a context called 'MySecret' in the vault. .EXAMPLE Set-Context -ID 'PSModule.GitHub' -Context @{ Name = 'MySecret'; AccessToken = '123123123' } Output: ```powershell ID : PSModule.GitHub Path : C:\Vault\Guid.json Context : @{ Name = 'MySecret'; AccessToken = '123123123' } ``` Creates a context called 'MySecret' in the vault with additional settings. .EXAMPLE $context = @{ ID = 'MySecret'; Name = 'SomeSecretIHave'; AccessToken = '123123123' } $context | Set-Context Sets a context using a hashtable object. .OUTPUTS [PSCustomObject] .NOTES Returns an object representing the stored or updated context. The object includes the ID, path, and securely stored context information. .LINK https://psmodule.io/Context/Functions/Set-Context/ #> [OutputType([object])] [CmdletBinding(SupportsShouldProcess)] param( # The ID of the context. [Parameter()] [string] $ID, # The data of the context. [Parameter(ValueFromPipeline)] [object] $Context = @{}, # Pass the context through the pipeline. [Parameter()] [switch] $PassThru ) begin { $stackPath = Get-PSCallStackPath Write-Debug "[$stackPath] - Start" if (-not $script:Config.Initialized) { Set-ContextVault } } process { if ($context -is [System.Collections.IDictionary]) { $Context = [PSCustomObject]$Context } if (-not $ID) { $ID = $Context.ID } if (-not $ID) { throw 'An ID is required, either as a parameter or as a property of the context object.' } $existingContextFile = $null # Check if context already exists by scanning disk files $contextFiles = Get-ChildItem -Path $script:Config.VaultPath -Filter *.json -File -Recurse foreach ($file in $contextFiles) { try { $contextInfo = Get-Content -Path $file.FullName | ConvertFrom-Json if ($contextInfo.ID -eq $ID) { $existingContextFile = $file $Path = $contextInfo.Path break } } catch { Write-Warning "Failed to read context file: $($file.FullName). Error: $_" } } if (-not $existingContextFile) { Write-Verbose "Context [$ID] not found in vault" $Guid = [Guid]::NewGuid().ToString() $Path = Join-Path -Path $script:Config.VaultPath -ChildPath "$Guid.json" } else { Write-Verbose "Context [$ID] found in vault" } $contextJson = ConvertTo-ContextJson -Context $Context -ID $ID $param = [pscustomobject]@{ ID = $ID Path = $Path Context = ConvertTo-SodiumSealedBox -Message $contextJson -PublicKey $script:Config.PublicKey } | ConvertTo-Json -Depth 5 Write-Debug ($param | ConvertTo-Json -Depth 5) if ($PSCmdlet.ShouldProcess($ID, 'Set context')) { Write-Verbose "Setting context [$ID] in vault" Set-Content -Path $Path -Value $param } if ($PassThru) { Get-Context -ID $ID } } end { Write-Debug "[$stackPath] - End" } } Write-Debug "[$scriptName] - [functions] - [public] - [Set-Context] - Done" #endregion [functions] - [public] - [Set-Context] Write-Debug "[$scriptName] - [functions] - [public] - Done" #endregion [functions] - [public] #region [variables] - [private] Write-Debug "[$scriptName] - [variables] - [private] - Processing folder" #region [variables] - [private] - [Config] Write-Debug "[$scriptName] - [variables] - [private] - [Config] - Importing" $script:Config = [pscustomobject]@{ Initialized = $false # Has the vault been initialized? VaultPath = Join-Path -Path $HOME -ChildPath '.contextvault' # Vault directory path SeedShardPath = 'vault.shard' # Seed shard path (relative to VaultPath) PrivateKey = $null # Private key (populated on init) PublicKey = $null # Public key (populated on init) } Write-Debug "[$scriptName] - [variables] - [private] - [Config] - Done" #endregion [variables] - [private] - [Config] Write-Debug "[$scriptName] - [variables] - [private] - Done" #endregion [variables] - [private] #region [completers] Write-Debug "[$scriptName] - [completers] - Importing" Register-ArgumentCompleter -CommandName ($script:PSModuleInfo.FunctionsToExport) -ParameterName 'ID' -ScriptBlock { param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter) $null = $commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter $contextInfos = Get-ContextInfo -ErrorAction SilentlyContinue -Verbose:$false -Debug:$false $contextInfos | Where-Object { $_.ID -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_.ID, $_.ID, 'ParameterValue', $_.ID) } } Write-Debug "[$scriptName] - [completers] - Done" #endregion [completers] #region [main] Write-Debug "[$scriptName] - [main] - Importing" Set-ContextVault Write-Debug "[$scriptName] - [main] - Done" #endregion [main] #region Member exporter $exports = @{ Alias = '*' Cmdlet = '' Function = @( 'Get-Context' 'Get-ContextInfo' 'Remove-Context' 'Rename-Context' 'Set-Context' ) Variable = '' } Export-ModuleMember @exports #endregion Member exporter |