🩹 [Patch]: Support pipeline input on ConvertTo- and ConvertFrom-SodiumSealedBox and New-SodiumKeyPair (#24)

## Description

This pull request enhances the `Sodium` PowerShell module by adding
support for pipeline input to various functions, updating documentation,
and adding new tests to ensure proper functionality. The most important
changes include the addition of pipeline input support, updates to
function documentation, and new tests for pipeline input scenarios.

Enhancements to functions:

*
[`src/functions/public/ConvertFrom-SodiumSealedBox.ps1`](diffhunk://#diff-afea5aa86ab4622c3a4bff63aa61976494cb620d338df534bf7121018056bbadL30-R56):
Added support for `ValueFromPipeline` and
`ValueFromPipelineByPropertyName` to the `SealedBox` parameter.
*
[`src/functions/public/ConvertTo-SodiumSealedBox.ps1`](diffhunk://#diff-be3e1727721972ed3d4275a880537b89ce6fbb16c1d97405e02d7e798b6c7bfbL25-R50):
Added support for `ValueFromPipeline` and
`ValueFromPipelineByPropertyName` to the `Message` parameter.
*
[`src/functions/public/New-SodiumKeyPair.ps1`](diffhunk://#diff-b951668ffde5fc1b700af8f8b2b6076d7ce27b0ec23e9d556ad1a893e204c87bL51-R82):
Added support for `ValueFromPipeline` to the `Seed` parameter.

Documentation updates:

*
[`src/functions/public/ConvertFrom-SodiumSealedBox.ps1`](diffhunk://#diff-afea5aa86ab4622c3a4bff63aa61976494cb620d338df534bf7121018056bbadR18-R41):
Enhanced documentation with examples, outputs, and notes for better
clarity.
*
[`src/functions/public/ConvertTo-SodiumSealedBox.ps1`](diffhunk://#diff-be3e1727721972ed3d4275a880537b89ce6fbb16c1d97405e02d7e798b6c7bfbL11-R35):
Enhanced documentation with examples, outputs, and notes for better
clarity.
*
[`src/functions/public/New-SodiumKeyPair.ps1`](diffhunk://#diff-b951668ffde5fc1b700af8f8b2b6076d7ce27b0ec23e9d556ad1a893e204c87bR40-R62):
Enhanced documentation with examples, outputs, and notes for better
clarity.

New tests:

*
[`tests/Sodium.Tests.ps1`](diffhunk://#diff-f601c73f9a5c51929710c76b4065f37025d3704dae0b299be2a892f7702e6875R66-R94):
Added tests to verify encryption and decryption using pipeline input for
`ConvertTo-SodiumSealedBox` and `ConvertFrom-SodiumSealedBox`.
*
[`tests/Sodium.Tests.ps1`](diffhunk://#diff-f601c73f9a5c51929710c76b4065f37025d3704dae0b299be2a892f7702e6875R116-R124):
Added tests to verify deterministic key generation using pipeline input
for `New-SodiumKeyPair`.

## Type of change

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

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [x] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [ ] 🌟 [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

src/functions/public/ConvertFrom-SodiumSealedBox.ps1

@@ -15,8 +15,30 @@
         }
         ConvertFrom-SodiumSealedBox @params
 
+        Output:
+        ```powershell
+        Secret message revealed!
+        ```
+
         Decrypts the given encrypted message using the specified public and private keys and returns the original string.
 
+        .EXAMPLE
+        $encryptedMessage | ConvertFrom-SodiumSealedBox -PublicKey $publicKey -PrivateKey $privateKey
+
+        Output:
+        ```powershell
+        Confidential Data
+        ```
+
+        Uses pipeline input to decrypt the given encrypted message with the specified keys.
+
+        .OUTPUTS
+        System.String
+
+        .NOTES
+        Returns the original plaintext string after decryption.
+        If decryption fails, an exception is thrown.
+
         .LINK
         https://psmodule.io/Sodium/Functions/ConvertFrom-SodiumSealedBox/
 
@@ -27,7 +49,11 @@
     [CmdletBinding()]
     param(
         # The base64-encoded encrypted secret string to decrypt.
-        [Parameter(Mandatory)]
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
         [Alias('CipherText')]
         [string] $SealedBox,
 

src/functions/public/ConvertTo-SodiumSealedBox.ps1

@@ -8,10 +8,31 @@
         The result is a base64-encoded sealed box that can only be decrypted by the corresponding private key.
 
         .EXAMPLE
-        ConvertTo-SodiumSealedBox -Message "Hello world!" -PublicKey "BASE64_PUBLIC_KEY"
+        ConvertTo-SodiumSealedBox -Message "Hello world!" -PublicKey $publicKey
+
+        Output:
+        ```powershell
+        hhCon4PO1X0TIPeh1i4GM6Wg9HSF5ge/x4L7p1vNd3lIdiJqNmBfswkcHipyM4HUr9wDLebjARVp5tsB
+        ```
 
         Encrypts the message "Hello world!" using the provided base64-encoded public key and returns a base64-encoded sealed box.
 
+        .EXAMPLE
+        "Sensitive Data" | ConvertTo-SodiumSealedBox -PublicKey $publicKey
+
+        Output:
+        ```powershell
+        p3PGL162uLCvrsCRLUDrc/Kfc5biGVzxRDg25ZdJoR9Y6ABZUKo8pvDoOGdchv0iBYQO2LP0Q6BkVbIDBUw=
+        ```
+
+        Uses pipeline input to encrypt the provided message using the specified public key.
+
+        .OUTPUTS
+        System.String
+
+        .NOTES
+        The function returns a base64-encoded sealed box string that can only be decrypted by the corresponding private key.
+
         .LINK
         https://psmodule.io/Sodium/Functions/ConvertTo-SodiumSealedBox/
 
@@ -22,7 +43,11 @@
     [CmdletBinding()]
     param(
         # The message string to be encrypted.
-        [Parameter(Mandatory)]
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
         [string] $Message,
 
         # The base64-encoded public key used for encryption.

src/functions/public/New-SodiumKeyPair.ps1

@@ -37,6 +37,29 @@
         Generates a deterministic key pair using the given seed string. The same seed will produce
         the same key pair every time.
 
+        .EXAMPLE
+        "MySecureSeed" | New-SodiumKeyPair
+
+        Output:
+        ```powershell
+        PublicKey                                    PrivateKey
+        ---------                                    ----------
+        WQakMx2mIAQMwLqiZteHUTwmMP6mUdK2FL0WEybWgB8= ci5/7eZ0IbGXtqQMaNvxhJ2d9qwFxA8Kjx+vivSTXqU=
+        ```
+
+        Generates a deterministic key pair using the given seed string via pipeline. The same seed will produce
+        the same key pair every time.
+
+        .OUTPUTS
+
+        PSCustomObject
+
+        .NOTES
+        Returns a PowerShell custom object with the following properties:
+        - **PublicKey**:  The base64-encoded public key.
+        - **PrivateKey**: The base64-encoded private key.
+        If key generation fails, an exception is thrown.
+
         .LINK
         https://psmodule.io/Sodium/Functions/New-SodiumKeyPair/
 
@@ -48,11 +71,15 @@
         Scope = 'Function',
         Justification = 'Does not change state'
     )]
-    [OutputType([pscustomobject])]
+    [OutputType([PSCustomObject])]
     [CmdletBinding(DefaultParameterSetName = 'NewKeyPair')]
     param(
         # A seed value to use for key generation.
-        [Parameter(Mandatory, ParameterSetName = 'SeededKeyPair')]
+        [Parameter(
+            Mandatory,
+            ParameterSetName = 'SeededKeyPair',
+            ValueFromPipeline
+        )]
         [string] $Seed
     )
 

tests/Sodium.Tests.ps1

@@ -63,6 +63,35 @@
                 ConvertFrom-SodiumSealedBox -SealedBox $sealedBox -PublicKey $keyPair.PublicKey -PrivateKey $invalidPrivateKey
             } | Should -Throw
         }
+
+        It 'Encrypts a message correctly when using pipeline input on ConvertTo-SodiumSealedBox' {
+            $keyPair = New-SodiumKeyPair
+            $publicKey = $keyPair.PublicKey
+            $privateKey = $keyPair.PrivateKey
+            $message = 'Pipeline input encryption test'
+
+            # Pass the message via pipeline input instead of -Message parameter
+            $sealedBox = $message | ConvertTo-SodiumSealedBox -PublicKey $publicKey
+
+            $decryptedString = ConvertFrom-SodiumSealedBox -SealedBox $sealedBox -PublicKey $publicKey -PrivateKey $privateKey
+
+            $decryptedString | Should -Be $message
+        }
+
+        It 'Decrypts a sealed box correctly when using pipeline input on ConvertFrom-SodiumSealedBox' {
+            $keyPair = New-SodiumKeyPair
+            $publicKey = $keyPair.PublicKey
+            $privateKey = $keyPair.PrivateKey
+            $message = 'Pipeline input decryption test'
+
+            # Encrypt using normal parameter binding
+            $sealedBox = ConvertTo-SodiumSealedBox -Message $message -PublicKey $publicKey
+
+            # Pass the sealed box via pipeline input to the decryption function
+            $decryptedString = $sealedBox | ConvertFrom-SodiumSealedBox -PublicKey $publicKey -PrivateKey $privateKey
+
+            $decryptedString | Should -Be $message
+        }
     }
 
     Context 'Key Pair Generation' {
@@ -84,6 +113,15 @@
             $keyPair1.PrivateKey | Should -Be $keyPair2.PrivateKey
         }
 
+        It 'Generates deterministic keys when a seed is provided - using a pipeline input' {
+            $seed = 'DeterministicSeed'
+            $keyPair1 = $seed | New-SodiumKeyPair
+            $keyPair2 = $seed | New-SodiumKeyPair
+
+            $keyPair1.PublicKey | Should -Be $keyPair2.PublicKey
+            $keyPair1.PrivateKey | Should -Be $keyPair2.PrivateKey
+        }
+
         It 'Generates different keys for different seeds' {
             $seed1 = 'SeedOne'
             $seed2 = 'SeedTwo'