🌟 [Major]: Introducing the PSCredential module (#3)

## Description

This pull request introduces the `PSCredential` PowerShell module,
adding functions, documentation, and tests.

### New Functions for Managing Credentials:

*
[`New-PSCredential`](diffhunk://#diff-aa91734ba63271be8a7ab9602778b91375c26e1fec6845e9ba22175e9efb6652R1-R58):
A function to create `PSCredential` objects, supporting both secure
string and plain text passwords.
*
[`Save-PSCredential`](diffhunk://#diff-8a06b7ceda52d583a0bac03ec26c39ea7f4fd01dc2a5b3a3eb548727d9dd651dR1-R52):
A function to save `PSCredential` objects to a file, creating necessary
directories if they do not exist.
*
[`Restore-PSCredential`](diffhunk://#diff-1a0a08ae412d3eba29c03fdf97dba14b8a76c158ac99962b0f9d54dd1aad3b6bR1-R51):
A function to restore `PSCredential` objects from a file, ensuring the
content is a valid `PSCredential` object.

### Documentation:

*
[`README.md`](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L1-R108):
Includes installation instructions, usage examples, and contribution
guidelines.
*
[`examples/General.md`](diffhunk://#diff-a967fe83dceabfadb93250149336d9defaf7854411d0434fef6d46af4e2d6c36R1-R79):
Covers detailed examples for the new `New-PSCredential`,
`Save-PSCredential`, and `Restore-PSCredential` functions.

### Tests:
*
[`tests/PSCredential.Tests.ps1`](diffhunk://#diff-05dbda35cc66dcc03e56aabc17eb0d195997c9174a771e5386026c64a63ea4ceR1-R53):
Added tests for `New-PSCredential`, `Save-PSCredential`, and
`Restore-PSCredential` functions to ensure they work as expected.

## Type of change

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

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

## Checklist

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

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

Author: MariusStorhaug

.github/workflows/Nightly-Run.yml

@@ -14,3 +14,6 @@ jobs:
   Process-PSModule:
     uses: PSModule/Process-PSModule/.github/workflows/CI.yml@v3
     secrets: inherit
+    with:
+      Debug: true
+      Verbose: true

README.md

@@ -1,69 +1,108 @@
-# {{ NAME }}
+# PSCredential
 
-{{ DESCRIPTION }}
+`PSCredential` is a PowerShell module that provides functions for managing credentials.
+It allows users to create, save, and restore `PSCredential` objects from disk.
 
 ## Prerequisites
 
-This uses the following external resources:
-- The [PSModule framework](https://github.com/PSModule) for building, testing and publishing the module.
+This module requires:
+
+- The [PSModule framework](https://github.com/PSModule) for building, testing, and publishing the module.
 
 ## Installation
 
 To install the module from the PowerShell Gallery, you can use the following command:
 
 ```powershell
-Install-PSResource -Name {{ NAME }}
-Import-Module -Name {{ NAME }}
+Install-PSResource -Name PSCredential
+Import-Module -Name PSCredential
 ```
 
 ## Usage
 
-Here is a list of example that are typical use cases for the module.
+Here are some typical use cases for the module.
+
+### Example 1: Creating a new `PSCredential` object
+
+This function generates a `PSCredential` object using user input.
+
+```powershell
+New-PSCredential
+```
 
-### Example 1: Greet an entity
+This prompts the user for a username and password and returns a `PSCredential` object.
 
-Provide examples for typical commands that a user would like to do with the module.
+Alternatively, you can specify the credentials explicitly:
 
 ```powershell
-Greet-Entity -Name 'World'
-Hello, World!
+New-PSCredential -Username 'admin' -Password (ConvertTo-SecureString 'P@ssw0rd!' -AsPlainText -Force)
 ```
 
-### Example 2
+### Example 2: Saving a `PSCredential` object to a file
 
-Provide examples for typical commands that a user would like to do with the module.
+You can save a credential to a file using `Save-PSCredential`:
 
 ```powershell
-Import-Module -Name PSModuleTemplate
+$credential = Get-Credential
+Save-PSCredential -Credential $credential -Path 'C:\secure\credential.cred'
+```
+
+This saves the credential to `C:\secure\credential.cred`.
+
+### Example 3: Restoring a `PSCredential` object from a file
+
+To restore a credential object from a previously saved file:
+
+```powershell
+Restore-PSCredential -Path 'C:\secure\credential.cred'
+```
+
+Alternatively, you can use pipeline input:
+
+```powershell
+'C:\secure\credential.cred' | Restore-PSCredential
 ```
 
 ### Find more examples
 
 To find more examples of how to use the module, please refer to the [examples](examples) folder.
 
-Alternatively, you can use the Get-Command -Module 'This module' to find more commands that are available in the module.
-To find examples of each of the commands you can use Get-Help -Examples 'CommandName'.
+Alternatively, you can use the following commands:
+
+- Find available commands in the module:
+
+  ```powershell
+  Get-Command -Module PSCredential
+  ```
+
+- Get examples for a specific command:
+
+  ```powershell
+  Get-Help -Examples New-PSCredential
+  ```
 
 ## Documentation
 
-Link to further documentation if available, or describe where in the repository users can find more detailed documentation about
-the module's functions and features.
+For further documentation, please refer to:
+
+- [PSCredential](https://psmodule.io/PSCredential/)
 
 ## Contributing
 
-Coder or not, you can contribute to the project! We welcome all contributions.
+Whether you're a coder or not, you can contribute to this project!
 
 ### For Users
 
-If you don't code, you still sit on valuable information that can make this project even better. If you experience that the
-product does unexpected things, throw errors or is missing functionality, you can help by submitting bugs and feature requests.
-Please see the issues tab on this project and submit a new issue that matches your needs.
+If you experience unexpected behavior, errors, or missing functionality, you can help by submitting bug reports and feature requests.
+Please visit the [issues tab](https://github.com/PSModule/PSCredential/issues) and submit a new issue.
 
 ### For Developers
 
-If you do code, we'd love to have your contributions. Please read the [Contribution guidelines](CONTRIBUTING.md) for more information.
-You can either help by picking up an existing issue or submit a new one if you have an idea for a new feature or improvement.
+If you are a developer, we welcome your contributions!
+Please read the [Contribution Guidelines](CONTRIBUTING.md) for more information.
+You can either help by picking up an existing issue or submit a new one if you have an idea for a feature or improvement.
 
-## Acknowledgements
+## Disclaimer
 
-Here is a list of people and projects that helped this project in some way.
+The Export-Clixml cmdlet is used to save credentials to disk, is not secure on Linux and macOS, and should be used with caution.
+For more information read the [Export-Clixml](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/export-clixml?view=powershell-7.5#example-4-exporting-a-credential-object-on-linux-or-macos) documentation.

examples/General.md

@@ -0,0 +1,79 @@
+# PSCredential Examples
+
+This documentation provides details on three PowerShell functions for managing `PSCredential` objects:
+
+- **`New-PSCredential`**: Creates a new `PSCredential` object.
+- **`Save-PSCredential`**: Saves a `PSCredential` object to a file.
+- **`Restore-PSCredential`**: Restores a `PSCredential` object from a file.
+
+---
+
+## `New-PSCredential`
+
+This function generates a `PSCredential` object using a specified username and password.
+The password can be provided as a secure string or a plain text string.
+
+### Example 1: Prompting for credentials
+
+```powershell
+New-PSCredential
+```
+
+Prompts the user for a username and password and returns a `PSCredential` object.
+
+### Example 2: Creating a `PSCredential` object with a predefined password
+
+```powershell
+New-PSCredential -Username 'admin' -Password (ConvertTo-SecureString 'P@ssw0rd!' -AsPlainText -Force)
+```
+Creates a `PSCredential` object for the specified username and password.
+
+---
+
+## `Save-PSCredential`
+
+This function takes a `PSCredential` object and exports it to a file using `Export-Clixml`.
+If the specified file path does not exist, the function creates the necessary directory structure before saving the credential.
+
+### Example 1: Saving credentials from user input
+
+```powershell
+$credential = Get-Credential
+Save-PSCredential -Credential $credential -Path 'C:\secure\credential.xml'
+```
+Prompts for a username and password, then securely saves the credential to `C:\secure\credential.xml`.
+
+### Example 2: Saving predefined credentials
+
+```powershell
+$password = ConvertTo-SecureString 'MyPassword' -AsPlainText -Force
+$credential = New-PSCredential -Username 'UserName' -Password $password
+Save-PSCredential -Credential $credential -Path 'C:\secure\mycreds.xml'
+```
+
+Saves the predefined credential to `C:\secure\mycreds.xml`.
+
+---
+
+## `Restore-PSCredential`
+
+The `Restore-PSCredential` function retrieves a `PSCredential` object that was previously saved using `Export-Clixml`.
+It reads the file from the specified path and ensures the content is a valid `PSCredential` object before returning it.
+
+### Example 1: Restoring credentials from a file
+
+```powershell
+Restore-PSCredential -Path 'C:\secure\mycredential.xml'
+```
+
+Restores the `PSCredential` object from the file located at `'C:\secure\mycredential.xml'`.
+
+### Example 2: Using pipeline input to restore credentials
+
+```powershell
+'C:\secure\mycredential.xml' | Restore-PSCredential
+```
+
+Uses pipeline input to restore the `PSCredential` object from the specified file path.
+
+---

examples/General.ps1

@@ -0,0 +1,58 @@
+function New-PSCredential {
+    <#
+        .SYNOPSIS
+        Creates a new PSCredential object.
+
+        .DESCRIPTION
+        This function generates a PSCredential object using a specified username and password.
+        The password can be provided as a secure string or a plain text string, which will be
+        converted into a SecureString automatically.
+
+        .EXAMPLE
+        New-PSCredential
+
+        Prompts the user for a username and password and returns a PSCredential object.
+
+        .EXAMPLE
+        New-PSCredential -Username 'admin' -Password (ConvertTo-SecureString 'P@ssw0rd!' -AsPlainText -Force)
+
+        Creates a PSCredential object for the specified username and password.
+
+        .LINK
+        https://psmodule.io/PSCredential/Functions/New-PSCredential/
+    #>
+
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSUseShouldProcessForStateChangingFunctions', '',
+        Justification = 'Does not change state, just holding a credential in memory'
+    )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingUsernameAndPasswordParams', '',
+        Justification = 'The function is for creating a PSCredential'
+    )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingConvertToSecureStringWithPlainText', '',
+        Justification = 'The function is for creating a PSCredential'
+    )]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSAvoidUsingPlainTextForPassword', '',
+        Justification = 'The function is for creating a PSCredential'
+    )]
+    [OutputType([System.Management.Automation.PSCredential])]
+    [CmdletBinding()]
+    param(
+        # Specifies the username for the PSCredential object.
+        [Parameter()]
+        [string] $Username = (Read-Host -Prompt 'Enter a username'),
+
+        # Specifies the password for the PSCredential object. Accepts a secure string or plain text.
+        [Parameter()]
+        [object] $Password = (Read-Host -Prompt 'Enter Password' -AsSecureString)
+    )
+
+    if ($Password -is [String]) {
+        $Password = ConvertTo-SecureString -String $Password -AsPlainText -Force
+    }
+
+    New-Object -TypeName System.Management.Automation.PSCredential($Username, $Password)
+}

src/functions/public/New-PSCredential.ps1

@@ -0,0 +1,51 @@
+function Restore-PSCredential {
+    <#
+        .SYNOPSIS
+        Restores a PSCredential object from a file.
+
+        .DESCRIPTION
+        The Restore-PSCredential function retrieves a PSCredential object that was previously saved using `Save-PSCredential`.
+        It reads the file from the specified path and ensures the content is a valid PSCredential object before returning it.
+
+        .EXAMPLE
+        Restore-PSCredential -Path 'C:\secure\mycredential.cred'
+
+        Restores the PSCredential object from the file located at `C:\secure\mycredential.cred`.
+
+        .EXAMPLE
+        'C:\secure\mycredential.cred' | Restore-PSCredential
+
+        Uses pipeline input to restore the PSCredential object from the specified file path.
+
+        .LINK
+        https://psmodule.io/PSCredential/Functions/Restore-PSCredential/
+    #>
+
+    [OutputType([System.Management.Automation.PSCredential])]
+    [Alias('Import-PSCredential')]
+    [CmdletBinding()]
+    param(
+        # Specifies the path to the credential file to restore.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [System.IO.FileInfo] $Path
+    )
+
+    process {
+        Write-Verbose "Restoring PSCredential from [$Path]"
+        if (Test-Path $Path) {
+            $credential = Import-Clixml -Path $Path
+        } else {
+            throw "Unable to locate a credential file for [$Path]"
+        }
+
+        if ($credential -isnot [System.Management.Automation.PSCredential]) {
+            throw "Unable to restore a PSCredential object from [$Path]"
+        }
+
+        $credential
+    }
+}