Utils.cs

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

using System;
using System.Collections;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Globalization;
using System.IO;
using System.Management.Automation;
using System.Management.Automation.Language;
using System.Management.Automation.Runspaces;
using System.Security;

namespace Microsoft.PowerShell.SecretManagement
{
    #region Utils

    internal static class Utils
    {
        #region Members

        private const string NoVaultRegistered = @"
        There are currently no extension vaults registered.
        At least one vault must be registered before SecretManagement can add or retrieve secrets.
        You can download SecretManagement extension vault modules from PowerShellGallery.
        https://aka.ms/SecretManagementVaults
        ";

        private const string ImplementingExtension = "Extension";

        private const string ConvertJsonToHashtableScript = @"
            param (
                [string] $json
            )

            function ConvertToHash
            {
                param (
                    [pscustomobject] $object
                )

                $output = @{}
                $object | Microsoft.PowerShell.Utility\Get-Member -MemberType NoteProperty | ForEach-Object {
                    $name = $_.Name
                    $value = $object.($name)

                    if ($value -is [object[]])
                    {
                        $array = @()
                        $value | ForEach-Object {
                            $array += (ConvertToHash $_)
                        }
                        $output.($name) = $array
                    }
                    elseif ($value -is [pscustomobject])
                    {
                        $output.($name) = (ConvertToHash $value)
                    }
                    else
                    {
                        $output.($name) = $value
                    }
                }

                $output
            }

            $customObject = Microsoft.PowerShell.Utility\ConvertFrom-Json -InputObject $json
            return ConvertToHash $customObject
        ";

        #endregion

        #region Methods

        public static Hashtable ConvertJsonToHashtable(string json)
        {
            using (var ps = System.Management.Automation.PowerShell.Create(RunspaceMode.NewRunspace))
            {
                var results = PowerShellInvoker.InvokeScriptOnPowerShell<Hashtable>(
                    script: ConvertJsonToHashtableScript,
                    args: new object[] { json },
                    psToUse: ps,
                    error: out ErrorRecord _);

                return (results.Count > 0) ? results[0] : null;
            }
        }

        public static Hashtable ConvertDictToHashtable(IDictionary<string, object> dict)
        {
            var returnHashtable = new Hashtable();
            if (dict != null)
            {
                foreach (var item in dict)
                {
                    returnHashtable.Add(item.Key, item.Value);
                }
            }

            return returnHashtable;
        }

        public static string ConvertHashtableToJson(Hashtable hashtable)
        {
            var results = PowerShellInvoker.InvokeScript<string>(
                script: @"param ([hashtable] $hashtable) Microsoft.PowerShell.Utility\ConvertTo-Json -InputObject $hashtable -Depth 10",
                args: new object[] { hashtable },
                error: out ErrorRecord _);

            return (results.Count > 0) ? results[0] : null;
        }

        public static SecureString ConvertToSecureString(string secret)
        {
            var results = PowerShellInvoker.InvokeScript<SecureString>(
                script: @"param([string] $value) Microsoft.PowerShell.Security\ConvertTo-SecureString -String $value -AsPlainText -Force",
                args: new object[] { secret },
                error: out ErrorRecord _);

            return (results.Count > 0) ? results[0] : null;
        }

        public static string GetModuleExtensionName(string moduleName)
        {
            return string.Format(CultureInfo.InvariantCulture,
                @"{0}.{1}", moduleName, ImplementingExtension);
        }

        public static string TrimQuotes(string name)
        {
            return name.Trim('\'', '"');
        }

        public static string QuoteName(string name)
        {
            bool quotesNeeded = false;
            foreach (var c in name)
            {
                if (Char.IsWhiteSpace(c))
                {
                    quotesNeeded = true;
                    break;
                }
            }

            if (!quotesNeeded)
            {
                return name;
            }

            return "'" + CodeGeneration.EscapeSingleQuotedStringContent(name) + "'";
        }

        public static void CheckForRegisteredVaults(PSCmdlet cmdlet)
        {
            if (RegisteredVaultCache.VaultExtensions.Count == 0)
            {
                cmdlet.WriteWarning(NoVaultRegistered);
            }
        }

        #endregion
    }

    #endregion

    #region Enums

    /// <summary>
    /// Supported secret types
    /// </summary>
    public enum SecretType
    {
        /// <summary>
        /// Specifies the value is of an unknown type.
        /// </summary>
        Unknown = 0,

        /// <summary>
        /// Specifes the value is a <see cref="T:byte[]"/>.
        /// </summary>
        ByteArray,

        /// <summary>
        /// Specifes the value is a <see cref="T:string"/>.
        /// </summary>
        String,

        /// <summary>
        /// Specifes the value is a <see cref="System.Security.SecureString"/>.
        /// </summary>
        SecureString,

        /// <summary>
        /// Specifies the value is a <see cref="System.Management.Automation.PSCredential"/>.
        /// </summary>
        PSCredential,

        /// <summary>
        /// Specifes the value is a <see cref="System.Collections.Hashtable"/> .
        /// </summary>
        Hashtable,
    }

    #endregion

    #region Exceptions

    /// <summary>
    /// Represents errors that occur due to a password not being specified when required.
    /// </summary>
    public sealed class PasswordRequiredException : InvalidOperationException
    {
        #region Constructor

        /// <summary>
        /// Initializes a new instance of the <see cref="PasswordRequiredException" /> class.
        /// </summary>
        /// <param name="msg">The message that describes the error.</param>
        public PasswordRequiredException(string msg)
            : base(msg)
        {
        }

        #endregion
    }

    #endregion

    #region SecretInformation class

    /// <summary>
    /// Represents a secret from a secret vault.
    /// </summary>
    public sealed class SecretInformation
    {
        #region Properties

        /// <summary>
        /// Gets the name of the secret.
        /// </summary>
        public string Name
        {
            get;
        }

        /// <summary>
        /// Gets the object type of the secret.
        /// </summary>
        public SecretType Type
        {
            get;
        }

        /// <summary>
        /// Gets the vault name where the secret resides.
        /// </summary>
        public string VaultName
        {
            get;
        }

        /// <summary>
        /// Gets metadata of the secret.
        /// </summary>
        public ReadOnlyDictionary<string, object> Metadata
        {
            get;
        }

        #endregion

        #region Constructor

        /// <summary>
        /// Constructor
        /// </summary>
        public SecretInformation(
            string name,
            SecretType type,
            string vaultName)
        {
            Name = name;
            Type = type;
            VaultName = vaultName;
        }

        /// <summary>
        /// Constructor
        /// </summary>
        public SecretInformation(
            string name,
            SecretType type,
            string vaultName,
            ReadOnlyDictionary<string, object> metadata) : this(name, type, vaultName)
        {
            Metadata = metadata;
        }

        /// <summary>
        /// Constructor
        /// </summary>
        public SecretInformation(
            string name,
            SecretType type,
            string vaultName,
            Hashtable metadata) : this(name, type, vaultName)
        {
            if (metadata == null) { return; }

            Dictionary<string, object> metaDictionary = new Dictionary<string, object>(metadata.Count);
            foreach (var key in metadata.Keys)
            {
                metaDictionary.Add((string)key, metadata[key]);
            }
            Metadata = new ReadOnlyDictionary<string, object>(metaDictionary);
        }

        private SecretInformation()
        {
        }

        #endregion
    }

    #endregion

    #region Extension vault module class

    /// <summary>
    /// Class that contains all vault module information and secret manipulation methods.
    /// </summary>
    internal class ExtensionVaultModule
    {
        #region Members

        #region Script

        // Invokes Get-Secret, Set-Secret, Get-SecretInfo, Remove-Secret, Test-SecretVault commands in
        // nested module within provided module path.
        // Assumes the following directory structure:
        //  Module directory (parent module)
        //      Module.psd1
        //      Module.psm1
        //      ImplementingModule directory (nested module)
        //          ImplementingModule.psd1
        //          ImplementingModule.psm1
        private const string RunCommandScript = @"
            param (
                [string] $ModuleName,
                [string] $ModulePath,
                [string] $ImplementingModuleName,
                [string] $Command,
                [hashtable] $Params
            )

            $verboseEnabled = $Params.AdditionalParameters.ContainsKey('Verbose') -and ($Params.AdditionalParameters['Verbose'] -eq $true)
            $module = Microsoft.PowerShell.Core\Get-Module -Name $ModuleName -ErrorAction Ignore
            if ($null -eq $module) {
                $module = Microsoft.PowerShell.Core\Import-Module -Name $ModulePath -PassThru
            }
            if ($null -eq $module) {
                return
            }
            Write-Verbose ""Invoking command $Command on module $ImplementingModuleName"" -Verbose:$verboseEnabled
            & $module ""$ImplementingModuleName\$Command"" @Params
        ";

        // Conditionally invokes an optional command if supported by the implementing module.
        // Assumes the following directory structure:
        //  Module directory (parent module)
        //      Module.psd1
        //      Module.psm1
        //      ImplementingModule directory (nested module)
        //          ImplementingModule.psd1
        //          ImplementingModule.psm1
        private const string RunIfCommandScript = @"
            param (
                [string] $ModuleName,
                [string] $ModulePath,
                [string] $ImplementingModuleName,
                [string] $Command,
                [hashtable] $Params
            )

            $verboseEnabled = $Params.AdditionalParameters.ContainsKey('Verbose') -and ($Params.AdditionalParameters['Verbose'] -eq $true)
            $module = Microsoft.PowerShell.Core\Get-Module -Name $ModuleName -ErrorAction Ignore
            if ($null -eq $module) {
                $module = Microsoft.PowerShell.Core\Import-Module -Name $ModulePath -PassThru
            }
            if ($null -eq $module) {
                return
            }
            try {
                Write-Verbose ""Invoking command $Command on module $ImplementingModuleName"" -Verbose:$verboseEnabled
                & $module ""$ImplementingModuleName\$Command"" @Params
            }
            catch [System.Management.Automation.CommandNotFoundException] {
                Write-Verbose ""Module $ImplementingModuleName does not support command : $Command"" -Verbose:$verboseEnabled
            }
        ";

        // Return values:
        // 0 - Command ran (command will emit any error message)
        // 1 - Module not found
        // 2 - Command not found
        private const string RunConditionalCommandScript = @"
            param (
                [string] $ModuleName,
                [string] $ModulePath,
                [string] $ImplementingModuleName,
                [string] $Command,
                [hashtable] $Params
            )

            $verboseEnabled = $Params.AdditionalParameters.ContainsKey('Verbose') -and ($Params.AdditionalParameters['Verbose'] -eq $true)
            $module = Microsoft.PowerShell.Core\Get-Module -Name $ModuleName -ErrorAction Ignore
            if ($null -eq $module) {
                $module = Microsoft.PowerShell.Core\Import-Module -Name $ModulePath -PassThru
            }
            if ($null -eq $module) {
                return 1
            }
            try {
                Write-Verbose ""Invoking command $Command on module $ImplementingModuleName"" -Verbose:$verboseEnabled
                $null = & $module ""$ImplementingModuleName\$Command"" @Params
                return 0
            }
            catch [System.Management.Automation.CommandNotFoundException] {
                return 2
            }
        ";

        #endregion

        internal const string GetSecretCmd = "Get-Secret";
        internal const string GetSecretInfoCmd = "Get-SecretInfo";
        internal const string SetSecretCmd = "Set-Secret";
        internal const string SetSecretInfoCmd = "Set-SecretInfo";
        internal const string RemoveSecretCmd = "Remove-Secret";
        internal const string UnlockVaultCmd = "Unlock-SecretVault";
        internal const string TestVaultCmd = "Test-SecretVault";
        internal const string UnregisterSecretVaultCommand = "Unregister-SecretVault";
        internal const string ModuleNameStr = "ModuleName";
        internal const string ModulePathStr = "ModulePath";
        internal const string VaultParametersStr = "VaultParameters";
        internal const string DescriptionStr = "Description";
        internal const string SetSecretSupportsMetadataStr = "SetSecretSupportsMetadata";

        #endregion

        #region Properties

        /// <summary>
        /// Name of extension vault.
        /// </summary>
        public string VaultName { get; }

        /// <summary>
        /// Module name to qualify module commands.
        /// </summary>
        public string ModuleName { get; }

        /// <summary>
        /// Name of module extension which implements required functions.
        /// </summary>
        public string ModuleExtensionName { get; }

        /// <summary>
        /// Module path.
        /// </summary>
        public string ModulePath { get; }

        /// <summary>
        /// Additional vault parameters.
        /// </summary>
        public IReadOnlyDictionary<string, object> VaultParameters { get; }

        /// <summary>
        /// True when this extension vault is the default vault.
        /// </summary>
        public bool IsDefault { get; }

        /// <summary>
        /// Optional description string for vault.
        /// </summary>
        public string Description { get; }

        /// <summary>
        /// True when this extension vault Set-Secret function supports the Metadata parameter.
        /// </summary>
        public bool SetSecretSupportsMetadata { get; }

        #endregion

        #region Constructor

        private ExtensionVaultModule()
        {
        }

        /// <summary>
        /// Initializes a new instance of ExtensionVaultModule.
        /// </summary>
        public ExtensionVaultModule(
            string vaultName,
            Hashtable vaultInfo,
            bool isDefault)
        {
            // Module information.
            IsDefault = isDefault;
            VaultName = vaultName;
            ModuleName = (string) vaultInfo[ModuleNameStr];
            ModuleExtensionName = Utils.GetModuleExtensionName(ModuleName);
            ModulePath = (string) vaultInfo[ModulePathStr];
            Description = vaultInfo.ContainsKey(DescriptionStr) ? (string) vaultInfo[DescriptionStr] : string.Empty;
            SetSecretSupportsMetadata = vaultInfo.ContainsKey(SetSecretSupportsMetadataStr) ?
                (bool) vaultInfo[SetSecretSupportsMetadataStr] : false;

            // Additional parameters.
            var vaultParameters = new Dictionary<string, object>();
            if (vaultInfo.ContainsKey(VaultParametersStr))
            {
                var vaultParamsHashtable = (Hashtable) vaultInfo[VaultParametersStr];
                foreach (string key in vaultParamsHashtable.Keys)
                {
                    vaultParameters.Add(
                        key: key,
                        value: vaultParamsHashtable[key]);
                }
            }
            VaultParameters = new ReadOnlyDictionary<string, object>(vaultParameters);
        }

        /// <summary>
        /// Initializes a new instance of ExtensionVaultModule from an existing instance.
        /// </summary>
        public ExtensionVaultModule(
            ExtensionVaultModule module)
        {
            VaultName = module.VaultName;
            ModuleName = module.ModuleName;
            ModuleExtensionName = module.ModuleExtensionName;
            ModulePath = module.ModulePath;
            Description = module.Description;
            VaultParameters = module.VaultParameters;
            IsDefault = module.IsDefault;
            SetSecretSupportsMetadata = module.SetSecretSupportsMetadata;
        }

        #endregion

        #region Public methods

        /// <summary>
        /// Invoke SetSecret method on vault extension.
        /// </summary>
        /// <param name="name">Name of secret to add.</param>
        /// <param name="secret">Secret object to add.</param>
        /// <param name="vaultName">Name of registered vault.</param>
        /// <param name="metadata">Optional metadata associated with the secret.</param>
        /// <param name="cmdlet">Calling cmdlet.</param>
        public void InvokeSetSecret(
            string name,
            object secret,
            string vaultName,
            Hashtable metadata,
            PSCmdlet cmdlet)
        {
            var additionalParameters = GetAdditionalParams(cmdlet);
            var parameters = new Hashtable() {
                { "Name", name },
                { "Secret", secret },
                { "VaultName", vaultName },
                { "AdditionalParameters", additionalParameters }
            };

            // Include metadata if supported by vault.
            if (SetSecretSupportsMetadata)
            {
                parameters.Add(
                    key: "Metadata",
                    value: metadata ?? new Hashtable());
            }

            PowerShellInvoker.InvokeScriptWithHost(
                cmdlet: cmdlet,
                script: RunCommandScript,
                args: new object[] { ModuleName, ModulePath, ModuleExtensionName, SetSecretCmd, parameters },
                out Exception terminatingError);

            if (terminatingError != null)
            {
                ThrowPasswordRequiredException(terminatingError);

                cmdlet.WriteError(
                    new ErrorRecord(
                        new PSInvalidOperationException(
                            message: string.Format(CultureInfo.InvariantCulture, "Unable to add secret {0} to vault {1}", name, VaultName),
                            innerException: terminatingError),
                        "SetSecretInvalidOperation",
                        ErrorCategory.InvalidOperation,
                        this));

                return;
            }

            // If metadata is provided but not supported through Set-Secret parameter, then attempt to call
            // the separate vault Set-SecretInfo function as an alternative.
            if (metadata?.Count > 0 && !SetSecretSupportsMetadata &&
                !InvokeSetSecretMetadata(
                    name: name,
                    metadata: metadata,
                    vaultName: vaultName,
                    cmdlet: cmdlet))
            {
                // Unable to write metadata, probably because metadata is not supported by the extension vault.
                // Remove the secret from the vault, since it did not fully write.
                InvokeRemoveSecret(
                    name: name,
                    vaultName: vaultName,
                    cmdlet: cmdlet);

                return;
            }

            cmdlet.WriteVerbose(
                string.Format(CultureInfo.InvariantCulture, "Secret {0} was successfully added to vault {1}.", name, VaultName));
        }

        public bool InvokeUnlockSecretVault(
            SecureString password,
            string vaultName,
            PSCmdlet cmdlet)
        {
            var additionalParameters = GetAdditionalParams(cmdlet);
            var parameters = new Hashtable() {
                { "Password", password },
                { "VaultName", vaultName },
                { "AdditionalParameters", additionalParameters }
            };

            // Result values:
            // 0 - Command ran (command will emit any error message)
            // 1 - Module not found
            // 2 - Command not found
            var results = PowerShellInvoker.InvokeScriptWithHost<int>(
                cmdlet: cmdlet,
                script: RunConditionalCommandScript,
                args: new object[] { ModuleName, ModulePath, ModuleExtensionName, UnlockVaultCmd, parameters },
                out Exception terminatingError);

            if (terminatingError != null)
            {
                ThrowPasswordRequiredException(terminatingError);

                cmdlet.WriteError(
                    new ErrorRecord(
                        new PSInvalidOperationException(
                            message: string.Format(CultureInfo.InvariantCulture, "Unlocking vault '{0}' failed with error: {1}", vaultName, terminatingError.Message),
                            innerException: terminatingError),
                        "UnlockSecretVaultInvalidOperation",
                        ErrorCategory.InvalidOperation,
                        this));

                return false;
            }

            int result = (results.Count > 0) ? results[0] : 0;
            switch (result)
            {
                case 0:
                    cmdlet.WriteVerbose(
                        string.Format(CultureInfo.InvariantCulture, "Secret vault '{0}' was successfully unlocked.", vaultName));
                    break;

                case 1:
                    cmdlet.WriteError(
                        new ErrorRecord(
                            new PSInvalidOperationException(
                                message: string.Format(CultureInfo.InvariantCulture, "Cannot unlock extension vault '{0}': Extension module could not load.",
                                    vaultName)),
                            "UnlockSecretVaultCommandModuleLoadFail",
                            ErrorCategory.InvalidOperation,
                            this));
                    break;

                case 2:
                    cmdlet.WriteWarning(
                        string.Format(CultureInfo.InvariantCulture,
                            "Cannot unlock extension vault '{0}': The vault does not support the Unlock-SecretVault function.",
                            vaultName));
                    break;
            }

            return result == 0;
        }

        public bool InvokeSetSecretMetadata(
            string name,
            Hashtable metadata,
            string vaultName,
            PSCmdlet cmdlet)
        {
            var additionalParameters = GetAdditionalParams(cmdlet);
            var parameters = new Hashtable() {
                { "Name", name },
                { "Metadata", metadata },
                { "VaultName", vaultName },
                { "AdditionalParameters", additionalParameters }
            };

            // Result values:
            // 0 - Command ran (command will emit any error message)
            // 1 - Module not found
            // 2 - Command not found
            var results = PowerShellInvoker.InvokeScriptWithHost<int>(
                cmdlet: cmdlet,
                script: RunConditionalCommandScript,
                args: new object[] { ModuleName, ModulePath, ModuleExtensionName, SetSecretInfoCmd, parameters },
                out Exception terminatingError);

            if (terminatingError != null)
            {
                ThrowPasswordRequiredException(terminatingError);

                cmdlet.WriteError(
                    new ErrorRecord(
                        new PSInvalidOperationException(
                            message: string.Format(CultureInfo.InvariantCulture, "Cannot add secret metadata '{0}' to vault '{1}'", name, VaultName),
                            innerException: terminatingError),
                        "SetSecretMetadataInvalidOperation",
                        ErrorCategory.InvalidOperation,
                        this));

                return false;
            }

            int result = (results.Count > 0) ? results[0] : 0;
            switch (result)
            {
                case 0:
                    cmdlet.WriteVerbose(
                        string.Format(CultureInfo.InvariantCulture, "Secret metadata '{0}' was successfully added to vault '{1}'.", name, VaultName));
                    break;

                case 1:
                    cmdlet.WriteError(
                        new ErrorRecord(
                            new PSInvalidOperationException(
                                message: string.Format(CultureInfo.InvariantCulture, "Cannot add secret metadata '{0}' to vault '{1}': Extension module could not load.",
                                    name, VaultName)),
                            "SetSecretMetaDataCommandModuleLoadFail",
                            ErrorCategory.InvalidOperation,
                            this));
                    break;

                case 2:
                    cmdlet.WriteError(
                        new ErrorRecord(
                            new PSNotSupportedException(
                                message: string.Format(CultureInfo.InvariantCulture, "Cannot add secret metadata '{0}' to vault '{1}: The vault does not support the Set-SecretInfo function.",
                                    name, VaultName)),
                            "SetSecretMetadataCommandNotSupported",
                            ErrorCategory.NotImplemented,
                            this));
                    break;
            }

            return result == 0;
        }

        /// <summary>
        /// Looks up a single secret by name.
        /// </summary>
        /// <returns>Secret object</returns>
        public object InvokeGetSecret(
            string name,
            string vaultName,
            PSCmdlet cmdlet)
        {
            var additionalParameters = GetAdditionalParams(cmdlet);
            var parameters = new Hashtable() {
                { "Name", name },
                { "VaultName", vaultName },
                { "AdditionalParameters", additionalParameters }
            };

            var results = PowerShellInvoker.InvokeScriptWithHost<object>(
                cmdlet: cmdlet,
                script: RunCommandScript,
                args: new object[] { ModuleName, ModulePath, ModuleExtensionName, GetSecretCmd, parameters },
                out Exception terminatingError);

            if (terminatingError != null)
            {
                ThrowPasswordRequiredException(terminatingError);

                cmdlet.WriteError(
                    new ErrorRecord(
                        new PSInvalidOperationException(
                            message: string.Format(CultureInfo.InvariantCulture, "Unable to get secret {0} from vault {1}", name, VaultName),
                            innerException: terminatingError),
                        "GetSecretInvalidOperation",
                        ErrorCategory.InvalidOperation,
                        this));
            }
            else
            {
                cmdlet.WriteVerbose(
                    string.Format(CultureInfo.InvariantCulture, "Secret {0} was successfully retrieved from vault {1}.", name, VaultName));
            }

            if (results.Count == 0)
            {
                return null;
            }

            object returnValue;
            if (results[0] is byte)
            {
                // Re-wrap collection of bytes into a byte array.
                byte[] byteArray = new byte[results.Count];
                for (int i=0; i<results.Count; i++)
                {
                    byteArray[i] = (byte) results[i];
                }
                returnValue = byteArray;
            }
            else
            {
                returnValue = results[0];
            }

            // Special case for PowerShell wrapping weirdness.
            if (returnValue is List<object> listWrap && listWrap.Count > 0)
            {
                returnValue = listWrap[0];
            }

            // Return only allowed types.
            switch (returnValue)
            {
                case string strValue:
                    return strValue;

                case SecureString secureStrValue:
                    return secureStrValue;

                case byte[] byteArrayValue:
                    return byteArrayValue;

                case PSCredential psCredValue:
                    return psCredValue;

                case Hashtable hashTableValue:
                    return hashTableValue;

                default:
                    cmdlet.WriteError(
                    new ErrorRecord(
                        new PSInvalidOperationException(
                            message: string.Format(
                                CultureInfo.InvariantCulture,
                                "Secret object returned for '{0}' from vault '{1}' is of invalid type '{2}'",
                                name,
                                VaultName,
                                returnValue.GetType().ToString()),
                            innerException: terminatingError),
                        "GetSecretInvalidOperation",
                        ErrorCategory.InvalidOperation,
                        this));
                    return null;
            }
        }

        /// <summary>
        /// Remove a single secret.
        /// </summary>
        public void InvokeRemoveSecret(
            string name,
            string vaultName,
            PSCmdlet cmdlet)
        {
            var additionalParameters = GetAdditionalParams(cmdlet);
            var parameters = new Hashtable() {
                { "Name", name },
                { "VaultName", vaultName },
                { "AdditionalParameters", additionalParameters }
            };

            PowerShellInvoker.InvokeScriptWithHost(
                cmdlet: cmdlet,
                script: RunCommandScript,
                args: new object[] { ModuleName, ModulePath, ModuleExtensionName, RemoveSecretCmd, parameters },
                out Exception terminatingError);

            if (terminatingError != null)
            {
                ThrowPasswordRequiredException(terminatingError);

                cmdlet.WriteError(
                    new ErrorRecord(
                        new PSInvalidOperationException(
                            message: string.Format(CultureInfo.InvariantCulture, "Unable to remove secret {0} from vault {1}", name, VaultName),
                            innerException: terminatingError),
                        "RemoveSecretInvalidOperation",
                        ErrorCategory.InvalidOperation,
                        this));
            }
            else
            {
                cmdlet.WriteVerbose(
                    string.Format(CultureInfo.InvariantCulture, "Secret {0} was successfully removed from vault {1}.", name, VaultName));
            }
        }

        /// <summary>
        /// Returns secret meta data.
        /// </summary>
        public SecretInformation[] InvokeGetSecretInfo(
            string filter,
            string vaultName,
            PSCmdlet cmdlet)
        {
            var additionalParameters = GetAdditionalParams(cmdlet);
            var parameters = new Hashtable() {
                { "Filter", filter },
                { "VaultName", vaultName },
                { "AdditionalParameters", additionalParameters }
            };

            var results = PowerShellInvoker.InvokeScriptWithHost<SecretInformation>(
                cmdlet: cmdlet,
                script: RunCommandScript,
                args: new object[] { ModuleName, ModulePath, ModuleExtensionName, GetSecretInfoCmd, parameters },
                out Exception terminatingError);

            if (terminatingError != null)
            {
                ThrowPasswordRequiredException(terminatingError);

                cmdlet.WriteError(
                    new ErrorRecord(
                        new PSInvalidOperationException(
                            message: string.Format(CultureInfo.InvariantCulture, "Unable to get secret information from vault {0}", VaultName),
                            innerException: terminatingError),
                        "GetSecretInfoInvalidOperation",
                        ErrorCategory.InvalidOperation,
                        this));
            }
            else
            {
                cmdlet.WriteVerbose(
                    string.Format(CultureInfo.InvariantCulture, "Secret information was successfully retrieved from vault {0}.", VaultName));
            }

            var secretInfo = new SecretInformation[results.Count];
            results.CopyTo(secretInfo, 0);
            return secretInfo;
        }

        public bool InvokeTestVault(
            string vaultName,
            PSCmdlet cmdlet)
        {
            var additionalParameters = GetAdditionalParams(cmdlet);
            var parameters = new Hashtable() {
                { "VaultName", VaultName },
                { "AdditionalParameters", additionalParameters }
            };

            var results = PowerShellInvoker.InvokeScriptWithHost<bool>(
                cmdlet: cmdlet,
                script: RunCommandScript,
                args: new object[] { ModuleName, ModulePath, ModuleExtensionName, TestVaultCmd, parameters },
                out Exception terminatingError);

            if (terminatingError != null)
            {
                ThrowPasswordRequiredException(terminatingError);

                cmdlet.WriteError(
                    new ErrorRecord(
                        new PSInvalidOperationException(
                            message: string.Format(CultureInfo.InvariantCulture, "Unable to run Test-SecretVault on vault {0}", VaultName),
                            innerException: terminatingError),
                        "TestSecretVaultInvalidOperation",
                        ErrorCategory.InvalidOperation,
                        this));
            }

            return (results.Count > 0) ? results[0] : false;
        }

        /// <Summary>
        /// Optional Unregister-Vault extension command.  Will invoke if available.
        /// </Summary>